beads/cmd/bd/testdata/command_tree/help/bd.golden
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

163 lines
9.6 KiB
Text

Issues chained together like beads. A lightweight issue tracker with first-class dependency support.
Usage:
bd [flags]
bd [command]
Working With Issues:
assign Assign an issue to someone
children List child beads of a parent
close Close one or more issues
comment Add a comment to an issue
comments View or manage comments on an issue
create Create a new issue (or batch from markdown/graph JSON)
create-form Create a new issue using an interactive form
delete Delete one or more issues and clean up references
edit Edit an issue field in $EDITOR
gate Manage async coordination gates
heartbeat Refresh the lease on an issue you hold in_progress
label Manage issue labels
link Link two issues with a dependency
list List issues
merge-slot Manage merge-slot gates for serialized conflict resolution
note Append a note to an issue
priority Set the priority of an issue
promote Promote a wisp to a permanent bead
provenance Append-only provenance event log
q Quick capture: create issue and output only ID
query Query issues using a simple query language
reclaim Revert stale-lease in_progress issues back to ready (dead-worker recovery)
reopen Reopen one or more closed issues
search Search issues by text query
set-state Set operational state (creates event + updates label)
show Show issue details
state Query the current value of a state dimension
tag Add a label to an issue
todo Manage TODO items (convenience wrapper for task issues)
unclaim Release a claimed issue
update Update one or more issues
Views & Reports:
count Count issues matching filters
diff Show changes between two commits or branches
find-duplicates Find semantically similar issues using text analysis or AI
history Show version history for an issue
lint Check issues for missing template sections
stale Show stale issues (not updated recently)
status Show issue database overview and statistics
statuses List valid issue statuses
types List valid issue types
versions List the recorded versions of a bead
Dependencies & Structure:
dep Manage dependencies
duplicate Mark an issue as a duplicate of another
duplicates Find and optionally merge duplicate issues
epic Epic management commands
graph Display issue dependency graph
supersede Mark an issue as superseded by a replacement issue
swarm Swarm management for structured epics
Sync & Data:
backup Back up your beads database
branch List or create branches
conflicts Inspect and resolve live merge conflicts
export Export issues to JSONL format
federation Manage peer-to-peer federation with other workspaces
import Import issues from a JSONL file or stdin into the database
restore Restore the pre-compaction content of a compacted issue
sync Pull, check for conflicts, repair is_blocked, and push (the federation loop)
vc Version control operations
Setup & Configuration:
bootstrap Non-destructive database setup for fresh clones and recovery
config Manage configuration settings
connect Attach this workspace to a remote bd serve over HTTP
context Show effective backend identity and repository context
dolt Configure Dolt database settings
forget Remove a persistent memory
hooks Manage git hooks for beads integration
human Show essential commands for human users
info Show database information
init Initialize bd in the current directory
kv Key-value store commands
memories List or search persistent memories
migrate-personal Move personal planning issues from the project database to your planning repo
onboard Display minimal snippet for agent instructions file
prime Output AI-optimized workflow context
quickstart Quick start guide for bd
recall Retrieve a specific memory
remember Store a persistent memory
setup Setup integration with AI editors
where Show active beads location
Maintenance:
batch Run multiple write operations in a single database transaction
compact Squash old Dolt commits to reduce history size
doctor Check and fix beads installation health (start here)
events Read and manage the durable events journal
flatten Squash all Dolt history into a single commit
gc Garbage collect: decay old issues, compact Dolt commits, run Dolt GC
migrate Database migration commands
ping Check database connectivity
preflight Show PR readiness checklist
prune Delete old closed beads to reclaim space and shrink exports
purge Delete closed ephemeral beads to reclaim space
recompute-blocked Recompute is_blocked for all issues (repairs stale flags after a pull)
rename-prefix Rename the issue prefix for all issues in the database
rules Audit and compact Claude rules
sql Execute raw SQL against the beads database
upgrade Check and manage bd version upgrades
worktree Manage git worktrees for parallel development
Integrations & Advanced:
admin Administrative commands for database maintenance
jira Jira integration commands
linear Linear integration commands
repo Manage multiple repository configuration
Additional Commands:
ado Azure DevOps integration commands
audit Record and label agent interactions (append-only JSONL)
blocked Show blocked issues
completion Generate the autocompletion script for the specified shell
cook Compile a formula into a proto (ephemeral by default)
defer Defer one or more issues for later
formula Manage workflow formulas
github GitHub integration commands
gitlab GitLab integration commands
help Help about any command
init-safety Explain bd init flag semantics and the destroy-token format
mail Delegate to mail provider (e.g., gt mail)
metrics Show or change anonymous usage-metrics settings
mol Molecule commands (work templates)
notion Notion integration commands
orphans Identify orphaned issues (referenced in commits but still open)
ready Show ready work (open, no active blockers)
rename Rename an issue ID
schema Print the JSON Schema for bd's --json / export output
serve Serve the beads HTTP API over loopback
ship Publish a capability for cross-project dependencies
undefer Undefer one or more issues (restore to open)
version Print version information
Flags:
--actor string Actor name for audit trail (default: $BEADS_ACTOR, git user.name, $USER)
--cpu-profile Generate CPU profile for performance analysis
--database string Run against a different server database for this invocation, without changing the project's configured database (proxied-server mode only)
--db string Database path (default: auto-discover .beads/*.db). In proxied-server mode, a value that isn't an existing path is treated as a database name override (see --database)
-C, --directory string Change to this directory before running the command (like git -C)
--dolt-auto-commit string Dolt auto-commit policy (off|on|batch). 'on': commit after each write. 'batch': defer commits to bd dolt commit; uncommitted changes persist in the working set until then (a live batch-mode bd process also flushes on SIGTERM/SIGHUP, except in proxied-server mode, where bd dolt commit is the only flush point). In proxied-server mode the deferral covers the writes the CLI makes on that route, including config and version metadata; explicit commit points (bd batch, bd mol bond/pour/squash, bd mol wisp create, and the wisp half of bd mol burn) still commit, and a bd serve process on the same database is unaffected. Default: on. Override via config key dolt.auto-commit
--global Use the global shared-server database (beads_global)
-h, --help help for bd
--ignore-schema-skew Proceed despite forward schema drift (some queries may fail)
--json Output in JSON format
--mem-profile string Write heap profile to FILE on exit (also respects BEADS_MEM_PROFILE)
--no-color Disable color output (also: NO_COLOR=1 or CLICOLOR=0)
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables Dolt auto-push
-v, --verbose Enable verbose/debug output
-V, --version Print version information
Use "bd [command] --help" for more information about a command.