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:
parent
d01d62eb21
commit
0c5fa422d8
4 changed files with 224 additions and 4 deletions
|
|
@ -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>`
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
178
cmd/bd/skip_store_annotation_test.go
Normal file
178
cmd/bd/skip_store_annotation_test.go
Normal 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")
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue