beads/cmd/bd/AGENTS.md
Julian Knutsen 36f81bab1c
test(cmd/bd): pin the command tree and representative --help output (#7675)
* test(cmd/bd): pin the command tree and representative --help output

Add two in-process goldens for the bd command surface, so any added,
removed, hidden or reworded command or flag fails until the goldens are
regenerated and shows up as a reviewed testdata diff:

- TestCommandTreeGolden walks the whole cobra tree (hidden commands
  included) and records, per command, Use, Aliases, Short, Long, Example,
  group, hidden/deprecated state, runnability and annotations, plus every
  local and persistent flag it defines (name, shorthand, type, default,
  usage, hidden, deprecation, annotations). Output is sorted and rendered
  twice to prove it is deterministic.
- TestCommandHelpGolden runs `bd <cmd> --help` through rootCmd for root,
  create, show, list, update, close, version, versions, config and serve.
  --help returns before the root pre-run, so no store is opened; color
  escapes are stripped. The snapshots are byte-identical to a built bd
  binary's --help output.

Both run from a fresh ordinary (dependency-mode) workspace: a
.beads/metadata.json with no graph marker and no database behind it.

The tree is primed the way the binary is (main()'s help command and its
--all/--doc/--list/--docs-root flags, ExecuteC's completion command), and
cobra's history-dependent pieces (the lazily added per-command --help flag,
the __complete request commands) are excluded, so the result does not
depend on which in-process tests ran first. The help runs reset every flag
afterwards so a later in-process command does not inherit --help.

docs/cli-docs.pin holds check-doc-flags at the v1.2.2 release, so drift on
main is not caught there; these goldens are the live guard. They pin the
cgo build (the !cgo build swaps in a federation stub). Regenerate with
BD_UPDATE_GOLDEN=1 go test -tags gms_pure_go ./cmd/bd -run '^TestCommand(Tree|Help)Golden$'.

Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(cmd/bd): keep the command goldens from merging flags into the shared tree

TestCommandTreeGolden read each command's flags through
LocalNonPersistentFlags, and TestCommandHelpGolden dispatches
`bd serve --help`. Both run cobra's mergePersistentFlags, which copies
every inherited persistent flag (--json, --db, ...) into the command's
own flag set for the rest of the process. TestServeFlags pins serveCmd's
exact flag set, so it failed whenever a golden test ran before it in the
same test binary: tree then serve flags, help then serve flags, and
-test.shuffle seeds 2 and 3, on the PR head and on its merge with main.
CI passes only because bd_test's 16 Bazel shards happen to run them in
different processes. Of 37 candidate tests, TestServeFlags is the only
one affected.

- goldenLocalFlags reads the set LocalNonPersistentFlags reports without
  calling it: c.Flags() minus c's own persistent flags and minus
  inherited copies. Like cobra, it treats a flag as inherited only if it
  is the nearest ancestor's own *pflag.Flag, so copies left by an
  earlier in-process execution are skipped and a flag that shadows an
  inherited one still renders.
- TestCommandTreeGolden fails if rendering changes the number of flags
  in any command's flag set.
- TestCommandHelpGolden calls restoreServeGlobals, which re-registers
  serveCmd's flags after the `bd serve --help` dispatch.

Review minors:
- The regeneration command (doc comment, failure-message constant,
  tree.golden header) sets CGO_ENABLED=1. Without cgo the file does not
  build, so the command matches no test and exits 0.
- enterOrdinaryWorkspaceForGolden calls isolateBeadsDirForTest.
- renderCommandHelpGolden's comment says when the ANSI strip matters.
- cmd/bd/AGENTS.md lists the goldens under "Adding a command" and
  "Guard tests".

Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com>
2026-10-19 05:56:15 +00:00

5 KiB

cmd/bd — contributor notes

cmd/bd is the bd CLI: one Go package (about 340 non-test files) plus the doctor/, setup/, protocol/, help_supplements/, and winres/ subpackages. Commands decide what to do; storage work belongs below them in internal/storage/issueops (see the layering rules in CONTRIBUTING_PR_GUIDELINES.md).

File families

Pattern Meaning
<cmd>.go The Cobra command, its flags, and the mode-independent body. Registers itself with rootCmd.AddCommand in its own init() — main.go adds no commands.
<cmd>_proxied_server.go The proxied-server route for the same command. A command that touches the store on a proxied-server workspace needs one.
capability_registry.go One table for every command path: what the pre-provider gate does with it on a proxied-server workspace.
<cmd>_embedded_test.go cgo tests against embedded Dolt.
<cmd>_integration_test.go Integration tests, usually cgo && unix.
<cmd>_proxied_test.go Proxied-server tests.
<topic>_guard_test.go Policy and safety guards.

Which tier a test belongs in, and which command runs it, is decided by engdocs/TESTING.md.

Adding a command

  1. Create cmd/bd/<cmd>.go with the Cobra command and register it in that file's init().
  2. Add its row to capability_registry.go. TestProxyCapabilityRegistryCoversCommandTree fails if a command path is missing, and TestProxyCapabilityRegistryHasNoStaleRows fails on rows for paths that no longer exist.
  3. If the command uses the store on proxied-server workspaces, add <cmd>_proxied_server.go.
  4. Support --json for agent use. The --json wire surface is pinned by the golden corpus in protocol/ (TestCorpusGolden; regenerate with make corpus-regen and review the diff — see protocol/CATALOG.md).
  5. Add tests in the right tier.
  6. Regenerate the CLI reference with scripts/generate-cli-docs.sh; scripts/check-cli-docs-drift.sh fails a PR whose command-surface change leaves the generated docs stale.
  7. Regenerate the command-surface goldens and review the testdata diff: BD_UPDATE_GOLDEN=1 CGO_ENABLED=1 go test -tags gms_pure_go ./cmd/bd -run '^TestCommand(Tree|Help)Golden$'. TestCommandTreeGolden fails on any added, removed or reworded command or flag until you do.

Prefer a flag on an existing command over a new command, and route recovery/repair operations to bd doctor --fix; see the CLI design principles in engdocs/UI_PHILOSOPHY.md.

Boundaries enforced by lint

From .golangci.yml (read the rule comments there before changing scope):

  • cmd-bd-role-constructors (depguard, all of cmd/bd/**): "a command reaches the reader role through store.IssueReader(), never through the constructor: the accessor is where each storage decorator adds its layer". The same applies to store.Counter(), store.WorkspaceConfig(), store.VersionReconciler(), store.StatsReporter(), store.ReadyCounter(), and store.Querier().
  • cmd-bd-domain-boundary (depguard, label.go and state.go): "bd label and bd state reach storage through an issueops role accessor, never through the domain use cases - see openIssueLifecycle in cmd/bd/label.go".
  • forbidigo LabelUseCase$: "reach the label plane through issueops.Lifecycle (Patch.Labels) and issueops.Reader, never the domain use case".
  • forbidigo types.IssueFilter / types.WorkFilter: "do not write a filter here: take one back from a builder in internal/workapi, or pass the whole request to issueops.Reader". cmd/bd denies these by default; the files allowed to build their own filters are listed, with reasons, in .golangci.yml.
  • forbidigo fmt.Print* / os.Stdout in list/graph code: "route format output through the command writer; mark an intentional non-format path locally".

A deliberate exception is marked on its line with //nolint:forbidigo // <reason>; the reason is expected (review checks it; no linter enforces it).

Guard tests

  • TestEveryStoreConstructionActivatesTheEventsJournal — every store construction site activates the events journal; new non-bead-writing sites go in its exemption table with a reason.
  • TestProxyCapabilityRegistryCoversCommandTree and the other TestProxyCapabilityRegistry* tests — the registry stays complete and consistent.
  • TestCobraParallelPolicyGuard — a test that calls t.Parallel() must not call the Cobra methods in cobraParallelUnsafeMethods; drop t.Parallel() or serialize the call under stdioMutex.
  • TestCorpusGolden (protocol/) — no unreviewed change to the --json wire shapes.
  • TestCommandTreeGolden and TestCommandHelpGolden — no unreviewed change to the command tree (every command and flag, hidden ones included) or to the pinned --help output in testdata/command_tree/.

Fresh-workspace command fixtures call isolateBeadsDirForTest(t) before setup or dispatch and must not use t.Parallel().