fix(init): admit a server workspace whose .beads/dolt is empty so the version marker is written (#6935)

A server-mode workspace with an empty .beads/dolt and no .local_version was refused as a legacy workspace, blocking every command including bd init. An empty directory holds no legacy data, so the guard now admits it (server mode only); bd init writes the marker and an existing workspace in that state self-heals on its next command. Refs #5682.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Julian Knutsen 2026-09-29 02:11:21 -07:00 • committed by GitHub
commit e3a12f4e5c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 340 additions and 19 deletions

View file

@ -79,6 +79,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
A token that was already pushed should still be rotated: deleting the row
locally does not unpublish it from remotes that already have a copy.
- **A server-mode workspace with an empty `.beads/dolt` is no longer refused
as legacy**
([#5682](https://github.com/gastownhall/beads/issues/5682),
[#6935](https://github.com/gastownhall/beads/pull/6935)). bd creates `.beads/dolt` on use even when the data lives on an
external Dolt server, and leaves it empty. When the gitignored
`.local_version` witness was missing — after a fresh checkout, or when a
provisioner created the empty root before `bd init --server --external` —
the legacy-upgrade guard refused every command, `bd init` included, as a
"legacy Dolt server workspace", and no bd command could repair it. An empty
root holds nothing a legacy release could have left, so the guard now admits
it: `bd init` writes the witness, and an existing workspace in that state
re-seeds it on the next command. A pre-1.0 witness, or a `.beads/dolt` that
holds anything, is still refused.
- **`bd -C dir prime` now describes the target workspace instead of the launch
directory** ([#5509](https://github.com/gastownhall/beads/issues/5509)). `-C`
resolves `BEADS_DIR` but never changes directory, so prime's cwd-relative

View file

@ -826,6 +826,8 @@ go_test(
"last_touched_test.go",
"legacy_upgrade_guard_config_yaml_test.go",
"legacy_upgrade_guard_e2e_test.go",
"legacy_upgrade_guard_empty_root_test.go",
"legacy_upgrade_guard_external_server_test.go",
"legacy_upgrade_guard_test.go",
"legacy_upgrade_guard_witness_test.go",
"linear_roundtrip_test.go",

View file

@ -76,6 +76,20 @@ func guardLegacyUpgradeWorkspace(beadsDir string) error {
return nil
}
if serverMode {
if !present && isEmptyDirectory(filepath.Join(beadsDir, "dolt")) {
// An empty .beads/dolt holds no Dolt data, so no legacy release
// could have left anything in it to protect: it carries no more
// evidence than a server workspace without that directory, which
// is admitted above. bd creates exactly this shape itself — the
// local Dolt root is made on use even when the data lives on an
// external server — so refusing it made `bd init --server
// --external` fail over a provisioner's empty root, and made a
// workspace that lost its gitignored witness unusable with no bd
// command able to repair it. Admitting it lets the command re-seed
// the witness. A present pre-1.0 witness was refused above, and a
// root holding anything at all still refuses below.
return nil
}
if present && classifyVersionWitness(version) == witnessEraUnknown {
// A witness that is present but unreadable — including one left
// blank or whitespace-only by an interrupted or disk-full
@ -270,6 +284,22 @@ func hasLegacyDoltRoot(beadsDir string) bool {
return err == nil && info.IsDir() && info.Mode()&os.ModeSymlink == 0
}
// isEmptyDirectory reports whether path is a real (non-symlink) directory with
// no entries. Any error reading it answers false, so callers fail closed.
func isEmptyDirectory(path string) bool {
info, err := os.Lstat(path)
if err != nil || !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
return false
}
dir, err := os.Open(path) // #nosec G304 -- bounded probe beneath selected workspace
if err != nil {
return false
}
defer func() { _ = dir.Close() }()
names, err := dir.Readdirnames(1)
return len(names) == 0 && err == io.EOF
}
func isNonEmptyRegularFile(path string) bool {
info, err := os.Lstat(path)
return err == nil && info.Mode().IsRegular() && info.Size() > 0

View file

@ -31,7 +31,7 @@ func bindSelectedWorkspaceConfig(t *testing.T, beadsDir string) {
}
// writeDoltRootWorkspace lays down the ambiguous shape the guard classifies: a
// .beads directory that owns a local Dolt root, plus whatever metadata.json,
// .beads directory that owns a populated local Dolt root, plus whatever metadata.json,
// config.yaml and version witness the case needs. An empty string means "do not
// write this file at all".
func writeDoltRootWorkspace(t *testing.T, metadata, configYaml, version string) string {
@ -52,9 +52,7 @@ func writeDoltRootWorkspace(t *testing.T, metadata, configYaml, version string)
t.Fatal(err)
}
}
if err := os.Mkdir(filepath.Join(beadsDir, "dolt"), 0o700); err != nil {
t.Fatal(err)
}
populateLegacyDoltRoot(t, beadsDir)
bindSelectedWorkspaceConfig(t, beadsDir)
return beadsDir
}

View file

@ -490,7 +490,7 @@ func TestLegacyGuardUsesSelectedTargetSharedServerConfig(t *testing.T) {
// TestLegacyGuardAdmitsConfigYamlServerWorkspace runs the real binary against
// the workspace shape gc provisions — `dolt.mode: server` in
// .beads/config.yaml, a local .beads/dolt root, a metadata.json that names no
// .beads/config.yaml, a populated local .beads/dolt root, a metadata.json that names no
// dolt_mode — and pins that the guard no longer calls it legacy. The in-process
// guard tests bind the workspace config themselves; only a subprocess proves
// that PersistentPreRunE's own binding puts the selected workspace's
@ -518,9 +518,7 @@ func TestLegacyGuardAdmitsConfigYamlServerWorkspace(t *testing.T) {
repoDir := t.TempDir()
initGitRepo(t, repoDir)
beadsDir := filepath.Join(repoDir, ".beads")
if err := os.MkdirAll(filepath.Join(beadsDir, "dolt"), 0o700); err != nil {
t.Fatal(err)
}
populateLegacyDoltRoot(t, beadsDir)
writeFile(t, filepath.Join(beadsDir, "metadata.json"), []byte(`{"backend":"dolt","dolt_database":"hq"}`))
writeFile(t, filepath.Join(beadsDir, "config.yaml"), []byte("dolt:\n mode: server\n auto-start: false\n"))
if tt.version != "" {

View file

@ -0,0 +1,143 @@
package main
import (
"os"
"path/filepath"
"testing"
)
// populateLegacyDoltRoot lays down a .beads/dolt root that holds a Dolt
// database, the shape a historical local sql-server left behind. The guard has
// to treat such a root as evidence worth protecting.
func populateLegacyDoltRoot(t *testing.T, beadsDir string) {
t.Helper()
if err := os.MkdirAll(filepath.Join(beadsDir, "dolt", "beads", ".dolt"), 0o700); err != nil {
t.Fatal(err)
}
}
// writeEmptyDoltRootServerWorkspace lays down the shape a current bd leaves
// behind after `bd init --server --external`: server mode selected, a
// .beads/dolt directory that bd created on use but that holds nothing because
// the data lives on the external server, and — once the gitignored witness has
// been lost, or when a provisioner created the empty root before bd init —
// no .local_version.
func writeEmptyDoltRootServerWorkspace(t *testing.T, metadata, configYaml, version string) string {
t.Helper()
beadsDir := t.TempDir()
for name, contents := range map[string]string{
"metadata.json": metadata,
"config.yaml": configYaml,
} {
if contents == "" {
continue
}
if err := os.WriteFile(filepath.Join(beadsDir, name), []byte(contents), 0o600); err != nil {
t.Fatal(err)
}
}
if version != "" {
if err := writeLocalVersion(filepath.Join(beadsDir, localVersionFile), version); err != nil {
t.Fatal(err)
}
}
if err := os.Mkdir(filepath.Join(beadsDir, "dolt"), 0o700); err != nil {
t.Fatal(err)
}
bindSelectedWorkspaceConfig(t, beadsDir)
return beadsDir
}
const externalServerMetadata = `{"backend":"dolt","dolt_mode":"server","dolt_server_host":"db.example.test","dolt_database":"ext_db"}`
// TestLegacyUpgradeGuardAdmitsServerWorkspaceWithEmptyDoltRoot pins the
// external-host recovery: a server-mode workspace whose .beads/dolt is empty
// and whose witness is missing holds no local Dolt data a legacy release could
// have left there, so it carries no more evidence than a workspace with no
// .beads/dolt at all — which the guard already admits. Refusing it made the
// workspace unusable after `bd init --server --external` whenever the witness
// was absent, with no bd command able to repair it.
func TestLegacyUpgradeGuardAdmitsServerWorkspaceWithEmptyDoltRoot(t *testing.T) {
cases := []struct {
name string
metadata string
configYaml string
}{
{name: "metadata.json external server", metadata: externalServerMetadata},
{name: "metadata.json server", metadata: `{"backend":"dolt","dolt_mode":"server"}`},
{name: "config.yaml server mode", configYaml: configYamlServerMode},
// Proxied-server does not select server mode, so it never reaches the
// empty-root branch; it is admitted by the final non-embedded arm. Pin
// that so a later change to either arm cannot start refusing it.
{name: "metadata.json proxied server", metadata: `{"backend":"dolt","dolt_mode":"proxied-server"}`},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
warnings := captureLegacyUpgradeWarnings(t)
beadsDir := writeEmptyDoltRootServerWorkspace(t, tc.metadata, tc.configYaml, "")
if err := guardLegacyUpgradeWorkspace(beadsDir); err != nil {
t.Fatalf("guardLegacyUpgradeWorkspace() = %v, want nil", err)
}
if warnings.Len() != 0 {
t.Fatalf("guard warned about an absent witness: %q", warnings.String())
}
})
}
}
// TestLegacyUpgradeGuardEmptyDoltRootAdmissionStaysNarrow proves the empty-root
// admission relaxes nothing else: pre-1.0 evidence still refuses, a root that
// holds anything still refuses, and outside server mode an empty root is still
// the legacy embedded shape.
func TestLegacyUpgradeGuardEmptyDoltRootAdmissionStaysNarrow(t *testing.T) {
t.Run("historical server witness", func(t *testing.T) {
captureLegacyUpgradeWarnings(t)
beadsDir := writeEmptyDoltRootServerWorkspace(t, externalServerMetadata, "", "0.62.0")
if err := guardLegacyUpgradeWorkspace(beadsDir); !isLegacyUpgradeRefusal(err) {
t.Fatalf("guardLegacyUpgradeWorkspace() = %v, want migration refusal", err)
}
})
t.Run("historical embedded witness", func(t *testing.T) {
captureLegacyUpgradeWarnings(t)
beadsDir := writeEmptyDoltRootServerWorkspace(t, externalServerMetadata, "", "0.49.6")
if err := guardLegacyUpgradeWorkspace(beadsDir); !isLegacyUpgradeRefusal(err) {
t.Fatalf("guardLegacyUpgradeWorkspace() = %v, want migration refusal", err)
}
})
for _, entry := range []string{"beads", ".dolt", "stray-file"} {
t.Run("root holding "+entry, func(t *testing.T) {
captureLegacyUpgradeWarnings(t)
beadsDir := writeEmptyDoltRootServerWorkspace(t, externalServerMetadata, "", "")
path := filepath.Join(beadsDir, "dolt", entry)
var err error
if entry == "stray-file" {
err = os.WriteFile(path, nil, 0o600)
} else {
err = os.Mkdir(path, 0o700)
}
if err != nil {
t.Fatal(err)
}
if err := guardLegacyUpgradeWorkspace(beadsDir); !isLegacyUpgradeRefusal(err) {
t.Fatalf("guardLegacyUpgradeWorkspace() = %v, want migration refusal", err)
}
})
}
for _, metadata := range []string{`{"backend":"dolt"}`, `{"backend":"dolt","dolt_mode":"embedded"}`} {
t.Run("embedded "+metadata, func(t *testing.T) {
captureLegacyUpgradeWarnings(t)
beadsDir := writeEmptyDoltRootServerWorkspace(t, metadata, "", "")
if err := guardLegacyUpgradeWorkspace(beadsDir); !isLegacyUpgradeRefusal(err) {
t.Fatalf("guardLegacyUpgradeWorkspace() = %v, want migration refusal", err)
}
})
}
}

View file

@ -0,0 +1,141 @@
//go:build cgo
package main
import (
"context"
"fmt"
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
"time"
)
// runExternalServerBD runs the bd binary under test in repoDir with env and
// returns its combined output.
func runExternalServerBD(t *testing.T, repoDir string, env []string, args ...string) (string, error) {
t.Helper()
ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
defer cancel()
cmd := exec.CommandContext(ctx, buildBDUnderTest(t), args...)
cmd.Dir = repoDir
cmd.Env = env
out, err := cmd.CombinedOutput()
if ctxErr := ctx.Err(); ctxErr != nil {
t.Fatalf("bd %s did not finish before the deadline: %v\n%s", strings.Join(args, " "), ctxErr, out)
}
return string(out), err
}
// externalServerTestEnv isolates a bd child from the developer's home and
// config (a real ~/.beads may select a shared server) and from the ambient
// BEADS_DOLT_* endpoint this package's TestMain exports, so only the flags and
// files under test choose the target.
func externalServerTestEnv(t *testing.T) []string {
t.Helper()
home := t.TempDir()
return append(envWithoutBeadsStorageSettings(),
"HOME="+home,
"XDG_CONFIG_HOME="+filepath.Join(home, ".config"),
"BEADS_TEST_IGNORE_REPO_CONFIG=1",
"BD_DISABLE_METRICS=1",
"BEADS_DOLT_AUTO_START=0",
)
}
func externalServerInitArgs(database string, extra ...string) []string {
args := []string{
"init", "--quiet", "--server", "--external",
"--server-host", "127.0.0.1",
"--server-port", fmt.Sprintf("%d", testDoltServerPort),
"--database", database,
"--prefix", "ext",
"--skip-hooks", "--skip-agents",
}
return append(args, extra...)
}
func assertCurrentVersionWitness(t *testing.T, beadsDir string) {
t.Helper()
data, err := os.ReadFile(filepath.Join(beadsDir, localVersionFile))
if err != nil {
t.Fatalf("expected %s after the command: %v", localVersionFile, err)
}
if got := strings.TrimSpace(string(data)); got != Version {
t.Fatalf("%s = %q, want %q", localVersionFile, got, Version)
}
}
// TestExternalServerInitWritesWitnessOverEmptyDoltRoot reproduces the
// provisioner shape: config.yaml already selects server mode and an empty
// .beads/dolt exists before `bd init --server --external` runs. The legacy
// guard used to refuse that init as a "legacy Dolt server workspace", so the
// scope never got a witness and every later command was refused too.
func TestExternalServerInitWritesWitnessOverEmptyDoltRoot(t *testing.T) {
skipIfNoDolt(t)
env := externalServerTestEnv(t)
repoDir := t.TempDir()
initGitRepo(t, repoDir)
beadsDir := filepath.Join(repoDir, ".beads")
if err := os.MkdirAll(filepath.Join(beadsDir, "dolt"), 0o700); err != nil {
t.Fatal(err)
}
writeFile(t, filepath.Join(beadsDir, "config.yaml"), []byte("dolt.mode: server\n"))
database := uniqueTestDBName(t)
t.Cleanup(func() { dropTestDatabase(database, testDoltServerPort) })
out, err := runExternalServerBD(t, repoDir, append(env, "BEADS_DIR="+beadsDir),
externalServerInitArgs(database, "--init-if-missing")...)
if err != nil {
t.Fatalf("bd init --server --external over an empty .beads/dolt failed: %v\n%s", err, out)
}
assertCurrentVersionWitness(t, beadsDir)
}
// TestExternalServerWorkspaceRecoversMissingWitness covers a workspace already
// in the broken state: initialized against an external server, then left
// without .local_version (it is gitignored, so a fresh checkout or a cleanup
// drops it) while bd's own empty .beads/dolt remains. The next ordinary
// command must open the workspace and re-seed the witness with no manual
// steps.
func TestExternalServerWorkspaceRecoversMissingWitness(t *testing.T) {
skipIfNoDolt(t)
env := externalServerTestEnv(t)
repoDir := t.TempDir()
initGitRepo(t, repoDir)
beadsDir := filepath.Join(repoDir, ".beads")
database := uniqueTestDBName(t)
t.Cleanup(func() { dropTestDatabase(database, testDoltServerPort) })
out, err := runExternalServerBD(t, repoDir, env, externalServerInitArgs(database)...)
if err != nil {
t.Fatalf("bd init --server --external failed: %v\n%s", err, out)
}
assertCurrentVersionWitness(t, beadsDir)
entries, err := os.ReadDir(filepath.Join(beadsDir, "dolt"))
if err != nil {
t.Fatalf("precondition: expected bd init to leave a .beads/dolt directory: %v", err)
}
if len(entries) != 0 {
t.Fatalf("precondition: expected an empty .beads/dolt for an external server, found %d entries", len(entries))
}
if err := os.Remove(filepath.Join(beadsDir, localVersionFile)); err != nil {
t.Fatal(err)
}
out, err = runExternalServerBD(t, repoDir, env, "list", "--json", "--all")
if err != nil {
t.Fatalf("bd list on an external-server workspace without a witness failed: %v\n%s", err, out)
}
if strings.Contains(out, "explicit migration is required") {
t.Fatalf("bd list reported a legacy-upgrade refusal:\n%s", out)
}
assertCurrentVersionWitness(t, beadsDir)
}

View file

@ -206,14 +206,12 @@ func TestLegacyUpgradeGuardMetadataLessSQLiteAndCurrentEmbeddedPrecedence(t *tes
}
})
t.Run("explicit server metadata with missing version witness and local Dolt root is refused", func(t *testing.T) {
t.Run("explicit server metadata with missing version witness and populated local Dolt root is refused", func(t *testing.T) {
beadsDir := t.TempDir()
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), []byte(`{"backend":"dolt","dolt_mode":"server"}`), 0o600); err != nil {
t.Fatal(err)
}
if err := os.Mkdir(filepath.Join(beadsDir, "dolt"), 0o700); err != nil {
t.Fatal(err)
}
populateLegacyDoltRoot(t, beadsDir)
if err := guardLegacyUpgradeWorkspace(beadsDir); !isLegacyUpgradeRefusal(err) {
t.Fatalf("guardLegacyUpgradeWorkspace() = %v, want migration refusal", err)
}
@ -290,9 +288,7 @@ func TestLegacyUpgradeGuardServerSelectionBeatsStaleEmbeddedRepository(t *testin
t.Fatal(err)
}
}
if err := os.Mkdir(filepath.Join(beadsDir, "dolt"), 0o700); err != nil {
t.Fatal(err)
}
populateLegacyDoltRoot(t, beadsDir)
staleRepo := filepath.Join(beadsDir, "embeddeddolt", "stale", ".dolt")
if err := os.MkdirAll(staleRepo, 0o700); err != nil {
t.Fatal(err)

View file

@ -84,7 +84,8 @@ func TestLegacyServerVersionSpansHistoricalServerEra(t *testing.T) {
}
// writeSelectedServerWorkspace lays down the ambiguous shape the guard has to
// classify: a selected Dolt server workspace that still owns a local Dolt root.
// classify: a selected Dolt server workspace that still owns a populated local
// Dolt root.
func writeSelectedServerWorkspace(t *testing.T, version string) string {
t.Helper()
beadsDir := t.TempDir()
@ -97,9 +98,7 @@ func writeSelectedServerWorkspace(t *testing.T, version string) string {
t.Fatal(err)
}
}
if err := os.Mkdir(filepath.Join(beadsDir, "dolt"), 0o700); err != nil {
t.Fatal(err)
}
populateLegacyDoltRoot(t, beadsDir)
return beadsDir
}