You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`spin` is a Go project scaffold CLI for the charmbracelet v2 ecosystem. It generates ready-to-run Go projects — TUI apps, CLI tools, or both — pre-wired with the right charmbracelet libraries, modern Go tooling (cobra, fang, gum), hot reload (air), and the prism test runner. One command produces a project that builds, tests, and runs without extra setup. Built with cobra + fang + gum so the tool itself demonstrates the charmbracelet experience.
5
+
`spin` is a universal, language-agnostic scaffolder and task runner. One CLI for both jobs:
6
6
7
-
## Core Value
7
+
-**Scaffolder** — `spin new <ecosystem> <name> [flags]` generates ready-to-run projects for any ecosystem (Go+charm, Rust, or anything with a template). `spin new <name> --template <user/repo>` pulls an external template (git repo) that declares its own params and post-hooks.
8
+
-**Task runner** — `spin run <task>` resolves tasks from `spin.config.toml`, `Taskfile.yml`, `Makefile`, `package.json`, `scripts/`, or a language-aware fallback. `--list` shows the merged list with sources; `--explain <task>` shows origin + raw command.
9
+
-**Discovery** — `spin search <query>`, `spin add <user/repo>`, `spin list` against a public registry of templates and ecosystems (server ships separately).
8
10
9
-
Generate a perfect, runnable Go project using charmbracelet v2 libraries with a single command — `spin new myapp --tui --bubbletea` produces a project that `go run`s cleanly on first try.
11
+
The first two ecosystems are **charm** (Go + charmbracelet v2) and **rust** (cargo). The first-class citizen is the ecosystem; the second-class citizen is the template; the third is the builder (deferred to v2.x). Built with cobra + fang + gum so the tool itself dogfoods the charm stack.
12
+
13
+
**Core Value:** One tool to scaffold any project and run its tasks, for any language — `spin new rust myapp --bin && spin run build && spin run test` works the same as `spin new charm myapp --tui --bubbletea && spin run build && spin run test`.
10
14
11
15
## Requirements
12
16
13
17
### Validated
14
18
15
-
<!-- Shipped and confirmed valuable. -->
16
-
17
-
(None yet — ship to validate)
19
+
-[x]`spin new <name>` scaffolds a Go+charmbracelet v2 project in `./<name>`
-`gofumpt` is stricter than `gofmt` and is the de facto standard in modern Go projects
56
-
-`prism` is a `go test` replacement that runs tests in parallel workers with better output
57
-
-`air` is the de facto Go hot-reload tool; configured via `.air.toml`
58
-
-`fang` is the styled, accessible help renderer for cobra — it gives cobra CLIs a polished feel
59
-
- The scaffolder should be a showcase for the charm stack — running `spin --help` should feel like using a charm product
60
-
- Target user: a Go developer who has heard of charmbracelet and wants a zero-friction on-ramp
89
+
- The charmbracelet v2 ecosystem (bubbletea, lipgloss, huh, bubbles, glamour, wish, log, fang) uses `charm.land/<lib>/v2` import paths as of 2024–2025
90
+
-`gum` is a binary (no Go library) — `spin` shells out to it for interactive prompts
91
+
-`huh` v2 is the in-process form backend — used as the fallback when `gum` is not on `$PATH` and the in-process form for the runner's update/dep picker
92
+
- The charm ecosystem is the first citizen; rust is the second; everything else is a template
93
+
- The user wants a "global and universal language- and ecosystem-agnostic scaffolder and task runner" — competing with `npx create-*` (per-template scaffolders) and `cargo`/`make`/`task` (per-tool task runners), with one CLI to do both
94
+
- Rust is a critical second ecosystem: it's the most-Go-like language, has a strong task model (`cargo run/build/test/clippy/fmt`), and proves the universal claim
95
+
- The registry server is a separate project (`spin-registry`) — `spin` ships the client, not the server
96
+
- The runner's source-precedence chain mirrors Task's and Just's: explicit project config wins; language defaults are the floor
97
+
- Template params (text/number/select/multiselect/bool/path/secret) cover the 80% case; huh v2 supports all of them; for the 20% case, templates can do their own prompting in a post-hook
98
+
- The v2.0 skeleton (built 2026-06-08) defines the package layout: `internal/params/`, `internal/ecosystem/`, `internal/ecosystems/{charm,rust,...}`, `internal/runner/`, `internal/runner/sources/`, `internal/template/`, `internal/registry/`, `internal/builder/`. This phase fills in the implementations.
61
99
62
100
## Constraints
63
101
64
-
-**Tech stack**: Go 1.22+ (use 1.23 if available); built with cobra + fang + gum; consumes charmbracelet v2 libs only — Why: user specified charm-only, modern Go
65
-
-**Distribution**: single static binary; install via `go install github.com/<org>/spin@latest` — Why: standard Go CLI distribution, no runtime deps
66
-
-**Templates**: embedded via `go:embed` (default) + `--template-repo` for external override — Why: works offline by default, flexible for advanced users
67
-
-**Test runner**: `prism` (https://github.com/DaltonSW/prism), not `go test` directly — Why: user requested, better DX for parallel/colored output
68
-
-**Formatter**: `gofumpt` (primary) with `goimports`; fall back to `gofmt` if gofumpt not installed — Why: stricter formatting is the modern Go default
69
-
-**Hot reload**: `air` with a sensible `.air.toml` — Why: user requested, industry standard
70
-
-**No CGO**: scaffolded projects should build with `CGO_ENABLED=0` — Why: cross-compile and minimal container sizes
71
-
-**Charm v2 only**: do not import v1 paths or APIs — Why: v1 deprecated, v2 is current; researched via context7
102
+
-**Tech stack**: Go 1.23+ (use 1.25 for scaffolded projects that need bubbles v2); cobra + fang + gum; charm v2 only for spin itself — Why: dogfooding, modern Go
103
+
-**Distribution**: single static binary; `go install github.com/<org>/spin@latest` — Why: standard Go CLI
104
+
-**No CGO**: spin itself builds with `CGO_ENABLED=0`; scaffolded Go projects also CGO=0 — Why: cross-compile, minimal containers
105
+
-**Compiled-in ecosystems (v2.0)**: charm + rust are Go packages in `internal/ecosystems/` — Why: simpler ABI, no plugin contract to maintain
106
+
-**External templates via git**: shallow clone, `GIT_TERMINAL_PROMPT=0` — Why: works without auth for public repos; depth-1 keeps it fast
107
+
-**Graceful degradation**: registry server not deployed → friendly message, not a stack trace — Why: don't block users on the registry MVP
108
+
-**Charm v2 only**: never import `github.com/charmbracelet/...` v1 paths in spin or in scaffolded projects — Why: v1 deprecated
72
109
73
110
## Key Decisions
74
111
75
112
| Decision | Rationale | Outcome |
76
-
|----------|-----------|---------|
77
-
| Binary name = `spin`| User-selected; short verb, evokes "spinning up" a project | — Pending |
78
-
| Templates embedded + override | Offline default, flexibility for power users | — Pending |
79
-
| Interactive gum prompts (default) | Friendly for new users; flag-only via `--no-interactive`| — Pending |
80
-
| Scaffolder wraps `go run`/`prism`/`go vet`/`gofumpt`| One tool to learn; consistent commands across projects | — Pending |
81
-
| Charm v2 only | v1 deprecated; user explicitly wants v2 | — Pending |
82
-
| Cobra + fang + gum for the scaffolder itself | Dogfooding; showcase the charm stack | — Pending |
83
-
| Viper as opt-in (`--viper`) | Not every CLI needs config; don't force it | — Pending |
84
-
|`AGENTS.md` opt-in via `--ai`| Some users want AI-assistant context, some don't | — Pending |
85
-
| Project root = working dir at scaffold time, project in subdir `name/`| Matches `cargo new`, `npm init` conventions | — Pending |
113
+
|----------|-----------|--------|
114
+
| Binary name = `spin`| User-selected; short verb, evokes "spinning up" a project | — Validated |
115
+
| Templates embedded + override (`--template-repo`) | Offline default; flexibility for power users | — Validated v1 |
0 commit comments