beads/cmd/bd/main.go
Julian Knutsen 1fcd715e75
fix(cli): refuse graph_mode workspaces and keep their metadata marker on save (#7671)
* fix(configfile): carry graph_mode and graph_* binding through Save

Graph-preview builds of bd persist a per-workspace format in
metadata.json: "graph_mode": "link" plus graph_scope_url,
graph_authority_id, graph_workspace, graph_schema_version and
graph_ready, beside an ordinary Dolt backend. configfile.Config had no
such fields, so every Save, and Load's config.json -> metadata.json
migration, rewrote the file without them, turning a graph workspace's
metadata into an ordinary Issue workspace's.

Config now carries the marker and the binding as omitempty fields, so
a Save round-trips them unchanged and metadata.json written for an
ordinary workspace is byte-for-byte what it was. GetGraphMode resolves
the marker: absent or "dependency" is the historical default, "link"
is recognized, and any other value is an error rather than a fallback
to the Issue store. Nothing in this build opens a non-default mode;
the CLI refusal follows in the next commit.

Ported from the donnabox fork commit deea8d57df (graph_mode.go,
graph_mode_test.go and the configfile.go fields), without any graph
code. The binding-survives-Save and omitted-from-ordinary-metadata
tests are new.

Co-authored-by: Donna Box <dbox@boxenllc.com>
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>

* fix(cli): refuse graph_mode workspaces before opening them

A workspace whose metadata.json declares a graph_mode other than
"dependency" holds a graph database behind an ordinary Dolt backend,
and nothing else in its metadata says so. bd admitted it like any
current workspace: `bd list` ran the Issue schema initialization
against the graph database (beads_graph_<id>), `bd init --force` wrote
a .gitignore and a .beads/dolt root into it, `bd dolt start` started a
server for it, and `bd doctor` reported on it as an Issue store.

guardLegacyUpgradeWorkspace, the admission check every store-opening
command, store-less command with workspace effects, init, doctor and
bootstrap already run before touching a workspace, now refuses such a
workspace first, before the legacy classifications that would admit
it or report it as a legacy store to migrate. An unknown graph_mode
value is refused the same way. The refusal is a typed error naming the
workspace and the format, rendered with a hint (as JSON under --json)
and exit code 16, ExitUnsupportedWorkspaceFormat, so a wrapper can
tell "needs a different bd build" from a generic failure.
`bd version`, `bd --version`, `bd help` and completion stay exempt, as
they are for legacy workspaces. validateConfiguredBackend refuses the
same metadata, which covers the store-open paths that skip command
admission (routed writes, cross-repository reads, create --repo).

Tests: guard and store-factory unit tests; a subprocess e2e test that
show/list/create/context/where/dolt start/doctor/bootstrap/init are
refused with exit 16 and leave .beads byte-identical (metadata.json and
legacy config.json, link and unknown markers, embedded and server
layouts), and that store-less commands still run; an embedded test
that an ordinary workspace, with the marker absent or "dependency",
still creates and lists issues and keeps the marker through a
metadata.json rewrite.

The guard hunk and graph_mode_admission_e2e_test.go are ported from
the donnabox fork commit deea8d57df; the exit code, rendering, store
factory backstop and remaining tests are new.

Co-authored-by: Donna Box <dbox@boxenllc.com>
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>

* fix(cli): refuse graph workspaces reached outside command admission

Command admission refuses a graph_mode workspace a command runs in, but
bd also reaches workspaces before or without admission: a create --repo
target, the path --db or BEADS_DB names, and the stores the factories
open for routed and cross-repository work. On those paths a workspace
marked only by a legacy config.json was changed before anything refused
it: configfile.Load migrates config.json into metadata.json before the
format check sees the loaded metadata, and create --repo initialized
such a target as a new workspace. Where the refusal did come, create
reported it with exit 1 rather than 16.

- checkDiscoveredWorkspaceFormat checks a workspace's metadata as
  configfile.LoadForDiscovery reads it, which never rewrites it.
  ensureBeadsDirForPath, the dry-run target open and the four store
  factories (cgo and nocgo builds) run it before their own load.
- resolveBeadsDirForDBPath and findDatabaseInBeadsDir locate a
  workspace with LoadForDiscovery, so resolving --db, BEADS_DB or a
  create target no longer migrates it.
- bd create renders a refused target as the workspace refusal, exit 16
  with its hint, on the initializing and both dry-run paths. A dry run
  without --parent opens no target, so it now checks a local one before
  rendering the preview (checkRepoTargetFormat).
- bd bootstrap, when discovery finds no workspace, reads each .beads
  from the working directory up to the repository root without
  migrating it and refuses one in a format this build cannot open, the
  way commands without a workspace already do. A .beads marked only by
  config.json is passed over by discovery, so bootstrap reported "no
  workspace" there instead of exit 16. The walk now returns its
  candidates (undiscoveredWorkspaceCandidates) to both checks: handing
  it the check as a func(string) error made gosec's G702 taint analysis
  connect BEADS_DIR to every func(string) error that runs git.
- backendNameForErrorFraming reads with LoadForDiscovery, and
  loadDoltBackendConfig, bd dolt status and bd dolt show refuse a graph
  workspace before their migrating configfile.Load. Admission refuses
  first on every path that reaches them today; this keeps a new caller
  from migrating a legacy config.json before the refusal.
- The CHANGELOG entry and the configfile comment now claim what holds:
  a routed read fails without touching a graph workspace but not with
  code 16, and a Save keeps only the known graph_* fields, with the
  tags graph-preview builds declare. workspace_gate.go no longer lists
  the pre-gate discovery reads as migrating.
- New e2e rows run create --repo from a workspace and from outside one,
  create --dry-run with and without --parent, --db, BEADS_DB, init
  --proxied-server, bootstrap in a workspace nested in a graph one, and
  the hook shim's bd hooks run pre-commit against every fixture; each
  refusal must exit 16 and name the format and the hint. bootstrap in a
  workspace marked only by config.json now refuses like the other
  commands. The store factory test also runs on a config.json graph
  workspace, TestWorkspaceMetadataReadersLeaveGraphWorkspaceUnchanged
  covers the framing, bd dolt loader and diagnostic reads, and
  TestNocgoStoreFactoriesRefuseGraphWorkspace covers the CGO_ENABLED=0
  factories; bazel.yml's pure lane runs it by name (PURE_CMD_BD_TESTS,
  pinned in scripts/ci_workflow_test.go).

Measured with gocyclo/gocognit: every function this changes stays below
the PR's worst changed function (guardLegacyUpgradeWorkspaceForInit
29/28, resolveBeadsDirForDBPath 26/36); showDoltConfig is 19/31 (was
18/30) and guardUndiscoveredLegacyWorkspace 3/3 (was 9/12).

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Donna Box <dbox@boxenllc.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-20 00:05:39 +00:00

3124 lines
133 KiB
Go
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

package main
import (
"context"
"errors"
"fmt"
"io"
"os"
"os/exec"
"os/signal"
"path/filepath"
"runtime"
"runtime/pprof"
"runtime/trace"
"slices"
"strconv"
"strings"
"sync"
"sync/atomic"
"syscall"
"time"
"github.com/spf13/cobra"
"github.com/subosito/gotenv"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/ceiling"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/debug"
"github.com/steveyegge/beads/internal/doltserver"
"github.com/steveyegge/beads/internal/hooks"
"github.com/steveyegge/beads/internal/httpclient"
"github.com/steveyegge/beads/internal/initprocs"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/migration"
"github.com/steveyegge/beads/internal/molecules"
"github.com/steveyegge/beads/internal/remotecache"
"github.com/steveyegge/beads/internal/routing"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backends"
"github.com/steveyegge/beads/internal/storage/dolt"
dbidentifier "github.com/steveyegge/beads/internal/storage/domain/db"
"github.com/steveyegge/beads/internal/storage/embeddeddolt"
"github.com/steveyegge/beads/internal/storage/schema"
"github.com/steveyegge/beads/internal/storage/uow"
"github.com/steveyegge/beads/internal/telemetry"
"github.com/steveyegge/beads/internal/ui"
"github.com/steveyegge/beads/internal/utils"
"go.opentelemetry.io/otel/attribute"
oteltrace "go.opentelemetry.io/otel/trace"
)
var (
changeDir string
dbPath string
databaseFlag string
actor string
store storage.DoltStorage
uowProvider uow.UnitOfWorkProvider
jsonOutput bool
// Signal-aware context for graceful cancellation
rootCtx context.Context
rootCancel context.CancelFunc
// Hook runner for extensibility
hookRunner *hooks.Runner
// Store concurrency protection
storeMutex sync.Mutex // Protects store access from background goroutine
storeActive = false // Tracks if store is available
// Version upgrade tracking
versionUpgradeDetected = false // Set to true if bd version changed since last run
previousVersion = "" // The last bd version user had (empty = first run or unknown)
upgradeAcknowledged = false // Set to true after showing upgrade notification once per session
)
type envSnapshotValue struct {
value string
ok bool
}
var changeDirEnvSnapshot map[string]envSnapshotValue
// beadsDirFromCaller is BEADS_DIR as the process INHERITED it, captured at
// package initialization — which the language guarantees runs before main, and
// therefore before any bd code exports a BEADS_DIR of its own.
//
// Reading os.Getenv("BEADS_DIR") later is a different question, and the wrong
// one for anything that needs to know what the CALLER asked for. By the time a
// command's RunE runs, bd has usually exported one itself:
//
// - the root PersistentPreRunE resolves a beads dir for every no-DB command
// and exports it (selectedNoDBBeadsDir -> prepareSelectedNoDBContext ->
// prepareSelectedCommandContext), and that resolution bottoms out in
// beads.FindBeadsDir(), which accepts any ancestor .beads/ carrying so much
// as a config.yaml — including the legacy user-level ~/.beads/config.yaml;
// - `bd -C <dir>` exports one too (applyChangeDirSelection), which names a
// beads dir without moving the working directory.
//
// Neither is the caller saying "use this". Consult this snapshot, not the live
// environment, when the answer must mean caller intent (GH#4635).
//
// A BEADS_DIR imported from a .beads/.env file is deliberately left out too,
// although beadsDirProvidedAtStartup counts it as user selection for role
// detection: the loaders read the .env of the beads dir beads.FindBeadsDir()
// discovers from the working directory, which in a home directory is the legacy
// ~/.beads/.env. Counting it would let the same discovered ~/.beads opt out of
// the home-directory guard; the caller opts out by exporting BEADS_DIR.
var beadsDirFromCaller = os.Getenv("BEADS_DIR")
var (
noColorFlag bool
sandboxMode bool
globalFlag bool
serverMode bool
proxiedServerMode bool
readonlyMode bool // Read-only mode: block write operations (for worker sandboxes)
storeIsReadOnly bool // Track if store was opened read-only (for staleness checks)
ignoreSchemaSkew bool // Proceed despite forward schema drift
lockTimeout = 30 * time.Second // Dolt open timeout (fixed default)
cpuProfileEnabled bool
profileFile *os.File
traceFile *os.File
memProfilePath string
verboseFlag bool // Enable verbose/debug output
quietFlag bool // Suppress non-essential output
// Dolt auto-commit policy (flag/config). Values: off | on
doltAutoCommit string
// commandDidWrite is set when a command performs a write that should trigger
// auto-flush. Used to decide whether to auto-commit Dolt after the command completes.
// Thread-safe via atomic.Bool to avoid data races in concurrent flush operations.
commandDidWrite atomic.Bool
// commandMayEmptyJSONLExport is set by destructive maintenance commands
// after they actually delete rows, allowing post-run auto-export to record
// an intentional empty JSONL artifact instead of treating it as ambiguous.
commandMayEmptyJSONLExport atomic.Bool
// commandDeletedIssueIDs is the in-process handoff from the delete
// commands to post-run auto-export: ids this command hard-deleted are
// PROVEN gone, so the export's orphan guard skips them instead of
// mistaking a deliberate delete for a torn store and refusing forever
// (GH#5896). See deletedIssueIDSet for why it is not persisted.
commandDeletedIssueIDs deletedIssueIDSet
// commandDidExplicitDoltCommit is set when a command already created a Dolt commit
// explicitly (e.g., bd sync in dolt-native mode, hook flows, bd vc commit).
// This prevents a redundant auto-commit attempt in PersistentPostRun.
commandDidExplicitDoltCommit bool
// commandDidWriteTipMetadata is set when a command records a tip as "shown" by writing
// metadata (tip_*_last_shown). This will be used to create a separate Dolt commit for
// tip writes, even when the main command is read-only.
commandDidWriteTipMetadata bool
// commandTipIDsShown tracks which tip IDs were shown in this command (deduped).
// This is used for tip-commit message formatting.
commandTipIDsShown map[string]struct{}
// commandFreeze is the migration-freeze lookup for this invocation,
// resolved once in PersistentPreRunE (dc-6jaq). Both hooks read it: the
// pre-run gate refuses writes from it, and PersistentPostRunE skips its
// own maintenance writes — auto-commit, tip metadata, backup, export,
// push — so a read command run during a freeze does not leave a new Dolt
// commit in the store being migrated. Zero value means "not frozen",
// which is the right default for the paths that never resolve it.
commandFreeze migration.Result
// commandSpan is the root OTel span for the current command execution.
// All storage and AI spans are nested as children of this span.
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{
"list": true,
"ready": true,
"show": true,
"stats": true,
"blocked": true,
"count": true,
"search": true,
"query": true,
"graph": true,
"duplicates": true,
"comments": true, // list comments (not add)
"current": true, // bd sync mode current
"ping": true,
"backup": true, // reads from Dolt, writes only to .beads/backup/
"export": true, // reads from Dolt, writes JSONL to file/stdout
"tail": true, // bd events tail: reads bd_events_journal, writes nothing
}
// isReadOnlyCommand returns true if the command only reads from the database.
// This is used to open the store in read-only mode, preventing file modifications
// that would trigger file watchers. See GH#804.
func isReadOnlyCommand(cmdName string) bool {
return readOnlyCommands[cmdName]
}
// isPreviewCommand reports whether cmd was explicitly invoked in a
// non-mutating preview mode. Preview flags are command-local rather than
// persistent, so checking them here after Cobra has parsed the selected
// command is the earliest reliable point to keep the store open read-only.
func isPreviewCommand(cmd *cobra.Command) bool {
for _, name := range []string{"dry-run", "inspect"} {
if flag := cmd.Flags().Lookup(name); flag != nil {
enabled, err := cmd.Flags().GetBool(name)
if err == nil && enabled {
return true
}
}
}
return false
}
type rootStorePolicy struct {
readOnly bool
disableAutoStart bool
runMaintenance bool
}
// effectiveRootStorePolicy separates strict --readonly/config policy from
// command classification. Classified reads retain their compatibility
// maintenance and auto-start behavior; strict readonly is mutation-free.
func effectiveRootStorePolicy(cmdName string, strictReadonly bool) rootStorePolicy {
return rootStorePolicy{
readOnly: strictReadonly || isReadOnlyCommand(cmdName),
disableAutoStart: strictReadonly,
runMaintenance: !strictReadonly,
}
}
// runsPostCommandMaintenance reports whether PersistentPostRunE should run the
// post-command maintenance net — Dolt auto-commit, the tip-metadata commit,
// auto-backup, auto-export and auto-push.
//
// `bd serve` is excluded, and not as an optimization. Those steps are per-
// COMMAND bookkeeping, and a server is not a command: it is a process that ran
// for hours and committed each mutation inside its own transaction as it
// happened. Running them when the operator finally sends SIGTERM would push and
// export on the way out of a signal handler — the worst possible moment — and
// attribute a whole process lifetime of requests to the shutdown. Proxied-mode
// serve never reached this branch at all (PersistentPostRunE only closes the
// provider there); server and shared-server mode do, so the exclusion has to be
// stated rather than inherited.
func runsPostCommandMaintenance(cmdName string, strictReadonly bool) bool {
if cmdName == serveCmdName {
return false
}
return effectiveRootStorePolicy(cmdName, strictReadonly).runMaintenance
}
// readMemoEnvVar turns the per-command http read memo off when set to "0": an
// operator who suspects a stale read can rule the memo out without a rebuild.
const readMemoEnvVar = "BD_HTTP_READ_MEMO"
// commandMemoizesReads reports whether this invocation's http transport may
// answer an identical row or settings read from a response it already received
// (httpclient.WithReadMemo, bts-xpw.3.14.6). A one-shot command may: it reads,
// writes and exits within seconds, and each write it makes drops the memo.
//
// A process that outlives its reads may not, and bd serve is excluded for the
// reason runsPostCommandMaintenance excludes it — a server is not a command.
// Over an http workspace it answers other clients, who must see what other
// writers changed. A --watch or --follow poll exists to see exactly those
// changes, and a memo would answer its polls from a snapshot instead.
// BD_HTTP_READ_MEMO=0 turns the memo off for every command.
func commandMemoizesReads(cmd *cobra.Command) bool {
if os.Getenv(readMemoEnvVar) == "0" {
return false
}
if cmd.Name() == serveCmdName {
return false
}
for _, name := range []string{"watch", "follow"} {
if f := cmd.Flags().Lookup(name); f != nil && f.Value.String() == "true" {
return false
}
}
return true
}
// resolveDoltServerConnection fills in how to reach the workspace's Dolt SQL
// server — host, port, socket, user, password, TLS — on doltCfg.
//
// Both consumers of a SQL server in this process go through here: the CLI's own
// store open, and the unit-of-work provider `bd serve` builds for a server-mode
// workspace. That matters more than the deduplication: an HTTP request and a
// CLI command in the same workspace must reach the same server as the same
// identity, and the only way to guarantee that is to resolve it once.
//
// It mirrors dolt.applyResolvedConfig, which this hand-built doltCfg path
// bypasses.
func resolveDoltServerConnection(ctx context.Context, beadsDir string, fileCfg *configfile.Config, doltCfg *dolt.Config) error {
doltCfg.ServerHost = fileCfg.GetDoltServerHost()
// Port 0 is fine here — auto-start will resolve it. Use the shared helper
// rather than DefaultConfig(...).Port: this hand-built doltCfg is handed
// straight to dolt.New, and a port arriving there without its source is
// read as a caller assertion (see ApplyResolvedServerPort).
dolt.ApplyResolvedServerPort(beadsDir, doltCfg)
doltCfg.ServerSocket = fileCfg.GetDoltServerSocket()
// A configured credential command targets an authenticating gateway server:
// run it for a short-lived token used as the connection username. Fail closed
// — never fall back to the static/root user when a command was configured but
// failed. Server mode only: embedded stores never present a username, so the
// command must not run (or fail) embedded opens even when the env var is set.
// Dolt-only: the gateway credential command mints a Dolt server
// username. IsSharedServerMode() forces ServerMode true with no backend
// guard, so non-Dolt metadata must not try to resolve a server username.
if doltCfg.ServerMode && fileCfg.GetBackend() == configfile.BackendDolt {
if _, err := dolt.ApplyGatewayCredential(ctx, fileCfg, doltCfg); err != nil {
return fmt.Errorf("resolving dolt credential command: %w", err)
}
}
if doltCfg.ServerUser == "" {
doltCfg.ServerUser = fileCfg.GetDoltServerUser()
}
// Use the resolved port for credential lookup — metadata.json port
// and runtime port can diverge (e.g., tunnel on 3308 vs local on 3307).
doltCfg.ServerPassword = fileCfg.GetDoltServerPasswordForPort(doltCfg.ServerPort)
doltCfg.ServerTLS = fileCfg.GetDoltServerTLS()
return nil
}
var (
runPostRunAutoCommit = maybeAutoCommit
runPostRunAutoBackup = maybeAutoBackup
runPostRunAutoExport = maybeAutoExport
runPostRunAutoPush = maybeAutoPush
)
// isWorkingSetReconcileCommand reports whether cmd's whole purpose is to
// reconcile the Dolt working set: "bd dolt commit" or "bd vc commit". These
// commands are the documented recovery from a pending-migration dirty-table
// refusal, but they also open the store, and an open runs the migration -
// hitting that same refusal before the commit that would clear the dirty
// state ever runs. Opening leniently (embeddeddolt.OpenForWorkingSetReconcile)
// breaks that deadlock by skipping the migration instead of failing the open
// (gastownhall/beads#4566).
func isWorkingSetReconcileCommand(cmd *cobra.Command) bool {
if cmd.Name() != "commit" {
return false
}
parent := cmd.Parent()
if parent == nil {
return false
}
return parent.Name() == "dolt" || parent.Name() == "vc"
}
// isRemoteSyncCommand reports whether cmd is `bd dolt pull`: the one command
// the #6575 data-behind migrate-gate refusal tells the operator to run.
//
// It is the same deadlock isWorkingSetReconcileCommand breaks for #4566, one
// refusal over. The gate stops a data-behind clone from migrating and names
// `bd dolt pull` as the remedy — but the pull opens the store too, so it hit
// that refusal before it could clear its cause. On an embedded clone there is
// no external `dolt` binary to fall back to, which left the refused clone with
// exactly one exit: BD_ALLOW_REMOTE_MIGRATE=1, i.e. performing the migration
// the refusal exists to prevent. Opening via embeddeddolt.OpenForRemoteSync /
// dolt.Config.RemoteSyncOpen tolerates that ONE gate reason and nothing else.
//
// Deliberately just the pull, not `bd sync`: sync also pushes and can write
// issue rows, and a write against a stale schema is the hazard the gate is
// about. The pull only moves the commit graph, which is precisely the
// precondition the refusal is waiting on.
func isRemoteSyncCommand(cmd *cobra.Command) bool {
if cmd.Name() != "pull" {
return false
}
parent := cmd.Parent()
return parent != nil && parent.Name() == "dolt"
}
// isForcedMigrate reports whether cmd is `bd migrate` or `bd migrate schema`
// invoked with --force: the operator confirming they are the single designated
// migrator, so the remote-migrate gate (#4259) must not block this run's store
// opens. Consulted in the root PersistentPreRunE because the gate fires during
// store open (and during autoMigrateOnVersionBump), long before the migrate
// command's own RunE.
func isForcedMigrate(cmd *cobra.Command) bool {
if cmd != migrateCmd && cmd != migrateSchemaCmd {
return false
}
force, _ := cmd.Flags().GetBool("force")
return force
}
// printGlobalDatabaseConsentHint adds the one thing the gate's own block
// cannot know: which database this invocation was aimed at. Under --global the
// open targets `beads_global`, so the block's `bd migrate schema` would
// migrate the PROJECT database and leave the refusal in place — the working
// remedy is the same verb with the same flag.
//
// It takes the refusal because "the same verb" is not the same verb on every
// arm: the #6575 data-behind stop on a shared store is remote-backed by
// construction, and there the bare verb's consent is never read (see
// schema.SharedConsentCommandForced), so retargeting the bare form would hand
// the operator a global-scoped command that still cannot succeed. This mirrors
// the retarget in handleRemoteMigrateGateJSON. A nil error keeps the
// pre-existing bare-verb wording, which is also the verb the
// migration-consent refusal prescribes, so that refusal passes nil.
func printGlobalDatabaseConsentHint(w io.Writer, e *schema.RemoteMigrateGateError) {
if !globalFlag {
return
}
consent := schema.SharedConsentCommandGlobal
if e != nil && e.IsDataBehind() && e.Shared {
consent = schema.SharedConsentCommandForcedGlobal
}
fmt.Fprintf(w,
"\n This command targeted the global database (--global), so run the\n"+
" migrate step with the same flag:\n"+
" %s\n",
consent)
}
// renderTypedOpenError prints the actionable block for the store-open failures
// that carry one, honoring --json, and reports whether it handled err. A false
// return means the caller should fall back to its own generic message.
//
// Every open path needs this — the Dolt store, the proxied unit-of-work
// provider, and `bd serve`'s startup. The proxied one used to render every
// failure as `%v` inside "failed to open uow provider", which turned a
// multi-line rebuild or migrate-consent guide into one truncated line.
func renderTypedOpenError(err error) bool {
// Schema skew gets dedicated UX with actionable rebuild instructions.
var skewErr *schema.SchemaSkewError
if errors.As(err, &skewErr) {
if jsonOutput {
handleSchemaSkewJSON(skewErr)
} else {
fmt.Fprint(os.Stderr, skewErr.UserMessage())
}
return true
}
// #4259 / #5920: the migrate gate blocks a silent in-place migration and
// tells the operator to migrate, adopt, or consent.
var gateErr *schema.RemoteMigrateGateError
if errors.As(err, &gateErr) {
if jsonOutput {
handleRemoteMigrateGateJSON(gateErr)
} else {
fmt.Fprint(os.Stderr, gateErr.UserMessage())
printGlobalDatabaseConsentHint(os.Stderr, gateErr)
}
return true
}
// The migration-consent gate blocks silent in-place migration of
// ANY existing database (1.2 release remediation) and tells the
// operator how to consent.
var consentErr *schema.MigrateConsentError
if errors.As(err, &consentErr) {
if jsonOutput {
handleMigrateConsentJSON(consentErr)
} else {
fmt.Fprint(os.Stderr, consentErr.UserMessage())
printGlobalDatabaseConsentHint(os.Stderr, nil)
}
return true
}
return false
}
// isSchemaMigrateVerb reports whether cmd is `bd migrate schema` — the one
// invocation in which the operator asked for a schema migration by name. That
// request is the consent the shared-store gate wants for a database with no
// remote (#5920), and the consent the migration-consent gate wants for any
// existing database; see schema.SetSharedMigrateConsent and
// schema.SetLocalMigrateConsent.
//
// Deliberately just this one command, not the `bd migrate` tree. Bare
// `bd migrate` reconciles version/repo-id/clone-id metadata and never applies
// a migration itself, and its flag modes are further from schema work still:
// `bd migrate --update-repo-id` is repo-fingerprint surgery after a git remote
// change, and treating it as consent would let a repo-ID update promote the
// schema for every co-resident client as a side effect. `bd migrate sync`,
// `bd migrate hooks`, and the mode-switch verbs consent to nothing either.
// The operator who does want to migrate has the verb this names, and
// `--force` still unlocks from either migrate command.
func isSchemaMigrateVerb(cmd *cobra.Command) bool {
return cmd == migrateSchemaCmd
}
// isMigrateConsentCommand reports whether invoking cmd is consent to apply
// pending schema migrations to an existing database (migrate_consent.go).
// That is `bd migrate schema` alone, the verb that names the migration: bare
// `bd migrate` does not consent, for the reasons isSchemaMigrateVerb gives,
// and --force on either migrate command consents separately, through the gate
// override. A preview withholds the consent, as it does the shared-store one:
// a --dry-run/--inspect must not consent to the work it only inspects.
func isMigrateConsentCommand(cmd *cobra.Command) bool {
return isSchemaMigrateVerb(cmd) && !isPreviewCommand(cmd)
}
// forcedMigratePreviewFlag returns the name of a preview flag (--dry-run,
// --inspect) that conflicts with --force on a forced migrate invocation, or ""
// when there is no conflict. The combination must be rejected BEFORE the store
// opens: with the gate override set, the open itself applies pending schema
// migrations, so the preview flag would be honored only after the destructive
// work it exists to prevent had already happened.
func forcedMigratePreviewFlag(cmd *cobra.Command) string {
for _, name := range []string{"dry-run", "inspect"} {
if v, err := cmd.Flags().GetBool(name); err == nil && v {
return name
}
}
return ""
}
// applyNoColorFlag disables colorized output when --no-color is set.
// Complements the NO_COLOR / CLICOLOR=0 env detection in package ui,
// giving callers a per-invocation override.
func applyNoColorFlag() {
if noColorFlag {
ui.DisableColors()
}
}
// loadBeadsEnvFile loads .beads/.env into process environment for per-project
// Dolt credentials (GH#2520). Uses gotenv.Load which is non-overriding —
// existing shell env vars always take precedence.
// Safe to call with an empty beadsDir (no-op).
func loadBeadsEnvFile(beadsDir string) {
if beadsDir == "" {
return
}
envFile := filepath.Join(beadsDir, ".env")
if _, err := os.Stat(envFile); err != nil {
return
}
// A .env-provided BEADS_DIR is user-authored selection wherever it is
// imported from, not only via loadBeadsSelectionEnvFile: that loader
// early-returns whenever BEADS_DB or BD_DB is already exported
// (loadSelectionEnvironment), and this broad loader then imports the very
// same .env line. Marking provenance here keeps one .env line meaning one
// thing, instead of target-role or CWD-role depending on the caller's
// unrelated BEADS_DB export.
beadsDirWasSet := os.Getenv("BEADS_DIR") != ""
_ = gotenv.Load(envFile)
if !beadsDirWasSet && os.Getenv("BEADS_DIR") != "" {
beadsDirProvidedAtStartup = true
}
}
func logConfigDiscovery(beadsDir, reason string) {
metadataPath := filepath.Join(beadsDir, configfile.ConfigFileName)
configYAMLPath := filepath.Join(beadsDir, "config.yaml")
_, metadataErr := os.Stat(metadataPath)
_, yamlErr := os.Stat(configYAMLPath)
debug.Logf("Debug: %s at %s -> metadata=%v (%v), config.yaml=%v (%v)\n",
reason, beadsDir, metadataErr == nil, metadataErr, yamlErr == nil, yamlErr)
}
func shouldLogDefaultDoltDatabase(cfg *configfile.Config) bool {
return cfg != nil && cfg.DoltDatabase == "" && os.Getenv("BEADS_DOLT_SERVER_DATABASE") == ""
}
// loadBeadsSelectionEnvFile loads only the selector keys needed for early
// workspace/database discovery. Unlike loadBeadsEnvFile, this intentionally
// limits itself to BEADS_DIR / BEADS_DB / BD_DB so caller credentials and
// runtime knobs do not leak into explicit-target commands before rebinding.
func loadBeadsSelectionEnvFile(beadsDir string) {
if beadsDir == "" {
return
}
envFile := filepath.Join(beadsDir, ".env")
pairs, err := gotenv.Read(envFile)
if err != nil {
return
}
for _, key := range []string{"BEADS_DIR", "BEADS_DB", "BD_DB"} {
if os.Getenv(key) != "" {
continue
}
if value, ok := pairs[key]; ok && strings.TrimSpace(value) != "" {
_ = os.Setenv(key, value)
if key == "BEADS_DIR" {
// A .beads/.env that routes commands via BEADS_DIR is
// user-authored selection, same as exporting the variable
// before running bd; role detection must honor it.
beadsDirProvidedAtStartup = true
}
}
}
}
// loadSelectionEnvironment loads only the selector keys required to discover
// the target workspace/database before the store-init path runs. This preserves
// historical support for .beads/.env files that route commands via BEADS_DB or
// BEADS_DIR without importing the caller workspace's broader runtime settings.
func loadSelectionEnvironment() {
if os.Getenv("BEADS_DIR") != "" || os.Getenv("BEADS_DB") != "" || os.Getenv("BD_DB") != "" {
return
}
if beadsDir := beads.FindBeadsDir(); beadsDir != "" {
loadBeadsSelectionEnvFile(beadsDir)
}
}
// loadEnvironment runs the lightweight, always-needed environment setup that
// must happen before the noDbCommands early return. This ensures commands like
// "bd doctor --server" pick up per-project Dolt credentials from .beads/.env.
//
// This function intentionally does NOT do any store initialization, auto-migrate,
// or telemetry setup — those belong in the store-init phase that runs after the
// noDbCommands check.
func loadEnvironment() {
// FindBeadsDir is lightweight (filesystem walk, no git subprocesses)
// and resolves BEADS_DIR, redirects, and worktree paths.
if beadsDir := beads.FindBeadsDir(); beadsDir != "" {
loadBeadsEnvFile(beadsDir)
// Non-fatal warning if .beads/ directory has overly permissive access.
config.CheckBeadsDirPermissions(beadsDir)
}
}
var sharedServerEmbeddedMismatchWarned bool
// warnSharedServerEmbeddedMismatch detects the case where shared-server mode
// is active but metadata.json explicitly pins dolt_mode=embedded. The
// shared-server setting wins for this invocation (GH#2946/2949: stale embedded
// metadata must not hide server-backed issue state), but bd never rewrites the
// committed metadata.json — per-machine environment must not leak into shared
// config (bd-6dnrw.5). Print guidance so the user resolves the conflict
// explicitly.
func warnSharedServerEmbeddedMismatch(cfg *configfile.Config) {
if cfg == nil || sharedServerEmbeddedMismatchWarned {
return
}
if strings.ToLower(strings.TrimSpace(cfg.DoltMode)) != configfile.DoltModeEmbedded {
return
}
if !doltserver.IsSharedServerMode() {
return
}
sharedServerEmbeddedMismatchWarned = true
fmt.Fprintln(os.Stderr, "Notice: shared-server mode is enabled (BEADS_DOLT_SHARED_SERVER or dolt.shared-server in config.yaml) but .beads/metadata.json pins dolt_mode=\"embedded\". Using the shared server for this run.")
fmt.Fprintln(os.Stderr, " To persist server mode: set dolt_mode to \"server\" in .beads/metadata.json and commit it.")
fmt.Fprintln(os.Stderr, " To stay embedded: unset BEADS_DOLT_SHARED_SERVER (or remove dolt.shared-server from config.yaml).")
}
// loadServerModeFromBeadsDir loads the storage mode (embedded vs server vs
// proxied-server) from the given beads directory's metadata.json so that
// usesSQLServer() and usesProxiedServer() return the correct values.
//
// A metadata.json that exists but cannot be loaded is a hard error: treating
// it like an absent file silently flips server-mode deployments onto the
// embedded store, where every query answers from an empty relic with exit 0
// (false-empty). Absent metadata.json (cfg == nil) keeps the fresh-repo
// embedded default.
func loadServerModeFromBeadsDir(beadsDir string) error {
if beadsDir == "" {
return nil
}
cfg, err := configfile.LoadForDiscovery(beadsDir)
if err != nil {
return fmt.Errorf("load %s: %w; no storage database was opened or modified (storage mode unknown; data commands refuse to fall back to the embedded store)", configfile.ConfigPath(beadsDir), err)
}
// Absent metadata.json keeps the fresh-repo embedded default unless
// env/config.yaml supply a remote host (GH#3545) — inference must not
// depend on metadata existing.
cfg = normalizeLoadedConfig(cfg)
warnSharedServerEmbeddedMismatch(cfg)
psm := cfg.IsDoltProxiedServerMode()
sm := cfg.IsDoltServerMode()
// GH#2946: shared-server override for stale metadata.json (no-db commands)
if !sm && !psm && doltserver.IsSharedServerMode() {
sm = true
}
serverMode = sm
proxiedServerMode = psm
if cmdCtx != nil {
cmdCtx.ServerMode = sm
cmdCtx.ProxiedServerMode = psm
}
return nil
}
// loadServerModeFromConfig loads the storage mode (embedded vs server vs
// proxied-server) from metadata.json so that usesSQLServer() and
// usesProxiedServer() return the correct values. Called for commands that
// skip full DB init but still need to know the mode.
func loadServerModeFromConfig() error {
return loadServerModeFromBeadsDir(beads.FindBeadsDir())
}
func preserveRedirectSourceDatabase(beadsDir string) {
if beadsDir == "" || os.Getenv("BEADS_DOLT_SERVER_DATABASE") != "" {
return
}
rInfo := beads.ResolveRedirect(beadsDir)
if rInfo.WasRedirected && rInfo.SourceDatabase != "" {
_ = os.Setenv("BEADS_DOLT_SERVER_DATABASE", rInfo.SourceDatabase)
if os.Getenv("BD_DEBUG_ROUTING") != "" {
fmt.Fprintf(os.Stderr, "[routing] Preserved source dolt_database %q across redirect\n", rInfo.SourceDatabase)
}
}
}
// explicitDBTargetGiven reports whether the caller named an explicit database
// target that overrides the ambient workspace. These are the three routes the
// PR body for be-fyt names and that selectedNoDBBeadsDir below honors ahead of
// the ambient repo: a --db value that resolves to a path (which lands in
// dbPath), BEADS_DB, and BD_DB.
//
// Deliberately NOT keyed on PersistentFlags().Changed("db"). A --db value that
// names a *database* rather than a path is moved to dbNameFromDBFlag and
// clears dbPath (~line 990), and that value is consumed only on the
// store-requiring path (~line 1553). On the no-DB path selectedNoDBBeadsDir
// therefore falls through to the ambient workspace anyway, so the ambient
// redirect source's database must still be preserved for it. Keying on
// Changed("db") would suppress that and reopen be-xil for
// `bd doctor --db <name>` in a redirected repo; see
// TestDoctorPersistentPreRunBareDBNameStillPreservesAmbientSourceDatabase.
//
// KNOWN GAP (be-bf75p): selectedNoDBBeadsDir honors a fourth route this
// predicate does not — BEADS_DIR != "" -> beads.FindBeadsDir() (~line 551) —
// so a BEADS_DIR naming a foreign target still inherits the ambient repo's
// redirect-source database. Reproduces only inside a git repo, because
// GetRedirectInfo reaches the ambient repo through findLocalBdsDirInRepo
// (internal/beads/beads.go:394), which keys off git.GetRepoRoot() alone.
// Emptiness is the wrong test for it: BEADS_DIR pre-set *to the redirect
// target* is bd-wayc3's own case, where preservation is wanted, so the fix has
// to compare BEADS_DIR against the redirect target rather than check that it
// is unset. That comparison is be-bf75p's, not this PR's.
func explicitDBTargetGiven() bool {
return dbPath != "" || os.Getenv("BEADS_DB") != "" || os.Getenv("BD_DB") != ""
}
func selectedNoDBBeadsDir(cmd *cobra.Command) string {
if cmd != nil && cmd.Root() != nil && cmd.Root().PersistentFlags().Changed("db") && dbPath != "" {
if selectedBeadsDir := resolveCommandBeadsDir(dbPath); selectedBeadsDir != "" {
return selectedBeadsDir
}
} else if cmd != nil && cmd.PersistentFlags().Changed("db") && dbPath != "" {
if selectedBeadsDir := resolveCommandBeadsDir(dbPath); selectedBeadsDir != "" {
return selectedBeadsDir
}
} else if envDB := os.Getenv("BEADS_DB"); envDB != "" {
if selectedBeadsDir := resolveCommandBeadsDir(envDB); selectedBeadsDir != "" {
return selectedBeadsDir
}
} else if envDB := os.Getenv("BD_DB"); envDB != "" {
if selectedBeadsDir := resolveCommandBeadsDir(envDB); selectedBeadsDir != "" {
return selectedBeadsDir
}
}
if os.Getenv("BEADS_DIR") != "" {
if selectedBeadsDir := beads.FindBeadsDir(); selectedBeadsDir != "" {
return selectedBeadsDir
}
}
if dbPath != "" {
if selectedBeadsDir := resolveCommandBeadsDir(dbPath); selectedBeadsDir != "" {
return selectedBeadsDir
}
}
return beads.FindBeadsDir()
}
func isSelectedNoDBCommand(cmd *cobra.Command) bool {
if cmd == nil {
return false
}
if cmd.Name() == "context" || cmd.Name() == "where" {
return true
}
if cmd.Parent() == nil || cmd.Parent().Name() != "dolt" {
return false
}
switch cmd.Name() {
case "push", "pull", "commit":
return false
default:
return true
}
}
// configCommandCanRunWithoutStore returns true for config subcommands whose Run
// path can execute without an opened Dolt store. This lets no-workspace calls
// fail or degrade in the command itself instead of tripping low-level DB init.
func configCommandCanRunWithoutStore(cmd *cobra.Command, args []string) bool {
if cmd == nil || cmd.Parent() == nil || cmd.Parent().Name() != "config" {
return false
}
switch cmd.Name() {
case "show", "validate", "drift", "apply":
return true
case "set", "get", "unset":
if len(args) == 0 {
return true
}
key := args[0]
return config.IsYamlOnlyKey(key) || key == "beads.role"
case "set-many":
if len(args) == 0 {
return true
}
for _, arg := range args {
key, _, ok := strings.Cut(arg, "=")
if !ok || key == "" {
return true
}
if !config.IsYamlOnlyKey(key) && key != "beads.role" {
return false
}
}
return true
default:
return false
}
}
func prepareSelectedCommandContext(beadsDir string, loadEnv bool) {
if beadsDir == "" {
return
}
_ = os.Setenv("BEADS_DIR", beadsDir)
if loadEnv {
loadBeadsEnvFile(beadsDir)
}
preserveRedirectSourceDatabase(beadsDir)
if err := config.Initialize(); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to reinitialize config for selected beads dir: %v\n", err)
}
config.CheckBeadsDirPermissions(beadsDir)
if err := loadServerModeFromBeadsDir(beadsDir); err != nil {
// Warn, don't fatal: this context also serves no-DB commands —
// doctor, init, bootstrap, config — which are exactly the repair
// paths for a corrupt metadata.json. Data commands stay protected
// by the hard error at store init and in the store factories.
fmt.Fprintf(os.Stderr, "warning: %v\n", err)
}
}
func prepareSelectedNoDBContext(beadsDir string) {
prepareSelectedCommandContext(beadsDir, true)
}
func commandJSONFlagChanged(cmd *cobra.Command) bool {
if cmd == nil {
return false
}
if cmd.Flags().Changed("json") {
return true
}
root := cmd.Root()
return root != nil && root.PersistentFlags().Changed("json")
}
// refreshBoundCommandConfig reapplies config-backed defaults after the command
// context has been rebound to a resolved target beads directory. This keeps
// explicit flags authoritative while letting rerouted/explicit-db commands use
// the target repo's config rather than the caller's config.
func refreshBoundCommandConfig(cmd *cobra.Command) {
if cmd == nil {
return
}
root := cmd.Root()
if root == nil {
root = cmd
}
if !commandJSONFlagChanged(cmd) && !root.PersistentFlags().Changed("format") {
jsonOutput = config.GetBool("json")
}
if !root.PersistentFlags().Changed("readonly") {
readonlyMode = config.GetBool("readonly")
}
if !root.PersistentFlags().Changed("actor") {
// Raw write, not setActor: every caller runs in PersistentPreRunE
// BEFORE deferActorGitFallback, which then decides from this value
// whether the git user.name fallback is pending. A call after it would
// need setActor (and the deferral re-run) to keep that decision true.
actor = resolveConfiguredActor()
}
if !root.PersistentFlags().Changed("dolt-auto-commit") {
doltAutoCommit = config.GetString("dolt.auto-commit")
}
}
// resolveCommandBeadsDir maps a discovered Dolt data path back to the owning
// .beads directory. filepath.Dir(dbPath) only works when the Dolt data lives
// under .beads/dolt; custom dolt_data_dir values can place it elsewhere.
func resolveCommandBeadsDir(dbPath string) string {
if dbPath == "" {
return ""
}
// Use the same validated candidate logic as the helper/reopen path
// (GH#2627). This checks filepath.Dir, canonicalized paths, AND
// FindBeadsDir — but only returns a candidate whose metadata.json
// actually points to dbPath, preventing CWD discovery from overriding
// an explicit --db flag.
if beadsDir := resolveBeadsDirForDBPath(dbPath); beadsDir != "" {
return beadsDir
}
bound := ceiling.For(filepath.Dir(dbPath))
for dir := filepath.Dir(dbPath); dir != "" && dir != filepath.Dir(dir) && !bound.Excludes(dir); dir = filepath.Dir(dir) {
candidate := filepath.Join(dir, ".beads")
if info, err := os.Stat(candidate); err == nil && info.IsDir() {
return candidate
}
}
// No candidate matched — fall back to parent directory of the db path.
// This handles bootstrap/init where no metadata.json exists yet.
return filepath.Dir(dbPath)
}
// resolveConfiguredActor returns the actor implied by env/config when no
// explicit --actor flag was passed, honoring the documented priority
// BEADS_ACTOR > BD_ACTOR (deprecated) > config.yaml `actor`.
//
// viper's AutomaticEnv binds the deprecated BD_ACTOR to the "actor" key (env
// prefix "BD"), and it is consulted ahead of any explicit binding — so
// config.GetString("actor") alone returns BD_ACTOR's value even when
// BEADS_ACTOR is also set, silently letting the deprecated alias win (GH#4645).
// Check BEADS_ACTOR explicitly first so the primary override outranks it.
func resolveConfiguredActor() string {
if beadsActor := os.Getenv("BEADS_ACTOR"); beadsActor != "" {
return beadsActor
}
return config.GetString("actor")
}
// actorGitFallbackPending records that PersistentPreRunE deferred the
// getActorWithGit fallback (git config user.name, then $USER) instead of
// resolving it eagerly. Most invocations — every read-only list/show/query a
// tool like gascity issues by the hundred — never consult the actor, and the
// eager lookup cost one `git config` subprocess per bd call. currentActor
// performs the deferred resolution on first use, so the resolved value and its
// priority order are unchanged; only the moment of the lookup moves.
//
// Guarded by actorMu together with the resolution it triggers. Plain writes to
// actor elsewhere stay unguarded, exactly as before this was introduced.
var (
actorMu sync.Mutex
actorGitFallbackPending bool
)
// deferActorGitFallback replaces the former eager `actor = getActorWithGit()`
// in PersistentPreRunE. A non-empty actor (--actor, BEADS_ACTOR, BD_ACTOR or
// config.yaml) is already the answer getActorWithGit would return, so only an
// empty actor needs the deferred fallback.
func deferActorGitFallback() {
actorMu.Lock()
defer actorMu.Unlock()
actorGitFallbackPending = actor == ""
}
// currentActor returns the actor for this invocation, resolving a fallback
// deferred by deferActorGitFallback on first use. Command code reads the actor
// through this instead of the raw global so that the git lookup happens only
// when an actor is actually needed.
func currentActor() string {
actorMu.Lock()
defer actorMu.Unlock()
resolvePendingActorLocked()
return actor
}
// resolvePendingActorLocked performs a deferred fallback. Caller holds actorMu.
func resolvePendingActorLocked() {
if !actorGitFallbackPending {
return
}
actorGitFallbackPending = false
deferred := actor
actor = resolveActorWithGit()
// Keep the CommandContext copy in step, as the eager assignment did
// before syncCommandContext copied it.
if cmdCtx != nil && cmdCtx.Actor == deferred {
cmdCtx.Actor = actor
}
}
// getActorWithGit returns the actor for audit trails with git config fallback.
// Priority: --actor flag > BEADS_ACTOR env > BD_ACTOR env (deprecated) > git config user.name > $USER > "unknown"
// This provides a sensible default for developers: their git identity is used unless
// explicitly overridden.
//
// After PersistentPreRunE it returns the same value as currentActor (resolving
// a deferred fallback once, into the global, as the eager assignment did).
func getActorWithGit() string {
actorMu.Lock()
defer actorMu.Unlock()
resolvePendingActorLocked()
return resolveActorWithGit()
}
// resolveActorWithGit is getActorWithGit's resolution order, without the
// deferred-fallback bookkeeping. Caller holds actorMu or owns the global.
func resolveActorWithGit() string {
// If actor is already set (from --actor flag), use it
if actor != "" {
return actor
}
// Check BEADS_ACTOR env var (primary env override)
if beadsActor := os.Getenv("BEADS_ACTOR"); beadsActor != "" {
return beadsActor
}
// Check BD_ACTOR env var (deprecated alias, kept for backwards compatibility)
if bdActor := os.Getenv("BD_ACTOR"); bdActor != "" {
return bdActor
}
// Try git config user.name - the natural default for a git-native tool
if out, err := exec.Command("git", "config", "user.name").Output(); err == nil {
if gitUser := strings.TrimSpace(string(out)); gitUser != "" {
return gitUser
}
}
// Fall back to system username
if user := os.Getenv("USER"); user != "" {
return user
}
return "unknown"
}
// getOwner returns the human owner for CV attribution.
// Priority: GIT_AUTHOR_EMAIL env > git config user.email > "" (empty)
// This is the foundation for HOP CV (curriculum vitae) chains per Decision 008.
// Unlike actor (which tracks who executed), owner tracks the human responsible.
func getOwner() string {
// Check GIT_AUTHOR_EMAIL first - this is set during git commit operations
if authorEmail := os.Getenv("GIT_AUTHOR_EMAIL"); authorEmail != "" {
return authorEmail
}
// Fall back to git config user.email - the natural default
if out, err := exec.Command("git", "config", "user.email").Output(); err == nil {
if gitEmail := strings.TrimSpace(string(out)); gitEmail != "" {
return gitEmail
}
}
// Return empty if no email found (owner is optional)
return ""
}
func init() {
// Initialize viper configuration
if err := config.Initialize(); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to initialize config: %v\n", err)
}
// Register persistent flags
rootCmd.PersistentFlags().StringVarP(&changeDir, "directory", "C", "", "Change to this directory before running the command (like git -C)")
rootCmd.PersistentFlags().StringVar(&dbPath, "db", "", "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)")
rootCmd.PersistentFlags().StringVar(&databaseFlag, "database", "", "Run against a different server database for this invocation, without changing the project's configured database (proxied-server mode only)")
rootCmd.PersistentFlags().StringVar(&actor, "actor", "", "Actor name for audit trail (default: $BEADS_ACTOR, git user.name, $USER)")
rootCmd.PersistentFlags().BoolVar(&jsonOutput, "json", false, "Output in JSON format")
rootCmd.PersistentFlags().String("format", "", "Output format (json). Alias for --json")
_ = rootCmd.PersistentFlags().MarkHidden("format") // Hidden alias for CLI ergonomics
rootCmd.PersistentFlags().BoolVar(&sandboxMode, "sandbox", false, "Sandbox mode: disables Dolt auto-push")
rootCmd.PersistentFlags().BoolVar(&readonlyMode, "readonly", false, "Read-only mode: block write operations (for worker sandboxes)")
rootCmd.PersistentFlags().BoolVar(&globalFlag, "global", false, "Use the global shared-server database (beads_global)")
rootCmd.PersistentFlags().StringVar(&doltAutoCommit, "dolt-auto-commit", "", "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")
rootCmd.PersistentFlags().BoolVar(&cpuProfileEnabled, "cpu-profile", false, "Generate CPU profile for performance analysis")
rootCmd.PersistentFlags().StringVar(&memProfilePath, "mem-profile", "", "Write heap profile to FILE on exit (also respects BEADS_MEM_PROFILE)")
rootCmd.PersistentFlags().BoolVarP(&verboseFlag, "verbose", "v", false, "Enable verbose/debug output")
rootCmd.PersistentFlags().BoolVarP(&quietFlag, "quiet", "q", false, "Suppress non-essential output (errors only)")
rootCmd.PersistentFlags().BoolVar(&ignoreSchemaSkew, "ignore-schema-skew", false, "Proceed despite forward schema drift (some queries may fail)")
rootCmd.PersistentFlags().BoolVar(&noColorFlag, "no-color", false, "Disable color output (also: NO_COLOR=1 or CLICOLOR=0)")
// Add --version flag to root command (same behavior as version subcommand)
rootCmd.Flags().BoolP("version", "V", false, "Print version information")
// Command groups for organized help output (Tufte-inspired)
rootCmd.AddGroup(&cobra.Group{ID: "issues", Title: "Working With Issues:"})
rootCmd.AddGroup(&cobra.Group{ID: "views", Title: "Views & Reports:"})
rootCmd.AddGroup(&cobra.Group{ID: "deps", Title: "Dependencies & Structure:"})
rootCmd.AddGroup(&cobra.Group{ID: "sync", Title: "Sync & Data:"})
rootCmd.AddGroup(&cobra.Group{ID: "setup", Title: "Setup & Configuration:"})
// NOTE: Many maintenance commands (clean, cleanup, compact, validate, repair-deps)
// should eventually be consolidated into 'bd doctor' and 'bd doctor --fix' to simplify
// the user experience. The doctor command can detect issues and offer fixes interactively.
rootCmd.AddGroup(&cobra.Group{ID: "maint", Title: "Maintenance:"})
rootCmd.AddGroup(&cobra.Group{ID: "advanced", Title: "Integrations & Advanced:"})
// Custom help function with semantic coloring (Tufte-inspired)
// Note: Usage output (shown on errors) is not styled to avoid recursion issues
rootCmd.SetHelpFunc(colorizedHelpFunc)
}
func resolveChangeDirBeadsDir(path string) (string, error) {
if strings.TrimSpace(path) == "" {
return "", nil
}
absPath, err := filepath.Abs(path)
if err != nil {
return "", fmt.Errorf("cannot resolve -C directory %q: %w", path, err)
}
info, err := os.Stat(absPath)
if err != nil {
return "", fmt.Errorf("cannot use -C directory %q: %w", path, err)
}
if !info.IsDir() {
return "", fmt.Errorf("cannot use -C directory %q: not a directory", path)
}
beadsDir := beads.FindBeadsDirFrom(absPath)
if beadsDir == "" {
return "", fmt.Errorf("cannot use -C directory %q: no beads project found", path)
}
return beadsDir, nil
}
// beadsDirProvidedAtStartup records whether BEADS_DIR carries user intent: it
// was present in the environment when the process started, or a .beads/.env
// selector file set it (loadBeadsSelectionEnvFile). Internal rebinds set
// BEADS_DIR for every command (prepareSelectedCommandContext,
// applyChangeDirSelection), so by the time role detection runs, the live env
// var can no longer say who set it.
var beadsDirProvidedAtStartup = os.Getenv("BEADS_DIR") != ""
// explicitBeadsSelection reports whether the active beads project was selected
// by the user (bd -C, or BEADS_DIR exported before bd ran) rather than
// discovered from the CWD — including discovery through a .beads/redirect,
// which relocates storage but must not move role detection off the workspace.
func explicitBeadsSelection() bool {
return beadsDirProvidedAtStartup || strings.TrimSpace(changeDir) != ""
}
func applyChangeDirSelection() error {
if strings.TrimSpace(changeDir) == "" {
return nil
}
beadsDir, err := resolveChangeDirBeadsDir(changeDir)
if err != nil {
return HandleError("%v", err)
}
changeDirEnvSnapshot = make(map[string]envSnapshotValue, 3)
for _, key := range []string{"BEADS_DIR", "BEADS_DB", "BD_DB"} {
value, ok := os.LookupEnv(key)
changeDirEnvSnapshot[key] = envSnapshotValue{value: value, ok: ok}
}
_ = os.Setenv("BEADS_DIR", beadsDir)
return nil
}
func restoreChangeDirSelection() {
if changeDirEnvSnapshot == nil {
return
}
for key, snapshot := range changeDirEnvSnapshot {
if snapshot.ok {
_ = os.Setenv(key, snapshot.value)
} else {
_ = os.Unsetenv(key)
}
}
changeDirEnvSnapshot = nil
}
func guardLegacyNoStoreCommand(cmd *cobra.Command, beadsDir string) error {
if cmd == nil || !cmd.Runnable() || cmd.Parent() == nil || cmd == versionCmd ||
cmd == doctorCmd || cmd == initCmd || cmd == bootstrapCmd ||
cmd == legacySQLiteCmd {
return nil
}
if cmd == schemaCmd && cmd.Parent() != nil && cmd.Parent().Parent() == nil {
return nil
}
for current := cmd; current != nil; current = current.Parent() {
if current == metricsCmd {
return nil
}
}
switch cmd.Name() {
case "__complete", "__completeNoDesc", "bash", "completion", "fish", "help", "powershell", "zsh":
return nil
}
if beadsDir == "" {
return guardUndiscoveredLegacyWorkspace()
}
return guardLegacyUpgradeWorkspace(beadsDir)
}
var rootCmd = &cobra.Command{
Use: "bd",
Short: "bd - Dependency-aware issue tracker",
Long: `Issues chained together like beads. A lightweight issue tracker with first-class dependency support.`,
Run: func(cmd *cobra.Command, args []string) {
// Handle --version flag on root command
if v, _ := cmd.Flags().GetBool("version"); v {
fmt.Printf("bd version %s (%s)\n", Version, Build)
return
}
// No subcommand - show help
_ = cmd.Help() // Help() always returns nil for cobra commands
},
PersistentPreRunE: func(cmd *cobra.Command, args []string) (retErr error) {
if err := clearWorktreeGitRoutingEnv(cmd); err != nil {
return err
}
applyNoColorFlag()
// Initialize CommandContext to hold runtime state (replaces scattered globals)
initCommandContext()
// Reset per-command write tracking (used by Dolt auto-commit).
commandDidWrite.Store(false)
commandMayEmptyJSONLExport.Store(false)
commandDeletedIssueIDs.reset()
commandDidExplicitDoltCommit = false
commandDidWriteTipMetadata = false
commandTipIDsShown = make(map[string]struct{})
commandFreeze = migration.Result{}
// Set up signal-aware context with batch commit flush on shutdown.
// Unlike signal.NotifyContext, this also handles SIGHUP and flushes
// pending batch commits before canceling the context.
//
// Publish through setRootContext, not a bare assignment to the
// globals: cmdCtx exists by now (initCommandContext above), so
// getRootContext() reads cmdCtx.RootCtx, and the commands that
// return early from this hook -- every skipsStoreInit command,
// migrate among them -- never reach syncCommandContext to have it
// backfilled. A bare assignment leaves those commands reading a nil
// per-command context and losing Ctrl-C entirely.
setRootContext(setupGracefulShutdown())
// Initialize OTel. Telemetry is opt-in — initTelemetry is a noop
// unless BD_OTEL_ENABLED=true or a legacy BD_OTEL_* selector is set.
// Must run before any DB access so SQL spans nest under the command
// span.
initTelemetry(rootCtx, Version)
// Materialize the user-level metrics config only when metrics are
// actually enabled. When metrics are disabled (BD_DISABLE_METRICS or a
// user-global metrics.disabled), there is nothing to bootstrap. The
// send-metrics flusher is exempt so it never recurses into bootstrap.
// This mirrors the resolveMetricsEnabled() gate on the first-run notice
// below. (~/.config/bd/ lives outside the repo, so this write is not a
// stealth/per-repository trace; stealth init is handled by suppressing
// the first-run notice, not by skipping this user-global bootstrap.)
if cmd.Name() != metrics.SendMetricsSubcommand && resolveMetricsEnabled() {
if err := metrics.EnsureUserConfigDefaults(); err != nil {
debug.Logf("warning: ensure user config defaults failed: %v", err)
}
}
if _, err := metrics.Init(Version, resolveMetricsEnabled(), resolveMetricsEndpoint()); err != nil {
debug.Logf("warning: metrics init failed: %v", err)
}
if cmd.Name() == metrics.SendMetricsSubcommand {
return nil
}
// Start root span for this command. rootCtx now carries the span, so
// all downstream DB and AI calls become child spans automatically.
rootCtx, commandSpan = startCommandSpan(rootCtx, cmd.Name(), Version, os.Args[1:], secretFlagTokens(cmd))
// Apply verbosity flags early (before any output)
debug.SetVerbose(verboseFlag)
debug.SetQuiet(quietFlag)
if err := applyChangeDirSelection(); err != nil {
return err
}
// Block dangerous env var overrides that could cause data fragmentation (bd-hevyw).
if err := checkBlockedEnvVars(); err != nil {
return HandleError("%v", err)
}
loadSelectionEnvironment()
// Apply viper configuration if flags weren't explicitly set
// Priority: flags > viper (config file + env vars) > defaults
// Do this BEFORE early-return so init/version/help respect config
// Track flag overrides for notification (only in verbose mode)
flagOverrides := make(map[string]struct {
Value interface{}
WasSet bool
})
// Handle --format json alias (desire-path from GH#2612)
if cmd.Root().PersistentFlags().Changed("format") {
format, _ := cmd.Root().PersistentFlags().GetString("format")
if strings.EqualFold(format, "json") {
jsonOutput = true
}
}
// If flag wasn't explicitly set, use viper value.
//
// SHADOWING HAZARD (GH#6278): this reads the ROOT persistent --format
// only, so a subcommand that registers its own local --format shadows
// it here and still gets `json: true` promoted over the format it was
// asked for. `bd list` compensates in gatherListInput; any new local
// --format registration needs the same treatment or this fires again.
if !commandJSONFlagChanged(cmd) && !cmd.Root().PersistentFlags().Changed("format") {
jsonOutput = config.GetBool("json")
} else {
flagOverrides["json"] = struct {
Value interface{}
WasSet bool
}{jsonOutput, true}
}
if !cmd.Root().PersistentFlags().Changed("readonly") {
readonlyMode = config.GetBool("readonly")
} else {
flagOverrides["readonly"] = struct {
Value interface{}
WasSet bool
}{readonlyMode, true}
}
var dbNameFromDBFlag string
if cmd.Name() != "init" && cmd.Root().PersistentFlags().Changed("db") && dbPath != "" &&
dbidentifier.ValidateIdentifier(dbPath) == nil {
if _, statErr := os.Stat(dbPath); statErr != nil {
if !os.IsNotExist(statErr) {
return HandleError("--db %q: %v", dbPath, statErr)
}
dbNameFromDBFlag = dbPath
dbPath = ""
}
}
if !cmd.Root().PersistentFlags().Changed("db") && dbPath == "" &&
os.Getenv("BEADS_DB") == "" && os.Getenv("BD_DB") == "" && os.Getenv("BEADS_DIR") == "" {
dbPath = config.GetString("db")
} else if cmd.Root().PersistentFlags().Changed("db") {
flagOverrides["db"] = struct {
Value interface{}
WasSet bool
}{dbPath, true}
}
// Reads and writes the raw global on purpose: this runs before
// deferActorGitFallback, so no fallback is pending yet and the value
// is only the flag/env/config actor. currentActor() here would resolve
// git user.name eagerly, which is what the deferral exists to avoid.
if !cmd.Root().PersistentFlags().Changed("actor") && actor == "" {
actor = resolveConfiguredActor()
} else if cmd.Root().PersistentFlags().Changed("actor") {
flagOverrides["actor"] = struct {
Value interface{}
WasSet bool
}{actor, true}
}
if !cmd.Root().PersistentFlags().Changed("dolt-auto-commit") && strings.TrimSpace(doltAutoCommit) == "" {
doltAutoCommit = config.GetString("dolt.auto-commit")
} else if cmd.Root().PersistentFlags().Changed("dolt-auto-commit") {
flagOverrides["dolt-auto-commit"] = struct {
Value interface{}
WasSet bool
}{doltAutoCommit, true}
}
// --ignore-schema-skew sets BD_IGNORE_SCHEMA_SKEW so the env-var escape
// hatch works uniformly for all store open paths (dolt, embedded).
if ignoreSchemaSkew {
_ = os.Setenv("BD_IGNORE_SCHEMA_SKEW", "1")
}
// Check for and log configuration overrides (only in verbose mode)
if verboseFlag {
overrides := config.CheckOverrides(flagOverrides)
for _, override := range overrides {
config.LogOverride(override)
}
}
// 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)
"bash",
"bootstrap",
"completion",
"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" 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
"help",
"hook", // manages its own store lifecycle (#1719)
"hooks",
"human",
"init",
"merge",
"metrics", // config-only: status/on/off/example never touch the DB
"onboard",
"powershell",
"prime",
"quickstart",
metrics.SendMetricsSubcommand,
"setup",
"version",
"where",
"zsh",
}
// GH#2042: Dolt subcommands that need the store for version-control operations.
// All other dolt subcommands (show, set, test, start, stop, status) are
// config/diagnostic commands that skip DB init via the "dolt" parent entry above.
needsStoreDoltSubcommands := []string{"push", "pull", "commit"}
// GH#2224: Dolt grandchild subcommands (e.g. "bd dolt remote add") whose
// Cobra parent is "remote", not "dolt". These need the store but would be
// silently skipped if "remote" were ever added to noDbCommands.
needsStoreDoltGrandchildren := []string{"remote"}
// bd-m7zzd: "human" is listed in noDbCommands for its bare help
// screen, but list/respond/dismiss/stats are DB-backed. Without this
// they skip store init entirely, which direct mode papered over by
// lazily opening a store via ensureStoreActive() — and which in
// proxied mode left no UOW provider for the proxied duals.
needsStoreHumanSubcommands := []string{"list", "respond", "dismiss", "stats"}
skipStoreMigrateSubcommands := []string{"from-server-to-proxied-server", "from-proxied-server-to-server", "from-shared-server-to-proxied-server", "from-proxied-server-to-shared-server"}
// Check both the command name and parent command name for subcommands
cmdName := cmd.Name()
isSubcommand := cmd.Parent() != nil && cmd.Parent().Name() != "bd"
skipsStoreInit := false
if cmd.Parent() != nil {
parentName := cmd.Parent().Name()
if parentName == "dolt" && slices.Contains(needsStoreDoltSubcommands, cmdName) {
// GH#2042: dolt push/pull/commit need the store — fall through to init
} else if slices.Contains(needsStoreDoltGrandchildren, parentName) {
// GH#2224: dolt remote add/list/remove need the store — fall through to init
} else if parentName == "human" && slices.Contains(needsStoreHumanSubcommands, cmdName) {
// bd-m7zzd: human list/respond/dismiss/stats need the store — fall through to init
} else if parentName == "migrate" && slices.Contains(skipStoreMigrateSubcommands, cmdName) {
skipsStoreInit = true
} else if slices.Contains(noDbCommands, parentName) {
skipsStoreInit = true
}
}
// Only skip for top-level commands in noDbCommands, not subcommands
// that happen to share names (e.g., "bd backup init" vs "bd init").
if slices.Contains(noDbCommands, cmdName) && !isSubcommand {
skipsStoreInit = true
}
// Skip for root command with no subcommand (just shows help)
if cmd.Parent() == nil && cmdName == cmd.Use {
skipsStoreInit = true
}
// Also skip for --version flag on root command (cmdName would be "bd")
if v, _ := cmd.Flags().GetBool("version"); v {
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
// stays suppressed in JSON/hook/protocol/quiet/stealth contexts and never
// corrupts machine-readable output. No-op after the first run.
maybeShowMetricsFirstRunNotice(cmd)
// Commands that skip store initialization still need early config/env
// setup before they inspect server mode or per-project Dolt settings.
// Rebind them to the selected workspace so explicit --db / BEADS_DB
// targets behave consistently across doctor/bootstrap/context/dolt.
//
// Capture redirect info BEFORE selectedNoDBBeadsDir() resolves the
// beads dir, mirroring the store-requiring path below (be-xil):
// selectedNoDBBeadsDir() always returns the post-redirect target
// directory (every branch bottoms out in beads.FindBeadsDir() or a
// dbPath already resolved through it, both of which call
// FollowRedirect internally). Calling preserveRedirectSourceDatabase
// with that already-resolved target means beads.ResolveRedirect finds
// no redirect file there and silently never preserves the source's
// configured dolt_database — so doctor (and other no-DB commands)
// would fall through to the shared target directory's own default
// database instead of the source's, producing false "wrong database"
// diagnoses against an unrelated rig's schema.
if skipsStoreInit {
// be-fyt round 1: only preserve when the caller did NOT name an
// explicit target. beads.GetRedirectInfo() always resolves from the
// ambient CWD repo's local .beads regardless of --db/BEADS_DIR
// (bd-wayc3), so calling it unconditionally let an explicit --db/
// BEADS_DB/BD_DB target's own database be silently shadowed by the
// ambient repo's unrelated redirect-source database — reopening
// be-xil's failure mode via a narrower trigger.
//
// Round 2 (review of PR #5774): the guard was spelled `dbPath == ""`,
// but dbPath is populated from BEADS_DB/BD_DB only when those are
// *unset* (~line 1002), so both env routes slipped straight through
// a guard that claimed to cover them while selectedNoDBBeadsDir
// (~lines 519, 523) rebound BEADS_DIR to the explicit target — the
// two disagreed. explicitDBTargetGiven now covers all three of the
// routes that populate dbPath/BEADS_DB/BD_DB.
//
// It does NOT cover selectedNoDBBeadsDir's fourth route, BEADS_DIR
// (~line 551), so the two predicates still disagree there and a
// foreign BEADS_DIR target inherits the ambient repo's
// redirect-source database — inside a git repo only. Measured, not
// assumed; tracked and specified as be-bf75p. See the KNOWN GAP
// paragraph on explicitDBTargetGiven for why emptiness is the wrong
// test and what the fix has to compare instead.
if !explicitDBTargetGiven() {
preserveRedirectSourceDatabase(beads.GetRedirectInfo().LocalDir)
}
beadsDir := selectedNoDBBeadsDir(cmd)
prepareSelectedNoDBContext(beadsDir)
refreshBoundCommandConfig(cmd)
if os.Getenv("BEADS_DIR") == "" {
loadEnvironment()
if err := loadServerModeFromConfig(); err != nil {
// Warn, don't fatal: skipsStoreInit commands (doctor,
// init, bootstrap, version, ...) never select a store,
// and several of them are the repair path for the very
// corruption being reported.
fmt.Fprintf(os.Stderr, "warning: %v\n", err)
}
}
if beadsDir == "" {
beadsDir = beads.FindBeadsDir()
}
if commandRegistryPath(cmd) == "doctor" && usesProxiedServer() {
// Refuse only on a real refusal. The registry validator
// returns nil for doctor subcommands, and returning early on
// that would skip the legacy-store guard and autocommit-mode
// resolution every other skipsStoreInit command still runs.
if err := validateProxyRegistryBeforeProvider(cmd, resolveProxiedTopology(beadsDir)); err != nil {
return err
}
}
if err := guardLegacyNoStoreCommand(cmd, beadsDir); err != nil {
if isUnsupportedWorkspaceFormat(err) {
return handleWorkspaceGuardError(err)
}
isMigrationCommand := false
for current := cmd; current != nil; current = current.Parent() {
if current.Name() == "migrate" {
isMigrationCommand = true
break
}
}
if isMigrationCommand {
return HandleProxyCapabilityError(&ProxyCapabilityError{Code: "proxy.migrate.invalid_state", Message: err.Error(), ExitCode: 1, Mutates: false})
}
return HandleError("%v", err)
}
if _, err := getDoltAutoCommitMode(); err != nil {
return HandleError("%v", err)
}
}
if skipsStoreInit {
return nil
}
// Performance profiling setup
if cpuProfileEnabled {
timestamp := time.Now().Format("20060102-150405")
if f, _ := os.Create(fmt.Sprintf("bd-profile-%s-%s.prof", cmd.Name(), timestamp)); f != nil {
profileFile = f
_ = pprof.StartCPUProfile(f) // Best effort: profiling is a debug tool, failure is non-fatal
}
if f, _ := os.Create(fmt.Sprintf("bd-trace-%s-%s.out", cmd.Name(), timestamp)); f != nil {
traceFile = f
_ = trace.Start(f) // Best effort: profiling is a debug tool, failure is non-fatal
}
}
// Auto-detect sandboxed environment (Phase 2 for GH #353)
if !cmd.Root().PersistentFlags().Changed("sandbox") {
if isSandboxed() {
sandboxMode = true
fmt.Fprintf(os.Stderr, "ℹ️ Sandbox detected, using direct mode\n")
}
}
// Capture redirect info BEFORE FindDatabasePath() follows the redirect.
// When .beads/redirect points to a shared directory with a different
// dolt_database, the source's database name would be lost. Capture it
// early and set BEADS_DOLT_SERVER_DATABASE so all store opens use it.
if dbPath == "" {
preserveRedirectSourceDatabase(beads.GetRedirectInfo().LocalDir)
}
if dbPath == "" {
if bd := beads.FindBeadsDir(); bd != "" {
// Bind the discovered target before admission so the legacy guard
// honors its config.yaml (including dolt.shared-server), not the
// caller's. This setup is read-only: metadata discovery below still
// uses LoadForDiscovery and cannot migrate config.json.
prepareSelectedCommandContext(bd, true)
refreshBoundCommandConfig(cmd)
if guardErr := guardLegacyUpgradeWorkspace(bd); guardErr != nil {
return handleWorkspaceGuardError(guardErr)
}
cfg, cfgErr := configfile.LoadForDiscovery(bd)
if cfgErr != nil || cfg != nil && (cfg.IsDoltProxiedServerMode() ||
registeredBackendWorkspaceIsBeadsDir(cfg) ||
!configfile.IsSupportedBackend(cfg.Backend)) {
// Proxied-server, registered remote, and removed-backend
// workspaces may have no local Dolt database file. Invalid
// or unknown metadata likewise must reach config validation
// instead of becoming a generic "no database" result.
dbPath = bd
} else if cfg == nil && cfgErr == nil &&
configfile.DefaultConfig().HostImpliesServerMode() {
// Metadata-less workspace whose server lives at a
// remote host named by BEADS_DOLT_SERVER_HOST or
// config.yaml (GH#3545): there is no local database
// directory to discover, so route the .beads dir as
// a server workspace instead of "no database found".
dbPath = bd
}
} else if guardErr := guardUndiscoveredLegacyWorkspace(); guardErr != nil {
return handleWorkspaceGuardError(guardErr)
}
}
// Initialize database path
if dbPath == "" {
// Use public API to find database (same logic as extensions)
if foundDB := beads.FindDatabasePath(); foundDB != "" {
dbPath = foundDB
} else {
// No database found — allow some commands to run without a database
// - import: auto-initializes database if missing
// - setup: creates editor integration files (no DB needed)
// - config subcommands that operate on config.yaml, git config,
// or best-effort diagnostics only (GH#536, bd-934, bd-omc, bd-3rw)
if configCommandCanRunWithoutStore(cmd, args) {
// When --db is provided, resolve BEADS_DIR so yaml-only
// config writes target the correct directory (GH#3348).
if dbPath != "" {
if beadsDir := resolveCommandBeadsDir(dbPath); beadsDir != "" {
prepareSelectedCommandContext(beadsDir, false)
}
}
return nil
}
// GH#3686: `bd create --repo=<path-or-URL>` targets a different
// repo's workspace. Without this, PreRun exits with "no beads
// database found" before create.go's --repo handling runs, even
// when the target has a valid workspace of its own. Resolve
// local targets here so store initialization points at them.
// Remote --repo URLs need no local database at all: create.go
// opens the remote store itself via the remote cache and never
// touches the local `store` global on that path (a gap left by
// #4615, which only handled local paths), so skip local
// discovery entirely instead of falling through to the "no
// beads database found" exit below. Match the command path,
// not the leaf name: `bd gate create --repo` names a GitHub
// OWNER/REPO for gh:run/gh:pr checks, not a workspace, and must
// still need the local database like any other gate command.
if commandRegistryPath(cmd) == "create" && cmd.Flags().Changed("repo") {
if repoVal, _ := cmd.Flags().GetString("repo"); repoVal != "" {
if remotecache.IsRemoteURL(repoVal) {
return nil
}
targetBeadsDir := filepath.Join(routing.ExpandPath(repoVal), ".beads")
dbPath = utils.CanonicalizePath(filepath.Join(targetBeadsDir, beads.CanonicalDatabaseName))
}
}
if dbPath == "" && cmd.Name() != "import" && cmd.Name() != "setup" {
// No database found - provide context-aware error message
fmt.Fprintf(os.Stderr, "Error: no beads database found\n")
fmt.Fprintf(os.Stderr, "Hint: %s\n", diagHint())
fmt.Fprintf(os.Stderr, " or set BEADS_DIR to point to your .beads directory\n")
return SilentExit()
}
if dbPath == "" {
// For import/setup commands, set default database path
// Invariant: dbPath must always be absolute. Use CanonicalizePath for OS-agnostic
// handling (symlinks, case normalization on macOS).
//
// IMPORTANT: Use FindBeadsDir() to get the correct .beads directory,
// which follows redirect files. Without this, a redirected .beads
// would create a local database instead of using the redirect target.
// (GH#bd-0qel)
targetBeadsDir := beads.FindBeadsDir()
if targetBeadsDir == "" {
// An explicit BEADS_DIR is authoritative even
// before it holds project files.
targetBeadsDir = beads.ExplicitBeadsDir()
}
if targetBeadsDir == "" {
targetBeadsDir = ".beads"
}
dbPath = utils.CanonicalizePath(filepath.Join(targetBeadsDir, beads.CanonicalDatabaseName))
}
}
}
beadsDir := resolveCommandBeadsDir(dbPath)
prepareSelectedCommandContext(beadsDir, true)
refreshBoundCommandConfig(cmd)
if guardErr := guardLegacyUpgradeWorkspace(beadsDir); guardErr != nil {
return handleWorkspaceGuardError(guardErr)
}
// Workspace operation gate: every command that reaches this point
// will open the store (the skipsStoreInit early return is above),
// so take the workspace + physical-root gates now, in the final
// mode (SHARED for normal commands, EXCLUSIVE for bd backup
// restore — there is no upgrade path). See workspace_gate.go for
// the fail-open/fail-closed posture. The handle is released in
// PersistentPostRunE after store close; if this PreRunE fails
// later, cobra never runs PostRunE, so the deferred release below
// covers the PreRunE error paths after acquisition.
if err := acquireCommandWorkspaceGates(rootCtx, cmd, beadsDir); err != nil {
return err
}
defer func() {
if retErr != nil {
// Gate-outlives-store: a PreRunE failure AFTER the store
// opened (cobra will skip PostRunE) must close the
// store/provider before the gates drop, or maintenance
// could start against un-quiesced storage.
closeStoreBeforeGateRelease()
releaseWorkspaceGates()
}
}()
if _, err := getDoltAutoCommitMode(); err != nil {
return HandleError("%v", err)
}
// Resolve the backend before version tracking, migration, server startup, or
// any store construction. PostgreSQL/MySQL values are retained as metadata
// tombstones so an existing workspace fails closed instead of falling through
// to a new, empty Dolt database.
cfg, cfgErr := configfile.Load(beadsDir)
if cfgErr != nil {
return HandleError("failed to load beads config from %s: %v (refusing to fall back to the embedded store; fix or restore metadata.json and retry)", beadsDir, cfgErr)
}
if backendErr := validateConfiguredBackend(cfg, beadsDir); backendErr != nil {
return HandleError("%v", backendErr)
}
// Reject proxy capability combinations before any workspace side effect
// (version tracking, migration, auto-start, or provider construction).
// Two validators, one for each half of the policy: flag-keyed rules and
// the path-keyed capability registry.
if cfg != nil && cfg.IsDoltProxiedServerMode() {
if err := validateProxyCapabilitiesBeforeProvider(cmd); err != nil {
return err
}
if err := validateProxyRegistryBeforeProvider(cmd, resolveProxiedTopology(beadsDir)); err != nil {
return err
}
}
// The proxied provider cannot guarantee strict read-only semantics. Refuse
// before provider construction so no connection, migration, or mutation
// is attempted; expose the same stable capability code as other proxy
// front-door refusals.
if readonlyMode && cfg != nil && cfg.IsDoltProxiedServerMode() {
return HandleProxyCapabilityError(AssertProxyCapability(ProxyModeProxied, ProxyCapReadonly))
}
// Set actor for audit trail. The git config user.name fallback is
// resolved lazily by currentActor, so commands that never consult the
// actor (read-only queries) do not spawn a git subprocess for it.
deferActorGitFallback()
// Attach actor to the command span. Only a recording span (telemetry
// enabled) needs the value, so a noop span does not force the lookup.
if commandSpan != nil && commandSpan.IsRecording() {
commandSpan.SetAttributes(attribute.String("bd.actor", currentActor()))
}
// Check if this is a read-only command (GH#804) or an explicitly
// non-mutating preview. Both must open the store read-only: otherwise
// schema initialization runs before the command's RunE can honor
// --dry-run/--inspect or reject invalid arguments. Resolved here,
// ahead of version tracking, because that is the first step a preview
// has to change.
previewMode := isPreviewCommand(cmd)
policy := effectiveRootStorePolicy(cmd.Name(), readonlyMode)
useReadOnly := policy.readOnly || previewMode
// dc-6jaq: consult the migration freeze marker here, before any of
// this hook's own store-touching side effects — trackBdVersion below
// (writes .local_version), autoMigrateOnVersionBump (opens its own
// store connection and can apply a schema migration), and
// maybeAutoImportJSONL (imports into the store when empty) all run
// before the command's RunE, where CheckReadonly would otherwise
// catch a frozen write first. By then the most dangerous writes this
// gate exists to prevent would already be done. useReadOnly already
// carries the exact classification this early gate must skip (strict
// --readonly, or a command on the read-only allowlist) — reusing it
// here means there is no second, independently-maintained list of
// "write" commands to drift out of sync with the one useReadOnly is
// built from. An explicit --dry-run/--inspect preview also sets
// useReadOnly and so skips this early gate the same way, but is NOT
// exempt overall: the per-command chokepoint checks again once RunE
// is reached, with no preview awareness — CheckReadonly for the ~120
// commands that call it, and runImport's own call for `bd import
// --dry-run`, which is not one of them. So a preview on a frozen
// workspace still exits ExitMigrationFrozen there, fail-closed, same
// as strict --readonly already blocks `create --dry-run` today.
// Returning the refusal rather than exiting is load-bearing: the
// gates acquired above are released by this hook's deferred cleanup,
// which os.Exit would skip.
//
// One lookup answers the whole invocation: the walk is a stat per
// ancestor of both the cwd and the resolved workspace, and resolving
// it twice a statement apart would not only pay for it twice but let
// the two readings disagree about a marker that appeared or vanished
// in between (write allowed but maintenance skipped, or the reverse).
// PostRunE reads the same answer via commandFreeze.
commandFreeze = migration.Find(beadsDir)
if !useReadOnly {
if err := migrationFreezeGate(cmd, strings.TrimPrefix(cmd.CommandPath(), cmd.Root().Name()+" "), commandFreeze); err != nil {
return err
}
}
// dc-6jaq (review round 2, ask #1): a command classified read-only —
// or an explicit preview — is deliberately allowed past the gate
// above; diagnosis must keep working during a freeze. But
// trackBdVersion/autoMigrateOnVersionBump below are this hook's OWN
// writes against the (possibly frozen) store, run regardless of the
// command's own classification — so "the command is a read" must not
// imply "these side effects may still run". Reproduced pre-fix:
// freeze the workspace, seed .local_version with a stale version, run
// `bd list` — exit 0 (correct, it's a read), but .local_version was
// silently rewritten mid-freeze anyway. Skip both calls under an
// active freeze without blocking the read itself. Reuses the single
// lookup resolved above rather than repeating the walk.
frozenForMaintenance := policy.runMaintenance && commandFreeze.Frozen()
// Track bd version changes unless strict readonly forbids repository mutation.
// Best-effort tracking - failures are silent.
//
// A preview detects the change but must not consume it: .local_version
// is the one-shot signal autoMigrateOnVersionBump reads, and a preview
// skips that reconciliation (see below). See trackBdVersionPreview.
if policy.runMaintenance && !frozenForMaintenance {
if previewMode {
trackBdVersionPreview()
} else {
trackBdVersion()
}
}
// If the operator passed --force on `bd migrate` or `bd migrate schema`,
// set the programmatic gate override before both autoMigrateOnVersionBump
// and the main store open — both open their own store connections and the
// gate fires on each.
forcedMigrate := isForcedMigrate(cmd)
if forcedMigrate {
if name := forcedMigratePreviewFlag(cmd); name != "" {
return HandleError("--force cannot be combined with --%s: opening the store with the gate overridden applies pending migrations before the preview runs", name)
}
}
// Unconditional set-or-clear keeps the override self-clearing should the
// root command ever be re-run in-process (tests, a future server mode).
schema.SetForceAllowRemoteMigrate(forcedMigrate)
// Typing `bd migrate schema` is consent to migrate a shared database
// that has no remote (#5920): there is no cross-clone fork to risk,
// only the co-resident lockout the operator is asking to accept. A
// preview withholds it — `bd migrate schema --dry-run` must not
// migrate on the way to printing what it would do. Same set-or-clear
// discipline as the --force override above.
schema.SetSharedMigrateConsent(isSchemaMigrateVerb(cmd) && !previewMode)
// The same verb carries migration consent on its own
// (migrate_consent.go): every other command refuses to apply pending
// schema migrations to an existing database. Same unconditional
// set-or-clear discipline as the gate override above.
schema.SetLocalMigrateConsent(isMigrateConsentCommand(cmd))
// Auto-migrate database on version bump (bd-jgxi).
// Runs for ALL non-preview commands (including read-only ones) because
// the migration opens its own store connection, writes the version
// metadata, commits it, and closes BEFORE the main store is opened.
// This ensures bd doctor and read-only commands see the correct version
// after a CLI upgrade.
//
// Preview paths must never call this helper: it opens a separate
// writable store before the main read-only store and can therefore
// apply schema migrations before RunE validates arguments or renders a
// dry-run plan. frozenForMaintenance excludes it for the same reason
// as the trackBdVersion call above — see that comment.
if policy.runMaintenance && !previewMode && !frozenForMaintenance {
autoMigrateOnVersionBump(beadsDir)
}
// Initialize direct storage access
var err error
// Create Dolt storage config — resolve dolt data dir which may be
// on a different filesystem (e.g., ext4 for performance on WSL).
doltPath := doltserver.ResolveDoltDir(beadsDir)
doltCfg := &dolt.Config{
ReadOnly: useReadOnly,
Preview: previewMode,
DisableAutoStart: policy.disableAutoStart,
BeadsDir: beadsDir,
LenientOpen: isWorkingSetReconcileCommand(cmd),
RemoteSyncOpen: isRemoteSyncCommand(cmd),
// Bulk loads outlive the pool's 10s fast-fail on every server
// pause (wy-sbgucn); explicit env/config settings still win.
PoolReadTimeoutFallback: bulkLoadPoolReadTimeout(cmd),
// Classification-only read (GH#804), never strict --readonly or a
// preview: the store is genuinely writable underneath, so the
// lazy defer-wake sweep may still run (be-vbhpf).
ClassifiedRead: policy.readOnly && !readonlyMode && !previewMode,
}
// Load config to get database name and server connection settings.
// A present-but-unloadable metadata.json must stop the command here:
// continuing with the zero-value config silently selects the embedded
// store with the default database name, and on server-mode
// deployments that empty relic answers every query with an empty
// result set and exit 0 (false-empty), which readers misinterpret as
// "no work". Absent metadata.json (cfg == nil, cfgErr == nil) keeps
// the fresh-repo embedded default below — unless the env/config.yaml
// layers already select server mode: that decision must not depend on
// metadata existing, so substitute the default config and let the
// normal mode/connection resolution run.
//
// The gate asks IsDoltServerMode — the same resolver the branch below
// uses to set doltCfg.ServerMode — rather than HostImpliesServerMode.
// Host inference (GH#3545) answers only one layer of that question and
// deliberately returns false as soon as config.yaml names a
// `dolt.mode`: correct for inferring FROM a host, wrong as the whole
// gate. A workspace declaring `dolt.mode: server` in .beads/config.yaml
// with no metadata.json therefore kept cfg nil, fell through to the
// embedded branch, and answered every query out of a phantom
// .beads/embeddeddolt database that same run had just created —
// exit 0, no rows, nothing to distinguish it from real emptiness.
// BEADS_DOLT_SERVER_MODE=1 did not rescue it either; the old gate
// never consulted it. IsDoltServerMode is a superset of
// HostImpliesServerMode, so nothing that reached server mode before
// stops reaching it now.
if cfg == nil && configfile.DefaultConfig().IsDoltServerMode() {
logConfigDiscovery(beadsDir, "no metadata.json; env/config.yaml select server mode")
cfg = configfile.DefaultConfig()
}
if cfg != nil {
warnSharedServerEmbeddedMismatch(cfg)
doltCfg.ProxiedServer = cfg.IsDoltProxiedServerMode()
proxiedServerMode = doltCfg.ProxiedServer
if cmdCtx != nil {
cmdCtx.ProxiedServerMode = doltCfg.ProxiedServer
}
doltCfg.ServerMode = cfg.IsDoltServerMode()
// Shared server mode (dolt.shared-server in config.yaml) is a
// form of server mode. Override metadata.json if it still says
// embedded — handles installs created before GH#2946 fix. Skip
// this for proxied-server: it's its own backend, not server.
if !doltCfg.ServerMode && !doltCfg.ProxiedServer && doltserver.IsSharedServerMode() {
doltCfg.ServerMode = true
}
serverMode = doltCfg.ServerMode
if cmdCtx != nil {
cmdCtx.ServerMode = doltCfg.ServerMode
}
// Always set database name (needed for bootstrap to find
// prefix-based databases like "beads_hq"; see #1669)
doltCfg.Database = cfg.GetDoltDatabase()
if shouldLogDefaultDoltDatabase(cfg) {
logConfigDiscovery(beadsDir, fmt.Sprintf("metadata loaded without dolt_database; using default database name %q", configfile.DefaultDoltDatabase))
}
if err := resolveDoltServerConnection(rootCtx, beadsDir, cfg, doltCfg); err != nil {
return HandleError("%v", err)
}
} else if cfgErr == nil {
logConfigDiscovery(beadsDir, "config discovery")
// Load returned (nil, nil) — no config file found.
// Fall back to the canonical default database name; matches the
// behavior of newDoltStoreFromConfig / newReadOnlyStoreFromConfig
// (see store_factory.go). Without this, embeddeddolt.New rejects
// the empty database name with "database name must not be empty
// (caller should default to \"beads\")".
fmt.Fprintf(os.Stderr, "warning: no beads configuration found in %s; using default database name %q\n", beadsDir, configfile.DefaultDoltDatabase)
doltCfg.Database = configfile.DefaultDoltDatabase
}
// Honor shared-server mode even when no project config was found
// (cfg == nil) or the parse failed. The override inside the
// cfg != nil branch above is skipped in those cases, so without this
// an exported BEADS_DOLT_SHARED_SERVER is silently ignored and bd
// falls through to embeddeddolt.Open, creating a phantom embedded DB
// that subsequent writes fragment into (GH#3817). This is idempotent:
// when the override above already ran, ServerMode is already true.
if !doltCfg.ServerMode && !doltCfg.ProxiedServer && doltserver.IsSharedServerMode() {
doltCfg.ServerMode = true
serverMode = doltCfg.ServerMode
if cmdCtx != nil {
cmdCtx.ServerMode = doltCfg.ServerMode
}
}
// Defensive: embeddeddolt.New rejects an empty database name, so
// default it even on paths that never set one.
if doltCfg.Database == "" {
doltCfg.Database = configfile.DefaultDoltDatabase
}
doltCfg.SyncRemote = resolveSyncRemote()
// --global flag: switch to the global shared-server database.
// Must be in shared-server mode; errors otherwise.
if globalFlag {
if !doltserver.IsSharedServerMode() {
return HandleError("--global requires shared-server mode (set BEADS_DOLT_SHARED_SERVER=1 or dolt.shared-server: true in config.yaml)")
}
doltCfg.Database = doltserver.GlobalDatabaseName
}
// Keep standalone CLI auto-start behavior centralized so doctor and
// other helper paths stay in lockstep with the main command path.
dolt.ApplyCLIAutoStart(beadsDir, doltCfg)
databaseOverride := databaseFlag
if dbNameFromDBFlag != "" {
if databaseOverride != "" && databaseOverride != dbNameFromDBFlag {
return HandleError("conflicting database selection: --db=%q vs --database=%q", dbNameFromDBFlag, databaseOverride)
}
databaseOverride = dbNameFromDBFlag
}
if databaseOverride != "" {
if !proxiedServerMode {
return HandleErrorRespectJSON("--database (or a --db value naming a database) is only supported in proxied-server mode")
}
if err := dbidentifier.ValidateIdentifier(databaseOverride); err != nil {
return HandleErrorRespectJSON("%v", err)
}
}
// In proxied mode the CLI short-circuits to the uowProvider path and
// dispatches through the *_proxied_server.go duals.
//
// Preview commands take the same policy here as they do on the
// embedded and server paths, and for the same reason: the provider
// open runs CREATE DATABASE and schema.MigrateUpWithLock, and
// reconcileVersionProxiedServer writes version metadata — all during
// root pre-run, before --dry-run/--inspect has had any effect. Proxied
// mode is where that is least visible, not where it is acceptable.
if proxiedServerMode {
p, err := newProxiedServerUOWProvider(rootCtx, beadsDir, databaseOverride,
rootProviderOptions(previewMode, useReadOnly)...)
if err != nil {
// Same typed rendering the store path gets below: a schema
// skew or a migration-gate refusal here carries a whole
// actionable block, and `%v` inside "failed to open uow
// provider" throws all of it away.
if rendered := renderTypedOpenError(err); rendered {
return SilentExit()
}
return HandleError("failed to open uow provider: %v", err)
}
// Fire the workspace's script hooks after commits on the
// unit-of-work plumbing, which notified no one: hooks now fire on
// both write plumbings, from the plumbing rather than from each
// command. This is the proxied twin of the wireStorageDecorators
// call below. With hooks disabled the sinks are empty and the
// provider comes back unwrapped.
var uowSinks uow.Sinks
if beadsDir != "" && !config.GetBool("no-hooks") {
hookRunner = hooks.NewRunner(filepath.Join(beadsDir, "hooks"))
uowSinks.Hook = hookRunner
}
uowProvider = wireProxiedUOWProvider(p, uowSinks)
// Honor dolt.auto-commit for proxied writes the same way
// issueOpsContext already does for the direct/SQL-server routes
// (bd-4wamg): batch/off defer the Dolt version commit rather than
// minting one per write (GH#4995). uow.issueOperations reads this
// off the context for every Create/Update/Close/Reopen it runs.
rootCtx, err = issueOpsContext(rootCtx)
if err != nil {
return HandleError("failed to resolve dolt auto-commit policy: %v", err)
}
if !previewMode {
reconcileVersionProxiedServer(rootCtx)
}
syncCommandContext()
return nil
}
// Default auto-commit to ON when the user hasn't set a value, in both
// modes — "on" names what each mode already does per write:
// - Embedded mode: each command writes to the working set and commits
// it in PersistentPostRun.
// - Server mode: the storage layer creates one Dolt commit inside each
// write transaction (the post-run flush stays embedded-only). The
// default here used to be OFF, but the mode was inert in server mode
// — every value behaved like ON — so ON is the compatible default
// now that batch/off actually defer version commits (bd-4wamg).
if strings.TrimSpace(doltAutoCommit) == "" {
doltAutoCommit = string(doltAutoCommitOn)
}
doltCfg.Path = doltPath
// Validate workspace identity for write commands (GH#2438, GH#2372)
// BEFORE the real store opens below. Skip for read-only commands
// since they can't corrupt data. Skip for --global: the global
// database uses a sentinel project ID that won't match any
// project's metadata.json.
//
// This has to run before the store opens, not after: opening it is
// what lets a pending schema migration auto-apply (the smart gate,
// #4516), and checking identity only after that open means a
// mismatch is caught after the migration already landed as a real,
// permanent commit — the refusal arrives too late to prevent it
// (be-0gfcs). newPreviewStoreFromConfig gives a non-mutating,
// behind-schema-tolerant peek at the same database: enough to read
// _project_id without running (or needing) the migration this check
// must complete ahead of.
//
// Dispatches on previewErr, not on idStore's own nilness: even the
// success case can't trust idStore to signal failure on its own.
// openNonMutatingStoreFromConfig's dolt-server-mode branch returns
// dolt.NewFromConfigWithOptions's result straight through, and on a
// failed connection that is a nil *dolt.DoltStore boxed into a
// non-nil storage.DoltStorage interface — the classic Go typed-nil
// trap, where `idStore != nil` reads true even though the store
// behind it is not there. Calling Close() (or anything else) on
// that reference panics (confirmed live:
// TestPersistentPreRunHonorsSkipStoreAnnotation's control case, a
// command with no skip-store annotation run against an absent
// server-mode database). Checking previewErr first sidesteps the
// trap entirely, matching the ordinary (value, err) contract every
// other caller of this pair already trusts.
//
// A failed peek still has to be told apart from a legitimate first
// run: isBootstrapPreviewErr recognizes "no local database yet" (a
// wrapped os.ErrNotExist from the embedded store's own data-dir
// check), and only that case is skipped silently — the bootstrap
// tolerance this check has always had. Any other previewErr
// (unreachable server-mode endpoint, unloadable config, a
// registered backend refusing the read-only open, ...) used to be
// swallowed the same way, which let a preview failure wave the
// real, mutating open through unexamined — the one thing this check
// exists to prevent (be-3bt2e). Those cases now refuse instead.
//
// openCtx scopes ONE http transport to the gate's preview open and the
// real open below (bts-xpw.3.14.6): over a gateway each dial pays its
// own handshake and, with a gasworks credential, its own sts.Context,
// so sharing it saves both on every write. A one-shot command's
// transport also answers its repeated row and settings reads from the
// response it already has (commandMemoizesReads). Other backends
// ignore both.
openCtx := httpclient.WithSharedConnections(rootCtx)
if commandMemoizesReads(cmd) {
openCtx = httpclient.WithReadMemo(openCtx)
}
if !useReadOnly && !globalFlag && os.Getenv("BEADS_SKIP_IDENTITY_CHECK") != "1" {
idStore, previewErr := newPreviewStoreFromConfig(openCtx, beadsDir)
switch {
case previewErr == nil:
checkErr := validateWorkspaceIdentity(rootCtx, idStore, beadsDir)
_ = idStore.Close()
if checkErr != nil {
return checkErr
}
case isBootstrapPreviewErr(previewErr):
debug.Logf("workspace identity check: skipping, no local database yet (%v)\n", previewErr)
default:
return refuseUnverifiablePreviewOpen(previewErr)
}
}
// WARNING: DO NOT remove, delete, or modify files inside Dolt's .dolt/
// directory — including noms/LOCK files. These are Dolt-internal files.
// Removing them WILL cause unrecoverable data corruption and data loss.
// Dolt manages these files itself; external interference is never safe.
if _, ok := backends.Lookup(cfg.GetBackend()); ok {
store, err = newRegisteredBackendStore(openCtx, cfg.GetBackend(), beadsDir, useReadOnly)
} else {
store, err = newDoltStore(rootCtx, doltCfg)
}
// Track final read-only state for staleness checks (GH#1089)
storeIsReadOnly = doltCfg.ReadOnly
if err != nil {
// A failed factory can return a typed-nil concrete pointer,
// which the interface assignment above makes non-nil; the
// gate-release cleanup would then call Close on a nil
// receiver and panic. No store was opened, so drop it.
store = nil
// Check for fresh clone scenario
if handleFreshCloneError(err) {
return SilentExit()
}
if renderTypedOpenError(err) {
return SilentExit()
}
return HandleError("%v", openStoreError(cfg.GetBackend(), err))
}
// Mark store as active for flush goroutine safety
storeMutex.Lock()
storeActive = true
storeMutex.Unlock()
// Auto-import from issues.jsonl when embedded database is empty (GH#2994).
// This handles the upgrade path from pre-0.56 (dolt/) to 1.0+ (embeddeddolt/)
// where the new embedded database starts empty but the git-tracked JSONL
// still has all the user's data.
// Skip auto-import when the user is explicitly running "bd import" —
// the import command handles JSONL files itself and auto-importing
// first would interfere (double-import / upsert confusion).
if shouldRunAutoImportJSONL(cmd, store, useReadOnly, globalFlag, doltCfg.ServerMode) &&
!isDisablingImportAutoViaConfigCommand(cmd, args) {
maybeAutoImportJSONL(rootCtx, store, beadsDir)
}
// Workspace identity is validated earlier now, before the store below
// was allowed to open and auto-apply a pending schema migration as a
// side effect (be-0gfcs) — see the check right before
// newRegisteredBackendStore/newDoltStore.
// Initialize hook runner using the .beads directory resolved above via
// resolveCommandBeadsDir. Do not use filepath.Dir(dbPath): for a
// registered WorkspaceIsBeadsDir backend dbPath is the .beads directory
// itself, so filepath.Dir(dbPath) would load hooks from the repo root
// (<repo>/hooks) instead of .beads/hooks; custom dolt_data_dir layouts
// can likewise place the Dolt data outside .beads.
if beadsDir != "" {
hookRunner = hooks.NewRunner(filepath.Join(beadsDir, "hooks"))
}
// Compose the storage decorator chain: OTel instrumentation (no-op
// when telemetry is off) wrapped by hook firing (skipped when
// BD_NO_HOOKS=1, which is useful for bulk imports, migrations, or
// environments where on_create/on_update/on_close hooks should not
// run). Order matters — see wireStorageDecorators in storage_chain.go.
store = wireStorageDecorators(store, hookRunner, config.GetBool("no-hooks"))
// Warn if multiple databases detected in directory hierarchy
warnMultipleDatabases(dbPath)
// Load molecule templates from hierarchical catalog locations
// Templates are loaded after auto-import to ensure the database is up-to-date.
// Skip for import command to avoid conflicts during import operations.
if cmd.Name() != "import" && store != nil {
// Reuse the resolved .beads directory (see the hook runner note
// above) so a registered WorkspaceIsBeadsDir workspace loads
// .beads/molecules.jsonl rather than <repo>/molecules.jsonl.
loader := molecules.NewLoader(store)
if result, err := loader.LoadAll(rootCtx, beadsDir); err != nil {
debug.Logf("warning: failed to load molecules: %v", err)
} else if result.Loaded > 0 {
debug.Logf("loaded %d molecules from %v", result.Loaded, result.Sources)
}
}
// Sync all state to CommandContext for unified access.
syncCommandContext()
// Tips (including sync conflict proactive checks) are shown via maybeShowTip()
// after successful command execution, not in PreRun
return nil
},
PersistentPostRunE: func(cmd *cobra.Command, args []string) error {
// Registered FIRST so it runs LAST: the signal context must outlive
// the store/gate cleanup below, which passes rootCtx to
// uowProvider.Close. Canceling in the function body (as this used
// to) handed those closers a dead context on the way out.
//
// Clearing matters as much as canceling. Leaving rootCtx pointing at
// the context we just canceled is harmless when a real bd process
// exits here, but every in-process caller that runs Execute() more
// than once -- the cmd/bd test binary, library embedders -- would
// hand that dead context to the next command, and anything reading
// it refuses work nobody canceled. nil is the documented "no process
// signal context yet" state and normalizes back to Background().
//
// Deferred rather than inline so the early error returns below clear
// the globals too.
defer func() {
if rootCancel != nil {
rootCancel()
}
setRootContext(nil, nil)
}()
defer restoreChangeDirSelection()
// Give the hooks this command fired their moment before the process
// exits. Both plumbings run them fire-and-forget on their own
// goroutines, and a bd command is short enough that returning from main
// can kill one that has not reached exec yet — a hook that silently did
// not fire, which is the failure this whole seam exists to stop.
// Bounded by the runner's own per-hook budget: a script that outlives it
// is being killed anyway, so waiting longer buys nothing.
//
// Deferred order is load-bearing on both sides. It runs AFTER the
// close-and-release below, because a hook script commonly shells out to
// bd and an EMBEDDED workspace's Dolt lock is held until this process
// closes its store — the child would fail to open it. (The workspace
// gates are not the reason: a normal command holds them SHARED, and the
// child takes them shared too, so those never contend.) It runs BEFORE
// restoreChangeDirSelection above, because under `-C` the child inherits
// this process's environment and must see the workspace the command
// actually ran against.
defer waitForCommandHooks()
// Release the workspace/physical-root gates on EVERY exit from
// PostRunE — deferred so the early error returns below cannot leak
// the handle past the function. Ordering is enforced, not assumed:
// the success path closes uowProvider/store itself (and nils them),
// making the close call here a no-op; on the early error returns
// the store is still open, so it is closed HERE, before the gates
// drop — gates must always outlive the store.
defer func() {
closeStoreBeforeGateRelease()
releaseWorkspaceGates()
}()
if proxiedServerMode {
// Retention maintenance before the provider closes: the journal
// this workspace just wrote to is reached through it. In the body
// rather than beside the deferred hook wait, for the reason spelled
// out at the other trigger site below.
if shouldAutoPruneEventsJournal(cmd) {
maybeAutoPruneEventsJournal(rootCtx, beads.FindBeadsDir())
}
// Auto-backup, through the provider this command opened. Same
// gate as the direct arm's maintenance net below (strict
// --readonly, `bd serve` and a migration freeze all skip it),
// plus previews: a --dry-run must not register a backup remote
// or write backup state. proxiedAutoBackupBackend decides the
// topology, so this stays inert off managed-local.
if runsPostCommandMaintenance(cmd.Name(), readonlyMode) && !isPreviewCommand(cmd) && !commandFreeze.Frozen() {
runPostRunAutoBackup(rootCtx)
}
if uowProvider != nil {
_ = uowProvider.Close(rootCtx)
uowProvider = nil
}
} else {
// dc-6jaq: the freeze covers this hook's own writes too. A read is
// allowed through a freeze, but the maintenance that trails it is
// not the user's command — auto-commit, the tip_*_last_shown
// metadata write and its separate Dolt commit, auto-backup,
// auto-export and auto-push all mutate the very store being
// migrated, and `bd list` on a frozen workspace reaches every one
// of them. Guarding the outer block keeps that promise in one
// place instead of six. Writes never get here at all: they were
// refused in PersistentPreRunE.
if runsPostCommandMaintenance(cmd.Name(), readonlyMode) && !commandFreeze.Frozen() {
// Dolt auto-commit: after a successful write command (and after final flush),
// create a Dolt commit so changes don't remain only in the working set.
if commandDidWrite.Load() && !commandDidExplicitDoltCommit {
if err := runPostRunAutoCommit(rootCtx, doltAutoCommitParams{Command: cmd.Name()}); err != nil {
return HandleError("dolt auto-commit failed: %v", err)
}
}
// Tip metadata auto-commit: if a tip was shown, create a separate Dolt commit for the
// tip_*_last_shown metadata updates. This may happen even for otherwise read-only commands.
if commandDidWriteTipMetadata && len(commandTipIDsShown) > 0 {
// Only applies when dolt auto-commit is enabled and backend is versioned (Dolt).
if mode, err := getDoltAutoCommitMode(); err != nil {
return HandleError("dolt tip auto-commit failed: %v", err)
} else if mode == doltAutoCommitOn {
// Apply tip metadata writes now (deferred in recordTipShown for Dolt).
//
// A store that refuses writes by construction — the
// preview open, and strict --readonly — must not turn
// an otherwise successful command into a non-zero exit
// here. This block is deliberately not gated by the
// read-only classification, and that has been fine
// because OpenForReadOnlyCommand is "otherwise a normal
// writable store"; the write-refusing opens break that
// assumption. Tip bookkeeping is incidental and
// recordTipShown's own contract is that it may fail
// silently, so skip it and carry on.
tipWritesRefused := false
for tipID := range commandTipIDsShown {
key := fmt.Sprintf("tip_%s_last_shown", tipID)
value := time.Now().Format(time.RFC3339)
if err := store.SetLocalMetadata(rootCtx, key, value); err != nil {
if errors.Is(err, embeddeddolt.ErrReadOnly) {
debug.Logf("tip auto-commit: store is read-only, skipping tip metadata: %v", err)
tipWritesRefused = true
break
}
return HandleError("dolt tip auto-commit failed: %v", err)
}
}
if !tipWritesRefused {
ids := make([]string, 0, len(commandTipIDsShown))
for tipID := range commandTipIDsShown {
ids = append(ids, tipID)
}
msg := formatDoltAutoCommitMessage("tip", getActor(), ids)
if err := runPostRunAutoCommit(rootCtx, doltAutoCommitParams{Command: "tip", MessageOverride: msg}); err != nil {
return HandleError("dolt tip auto-commit failed: %v", err)
}
}
}
}
// Auto-backup: sync a Dolt-native backup if enabled and due
runPostRunAutoBackup(rootCtx)
// Auto-export: write git-tracked JSONL for portability if enabled and due.
// Read-only commands must not perform post-run maintenance writes or emit
// sync guidance after machine-readable output.
if shouldRunPostCommandAutoExport(cmd) {
if err := runPostRunAutoExport(rootCtx, commandAllowsEmptyAutoExport(cmd)); err != nil {
return HandleError("%v", err)
}
}
// Auto-push: push to Dolt remote if enabled and due.
// Skip for read-only commands to avoid unnecessary network operations
// and metadata writes on commands like bd list/show/ready (GH#2191).
if !isReadOnlyCommand(cmd.Name()) {
runPostRunAutoPush(rootCtx)
}
// Events-journal retention, LAST in the maintenance net. It is
// the only step here that serves nobody but the database
// itself, so everything the user can observe — the commit, the
// backup, the export, the push — is already done and durable
// before a maintenance transaction opens. Its failures are
// logged, never returned.
//
// COMBINED ORDERING with the hook teardown above, since both
// land in this function and each has its own reason:
// maintenance runs in the BODY, so it is finished before the
// first defer; the defers then run close-and-release, then
// waitForCommandHooks, then restoreChangeDirSelection, then the
// context cancel. That is the only order in which both hold.
// Auto-prune needs an OPEN store, which the body still has and
// the hook wait deliberately does not (it is sequenced after
// the close so a hook that shells out to bd can take the
// embedded Dolt lock). And it must not be deferred alongside
// them: it would then either run after the store closed, or
// delay the close the hook children are waiting on. Its cost is
// bounded — one indexed query when nothing is due, a 30s pass
// budget at worst — so the hook wait it precedes starts
// essentially on time.
if shouldAutoPruneEventsJournal(cmd) {
maybeAutoPruneEventsJournal(rootCtx, beads.FindBeadsDir())
}
}
// Signal that store is closing (prevents background flush from accessing closed store)
storeMutex.Lock()
storeActive = false
storeMutex.Unlock()
if store != nil {
_ = store.Close() // Best effort cleanup
// Mark closed so the deferred gate-release cleanup above
// does not double-close it.
store = nil
}
}
// End the command span and flush OTel data before process exit.
if commandSpan != nil {
commandSpan.End()
commandSpan = nil
}
shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
telemetry.Shutdown(shutdownCtx)
shutdownCancel()
if profileFile != nil {
pprof.StopCPUProfile()
_ = profileFile.Close() // Best effort cleanup
}
if traceFile != nil {
trace.Stop()
_ = traceFile.Close() // Best effort cleanup
}
// Heap profiling / MemStats summary: --mem-profile flag or
// BEADS_MEM_PROFILE / BEADS_MEM_STATS env vars. See writeMemDiagnostics.
writeMemDiagnostics(memProfilePath)
// The signal context is canceled and cleared by the deferred hook
// registered at the top of this function, so that it also covers the
// early error returns above.
return nil
},
}
// flusherDiagnosticsSuffix separates the detached send-metrics child's memory
// diagnostics from the parent command's. See memDiagnosticsDest.
const flusherDiagnosticsSuffix = ".send-metrics"
// memDiagnosticsDest returns the destination writeMemDiagnostics should write
// dest to, suffixed when this process is the detached flusher child.
//
// MaybeSpawnFlusher hands the child the parent's environment minus the endpoint
// (flusherChildEnv in internal/metrics/spawn.go), so BEADS_MEM_PROFILE and
// BEADS_MEM_STATS arrive holding the same absolute paths the parent resolved.
// The spawn happens on main()'s post-ExecuteC tail, i.e. after
// PersistentPostRunE already wrote them, so an unsuffixed child would silently
// replace the profile of the command the user actually asked about with a
// profile of the trivial flusher -- no error, no size anomaly. Error exits are
// worse: CheckReadonly and the pre-run gates call CloseAndFlush while
// PersistentPostRunE never runs, leaving the child's file as the only one.
//
// BD_IS_FLUSHER=1 is set only by flusherChildEnv, so a human running
// `bd send-metrics` directly still gets the plain path. The suffix is applied
// to the resolved destination, after the flag/env fallback, so both knobs and
// both sources follow one rule.
func memDiagnosticsDest(dest string) string {
if dest == "" || os.Getenv(metrics.EnvIsFlusher) != "1" {
return dest
}
return dest + flusherDiagnosticsSuffix
}
// writeMemDiagnostics honors the heap-profile and MemStats diagnostic knobs
// (--mem-profile / BEADS_MEM_PROFILE / BEADS_MEM_PROFILE_NOGC / BEADS_MEM_STATS).
// memProfileFlag is the --mem-profile flag value, which wins over
// BEADS_MEM_PROFILE. Both call sites pass memProfilePath: --mem-profile is
// registered on rootCmd.PersistentFlags(), so every subcommand inherits it,
// including the hidden send-metrics one -- which calls this directly because its
// Run exits before Cobra ever reaches PersistentPostRunE below.
func writeMemDiagnostics(memProfileFlag string) {
// Runs a GC first by default; BEADS_MEM_PROFILE_NOGC=1 skips it to capture peak.
heapDest := memProfileFlag
if heapDest == "" {
heapDest = os.Getenv("BEADS_MEM_PROFILE")
}
heapDest = memDiagnosticsDest(heapDest)
if heapDest != "" {
if os.Getenv("BEADS_MEM_PROFILE_NOGC") == "" {
runtime.GC()
}
if f, err := os.Create(heapDest); err == nil { // #nosec G304 -- user-supplied profiling path
_ = pprof.WriteHeapProfile(f)
_ = f.Close()
}
}
// Optional one-line MemStats summary: BEADS_MEM_STATS=/path/to/stats.txt
if statsDest := memDiagnosticsDest(os.Getenv("BEADS_MEM_STATS")); statsDest != "" {
var ms runtime.MemStats
runtime.ReadMemStats(&ms)
if f, err := os.Create(statsDest); err == nil { // #nosec G304 -- user-supplied profiling path
fmt.Fprintf(f, "HeapAlloc=%d HeapSys=%d HeapInuse=%d HeapObjects=%d\n",
ms.HeapAlloc, ms.HeapSys, ms.HeapInuse, ms.HeapObjects)
_ = f.Close()
}
}
}
func shouldRunPostCommandAutoExport(cmd *cobra.Command) bool {
if cmd == nil {
return true
}
return !isReadOnlyCommand(cmd.Name())
}
func shouldRunAutoImportJSONL(cmd *cobra.Command, s storage.DoltStorage, useReadOnly, globalFlag, serverMode bool) bool {
if cmd == nil || s == nil || useReadOnly || globalFlag || serverMode {
return false
}
// import.auto=false (or BD_IMPORT_AUTO=false) must disable ALL auto-import
// behavior, not just the git-hook sync path (importJSONLForSync). Without
// this check, a fresh/empty database would silently auto-import stale
// issues.jsonl on every write command regardless of the config setting
// (GH#4304).
if !config.GetBool("import.auto") {
return false
}
return cmd.Name() != "import"
}
// isDisablingImportAutoViaConfigCommand reports whether the command about to
// run is "bd config set import.auto false" (or an equivalent
// "bd config set-many ... import.auto=false" pair). shouldRunAutoImportJSONL
// runs in PersistentPreRun before configSetCmd/configSetManyCmd write the new
// value to config.yaml, so without this exemption the master switch would
// trigger the very auto-import it is meant to disable on its own invocation
// when a stale .beads/issues.jsonl sits next to an empty database (GH#4304).
func isDisablingImportAutoViaConfigCommand(cmd *cobra.Command, args []string) bool {
if cmd == nil || cmd.Parent() == nil || cmd.Parent().Name() != "config" {
return false
}
switch cmd.Name() {
case "set":
return len(args) >= 2 && args[0] == "import.auto" && isFalsyConfigValue(args[1])
case "set-many":
for _, arg := range args {
key, value, ok := strings.Cut(arg, "=")
if ok && key == "import.auto" && isFalsyConfigValue(value) {
return true
}
}
}
return false
}
// isFalsyConfigValue reports whether a config value string parses as a
// boolean false (e.g. "false", "0", "f").
func isFalsyConfigValue(value string) bool {
parsed, err := strconv.ParseBool(value)
return err == nil && !parsed
}
func commandAllowsEmptyAutoExport(cmd *cobra.Command) bool {
if cmd == nil {
return false
}
switch cmd.Name() {
case "prune", "purge":
return commandMayEmptyJSONLExport.Load()
default:
return false
}
}
// blockedEnvVars lists environment variables that must not be set because they
// could silently override the storage backend via viper's AutomaticEnv, causing
// data fragmentation (bd-hevyw).
var blockedEnvVars = []string{"BD_BACKEND", "BD_DATABASE_BACKEND"}
// checkBlockedEnvVars returns an error if any blocked env vars are set.
func checkBlockedEnvVars() error {
for _, name := range blockedEnvVars {
if os.Getenv(name) != "" {
return fmt.Errorf("%s env var is not supported and has been removed to prevent data fragmentation.\n"+
"Unset %s; storage selection comes from .beads/metadata.json. To choose a different supported backend, follow 'bd help init-safety'; do not edit metadata.json by hand", name, name)
}
}
return nil
}
// setupGracefulShutdown creates a context that cancels on SIGINT/SIGTERM/SIGHUP.
// Before cancellation, it flushes pending batch commits so that accumulated
// changes in the Dolt working set are not lost on graceful shutdown.
func setupGracefulShutdown() (context.Context, context.CancelFunc) {
ctx, cancel := context.WithCancel(context.Background()) //nolint:gosec // G118: cancel is returned and called by caller
sigCh := make(chan os.Signal, 1)
signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM, syscall.SIGHUP)
go func() {
select {
case <-sigCh:
flushBatchCommitOnShutdown()
cancel()
// On second signal, force exit
<-sigCh
os.Exit(1)
case <-ctx.Done():
signal.Stop(sigCh)
}
}()
return ctx, cancel
}
// flushBatchCommitOnShutdown commits any pending batch changes before process exit.
// This prevents data loss when SIGTERM/SIGHUP kills a process with uncommitted
// batch writes sitting in the Dolt working set.
func flushBatchCommitOnShutdown() {
mode, err := getDoltAutoCommitMode()
if err != nil || mode != doltAutoCommitBatch {
return
}
storeMutex.Lock()
active := storeActive
st := store
storeMutex.Unlock()
if !active || st == nil {
return
}
// Use a fresh context with timeout — rootCtx is about to be canceled.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
// CommitPending reports atomically whether a commit actually landed, so a
// clean shutdown stays quiet without spending the 5s flush budget on
// HEAD-reporting probes before the commit itself (and without racing a
// concurrent writer's HEAD movement the way a before/after compare would).
committed, err := st.CommitPending(ctx, getActorWithGit())
if err != nil {
if !isDoltNothingToCommit(err) {
fmt.Fprintf(os.Stderr, "\nWarning: failed to flush batch commit on shutdown: %v\n", err)
}
return
}
if !committed {
return
}
fmt.Fprintf(os.Stderr, "\nFlushed pending batch commit on shutdown\n")
}
// isBootstrapPreviewErr reports whether err is the identity check's preview
// open failing because no local database exists yet — a legitimate first
// run, not a workspace problem. It must stay narrow: any other previewErr
// (unreachable server, bad config, ...) has to refuse rather than silently
// wave the real, mutating open through (be-3bt2e).
func isBootstrapPreviewErr(err error) bool {
return errors.Is(err, os.ErrNotExist)
}
// refuseUnverifiablePreviewOpen renders the identity gate's refusal when the
// preview open failed for a reason other than first-run bootstrap.
//
// The preview IS a real store open, so it can hit the same typed open errors the
// real one does, and those must be rendered exactly as the real-open arm renders
// them. Moving the gate earlier is not license to downgrade
// SchemaSkewError.UserMessage()'s actionable rebuild block into a generic
// wrapper, nor to drop the JSON body that every `--json` consumer depends on.
//
// Only ONE class actually arrives here typed today — schema skew: the preview
// runs CheckForwardDrift (embeddeddolt openReadOnly, dolt store open), which is
// how the recurring stale-binary class #4135/#4137 surfaces at the preview
// first. The other two calls below are defensive-for-symmetry with the real-open
// arm, and cannot fire from a preview as the code stands:
// - handleFreshCloneError matches a post-migration failure string that a
// non-mutating preview never produces. Note for whoever makes it reachable:
// it ignores jsonOutput (main_errors.go), so it would break the `--json`
// guarantee this arm otherwise keeps.
// - CheckRemoteMigrateGate* runs only from mutating opens, never from
// openReadOnly, so RemoteMigrateGateError cannot originate in the preview.
//
// projectIdentityMismatchError is deliberately NOT in that list: it is a plain
// fmt.Errorf block with no typed wrapper, so it falls to the generic arm below
// and picks up its prefix. That matches base, where the mismatch block reached
// the operator inside the real arm's "failed to open database: %v" wrapper.
//
// Extracted from the gate's default arm so both halves are directly testable
// without standing up a forward-drifted workspace; the wire itself is pinned on
// the embedded tier by
// TestEmbeddedIdentityGateRendersSchemaSkewFromForwardDriftedWorkspace.
func refuseUnverifiablePreviewOpen(previewErr error) error {
if handleFreshCloneError(previewErr) {
return SilentExit()
}
if renderTypedOpenError(previewErr) {
return SilentExit()
}
// What remains is preview-specific: an unreachable endpoint, unloadable
// config, a registered backend refusing the read-only open. Respect --json
// so a machine caller still receives a structured error. The override hint
// lives only on this arm, and states what it actually does: on the typed
// arms above it cannot help, because the real open fails on the identical
// condition.
return HandleErrorRespectJSON(
"could not verify workspace identity before opening the database: %v "+
"(BEADS_SKIP_IDENTITY_CHECK=1 skips this pre-open check; it does not fix an error the real open would hit too)",
previewErr)
}
// validateWorkspaceIdentity checks that the project identity from metadata.json
// matches s's stored project_id. A mismatch indicates configuration drift —
// the CLI may be pointing at the wrong database (GH#2438, GH#2372).
//
// This check only runs for write commands because:
// 1. Read commands are safe even against wrong databases (no data mutation)
// 2. The check requires a store connection
// 3. New databases won't have _project_id yet (bootstrap case)
//
// s is passed explicitly rather than read off the package-level store: the
// caller runs this against a throwaway, non-mutating store opened BEFORE the
// real command store, specifically so a mismatch is caught before that real
// open lets a pending schema migration auto-apply (be-0gfcs) — see the call
// site in the root command's PersistentPreRunE.
func validateWorkspaceIdentity(ctx context.Context, s storage.DoltStorage, beadsDir string) error {
if s == nil {
return nil // No store connection, nothing to validate
}
// Load project_id from metadata.json
cfg, err := configfile.Load(beadsDir)
if err != nil || cfg == nil {
return nil // No config, skip validation (fresh init)
}
configProjectID := cfg.ProjectID
if cfg.GetBackend() == httpclient.Backend {
// The http backend's identity pin lives in the per-user, gitignored
// sidecar, not in metadata.json: `bd connect` (MED-6) stopped
// mirroring project_id into the git-tracked config, so cfg.ProjectID
// here is whatever the workspace carried BEFORE connect — generally
// a different project's id than the server `bd connect --force`
// just pointed it at. Comparing that stale value against the live
// database's _project_id below would flag every write as drift.
// Read the sidecar instead, exactly as applyContextBackend
// (context_cmd.go) does for `bd context`. A missing sidecar
// (ErrNotConnected) or any other read failure falls through to the
// "no project_id" skip just below, the same as a pre-identity
// workspace — the wire handshake's own ExpectProjectID gate (design
// D6) is what actually refuses a mismatched server at dial time;
// this check only needs to avoid a FALSE mismatch once that gate has
// already passed.
target, err := httpclient.LoadTarget(beadsDir)
if err != nil {
return nil
}
configProjectID = target.ExpectProjectID
}
if configProjectID == "" {
return nil // No project_id in config (pre-identity era)
}
// Get project_id from database
dbProjectID, err := s.GetMetadata(ctx, "_project_id")
if err != nil || dbProjectID == "" {
return nil // No project_id in DB (new or pre-identity database)
}
// Compare: mismatch means drift
if configProjectID != dbProjectID {
fmt.Fprintf(os.Stderr, "Error: workspace identity mismatch detected\n\n")
fmt.Fprintf(os.Stderr, " metadata.json project_id: %s\n", configProjectID)
fmt.Fprintf(os.Stderr, " database _project_id: %s\n\n", dbProjectID)
fmt.Fprintf(os.Stderr, "This means the CLI config and database belong to different projects.\n")
fmt.Fprintf(os.Stderr, "Possible causes:\n")
fmt.Fprintf(os.Stderr, " • BEADS_DIR points to a different project's .beads/\n")
fmt.Fprintf(os.Stderr, " • Dolt server endpoint changed and now serves a different database\n")
fmt.Fprintf(os.Stderr, " • metadata.json was copied from another project\n\n")
fmt.Fprintf(os.Stderr, "Recovery: run 'bd doctor --fix' or 'bd bootstrap' to reconcile workspace metadata with the authoritative database when shared-server metadata drifted.\n")
fmt.Fprintf(os.Stderr, "To diagnose: bd context --json\n")
fmt.Fprintf(os.Stderr, "To override: set BEADS_SKIP_IDENTITY_CHECK=1\n")
return SilentExit()
}
return nil
}
func main() {
initprocs.Done()
// BD_NAME overrides the binary name in help text (e.g. BD_NAME=ops makes
// "ops --help" show "ops" instead of "bd"). Useful for multi-instance
// setups where wrapper scripts set BEADS_DIR for routing.
if name := os.Getenv("BD_NAME"); name != "" {
rootCmd.Use = name
}
// Register --all flag on Cobra's auto-generated help command.
// Must be called after init() so all subcommands are registered and
// Cobra has created its default help command.
rootCmd.InitDefaultHelpCmd()
registerHelpAllFlag()
executedCmd, err := rootCmd.ExecuteC()
// Let this command's fire-and-forget hooks finish, for the same
// every-exit-path reason the metrics flush below is here rather than in
// PersistentPostRunE: cobra SKIPS PostRunE when RunE returns an error, so a
// partial batch — `bd close A B` where A commits and B refuses — would exit
// with A's committed mutation never reaching its hook script. Idempotent, so
// the PostRunE call on the clean path makes this one free.
waitForCommandHooks()
// Finalize queued metrics and detach the uploader. Shared with the os.Exit
// guards (CheckReadonly and the pre-run gates) so every exit path flushes the
// same way instead of only the clean RunE/ExecuteC return.
metrics.CloseAndFlush()
if err != nil {
if code, ok := exitCodeFromError(err); ok {
os.Exit(code)
}
if executedCmd != nil && executedCmd.SilenceErrors {
fmt.Fprintf(os.Stderr, "Error: %s\n", err.Error())
}
os.Exit(1)
}
}
func resolveMetricsEnabled() bool {
if v, ok := os.LookupEnv(metrics.EnvDisableMetrics); ok {
return !envTruthyValue(v)
}
// DO_NOT_TRACK is a disable-only alias: a truthy value opts out, but a
// falsey or empty value (DO_NOT_TRACK=0/false/"") must fall through to the
// user's saved preference instead of forcing metrics back on over a saved
// `bd metrics off`. Only BD_DISABLE_METRICS (checked first) is a
// bidirectional override.
if v, ok := os.LookupEnv(metrics.EnvDoNotTrack); ok && envTruthyValue(v) {
return false
}
// Consent is the user's own global choice: resolve it from the user-global
// config only, never merged project/BEADS_DIR config. Otherwise a
// repository's .beads/config.yaml (highest viper precedence) could re-enable
// metrics for a user who ran `bd metrics off`.
return !config.MetricsDisabledByUserConfig()
}
func resolveMetricsEndpoint() string {
if v := os.Getenv(metrics.EnvEndpoint); v != "" {
return v
}
// Like enablement, the endpoint is resolved from env + user-global config
// only so a repository can never redirect where a user's metrics are sent.
if ep := config.UserMetricsEndpoint(); ep != "" {
return ep
}
return metrics.DefaultEndpoint
}
func envTruthyValue(v string) bool {
if v == "" {
return false
}
switch strings.ToLower(v) {
case "0", "false":
return false
}
return true
}
// secretFlagNames are long flag names whose entire value is an opaque credential
// that must never reach the bd.args telemetry span. The flag's value is redacted
// wholesale. Only federation add-peer's --password currently qualifies. Its shorthand (-p) is
// resolved per command via secretFlagTokens so the same letter bound to
// --priority/--prefix/--parallel on other commands is never redacted.
var secretFlagNames = map[string]bool{"password": true}
// secretFlagTokens returns the concrete --long and -short flag tokens that carry a
// secret value for cmd. Resolving against the running command is what makes the
// redaction "by flag identity": -p is treated as secret only on the command that
// actually binds it to a secret flag (federation add-peer), not on the many
// commands that bind -p to a non-secret option.
func secretFlagTokens(cmd *cobra.Command) map[string]bool {
tokens := make(map[string]bool)
if cmd == nil {
return tokens
}
for name := range secretFlagNames {
f := cmd.Flags().Lookup(name)
if f == nil {
continue
}
tokens["--"+f.Name] = true
if f.Shorthand != "" {
tokens["-"+f.Shorthand] = true
}
}
return tokens
}
// scrubArgsForTelemetry joins argv for the bd.args span attribute with any
// credential-bearing values redacted. A secretFlags token's value is redacted
// wholesale across the `--password <v>`,
// `--password=<v>`, `-p <v>`, `-p=<v>`, and `-p<v>` spellings pflag accepts. Every
// other arg gets a conservative DSN/userinfo scrub as defense in depth so a
// positional connection string cannot leak a password.
func scrubArgsForTelemetry(argv []string, secretFlags map[string]bool) string {
parts := make([]string, len(argv))
redactNext := false
for i, a := range argv {
if redactNext {
parts[i] = "xxxxx"
redactNext = false
continue
}
if name, value, ok := strings.Cut(a, "="); ok {
if secretFlags[name] {
// --password=<secret> / -p=<secret> — redact the whole value.
parts[i] = name + "=xxxxx"
continue
}
if strings.HasPrefix(name, "-") {
scrubbed := scrubUserinfoPassword(scrubPotentialDSNPasswords(value))
if scrubbed != value {
// Preserve an arbitrary flag name while parsing its equals-value as
// a possible DSN. Passing the whole token to url.Parse would treat
// the flag prefix as the URL scheme and miss query credentials.
parts[i] = name + "=" + scrubbed
continue
}
}
}
if i > 0 {
if secretFlags[argv[i-1]] {
// <secret> following a bare --password / -p token.
parts[i] = "xxxxx"
continue
}
}
if short, ok := secretShorthandPrefix(a, secretFlags); ok {
// -p<secret> — pflag's concatenated shorthand spelling.
parts[i] = short + "xxxxx"
continue
}
if secretShorthandTakesSeparateValue(a, secretFlags) {
// -qp <secret> — a boolean shorthand cluster ending in the
// value-taking secret shorthand, with its value in the next token.
parts[i] = a
redactNext = true
continue
}
parts[i] = scrubUserinfoPassword(scrubPotentialDSNPasswords(a))
}
return strings.Join(parts, " ")
}
// secretShorthandPrefix reports whether a is pflag's concatenated secret-shorthand
// spelling, returning the "-x...-p" prefix to preserve. Long flags cannot concatenate
// a value, so only -X<value> shorthands are matched.
//
// pflag also accepts a CLUSTER of boolean shorthands ending in a value-taking
// shorthand: given boolean flags -q/-v and value flag -p, "-qpSECRET" parses as -q
// followed by -p SECRET, and "-vpSECRET" parses as -v followed by -p SECRET — but the
// raw token still reaches telemetry as one string. Walk the leading run of letters in
// a; the first letter whose "-x" token is a registered secret shorthand ends the
// cluster, and everything after it is that flag's value, regardless of how many
// boolean shorthands preceded it. This mirrors pflag's own grammar (a cluster is zero
// or more boolean shorthands followed by one value-taking shorthand) without needing
// the running command's flag set here: it is conservative in the safe direction,
// since treating a longer prefix as consumed by the secret shorthand only ever
// over-redacts, never under-redacts.
func secretShorthandPrefix(a string, secretFlags map[string]bool) (string, bool) {
if len(a) < 3 || a[0] != '-' || a[1] == '-' {
return "", false
}
for i := 1; i < len(a); i++ {
c := a[i]
if !((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')) {
return "", false
}
if secretFlags["-"+string(c)] {
if i+1 >= len(a) {
return "", false // no value follows; not the concatenated spelling
}
return a[:i+1], true
}
}
return "", false
}
// secretShorthandTakesSeparateValue recognizes a boolean-shorthand cluster that
// ends in a registered secret shorthand with no attached value. For example,
// pflag parses "-qp secret" as -q followed by -p=secret.
func secretShorthandTakesSeparateValue(a string, secretFlags map[string]bool) bool {
if len(a) < 3 || a[0] != '-' || a[1] == '-' {
return false
}
for i := 1; i < len(a); i++ {
c := a[i]
if !((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')) {
return false
}
if secretFlags["-"+string(c)] {
return i == len(a)-1
}
}
return false
}
// scrubUserinfoPassword redacts the password in a URL/DSN userinfo section
// (postgres://user:PASS@host or user:PASS@tcp(...)); args without a user:pass@
// userinfo pass through unchanged, so ordinary text is never mangled.
func scrubUserinfoPassword(a string) string {
at := strings.LastIndexByte(a, '@')
if at < 0 {
return a
}
head := a[:at]
start := 0
if s := strings.LastIndex(head, "//"); s >= 0 {
start = s + 2 // userinfo begins after the scheme's "//"
}
colon := strings.IndexByte(head[start:], ':')
if colon < 0 {
return a // no "user:pass" userinfo, nothing to redact
}
return head[:start+colon+1] + "xxxxx" + a[at:]
}