feat(cli): opt out of store init via bd:skip_store annotation (#5060)

Commands that don't need the database (version, doctor, completions, ...)
skip store initialization in PersistentPreRunE. Today that exemption is the
central noDbCommands []string in cmd/bd/main.go — a command defined in
another file, or a build-tagged variant, cannot add itself without editing
that shared list, which is a recurring merge-conflict point for downstream
forks and plugins.

Add a cobra-annotation seam: a command (or any ancestor) carrying
Annotations{"bd:skip_store":"1"} is treated as no-store, via the new
commandOptsOutOfStore helper OR-d into the existing store-skip gate. This is
a no-op for OSS today (no command sets it) and lets out-of-tree or
build-tagged commands opt out locally, where they are defined.

Dogfood it on doctor: doctor now opts out via the annotation on its Command
literal instead of a noDbCommands entry, so the seam has a live in-tree
consumer already exercised by the existing doctor PersistentPreRunE tests.

Tests: pure-helper coverage (self / parent / grandparent / nil-safe) plus a
self-validating end-to-end gate test — a non-annotated control command proves
the environment does open a store when a command is not skipped, so the
annotated command's clean return is a real signal, not incidental.

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Julian Knutsen 2026-07-26 06:13:54 -07:00 • committed by GitHub
commit 0c5fa422d8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 224 additions and 4 deletions

View file

@ -68,7 +68,11 @@ const ConfigKeyHintsDoctor = "hints.doctor"
var doctorCmd = &cobra.Command{
Use: "doctor [path]",
GroupID: "maint",
Short: "Check and fix beads installation health (start here)",
// doctor diagnoses installation health and must run without opening the
// store. It opts out of store init via the annotation seam rather than the
// noDbCommands list (see commandOptsOutOfStore in main.go).
Annotations: map[string]string{skipStoreAnnotation: "1"},
Short: "Check and fix beads installation health (start here)",
Long: `Sanity check the beads installation for the current directory or specified path.
This command checks:
@ -495,7 +499,7 @@ func runDiagnostics(path string) doctorResult {
}
// bd-jgxi: Auto-migrate database version before checking it.
// Since doctor skips PersistentPreRun DB init (it's in noDbCommands),
// Since doctor skips PersistentPreRun DB init (via skipStoreAnnotation),
// trackBdVersion() and autoMigrateOnVersionBump() haven't run yet.
//
// Scope version tracking to the doctor target. Without this, `bd doctor <path>`

View file

@ -11,7 +11,8 @@ import (
// runConventionsCheck runs a composite conventions check: lint, stale, and orphans.
// All findings are advisory (warning, never error) - conventions are a choice.
func runConventionsCheck(path string) error {
// doctor is in noDbCommands so PersistentPreRun doesn't open the store.
// doctor opts out of PersistentPreRun DB init via skipStoreAnnotation, so
// PersistentPreRun doesn't open the store.
// The lint/stale/orphans primitives all require the global store, so
// initialize it lazily here; ensureDirectMode routes to embedded or
// server based on metadata.json (GH#3597).

View file

@ -124,6 +124,28 @@ var (
commandSpan oteltrace.Span
)
// skipStoreAnnotation, when set to "1" on a command (or any of its ancestors),
// makes bd skip database/store initialization for that command — the
// annotation-based equivalent of listing the command name in noDbCommands. It
// lets commands defined in other files or build-tagged variants opt out of the
// store gate locally, without editing the central noDbCommands list.
const skipStoreAnnotation = "bd:skip_store"
// commandOptsOutOfStore reports whether cmd or any of its ancestors carries the
// skipStoreAnnotation set to "1". The whole ancestor chain is walked, so
// annotating a command exempts that command and every subcommand beneath it.
// (This is broader than the noDbCommands list, which only matches a command
// name or its direct parent — annotate deliberately, on the specific command
// you want to skip the store.)
func commandOptsOutOfStore(cmd *cobra.Command) bool {
for c := cmd; c != nil; c = c.Parent() {
if c.Annotations[skipStoreAnnotation] == "1" {
return true
}
}
return false
}
// readOnlyCommands lists commands that only read from the database.
// These commands open the store in read-only mode. See GH#804.
var readOnlyCommands = map[string]bool{
@ -883,6 +905,12 @@ var rootCmd = &cobra.Command{
// GH#1093: Check noDbCommands BEFORE expensive operations
// to avoid spawning git subprocesses for simple commands
// like "bd version" that don't need database access.
//
// A command can also opt out of store init by setting the
// skipStoreAnnotation on its Command literal instead of being listed
// here (see commandOptsOutOfStore) — useful for commands defined in
// other files or build-tagged variants that can't edit this list. The
// "doctor" command uses that seam and so is intentionally absent below.
noDbCommands := []string{
"__complete", // Cobra's internal completion command (shell completions work without db)
"__completeNoDesc", // Cobra's completion without descriptions (used by fish)
@ -892,7 +920,7 @@ var rootCmd = &cobra.Command{
"context", // reads config files directly, does not need DB open
"codex-hook",
"cursor-hook", // shells out to `bd prime`; never opens the store itself
"doctor",
// "doctor" opts out via skipStoreAnnotation on its Command literal.
"dolt", // bare "bd dolt" shows help only; subcommands handled below
"fish",
"formula", // parser-only subcommands; add a store-needed guard before adding DB-backed formula subcommands
@ -958,6 +986,15 @@ var rootCmd = &cobra.Command{
skipsStoreInit = true
}
// A command may also opt out of store init by declaring the
// bd:skip_store annotation (see commandOptsOutOfStore), instead of being
// added to the noDbCommands list above. Commands defined in other files
// or build-tagged variants use this to exempt themselves without editing
// the central list.
if commandOptsOutOfStore(cmd) {
skipsStoreInit = true
}
// One-time friendly heads-up about anonymous usage metrics. Placed after
// the config-derived json/quiet rebind and command classification above so
// it can read the real output mode and command identity — that is how it

View file

@ -0,0 +1,178 @@
package main
import (
"path/filepath"
"testing"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/configfile"
)
// annotate returns a command carrying the skip-store annotation set to v.
func annotate(use, v string) *cobra.Command {
return &cobra.Command{Use: use, Annotations: map[string]string{skipStoreAnnotation: v}}
}
func TestCommandOptsOutOfStore(t *testing.T) {
// Build a small tree: root -> parent -> child, so ancestor-walking is exercised.
newTree := func(root, parent, child *cobra.Command) *cobra.Command {
if parent != nil {
if child != nil {
parent.AddCommand(child)
}
root.AddCommand(parent)
}
return child
}
tests := []struct {
name string
cmd *cobra.Command
want bool
}{
{
name: "self annotated 1 opts out",
cmd: annotate("login", "1"),
want: true,
},
{
name: "no annotations map does not opt out",
cmd: &cobra.Command{Use: "add"},
want: false,
},
{
name: "annotation present but not 1 does not opt out",
cmd: annotate("add", "0"),
want: false,
},
{
name: "empty annotation value does not opt out",
cmd: annotate("add", ""),
want: false,
},
{
name: "child inherits annotated parent",
cmd: newTree(&cobra.Command{Use: "bd"}, annotate("remote", "1"), &cobra.Command{Use: "use"}),
want: true,
},
{
name: "grandchild inherits annotated root ancestor",
cmd: newTree(annotate("bd", "1"), &cobra.Command{Use: "remote"}, &cobra.Command{Use: "use"}),
want: true,
},
{
name: "child of unannotated parent does not opt out",
cmd: newTree(&cobra.Command{Use: "bd"}, &cobra.Command{Use: "remote"}, &cobra.Command{Use: "use"}),
want: false,
},
{
name: "annotated child under unannotated parent opts out",
cmd: newTree(&cobra.Command{Use: "bd"}, &cobra.Command{Use: "remote"}, annotate("use", "1")),
want: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := commandOptsOutOfStore(tt.cmd); got != tt.want {
t.Errorf("commandOptsOutOfStore(%q) = %v, want %v", tt.cmd.Name(), got, tt.want)
}
})
}
}
// TestCommandOptsOutOfStore_NilSafe guards the nil-command edge (the loop guard
// must terminate rather than panic).
func TestCommandOptsOutOfStore_NilSafe(t *testing.T) {
if commandOptsOutOfStore(nil) {
t.Fatal("nil command must not opt out of store init")
}
}
// TestPersistentPreRunHonorsSkipStoreAnnotation exercises the behavioral change
// end-to-end: PersistentPreRunE must route a command carrying skipStoreAnnotation
// down the no-store early-return path instead of opening the database. Without
// this, a refactor that drops the commandOptsOutOfStore call from the store-skip
// gate would silently break every annotation-based command (doctor, and any
// build-tagged command that opts out via the annotation) while the pure-helper
// tests above stay green.
//
// The test is self-validating via a control: a non-annotated command run in the
// same environment must reach store init and fail to open the configured
// (server-mode, absent) database. That control proves the environment really does
// attempt a store open for a non-skipped command — so the annotated command
// returning nil without assigning the global store is a meaningful signal that
// the annotation short-circuited the open, not that the open happened to succeed.
// If the store open ever stops failing here, the control fails loudly rather than
// letting a dropped gate pass silently. serverMode is deliberately not asserted:
// it is set on both the skip and full-store paths, so it does not discriminate.
func TestPersistentPreRunHonorsSkipStoreAnnotation(t *testing.T) {
repoDir := t.TempDir()
beadsDir := filepath.Join(repoDir, ".beads")
writeTestConfigYAML(t, beadsDir, "")
writeMetadataConfig(t, beadsDir, configfile.DoltModeServer, "skip_annotation_test")
t.Chdir(repoDir)
t.Setenv("BEADS_DIR", beadsDir)
t.Setenv("BEADS_DOLT_SHARED_SERVER", "")
t.Setenv("BEADS_DOLT_SERVER_DATABASE", "")
t.Setenv("BEADS_DOLT_SERVER_PORT", "")
// If the store IS opened (a broken gate), fail fast: never auto-start a server.
t.Setenv("BEADS_DOLT_AUTO_START", "0")
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
savePersistentPreRunState(t)
oldStore := store
t.Cleanup(func() { store = oldStore })
if rootCmd.PersistentPreRunE == nil {
t.Fatal("rootCmd.PersistentPreRunE must be set")
}
// Return the mutable globals a PersistentPreRunE drive touches to zero so the
// two independent drives below cannot cross-contaminate.
resetPreRunGlobals := func() {
serverMode = false
cmdCtx = nil
dbPath = ""
readonlyMode = false
doltAutoCommit = ""
store = nil
}
// Subject: opts out of store init purely via the annotation (it is NOT in
// noDbCommands), attached to rootCmd so it classifies as a top-level command.
// It must take the no-store early return — PersistentPreRunE returns nil and
// never assigns the global store.
resetPreRunGlobals()
annotated := &cobra.Command{
Use: "skipstoreprobe",
Annotations: map[string]string{skipStoreAnnotation: "1"},
RunE: func(*cobra.Command, []string) error { return nil },
}
rootCmd.AddCommand(annotated)
t.Cleanup(func() { rootCmd.RemoveCommand(annotated) })
if err := rootCmd.PersistentPreRunE(annotated, nil); err != nil {
t.Fatalf("annotated command must skip store init and return nil, got: %v", err)
}
if store != nil {
t.Fatal("annotated command must not open the store")
}
// Control: the same shape WITHOUT the annotation (and not in noDbCommands)
// must reach store init and fail to open the absent server-mode database.
resetPreRunGlobals()
control := &cobra.Command{
Use: "storeprobe-control",
RunE: func(*cobra.Command, []string) error { return nil },
}
rootCmd.AddCommand(control)
t.Cleanup(func() { rootCmd.RemoveCommand(control) })
if err := rootCmd.PersistentPreRunE(control, nil); err == nil {
t.Fatal("control (non-annotated) command should attempt store init and fail to open the absent database; test-environment precondition broken")
}
}