fix(init): #5791 follow-up — name --recreate-missing without a paste-ready command; align help, playbook and ADR 0004 (#7070)
* fix(init): name --recreate-missing in the refusal without a paste-ready command The missing-server-database refusal added in #5791 ended with a complete `bd init --recreate-missing --prefix <prefix>` line. ADR 0002 Invariant 4 keeps complete destructive invocations out of bd error output, and this refusal also fires when the server merely could not be reached: a stopped server, a wrong port and a wrong data dir all look the same from here, and recreating in any of them strands the real data behind an empty database of the same name. The line also echoed the raw --prefix flag value, so a run without --prefix printed `--prefix ` with nothing after it. The refusal now names the flag and points to `bd help init-safety`, which keeps the full invocation behind the diagnosis it requires. The unused prefix parameter stays as `_` so the guard call sites are unchanged. Also: - --force / --reinit-local flag help, `bd help init-safety` and the init guard comment now say neither flag authorizes recreating a missing server-mode database; the --recreate-missing stanza says to rule out a stopped server or wrong port/data dir and restore first. - bootstrap.go comments no longer describe #5791 as open and unmerged. - TestInitGuardMissingServerDBMessage_RefusalTextNoEcho pins the wording for both evidence arms, with and without a prefix. - TestInitGuard_RecreateMissingE2ECreatesMissingServerDB runs the real binary against a live server lacking the database: refused without the flag, created with it. The unit tests flip initAllowRecreateMissing directly, so nothing exercised the documented command end to end. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(recovery): init-missing-server-db covers both evidence arms and the flag limits The init-missing-server-db section described only the project_id arm of the guard. Under --reinit-local or --force a workspace that predates project_id is also refused when its local Dolt data directory survives, and the refusal then cites that directory instead of metadata.json. "What happened" now covers both arms. "Limits worth knowing" replaces the stale "fails open" bullet with a table of which local state meets the refusal under bd init and under --reinit-local / --force, and what --recreate-missing changes. The init-force-refused section now says --force / --reinit-local bypass only the local data-safety guard, not this refusal or the remote one, and step 3 says why the refusal names --recreate-missing without printing the command (ADR 0002 Invariant 4). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(adr): mark ADR 0004 Accepted now that #5791 has landed ADR 0004 (the missing-database guard signal) still read "Proposed" after the guards implementing it merged in #5791, and its Consequences said checkExistingBeadsDataAt "does not change" although the same PR gave it the Tier 1 probe ahead of project_id. Record the acceptance and say what the PR already changed; DOC_INVENTORY.md follows the status. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
1cc19040af
commit
b81fdc0b20
10 changed files with 219 additions and 73 deletions
11
CHANGELOG.md
11
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*`;
|
||||
|
|
|
|||
|
|
@ -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")
|
||||
|
|
|
|||
|
|
@ -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")
|
||||
|
|
|
|||
|
|
@ -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())
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
)
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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 <p>`. With the
|
||||
// told the operator to run `bd init --recreate-missing --prefix <p>`. 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
|
||||
|
|
|
|||
|
|
@ -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 <prefix>
|
||||
|
||||
bd init --from-jsonl Import from configured import.path. If
|
||||
origin has Dolt data, this refuses unless
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: Recovery Playbooks
|
|||
description: Step-by-step recovery for bd init and bd dolt push/pull refusals, including the primary-key fork playbook
|
||||
---
|
||||
|
||||
Last reviewed: 2026-09-27
|
||||
Last reviewed: 2026-10-01
|
||||
|
||||
Freshness source: `cmd/bd/init.go`, `cmd/bd/init_safety.go`,
|
||||
`cmd/bd/init_safety_test.go`, `cmd/bd/init_safety_help.go`, and
|
||||
|
|
@ -46,9 +46,11 @@ bd init refuses: remote 'origin' already has Dolt history (refs/dolt/data).
|
|||
**Why this happens**
|
||||
|
||||
`bd init --force` (or `--reinit-local`) tells `bd` to bypass the local
|
||||
data-safety guard. `bd init --from-jsonl` selects a local JSONL export as
|
||||
the source. But the remote already has project history. Proceeding would
|
||||
create an orphan local Dolt branch with no common ancestor on origin. The
|
||||
data-safety guard, and only that guard: neither flag bypasses this refusal
|
||||
or the [missing server-side database refusal](#init-missing-server-db).
|
||||
`bd init --from-jsonl` selects a local JSONL export as the source. But the
|
||||
remote already has project history. Proceeding would create an orphan local
|
||||
Dolt branch with no common ancestor on origin. The
|
||||
next `bd dolt push` would either fail (no common ancestor) or — worse, if
|
||||
force-pushed — destroy the team's data.
|
||||
|
||||
|
|
@ -224,14 +226,17 @@ issue data behind a new, empty database of the same name.
|
|||
|
||||
**What happened**
|
||||
|
||||
This workspace is in server mode and `.beads/metadata.json` carries a
|
||||
`project_id`, which is written only by a real prior `bd init`. So the project
|
||||
was definitely initialized at some point — but its configured database is not
|
||||
on the server, or the server could not be reached to confirm.
|
||||
This workspace is in server mode and shows evidence of a prior `bd init`:
|
||||
`.beads/metadata.json` carries a `project_id`, or (under `--reinit-local` or
|
||||
`--force`) a workspace that predates `project_id` still has a local Dolt data
|
||||
directory, in which case the message cites that instead of `metadata.json`.
|
||||
Yet its configured database is not on the server, or the server could not be
|
||||
reached to confirm.
|
||||
|
||||
That is a **recovery** situation, not a fresh clone, and the two are otherwise
|
||||
indistinguishable from the local filesystem alone: in server mode there is
|
||||
normally no local database directory either way. `bd init` used to resolve the
|
||||
That is treated as a **recovery** situation, not a fresh clone, and the two are
|
||||
otherwise indistinguishable from the local filesystem alone: this project's own
|
||||
database directory is absent either way, because it was never created here or
|
||||
because it was lost with the local storage. `bd init` used to resolve the
|
||||
ambiguity by assuming "fresh clone" and creating the database. When the
|
||||
assumption was wrong, the result was a new, empty database sitting at the name
|
||||
the real one used to occupy — the 2026-08-11 fleet-wide data loss.
|
||||
|
|
@ -274,12 +279,34 @@ bd init --recreate-missing --prefix myproject
|
|||
by `--force`, `--reinit-local`, a config key, or an environment variable,
|
||||
because it authorizes the one thing this guard exists to prevent.
|
||||
|
||||
The refusal names `--recreate-missing` but does not print this command: it also
|
||||
fires when the server merely could not be reached, so it sends you through
|
||||
steps 1 and 2 here instead of handing you a line to paste. See
|
||||
[ADR 0002 — Invariant 4](https://github.com/gastownhall/beads/blob/main/engdocs/adr/0002-init-safety-invariants.md).
|
||||
|
||||
**Limits worth knowing**
|
||||
|
||||
- The guard keys on `project_id`, which was introduced by GH#2372. A workspace
|
||||
initialized before that has no `project_id` and is indistinguishable from a
|
||||
fresh clone, so it **fails open** — `bd init` will still create the database.
|
||||
- The same `project_id` is inherited by a **fresh clone**, because
|
||||
Whether a workspace meets this refusal depends on two pieces of local
|
||||
evidence: whether this project's own database directory
|
||||
(`<dolt-data-dir>/<database>/.dolt`) exists, and whether `metadata.json`
|
||||
carries a `project_id` (introduced by GH#2372). With the configured database
|
||||
missing from the server, or the server unreachable:
|
||||
|
||||
| Local Dolt storage | `project_id` | `bd init` | `bd init --reinit-local` / `--force` |
|
||||
|---|---|---|---|
|
||||
| This project's database directory present | Either | Refused as already initialized, not by this guard | Not this guard; the ordinary re-init path |
|
||||
| Data dir present, database directory absent | Present | This refusal | This refusal |
|
||||
| Data dir present, database directory absent | Absent | Refused as already initialized, not by this guard | This refusal |
|
||||
| No Dolt data dir | Present | This refusal | This refusal |
|
||||
| No Dolt data dir | Absent | Proceeds, as for a fresh clone | Proceeds, as for a fresh clone |
|
||||
|
||||
Adding `--recreate-missing` lifts every refusal in the last four rows,
|
||||
including the third row's "already initialized". It changes nothing in the
|
||||
first row, where this project's database is still on local disk. In
|
||||
shared-server mode the data dir is machine-global (see below), so the last two
|
||||
rows rarely apply there.
|
||||
|
||||
- `project_id` is also inherited by a **fresh clone**, because
|
||||
`.beads/metadata.json` is git-tracked by default. Cloning a beads-managed
|
||||
repo whose server-side database does not exist yet therefore meets this
|
||||
refusal rather than a plain first init. It fails in the safe direction —
|
||||
|
|
@ -290,11 +317,6 @@ because it authorizes the one thing this guard exists to prevent.
|
|||
cannot tell "never initialized here" from "initialized here, storage since
|
||||
lost"), and why `--recreate-missing` is the permanent resolution path rather
|
||||
than a stopgap.
|
||||
- The guard applies equally to `bd init`, `bd init --reinit-local` and
|
||||
`bd init --force`. If your workspace predates `project_id` and its local
|
||||
Dolt storage is gone, all three refuse until you pass `--recreate-missing`;
|
||||
a workspace with no local Dolt storage at all is treated as a fresh clone by
|
||||
all three.
|
||||
- Server mode only, and shared-server mode counts as server mode — the guard
|
||||
tests for *this project's* database directory under the resolved Dolt data
|
||||
dir, not for the data dir itself, which in shared mode is the machine-global
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ Follow-up automation should replace marker-only checks with generated or
|
|||
| `adr/0001-multi-remote-approach.md` | Keep | ADR; historical decision record, not a live reference table. |
|
||||
| `adr/0002-init-safety-invariants.md` | Keep | ADR backing `RECOVERY.md` and init safety code. |
|
||||
| `adr/0003-provenance-event-log.md` | Keep | ADR; historical decision record for the `provenance_events` table and `bd provenance` command group. Status: Proposed pending a maintainer post on issue 4460. |
|
||||
| `adr/0004-missing-database-guard-signal.md` | Keep | ADR; settles the proof-of-prior-init signal for the missing-database init guards. Extends `adr/0002`. Status: Proposed. |
|
||||
| `adr/0004-missing-database-guard-signal.md` | Keep | ADR; settles the proof-of-prior-init signal for the missing-database init guards. Extends `adr/0002`. Status: Accepted. |
|
||||
| `ADVANCED.md` | Keep/revise as needed | User-facing advanced workflows; mixed command examples should defer to generated CLI reference when expanded. |
|
||||
| `AIDER_INTEGRATION.md` | Keep | User-facing integration guide; evidence is setup/integration behaviour. |
|
||||
| `ANTIVIRUS.md` | Keep | User-facing operational note; review vendor/version claims when touched. |
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
## Status
|
||||
|
||||
Proposed — 2026-09-16.
|
||||
Accepted — 2026-10-01, landed with #5791 (proposed 2026-09-16).
|
||||
|
||||
Extends [ADR 0002](0002-init-safety-invariants.md), which established the
|
||||
`bd init` safety invariants and the scope-bound `--force` / `--reinit-local`
|
||||
|
|
@ -133,7 +133,10 @@ would need new mechanism for no safety gain.
|
|||
pre-GH#2372 workspace whose local database was lost was protected under
|
||||
plain `bd init` but waved through under `--reinit-local` / `--force` — the
|
||||
flags an operator reaches for in a panic were the weaker path.
|
||||
- `checkExistingBeadsDataAt` does not change.
|
||||
- `checkExistingBeadsDataAt` needs no further change for this decision. The
|
||||
probe fix described under Context, which landed in the same PR (#5791),
|
||||
already gave it the Tier 1 probe ahead of `project_id` and the
|
||||
coarse-directory permit condition.
|
||||
- The fresh-clone false positive (GH#2433) remains by design for the cells
|
||||
where it is unavoidable.
|
||||
- Both guards cite this ADR, so the question stops being re-litigated each
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue