From bc1cd64c7825b35053c64c02a1a32ba84ee2cd8d Mon Sep 17 00:00:00 2001 From: Julian Knutsen Date: Tue, 20 Oct 2026 07:25:38 +0000 Subject: [PATCH 1/2] fix(cli): refuse graph workspaces marked by graph-preview-format (#7722) The graph-mode fence decides a workspace's format from graph_mode in its metadata alone. Graph-preview builds also write a .beads/graph-preview-format marker before metadata.json (donnabox fork commit deea8d57df, Donna Box), so that an interrupted or metadata-lost graph workspace stays fenced. bd ignored the marker. When a bd that predates graph_mode had rewritten metadata.json without the field, bd opened the graph database by its recorded name and `bd list` ran Issue schema initialization against it. When metadata.json was never written or was lost, bd fell back to the default database name and created an Issue database inside the graph workspace, and `bd init` initialized an Issue workspace there. checkWorkspaceFormat now also refuses a beadsDir that holds anything at graph-preview-format, whatever its content and whatever the metadata says (absent, stripped, or an explicit "dependency"). The graph_mode check still runs first, so a normal graph workspace is still reported by its graph_mode. The refusal is the same typed error with its own message and a hint to restore metadata.json, so every call site, the --json rendering and exit code 16 (ExitUnsupportedWorkspaceFormat) are unchanged. An empty beadsDir never probes the working directory. loadAndCheckWorkspaceFormat reads the metadata with LoadForDiscovery and refuses metadata that cannot be parsed beside the marker as the marker's format: the marker alone declares it. Command admission (guardLegacyUpgradeWorkspaceForInit) uses it, and checkDiscoveredWorkspaceFormat now delegates to it, so the paths that check before a migrating configfile.Load (the four store factories, create --repo's ensureBeadsDirForPath and dry-run target open, the bd dolt loaders, bootstrap's undiscovered walk) refuse a marked workspace too, with or without readable metadata. Other metadata load failures are still left to the caller's own load, so a malformed legacy config.json without the marker keeps create --repo's auto-initialization. bootstrap's ancestor walk (findParentConfig) refuses an ancestor that holds the marker without metadata it can read, as it refuses one whose metadata declares graph_mode. It used to skip a marker-only ancestor and take a more distant workspace's metadata or the defaults, and to report a marked ancestor with unparseable metadata as a load failure (exit 1). With the check in checkWorkspaceFormat, bootstrap in a .beads holding only the marker refuses it (exit 16) instead of reporting no workspace. validateConfiguredBackend returns early for nil metadata, so its backstop covers the marker only when metadata was loaded; every caller runs admission or checkDiscoveredWorkspaceFormat on the same beadsDir first, and its comment now says so. Tests: guard unit tests for marker-only, metadata lost, stripped (metadata.json and legacy config.json), server, explicit dependency, unparseable metadata, marker over a legacy Dolt root, and arbitrary marker content; the four store factories (cgo, and the CGO_ENABLED=0 copies goreleaser ships) with stripped, missing and, for cgo, unparseable metadata beside the marker; findParentConfig with a marked ancestor below an ordinary workspace; the exit-code mapping; ensureBeadsDirForPath with a malformed config.json with and without the marker; and the subprocess e2e matrices (in-workspace commands, plain `bd init`, and the outside entry points: create --repo, create --dry-run, --db, BEADS_DB, init --proxied-server, bootstrap below it) extended with four marker fixtures that must exit 16 with the marker refusal and leave .beads byte-identical, while store-less commands still run. The e2e subprocess timeout goes from 10s to 20s: refused runs finish in well under a second, but an unrefused one creates or opens a database and can approach 10s under load, so without the fence the rows fail on their assertion rather than on the timeout. Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-authored-by: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 15 ++ cmd/bd/backend_support.go | 6 +- cmd/bd/bootstrap.go | 6 + cmd/bd/create.go | 6 +- cmd/bd/graph_mode_admission_e2e_test.go | 161 ++++++++++++------ cmd/bd/legacy_upgrade_guard.go | 7 +- cmd/bd/store_factory_nocgo_test.go | 60 +++++-- cmd/bd/workspace_format_guard.go | 86 ++++++++-- cmd/bd/workspace_format_guard_test.go | 215 +++++++++++++++++++++++- 9 files changed, 469 insertions(+), 93 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a54cb677a..0a0ba3976 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -868,6 +868,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 A `metadata.json` rewrite keeps `graph_mode` and the `graph_*` fields graph-preview builds write, and like those builds it omits a zero `graph_schema_version` and a false `graph_ready`. +- **A graph workspace without `graph_mode` in its metadata is refused too.** + Graph-preview builds write a `.beads/graph-preview-format` marker before + `metadata.json`. bd ignored it. When an older bd had rewritten + `metadata.json` without `graph_mode`, bd opened the graph database by its + recorded name and ran Issue schema initialization against it; when + `metadata.json` was never written or was lost, bd fell back to the default + database name and created an Issue database inside the graph workspace, and + `bd init` initialized an Issue workspace there. A `.beads` holding that + marker, whatever it contains and whatever its metadata says (absent, + stripped, unparseable or an explicit `dependency`), is now refused wherever + a `graph_mode` workspace is: commands run in it or naming it with `--db` or + `BEADS_DB`, `bd create --repo` aimed at it, and `bd bootstrap` in a + workspace below it that would take its metadata exit with code 16 and a + hint to restore `metadata.json`, and routed and cross-repository opens fail + without opening its database. - **`bd setup claude --remove` no longer leaves a blank-line hole.** Removing the beads section from `CLAUDE.md` (or, with the other setup recipes, from `AGENTS.md` or `GEMINI.md`) left the blank lines around it behind, three in diff --git a/cmd/bd/backend_support.go b/cmd/bd/backend_support.go index 60d256cd1..a0fb89e99 100644 --- a/cmd/bd/backend_support.go +++ b/cmd/bd/backend_support.go @@ -17,7 +17,11 @@ import ( // open (checkWorkspaceFormat). Command admission refuses those first, and the // store factories check before their migrating configfile.Load // (checkDiscoveredWorkspaceFormat), so here it backs up any other caller that -// validates metadata it loaded itself. +// validates metadata it loaded itself. It returns early for a nil cfg, so that +// backstop covers the graph format marker only when metadata was loaded; a +// caller that may have none must check beadsDir with +// checkDiscoveredWorkspaceFormat or command admission first, as every caller +// does today. func validateConfiguredBackend(cfg *configfile.Config, beadsDir string) error { if cfg == nil { return nil diff --git a/cmd/bd/bootstrap.go b/cmd/bd/bootstrap.go index b7c28aded..8d07611cf 100644 --- a/cmd/bd/bootstrap.go +++ b/cmd/bd/bootstrap.go @@ -1594,6 +1594,9 @@ func isNonInteractiveBootstrap(flagValue bool) bool { // parent workspace does. Returns nil if no parent config is found. A malformed // or unreadable ancestor metadata file is authoritative and returned as an error; // bootstrap must not skip it and select a more distant workspace or defaults. +// An ancestor holding the graph format marker without metadata it can read is +// a graph workspace, refused like one whose metadata declares graph_mode, +// rather than skipped or reported as a metadata load failure. func findParentConfig(beadsDir string) (*configfile.Config, error) { // Start from the parent of beadsDir's enclosing directory. // beadsDir is typically "/.beads", so we start from 's parent. @@ -1611,6 +1614,9 @@ func findParentConfig(beadsDir string) (*configfile.Config, error) { for dir, ok := walk.Next(); ok; dir, ok = walk.Next() { candidate := filepath.Join(dir, ".beads") cfg, err := configfile.LoadForDiscovery(candidate) + if (err != nil || cfg == nil) && hasGraphFormatMarker(candidate) { + return nil, &unsupportedWorkspaceFormatError{beadsDir: candidate, formatMarker: true} + } if err != nil { return nil, fmt.Errorf("%s: %w", configfile.ConfigPath(candidate), err) } diff --git a/cmd/bd/create.go b/cmd/bd/create.go index c54ce7fb8..d3df37f1b 100644 --- a/cmd/bd/create.go +++ b/cmd/bd/create.go @@ -1085,9 +1085,9 @@ func ensureBeadsDirForPath(ctx context.Context, targetPath string, sourceStore s metadataPath := filepath.Join(beadsDir, "metadata.json") // A target in a format this build cannot open is refused before anything - // below: one marked only by a legacy config.json has no metadata.json, so - // it would otherwise be initialized here and lose its marker to the - // metadata.json written beside it. + // below: one marked only by a legacy config.json or by the graph format + // marker file has no metadata.json, so it would otherwise be initialized + // here, with an Issue database and a metadata.json written beside it. if err := checkDiscoveredWorkspaceFormat(beadsDir); err != nil { return err } diff --git a/cmd/bd/graph_mode_admission_e2e_test.go b/cmd/bd/graph_mode_admission_e2e_test.go index c0c91187c..6270c25c7 100644 --- a/cmd/bd/graph_mode_admission_e2e_test.go +++ b/cmd/bd/graph_mode_admission_e2e_test.go @@ -14,29 +14,43 @@ import ( "time" ) -// graphModeAdmissionFixture is a workspace whose metadata declares a -// graph_mode this build does not open. +// graphModeAdmissionFixture is a workspace whose metadata or format marker +// declares a format this build does not open. type graphModeAdmissionFixture struct { - name string + name string + // filename is the metadata file; "" lays down no metadata. filename string - mode string metadata string - // embedded adds what a real graph workspace holds beside its metadata: - // the embedded Dolt root of its graph database and the format sentinel - // graph-preview builds write. Without the guard, an ordinary bd opens - // that database as an Issue store and migrates it. + // embedded adds the embedded Dolt root of a graph database. Without the + // guard, an ordinary bd opens that database as an Issue store and + // migrates it. embedded bool + // marker adds the graph-preview-format sentinel graph-preview builds + // write before metadata.json. + marker bool + // refusal lists what the refusal must mention besides "this bd build + // does not support": the declared format and the start of its hint. + refusal []string } -// write lays the fixture down under beadsDir and returns the metadata path. +// write lays the fixture down under beadsDir and returns the metadata path, +// or "" when the fixture has no metadata. func (f graphModeAdmissionFixture) write(t *testing.T, beadsDir string) string { t.Helper() - path := filepath.Join(beadsDir, f.filename) - writeFile(t, path, []byte(f.metadata)) + if err := os.MkdirAll(beadsDir, 0o700); err != nil { + t.Fatal(err) + } + path := "" + if f.filename != "" { + path = filepath.Join(beadsDir, f.filename) + writeFile(t, path, []byte(f.metadata)) + } if f.embedded { if err := os.MkdirAll(filepath.Join(beadsDir, "embeddeddolt", "beads_graph_0123456789abcdef0123456789abcdef", ".dolt"), 0o700); err != nil { t.Fatal(err) } + } + if f.marker { writeFile(t, filepath.Join(beadsDir, "graph-preview-format"), []byte("link-preview-v9\n")) } if err := os.Chmod(beadsDir, 0o700); err != nil { @@ -46,19 +60,48 @@ func (f graphModeAdmissionFixture) write(t *testing.T, beadsDir string) string { } func graphModeAdmissionFixtures() []graphModeAdmissionFixture { + graphModeRefusal := func(mode string) []string { + return []string{"graph_mode", mode, "use a bd build that supports graph_mode"} + } var fixtures []graphModeAdmissionFixture fixtures = append(fixtures, graphModeAdmissionFixture{ - name: "metadata.json/link/embedded", filename: "metadata.json", mode: "link", - metadata: graphLinkWorkspaceMetadata, embedded: true, + name: "metadata.json/link/embedded", filename: "metadata.json", + metadata: graphLinkWorkspaceMetadata, embedded: true, marker: true, + refusal: graphModeRefusal("link"), }) for _, filename := range []string{"metadata.json", "config.json"} { for _, mode := range []string{"link", "future-format"} { fixtures = append(fixtures, graphModeAdmissionFixture{ - name: filename + "/" + mode + "/server", filename: filename, mode: mode, + name: filename + "/" + mode + "/server", filename: filename, metadata: `{"backend":"dolt","dolt_mode":"server","graph_mode":"` + mode + `"}`, + refusal: graphModeRefusal(mode), }) } } + // Only the format marker declares these: graph init stopped before + // metadata.json, metadata.json was lost, or a bd that predates + // graph_mode rewrote it without the field. + markerRefusal := []string{"graph-preview-format", "restore metadata.json"} + fixtures = append(fixtures, + graphModeAdmissionFixture{ + name: "marker/only", marker: true, + refusal: markerRefusal, + }, + graphModeAdmissionFixture{ + name: "marker/metadata-lost/embedded", embedded: true, marker: true, + refusal: markerRefusal, + }, + graphModeAdmissionFixture{ + name: "marker/metadata-stripped/embedded", filename: "metadata.json", + metadata: graphStrippedWorkspaceMetadata, embedded: true, marker: true, + refusal: markerRefusal, + }, + graphModeAdmissionFixture{ + name: "marker/dependency/server", filename: "metadata.json", + metadata: `{"backend":"dolt","dolt_mode":"server","graph_mode":"dependency"}`, marker: true, + refusal: markerRefusal, + }, + ) return fixtures } @@ -73,7 +116,11 @@ func runGraphModeAdmissionBD(t *testing.T, bd, repoDir string, args ...string) ( // added to bd's environment. func runGraphModeAdmissionBDEnv(t *testing.T, bd, dir string, env []string, args ...string) (string, int) { t.Helper() - ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + // A refused run takes well under a second. An unrefused one (what these + // tests catch) goes on to create or open a database, which under load + // can approach 10s; the bound leaves room for it to fail on the + // assertion that names the regression rather than on the timeout. + ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second) defer cancel() cmd := exec.CommandContext(ctx, bd, args...) cmd.Dir = dir @@ -111,7 +158,7 @@ func requireGraphModeRefusal(t *testing.T, fixture graphModeAdmissionFixture, ar } // --json renders the refusal as a JSON error, which escapes the quotes // around the mode, so match its parts. - for _, want := range []string{"graph_mode", fixture.mode, "this bd build does not support", "use a bd build that supports graph_mode"} { + for _, want := range append([]string{"this bd build does not support"}, fixture.refusal...) { if !strings.Contains(output, want) { t.Fatalf("bd %s refusal does not mention %q:\n%s", strings.Join(args, " "), want, output) } @@ -131,13 +178,18 @@ func TestGraphModeCLIRefusesLegacyStoreWithoutWorkspaceEffects(t *testing.T) { {"dolt", "start"}, {"doctor", "--json"}, {"bootstrap", "--dry-run", "--yes"}, + {"init", "--quiet", "--non-interactive", "--skip-hooks", "--skip-agents"}, {"init", "--force", "--quiet", "--non-interactive", "--skip-hooks", "--skip-agents"}, // What the installed git hooks run; their shim passes exit 16 on. {"hooks", "run", "pre-commit"}, } for _, fixture := range graphModeAdmissionFixtures() { for _, args := range commands { - t.Run(fixture.name+"/"+args[0], func(t *testing.T) { + name := args[0] + if name == "init" && args[1] == "--force" { + name = "init-force" + } + t.Run(fixture.name+"/"+name, func(t *testing.T) { repoDir := t.TempDir() initGitRepoAt(t, repoDir) beadsDir := filepath.Join(repoDir, ".beads") @@ -149,8 +201,10 @@ func TestGraphModeCLIRefusesLegacyStoreWithoutWorkspaceEffects(t *testing.T) { if after := legacyUpgradeTreeDigest(t, beadsDir); after != before { t.Fatalf("refused bd %s changed the workspace\n%s", strings.Join(args, " "), output) } - if got, err := os.ReadFile(metadataPath); err != nil || string(got) != fixture.metadata { - t.Fatalf("refused bd %s rewrote %s: %q, %v", strings.Join(args, " "), fixture.filename, got, err) + if metadataPath != "" { + if got, err := os.ReadFile(metadataPath); err != nil || string(got) != fixture.metadata { + t.Fatalf("refused bd %s rewrote %s: %q, %v", strings.Join(args, " "), fixture.filename, got, err) + } } }) } @@ -160,7 +214,8 @@ func TestGraphModeCLIRefusesLegacyStoreWithoutWorkspaceEffects(t *testing.T) { // Commands also reach a workspace they do not run in: create --repo, from // another workspace or from none and as a dry run, --db and BEADS_DB, // init --proxied-server, and bootstrap in a workspace with no metadata of its -// own, which takes the nearest ancestor's. Each must refuse a graph workspace +// own, which takes the nearest ancestor's (and refuses a graph ancestor even +// when only its format marker declares it, rather than skip past it). Each must refuse a graph workspace // the same way, before resolving it migrates a legacy config.json or anything // opens its store. func TestGraphModeOutsideEntryPointsRefuseWithoutWorkspaceEffects(t *testing.T) { @@ -216,10 +271,12 @@ func TestGraphModeOutsideEntryPointsRefuseWithoutWorkspaceEffects(t *testing.T) output, code := runGraphModeAdmissionBDEnv(t, bd, dir, env, args...) requireGraphModeRefusal(t, fixture, args, output, code) if after := legacyUpgradeTreeDigest(t, beadsDir); after != before { - t.Fatalf("refused bd %s changed the workspace\n%s", strings.Join(args, " "), output) + t.Fatalf("bd %s changed the graph workspace\n%s", strings.Join(args, " "), output) } - if got, err := os.ReadFile(metadataPath); err != nil || string(got) != fixture.metadata { - t.Fatalf("refused bd %s rewrote %s: %q, %v", strings.Join(args, " "), fixture.filename, got, err) + if metadataPath != "" { + if got, err := os.ReadFile(metadataPath); err != nil || string(got) != fixture.metadata { + t.Fatalf("refused bd %s rewrote %s: %q, %v", strings.Join(args, " "), fixture.filename, got, err) + } } }) } @@ -230,30 +287,40 @@ func TestGraphModeOutsideEntryPointsRefuseWithoutWorkspaceEffects(t *testing.T) // refuses, and leave it untouched. func TestGraphModeWorkspaceAdmitsStorelessCommands(t *testing.T) { bd := buildBDUnderTest(t) - fixture := graphModeAdmissionFixtures()[0] - for _, args := range [][]string{ - {"version"}, - {"--version"}, - {"help"}, - {"completion", "bash"}, - } { - t.Run(strings.Join(args, " "), func(t *testing.T) { - repoDir := t.TempDir() - initGitRepoAt(t, repoDir) - beadsDir := filepath.Join(repoDir, ".beads") - fixture.write(t, beadsDir) - before := legacyUpgradeTreeDigest(t, beadsDir) + var fixtures []graphModeAdmissionFixture + for _, fixture := range graphModeAdmissionFixtures() { + if fixture.name == "metadata.json/link/embedded" || fixture.name == "marker/only" { + fixtures = append(fixtures, fixture) + } + } + if len(fixtures) != 2 { + t.Fatalf("store-less fixtures = %d, want 2", len(fixtures)) + } + for _, fixture := range fixtures { + for _, args := range [][]string{ + {"version"}, + {"--version"}, + {"help"}, + {"completion", "bash"}, + } { + t.Run(fixture.name+"/"+strings.Join(args, " "), func(t *testing.T) { + repoDir := t.TempDir() + initGitRepoAt(t, repoDir) + beadsDir := filepath.Join(repoDir, ".beads") + fixture.write(t, beadsDir) + before := legacyUpgradeTreeDigest(t, beadsDir) - output, code := runGraphModeAdmissionBD(t, bd, repoDir, args...) - if code != 0 { - t.Fatalf("bd %s exit = %d, want 0\n%s", strings.Join(args, " "), code, output) - } - if strings.Contains(output, "graph_mode") { - t.Fatalf("store-less bd %s reported the workspace format:\n%s", strings.Join(args, " "), output) - } - if after := legacyUpgradeTreeDigest(t, beadsDir); after != before { - t.Fatalf("bd %s changed the workspace", strings.Join(args, " ")) - } - }) + output, code := runGraphModeAdmissionBD(t, bd, repoDir, args...) + if code != 0 { + t.Fatalf("bd %s exit = %d, want 0\n%s", strings.Join(args, " "), code, output) + } + if strings.Contains(output, "this bd build does not support") { + t.Fatalf("store-less bd %s reported the workspace format:\n%s", strings.Join(args, " "), output) + } + if after := legacyUpgradeTreeDigest(t, beadsDir); after != before { + t.Fatalf("bd %s changed the workspace", strings.Join(args, " ")) + } + }) + } } } diff --git a/cmd/bd/legacy_upgrade_guard.go b/cmd/bd/legacy_upgrade_guard.go index bbaf45f08..db1570cb0 100644 --- a/cmd/bd/legacy_upgrade_guard.go +++ b/cmd/bd/legacy_upgrade_guard.go @@ -42,14 +42,11 @@ func guardLegacyUpgradeWorkspaceForInit(beadsDir string, initSelectsServer bool) if beadsDir == "" { return nil } - cfg, err := configfile.LoadForDiscovery(beadsDir) - if err != nil { - return fmt.Errorf("loading config: %w", err) - } // This guard admits only the ordinary Issue store. A workspace in another // format is refused before any legacy classification, which could // otherwise admit it, or report it as a legacy store to migrate. - if err := checkWorkspaceFormat(cfg, beadsDir); err != nil { + cfg, err := loadAndCheckWorkspaceFormat(beadsDir) + if err != nil { return err } if isHistoricalSQLiteWorkspace(beadsDir, cfg) { diff --git a/cmd/bd/store_factory_nocgo_test.go b/cmd/bd/store_factory_nocgo_test.go index acf430c12..52dc49e89 100644 --- a/cmd/bd/store_factory_nocgo_test.go +++ b/cmd/bd/store_factory_nocgo_test.go @@ -205,25 +205,54 @@ func TestNocgoFactoriesHonorSharedServer(t *testing.T) { // .goreleaser.yml ships open routed, cross-repository and create --repo // targets through their own copies of these factories, so each must refuse a // graph workspace before its configfile.Load, which would otherwise migrate -// one marked only by a legacy config.json into metadata.json first. It runs in -// CI only because bazel.yml's PURE_CMD_BD_TESTS allowlists it by name. +// one marked only by a legacy config.json into metadata.json first, and one +// declared only by the graph-preview-format marker, whose metadata is lost or +// stripped. It runs in CI only because bazel.yml's PURE_CMD_BD_TESTS +// allowlists it by name. func TestNocgoStoreFactoriesRefuseGraphWorkspace(t *testing.T) { isolateSharedServerSignals(t) pinLegacyUpgradeGuardEnv(t) - const metadata = `{"backend":"dolt","graph_mode":"link"}` + const graphMetadata = `{"backend":"dolt","graph_mode":"link"}` + // What a bd that predates graph_mode leaves of a graph workspace's + // metadata: the database name still selects the graph database. + const strippedMetadata = `{"backend":"dolt","dolt_mode":"server","dolt_database":"beads_graph_0123456789abcdef0123456789abcdef"}` factories := map[string]func(context.Context, string) (storage.DoltStorage, error){ "read-write": newDoltStoreFromConfig, "routed": newExistingDoltStoreFromConfig, "read-only": newReadOnlyStoreFromConfig, "preview": newPreviewStoreFromConfig, } - for _, filename := range []string{"metadata.json", "config.json"} { + layouts := []struct { + name string + // filename is the metadata file; "" lays down no metadata. + filename string + metadata string + // marker adds the graph-preview-format sentinel. + marker bool + }{ + {name: "metadata.json", filename: "metadata.json", metadata: graphMetadata}, + {name: "config.json", filename: "config.json", metadata: graphMetadata}, + {name: "marker only", marker: true}, + {name: "marker, metadata stripped", filename: "metadata.json", metadata: strippedMetadata, marker: true}, + } + for _, layout := range layouts { for name, open := range factories { - t.Run(filename+"/"+name, func(t *testing.T) { + t.Run(layout.name+"/"+name, func(t *testing.T) { beadsDir := t.TempDir() - path := filepath.Join(beadsDir, filename) - if err := os.WriteFile(path, []byte(metadata), 0o600); err != nil { - t.Fatal(err) + want := map[string]bool{} + path := "" + if layout.filename != "" { + path = filepath.Join(beadsDir, layout.filename) + if err := os.WriteFile(path, []byte(layout.metadata), 0o600); err != nil { + t.Fatal(err) + } + want[layout.filename] = true + } + if layout.marker { + if err := os.WriteFile(filepath.Join(beadsDir, "graph-preview-format"), []byte("link-preview-v9\n"), 0o600); err != nil { + t.Fatal(err) + } + want["graph-preview-format"] = true } store, err := open(t.Context(), beadsDir) if err == nil { @@ -232,12 +261,19 @@ func TestNocgoStoreFactoriesRefuseGraphWorkspace(t *testing.T) { if !isUnsupportedWorkspaceFormat(err) { t.Fatalf("%s open = %v, want unsupported workspace format refusal", name, err) } - if got, readErr := os.ReadFile(path); readErr != nil || string(got) != metadata { - t.Fatalf("%s open rewrote %s: %q, %v", name, filename, got, readErr) + if path != "" { + if got, readErr := os.ReadFile(path); readErr != nil || string(got) != layout.metadata { + t.Fatalf("%s open rewrote %s: %q, %v", name, layout.filename, got, readErr) + } } entries, readErr := os.ReadDir(beadsDir) - if readErr != nil || len(entries) != 1 { - t.Fatalf("%s open left %d entries in the workspace, want only %s (%v)", name, len(entries), filename, readErr) + if readErr != nil || len(entries) != len(want) { + t.Fatalf("%s open left %d entries in the workspace, want %d (%v)", name, len(entries), len(want), readErr) + } + for _, entry := range entries { + if !want[entry.Name()] { + t.Fatalf("%s open created %s in the workspace", name, entry.Name()) + } } }) } diff --git a/cmd/bd/workspace_format_guard.go b/cmd/bd/workspace_format_guard.go index 4e9daa0a4..1ae6c3995 100644 --- a/cmd/bd/workspace_format_guard.go +++ b/cmd/bd/workspace_format_guard.go @@ -3,13 +3,16 @@ package main import ( "errors" "fmt" + "os" + "path/filepath" "github.com/steveyegge/beads/internal/configfile" ) // ExitUnsupportedWorkspaceFormat is the exit code for a command refused // because its workspace declares a format this bd build cannot open: a -// metadata.json graph_mode other than "dependency". Stable so a wrapper can +// metadata.json graph_mode other than "dependency", or a graph workspace +// format marker (graphFormatMarkerFile). Stable so a wrapper can // tell "this workspace needs a different bd build" apart from a generic // failure (1) without grepping stderr. // @@ -18,35 +21,86 @@ import ( // §E3, which freezes 10/11/12/130. const ExitUnsupportedWorkspaceFormat = 16 -// unsupportedWorkspaceFormatError refuses a workspace whose metadata declares -// a data model other than the Issue store this build opens. Graph-preview -// builds persist graph_mode "link" plus graph_* binding fields beside an -// ordinary Dolt backend, so nothing else in the metadata tells this build -// that the database behind it is not an Issue store; opening it as one would -// run Issue migrations into it. +// graphFormatMarkerFile is the format sentinel graph-preview builds write in +// .beads before metadata.json, so that a graph workspace whose metadata was +// never written, was lost, or was rewritten without graph_mode by a bd that +// does not know the field still declares its format. +const graphFormatMarkerFile = "graph-preview-format" + +// unsupportedWorkspaceFormatError refuses a workspace whose metadata or format +// marker declares a data model other than the Issue store this build opens. +// Graph-preview builds persist graph_mode "link" plus graph_* binding fields +// beside an ordinary Dolt backend, and the graphFormatMarkerFile beside them, +// so nothing else tells this build that the database behind it is not an +// Issue store; opening it as one would run Issue migrations into it. type unsupportedWorkspaceFormatError struct { beadsDir string graphMode string + // formatMarker reports that graphFormatMarkerFile, not graph_mode, + // declared the format. + formatMarker bool } func (e *unsupportedWorkspaceFormatError) Error() string { + if e.formatMarker { + return fmt.Sprintf("workspace %s has a %s marker, which this bd build does not support; %s", + e.beadsDir, graphFormatMarkerFile, configfile.BackendNotOpenedGuarantee) + } return fmt.Sprintf("workspace %s uses format graph_mode %q, which this bd build does not support; %s", e.beadsDir, e.graphMode, configfile.BackendNotOpenedGuarantee) } func (e *unsupportedWorkspaceFormatError) hint() string { + if e.formatMarker { + return fmt.Sprintf("restore metadata.json (graph_mode and the graph_* fields) from version control or a backup, then use a bd build that supports graph workspaces; do not remove .beads/%s", graphFormatMarkerFile) + } return fmt.Sprintf("use a bd build that supports graph_mode %q workspaces; leave graph_mode and the graph_* fields in metadata.json unchanged", e.graphMode) } // checkWorkspaceFormat refuses metadata whose graph_mode marker names any // model but the default. An unknown marker is refused too: it may describe a // format newer than this build, so it must never fall back to the Issue store. -// cfg may be nil (no metadata), which is an ordinary workspace. +// It also refuses a beadsDir holding the graph format marker file, whatever +// the metadata says and whatever the file holds. cfg may be nil (no metadata); +// beadsDir may be "" (no workspace directory, so no marker to find). func checkWorkspaceFormat(cfg *configfile.Config, beadsDir string) error { - if mode, err := cfg.GetGraphMode(); err == nil && mode == configfile.GraphModeDependency { - return nil + if mode, err := cfg.GetGraphMode(); err != nil || mode != configfile.GraphModeDependency { + return &unsupportedWorkspaceFormatError{beadsDir: beadsDir, graphMode: cfg.GraphMode} } - return &unsupportedWorkspaceFormatError{beadsDir: beadsDir, graphMode: cfg.GraphMode} + if hasGraphFormatMarker(beadsDir) { + return &unsupportedWorkspaceFormatError{beadsDir: beadsDir, formatMarker: true} + } + return nil +} + +// loadAndCheckWorkspaceFormat reads beadsDir's discovery metadata without +// migrating it and refuses a workspace in a format this build cannot open +// (checkWorkspaceFormat). cfg is nil when beadsDir has no metadata. Metadata +// that cannot be read beside the graph format marker is refused as that +// format too: the marker alone declares it. +func loadAndCheckWorkspaceFormat(beadsDir string) (*configfile.Config, error) { + cfg, err := configfile.LoadForDiscovery(beadsDir) + if err != nil { + if hasGraphFormatMarker(beadsDir) { + return nil, &unsupportedWorkspaceFormatError{beadsDir: beadsDir, formatMarker: true} + } + return nil, fmt.Errorf("loading config: %w", err) + } + if err := checkWorkspaceFormat(cfg, beadsDir); err != nil { + return nil, err + } + return cfg, nil +} + +// hasGraphFormatMarker reports whether anything exists at beadsDir's graph +// format marker path. Callers read beadsDir's metadata first, so a directory +// bd cannot search has already failed there. +func hasGraphFormatMarker(beadsDir string) bool { + if beadsDir == "" { + return false + } + _, err := os.Lstat(filepath.Join(beadsDir, graphFormatMarkerFile)) + return err == nil } // checkDiscoveredWorkspaceFormat runs checkWorkspaceFormat on beadsDir's @@ -54,13 +108,13 @@ func checkWorkspaceFormat(cfg *configfile.Config, beadsDir string) error { // A path that opens or initializes a workspace without passing through command // admission runs it first: configfile.Load would otherwise migrate a legacy // config.json into metadata.json before the format check could refuse it. -// Metadata that does not load is left to the caller's own load to report. +// Metadata that does not load is left to the caller's own load to report, +// unless the graph format marker sits beside it (loadAndCheckWorkspaceFormat). func checkDiscoveredWorkspaceFormat(beadsDir string) error { - cfg, err := configfile.LoadForDiscovery(beadsDir) - if err != nil { - return nil + if _, err := loadAndCheckWorkspaceFormat(beadsDir); isUnsupportedWorkspaceFormat(err) { + return err } - return checkWorkspaceFormat(cfg, beadsDir) + return nil } func isUnsupportedWorkspaceFormat(err error) bool { diff --git a/cmd/bd/workspace_format_guard_test.go b/cmd/bd/workspace_format_guard_test.go index a0609ed82..d66f03f29 100644 --- a/cmd/bd/workspace_format_guard_test.go +++ b/cmd/bd/workspace_format_guard_test.go @@ -6,6 +6,7 @@ import ( "context" "os" "path/filepath" + "strconv" "strings" "testing" @@ -29,11 +30,26 @@ const graphLinkWorkspaceMetadata = `{ "project_id": "0123456789abcdef0123456789abcdef" }` +// graphStrippedWorkspaceMetadata is graphLinkWorkspaceMetadata as a bd that +// predates graph_mode leaves it after any Save: the graph_* keys are gone, and +// the database name still selects the graph database. +const graphStrippedWorkspaceMetadata = `{ + "database": "", + "backend": "dolt", + "dolt_mode": "embedded", + "dolt_database": "beads_graph_0123456789abcdef0123456789abcdef", + "project_id": "0123456789abcdef0123456789abcdef" +}` + // graphWorkspaceLayout is a .beads directory whose metadata declares a // graph_mode, plus whatever else the case lays down beside it. type graphWorkspaceLayout struct { + // filename is the metadata file; "" lays down no metadata. filename string metadata string + // marker adds the graph-preview-format sentinel graph-preview builds + // write before metadata.json. + marker bool // embedded adds the embedded Dolt root a graph database lives in. embedded bool // doltRoot adds a .beads/dolt root without a version witness, which @@ -44,11 +60,18 @@ type graphWorkspaceLayout struct { sqlite bool } -// write lays the layout down under beadsDir and returns the metadata path. +// write lays the layout down under beadsDir and returns the metadata path, or +// "" when the layout has no metadata. func (l graphWorkspaceLayout) write(t *testing.T, beadsDir string) string { t.Helper() - path := filepath.Join(beadsDir, l.filename) - writeFile(t, path, []byte(l.metadata)) + path := "" + if l.filename != "" { + path = filepath.Join(beadsDir, l.filename) + writeFile(t, path, []byte(l.metadata)) + } + if l.marker { + writeFile(t, filepath.Join(beadsDir, "graph-preview-format"), []byte("link-preview-v9\n")) + } if l.embedded { if err := os.MkdirAll(filepath.Join(beadsDir, "embeddeddolt", "beads_graph_0123456789abcdef0123456789abcdef", ".dolt"), 0o700); err != nil { t.Fatal(err) @@ -116,6 +139,114 @@ func TestWorkspaceFormatGuardRefusesGraphWorkspaces(t *testing.T) { } } +// A graph workspace whose metadata does not declare graph_mode is still +// refused by its format marker: graph-preview builds write the marker before +// metadata.json, and a bd that predates graph_mode drops the field on Save. +func TestWorkspaceFormatGuardRefusesFormatMarker(t *testing.T) { + pinLegacyUpgradeGuardEnv(t) + tests := []struct { + name string + layout graphWorkspaceLayout + }{ + // Graph init interrupted after the marker, before metadata.json. + {name: "marker only", layout: graphWorkspaceLayout{marker: true}}, + {name: "metadata lost", layout: graphWorkspaceLayout{marker: true, embedded: true}}, + {name: "metadata stripped", layout: graphWorkspaceLayout{filename: "metadata.json", metadata: graphStrippedWorkspaceMetadata, marker: true, embedded: true}}, + {name: "legacy config.json stripped", layout: graphWorkspaceLayout{filename: "config.json", metadata: graphStrippedWorkspaceMetadata, marker: true, embedded: true}}, + {name: "server metadata stripped", layout: graphWorkspaceLayout{filename: "metadata.json", metadata: `{"backend":"dolt","dolt_mode":"server"}`, marker: true}}, + {name: "explicit dependency", layout: graphWorkspaceLayout{filename: "metadata.json", metadata: `{"backend":"dolt","graph_mode":"dependency"}`, marker: true, embedded: true}}, + // Metadata that does not parse (a conflicted merge, a truncated + // write) cannot outrank the marker. + {name: "unparseable metadata", layout: graphWorkspaceLayout{filename: "metadata.json", metadata: `{"backend":"dolt",`, marker: true, embedded: true}}, + // Without the format check first, this is reported as a legacy + // Dolt workspace to migrate. + {name: "marker over legacy dolt root", layout: graphWorkspaceLayout{marker: true, doltRoot: true}}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + beadsDir := t.TempDir() + path := tt.layout.write(t, beadsDir) + before := legacyUpgradeTreeDigest(t, beadsDir) + + err := guardLegacyUpgradeWorkspace(beadsDir) + if !isUnsupportedWorkspaceFormat(err) { + t.Fatalf("guardLegacyUpgradeWorkspace() = %v, want unsupported workspace format refusal", err) + } + for _, want := range []string{beadsDir, "graph-preview-format", "this bd build does not support", "no storage database was opened or modified"} { + if !strings.Contains(err.Error(), want) { + t.Fatalf("refusal %q does not mention %q", err, want) + } + } + if after := legacyUpgradeTreeDigest(t, beadsDir); after != before { + t.Fatalf("guard changed the workspace") + } + if path != "" { + if got, readErr := os.ReadFile(path); readErr != nil || string(got) != tt.layout.metadata { + t.Fatalf("guard rewrote %s: %q, %v", tt.layout.filename, got, readErr) + } + } + }) + } + // The marker's presence is the signal, not its content. + for _, content := range []string{"", "link-preview-v5\n", "not a generation"} { + t.Run("content "+strconv.Quote(content), func(t *testing.T) { + beadsDir := t.TempDir() + writeFile(t, filepath.Join(beadsDir, "graph-preview-format"), []byte(content)) + if err := guardLegacyUpgradeWorkspace(beadsDir); !isUnsupportedWorkspaceFormat(err) { + t.Fatalf("guardLegacyUpgradeWorkspace() = %v, want unsupported workspace format refusal", err) + } + }) + } +} + +// With no workspace directory there is no marker to look for: an empty +// beadsDir must not probe the working directory. +func TestWorkspaceFormatCheckWithoutWorkspaceDirectory(t *testing.T) { + t.Chdir(t.TempDir()) + writeFile(t, "graph-preview-format", []byte("link-preview-v9\n")) + if err := checkWorkspaceFormat(nil, ""); err != nil { + t.Fatalf("checkWorkspaceFormat(nil, \"\") = %v, want nil", err) + } + if err := validateConfiguredBackend(&configfile.Config{Backend: configfile.BackendDolt}, ""); err != nil { + t.Fatalf("validateConfiguredBackend(dolt, \"\") = %v, want nil", err) + } +} + +// Bootstrap in a workspace with no metadata of its own takes its nearest +// ancestor's. An ancestor declared a graph workspace only by its format marker +// is refused like one declaring graph_mode: neither skipped for a more distant +// workspace or the defaults, nor reported as a metadata load failure. +func TestFindParentConfigRefusesMarkedAncestor(t *testing.T) { + pinLegacyUpgradeGuardEnv(t) + for name, layout := range map[string]graphWorkspaceLayout{ + "marker only": {marker: true}, + "marker, metadata unparseable": {filename: "metadata.json", metadata: `{"backend":`, marker: true, embedded: true}, + "marker, metadata stripped": {filename: "metadata.json", metadata: graphStrippedWorkspaceMetadata, marker: true, embedded: true}, + } { + t.Run(name, func(t *testing.T) { + outer := t.TempDir() + // An ordinary workspace further up must not be selected instead. + writeFile(t, filepath.Join(outer, ".beads", "metadata.json"), []byte(`{"backend":"dolt","dolt_database":"outer"}`)) + graphDir := filepath.Join(outer, "graph") + graphBeadsDir := filepath.Join(graphDir, ".beads") + layout.write(t, graphBeadsDir) + before := legacyUpgradeTreeDigest(t, graphBeadsDir) + t.Setenv("HOME", outer) + + cfg, err := findParentConfig(filepath.Join(graphDir, "inner", ".beads")) + if !isUnsupportedWorkspaceFormat(err) { + t.Fatalf("findParentConfig() = %+v, %v, want unsupported workspace format refusal", cfg, err) + } + if !strings.Contains(err.Error(), "graph-preview-format") { + t.Fatalf("refusal %q does not name the marker", err) + } + if after := legacyUpgradeTreeDigest(t, graphBeadsDir); after != before { + t.Fatal("findParentConfig changed the graph workspace") + } + }) + } +} + func TestWorkspaceFormatGuardAdmitsDependencyWorkspaces(t *testing.T) { pinLegacyUpgradeGuardEnv(t) for _, metadata := range []string{ @@ -140,7 +271,9 @@ func TestWorkspaceFormatGuardAdmitsDependencyWorkspaces(t *testing.T) { // workspace's store without passing through command admission, so the store // factories must refuse a graph workspace themselves, before any open. That // includes one marked only by a legacy config.json, which configfile.Load -// would migrate into metadata.json before a check of the loaded metadata ran. +// would migrate into metadata.json before a check of the loaded metadata ran, +// and one declared only by the graph format marker, whose metadata is +// stripped, lost or unparseable. func TestStoreFactoriesRefuseGraphWorkspace(t *testing.T) { pinLegacyUpgradeGuardEnv(t) factories := map[string]func(context.Context, string) (storage.DoltStorage, error){ @@ -149,11 +282,23 @@ func TestStoreFactoriesRefuseGraphWorkspace(t *testing.T) { "read-only": newReadOnlyStoreFromConfig, "preview": newPreviewStoreFromConfig, } - for _, filename := range []string{"metadata.json", "config.json"} { + layouts := map[string]graphWorkspaceLayout{ + "metadata.json graph_mode link": {filename: "metadata.json", metadata: graphLinkWorkspaceMetadata, embedded: true}, + "config.json graph_mode link": {filename: "config.json", metadata: graphLinkWorkspaceMetadata, embedded: true}, + "marker, metadata stripped": {filename: "metadata.json", metadata: graphStrippedWorkspaceMetadata, marker: true, embedded: true}, + // No metadata at all: the factories must not fall back to the + // default database before looking for the marker. + "marker, metadata lost": {marker: true, embedded: true}, + // Metadata that does not parse beside the marker: the marker alone + // declares the format, so this is refused as that, not reported as + // a metadata load failure. + "marker, metadata unparseable": {filename: "metadata.json", metadata: `{"backend":`, marker: true, embedded: true}, + } + for layoutName, layout := range layouts { for name, open := range factories { - t.Run(filename+"/"+name, func(t *testing.T) { + t.Run(layoutName+"/"+name, func(t *testing.T) { beadsDir := t.TempDir() - path := graphWorkspaceLayout{filename: filename, metadata: graphLinkWorkspaceMetadata, embedded: true}.write(t, beadsDir) + path := layout.write(t, beadsDir) before := legacyUpgradeTreeDigest(t, beadsDir) store, err := open(t.Context(), beadsDir) if err == nil { @@ -165,8 +310,10 @@ func TestStoreFactoriesRefuseGraphWorkspace(t *testing.T) { if after := legacyUpgradeTreeDigest(t, beadsDir); after != before { t.Fatalf("%s open changed the workspace", name) } - if got, readErr := os.ReadFile(path); readErr != nil || string(got) != graphLinkWorkspaceMetadata { - t.Fatalf("%s open rewrote %s: %q, %v", name, filename, got, readErr) + if path != "" { + if got, readErr := os.ReadFile(path); readErr != nil || string(got) != layout.metadata { + t.Fatalf("%s open rewrote %s: %q, %v", name, layout.filename, got, readErr) + } } }) } @@ -233,12 +380,19 @@ func TestHandleWorkspaceGuardErrorExitCodes(t *testing.T) { t.Fatalf("handleWorkspaceGuardError(nil) = %v", err) } formatErr := &unsupportedWorkspaceFormatError{beadsDir: "/w/.beads", graphMode: "link"} + markerDir := t.TempDir() + writeFile(t, filepath.Join(markerDir, "graph-preview-format"), []byte("link-preview-v9\n")) + markerErr := checkWorkspaceFormat(nil, markerDir) + if markerErr == nil { + t.Fatalf("checkWorkspaceFormat(no metadata, format marker) = nil, want a refusal") + } tests := []struct { name string err error want int }{ {name: "unsupported format", err: formatErr, want: ExitUnsupportedWorkspaceFormat}, + {name: "format marker", err: markerErr, want: ExitUnsupportedWorkspaceFormat}, {name: "legacy refusal", err: legacyUpgradeRefusal("legacy Dolt workspace"), want: 1}, } for _, tt := range tests { @@ -257,3 +411,46 @@ func TestHandleWorkspaceGuardErrorExitCodes(t *testing.T) { t.Fatalf("ExitUnsupportedWorkspaceFormat = %d; it is a stable scripting contract", ExitUnsupportedWorkspaceFormat) } } + +// A create target without metadata.json is refused when it declares a graph +// format, and is otherwise left to the auto-initialization path as before, +// even when its legacy config.json cannot be parsed. +func TestEnsureBeadsDirForPathChecksWorkspaceFormat(t *testing.T) { + malformedConfig := `{"backend":"dolt",` + for _, tc := range []struct { + name string + marker bool + wantFormat bool + }{ + {name: "malformed config.json", marker: false, wantFormat: false}, + {name: "malformed config.json beside the marker", marker: true, wantFormat: true}, + } { + t.Run(tc.name, func(t *testing.T) { + targetDir := t.TempDir() + beadsDir := filepath.Join(targetDir, ".beads") + if err := os.MkdirAll(beadsDir, 0o750); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(beadsDir, "config.json"), []byte(malformedConfig), 0o600); err != nil { + t.Fatal(err) + } + if tc.marker { + if err := os.WriteFile(filepath.Join(beadsDir, "graph-preview-format"), []byte("1\n"), 0o600); err != nil { + t.Fatal(err) + } + } + // allowCreate=false stops just after the format check, before + // anything is created, so the result shows which branch ran. + err := ensureBeadsDirForPath(context.Background(), targetDir, nil, false) + if err == nil { + t.Fatal("ensureBeadsDirForPath() = nil, want an error") + } + if got := isUnsupportedWorkspaceFormat(err); got != tc.wantFormat { + t.Fatalf("ensureBeadsDirForPath() = %v, unsupported format = %v, want %v", err, got, tc.wantFormat) + } + if !tc.wantFormat && !strings.Contains(err.Error(), "no beads workspace found") { + t.Fatalf("ensureBeadsDirForPath() = %v, want the not-auto-created refusal", err) + } + }) + } +} From f3c47390e7885c6cbfc0fd043b4a7a90d002755e Mon Sep 17 00:00:00 2001 From: Julian Knutsen Date: Tue, 20 Oct 2026 09:29:54 +0000 Subject: [PATCH 2/2] fix(storage): refuse graph_mode workspaces on library opens (#7721) #7671 fences graph workspaces in cmd/bd: command admission, the store factories and the other CLI paths refuse one, and #7722 extends that fence to a .beads holding the graph-preview-format marker whatever its metadata says. But the public library opens (beads.OpenBestAvailable, OpenBestAvailableWith, OpenFromConfig, OpenGated) and the Dolt store's metadata-driven constructors (NewFromConfig, NewFromConfigWithOptions, NewFromConfigWithCLIOptions) still opened either kind of graph workspace as an Issue store and ran Issue schema migrations into the graph database (or, with no metadata beside the marker, created an Issue database inside the graph workspace). - Move the typed refusal into internal/configfile (UnsupportedWorkspaceFormatError with BeadsDir, GraphMode and FormatMarker; CheckWorkspaceFormat; GraphFormatMarkerFile; HasGraphFormatMarker) with byte-identical text and hints for both the graph_mode and the marker refusal, and move cmd/bd's discovery pre-checks there as LoadAndCheckWorkspaceFormat and CheckDiscoveredWorkspaceFormat (LoadForDiscovery, which never migrates a legacy config.json; unreadable metadata beside the marker is refused as the marker's format). cmd/bd's checkWorkspaceFormat, loadAndCheckWorkspaceFormat, hasGraphFormatMarker and checkDiscoveredWorkspaceFormat become thin delegates, so the CLI keeps its behaviour (exit 16 with the same hints) and every caller of them is unchanged; bootstrap's ancestor walk builds the configfile type. - Every public metadata-driven open runs CheckDiscoveredWorkspaceFormat as its first statement: before OpenGated takes its gates and before OpenBestAvailableWith's Load can migrate config.json. A refused open leaves the workspace byte-identical. The type is exported as beads.UnsupportedWorkspaceFormatError. - The Dolt constructors run CheckDiscoveredWorkspaceFormat before configfile.Load, so a graph workspace marked only by a legacy config.json, or by the marker beside stripped, missing or unparseable metadata, is refused before Load can migrate it into metadata.json (and drop graph_* keys this build does not know). requireDoltBackend re-checks the loaded config as a backstop, so they also refuse before resolving a server or writing a port file or Dolt root. Tests: configfile unit tests for both refusals (exact marker text and hint, graph_mode winning over the marker, unparseable metadata with and without the marker); the public opens and the three Dolt constructors against graph_mode workspaces and against marker-only, stripped (metadata.json and legacy config.json), server, explicit dependency and unparseable-metadata marker workspaces, each refused with the typed error and the workspace left unchanged. Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-authored-by: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 9 + beads.go | 20 ++ beads_cgo.go | 5 + beads_nocgo.go | 5 + cmd/bd/bootstrap.go | 2 +- cmd/bd/workspace_format_guard.go | 100 ++-------- cmd/bd/workspace_format_guard_test.go | 2 +- internal/configfile/BUILD.bazel | 2 + internal/configfile/workspace_format.go | 118 ++++++++++++ internal/configfile/workspace_format_test.go | 160 ++++++++++++++++ internal/storage/dolt/open.go | 18 ++ internal/storage/dolt/open_test.go | 133 +++++++++++++ open_backend_selection_test.go | 191 +++++++++++++++++++ 13 files changed, 682 insertions(+), 83 deletions(-) create mode 100644 internal/configfile/workspace_format.go create mode 100644 internal/configfile/workspace_format_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a0ba3976..884a0d7f0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -883,6 +883,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 workspace below it that would take its metadata exit with code 16 and a hint to restore `metadata.json`, and routed and cross-repository opens fail without opening its database. +- **The Go library's opens refuse a graph workspace too.** + `beads.OpenBestAvailable`, `OpenBestAvailableWith`, `OpenFromConfig` and + `OpenGated` opened a workspace whose `metadata.json` declares a + `graph_mode` other than `dependency`, or whose `.beads` holds the + `graph-preview-format` marker, as an Issue store and ran Issue schema + migrations into the graph database. They now + return `*beads.UnsupportedWorkspaceFormatError` (match it with `errors.As`) + before opening, creating or changing anything, the same refusal the CLI + exits 16 with. - **`bd setup claude --remove` no longer leaves a blank-line hole.** Removing the beads section from `CLAUDE.md` (or, with the other setup recipes, from `AGENTS.md` or `GEMINI.md`) left the blank lines around it behind, three in diff --git a/beads.go b/beads.go index 3b7d03fde..235415c84 100644 --- a/beads.go +++ b/beads.go @@ -99,6 +99,18 @@ func configuredBackendUnavailable(backend, beadsDir string, cfg *configfile.Conf } } +// UnsupportedWorkspaceFormatError is returned by OpenBestAvailable, +// OpenBestAvailableWith, OpenFromConfig and OpenGated when the workspace +// declares a data model this build cannot open: a metadata.json graph_mode +// other than "dependency", such as the "link" workspaces graph-preview builds +// of bd write, or the .beads/graph-preview-format marker those builds write +// beside it (FormatMarker), whatever the metadata says. Nothing was opened, +// created or modified. Match it with errors.As to read BeadsDir, GraphMode and +// FormatMarker; the bd CLI refuses the same workspaces with exit code 16. +// Aliased here because internal/configfile is unimportable outside this +// module. +type UnsupportedWorkspaceFormatError = configfile.UnsupportedWorkspaceFormatError + // Transaction provides atomic multi-operation support within a database transaction. // Use Storage.RunInTransaction() to obtain a Transaction instance. type Transaction = beads.Transaction @@ -369,6 +381,9 @@ func Open(ctx context.Context, dbPath string) (Storage, error) { // name configuration. // beadsDir is the path to the .beads directory. func OpenFromConfig(ctx context.Context, beadsDir string) (Storage, error) { + if err := configfile.CheckDiscoveredWorkspaceFormat(beadsDir); err != nil { + return nil, err + } return dolt.NewFromConfigWithOptions(ctx, beadsDir, &dolt.Config{CreateIfMissing: true}) } @@ -403,6 +418,11 @@ func OpenFromConfig(ctx context.Context, beadsDir string) (Storage, error) { // operation holds one exclusively; zero means fail fast. A busy gate is // reported as ErrGateBusy (match with errors.Is). func OpenGated(ctx context.Context, beadsDir string, wait time.Duration) (Storage, error) { + // Before the gates: taking them creates gate files in and beside a + // workspace this build must leave untouched. + if err := configfile.CheckDiscoveredWorkspaceFormat(beadsDir); err != nil { + return nil, err + } wsGate, err := workspacegate.ForWorkspace(beadsDir) if err != nil { return nil, err diff --git a/beads_cgo.go b/beads_cgo.go index d36297ce3..31b91c683 100644 --- a/beads_cgo.go +++ b/beads_cgo.go @@ -46,6 +46,11 @@ func OpenBestAvailable(ctx context.Context, beadsDir string) (Storage, error) { // typed refusal (the matching ErrXWithoutOpenWith sentinel), never a silent // open with the field ignored. func OpenBestAvailableWith(ctx context.Context, beadsDir string, opts OpenOptions) (Storage, error) { + // Before Load, which can migrate a legacy config.json, and before any + // backend is chosen, as the CLI store factories do. + if err := configfile.CheckDiscoveredWorkspaceFormat(beadsDir); err != nil { + return nil, err + } cfg, err := configfile.Load(beadsDir) if err != nil { return nil, fmt.Errorf("loading storage metadata: %w", err) diff --git a/beads_nocgo.go b/beads_nocgo.go index ba6853c4a..878a87d45 100644 --- a/beads_nocgo.go +++ b/beads_nocgo.go @@ -32,6 +32,11 @@ func OpenBestAvailable(ctx context.Context, beadsDir string) (Storage, error) { // rationale; behavior here is identical except that embedded Dolt is // unavailable without CGO. func OpenBestAvailableWith(ctx context.Context, beadsDir string, opts OpenOptions) (Storage, error) { + // Before Load, which can migrate a legacy config.json, and before any + // backend is chosen, as the CLI store factories do. + if err := configfile.CheckDiscoveredWorkspaceFormat(beadsDir); err != nil { + return nil, err + } cfg, err := configfile.Load(beadsDir) if err != nil { return nil, fmt.Errorf("loading storage metadata: %w", err) diff --git a/cmd/bd/bootstrap.go b/cmd/bd/bootstrap.go index 8d07611cf..c910aa300 100644 --- a/cmd/bd/bootstrap.go +++ b/cmd/bd/bootstrap.go @@ -1615,7 +1615,7 @@ func findParentConfig(beadsDir string) (*configfile.Config, error) { candidate := filepath.Join(dir, ".beads") cfg, err := configfile.LoadForDiscovery(candidate) if (err != nil || cfg == nil) && hasGraphFormatMarker(candidate) { - return nil, &unsupportedWorkspaceFormatError{beadsDir: candidate, formatMarker: true} + return nil, &configfile.UnsupportedWorkspaceFormatError{BeadsDir: candidate, FormatMarker: true} } if err != nil { return nil, fmt.Errorf("%s: %w", configfile.ConfigPath(candidate), err) diff --git a/cmd/bd/workspace_format_guard.go b/cmd/bd/workspace_format_guard.go index 1ae6c3995..2b7d35124 100644 --- a/cmd/bd/workspace_format_guard.go +++ b/cmd/bd/workspace_format_guard.go @@ -2,9 +2,6 @@ package main import ( "errors" - "fmt" - "os" - "path/filepath" "github.com/steveyegge/beads/internal/configfile" ) @@ -12,7 +9,7 @@ import ( // ExitUnsupportedWorkspaceFormat is the exit code for a command refused // because its workspace declares a format this bd build cannot open: a // metadata.json graph_mode other than "dependency", or a graph workspace -// format marker (graphFormatMarkerFile). Stable so a wrapper can +// format marker (configfile.GraphFormatMarkerFile). Stable so a wrapper can // tell "this workspace needs a different bd build" apart from a generic // failure (1) without grepping stderr. // @@ -21,86 +18,28 @@ import ( // §E3, which freezes 10/11/12/130. const ExitUnsupportedWorkspaceFormat = 16 -// graphFormatMarkerFile is the format sentinel graph-preview builds write in -// .beads before metadata.json, so that a graph workspace whose metadata was -// never written, was lost, or was rewritten without graph_mode by a bd that -// does not know the field still declares its format. -const graphFormatMarkerFile = "graph-preview-format" - -// unsupportedWorkspaceFormatError refuses a workspace whose metadata or format -// marker declares a data model other than the Issue store this build opens. -// Graph-preview builds persist graph_mode "link" plus graph_* binding fields -// beside an ordinary Dolt backend, and the graphFormatMarkerFile beside them, -// so nothing else tells this build that the database behind it is not an -// Issue store; opening it as one would run Issue migrations into it. -type unsupportedWorkspaceFormatError struct { - beadsDir string - graphMode string - // formatMarker reports that graphFormatMarkerFile, not graph_mode, - // declared the format. - formatMarker bool -} - -func (e *unsupportedWorkspaceFormatError) Error() string { - if e.formatMarker { - return fmt.Sprintf("workspace %s has a %s marker, which this bd build does not support; %s", - e.beadsDir, graphFormatMarkerFile, configfile.BackendNotOpenedGuarantee) - } - return fmt.Sprintf("workspace %s uses format graph_mode %q, which this bd build does not support; %s", - e.beadsDir, e.graphMode, configfile.BackendNotOpenedGuarantee) -} - -func (e *unsupportedWorkspaceFormatError) hint() string { - if e.formatMarker { - return fmt.Sprintf("restore metadata.json (graph_mode and the graph_* fields) from version control or a backup, then use a bd build that supports graph workspaces; do not remove .beads/%s", graphFormatMarkerFile) - } - return fmt.Sprintf("use a bd build that supports graph_mode %q workspaces; leave graph_mode and the graph_* fields in metadata.json unchanged", e.graphMode) -} - // checkWorkspaceFormat refuses metadata whose graph_mode marker names any -// model but the default. An unknown marker is refused too: it may describe a -// format newer than this build, so it must never fall back to the Issue store. -// It also refuses a beadsDir holding the graph format marker file, whatever -// the metadata says and whatever the file holds. cfg may be nil (no metadata); -// beadsDir may be "" (no workspace directory, so no marker to find). +// model but the default, and a beadsDir holding the graph format marker file, +// with a *configfile.UnsupportedWorkspaceFormatError. It is +// configfile.CheckWorkspaceFormat, the check the public beads package and the +// Dolt store's metadata-driven opens apply too, so the CLI and a library +// caller refuse the same workspaces with the same error. func checkWorkspaceFormat(cfg *configfile.Config, beadsDir string) error { - if mode, err := cfg.GetGraphMode(); err != nil || mode != configfile.GraphModeDependency { - return &unsupportedWorkspaceFormatError{beadsDir: beadsDir, graphMode: cfg.GraphMode} - } - if hasGraphFormatMarker(beadsDir) { - return &unsupportedWorkspaceFormatError{beadsDir: beadsDir, formatMarker: true} - } - return nil + return configfile.CheckWorkspaceFormat(cfg, beadsDir) } // loadAndCheckWorkspaceFormat reads beadsDir's discovery metadata without -// migrating it and refuses a workspace in a format this build cannot open -// (checkWorkspaceFormat). cfg is nil when beadsDir has no metadata. Metadata -// that cannot be read beside the graph format marker is refused as that -// format too: the marker alone declares it. +// migrating it and refuses a workspace in a format this build cannot open, +// including unreadable metadata beside the graph format marker. It is +// configfile.LoadAndCheckWorkspaceFormat. func loadAndCheckWorkspaceFormat(beadsDir string) (*configfile.Config, error) { - cfg, err := configfile.LoadForDiscovery(beadsDir) - if err != nil { - if hasGraphFormatMarker(beadsDir) { - return nil, &unsupportedWorkspaceFormatError{beadsDir: beadsDir, formatMarker: true} - } - return nil, fmt.Errorf("loading config: %w", err) - } - if err := checkWorkspaceFormat(cfg, beadsDir); err != nil { - return nil, err - } - return cfg, nil + return configfile.LoadAndCheckWorkspaceFormat(beadsDir) } // hasGraphFormatMarker reports whether anything exists at beadsDir's graph -// format marker path. Callers read beadsDir's metadata first, so a directory -// bd cannot search has already failed there. +// format marker path (configfile.HasGraphFormatMarker). func hasGraphFormatMarker(beadsDir string) bool { - if beadsDir == "" { - return false - } - _, err := os.Lstat(filepath.Join(beadsDir, graphFormatMarkerFile)) - return err == nil + return configfile.HasGraphFormatMarker(beadsDir) } // checkDiscoveredWorkspaceFormat runs checkWorkspaceFormat on beadsDir's @@ -110,15 +49,14 @@ func hasGraphFormatMarker(beadsDir string) bool { // config.json into metadata.json before the format check could refuse it. // Metadata that does not load is left to the caller's own load to report, // unless the graph format marker sits beside it (loadAndCheckWorkspaceFormat). +// It is configfile.CheckDiscoveredWorkspaceFormat, the pre-check the public +// beads package's opens run too. func checkDiscoveredWorkspaceFormat(beadsDir string) error { - if _, err := loadAndCheckWorkspaceFormat(beadsDir); isUnsupportedWorkspaceFormat(err) { - return err - } - return nil + return configfile.CheckDiscoveredWorkspaceFormat(beadsDir) } func isUnsupportedWorkspaceFormat(err error) bool { - var formatErr *unsupportedWorkspaceFormatError + var formatErr *configfile.UnsupportedWorkspaceFormatError return errors.As(err, &formatErr) } @@ -130,10 +68,10 @@ func handleWorkspaceGuardError(err error) error { if err == nil { return nil } - var formatErr *unsupportedWorkspaceFormatError + var formatErr *configfile.UnsupportedWorkspaceFormatError if !errors.As(err, &formatErr) { return HandleError("%v", err) } - _ = HandleErrorWithHint(formatErr.Error(), formatErr.hint()) + _ = HandleErrorWithHint(formatErr.Error(), formatErr.Hint()) return &exitError{Code: ExitUnsupportedWorkspaceFormat} } diff --git a/cmd/bd/workspace_format_guard_test.go b/cmd/bd/workspace_format_guard_test.go index d66f03f29..a19ae0d80 100644 --- a/cmd/bd/workspace_format_guard_test.go +++ b/cmd/bd/workspace_format_guard_test.go @@ -379,7 +379,7 @@ func TestHandleWorkspaceGuardErrorExitCodes(t *testing.T) { if err := handleWorkspaceGuardError(nil); err != nil { t.Fatalf("handleWorkspaceGuardError(nil) = %v", err) } - formatErr := &unsupportedWorkspaceFormatError{beadsDir: "/w/.beads", graphMode: "link"} + formatErr := &configfile.UnsupportedWorkspaceFormatError{BeadsDir: "/w/.beads", GraphMode: "link"} markerDir := t.TempDir() writeFile(t, filepath.Join(markerDir, "graph-preview-format"), []byte("link-preview-v9\n")) markerErr := checkWorkspaceFormat(nil, markerDir) diff --git a/internal/configfile/BUILD.bazel b/internal/configfile/BUILD.bazel index b56381c3c..44d63260a 100644 --- a/internal/configfile/BUILD.bazel +++ b/internal/configfile/BUILD.bazel @@ -12,6 +12,7 @@ go_library( "external_dolt_config.go", "graph_mode.go", "proxied_server_client_info.go", + "workspace_format.go", ], importpath = "github.com/steveyegge/beads/internal/configfile", visibility = ["//:__subpackages__"], @@ -30,6 +31,7 @@ go_test( "credentials_test.go", "external_dolt_config_test.go", "graph_mode_test.go", + "workspace_format_test.go", ], embed = [":configfile"], deps = ["//internal/config"], diff --git a/internal/configfile/workspace_format.go b/internal/configfile/workspace_format.go new file mode 100644 index 000000000..9da5f88b1 --- /dev/null +++ b/internal/configfile/workspace_format.go @@ -0,0 +1,118 @@ +package configfile + +import ( + "errors" + "fmt" + "os" + "path/filepath" +) + +// GraphFormatMarkerFile is the format sentinel graph-preview builds write in +// .beads before metadata.json, so that a graph workspace whose metadata was +// never written, was lost, or was rewritten without graph_mode by a bd that +// does not know the field still declares its format. +const GraphFormatMarkerFile = "graph-preview-format" + +// UnsupportedWorkspaceFormatError refuses a workspace whose metadata or format +// marker declares a data model other than the Issue store this build opens. +// Graph-preview builds persist graph_mode "link" plus graph_* binding fields +// beside an ordinary Dolt backend, and the GraphFormatMarkerFile beside them, +// so nothing else tells this build that the database behind it is not an +// Issue store; opening it as one would run Issue migrations into it. +// +// It is defined here, beside the metadata, so that every open path refuses +// with the same type and text: cmd/bd's admission guard and store factories, +// the public beads package, and the Dolt store's metadata-driven constructors. +type UnsupportedWorkspaceFormatError struct { + // BeadsDir is the workspace whose metadata or marker declared the format. + BeadsDir string + // GraphMode is the graph_mode marker exactly as the metadata wrote it. + GraphMode string + // FormatMarker reports that GraphFormatMarkerFile, not graph_mode, + // declared the format. + FormatMarker bool +} + +func (e *UnsupportedWorkspaceFormatError) Error() string { + if e.FormatMarker { + return fmt.Sprintf("workspace %s has a %s marker, which this bd build does not support; %s", + e.BeadsDir, GraphFormatMarkerFile, BackendNotOpenedGuarantee) + } + return fmt.Sprintf("workspace %s uses format graph_mode %q, which this bd build does not support; %s", + e.BeadsDir, e.GraphMode, BackendNotOpenedGuarantee) +} + +// Hint names the remedy: a build that supports the format, with the +// workspace's metadata and marker left as they are (or, for a marker without +// graph metadata, the metadata restored first). +func (e *UnsupportedWorkspaceFormatError) Hint() string { + if e.FormatMarker { + return fmt.Sprintf("restore metadata.json (graph_mode and the graph_* fields) from version control or a backup, then use a bd build that supports graph workspaces; do not remove .beads/%s", GraphFormatMarkerFile) + } + return fmt.Sprintf("use a bd build that supports graph_mode %q workspaces; leave graph_mode and the graph_* fields in metadata.json unchanged", e.GraphMode) +} + +// CheckWorkspaceFormat refuses metadata whose graph_mode marker names any +// model but the default, with an *UnsupportedWorkspaceFormatError. An unknown +// marker is refused too: it may describe a format newer than this build, so +// it must never fall back to the Issue store. It also refuses a beadsDir +// holding GraphFormatMarkerFile, whatever the metadata says and whatever the +// file holds. cfg may be nil (no metadata); beadsDir may be "" (no workspace +// directory, so no marker to find). +func CheckWorkspaceFormat(cfg *Config, beadsDir string) error { + if mode, err := cfg.GetGraphMode(); err != nil || mode != GraphModeDependency { + return &UnsupportedWorkspaceFormatError{BeadsDir: beadsDir, GraphMode: cfg.GraphMode} + } + if HasGraphFormatMarker(beadsDir) { + return &UnsupportedWorkspaceFormatError{BeadsDir: beadsDir, FormatMarker: true} + } + return nil +} + +// LoadAndCheckWorkspaceFormat reads beadsDir's discovery metadata without +// migrating it (LoadForDiscovery) and refuses a workspace in a format this +// build cannot open (CheckWorkspaceFormat). cfg is nil when beadsDir has no +// metadata. Metadata that cannot be read beside the graph format marker is +// refused as that format too: the marker alone declares it. Any other load +// failure is returned wrapped. +func LoadAndCheckWorkspaceFormat(beadsDir string) (*Config, error) { + cfg, err := LoadForDiscovery(beadsDir) + if err != nil { + if HasGraphFormatMarker(beadsDir) { + return nil, &UnsupportedWorkspaceFormatError{BeadsDir: beadsDir, FormatMarker: true} + } + return nil, fmt.Errorf("loading config: %w", err) + } + if err := CheckWorkspaceFormat(cfg, beadsDir); err != nil { + return nil, err + } + return cfg, nil +} + +// HasGraphFormatMarker reports whether anything exists at beadsDir's graph +// format marker path. Callers read beadsDir's metadata first, so a directory +// bd cannot search has already failed there. An empty beadsDir never probes +// the working directory. +func HasGraphFormatMarker(beadsDir string) bool { + if beadsDir == "" { + return false + } + _, err := os.Lstat(filepath.Join(beadsDir, GraphFormatMarkerFile)) + return err == nil +} + +// CheckDiscoveredWorkspaceFormat runs CheckWorkspaceFormat on beadsDir's +// metadata as LoadForDiscovery reads it, which never rewrites the workspace. +// An open that has not yet decided this build may touch the workspace runs it +// first: Load would otherwise migrate a legacy config.json into metadata.json +// before the format check could refuse it. Metadata that does not load is +// left to the caller's own load to report, unless the graph format marker +// sits beside it (LoadAndCheckWorkspaceFormat). +func CheckDiscoveredWorkspaceFormat(beadsDir string) error { + _, err := LoadAndCheckWorkspaceFormat(beadsDir) + var formatErr *UnsupportedWorkspaceFormatError + if errors.As(err, &formatErr) { + return err + } + return nil +} diff --git a/internal/configfile/workspace_format_test.go b/internal/configfile/workspace_format_test.go new file mode 100644 index 000000000..ddcf6f2ca --- /dev/null +++ b/internal/configfile/workspace_format_test.go @@ -0,0 +1,160 @@ +package configfile + +import ( + "errors" + "os" + "path/filepath" + "strings" + "testing" +) + +func TestCheckWorkspaceFormatRefusesOtherModels(t *testing.T) { + const beadsDir = "/work/repo/.beads" + for _, mode := range []string{GraphModeLink, "future-format", "Dependency"} { + t.Run(mode, func(t *testing.T) { + err := CheckWorkspaceFormat(&Config{Backend: BackendDolt, GraphMode: mode}, beadsDir) + var formatErr *UnsupportedWorkspaceFormatError + if !errors.As(err, &formatErr) { + t.Fatalf("CheckWorkspaceFormat() = %v, want *UnsupportedWorkspaceFormatError", err) + } + if formatErr.BeadsDir != beadsDir || formatErr.GraphMode != mode { + t.Fatalf("refusal = %+v, want BeadsDir %q and GraphMode %q", formatErr, beadsDir, mode) + } + for _, want := range []string{beadsDir, `graph_mode "` + mode + `"`, "this bd build does not support", BackendNotOpenedGuarantee} { + if !strings.Contains(err.Error(), want) { + t.Errorf("refusal %q does not mention %q", err, want) + } + } + if hint := formatErr.Hint(); !strings.Contains(hint, `graph_mode "`+mode+`"`) || !strings.Contains(hint, "unchanged") { + t.Errorf("hint %q does not name the mode or ask to keep the marker", hint) + } + }) + } +} + +func TestCheckWorkspaceFormatAdmitsIssueWorkspaces(t *testing.T) { + for name, cfg := range map[string]*Config{ + "no metadata": nil, + "absent marker": {Backend: BackendDolt}, + "dependency marker": {Backend: BackendDolt, GraphMode: GraphModeDependency}, + } { + t.Run(name, func(t *testing.T) { + if err := CheckWorkspaceFormat(cfg, "/work/repo/.beads"); err != nil { + t.Fatalf("CheckWorkspaceFormat() = %v, want admission", err) + } + }) + } +} + +// TestCheckDiscoveredWorkspaceFormatLeavesWorkspaceUnchanged pins the +// pre-check every open runs before Load: it refuses a graph workspace marked +// in either metadata file without migrating a legacy config.json, and leaves +// a workspace with no metadata to the caller's own load. +func TestCheckDiscoveredWorkspaceFormatLeavesWorkspaceUnchanged(t *testing.T) { + const metadata = `{"backend":"dolt","graph_mode":"link"}` + for _, name := range []string{ConfigFileName, "config.json"} { + t.Run(name, func(t *testing.T) { + beadsDir := t.TempDir() + if err := os.WriteFile(filepath.Join(beadsDir, name), []byte(metadata), 0o600); err != nil { + t.Fatal(err) + } + err := CheckDiscoveredWorkspaceFormat(beadsDir) + var formatErr *UnsupportedWorkspaceFormatError + if !errors.As(err, &formatErr) || formatErr.BeadsDir != beadsDir || formatErr.GraphMode != GraphModeLink { + t.Fatalf("CheckDiscoveredWorkspaceFormat() = %v, want the link refusal for %s", err, beadsDir) + } + entries, err := os.ReadDir(beadsDir) + if err != nil || len(entries) != 1 || entries[0].Name() != name { + t.Fatalf("pre-check changed the workspace: %v, %v", entries, err) + } + }) + } + if err := CheckDiscoveredWorkspaceFormat(t.TempDir()); err != nil { + t.Fatalf("CheckDiscoveredWorkspaceFormat(no metadata) = %v, want nil", err) + } +} + +// TestCheckWorkspaceFormatRefusesFormatMarker pins the marker half of the +// check: a beadsDir holding GraphFormatMarkerFile is refused whatever its +// metadata says, with its own text and hint, while graph_mode still wins when +// both declare the format. +func TestCheckWorkspaceFormatRefusesFormatMarker(t *testing.T) { + beadsDir := t.TempDir() + if err := os.WriteFile(filepath.Join(beadsDir, GraphFormatMarkerFile), []byte("anything"), 0o600); err != nil { + t.Fatal(err) + } + for name, cfg := range map[string]*Config{ + "no metadata": nil, + "stripped metadata": {Backend: BackendDolt}, + "dependency marker": {Backend: BackendDolt, GraphMode: GraphModeDependency}, + } { + t.Run(name, func(t *testing.T) { + err := CheckWorkspaceFormat(cfg, beadsDir) + var formatErr *UnsupportedWorkspaceFormatError + if !errors.As(err, &formatErr) || !formatErr.FormatMarker || formatErr.BeadsDir != beadsDir || formatErr.GraphMode != "" { + t.Fatalf("CheckWorkspaceFormat() = %#v, want the format marker refusal", err) + } + wantErr := "workspace " + beadsDir + " has a graph-preview-format marker, which this bd build does not support; " + BackendNotOpenedGuarantee + if err.Error() != wantErr { + t.Errorf("refusal = %q, want %q", err, wantErr) + } + wantHint := "restore metadata.json (graph_mode and the graph_* fields) from version control or a backup, then use a bd build that supports graph workspaces; do not remove .beads/graph-preview-format" + if formatErr.Hint() != wantHint { + t.Errorf("hint = %q, want %q", formatErr.Hint(), wantHint) + } + }) + } + err := CheckWorkspaceFormat(&Config{Backend: BackendDolt, GraphMode: GraphModeLink}, beadsDir) + var formatErr *UnsupportedWorkspaceFormatError + if !errors.As(err, &formatErr) || formatErr.FormatMarker || formatErr.GraphMode != GraphModeLink { + t.Fatalf("CheckWorkspaceFormat(link beside marker) = %#v, want the graph_mode refusal", err) + } + if err := CheckWorkspaceFormat(nil, ""); err != nil { + t.Fatalf("CheckWorkspaceFormat(nil, \"\") = %v, want admission without probing the working directory", err) + } +} + +// TestCheckDiscoveredWorkspaceFormatRefusesFormatMarker pins that the +// pre-check refuses a marked workspace with no, stripped or unparseable +// metadata, and still leaves unparseable metadata without the marker to the +// caller's own load. +func TestCheckDiscoveredWorkspaceFormatRefusesFormatMarker(t *testing.T) { + for name, files := range map[string]map[string]string{ + "marker only": {GraphFormatMarkerFile: ""}, + "stripped metadata.json": {GraphFormatMarkerFile: "x", ConfigFileName: `{"backend":"dolt"}`}, + "stripped legacy config.json": {GraphFormatMarkerFile: "x", "config.json": `{"backend":"dolt"}`}, + "unparseable metadata.json": {GraphFormatMarkerFile: "x", ConfigFileName: `{"backend":`}, + "unparseable legacy config.json": {GraphFormatMarkerFile: "x", "config.json": `{"backend":`}, + } { + t.Run(name, func(t *testing.T) { + beadsDir := t.TempDir() + for file, content := range files { + if err := os.WriteFile(filepath.Join(beadsDir, file), []byte(content), 0o600); err != nil { + t.Fatal(err) + } + } + err := CheckDiscoveredWorkspaceFormat(beadsDir) + var formatErr *UnsupportedWorkspaceFormatError + if !errors.As(err, &formatErr) || !formatErr.FormatMarker || formatErr.BeadsDir != beadsDir { + t.Fatalf("CheckDiscoveredWorkspaceFormat() = %v, want the format marker refusal", err) + } + if _, err := LoadAndCheckWorkspaceFormat(beadsDir); !errors.As(err, &formatErr) || !formatErr.FormatMarker { + t.Fatalf("LoadAndCheckWorkspaceFormat() = %v, want the format marker refusal", err) + } + entries, err := os.ReadDir(beadsDir) + if err != nil || len(entries) != len(files) { + t.Fatalf("pre-check changed the workspace: %v, %v", entries, err) + } + }) + } + unparseable := t.TempDir() + if err := os.WriteFile(filepath.Join(unparseable, ConfigFileName), []byte(`{"backend":`), 0o600); err != nil { + t.Fatal(err) + } + if err := CheckDiscoveredWorkspaceFormat(unparseable); err != nil { + t.Fatalf("CheckDiscoveredWorkspaceFormat(unparseable, no marker) = %v, want nil", err) + } + if _, err := LoadAndCheckWorkspaceFormat(unparseable); err == nil || !strings.Contains(err.Error(), "loading config") { + t.Fatalf("LoadAndCheckWorkspaceFormat(unparseable, no marker) = %v, want the load failure", err) + } +} diff --git a/internal/storage/dolt/open.go b/internal/storage/dolt/open.go index 6de61bbff..9d55757c7 100644 --- a/internal/storage/dolt/open.go +++ b/internal/storage/dolt/open.go @@ -83,7 +83,15 @@ func ApplyResolvedServerPort(beadsDir string, cfg *Config) { // closed instead of opening a new, empty Dolt database. beadsDir is the workspace // the config came from, so the refusal can offer the metadata heal when that // workspace already holds a Dolt database. +// +// It first refuses a workspace whose metadata or graph format marker declares a +// data model this build cannot open (configfile.CheckWorkspaceFormat): such a +// workspace keeps another model's database behind an ordinary Dolt backend, +// and opening it here would run Issue migrations into that database. func requireDoltBackend(fileCfg *configfile.Config, beadsDir string) error { + if err := configfile.CheckWorkspaceFormat(fileCfg, beadsDir); err != nil { + return err + } switch fileCfg.Backend { case configfile.BackendPostgres, configfile.BackendMySQL, configfile.BackendSQLite: return fmt.Errorf("configured storage backend %q is no longer supported and cannot be opened as Dolt: %s", fileCfg.Backend, configfile.RemovedBackendDetailAt(fileCfg.Backend, beadsDir, fileCfg)) @@ -109,6 +117,11 @@ func NewFromConfig(ctx context.Context, beadsDir string) (*DoltStore, error) { // `bd doctor` that should behave the same way as normal top-level CLI commands // while still honoring externally managed server mode. func NewFromConfigWithCLIOptions(ctx context.Context, beadsDir string, cfg *Config) (*DoltStore, error) { + // Refuse a graph workspace before Load can migrate a legacy config.json + // into metadata.json; requireDoltBackend re-checks the loaded config. + if err := configfile.CheckDiscoveredWorkspaceFormat(beadsDir); err != nil { + return nil, err + } fileCfg, err := configfile.Load(beadsDir) if err != nil { return nil, fmt.Errorf("loading config: %w", err) @@ -139,6 +152,11 @@ func NewFromConfigWithCLIOptions(ctx context.Context, beadsDir string, cfg *Conf // NewFromConfigWithOptions creates a DoltStore with options from metadata.json. // Options in cfg override those from the config file. Pass nil for default options. func NewFromConfigWithOptions(ctx context.Context, beadsDir string, cfg *Config) (*DoltStore, error) { + // Refuse a graph workspace before Load can migrate a legacy config.json + // into metadata.json; requireDoltBackend re-checks the loaded config. + if err := configfile.CheckDiscoveredWorkspaceFormat(beadsDir); err != nil { + return nil, err + } fileCfg, err := configfile.Load(beadsDir) if err != nil { return nil, fmt.Errorf("loading config: %w", err) diff --git a/internal/storage/dolt/open_test.go b/internal/storage/dolt/open_test.go index c3d86077d..10a79f28b 100644 --- a/internal/storage/dolt/open_test.go +++ b/internal/storage/dolt/open_test.go @@ -3,6 +3,7 @@ package dolt import ( "bytes" "context" + "errors" "io" "os" "path/filepath" @@ -208,6 +209,138 @@ func TestConfigConstructorsRejectNonDoltBackends(t *testing.T) { } } +// TestConfigConstructorsRefuseGraphWorkspace pins that every metadata-driven +// constructor refuses a workspace whose metadata declares another data model, +// before it resolves a server or writes anything into the workspace (a port +// file, a Dolt root, or the metadata.json that Load would migrate a legacy +// config.json into). The CLI's own store open does not come through here; the +// public beads package's config opens and cmd/bd's direct NewFromConfig* +// callers do. +func TestConfigConstructorsRefuseGraphWorkspace(t *testing.T) { + // If the refusal were missing, the open must fail fast rather than reach + // the suite's shared test server. + t.Setenv("BEADS_DOLT_SERVER_HOST", "127.0.0.1") + t.Setenv("BEADS_DOLT_SERVER_PORT", "1") + for _, mode := range []string{configfile.GraphModeLink, "future-format"} { + for _, doltMode := range []string{configfile.DoltModeEmbedded, configfile.DoltModeServer} { + // "config.json" is the legacy name Load migrates into metadata.json; + // a refused open must not run that migration either. + for _, fileName := range []string{configfile.ConfigFileName, "config.json"} { + t.Run(mode+"/"+doltMode+"/"+fileName, func(t *testing.T) { + beadsDir := t.TempDir() + metadata := `{"backend":"dolt","dolt_mode":"` + doltMode + `","dolt_database":"beads_graph_0123","graph_mode":"` + mode + `","graph_future_binding":"keep-me"}` + path := filepath.Join(beadsDir, fileName) + if err := os.WriteFile(path, []byte(metadata), 0o600); err != nil { + t.Fatal(err) + } + constructors := map[string]func() (*DoltStore, error){ + "default": func() (*DoltStore, error) { + return NewFromConfig(t.Context(), beadsDir) + }, + "standard": func() (*DoltStore, error) { + return NewFromConfigWithOptions(t.Context(), beadsDir, &Config{DisableAutoStart: true, CreateIfMissing: true}) + }, + "cli": func() (*DoltStore, error) { + return NewFromConfigWithCLIOptions(t.Context(), beadsDir, &Config{DisableAutoStart: true, ReadOnly: true}) + }, + } + for name, construct := range constructors { + t.Run(name, func(t *testing.T) { + store, err := construct() + if err == nil { + _ = store.Close() + t.Fatalf("graph_mode %q workspace opened as Dolt", mode) + } + var formatErr *configfile.UnsupportedWorkspaceFormatError + if !errors.As(err, &formatErr) || formatErr.BeadsDir != beadsDir || formatErr.GraphMode != mode { + t.Fatalf("constructor error = %v, want UnsupportedWorkspaceFormatError for %s", err, beadsDir) + } + entries, readErr := os.ReadDir(beadsDir) + if readErr != nil || len(entries) != 1 { + t.Fatalf("refused open changed the workspace: %v, %v", entries, readErr) + } + if got, readErr := os.ReadFile(path); readErr != nil || string(got) != metadata { + t.Fatalf("refused open rewrote %s: %q, %v", fileName, got, readErr) + } + }) + } + }) + } + } + } +} + +// TestConfigConstructorsRefuseGraphFormatMarker pins that every +// metadata-driven constructor refuses a workspace holding the +// graph-preview-format marker graph-preview builds write, whatever its +// metadata says (none, stripped of graph_mode in either metadata file, an +// explicit dependency, or unparseable), and leaves the workspace unchanged. +func TestConfigConstructorsRefuseGraphFormatMarker(t *testing.T) { + // If the refusal were missing, the open must fail fast rather than reach + // the suite's shared test server. + t.Setenv("BEADS_DOLT_SERVER_HOST", "127.0.0.1") + t.Setenv("BEADS_DOLT_SERVER_PORT", "1") + layouts := []struct { + name string + fileName string // "" writes no metadata file + metadata string + }{ + {name: "marker only"}, + {name: "stripped embedded metadata", fileName: configfile.ConfigFileName, metadata: `{"backend":"dolt","dolt_mode":"embedded","dolt_database":"beads_graph_0123"}`}, + {name: "stripped server metadata", fileName: configfile.ConfigFileName, metadata: `{"backend":"dolt","dolt_mode":"server","dolt_database":"beads_graph_0123"}`}, + {name: "stripped legacy config.json", fileName: "config.json", metadata: `{"backend":"dolt","dolt_mode":"embedded","dolt_database":"beads_graph_0123"}`}, + {name: "dependency metadata", fileName: configfile.ConfigFileName, metadata: `{"backend":"dolt","dolt_mode":"server","graph_mode":"dependency"}`}, + {name: "unparseable metadata", fileName: configfile.ConfigFileName, metadata: `{"backend":"dolt",`}, + } + for _, layout := range layouts { + t.Run(layout.name, func(t *testing.T) { + beadsDir := t.TempDir() + want := map[string]string{configfile.GraphFormatMarkerFile: "link-preview-v9\n"} + if layout.fileName != "" { + want[layout.fileName] = layout.metadata + } + for name, content := range want { + if err := os.WriteFile(filepath.Join(beadsDir, name), []byte(content), 0o600); err != nil { + t.Fatal(err) + } + } + constructors := map[string]func() (*DoltStore, error){ + "default": func() (*DoltStore, error) { + return NewFromConfig(t.Context(), beadsDir) + }, + "standard": func() (*DoltStore, error) { + return NewFromConfigWithOptions(t.Context(), beadsDir, &Config{DisableAutoStart: true, CreateIfMissing: true}) + }, + "cli": func() (*DoltStore, error) { + return NewFromConfigWithCLIOptions(t.Context(), beadsDir, &Config{DisableAutoStart: true, ReadOnly: true}) + }, + } + for name, construct := range constructors { + t.Run(name, func(t *testing.T) { + store, err := construct() + if err == nil { + _ = store.Close() + t.Fatalf("workspace with a %s marker opened as Dolt", configfile.GraphFormatMarkerFile) + } + var formatErr *configfile.UnsupportedWorkspaceFormatError + if !errors.As(err, &formatErr) || formatErr.BeadsDir != beadsDir || !formatErr.FormatMarker { + t.Fatalf("constructor error = %v, want the format marker refusal for %s", err, beadsDir) + } + entries, readErr := os.ReadDir(beadsDir) + if readErr != nil || len(entries) != len(want) { + t.Fatalf("refused open changed the workspace: %v, %v", entries, readErr) + } + for fileName, content := range want { + if got, readErr := os.ReadFile(filepath.Join(beadsDir, fileName)); readErr != nil || string(got) != content { + t.Fatalf("refused open rewrote %s: %q, %v", fileName, got, readErr) + } + } + }) + } + }) + } +} + func TestCLIDirUsesSharedDoltRootInSharedServerMode(t *testing.T) { sharedRoot := t.TempDir() t.Setenv("BEADS_DOLT_SHARED_SERVER", "1") diff --git a/open_backend_selection_test.go b/open_backend_selection_test.go index dc79697d7..36ca6bb7e 100644 --- a/open_backend_selection_test.go +++ b/open_backend_selection_test.go @@ -3,9 +3,11 @@ package beads_test import ( "context" "errors" + "maps" "net/http" "os" "path/filepath" + "slices" "strings" "testing" @@ -475,3 +477,192 @@ func TestOpenBestAvailableWithRefusesPerOpenOptionsOnPlainDolt(t *testing.T) { }) } } + +// graphWorkspaceMetadata is the metadata.json a graph-preview build of bd +// writes for a graph_mode "link" workspace: the marker and its binding beside +// an ordinary embedded Dolt backend. +const graphWorkspaceMetadata = `{ + "database": "", + "backend": "dolt", + "graph_mode": "link", + "graph_scope_url": "https://example.test/scope", + "graph_authority_id": "0123456789abcdef0123456789abcdef", + "graph_workspace": "/work/repo/.beads", + "graph_schema_version": 7, + "graph_ready": true, + "dolt_mode": "embedded", + "dolt_database": "beads_graph_0123456789abcdef0123456789abcdef", + "project_id": "0123456789abcdef0123456789abcdef" +}` + +// graphWorkspaceMetadataStripped is graphWorkspaceMetadata as a bd that +// predates graph_mode rewrites it: the graph fields are gone, but the database +// name still points at the graph database. +const graphWorkspaceMetadataStripped = `{ + "database": "", + "backend": "dolt", + "dolt_mode": "embedded", + "dolt_database": "beads_graph_0123456789abcdef0123456789abcdef", + "project_id": "0123456789abcdef0123456789abcdef" +}` + +// publicOpens are the public entry points that open a workspace from its +// metadata. +var publicOpens = map[string]func(context.Context, string) (beads.Storage, error){ + "OpenBestAvailable": beads.OpenBestAvailable, + "OpenBestAvailableWith": func(ctx context.Context, beadsDir string) (beads.Storage, error) { + return beads.OpenBestAvailableWith(ctx, beadsDir, beads.OpenOptions{}) + }, + "OpenFromConfig": beads.OpenFromConfig, + "OpenGated": func(ctx context.Context, beadsDir string) (beads.Storage, error) { + return beads.OpenGated(ctx, beadsDir, 0) + }, +} + +// workspaceTreeDigest records every path under root with its kind and, for +// files, its content, so a test can prove an open left a workspace untouched. +func workspaceTreeDigest(t *testing.T, root string) map[string]string { + t.Helper() + digest := map[string]string{} + err := filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error { + if err != nil { + return err + } + rel, err := filepath.Rel(root, path) + if err != nil { + return err + } + if d.IsDir() { + digest[rel] = "dir" + return nil + } + content, err := os.ReadFile(path) + if err != nil { + return err + } + digest[rel] = "file:" + string(content) + return nil + }) + if err != nil { + t.Fatalf("digest %s: %v", root, err) + } + return digest +} + +// TestPublicOpensRefuseGraphWorkspace is the library half of the graph_mode +// fence the CLI applies at admission: every public open of a workspace whose +// metadata or graph-preview-format marker declares another data model refuses +// it with the typed error before it opens, creates or modifies anything, in +// the workspace or beside it (the workspace gate file OpenGated takes lives +// beside .beads). +func TestPublicOpensRefuseGraphWorkspace(t *testing.T) { + // If the fence were missing, a server-mode open must fail fast rather + // than reach TestMain's shared test server. + t.Setenv("BEADS_DOLT_SERVER_HOST", "127.0.0.1") + t.Setenv("BEADS_DOLT_SERVER_PORT", "1") + layouts := []struct { + name string + filename string // "" writes no metadata file + metadata string + mode string + embedded bool + // marker writes the graph-preview-format marker graph-preview builds + // leave in .beads; the refusal then names the marker, not a mode. + marker bool + }{ + {name: "link embedded", filename: "metadata.json", metadata: graphWorkspaceMetadata, mode: "link", embedded: true}, + {name: "link server", filename: "metadata.json", metadata: `{"backend":"dolt","dolt_mode":"server","dolt_database":"beads_graph_0123","graph_mode":"link"}`, mode: "link"}, + {name: "unknown marker", filename: "metadata.json", metadata: `{"backend":"dolt","graph_mode":"future-format"}`, mode: "future-format"}, + // A refused open must not migrate a legacy config.json either. + {name: "link legacy config.json", filename: "config.json", metadata: graphWorkspaceMetadata, mode: "link", embedded: true}, + // A graph workspace whose metadata was never written, was lost, or + // was rewritten without graph_mode is still declared by the marker. + {name: "marker only", marker: true}, + {name: "marker beside stripped metadata", filename: "metadata.json", metadata: graphWorkspaceMetadataStripped, embedded: true, marker: true}, + {name: "marker beside stripped legacy config.json", filename: "config.json", metadata: graphWorkspaceMetadataStripped, embedded: true, marker: true}, + {name: "marker beside server metadata", filename: "metadata.json", metadata: `{"backend":"dolt","dolt_mode":"server","dolt_database":"beads_graph_0123"}`, marker: true}, + {name: "marker beside dependency metadata", filename: "metadata.json", metadata: `{"backend":"dolt","dolt_mode":"server","graph_mode":"dependency"}`, marker: true}, + {name: "marker beside unparseable metadata", filename: "metadata.json", metadata: `{"backend":"dolt",`, marker: true}, + } + for _, layout := range layouts { + for name, open := range publicOpens { + t.Run(layout.name+"/"+name, func(t *testing.T) { + root := t.TempDir() + beadsDir := filepath.Join(root, ".beads") + if err := os.MkdirAll(beadsDir, 0o750); err != nil { + t.Fatal(err) + } + if layout.filename != "" { + if err := os.WriteFile(filepath.Join(beadsDir, layout.filename), []byte(layout.metadata), 0o600); err != nil { + t.Fatal(err) + } + } + if layout.marker { + if err := os.WriteFile(filepath.Join(beadsDir, "graph-preview-format"), []byte("link-preview-v9\n"), 0o600); err != nil { + t.Fatal(err) + } + } + if layout.embedded { + graphDB := filepath.Join(beadsDir, "embeddeddolt", "beads_graph_0123456789abcdef0123456789abcdef", ".dolt") + if err := os.MkdirAll(graphDB, 0o750); err != nil { + t.Fatal(err) + } + } + before := workspaceTreeDigest(t, root) + + // Check err, not store: a failed OpenFromConfig can return a + // typed-nil store. + store, err := open(t.Context(), beadsDir) + if err == nil { + _ = store.Close() + t.Fatalf("%s opened a graph_mode %q workspace", name, layout.mode) + } + var formatErr *beads.UnsupportedWorkspaceFormatError + if !errors.As(err, &formatErr) { + t.Fatalf("%s error = %v, want *beads.UnsupportedWorkspaceFormatError", name, err) + } + if formatErr.BeadsDir != beadsDir || formatErr.GraphMode != layout.mode || formatErr.FormatMarker != layout.marker { + t.Fatalf("refusal = %+v, want BeadsDir %q, GraphMode %q and FormatMarker %v", formatErr, beadsDir, layout.mode, layout.marker) + } + if layout.marker && !strings.Contains(err.Error(), "graph-preview-format marker") { + t.Fatalf("refusal does not name the format marker: %v", err) + } + if !strings.Contains(err.Error(), "no storage database was opened or modified") { + t.Fatalf("refusal lacks the data-safety guarantee: %v", err) + } + if after := workspaceTreeDigest(t, root); !maps.Equal(after, before) { + t.Fatalf("%s changed the workspace: before %v, after %v", name, slices.Sorted(maps.Keys(before)), slices.Sorted(maps.Keys(after))) + } + }) + } + } +} + +// TestPublicOpensAdmitDependencyWorkspace pins the other side of the fence: a +// "dependency" marker is the ordinary Issue workspace, so the open proceeds to +// its backend (here, a server nothing listens on) instead of being refused. +func TestPublicOpensAdmitDependencyWorkspace(t *testing.T) { + t.Setenv("BEADS_DOLT_SERVER_HOST", "127.0.0.1") + t.Setenv("BEADS_DOLT_SERVER_PORT", "1") + for name, open := range publicOpens { + t.Run(name, func(t *testing.T) { + beadsDir := filepath.Join(t.TempDir(), ".beads") + if err := os.MkdirAll(beadsDir, 0o750); err != nil { + t.Fatal(err) + } + metadata := `{"backend":"dolt","dolt_mode":"server","graph_mode":"dependency"}` + if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), []byte(metadata), 0o600); err != nil { + t.Fatal(err) + } + store, err := open(t.Context(), beadsDir) + if err == nil { + _ = store.Close() + t.Fatalf("%s opened a store on an unreachable server", name) + } + var formatErr *beads.UnsupportedWorkspaceFormatError + if errors.As(err, &formatErr) || !strings.Contains(err.Error(), "unreachable") { + t.Fatalf("%s error = %v, want the backend's unreachable-server error", name, err) + } + }) + } +}