From 0c5fa422d83ed152ba438232f0181c97bb364b3f Mon Sep 17 00:00:00 2001 From: Julian Knutsen Date: Sun, 26 Jul 2026 06:13:54 -0700 Subject: [PATCH] feat(cli): opt out of store init via bd:skip_store annotation (#5060) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Co-authored-by: Claude Opus 4.8 (1M context) --- cmd/bd/doctor.go | 8 +- cmd/bd/doctor_conventions.go | 3 +- cmd/bd/main.go | 39 +++++- cmd/bd/skip_store_annotation_test.go | 178 +++++++++++++++++++++++++++ 4 files changed, 224 insertions(+), 4 deletions(-) create mode 100644 cmd/bd/skip_store_annotation_test.go diff --git a/cmd/bd/doctor.go b/cmd/bd/doctor.go index 2e8b95b89..c7421f3b6 100644 --- a/cmd/bd/doctor.go +++ b/cmd/bd/doctor.go @@ -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 ` diff --git a/cmd/bd/doctor_conventions.go b/cmd/bd/doctor_conventions.go index b0cd80fd5..69fe686ae 100644 --- a/cmd/bd/doctor_conventions.go +++ b/cmd/bd/doctor_conventions.go @@ -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). diff --git a/cmd/bd/main.go b/cmd/bd/main.go index bb80e3bc5..5275afa28 100644 --- a/cmd/bd/main.go +++ b/cmd/bd/main.go @@ -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 diff --git a/cmd/bd/skip_store_annotation_test.go b/cmd/bd/skip_store_annotation_test.go new file mode 100644 index 000000000..2cf990a80 --- /dev/null +++ b/cmd/bd/skip_store_annotation_test.go @@ -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") + } +}