RFC: CLI Rewrite — Go + Cobra + Bubble Tea + npm Distribution

[Hyperxq]

Overview

This is the full plan for rewriting @pbuilder/cli from TypeScript/Node.js to Go, using the Charmbracelet ecosystem for TUI and distributing via npm.

Why Rewrite?

• Current CLI is slow (Node.js module loading, heavy Angular deps loaded upfront, no lazy loading)
• No interactivity — all flag-driven, no modern UX
• Go binary startup: ~5ms vs Node.js: ~300-500ms
• Single binary distribution, no runtime dependency

---

Current CLI Audit

Commands (5 active, 1 dead)

Command	Aliases	What It Does
new <library-name> [author]	—	Scaffolds a new Angular schematics library project
execute <collection> <schematic>	exec, g, generate	Runs ANY schematic outside an Angular workspace
add <collection-name>	—	Installs a schematic package + auto-runs its ng-add
info <collection-name> [schematic]	—	Lists schematics in a collection, shows options from schema.json
config <action> [key] [value]	—	Manages CLI config (get, set, delete, list)
create	—	DEAD CODE — exists but NOT registered in CommandLoader

Core Architecture: Subprocess Delegation

The CLI does NOT use Angular schematics engine in-process. It:

1. Resolves @angular-devkit/schematics-cli/bin/schematics.js via require.resolve
2. Spawns: node [binaryPath] collection:schematic --flags with stdio: inherit
3. Auto-install-then-uninstall pattern for collections (controlled by --keep-installed)

Current Dependencies & Their Roles

Package	Role
commander	Arg parsing
@angular-devkit/schematics-cli	Subprocess binary for running schematics
@angular-devkit/schematics	Types/utilities only, NOT execution
conf	Persistent config store
axios	HTTP (only in dead create command)
npm-package-arg + npm-registry-fetch	Package validation
chalk + ora + node-emoji	UI
pino + pino-pretty	Logging

Key Observations

• NO interactive prompts — major gap for modern UX
• Config system functional but minimal (only 1 real key: cli.showBanner)
• create command is dead code — don't port unless reviving

---

New Stack

Layer	Old (TypeScript)	New (Go)
Commands/flags	commander	Cobra
Config	conf	Viper
TUI framework	(none)	Bubble Tea (Elm Architecture)
UI components	ora (spinner only)	Bubbles (spinners, inputs, tables, lists)
Interactive forms	(none)	Huh (text inputs, selects, confirms, multi-step)
Styling	chalk	Lip Gloss (colors, borders, padding, layout)
Logging	pino	charmbracelet/log
Markdown render	(none)	Glamour
Subprocess	child_process.spawn	os/exec
HTTP client	axios / npm-registry-fetch	net/http
JSON parsing	built-in	encoding/json
Distribution	npm (native)	npm via platform-specific optionalDependencies

---

npm Distribution Pattern

Same pattern used by esbuild, turbo, Biome, SWC, Lightning CSS:

my-cli/                        <- main npm package
├── package.json               <- optionalDependencies per platform
├── bin/cli.js                 <- thin JS wrapper (~5 lines)

@my-cli/darwin-arm64/          <- separate npm package
├── package.json               <- os: ["darwin"], cpu: ["arm64"]
└── bin/my-cli                 <- Go binary

@my-cli/linux-x64/
├── package.json               <- os: ["linux"], cpu: ["x64"]
└── bin/my-cli

npm auto-installs ONLY the matching platform package. Users run npm i -g my-cli or npx my-cli — transparent.

---

Implementation Phases

Phase 0: Learn Go (Targeted)

Not "learn all of Go" — only what's needed:

Concept	Why
Structs	Bubble Tea Model IS a struct
Interfaces	tea.Model is an interface — Go's entire polymorphism
Error handling	(result, error) pattern everywhere
Pointers vs values	Update function mutations
os/exec	Core logic — subprocess spawning
net/http	npm registry queries
encoding/json	Parsing collection.json, schema.json

Resources:

1. A Tour of Go
2. Go by Example — focus: Structs, Interfaces, Errors, Spawning Processes, JSON, HTTP Clients
3. Boot.dev Learn Go

Mini-project: CLI that queries https://registry.npmjs.org/<package>, parses JSON, prints name/version/description.

Phase 1: Cobra Skeleton

• Root command + 5 subcommands with all flags
• Viper for config management
• info command queries npm registry for real

Resources:

1. Cobra docs
2. Building CLI Apps with Cobra and Viper (2026)
3. Viper

Phase 2: Bubble Tea TUI

• Elm Architecture: Init() → Update() → View()
• Huh forms when commands called without required args
• Bubbles spinners for async operations
• Lip Gloss styling for all output

Resources (in this exact order):

1. Bubble Tea Basics Tutorial
2. Bubble Tea Commands Tutorial
3. Charming Cobras with Bubbletea — Cobra + Bubble Tea combo
4. Wizard Tutorial
5. Inngest guide

Charmbracelet Ecosystem:

                    ┌─────────────┐
                    │  Bubble Tea │  <- Framework
                    └──────┬──────┘
           ┌───────────────┼───────────────┐
     ┌─────┴─────┐  ┌──────┴──────┐  ┌────┴────┐
     │  Bubbles  │  │  Lip Gloss  │  │   Huh   │
     │(components)│ │  (styling)  │  │ (forms) │
     └───────────┘  └─────────────┘  └─────────┘

Phase 3: Core Logic (Subprocess Management)

cmd := exec.Command("node", append([]string{schematicsBin}, args...)...)
cmd.Stdin = os.Stdin
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
err := cmd.Run()

Resources:

1. Go by Example: Spawning Processes
2. DoltHub os/exec patterns
3. Advanced command execution

Phase 4: npm Distribution

• Multi-platform build with GOOS + GOARCH
• Platform-specific npm packages
• CI/CD for automated builds

Phase 5: NEW Features

• Rich interactive prompts for ALL commands
• Better error messages with styled output
• Template marketplace, plugin system, etc.

---

TypeScript → Go Mental Model

TypeScript	Go
interface	interface (implicit — no implements)
class	struct + methods
try/catch	if err != nil
async/await	goroutines + channels (or tea.Cmd)
npm install	go get
package.json	go.mod

[Hyperxq]

📦 This RFC has moved

The Project Builder ecosystem has been reorganized into a dedicated GitHub organization: Project-Builder-Schematics.

This RFC now lives at: Project-Builder-Schematics/project-builder-cli#1

Please continue the conversation there. This original discussion remains as a historical reference — a record of the thinking that led to the Go rewrite after several years of building @pbuilder/cli in TypeScript.

The new home:

• 🔓 Public CLI repo: https://github.com/Project-Builder-Schematics/project-builder-cli
• 🔒 Private engine repo: (access by invitation)

Thanks for reading, and see you on the other side. 🚀