@@ -16,24 +16,6 @@ fizzy-cli/
1616└── .claude-plugin/ # Claude Code integration
1717```
1818
19- ## Command Architecture
20-
21- Built on ` cobra ` . Each command lives in its own file under ` internal/commands/ `
22- (e.g. ` card.go ` , ` board.go ` ) with a colocated ` _test.go ` . A command registers
23- itself via an ` init() ` that calls ` rootCmd.AddCommand(...) ` — there is no central
24- registration list. ` commands.go ` defines ` commandCatalogGroups ` (core /
25- collaboration / admin / utilities), which only controls how ` fizzy commands ` and
26- help group output; adding a command there is cosmetic, not wiring.
27-
28- ` root.go ` owns global flags and the output layer. Commands write results through
29- the shared ` *output.Writer ` (` out ` ) and the raw ` outWriter ` . Output mode is
30- selected by global flags: ` --json ` , ` --agent ` , ` --styled ` , ` --markdown ` ,
31- ` --quiet ` , ` --ids-only ` , ` --count ` , ` --jq ` . Use ` isHumanOutput() ` to branch
32- between styled rendering and structured output, and ` printSuccess(data) ` /
33- breadcrumbs (` output.Breadcrumb ` ) for machine output. ` internal/render/ ` does the
34- styled/markdown/column rendering; ` internal/harness/ ` runs the agent-integration
35- health checks behind ` fizzy doctor ` and ` fizzy setup ` .
36-
3719## SDK Architecture
3820
3921Commands use the fizzy-sdk (` github.com/basecamp/fizzy-sdk/go/pkg/fizzy ` ) for API access:
@@ -62,41 +44,16 @@ Key endpoints used by the CLI:
6244
6345** Important:** Cards use NUMBER for CLI commands, not internal ID. ` fizzy card show 42 ` uses the card number.
6446
65- ## Build & Quality Gates
66-
67- ``` bash
68- make build # Build binary to ./bin/fizzy
69- make check # DEFAULT gate: fmt-check + vet + lint + tidy-check + race-test
70- make test-unit # Go unit tests, no API required (./internal/...)
71- make lint # golangci-lint
72- ```
73-
74- ` make check ` is the default target and the local CI gate — run it before
75- considering work done. Toolchain: Go 1.26+ managed via ` mise ` (` .mise.toml ` ).
76- Every build/test target runs ` check-toolchain ` first, which ** fails fast if the
77- ` PATH ` go and ` GOROOT ` go disagree** — if you hit that, run
78- ` eval "$(mise hook-env)" ` and retry.
79-
80- ### SURFACE.txt — regenerate when the CLI surface changes
81-
82- ` SURFACE.txt ` is a golden snapshot of the entire command/flag/arg tree, verified
83- by ` make surface-check ` (a unit test) and in CI. ** Any time you add, rename, or
84- remove a command, flag, or argument you must regenerate it** or the build fails:
85-
86- ``` bash
87- make surface-snapshot # rewrites SURFACE.txt from the current command tree
88- ```
89-
9047## Testing
9148
9249``` bash
93- make test-unit # unit tests (no API)
94- make test-e2e # e2e tests (requires credentials )
95- make test-run NAME=TestBoardCRUD # single e2e test by name
96- make test-file FILE=crud_board # single e2e test file
50+ make build # Build binary to ./bin/fizzy
51+ make test-unit # Run Go unit tests (no API required )
52+ make test-e2e # Run e2e tests (requires credentials)
53+ make test-run NAME=TestBoardCRUD # Run a specific test
9754```
9855
99- E2E tests hit a live API and require credentials (see below). Unit tests do not .
56+ Requirements: Go 1.26+, API credentials for e2e tests.
10057
10158### Unit Test Patterns
10259
0 commit comments