From bb0df97039a4ce178ecc7e3ac3083adeb3dc4d8b Mon Sep 17 00:00:00 2001 From: Andrew Lee Date: Sun, 14 Jun 2026 15:53:24 -0700 Subject: [PATCH] docs: document the flagsets.go/NewFlagSet wiring in the add-a-command recipes Both 'add a command' recipes predate flagsets.go + Command.NewFlagSet and stop at 'add cmd/frob.go + a --json flag'. A contributor who follows the happy path to add a flag-bearing command gets machine help that reports only --json and a red make ci from TestCommandFlagsMatchExpected naming a file+table the recipe never introduced. Add the three-step wiring (frobFlagSet in flagsets.go, NewFlagSet in register, the expected-table entry), framed around keeping help in sync -- Run parses the flags either way. --- CLAUDE.md | 7 +++++++ CONTRIBUTING.md | 6 +++++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 0d52833..e3c9729 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -69,6 +69,13 @@ e2e/ black-box tests driving the real binary as a subprocess 3. Add `cmd/frob.go` — a thin adapter that parses flags and calls `mutate("frob", asJSON, func(env stack.Env, s *stack.State) (*stack.OpResult, error) { return stack.Frobnicate(env, s, arg) })`, self-registering via `init()` → `register(&Command{...})`. Add a `--json` flag. + If `frob` parses any flag beyond `--json`, also add a `frobFlagSet()` constructor + to `cmd/flagsets.go` declaring those flags, set `NewFlagSet: frobFlagSet` in its + `register(&Command{...})`, and list `frob`'s flags in `TestCommandFlagsMatchExpected` + (`cmd/execute_test.go`). `Run` parses the flags either way; this wiring keeps + `st help --json` (and the declared-flags contract in `docs/AGENT.md`) reporting + exactly what `Run` accepts — skip it and `make ci` fails with "update flagsets.go + or this table". 4. If it has interesting CLI output, add a golden test (`cmd/golden_test.go`, regenerate with `go test ./cmd -run Golden -update`). 5. `make ci`. Adding the command shifts the help golden — regenerate it deliberately. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b4c7d11..f8d42b2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,7 +41,11 @@ interface (JSON, exit codes). the fake git (`mkBranch`). Microseconds, no real git. 3. **Adapter** — `cmd/frob.go`, a thin wrapper that self-registers and calls `mutate("frob", asJSON, func(env stack.Env, s *stack.State) (*stack.OpResult, error) { return stack.Frobnicate(env, s, arg) })`. - Add a `--json` flag (see `docs/AGENT.md` — every command speaks JSON). + Add a `--json` flag (see `docs/AGENT.md` — every command speaks JSON). For any + flag beyond `--json`, also add a `frobFlagSet()` to `cmd/flagsets.go`, set + `NewFlagSet: frobFlagSet` in `register()`, and list `frob`'s flags in + `TestCommandFlagsMatchExpected` — this keeps `help --json` reporting exactly + what `Run` accepts (or `make ci` fails with "update flagsets.go or this table"). 4. **Golden output** (optional) — `cmd/golden_test.go`; regenerate with `go test ./cmd -run Golden -update`. 5. `make ci`. Adding a command shifts the `--help` golden — regenerate it