beads/cmd/bd/bootstrap.go
matt wilkie ef3ffd45b3
feat(migrate): add --force flag as CLI twin of BD_ALLOW_REMOTE_MIGRATE (#4654)
* feat(migrate): add --force flag as CLI twin of BD_ALLOW_REMOTE_MIGRATE

The remote-migrate gate (#4259) refuses to auto-apply pending schema
migrations to a remote-backed database because two clones migrating
independently fork the schema unrecoverably. Until now the only unlock
was the env var BD_ALLOW_REMOTE_MIGRATE=1, which is awkward at the CLI
and can leak into child processes (git hooks, dolt subprocesses). The
--force flag is the natural CLI form of the designated-migrator escape
hatch: it is set before both autoMigrateOnVersionBump and the main store
open in the root PersistentPreRunE via a package-level bool, so it never
leaks out of the process. The env var remains supported for scripted/CI
use and is documented as a parenthetical alongside the new primary form.

Agent-Signature: claude-sonnet-4-6-high on behalf of matt wilkie

* fix(embeddeddolt): point lenient-gate guidance at bd migrate --force

The soft-fail (warn-and-continue) gate warning for read-only and
working-set-reconcile opens still named the env-var escape hatch; align
it with the new primary form introduced for the strict gate.

Agent-Signature: claude-fable-5-high on behalf of matt wilkie

* fix(migrate): reject --force with preview flags; harden override lifecycle

Review findings on the --force flag (cross-vendor: codex gpt-5.5 + claude
opus):

- --force combined with --dry-run/--inspect must fail before the store
  opens: with the gate overridden, the open itself applies pending
  migrations, so the preview flag would be honored only after the
  destructive work it exists to prevent (codex P2).
- Set-or-clear the override unconditionally so it is self-clearing under
  any future in-process root-command reuse (reviewer nit).
- Lock the agent-safety contract against the new flag form: AgentDirective
  must not embed 'bd migrate --force' any more than the env form (nit).

Agent-Signature: claude-fable-5-high on behalf of matt wilkie
2026-07-07 15:58:18 -07:00

990 lines
33 KiB
Go

package main
import (
"bufio"
"context"
"database/sql"
"errors"
"fmt"
"io"
"os"
"path/filepath"
"strconv"
"strings"
"time"
_ "github.com/go-sql-driver/mysql"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/cmd/bd/doctor"
"github.com/steveyegge/beads/cmd/bd/doctor/fix"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/doltserver"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/storage/dolt"
"github.com/steveyegge/beads/internal/storage/doltutil"
"github.com/steveyegge/beads/internal/storage/embeddeddolt"
"github.com/steveyegge/beads/internal/storage/schema"
"github.com/steveyegge/beads/internal/storage/versioncontrolops"
"golang.org/x/term"
)
var resolveBootstrapAuthoritativeMetadata = fix.ResolveAuthoritativeServerMetadata
type bootstrapServerProbeConfig struct {
host string
port int
user string
pass string
database string
tls bool
}
type bootstrapServerDBCheck struct {
Exists bool
Reachable bool
Err error
}
var checkBootstrapServerDB = func(probeCfg bootstrapServerProbeConfig) bootstrapServerDBCheck {
host := probeCfg.host
port := probeCfg.port
dbName := probeCfg.database
dsn := doltutil.ServerDSN{
Host: host,
Port: port,
User: probeCfg.user,
Password: probeCfg.pass,
TLS: probeCfg.tls,
}.String()
db, err := sql.Open("mysql", dsn)
if err != nil {
return bootstrapServerDBCheck{Reachable: false, Err: err}
}
defer db.Close()
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := db.PingContext(ctx); err != nil {
return bootstrapServerDBCheck{Reachable: false, Err: err}
}
rows, err := db.QueryContext(ctx, "SHOW DATABASES")
if err != nil {
return bootstrapServerDBCheck{Reachable: true, Err: err}
}
defer rows.Close()
for rows.Next() {
var name string
if err := rows.Scan(&name); err != nil {
return bootstrapServerDBCheck{Reachable: true, Err: err}
}
if name == dbName {
return bootstrapServerDBCheck{Exists: true, Reachable: true}
}
}
if err := rows.Err(); err != nil {
return bootstrapServerDBCheck{Reachable: true, Err: err}
}
return bootstrapServerDBCheck{Exists: false, Reachable: true}
}
var bootstrapCmd = &cobra.Command{
Use: "bootstrap",
GroupID: "setup",
Short: "Non-destructive database setup for fresh clones and recovery",
Long: `Bootstrap sets up the beads database without destroying existing data.
Unlike 'bd init --force', bootstrap will never delete existing issues.
Bootstrap auto-detects the right action:
• If sync.remote is configured: clones from the remote
• If git origin has Dolt data (refs/dolt/data): clones from git and wires origin for future push/pull
• If .beads/backup/*.jsonl exists: restores from backup
• If .beads/issues.jsonl exists: imports from git-tracked JSONL
• If no database exists: creates a fresh one
• If database already exists: validates and reports status
This is the recommended command for:
• Setting up beads on a fresh clone
• Recovering after moving to a new machine
• Repairing a broken database configuration
Non-interactive mode (--non-interactive, --yes/-y, or BD_NON_INTERACTIVE=1):
Skips the confirmation prompt before executing the bootstrap plan.
Also auto-detected when stdin is not a terminal or CI=true is set.
Examples:
bd bootstrap # Auto-detect and set up
bd bootstrap --dry-run # Show what would be done
bd bootstrap --json # Output plan as JSON
bd bootstrap --yes # Skip confirmation prompt
`,
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
evt := metrics.NewCommandEvent("bootstrap")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
dryRun, _ := cmd.Flags().GetBool("dry-run")
yesFlag, _ := cmd.Flags().GetBool("yes")
nonInteractiveFlag, _ := cmd.Flags().GetBool("non-interactive")
// Resolve non-interactive mode: flag > env var > CI env > terminal detection.
nonInteractive := isNonInteractiveBootstrap(yesFlag || nonInteractiveFlag)
// Find beads directory
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
// No .beads directory exists yet. Before giving up, probe the
// git remote for Dolt data stored in git (refs/dolt/data). This
// is the "fresh second clone" case: clone1 pushed Beads state
// to a git remote, and clone2 needs to bootstrap from it.
// Only applies to git remotes — Dolt-native remotes (DoltHub,
// S3, etc.) should be configured via sync.remote. (GH#2792)
//
// If found, synthesize the theoretical .beads path and fall
// through to the normal detectBootstrapAction + executeBootstrapPlan
// flow. Actual directory creation is deferred to executeSyncAction
// to preserve --dry-run semantics.
if isGitRepo() && !isBareGitRepo() {
if originURL, err := gitOriginGetURL(); err == nil && originURL != "" {
if gitOriginHasDoltDataRef() {
if fallbackDir := beads.GetWorktreeFallbackBeadsDir(); fallbackDir != "" {
beadsDir = fallbackDir
} else {
cwd, err := os.Getwd()
if err != nil {
return HandleError("failed to get working directory: %v", err)
}
beadsDir = filepath.Join(cwd, ".beads")
}
}
}
}
}
if beadsDir == "" {
if jsonOutput {
if err := outputJSON(noWorkspaceBootstrapPayload()); err != nil {
return err
}
return SilentExit()
}
fmt.Fprintf(os.Stderr, "Hint: %s\n", diagHint())
fmt.Fprintf(os.Stderr, "Bootstrap is for existing projects that need database setup.\n")
return HandleError("%s", activeWorkspaceNotFoundMessage())
}
// Load config from .beads/metadata.json. When the beadsDir was
// synthesized (fresh clone or rig with no local .beads), the file
// won't exist. In that case, walk up parent directories to find a
// workspace-level metadata.json that contains the correct database
// name (e.g. dolt_database). Without this, server-mode rigs get the
// default name "beads" instead of their configured name. (GH#3029)
cfg, err := configfile.Load(beadsDir)
if err != nil || cfg == nil {
cfg = findParentConfig(beadsDir)
}
if cfg == nil {
cfg = configfile.DefaultConfig()
}
resolvedCfg, repairMsg, err := applyBootstrapMetadataRepair(beadsDir, cfg, !dryRun)
if err != nil {
return HandleError("failed to reconcile shared-server metadata: %v", err)
}
if resolvedCfg != nil {
cfg = resolvedCfg
}
// Determine action based on state
plan := detectBootstrapAction(beadsDir, cfg)
if jsonOutput {
if err := outputJSON(plan); err != nil {
return err
}
if plan.Action == "none" || dryRun {
return nil
}
} else {
if repairMsg != "" {
fmt.Fprintf(os.Stderr, "Bootstrap metadata repair: %s\n", repairMsg)
}
printBootstrapPlan(plan)
if plan.Action == "none" || dryRun {
return nil
}
}
if err := executeBootstrapPlan(plan, cfg, nonInteractive); err != nil {
return HandleError("Bootstrap failed: %v", err)
}
return nil
},
}
func applyBootstrapMetadataRepair(beadsDir string, cfg *configfile.Config, apply bool) (*configfile.Config, string, error) {
if beadsDir == "" {
return cfg, "", nil
}
if _, err := os.Stat(beadsDir); err != nil {
return cfg, "", nil
}
resolved, msg, err := resolveBootstrapAuthoritativeMetadata(filepath.Dir(beadsDir), apply)
if err != nil {
return nil, "", err
}
if resolved == nil {
return cfg, msg, nil
}
return resolved, msg, nil
}
// BootstrapPlan describes what bootstrap will do.
type BootstrapPlan struct {
Action string `json:"action"` // "sync", "restore", "jsonl-import", "init", "none"
Reason string `json:"reason"` // Human-readable explanation
BeadsDir string `json:"beads_dir"`
Database string `json:"database"`
SyncRemote string `json:"sync_remote,omitempty"`
BackupDir string `json:"backup_dir,omitempty"`
JSONLFile string `json:"jsonl_file,omitempty"`
HasExisting bool `json:"has_existing"`
}
func noWorkspaceBootstrapPayload() map[string]interface{} {
return map[string]interface{}{
"action": "none",
"reason": activeWorkspaceNotFoundError(),
"suggestion": diagHint(),
}
}
func detectBootstrapAction(beadsDir string, cfg *configfile.Config) BootstrapPlan {
plan := BootstrapPlan{
BeadsDir: beadsDir,
Database: cfg.GetDoltDatabase(),
}
// When bootstrap synthesized a fallback beadsDir for a fresh clone or
// worktree recovery, the path may not exist yet. In that case we must let
// sync.remote / refs/dolt/data detection run before treating an existing
// shared-server database as "nothing to do", otherwise an unrelated default
// "beads" database can mask the real recovery path.
beadsDirExists := false
if info, err := os.Stat(beadsDir); err == nil && info.IsDir() {
beadsDirExists = true
}
// Check for existing database (path differs between server and embedded mode).
// Determine server/shared-server mode from the target workspace itself
// (metadata.json, env vars, and the target config.yaml when present) rather
// than unrelated global config loaded from the caller's current repo.
isSharedServer := bootstrapSharedServerMode(beadsDir)
isServer := cfg.IsDoltServerMode() || isSharedServer
// Check sync.remote (primary) or sync.git-remote (deprecated fallback)
syncRemote := resolveSyncRemote()
if syncRemote != "" {
// User-provided sync.remote — trust the URL format as-is.
// normalizeRemoteURL would convert http:// to git+http://,
// breaking Dolt remotesapi endpoints (GH#3339).
plan.SyncRemote = syncRemote
plan.Action = "sync"
plan.Reason = "sync.remote configured — will clone from " + syncRemote
return plan
}
// Auto-detect: probe git origin for Dolt data stored in git
// (refs/dolt/data). This only applies to git remotes — Dolt-native
// remotes (DoltHub, S3, etc.) must be configured via sync.remote.
if isGitRepo() && !isBareGitRepo() {
if originURL, err := gitOriginGetURL(); err == nil && originURL != "" {
if gitOriginHasDoltDataRef() {
plan.SyncRemote = normalizeRemoteURL(originURL)
plan.Action = "sync"
plan.Reason = "Found Dolt data on git origin (refs/dolt/data) — will clone from " + originURL
return plan
}
}
}
if dbAction, ok := existingBootstrapDBPlan(beadsDir, cfg, isServer, isSharedServer); ok {
// If the local beadsDir does not exist yet, prefer recovering via sync
// first. This avoids false "nothing to do" results when the default
// shared-server database name happens to exist for another project.
if beadsDirExists || dbAction.Action != "none" {
return dbAction
}
// For synthesized paths with no local workspace directory yet, defer the
// existing-db no-op until we've ruled out all other recovery paths.
// This preserves the sync-precedence fix without downgrading the
// legitimate "database already exists" case into a fresh init.
plan = dbAction
}
// Check for backup JSONL files (must be non-empty to be useful)
backupDir := filepath.Join(beadsDir, "backup")
issuesFile := filepath.Join(backupDir, "issues.jsonl")
if info, err := os.Stat(issuesFile); err == nil && info.Size() > 0 {
plan.BackupDir = backupDir
plan.Action = "restore"
plan.Reason = "Backup files found — will restore from " + backupDir
return plan
}
// Check for git-tracked JSONL (the portable export format)
gitJSONL := filepath.Join(beadsDir, "issues.jsonl")
if _, err := os.Stat(gitJSONL); err == nil {
plan.JSONLFile = gitJSONL
plan.Action = "jsonl-import"
plan.Reason = "Git-tracked issues.jsonl found — will import from " + gitJSONL
return plan
}
if plan.Action == "none" {
return plan
}
// Fresh setup
plan.Action = "init"
plan.Reason = "No existing database, remote, or backup — will create fresh database"
return plan
}
func existingBootstrapDBPlan(beadsDir string, cfg *configfile.Config, isServer, isSharedServer bool) (BootstrapPlan, bool) {
plan := BootstrapPlan{
BeadsDir: beadsDir,
Database: cfg.GetDoltDatabase(),
}
var dbPath string
if isServer {
dbPath = bootstrapServerDoltDir(beadsDir, cfg, isSharedServer)
} else {
dbPath = filepath.Join(beadsDir, "embeddeddolt")
}
if info, err := os.Stat(dbPath); err != nil || !info.IsDir() {
return BootstrapPlan{}, false
}
entries, _ := os.ReadDir(dbPath)
if len(entries) == 0 {
return BootstrapPlan{}, false
}
if isServer {
probeCfg := bootstrapServerProbeConfig{
host: cfg.GetDoltServerHost(),
port: bootstrapServerPort(beadsDir, cfg, isSharedServer),
user: cfg.GetDoltServerUser(),
pass: cfg.GetDoltServerPassword(),
database: cfg.GetDoltDatabase(),
tls: cfg.GetDoltServerTLS(),
}
result := checkBootstrapServerDB(probeCfg)
if result.Err != nil {
plan.Action = "none"
plan.Reason = fmt.Sprintf("Could not verify existing server database %s: %v", cfg.GetDoltDatabase(), result.Err)
return plan, true
}
if result.Exists {
plan.HasExisting = true
plan.Action = "none"
plan.Reason = fmt.Sprintf("Database %s already exists on server at %s:%d", probeCfg.database, probeCfg.host, probeCfg.port)
return plan, true
}
return BootstrapPlan{}, false
}
plan.HasExisting = true
plan.Action = "none"
plan.Reason = "Database already exists at " + dbPath
return plan, true
}
func bootstrapSharedServerMode(beadsDir string) bool {
if v := os.Getenv("BEADS_DOLT_SHARED_SERVER"); v == "1" || strings.EqualFold(v, "true") {
return true
}
return strings.EqualFold(config.GetStringFromDir(beadsDir, "dolt.shared-server"), "true")
}
func bootstrapServerDoltDir(beadsDir string, cfg *configfile.Config, isSharedServer bool) string {
if isSharedServer {
if dir, err := doltserver.SharedDoltDir(); err == nil {
return dir
}
}
if d := cfg.GetDoltDataDir(); d != "" {
if filepath.IsAbs(d) {
return d
}
return filepath.Join(beadsDir, d)
}
return filepath.Join(beadsDir, "dolt")
}
func bootstrapServerPort(beadsDir string, cfg *configfile.Config, isSharedServer bool) int {
if p := os.Getenv("BEADS_DOLT_SERVER_PORT"); p != "" {
if port, err := strconv.Atoi(p); err == nil && port > 0 {
return port
}
}
if isSharedServer {
if sharedDir, err := doltserver.SharedServerDir(); err == nil {
if port := doltserver.ReadPortFile(sharedDir); port > 0 {
return port
}
}
return doltserver.DefaultSharedServerPort
}
if port := doltserver.ReadPortFile(beadsDir); port > 0 {
return port
}
if p := config.GetStringFromDir(beadsDir, "dolt.port"); p != "" {
if port, err := strconv.Atoi(p); err == nil && port > 0 {
return port
}
}
if cfg.DoltServerPort > 0 {
return cfg.DoltServerPort
}
return configfile.DefaultDoltServerPort
}
func printBootstrapPlan(plan BootstrapPlan) {
switch plan.Action {
case "none":
fmt.Printf("✓ Database already exists: %s\n", plan.BeadsDir)
if !usesSQLServer() {
fmt.Printf(" Nothing to do.\n")
} else {
fmt.Printf(" Nothing to do. Use 'bd doctor' to check health.\n")
}
case "sync":
fmt.Printf("Bootstrap plan: clone from remote\n")
fmt.Printf(" Remote: %s\n", plan.SyncRemote)
fmt.Printf(" Database: %s\n", plan.Database)
case "restore":
fmt.Printf("Bootstrap plan: restore from backup\n")
fmt.Printf(" Backup dir: %s\n", plan.BackupDir)
case "jsonl-import":
fmt.Printf("Bootstrap plan: import from git-tracked JSONL\n")
fmt.Printf(" JSONL file: %s\n", plan.JSONLFile)
fmt.Printf(" Database: %s\n", plan.Database)
case "init":
fmt.Printf("Bootstrap plan: create fresh database\n")
fmt.Printf(" Database: %s\n", plan.Database)
}
}
// confirmPrompt asks the user to confirm an action. Returns true if
// nonInteractive is set, stdin is not a terminal, or the user confirms.
func confirmPrompt(message string, nonInteractive bool) bool {
if nonInteractive {
return true
}
if !term.IsTerminal(int(os.Stdin.Fd())) {
return true
}
fmt.Fprintf(os.Stderr, "%s [Y/n] ", message)
reader := bufio.NewReader(os.Stdin)
line, _ := reader.ReadString('\n')
line = strings.TrimSpace(strings.ToLower(line))
return line == "" || line == "y" || line == "yes"
}
func executeBootstrapPlan(plan BootstrapPlan, cfg *configfile.Config, nonInteractive bool) error {
if !confirmPrompt("Proceed?", nonInteractive) {
fmt.Fprintf(os.Stderr, "Aborted.\n")
return nil
}
ctx := context.Background()
switch plan.Action {
case "sync":
return executeSyncAction(ctx, plan, cfg)
case "restore":
return executeRestoreAction(ctx, plan, cfg)
case "jsonl-import":
return executeJSONLImportAction(ctx, plan, cfg)
case "init":
return executeInitAction(ctx, plan, cfg)
}
return nil
}
func executeInitAction(ctx context.Context, plan BootstrapPlan, cfg *configfile.Config) error {
prefix := inferPrefix(cfg)
dbName := cfg.GetDoltDatabase()
s, err := newDoltStore(ctx, &dolt.Config{
Path: doltserver.ResolveDoltDir(plan.BeadsDir),
Database: dbName,
CreateIfMissing: true,
AutoStart: true,
BeadsDir: plan.BeadsDir,
})
if err != nil {
return fmt.Errorf("create database: %w", err)
}
defer func() { _ = s.Close() }()
if err := s.SetConfig(ctx, "issue_prefix", prefix); err != nil {
return fmt.Errorf("set issue prefix: %w", err)
}
if err := s.CommitWithConfig(ctx, "bd bootstrap"); err != nil {
return fmt.Errorf("commit: %w", err)
}
fmt.Fprintf(os.Stderr, "Created fresh database with prefix %q\n", prefix)
return nil
}
func executeRestoreAction(ctx context.Context, plan BootstrapPlan, cfg *configfile.Config) error {
prefix := inferPrefix(cfg)
dbName := cfg.GetDoltDatabase()
s, err := newDoltStore(ctx, &dolt.Config{
Path: doltserver.ResolveDoltDir(plan.BeadsDir),
Database: dbName,
CreateIfMissing: true,
AutoStart: true,
BeadsDir: plan.BeadsDir,
})
if err != nil {
return fmt.Errorf("create database: %w", err)
}
defer func() { _ = s.Close() }()
if err := s.SetConfig(ctx, "issue_prefix", prefix); err != nil {
return fmt.Errorf("set issue prefix: %w", err)
}
if err := s.CommitWithConfig(ctx, "bd bootstrap: init"); err != nil {
return fmt.Errorf("commit init: %w", err)
}
if err := runBackupRestore(ctx, s, plan.BackupDir, false); err != nil {
return fmt.Errorf("restore from backup: %w", err)
}
fmt.Fprintf(os.Stderr, "Restored from backup\n")
return nil
}
func executeJSONLImportAction(ctx context.Context, plan BootstrapPlan, cfg *configfile.Config) error {
prefix := inferPrefix(cfg)
dbName := cfg.GetDoltDatabase()
s, err := newDoltStore(ctx, &dolt.Config{
Path: doltserver.ResolveDoltDir(plan.BeadsDir),
Database: dbName,
CreateIfMissing: true,
AutoStart: true,
BeadsDir: plan.BeadsDir,
})
if err != nil {
return fmt.Errorf("create database: %w", err)
}
defer func() { _ = s.Close() }()
if err := s.SetConfig(ctx, "issue_prefix", prefix); err != nil {
return fmt.Errorf("set issue prefix: %w", err)
}
if err := s.CommitWithConfig(ctx, "bd bootstrap: init"); err != nil {
return fmt.Errorf("commit init: %w", err)
}
count, err := importFromLocalJSONL(ctx, s, plan.JSONLFile)
if err != nil {
return fmt.Errorf("import from JSONL: %w", err)
}
if err := s.Commit(ctx, "bd bootstrap: import from issues.jsonl"); err != nil {
return fmt.Errorf("commit import: %w", err)
}
fmt.Fprintf(os.Stderr, "Imported %d issues from %s\n", count, plan.JSONLFile)
return nil
}
func executeSyncAction(ctx context.Context, plan BootstrapPlan, cfg *configfile.Config) error {
// Ensure .beads directory exists — it may not in the "fresh clone"
// bootstrap path where we detected remote data before .beads was
// created. Deferred here to preserve --dry-run semantics. (GH#2792)
if err := os.MkdirAll(plan.BeadsDir, 0o750); err != nil {
return fmt.Errorf("create beads directory: %w", err)
}
dbName := cfg.GetDoltDatabase()
if err := cloneFromRemote(ctx, plan.BeadsDir, plan.SyncRemote, dbName, cfg); err != nil {
return err
}
// Finalize the bootstrapped workspace so subsequent bd commands can open
// the cloned database. Without metadata.json and config.yaml,
// configfile.Load() returns nil, callers fall back to the default
// dolt_database name, and bd loses track of the cloned database —
// producing "no beads configuration found" and "Error 1105: no database
// selected" on bd status / bd dolt push in fresh clones. Every other
// bootstrap action (init, restore, jsonl-import) writes these files via
// newDoltStore + createConfigYaml; the sync path historically did not.
// (GH#3201)
if err := finalizeSyncedBootstrap(plan.BeadsDir, plan.SyncRemote, cfg, dbName); err != nil {
return err
}
// Open and close the store to ensure dolt_ignore'd wisp tables are
// created in the working set. Clone does not include these tables
// (they are never committed), so they must be recreated after clone.
// Both embedded and server mode handle this in their store init paths.
warmupStore, err := newDoltStoreFromConfig(ctx, plan.BeadsDir)
if err != nil {
// #4259: the cloned remote is behind this binary, so the remote-migrate
// gate held migration for an explicit operator decision. Surface that
// now with bootstrap-specific guidance and a non-zero exit. Returning
// silent success here (as this path once did) sent operators in a
// loop: the first real command failed with the gate message, whose
// generic "adopt" remedy is `bd bootstrap` — which re-clones the same
// behind database and silently "succeeds" again (bd-6dnrw.31).
var gateErr *schema.RemoteMigrateGateError
if errors.As(err, &gateErr) {
if !jsonOutput {
printBootstrapRemoteBehindGuidance(os.Stderr, gateErr, plan.SyncRemote, "bd bootstrap")
}
unit := "migrations"
if gateErr.Pending == 1 {
unit = "migration"
}
return fmt.Errorf("clone from %s succeeded, but the database needs %d schema %s (v%d -> v%d) that bd will not auto-apply to a remote-backed database (#4259)",
plan.SyncRemote, gateErr.Pending, unit, gateErr.CurrentVersion, gateErr.LatestVersion)
}
// Non-fatal: wisp tables will be created on the next command that
// opens the store. Warn so the user knows to retry if they hit
// "table not found: wisp_*" errors.
fmt.Fprintf(os.Stderr, "Warning: post-clone store init failed (wisp tables may be missing): %v\n", err)
return nil
}
configureInitDoltRemote(ctx, warmupStore, plan.SyncRemote, false)
_ = warmupStore.Close()
return nil
}
// printBootstrapRemoteBehindGuidance explains a remote-migrate gate refusal in
// bootstrap terms. The gate's generic remedy ("adopt the migrated database:
// bd bootstrap") is wrong from inside a bootstrap-style clone — the database
// was just cloned from the remote, so the REMOTE is what is behind this binary
// and re-cloning can never help. The way out is exactly one designated machine
// migrating and pushing. rerunCmd is the command the operator just ran ("bd
// bootstrap", "bd init") so the don't-bother-retrying line names it.
func printBootstrapRemoteBehindGuidance(w io.Writer, e *schema.RemoteMigrateGateError, syncRemote, rerunCmd string) {
unit := "migrations"
if e.Pending == 1 {
unit = "migration"
}
fmt.Fprintf(w, "\nThe database cloned from %s needs %d schema %s (v%d -> v%d).\n",
syncRemote, e.Pending, unit, e.CurrentVersion, e.LatestVersion)
fmt.Fprint(w,
" bd will not migrate it automatically: migrating clones independently forks\n"+
" the schema so `bd dolt pull` can no longer merge (#4259).\n"+
"\n"+
" Re-running `"+rerunCmd+"` will NOT fix this — the remote itself is behind.\n"+
" Choose one:\n"+
" • This machine is the designated migrator (exactly ONE machine should be):\n"+
" bd migrate --force\n"+
" bd dolt push\n"+
" then other machines re-run `bd bootstrap` to adopt the migrated database.\n"+
" • Another machine is the designated migrator: wait for it to push, then\n"+
" re-run `bd bootstrap`, or keep using a bd version that matches the remote.\n\n")
}
// finalizeSyncedBootstrap writes metadata.json and config.yaml after a
// successful sync clone, matching the on-disk layout that bd init produces.
// It is idempotent: re-running over an already-finalized workspace leaves
// existing files intact (createConfigYaml skips if config.yaml exists; the
// metadata.json write is a full rewrite that preserves caller fields).
func finalizeSyncedBootstrap(beadsDir, syncRemote string, cfg *configfile.Config, dbName string) error {
// Preserve whatever upstream fields were already set in cfg (which may
// be DefaultConfig when metadata.json was absent, or a parent workspace
// config propagated by findParentConfig), then fill in the bits
// required by configfile.Load consumers.
cfg.Backend = configfile.BackendDolt
cfg.DoltDatabase = dbName
switch {
case cfg.IsDoltProxiedServerMode():
cfg.DoltMode = configfile.DoltModeProxiedServer
case cfg.IsDoltServerMode() || doltserver.IsSharedServerMode():
cfg.DoltMode = configfile.DoltModeServer
default:
cfg.DoltMode = configfile.DoltModeEmbedded
}
// Mirror init's convention: metadata.json database points at the Dolt
// directory rather than the legacy "beads.db" placeholder.
if cfg.Database == "" || cfg.Database == beads.CanonicalDatabaseName {
cfg.Database = "dolt"
}
if err := cfg.Save(beadsDir); err != nil {
return fmt.Errorf("write metadata.json: %w", err)
}
if err := createConfigYaml(beadsDir, false, ""); err != nil {
return fmt.Errorf("create config.yaml: %w", err)
}
if err := doctor.EnsureGitignoreForBeadsDir(beadsDir); err != nil {
return fmt.Errorf("ensure .beads/.gitignore: %w", err)
}
// Persist sync.remote so subsequent fresh clones (and bd bootstrap
// retries) can rediscover the remote without re-probing origin refs.
if syncRemote != "" {
if err := config.SetYamlConfigInDir(beadsDir, "sync.remote", syncRemote); err != nil {
return fmt.Errorf("persist sync.remote to config.yaml: %w", err)
}
}
return nil
}
type remoteCloneMode int
const (
remoteCloneAuto remoteCloneMode = iota
remoteCloneEmbedded
remoteCloneExternalServer
remoteCloneCLI
)
// cloneFromRemote clones a Dolt database from a remote URL.
// In embedded mode, uses the embedded engine's DOLT_CLONE procedure.
// In external server mode, connects to the running server via MySQL and
// executes DOLT_CLONE so the server places the database in its own data
// directory. In owned-server mode, shells out to dolt clone via
// BootstrapFromRemoteWithDB.
// Shared by bd init and bd bootstrap to keep clone logic in one place.
func cloneFromRemote(ctx context.Context, beadsDir, remoteURL, dbName string, cfg *configfile.Config) error {
return cloneFromRemoteWithMode(ctx, beadsDir, remoteURL, dbName, cfg, remoteCloneAuto)
}
func cloneFromRemoteWithMode(ctx context.Context, beadsDir, remoteURL, dbName string, cfg *configfile.Config, cloneMode remoteCloneMode) error {
mode := resolveRemoteCloneMode(beadsDir, cfg, cloneMode)
switch mode {
case remoteCloneEmbedded:
return cloneViaEmbedded(ctx, beadsDir, remoteURL, dbName)
case remoteCloneExternalServer:
if cfg == nil {
// Caller didn't provide config; fall back to loading from disk.
if loaded, err := configfile.Load(beadsDir); err == nil && loaded != nil {
cfg = loaded
}
}
if cfg != nil {
return cloneViaServer(ctx, beadsDir, remoteURL, dbName, cfg)
}
// No config available — fall through to CLI clone.
fmt.Fprintf(os.Stderr, "Warning: server mode detected but no config available, falling back to CLI clone\n")
return cloneViaCLI(ctx, beadsDir, remoteURL, dbName)
default:
return cloneViaCLI(ctx, beadsDir, remoteURL, dbName)
}
}
func resolveRemoteCloneMode(beadsDir string, cfg *configfile.Config, cloneMode remoteCloneMode) remoteCloneMode {
if cloneMode != remoteCloneAuto {
return cloneMode
}
if cfg != nil {
if cfg.IsDoltServerMode() || doltserver.IsSharedServerMode() || os.Getenv("BEADS_DOLT_SERVER_MODE") == "1" {
return remoteCloneExternalServer
}
return remoteCloneEmbedded
}
switch doltserver.ResolveServerMode(beadsDir) {
case doltserver.ServerModeEmbedded:
return remoteCloneEmbedded
case doltserver.ServerModeExternal:
return remoteCloneExternalServer
default:
return remoteCloneCLI
}
}
// cloneViaEmbedded clones using the embedded Dolt engine (CGO required).
func cloneViaEmbedded(ctx context.Context, beadsDir, remoteURL, dbName string) error {
dataDir := filepath.Join(beadsDir, "embeddeddolt")
if err := os.MkdirAll(dataDir, 0o750); err != nil {
return fmt.Errorf("create embeddeddolt directory: %w", err)
}
db, cleanup, err := embeddeddolt.OpenSQL(ctx, dataDir, "", "")
if err != nil {
return fmt.Errorf("open embedded engine for clone: %w", err)
}
defer func() { _ = cleanup() }()
if err := versioncontrolops.DoltClone(ctx, db, remoteURL, dbName, os.Getenv("DOLT_REMOTE_USER")); err != nil {
return fmt.Errorf("clone from remote: %w", err)
}
fmt.Fprintf(os.Stderr, "Synced database from %s\n", remoteURL)
return nil
}
// cloneViaServer clones by connecting to the external Dolt server and
// executing CALL DOLT_CLONE. The server places the database in its own
// data directory, which is the correct behavior for externally managed
// servers where bd does not know the filesystem layout.
func cloneViaServer(ctx context.Context, beadsDir, remoteURL, dbName string, cfg *configfile.Config) error {
port := serverClonePort(beadsDir, cfg)
dsn := doltutil.ServerDSN{
Socket: cfg.GetDoltServerSocket(),
Host: cfg.GetDoltServerHost(),
Port: port,
User: cfg.GetDoltServerUser(),
Password: cfg.GetDoltServerPasswordForPort(port),
TLS: cfg.GetDoltServerTLS(),
// No Database — DOLT_CLONE creates the database.
}.String()
db, err := sql.Open("mysql", dsn)
if err != nil {
return fmt.Errorf("connect to dolt server for clone: %w", err)
}
defer db.Close()
cloneCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)
defer cancel()
if err := db.PingContext(cloneCtx); err != nil {
return fmt.Errorf("dolt server unreachable at %s:%d (is dolt sql-server running?): %w",
cfg.GetDoltServerHost(), port, err)
}
if err := versioncontrolops.DoltClone(cloneCtx, db, remoteURL, dbName, os.Getenv("DOLT_REMOTE_USER")); err != nil {
return fmt.Errorf("clone from remote via server: %w", err)
}
fmt.Fprintf(os.Stderr, "Synced database from %s (via server at %s:%d)\n",
remoteURL, cfg.GetDoltServerHost(), port)
return nil
}
func serverClonePort(beadsDir string, cfg *configfile.Config) int {
if cfg != nil && cfg.DoltServerPort > 0 {
return cfg.DoltServerPort
}
if p := os.Getenv("BEADS_DOLT_SERVER_PORT"); p != "" {
if port, err := strconv.Atoi(p); err == nil && port > 0 {
return port
}
}
if p := os.Getenv("BEADS_DOLT_PORT"); p != "" {
if port, err := strconv.Atoi(p); err == nil && port > 0 {
return port
}
}
if resolved := doltserver.DefaultConfig(beadsDir); resolved.Port > 0 {
return resolved.Port
}
if cfg != nil {
return cfg.GetDoltServerPort()
}
return configfile.DefaultDoltServerPort
}
// cloneViaCLI clones by shelling out to the dolt CLI.
// Used for owned-server mode where bd manages the server lifecycle.
func cloneViaCLI(ctx context.Context, beadsDir, remoteURL, dbName string) error {
doltDir := doltserver.ResolveDoltDir(beadsDir)
synced, err := dolt.BootstrapFromRemoteWithDB(ctx, doltDir, remoteURL, dbName)
if err != nil {
return fmt.Errorf("sync from remote: %w", err)
}
if synced {
fmt.Fprintf(os.Stderr, "Synced database from %s\n", remoteURL)
}
return nil
}
func inferPrefix(cfg *configfile.Config) string {
db := cfg.GetDoltDatabase()
if db != "" && db != "beads" {
return db
}
cwd, _ := os.Getwd()
return filepath.Base(cwd)
}
// isNonInteractiveBootstrap returns true if bootstrap should skip confirmation prompts.
// Precedence: explicit flag > BD_NON_INTERACTIVE env > CI env > terminal detection.
func isNonInteractiveBootstrap(flagValue bool) bool {
if flagValue {
return true
}
if v := os.Getenv("BD_NON_INTERACTIVE"); v == "1" || v == "true" {
return true
}
if v := os.Getenv("CI"); v == "true" || v == "1" {
return true
}
return !term.IsTerminal(int(os.Stdin.Fd()))
}
// findParentConfig walks up from beadsDir's parent looking for a
// .beads/metadata.json in ancestor directories. This handles the case where a
// rig subdirectory (its own git repo) doesn't have a local .beads but its
// parent workspace does. Returns nil if no parent config is found.
func findParentConfig(beadsDir string) *configfile.Config {
// Start from the parent of beadsDir's enclosing directory.
// beadsDir is typically "<project>/.beads", so we start from <project>'s parent.
start := filepath.Dir(filepath.Dir(beadsDir))
homeDir, _ := os.UserHomeDir()
for dir := start; dir != "/" && dir != "."; {
candidate := filepath.Join(dir, ".beads")
if cfg, err := configfile.Load(candidate); err == nil && cfg != nil {
return cfg
}
// Don't search above $HOME
if homeDir != "" && dir == homeDir {
break
}
parent := filepath.Dir(dir)
if parent == dir {
break
}
dir = parent
}
return nil
}
func init() {
bootstrapCmd.Flags().Bool("dry-run", false, "Show what would be done without doing it")
bootstrapCmd.Flags().BoolP("yes", "y", false, "Skip confirmation prompts (for CI/automation)")
bootstrapCmd.Flags().Bool("non-interactive", false, "Alias for --yes")
rootCmd.AddCommand(bootstrapCmd)
}