* 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>
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
- Create
cmd/bd/<cmd>.gowith the Cobra command and register it in that file'sinit(). - Add its row to
capability_registry.go.TestProxyCapabilityRegistryCoversCommandTreefails if a command path is missing, andTestProxyCapabilityRegistryHasNoStaleRowsfails on rows for paths that no longer exist. - If the command uses the store on proxied-server workspaces, add
<cmd>_proxied_server.go. - Support
--jsonfor agent use. The--jsonwire surface is pinned by the golden corpus inprotocol/(TestCorpusGolden; regenerate withmake corpus-regenand review the diff — seeprotocol/CATALOG.md). - Add tests in the right tier.
- Regenerate the CLI reference with
scripts/generate-cli-docs.sh;scripts/check-cli-docs-drift.shfails a PR whose command-surface change leaves the generated docs stale. - 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$'.TestCommandTreeGoldenfails 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 ofcmd/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 tostore.Counter(),store.WorkspaceConfig(),store.VersionReconciler(),store.StatsReporter(),store.ReadyCounter(), andstore.Querier().cmd-bd-domain-boundary(depguard,label.goandstate.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/bddenies these by default; the files allowed to build their own filters are listed, with reasons, in.golangci.yml. - forbidigo
fmt.Print*/os.Stdoutin 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.TestProxyCapabilityRegistryCoversCommandTreeand the otherTestProxyCapabilityRegistry*tests — the registry stays complete and consistent.TestCobraParallelPolicyGuard— a test that callst.Parallel()must not call the Cobra methods incobraParallelUnsafeMethods; dropt.Parallel()or serialize the call understdioMutex.TestCorpusGolden(protocol/) — no unreviewed change to the--jsonwire shapes.TestCommandTreeGoldenandTestCommandHelpGolden— no unreviewed change to the command tree (every command and flag, hidden ones included) or to the pinned--helpoutput intestdata/command_tree/.
Fresh-workspace command fixtures call isolateBeadsDirForTest(t) before
setup or dispatch and must not use t.Parallel().