diff --git a/CHANGELOG.md b/CHANGELOG.md index f61dd857f..c11f28a97 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -85,6 +85,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 no-op in shared-server mode, which is the topology of the 2026-08-11 loss. User-visible wherever the data directory exists but the database is gone. +- **The missing-database refusal no longer prints a ready-to-paste + `bd init --recreate-missing` command line.** It names the flag and points + to `bd help init-safety`, which keeps the full invocation behind the + diagnosis it requires (ADR 0002 Invariant 4). The refusal also fires when + the server merely could not be reached, and a stopped server, a wrong port + or a wrong data dir all look the same from there; recreating in any of them + strands the real data behind an empty namesake. Run without `--prefix`, the + old line also printed `--prefix` with no value. The `--force` and + `--reinit-local` help, `bd help init-safety` and the recovery playbook now + say that neither flag authorizes recreating a missing server-mode database. + - **`BEADS_DOLT_POOL_READ_TIMEOUT` / `dolt.pool-read-timeout` (and the write twins) now apply to every `bd` command in server mode.** The knobs shipped in #5089, but their env/config ladder ran only for callers of `NewFromConfig*`; diff --git a/cmd/bd/bootstrap.go b/cmd/bd/bootstrap.go index f361dc980..305989c43 100644 --- a/cmd/bd/bootstrap.go +++ b/cmd/bd/bootstrap.go @@ -664,7 +664,7 @@ func localFileRecoveryPlan(plan BootstrapPlan, beadsDir string) (BootstrapPlan, // initialized (ProjectID set) and the configured server-mode database could // not be confirmed to exist. Creating one here would strand the existing issue // data behind a new, empty database of the same name — the same root cause -// PR #5791 (open, not yet merged) addresses for bd init. +// the be-5up5 guards in init.go address for bd init (PR #5791). // // Reaching the init fall-through already implies the database was not // confirmed: existingBootstrapDBPlan returns a settled "none" plan whenever a @@ -1111,9 +1111,9 @@ func bootstrapMissingServerDBSummary(dbName, host string, port int, probeErr err // workspace that was already initialized elsewhere. Per GH#2363, this must // never suggest a destructive "recreate" action as an actionable next step. // -// The equivalent guard for `bd init` is proposed in PR #5791, which is open -// and not yet merged; this wording is kept deliberately close to it so the -// two can share one message once that lands. +// The equivalent `bd init` refusal is initGuardMissingServerDBMessage, from +// PR #5791. This wording is kept deliberately close to it so the two can be +// folded into one message. func bootstrapMissingServerDBRefusal(dbName, host string, port int, probeErr error) error { var b strings.Builder if probeErr != nil { @@ -1134,8 +1134,8 @@ func bootstrapMissingServerDBRefusal(dbName, host string, port int, probeErr err // Every route here must be followable FROM this state. `bd backup restore` // alone is not: it restores a Dolt-native snapshot, not a `bd export` // JSONL, and it requires an initialized database — so it silently routes - // the operator back through `bd init`, the very unguarded door this - // refusal exists to keep shut (PR #5791). Name that precondition instead + // the operator back through `bd init`, the door this refusal exists to + // keep shut (PR #5791). Name that precondition instead // of implying it, and lead with the routes that need no init at all. b.WriteString("\nTo recover existing data, repopulate the database rather than creating fresh.\n") b.WriteString("Routes that work from this state:\n") diff --git a/cmd/bd/init.go b/cmd/bd/init.go index 4954ae332..c57f26478 100644 --- a/cmd/bd/init.go +++ b/cmd/bd/init.go @@ -807,7 +807,9 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1): // --reinit-local both bypass this local-only guard; they do NOT // authorize cross-boundary operations on remote history (see // CheckRemoteSafety at cmd/bd/init_safety.go and - // engdocs/adr/0002-init-safety-invariants.md). + // engdocs/adr/0002-init-safety-invariants.md), nor recreating a + // missing server-mode database (guardMissingServerDatabase below; + // engdocs/adr/0004-missing-database-guard-signal.md). if reinitLocal { // be-5up5 round 2 (review of PR #5791): --reinit-local/--force skip // checkExistingBeadsData entirely, and the typed confirmation below @@ -2258,8 +2260,8 @@ func init() { initCmd.Flags().Bool("setup-exclude", false, "Configure .git/info/exclude to keep beads files local (for forks)") initCmd.Flags().Bool("skip-hooks", false, "Skip git hooks installation") initCmd.Flags().Bool("skip-agents", false, "Skip AGENTS.md and Claude/Codex/Cursor setup generation") - initCmd.Flags().Bool("force", false, "Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence (see 'bd help init-safety').") - initCmd.Flags().Bool("reinit-local", false, "Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence; see --discard-remote.") + initCmd.Flags().Bool("force", false, "Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence or recreating a missing server-mode database (see 'bd help init-safety').") + initCmd.Flags().Bool("reinit-local", false, "Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence (see --discard-remote) or recreating a missing server-mode database (see --recreate-missing).") initCmd.Flags().Bool("discard-remote", false, "Authorize discarding the configured remote's Dolt history when re-initializing. Requires --destroy-token in non-interactive mode; see 'bd help init-safety'.") initCmd.Flags().Bool("recreate-missing", false, "Explicitly authorize creating a fresh, empty database when this project's configured server-mode database is missing or unreachable. Opt-in per invocation only; never implied by --force, config, or env (see 'bd help init-safety').") initCmd.Flags().Bool("from-jsonl", false, "Import issues from configured import.path; refuses remote history unless --discard-remote authorizes replacement") diff --git a/cmd/bd/init_guard.go b/cmd/bd/init_guard.go index 667241157..3bd2fc56c 100644 --- a/cmd/bd/init_guard.go +++ b/cmd/bd/init_guard.go @@ -141,7 +141,16 @@ var initAllowRecreateMissing bool // project_id (GH#2372) and is proven only by its local Dolt storage. Naming // metadata.json in that cell would assert evidence the caller does not have, // misdirecting an operator who audits metadata.json mid-recovery. -func initGuardMissingServerDBMessage(dbName, host string, port int, prefix string, haveProjectID bool) error { +// +// The --recreate-missing opt-in is named by flag only, never as a paste-ready +// command line (ADR 0002 Invariant 4). This refusal also fires when the server +// merely could not be reached to confirm, so whoever reads it may not yet know +// which case they are in, and a one-liner copied out of the error skips the +// diagnosis it asks for. The full invocation lives in `bd help init-safety` and +// docs/recovery/init-safety.md. The blank string parameter is the raw --prefix +// value that one-liner used to echo; it is ignored now, and kept only so the +// guard call sites stay unchanged. +func initGuardMissingServerDBMessage(dbName, host string, port int, _ string, haveProjectID bool) error { var b strings.Builder fmt.Fprintf(&b, "\n%s Database %q not found on server at %s:%d (or the server could not be reached to confirm).\n", ui.RenderWarn("⚠"), dbName, host, port) if haveProjectID { @@ -166,9 +175,9 @@ func initGuardMissingServerDBMessage(dbName, host string, port int, prefix strin b.WriteString(" bd backup restore # if a local backup snapshot exists\n") b.WriteString(" Check .beads/backup/ for a JSONL export you can import manually.\n") - b.WriteString("\nIf you are certain no recoverable data exists and want a fresh, empty database at\n") - b.WriteString("this name, opt in explicitly for this one invocation:\n") - fmt.Fprintf(&b, " bd init --recreate-missing --prefix %s\n", prefix) + b.WriteString("\nCreate a fresh, empty database at this name (only if you are certain no\n") + b.WriteString("recoverable data exists):\n") + b.WriteString(" See 'bd help init-safety' for the --recreate-missing workflow.\n") b.WriteString("\nAborting.") return errors.New(b.String()) diff --git a/cmd/bd/init_guard_force_e2e_test.go b/cmd/bd/init_guard_force_e2e_test.go index b92d57a3d..64c8fa74b 100644 --- a/cmd/bd/init_guard_force_e2e_test.go +++ b/cmd/bd/init_guard_force_e2e_test.go @@ -7,6 +7,7 @@ import ( "os" "os/exec" "path/filepath" + "strconv" "strings" "testing" ) @@ -45,27 +46,10 @@ func TestInitGuard_ForceE2EDoesNotRecreateMissingServerDB(t *testing.T) { // Port 1 is unreachable by construction, standing in for a server // whose database has been lost. - env := []string{} - for _, kv := range os.Environ() { - switch { - case strings.HasPrefix(kv, "BEADS_DIR="), - strings.HasPrefix(kv, "BEADS_DB="), - strings.HasPrefix(kv, "BD_DB="), - strings.HasPrefix(kv, "BEADS_DOLT_SERVER_PORT="), - strings.HasPrefix(kv, "BEADS_DOLT_SERVER_DATABASE="): - continue - } - env = append(env, kv) - } - env = append(env, - "BEADS_DOLT_SERVER_PORT=1", - "BD_NON_INTERACTIVE=1", - ) - // #nosec G204 -- bd is a locally built binary, flag is a literal cmd := exec.Command(bd, "init", flag, "--prefix", "myproject", "--skip-hooks") cmd.Dir = projectDir - cmd.Env = env + cmd.Env = initGuardE2EEnv(t, 1) out, err := cmd.CombinedOutput() if err == nil { @@ -80,3 +64,71 @@ func TestInitGuard_ForceE2EDoesNotRecreateMissingServerDB(t *testing.T) { }) } } + +// TestInitGuard_RecreateMissingE2ECreatesMissingServerDB is the success-side +// twin of the test above. The unit tests that permit --recreate-missing flip +// initAllowRecreateMissing directly, so nothing else runs the documented +// recovery command itself through what follows the guard (remote safety, the +// metadata rewrite, CREATE DATABASE). This runs the real binary against a live +// server that lacks the configured database: refused without the opt-in, and +// with it, init succeeds and the database exists on that server. +func TestInitGuard_RecreateMissingE2ECreatesMissingServerDB(t *testing.T) { + beadsDir := startProjectServerModeGuardFixture(t, "myproject") + port, err := strconv.Atoi(os.Getenv("BEADS_DOLT_SERVER_PORT")) + if err != nil { + t.Fatalf("fixture must pin BEADS_DOLT_SERVER_PORT: %v", err) + } + // The legacy-upgrade guard runs before init's own guards and refuses a + // server workspace whose local Dolt storage has no current-era version + // witness; a workspace bd initialized has one. + if err := writeLocalVersion(filepath.Join(beadsDir, localVersionFile), Version); err != nil { + t.Fatalf("write local version: %v", err) + } + if check := checkDatabaseOnServer("127.0.0.1", port, "root", "", "myproject", false); !check.Reachable || check.Exists { + t.Fatalf("precondition: server must be reachable and lack the database, got %+v", check) + } + + projectDir := filepath.Dir(beadsDir) + env := initGuardE2EEnv(t, port) + args := []string{"init", "--prefix", "myproject", "--skip-hooks", "--skip-agents"} + + // Without the opt-in this exact workspace is refused, so the success below + // is the flag's doing rather than a fixture init would accept anyway. + out, err := runExternalServerBD(t, projectDir, env, args...) + if err == nil || !strings.Contains(out, "not found on server") { + t.Fatalf("precondition: bd init without --recreate-missing must be refused by the missing-database guard, got err=%v:\n%s", err, out) + } + + out, err = runExternalServerBD(t, projectDir, env, append(args, "--recreate-missing")...) + if err != nil { + t.Fatalf("bd init --recreate-missing must create the missing database, got %v:\n%s", err, out) + } + if check := checkDatabaseOnServer("127.0.0.1", port, "root", "", "myproject", false); !check.Reachable || !check.Exists { + t.Fatalf("bd init --recreate-missing reported success but the database is not on the server: %+v\n%s", check, out) + } +} + +// initGuardE2EEnv builds a bd child environment in which only the fixture's +// files and the given port choose the server. Every BEADS_DOLT_* setting +// (shared-server mode, data dir, mode, the TestMain container's port) and the +// BEADS_DIR, BEADS_DB, BD_DB and BEADS_SHARED_SERVER_DIR overrides are +// dropped, which is what startProjectServerModeGuardFixture pins in-process. +// The mode variables are dropped rather than set to "0": +// initModeExplicitlyRequested treats any non-empty value as an explicit mode +// choice, and init would then stop inheriting server mode from metadata.json. +func initGuardE2EEnv(t *testing.T, port int) []string { + t.Helper() + env := []string{} + for _, kv := range externalServerTestEnv(t) { + name, _, _ := strings.Cut(kv, "=") + switch name { + case "BEADS_DB", "BD_DB", "BEADS_SHARED_SERVER_DIR": + continue + } + env = append(env, kv) + } + return append(env, + "BEADS_DOLT_SERVER_PORT="+strconv.Itoa(port), + "BD_NON_INTERACTIVE=1", + ) +} diff --git a/cmd/bd/init_guard_test.go b/cmd/bd/init_guard_test.go index ddb6643e6..cfa6a5c18 100644 --- a/cmd/bd/init_guard_test.go +++ b/cmd/bd/init_guard_test.go @@ -458,16 +458,50 @@ func TestInitGuardServerMessage_DiagnosticsBeforeForce(t *testing.T) { } } -// be-5up5: 2026-08-11 fleet-wide data loss. In server mode there is NEVER a -// local dolt/ directory, whether this is a genuine fresh clone or an existing -// project whose server-side database was lost — doltDirExists==false alone -// (GH#2433's signal) cannot tell them apart. metadata.json's project_id is -// only written by a real prior init, so a non-empty project_id here is proof -// this is an existing project recovering from a missing database, not -// GH#2433's fresh-clone case (whose fixture carries no project_id — see -// TestInitGuard_FreshCloneWithMetadataJSON above). init must refuse and -// point at bd bootstrap, not silently recreate an empty database on the -// server (the missing-database state that reproduced the 2026-08-11 loss). +// TestInitGuardMissingServerDBMessage_RefusalTextNoEcho extends ADR 0002 +// Invariant 4 (error-text-no-echo) to the missing-database refusal, which the +// TestCheckRemoteSafety_*NoEcho family does not reach. The refusal must name +// --recreate-missing, since that opt-in is the documented way out, but must not +// spell out a runnable invocation of it: it also fires when the server merely +// could not be reached, and a one-liner copied from the error skips the +// diagnosis the message asks for. Both evidence arms are covered, with an empty +// prefix too, because the guard runs before --prefix is resolved and so sees +// the raw flag value, which may be "". +func TestInitGuardMissingServerDBMessage_RefusalTextNoEcho(t *testing.T) { + for _, haveProjectID := range []bool{true, false} { + for _, prefix := range []string{"myproject", ""} { + msg := initGuardMissingServerDBMessage("myproject", "127.0.0.1", 3307, prefix, haveProjectID).Error() + for _, line := range strings.Split(msg, "\n") { + if strings.Contains(line, "--recreate-missing") && + (strings.Contains(line, "bd init") || strings.Contains(line, "--prefix")) { + t.Errorf("haveProjectID=%v prefix=%q: refusal spells out a runnable --recreate-missing invocation %q:\n%s", + haveProjectID, prefix, line, msg) + } + } + if !strings.Contains(msg, "--recreate-missing") { + t.Errorf("haveProjectID=%v prefix=%q: refusal must still name the --recreate-missing opt-in:\n%s", + haveProjectID, prefix, msg) + } + if !strings.Contains(msg, "bd help init-safety") { + t.Errorf("haveProjectID=%v prefix=%q: refusal does not point to 'bd help init-safety':\n%s", + haveProjectID, prefix, msg) + } + } + } +} + +// be-5up5: 2026-08-11 fleet-wide data loss. With no local Dolt storage for +// this project, the filesystem cannot tell a genuine fresh clone from an +// existing project whose server-side database was lost — doltDirExists==false +// (GH#2433's signal) is true of both. A non-empty project_id in metadata.json +// is taken as evidence of a prior init, so this is treated as an existing +// project recovering from a missing database, not GH#2433's fresh-clone case +// (whose fixture carries no project_id — see +// TestInitGuard_FreshCloneWithMetadataJSON above; ADR 0004 records why that +// signal is kept despite clones inheriting it). init must refuse and name a +// restore path rather than bd bootstrap, and must not silently recreate an +// empty database on the server (the state that reproduced the 2026-08-11 +// loss). func TestInitGuard_ExistingProjectMissingServerDB_Refuses(t *testing.T) { testutil.RequireDoltBinary(t) @@ -568,7 +602,7 @@ func TestInitGuard_ExistingProjectMissingServerDB_RecreateMissingAllows(t *testi return data } - t.Run("server_reachable_db_missing (init.go:2566)", func(t *testing.T) { + t.Run("server_reachable_db_missing", func(t *testing.T) { testutil.RequireDoltBinary(t) oldServerMode := serverMode @@ -613,7 +647,7 @@ func TestInitGuard_ExistingProjectMissingServerDB_RecreateMissingAllows(t *testi } }) - t.Run("server_unreachable (init.go:2578)", func(t *testing.T) { + t.Run("server_unreachable", func(t *testing.T) { oldServerMode := serverMode serverMode = true defer func() { serverMode = oldServerMode }() @@ -1088,11 +1122,14 @@ func TestInitGuard_ExistingProjectMissingServerDB_DataDirPresent_Refuses(t *test // TestInitGuard_RecreateMissing_ReachesOptIn_DataDirPresent is the blocker // itself: four surfaces (the --recreate-missing flag help, `bd help // init-safety`, docs/recovery/init-safety.md and the guard's own refusal text) -// tell the operator to run `bd init --recreate-missing --prefix
`. With the +// told the operator to run `bd init --recreate-missing --prefix
`. With the
// data directory present, that command could not reach its own opt-in and
// exited 1 with the false "already initialized" message — so the documented
// recovery was a dead end, and the only thing that worked (--reinit-local
-// --recreate-missing) is named nowhere.
+// --recreate-missing) was named nowhere. The refusal text has since stopped
+// spelling the command out (it names the flag and routes to `bd help
+// init-safety`; see TestInitGuardMissingServerDBMessage_RefusalTextNoEcho),
+// but the other three surfaces still document it.
func TestInitGuard_RecreateMissing_ReachesOptIn_DataDirPresent(t *testing.T) {
oldServerMode := serverMode
serverMode = true
diff --git a/cmd/bd/init_safety_help.go b/cmd/bd/init_safety_help.go
index cb47ad392..29708f6a3 100644
--- a/cmd/bd/init_safety_help.go
+++ b/cmd/bd/init_safety_help.go
@@ -31,15 +31,18 @@ FLAG SURFACE
local data. Does NOT authorize discarding
remote history. If origin has Dolt data
this will refuse — pair with
- --discard-remote to override.
+ --discard-remote to override. Nor does it
+ authorize recreating a missing server-mode
+ database; that takes --recreate-missing.
bd init --reinit-local \ Discard the remote's Dolt history and
--discard-remote replace it with the local reinit. First
bd dolt push after this will be a
history-replacing force-push.
- bd init --force Deprecated alias for --reinit-local.
- Kept working for ≥2 releases.
+ bd init --force Deprecated alias for --reinit-local, with
+ the same limits. Kept working for ≥2
+ releases.
bd init --recreate-missing Authorize creating a fresh, empty database
when this project's configured server-mode
@@ -48,7 +51,14 @@ FLAG SURFACE
--force/--reinit-local, config, or env.
Without it, bd init REFUSES rather than
silently recreating a lost database as
- empty (be-5up5).
+ empty (be-5up5). First rule out a stopped
+ server or a wrong port or data dir, and
+ restore if you can; the playbook is
+ init-missing-server-db in
+ docs/recovery/init-safety.md. Only when
+ nothing is recoverable:
+
+ bd init --recreate-missing --prefix