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) <noreply@anthropic.com>
This commit is contained in:
Julian Knutsen 2026-10-20 07:25:38 +00:00 • committed by GitHub
commit bc1cd64c78
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 469 additions and 93 deletions

View file

@ -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

View file

@ -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

View file

@ -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 "<project>/.beads", so we start from <project>'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)
}

View file

@ -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
}

View file

@ -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, " "))
}
})
}
}
}

View file

@ -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) {

View file

@ -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())
}
}
})
}

View file

@ -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 {

View file

@ -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)
}
})
}
}