diff --git a/CHANGELOG.md b/CHANGELOG.md index d000a532b..2ed4a6e06 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Upgrade Notes + +- **JSONL auto-export and auto-staging are now opt-in.** Repositories that + relied on the previous implicit default should set it explicitly before or + after upgrading: + + ```bash + bd config set export.auto true + bd config set export.git-add true + ``` + + Dolt is the primary datastore. `.beads/issues.jsonl` is now treated as an + optional export for viewers such as `bv`, interchange, and issue-level + migration. It is not the canonical git-tracked source of truth, not + cross-machine sync, and not a full database backup. Use `bd dolt push` / + `bd dolt pull` for sync and `bd backup` for restorable database backups. + Existing repositories that already have `export.auto: true` or + `export.git-add: true` configured keep that behavior. + ### Added - **Foreign keys across issue and wisp tables.** Migrations `0040`–`0042` and the new `ignored/0001`–`ignored/0004` add explicit FKs with `ON DELETE CASCADE ON UPDATE CASCADE` on `dependencies`, `labels`, `comments`, `events`, `issue_snapshots`, `compaction_snapshots`, `child_counters`, and the matching `wisp_*` tables. Deleting or renaming a parent row now cascades automatically — the manual cleanup loops in `issueops/delete.go`, `dolt/wisps.go`, `dolt/ephemeral_routing.go`, and `cmd/bd/rename_prefix.go` have been removed (net ~300 lines down). ([#3952](https://github.com/gastownhall/beads/pull/3952)) @@ -43,7 +62,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Init refusal messages follow What/Why/Next structure** — runtime error text no longer echoes copy-pasteable destructive invocations. Token values and exact override commands live in `bd help init-safety` and `docs/RECOVERY.md` only. Closes the failure class where an AI agent destroyed 247 issues by pattern-matching on the tool's own error output (`58f5989bf`). - **`beads.OpenBestAvailable` signature changed (breaking)** — returns `(Storage, error)` instead of `(Storage, Unlocker, error)`. The per-open flock and `Unlocker` return value were removed; the embedded Dolt engine handles its own concurrency internally. External SDK consumers that call `OpenBestAvailable` must drop the second return value. ([PR #3614](https://github.com/gastownhall/beads/pull/3614)) - **Embedded-mode flock removed** — the process-lifetime exclusive flock on `.beads/embeddeddolt/` has been removed. Concurrent `bd` processes now open the embedded engine independently. If the GH#2571 nil-deref stack (`NewConnector` → `DoltDB.SetCrashOnFatalError` → `CollectDBs`) resurfaces under concurrent access, it should be filed and fixed in `dolthub/driver`, not reintroduced as a beads-side flock. ([PR #3614](https://github.com/gastownhall/beads/pull/3614)) -- **Auto-export is now on by default** — pending Dolt changes are committed automatically and exported to JSONL when configured, reducing manual sync drift in coordinated repos. +- **Auto-export is now opt-in by default** — repositories without explicit + `export.auto` / `export.git-add` settings leave JSONL refresh and staging + disabled unless a viewer or JSONL integration explicitly enables them. This + keeps `.beads/issues.jsonl` as an optional export surface, not the default + mutation path. ([GH#4062](https://github.com/gastownhall/beads/issues/4062)) + - **Release workflow uses the checked-in beads-release formula** — the old release shell path now delegates to the formula-backed release workflow with CI gates. ### Deprecated diff --git a/cmd/bd/config.go b/cmd/bd/config.go index 6cf6d1fc2..424748f90 100644 --- a/cmd/bd/config.go +++ b/cmd/bd/config.go @@ -36,15 +36,17 @@ Common namespaces: - doctor.suppress.* Suppress specific bd doctor warnings (GH#1095) Auto-Export (config.yaml): - Writes .beads/issues.jsonl after every write command (throttled). - Enabled by default. Useful for viewers (bv) and interchange; not a backup. + Optional JSONL export to .beads/issues.jsonl after write commands (throttled). + Useful for viewers (bv), interchange, and issue-level migration; not a backup. It is not cross-machine sync; use bd dolt push/pull with a Dolt remote. + Disabled by default. Enable only for integrations that need fresh JSONL. + Auto-staging is separate and disabled by default. Keys: - export.auto Enable/disable auto-export (default: true) + export.auto Enable/disable auto-export (default: false) export.path Output filename relative to .beads/ (default: issues.jsonl) export.interval Minimum time between exports (default: 60s) - export.git-add Auto-stage the export file (default: true) + export.git-add Auto-stage the export file (default: false) Custom Status States: You can define custom status states for multi-step pipelines using the @@ -65,8 +67,9 @@ Suppressing Doctor Warnings: To unsuppress: bd config unset doctor.suppress. Examples: - bd config set export.auto false # Disable auto-export + bd config set export.auto true # Enable auto-export for viewer integrations bd config set export.path "beads.jsonl" # Custom export filename + bd config set export.git-add true # Also stage the export file bd config set jira.url "https://company.atlassian.net" bd config set jira.project "PROJ" bd config set status.custom "awaiting_review,awaiting_testing" diff --git a/cmd/bd/export_auto.go b/cmd/bd/export_auto.go index 997e98412..9051a55d4 100644 --- a/cmd/bd/export_auto.go +++ b/cmd/bd/export_auto.go @@ -54,19 +54,27 @@ func maybeAutoExport(ctx context.Context) { return } - // Load state and check throttle + // Resolve the export path before throttle/check detection so all decisions + // refer to the path that would actually be written. + exportPath := config.GetString("export.path") + if exportPath == "" { + if globalFlag { + exportPath = "global-issues.jsonl" + } else { + exportPath = "issues.jsonl" + } + } + fullPath := filepath.Join(beadsDir, exportPath) + + // Load state + interval. state := loadExportAutoState(beadsDir) interval := config.GetDuration("export.interval") if interval == 0 { interval = 60 * time.Second } - if !state.Timestamp.IsZero() && time.Since(state.Timestamp) < interval { - debug.Logf("auto-export: throttled (last export %s ago, interval %s)\n", - time.Since(state.Timestamp).Round(time.Second), interval) - return - } - // Change detection via Dolt commit hash + // Change detection via Dolt commit hash. This is cheap, so do it before + // throttle: when there are no changes, there is nothing to throttle. currentCommit, err := store.GetCurrentCommit(ctx) if err != nil { fmt.Fprintf(os.Stderr, "Warning: auto-export skipped: failed to get current commit: %v\n", err) @@ -77,16 +85,11 @@ func maybeAutoExport(ctx context.Context) { return } - // Determine output path - exportPath := config.GetString("export.path") - if exportPath == "" { - if globalFlag { - exportPath = "global-issues.jsonl" - } else { - exportPath = "issues.jsonl" - } + if !shouldExport(state, interval) { + debug.Logf("auto-export: throttled (last export %s ago, interval %s)\n", + time.Since(state.Timestamp).Round(time.Second), interval) + return } - fullPath := filepath.Join(beadsDir, exportPath) // Run the export — memories are excluded from auto-export because they // contain private agent context that must not reach git history (GH#3650). @@ -128,6 +131,18 @@ func maybeAutoExport(ctx context.Context) { saveExportAutoState(beadsDir, &newState) } +// shouldExport reports whether the throttle window has elapsed, or whether +// this is the first auto-export attempt. It returns false only when a recent +// export exists and the configured interval has not elapsed. +// +// Extracted from Jeremy Longshore's GH#4061 throttle-decision refactor. +func shouldExport(state *exportAutoState, interval time.Duration) bool { + if state.Timestamp.IsZero() { + return true + } + return time.Since(state.Timestamp) >= interval +} + // exportToFile atomically exports issues + memories to the given file path. // Writes to a temp file first, then renames into place so readers never see // a partial or truncated export. Used by both `bd export -o` and auto-export. diff --git a/cmd/bd/export_auto_test.go b/cmd/bd/export_auto_test.go index 3dddbbe72..07331651d 100644 --- a/cmd/bd/export_auto_test.go +++ b/cmd/bd/export_auto_test.go @@ -6,6 +6,7 @@ import ( "path/filepath" "strings" "testing" + "time" "github.com/spf13/cobra" ) @@ -547,3 +548,54 @@ func TestGitAddFile_RedirectCase_DoesNotStageInMainRepo(t *testing.T) { checkNoStage("worktree", worktree) checkNoStage("main", mainRepo) } + +// TestShouldExport covers the pure throttle-window decision used by +// maybeAutoExport. Adapted from Jeremy Longshore's GH#4061 refactor. +func TestShouldExport(t *testing.T) { + now := time.Now() + cases := []struct { + name string + state *exportAutoState + interval time.Duration + want bool + }{ + { + name: "first run always exports", + state: &exportAutoState{}, + interval: time.Minute, + want: true, + }, + { + name: "throttle window active blocks", + state: &exportAutoState{Timestamp: now.Add(-10 * time.Second)}, + interval: time.Minute, + want: false, + }, + { + name: "throttle window elapsed allows", + state: &exportAutoState{Timestamp: now.Add(-2 * time.Minute)}, + interval: time.Minute, + want: true, + }, + { + name: "at interval boundary allows", + state: &exportAutoState{Timestamp: now.Add(-time.Minute)}, + interval: time.Minute, + want: true, + }, + { + name: "zero interval allows", + state: &exportAutoState{Timestamp: now.Add(-time.Microsecond)}, + interval: 0, + want: true, + }, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := shouldExport(tc.state, tc.interval); got != tc.want { + t.Errorf("shouldExport(%+v, %s) = %v, want %v", tc.state, tc.interval, got, tc.want) + } + }) + } +} diff --git a/cmd/bd/init.go b/cmd/bd/init.go index fed901577..5817a000d 100644 --- a/cmd/bd/init.go +++ b/cmd/bd/init.go @@ -53,17 +53,17 @@ Pass --server to use an external dolt sql-server instead. In server mode, set connection details with --server-host, --server-port, and --server-user. Password should be set via BEADS_DOLT_PASSWORD environment variable. -Auto-export is enabled by default. After every write command, bd exports -issues to .beads/issues.jsonl (throttled to once per 60s). This keeps -viewers (bv) and interchange up to date without extra steps. +Auto-export is optional. When enabled, bd exports issues to +.beads/issues.jsonl after write commands (throttled to once per 60s). This is +for viewers (bv), interchange, and issue-level migration; not backup. Cross-machine sync and backups use Dolt remotes/backups, not JSONL import/export. -To disable: bd config set export.auto false +To enable: bd config set export.auto true Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1): Skips all interactive prompts, using sensible defaults: • Role defaults to "maintainer" (override with --role) • Fork exclude auto-configured when fork detected - • Auto-export left at default (enabled) + • Auto-export left at default (disabled) • --contributor and --team flags are rejected (wizards require interaction) Also auto-detected when stdin is not a terminal or CI=true is set.`, Run: func(cmd *cobra.Command, _ []string) { @@ -1275,22 +1275,23 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1): } } - // Auto-export prompt: enabled by default, let user opt out interactively (GH#2973). - // In non-interactive mode the default (enabled) is kept. + // Auto-export prompt: disabled by default, let users opt in + // interactively for viewers and other JSONL integrations (GH#4062). + // In non-interactive mode the default (disabled) is kept. if !nonInteractive && !quiet { wantExport, err := promptAutoExport() if err != nil && isCanceled(err) { fmt.Fprintln(os.Stderr, "Setup canceled.") exitCanceled() } - if !wantExport { - if err := config.SetYamlConfig("export.auto", "false"); err != nil { - fmt.Fprintf(os.Stderr, "Warning: failed to disable auto-export: %v\n", err) + if wantExport { + if err := config.SetYamlConfig("export.auto", "true"); err != nil { + fmt.Fprintf(os.Stderr, "Warning: failed to enable auto-export: %v\n", err) } else { - fmt.Printf(" %s Auto-export disabled (enable later with: bd config set export.auto true)\n", ui.RenderPass("✓")) + fmt.Printf(" %s Auto-export enabled -> .beads/issues.jsonl\n", ui.RenderPass("✓")) } } else if !quiet { - fmt.Printf(" %s Auto-export enabled → .beads/issues.jsonl\n", ui.RenderPass("✓")) + fmt.Printf(" %s Auto-export disabled (enable later with: bd config set export.auto true)\n", ui.RenderPass("✓")) } } @@ -1978,12 +1979,13 @@ func promptContributorMode() (isContributor bool, err error) { return isContributor, nil } -// promptAutoExport asks the user whether to keep auto-export enabled (the default). -// Returns true to keep it enabled, false to disable. +// promptAutoExport asks the user whether to enable optional auto-export. +// Returns true to enable it, false to leave it disabled. func promptAutoExport() (bool, error) { - fmt.Printf("\n%s Auto-export keeps .beads/issues.jsonl up to date after every write command.\n", ui.RenderAccent("▶")) - fmt.Println(" This is useful for viewers (bv) and interchange. Dolt remotes/backups handle sync and backup.") - fmt.Print("\nEnable auto-export? [Y/n]: ") + fmt.Printf("\n%s Auto-export can keep .beads/issues.jsonl up to date after write commands.\n", ui.RenderAccent("▶")) + fmt.Println(" This optional JSONL export is useful for viewers (bv), interchange, and issue-level migration.") + fmt.Println(" Dolt remotes/backups handle cross-machine sync and backup.") + fmt.Print("\nEnable auto-export? [y/N]: ") reader := bufio.NewReader(os.Stdin) response, err := readLineWithContext(getRootContext(), reader, os.Stdin) @@ -1995,8 +1997,8 @@ func promptAutoExport() (bool, error) { } response = strings.TrimSpace(strings.ToLower(response)) - // Default to yes (empty or "y" or "yes") - return response == "" || response == "y" || response == "yes", nil + // Default to no. Users and integrations can enable it explicitly. + return response == "y" || response == "yes", nil } func shouldWireInitRemote(syncURL string, syncFromRemote, syncURLFromConfig, syncURLFromGitOrigin bool) bool { diff --git a/cmd/bd/init_noninteractive_test.go b/cmd/bd/init_noninteractive_test.go index 95c4df1da..08b4d83ec 100644 --- a/cmd/bd/init_noninteractive_test.go +++ b/cmd/bd/init_noninteractive_test.go @@ -2,7 +2,11 @@ package main import ( "os" + "os/exec" + "path/filepath" + "strings" "testing" + "time" ) // TestIsNonInteractiveInit tests the non-interactive detection logic. @@ -126,3 +130,62 @@ func TestIsNonInteractiveInitPrecedence(t *testing.T) { t.Error("BD_NON_INTERACTIVE=1 should return true") } } + +func TestInitNonInteractiveAutoExportDefaultOffAndOptIn(t *testing.T) { + bd := buildBDForInitTests(t) + dir := t.TempDir() + + runBDForAutoExportInitTest(t, bd, dir, "init", "--prefix", "test", "--quiet", "--non-interactive", "--skip-hooks", "--skip-agents") + + if got := strings.TrimSpace(runBDStdoutForAutoExportInitTest(t, bd, dir, "config", "get", "export.auto")); got != "false" { + t.Fatalf("export.auto default = %q, want false", got) + } + if got := strings.TrimSpace(runBDStdoutForAutoExportInitTest(t, bd, dir, "config", "get", "export.git-add")); got != "false" { + t.Fatalf("export.git-add default = %q, want false", got) + } + + runBDForAutoExportInitTest(t, bd, dir, "create", "default-off issue", "-p", "2") + jsonlPath := filepath.Join(dir, ".beads", "issues.jsonl") + if _, err := os.Stat(jsonlPath); !os.IsNotExist(err) { + t.Fatalf("default-off create wrote %s; stat err=%v", jsonlPath, err) + } + + runBDForAutoExportInitTest(t, bd, dir, "config", "set", "export.interval", "1ms") + runBDForAutoExportInitTest(t, bd, dir, "config", "set", "export.auto", "true") + if got := strings.TrimSpace(runBDStdoutForAutoExportInitTest(t, bd, dir, "config", "get", "export.auto")); got != "true" { + t.Fatalf("explicit export.auto = %q, want true", got) + } + time.Sleep(10 * time.Millisecond) + runBDForAutoExportInitTest(t, bd, dir, "create", "explicit export issue", "-p", "2") + data, err := os.ReadFile(jsonlPath) + if err != nil { + t.Fatalf("explicit export.auto did not write %s: %v", jsonlPath, err) + } + if !strings.Contains(string(data), "explicit export issue") { + t.Fatalf("JSONL export did not contain created issue:\n%s", data) + } +} + +func runBDStdoutForAutoExportInitTest(t *testing.T, bd, dir string, args ...string) string { + t.Helper() + cmd := exec.Command(bd, args...) + cmd.Dir = dir + cmd.Env = append(os.Environ(), "BD_NON_INTERACTIVE=1") + out, err := cmd.Output() + if err != nil { + t.Fatalf("bd %v failed: %v", args, err) + } + return string(out) +} + +func runBDForAutoExportInitTest(t *testing.T, bd, dir string, args ...string) string { + t.Helper() + cmd := exec.Command(bd, args...) + cmd.Dir = dir + cmd.Env = append(os.Environ(), "BD_NON_INTERACTIVE=1") + out, err := cmd.CombinedOutput() + if err != nil { + t.Fatalf("bd %v failed: %v\n%s", args, err, out) + } + return string(out) +} diff --git a/cmd/bd/init_templates.go b/cmd/bd/init_templates.go index d82c59470..c0a467df8 100644 --- a/cmd/bd/init_templates.go +++ b/cmd/bd/init_templates.go @@ -81,6 +81,14 @@ func renderInitConfigYAML(prefix string, noDbMode bool) []byte { # git-push: false # Disable git push (backup locally only) # git-repo: "" # Separate git repo for backups (default: project repo) +# Optional JSONL auto-export for viewers, interchange, and issue-level migration. +# Disabled by default; enable only when an integration needs fresh .beads/issues.jsonl. +# export: +# auto: false +# path: issues.jsonl +# interval: 60s +# git-add: false + # Integration settings (access with 'bd config get/set') # Non-secret keys (stored in the database): # - jira.url, jira.project diff --git a/cmd/bd/prompt_test.go b/cmd/bd/prompt_test.go index 6a8aa9829..d94328b8f 100644 --- a/cmd/bd/prompt_test.go +++ b/cmd/bd/prompt_test.go @@ -89,3 +89,85 @@ func TestReadLineWithContextCanceled(t *testing.T) { t.Fatal("timeout waiting for readLineWithContext") } } + +func TestPromptAutoExportDefaultsOff(t *testing.T) { + got, output, err := runPromptAutoExport(t, "\n") + if err != nil { + t.Fatalf("promptAutoExport returned error: %v", err) + } + if got { + t.Fatal("empty response should leave auto-export disabled") + } + if !strings.Contains(output, "Enable auto-export? [y/N]:") { + t.Fatalf("prompt did not show opt-in default:\n%s", output) + } + if !strings.Contains(output, "optional JSONL export") { + t.Fatalf("prompt should describe JSONL as optional export:\n%s", output) + } + if !strings.Contains(output, "Dolt remotes/backups handle cross-machine sync and backup") { + t.Fatalf("prompt should direct sync to Dolt remotes:\n%s", output) + } +} + +func TestPromptAutoExportAcceptsYes(t *testing.T) { + got, _, err := runPromptAutoExport(t, "yes\n") + if err != nil { + t.Fatalf("promptAutoExport returned error: %v", err) + } + if !got { + t.Fatal("yes response should enable auto-export") + } +} + +func runPromptAutoExport(t *testing.T, input string) (bool, string, error) { + t.Helper() + + stdinFile, err := os.CreateTemp(t.TempDir(), "stdin-*") + if err != nil { + t.Fatalf("create temp stdin: %v", err) + } + if _, err := stdinFile.WriteString(input); err != nil { + t.Fatalf("write temp stdin: %v", err) + } + if _, err := stdinFile.Seek(0, 0); err != nil { + t.Fatalf("rewind temp stdin: %v", err) + } + + oldStdin := os.Stdin + oldStdout := os.Stdout + oldRootCtx := rootCtx + oldRootCancel := rootCancel + var oldCmdRootCtx context.Context + var oldCmdRootCancel context.CancelFunc + if cmdCtx != nil { + oldCmdRootCtx = cmdCtx.RootCtx + oldCmdRootCancel = cmdCtx.RootCancel + } + r, w, err := os.Pipe() + if err != nil { + t.Fatalf("create stdout pipe: %v", err) + } + ctx, cancel := context.WithCancel(context.Background()) + setRootContext(ctx, cancel) + os.Stdin = stdinFile + os.Stdout = w + + got, promptErr := promptAutoExport() + + _ = w.Close() + var b strings.Builder + _, _ = io.Copy(&b, r) + _ = r.Close() + os.Stdin = oldStdin + os.Stdout = oldStdout + cancel() + rootCtx = oldRootCtx + rootCancel = oldRootCancel + if cmdCtx != nil { + cmdCtx.RootCtx = oldCmdRootCtx + cmdCtx.RootCancel = oldCmdRootCancel + } + _ = stdinFile.Close() + + return got, b.String(), promptErr +} diff --git a/cmd/bd/testdata/auto_export.txt b/cmd/bd/testdata/auto_export.txt index 51e7a24b9..c326b34a9 100644 --- a/cmd/bd/testdata/auto_export.txt +++ b/cmd/bd/testdata/auto_export.txt @@ -8,6 +8,7 @@ stdout 'initialized successfully' ! exists .beads/export-state.json # First real write must export immediately, not wait for throttle to expire. +bd config set export.auto true bd create 'First issue' exists .beads/issues.jsonl grep 'First issue' .beads/issues.jsonl diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index 31280c855..138786600 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -2584,15 +2584,17 @@ Common namespaces: - doctor.suppress.* Suppress specific bd doctor warnings (GH#1095) Auto-Export (config.yaml): - Writes .beads/issues.jsonl after every write command (throttled). - Enabled by default. Useful for viewers (bv) and interchange; not a backup. + Optional JSONL export to .beads/issues.jsonl after write commands (throttled). + Useful for viewers (bv), interchange, and issue-level migration; not a backup. It is not cross-machine sync; use bd dolt push/pull with a Dolt remote. + Disabled by default. Enable only for integrations that need fresh JSONL. + Auto-staging is separate and disabled by default. Keys: - export.auto Enable/disable auto-export (default: true) + export.auto Enable/disable auto-export (default: false) export.path Output filename relative to .beads/ (default: issues.jsonl) export.interval Minimum time between exports (default: 60s) - export.git-add Auto-stage the export file (default: true) + export.git-add Auto-stage the export file (default: false) Custom Status States: You can define custom status states for multi-step pipelines using the @@ -2613,8 +2615,9 @@ Suppressing Doctor Warnings: To unsuppress: bd config unset doctor.suppress.<slug> Examples: - bd config set export.auto false # Disable auto-export + bd config set export.auto true # Enable auto-export for viewer integrations bd config set export.path "beads.jsonl" # Custom export filename + bd config set export.git-add true # Also stage the export file bd config set jira.url "https://company.atlassian.net" bd config set jira.project "PROJ" bd config set status.custom "awaiting_review,awaiting_testing" @@ -3343,17 +3346,17 @@ Pass --server to use an external dolt sql-server instead. In server mode, set connection details with --server-host, --server-port, and --server-user. Password should be set via BEADS_DOLT_PASSWORD environment variable. -Auto-export is enabled by default. After every write command, bd exports -issues to .beads/issues.jsonl (throttled to once per 60s). This keeps -viewers (bv) and interchange up to date without extra steps. +Auto-export is optional. When enabled, bd exports issues to +.beads/issues.jsonl after write commands (throttled to once per 60s). This is +for viewers (bv), interchange, and issue-level migration; not backup. Cross-machine sync and backups use Dolt remotes/backups, not JSONL import/export. -To disable: bd config set export.auto false +To enable: bd config set export.auto true Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1): Skips all interactive prompts, using sensible defaults: • Role defaults to "maintainer" (override with --role) • Fork exclude auto-configured when fork detected - • Auto-export left at default (enabled) + • Auto-export left at default (disabled) • --contributor and --team flags are rejected (wizards require interaction) Also auto-detected when stdin is not a terminal or CI=true is set. diff --git a/docs/CONFIG.md b/docs/CONFIG.md index 031782bca..d0a47906f 100644 --- a/docs/CONFIG.md +++ b/docs/CONFIG.md @@ -346,10 +346,10 @@ Configuration keys use dot-notation namespaces to organize settings: - `min_hash_length` - Minimum hash ID length (default: 4) - `max_hash_length` - Maximum hash ID length (default: 8) - `import.orphan_handling` - How to handle hierarchical issues with missing parents during import (default: `allow`) -- `export.auto` - Refresh the JSONL export after every write command (default: `true`). This is for viewers, interchange, and issue-level migration; it is not cross-machine sync and not a full database backup. +- `export.auto` - Refresh the JSONL export after every write command (default: `false`). This is for viewers, interchange, and issue-level migration; it is not cross-machine sync and not a full database backup. - `export.path` - Output filename relative to `.beads/` (default: `issues.jsonl`) - `export.interval` - Minimum time between auto-exports (default: `60s`) -- `export.git-add` - Run `git add` on the export file after writing (default: `true`) +- `export.git-add` - Run `git add` on the export file after writing (default: `false`) - `export.error_policy` - Error handling strategy for exports (default: `strict`) - `export.retry_attempts` - Number of retry attempts for transient errors (default: 3) - `export.retry_backoff_ms` - Initial backoff in milliseconds for retries (default: 100) @@ -360,6 +360,20 @@ Configuration keys use dot-notation namespaces to organize settings: - `sync.branch` - Name of the dedicated sync branch for beads data (see docs/PROTECTED_BRANCHES.md) - `sync.require_confirmation_on_mass_delete` - Require interactive confirmation before pushing when >50% of issues vanish during a merge AND more than 5 issues existed before (default: `false`) +**Upgrade note:** `export.auto` and `export.git-add` are opt-in. Older releases +briefly made `.beads/issues.jsonl` look like the default git-tracked source of +truth; current releases treat it as an optional export for viewers, +interchange, and issue-level migration. If your workflow depends on fresh JSONL +or on the pre-commit hook staging that file, set both values explicitly: + +```bash +bd config set export.auto true +bd config set export.git-add true +``` + +Use `bd dolt push` / `bd dolt pull` for cross-machine sync and `bd backup` for +restorable database backups. + ### Integration Namespaces Use these namespaces for external integrations: diff --git a/internal/config/config.go b/internal/config/config.go index b9161e5ee..706dd55fc 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -237,13 +237,13 @@ func Initialize() error { v.SetDefault("backup.git-push", false) v.SetDefault("backup.git-repo", "") - // Auto-export: write JSONL after mutations for viewers, interchange, and - // backup. It is not cross-machine sync; Dolt remotes are the source of - // truth for sync. Enabled by default so tools like bv see fresh data. - v.SetDefault("export.auto", true) + // Auto-export: optional JSONL export after mutations for viewers, + // interchange, and backup. It is not cross-machine sync; Dolt remotes are + // the source of truth for sync. Viewer integrations can opt in explicitly. + v.SetDefault("export.auto", false) v.SetDefault("export.interval", "60s") v.SetDefault("export.path", "issues.jsonl") // relative to .beads/; canonical name - v.SetDefault("export.git-add", true) + v.SetDefault("export.git-add", false) // Auto-import: legacy compatibility fallback for projects that have not // configured a Dolt remote yet. Hook code skips this path when sync.remote diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 6d4216a48..b35fd25d2 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -66,6 +66,8 @@ func TestDefaults(t *testing.T) { {"json", false, func(k string) interface{} { return GetBool(k) }}, {"db", "", func(k string) interface{} { return GetString(k) }}, {"actor", "", func(k string) interface{} { return GetString(k) }}, + {"export.auto", false, func(k string) interface{} { return GetBool(k) }}, + {"export.git-add", false, func(k string) interface{} { return GetBool(k) }}, } for _, tt := range tests { diff --git a/website/docs/cli-reference/config.md b/website/docs/cli-reference/config.md index 061c41f0c..584188f7e 100644 --- a/website/docs/cli-reference/config.md +++ b/website/docs/cli-reference/config.md @@ -24,15 +24,17 @@ Common namespaces: - doctor.suppress.* Suppress specific bd doctor warnings (GH#1095) Auto-Export (config.yaml): - Writes .beads/issues.jsonl after every write command (throttled). - Enabled by default. Useful for viewers (bv) and interchange; not a backup. + Optional JSONL export to .beads/issues.jsonl after write commands (throttled). + Useful for viewers (bv), interchange, and issue-level migration; not a backup. It is not cross-machine sync; use bd dolt push/pull with a Dolt remote. + Disabled by default. Enable only for integrations that need fresh JSONL. + Auto-staging is separate and disabled by default. Keys: - export.auto Enable/disable auto-export (default: true) + export.auto Enable/disable auto-export (default: false) export.path Output filename relative to .beads/ (default: issues.jsonl) export.interval Minimum time between exports (default: 60s) - export.git-add Auto-stage the export file (default: true) + export.git-add Auto-stage the export file (default: false) Custom Status States: You can define custom status states for multi-step pipelines using the @@ -53,8 +55,9 @@ Suppressing Doctor Warnings: To unsuppress: bd config unset doctor.suppress.<slug> Examples: - bd config set export.auto false # Disable auto-export + bd config set export.auto true # Enable auto-export for viewer integrations bd config set export.path "beads.jsonl" # Custom export filename + bd config set export.git-add true # Also stage the export file bd config set jira.url "https://company.atlassian.net" bd config set jira.project "PROJ" bd config set status.custom "awaiting_review,awaiting_testing" diff --git a/website/docs/cli-reference/init.md b/website/docs/cli-reference/init.md index 6d917a854..583d02f59 100644 --- a/website/docs/cli-reference/init.md +++ b/website/docs/cli-reference/init.md @@ -30,17 +30,17 @@ Pass --server to use an external dolt sql-server instead. In server mode, set connection details with --server-host, --server-port, and --server-user. Password should be set via BEADS_DOLT_PASSWORD environment variable. -Auto-export is enabled by default. After every write command, bd exports -issues to .beads/issues.jsonl (throttled to once per 60s). This keeps -viewers (bv) and interchange up to date without extra steps. +Auto-export is optional. When enabled, bd exports issues to +.beads/issues.jsonl after write commands (throttled to once per 60s). This is +for viewers (bv), interchange, and issue-level migration; not backup. Cross-machine sync and backups use Dolt remotes/backups, not JSONL import/export. -To disable: bd config set export.auto false +To enable: bd config set export.auto true Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1): Skips all interactive prompts, using sensible defaults: • Role defaults to "maintainer" (override with --role) • Fork exclude auto-configured when fork detected - • Auto-export left at default (enabled) + • Auto-export left at default (disabled) • --contributor and --team flags are rejected (wizards require interaction) Also auto-detected when stdin is not a terminal or CI=true is set. diff --git a/website/docs/reference/configuration.md b/website/docs/reference/configuration.md index cf7e5b49e..e10e7ac0a 100644 --- a/website/docs/reference/configuration.md +++ b/website/docs/reference/configuration.md @@ -108,10 +108,10 @@ Secrets in this list are refused on git-tracked `config.yaml` files unless you p | `backup.interval` | — | `BD_BACKUP_INTERVAL` | `15m` | Minimum time between auto-backups | | `backup.git-push` | — | — | `false` | Auto-push backup repo | | `backup.git-repo` | — | `BD_BACKUP_GIT_REPO` | (none) | Backup git repo URL | -| `export.auto` | — | — | `true` | Refresh `.beads/issues.jsonl` export after every write; not cross-machine sync | +| `export.auto` | — | — | `false` | Refresh `.beads/issues.jsonl` export after every write; not cross-machine sync | | `export.path` | — | — | `issues.jsonl` | Output filename relative to `.beads/` | | `export.interval` | — | — | `60s` | Minimum time between auto-exports | -| `export.git-add` | — | — | `true` | Run `git add` on the export file | +| `export.git-add` | — | — | `false` | Run `git add` on the export file | | `routing.mode` | — | — | (none) | Multi-repo routing: `auto`, `maintainer`, `contributor`, `explicit` | | `routing.default` | — | — | `.` | Default routing target | | `routing.maintainer` | — | — | `.` | Maintainer-routed path | @@ -127,6 +127,25 @@ Secrets in this list are refused on git-tracked `config.yaml` files unless you p | `ai.model` | — | `BD_AI_MODEL` | `claude-haiku-4-5-20251001` | Default AI model | | `agents.file` | — | — | `AGENTS.md` | Agents instruction filename; see routing note below | +:::important JSONL export is opt-in + +`export.auto` and `export.git-add` are disabled unless configured explicitly. +`.beads/issues.jsonl` is an optional export for viewers, interchange, and +issue-level migration. It is not the canonical source of truth, not +cross-machine sync, and not a full database backup. + +Workflows that depend on a fresh, git-staged JSONL file should opt in: + +```bash +bd config set export.auto true +bd config set export.git-add true +``` + +Use `bd dolt push` / `bd dolt pull` for sync and `bd backup` for restorable +database backups. + +::: + Routing note: `output.title-length` and `agents.file` are functionally tool-level settings, but `bd config set` writes them to the Dolt database. They are typically read from `config.yaml` when set there directly. `bd config show` is the source of truth for what's currently effective on your machine, including provenance. @@ -212,12 +231,12 @@ backup: enabled: true interval: 15m -# Auto-export issues.jsonl after writes for viewers/interchange +# Optional auto-export of issues.jsonl after writes for viewers/interchange export: - auto: true + auto: false path: issues.jsonl interval: 60s - git-add: true + git-add: false # Optional Dolt federation federation: diff --git a/website/versioned_docs/version-1.0.0/cli-reference/config.md b/website/versioned_docs/version-1.0.0/cli-reference/config.md index 061c41f0c..584188f7e 100644 --- a/website/versioned_docs/version-1.0.0/cli-reference/config.md +++ b/website/versioned_docs/version-1.0.0/cli-reference/config.md @@ -24,15 +24,17 @@ Common namespaces: - doctor.suppress.* Suppress specific bd doctor warnings (GH#1095) Auto-Export (config.yaml): - Writes .beads/issues.jsonl after every write command (throttled). - Enabled by default. Useful for viewers (bv) and interchange; not a backup. + Optional JSONL export to .beads/issues.jsonl after write commands (throttled). + Useful for viewers (bv), interchange, and issue-level migration; not a backup. It is not cross-machine sync; use bd dolt push/pull with a Dolt remote. + Disabled by default. Enable only for integrations that need fresh JSONL. + Auto-staging is separate and disabled by default. Keys: - export.auto Enable/disable auto-export (default: true) + export.auto Enable/disable auto-export (default: false) export.path Output filename relative to .beads/ (default: issues.jsonl) export.interval Minimum time between exports (default: 60s) - export.git-add Auto-stage the export file (default: true) + export.git-add Auto-stage the export file (default: false) Custom Status States: You can define custom status states for multi-step pipelines using the @@ -53,8 +55,9 @@ Suppressing Doctor Warnings: To unsuppress: bd config unset doctor.suppress.<slug> Examples: - bd config set export.auto false # Disable auto-export + bd config set export.auto true # Enable auto-export for viewer integrations bd config set export.path "beads.jsonl" # Custom export filename + bd config set export.git-add true # Also stage the export file bd config set jira.url "https://company.atlassian.net" bd config set jira.project "PROJ" bd config set status.custom "awaiting_review,awaiting_testing" diff --git a/website/versioned_docs/version-1.0.0/cli-reference/init.md b/website/versioned_docs/version-1.0.0/cli-reference/init.md index 6d917a854..583d02f59 100644 --- a/website/versioned_docs/version-1.0.0/cli-reference/init.md +++ b/website/versioned_docs/version-1.0.0/cli-reference/init.md @@ -30,17 +30,17 @@ Pass --server to use an external dolt sql-server instead. In server mode, set connection details with --server-host, --server-port, and --server-user. Password should be set via BEADS_DOLT_PASSWORD environment variable. -Auto-export is enabled by default. After every write command, bd exports -issues to .beads/issues.jsonl (throttled to once per 60s). This keeps -viewers (bv) and interchange up to date without extra steps. +Auto-export is optional. When enabled, bd exports issues to +.beads/issues.jsonl after write commands (throttled to once per 60s). This is +for viewers (bv), interchange, and issue-level migration; not backup. Cross-machine sync and backups use Dolt remotes/backups, not JSONL import/export. -To disable: bd config set export.auto false +To enable: bd config set export.auto true Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1): Skips all interactive prompts, using sensible defaults: • Role defaults to "maintainer" (override with --role) • Fork exclude auto-configured when fork detected - • Auto-export left at default (enabled) + • Auto-export left at default (disabled) • --contributor and --team flags are rejected (wizards require interaction) Also auto-detected when stdin is not a terminal or CI=true is set. diff --git a/website/versioned_docs/version-1.0.4/cli-reference/config.md b/website/versioned_docs/version-1.0.4/cli-reference/config.md index 061c41f0c..584188f7e 100644 --- a/website/versioned_docs/version-1.0.4/cli-reference/config.md +++ b/website/versioned_docs/version-1.0.4/cli-reference/config.md @@ -24,15 +24,17 @@ Common namespaces: - doctor.suppress.* Suppress specific bd doctor warnings (GH#1095) Auto-Export (config.yaml): - Writes .beads/issues.jsonl after every write command (throttled). - Enabled by default. Useful for viewers (bv) and interchange; not a backup. + Optional JSONL export to .beads/issues.jsonl after write commands (throttled). + Useful for viewers (bv), interchange, and issue-level migration; not a backup. It is not cross-machine sync; use bd dolt push/pull with a Dolt remote. + Disabled by default. Enable only for integrations that need fresh JSONL. + Auto-staging is separate and disabled by default. Keys: - export.auto Enable/disable auto-export (default: true) + export.auto Enable/disable auto-export (default: false) export.path Output filename relative to .beads/ (default: issues.jsonl) export.interval Minimum time between exports (default: 60s) - export.git-add Auto-stage the export file (default: true) + export.git-add Auto-stage the export file (default: false) Custom Status States: You can define custom status states for multi-step pipelines using the @@ -53,8 +55,9 @@ Suppressing Doctor Warnings: To unsuppress: bd config unset doctor.suppress.<slug> Examples: - bd config set export.auto false # Disable auto-export + bd config set export.auto true # Enable auto-export for viewer integrations bd config set export.path "beads.jsonl" # Custom export filename + bd config set export.git-add true # Also stage the export file bd config set jira.url "https://company.atlassian.net" bd config set jira.project "PROJ" bd config set status.custom "awaiting_review,awaiting_testing" diff --git a/website/versioned_docs/version-1.0.4/cli-reference/init.md b/website/versioned_docs/version-1.0.4/cli-reference/init.md index 6d917a854..583d02f59 100644 --- a/website/versioned_docs/version-1.0.4/cli-reference/init.md +++ b/website/versioned_docs/version-1.0.4/cli-reference/init.md @@ -30,17 +30,17 @@ Pass --server to use an external dolt sql-server instead. In server mode, set connection details with --server-host, --server-port, and --server-user. Password should be set via BEADS_DOLT_PASSWORD environment variable. -Auto-export is enabled by default. After every write command, bd exports -issues to .beads/issues.jsonl (throttled to once per 60s). This keeps -viewers (bv) and interchange up to date without extra steps. +Auto-export is optional. When enabled, bd exports issues to +.beads/issues.jsonl after write commands (throttled to once per 60s). This is +for viewers (bv), interchange, and issue-level migration; not backup. Cross-machine sync and backups use Dolt remotes/backups, not JSONL import/export. -To disable: bd config set export.auto false +To enable: bd config set export.auto true Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1): Skips all interactive prompts, using sensible defaults: • Role defaults to "maintainer" (override with --role) • Fork exclude auto-configured when fork detected - • Auto-export left at default (enabled) + • Auto-export left at default (disabled) • --contributor and --team flags are rejected (wizards require interaction) Also auto-detected when stdin is not a terminal or CI=true is set.