beads/cmd/bd/bootstrap.go
Bella-Giraffety 4e4d958baf
fix: prefer bootstrap for missing database recovery (#2940)
* fix: prefer bootstrap for missing database recovery

Executed-By: beads/crew/emma

* fix: align doctor recovery guidance with bootstrap

Executed-By: beads/crew/emma

* fix: let bootstrap recover missing server databases

Executed-By: beads/crew/emma

* fix: bootstrap missing server databases safely

Executed-By: beads/crew/emma

* fix: fail closed on bootstrap server probe errors

Executed-By: beads/crew/emma

* fix: honor runtime server config in bootstrap

Executed-By: beads/crew/emma

* docs: soften bootstrap-first recovery wording

Executed-By: beads/crew/emma

* fix: report resolved bootstrap server port

Executed-By: beads/crew/emma

* fix: repair test failures from build tag mismatch and mode detection

Three issues causing CI failures on macOS and Ubuntu:

1. detectBootstrapAction used isEmbeddedMode() (global state) to choose
   the database path, but tests set cfg.DoltMode without updating the
   global serverMode flag. Switch to cfg.GetDoltMode() so the detection
   logic respects the config object passed by the caller.

2. TestDetectBootstrapAction_NoneWhenDatabaseExists created a "dolt"
   directory but default (embedded) config looks for "embeddeddolt".
   Fix the test to create the correct directory.

3. embeddeddolt/slots.go and new_methods_test.go used //go:build
   embeddeddolt tag while all other files in the package use cgo,
   causing interface satisfaction failures. Also fix undefined
   isEmbeddedDolt reference (should be isEmbeddedMode()).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Executed-By: beads/crew/emma

---------

Co-authored-by: mayor <thalia.geraghty@fiserv.com>
Co-authored-by: beads/crew/emma <steve.yegge@gmail.com>
2026-04-02 19:52:58 -07:00

547 lines
17 KiB
Go

package main
import (
"bufio"
"context"
"database/sql"
"fmt"
"os"
"path/filepath"
"strings"
"time"
_ "github.com/go-sql-driver/mysql"
"github.com/spf13/cobra"
"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/storage/dolt"
"github.com/steveyegge/beads/internal/storage/embeddeddolt"
"github.com/steveyegge/beads/internal/storage/versioncontrolops"
"golang.org/x/term"
)
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
user := probeCfg.user
password := probeCfg.pass
dbName := probeCfg.database
var userPart string
if password != "" {
userPart = fmt.Sprintf("%s:%s", user, password)
} else {
userPart = user
}
params := "timeout=5s"
if probeCfg.tls {
params += "&tls=true"
}
dsn := fmt.Sprintf("%s@tcp(%s:%d)/?%s", userPart, host, port, params)
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.git-remote is configured: clones from the remote
• 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
`,
Run: func(cmd *cobra.Command, args []string) {
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 existing Beads data (refs/dolt/data). This is
// the "fresh second clone" case: clone1 pushed Beads state to
// origin, and clone2 needs to bootstrap from it. (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 := gitRemoteGetURL("origin"); err == nil && originURL != "" {
if gitLsRemoteHasRef("origin", "refs/dolt/data") {
cwd, err := os.Getwd()
if err != nil {
FatalError("failed to get working directory: %v", err)
}
beadsDir = filepath.Join(cwd, ".beads")
}
}
}
}
if beadsDir == "" {
// No .beads and no remote data — nothing to bootstrap from.
if jsonOutput {
outputJSON(map[string]interface{}{
"action": "none",
"reason": "no .beads directory found",
"suggestion": "Run 'bd init' to create a new project",
})
} else {
fmt.Fprintf(os.Stderr, "No .beads directory found.\n")
fmt.Fprintf(os.Stderr, "To create a new project, use: bd init\n")
fmt.Fprintf(os.Stderr, "Bootstrap is for existing projects that need database setup.\n")
}
os.Exit(1)
}
// Load config
cfg, err := configfile.Load(beadsDir)
if err != nil || cfg == nil {
cfg = configfile.DefaultConfig()
}
// Determine action based on state
plan := detectBootstrapAction(beadsDir, cfg)
if jsonOutput {
outputJSON(plan)
if plan.Action == "none" || dryRun {
return
}
} else {
printBootstrapPlan(plan)
if plan.Action == "none" || dryRun {
return
}
}
// Execute the plan
if err := executeBootstrapPlan(plan, cfg, nonInteractive); err != nil {
FatalError("Bootstrap failed: %v", err)
}
},
}
// 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 detectBootstrapAction(beadsDir string, cfg *configfile.Config) BootstrapPlan {
plan := BootstrapPlan{
BeadsDir: beadsDir,
Database: cfg.GetDoltDatabase(),
}
// Check for existing database (path differs between server and embedded mode).
// Use cfg.GetDoltMode() rather than the global isEmbeddedMode() so that
// the detection logic respects the config object passed in by the caller
// (important for tests and for cases where the global serverMode flag
// has not been set yet).
var dbPath string
if cfg.GetDoltMode() == configfile.DoltModeServer {
dbPath = doltserver.ResolveDoltDir(beadsDir)
} else {
dbPath = filepath.Join(beadsDir, "embeddeddolt")
}
if info, err := os.Stat(dbPath); err == nil && info.IsDir() {
entries, _ := os.ReadDir(dbPath)
if len(entries) > 0 {
if cfg.GetDoltMode() == configfile.DoltModeServer {
resolved := doltserver.DefaultConfig(beadsDir)
probeCfg := bootstrapServerProbeConfig{
host: cfg.GetDoltServerHost(),
port: resolved.Port,
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
}
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
}
} else {
plan.HasExisting = true
plan.Action = "none"
plan.Reason = "Database already exists at " + dbPath
return plan
}
}
}
// Check sync.git-remote
syncRemote := config.GetString("sync.git-remote")
if syncRemote != "" {
plan.SyncRemote = syncRemote
plan.Action = "sync"
plan.Reason = "sync.git-remote configured — will clone from " + syncRemote
return plan
}
// Auto-detect: probe origin for refs/dolt/data
if isGitRepo() && !isBareGitRepo() {
if originURL, err := gitRemoteGetURL("origin"); err == nil && originURL != "" {
if gitLsRemoteHasRef("origin", "refs/dolt/data") {
plan.SyncRemote = gitURLToDoltRemote(originURL)
plan.Action = "sync"
plan.Reason = "Found existing beads database on origin (refs/dolt/data) — will clone from " + originURL
return plan
}
}
}
// 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
}
// Fresh setup
plan.Action = "init"
plan.Reason = "No existing database, remote, or backup — will create fresh database"
return plan
}
func printBootstrapPlan(plan BootstrapPlan) {
switch plan.Action {
case "none":
fmt.Printf("✓ Database already exists: %s\n", plan.BeadsDir)
if isEmbeddedMode() {
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.Commit(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.Commit(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.Commit(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 isEmbeddedMode() {
// Embedded mode: open a connection to the embedded engine and use
// DOLT_CLONE to create the database from the remote URL.
dataDir := filepath.Join(plan.BeadsDir, "embeddeddolt")
if err := os.MkdirAll(dataDir, 0o750); err != nil {
return fmt.Errorf("create embeddeddolt directory: %w", err)
}
// Open a connection without specifying a database (clone creates it).
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, plan.SyncRemote, dbName); err != nil {
return fmt.Errorf("clone from remote: %w", err)
}
// 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.
fmt.Fprintf(os.Stderr, "Synced database from %s\n", plan.SyncRemote)
return nil
}
doltDir := doltserver.ResolveDoltDir(plan.BeadsDir)
synced, err := dolt.BootstrapFromGitRemoteWithDB(ctx, doltDir, plan.SyncRemote, dbName)
if err != nil {
return fmt.Errorf("sync from remote: %w", err)
}
if synced {
// 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.
fmt.Fprintf(os.Stderr, "Synced database from %s\n", plan.SyncRemote)
}
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()))
}
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)
}