Merge origin/main into bee/wy-j2upyy-gated-render (be-lpi unresolvable-dep notice)

wy-j2upyy: resolve the three conflicts with be-lpi's unresolvable-edge
notice. types.go keeps both additive IssueDetails fields (gated_by and
unresolvable_dependencies/dependents). In both show renders the hoisted
dependency read that decorates the GATED header now also reads the counts
FIRST (readDepCounts order convention) and keeps the listing's error, so
warnUnresolvableDepEdges below sees the same snapshot pair main gives it.

Ran: go build ./...; go vet ./cmd/bd/ ./internal/types/;
go test -run 'Gated|GatesHolding|GateRef|Unresolvable|DepCount|ReadDepCounts|Show'
./cmd/bd/ ./internal/types/ ./internal/workapi/ — ok.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Bee 2026-10-01 01:53:47 -07:00
commit d21237f3dc
260 changed files with 19735 additions and 862 deletions

View file

@ -8,7 +8,8 @@
# in this mode, for CI_GATE_SKIPPED_OK:
# skip: every lane and the aggregate (BAZEL)
# local: the remote-only BAZEL_EMBEDDED,
# BAZEL_PROXIED, BAZEL_SERVER_STORAGE
# BAZEL_INTEGRATION, BAZEL_PROXIED,
# BAZEL_SERVER_STORAGE
# remote: none
# bazel-gate.sh aggregate the value to gate on for BAZEL: the call's
# aggregate result, or, when the mode is missing
@ -36,8 +37,8 @@ case "${1:-}" in
skips=()
if [[ "$valid" == true ]]; then
case "$mode" in
skip) skips+=(BAZEL BAZEL_TEST BAZEL_PURE BAZEL_EMBEDDED BAZEL_DOLTSERVER BAZEL_PROXIED BAZEL_SERVER_STORAGE) ;;
local) skips+=(BAZEL_EMBEDDED BAZEL_PROXIED BAZEL_SERVER_STORAGE) ;;
skip) skips+=(BAZEL BAZEL_TEST BAZEL_PURE BAZEL_EMBEDDED BAZEL_INTEGRATION BAZEL_DOLTSERVER BAZEL_PROXIED BAZEL_SERVER_STORAGE) ;;
local) skips+=(BAZEL_EMBEDDED BAZEL_INTEGRATION BAZEL_PROXIED BAZEL_SERVER_STORAGE) ;;
esac
fi
echo "${skips[*]-}"

View file

@ -8,10 +8,11 @@
#
# ADVISORY. pr.yml is unchanged: every fork PR, listed or not, still runs the
# local Bazel lanes inside the enforced `CI Gate / Required`. This run adds a
# fast remote signal, including the remote-only embedded, proxied-server and
# server-storage tiers, that no required check and no privileged workflow
# reads. Making it authoritative needs a trusted reporter; see
# engdocs/CI_REQUIRED_CHECK_TOPOLOGY.md, "Trusted-author fork PRs".
# fast remote signal, including the remote-only embedded, integration,
# proxied-server and server-storage tiers, that no required check and no
# privileged workflow reads. Making it authoritative needs a trusted
# reporter; see engdocs/CI_REQUIRED_CHECK_TOPOLOGY.md, "Trusted-author fork
# PRs".
#
# SECURITY MODEL (policy-tested in scripts/ci_workflow_test.go,
# TestBazelFarmWorkflowSecurity; threat model in the engdoc):
@ -128,5 +129,5 @@ jobs:
with:
checkout-sha: ${{ github.event.pull_request.head.sha }}
fork-farm: authorized
integration: "off"
integration: "on"
build-artifact-name: bazel-farm-build-artifacts

View file

@ -10,16 +10,19 @@
# runs the lane once. Every lane reports its job.status as a workflow_call
# output (named after the job) from an always() last step. pr.yml's ci-gate
# requires the call's aggregate result (BAZEL) and bazel-test, bazel-pure,
# bazel-embedded, bazel-doltserver, bazel-proxied and bazel-server-storage
# (BAZEL_TEST, BAZEL_PURE, BAZEL_EMBEDDED, BAZEL_DOLTSERVER, BAZEL_PROXIED,
# BAZEL_SERVER_STORAGE); .github/scripts/bazel-gate.sh turns the rbe job's
# rbe-mode output into the skips it accepts, so a lane skipped by its `if:`
# below passes and one that should have run and failed, was cancelled or
# reported nothing fails the gate. bazel-integration is not part of the PR
# call (pr.yml passes integration: "off"): its legacy counterparts, main.yml's
# integration jobs, run only on push to main, so it runs on push to main,
# dispatch and nightly, like them. Direct runs (push to main,
# workflow_dispatch, nightly.yml's call) gate nothing.
# bazel-embedded, bazel-integration, bazel-doltserver, bazel-proxied and
# bazel-server-storage (BAZEL_TEST, BAZEL_PURE, BAZEL_EMBEDDED,
# BAZEL_INTEGRATION, BAZEL_DOLTSERVER, BAZEL_PROXIED, BAZEL_SERVER_STORAGE);
# .github/scripts/bazel-gate.sh turns the rbe job's rbe-mode output into the
# skips it accepts, so a lane skipped by its `if:` below passes and one that
# should have run and failed, was cancelled or reported nothing fails the
# gate. bazel-integration runs in the PR call (pr.yml passes integration:
# "on") although its legacy counterparts, main.yml's integration jobs, run
# only on push to main: remotely it is minutes, and it catches on the PR what
# main.yml would catch after the merge. Like every remote-only lane it skips
# for fork and Dependabot PRs (mode local); forks get it once the farm has a
# read-only cache for them. Direct runs (push to main, workflow_dispatch,
# nightly.yml's call) gate nothing.
#
# Execution mode, decided once by the rbe job (every other job needs it and
# reads its outputs; none re-derives the condition) and passed to
@ -130,8 +133,8 @@ on:
# test would silently stop the lane on main.
integration:
description: >
"off" skips bazel-integration (pr.yml: its legacy counterparts do
not run on PRs); anything else runs it where remote execution is on.
"off" skips bazel-integration; anything else (pr.yml and
bazel-farm.yml pass "on") runs it where remote execution is on.
type: string
required: false
default: "on"
@ -192,7 +195,7 @@ on:
description: "bazel-embedded's job.status"
value: ${{ jobs.bazel-embedded.outputs.result }}
bazel-integration:
description: "bazel-integration's job.status (empty in pr.yml's call, which turns the lane off)"
description: "bazel-integration's job.status"
value: ${{ jobs.bazel-integration.outputs.result }}
bazel-doltserver:
description: "bazel-doltserver's job.status"
@ -737,17 +740,19 @@ jobs:
# selection (go list without the integration tag, -short, ^TestEmbedded
# skipped), and its job mode needs the integration jobs' go test -json,
# which no run here has. check_testcases.py still catches a target or
# shard that ran no tests.
# shard that ran no tests. pr.yml's gate requires it (BAZEL_INTEGRATION)
# on same-repo PRs; see the header.
bazel-integration:
name: integration (advisory)
name: integration
# Remote execution only, like bazel-embedded: locally the tagged race
# build of //... plus 14 jobs' worth of tests on one runner is well over
# the timeout, for tests main.yml's integration jobs already run. Off in
# pr.yml's call (integration: "off"), as those jobs are off on PRs.
# the timeout, for tests main.yml's integration jobs already run. A
# caller may turn it off with integration: "off"; pr.yml and
# bazel-farm.yml pass "on".
needs: rbe
runs-on: ${{ needs.rbe.outputs.enabled == 'true' && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
if: ${{ needs.rbe.outputs.enabled == 'true' && inputs.integration != 'off' }}
timeout-minutes: 40
timeout-minutes: 55
outputs:
result: ${{ steps.result.outputs.result }}
steps:
@ -770,11 +775,13 @@ jobs:
RBE_TLS_CA: ${{ needs.rbe.outputs.enabled == 'true' && secrets.RBE_TLS_CA || '' }}
RBE_INSTANCE: ${{ needs.rbe.outputs.enabled == 'true' && 'oss' || '' }}
# Remote: a cold compile plus the longest test action (1200s cap, see
# .bazelrc) fits well inside 30 minutes.
# Remote: a cold compile (a PR touching a widely imported package; the
# first cold run took 17 minutes end to end, warm ones ~3.5) plus the
# longest test action (1200s cap, see .bazelrc) if it starts last.
# scripts/ci_workflow_test.go keeps this at or above that sum.
- name: bazel test //... --config=integration
id: test
timeout-minutes: 30
timeout-minutes: 45
run: |
set -o pipefail
start=$(date +%s)
@ -803,8 +810,9 @@ jobs:
if-no-files-found: ignore
retention-days: 7
# Last step: the job's result as a workflow_call output (for
# symmetry; pr.yml's call turns this lane off).
# Last step: the job's result as a workflow_call output for pr.yml's
# ci-gate. always() runs it after a failure, a timeout or a
# cancellation too.
- name: Record job result
id: result
if: ${{ always() }}

View file

@ -134,7 +134,7 @@ jobs:
# -timeout=30m matches the macOS lanes this measures (pr.yml, main.yml).
# This is the job that produced the ./cmd/bd duration distribution, and
# at 10m it clips its own longest samples into timeout panics.
ci_time "macos short go test" -- go test -v -race -short -timeout=30m -skip '^TestEmbedded' ./...
ci_time "macos short go test" -- go test -tags=gms_pure_go -v -race -short -timeout=30m -skip '^TestEmbedded' ./...
macos-candidates:
name: Measure macOS no-short candidates
@ -499,7 +499,7 @@ jobs:
source scripts/ci/lib/timing.sh
source ./.buildflags
ci_time "build cmd/bd subprocess binary" -- go build -tags "$BEADS_BUILD_TAGS" -o artifacts/bd ./cmd/bd
ci_time "build cmd/bd subprocess binary" -- go build -tags gms_pure_go -o artifacts/bd ./cmd/bd
- name: Upload prebuilt bd
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
@ -667,7 +667,7 @@ jobs:
source scripts/ci/lib/timing.sh
source ./.buildflags
ci_time "build candidate binary" -- go build -o /tmp/bd-candidate ./cmd/bd
ci_time "build candidate binary" -- go build -tags gms_pure_go -o /tmp/bd-candidate ./cmd/bd
export CANDIDATE_BIN=/tmp/bd-candidate
if [[ -z "$SMOKE_VERSION" ]]; then
SMOKE_VERSION="$(gh release list --repo "$GITHUB_REPOSITORY" --limit 1 --json tagName --jq '.[0].tagName')"
@ -763,4 +763,3 @@ jobs:
path: artifacts/
retention-days: 7
if-no-files-found: ignore

View file

@ -93,9 +93,9 @@ jobs:
source ./.buildflags
go_version="$(go version)"
commit="$(git rev-parse HEAD)"
go build -tags "$BEADS_BUILD_TAGS" -o artifacts/bd-linux-gms-pure ./cmd/bd
go build -tags gms_pure_go -o artifacts/bd-linux-gms-pure ./cmd/bd
chmod +x artifacts/bd-linux-gms-pure
go test -tags "$BEADS_BUILD_TAGS" -c -o artifacts/bd-cmd-test ./cmd/bd
go test -tags gms_pure_go -c -o artifacts/bd-cmd-test ./cmd/bd
chmod +x artifacts/bd-cmd-test
(
cd artifacts
@ -130,9 +130,8 @@ jobs:
path: ${{ runner.temp }}/go-cache/non-race
key: beads-go-build-v2-${{ runner.os }}-${{ runner.arch }}-go-${{ steps.setup-go.outputs.go-version }}-base-gms_pure_go-non-race-${{ github.sha }}
# Fast check: every `go build|test|run|generate|install` invocation in
# tracked scripts/hooks/CI carries -tags=gms_pure_go. Prevents ICU-linkage
# regressions from re-entering the build (see engdocs/ICU-POLICY.md).
# Fast shell/Make guard for direct source-time build-tag declarations.
# Workflow `run` steps are checked structurally in the required policy wrapper.
check-build-tags:
name: Check build-tag policy
runs-on: ubuntu-latest
@ -140,6 +139,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
- run: ./scripts/check-build-tags.sh
- run: ./scripts/check-go-install-guidance.sh
- run: ./scripts/check-winget-portable-alias.sh
# Lock in the cgo-test-contamination fix (mybd-ycx / GH#3683 follow-up).
# cmd/bd carries a mix of cgo-only test helpers (embedded Dolt, sql.DB) and
@ -715,6 +715,13 @@ jobs:
- name: Test domain + uow + tracker
env:
BEADS_TEST_BD_BINARY: ${{ github.workspace }}/ci-build-artifacts/bd-linux-gms-pure
# internal/storage/domain, internal/storage/uow, and internal/tracker
# run as concurrent package test binaries in this one invocation.
# testcontainers-go shares one Ryuk reaper per host; a failed
# handshake in one process can reap a sibling's live Dolt container
# mid-suite (be-2on). The runner is destroyed after the job, so the
# reaper buys nothing here and only costs this race.
TESTCONTAINERS_RYUK_DISABLED: "true"
run: go test -tags gms_pure_go -race -count=1 -timeout 15m -v ./internal/storage/domain/... ./internal/storage/uow/... ./internal/tracker/...
# The doctor/fix DB-backed suite spins its own Dolt container in
@ -725,6 +732,9 @@ jobs:
env:
BEADS_TEST_BD_BINARY: ${{ github.workspace }}/ci-build-artifacts/bd-linux-gms-pure
BEADS_FIX_REQUIRE_DOLT: "1"
# Pinned for consistency with the step above: this single-package
# step has no sibling test binary to race for the reaper (be-2on).
TESTCONTAINERS_RYUK_DISABLED: "true"
run: go test -tags gms_pure_go -race -count=1 -timeout 10m -v ./cmd/bd/doctor/fix/
main-linux-integration-packages:

View file

@ -56,7 +56,7 @@ jobs:
source ./.buildflags
go_version="$(go version)"
commit="$(git rev-parse HEAD)"
go build -tags "$BEADS_BUILD_TAGS" -o artifacts/bd-linux-gms-pure ./cmd/bd
go build -tags gms_pure_go -o artifacts/bd-linux-gms-pure ./cmd/bd
chmod +x artifacts/bd-linux-gms-pure
(
cd artifacts
@ -154,9 +154,8 @@ jobs:
run: |
echo "::warning title=Example build check skipped::checkout or Go setup failed, so examples/ could not be checked this run (checkout: ${{ steps.checkout.outcome }}, setup-go: ${{ steps.setup-go.outcome }}). Advisory only; this does not block the merge."
# Fast check: every `go build|test|run|generate|install` invocation in
# tracked scripts/hooks/CI carries -tags=gms_pure_go. Prevents ICU-linkage
# regressions from re-entering the build (see engdocs/ICU-POLICY.md).
# Fast shell/Make guard for direct source-time build-tag declarations.
# Workflow `run` steps are checked structurally in the required policy wrapper.
check-build-tags:
name: Check build-tag policy
runs-on: ubuntu-latest
@ -164,6 +163,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
- run: ./scripts/check-build-tags.sh
- run: ./scripts/check-go-install-guidance.sh
- run: ./scripts/check-winget-portable-alias.sh
# Lock in two CGO-disabled portability boundaries. cmd/bd carries a mix of
# cgo-only test helpers (embedded Dolt, sql.DB) and pure-Go tests; compiling
@ -320,7 +320,9 @@ jobs:
# Ubuntu job above selects it by name but compiles it out, and main.yml's
# Windows job runs only on pushes to main (build/smoke, no go test). Run
# the liveness pair and native config fixture on Windows so their platform
# regressions actually execute at PR time.
# regressions actually execute at PR time. The init credential shell
# fixtures are a separate concern and run natively in
# pr-preflight-platforms, not here.
test-windows-liveness:
name: Test (Windows) cmd/bd liveness regression
runs-on: windows-latest
@ -560,7 +562,7 @@ jobs:
restore-keys: beads-go-mod-v2-${{ runner.os }}-${{ runner.arch }}-go-${{ steps.setup-go.outputs.go-version }}-
- name: Exercise native date and Bash process boundary
run: go test '-tags=integration,gms_pure_go' -count=1 -run '^TestDocFreshness' ./scripts
run: go test '-tags=integration,gms_pure_go' -count=1 -run '^(TestDocFreshness.*|TestRequiredSuiteContract)$' ./scripts -args -required-suite=doc-freshness
- name: Exercise repository text EOL policy boundary
run: go test '-tags=integration,gms_pure_go' -count=1 ./scripts/gitattributespolicy -args -required-host -expected-goos '${{ matrix.expected_goos }}'
@ -615,6 +617,10 @@ jobs:
shell: bash
run: go test '-tags=gms_pure_go' -count=1 -run '^TestGeneratedHookTimeoutProcessBoundary$' ./cmd/bd
- name: Exercise native init gateway credential shell
shell: bash
run: bash scripts/ci/test-init-gateway-credential.sh "$RUNNER_OS"
- name: Exercise credential command fixtures on Windows
if: matrix.os == 'windows-latest'
shell: pwsh
@ -1064,6 +1070,13 @@ jobs:
- name: Test domain + uow + tracker
env:
BEADS_TEST_BD_BINARY: ${{ github.workspace }}/ci-build-artifacts/bd-linux-gms-pure
# internal/storage/domain, internal/storage/uow, and internal/tracker
# run as concurrent package test binaries in this one invocation.
# testcontainers-go shares one Ryuk reaper per host; a failed
# handshake in one process can reap a sibling's live Dolt container
# mid-suite (be-2on). The runner is destroyed after the job, so the
# reaper buys nothing here and only costs this race.
TESTCONTAINERS_RYUK_DISABLED: "true"
run: go test -tags gms_pure_go -race -count=1 -timeout 15m -v ./internal/storage/domain/... ./internal/storage/uow/... ./internal/tracker/...
# The doctor/fix DB-backed suite spins its own Dolt container in
@ -1074,6 +1087,9 @@ jobs:
env:
BEADS_TEST_BD_BINARY: ${{ github.workspace }}/ci-build-artifacts/bd-linux-gms-pure
BEADS_FIX_REQUIRE_DOLT: "1"
# Pinned for consistency with the step above: this single-package
# step has no sibling test binary to race for the reaper (be-2on).
TESTCONTAINERS_RYUK_DISABLED: "true"
run: go test -tags gms_pure_go -race -count=1 -timeout 10m -v ./cmd/bd/doctor/fix/
# macOS-only regressions were landing on main undetected: main.yml's Test
@ -1757,10 +1773,11 @@ jobs:
# this call is its only PR run. It gets the four RBE secrets and nothing
# else; its rbe job decides remote, local (forks, Dependabot: no
# remote-only lanes) or skip, and exports that for ci-gate. Its
# bazel-integration lane is off here (main.yml's integration jobs, its
# legacy counterpart, run only on push to main; bazel.yml runs it there).
# Its bd artifact is renamed so it cannot collide with build-artifacts'
# upload.
# bazel-integration lane (main.yml's integration jobs, which run only on
# push to main) is on and required here, remote only: same-repo PRs run
# it, fork and Dependabot PRs (mode local) skip it until the farm has a
# read-only cache for them. Its bd artifact is renamed so it cannot
# collide with build-artifacts' upload.
bazel:
name: Bazel
permissions:
@ -1773,7 +1790,7 @@ jobs:
RBE_TLS_CA: ${{ secrets.RBE_TLS_CA }}
with:
build-artifact-name: bazel-ci-build-artifacts
integration: "off"
integration: "on"
ci-gate:
name: CI Gate / Required
@ -1838,6 +1855,7 @@ jobs:
BAZEL_TEST
BAZEL_PURE
BAZEL_EMBEDDED
BAZEL_INTEGRATION
BAZEL_DOLTSERVER
BAZEL_PROXIED
BAZEL_SERVER_STORAGE
@ -1870,6 +1888,7 @@ jobs:
BAZEL_TEST: ${{ needs.bazel.outputs.bazel-test || 'skipped' }}
BAZEL_PURE: ${{ needs.bazel.outputs.bazel-pure || 'skipped' }}
BAZEL_EMBEDDED: ${{ needs.bazel.outputs.bazel-embedded || 'skipped' }}
BAZEL_INTEGRATION: ${{ needs.bazel.outputs.bazel-integration || 'skipped' }}
BAZEL_DOLTSERVER: ${{ needs.bazel.outputs.bazel-doltserver || 'skipped' }}
BAZEL_PROXIED: ${{ needs.bazel.outputs.bazel-proxied || 'skipped' }}
BAZEL_SERVER_STORAGE: ${{ needs.bazel.outputs.bazel-server-storage || 'skipped' }}
@ -1885,9 +1904,9 @@ jobs:
skipped_ok="CHECK_NO_BEADS_CHANGES"
fi
# Bazel lanes skipped by design in the call's execution mode (all
# of them in mode skip, the remote-only embedded, proxied and
# server-storage tiers in mode local), and the aggregate unless the
# mode is missing or invalid.
# of them in mode skip, the remote-only embedded, integration,
# proxied and server-storage tiers in mode local), and the
# aggregate unless the mode is missing or invalid.
skipped_ok="$skipped_ok $(bash .github/scripts/bazel-gate.sh skips)"
BAZEL="$(bash .github/scripts/bazel-gate.sh aggregate)"
export BAZEL

View file

@ -12,6 +12,14 @@ load("@rules_go//go:def.bzl", "go_library", "go_test")
# gazelle:exclude integrations
gazelle(name = "gazelle")
exports_files(
[".buildflags"],
visibility = [
"//scripts/pr-lint:__pkg__",
"//scripts/prlintmake:__pkg__",
],
)
exports_files([
"go.mod",
"go.sum",

View file

@ -9,6 +9,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
- **`bd list` no longer silently drops all but the last repeated filter flag.**
`--status`, `--state`, and `--id` were plain string flags, so
`bd list --status open --status closed --status pinned` kept only `pinned` —
a census over 477 issues quietly answered over 3, with nothing in the output
to distinguish the narrowed answer from a correct one. Repeats of those three
flags now accumulate (duplicates collapse) instead of overwriting, so
`--status open --status closed` selects the same set as
`--status open,closed`. The one repeat that does not simply accumulate is one
involving `--status all`: `all` cannot be combined with other statuses, so
`--status all --status open` is now refused rather than narrowed to `open`.
`--type` and `--assignee` are single-valued all the way down — unioning would
fail type validation or exact-match nobody — so a repeat of either now refuses
loudly instead of silently keeping the last value:
`invalid argument "epic" for "-t, --type" flag: --type given more than once
(already "bug"); pass a single value`.
Single-flag and comma-form spellings behave exactly as before.
- **`bd restore`, `bd admin compact`, `bd repo <add|remove|list|sync>`,
`bd migrate [sync|hooks|schema]` and `bd preflight` no longer register a
local `--json` that shadows the root persistent flag.** pflag keeps a
command's own flag and drops the inherited one, so
`rootCmd.PersistentFlags().Changed("json")` stays false for that command;
[#6293](https://github.com/gastownhall/beads/pull/6293) compensated for that
per command by making the pre-run consult the subcommand's own `Changed` bit
before the root's. Deleting the eleven local registrations removes the
shadowing itself rather than working around it: `--json` moves to the Global
Flags section of those commands' `--help`, and a guard test now fails the
build if a command shadows the root flag again — closing the class before an
*unbound* local copy can reappear and invert the output mode it was meant to
select.
- **`bd init --force` can no longer silently recreate a missing server-side
database as empty** (be-5up5). `--force` is an alias for `--reinit-local`,
which skips the existing-data guard entirely, and the reinit path's own typed
confirmation keys on the issue count — which is 0 in exactly the case where
the database is missing. So `bd init --force` against a lost database created
a fresh empty one at the same name, with no prompt and no destroy token: the
2026-08-11 fleet-wide data-loss reflex, reached through the flag an operator
in a panic is most likely to try. The missing-database refusal now applies on
the reinit path too. `--force`/`--reinit-local` authorize destroying a
database that exists; only the explicit, per-invocation `--recreate-missing`
authorizes creating one where the configured database has gone missing.
- **`bd init --reinit-local` and `--force` no longer wave through a workspace
that predates `project_id`.** Their missing-database safety net returned
early whenever `.beads/metadata.json` carried no `project_id`, before it ever
probed for this project's local database directory — so a workspace
initialized before GH#2372 minted that field, whose local Dolt storage had
since been lost, was protected under plain `bd init` but not under the two
flags an operator reaches for in a panic. The probe now runs first and
unconditionally, and an absent `project_id` is allowed through only when
there is no local Dolt data directory either, matching the plain-`bd init`
guard. `--recreate-missing` still opens it. The signal decision behind both
guards is recorded in `engdocs/adr/0004-missing-database-guard-signal.md`.
- **`bd init --recreate-missing` now reaches its own opt-in.** The existing-data
check derived "is this project's database here?" from the Dolt data
directory, which exists on every initialized workspace, so the
missing-database branch was unreachable and both `--recreate-missing` opt-ins
behind it were dead code. Four surfaces — the flag help, `bd help
init-safety`, `docs/recovery/init-safety.md`, and the guard's own refusal
text — told the operator to run `bd init --recreate-missing --prefix <p>`;
that command exited 1 with a false "already initialized" message and pointed
back at `bd init --reinit-local`, which is the destructive path, leaving the
documented recovery circling between two refusals. The check now probes
`<dolt-data-dir>/<database>/.dolt`, the same probe the reinit-path guard
uses.
- **The missing-database guard probes this project's own database directory**
(`<dolt-data-dir>/<database>/.dolt`) rather than the Dolt data directory that
merely contains it. The data directory always exists on an initialized
workspace — shared-server mode creates the machine-global one on resolution,
and per-project mode creates it at init — so probing it made the guard a
no-op in shared-server mode, which is the topology of the 2026-08-11 loss.
User-visible wherever the data directory exists but the database is gone.
- **`BEADS_DOLT_POOL_READ_TIMEOUT` / `dolt.pool-read-timeout` (and the write
twins) now apply to every `bd` command in server mode.** The knobs shipped in
#5089, but their env/config ladder ran only for callers of `NewFromConfig*`;
@ -63,6 +139,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
its server through the proxy, so an ambient port does not describe its
lifecycle.
- **`bd` caps how large the auto-backup destination can grow, instead of
growing it forever** ([#6071](https://github.com/gastownhall/beads/pull/6071)).
`CALL DOLT_BACKUP('sync', ...)` only ever adds new chunks to the
destination — it never prunes ones that became unreachable on the source
(history rewrites, superseded data) — and Dolt exposes no supported way to
GC a backup destination in place. Left uncapped, the destination could
only grow until disk filled; this is the root cause of the 2026-06-19
outage, where a 1.7GB store produced a 43GB backup directory. Auto-backup
now pauses (nothing is deleted) once the destination reaches
`backup.size-cap-mb` (default 2048MB); set it to `0` to disable the cap
entirely. The pause is no longer stderr-only: `bd backup status` and its
`--json` output now report a `size_cap` object (`enabled`, `cap_mb`,
`current_bytes`, `exceeded`), so an agent/CI caller relying on `--json` or
`--quiet` can see that auto-backup has stopped instead of reading a
reassuring "Last backup" line while nothing further syncs. The remediation
advice no longer suggests deleting the backup directory — nothing
guarantees a deleted destination is cleanly recreated by the next sync, and
the server-side backup remote stays registered against that path; it now
points at `backup.size-cap-mb` / `bd backup init <new-path>` instead. The
size-cap check itself runs after both the interval throttle and change
detection, so it costs nothing on any path that is not about to sync — an
idle workspace never reaches it at all, and a paused destination re-arms
the interval throttle on the skip, so it is measured at most once per
`backup.interval` rather than on every command. `backup.size-warn-interval`
(default 24h) controls how often the pause is re-announced. Manual `bd
backup` / `bd backup sync` are not capped.
- **`bd doctor` no longer flags a `.local_version` that starts with `v`.** The
canonical spelling of a Go module version — and the string a build stamped
from a Go pseudo-version reports and writes into `.local_version` itself —
@ -71,6 +174,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
first. They now accept an optional leading `v`; versions without it are
unchanged ([#6152](https://github.com/gastownhall/beads/issues/6152)).
- **`bd serve`'s blocked-close refusal names the blockers.** A `409
not_closable` for a live blocker — on `issues/{id}:close`, `issues:batchClose`
per-item outcomes, `PATCH issues/{id}` into a done status, and
`issues:batchApply` — said only "issue is blocked", so an HTTP client could
not tell the user what held the close, while `bd close` on the direct and
proxied routes prints `cannot close blocked issue: X is blocked by [Y]`. The
refusal now carries a `blockers` extension member (`[{id, kind, type}]`,
`kind` `local` or `external`, `type` the blocking edge type when known) and a
`detail` that opens with the direct route's sentence. The code, the status
and the `open_children` discriminator are unchanged. The list travels typed
end to end: close refusals are now an `issueops.BlockedError` (still matching
`ErrCloseBlocked`, with a byte-identical message), so the server never parses
prose to build the member and a client can rebuild the same typed error.
- **The #6716 fan-in stall is fixed on the proxied-server route and the
remaining store routes.** Two blockers of one dependent taken away at the
same time (parallel workers closing both, or a close racing a
@ -166,6 +283,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
resolves, and abbreviation matching is otherwise unchanged. The empty string
already failed; it now says why.
- **Table-rebuild `__temp__` intermediates can no longer materialize as
tracked tables on `@@dolt_transaction_commit=1` servers.** The
ignored-series rebuilds stage every clone-local table through a
`__temp__<table>` rename, but the intermediate names carried no
`dolt_ignore` pattern: against a transaction-commit server each
`CREATE TABLE __temp__X` auto-committed a real table at HEAD, and the
rename onto the ignored final name left an unstageable `__temp__X -> X`
half in `dolt_status` that wedged every later open behind the dirty-table
guard (observed in the field as a three-city shared hub wedging twice in
one day, each time ending in fleet-wide write refusal and a manual SQL
repair). `__temp__%` now ships in the canonical seeded pattern set —
asserted, like the events-journal patterns, before the series that creates
the tables — so intermediates are born ignored. The scoped seed commit also
gains `--skip-empty`: under `@@dolt_transaction_commit=1` the server has
already committed the seeded rows at their own transaction boundaries, and
the previously unconditional `DOLT_COMMIT` died with "nothing to commit",
killing the pass on exactly the under-seeded stores the heal targets.
Fenced deployments: adding a canonical pattern un-converges `dolt_ignore` for
every existing database, so the next write-mode open issues one
`INSERT IGNORE INTO dolt_ignore`; a hosted or box-fenced wire client that is
denied that INSERT fails its open until one privileged `bd` opens the store
and heals the pattern — self-healing, one privileged open per upgrade
(degrading a denied seed to a skip is tracked separately).
- **`bd ready --parent` and `bd blocked --parent` no longer re-scan the whole
parent-child edge relation for every descendant they find.** The transitive
descendant walk recursed against a materialized `parent_edges` CTE that Dolt
cannot index through, so its cost was (parent-child rows) × (descendants):
7.5 s for a 483-descendant parent on a 4.6k-edge database, and past the
shared-pool read deadline on a busy server. The walk now recurses directly
off `dependencies` / `wisp_dependencies` through their typed target indexes
and returns the same rows in a fraction of the time
([#6128](https://github.com/gastownhall/beads/issues/6128)).
- **`bd list --parent` on a proxied-server workspace no longer drops a child
whose prefix differs from its parent's**
([#6130](https://github.com/gastownhall/beads/pull/6130)). The edge to such
a parent is stored in `depends_on_external` — `issueops.IsExternalDepTarget`
routes every cross-prefix target there — but the descendant walk behind the
proxied tree view resolved a parent only through the issue and wisp target
columns, so the child and its subtree were missing from the tree and from
`--watch`, while the direct route listed them. The walk now reads all three
target columns, as the direct route's `--parent` filter does. Nothing listed
before can drop out: the added column is read only when the other two are
both empty.
- **`notion.token` is kept out of the Dolt database**
([#6676](https://github.com/gastownhall/beads/issues/6676)). It was missing
from the yaml-only key list that holds the other tracker secrets, so
@ -287,6 +450,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
already refused the combination. Both routes now fail with the same
`--format cannot be combined with --watch` usage error.
- Explicit `bd update --claim` and direct `bd close` now enforce unsatisfied
external capability dependencies. Mixed close batches still commit eligible
items together, and `--claim-next` skips externally blocked work even when
`--force` overrides the close guard.
- **The smart migrate gate no longer auto-migrates a clone whose data is behind
the remote, and `bd dolt pull` now works from that state**
([#6575](https://github.com/gastownhall/beads/issues/6575)). The gate's
@ -378,8 +546,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
(non-readonly) `bd show` keeps recording last-touched exactly as before, so
only consumers driving `bd --readonly … --json` see the change.
- **Markdown bodies now honor the terminal's actual background instead of
always rendering dark**
([#5776](https://github.com/gastownhall/beads/pull/5776)).
`glamour.WithEnvironmentConfig()` defaults to `styles.DarkStyle` whenever
`GLAMOUR_STYLE` is unset, with no regard for the terminal's real
background — unlike `internal/ui`'s own adaptive colors, which probe it
via `lipgloss.HasDarkBackground`. That left every markdown body's colors
wrong on a light-background terminal even though the section header
wrapping it adapted correctly. The fix lands at the shared renderer, so it
covers every markdown body `bd` prints — DESCRIPTION, DESIGN, NOTES,
ACCEPTANCE CRITERIA, and comment bodies, direct and proxied alike — not
just `bd show`'s DESCRIPTION field. An explicit `GLAMOUR_STYLE` override
still takes priority over the detected background.
### Added
- **A long-running schema migration now says so instead of going quiet**
([#5997](https://github.com/gastownhall/beads/pull/5997)). Migrations are
allowed to take a long time by design — migration 0047's full-table
`is_blocked` recompute is a real example — but until now a slow one and a
wedged one looked identical from outside: `bd` simply stopped printing. A
watchdog now emits a WARN naming the migration's version, name, and elapsed
time once the migration's own SQL has been running past the interval, and
repeats every interval while it keeps running, so an operator reading logs
can tell "still working" from "stopped emitting anything". Coverage is the
migration body specifically — the per-step Dolt commit that follows it on
the production embedded path is outside the watchdog, so a stall there is
still quiet. Set `BEADS_MIGRATION_WATCHDOG_INTERVAL` to change the
5-minute default; it accepts durations like `10m` and bare seconds like `90`,
and falls back to the default when unset or unparsable. This is observability
only and never a circuit breaker: the migration receives the caller's exact
context, its error is passed through unchanged, and nothing is aborted or
rolled back. The warning is deliberately not terminal-gated, so it survives
`bd serve`, systemd, CI, and piped invocations.
- **Auto-backup runs on a managed-local proxied-server workspace.** The
proxied arm of the post-command hook now calls auto-backup, so an explicit
`backup.enabled=true` (or `BD_BACKUP_ENABLED=1`) takes the same throttled,
@ -620,6 +821,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Changed
- **The managed shared Dolt server now opens its configured remotesapi
listener** ([#6020](https://github.com/gastownhall/beads/pull/6020)).
`dolt.remotesapi-port` (machine-global user config) and
`BEADS_DOLT_REMOTESAPI_PORT` now reach the launched `dolt sql-server`
(as `--remotesapi-port` in flag mode, `remotesapi.port` in generated-YAML
mode), and `doltserver.Restart` applies a listener change under one
lifecycle lock. Zero (the shared-mode default) still means no listener.
This changes the meaning of a pre-existing knob: `BEADS_DOLT_REMOTESAPI_PORT`
previously only informed federation doctor checks; a managed server launched
with it set now actually opens that listener. A server still running from
before the setting appeared refuses `bd dolt start` with a
`bd dolt stop && bd dolt start` remedy, while auto-start keeps serving SQL
and prints a warning until the server is restarted.
Security caveat: Dolt binds the remotesapi listener on all interfaces and
serves it unauthenticated, unlike the managed 127.0.0.1 SQL listener. Only
enable it where a firewall, private interface, or tunnel bounds who can
reach the port.
- **A formula with a `waits_for` gate and no spawner to wait for is now
rejected, and an invalid formula is no longer reported as not found.** A gate
step infers its spawner from `needs[0]`, so with nothing to infer from,
@ -763,12 +984,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
stdout is unlimited, agent mode on a terminal gets 20, and a terminal gets 50.
- **`bd preflight` honors the `json` config default**
([#6293](https://github.com/gastownhall/beads/pull/6293)). Its `--json` flag
is bound to the same global every sibling command binds, so `json: true` in
the config file now selects JSON output for `bd preflight` as it already did
elsewhere. Previously only the explicit flag was honored — and, because an
unbound flag reports as unset, `bd preflight --json` did not reach every
JSON-aware renderer.
([#6293](https://github.com/gastownhall/beads/pull/6293)). `json: true` in the
config file selects JSON output for `bd preflight`, as it already did
elsewhere; previously only the explicit flag was honored.
- **`bd gate check` resolves bead gates whose target lives in a prefix-routed
rig** ([#5859](https://github.com/gastownhall/beads/pull/5859)). After a local
miss, the evaluator follows the target bead ID through `routes.jsonl` and
@ -866,6 +1084,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
ready set should fail to compile rather than silently fall back to an
unbounded query.
- **`storage.Storage` gains a required `SearchIssueSummaries` method**
([#3458](https://github.com/gastownhall/beads/pull/3458)). It is a
narrow-projection variant of `SearchIssues` for list-shaped rendering: it
returns `[]*types.IssueSummary` (exported as `backend.IssueSummary`), which
carries the list columns, labels, and the four wisp-plane markers but none of
the TEXT/JSON columns. Nothing in `bd` calls it yet, so no command's output
changes. Consumers that only *call* the interface are unaffected; any external
type that *implements* it (a custom store, mock, or proxy, or an
`internal/storage/backends` registrant) must add the method to compile:
`SearchIssueSummaries(ctx context.Context, query string, filter types.IssueFilter) ([]*types.IssueSummary, error)`.
It honors `SortBy`/`SortDesc` and `SkipLabels` exactly as `SearchIssues`
does, `IncludeDependencies` is a silent no-op (a summary has nowhere to put
dependency records), and wisps are merged in unless `SkipWisps` is set, with
their markers set so a wisp row stays distinguishable from a durable issue.
- **Push `--dry-run` now honors `--create-only`**
([#6337](https://github.com/gastownhall/beads/issues/6337)). The sequential
tracker push previewed "Would update" for every already-linked issue, even

View file

@ -75,11 +75,11 @@ type SQLStatement struct {
Args []any
}
// RunCycleDetectorReportsNoCycleForAnAcyclicSubgraph pins cycledetector.go:135
// RunCycleDetectorReportsNoCycleForAnAcyclicSubgraph pins cycledetector.go:171
// from the empty side: an acyclic graph is an empty report and a nil error,
// with no ErrNotFound to classify. The nil-slice half IS asserted globally —
// that one is a property of the answer, not of the workspace
// (cycledetector.go:78).
// (cycledetector.go:108).
func RunCycleDetectorReportsNoCycleForAnAcyclicSubgraph(t *testing.T, ctx context.Context, fixture CycleDetectorFixture) {
t.Helper()
first := fixture.IssuePrefix + "-acyclic-a"
@ -98,10 +98,10 @@ func RunCycleDetectorReportsNoCycleForAnAcyclicSubgraph(t *testing.T, ctx contex
}
// RunCycleDetectorFindsADurableCycleRotatedToItsLowestID pins the shape of a
// found cycle: members in EDGE ORDER (cycledetector.go:48-50), rotated so the
// lowest id comes first (cycledetector.go:52-58), the closing edge implied
// found cycle: members in EDGE ORDER (cycledetector.go:78-80), rotated so the
// lowest id comes first (cycledetector.go:82-88), the closing edge implied
// rather than repeated, and Partial false when every member was described
// (cycledetector.go:63).
// (cycledetector.go:93).
//
// The three ids are seeded so that the edge order and the sorted order are NOT
// the same sequence, which is what makes the rotation assertion say something.
@ -138,8 +138,8 @@ func RunCycleDetectorFindsADurableCycleRotatedToItsLowestID(t *testing.T, ctx co
}
}
// RunCycleDetectorReportsTheSameCyclesEveryRun pins cycledetector.go:52-58 and
// :91-92: two calls against an unchanged database must agree, id for id and
// RunCycleDetectorReportsTheSameCyclesEveryRun pins cycledetector.go:82-88 and
// :126-127: two calls against an unchanged database must agree, id for id and
// cycle for cycle.
//
// It compares the WHOLE report rather than the case's own cycle: the walk used
@ -175,7 +175,7 @@ func RunCycleDetectorReportsTheSameCyclesEveryRun(t *testing.T, ctx context.Cont
}
// RunCycleDetectorMergesTheDurableAndEphemeralPlanes pins
// cycledetector.go:120-122: the two dependency planes are one graph, so a cycle
// cycledetector.go:156-158: the two dependency planes are one graph, so a cycle
// that runs issue → wisp → issue is found. This is the clause a single-table
// read passes every other case and fails here.
func RunCycleDetectorMergesTheDurableAndEphemeralPlanes(t *testing.T, ctx context.Context, fixture CycleDetectorFixture) {
@ -198,10 +198,12 @@ func RunCycleDetectorMergesTheDurableAndEphemeralPlanes(t *testing.T, ctx contex
}
}
// RunCycleDetectorFollowsOnlyBlockingEdges pins cycledetector.go:110-119: the
// RunCycleDetectorFollowsOnlyBlockingEdges pins cycledetector.go:145-154: the
// walk follows `blocks` and `conditional-blocks`, and nothing else — not
// `waits-for`, whose gate semantics make a mutual wait legitimate, and not
// `parent-child`, which the ADD-time gate does walk.
// `waits-for`, whose gate semantics make a mutual wait legitimate, not
// `parent-child`, which the ADD-time gate does walk, and not `tracks`, on the
// DEFAULT (zero-value) request. IncludeTracks's own widened walk is pinned
// separately by RunCycleDetectorIncludeTracks*, below.
//
// The conditional-blocks half is asserted in the same case as the exclusions on
// purpose: a body narrowed to `blocks` alone would pass an exclusion-only case,
@ -217,6 +219,7 @@ func RunCycleDetectorFollowsOnlyBlockingEdges(t *testing.T, ctx context.Context,
{types.DepWaitsFor, "wait", false},
{types.DepParentChild, "kid", false},
{types.DepRelated, "rel", false},
{types.DepTracks, "trk", false},
} {
first := fmt.Sprintf("%s-edge-%s-a", fixture.IssuePrefix, test.slug)
second := fmt.Sprintf("%s-edge-%s-b", fixture.IssuePrefix, test.slug)
@ -236,8 +239,87 @@ func RunCycleDetectorFollowsOnlyBlockingEdges(t *testing.T, ctx context.Context,
}
}
// RunCycleDetectorReportsAnHonestPartial pins cycledetector.go:140-144 and
// :24-33 against real storage: a member the database cannot describe keeps its
// RunCycleDetectorIncludeTracksIgnoresAPureTracksLoop pins
// DetectCyclesRequest.IncludeTracks's own guard: widening the walk to `tracks`
// must not resurrect the PR #4933 false-positive shape, where ordinary
// convoy/tracking topology with no scheduling edge at all got reported as a
// cycle. A loop made entirely of `tracks` edges stays silent even with
// IncludeTracks set.
func RunCycleDetectorIncludeTracksIgnoresAPureTracksLoop(t *testing.T, ctx context.Context, fixture CycleDetectorFixture) {
t.Helper()
first := fixture.IssuePrefix + "-trkloop-a"
second := fixture.IssuePrefix + "-trkloop-b"
seedCycleDetectorIssue(t, ctx, fixture, first)
seedCycleDetectorIssue(t, ctx, fixture, second)
seedCycleDetectorEdges(t, ctx, fixture, false,
cycleDetectorEdge{Source: first, Target: second, Type: types.DepTracks},
cycleDetectorEdge{Source: second, Target: first, Type: types.DepTracks})
report := cycleDetectorReportIncludingTracks(t, ctx, fixture)
if found := cycleDetectorTouching(report, first, second); len(found) > 0 {
t.Errorf("a mutual tracks-only pair produced %v under IncludeTracks, want none: a cycle needs at least one scheduling edge", found)
}
}
// RunCycleDetectorIncludeTracksFindsTheMoleculeRootShape pins the gc-818bx
// deadlock this option exists to surface: a molecule root that
// blocks-depends on its own entry step, which tracks-depends back to the
// root. Neither edge alone is a cycle; the shape only closes across both edge
// types, which is exactly what the default (blocks-only) walk cannot see.
func RunCycleDetectorIncludeTracksFindsTheMoleculeRootShape(t *testing.T, ctx context.Context, fixture CycleDetectorFixture) {
t.Helper()
root := fixture.IssuePrefix + "-molroot"
step := fixture.IssuePrefix + "-molstep"
seedCycleDetectorIssue(t, ctx, fixture, root)
seedCycleDetectorIssue(t, ctx, fixture, step)
seedCycleDetectorEdges(t, ctx, fixture, false,
cycleDetectorEdge{Source: root, Target: step, Type: types.DepBlocks},
cycleDetectorEdge{Source: step, Target: root, Type: types.DepTracks})
// The default request must still see nothing: the closing edge is a
// tracks edge, outside the base walk.
if found := cycleDetectorTouching(cycleDetectorReport(t, ctx, fixture), root, step); len(found) > 0 {
t.Errorf("the default request reported %v; IncludeTracks defaults to false and must leave the base walk unchanged", found)
}
cycle := cycleDetectorFind(t, cycleDetectorReportIncludingTracks(t, ctx, fixture), root, step)
assertCycleDetectorPath(t, cycle, root, step)
}
// RunCycleDetectorIncludeTracksWalksEachEdgeInItsStoredDirection pins the
// direction of the widened graph, which the two-node cases above cannot: a
// two-node cycle reads the same reversed once it is rotated to its lowest id.
// This loop has three nodes in edge order a, c, b. Reversed it is a, b, c, the
// same member set in the other order, so a graph builder that stored
// depends_on_id -> issue_id would still find exactly one cycle here and fail
// only on the path.
//
// The blocks edge sits in the middle of the loop and the closing edges are
// tracks, so the default request must see nothing.
func RunCycleDetectorIncludeTracksWalksEachEdgeInItsStoredDirection(t *testing.T, ctx context.Context, fixture CycleDetectorFixture) {
t.Helper()
a := fixture.IssuePrefix + "-trkdir-a"
b := fixture.IssuePrefix + "-trkdir-b"
c := fixture.IssuePrefix + "-trkdir-c"
for _, id := range []string{a, b, c} {
seedCycleDetectorIssue(t, ctx, fixture, id)
}
// a -> c -> b -> a.
seedCycleDetectorEdges(t, ctx, fixture, false,
cycleDetectorEdge{Source: a, Target: c, Type: types.DepTracks},
cycleDetectorEdge{Source: c, Target: b, Type: types.DepBlocks},
cycleDetectorEdge{Source: b, Target: a, Type: types.DepTracks})
if found := cycleDetectorTouching(cycleDetectorReport(t, ctx, fixture), a, b, c); len(found) > 0 {
t.Errorf("the default request reported %v; two of the three edges are tracks, outside the base walk", found)
}
cycle := cycleDetectorFind(t, cycleDetectorReportIncludingTracks(t, ctx, fixture), a, b, c)
assertCycleDetectorPath(t, cycle, a, c, b)
}
// RunCycleDetectorReportsAnHonestPartial pins cycledetector.go:176-180 and
// :54-63 against real storage: a member the database cannot describe keeps its
// place on the path, carries no issue, and marks the cycle. The previous body
// dropped the member, so this three-node cycle came back as a TWO-node cycle and
// looked complete.
@ -272,7 +354,7 @@ func RunCycleDetectorReportsAnHonestPartial(t *testing.T, ctx context.Context, f
}
}
// RunCycleDetectorCountsAWhollyUndescribableCycle pins cycledetector.go:81-85:
// RunCycleDetectorCountsAWhollyUndescribableCycle pins cycledetector.go:111-115:
// a cycle no member of which can be described is still IN the report, so the
// count cannot shrink because rows went missing. Under the previous body this
// cycle produced nothing at all, so `bd dep cycles` printed a smaller number and
@ -297,7 +379,7 @@ func RunCycleDetectorCountsAWhollyUndescribableCycle(t *testing.T, ctx context.C
}
}
// RunCycleDetectorWritesNothing pins cycledetector.go:130-131: detecting is a
// RunCycleDetectorWritesNothing pins cycledetector.go:166-167: detecting is a
// read. It is asserted on the history log rather than on a row read-back
// because every versioned unit of work in this tree ends in a Dolt commit, so a
// sweep that took a write transaction would show up here even when it changed
@ -433,6 +515,17 @@ func cycleDetectorReport(t *testing.T, ctx context.Context, fixture CycleDetecto
return report
}
// cycleDetectorReportIncludingTracks is cycleDetectorReport with
// IncludeTracks set, for the cases pinning that option's own widened walk.
func cycleDetectorReportIncludingTracks(t *testing.T, ctx context.Context, fixture CycleDetectorFixture) publicops.CycleReport {
t.Helper()
report, err := fixture.Detector.DetectCycles(ctx, publicops.DetectCyclesRequest{IncludeTracks: true})
if err != nil {
t.Fatalf("DetectCycles: %v", err)
}
return report
}
// cycleDetectorPaths renders a report as id paths, which is what the
// determinism case compares.
func cycleDetectorPaths(report publicops.CycleReport) [][]string {

View file

@ -205,6 +205,9 @@ var roleContractCases = []roleContract{
RunCycleDetectorReportsTheSameCyclesEveryRun,
RunCycleDetectorMergesTheDurableAndEphemeralPlanes,
RunCycleDetectorFollowsOnlyBlockingEdges,
RunCycleDetectorIncludeTracksIgnoresAPureTracksLoop,
RunCycleDetectorIncludeTracksFindsTheMoleculeRootShape,
RunCycleDetectorIncludeTracksWalksEachEdgeInItsStoredDirection,
RunCycleDetectorReportsAnHonestPartial,
RunCycleDetectorCountsAWhollyUndescribableCycle,
RunCycleDetectorWritesNothing,

View file

@ -27,6 +27,7 @@ type (
IssueDetails = types.IssueDetails
IssueFilter = types.IssueFilter
IssueSnapshot = types.IssueSnapshot
IssueSummary = types.IssueSummary
IssueType = types.IssueType
IssueWithCounts = types.IssueWithCounts
IssueWithDependencyMetadata = types.IssueWithDependencyMetadata

View file

@ -1,6 +1,17 @@
load("@rules_go//go:def.bzl", "go_binary", "go_library", "go_test")
load("@rules_shell//shell:sh_test.bzl", "sh_test")
# testdata/ holds the compilable preflight fixture below. Left to itself gazelle
# would make testdata/ its own package, which empties this package's
# glob(["testdata/**"]) and puts the fixture source across a package boundary.
# gazelle:exclude testdata
go_binary(
name = "preflight_go_fixture",
testonly = True,
srcs = ["testdata/preflight-go.go"],
)
go_library(
name = "bd_lib",
srcs = [
@ -13,6 +24,7 @@ go_library(
"backend_support.go",
"backup.go",
"backup_auto.go",
"backup_cap.go",
"backup_dolt.go",
"backup_export.go",
"backup_lock.go",
@ -180,6 +192,7 @@ go_library(
"lint.go",
"lint_proxied_server.go",
"list.go",
"list_filter_flags.go",
"list_format.go",
"list_input.go",
"list_output.go",
@ -440,6 +453,7 @@ go_library(
"@io_opentelemetry_go_otel_trace//:trace",
"@land_charm_huh_v2//:huh",
"@land_charm_lipgloss_v2//:lipgloss",
"@org_golang_x_mod//module",
"@org_golang_x_mod//semver",
"@org_golang_x_term//:term",
] + select({
@ -501,6 +515,7 @@ go_test(
"backup_auto_proxied_local_integration_test.go",
"backup_auto_proxied_test.go",
"backup_auto_test.go",
"backup_cap_test.go",
"backup_dolt_test.go",
"backup_embedded_test.go",
"backup_export_failure_test.go",
@ -621,6 +636,7 @@ go_test(
"db_proxy_child_test.go",
"defer_embedded_test.go",
"defer_proxied_integration_test.go",
"defer_until_hint_test.go",
"defer_wake_embedded_test.go",
"defer_wake_proxied_integration_test.go",
"defer_wake_server_test.go",
@ -645,9 +661,11 @@ go_test(
"diff_embedded_test.go",
"directory_flag_test.go",
"doctor_backend_guard_test.go",
"doctor_check_gate_test.go",
"doctor_context_test.go",
"doctor_conventions_test.go",
"doctor_embedded_test.go",
"doctor_fix_gate_wiring_test.go",
"doctor_fix_order_test.go",
"doctor_fix_pending_migrations_test.go",
"doctor_health_integration_test.go",
@ -720,6 +738,8 @@ go_test(
"export_proxied_integration_test.go",
"export_source_wisp_subset_test.go",
"export_test.go",
"external_policy_direct_integration_test.go",
"external_policy_embedded_test.go",
"external_ref_test.go",
"federation_embedded_test.go",
"feedback_test.go",
@ -745,6 +765,7 @@ go_test(
"gc_embedded_test.go",
"gc_prune_test.go",
"git_repo_template_test.go",
"github_link_scope_test.go",
"gitlab_integration_test.go",
"gitlab_test.go",
"global_identity_integration_test.go",
@ -803,6 +824,7 @@ go_test(
"init_explicit_beads_dir_embedded_test.go",
"init_gateway_test.go",
"init_git_bootstrap_routing_test.go",
"init_guard_force_e2e_test.go",
"init_guard_test.go",
"init_hooks_test.go",
"init_metrics_test.go",
@ -824,6 +846,7 @@ go_test(
"init_worktree_test.go",
"jira_max_rows_gate_test.go",
"jira_test.go",
"json_flag_shadow_test.go",
"kv_embedded_test.go",
"kv_proxied_integration_test.go",
"kv_test.go",
@ -852,6 +875,7 @@ go_test(
"list_comments_embedded_test.go",
"list_comments_proxied_integration_test.go",
"list_embedded_test.go",
"list_filter_flags_test.go",
"list_footer_counts_test.go",
"list_format_json_test.go",
"list_helpers_test.go",
@ -938,6 +962,7 @@ go_test(
"prime_divergence_test.go",
"prime_embedded_test.go",
"prime_gemini_hook_test.go",
"prime_git_remote_test.go",
"prime_memory_caps_test.go",
"prime_proxied_integration_test.go",
"prime_shared_server_test.go",
@ -1067,6 +1092,8 @@ go_test(
"show_proxied_watch_integration_test.go",
"show_test.go",
"show_unit_helpers_test.go",
"show_unresolvable_deps_embedded_test.go",
"show_unresolvable_deps_unit_test.go",
"show_watch_loop_test.go",
"show_watch_test.go",
"simple_helpers_test.go",
@ -1185,6 +1212,7 @@ go_test(
data = glob(["testdata/**"]) + [
":bd_for_tests",
":go_srcs",
":preflight_go_fixture",
"//:bd_test_files",
"//cmd/bd/doctor:go_srcs",
"//cmd/bd/doctor/fix:go_srcs",
@ -1195,6 +1223,7 @@ go_test(
env = {
"BEADS_TEST_BD_BINARY": "$(rlocationpath :bd_for_tests)",
"BEADS_TEST_GOFMT": "$(rlocationpath @go_sdk//:bin/gofmt)",
"BEADS_TEST_PREFLIGHT_GO": "$(rlocationpath :preflight_go_fixture)",
},
shard_count = 16,
deps = [
@ -1247,6 +1276,7 @@ go_test(
"//internal/telemetry",
"//internal/testutil",
"//internal/testutil/bazeltest",
"//internal/timeparsing",
"//internal/tracker",
"//internal/types",
"//internal/ui",

View file

@ -88,8 +88,9 @@ func newBackupStatusCommand(sizeDatabase backupSizeFunc) *cobra.Command {
if jsonOutput {
result := map[string]interface{}{
"backup": state,
"dolt": showDoltBackupStatusJSON(),
"backup": state,
"dolt": showDoltBackupStatusJSON(),
"size_cap": showSizeCapStatusJSON(dir),
}
if sizeAvailable {
result["database_size"] = showDBSizeJSON(databaseSize)
@ -137,6 +138,7 @@ func newBackupStatusCommand(sizeDatabase backupSizeFunc) *cobra.Command {
}
fmt.Printf("\nConfig: enabled=%v%s interval=%s\n",
enabled, enabledNote, interval)
showSizeCapStatus(dir)
// Show Dolt backup info
showDoltBackupStatus()

View file

@ -189,7 +189,12 @@ func maybeAutoBackup(ctx context.Context) {
return
}
// Throttle: skip if we backed up recently
// Throttle: skip if we backed up recently. Checked before the size-cap
// walk below so the common case — the majority of bd invocations,
// still inside the interval — pays zero directory-walk cost (ga-y6gjv
// PR #6071 review: getDirSize's filepath.Walk cost 65-100ms per
// invocation at 20k files when the cap check ran unconditionally,
// before this throttle, on every single command).
interval := config.GetDuration("backup.interval")
if interval == 0 {
interval = 15 * time.Minute
@ -211,6 +216,32 @@ func maybeAutoBackup(ctx context.Context) {
return
}
// Size cap: skip entirely once the destination has grown past
// backup.size-cap-mb (ga-y6gjv) — see backupSizeCapExceeded for why a
// cap, not an in-place prune, is the safe fix here.
//
// Placed AFTER change detection, which is the order
// docs/reference/configuration.md:"How it works" documents. Ahead of
// it, the walk ran on EVERY bd invocation indefinitely in an idle
// workspace: nothing on the idle path advances state.Timestamp, so the
// interval throttle above can never re-arm while nothing is changing
// (ga-y6gjv PR #6071 review). Keep it above any lock acquisition —
// a skip should not first take a lock it is about to release.
if exceeded, size, err := backupSizeCapExceeded(dir); err != nil {
warnBackupSizeCapUnavailable(err)
// Re-arm the interval throttle before proceeding uncapped: not
// every runBackupExport exit persists state.Timestamp (see
// warnBackupSizeCapUnavailable), and without this the walk and
// its warning would repeat on every bd command.
state.Timestamp = time.Now().UTC()
if saveErr := saveBackupState(dir, state); saveErr != nil {
debug.Logf("backup: failed to persist throttle state after size cap error: %v\n", saveErr)
}
} else if exceeded {
pauseAutoBackupForSizeCap(dir, state, size)
return
}
// One backup at a time per workspace (backup_lock.go). Auto-backup never
// waits: a held lock means a backup is already running.
release, err := acquireBackupLock(0)

232
cmd/bd/backup_cap.go Normal file
View file

@ -0,0 +1,232 @@
package main
import (
"fmt"
"os"
"path/filepath"
"time"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/debug"
)
// effectiveSizeCapMB returns the configured backup.size-cap-mb, or 0 if the
// cap is disabled. internal/config/config.go registers a viper default of
// 2048 for this key, so GetInt only returns <= 0 when the operator has
// explicitly set 0 (or an unparseable value, which viper's GetInt also
// resolves to 0) — per the ga-y6gjv PR #6071 review, that means "no cap",
// not "use the 2048 default instead" (an operator with a legitimately
// larger destination needs an off switch).
func effectiveSizeCapMB() int {
capMB := config.GetInt("backup.size-cap-mb")
if capMB <= 0 {
return 0
}
return capMB
}
// backupSizeCapExceeded reports whether dir's on-disk size has crossed
// backup.size-cap-mb (default 2048MB / 2GB; 0 disables the cap).
//
// A hard cap exists because BackupSync/CALL DOLT_BACKUP('sync', ...) only
// ever transfers new chunks into dir — it never prunes ones that became
// unreachable on the source DB (history rewrites, superseded data) — and
// Dolt exposes no supported way to GC a backup destination in place: it is
// a bare chunk-store directory with no .dolt repo-root marker (confirmed
// against dolt_backup.go's SQL procedures — add/sync/restore only, no gc;
// and empirically, `dolt gc` run with its working directory set to a real
// backup destination fails "not a valid dolt repository" because there is
// no .dolt for the CLI to find). Absent a cap, the destination can only
// grow forever until disk fills (ga-y6gjv, the 2026-06-19 outage: 43GB
// backup dir from a 1.7GB store). formatBytes is shared with
// runCompactDolt (compact.go); getDirSize is defined below.
func backupSizeCapExceeded(dir string) (exceeded bool, size int64, err error) {
capMB := effectiveSizeCapMB()
if capMB == 0 {
return false, 0, nil
}
size, err = getDirSize(dir)
if err != nil {
return false, 0, err
}
return size >= int64(capMB)*1024*1024, size, nil
}
// walkBackupDestination is getDirSize, indirected so tests can inject the
// mid-walk ENOENT that a real filesystem produces only under a race.
var walkBackupDestination = getDirSize
// backupDestinationSize measures dir for the status readers. Only a
// destination that does not exist yet counts as empty; every walk error is
// returned, ENOENT included. getDirSize aborts on the first per-entry
// error, so a chunk file removed between listing its directory and
// stat-ing it would otherwise read as 0 bytes: a false all-clear on a
// destination that may be well over its cap.
func backupDestinationSize(dir string) (int64, error) {
if _, err := os.Stat(dir); os.IsNotExist(err) {
return 0, nil
}
return walkBackupDestination(dir)
}
// showSizeCapStatus prints size-cap info as part of `bd backup status`
// (ga-y6gjv PR #6071 review: status previously said nothing about the cap,
// so an agent/CI caller watching a paused destination saw only a
// reassuring "Last backup" line).
func showSizeCapStatus(dir string) {
capMB := effectiveSizeCapMB()
if capMB == 0 {
// Echo the configured value rather than a literal 0: an
// unparseable one ("2048MB") also disables the cap (see
// effectiveSizeCapMB), and this line is where an operator
// debugging that looks.
fmt.Printf(" Size cap: disabled (backup.size-cap-mb=%s)\n", config.GetString("backup.size-cap-mb"))
return
}
size, err := backupDestinationSize(dir)
if err != nil {
// Say so rather than dropping the line: a silent omission
// looks identical to "no cap configured" to an operator
// debugging a permission problem on the destination, and
// --json already reports this case (showSizeCapStatusJSON).
debug.Logf("backup status: size cap check failed (non-fatal): %v\n", err)
fmt.Printf(" Size cap: unavailable (%v)\n", err)
return
}
capBytes := int64(capMB) * 1024 * 1024
if size >= capBytes {
fmt.Printf(" Size cap: PAUSED (cap exceeded) — %s / %s. Raise backup.size-cap-mb "+
"or run `bd backup init <new-path>` to switch destinations.\n",
formatBytes(size), formatBytes(capBytes))
return
}
fmt.Printf(" Size cap: %s / %s\n", formatBytes(size), formatBytes(capBytes))
}
// showSizeCapStatusJSON returns size-cap info for `bd backup status --json`
// — see showSizeCapStatus.
func showSizeCapStatusJSON(dir string) map[string]interface{} {
capMB := effectiveSizeCapMB()
if capMB == 0 {
return map[string]interface{}{"enabled": false}
}
size, err := backupDestinationSize(dir)
if err != nil {
// exceeded is explicitly null, not omitted: a consumer that
// reads a missing key as false would see "not exceeded"
// during exactly the failure that makes it unmeasurable.
return map[string]interface{}{
"enabled": true,
"cap_mb": capMB,
"error": err.Error(),
"exceeded": nil,
}
}
capBytes := int64(capMB) * 1024 * 1024
return map[string]interface{}{
"enabled": true,
"cap_mb": capMB,
"current_bytes": size,
"exceeded": size >= capBytes,
}
}
// warnBackupSizeCapUnavailable reports, on stderr, that the cap could not
// be measured and the backup is proceeding uncapped.
//
// getDirSize returns the first per-file error straight out of its
// filepath.Walk callback, so one unreadable entry — or a chunk file removed
// mid-walk — aborts the whole measurement. maybeAutoBackup deliberately
// fails OPEN there (blocking backups outright on an unreadable destination
// would be worse), but a debug-only line made that silent: the cap can
// disable itself and restore the unbounded growth this feature exists to
// prevent with nothing on the operator's terminal, while `bd backup status
// --json` reports the very same error (ga-y6gjv PR #6071 review).
//
// It is throttled by the backup interval, not by the PAUSED warning's
// LastCapWarnAt slot — spending that slot here would let a transient walk
// error suppress the more important "auto-backup PAUSED" notice for a full
// warn interval. maybeAutoBackup reaches the walk only after the interval
// throttle and change detection have both passed, and re-arms
// state.Timestamp itself after this warning rather than relying on the
// fall-through into runBackupExport: not every runBackupExport exit
// persists it (a failed post-sync GetCurrentCommit returns without saving
// state), and the next command would then walk and warn again. That bounds
// this warning to once per backup.interval whenever backup_state.json can
// be written.
func warnBackupSizeCapUnavailable(err error) {
if !isQuiet() && !jsonOutput {
fmt.Fprintf(os.Stderr,
"Warning: backup size cap could not be measured (%v); "+
"proceeding without the cap. Auto-backup is unbounded until this clears.\n", err)
}
debug.Logf("backup: size cap check failed (non-fatal): %v\n", err)
}
// pauseAutoBackupForSizeCap records the skip that happens when the
// destination is over backup.size-cap-mb, and announces it to stderr at
// most once per backup.size-warn-interval (default 24h).
//
// It re-arms the interval throttle (state.Timestamp) even though no backup
// ran, leaving LastDoltCommit untouched exactly as runBackupExport's own
// failure path does (backup_export.go, wy-zrmqr). Without that, the paused
// state is self-perpetuating and pathological: Timestamp is only ever
// advanced by a backup attempt, so a destination that is over cap — by
// definition the largest one — would pay the full getDirSize walk on every
// single bd command, forever, until an operator intervenes (ga-y6gjv
// PR #6071 review). LastDoltCommit is deliberately left alone so change
// detection still sees the pending work once the cap is raised.
//
// The warn timestamp, by contrast, is recorded only when the message was
// actually printed. --json/--quiet callers — i.e. every agent-driven
// command — would otherwise consume the 24h slot silently and the
// human-visible warning could effectively never fire; those callers have
// `bd backup status --json`'s size_cap field instead.
//
// Never returns an error: a failure to persist must not block the
// (already-decided) skip of the backup attempt itself.
func pauseAutoBackupForSizeCap(dir string, state *backupState, size int64) {
warnInterval := config.GetDuration("backup.size-warn-interval")
if warnInterval == 0 {
warnInterval = 24 * time.Hour
}
state.Timestamp = time.Now().UTC()
lastWarn := state.LastCapWarnAt
throttled := !lastWarn.IsZero() && time.Since(lastWarn) < warnInterval
announce := !throttled && !isQuiet() && !jsonOutput
if announce {
state.LastCapWarnAt = time.Now().UTC()
}
if err := saveBackupState(dir, state); err != nil {
debug.Logf("backup: failed to persist size-cap skip state: %v\n", err)
}
if announce {
fmt.Fprintf(os.Stderr,
"Warning: auto-backup PAUSED — destination %s has reached %s. "+
"No further syncs will run until you raise backup.size-cap-mb "+
"or switch to a fresh destination with `bd backup init <new-path>`.\n",
dir, formatBytes(size))
debug.Logf("backup: size cap exceeded (%s), auto-backup paused\n", formatBytes(size))
return
}
debug.Logf("backup: size cap exceeded (%s), auto-backup paused (warning throttled)\n", formatBytes(size))
}
// getDirSize calculates the total size of a directory recursively.
func getDirSize(path string) (int64, error) {
var size int64
err := filepath.Walk(path, func(_ string, info os.FileInfo, err error) error {
if err != nil {
return err
}
if !info.IsDir() {
size += info.Size()
}
return nil
})
return size, err
}

824
cmd/bd/backup_cap_test.go Normal file
View file

@ -0,0 +1,824 @@
package main
import (
"context"
"errors"
"io/fs"
"os"
"path/filepath"
"strings"
"testing"
"time"
"github.com/steveyegge/beads/internal/config"
)
// TestBackupSizeCapExceeded pins the threshold check itself against a real
// directory (no stubbing needed — getDirSize is a pure filesystem read and
// formatBytes a pure formatter).
func TestBackupSizeCapExceeded(t *testing.T) {
tests := []struct {
name string
fileBytes int
capMB string // config value; "" = use default (2048)
wantExceeded bool
}{
{
name: "tiny dir, default cap → not exceeded",
fileBytes: 1024,
wantExceeded: false,
},
{
name: "dir over a small explicit cap → exceeded",
fileBytes: 2 * 1024 * 1024, // 2MB
capMB: "1",
wantExceeded: true,
},
{
name: "dir under a small explicit cap → not exceeded",
fileBytes: 1024,
capMB: "1",
wantExceeded: false,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
if tt.capMB != "" {
t.Setenv("BD_BACKUP_SIZE_CAP_MB", tt.capMB)
} else {
os.Unsetenv("BD_BACKUP_SIZE_CAP_MB")
t.Cleanup(func() { os.Unsetenv("BD_BACKUP_SIZE_CAP_MB") })
}
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
dir := t.TempDir()
if err := os.WriteFile(filepath.Join(dir, "data"), make([]byte, tt.fileBytes), 0o600); err != nil {
t.Fatal(err)
}
exceeded, size, err := backupSizeCapExceeded(dir)
if err != nil {
t.Fatalf("backupSizeCapExceeded: %v", err)
}
if exceeded != tt.wantExceeded {
t.Errorf("exceeded = %v (size=%d), want %v", exceeded, size, tt.wantExceeded)
}
})
}
}
// TestPauseAutoBackupForSizeCap_WarnThrottle pins the warning throttle: the
// stderr warning must not repeat on every single call once the cap is
// already known to be exceeded — only once per backup.size-warn-interval.
// Mirrors the throttle-persistence pattern already used for the backup
// interval itself (backup_export.go, wy-zrmqr).
//
// It also pins the half of the PR #6071 review fix that is independent of
// the warning: every call, throttled or not, re-arms the backup interval
// throttle (state.Timestamp) and persists it, so a paused destination pays
// the getDirSize walk at most once per backup.interval instead of once per
// bd command.
func TestPauseAutoBackupForSizeCap_WarnThrottle(t *testing.T) {
tests := []struct {
name string
lastWarnAt time.Time
warnInterval string // "" = use default (24h)
wantUpdated bool // whether LastCapWarnAt should advance
}{
{
name: "never warned → warns now",
lastWarnAt: time.Time{},
wantUpdated: true,
},
{
name: "warned 1h ago, default 24h interval → throttled",
lastWarnAt: time.Now().UTC().Add(-1 * time.Hour),
wantUpdated: false,
},
{
name: "warned 25h ago, default 24h interval → warns again",
lastWarnAt: time.Now().UTC().Add(-25 * time.Hour),
wantUpdated: true,
},
{
name: "warned 1h ago, custom 30m interval → warns again",
lastWarnAt: time.Now().UTC().Add(-1 * time.Hour),
warnInterval: "30m",
wantUpdated: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
if tt.warnInterval != "" {
t.Setenv("BD_BACKUP_SIZE_WARN_INTERVAL", tt.warnInterval)
} else {
os.Unsetenv("BD_BACKUP_SIZE_WARN_INTERVAL")
t.Cleanup(func() { os.Unsetenv("BD_BACKUP_SIZE_WARN_INTERVAL") })
}
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
dir := t.TempDir()
before := tt.lastWarnAt
state := &backupState{LastCapWarnAt: tt.lastWarnAt, LastDoltCommit: "deadbeef"}
pauseAutoBackupForSizeCap(dir, state, 3*1024*1024*1024)
updated := !state.LastCapWarnAt.Equal(before)
if updated != tt.wantUpdated {
t.Errorf("LastCapWarnAt updated = %v (before=%v after=%v), want %v",
updated, before, state.LastCapWarnAt, tt.wantUpdated)
}
// The interval throttle is re-armed and persisted on EVERY
// skip, throttled warning or not — that is what stops a
// paused destination from walking on every bd command.
st, err := loadBackupState(dir)
if err != nil {
t.Fatalf("loadBackupState: %v", err)
}
if st.Timestamp.IsZero() {
t.Error("timestamp not persisted to backup_state.json: the interval throttle never re-arms, so the cap walk reruns on every command")
}
if st.LastDoltCommit != "deadbeef" {
t.Errorf("last_dolt_commit = %q, want it left untouched so change detection still sees pending work", st.LastDoltCommit)
}
if tt.wantUpdated {
// Persisted state must reflect the new warning time too.
if st.LastCapWarnAt.IsZero() {
t.Error("last_cap_warn_at not persisted to backup_state.json")
}
}
})
}
}
// TestMaybeAutoBackup_SkipsWhenCapExceeded is the wiring test: a backup
// destination already over the size cap must never attempt a sync at all
// (runDoltGCCommand-equivalent risk avoided entirely — there is nothing to
// stub here because the whole point is that BackupDatabase must NOT be
// called once capped).
func TestMaybeAutoBackup_SkipsWhenCapExceeded(t *testing.T) {
// Isolate CWD/BEADS_DIR: unlike runBackupExport (used by the other
// tests in this file), maybeAutoBackup also calls
// clientServerShareFilesystem → beads.FindBeadsDir before ever
// reaching backupDir(), so an unisolated CWD could walk up into this
// repo's own real .beads/ directory (be-yjp4z; see backup_auto_test.go).
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
repo := t.TempDir()
if err := os.MkdirAll(filepath.Join(repo, ".git"), 0o755); err != nil {
t.Fatal(err)
}
t.Setenv("BD_BACKUP_GIT_REPO", repo)
t.Setenv("BD_BACKUP_ENABLED", "1")
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "1")
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
dir, err := backupDir()
if err != nil {
t.Fatalf("backupDir: %v", err)
}
// Push the destination over the 1MB cap before any backup attempt.
if err := os.WriteFile(filepath.Join(dir, "filler"), make([]byte, 2*1024*1024), 0o600); err != nil {
t.Fatal(err)
}
oldStore := store
fake := &failingBackupStore{commit: "deadbeef", backupErr: nil}
store = fake
t.Cleanup(func() { store = oldStore })
maybeAutoBackup(context.Background())
if fake.backupCalls != 0 {
t.Fatalf("BackupDatabase should not be called once the size cap is exceeded, got %d calls", fake.backupCalls)
}
}
// TestBackupSizeCapExceeded_DisabledWithZero pins the PR #6071 review fix:
// backup.size-cap-mb: 0 must mean "no cap", not "use the legacy 2048MB
// default" — an operator with a legitimately larger destination has no off
// switch otherwise. Uses a sparse file (Truncate, not a real write) to
// cross the legacy 2048MB threshold without allocating 2GB of real disk or
// memory.
func TestBackupSizeCapExceeded_DisabledWithZero(t *testing.T) {
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "0")
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
dir := t.TempDir()
f, err := os.Create(filepath.Join(dir, "sparse-filler"))
if err != nil {
t.Fatal(err)
}
const overLegacyDefault = int64(2049) * 1024 * 1024 // just over the old 2048MB fallback
if err := f.Truncate(overLegacyDefault); err != nil {
t.Fatal(err)
}
if err := f.Close(); err != nil {
t.Fatal(err)
}
exceeded, _, err := backupSizeCapExceeded(dir)
if err != nil {
t.Fatalf("backupSizeCapExceeded: %v", err)
}
if exceeded {
t.Error("exceeded = true with backup.size-cap-mb=0, want false (cap disabled)")
}
}
// TestPauseAutoBackupForSizeCap_RemediationAdvice pins the PR #6071 review
// fix: the warning must not tell operators to delete the backup directory
// — nothing confirms the destination is cleanly recreated by the next
// sync, and Dolt's server-side backup remote stays registered against that
// path. It should point at the safe levers instead: raising the cap, or a
// fresh destination via `bd backup init`.
func TestPauseAutoBackupForSizeCap_RemediationAdvice(t *testing.T) {
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
dir := t.TempDir()
state := &backupState{}
stderr := captureStderr(t, func() {
pauseAutoBackupForSizeCap(dir, state, 3*1024*1024*1024)
})
if strings.Contains(stderr, "delete") {
t.Errorf("warning suggests deleting the backup directory (unsafe — see PR #6071 review): %q", stderr)
}
if !strings.Contains(stderr, "backup.size-cap-mb") {
t.Errorf("warning missing backup.size-cap-mb pointer: %q", stderr)
}
if !strings.Contains(stderr, "bd backup init") {
t.Errorf("warning missing `bd backup init <new-path>` pointer: %q", stderr)
}
}
// TestPauseAutoBackupForSizeCap_PersistFailureIsNonFatal pins the contract
// the whole pause path rests on: it persists the throttle by writing
// backup_state.json INTO the directory it just declared over-cap, and in
// the disk-full case this cap exists for that write fails. The skip and
// its operator warning must still happen — a failure to record the
// throttle must never block the already-decided skip, nor escape.
func TestPauseAutoBackupForSizeCap_PersistFailureIsNonFatal(t *testing.T) {
if os.Geteuid() == 0 {
t.Skip("running as root; chmod does not deny writes")
}
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
dir := t.TempDir()
// Make the destination read-only so saveBackupState can never persist
// the throttle timestamp — the same failure mode as the disk-full case
// this cap exists for.
if err := os.Chmod(dir, 0o500); err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = os.Chmod(dir, 0o700) }) // let t.TempDir() clean up
state := &backupState{}
stderr := captureStderr(t, func() {
pauseAutoBackupForSizeCap(dir, state, 3*1024*1024*1024)
})
if !strings.Contains(stderr, "PAUSED") {
t.Fatalf("expected a PAUSED warning even when the throttle cannot be persisted, got %q", stderr)
}
// The in-memory state still carries the re-armed throttle, so the rest
// of this process behaves as though it had been recorded.
if state.Timestamp.IsZero() {
t.Error("interval throttle not re-armed in memory when persistence failed")
}
if state.LastCapWarnAt.IsZero() {
t.Error("warn timestamp not recorded in memory when persistence failed")
}
}
// TestMaybeAutoBackup_CapCheckSkippedWhenThrottled pins the ga-y6gjv PR
// review's performance fix: the size-cap directory walk must not run when
// the interval throttle would already skip the backup — the reviewer
// measured 65-100ms per bd invocation at 20k files in the backup dir if
// the cap check runs unconditionally before the throttle. Detected
// indirectly: if the cap check ran, it would find the destination over
// cap and persist LastCapWarnAt via pauseAutoBackupForSizeCap; if the
// interval throttle short-circuits first (as it must), LastCapWarnAt
// stays exactly as pre-seeded (zero). The cap check now sits after change
// detection too, so the store reports a commit that differs from the
// seeded watermark: otherwise change detection alone would stop the walk
// and this test would pass without the throttle.
func TestMaybeAutoBackup_CapCheckSkippedWhenThrottled(t *testing.T) {
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
repo := t.TempDir()
if err := os.MkdirAll(filepath.Join(repo, ".git"), 0o755); err != nil {
t.Fatal(err)
}
t.Setenv("BD_BACKUP_GIT_REPO", repo)
t.Setenv("BD_BACKUP_ENABLED", "1")
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "1")
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
dir, err := backupDir()
if err != nil {
t.Fatalf("backupDir: %v", err)
}
// Push the destination over the 1MB cap...
if err := os.WriteFile(filepath.Join(dir, "filler"), make([]byte, 2*1024*1024), 0o600); err != nil {
t.Fatal(err)
}
// ...but seed a fresh backup timestamp so the interval throttle (15m
// default) fires first, before the cap check ever gets a chance to run.
seeded := &backupState{Timestamp: time.Now().UTC(), LastDoltCommit: "oldcommit"}
if err := saveBackupState(dir, seeded); err != nil {
t.Fatal(err)
}
oldStore := store
// Different commit from the watermark ⇒ change detection would pass,
// so only the interval throttle can keep the walk from running.
fake := &failingBackupStore{commit: "deadbeef", backupErr: nil}
store = fake
t.Cleanup(func() { store = oldStore })
maybeAutoBackup(context.Background())
if fake.backupCalls != 0 {
t.Fatalf("BackupDatabase should not be called while throttled, got %d calls", fake.backupCalls)
}
st, err := loadBackupState(dir)
if err != nil {
t.Fatalf("loadBackupState: %v", err)
}
if !st.LastCapWarnAt.IsZero() {
t.Error("LastCapWarnAt was set — size-cap check ran despite the interval throttle, want it skipped entirely")
}
}
// TestMaybeAutoBackup_CapCheckSkippedWhenUnchanged pins the first half of
// the PR #6071 review's gating finding: the size-cap walk must sit AFTER
// change detection, so an IDLE workspace — nothing new committed since the
// last backup — never pays it.
//
// The interval throttle alone cannot cover this case, because only a
// backup attempt advances state.Timestamp: an idle workspace never reaches
// runBackupExport, so the throttle can never re-arm and, with the walk
// ahead of change detection, every single bd command paid the full
// filepath.Walk indefinitely.
//
// Detected the same way as the throttle test above: if the cap check ran,
// it would find the destination over cap and record LastCapWarnAt.
func TestMaybeAutoBackup_CapCheckSkippedWhenUnchanged(t *testing.T) {
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
repo := t.TempDir()
if err := os.MkdirAll(filepath.Join(repo, ".git"), 0o755); err != nil {
t.Fatal(err)
}
t.Setenv("BD_BACKUP_GIT_REPO", repo)
t.Setenv("BD_BACKUP_ENABLED", "1")
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "1")
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
dir, err := backupDir()
if err != nil {
t.Fatalf("backupDir: %v", err)
}
// Push the destination over the 1MB cap, so any walk that runs finds
// it exceeded and leaves a mark.
if err := os.WriteFile(filepath.Join(dir, "filler"), make([]byte, 2*1024*1024), 0o600); err != nil {
t.Fatal(err)
}
// Last backup an hour ago: the 15m interval throttle has passed, so
// change detection — not the throttle — is what must stop this.
seeded := &backupState{Timestamp: time.Now().UTC().Add(-time.Hour), LastDoltCommit: "deadbeef"}
if err := saveBackupState(dir, seeded); err != nil {
t.Fatal(err)
}
want, err := loadBackupState(dir)
if err != nil {
t.Fatalf("loadBackupState: %v", err)
}
oldStore := store
// Same commit as the recorded watermark ⇒ nothing changed ⇒ idle.
fake := &failingBackupStore{commit: "deadbeef", backupErr: nil}
store = fake
t.Cleanup(func() { store = oldStore })
maybeAutoBackup(context.Background())
if fake.backupCalls != 0 {
t.Fatalf("BackupDatabase should not be called when nothing changed, got %d calls", fake.backupCalls)
}
st, err := loadBackupState(dir)
if err != nil {
t.Fatalf("loadBackupState: %v", err)
}
if !st.LastCapWarnAt.IsZero() {
t.Error("LastCapWarnAt was set — the size-cap walk ran on an idle workspace, want it skipped entirely (it would then run on every bd command, forever)")
}
if !st.Timestamp.Equal(want.Timestamp) {
t.Errorf("timestamp = %v, want it untouched at %v: the idle path must not write state at all, or an idle period would cost up to one backup.interval of extra latency",
st.Timestamp, want.Timestamp)
}
}
// TestMaybeAutoBackup_PausedSkipArmsIntervalThrottle pins the second half
// of the PR #6071 review's gating finding, and is the positive control for
// the idle test above: with data genuinely changed, the cap walk DOES run
// and finds the destination over cap — and that skip must re-arm the
// interval throttle it would otherwise never reach.
//
// PAUSED is the pathological state: an over-cap destination is by
// definition the largest one, so without this the feature's terminal state
// is its most expensive, paying the full walk on every bd command until an
// operator intervenes. LastDoltCommit stays untouched so change detection
// still sees the pending work once the cap is raised.
func TestMaybeAutoBackup_PausedSkipArmsIntervalThrottle(t *testing.T) {
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
repo := t.TempDir()
if err := os.MkdirAll(filepath.Join(repo, ".git"), 0o755); err != nil {
t.Fatal(err)
}
t.Setenv("BD_BACKUP_GIT_REPO", repo)
t.Setenv("BD_BACKUP_ENABLED", "1")
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "1")
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
dir, err := backupDir()
if err != nil {
t.Fatalf("backupDir: %v", err)
}
if err := os.WriteFile(filepath.Join(dir, "filler"), make([]byte, 2*1024*1024), 0o600); err != nil {
t.Fatal(err)
}
seededAt := time.Now().UTC().Add(-time.Hour)
seeded := &backupState{Timestamp: seededAt, LastDoltCommit: "oldcommit"}
if err := saveBackupState(dir, seeded); err != nil {
t.Fatal(err)
}
oldStore := store
// Different commit from the watermark ⇒ data changed ⇒ the cap check
// is reached.
fake := &failingBackupStore{commit: "deadbeef", backupErr: nil}
store = fake
t.Cleanup(func() { store = oldStore })
maybeAutoBackup(context.Background())
if fake.backupCalls != 0 {
t.Fatalf("BackupDatabase should not be called once the size cap is exceeded, got %d calls", fake.backupCalls)
}
st, err := loadBackupState(dir)
if err != nil {
t.Fatalf("loadBackupState: %v", err)
}
if st.LastCapWarnAt.IsZero() {
t.Fatal("LastCapWarnAt not set — the cap path never ran, so this test proves nothing about the skip")
}
if !st.Timestamp.After(seededAt) {
t.Errorf("timestamp = %v, want it advanced past %v: the cap skip must re-arm the interval throttle or the walk reruns on every bd command",
st.Timestamp, seededAt)
}
if st.LastDoltCommit != "oldcommit" {
t.Errorf("last_dolt_commit = %q, want %q left untouched so change detection still sees pending work once the cap is raised",
st.LastDoltCommit, "oldcommit")
}
}
// TestWarnBackupSizeCapUnavailable_IsOperatorVisible pins the PR #6071
// review's error-handling minor: getDirSize aborts its whole walk on the
// first unreadable entry, and maybeAutoBackup then proceeds UNCAPPED. That
// is the right direction (fail open), but it used to happen behind a
// debug-only line, so the cap could silently disable itself and restore
// the unbounded growth the feature exists to prevent. The operator must be
// told, on stderr, both that the measurement failed and what it costs.
func TestWarnBackupSizeCapUnavailable_IsOperatorVisible(t *testing.T) {
stderr := captureStderr(t, func() {
warnBackupSizeCapUnavailable(errors.New("permission denied"))
})
if !strings.Contains(stderr, "permission denied") {
t.Errorf("warning does not name the underlying error: %q", stderr)
}
if !strings.Contains(stderr, "cap") {
t.Errorf("warning does not say the size cap is what failed: %q", stderr)
}
if !strings.Contains(stderr, "unbounded") {
t.Errorf("warning does not state the consequence — the backup proceeds uncapped: %q", stderr)
}
}
// TestSizeCapStatus_UnavailableOnWalkError pins the PR #6071 review's
// render-asymmetry nit: on a non-ENOENT getDirSize error the human status
// path used to drop the "Size cap:" line entirely — indistinguishable from
// "no cap configured" for an operator debugging a permission problem —
// while --json reported the error all along. The JSON error object must
// also carry an explicit null `exceeded`, because a consumer reading a
// missing key as false sees "not exceeded" during exactly the failure that
// makes it unmeasurable.
func TestSizeCapStatus_UnavailableOnWalkError(t *testing.T) {
if os.Geteuid() == 0 {
t.Skip("running as root; chmod does not deny reads")
}
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "1")
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
dir := t.TempDir()
// Unreadable, but present: getDirSize fails with a permission error,
// which is NOT os.IsNotExist, so it takes the error branch rather than
// the "destination not created yet" branch.
if err := os.Chmod(dir, 0o000); err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = os.Chmod(dir, 0o700) }) // let t.TempDir() clean up
stdout := captureStdout(t, func() error {
showSizeCapStatus(dir)
return nil
})
if !strings.Contains(stdout, "Size cap: unavailable") {
t.Errorf("human status dropped the size-cap line on a walk error, want an explicit `unavailable`: %q", stdout)
}
got := showSizeCapStatusJSON(dir)
if got["error"] == nil || got["error"] == "" {
t.Errorf("JSON status omits the walk error: %#v", got)
}
exceeded, ok := got["exceeded"]
if !ok {
t.Errorf("JSON error object omits `exceeded`; a consumer reading the missing key as false sees `not exceeded`: %#v", got)
}
if exceeded != nil {
t.Errorf("exceeded = %#v, want an explicit null while the size is unmeasurable", exceeded)
}
}
// postSyncCommitFailingStore syncs successfully but then fails the
// GetCurrentCommit that runBackupExport needs to record its watermark — one
// of the runBackupExport exits that returns without persisting state. Every
// other GetCurrentCommit (change detection) succeeds.
type postSyncCommitFailingStore struct {
failingBackupStore
justSynced bool
}
func (f *postSyncCommitFailingStore) BackupDatabase(ctx context.Context, dir string) error {
f.justSynced = true
return f.failingBackupStore.BackupDatabase(ctx, dir)
}
func (f *postSyncCommitFailingStore) GetCurrentCommit(context.Context) (string, error) {
if f.justSynced {
f.justSynced = false
return "", errors.New("dolt server unavailable")
}
return f.commit, nil
}
// TestMaybeAutoBackup_WalkErrorArmsIntervalThrottle pins the PR #6071
// iteration-2 review's behavioral minor: when the size-cap walk fails,
// maybeAutoBackup warns and proceeds uncapped, and it must re-arm the
// interval throttle itself before doing so. runBackupExport does not persist
// state.Timestamp on every exit — here the post-sync GetCurrentCommit fails
// after a successful sync — so without the re-arm the walk, its warning and
// the sync itself all repeat on every bd command instead of once per
// backup.interval.
func TestMaybeAutoBackup_WalkErrorArmsIntervalThrottle(t *testing.T) {
if os.Geteuid() == 0 {
t.Skip("running as root; chmod does not deny reads")
}
t.Chdir(t.TempDir())
// The sync has to actually run for this test to reach runBackupExport's
// non-persisting exit, so give the command a real workspace: a
// workspace-scoped step on the way (a backup lock, for one) must not
// skip the sync before it starts.
prepareBackupStatusTest(t)
repo := t.TempDir()
if err := os.MkdirAll(filepath.Join(repo, ".git"), 0o755); err != nil {
t.Fatal(err)
}
t.Setenv("BD_BACKUP_GIT_REPO", repo)
t.Setenv("BD_BACKUP_ENABLED", "1")
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "1")
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
dir, err := backupDir()
if err != nil {
t.Fatalf("backupDir: %v", err)
}
// One unreadable entry inside an otherwise writable destination: the
// walk fails, but backup_state.json can still be read and written.
locked := filepath.Join(dir, "locked")
if err := os.Mkdir(locked, 0o000); err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = os.Chmod(locked, 0o700) }) // let t.TempDir() clean up
seededAt := time.Now().UTC().Add(-time.Hour)
seeded := &backupState{Timestamp: seededAt, LastDoltCommit: "oldcommit"}
if err := saveBackupState(dir, seeded); err != nil {
t.Fatal(err)
}
oldStore := store
// Different commit from the watermark ⇒ data changed ⇒ the walk runs.
fake := &postSyncCommitFailingStore{failingBackupStore: failingBackupStore{commit: "deadbeef"}}
store = fake
t.Cleanup(func() { store = oldStore })
first := captureStderr(t, func() { maybeAutoBackup(context.Background()) })
if !strings.Contains(first, "could not be measured") {
t.Fatalf("the walk error never reached its warning, so this test proves nothing: %q", first)
}
if fake.backupCalls != 1 {
t.Fatalf("BackupDatabase calls = %d, want 1: an unmeasurable destination must fail open and still sync", fake.backupCalls)
}
st, err := loadBackupState(dir)
if err != nil {
t.Fatalf("loadBackupState: %v", err)
}
if !st.Timestamp.After(seededAt) {
t.Errorf("timestamp = %v, want it advanced past %v: runBackupExport returned without persisting it, so the walk-error path must re-arm the interval throttle",
st.Timestamp, seededAt)
}
if st.LastDoltCommit != "oldcommit" {
t.Errorf("last_dolt_commit = %q, want %q left untouched: no watermark was recorded, so change detection must still see the pending work",
st.LastDoltCommit, "oldcommit")
}
second := captureStderr(t, func() { maybeAutoBackup(context.Background()) })
if strings.Contains(second, "could not be measured") {
t.Errorf("the walk-error warning repeated on the very next command, want it bounded by the interval throttle: %q", second)
}
if fake.backupCalls != 1 {
t.Errorf("BackupDatabase calls = %d after a second command, want still 1: the interval throttle should have stopped it", fake.backupCalls)
}
}
// TestShowSizeCapStatus_DisabledEchoesConfiguredValue pins the PR #6071
// iteration-2 review's debuggability minor: viper's GetInt resolves an
// unparseable backup.size-cap-mb ("2048MB") to 0, which disables the cap,
// so the status line must echo what is actually configured rather than
// asserting "backup.size-cap-mb=0", a value the operator never wrote.
func TestShowSizeCapStatus_DisabledEchoesConfiguredValue(t *testing.T) {
for _, raw := range []string{"0", "2048MB"} {
t.Run(raw, func(t *testing.T) {
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
t.Setenv("BD_BACKUP_SIZE_CAP_MB", raw)
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
if got := effectiveSizeCapMB(); got != 0 {
t.Fatalf("effectiveSizeCapMB() = %d for %q, want 0 (cap disabled), or this test proves nothing", got, raw)
}
stdout := captureStdout(t, func() error {
showSizeCapStatus(t.TempDir())
return nil
})
want := "Size cap: disabled (backup.size-cap-mb=" + raw + ")"
if !strings.Contains(stdout, want) {
t.Errorf("status = %q, want it to contain %q", stdout, want)
}
})
}
}
// TestSizeCapStatus_MidWalkNotExistIsUnavailable pins the PR #6071
// iteration-2 review's error-handling minor: only a destination that does
// not exist yet may read as empty. An ENOENT from inside the walk — a chunk
// file removed between listing and stat-ing it — used to be swallowed as
// size 0, reporting `"exceeded": false` for a destination that may be well
// over its cap, which is exactly what the explicit-null `exceeded` on the
// error branch exists to prevent.
func TestSizeCapStatus_MidWalkNotExistIsUnavailable(t *testing.T) {
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "1")
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
t.Run("missing destination reads as empty", func(t *testing.T) {
missing := filepath.Join(t.TempDir(), "not-created-yet")
stdout := captureStdout(t, func() error {
showSizeCapStatus(missing)
return nil
})
if !strings.Contains(stdout, "Size cap: 0 B / ") {
t.Errorf("status for a not-yet-created destination = %q, want an empty `Size cap: 0 B / ...`", stdout)
}
got := showSizeCapStatusJSON(missing)
if got["exceeded"] != false || got["current_bytes"] != int64(0) {
t.Errorf("JSON status for a not-yet-created destination = %#v, want current_bytes 0 and exceeded false", got)
}
})
t.Run("ENOENT inside an existing destination is unavailable", func(t *testing.T) {
dir := t.TempDir()
vanished := &fs.PathError{Op: "lstat", Path: filepath.Join(dir, "chunk"), Err: fs.ErrNotExist}
if !os.IsNotExist(vanished) {
t.Fatalf("injected error is not an os.IsNotExist error, so this test proves nothing: %v", vanished)
}
oldWalk := walkBackupDestination
walkBackupDestination = func(string) (int64, error) { return 0, vanished }
t.Cleanup(func() { walkBackupDestination = oldWalk })
stdout := captureStdout(t, func() error {
showSizeCapStatus(dir)
return nil
})
if !strings.Contains(stdout, "Size cap: unavailable") {
t.Errorf("status after a mid-walk ENOENT = %q, want `Size cap: unavailable`, not a size", stdout)
}
got := showSizeCapStatusJSON(dir)
exceeded, ok := got["exceeded"]
if !ok || exceeded != nil {
t.Errorf("JSON status after a mid-walk ENOENT = %#v, want an explicit null `exceeded`", got)
}
if got["error"] == nil || got["error"] == "" {
t.Errorf("JSON status omits the walk error: %#v", got)
}
})
}

View file

@ -19,6 +19,7 @@ import (
type backupState struct {
LastDoltCommit string `json:"last_dolt_commit"`
Timestamp time.Time `json:"timestamp"`
LastCapWarnAt time.Time `json:"last_cap_warn_at"`
}
// backupDir returns the backup directory path, creating it if needed.

View file

@ -8,6 +8,7 @@ import (
"path/filepath"
"strings"
"testing"
"time"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/configfile"
@ -160,6 +161,135 @@ func TestBackupStatusIncludesAvailableDatabaseSize(t *testing.T) {
})
}
// TestBackupStatusShowsSizeCapPaused pins the PR #6071 review's second
// major point: `bd --json` / `--quiet` callers never saw the size-cap
// pause — the warning is stderr-only and throttled, and status previously
// said nothing about the cap, so an agent/CI caller saw a reassuring
// "Last backup" line while auto-backup was silently, permanently paused.
func TestBackupStatusShowsSizeCapPaused(t *testing.T) {
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "1")
prepareBackupStatusTest(t)
sizeDatabase := func(context.Context) (int64, bool, error) { return 0, false, nil }
dir, err := backupDir()
if err != nil {
t.Fatalf("backupDir: %v", err)
}
if err := os.WriteFile(filepath.Join(dir, "filler"), make([]byte, 2*1024*1024), 0o600); err != nil {
t.Fatal(err)
}
seeded := &backupState{Timestamp: time.Now().UTC().Add(-time.Hour), LastDoltCommit: "deadbeef"}
if err := saveBackupState(dir, seeded); err != nil {
t.Fatal(err)
}
t.Run("json", func(t *testing.T) {
cmd := newBackupStatusTestRoot(sizeDatabase)
cmd.SetArgs([]string{"backup", "status", "--json"})
stdout, stderr, err := executeBackupStatusCommand(t, cmd)
if err != nil {
t.Fatalf("backup status: %v", err)
}
if stderr != "" {
t.Errorf("stderr = %q, want empty", stderr)
}
var response struct {
SizeCap struct {
Enabled bool `json:"enabled"`
CapMB int `json:"cap_mb"`
CurrentBytes int64 `json:"current_bytes"`
Exceeded bool `json:"exceeded"`
} `json:"size_cap"`
}
if err := json.Unmarshal([]byte(stdout), &response); err != nil {
t.Fatalf("stdout is not valid JSON: %v\nstdout: %s", err, stdout)
}
if !response.SizeCap.Enabled {
t.Errorf("size_cap.enabled = false, want true: %s", stdout)
}
if !response.SizeCap.Exceeded {
t.Errorf("size_cap.exceeded = false, want true: %s", stdout)
}
if response.SizeCap.CapMB != 1 {
t.Errorf("size_cap.cap_mb = %d, want 1: %s", response.SizeCap.CapMB, stdout)
}
if response.SizeCap.CurrentBytes < 2*1024*1024 {
t.Errorf("size_cap.current_bytes = %d, want >= 2MB: %s", response.SizeCap.CurrentBytes, stdout)
}
})
t.Run("human", func(t *testing.T) {
cmd := newBackupStatusTestRoot(sizeDatabase)
cmd.SetArgs([]string{"backup", "status"})
stdout, stderr, err := executeBackupStatusCommand(t, cmd)
if err != nil {
t.Fatalf("backup status: %v", err)
}
if stderr != "" {
t.Errorf("stderr = %q, want empty", stderr)
}
if !strings.Contains(stdout, "PAUSED (cap exceeded)") {
t.Errorf("status text missing PAUSED indicator: %s", stdout)
}
})
}
// TestBackupStatusShowsSizeCapDisabled pins the PR #6071 review's first
// major point from the status side: backup.size-cap-mb: 0 must render as
// disabled in status, not silently report the legacy 2048MB default.
func TestBackupStatusShowsSizeCapDisabled(t *testing.T) {
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "0")
prepareBackupStatusTest(t)
sizeDatabase := func(context.Context) (int64, bool, error) { return 0, false, nil }
dir, err := backupDir()
if err != nil {
t.Fatalf("backupDir: %v", err)
}
seeded := &backupState{Timestamp: time.Now().UTC().Add(-time.Hour), LastDoltCommit: "deadbeef"}
if err := saveBackupState(dir, seeded); err != nil {
t.Fatal(err)
}
t.Run("json", func(t *testing.T) {
cmd := newBackupStatusTestRoot(sizeDatabase)
cmd.SetArgs([]string{"backup", "status", "--json"})
stdout, _, err := executeBackupStatusCommand(t, cmd)
if err != nil {
t.Fatalf("backup status: %v", err)
}
var raw map[string]json.RawMessage
if err := json.Unmarshal([]byte(stdout), &raw); err != nil {
t.Fatalf("stdout is not valid JSON: %v\nstdout: %s", err, stdout)
}
sizeCapRaw, ok := raw["size_cap"]
if !ok {
t.Fatalf("size_cap key missing from status JSON: %s", stdout)
}
var sizeCap struct {
Enabled bool `json:"enabled"`
}
if err := json.Unmarshal(sizeCapRaw, &sizeCap); err != nil {
t.Fatalf("size_cap is not valid JSON: %v\nraw: %s", err, sizeCapRaw)
}
if sizeCap.Enabled {
t.Errorf("size_cap.enabled = true with backup.size-cap-mb=0, want false: %s", stdout)
}
})
t.Run("human", func(t *testing.T) {
cmd := newBackupStatusTestRoot(sizeDatabase)
cmd.SetArgs([]string{"backup", "status"})
stdout, _, err := executeBackupStatusCommand(t, cmd)
if err != nil {
t.Fatalf("backup status: %v", err)
}
if !strings.Contains(stdout, "Size cap: disabled") {
t.Errorf("status text missing disabled size-cap line: %s", stdout)
}
})
}
// TestBackupStatusProxiedGuardFollowsLocality replaces a test that asserted a
// blanket proxied refusal. Since slice S3 the guard is scoped to locality: bd
// owns the dolt process on a managed-local workspace and can honor the command

View file

@ -986,7 +986,6 @@ func init() {
compactCmd.Flags().IntVar(&compactBatch, "batch-size", 10, "Issues per batch")
compactCmd.Flags().IntVar(&compactWorkers, "workers", 5, "Parallel workers")
compactCmd.Flags().BoolVar(&compactStats, "stats", false, "Show compaction statistics")
compactCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output JSON format")
// New mode flags
compactCmd.Flags().BoolVar(&compactAnalyze, "analyze", false, "Analyze mode: export candidates for agent review")

View file

@ -345,9 +345,9 @@ func TestCompactInitCommand(t *testing.T) {
t.Error("compactCmd should have Long description")
}
// Verify --json flag exists
jsonFlag := compactCmd.Flags().Lookup("json")
if jsonFlag == nil {
t.Error("compact command should have --json flag")
// --json is inherited from rootCmd as a persistent flag; a local copy
// would shadow it (see TestNoSubcommandShadowsRootJSONFlag).
if f := compactCmd.Flags().Lookup("json"); f != nil && f != rootCmd.PersistentFlags().Lookup("json") {
t.Error("compact command must not register a local --json; it inherits the root flag")
}
}

View file

@ -38,6 +38,44 @@ func TestCountIncludeInfraFlagShape(t *testing.T) {
}
}
// TestCountIncludeEphemeralFlagShape is the same pin for --include-ephemeral,
// plus the case TestParseCountRequestCarriesEveryFilterFlag cannot see because
// it sets both plane flags at once: --include-ephemeral ALONE must not reach
// the role as IncludeInfra, which would also drop templates and gates from
// the count.
func TestCountIncludeEphemeralFlagShape(t *testing.T) {
flag := countCmd.Flags().Lookup("include-ephemeral")
if flag == nil {
t.Fatal("bd count must expose an --include-ephemeral flag")
}
if flag.DefValue != "false" {
t.Fatalf("--include-ephemeral must default to false, got %q", flag.DefValue)
}
request, _, err := parseCountRequest(newCountFlagSet(t))
if err != nil {
t.Fatalf("parseCountRequest with no flags set: %v", err)
}
if request.IncludeEphemeral {
t.Error("IncludeEphemeral = true with no flags set, want the durable-only default")
}
flags := newCountFlagSet(t)
if err := flags.Flags().Set("include-ephemeral", "true"); err != nil {
t.Fatalf("set --include-ephemeral: %v", err)
}
request, _, err = parseCountRequest(flags)
if err != nil {
t.Fatalf("parseCountRequest --include-ephemeral: %v", err)
}
if !request.IncludeEphemeral {
t.Error("IncludeEphemeral = false with --include-ephemeral set; the flag was dropped on the way into the request")
}
if request.IncludeInfra {
t.Error("IncludeInfra = true with only --include-ephemeral set; it is the plane bit and nothing else")
}
}
// TestParseCountRequestCarriesEveryFilterFlag is the tripwire for a flag that
// is registered, documented and silently dropped on the way into the request.
// Every filter flag is set to a value distinguishable from its zero and read

View file

@ -233,7 +233,7 @@ var createCmd = &cobra.Command{
if dueStr != "" {
t, err := timeparsing.ParseRelativeTime(dueStr, time.Now())
if err != nil {
return HandleError("invalid --due format %q. Examples: +6h, tomorrow, next monday, 2025-01-15", dueStr)
return HandleError("invalid --due format %q. %s", dueStr, deferUntilFormatHint)
}
dueAt = &t
}
@ -243,7 +243,7 @@ var createCmd = &cobra.Command{
if deferStr != "" {
t, err := timeparsing.ParseRelativeTime(deferStr, time.Now())
if err != nil {
return HandleError("invalid --defer format %q. Examples: +1h, tomorrow, next monday, 2025-01-15", deferStr)
return HandleError("invalid --defer format %q. %s", deferStr, deferUntilFormatHint)
}
// Warn if defer date is in the past (user probably meant future)
if t.Before(time.Now()) && !silent && !debug.IsQuiet() {

View file

@ -252,7 +252,7 @@ func gatherCreateInput(cmd *cobra.Command, args []string) (createInput, error) {
if dueStr, _ := cmd.Flags().GetString("due"); dueStr != "" {
t, err := timeparsing.ParseRelativeTime(dueStr, time.Now())
if err != nil {
return in, HandleError("invalid --due format %q. Examples: +6h, tomorrow, next monday, 2025-01-15", dueStr)
return in, HandleError("invalid --due format %q. %s", dueStr, deferUntilFormatHint)
}
in.dueAt = &t
}
@ -260,7 +260,7 @@ func gatherCreateInput(cmd *cobra.Command, args []string) (createInput, error) {
if deferStr, _ := cmd.Flags().GetString("defer"); deferStr != "" {
t, err := timeparsing.ParseRelativeTime(deferStr, time.Now())
if err != nil {
return in, HandleError("invalid --defer format %q. Examples: +1h, tomorrow, next monday, 2025-01-15", deferStr)
return in, HandleError("invalid --defer format %q. %s", deferStr, deferUntilFormatHint)
}
if t.Before(time.Now()) && !in.silent && !debug.IsQuiet() {
fmt.Fprintf(os.Stderr, "%s Defer date %q is in the past. Issue will appear in bd ready immediately.\n",

View file

@ -14,6 +14,13 @@ import (
"github.com/steveyegge/beads/internal/utils"
)
// deferUntilFormatHint restates the vocabulary of
// timeparsing.ParseCompactDuration for every flag that reaches it. The unit set
// and its order track that parser's doc comment, so a unit added there must be
// added here too -- TestDeferUntilFormatHintCoversCompactUnits only catches
// units this constant already names.
const deferUntilFormatHint = "Use a relative offset [+-]?<n><unit> with unit min=minutes, h=hours, d=days, w=weeks, m=months, y=years (+30min, +1h, +3m), natural language (tomorrow, next monday), or a date (2025-01-15)"
var deferCmd = &cobra.Command{
Use: "defer [id...]",
Short: "Defer one or more issues for later",
@ -52,7 +59,7 @@ Examples:
if untilStr != "" {
t, err := timeparsing.ParseRelativeTime(untilStr, time.Now())
if err != nil {
return HandleError("invalid --until format %q. Examples: +1h, tomorrow, next monday, 2025-01-15", untilStr)
return HandleError("invalid --until format %q. %s", untilStr, deferUntilFormatHint)
}
if t.Before(time.Now()) && !jsonOutput {
fmt.Fprintf(os.Stderr, "%s Defer date %q is in the past. Issue will appear in bd ready immediately.\n",

View file

@ -0,0 +1,224 @@
package main
import (
"encoding/json"
"os"
"path/filepath"
"regexp"
"strings"
"testing"
"time"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/timeparsing"
)
// TestDeferUntilFormatHintCoversCompactUnits keeps the --until failure message
// and the parser it describes in step. "+3mo" is rejected while "+3m" is three
// months, so a message naming one example leaves the caller trying units one at
// a time to find the boundary. "min" is the sharpest case: "+3m" is months and
// "+30min" is minutes, which is why the parser's own doc comment spells out
// "m = months (NOT minutes; use \"min\" for minutes)".
func TestDeferUntilFormatHintCoversCompactUnits(t *testing.T) {
now := time.Date(2026, 1, 15, 12, 0, 0, 0, time.UTC)
for _, unit := range []string{"min", "h", "d", "w", "m", "y"} {
value := "+3" + unit
if _, err := timeparsing.ParseRelativeTime(value, now); err != nil {
t.Errorf("parser rejected %q, which the --until hint names as supported: %v", value, err)
}
if !strings.Contains(deferUntilFormatHint, unit+"=") {
t.Errorf("--until hint does not name unit %q: %s", unit, deferUntilFormatHint)
}
}
if _, err := timeparsing.ParseRelativeTime("+3mo", now); err == nil {
t.Fatal("expected +3mo to be rejected; the hint exists to send that caller to +3m")
}
if !strings.Contains(deferUntilFormatHint, "+3m") {
t.Errorf("--until hint should show the month form +3m: %s", deferUntilFormatHint)
}
}
// TestDeferUntilRejectionNamesUnitSet exercises the real --until failure path
// and asserts the unit set reaches stderr, so dropping the hint from the error
// fails here rather than only degrading the message.
func TestDeferUntilRejectionNamesUnitSet(t *testing.T) {
if err := deferCmd.Flags().Set("until", "+3mo"); err != nil {
t.Fatalf("setting --until: %v", err)
}
t.Cleanup(func() {
if err := deferCmd.Flags().Set("until", ""); err != nil {
t.Fatalf("resetting --until: %v", err)
}
deferCmd.Flags().Lookup("until").Changed = false
})
var err error
output := captureStderr(t, func() {
err = deferCmd.RunE(deferCmd, []string{"t-1"})
})
if err == nil {
t.Fatal("expected --until=+3mo to fail")
}
if !strings.Contains(output, `invalid --until format "+3mo"`) {
t.Fatalf("expected the rejected value in the error, got: %s", output)
}
for _, unit := range []string{"min=minutes", "h=hours", "d=days", "w=weeks", "m=months", "y=years"} {
if !strings.Contains(output, unit) {
t.Errorf("expected the error to name %q, got: %s", unit, output)
}
}
}
// TestRelativeTimeRejectionsShareTheHint guards the half of this fix that no
// behavioural test can reach cheaply. --defer and --due land on the same
// parser as --until, through the direct create and update paths and through
// their proxied-input twins, so a caller who mistypes any of them deserves the
// same unit set. A site that re-inlines its own example list still passes every
// call-level test while sending that caller back on the hunt, which is why the
// uniformity is pinned at the source. Blunt line matching, in the style of
// TestCobraParallelPolicyGuard.
//
// The matching is deliberately per-line, which constrains how a site may be
// written: a compliant call wrapped so that the format string and
// deferUntilFormatHint land on different lines would be reported here. All nine
// sites today are single-line, so keep them that way rather than loosening the
// guard.
func TestRelativeTimeRejectionsShareTheHint(t *testing.T) {
sources, err := filepath.Glob("*.go")
if err != nil {
t.Fatalf("glob: %v", err)
}
rejection := regexp.MustCompile(`invalid --(?:until|defer|due) format`)
found := 0
for _, file := range sources {
if strings.HasSuffix(file, "_test.go") {
continue
}
data, err := os.ReadFile(file)
if err != nil {
t.Fatalf("read %s: %v", file, err)
}
for i, line := range strings.Split(string(data), "\n") {
if !rejection.MatchString(line) {
continue
}
found++
if !strings.Contains(line, "deferUntilFormatHint") {
t.Errorf("%s:%d rejects a relative-time flag without the shared hint: %s",
file, i+1, strings.TrimSpace(line))
}
}
}
if found == 0 {
t.Fatal("found no relative-time rejection sites; the guard is matching nothing")
}
}
// TestGatherInputRejectionsNameUnitSet exercises the proxied-input paths for
// both flags that share the hint, so the unit set is proven to reach a real
// caller rather than only to be present in the constant.
func TestGatherInputRejectionsNameUnitSet(t *testing.T) {
prevJSON := jsonOutput
jsonOutput = false
t.Cleanup(func() { jsonOutput = prevJSON })
units := []string{"min=minutes", "h=hours", "d=days", "w=weeks", "m=months", "y=years"}
assertNamesUnits := func(t *testing.T, flag, output string) {
t.Helper()
if !strings.Contains(output, `invalid `+flag+` format "+3mo"`) {
t.Fatalf("expected the rejected %s value in the error, got: %s", flag, output)
}
for _, unit := range units {
if !strings.Contains(output, unit) {
t.Errorf("expected the %s error to name %q, got: %s", flag, unit, output)
}
}
}
for _, flag := range []string{"--due", "--defer"} {
t.Run("create "+flag, func(t *testing.T) {
cmd := newCreateFlagsCommand(t, flag, "+3mo")
var err error
output := captureStderr(t, func() {
_, err = gatherCreateInput(cmd, []string{"title"})
})
if err == nil {
t.Fatalf("expected %s=+3mo to fail", flag)
}
assertNamesUnits(t, flag, output)
})
t.Run("update "+flag, func(t *testing.T) {
cmd := &cobra.Command{Use: "update"}
cmd.Flags().String("due", "", "Due date")
cmd.Flags().String("defer", "", "Defer until")
cmd.Flags().Bool("json", false, "JSON output")
if err := cmd.ParseFlags([]string{flag, "+3mo"}); err != nil {
t.Fatalf("parse update flags: %v", err)
}
var err error
output := captureStderr(t, func() {
_, err = gatherUpdateInput(t.Context(), cmd)
})
if err == nil {
t.Fatalf("expected %s=+3mo to fail", flag)
}
assertNamesUnits(t, flag, output)
})
}
// The four update sites use HandleErrorRespectJSON, which under --json emits
// the message on STDOUT inside a JSON error payload instead of on stderr. The
// subtests above pin jsonOutput = false, so that branch -- the one machine
// consumers read -- would otherwise carry this ~190-char hint untested.
// Assert on the DECODED message, not the raw bytes: json.Encoder HTML-escapes
// the angle brackets in the hint's "[+-]?<n><unit>" notation, so a
// strings.Contains over stdout would fail on a perfectly correct payload.
t.Run("update --defer json", func(t *testing.T) {
jsonOutput = true
t.Cleanup(func() { jsonOutput = false })
cmd := &cobra.Command{Use: "update"}
cmd.Flags().String("due", "", "Due date")
cmd.Flags().String("defer", "", "Defer until")
cmd.Flags().Bool("json", false, "JSON output")
if err := cmd.ParseFlags([]string{"--defer", "+3mo"}); err != nil {
t.Fatalf("parse update flags: %v", err)
}
var err error
output := captureStdout(t, func() error {
_, err = gatherUpdateInput(t.Context(), cmd)
return nil
})
if err == nil {
t.Fatal("expected --defer=+3mo to fail")
}
var payload struct {
Error string `json:"error"`
Data struct {
Error string `json:"error"`
} `json:"data"`
}
if jsonErr := json.Unmarshal([]byte(output), &payload); jsonErr != nil {
t.Fatalf("stdout was not a JSON error payload (%v), got: %s", jsonErr, output)
}
message := payload.Error
if message == "" {
// BD_JSON_ENVELOPE=1 nests the same fields under "data".
message = payload.Data.Error
}
if message == "" {
t.Fatalf("no error message in the JSON payload, got: %s", output)
}
assertNamesUnits(t, "--defer", message)
})
}

View file

@ -1365,7 +1365,9 @@ var depCyclesCmd = &cobra.Command{
// Both routes, one body: the only difference between them is which
// accessor answers, and that is inside openCycleDetector.
return runDepCycles()
includeTracks, _ := cmd.Flags().GetBool("include-tracks")
limit, _ := cmd.Flags().GetInt("limit")
return runDepCycles(includeTracks, limit)
},
}
@ -1668,6 +1670,23 @@ func init() {
depListCmd.Flags().String("direction", "down", "Direction: 'down' (dependencies), 'up' (dependents)")
depListCmd.Flags().StringP("type", "t", "", "Filter by dependency type (e.g., tracks, blocks, parent-child)")
// Widens the report, never narrows it: every cycle the default walk finds is
// kept, and cycles that close through tracks edges are added. A loop made
// only of tracks edges is still not reported, but that is the only thing
// the guard excludes: a tracks loop fuses a component and every scheduling
// edge inside it is then reported, so a tracks-dense workspace can print
// many cycles here even where the default walk prints none — hence
// --limit. See issueops.DetectCyclesRequest.IncludeTracks.
depCyclesCmd.Flags().Bool("include-tracks", false, "Also walk 'tracks' edges: reports every cycle the default walk finds plus cycles that close through a tracks edge, never a loop made only of tracks edges (diagnostic for molecule-root deadlocks hidden by tracks-only propagation)")
// Caps the RENDERED list only, and on BOTH walks: this does not consult
// --include-tracks, so it bounds the default invocation's rendering too.
// The widened walk is what makes the cap necessary rather than what scopes
// it — bounded by the scheduling-edge count, not by the number of
// deadlocks, so a tracks-dense workspace can report more cycles than a
// reader can use. The printed total stays the whole report's and --json is
// never truncated.
depCyclesCmd.Flags().Int("limit", 50, "Maximum cycles to print (0 = no limit); the reported total is always the whole count, and --json is never truncated")
// Issue ID completions for dep subcommands
depAddCmd.ValidArgsFunction = issueIDCompletion
depRemoveCmd.ValidArgsFunction = issueIDCompletion

View file

@ -36,13 +36,34 @@ func proxiedCycleDetector() (issueops.CycleDetector, error) {
return src.CycleDetector()
}
// runDepCycles is the whole of `bd dep cycles` on both routes.
func runDepCycles() error {
// runDepCycles is the whole of `bd dep cycles` on both routes. includeTracks
// widens the walk per issueops.DetectCyclesRequest.IncludeTracks; the default
// invocation leaves it false and the walk unchanged.
//
// limit caps how many cycles are PRINTED, and nothing else: 0 prints them all.
// THE CAP IS UNCONDITIONAL — it does not consult includeTracks, so it bounds
// the default walk's rendering too, and plain `bd dep cycles` now prints at most
// 50 cycles where before this change it printed every one. The widened walk is
// what makes the cap necessary rather than what scopes it: that walk is bounded
// by the scheduling-edge count and not by the number of deadlocks (see that
// field's BOUND), so a tracks-dense workspace can hold a correct report longer
// than anyone can read. Capping both walks by one rule is the deliberate
// choice — an operator can predict one rendering rule, and a --limit that
// silently did nothing without a second flag would be the worse surprise. It
// also matches --limit in list/search/stale/find_duplicates, which cap
// unconditionally.
//
// It stays a rendering cap rather than a narrower request on EITHER walk:
// CycleReport.Cycles promises to omit no cycle, and a --json consumer diffing
// two snapshots needs the whole of it. So the count this prints is always the
// whole report's, the truncation says how much it held back, and the --json
// branch below is never capped.
func runDepCycles(includeTracks bool, limit int) error {
detector, err := openCycleDetector()
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
report, err := detector.DetectCycles(rootCtx, issueops.DetectCyclesRequest{})
report, err := detector.DetectCycles(rootCtx, issueops.DetectCyclesRequest{IncludeTracks: includeTracks})
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
@ -59,7 +80,11 @@ func runDepCycles() error {
}
fmt.Printf("\n%s Found %d dependency cycles:\n\n", ui.RenderFail("⚠"), len(report.Cycles))
for i, cycle := range report.Cycles {
shown := report.Cycles
if limit > 0 && len(shown) > limit {
shown = shown[:limit]
}
for i, cycle := range shown {
if missing := unknownCycleMembers(cycle); missing > 0 {
fmt.Printf("%d. Cycle involving (%d of %d members have no record in this database):\n",
i+1, missing, len(cycle.Members))
@ -71,6 +96,10 @@ func runDepCycles() error {
}
fmt.Println()
}
if len(shown) < len(report.Cycles) {
fmt.Printf("... and %d more not shown. The count above is the whole report; use --limit 0 to print all of it.\n\n",
len(report.Cycles)-len(shown))
}
return nil
}

View file

@ -3,6 +3,7 @@ package main
import (
"bytes"
"context"
"fmt"
"io"
"os"
"runtime"
@ -33,7 +34,7 @@ func TestDepCyclesNamesTheMembersItCannotDescribe(t *testing.T) {
{ID: "bd-c", Issue: &types.Issue{ID: "bd-c", Title: "Gamma"}},
{ID: "bd-ghost"},
}},
}})
}}, 0)
})
if !strings.Contains(out, "Found 2 dependency cycles") {
@ -55,7 +56,7 @@ func TestDepCyclesNamesTheMembersItCannotDescribe(t *testing.T) {
func TestDepCyclesSaysNothingIsWrongForACleanWorkspace(t *testing.T) {
out := captureCycleStdout(t, func() {
printCycleReportForTest(t, issueops.CycleReport{Cycles: []issueops.Cycle{}})
printCycleReportForTest(t, issueops.CycleReport{Cycles: []issueops.Cycle{}}, 0)
})
if !strings.Contains(out, "No dependency cycles detected") {
t.Errorf("a clean workspace did not say so:\n%s", out)
@ -124,8 +125,9 @@ func TestCycleWarningIsSilentWithoutCycles(t *testing.T) {
}
// printCycleReportForTest drives `bd dep cycles`'s human rendering with a
// report, through the same role the command uses.
func printCycleReportForTest(t *testing.T, report issueops.CycleReport) {
// report, through the same role the command uses. limit is the rendering cap
// runDepCycles takes; 0 prints the whole report.
func printCycleReportForTest(t *testing.T, report issueops.CycleReport, limit int) {
t.Helper()
previousStore := store
previousJSON := jsonOutput
@ -136,11 +138,183 @@ func printCycleReportForTest(t *testing.T, report issueops.CycleReport) {
jsonOutput = previousJSON
}()
if err := runDepCycles(); err != nil {
if err := runDepCycles(false, limit); err != nil {
t.Fatalf("runDepCycles: %v", err)
}
}
// TestDepCyclesFlagRegistration pins the --include-tracks flag itself: it
// exists on the command, is a bool, and defaults to false so an invocation
// with no flag leaves the base (blocks/conditional-blocks-only) walk
// unchanged.
func TestDepCyclesFlagRegistration(t *testing.T) {
flag := depCyclesCmd.Flags().Lookup("include-tracks")
if flag == nil {
t.Fatal("depCyclesCmd has no --include-tracks flag")
}
if flag.Value.Type() != "bool" {
t.Errorf("--include-tracks is a %s, want bool", flag.Value.Type())
}
if flag.DefValue != "false" {
t.Errorf("--include-tracks defaults to %q, want \"false\"", flag.DefValue)
}
}
// TestDepCyclesLimitFlagRegistration pins the rendering cap: an int flag whose
// default is not 0, so any workspace dense enough to report more cycles than a
// reader can use gets a readable diagnostic without the operator having to know
// the flag exists. This pins only the REGISTRATION; the "registered default"
// arm of TestDepCyclesTruncatesTheRenderedListButNotTheCount is what exercises
// the value through the renderer.
func TestDepCyclesLimitFlagRegistration(t *testing.T) {
flag := depCyclesCmd.Flags().Lookup("limit")
if flag == nil {
t.Fatal("depCyclesCmd has no --limit flag")
}
if flag.Value.Type() != "int" {
t.Errorf("--limit is a %s, want int", flag.Value.Type())
}
if flag.DefValue == "0" {
t.Error("--limit defaults to 0 (no limit), so the default invocation is unbounded; it exists to bound the default rendering")
}
}
// TestDepCyclesTruncatesTheRenderedListButNotTheCount pins the cap's contract.
// --include-tracks is bounded by the scheduling-edge count and not by the number
// of real deadlocks, so the printed LIST is capped — but the reported total stays
// the whole report's and the truncation announces itself, because a diagnostic
// that quietly dropped rows would understate the very problem it exists to show.
func TestDepCyclesTruncatesTheRenderedListButNotTheCount(t *testing.T) {
var report issueops.CycleReport
for i := range 5 {
id := fmt.Sprintf("bd-%d", i)
report.Cycles = append(report.Cycles, issueops.Cycle{Members: []issueops.CycleMember{
{ID: id, Issue: &types.Issue{ID: id, Title: "Cycle " + id}},
}})
}
t.Run("capped", func(t *testing.T) {
out := captureCycleStdout(t, func() { printCycleReportForTest(t, report, 2) })
if !strings.Contains(out, "Found 5 dependency cycles") {
t.Errorf("the total is not the whole report's; a cap must not shrink the count:\n%s", out)
}
for _, shown := range []string{"bd-0", "bd-1"} {
if !strings.Contains(out, shown) {
t.Errorf("%s is inside the cap but was not printed:\n%s", shown, out)
}
}
for _, held := range []string{"bd-2", "bd-3", "bd-4"} {
if strings.Contains(out, held) {
t.Errorf("%s is past the cap but was printed anyway:\n%s", held, out)
}
}
if !strings.Contains(out, "and 3 more not shown") {
t.Errorf("the truncation is silent, so a reader cannot tell the list is partial:\n%s", out)
}
if !strings.Contains(out, "--limit 0") {
t.Errorf("the truncation does not name the way to print the rest:\n%s", out)
}
})
// The uncapped arm is what proves the cap is doing the work above, rather
// than the fixture or the renderer dropping cycles on its own.
t.Run("no limit", func(t *testing.T) {
out := captureCycleStdout(t, func() { printCycleReportForTest(t, report, 0) })
for _, id := range []string{"bd-0", "bd-1", "bd-2", "bd-3", "bd-4"} {
if !strings.Contains(out, id) {
t.Errorf("--limit 0 held back %s:\n%s", id, out)
}
}
if strings.Contains(out, "not shown") {
t.Errorf("--limit 0 announced a truncation it did not make:\n%s", out)
}
})
// Both arms above drive an explicit limit, so the value that actually SHIPS
// would otherwise be pinned only by TestDepCyclesLimitFlagRegistration's
// "not 0" assertion — a registration property, not a behavior. This arm
// reads the default off the command and renders past it, so it keeps
// exercising whatever the command registers. Ids are fixed-width so that
// "past the cap" cannot match as a prefix of an id inside it.
t.Run("registered default", func(t *testing.T) {
registered, err := depCyclesCmd.Flags().GetInt("limit")
if err != nil {
t.Fatalf("reading the registered --limit default: %v", err)
}
if registered <= 0 {
t.Fatalf("the registered --limit default is %d, so this arm would cap nothing", registered)
}
var big issueops.CycleReport
for i := range registered + 3 {
id := fmt.Sprintf("bd-big-%03d", i)
big.Cycles = append(big.Cycles, issueops.Cycle{Members: []issueops.CycleMember{
{ID: id, Issue: &types.Issue{ID: id, Title: "Cycle " + id}},
}})
}
out := captureCycleStdout(t, func() { printCycleReportForTest(t, big, registered) })
if want := fmt.Sprintf("Found %d dependency cycles", registered+3); !strings.Contains(out, want) {
t.Errorf("the registered default shrank the count; want %q:\n%s", want, out)
}
if last := fmt.Sprintf("bd-big-%03d", registered-1); !strings.Contains(out, last) {
t.Errorf("%s is the last cycle inside the registered default but was not printed:\n%s", last, out)
}
if first := fmt.Sprintf("bd-big-%03d", registered); strings.Contains(out, first) {
t.Errorf("%s is past the registered default but was printed anyway:\n%s", first, out)
}
if !strings.Contains(out, "and 3 more not shown") {
t.Errorf("the registered default truncated silently:\n%s", out)
}
})
}
// TestRunDepCyclesThreadsIncludeTracks pins dep_cycles.go's one line of real
// logic for this option: the includeTracks parameter lands on
// DetectCyclesRequest.IncludeTracks unchanged, in both directions.
func TestRunDepCyclesThreadsIncludeTracks(t *testing.T) {
for _, includeTracks := range []bool{false, true} {
recorder := &recordingCycleStore{}
previousStore := store
previousJSON := jsonOutput
store = recorder
jsonOutput = false
func() {
defer func() {
store = previousStore
jsonOutput = previousJSON
}()
if err := runDepCycles(includeTracks, 0); err != nil {
t.Fatalf("runDepCycles(%v): %v", includeTracks, err)
}
}()
if recorder.gotRequest.IncludeTracks != includeTracks {
t.Errorf("runDepCycles(%v) called DetectCycles with IncludeTracks=%v",
includeTracks, recorder.gotRequest.IncludeTracks)
}
}
}
// recordingCycleStore is a store whose cycle detector remembers the last
// request it was asked to detect, so the flag-threading test can look inside
// runDepCycles rather than only at its rendered output.
type recordingCycleStore struct {
storage.DoltStorage
gotRequest issueops.DetectCyclesRequest
}
func (s *recordingCycleStore) CycleDetector() (issueops.CycleDetector, error) {
return &recordingCycleDetector{store: s}, nil
}
type recordingCycleDetector struct{ store *recordingCycleStore }
func (d *recordingCycleDetector) DetectCycles(_ context.Context, req issueops.DetectCyclesRequest) (issueops.CycleReport, error) {
d.store.gotRequest = req
return issueops.CycleReport{}, nil
}
// fixedCycleStore is a store whose only real method is the cycle accessor. It
// embeds the interface, so any other method the command reached for would panic
// rather than quietly answering zero — which is the assertion that `bd dep

View file

@ -7,6 +7,7 @@ import (
"path/filepath"
"slices"
"strings"
"sync"
"time"
"github.com/spf13/cobra"
@ -247,10 +248,19 @@ Examples:
return nil
}
// GH#4993: assess once, before any branch that can write. Lazy so
// read-only paths skip the probe; memoised so repeats cannot disagree.
schemaGate := newSchemaGate(absPath)
// artifacts, conventions, and pollution work in embedded mode and run
// unconditionally; validate still requires a server-mode connection
// and stays gated (GH#3597).
if doctorCheckFlag != "" {
// GH#4993: these handlers return directly, so their destructive
// paths bypassed the gate. Refuse at the single branch point.
if err := destructiveCheckRefusal(doctorCheckFlag, doctorClean, doctorFix, schemaGate); err != nil {
return err
}
switch doctorCheckFlag {
case "artifacts":
return runArtifactsCheck(absPath, doctorClean, doctorYes)
@ -294,12 +304,17 @@ Examples:
result := runDiagnostics(absPath)
// GH#4993: guard once, on the result, before any emitter reads it.
// Per-renderer sanitizing exempted --json, --agent and --output.
sanitizeFixAdvice(&result, schemaGate())
if doctorDryRun {
previewFixes(result)
previewFixes(result, schemaGate())
} else if doctorFix {
applyFixes(result)
applyFixes(result, schemaGate())
fmt.Println("\nVerifying fixes...")
result = runDiagnostics(absPath)
sanitizeFixAdvice(&result, schemaGate())
}
if doctorOutput != "" || jsonOutput {
@ -315,7 +330,7 @@ Examples:
}
if doctorAgent {
agentResult := buildAgentResult(result)
agentResult := buildAgentResult(result, schemaGate())
if jsonOutput {
if err := outputJSON(agentResult); err != nil {
return err
@ -328,7 +343,7 @@ Examples:
return err
}
} else if doctorOutput == "" {
printDiagnostics(result)
printDiagnostics(result, schemaGate())
}
if !result.OverallOK {
@ -1184,7 +1199,96 @@ func exportDiagnostics(result doctorResult, outputPath string) error {
return nil
}
func printDiagnostics(result doctorResult) {
// checkFlagWrites reports whether a `--check=<flag>` can modify state and so
// must clear the schema gate (GH#4993). New destructive checks go here.
func checkFlagWrites(flag string, clean, fix bool) bool {
switch flag {
case "artifacts", "pollution":
return clean
case "validate":
return fix
}
return false
}
// checkFlagFixName names the classified repair a destructive `--check=<flag>`
// performs, so the schema gate can admit it through the same policy that governs
// the equivalent `bd doctor --fix` repair (GH#4993). "" means the flag's
// destructive work maps to no single classified fix and is therefore treated as
// schema-writing, exactly like an unlisted fix name in filesystemOnlyFixes.
//
// `pollution --clean` and `validate --fix` deliberately have no entry: both
// delete or rewrite rows through an opened store.
func checkFlagFixName(flag string) string {
if flag == "artifacts" {
// --clean removes the same on-disk artifacts as the "Classic Artifacts"
// fix, which fix_gate.go classifies filesystem-only.
return "Classic Artifacts"
}
return ""
}
// assessSchemaFixGate is the schema-gate assessor, indirected so tests can
// observe when and how often it is evaluated. Production always uses
// doctor.AssessSchemaFixGate.
var assessSchemaFixGate = doctor.AssessSchemaFixGate
// newSchemaGate returns this invocation's schema gate accessor (GH#4993). Lazy
// so a read-only path never probes the database, and memoised so every consumer
// in one invocation sees one verdict that repeats cannot disagree with.
func newSchemaGate(absPath string) func() doctor.FixGate {
return sync.OnceValue(func() doctor.FixGate {
return assessSchemaFixGate(absPath)
})
}
// destructiveCheckRefusal returns the refusal for a destructive `bd doctor
// --check=<flag>` the schema gate does not admit, or nil when the command may
// proceed (GH#4993). gate is an accessor rather than a value so a read-only
// --check never probes the database.
//
// The gate is consulted here, before the caller's switch dispatches to a
// handler, because the handler's own store open is the hazard: the migrating
// factory auto-starts a stopped server and applies pending migrations before the
// write lands.
func destructiveCheckRefusal(flag string, clean, fix bool, gate func() doctor.FixGate) error {
if !checkFlagWrites(flag, clean, fix) {
return nil
}
g := gate()
if !g.BlocksDestructiveWrites() {
return nil
}
// Filesystem-only cleanup is not what the gate is about: `bd doctor --fix`
// admits the same repair under the same blocked gate, so refusing it here
// would leave the two planes disagreeing about one operation.
if name := checkFlagFixName(flag); name != "" && g.AllowsFix(name) {
return nil
}
return HandleErrorWithHint(
fmt.Sprintf("refusing destructive 'bd doctor --check=%s': %s", flag, g.Reason),
"Re-run without --clean/--fix to inspect read-only, or resolve the schema state first",
)
}
// sanitizeFixAdvice rewrites each Fix tip in place so no emitter publishes
// advice the gate ruled unsafe (GH#4993). Index-based write is load-bearing:
// ranging by value over []doctorCheck mutates a copy.
func sanitizeFixAdvice(result *doctorResult, gate doctor.FixGate) {
if result == nil {
return
}
for i := range result.Checks {
if result.Checks[i].Fix == "" {
continue
}
result.Checks[i].Fix = doctor.SanitizeFixRecommendation(result.Checks[i].Fix, gate)
}
}
func printDiagnostics(result doctorResult, gate doctor.FixGate) {
// GH#4993: tips arrive already sanitized; do not re-assess the gate here.
// Pre-calculate counts and collect issues grouped by category
checksByCategory := make(map[string][]doctorCheck)
issuesByCategory := make(map[string][]doctorCheck)
@ -1330,6 +1434,11 @@ func printDiagnostics(result doctorResult) {
}
fmt.Printf("%s\n", ui.RenderMuted(fmt.Sprintf("(%d %s suppressed via doctor.suppress config)", result.SuppressedCount, noun)))
}
// GH#4993: surface the schema gate verdict assessed once in RunE.
if gate.Reason != "" {
fmt.Printf("\n%s Schema fix-gate: %s\n", ui.RenderWarn("⚠"), gate.Reason)
}
}
// printAllChecks prints all checks grouped by category with section headers.

View file

@ -19,6 +19,7 @@ go_library(
"dependency_sql.go",
"dolt.go",
"federation.go",
"fix_gate.go",
"fresh_clone_server.go",
"git.go",
"gitignore.go",
@ -74,6 +75,7 @@ go_library(
"//internal/storage/schema",
"//internal/types",
"//internal/utils",
"//schema",
"@com_github_go_sql_driver_mysql//:mysql",
"@com_github_spf13_viper//:viper",
"@in_gopkg_yaml_v3//:yaml_v3",
@ -105,6 +107,9 @@ go_test(
"dolt_phantom_test.go",
"dolt_test.go",
"federation_test.go",
"fix_gate_assess_dolt_test.go",
"fix_gate_assess_test.go",
"fix_gate_test.go",
"fresh_clone_server_test.go",
"git_hygiene_test.go",
"git_repo_template_test.go",
@ -164,6 +169,7 @@ go_test(
"//internal/testutil/bazeltest",
"//internal/types",
"//internal/utils",
"//schema",
"@com_github_data_dog_go_sqlmock//:go-sqlmock",
"@com_github_go_sql_driver_mysql//:mysql",
],

View file

@ -2,6 +2,7 @@ package doctor
import (
"fmt"
"sort"
"strings"
)
@ -33,7 +34,20 @@ type agentEnrichment struct {
type enricher func(dc DoctorCheck) agentEnrichment
// EnrichForAgent converts a DoctorCheck into an AgentDiagnostic with rich context.
func EnrichForAgent(dc DoctorCheck) AgentDiagnostic {
//
// Enrichers hardcode their own remediation commands (many are literally
// `bd doctor --fix`) and never read the already-sanitized dc.Fix, so the gate
// is applied to the finished Commands here, after enrichment (GH#4993). An
// agent is the consumer most likely to execute that list unattended.
func EnrichForAgent(dc DoctorCheck, gate FixGate) AgentDiagnostic {
ad := enrichForAgent(dc)
for i, c := range ad.Commands {
ad.Commands[i] = SanitizeFixRecommendation(c, gate)
}
return ad
}
func enrichForAgent(dc DoctorCheck) AgentDiagnostic {
ad := AgentDiagnostic{
Name: dc.Name,
Status: dc.Status,
@ -88,6 +102,19 @@ func buildGenericExplanation(dc DoctorCheck) string {
return s
}
// AgentEnricherNames returns every check name with a specialized agent
// enricher, sorted. Enrichers hardcode their own remediation commands, so
// tests that assert on agent output must cover each one rather than a
// hand-picked name that may fall through to the generic path (GH#4993).
func AgentEnricherNames() []string {
names := make([]string, 0, len(agentEnrichers))
for name := range agentEnrichers {
names = append(names, name)
}
sort.Strings(names)
return names
}
// agentEnrichers maps check names to specialized enrichment functions.
var agentEnrichers = map[string]enricher{
"Installation": enrichInstallation,

View file

@ -267,11 +267,38 @@ func CheckFederationRemotesAPI(path string) DoctorCheck {
}
}
// Server is running and peers are configured - check if remotesapi port is accessible.
// Read port from config instead of hardcoding 8080.
remotesAPIPort := configfile.DefaultDoltRemotesAPIPort
if cfg, err := configfile.Load(beadsDir); err == nil && cfg != nil {
remotesAPIPort = cfg.GetDoltRemotesAPIPort()
// Server is running and peers are configured - check if remotesapi port is
// accessible.
return checkRemotesAPIListener(beadsDir, serverState.PID)
}
// checkRemotesAPIListener probes the remotesapi listener of a running server.
// It resolves the port through the same chain the launcher uses
// (BEADS_DOLT_REMOTESAPI_PORT -> user-global dolt.remotesapi-port for a shared
// server -> the per-project configfile), not configfile alone: reading
// configfile alone diagnoses port 8080 while a shared server launched from the
// user-global key is listening somewhere else.
//
// The mode is classified once because it also decides the remedy. bd opens a
// remotesapi listener only for the shared server it launches, so restarting is
// the fix there; restarting a per-project server reproduces the same error.
func checkRemotesAPIListener(beadsDir string, pid int) DoctorCheck {
sharedMode := doltserver.IsSharedServerModeForDir(beadsDir)
remotesAPIPort := doltserver.ResolveRemotesAPIPortForMode(beadsDir, sharedMode)
if remotesAPIPort <= 0 {
// Resolved zero means no listener was requested. Dialing port 0 would
// report a spurious federation error for a correct configuration.
detail := "The remotesapi port resolves to 0, so no remotesapi listener is expected."
if sharedMode {
detail = "No remotesapi port is configured, so the shared dolt sql-server does not open a remotesapi listener."
}
return DoctorCheck{
Name: "Federation remotesapi",
Status: StatusOK,
Message: "N/A (remotesapi listener disabled)",
Detail: detail,
Category: CategoryFederation,
}
}
host := "127.0.0.1"
@ -281,12 +308,16 @@ func CheckFederationRemotesAPI(path string) DoctorCheck {
// greeting to drain here.
conn, err := net.DialTimeout("tcp", addr, 2*time.Second)
if err != nil {
fix := fmt.Sprintf("bd opens a remotesapi listener only for the shared server: run dolt sql-server with --remotesapi-port %d, or enable dolt.shared-server and set dolt.remotesapi-port in the user-global config", remotesAPIPort)
if sharedMode {
fix = "Restart the shared server so it picks up the resolved remotesapi port: bd dolt stop && bd dolt start"
}
return DoctorCheck{
Name: "Federation remotesapi",
Status: StatusError,
Message: fmt.Sprintf("remotesapi port %d not accessible", remotesAPIPort),
Detail: fmt.Sprintf("Server running (PID %d) but remotesapi port unreachable: %v", serverState.PID, err),
Fix: "Check if dolt sql-server is running with --remotesapi-port flag",
Detail: fmt.Sprintf("Server running (PID %d) but remotesapi port unreachable: %v", pid, err),
Fix: fix,
Category: CategoryFederation,
}
}

View file

@ -4,9 +4,11 @@ package doctor
import (
"encoding/json"
"net"
"os"
"os/exec"
"path/filepath"
"strconv"
"strings"
"testing"
@ -413,6 +415,107 @@ func TestCheckFederationRemotesAPI_EnvOverridesConfig(t *testing.T) {
}
}
// remotesAPITarget isolates the inputs checkRemotesAPIListener resolves from:
// the server mode, the user-global dolt.remotesapi-port ("" leaves it unset)
// and BEADS_DOLT_REMOTESAPI_PORT ("" leaves it unset).
func remotesAPITarget(t *testing.T, shared bool, userGlobalPort, envPort string) string {
t.Helper()
home := t.TempDir()
t.Setenv("HOME", home)
t.Setenv("USERPROFILE", home)
t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
if userGlobalPort != "" {
dir := filepath.Join(home, ".config", "bd")
if err := os.MkdirAll(dir, 0o755); err != nil {
t.Fatal(err)
}
yaml := "dolt:\n remotesapi-port: " + userGlobalPort + "\n"
if err := os.WriteFile(filepath.Join(dir, "config.yaml"), []byte(yaml), 0o600); err != nil {
t.Fatal(err)
}
}
t.Setenv("BEADS_DOLT_SHARED_SERVER", strconv.FormatBool(shared))
t.Setenv("BEADS_DOLT_REMOTESAPI_PORT", envPort)
beadsDir := filepath.Join(t.TempDir(), ".beads")
if err := os.MkdirAll(beadsDir, 0o755); err != nil {
t.Fatal(err)
}
return beadsDir
}
// localTCPPort returns a loopback port, still listening when open is true and
// already closed (so a dial is refused) otherwise.
func localTCPPort(t *testing.T, open bool) int {
t.Helper()
ln, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
port := ln.Addr().(*net.TCPAddr).Port
if open {
t.Cleanup(func() { _ = ln.Close() })
} else {
_ = ln.Close()
}
return port
}
// TestCheckRemotesAPIListener covers the running-server arm of
// CheckFederationRemotesAPI, which the getter tests above never reach: the
// port it resolves and the remedy it prints for each server mode.
func TestCheckRemotesAPIListener(t *testing.T) {
t.Run("shared server resolves the user-global port", func(t *testing.T) {
port := localTCPPort(t, true)
check := checkRemotesAPIListener(remotesAPITarget(t, true, strconv.Itoa(port), ""), 4242)
if check.Status != StatusOK || check.Message != "Port "+strconv.Itoa(port)+" accessible" {
t.Fatalf("got %s %q, want the user-global port %d accessible", check.Status, check.Message, port)
}
})
t.Run("environment overrides the user-global port", func(t *testing.T) {
port := localTCPPort(t, true)
check := checkRemotesAPIListener(remotesAPITarget(t, true, strconv.Itoa(localTCPPort(t, false)), strconv.Itoa(port)), 4242)
if check.Status != StatusOK || check.Message != "Port "+strconv.Itoa(port)+" accessible" {
t.Fatalf("got %s %q, want the env port %d accessible", check.Status, check.Message, port)
}
})
t.Run("unreachable shared server prescribes a restart", func(t *testing.T) {
port := localTCPPort(t, false)
check := checkRemotesAPIListener(remotesAPITarget(t, true, strconv.Itoa(port), ""), 4242)
if check.Status != StatusError || !strings.Contains(check.Fix, "bd dolt stop && bd dolt start") {
t.Fatalf("got %s, Fix %q; want StatusError with the stop/start remedy", check.Status, check.Fix)
}
})
t.Run("unreachable per-project server names the flag, not a restart", func(t *testing.T) {
port := localTCPPort(t, false)
check := checkRemotesAPIListener(remotesAPITarget(t, false, "", strconv.Itoa(port)), 4242)
if check.Status != StatusError {
t.Fatalf("got %s, want StatusError", check.Status)
}
// bd never opens a listener for a per-project server, so a restart
// cannot clear this error.
if !strings.Contains(check.Fix, "--remotesapi-port "+strconv.Itoa(port)) || strings.Contains(check.Fix, "bd dolt stop") {
t.Fatalf("Fix %q must name --remotesapi-port %d and must not prescribe a restart", check.Fix, port)
}
})
t.Run("shared server without a port is disabled", func(t *testing.T) {
check := checkRemotesAPIListener(remotesAPITarget(t, true, "", ""), 4242)
if check.Status != StatusOK || check.Message != "N/A (remotesapi listener disabled)" || !strings.Contains(check.Detail, "shared dolt sql-server") {
t.Fatalf("got %s %q, Detail %q; want the shared server's disabled listener", check.Status, check.Message, check.Detail)
}
})
t.Run("per-project port zero is disabled without naming a shared server", func(t *testing.T) {
check := checkRemotesAPIListener(remotesAPITarget(t, false, "", "0"), 4242)
if check.Status != StatusOK || check.Message != "N/A (remotesapi listener disabled)" || strings.Contains(check.Detail, "shared") {
t.Fatalf("got %s %q, Detail %q; want a disabled listener that does not claim a shared server", check.Status, check.Message, check.Detail)
}
})
}
func TestCheckFederationChecks_CategoryIsFederation(t *testing.T) {
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")

321
cmd/bd/doctor/fix_gate.go Normal file
View file

@ -0,0 +1,321 @@
package doctor
import (
"context"
"fmt"
"os"
"regexp"
"strings"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/schema"
)
// FixGate reports whether `bd doctor --fix` is safe given the schema/binary
// relationship (GH#4993): opening the store can apply pending migrations.
// Callers ask three distinct questions, so it answers three.
type FixGate struct {
// Determined is false when a database exists but its version could not be
// read — either the connection failed or the query did. Unknown is not safe.
Determined bool
// DBReachable is false whenever this process did not get a working
// connection. That covers both "there is no database" and "there is one but
// it could not be connected to", so it is not on its own a statement about
// hazard — see DBPresent.
DBReachable bool
// DBPresent is true when a beads database exists for this repo: either the
// connection succeeded, or a connection was impossible but the on-disk
// database is still there (a stopped server, a wrong port). It is the hazard
// question — a database that exists has a schema that a migrating open can
// rewrite, whether or not this process could read it. Without a connection,
// "exists" is databaseExistsOnDisk's verdict, and a workspace with no
// metadata.json reads as absent there even with a data directory on disk —
// see that function for why. DBReachable implies DBPresent; the converse
// does not hold.
DBPresent bool
// RecommendFix allows printed advice to steer at `bd doctor --fix`.
RecommendFix bool
// AllowDBFix allows repairs that may write schema or resume migrations.
AllowDBFix bool
// AllowFSFix allows filesystem-only repairs, which never touch the schema.
AllowFSFix bool
DBVersion int // max applied schema_migrations version (0 if unknown)
BinaryVersion int // schema.LatestVersion() for this binary
Reason string
Ahead bool // DB schema newer than this binary
Pending bool // binary knows migrations the DB has not applied
}
// AssessSchemaFixGate compares schema_migrations to this binary. It yields one
// memoised verdict per invocation, evaluated before any *gated* write and
// threaded through to every consumer: probing at print time cannot guard writes
// that already happened. The bd-jgxi auto-migrate that runs earlier in the
// command (cmd/bd/version_tracking.go) is deliberately outside this gate's
// jurisdiction — it is the sanctioned migration path, not a repair the gate
// withholds — so "before any gated write" is the contract, not "before
// anything that touches the schema".
func AssessSchemaFixGate(path string) FixGate {
binary := schema.LatestVersion()
// No database at all: scoped allowance, not a fail-open — DB fixes stay
// disallowed because there is no DB to fix, and no schema exists to skew.
unreachable := FixGate{
BinaryVersion: binary,
Determined: true,
RecommendFix: true,
AllowFSFix: true,
}
beadsDir := ResolveBeadsDirForRepo(path)
db, _, err := openDoltDB(beadsDir)
if err != nil {
// A failed connection is not evidence that there is no database. When
// the database is still on disk — a stopped server, a moved port — the
// schema hazard is real and unmeasured: every gated repair opens the
// store through the migrating factory, which auto-starts the server and
// applies pending migrations before writing. Fail closed on that, and
// keep the genuine no-database case above as the only no-hazard shape.
// Recovery fixers stay available either way (AllowsFix keys them on
// DBReachable, which is false here too) because they are the cure for a
// database that cannot be opened.
if !databaseExistsOnDisk(beadsDir) {
return unreachable
}
return FixGate{
BinaryVersion: binary,
DBPresent: true,
AllowFSFix: true,
Reason: "database exists but could not be opened, so its schema version is unknown; " +
"`bd doctor --fix` may apply migrations blind — start the database and re-run",
}
}
defer db.Close()
// Reachable but unreadable: fail closed rather than claim safety.
undetermined := FixGate{
BinaryVersion: binary,
DBReachable: true,
DBPresent: true,
AllowFSFix: true,
Reason: "database schema version could not be determined; " +
"`bd doctor --fix` may apply migrations blind — resolve the database state first",
}
ctx := context.Background()
dbVer, err := schema.CurrentVersion(ctx, db)
if err != nil || dbVer == 0 {
return undetermined
}
gate := FixGate{
Determined: true,
DBReachable: true,
DBPresent: true,
DBVersion: dbVer,
BinaryVersion: binary,
AllowFSFix: true,
}
switch {
case dbVer > binary:
gate.Ahead = true
gate.Reason = fmt.Sprintf(
"database schema is at v%d, this binary knows up to v%d (%s ahead). "+
"`bd doctor --fix` can write/migrate and is unsafe on a newer schema — upgrade bd first",
dbVer, binary, pluralMigrations(dbVer-binary),
)
case dbVer < binary:
gate.Pending = true
gate.Reason = fmt.Sprintf(
"database schema is at v%d, this binary expects v%d (%s pending). "+
"`bd doctor --fix` may apply write migrations — upgrade/migrate deliberately, not as a cosmetic tip",
dbVer, binary, pluralMigrations(binary-dbVer),
)
default:
gate.RecommendFix = true
gate.AllowDBFix = true
}
return gate
}
// databaseExistsOnDisk reports whether a beads database is present for this
// workspace, independent of whether anything can currently connect to it. It
// stats the path autoMigrateOnVersionBump stats (cmd/bd/version_tracking.go)
// and, like it, reads only ENOENT as absent: a path that cannot be stat'ed for
// any other reason is unknown, and unknown is not safe. An unloadable
// metadata.json reads as absent in both, which is safe: the store factory
// refuses to open such a workspace at all.
//
// It departs from that probe deliberately in two arms:
//
// - No metadata.json reads as absent, where auto-migrate falls back to
// DefaultConfig. The gate cannot connect without metadata.json (openDoltDB
// requires it), so a fail-closed verdict here could never be cleared by
// starting a server, and it would rewrite doctor's own advice for this
// state — regenerate metadata.json with `bd doctor --fix`, a
// filesystem-only repair — into "Do NOT run 'bd doctor --fix'". The cost is
// one unguarded state: server mode selected by the environment or
// config.yaml while metadata.json is missing, where a gated repair still
// reaches the server's schema unmeasured.
// - A proxied-server workspace reads as present when its data directory is
// on disk. Auto-migrate skips proxied workspaces because their migration
// runs later, at UOW-provider init, not because they lack a local database:
// the proxied root defaults to this same directory. `bd doctor` itself is
// refused up front in proxied-server mode (proxy.doctor.unsupported); this
// arm fails closed so that it is already safe when doctor gains a proxied
// route.
func databaseExistsOnDisk(beadsDir string) bool {
cfg, err := configfile.Load(beadsDir)
if err != nil || cfg == nil {
return false
}
if _, err := os.Stat(cfg.DatabasePath(beadsDir)); os.IsNotExist(err) {
return false
}
return true
}
// BlocksDestructiveWrites reports whether an operation that can resume
// migrations must be refused outright. It is the hazard question rather than the
// connectivity one: a database that exists but whose schema state does not
// permit schema-writing repair blocks, whether or not this process reached it.
// A workspace with no database never blocks — there is nothing to skew.
func (g FixGate) BlocksDestructiveWrites() bool {
return g.DBPresent && !g.AllowDBFix
}
func pluralMigrations(n int) string {
if n == 1 {
return "1 migration"
}
return fmt.Sprintf("%d migrations", n)
}
// fixAdvicePattern matches a tip steering at `bd doctor --fix`, tolerating flag
// order and spacing. Best-effort: it is still a sniff over free-form prose.
var fixAdvicePattern = regexp.MustCompile(`(?i)\bdoctor\b[^\n]*--fix\b`)
// originalTipMarker prefixes preserved advice in a rewritten tip, and doubles
// as the idempotence sentinel.
const originalTipMarker = "Original tip was: "
// MentionsFixAdvice reports whether a tip steers at `bd doctor --fix`.
func MentionsFixAdvice(fix string) bool {
return fixAdvicePattern.MatchString(fix)
}
// SanitizeFixRecommendation rewrites Fix text that steers into `bd doctor
// --fix` when the gate says that is unsafe (GH#4993). Apply once to the
// result, not per-renderer — see sanitizeFixAdvice in cmd/bd.
func SanitizeFixRecommendation(fix string, gate FixGate) string {
if gate.RecommendFix || fix == "" || !MentionsFixAdvice(fix) {
return fix
}
// The --fix path sanitizes again after re-running diagnostics.
if strings.Contains(fix, originalTipMarker) {
return fix
}
switch {
case gate.Ahead:
return fmt.Sprintf("Do NOT run 'bd doctor --fix' until bd is upgraded (%s). %s%s",
gate.Reason, originalTipMarker, fix)
case gate.Pending:
return fmt.Sprintf(
"Avoid 'bd doctor --fix' for cosmetic repair while schema migrations are pending (%s). "+
"Prefer targeted fixes or an intentional migrate. %s%s",
gate.Reason, originalTipMarker, fix)
case !gate.Determined:
return fmt.Sprintf("Do NOT run 'bd doctor --fix' (%s). %s%s",
gate.Reason, originalTipMarker, fix)
}
return fix
}
// filesystemOnlyFixes are repairs that provably touch only files on disk.
// Unlisted names are treated as database-touching, so a fix added later is
// guarded by default rather than escaping the gate silently.
//
// Every name in applyFixList's dispatch switch (cmd/bd/doctor_fix.go) was
// audited against that rule. The ones deliberately left out open a store, so
// being withheld under a blocked gate is correct rather than an omission:
// "Database", "Database Integrity", "Fresh Clone", "Schema Compatibility",
// "Repo Fingerprint" (fix.RepoFingerprint and fix.FixMissingMetadata both write
// through the store), "Dolt Schema", "Pending Migrations", and the row-level
// data repairs. "Sync Divergence", "JSONL Config" and "Untracked Files" are
// retired no-ops that write nothing at all; they stay unlisted because they are
// not filesystem repairs, and withholding a no-op costs the user nothing.
var filesystemOnlyFixes = map[string]bool{
"Gitignore": true,
"Project Gitignore": true,
"Metadata Config": true,
"Redirect Tracking": true,
"Last-Touched Tracking": true,
"Tracked Runtime Files": true,
"Git Hooks": true,
"Hooks Path": true, // git-config unset, beads-managed paths only
"Permissions": true,
"Lock Files": true,
"Legacy MQ Files": true,
"Classic Artifacts": true,
"Btrfs NoCOW (dolt)": true,
"Circuit Breaker": true, // removes stale circuit-breaker marker files
"Database Config": true, // rewrites metadata.json only; refuses Dolt outright
}
// IsFilesystemOnlyFix reports whether the named fix touches only the
// filesystem. Unknown names report false — see filesystemOnlyFixes.
func IsFilesystemOnlyFix(checkName string) bool {
return filesystemOnlyFixes[strings.TrimSpace(checkName)]
}
// recoveryFixes are the repairs a user reaches for when the database cannot be
// opened at all. Each rewrites on-disk database state or metadata and none can
// migrate a schema that already exists elsewhere; each is the *cure* for an
// unreachable database rather than a schema write:
// - Corrupt Manifest moves .dolt/ aside and runs a plain `dolt init`.
// - Dolt Format seeds a marker file.
// - Dolt Schema probes the server over a plain read connection to find the
// right database name and writes only metadata.json.
// - Database Integrity moves the local dolt directory aside and runs
// `bd init --force`, which does open a store, but only the fresh one it
// just created; server-mode repos, whose schema lives on a shared server,
// are refused up front by serverModeIntegrityRecoveryGuard.
//
// Fresh Clone and Database are deliberately absent: they open the existing
// store through the migrating factory. Unlisted names are treated as
// schema-writing, as in filesystemOnlyFixes.
var recoveryFixes = map[string]bool{
"Corrupt Manifest": true, // backup + reinit of a corrupt .dolt/
"Database Integrity": true, // backup + `bd init --force`
"Dolt Format": true, // seeds a marker file
"Dolt Schema": true, // backfills dolt_database in metadata.json
}
// IsRecoveryFix reports whether the named fix repairs an unopenable database
// without a schema-writing open. See recoveryFixes.
func IsRecoveryFix(checkName string) bool {
return recoveryFixes[strings.TrimSpace(checkName)]
}
// AllowsFix is the single admission policy for applying (or previewing as
// runnable) the named fix under this gate. Filesystem-only fixes follow
// AllowFSFix. Everything else needs AllowDBFix, with one narrow exception:
// recovery fixers stay available while the database is unreachable, because
// with no readable schema there is nothing to skew, and withholding them would
// block the very repairs that make a dead database reachable again. When the
// database is reachable but skewed or undetermined they stay withheld.
func (g FixGate) AllowsFix(checkName string) bool {
switch {
case IsFilesystemOnlyFix(checkName):
return g.AllowFSFix
case g.AllowDBFix:
return true
case !g.DBReachable && IsRecoveryFix(checkName):
return true
}
return false
}

View file

@ -0,0 +1,213 @@
//go:build cgo
package doctor
import (
"context"
"crypto/rand"
"database/sql"
"encoding/hex"
"fmt"
"strings"
"testing"
"time"
"github.com/steveyegge/beads/internal/storage/doltutil"
"github.com/steveyegge/beads/internal/testutil"
"github.com/steveyegge/beads/schema"
)
// seedGateDatabase creates a throwaway database on the shared test server and
// runs setup against it. Returns the database name; dropped on cleanup.
func seedGateDatabase(t *testing.T, port int, setup func(t *testing.T, db *sql.DB)) string {
t.Helper()
ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()
buf := make([]byte, 6)
if _, err := rand.Read(buf); err != nil {
t.Fatalf("rand: %v", err)
}
dbName := "gateassess_" + hex.EncodeToString(buf)
dsn := doltutil.ServerDSN{Host: "127.0.0.1", Port: port, User: "root", Timeout: 10 * time.Second}.String()
admin, err := sql.Open("mysql", dsn)
if err != nil {
t.Fatalf("open admin connection: %v", err)
}
t.Cleanup(func() {
dropCtx, dropCancel := context.WithTimeout(context.Background(), 30*time.Second)
defer dropCancel()
_, _ = admin.ExecContext(dropCtx, fmt.Sprintf("DROP DATABASE IF EXISTS `%s`", dbName))
_ = admin.Close()
})
// Single connection: USE and the statements that follow must share a session.
admin.SetMaxOpenConns(1)
if _, err := admin.ExecContext(ctx, fmt.Sprintf("CREATE DATABASE `%s`", dbName)); err != nil {
t.Fatalf("create database: %v", err)
}
if _, err := admin.ExecContext(ctx, fmt.Sprintf("USE `%s`", dbName)); err != nil {
t.Fatalf("use database: %v", err)
}
setup(t, admin)
return dbName
}
// seedMigrations returns a setup func that creates schema_migrations and
// records the given versions as applied.
func seedMigrations(versions ...int) func(t *testing.T, db *sql.DB) {
return func(t *testing.T, db *sql.DB) {
t.Helper()
if _, err := db.ExecContext(t.Context(),
"CREATE TABLE schema_migrations (version INT NOT NULL PRIMARY KEY)"); err != nil {
t.Fatalf("create schema_migrations: %v", err)
}
for _, v := range versions {
if _, err := db.ExecContext(t.Context(), "INSERT INTO schema_migrations (version) VALUES (?)", v); err != nil {
t.Fatalf("insert version %d: %v", v, err)
}
}
}
}
// TestAssessSchemaFixGate_RealDolt exercises the function that decides ahead /
// pending / equal / undetermined against a real Dolt server with a seeded
// schema_migrations. Every other gate test builds a FixGate literal by hand, so
// without this the assessor itself — the headline guard of GH#4993 — is never
// run: `case dbVer > binary:` could be replaced by `case false:` and the suite
// stayed green.
func TestAssessSchemaFixGate_RealDolt(t *testing.T) {
if testutil.DoltContainerCrashed() {
t.Skipf("Dolt test server crashed: %v", testutil.DoltContainerCrashError())
}
port := doctorTestServerPort()
if port == 0 {
t.Skip("Dolt test server not available, skipping")
}
binary := schema.LatestVersion()
if binary < 2 {
t.Fatalf("test needs at least 2 known migrations, binary knows %d", binary)
}
// The reachable-but-not-readable states share one expectation: fail closed.
failClosed := func(t *testing.T, g FixGate) {
t.Helper()
if !g.DBReachable {
t.Error("DBReachable = false, want true (the server answered)")
}
if g.Determined || g.AllowDBFix || g.RecommendFix {
t.Errorf("Determined=%v AllowDBFix=%v RecommendFix=%v, want all false: unknown is not safe",
g.Determined, g.AllowDBFix, g.RecommendFix)
}
if g.Ahead || g.Pending {
t.Errorf("Ahead=%v Pending=%v, want neither when the version is unknown", g.Ahead, g.Pending)
}
if !strings.Contains(g.Reason, "could not be determined") {
t.Errorf("Reason = %q, want it to say the version could not be determined", g.Reason)
}
}
cases := []struct {
name string
setup func(t *testing.T, db *sql.DB)
verify func(t *testing.T, g FixGate)
}{
{
name: "ahead",
setup: seedMigrations(binary + 3),
verify: func(t *testing.T, g FixGate) {
if !g.Ahead || g.Pending {
t.Errorf("Ahead=%v Pending=%v, want Ahead only", g.Ahead, g.Pending)
}
if g.AllowDBFix || g.RecommendFix {
t.Errorf("AllowDBFix=%v RecommendFix=%v, want both false on a newer schema", g.AllowDBFix, g.RecommendFix)
}
if g.DBVersion != binary+3 || g.BinaryVersion != binary {
t.Errorf("DBVersion=%d BinaryVersion=%d, want %d/%d", g.DBVersion, g.BinaryVersion, binary+3, binary)
}
if !strings.Contains(g.Reason, "3 migrations ahead") {
t.Errorf("Reason = %q, want it to name 3 migrations ahead", g.Reason)
}
},
},
{
name: "behind (pending)",
setup: seedMigrations(binary - 1),
verify: func(t *testing.T, g FixGate) {
if !g.Pending || g.Ahead {
t.Errorf("Ahead=%v Pending=%v, want Pending only", g.Ahead, g.Pending)
}
if g.AllowDBFix || g.RecommendFix {
t.Errorf("AllowDBFix=%v RecommendFix=%v, want both false while migrations are pending", g.AllowDBFix, g.RecommendFix)
}
if g.DBVersion != binary-1 {
t.Errorf("DBVersion = %d, want %d", g.DBVersion, binary-1)
}
if !strings.Contains(g.Reason, "1 migration pending") {
t.Errorf("Reason = %q, want it to name 1 migration pending", g.Reason)
}
},
},
{
name: "equal",
setup: seedMigrations(binary-1, binary),
verify: func(t *testing.T, g FixGate) {
if g.Ahead || g.Pending {
t.Errorf("Ahead=%v Pending=%v, want neither at parity", g.Ahead, g.Pending)
}
if !g.AllowDBFix || !g.RecommendFix || !g.Determined {
t.Errorf("AllowDBFix=%v RecommendFix=%v Determined=%v, want all true at parity",
g.AllowDBFix, g.RecommendFix, g.Determined)
}
if g.Reason != "" {
t.Errorf("Reason = %q, want empty at parity", g.Reason)
}
if g.DBVersion != binary {
t.Errorf("DBVersion = %d, want %d", g.DBVersion, binary)
}
},
},
{
// Pins current behavior, not an endorsement: a version of 0 (empty
// table) is treated as "could not be determined" and so fails
// closed. Revisit together with the table-absent case below.
name: "empty schema_migrations",
setup: seedMigrations(),
verify: failClosed,
},
{
name: "no schema_migrations table",
setup: func(*testing.T, *sql.DB) {},
verify: failClosed,
},
{
name: "schema_migrations unreadable",
setup: func(t *testing.T, db *sql.DB) {
if _, err := db.ExecContext(t.Context(), "CREATE TABLE schema_migrations (unrelated INT)"); err != nil {
t.Fatalf("create malformed schema_migrations: %v", err)
}
},
verify: failClosed,
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
dbName := seedGateDatabase(t, port, tc.setup)
setGatePort(t, port)
gate := AssessSchemaFixGate(writeGateWorkspace(t, dbName))
// Invariants for every reachable assessment.
if !gate.DBReachable {
t.Fatalf("DBReachable = false; the seeded database should be reachable: %+v", gate)
}
if !gate.AllowFSFix {
t.Error("AllowFSFix = false; filesystem repair must not depend on schema state")
}
if gate.BinaryVersion != binary {
t.Errorf("BinaryVersion = %d, want %d", gate.BinaryVersion, binary)
}
tc.verify(t, gate)
})
}
}

View file

@ -0,0 +1,280 @@
package doctor
import (
"net"
"os"
"path/filepath"
"runtime"
"strconv"
"testing"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/schema"
)
// writeGateWorkspace writes a Dolt-backend .beads/metadata.json naming dbName
// and returns the repo path handed to AssessSchemaFixGate.
func writeGateWorkspace(t *testing.T, dbName string) string {
t.Helper()
return writeGateConfig(t, &configfile.Config{Backend: configfile.BackendDolt, DoltDatabase: dbName})
}
// writeGateConfig writes cfg as .beads/metadata.json in a fresh repo and
// returns the repo path.
func writeGateConfig(t *testing.T, cfg *configfile.Config) string {
t.Helper()
repo := t.TempDir()
beadsDir := filepath.Join(repo, ".beads")
if err := os.MkdirAll(beadsDir, 0o750); err != nil {
t.Fatal(err)
}
if err := cfg.Save(beadsDir); err != nil {
t.Fatalf("save metadata.json: %v", err)
}
return repo
}
// mkdirGateDoltDir creates <repo>/.beads/dolt, where DatabasePath resolves for
// a config with no dolt_data_dir.
func mkdirGateDoltDir(t *testing.T, repo string) {
t.Helper()
if err := os.MkdirAll(filepath.Join(repo, ".beads", "dolt"), 0o750); err != nil {
t.Fatal(err)
}
}
// closedPort returns a loopback port with nothing listening on it.
func closedPort(t *testing.T) int {
t.Helper()
l, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
port := l.Addr().(*net.TCPAddr).Port
if err := l.Close(); err != nil {
t.Fatal(err)
}
return port
}
// setGatePort routes doltserver port resolution to port for this test.
func setGatePort(t *testing.T, port int) {
t.Helper()
// BEADS_DOLT_SERVER_PORT is the highest-priority source in
// doltserver.DefaultConfig, which openDoltDB resolves the port through.
t.Setenv("BEADS_DOLT_SERVER_PORT", strconv.Itoa(port))
}
// TestAssessSchemaFixGate_Unreachable pins the no-database shape: no schema
// hazard exists to guard against, so filesystem repair and printed advice are
// unaffected, but schema-writing fixes stay disallowed because there is no
// database to fix. Both cases reach it with nothing on disk to migrate — a
// missing config, and a config whose database directory was never created.
//
// "Configured, on disk, and unreachable" is deliberately NOT this shape: see
// TestAssessSchemaFixGate_PresentButUnopenableFailsClosed, which pins the
// fail-closed complement.
func TestAssessSchemaFixGate_Unreachable(t *testing.T) {
cases := map[string]func(t *testing.T) string{
"no metadata.json": func(t *testing.T) string {
repo := t.TempDir()
if err := os.MkdirAll(filepath.Join(repo, ".beads"), 0o750); err != nil {
t.Fatal(err)
}
setGatePort(t, closedPort(t))
return repo
},
"configured but no database on disk": func(t *testing.T) string {
setGatePort(t, closedPort(t))
return writeGateWorkspace(t, "gate_unreachable")
},
}
for name, setup := range cases {
t.Run(name, func(t *testing.T) {
gate := AssessSchemaFixGate(setup(t))
if gate.DBReachable {
t.Error("DBReachable = true, want false")
}
if gate.AllowDBFix {
t.Error("AllowDBFix = true on an unreachable database; schema-writing fixes must stay withheld")
}
if !gate.AllowFSFix {
t.Error("AllowFSFix = false; filesystem repair must not depend on the database")
}
if !gate.RecommendFix || !gate.Determined {
t.Errorf("RecommendFix=%v Determined=%v, want both true (no hazard to warn about)",
gate.RecommendFix, gate.Determined)
}
if gate.Ahead || gate.Pending {
t.Errorf("Ahead=%v Pending=%v, want neither without a database", gate.Ahead, gate.Pending)
}
if gate.BinaryVersion != schema.LatestVersion() {
t.Errorf("BinaryVersion = %d, want %d", gate.BinaryVersion, schema.LatestVersion())
}
if gate.DBPresent {
t.Error("DBPresent = true with no database on disk; nothing exists to guard")
}
if gate.BlocksDestructiveWrites() {
t.Error("BlocksDestructiveWrites() = true with no database; there is no schema to skew")
}
})
}
}
// TestAssessSchemaFixGate_PresentButUnopenableFailsClosed is the regression test
// for the fail-open reported on PR #5145: a server-mode repo whose database is
// still on disk but whose server is stopped assessed identically to a repo with
// no database at all. That shape left DBReachable false, which the destructive
// `--check` refusal keyed on, so `bd doctor --check=pollution --clean` skipped
// the refusal, auto-started the server through the migrating factory, applied
// pending migrations blind and then deleted rows — while the identical command
// against the identical schema was refused whenever the server happened to be up.
//
// A database that exists has a schema a migrating open can rewrite, whether or
// not this process could read it, so the verdict must fail closed. The other
// cases pin the arms where databaseExistsOnDisk departs from, or had drifted
// from, autoMigrateOnVersionBump's probe: a proxied-server workspace, whose
// data directory is local even though auto-migrate skips it, and a data
// directory whose stat fails with something other than ENOENT.
func TestAssessSchemaFixGate_PresentButUnopenableFailsClosed(t *testing.T) {
cases := map[string]func(t *testing.T) string{
"stopped server": func(t *testing.T) string {
repo := writeGateWorkspace(t, "gate_present_unopenable")
// The database directory is what makes this distinct from the
// unreachable case.
mkdirGateDoltDir(t, repo)
return repo
},
"proxied-server workspace": func(t *testing.T) string {
repo := writeGateConfig(t, &configfile.Config{
Backend: configfile.BackendDolt,
DoltMode: configfile.DoltModeProxiedServer,
DoltDatabase: "gate_proxied",
})
// The proxied root defaults to the same directory.
mkdirGateDoltDir(t, repo)
return repo
},
"data directory cannot be stat'ed": func(t *testing.T) string {
if runtime.GOOS == "windows" {
t.Skip("POSIX-only: Windows can report a file used as a directory as path-not-found, which os.IsNotExist matches")
}
// A data directory configured beneath a regular file fails its
// stat with ENOTDIR: unknown, not absent. Relative, because Save
// drops an absolute dolt_data_dir as machine-local.
repo := writeGateConfig(t, &configfile.Config{
Backend: configfile.BackendDolt,
DoltDatabase: "gate_unstatable",
DoltDataDir: filepath.Join("not-a-directory", "dolt"),
})
if err := os.WriteFile(filepath.Join(repo, ".beads", "not-a-directory"), nil, 0o600); err != nil {
t.Fatal(err)
}
return repo
},
}
for name, setup := range cases {
t.Run(name, func(t *testing.T) {
setGatePort(t, closedPort(t))
t.Setenv("BEADS_DOLT_DATA_DIR", "") // would override DatabasePath
gate := AssessSchemaFixGate(setup(t))
assertPresentButUnopenable(t, gate)
})
}
}
// TestAssessSchemaFixGate_MissingMetadataReadsAbsent pins databaseExistsOnDisk's
// deliberate departure from autoMigrateOnVersionBump, which falls back to
// DefaultConfig: with no metadata.json, a data directory on disk still assesses
// as the no-database shape. The gate cannot connect without metadata.json, so
// failing closed could never be cleared, and it would turn doctor's advice for
// this state — the filesystem-only `bd doctor --fix` that regenerates
// metadata.json — into "Do NOT run 'bd doctor --fix'".
func TestAssessSchemaFixGate_MissingMetadataReadsAbsent(t *testing.T) {
setGatePort(t, closedPort(t))
repo := t.TempDir()
mkdirGateDoltDir(t, repo)
gate := AssessSchemaFixGate(repo)
if gate.DBPresent || gate.BlocksDestructiveWrites() {
t.Errorf("DBPresent=%v BlocksDestructiveWrites()=%v, want both false without metadata.json",
gate.DBPresent, gate.BlocksDestructiveWrites())
}
if !gate.RecommendFix || !gate.Determined {
t.Errorf("RecommendFix=%v Determined=%v, want both true: the advice for this state is `bd doctor --fix`",
gate.RecommendFix, gate.Determined)
}
if !gate.AllowsFix("Metadata Config") {
t.Error(`AllowsFix("Metadata Config") = false; regenerating metadata.json is the repair for this state`)
}
}
// assertPresentButUnopenable checks the fail-closed shape for a database that
// may exist but whose schema version was never read.
func assertPresentButUnopenable(t *testing.T, gate FixGate) {
t.Helper()
if !gate.DBPresent {
t.Fatal("DBPresent = false; a database that may be on disk must be guarded")
}
if gate.DBReachable {
t.Error("DBReachable = true although nothing is listening; the connection did not happen")
}
if !gate.BlocksDestructiveWrites() {
t.Error("BlocksDestructiveWrites() = false; a destructive --check must be refused here")
}
if gate.AllowDBFix {
t.Error("AllowDBFix = true for a database whose schema version was never read")
}
if gate.Determined {
t.Error("Determined = true although the schema version could not be read")
}
if gate.RecommendFix {
t.Error("RecommendFix = true; printed advice must not steer at --fix for an unread schema")
}
if gate.Reason == "" {
t.Error("Reason is empty; the refusal and the sanitized advice both interpolate it")
}
if !gate.AllowFSFix {
t.Error("AllowFSFix = false; filesystem repair does not depend on the schema")
}
// Recovery fixers are the cure for a database that cannot be opened, so they
// must survive this shape exactly as they survive the no-database one.
for _, name := range []string{"Corrupt Manifest", "Database Integrity"} {
if !gate.AllowsFix(name) {
t.Errorf("AllowsFix(%q) = false; the recovery fixers for an unopenable database must stay available", name)
}
}
// ...but a repair that opens the store through the migrating factory is
// exactly the hazard, and stays withheld.
for _, name := range []string{"Fresh Clone", "Schema Compatibility"} {
if gate.AllowsFix(name) {
t.Errorf("AllowsFix(%q) = true; a migrating open is the hazard this gate exists for", name)
}
}
}
// TestFixGateBlocksDestructiveWrites pins the hazard predicate across every
// shape, so the destructive `--check` refusal cannot drift back onto a
// connectivity test. Only "no database at all" and "schema verified current"
// may admit a destructive write.
func TestFixGateBlocksDestructiveWrites(t *testing.T) {
cases := []struct {
name string
gate FixGate
want bool
}{
{"no database", FixGate{Determined: true, RecommendFix: true, AllowFSFix: true}, false},
{"schema current", FixGate{Determined: true, DBReachable: true, DBPresent: true, AllowDBFix: true, AllowFSFix: true}, false},
{"present but unopenable", FixGate{DBPresent: true, AllowFSFix: true}, true},
{"reachable but unreadable", FixGate{DBReachable: true, DBPresent: true, AllowFSFix: true}, true},
{"pending", FixGate{Determined: true, DBReachable: true, DBPresent: true, Pending: true, AllowFSFix: true}, true},
{"ahead", FixGate{Determined: true, DBReachable: true, DBPresent: true, Ahead: true, AllowFSFix: true}, true},
}
for _, c := range cases {
if got := c.gate.BlocksDestructiveWrites(); got != c.want {
t.Errorf("%s: BlocksDestructiveWrites() = %v, want %v", c.name, got, c.want)
}
}
}

View file

@ -0,0 +1,199 @@
package doctor
import (
"strings"
"testing"
)
func safeGate() FixGate {
return FixGate{
Determined: true,
DBReachable: true,
RecommendFix: true,
AllowDBFix: true,
AllowFSFix: true,
}
}
func TestSanitizeFixRecommendation_SafePassesThrough(t *testing.T) {
in := "Run 'bd doctor --fix' to untrack runtime files"
if got := SanitizeFixRecommendation(in, safeGate()); got != in {
t.Fatalf("safe gate should pass through, got %q", got)
}
}
func TestSanitizeFixRecommendation_AheadBlocksTip(t *testing.T) {
gate := FixGate{
Determined: true,
DBReachable: true,
Ahead: true,
AllowFSFix: true,
DBVersion: 52,
BinaryVersion: 49,
Reason: "database schema is at v52, this binary knows up to v49 (3 migrations ahead)",
}
in := "Run 'bd doctor --fix' to untrack, or manually: git rm --cached .beads/redirect"
got := SanitizeFixRecommendation(in, gate)
if got == in {
t.Fatal("expected rewrite when schema is ahead")
}
for _, part := range []string{"Do NOT run", "doctor --fix", "Original tip"} {
if !strings.Contains(got, part) {
t.Fatalf("rewrite missing %q: %q", part, got)
}
}
}
func TestSanitizeFixRecommendation_PendingWarns(t *testing.T) {
gate := FixGate{
Determined: true,
DBReachable: true,
Pending: true,
AllowFSFix: true,
DBVersion: 48,
BinaryVersion: 52,
Reason: "pending migrations",
}
in := "Run: bd doctor --fix"
got := SanitizeFixRecommendation(in, gate)
if got == in {
t.Fatal("expected rewrite when migrations pending")
}
for _, part := range []string{"Avoid", "pending", "Original tip"} {
if !strings.Contains(got, part) {
t.Fatalf("rewrite missing %q: %q", part, got)
}
}
}
func TestSanitizeFixRecommendation_NoDoctorFixUnchanged(t *testing.T) {
gate := FixGate{Determined: true, DBReachable: true, Ahead: true, Reason: "skew"}
in := "Run 'bd bootstrap' as recovery"
if got := SanitizeFixRecommendation(in, gate); got != in {
t.Fatalf("non --fix tip should pass through, got %q", got)
}
}
// TestSanitizeFixRecommendation_UndeterminedFailsClosed pins the property that
// "we could not determine the schema version" is not the same as "safe".
func TestSanitizeFixRecommendation_UndeterminedFailsClosed(t *testing.T) {
gate := FixGate{
DBReachable: true,
Determined: false,
AllowFSFix: true,
Reason: "database schema version could not be determined",
}
in := "Run 'bd doctor --fix' to repair"
got := SanitizeFixRecommendation(in, gate)
if got == in {
t.Fatal("an undetermined schema version must not pass --fix advice through unchanged")
}
if !strings.Contains(got, "Do NOT run") {
t.Fatalf("undetermined gate should refuse, got %q", got)
}
}
// TestMentionsFixAdvice_ToleratesFlagOrderAndSpacing covers the wordings the
// previous strings.Contains("doctor --fix") sniff silently missed.
func TestMentionsFixAdvice_ToleratesFlagOrderAndSpacing(t *testing.T) {
shouldMatch := []string{
"Run 'bd doctor --fix'",
"bd doctor --fix",
"bd doctor --yes --fix",
"try `bd doctor --fix --verbose` next",
"Run BD DOCTOR --FIX",
}
for _, s := range shouldMatch {
if !MentionsFixAdvice(s) {
t.Errorf("expected %q to be recognised as --fix advice", s)
}
}
shouldNotMatch := []string{
"Run 'bd bootstrap'",
"see the doctor documentation",
"pass --fixture to the test runner",
}
for _, s := range shouldNotMatch {
if MentionsFixAdvice(s) {
t.Errorf("did not expect %q to be treated as --fix advice", s)
}
}
}
// TestIsFilesystemOnlyFix_DefaultsToGuarded pins the fail-closed default: a fix
// nobody has classified is treated as database-touching, so a check added later
// is guarded rather than silently escaping the gate.
func TestIsFilesystemOnlyFix_DefaultsToGuarded(t *testing.T) {
for _, name := range []string{"Gitignore", "Permissions", "Lock Files", "Git Hooks"} {
if !IsFilesystemOnlyFix(name) {
t.Errorf("%q should be classified filesystem-only", name)
}
}
for _, name := range []string{
"Database", "Schema Compatibility", "Blocked State",
"Some Check Added Next Year", "",
} {
if IsFilesystemOnlyFix(name) {
t.Errorf("%q must default to database-touching (guarded)", name)
}
}
}
// TestFixGateAllowsFix pins the single admission policy: filesystem-only fixes
// follow AllowFSFix; everything else needs AllowDBFix, except recovery fixers,
// which stay available only while the database is unreachable.
func TestFixGateAllowsFix(t *testing.T) {
ahead := FixGate{Determined: true, DBReachable: true, Ahead: true, AllowFSFix: true}
unreachable := FixGate{Determined: true, RecommendFix: true, AllowFSFix: true}
undetermined := FixGate{DBReachable: true, AllowFSFix: true}
safe := safeGate()
cases := []struct {
gate string
g FixGate
fix string
want bool
}{
{"safe", safe, "Schema Compatibility", true},
{"safe", safe, "Corrupt Manifest", true},
{"safe", safe, "Gitignore", true},
{"ahead", ahead, "Schema Compatibility", false},
{"ahead", ahead, "Pending Migrations", false},
{"ahead", ahead, "Corrupt Manifest", false},
{"ahead", ahead, "Database Integrity", false},
{"ahead", ahead, "Gitignore", true},
{"undetermined", undetermined, "Corrupt Manifest", false},
{"undetermined", undetermined, "Schema Compatibility", false},
{"unreachable", unreachable, "Schema Compatibility", false},
{"unreachable", unreachable, "Pending Migrations", false},
{"unreachable", unreachable, "Database", false},
{"unreachable", unreachable, "Fresh Clone", false},
{"unreachable", unreachable, "Some Future Fix", false},
{"unreachable", unreachable, "Corrupt Manifest", true},
{"unreachable", unreachable, "Database Integrity", true},
{"unreachable", unreachable, "Dolt Format", true},
{"unreachable", unreachable, "Dolt Schema", true},
{"unreachable", unreachable, " Corrupt Manifest ", true},
{"unreachable", unreachable, "Gitignore", true},
{"no-fs", FixGate{}, "Gitignore", false},
}
for _, c := range cases {
if got := c.g.AllowsFix(c.fix); got != c.want {
t.Errorf("%s gate: AllowsFix(%q) = %v, want %v", c.gate, c.fix, got, c.want)
}
}
}
// Recovery and filesystem-only are disjoint classes; a name in both would
// silently take the filesystem branch and ignore the reachability rule.
func TestRecoveryFixesAreNotFilesystemOnly(t *testing.T) {
for name := range recoveryFixes {
if IsFilesystemOnlyFix(name) {
t.Errorf("%q is listed as both a recovery fix and a filesystem-only fix", name)
}
}
}

View file

@ -155,7 +155,7 @@ func CheckGitignore(repoPath string) DoctorCheck {
Name: "Gitignore",
Status: "warning",
Message: ".beads/.gitignore not found",
Fix: "Run: bd init (safe to re-run) or bd doctor --fix",
Fix: "Run: bd doctor --fix",
}
}
@ -168,7 +168,7 @@ func CheckGitignore(repoPath string) DoctorCheck {
Status: "warning",
Message: "Outdated .beads/.gitignore (missing required patterns)",
Detail: "Missing: " + strings.Join(missing, ", "),
Fix: "Run: bd doctor --fix or bd init (safe to re-run)",
Fix: "Run: bd doctor --fix",
}
}
@ -182,7 +182,7 @@ func CheckGitignore(repoPath string) DoctorCheck {
Status: "warning",
Message: "Unexpected permissions on .beads/.gitignore",
Detail: fmt.Sprintf("Mode is %04o, want 0600", info.Mode().Perm()),
Fix: "Run: bd doctor --fix or bd init (safe to re-run)",
Fix: "Run: bd doctor --fix",
}
}
}
@ -749,7 +749,7 @@ func CheckProjectGitignore(repoPath string) DoctorCheck {
Name: "Project Gitignore",
Status: StatusWarning,
Message: "No project .gitignore found — Dolt/credential files may be committed accidentally",
Fix: "Run: bd init (safe to re-run) or bd doctor --fix",
Fix: "Run: bd doctor --fix",
}
}
return DoctorCheck{
@ -773,7 +773,7 @@ func CheckProjectGitignore(repoPath string) DoctorCheck {
Status: StatusWarning,
Message: "Project .gitignore missing required exclusion patterns",
Detail: "Missing: " + strings.Join(missing, ", "),
Fix: "Run: bd doctor --fix or bd init (safe to re-run)",
Fix: "Run: bd doctor --fix",
}
}

View file

@ -1061,7 +1061,7 @@ func TestCheckGitignore_VariousStatuses(t *testing.T) {
// Don't create .beads directory
},
expectedStatus: StatusWarning,
expectedFix: "Run: bd init (safe to re-run) or bd doctor --fix",
expectedFix: "Run: bd doctor --fix",
description: "returns warning when .beads directory doesn't exist",
},
{
@ -1073,7 +1073,7 @@ func TestCheckGitignore_VariousStatuses(t *testing.T) {
}
},
expectedStatus: StatusWarning,
expectedFix: "Run: bd init (safe to re-run) or bd doctor --fix",
expectedFix: "Run: bd doctor --fix",
description: "returns warning when .gitignore doesn't exist",
},
{
@ -1109,7 +1109,7 @@ daemon.log
}
},
expectedStatus: StatusWarning,
expectedFix: "Run: bd doctor --fix or bd init (safe to re-run)",
expectedFix: "Run: bd doctor --fix",
description: "returns warning when missing required patterns like dolt/ and redirect",
},
{
@ -1128,7 +1128,7 @@ daemon.log
}
},
expectedStatus: StatusWarning,
expectedFix: "Run: bd doctor --fix or bd init (safe to re-run)",
expectedFix: "Run: bd doctor --fix",
description: "returns warning when missing multiple patterns",
},
{
@ -1144,7 +1144,7 @@ daemon.log
}
},
expectedStatus: StatusWarning,
expectedFix: "Run: bd doctor --fix or bd init (safe to re-run)",
expectedFix: "Run: bd doctor --fix",
description: "returns warning for empty file",
},
{
@ -1164,7 +1164,7 @@ daemon.log
}
},
expectedStatus: StatusWarning,
expectedFix: "Run: bd doctor --fix or bd init (safe to re-run)",
expectedFix: "Run: bd doctor --fix",
description: "returns warning for comments-only file",
},
{
@ -3057,8 +3057,10 @@ func TestCheckGitignore_WarnsOnLoosePermsWhenPatternComplete(t *testing.T) {
if !strings.Contains(check.Detail, "0644") {
t.Errorf("Detail = %q, want the observed mode 0644", check.Detail)
}
if check.Fix == "" {
t.Error("expected a Fix suggestion for loose permissions")
// Pin the exact hint: re-running bd init is not a safe repair to suggest
// (be-5up5), and FixGitignore below is what actually restores the mode.
if check.Fix != "Run: bd doctor --fix" {
t.Errorf("Fix = %q, want %q", check.Fix, "Run: bd doctor --fix")
}
// After the fix runs, the check must go green.

View file

@ -19,7 +19,8 @@ type agentDoctorResult struct {
// buildAgentResult converts a standard doctorResult to an agent-enriched result.
// Only non-OK checks are included in diagnostics — agents don't need 45 "ok" entries.
func buildAgentResult(result doctorResult) agentDoctorResult {
// The gate is applied to each enriched command list; see doctor.EnrichForAgent.
func buildAgentResult(result doctorResult, gate doctor.FixGate) agentDoctorResult {
ar := agentDoctorResult{
Path: result.Path,
OverallOK: result.OverallOK,
@ -40,7 +41,7 @@ func buildAgentResult(result doctorResult) agentDoctorResult {
Detail: check.Detail,
Fix: check.Fix,
Category: check.Category,
}))
}, gate))
case statusWarning:
warnCount++
ar.Diagnostics = append(ar.Diagnostics, doctor.EnrichForAgent(doctor.DoctorCheck{
@ -50,7 +51,7 @@ func buildAgentResult(result doctorResult) agentDoctorResult {
Detail: check.Detail,
Fix: check.Fix,
Category: check.Category,
}))
}, gate))
}
}

View file

@ -0,0 +1,204 @@
package main
import (
"strings"
"sync/atomic"
"testing"
"github.com/steveyegge/beads/cmd/bd/doctor"
)
// gateStub builds the accessor destructiveCheckRefusal takes, counting how many
// times the gate was actually evaluated.
func gateStub(g doctor.FixGate, calls *atomic.Int32) func() doctor.FixGate {
return func() doctor.FixGate {
calls.Add(1)
return g
}
}
// presentButUnopenableGate is the shape AssessSchemaFixGate returns for a
// database that is on disk but could not be opened.
func presentButUnopenableGate() doctor.FixGate {
return doctor.FixGate{
DBPresent: true,
AllowFSFix: true,
Reason: "database exists but could not be opened, so its schema version is unknown",
}
}
// TestDestructiveCheckRefusalRefusesOnPresentButUnopenableDatabase is the
// call-site half of the PR #5145 fail-open: the refusal must fire for a database
// that exists but could not be opened, because the handler it guards opens the
// store through the migrating factory, which auto-starts a stopped server and
// applies pending migrations before writing.
func TestDestructiveCheckRefusalRefusesOnPresentButUnopenableDatabase(t *testing.T) {
var calls atomic.Int32
var err error
// HandleErrorWithHint reports on stderr and returns a bare exit code, so the
// refusal text — which interpolates the gate's Reason — is only observable
// there.
stderr := captureStderrDuring(t, func() {
err = destructiveCheckRefusal("pollution", true, false, gateStub(presentButUnopenableGate(), &calls))
})
if err == nil {
t.Fatal("destructiveCheckRefusal returned nil; --check=pollution --clean must be refused on an unopenable database")
}
if !strings.Contains(stderr, "refusing destructive 'bd doctor --check=pollution'") {
t.Errorf("refusal did not name the command it refused:\n%s", stderr)
}
if !strings.Contains(stderr, "could not be opened") {
t.Errorf("refusal did not explain why, so the operator cannot act on it:\n%s", stderr)
}
if calls.Load() != 1 {
t.Errorf("gate evaluated %d times, want exactly 1", calls.Load())
}
}
// TestDestructiveCheckRefusalAllowsFilesystemOnlyCleanup pins the two planes
// agreeing about one operation: `bd doctor --fix` admits "Classic Artifacts"
// under a blocked gate because it is filesystem-only, so
// `--check=artifacts --clean` must not be refused with a schema-skew message in
// exactly the degraded state where clearing stale artifacts is safe and useful.
func TestDestructiveCheckRefusalAllowsFilesystemOnlyCleanup(t *testing.T) {
blocked := []struct {
name string
gate doctor.FixGate
}{
{"present but unopenable", presentButUnopenableGate()},
{"pending", doctor.FixGate{Determined: true, DBReachable: true, DBPresent: true, Pending: true, AllowFSFix: true, Reason: "pending"}},
{"ahead", doctor.FixGate{Determined: true, DBReachable: true, DBPresent: true, Ahead: true, AllowFSFix: true, Reason: "ahead"}},
}
for _, b := range blocked {
var calls atomic.Int32
if err := destructiveCheckRefusal("artifacts", true, false, gateStub(b.gate, &calls)); err != nil {
t.Errorf("%s gate: --check=artifacts --clean refused, but the same cleanup is admitted by --fix: %v", b.name, err)
}
// The same gate must still refuse the row-deleting sibling, or this test
// would pass by disabling the guard rather than by scoping it.
if err := destructiveCheckRefusal("pollution", true, false, gateStub(b.gate, &calls)); err == nil {
t.Errorf("%s gate: --check=pollution --clean was admitted; it deletes rows and must stay refused", b.name)
}
if err := destructiveCheckRefusal("validate", false, true, gateStub(b.gate, &calls)); err == nil {
t.Errorf("%s gate: --check=validate --fix was admitted; it writes through an opened store", b.name)
}
}
}
// TestDestructiveCheckRefusalAdmitsWhenNoDatabaseExists keeps the no-hazard case
// unguarded: with no database on disk there is no schema to skew, so refusing
// would block a cleanup that cannot possibly migrate anything.
func TestDestructiveCheckRefusalAdmitsWhenNoDatabaseExists(t *testing.T) {
noDB := doctor.FixGate{Determined: true, RecommendFix: true, AllowFSFix: true}
for _, flag := range []string{"artifacts", "pollution"} {
var calls atomic.Int32
if err := destructiveCheckRefusal(flag, true, false, gateStub(noDB, &calls)); err != nil {
t.Errorf("--check=%s --clean refused with no database present: %v", flag, err)
}
}
}
// TestDestructiveCheckRefusalDoesNotProbeReadOnlyChecks pins the laziness the
// gate's contract claims: a read-only `--check` must not evaluate the gate at
// all, because the probe is the only thing that would touch the database on a
// path that otherwise does not.
func TestDestructiveCheckRefusalDoesNotProbeReadOnlyChecks(t *testing.T) {
cases := []struct {
flag string
clean bool
fix bool
}{
{"artifacts", false, false},
{"pollution", false, false},
{"conventions", true, true},
{"validate", true, false},
}
for _, c := range cases {
var calls atomic.Int32
if err := destructiveCheckRefusal(c.flag, c.clean, c.fix, gateStub(presentButUnopenableGate(), &calls)); err != nil {
t.Errorf("--check=%s (clean=%v fix=%v) refused although it cannot write: %v", c.flag, c.clean, c.fix, err)
}
if calls.Load() != 0 {
t.Errorf("--check=%s (clean=%v fix=%v) evaluated the gate %d times; a read-only check must not probe",
c.flag, c.clean, c.fix, calls.Load())
}
}
}
// TestNewSchemaGateIsLazyAndMemoised pins the half of the gate's stated contract
// that is a real invariant rather than a call-order claim: one verdict per
// invocation, produced on first use and reused by every later consumer. The
// assessor is the only thing in the command that opens a connection for the
// gate, so evaluating it eagerly would probe on read-only paths, and evaluating
// it twice would let two consumers in one invocation disagree.
func TestNewSchemaGateIsLazyAndMemoised(t *testing.T) {
var calls atomic.Int32
original := assessSchemaFixGate
t.Cleanup(func() { assessSchemaFixGate = original })
assessSchemaFixGate = func(path string) doctor.FixGate {
calls.Add(1)
return doctor.FixGate{Determined: true, DBReachable: true, DBPresent: true, DBVersion: 7, AllowFSFix: true}
}
gate := newSchemaGate("/some/repo")
if calls.Load() != 0 {
t.Fatalf("assessor ran %d times before first use; the gate must be lazy", calls.Load())
}
first := gate()
for i := 0; i < 4; i++ {
if got := gate(); got != first {
t.Fatalf("gate() returned %+v on call %d, want the memoised %+v", got, i+2, first)
}
}
if calls.Load() != 1 {
t.Errorf("assessor ran %d times across five reads, want exactly 1", calls.Load())
}
}
// TestNewSchemaGatePassesTheRepoPathThrough guards against a seam that reads a
// different workspace than the command was pointed at.
func TestNewSchemaGatePassesTheRepoPathThrough(t *testing.T) {
original := assessSchemaFixGate
t.Cleanup(func() { assessSchemaFixGate = original })
var seen string
assessSchemaFixGate = func(path string) doctor.FixGate {
seen = path
return doctor.FixGate{}
}
newSchemaGate("/repo/under/test")()
if seen != "/repo/under/test" {
t.Errorf("assessor received %q, want %q", seen, "/repo/under/test")
}
}
// TestApplyFixesReportsWithheldFilesystemOnlyFix pins the reporting hole: a
// filesystem-only fix the gate rejects used to be appended to neither the
// fixable list nor the withheld list, so it was silently no-opped with no
// output. Unreachable while every assessed gate sets AllowFSFix, which is why
// this drives the gate shape directly.
func TestApplyFixesReportsWithheldFilesystemOnlyFix(t *testing.T) {
result := doctorResult{
Checks: []doctorCheck{
{Name: "Gitignore", Status: statusWarning, Fix: "add entries"},
},
}
// AllowFSFix false is the shape that exposed the hole.
out := captureStdout(t, func() error {
applyFixes(result, doctor.FixGate{DBReachable: true, DBPresent: true, Reason: "schema state unknown"})
return nil
})
if !strings.Contains(out, "Gitignore") {
t.Errorf("withheld filesystem-only fix was not reported at all:\n%s", out)
}
if !strings.Contains(out, "Skipping 1 gated fix(es)") {
t.Errorf("withheld count/label missing; the withheld set is whatever the gate blocked:\n%s", out)
}
if strings.Contains(out, "database fix(es)") {
t.Errorf("a withheld filesystem-only fix was labelled a database fix:\n%s", out)
}
}

View file

@ -16,17 +16,36 @@ import (
"golang.org/x/term"
)
// previewFixes shows what would be fixed without applying changes
func previewFixes(result doctorResult) {
// Collect all fixable issues
var fixableIssues []doctorCheck
// collectFixableIssues returns actionable fixes split by whether applying them
// can touch the database schema (GH#4993). A schema gate should withhold schema
// writes, not refuse to repair a file mode.
func collectFixableIssues(result doctorResult) (dbFixes, fsFixes []doctorCheck) {
for _, check := range result.Checks {
if (check.Status == statusWarning || check.Status == statusError) && check.Fix != "" {
fixableIssues = append(fixableIssues, check)
if check.Status != statusWarning && check.Status != statusError {
continue
}
if check.Fix == "" {
continue
}
if doctor.IsFilesystemOnlyFix(check.Name) {
fsFixes = append(fsFixes, check)
} else {
dbFixes = append(dbFixes, check)
}
}
return dbFixes, fsFixes
}
if len(fixableIssues) == 0 {
// previewFixes shows what would be fixed without applying changes. A dry run
// writes nothing, so it is never refused on schema grounds; the gate decides
// how each fix is labeled, not whether the preview runs.
func previewFixes(result doctorResult, gate doctor.FixGate) {
if gate.Reason != "" {
fmt.Printf("\n%s Schema gate: %s\n", ui.RenderWarn("⚠"), gate.Reason)
}
dbFixes, fsFixes := collectFixableIssues(result)
if len(dbFixes)+len(fsFixes) == 0 {
fmt.Println("\n✓ No fixable issues found (dry-run)")
return
}
@ -34,9 +53,10 @@ func previewFixes(result doctorResult) {
fmt.Println("\n[DRY-RUN] The following issues would be fixed with --fix:")
fmt.Println()
for i, issue := range fixableIssues {
// Show the issue details
fmt.Printf(" %d. %s\n", i+1, issue.Name)
n := 0
printIssue := func(issue doctorCheck, blocked bool) {
n++
fmt.Printf(" %d. %s\n", n, issue.Name)
if issue.Status == statusError {
fmt.Printf(" Status: %s\n", ui.RenderFail("ERROR"))
} else {
@ -47,19 +67,75 @@ func previewFixes(result doctorResult) {
fmt.Printf(" Detail: %s\n", issue.Detail)
}
fmt.Printf(" Fix: %s\n", issue.Fix)
if blocked {
fmt.Printf(" %s\n", ui.RenderWarn("Blocked by the schema gate — would be skipped"))
}
fmt.Println()
}
fmt.Printf("[DRY-RUN] Would attempt to fix %d issue(s)\n", len(fixableIssues))
fmt.Println("Run 'bd doctor --fix' to apply these fixes")
// GH#4993: admission is FixGate.AllowsFix alone. Reason is advisory text,
// not a safety signal — an unreachable/undetermined gate leaves Reason at
// its zero value ("") while still needing schema-writing fixes withheld,
// so admitting on gate.Reason == "" reopened the bypass this gate closes.
blocked := 0
for _, issue := range append(append([]doctorCheck{}, fsFixes...), dbFixes...) {
withheld := !gate.AllowsFix(issue.Name)
if withheld {
blocked++
}
printIssue(issue, withheld)
}
total := len(fsFixes) + len(dbFixes)
switch {
case blocked > 0 && blocked < total:
fmt.Printf("[DRY-RUN] Would apply %d fix(es); %d fix(es) are blocked by the schema gate\n",
total-blocked, blocked)
fmt.Println("Run 'bd doctor --fix' to apply the permitted fixes; resolve the schema state to apply the rest")
case blocked > 0:
fmt.Printf("[DRY-RUN] All %d fix(es) are blocked by the schema gate\n", total)
fmt.Println("Resolve the schema state shown above before running 'bd doctor --fix'")
default:
fmt.Printf("[DRY-RUN] Would attempt to fix %d issue(s)\n", total)
fmt.Println("Run 'bd doctor --fix' to apply these fixes")
}
}
func applyFixes(result doctorResult) {
// Collect all fixable issues
var fixableIssues []doctorCheck
for _, check := range result.Checks {
if (check.Status == statusWarning || check.Status == statusError) && check.Fix != "" {
fixableIssues = append(fixableIssues, check)
func applyFixes(result doctorResult, gate doctor.FixGate) {
if gate.Reason != "" {
fmt.Printf("\n%s Schema gate: %s\n", ui.RenderWarn("⚠"), gate.Reason)
}
dbFixes, fsFixes := collectFixableIssues(result)
// GH#4993: withhold only what the gate is about. Filesystem-only fixes
// are never schema writes, and recovery fixers stay available when the
// database is unreachable (FixGate.AllowsFix); everything else is withheld
// whenever the gate blocks. Admission is AllowsFix alone, never
// gate.Reason == "".
// Everything AllowsFix rejects is reported. Qualifying this with
// !IsFilesystemOnlyFix would drop a withheld filesystem-only fix from both
// lists, silently no-opping it: unreachable while every constructed gate sets
// AllowFSFix, but a future gate shape that does not would fix nothing and say
// nothing. The label stays generic for the same reason — the withheld set is
// whatever the gate blocked, not necessarily database work.
var fixableIssues, withheld []doctorCheck
for _, issue := range append(append([]doctorCheck{}, fsFixes...), dbFixes...) {
if gate.AllowsFix(issue.Name) {
fixableIssues = append(fixableIssues, issue)
} else {
withheld = append(withheld, issue)
}
}
if len(withheld) > 0 {
reason := gate.Reason
if reason == "" {
reason = "database schema state could not be assessed"
}
fmt.Printf("\n%s Skipping %d gated fix(es) — %s\n",
ui.RenderFail("✗"), len(withheld), reason)
for _, issue := range withheld {
fmt.Printf(" · %s\n", issue.Name)
}
}

View file

@ -0,0 +1,460 @@
package main
import (
"encoding/json"
"os"
"path/filepath"
"strings"
"testing"
"github.com/steveyegge/beads/cmd/bd/doctor"
)
// The tests in this file cover the WIRING of the schema fix gate, not its
// predicate logic (that lives in cmd/bd/doctor/fix_gate_test.go).
//
// This distinction is the whole point. GH#4993 originally shipped with a
// correct predicate and a full suite of green tests, while three of the four
// output paths emitted unguarded advice, one command family bypassed the gate
// entirely, and a bare `bd doctor` applied migrations before the gate was
// consulted. Every one of those is a wiring defect, and a test that constructs
// a FixGate by hand cannot observe any of them.
const rawFixTip = "Run 'bd doctor --fix' to untrack runtime files"
// blockedGate is a determined gate that forbids recommending --fix.
func blockedGate() doctor.FixGate {
return doctor.FixGate{
Determined: true,
DBReachable: true,
Ahead: true,
AllowFSFix: true,
DBVersion: 52,
BinaryVersion: 49,
Reason: "database schema is at v52, this binary knows up to v49 (3 migrations ahead)",
}
}
func resultWithFixTip() doctorResult {
return doctorResult{
Path: "/tmp/does-not-need-to-exist",
CLIVersion: "test",
Checks: []doctorCheck{
{
Name: "Tracked Runtime Files",
Status: statusWarning,
Message: "runtime files are tracked",
Category: "Core",
Fix: rawFixTip,
},
},
}
}
// assertNoUnguardedFixAdvice fails if the raw tip appears anywhere that is not
// inside the gate's own "Original tip was: ..." rewrite.
func assertNoUnguardedFixAdvice(t *testing.T, label, out string) {
t.Helper()
if !strings.Contains(out, rawFixTip) {
return
}
guarded := strings.Count(out, "Original tip was: "+rawFixTip)
total := strings.Count(out, rawFixTip)
if guarded != total {
t.Errorf("%s emitted --fix advice the schema gate had ruled unsafe\n"+
" %d occurrence(s), only %d guarded\n---output---\n%s",
label, total, guarded, out)
}
}
// TestNoEmitterLeaksUnguardedFixAdvice is the regression test for the central
// defect: the sanitizer used to run inside printDiagnostics only, so --json,
// --agent and --output published advice the gate had already ruled unsafe.
//
// It is written as a property over the whole emitter set rather than as one
// example per format, because the failure mode is "somebody added an output
// path and did not know the guard existed."
func TestNoEmitterLeaksUnguardedFixAdvice(t *testing.T) {
gate := blockedGate()
result := resultWithFixTip()
sanitizeFixAdvice(&result, gate)
tmp := t.TempDir()
emitters := []struct {
name string
emit func(t *testing.T, r doctorResult) string
}{
{
name: "text/printDiagnostics",
emit: func(t *testing.T, r doctorResult) string {
return captureStdout(t, func() error {
printDiagnostics(r, gate)
return nil
})
},
},
{
name: "json/doctorResult",
emit: func(t *testing.T, r doctorResult) string {
b, err := json.Marshal(r)
if err != nil {
t.Fatalf("marshal: %v", err)
}
return string(b)
},
},
{
name: "agent/buildAgentResult",
emit: func(t *testing.T, r doctorResult) string {
b, err := json.Marshal(buildAgentResult(r, gate))
if err != nil {
t.Fatalf("marshal agent result: %v", err)
}
return string(b)
},
},
{
name: "export/exportDiagnostics",
emit: func(t *testing.T, r doctorResult) string {
p := filepath.Join(tmp, "diag.json")
if err := exportDiagnostics(r, p); err != nil {
t.Fatalf("export: %v", err)
}
b, err := os.ReadFile(p) // #nosec G304 - test-controlled path
if err != nil {
t.Fatalf("read export: %v", err)
}
return string(b)
},
},
}
for _, e := range emitters {
t.Run(e.name, func(t *testing.T) {
assertNoUnguardedFixAdvice(t, e.name, e.emit(t, result))
})
}
}
// assertAgentCommandsGuarded fails if any remediation command in the agent
// output steers at `bd doctor --fix` without the gate's rewrite marker.
// Agent enrichers hardcode their own commands, so the raw tip used by the
// other emitters is not what leaks here; the command text itself is.
func assertAgentCommandsGuarded(t *testing.T, label string, ar agentDoctorResult) {
t.Helper()
for _, d := range ar.Diagnostics {
for _, c := range d.Commands {
if doctor.MentionsFixAdvice(c) && !strings.Contains(c, "Original tip was: ") {
t.Errorf("%s: check %q (%s) published unguarded --fix command %q under a blocked gate",
label, d.Name, d.Status, c)
}
}
}
}
// TestNoAgentEnricherLeaksUnguardedFixCommand runs the --agent emitter over
// EVERY registered enricher, plus a name with no enricher (generic path).
// The original fixture used only an unenriched name, so the ~18 enrichers that
// hardcode `bd doctor --fix` were never exercised and the test passed
// vacuously. Both statuses are covered because some enrichers branch on it.
func TestNoAgentEnricherLeaksUnguardedFixCommand(t *testing.T) {
names := append(doctor.AgentEnricherNames(), "Tracked Runtime Files")
if len(names) < 20 {
t.Fatalf("expected the full enricher registry plus the unenriched case, got %d names", len(names))
}
build := func(gate doctor.FixGate) agentDoctorResult {
var r doctorResult
for _, name := range names {
for _, status := range []string{statusError, statusWarning} {
r.Checks = append(r.Checks, doctorCheck{
Name: name, Status: status, Message: "m", Category: "Core", Fix: rawFixTip,
})
}
}
sanitizeFixAdvice(&r, gate)
return buildAgentResult(r, gate)
}
// Non-vacuity: under a safe gate the fixture must actually surface
// `bd doctor --fix` commands from enrichers, or the blocked-gate assertion
// below proves nothing. Schema Compatibility and Database Integrity are
// the checks that fire on the very skew this gate exists for.
surfaced := map[string]bool{}
for _, d := range build(doctor.FixGate{Determined: true, DBReachable: true, RecommendFix: true, AllowDBFix: true, AllowFSFix: true}).Diagnostics {
for _, c := range d.Commands {
if doctor.MentionsFixAdvice(c) {
surfaced[d.Name] = true
}
}
}
for _, must := range []string{"Schema Compatibility", "Database Integrity", "Tracked Runtime Files"} {
if !surfaced[must] {
t.Fatalf("fixture too weak: %q surfaced no --fix command under a safe gate", must)
}
}
if len(surfaced) < 15 {
t.Fatalf("fixture too weak: only %d names surfaced --fix commands", len(surfaced))
}
assertAgentCommandsGuarded(t, "blocked gate", build(blockedGate()))
}
// TestSanitizeFixAdviceWritesThroughSlice pins the specific Go mistake that
// made the original guard a no-op: ranging by value over []doctorCheck mutates
// a copy. Asserting on the caller's slice — not on a returned value — is what
// makes this test able to fail.
func TestSanitizeFixAdviceWritesThroughSlice(t *testing.T) {
result := resultWithFixTip()
sanitizeFixAdvice(&result, blockedGate())
if result.Checks[0].Fix == rawFixTip {
t.Fatal("sanitizeFixAdvice did not write through to result.Checks — " +
"the mutation was applied to a copy")
}
if !strings.Contains(result.Checks[0].Fix, "Do NOT run") {
t.Fatalf("expected a guarded tip, got %q", result.Checks[0].Fix)
}
}
// TestSanitizeFixAdviceIsIdempotent guards against double-wrapping now that the
// pass runs again after --fix re-runs diagnostics.
func TestSanitizeFixAdviceIsIdempotent(t *testing.T) {
gate := blockedGate()
result := resultWithFixTip()
sanitizeFixAdvice(&result, gate)
once := result.Checks[0].Fix
sanitizeFixAdvice(&result, gate)
twice := result.Checks[0].Fix
if strings.Count(twice, "Original tip was:") > 1 {
t.Fatalf("sanitizing twice nested the guard:\n once: %q\ntwice: %q", once, twice)
}
}
// TestCheckFlagWrites enumerates which --check= invocations can modify state.
// The gate is applied at a single branch point in RunE keyed off this function,
// so this table is the complete statement of what is guarded — a new
// destructive check that is missing here is a silent bypass.
func TestCheckFlagWrites(t *testing.T) {
cases := []struct {
flag string
clean bool
fix bool
want bool
}{
{"pollution", true, false, true},
{"pollution", false, false, false},
{"artifacts", true, false, true},
{"artifacts", false, false, false},
{"validate", false, true, true},
{"validate", false, false, false},
{"conventions", true, true, false},
{"unknown-check", true, true, false},
}
for _, c := range cases {
if got := checkFlagWrites(c.flag, c.clean, c.fix); got != c.want {
t.Errorf("checkFlagWrites(%q, clean=%v, fix=%v) = %v, want %v",
c.flag, c.clean, c.fix, got, c.want)
}
}
}
// unreachableGate mirrors the `unreachable` FixGate literal in
// cmd/bd/doctor/fix_gate.go (AssessSchemaFixGate, openDoltDB failure branch):
// Determined and AllowFSFix are true, but AllowDBFix and Reason are left at
// their zero values (false, ""). A gate keyed off `gate.Reason == ""` reads
// this shape as "safe to fix" and admits database fixes on a stopped or
// unreachable Dolt server — the bypass GH#4993 exists to close.
func unreachableGate() doctor.FixGate {
return doctor.FixGate{
Determined: true,
RecommendFix: true,
AllowFSFix: true,
BinaryVersion: 49,
}
}
func resultWithDBFix() doctorResult {
return doctorResult{
Path: "/tmp/does-not-need-to-exist",
CLIVersion: "test",
Checks: []doctorCheck{
{
Name: "Schema Compatibility",
Status: statusError,
Message: "schema version mismatch",
Category: "Core",
Fix: "run 'bd doctor --fix' to migrate",
},
},
}
}
// TestApplyFixesWithholdsDBFixOnUnreachableGate is the regression test for the
// gate bypass: applyFixes admitted a database fix whenever
// `gate.AllowDBFix || gate.Reason == ""`, which is true for the unreachable
// shape above even though AllowDBFix is false. Gating on AllowDBFix alone
// withholds it.
func TestApplyFixesWithholdsDBFixOnUnreachableGate(t *testing.T) {
gate := unreachableGate()
result := resultWithDBFix()
out := captureStdout(t, func() error {
applyFixes(result, gate)
return nil
})
if strings.Contains(out, "Fixing Schema Compatibility") {
t.Fatalf("applyFixes attempted a database fix on an unreachable gate:\n%s", out)
}
if !strings.Contains(out, "No fixable issues found") {
t.Fatalf("expected applyFixes to withhold the only fix (a database fix) on an unreachable gate, got:\n%s", out)
}
}
// withNullStdin points os.Stdin at /dev/null so applyFixes takes its
// non-interactive early return after listing what it would fix, instead of
// prompting or running a real fixer against the test's fake path.
func withNullStdin(t *testing.T) {
t.Helper()
f, err := os.Open(os.DevNull)
if err != nil {
t.Fatal(err)
}
orig := os.Stdin
os.Stdin = f
t.Cleanup(func() {
os.Stdin = orig
_ = f.Close()
})
}
func resultWithRecoveryAndSchemaFixes() doctorResult {
return doctorResult{
Path: "/tmp/does-not-need-to-exist",
CLIVersion: "test",
Checks: []doctorCheck{
{Name: "Corrupt Manifest", Status: statusError, Message: "manifest corrupt", Fix: "bd doctor --fix"},
{Name: "Dolt Format", Status: statusWarning, Message: "pre-v56 dolt dir", Fix: "bd doctor --fix"},
{Name: "Database Integrity", Status: statusError, Message: "integrity check failed", Fix: "bd doctor --fix"},
{Name: "Dolt Schema", Status: statusWarning, Message: "dolt_database missing", Fix: "bd doctor --fix"},
{Name: "Schema Compatibility", Status: statusError, Message: "schema mismatch", Fix: "bd doctor --fix"},
{Name: "Pending Migrations", Status: statusWarning, Message: "pending", Fix: "bd doctor --fix"},
},
}
}
// TestApplyFixesKeepsRecoveryFixesOnUnreachableGate pins the narrow rule that
// an unopenable database must not withhold the fixes that repair an unopenable
// database: recovery fixers are listed as runnable, schema-writing fixes are
// still skipped.
func TestApplyFixesKeepsRecoveryFixesOnUnreachableGate(t *testing.T) {
withNullStdin(t)
out := captureStdout(t, func() error {
applyFixes(resultWithRecoveryAndSchemaFixes(), unreachableGate())
return nil
})
for _, name := range []string{"Corrupt Manifest", "Dolt Format", "Database Integrity", "Dolt Schema"} {
if !strings.Contains(out, name+": ") {
t.Errorf("recovery fix %q was not offered on an unreachable gate:\n%s", name, out)
}
}
for _, name := range []string{"Schema Compatibility", "Pending Migrations"} {
if strings.Contains(out, name+": ") {
t.Errorf("schema-writing fix %q was offered on an unreachable gate:\n%s", name, out)
}
if !strings.Contains(out, "· "+name) {
t.Errorf("schema-writing fix %q was not reported as skipped:\n%s", name, out)
}
}
}
// TestApplyFixesWithholdsRecoveryFixesWhenDatabaseReachableButBlocked is the
// other edge of the same rule: the exception exists because an unreachable
// database has no readable schema to skew. A reachable database that is ahead
// of the binary still gets backup+reinit withheld.
func TestApplyFixesWithholdsRecoveryFixesWhenDatabaseReachableButBlocked(t *testing.T) {
withNullStdin(t)
out := captureStdout(t, func() error {
applyFixes(resultWithRecoveryAndSchemaFixes(), blockedGate())
return nil
})
if !strings.Contains(out, "No fixable issues found") {
t.Fatalf("expected every fix withheld on a reachable, skewed gate, got:\n%s", out)
}
if strings.Contains(out, "Corrupt Manifest: ") {
t.Fatalf("recovery fix offered while the database is reachable and ahead:\n%s", out)
}
}
// TestPreviewFixesLabelsOnlySchemaWritingFixesBlockedOnUnreachableGate is the
// dry-run half of the recovery rule.
func TestPreviewFixesLabelsOnlySchemaWritingFixesBlockedOnUnreachableGate(t *testing.T) {
out := captureStdout(t, func() error {
previewFixes(resultWithRecoveryAndSchemaFixes(), unreachableGate())
return nil
})
if got := strings.Count(out, "Blocked by the schema gate"); got != 2 {
t.Fatalf("expected exactly the 2 schema-writing fixes labelled blocked, got %d:\n%s", got, out)
}
if !strings.Contains(out, "Would apply 4 fix(es); 2 fix(es) are blocked by the schema gate") {
t.Fatalf("unexpected dry-run summary:\n%s", out)
}
}
// TestPreviewFixesFlagsDBFixAsBlockedOnUnreachableGate is the dry-run half of
// the same regression: blockDB used `!gate.AllowDBFix && gate.Reason != ""`,
// which is false (not blocked) for the same unreachable shape, so a dry run
// never warned that the fix would actually be withheld.
func TestPreviewFixesFlagsDBFixAsBlockedOnUnreachableGate(t *testing.T) {
gate := unreachableGate()
result := resultWithDBFix()
out := captureStdout(t, func() error {
previewFixes(result, gate)
return nil
})
if !strings.Contains(out, "Blocked by the schema gate") {
t.Fatalf("previewFixes did not flag the database fix as blocked on an unreachable gate:\n%s", out)
}
if !strings.Contains(out, "blocked by the schema gate") {
t.Fatalf("expected the dry-run summary to report the fix(es) as blocked, got:\n%s", out)
}
}
// TestCollectFixableIssuesPartitionsByBlastRadius pins the split that lets a
// schema gate withhold schema writes without also refusing to repair a file
// mode — the "no hatch for filesystem-only fixes" complaint.
func TestCollectFixableIssuesPartitionsByBlastRadius(t *testing.T) {
result := doctorResult{
Checks: []doctorCheck{
{Name: "Gitignore", Status: statusWarning, Fix: "add entries"},
{Name: "Permissions", Status: statusError, Fix: "chmod"},
{Name: "Schema Compatibility", Status: statusError, Fix: "migrate"},
{Name: "Database", Status: statusWarning, Fix: "repair"},
{Name: "Healthy Thing", Status: statusOK, Fix: "should be ignored"},
{Name: "No Fix Available", Status: statusError},
},
}
dbFixes, fsFixes := collectFixableIssues(result)
if len(fsFixes) != 2 {
t.Errorf("expected 2 filesystem fixes, got %d: %+v", len(fsFixes), fsFixes)
}
if len(dbFixes) != 2 {
t.Errorf("expected 2 database fixes, got %d: %+v", len(dbFixes), dbFixes)
}
for _, f := range fsFixes {
if !doctor.IsFilesystemOnlyFix(f.Name) {
t.Errorf("%q was partitioned as filesystem-only but is not", f.Name)
}
}
}

View file

@ -0,0 +1,15 @@
//go:build cgo && unix
package main
import "testing"
func TestProxiedServerExternalPolicyDirectParity(t *testing.T) {
requireSharedProxiedServer(t)
// This fixture drops its database and purges the shared server's dropped
// databases on cleanup. Finish before parallel proxied fixtures start so
// that server-wide cleanup cannot race their schema initialization.
bd := buildEmbeddedBD(t)
p := newDirectHistoryProject(t, bd, "xd")
exerciseExternalMutationPolicy(t, crossModeEnv{mode: "direct-server", bd: bd, dir: p.dir, env: p.env})
}

View file

@ -0,0 +1,117 @@
//go:build cgo
package main
import (
"fmt"
"os"
"path/filepath"
"strings"
"testing"
"github.com/steveyegge/beads/internal/types"
)
// Exercise the CLI wiring: testing Lifecycle.Close or IssueClaimer alone misses
// that close uses BatchCloser and update --claim uses Lifecycle.Update.
func TestEmbeddedExternalMutationPolicy(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
t.Parallel()
bd := buildEmbeddedBD(t)
dir, _, _ := bdInit(t, bd, "--prefix", "xp")
exerciseExternalMutationPolicy(t, crossModeEnv{mode: "embedded", bd: bd, dir: dir, env: bdEnv(dir)})
}
func TestProxiedServerExternalMutationPolicy(t *testing.T) {
requireSharedProxiedServer(t)
t.Parallel()
bd := buildEmbeddedBD(t)
p := newSharedProxiedProject(t, bd, "xp")
exerciseExternalMutationPolicy(t, crossModeEnv{mode: "proxied", bd: bd, dir: p.dir, env: bdProxiedEnv(p.dir)})
}
func exerciseExternalMutationPolicy(t *testing.T, local crossModeEnv) {
t.Helper()
remoteDir, _, _ := bdInit(t, local.bd, "--prefix", "xr")
remote := crossModeEnv{mode: "foreign-embedded", bd: local.bd, dir: remoteDir, env: bdEnv(remoteDir)}
config := fmt.Sprintf("external_projects:\n remote: %q\n", remoteDir)
if err := os.WriteFile(filepath.Join(local.dir, ".beads", "config.local.yaml"), []byte(config), 0o600); err != nil {
t.Fatal(err)
}
provider := remote.create(t, "Payments provider", "--labels", "export:payments")
blocked := local.create(t, "Blocked consumer", "--priority", "0")
local.mustRun(t, "dep", "add", blocked, "external:remote:payments")
assertOpen := func(t *testing.T, id string) {
t.Helper()
got := local.show(t, id)
if got.Status != types.StatusOpen || got.Assignee != "" {
t.Fatalf("refused mutation changed %s: status=%s assignee=%q", id, got.Status, got.Assignee)
}
}
refuse := func(t *testing.T, args ...string) string {
t.Helper()
stdout, stderr, code := local.run(t, args...)
if code == 0 || !strings.Contains(stderr, "external:remote:payments") {
t.Errorf("bd %v: expected external-blocker refusal, got exit %d\n%s\n%s", args, code, stdout, stderr)
}
return stderr
}
t.Run("claim_is_atomic", func(t *testing.T) {
// --force waives only the close policy, so a claim refusal must not
// suggest it.
if stderr := refuse(t, "update", blocked, "--claim", "--notes", "must not be written"); strings.Contains(stderr, "--force") {
t.Errorf("claim refusal suggests --force, which cannot waive it:\n%s", stderr)
}
assertOpen(t, blocked)
if got := local.show(t, blocked); got.Notes != "" {
t.Fatalf("refused claim wrote notes: %q", got.Notes)
}
})
t.Run("single_close", func(t *testing.T) {
refuse(t, "close", blocked)
assertOpen(t, blocked)
})
t.Run("mixed_batch_and_claim_next", func(t *testing.T) {
finished := local.create(t, "Finished work")
next := local.create(t, "Eligible next work", "--priority", "1")
stdout, stderr, code := local.run(t, "close", blocked, finished, "--claim-next")
// Partial success reports each refused item separately on stderr and,
// since #6648, exits 1 with a count of the refusals. The eligible item
// and --claim-next still land; that is asserted below.
if code != 1 || !strings.Contains(stderr, "external:remote:payments") ||
!strings.Contains(stderr, "1 of 2 issues failed to close") {
t.Fatalf("mixed batch: exit %d\n%s\n%s", code, stdout, stderr)
}
assertOpen(t, blocked)
if got := local.show(t, finished); got.Status != types.StatusClosed {
t.Fatalf("eligible batch item was not closed: %s", got.Status)
}
if got := local.show(t, next); got.Status != types.StatusInProgress {
t.Fatalf("claim-next did not choose eligible work: %s", got.Status)
}
})
t.Run("force_only_waives_close", func(t *testing.T) {
forced := local.create(t, "Forced close")
local.mustRun(t, "dep", "add", forced, "external:remote:payments")
local.mustRun(t, "close", forced, "--force", "--claim-next")
assertOpen(t, blocked)
if got := local.show(t, forced); got.Status != types.StatusClosed {
t.Fatalf("forced close did not persist: %s", got.Status)
}
local.mustRun(t, "close", forced, "--claim-next")
assertOpen(t, blocked)
})
t.Run("shipped_allows_claim_and_close", func(t *testing.T) {
remote.mustRun(t, "close", provider)
remote.mustRun(t, "ship", "payments")
local.mustRun(t, "update", blocked, "--claim")
local.mustRun(t, "close", blocked)
if got := local.show(t, blocked); got.Status != types.StatusClosed {
t.Fatalf("shipped capability did not allow closure: %s", got.Status)
}
})
}

View file

@ -3,6 +3,7 @@
package main
import (
"errors"
"fmt"
"os"
"strings"
@ -303,6 +304,10 @@ func runFederationStatus(cmd *cobra.Command, args []string) error {
URL string
Reachable bool
ReachError string
// localCredentialErr marks a fetch that failed on this machine's
// credential key rather than on the network, so the line below does not
// blame the peer. Unexported: not part of the --json shape.
localCredentialErr bool
}
var peerStatuses []peerStatus
@ -321,6 +326,7 @@ func runFederationStatus(cmd *cobra.Command, args []string) error {
ps.Status = status
} else {
ps.ReachError = fetchErr.Error()
ps.localCredentialErr = errors.Is(fetchErr, storage.ErrCredentialKeyMismatch)
}
peerStatuses = append(peerStatuses, ps)
@ -343,9 +349,12 @@ func runFederationStatus(cmd *cobra.Command, args []string) error {
status := ps.Status
fmt.Printf(" %s %s\n", ui.RenderAccent(status.Peer), ui.RenderMuted(ps.URL))
if ps.Reachable {
switch {
case ps.Reachable:
fmt.Printf(" %s Reachable\n", ui.RenderPass("✓"))
} else {
case ps.localCredentialErr:
fmt.Printf(" %s Local credential error: %s\n", ui.RenderFail("✗"), ps.ReachError)
default:
fmt.Printf(" %s Unreachable: %s\n", ui.RenderFail("✗"), ps.ReachError)
}

View file

@ -3,10 +3,13 @@
package main
import (
"crypto/rand"
"encoding/json"
"fmt"
"io"
"os"
"os/exec"
"path/filepath"
"strings"
"sync"
"testing"
@ -42,6 +45,24 @@ func bdFederationFail(t *testing.T, bd, dir string, args ...string) string {
return string(out)
}
// assertExactJSONKeys pins a JSON object's key set: every wanted key present,
// nothing else added.
func assertExactJSONKeys(t *testing.T, what string, obj map[string]json.RawMessage, want ...string) {
t.Helper()
wanted := make(map[string]bool, len(want))
for _, key := range want {
wanted[key] = true
if _, ok := obj[key]; !ok {
t.Errorf("%s is missing key %q", what, key)
}
}
for key := range obj {
if !wanted[key] {
t.Errorf("%s gained key %q, want only %v", what, key, want)
}
}
}
func TestFormatFederationPeerListJSONPreservesLegacyKeys(t *testing.T) {
formatted := formatFederationPeerListJSON([]storage.RemoteInfo{{
Name: "town-beta",
@ -197,6 +218,58 @@ func TestEmbeddedFederation(t *testing.T) {
}
})
// Machine B: the peer row arrived with the database, the machine-local
// credential key did not. Status must point at the local key rather than
// report the peer as unreachable (GH#5085 review).
t.Run("status_credential_key_mismatch", func(t *testing.T) {
dir, beadsDir, _ := bdInit(t, bd, "--prefix", "fdkey")
bdFederation(t, bd, dir, "add-peer", "keyless", "file:///tmp/keyless",
"--user", "admin", "--password", "secret")
otherKey := make([]byte, 32)
if _, err := io.ReadFull(rand.Reader, otherKey); err != nil {
t.Fatalf("generate replacement key: %v", err)
}
if err := os.WriteFile(filepath.Join(beadsDir, ".beads-credential-key"), otherKey, 0600); err != nil {
t.Fatalf("write replacement key: %v", err)
}
out := bdFederation(t, bd, dir, "status")
if !strings.Contains(out, "Local credential error") {
t.Errorf("expected the local-credential label, got: %s", out)
}
if strings.Contains(out, "Unreachable:") {
t.Errorf("a local key failure should not be reported as unreachable, got: %s", out)
}
for _, want := range []string{".beads-credential-key", "machine-local", "bd federation add-peer"} {
if !strings.Contains(out, want) {
t.Errorf("status output does not mention %q, got: %s", want, out)
}
}
// The local-credential signal is a text-mode label carried by an
// unexported field, so --json keeps exactly the keys it had before that
// field existed. Asserted with the failing peer present, which is the
// only shape where the field is set.
jsonOut := bdFederation(t, bd, dir, "status", "--json")
var payload map[string]json.RawMessage
if err := json.Unmarshal([]byte(jsonOut), &payload); err != nil {
t.Fatalf("failed to parse status --json: %v\n%s", err, jsonOut)
}
// schema_version comes from the outputJSON envelope, not from this command.
assertExactJSONKeys(t, "status --json", payload, "peers", "pendingChanges", "schema_version")
var peers []map[string]json.RawMessage
if err := json.Unmarshal(payload["peers"], &peers); err != nil {
t.Fatalf("failed to parse status --json peers: %v\n%s", err, jsonOut)
}
if len(peers) != 1 {
t.Fatalf("status --json peers length = %d, want 1: %s", len(peers), jsonOut)
}
assertExactJSONKeys(t, "status --json peer", peers[0], "Status", "URL", "Reachable", "ReachError")
})
t.Run("status_json_no_peers", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "fdstj")

View file

@ -4,7 +4,9 @@ package main
import (
"context"
"fmt"
"io"
"os"
"slices"
"strconv"
"strings"
@ -12,8 +14,10 @@ import (
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/github"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/tracker"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/issueops"
)
// GitHubConfig holds GitHub connection configuration.
@ -456,6 +460,28 @@ func runGitHubSync(cmd *cobra.Command, args []string) error {
return HandleError("%v", err)
}
// Relationship push pass: converge beads parent/child links and "blocks"
// dependencies into GitHub sub-issues and issue dependencies. Runs after
// the content sync so relationships stay correct even when issue content
// itself was unchanged and the main push loop skipped the issue.
//
// This pass deliberately leaves github.last_sync alone. That cursor is the
// engine's record of when local rows were last reconciled, and
// DetectConflicts treats every issue updated after it as a local edit;
// advancing it here would hide edits made since the engine set it from the
// next sync's conflict detection. The engine owns the cursor
// (internal/tracker/engine.go), and this pass writes no local rows.
var linksPushed int
if push {
var linkWarnings []string
warnLink := func(msg string) {
linkWarnings = append(linkWarnings, msg)
_, _ = fmt.Fprintf(os.Stderr, "Warning: %s\n", msg)
}
linksPushed = pushGitHubDependencyLinks(ctx, gt, store, opts, githubSyncDryRun, out, warnLink)
result.Warnings = append(result.Warnings, linkWarnings...)
}
// Output results
if !githubSyncDryRun {
if result.Stats.Pulled > 0 {
@ -465,6 +491,9 @@ func runGitHubSync(cmd *cobra.Command, args []string) error {
if result.Stats.Pushed > 0 {
_, _ = fmt.Fprintf(out, "✓ Pushed %d issues\n", result.Stats.Pushed)
}
if linksPushed > 0 {
_, _ = fmt.Fprintf(out, "✓ Synced %d relationship links\n", linksPushed)
}
if result.Stats.Conflicts > 0 {
_, _ = fmt.Fprintf(out, "→ Resolved %d conflicts\n", result.Stats.Conflicts)
}
@ -478,6 +507,221 @@ func runGitHubSync(cmd *cobra.Command, args []string) error {
return nil
}
// githubLinkSyncData holds the desired GitHub relationship links collected
// from beads dependency state for the issues in scope of a sync/push pass.
type githubLinkSyncData struct {
DesiredLinks []github.DependencyLink
}
// collectGitHubLinkSyncData walks the beads issues in scope of opts and
// derives the GitHub relationship links (sub-issue for epic/child,
// blocked_by for beads "blocks" dependencies) that should exist remotely.
// Only issues already linked to GitHub (an ExternalRef that scope resolves to
// an issue number in the configured repository) can contribute or receive a
// link; refs pointing at another repository or host are skipped, since the
// relationship endpoints take bare issue numbers scoped to one repo.
//
// The workspace read is issueops.Reader's, reached through the store's own
// accessor so it carries whatever layers that store carries; the request it
// takes is githubLinkSyncListRequest below.
func collectGitHubLinkSyncData(ctx context.Context, st storage.Storage, scope github.RefScope, opts tracker.SyncOptions) (githubLinkSyncData, []string) {
if st == nil {
return githubLinkSyncData{}, []string{"GitHub relationship sync skipped: database not available"}
}
reader, err := st.IssueReader()
if err != nil {
return githubLinkSyncData{}, []string{fmt.Sprintf("GitHub relationship sync skipped: %v", err)}
}
page, err := reader.List(ctx, githubLinkSyncListRequest())
if err != nil {
return githubLinkSyncData{}, []string{fmt.Sprintf("GitHub relationship sync skipped: %v", err)}
}
allIssues := make([]*types.Issue, 0, len(page.Items))
for _, item := range page.Items {
if item == nil || item.Issue == nil {
continue
}
allIssues = append(allIssues, item.Issue)
}
// --parent scopes the content push to a subtree; the relationship pass has
// to honor the same subtree or it writes GitHub links for issues the user
// excluded from the sync.
var descendantSet map[string]bool
if opts.ParentID != "" {
descendantSet, err = buildSyncDescendantSet(ctx, st, opts.ParentID)
if err != nil {
return githubLinkSyncData{}, []string{fmt.Sprintf("GitHub relationship sync skipped: resolving parent %s: %v", opts.ParentID, err)}
}
}
scopedIssues := filterGitHubLinkScopedIssues(allIssues, opts, descendantSet)
scopedIssueIDs := make(map[string]bool, len(scopedIssues))
for _, issue := range scopedIssues {
if issue != nil && issue.ID != "" {
scopedIssueIDs[issue.ID] = true
}
}
var warnings []string
var desired []github.DependencyLink
for _, issue := range scopedIssues {
if issue.ExternalRef == nil {
continue
}
deps, err := st.GetDependenciesWithMetadata(ctx, issue.ID)
if err != nil {
warnings = append(warnings, fmt.Sprintf("GitHub relationship sync skipped dependencies for %s: %v", issue.ID, err))
continue
}
for _, dep := range deps {
if !scopedIssueIDs[dep.ID] {
continue
}
switch dep.DependencyType {
case types.DepParentChild:
if link, ok := scope.SubIssueLinkFromParentChild(issue, dep); ok {
desired = append(desired, link)
}
case types.DepBlocks:
if link, ok := scope.BlockedByLinkFromBeadsDependency(issue, dep); ok {
desired = append(desired, link)
}
}
}
}
return githubLinkSyncData{DesiredLinks: desired}, warnings
}
// githubLinkSyncListRequest is the whole-workspace read the relationship pass
// runs: every bead in both planes, at any status, of any type, unpaged.
//
// SCOPE IS NOT THIS REQUEST'S JOB. filterGitHubLinkScopedIssues narrows to the
// tracker.SyncOptions selectors the GitHub commands can set — that function
// names them and is the place to extend — the way the engine's push loop
// narrows the same unfiltered read with shouldPushIssue
// (internal/tracker/engine.go). Expressing half that selection here in a second
// vocabulary is how the two would drift, so this lifts every default a listing
// applies rather than reproducing the engine's choices:
//
// AllFlag drops the default status exclusions, and with them the
// pinned predicate. A relationship is still true for a closed
// bead, and the engine pushes closed issues too.
// IncludeAllTypes drops the template, gate and infra type exclusions AND the
// plane decision, so the wisps table is read. opts.
// ExcludeEphemeral is what drops that plane, downstream, when
// the caller asked for it.
// Limit zero, not nil: nil takes the shared list default, which
// would silently cap relationship sync at one page.
//
// SkipLabels and SkipCounts choose what is HYDRATED, never which rows match.
// This pass reads ID, ExternalRef, IssueType and Ephemeral and nothing else,
// and the counts are per-row aggregate joins the scan has no use for.
func githubLinkSyncListRequest() issueops.ListRequest {
unlimited := 0
return issueops.ListRequest{
AllFlag: true,
IncludeAllTypes: true,
Limit: &unlimited,
SkipLabels: true,
SkipCounts: true,
}
}
// filterGitHubLinkScopedIssues narrows the unfiltered workspace read to the
// issues opts selects. descendantSet is the resolved --parent subtree, or nil
// when --parent was not given; a non-nil set is a membership requirement.
//
// The selectors applied here are the ones a GitHub command can put on
// SyncOptions today: ParentID (as descendantSet), IssueIDs, ExcludeEphemeral,
// TypeFilter and ExcludeTypes. SyncOptions carries further selectors that the
// engine's push loop honors and no GitHub command currently sets — State,
// ExcludeIDPrefix, ExcludeIDPatterns. Anything that starts setting one of
// those has to extend this function in the same change, or the relationship
// pass will write links for issues the content push skipped.
func filterGitHubLinkScopedIssues(issues []*types.Issue, opts tracker.SyncOptions, descendantSet map[string]bool) []*types.Issue {
var issueIDSet map[string]bool
if len(opts.IssueIDs) > 0 {
issueIDSet = make(map[string]bool, len(opts.IssueIDs))
for _, id := range opts.IssueIDs {
issueIDSet[id] = true
}
}
result := make([]*types.Issue, 0, len(issues))
for _, issue := range issues {
if issue == nil {
continue
}
if issueIDSet != nil && !issueIDSet[issue.ID] {
continue
}
if descendantSet != nil && !descendantSet[issue.ID] {
continue
}
if opts.ExcludeEphemeral && issue.Ephemeral {
continue
}
if len(opts.TypeFilter) > 0 && !slices.Contains(opts.TypeFilter, issue.IssueType) {
continue
}
if slices.Contains(opts.ExcludeTypes, issue.IssueType) {
continue
}
result = append(result, issue)
}
return result
}
// pushGitHubDependencyLinks runs the relationship push pass: it converts
// beads epic/child links and "blocks" dependencies among the scoped issues
// (per opts) into GitHub sub-issues and issue dependencies. Additive — stale
// remote relationships are left untouched. Shared by `bd github sync` and
// `bd github push` so both reach the same relationship parity. Dry-run plan
// lines are written to out (unless --json); warnings are delivered via warn.
// Returns the number of relationships created.
func pushGitHubDependencyLinks(ctx context.Context, gt *github.Tracker, st storage.Storage, opts tracker.SyncOptions, dryRun bool, out io.Writer, warn func(string)) int {
if gt == nil {
return 0
}
linkData, collectWarnings := collectGitHubLinkSyncData(ctx, st, gt.RefScope(), opts)
for _, warning := range collectWarnings {
warn(warning)
}
resolver := gt.LinkResolver()
if resolver == nil || len(linkData.DesiredLinks) == 0 {
return 0
}
res := resolver.PushLinks(ctx, linkData.DesiredLinks, github.PushLinkOptions{
DryRun: dryRun,
OnPlan: func(link github.DependencyLink) {
if !jsonOutput {
_, _ = fmt.Fprintf(out, " [dry-run] Would create GitHub %s relationship: #%d -> #%d\n",
link.LinkType, link.FromNumber, link.ToNumber)
}
},
})
for _, err := range res.Errors {
warn(fmt.Sprintf("GitHub relationship sync: %v", err))
}
// Both counters are a silent no-op otherwise: PushLinks deliberately does
// not raise a 404 per link, so this is the only place the user learns the
// relationships were not written. One line per class, never merged — an
// unavailable endpoint is a host capability the operator cannot fix per
// issue, a missing source issue is a stale local ref they can.
if res.UnsupportedSkipped > 0 {
warn(fmt.Sprintf("GitHub relationship sync: %d link(s) skipped; the sub-issue/dependency API is unavailable on this host", res.UnsupportedSkipped))
}
if res.SourceMissing > 0 {
warn(fmt.Sprintf("GitHub relationship sync: %d link(s) skipped; the source issue is not readable on GitHub (deleted, renumbered, or not visible to this token)", res.SourceMissing))
}
return res.Created
}
// buildGitHubPushHooks creates PushHooks for GitHub-specific push behavior.
// The ContentEqual hook lets the engine skip issues whose pushable fields
// already match GitHub, so repeated `github sync --push-only` / `github push`

View file

@ -0,0 +1,155 @@
package main
import (
"context"
"slices"
"testing"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/tracker"
"github.com/steveyegge/beads/internal/types"
)
// descendantFakeStore answers GetDependentsWithMetadata from an in-memory
// parent -> children map. Every other storage.Storage method is promoted from
// the nil embedded interface, so a reach for one panics rather than silently
// widening what this test covers.
type descendantFakeStore struct {
storage.Storage
children map[string][]string
// related are non-parent-child dependents, returned alongside the real
// children so the traversal's edge-type filter is exercised.
related map[string][]string
}
func (s *descendantFakeStore) GetDependentsWithMetadata(_ context.Context, issueID string) ([]*types.IssueWithDependencyMetadata, error) {
var out []*types.IssueWithDependencyMetadata
for _, childID := range s.children[issueID] {
out = append(out, &types.IssueWithDependencyMetadata{
Issue: types.Issue{ID: childID},
DependencyType: types.DepParentChild,
})
}
for _, otherID := range s.related[issueID] {
out = append(out, &types.IssueWithDependencyMetadata{
Issue: types.Issue{ID: otherID},
DependencyType: types.DepBlocks,
})
}
return out, nil
}
// TestFilterGitHubLinkScopedIssues pins one row per tracker.SyncOptions
// selector the GitHub commands can set. The --parent row is the one that
// matters most: before the relationship pass honoured opts.ParentID it kept
// every issue in the workspace, so `bd github sync --push --parent X` created
// GitHub links on issues the content push had excluded.
func TestFilterGitHubLinkScopedIssues(t *testing.T) {
issues := []*types.Issue{
{ID: "bd-epic", IssueType: types.TypeEpic},
{ID: "bd-child", IssueType: types.TypeTask},
{ID: "bd-grandchild", IssueType: types.TypeBug},
{ID: "bd-outside", IssueType: types.TypeTask},
{ID: "bd-wisp", IssueType: types.TypeTask, Ephemeral: true},
}
store := &descendantFakeStore{
children: map[string][]string{
"bd-epic": {"bd-child"},
"bd-child": {"bd-grandchild"},
},
// bd-outside blocks bd-epic: a dependent, but not a descendant.
related: map[string][]string{"bd-epic": {"bd-outside"}},
}
tests := []struct {
name string
opts tracker.SyncOptions
want []string
}{
{
name: "no selectors keeps everything",
opts: tracker.SyncOptions{},
want: []string{"bd-epic", "bd-child", "bd-grandchild", "bd-outside", "bd-wisp"},
},
{
name: "IssueIDs keeps only the listed beads",
opts: tracker.SyncOptions{IssueIDs: []string{"bd-child", "bd-wisp"}},
want: []string{"bd-child", "bd-wisp"},
},
{
name: "ParentID keeps the subtree and drops the rest",
opts: tracker.SyncOptions{ParentID: "bd-epic"},
want: []string{"bd-epic", "bd-child", "bd-grandchild"},
},
{
name: "ParentID on a leaf keeps only that leaf",
opts: tracker.SyncOptions{ParentID: "bd-grandchild"},
want: []string{"bd-grandchild"},
},
{
name: "TypeFilter keeps only the named types",
opts: tracker.SyncOptions{TypeFilter: []types.IssueType{types.TypeEpic, types.TypeBug}},
want: []string{"bd-epic", "bd-grandchild"},
},
{
name: "ExcludeTypes drops the named types",
opts: tracker.SyncOptions{ExcludeTypes: []types.IssueType{types.TypeTask}},
want: []string{"bd-epic", "bd-grandchild"},
},
{
name: "ExcludeEphemeral drops wisps",
opts: tracker.SyncOptions{ExcludeEphemeral: true},
want: []string{"bd-epic", "bd-child", "bd-grandchild", "bd-outside"},
},
{
name: "ParentID composes with the other selectors",
opts: tracker.SyncOptions{ParentID: "bd-epic", ExcludeTypes: []types.IssueType{types.TypeBug}},
want: []string{"bd-epic", "bd-child"},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
// Resolve the subtree exactly the way collectGitHubLinkSyncData
// does, so the helper is under test too.
var descendantSet map[string]bool
if tt.opts.ParentID != "" {
var err error
descendantSet, err = buildSyncDescendantSet(context.Background(), store, tt.opts.ParentID)
if err != nil {
t.Fatalf("buildSyncDescendantSet(%q) error = %v", tt.opts.ParentID, err)
}
}
got := filterGitHubLinkScopedIssues(issues, tt.opts, descendantSet)
ids := make([]string, 0, len(got))
for _, issue := range got {
ids = append(ids, issue.ID)
}
if !slices.Equal(ids, tt.want) {
t.Errorf("filterGitHubLinkScopedIssues() = %v, want %v", ids, tt.want)
}
})
}
}
// TestBuildSyncDescendantSetIgnoresNonParentChildEdges pins the traversal's
// edge-type filter directly: a blocks dependent is not a descendant, so
// --parent must not drag it into scope.
func TestBuildSyncDescendantSetIgnoresNonParentChildEdges(t *testing.T) {
store := &descendantFakeStore{
children: map[string][]string{"bd-epic": {"bd-child"}},
related: map[string][]string{"bd-epic": {"bd-blocker"}},
}
got, err := buildSyncDescendantSet(context.Background(), store, "bd-epic")
if err != nil {
t.Fatalf("buildSyncDescendantSet error = %v", err)
}
if !got["bd-epic"] || !got["bd-child"] {
t.Errorf("descendant set = %v, want it to contain bd-epic and bd-child", got)
}
if got["bd-blocker"] {
t.Errorf("descendant set = %v, want it to exclude the blocks-edge dependent bd-blocker", got)
}
}

View file

@ -720,7 +720,7 @@ func collectGitLabLinkSyncData(ctx context.Context, st storage.Storage, opts tra
var warnings []string
var descendantSet map[string]bool
if opts.ParentID != "" {
descendantSet, err = buildGitLabDescendantSet(ctx, st, opts.ParentID)
descendantSet, err = buildSyncDescendantSet(ctx, st, opts.ParentID)
if err != nil {
return gitlabLinkSyncData{}, []string{fmt.Sprintf("GitLab dependency link sync skipped: resolving parent %s: %v", opts.ParentID, err)}
}
@ -803,26 +803,6 @@ func gitlabIssueAllowedByPushFilters(issue *types.Issue, opts tracker.SyncOption
return true
}
func buildGitLabDescendantSet(ctx context.Context, st storage.Storage, parentID string) (map[string]bool, error) {
result := map[string]bool{parentID: true}
queue := []string{parentID}
for len(queue) > 0 {
current := queue[0]
queue = queue[1:]
dependents, err := st.GetDependentsWithMetadata(ctx, current)
if err != nil {
return nil, fmt.Errorf("getting dependents of %s: %w", current, err)
}
for _, dep := range dependents {
if dep.DependencyType == types.DepParentChild && !result[dep.Issue.ID] {
result[dep.Issue.ID] = true
queue = append(queue, dep.Issue.ID)
}
}
}
return result, nil
}
func gitlabIssueIDSet(ids []string) map[string]bool {
if len(ids) == 0 {
return nil

View file

@ -373,6 +373,15 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
reinitLocal, _ := cmd.Flags().GetBool("reinit-local")
initIfMissing, _ := cmd.Flags().GetBool("init-if-missing")
discardRemote, _ := cmd.Flags().GetBool("discard-remote")
recreateMissing, _ := cmd.Flags().GetBool("recreate-missing")
// Assigned here, beside the flag read, and deliberately NOT beside the
// guard it gates: runInit dispatches to runInitProxiedServer and
// returns well before that point, while runInitProxiedServer calls
// checkExistingBeadsData, which reads this global. Assigning it later
// left --recreate-missing inert on the --proxied-server route, so the
// refusal told the operator to pass the flag they had just passed. Keep
// every route that can reach the guard downstream of this line.
initAllowRecreateMissing = recreateMissing
nonInteractiveFlag, _ := cmd.Flags().GetBool("non-interactive")
roleFlag, _ := cmd.Flags().GetString("role")
fromJSONL, _ := cmd.Flags().GetBool("from-jsonl")
@ -799,6 +808,19 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
// authorize cross-boundary operations on remote history (see
// CheckRemoteSafety at cmd/bd/init_safety.go and
// engdocs/adr/0002-init-safety-invariants.md).
if reinitLocal {
// be-5up5 round 2 (review of PR #5791): --reinit-local/--force skip
// checkExistingBeadsData entirely, and the typed confirmation below
// keys on countExistingIssues, which returns 0/err in exactly the
// missing-database case — so `bd init --force` against a lost
// server-side database used to create a fresh empty one with no
// prompt and no destroy token. Those flags authorize destroying a
// database that exists; only --recreate-missing authorizes creating
// one where the configured database has gone missing.
if err := guardMissingServerDatabase(prefix); err != nil {
return fmt.Errorf("%v", err)
}
}
if !reinitLocal {
if err := checkExistingBeadsData(prefix); err != nil {
// --init-if-missing makes init idempotent, but ONLY for the
@ -2239,6 +2261,7 @@ func init() {
initCmd.Flags().Bool("force", false, "Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence (see 'bd help init-safety').")
initCmd.Flags().Bool("reinit-local", false, "Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence; see --discard-remote.")
initCmd.Flags().Bool("discard-remote", false, "Authorize discarding the configured remote's Dolt history when re-initializing. Requires --destroy-token in non-interactive mode; see 'bd help init-safety'.")
initCmd.Flags().Bool("recreate-missing", false, "Explicitly authorize creating a fresh, empty database when this project's configured server-mode database is missing or unreachable. Opt-in per invocation only; never implied by --force, config, or env (see 'bd help init-safety').")
initCmd.Flags().Bool("from-jsonl", false, "Import issues from configured import.path; refuses remote history unless --discard-remote authorizes replacement")
initCmd.Flags().Bool("init-if-missing", false, "If the workspace is already initialized, skip init and exit 0 instead of failing (idempotent init for scaffolds)")
initCmd.Flags().String("destroy-token", "", "Explicit confirmation token for destructive re-init in non-interactive mode (format: 'DESTROY-<prefix>')")
@ -2477,40 +2500,131 @@ Aborting.`, ui.RenderWarn("⚠"), location, ui.RenderAccent("bd list"), prefix)
return nil
}
// Check both the local directory AND server mode config.
// In server mode the local dolt/ directory may be empty — the database
// lives on the Dolt sql-server. Checking only the directory would miss
// server-mode installations.
// Check both the local database AND server mode config.
// In server mode the local dolt/ directory may hold no database for
// this project — the data lives on the Dolt sql-server. Checking only
// the directory would miss server-mode installations.
doltPath := doltserver.ResolveDoltDir(beadsDir)
dbName := cfg.GetDoltDatabase()
// Probe THIS PROJECT's database directory, not the Dolt data directory
// that merely holds it: a data dir contains one subdirectory per
// database, each with its own .dolt.
//
// Statting the data dir instead made the FR-010 branch below
// unreachable on every initialized workspace, because the data dir
// always exists there — shared-server mode MkdirAlls the
// machine-global one in SharedDoltDir(), per-project mode MkdirAlls it
// in ensureDoltInit. So the branch never ran, and both
// --recreate-missing opt-ins inside it were dead code: the escape
// hatch named by the flag help, `bd help init-safety`,
// docs/recovery/init-safety.md and the guard's own refusal text all
// pointed at a command that could not reach its own opt-in, leaving
// the operator circling between two refusals. Same probe, and the same
// reason, as guardMissingServerDatabaseAt. Pinned by
// TestInitGuard_ExistingProjectMissingServerDB_DataDirPresent_Refuses
// and TestInitGuard_RecreateMissing_ReachesOptIn_DataDirPresent.
//
// The data-dir stat does not go away, it stops being the gate: making
// the branch reachable also exposes states it used to shadow, and
// permitting those would be a new fail-open policy rather than a fix.
// The permit condition below keeps it to what the old probe already
// allowed, plus the explicit opt-in. Pinned by
// TestInitGuard_NoProjectID_DataDirPresent_StillBlocks.
localDatabaseExists := false
if info, err := os.Stat(filepath.Join(doltPath, dbName, ".dolt")); err == nil && info.IsDir() {
localDatabaseExists = true
}
// The data directory is still read, but only to keep this fix from
// widening what fails OPEN. See the permit condition below.
doltDirExists := false
if info, err := os.Stat(doltPath); err == nil && info.IsDir() {
doltDirExists = true
}
if doltDirExists || cfg.IsDoltServerMode() {
if localDatabaseExists || cfg.IsDoltServerMode() {
// For server mode, distinguish "DB exists" from "DB missing" (FR-010).
if cfg.IsDoltServerMode() && !doltDirExists {
if cfg.IsDoltServerMode() && !localDatabaseExists {
host := cfg.GetDoltServerHost()
port := doltserver.DefaultConfig(beadsDir).Port
dbName := cfg.GetDoltDatabase()
password := cfg.GetDoltServerPassword()
user := cfg.GetDoltServerUser()
// localDatabaseExists==false is ambiguous in server mode: it's the
// normal state both for a genuine fresh clone (GH#2433) and for an
// existing project whose server-side database was lost or is
// unreachable (be-5up5: 2026-08-11 fleet-wide data loss). project_id
// is written by a real prior `bd init`, so a non-empty value here is
// taken as the latter — recovery, not a fresh clone.
//
// Known limit: project_id was minted by GH#2372, so a workspace
// initialized before that carries none and is indistinguishable
// here from a fresh clone. Such workspaces FAIL OPEN — init will
// still create the database. Accepted deliberately: failing closed
// would block legitimate first inits on every pre-GH#2372 clone,
// and this guard's job is to stop a silent recreate where we can
// PROVE prior initialization, not to guess where we cannot.
//
// SETTLED by ADR-0004 (engdocs/adr/0004-missing-database-guard-signal.md).
// project_id is a weak proof of prior LOCAL init: .beads/metadata.json
// is git-tracked by default (see GitignoreTemplate in
// cmd/bd/doctor/gitignore.go, which says so in as many words), so a
// fresh clone inherits one and is refused here with a recovery
// message. That is ACCEPTED, not a gap awaiting a fix: absence of
// local state cannot distinguish "never initialized here" from
// "initialized here, storage since lost", and the second is the
// shape of the 2026-08-11 loss. The failure direction is the safe
// one — it never recreates a database silently — and
// --recreate-missing is the permanent, documented resolution path,
// reachable since the probe fix above. Read the ADR before
// reopening this; the data-directory and local-marker alternatives
// are recorded there as rejected, with reasons.
existingProject := cfg.ProjectID != ""
result := checkDatabaseOnServer(host, port, user, password, dbName, cfg.GetDoltServerTLS())
if result.Reachable && !result.Exists && result.Err == nil {
// Server is up but DB doesn't exist. Since we also know
// doltDirExists==false, this is a fresh clone — there's no
// local database to protect. Allow init to proceed so the
// user can bootstrap (e.g. via --from-jsonl). (GH#2433)
return nil
// Server is up but DB doesn't exist.
if existingProject && !initAllowRecreateMissing {
return initGuardMissingServerDBMessage(dbName, host, port, prefix, true)
}
// Fresh clone (GH#2433) or explicit --recreate-missing opt-in —
// there's no local database to protect. Allow init to proceed so
// the user can bootstrap (e.g. via --from-jsonl).
if initAllowRecreateMissing || !doltDirExists {
return nil
}
// Reached only with no project_id AND a local Dolt data
// directory present. The old data-dir probe blocked this
// state by never arriving here at all; it keeps being
// blocked, by the same message as before. Permitting it
// would be a new fail-open policy on workspaces that
// predate project_id (GH#2372) — exactly the population
// this guard exists for — and choosing the replacement
// signal is be-5pjhd's call, not this fix's.
}
if result.Reachable && result.Exists {
// Server up and DB exists — fall through to "already initialized" error.
} else {
// Server unreachable or error during check: this is a fresh clone
// with committed metadata.json but no local dolt/ directory.
// Allow init to proceed so the user can bootstrap the database
// (e.g. via --from-jsonl). (GH#2433)
return nil
// Either the server was unreachable or errored during the
// check, OR the block above adjudicated a reachable server
// that positively confirmed the database is gone and fell
// through without returning (no project_id, local Dolt data
// directory present). Do not give this branch
// unreachability-specific text, telemetry or error wrapping
// without first re-reading that fall-through: on that path
// the server answered authoritatively, and the two guards
// below are correct for both cases only because their
// conditions do not mention reachability.
if existingProject && !initAllowRecreateMissing {
return initGuardMissingServerDBMessage(dbName, host, port, prefix, true)
}
// Fresh clone with committed metadata.json but no local dolt/
// directory, or explicit --recreate-missing opt-in — allow init
// to proceed so the user can bootstrap the database (e.g. via
// --from-jsonl). Same narrowing as the reachable-server branch
// above, for the same reason.
if initAllowRecreateMissing || !doltDirExists {
return nil
}
}
}
@ -2870,6 +2984,128 @@ func initModeExplicitlyRequested(cmd *cobra.Command) bool {
return config.GetYamlConfig("dolt.mode") != ""
}
// guardMissingServerDatabaseAt is the be-5up5 refusal, narrowed to the single
// question --reinit-local/--force must NOT be able to answer for you: is this
// an already-initialized server-mode project whose configured database is
// missing or unconfirmable?
//
// It exists because those flags bypass checkExistingBeadsData entirely (see the
// !reinitLocal gate in the init command), and the reinit path's own typed
// confirmation keys on countExistingIssues — which returns 0 or an error in
// exactly the case this guard is about, so no prompt fires either. That left
// `bd init --force` against a lost database creating a fresh empty one with no
// prompt and no destroy token: the precise reflex of the 2026-08-11 fleet-wide
// data loss, reached by the flag a panicking operator is most likely to try.
//
// --reinit-local/--force authorize destroying a database that EXISTS. They do
// not authorize inventing an empty one where the configured database has gone
// missing. Only the explicit, per-invocation --recreate-missing does that,
// which is what keeps that flag's "never implied by --force" help text true.
//
// Deliberately narrow: it answers only the missing-database question and
// returns nil for every other state, so it never resurrects the
// "already initialized" refusal that --reinit-local is legitimately meant to
// bypass.
func guardMissingServerDatabaseAt(beadsDir string, prefix string) error {
if initAllowRecreateMissing {
return nil
}
if beadsDir == "" {
return nil
}
if _, err := os.Stat(beadsDir); os.IsNotExist(err) {
return nil
}
cfg, cfgErr := configfile.LoadForDiscovery(beadsDir)
if cfgErr != nil || cfg == nil {
// Unreadable or absent metadata is the caller's problem, not this
// guard's: without it we cannot prove the workspace was ever
// initialized, and this guard only ever fires on proof that it was.
return nil
}
if cfg.GetBackend() != configfile.BackendDolt || !cfg.IsDoltServerMode() {
return nil
}
host := cfg.GetDoltServerHost()
port := doltserver.DefaultConfig(beadsDir).Port
dbName := cfg.GetDoltDatabase()
doltPath := doltserver.ResolveDoltDir(beadsDir)
// TIER 1 (ADR-0004, engdocs/adr/0004-missing-database-guard-signal.md).
// Local data means data belonging to THIS project, which is what
// --reinit-local exists to override. Test for this project's own database
// directory, not the data directory that merely holds it: a Dolt data dir
// contains one subdirectory per database, each with its own .dolt.
//
// Statting the data dir itself made this guard a no-op in shared-server
// mode, where ResolveDoltDir returns the machine-global
// ~/.beads/shared-server/dolt and SharedDoltDir() MkdirAlls it — so the
// stat always succeeded and checkDatabaseOnServer below was never reached.
// Shared-server is the topology of the 2026-08-11 data loss, so that was
// the primary case going unguarded. Pinned by
// TestInitGuard_SharedServerMode_MissingServerDB_Refuses.
//
// This probe runs BEFORE the project_id check below, and unconditionally.
// It used to run after an early `return nil` on empty project_id, which
// made this guard — the safety net for --reinit-local/--force — weaker
// than the plain-`bd init` guard it backstops: a pre-GH#2372 workspace
// (no project_id) whose local database was lost was protected under
// `bd init` and waved straight through under --force.
if info, err := os.Stat(filepath.Join(doltPath, dbName, ".dolt")); err == nil && info.IsDir() {
return nil
}
// TIER 2 (ADR-0004). No local database for this project. project_id is
// written by a real prior `bd init`, so a non-empty value is what
// separates recovery from a genuine fresh clone. It is imperfect —
// .beads/metadata.json is git-tracked by default, so a clone inherits one
// it never earned — and that is accepted deliberately: absence of local
// state cannot distinguish "never initialized here" from "initialized
// here, storage since lost", and the second is the 2026-08-11 shape.
// --recreate-missing is the resolution path for both, and it returned nil
// at the top of this function.
if cfg.ProjectID == "" {
// Same coarse-directory permit condition checkExistingBeadsDataAt
// applies, so the two guards agree: allow only when NOTHING local
// exists. A data dir with no database in it still says this
// workspace touched local Dolt storage.
//
// Accepted asymmetry (ADR-0004): in owned mode doltPath is
// per-project and this is a meaningful second signal. In
// same-machine shared-server mode it is the machine-global
// ~/.beads/shared-server/dolt, true once ANY project has used the
// shared server, so this cell is more conservative there. That fails
// toward refuse, is resolved the same documented way, and affects a
// population that only shrinks — every successful init mints a
// project_id. Do not re-litigate it without reading the ADR.
if info, err := os.Stat(doltPath); err != nil || !info.IsDir() {
return nil
}
}
result := checkDatabaseOnServer(host, port, cfg.GetDoltServerUser(), cfg.GetDoltServerPassword(), dbName, cfg.GetDoltServerTLS())
if result.Reachable && result.Exists && result.Err == nil {
// The database is there. Whatever happens next is the ordinary
// reinit path's business, not this guard's.
return nil
}
// Unlike the plain-init guard, this one is reachable with an empty
// project_id — the pre-GH#2372 cell permitted just above only when nothing
// local exists. Tell the message which evidence it actually has.
return initGuardMissingServerDBMessage(dbName, host, port, prefix, cfg.ProjectID != "")
}
// guardMissingServerDatabase resolves the init target the same way
// checkExistingBeadsData does, then applies guardMissingServerDatabaseAt.
func guardMissingServerDatabase(prefix string) error {
beadsDir := resolveInitBeadsDir()
if beadsDir == "" {
return nil
}
return guardMissingServerDatabaseAt(beadsDir, prefix)
}
func checkExistingBeadsData(prefix string) error {
beadsDir := resolveInitBeadsDir()
if beadsDir == "" {

View file

@ -3,6 +3,12 @@ package main
import (
"context"
"errors"
"fmt"
"io"
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"testing"
@ -10,6 +16,243 @@ import (
"github.com/steveyegge/beads/issueops"
)
const (
initGatewayHelperProcessEnv = "BEADS_TEST_INTERNAL_INIT_GATEWAY_HELPER"
initGatewayHelperExecutableEnv = "BEADS_TEST_INTERNAL_INIT_GATEWAY_HELPER_EXE"
initGatewayHelperMarkerEnv = "BEADS_TEST_INTERNAL_INIT_GATEWAY_MARKER"
initGatewayHelperTargetEnv = "BEADS_TEST_INTERNAL_INIT_GATEWAY_HELPER_TARGET"
initGatewayHelperMalformedExit = 97
)
// runInitGatewayCredentialHelper dispatches an opt-in subprocess before the
// package's ordinary TestMain setup. This keeps credential fixture processes
// from starting Dolt, changing HOME, or allocating the cmd/bd suite's shared
// resources. The -- separator prevents the test harness from interpreting the
// helper protocol as test flags.
func runInitGatewayCredentialHelper() (int, bool) {
if os.Getenv(initGatewayHelperProcessEnv) != "1" {
return 0, false
}
separator := -1
for i, arg := range os.Args {
if arg == "--" {
separator = i
break
}
}
if separator < 0 {
fmt.Fprintln(os.Stderr, "init gateway credential helper: missing -- separator")
return initGatewayHelperMalformedExit, true
}
args := os.Args[separator+1:]
switch {
case len(args) == 2 && args[0] == "emit":
_, _ = io.WriteString(os.Stdout, args[1])
return 0, true
case len(args) == 2 && args[0] == "exit" && args[1] == "23":
return 23, true
case len(args) == 1 && args[0] == "marker":
marker := os.Getenv(initGatewayHelperMarkerEnv)
if marker == "" {
fmt.Fprintln(os.Stderr, "init gateway credential helper: marker path is empty")
return initGatewayHelperMalformedExit, true
}
if err := os.WriteFile(marker, []byte("invoked"), 0o600); err != nil {
fmt.Fprintf(os.Stderr, "init gateway credential helper: write marker: %v\n", err)
return initGatewayHelperMalformedExit, true
}
return 0, true
default:
fmt.Fprintf(os.Stderr, "init gateway credential helper: malformed arguments: %q\n", args)
return initGatewayHelperMalformedExit, true
}
}
func initGatewayCredentialCommand(t *testing.T, args ...string) string {
t.Helper()
shell := "sh"
if runtime.GOOS == "windows" {
shell = "cmd.exe"
}
shellPath, err := exec.LookPath(shell)
if err != nil {
t.Fatalf("resolve production credential shell %q: %v", shell, err)
}
shellPath, err = filepath.Abs(shellPath)
if err != nil {
t.Fatalf("resolve absolute credential shell path: %v", err)
}
shellDir := filepath.Dir(shellPath)
isolatedShellPath := shellPath
if runtime.GOOS != "windows" {
shellDir = filepath.Join(t.TempDir(), "credential shell only")
if err := os.MkdirAll(shellDir, 0o755); err != nil {
t.Fatalf("create isolated credential shell directory: %v", err)
}
isolatedShellPath = filepath.Join(shellDir, shell)
// Execute the original system shell: macOS AMFI may kill a copied sh.
// An absolute symlink keeps it usable from the restricted PATH.
if err := os.Symlink(shellPath, isolatedShellPath); err != nil {
t.Fatalf("link original credential shell: %v", err)
}
}
helperDir := filepath.Join(t.TempDir(), "credential helper with spaces")
if err := os.MkdirAll(helperDir, 0o755); err != nil {
t.Fatalf("create credential helper directory: %v", err)
}
helperName := "credential-helper"
if runtime.GOOS == "windows" {
helperName += ".cmd"
}
helperPath := filepath.Join(helperDir, helperName)
currentExecutable, err := os.Executable()
if err != nil {
t.Fatalf("resolve current test executable: %v", err)
}
if runtime.GOOS == "windows" {
trampoline := "@echo off\r\n\"%" + initGatewayHelperTargetEnv + "%\" %*\r\nexit /b %errorlevel%\r\n"
if err := os.WriteFile(helperPath, []byte(trampoline), 0o600); err != nil {
t.Fatalf("write credential helper trampoline: %v", err)
}
t.Setenv(initGatewayHelperTargetEnv, currentExecutable)
} else {
installInitGatewayExecutable(t, currentExecutable, helperPath)
}
if !strings.Contains(helperPath, " ") {
t.Fatalf("credential helper path does not exercise quoting: %q", helperPath)
}
// Keep only the shell that production requires. Unix links the original
// sh. Windows keeps the resolved system cmd.exe in place to avoid a
// suspicious copied-system-binary/copied-PE process chain.
t.Setenv("PATH", shellDir)
resolvedShell, err := exec.LookPath(shell)
if err != nil {
t.Fatalf("resolve credential shell from isolated PATH: %v", err)
}
if runtime.GOOS == "windows" {
resolvedInfo, err := os.Stat(resolvedShell)
if err != nil {
t.Fatalf("stat resolved credential shell: %v", err)
}
wantInfo, err := os.Stat(shellPath)
if err != nil {
t.Fatalf("stat production credential shell: %v", err)
}
if !os.SameFile(resolvedInfo, wantInfo) {
t.Fatalf("credential shell resolved outside restricted PATH: got %q, want %q", resolvedShell, shellPath)
}
for _, forbidden := range []string{"printf", "false"} {
if path, err := exec.LookPath(forbidden); err == nil {
t.Fatalf("ambient fixture utility %q remains available at %q", forbidden, path)
}
}
} else if filepath.Clean(resolvedShell) != filepath.Clean(isolatedShellPath) {
t.Fatalf("credential shell resolved outside isolated PATH: got %q, want %q", resolvedShell, isolatedShellPath)
}
t.Setenv(initGatewayHelperProcessEnv, "1")
executable := `"$` + initGatewayHelperExecutableEnv + `"`
if runtime.GOOS == "windows" {
// Let cmd.exe expand the quotes as part of the variable value. Passing
// literal quotes inside exec.Command's single /C argument makes Go's
// Windows argv encoder escape them for CommandLineToArgvW, which is not
// cmd.exe's parser and leaves backslashes in the command token.
t.Setenv(initGatewayHelperExecutableEnv, `"`+helperPath+`"`)
executable = `%` + initGatewayHelperExecutableEnv + `%`
} else {
t.Setenv(initGatewayHelperExecutableEnv, helperPath)
}
return executable + " -test.run=NoTestsMatchInitGatewayCredentialHelper -- " + strings.Join(args, " ")
}
func installInitGatewayExecutable(t *testing.T, source, destination string) {
t.Helper()
if err := os.Link(source, destination); err == nil {
return
}
// This fallback copies only the Unix test image, never the system shell.
// Windows uses a trampoline to its original test image instead.
input, err := os.Open(source)
if err != nil {
t.Fatalf("open current test executable: %v", err)
}
defer input.Close()
output, err := os.OpenFile(destination, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o755)
if err != nil {
t.Fatalf("create credential helper executable: %v", err)
}
if _, err := io.Copy(output, input); err != nil {
_ = output.Close()
t.Fatalf("copy credential helper executable: %v", err)
}
if err := output.Close(); err != nil {
t.Fatalf("close credential helper executable: %v", err)
}
if err := os.Chmod(destination, 0o755); err != nil {
t.Fatalf("make credential helper executable: %v", err)
}
}
func assertInitGatewayCredentialMarkerAbsent(t *testing.T, marker string) {
t.Helper()
if _, err := os.Stat(marker); err == nil {
t.Fatalf("credential command ran unexpectedly and wrote %q", marker)
} else if !os.IsNotExist(err) {
t.Fatalf("inspect credential marker %q: %v", marker, err)
}
}
func TestApplyInitGatewayCredentialHelperProtocol(t *testing.T) {
helperPath, err := os.Executable()
if err != nil {
t.Fatalf("resolve current test executable: %v", err)
}
helperCommand := func(args ...string) *exec.Cmd {
commandArgs := append([]string{"-test.run=NoTestsMatchInitGatewayCredentialHelper", "--"}, args...)
cmd := exec.Command(helperPath, commandArgs...)
cmd.Env = append(os.Environ(), initGatewayHelperProcessEnv+"=1")
return cmd
}
output, err := helperCommand("emit", "tok-init").Output()
if err != nil {
t.Fatalf("emit helper: %v", err)
}
if got := string(output); got != "tok-init" {
t.Fatalf("emit helper stdout = %q, want exact no-newline token", got)
}
output, err = helperCommand("unknown").CombinedOutput()
var exitErr *exec.ExitError
if !errors.As(err, &exitErr) || exitErr.ExitCode() != initGatewayHelperMalformedExit {
t.Fatalf("malformed helper exit = %v, output=%q; want %d", err, output, initGatewayHelperMalformedExit)
}
if !strings.Contains(string(output), "malformed arguments") {
t.Fatalf("malformed helper diagnostic = %q", output)
}
marker := filepath.Join(t.TempDir(), "helper-invoked")
markerCommand := helperCommand("marker")
markerCommand.Env = append(markerCommand.Env, initGatewayHelperMarkerEnv+"="+marker)
if output, err = markerCommand.CombinedOutput(); err != nil {
t.Fatalf("marker helper: %v, output=%q", err, output)
}
markerContent, err := os.ReadFile(marker)
if err != nil {
t.Fatalf("read helper marker: %v", err)
}
if got := string(markerContent); got != "invoked" {
t.Fatalf("helper marker = %q, want invoked", got)
}
}
// Gateway mode: a configured credential command resolves its token into the
// connection username, marks the config as targeting a gateway server, and
// disables local auto-start (the gateway is externally managed). This is what
@ -17,19 +260,18 @@ import (
// store skip the SHOW/CREATE DATABASE probe (openServerConnection keys that on
// cfg.Gateway). ServerMode is set because gateway init always targets a server.
func TestApplyInitGatewayCredentialAdoptsToken(t *testing.T) {
t.Setenv("BEADS_DOLT_CREDENTIAL_COMMAND", "printf tok-init")
t.Setenv("BEADS_DOLT_CREDENTIAL_COMMAND", initGatewayCredentialCommand(t, "emit", "tok-init"))
doltCfg := &dolt.Config{ServerMode: true, AutoStart: true}
want := *doltCfg
want.ServerUser = "tok-init"
want.Gateway = true
want.AutoStart = false
want.DisableAutoStart = true
if err := applyInitGatewayCredential(context.Background(), t.TempDir(), doltCfg); err != nil {
t.Fatalf("applyInitGatewayCredential: %v", err)
}
if doltCfg.ServerUser != "tok-init" {
t.Fatalf("ServerUser = %q, want tok-init (never root)", doltCfg.ServerUser)
}
if !doltCfg.Gateway {
t.Fatal("Gateway must be true so the store skips SHOW/CREATE DATABASE")
}
if doltCfg.AutoStart {
t.Fatal("AutoStart must be disabled in gateway mode (server is externally managed)")
if *doltCfg != want {
t.Fatalf("gateway config = %+v, want %+v", *doltCfg, want)
}
}
@ -37,17 +279,20 @@ func TestApplyInitGatewayCredentialAdoptsToken(t *testing.T) {
// BEADS_DOLT_CREDENTIAL_COMMAND is ambient on the host. This is the FIX-1
// regression guard: the canonical open path gates the command on server mode
// ("a command exported in the environment must not run (or fail) an embedded
// open"), so init must too. The command here (`false`) would error if it ran;
// the helper returning nil with the config untouched proves it did not.
// open"), so init must too. The marker helper makes non-invocation observable.
func TestApplyInitGatewayCredentialSkipsEmbeddedMode(t *testing.T) {
t.Setenv("BEADS_DOLT_CREDENTIAL_COMMAND", "false")
marker := filepath.Join(t.TempDir(), "credential-invoked")
t.Setenv(initGatewayHelperMarkerEnv, marker)
t.Setenv("BEADS_DOLT_CREDENTIAL_COMMAND", initGatewayCredentialCommand(t, "marker"))
doltCfg := &dolt.Config{AutoStart: true} // ServerMode defaults to false
want := *doltCfg
if err := applyInitGatewayCredential(context.Background(), t.TempDir(), doltCfg); err != nil {
t.Fatalf("embedded init must not run the credential command: %v", err)
}
if doltCfg.Gateway || doltCfg.ServerUser != "" || !doltCfg.AutoStart {
t.Fatalf("embedded config must be left untouched: %+v", doltCfg)
if *doltCfg != want {
t.Fatalf("embedded config = %+v, want untouched %+v", *doltCfg, want)
}
assertInitGatewayCredentialMarkerAbsent(t, marker)
}
// Server mode, but no command configured: a strict no-op. The hand-built config is
@ -55,39 +300,49 @@ func TestApplyInitGatewayCredentialSkipsEmbeddedMode(t *testing.T) {
func TestApplyInitGatewayCredentialNoopWithoutCommand(t *testing.T) {
t.Setenv("BEADS_DOLT_CREDENTIAL_COMMAND", "")
doltCfg := &dolt.Config{ServerMode: true, AutoStart: true}
want := *doltCfg
if err := applyInitGatewayCredential(context.Background(), t.TempDir(), doltCfg); err != nil {
t.Fatalf("applyInitGatewayCredential: %v", err)
}
if doltCfg.ServerUser != "" || doltCfg.Gateway || !doltCfg.AutoStart {
t.Fatalf("config must be untouched without a command: %+v", doltCfg)
if *doltCfg != want {
t.Fatalf("config without a command = %+v, want untouched %+v", *doltCfg, want)
}
}
// Fail-closed: in server mode a configured-but-failing command aborts init and
// never leaves a fallback (root) user behind.
func TestApplyInitGatewayCredentialFailsClosed(t *testing.T) {
t.Setenv("BEADS_DOLT_CREDENTIAL_COMMAND", "false")
t.Setenv("BEADS_DOLT_CREDENTIAL_COMMAND", initGatewayCredentialCommand(t, "exit", "23"))
doltCfg := &dolt.Config{ServerMode: true, AutoStart: true}
want := *doltCfg
err := applyInitGatewayCredential(context.Background(), t.TempDir(), doltCfg)
if err == nil {
t.Fatal("expected an error when the credential command fails")
}
if doltCfg.ServerUser != "" || doltCfg.Gateway {
t.Fatalf("config must be untouched on failure: %+v", doltCfg)
var exitErr *exec.ExitError
if !errors.As(err, &exitErr) || exitErr.ExitCode() != 23 {
t.Fatalf("credential failure = %v, want helper exit code 23", err)
}
if *doltCfg != want {
t.Fatalf("config after failure = %+v, want untouched %+v", *doltCfg, want)
}
}
// A caller/flag-preset --server-user wins over the credential command (the
// command is not run). Mirrors ApplyGatewayCredential's preset short-circuit.
func TestApplyInitGatewayCredentialPresetWins(t *testing.T) {
t.Setenv("BEADS_DOLT_CREDENTIAL_COMMAND", "false")
marker := filepath.Join(t.TempDir(), "credential-invoked")
t.Setenv(initGatewayHelperMarkerEnv, marker)
t.Setenv("BEADS_DOLT_CREDENTIAL_COMMAND", initGatewayCredentialCommand(t, "marker"))
doltCfg := &dolt.Config{ServerMode: true, ServerUser: "preset", AutoStart: true}
want := *doltCfg
if err := applyInitGatewayCredential(context.Background(), t.TempDir(), doltCfg); err != nil {
t.Fatalf("preset should short-circuit before running the command: %v", err)
}
if doltCfg.ServerUser != "preset" || doltCfg.Gateway || !doltCfg.AutoStart {
t.Fatalf("preset user must be preserved untouched: %+v", doltCfg)
if *doltCfg != want {
t.Fatalf("preset config = %+v, want untouched %+v", *doltCfg, want)
}
assertInitGatewayCredentialMarkerAbsent(t, marker)
}
// issue_prefix resolution.

View file

@ -113,3 +113,63 @@ func initGuardServerMessage(dbName, host string, port int, prefix, syncRemote st
b.WriteString("\nAborting.")
return errors.New(b.String())
}
// initAllowRecreateMissing is threaded from --recreate-missing for the
// duration of a single `bd init` invocation (be-5up5). It must only ever be
// set from that explicit per-invocation flag — never from a config key, env
// var, or implied by --force/--reinit-local — because it authorizes the one
// thing this file's guard exists to prevent: creating a fresh database when
// an existing project's configured one is missing or unreachable.
var initAllowRecreateMissing bool
// initGuardMissingServerDBMessage builds the refusal error for be-5up5: a
// workspace with evidence of prior initialization whose configured
// server-mode database is absent or the server could not be reached to
// confirm. This differs from initGuardServerMessage above, which would be used
// where there is no evidence either way about prior initialization and
// `bd bootstrap` is a reasonable next step — it has no production caller
// today, so the contrast is one of intent, not of two live code paths. Here
// prior initialization is already established, so recommending bootstrap would
// route straight back into the same class of silent-empty-database creation
// this guard exists to stop (2026-08-11 fleet-wide data loss). Point at
// restore-from-export instead, and require the explicit --recreate-missing
// opt-in before bd init will create anything.
//
// haveProjectID selects which evidence the message may cite. The plain-init
// guard only reaches this message with a project_id in hand, but the
// --reinit-local/--force guard also reaches it for a workspace that predates
// project_id (GH#2372) and is proven only by its local Dolt storage. Naming
// metadata.json in that cell would assert evidence the caller does not have,
// misdirecting an operator who audits metadata.json mid-recovery.
func initGuardMissingServerDBMessage(dbName, host string, port int, prefix string, haveProjectID bool) error {
var b strings.Builder
fmt.Fprintf(&b, "\n%s Database %q not found on server at %s:%d (or the server could not be reached to confirm).\n", ui.RenderWarn("⚠"), dbName, host, port)
if haveProjectID {
b.WriteString("This workspace was already initialized (metadata.json has a project_id from a prior\n")
b.WriteString("bd init), so this looks like a recovery situation, not a fresh clone: the configured\n")
b.WriteString("database is missing from the server, or the server could not be reached to check.\n")
} else {
b.WriteString("This workspace shows evidence of prior initialization (local Dolt storage is present,\n")
b.WriteString("though metadata.json carries no project_id — the shape of a workspace predating\n")
b.WriteString("GH#2372), so this looks like a recovery situation, not a fresh clone: the configured\n")
b.WriteString("database is missing from the server, or the server could not be reached to check.\n")
}
b.WriteString("\nbd init will NOT create an empty database here — that would strand any existing\n")
b.WriteString("issue data behind a new, empty database of the same name.\n")
b.WriteString("\nDiagnose with:\n")
b.WriteString(" bd doctor # check project health\n")
b.WriteString(" bd dolt status # inspect Dolt server state\n")
b.WriteString("\nTo recover existing data, restore from an export rather than creating fresh:\n")
b.WriteString(" bd backup restore # if a local backup snapshot exists\n")
b.WriteString(" Check .beads/backup/ for a JSONL export you can import manually.\n")
b.WriteString("\nIf you are certain no recoverable data exists and want a fresh, empty database at\n")
b.WriteString("this name, opt in explicitly for this one invocation:\n")
fmt.Fprintf(&b, " bd init --recreate-missing --prefix %s\n", prefix)
b.WriteString("\nAborting.")
return errors.New(b.String())
}

View file

@ -0,0 +1,82 @@
//go:build cgo
package main
import (
"encoding/json"
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
)
// TestInitGuard_ForceE2EDoesNotRecreateMissingServerDB is the behavioural proof
// for review item 1 on PR #5791. The unit subtests above pin
// guardMissingServerDatabaseAt's semantics; only this one proves the reinit
// path actually CALLS it, which is where the bug lived — the guard existed and
// was simply never reached with --force.
//
// Runs the real binary, because that is the only way to exercise the
// --force -> reinitLocal -> "skip checkExistingBeadsData" path end to end.
// Without the wiring this test fails: init proceeds past the guard and reports
// a connection failure instead of the refusal.
func TestInitGuard_ForceE2EDoesNotRecreateMissingServerDB(t *testing.T) {
bd := buildBDUnderTest(t)
for _, flag := range []string{"--force", "--reinit-local"} {
t.Run(flag, func(t *testing.T) {
projectDir := t.TempDir()
beadsDir := filepath.Join(projectDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
metadata := map[string]interface{}{
"database": "dolt",
"backend": "dolt",
"dolt_mode": "server",
"dolt_database": "myproject",
"project_id": "existing-0000-1111-2222-333344445555",
}
data, _ := json.Marshal(metadata)
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), data, 0644); err != nil {
t.Fatal(err)
}
// Port 1 is unreachable by construction, standing in for a server
// whose database has been lost.
env := []string{}
for _, kv := range os.Environ() {
switch {
case strings.HasPrefix(kv, "BEADS_DIR="),
strings.HasPrefix(kv, "BEADS_DB="),
strings.HasPrefix(kv, "BD_DB="),
strings.HasPrefix(kv, "BEADS_DOLT_SERVER_PORT="),
strings.HasPrefix(kv, "BEADS_DOLT_SERVER_DATABASE="):
continue
}
env = append(env, kv)
}
env = append(env,
"BEADS_DOLT_SERVER_PORT=1",
"BD_NON_INTERACTIVE=1",
)
// #nosec G204 -- bd is a locally built binary, flag is a literal
cmd := exec.Command(bd, "init", flag, "--prefix", "myproject", "--skip-hooks")
cmd.Dir = projectDir
cmd.Env = env
out, err := cmd.CombinedOutput()
if err == nil {
t.Fatalf("bd init %s against a missing server-side database must fail, got success.\nOutput:\n%s", flag, out)
}
if !strings.Contains(string(out), "not found on server") {
t.Fatalf("bd init %s must be refused by the missing-database guard, not fail incidentally.\nWanted the guard's refusal; got:\n%s", flag, out)
}
if !strings.Contains(string(out), "--recreate-missing") {
t.Errorf("refusal must name the explicit opt-in flag, got:\n%s", out)
}
})
}
}

View file

@ -3,9 +3,15 @@ package main
import (
"encoding/json"
"os"
"os/exec"
"path/filepath"
"strconv"
"strings"
"testing"
"time"
"github.com/steveyegge/beads/internal/doltserver"
"github.com/steveyegge/beads/internal/testutil"
)
func TestInitGuardServerMessage(t *testing.T) {
@ -451,3 +457,813 @@ func TestInitGuardServerMessage_DiagnosticsBeforeForce(t *testing.T) {
doctorIdx, forceIdx, msg)
}
}
// be-5up5: 2026-08-11 fleet-wide data loss. In server mode there is NEVER a
// local dolt/ directory, whether this is a genuine fresh clone or an existing
// project whose server-side database was lost — doltDirExists==false alone
// (GH#2433's signal) cannot tell them apart. metadata.json's project_id is
// only written by a real prior init, so a non-empty project_id here is proof
// this is an existing project recovering from a missing database, not
// GH#2433's fresh-clone case (whose fixture carries no project_id — see
// TestInitGuard_FreshCloneWithMetadataJSON above). init must refuse and
// point at bd bootstrap, not silently recreate an empty database on the
// server (the missing-database state that reproduced the 2026-08-11 loss).
func TestInitGuard_ExistingProjectMissingServerDB_Refuses(t *testing.T) {
testutil.RequireDoltBinary(t)
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
dataDir := t.TempDir()
port, err := testutil.FindFreePort()
if err != nil {
t.Fatalf("FindFreePort: %v", err)
}
// #nosec G204 -- fixed args, no user input
serverCmd := exec.Command("dolt", "sql-server", "-H", "127.0.0.1", "-P", strconv.Itoa(port), "--data-dir", dataDir)
if err := serverCmd.Start(); err != nil {
t.Fatalf("failed to start dolt sql-server: %v", err)
}
t.Cleanup(func() {
_ = serverCmd.Process.Kill()
_ = serverCmd.Wait()
})
if !testutil.WaitForServer(port, 15*time.Second) {
t.Fatal("dolt sql-server did not become ready within timeout")
}
t.Setenv("BEADS_DOLT_SERVER_PORT", strconv.Itoa(port))
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
// The server above has no "myproject" database — simulating server-side
// data loss on an existing project, not a never-initialized clone.
metadata := map[string]interface{}{
"database": "dolt",
"backend": "dolt",
"dolt_mode": "server",
"dolt_database": "myproject",
"project_id": "existing-0000-1111-2222-333344445555",
}
data, _ := json.Marshal(metadata)
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), data, 0644); err != nil {
t.Fatal(err)
}
err = checkExistingBeadsDataAt(beadsDir, "myproject")
if err == nil {
t.Fatal("existing project (non-empty project_id) with missing server-side database must refuse init, got nil error")
}
if !strings.Contains(err.Error(), "not found on server") {
t.Errorf("expected refusal message about missing database, got: %v", err)
}
if strings.Contains(err.Error(), "init --force") {
t.Errorf("message must NOT suggest deprecated --force, got:\n%s", err)
}
if strings.Contains(err.Error(), "bd bootstrap") {
t.Errorf("message must NOT recommend bd bootstrap for a server-mode workspace (bootstrap has its own related mode-blind create bug — be-cy41), got:\n%s", err)
}
if !strings.Contains(err.Error(), "bd backup restore") {
t.Errorf("message must name a recovery path, got:\n%s", err)
}
// Positive half of the evidence pin; the negative half is in
// TestInitGuard_ReinitLocal_NoProjectID_DataDirPresent_StillBlocks. This
// cell HAS a project_id, so citing metadata.json is accurate here and the
// operator should be told exactly which artifact proves prior init.
if !strings.Contains(err.Error(), "metadata.json has a project_id") {
t.Errorf("with a project_id present the refusal should cite that evidence, got:\n%s", err)
}
}
// be-ab3b: TestInitGuard_ExistingProjectMissingServerDB_Refuses above proves
// initAllowRecreateMissing is REQUIRED (refuses without it); this proves it is
// SUFFICIENT (permits init to proceed with it), covering both guard sites the
// flag gates inside checkExistingBeadsDataAt — "server reachable, database
// confirmed missing" and "server unreachable, or errored, while checking".
// Cited by branch rather than by line: this campaign keeps editing the
// enclosing function, so line numbers here go stale by construction.
//
// Without this, a wiring bug could silently strand the documented
// --recreate-missing recovery path (asymmetric risk: fails safe by blocking a
// legitimate recreate, but untested is untested).
func TestInitGuard_ExistingProjectMissingServerDB_RecreateMissingAllows(t *testing.T) {
oldAllow := initAllowRecreateMissing
initAllowRecreateMissing = true
defer func() { initAllowRecreateMissing = oldAllow }()
newExistingProjectMetadata := func() []byte {
metadata := map[string]interface{}{
"database": "dolt",
"backend": "dolt",
"dolt_mode": "server",
"dolt_database": "myproject",
"project_id": "existing-0000-1111-2222-333344445555",
}
data, _ := json.Marshal(metadata)
return data
}
t.Run("server_reachable_db_missing (init.go:2566)", func(t *testing.T) {
testutil.RequireDoltBinary(t)
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
dataDir := t.TempDir()
port, err := testutil.FindFreePort()
if err != nil {
t.Fatalf("FindFreePort: %v", err)
}
// #nosec G204 -- fixed args, no user input
serverCmd := exec.Command("dolt", "sql-server", "-H", "127.0.0.1", "-P", strconv.Itoa(port), "--data-dir", dataDir)
if err := serverCmd.Start(); err != nil {
t.Fatalf("failed to start dolt sql-server: %v", err)
}
t.Cleanup(func() {
_ = serverCmd.Process.Kill()
_ = serverCmd.Wait()
})
if !testutil.WaitForServer(port, 15*time.Second) {
t.Fatal("dolt sql-server did not become ready within timeout")
}
t.Setenv("BEADS_DOLT_SERVER_PORT", strconv.Itoa(port))
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
// Same fixture as TestInitGuard_ExistingProjectMissingServerDB_Refuses
// (existing project, server up, "myproject" DB absent) — only
// initAllowRecreateMissing differs.
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), newExistingProjectMetadata(), 0644); err != nil {
t.Fatal(err)
}
if err := checkExistingBeadsDataAt(beadsDir, "myproject"); err != nil {
t.Fatalf("existing project with --recreate-missing must permit init to proceed when the server-side database is missing, got refusal: %v", err)
}
})
t.Run("server_unreachable (init.go:2578)", func(t *testing.T) {
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
// Port 1 is a privileged port nothing listens on in test environments —
// same deterministic-unreachable technique as
// TestInitGuardDBCheck_ServerUnreachable. No real dolt server needed:
// this exercises the "server unreachable or error during check" branch,
// not the "confirmed missing" branch above.
t.Setenv("BEADS_DOLT_SERVER_PORT", "1")
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), newExistingProjectMetadata(), 0644); err != nil {
t.Fatal(err)
}
if err := checkExistingBeadsDataAt(beadsDir, "myproject"); err != nil {
t.Fatalf("existing project with --recreate-missing must permit init to proceed even when the server is unreachable, got refusal: %v", err)
}
})
}
// TestInitGuard_UnreachableServerRefuses covers the second guard site — server
// unreachable, or errored while checking — on the REFUSE side.
//
// Review of PR #5791, item 2: the PR claimed
// TestInitGuard_ExistingProjectMissingServerDB_Refuses covered both the
// reachable-but-missing and the server-unreachable cases, but that test starts
// a live server, so it only ever exercises the first. The unreachable site had
// coverage only on the permit side (the BEADS_DOLT_SERVER_PORT=1 subtest of
// _RecreateMissingAllows), which would not notice if the refusal there were
// dropped. Needs no Dolt binary: port 1 is unreachable by construction.
func TestInitGuard_UnreachableServerRefuses(t *testing.T) {
oldAllow := initAllowRecreateMissing
initAllowRecreateMissing = false
defer func() { initAllowRecreateMissing = oldAllow }()
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
t.Setenv("BEADS_DOLT_SERVER_PORT", "1")
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
metadata := map[string]interface{}{
"database": "dolt",
"backend": "dolt",
"dolt_mode": "server",
"dolt_database": "myproject",
"project_id": "existing-0000-1111-2222-333344445555",
}
data, _ := json.Marshal(metadata)
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), data, 0644); err != nil {
t.Fatal(err)
}
err := checkExistingBeadsDataAt(beadsDir, "myproject")
if err == nil {
t.Fatal("existing project whose server could not be reached must refuse init, got nil error")
}
if !strings.Contains(err.Error(), "not found on server") {
t.Errorf("expected the missing-database refusal, got: %v", err)
}
if !strings.Contains(err.Error(), "bd backup restore") {
t.Errorf("message must name a recovery path, got:\n%s", err)
}
}
// TestInitGuard_ReinitLocalDoesNotBypassMissingServerDB is the review's item 1.
//
// --force is a deprecated alias for --reinit-local, and --reinit-local skips
// checkExistingBeadsData entirely. The reinit path's own typed confirmation
// keys on countExistingIssues, which returns 0 or an error in exactly the case
// where the server-side database is missing — so before this fix,
// `bd init --force` against a lost database created a fresh empty one with no
// prompt and no destroy token. That is the 2026-08-11 fleet-wide data-loss
// reflex, reached through the flag an operator in a panic is most likely to
// reach for, and it is what makes --recreate-missing's "never implied by
// --force" help text an honest guarantee rather than an aspiration.
//
// guardMissingServerDatabaseAt is the narrow guard the reinit path now runs.
// The subtests pin both halves: it must refuse without --recreate-missing, and
// must still permit with it (otherwise the documented recovery path is dead).
func TestInitGuard_ReinitLocalDoesNotBypassMissingServerDB(t *testing.T) {
newExistingProjectWorkspace := func(t *testing.T) string {
t.Helper()
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
metadata := map[string]interface{}{
"database": "dolt",
"backend": "dolt",
"dolt_mode": "server",
"dolt_database": "myproject",
"project_id": "existing-0000-1111-2222-333344445555",
}
data, _ := json.Marshal(metadata)
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), data, 0644); err != nil {
t.Fatal(err)
}
return beadsDir
}
t.Run("refuses without --recreate-missing", func(t *testing.T) {
oldAllow := initAllowRecreateMissing
initAllowRecreateMissing = false
defer func() { initAllowRecreateMissing = oldAllow }()
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
t.Setenv("BEADS_DOLT_SERVER_PORT", "1")
err := guardMissingServerDatabaseAt(newExistingProjectWorkspace(t), "myproject")
if err == nil {
t.Fatal("bd init --force/--reinit-local against a missing server-side database must refuse, got nil error")
}
if !strings.Contains(err.Error(), "not found on server") {
t.Errorf("expected the missing-database refusal, got: %v", err)
}
})
t.Run("permits with --recreate-missing", func(t *testing.T) {
oldAllow := initAllowRecreateMissing
initAllowRecreateMissing = true
defer func() { initAllowRecreateMissing = oldAllow }()
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
t.Setenv("BEADS_DOLT_SERVER_PORT", "1")
if err := guardMissingServerDatabaseAt(newExistingProjectWorkspace(t), "myproject"); err != nil {
t.Fatalf("--recreate-missing must still authorize the reinit path, got: %v", err)
}
})
t.Run("stays silent on a fresh clone with no project_id", func(t *testing.T) {
oldAllow := initAllowRecreateMissing
initAllowRecreateMissing = false
defer func() { initAllowRecreateMissing = oldAllow }()
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
t.Setenv("BEADS_DOLT_SERVER_PORT", "1")
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
metadata := map[string]interface{}{
"database": "dolt",
"backend": "dolt",
"dolt_mode": "server",
"dolt_database": "myproject",
// no project_id: a genuine fresh clone, which --reinit-local must
// still be able to initialize.
}
data, _ := json.Marshal(metadata)
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), data, 0644); err != nil {
t.Fatal(err)
}
if err := guardMissingServerDatabaseAt(beadsDir, "myproject"); err != nil {
t.Fatalf("a fresh clone (no project_id) must not be blocked by this guard, got: %v", err)
}
})
}
// TestInitGuard_SharedServerMode_MissingServerDB_Refuses pins the shared-server
// case, which the per-project tests above cannot reach.
//
// guardMissingServerDatabaseAt used to stat doltserver.ResolveDoltDir(beadsDir)
// and return early when it was a directory, treating that as "there is local
// data to protect". In shared-server mode ResolveDoltDir returns the
// machine-global ~/.beads/shared-server/dolt, and SharedDoltDir() MkdirAlls it
// — so the stat always succeeded and checkDatabaseOnServer was never reached.
// The guard was a no-op in exactly the topology the 2026-08-11 loss happened
// in, while passing every per-project test.
//
// Here the server is REACHABLE and simply does not have this project's
// database — the actual loss shape, not an unreachable-host stand-in.
func TestInitGuard_SharedServerMode_MissingServerDB_Refuses(t *testing.T) {
testutil.RequireDoltBinary(t)
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
// Shared-server mode, redirected so SharedDoltDir() resolves (and
// MkdirAlls) inside the test's own tree rather than the developer's.
//
// Set BEADS_SHARED_SERVER_DIR, not HOME: SharedServerPath() reads that
// variable FIRST and only falls back to os.UserHomeDir(). Redirecting HOME
// alone left an ambient BEADS_SHARED_SERVER_DIR winning -- the pair then
// wrote into, and asserted against, the developer's real
// ~/.beads/shared-server/dolt, and _Refuses failed spuriously if a real
// "myproject" lived there. HOME is also a no-op on Windows, where
// os.UserHomeDir() reads %USERPROFILE%.
t.Setenv("BEADS_SHARED_SERVER_DIR", filepath.Join(t.TempDir(), "shared-server"))
t.Setenv("BEADS_DOLT_SHARED_SERVER", "1")
if !doltserver.IsSharedServerMode() {
t.Fatal("precondition: BEADS_DOLT_SHARED_SERVER=1 did not enable shared-server mode")
}
dataDir := t.TempDir()
port, err := testutil.FindFreePort()
if err != nil {
t.Fatalf("FindFreePort: %v", err)
}
// #nosec G204 -- fixed args, no user input
serverCmd := exec.Command("dolt", "sql-server", "-H", "127.0.0.1", "-P", strconv.Itoa(port), "--data-dir", dataDir)
if err := serverCmd.Start(); err != nil {
t.Fatalf("failed to start dolt sql-server: %v", err)
}
t.Cleanup(func() {
_ = serverCmd.Process.Kill()
_ = serverCmd.Wait()
})
if !testutil.WaitForServer(port, 15*time.Second) {
t.Fatal("dolt sql-server did not become ready within timeout")
}
t.Setenv("BEADS_DOLT_SERVER_PORT", strconv.Itoa(port))
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
metadata := map[string]interface{}{
"database": "dolt",
"backend": "dolt",
"dolt_mode": "server",
"dolt_database": "myproject",
"project_id": "shared-0000-1111-2222-333344445555",
}
data, _ := json.Marshal(metadata)
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), data, 0644); err != nil {
t.Fatal(err)
}
// The regression this pins: the shared dolt dir exists (MkdirAll'd on
// resolve) but holds no database for this project.
sharedDolt, err := doltserver.SharedDoltDir()
if err != nil {
t.Fatalf("SharedDoltDir: %v", err)
}
if _, statErr := os.Stat(sharedDolt); statErr != nil {
t.Fatalf("precondition: shared dolt dir %q should exist after resolve: %v", sharedDolt, statErr)
}
if _, statErr := os.Stat(filepath.Join(sharedDolt, "myproject")); statErr == nil {
t.Fatalf("precondition: shared dolt dir must NOT hold a myproject database")
}
err = guardMissingServerDatabaseAt(beadsDir, "myproject")
if err == nil {
t.Fatal("shared-server mode with a reachable server and no myproject database must refuse init, got nil error " +
"(the guard returned early on the machine-global shared dolt dir instead of checking the server)")
}
if !strings.Contains(err.Error(), "not found on server") {
t.Errorf("expected refusal message about missing database, got: %v", err)
}
}
// TestInitGuard_SharedServerMode_PresentServerDB_Allows is the positive control
// for the test above: with this project's database actually present on the
// shared server, the guard must stay out of the way so --reinit-local and
// ordinary reinit keep working. Without this, tightening the guard could
// silently start refusing healthy shared-server workspaces.
func TestInitGuard_SharedServerMode_PresentServerDB_Allows(t *testing.T) {
testutil.RequireDoltBinary(t)
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
// BEADS_SHARED_SERVER_DIR, not HOME -- see _MissingServerDB_Refuses above.
t.Setenv("BEADS_SHARED_SERVER_DIR", filepath.Join(t.TempDir(), "shared-server"))
t.Setenv("BEADS_DOLT_SHARED_SERVER", "1")
dataDir := t.TempDir()
port, err := testutil.FindFreePort()
if err != nil {
t.Fatalf("FindFreePort: %v", err)
}
// #nosec G204 -- fixed args, no user input
serverCmd := exec.Command("dolt", "sql-server", "-H", "127.0.0.1", "-P", strconv.Itoa(port), "--data-dir", dataDir)
if err := serverCmd.Start(); err != nil {
t.Fatalf("failed to start dolt sql-server: %v", err)
}
t.Cleanup(func() {
_ = serverCmd.Process.Kill()
_ = serverCmd.Wait()
})
if !testutil.WaitForServer(port, 15*time.Second) {
t.Fatal("dolt sql-server did not become ready within timeout")
}
t.Setenv("BEADS_DOLT_SERVER_PORT", strconv.Itoa(port))
sharedDB, err := testutil.SetupSharedTestDB(port, "myproject")
if err != nil {
t.Fatalf("create myproject database on server: %v", err)
}
_ = sharedDB.Close()
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
metadata := map[string]interface{}{
"database": "dolt",
"backend": "dolt",
"dolt_mode": "server",
"dolt_database": "myproject",
"project_id": "shared-0000-1111-2222-333344445555",
}
data, _ := json.Marshal(metadata)
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), data, 0644); err != nil {
t.Fatal(err)
}
// Give this project a database directory under the shared data dir, the
// way a real shared-mode install has one. Without it this test returned
// nil via the server check alone, so nothing pinned the local-database
// early return -- reverting that early return left this test green.
sharedDolt, err := doltserver.SharedDoltDir()
if err != nil {
t.Fatalf("SharedDoltDir: %v", err)
}
localDB := filepath.Join(sharedDolt, "myproject", ".dolt")
if err := os.MkdirAll(localDB, 0755); err != nil {
t.Fatal(err)
}
if info, statErr := os.Stat(localDB); statErr != nil || !info.IsDir() {
t.Fatalf("precondition: %q must exist: %v", localDB, statErr)
}
if err := guardMissingServerDatabaseAt(beadsDir, "myproject"); err != nil {
t.Fatalf("database present on the shared server must NOT be refused, got: %v", err)
}
// Pin the early return specifically: with the server gone entirely, the
// local database directory alone must still keep the guard out of the way.
// This is the assertion that goes red if the early return is removed.
t.Setenv("BEADS_DOLT_SERVER_PORT", "1")
if err := guardMissingServerDatabaseAt(beadsDir, "myproject"); err != nil {
t.Fatalf("this project's local database directory must satisfy the guard without reaching the server, got: %v", err)
}
}
// startProjectServerModeGuardFixture builds the state a real server-mode
// workspace is in after its server-side database is lost: a Dolt data
// directory that exists (ensureDoltInit MkdirAlls it and runs `dolt init`
// there at first init, and DROP DATABASE does not remove it), holding NO
// subdirectory for this project's database, against a live server that does
// not have the database either.
//
// The pre-existing _Refuses/_RecreateMissingAllows fixtures omit the data
// directory entirely, which is why they passed while the guard was probing it:
// their `!localDatabaseExists` was true for the wrong reason. Round-3 MAJOR-1 /
// round-4 finding 1 is exactly the gap between those fixtures and this one.
func startProjectServerModeGuardFixture(t *testing.T, dbName string) string {
t.Helper()
testutil.RequireDoltBinary(t)
// Per-project server mode, pinned rather than inherited: an ambient
// BEADS_DOLT_SHARED_SERVER or BEADS_DOLT_DATA_DIR would otherwise
// redirect ResolveDoltDir out of this test's tree (round-3 MINOR-2 is the
// same class of ambient-env leak, one variable over).
t.Setenv("BEADS_DOLT_SHARED_SERVER", "0")
t.Setenv("BEADS_DOLT_DATA_DIR", "")
if doltserver.IsSharedServerMode() {
t.Fatal("precondition: this test requires per-project server mode")
}
dataDir := t.TempDir()
port, err := testutil.FindFreePort()
if err != nil {
t.Fatalf("FindFreePort: %v", err)
}
// #nosec G204 -- fixed args, no user input
serverCmd := exec.Command("dolt", "sql-server", "-H", "127.0.0.1", "-P", strconv.Itoa(port), "--data-dir", dataDir)
if err := serverCmd.Start(); err != nil {
t.Fatalf("failed to start dolt sql-server: %v", err)
}
t.Cleanup(func() {
_ = serverCmd.Process.Kill()
_ = serverCmd.Wait()
})
if !testutil.WaitForServer(port, 15*time.Second) {
t.Fatal("dolt sql-server did not become ready within timeout")
}
t.Setenv("BEADS_DOLT_SERVER_PORT", strconv.Itoa(port))
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
metadata := map[string]interface{}{
"database": "dolt",
"backend": "dolt",
"dolt_mode": "server",
"dolt_database": dbName,
"project_id": "existing-0000-1111-2222-333344445555",
}
data, _ := json.Marshal(metadata)
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), data, 0644); err != nil {
t.Fatal(err)
}
// The regression this pins: the DATA directory is present, the way it is
// on every initialized workspace...
doltDir := doltserver.ResolveDoltDir(beadsDir)
if err := os.MkdirAll(filepath.Join(doltDir, ".dolt"), 0755); err != nil {
t.Fatal(err)
}
if info, statErr := os.Stat(doltDir); statErr != nil || !info.IsDir() {
t.Fatalf("precondition: dolt data dir %q must exist: %v", doltDir, statErr)
}
// ...while this project's own database directory is NOT.
if _, statErr := os.Stat(filepath.Join(doltDir, dbName, ".dolt")); statErr == nil {
t.Fatalf("precondition: data dir must NOT hold a %q database", dbName)
}
return beadsDir
}
// TestInitGuard_ExistingProjectMissingServerDB_DataDirPresent_Refuses is the
// negative half of round-3 MAJOR-1. With the data directory present — the real
// state of every initialized workspace — the guard must still reach the FR-010
// missing-database branch and refuse, rather than falling through to the false
// "already initialized" message.
func TestInitGuard_ExistingProjectMissingServerDB_DataDirPresent_Refuses(t *testing.T) {
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
oldAllow := initAllowRecreateMissing
initAllowRecreateMissing = false
defer func() { initAllowRecreateMissing = oldAllow }()
beadsDir := startProjectServerModeGuardFixture(t, "myproject")
err := checkExistingBeadsDataAt(beadsDir, "myproject")
if err == nil {
t.Fatal("existing project whose server-side database is gone must refuse init, got nil error")
}
if !strings.Contains(err.Error(), "not found on server") {
t.Errorf("guard fell through to the wrong branch: expected the missing-database refusal, got:\n%v", err)
}
// The false message this replaces: alreadyInitialized() announces a
// database that is NOT there and routes the operator at --reinit-local,
// which recreates it empty. Match on its own distinguishing line -- the
// correct refusal above legitimately says "was already initialized",
// meaning the WORKSPACE was, which is the whole basis for refusing.
if strings.Contains(err.Error(), "Found existing Dolt database") {
t.Errorf("refusal must not announce a database that is gone, got:\n%v", err)
}
}
// TestInitGuard_RecreateMissing_ReachesOptIn_DataDirPresent is the blocker
// itself: four surfaces (the --recreate-missing flag help, `bd help
// init-safety`, docs/recovery/init-safety.md and the guard's own refusal text)
// tell the operator to run `bd init --recreate-missing --prefix <p>`. With the
// data directory present, that command could not reach its own opt-in and
// exited 1 with the false "already initialized" message — so the documented
// recovery was a dead end, and the only thing that worked (--reinit-local
// --recreate-missing) is named nowhere.
func TestInitGuard_RecreateMissing_ReachesOptIn_DataDirPresent(t *testing.T) {
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
oldAllow := initAllowRecreateMissing
initAllowRecreateMissing = true
defer func() { initAllowRecreateMissing = oldAllow }()
beadsDir := startProjectServerModeGuardFixture(t, "myproject")
if err := checkExistingBeadsDataAt(beadsDir, "myproject"); err != nil {
t.Fatalf("bd init --recreate-missing must reach its opt-in and permit init when the configured database is gone; got:\n%v", err)
}
}
// TestInitGuard_NoProjectID_DataDirPresent_StillBlocks pins the narrowing that
// keeps the finding-1 fix from widening what fails OPEN.
//
// A pre-GH#2372 workspace carries no project_id, so `existingProject` is false
// and the FR-010 branch would otherwise permit init. Before the fix that branch
// was simply never reached in this state — the data-dir stat sent every such
// workspace to the "already initialized" refusal — so permitting it now would
// be a NEW silent-empty-recreate path on exactly the installed base this guard
// exists to protect. It stays blocked. Only an explicit --recreate-missing
// opens it, which the companion test below asserts.
func TestInitGuard_NoProjectID_DataDirPresent_StillBlocks(t *testing.T) {
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
oldAllow := initAllowRecreateMissing
initAllowRecreateMissing = false
defer func() { initAllowRecreateMissing = oldAllow }()
beadsDir := startProjectServerModeGuardFixture(t, "myproject")
stripProjectID(t, beadsDir)
err := checkExistingBeadsDataAt(beadsDir, "myproject")
if err == nil {
t.Fatal("a workspace with a local Dolt data directory must not be permitted to " +
"silently recreate its missing database just because it predates project_id")
}
}
// TestInitGuard_NoProjectID_DataDirPresent_RecreateMissingAllows is the
// positive control for the test above: the explicit per-invocation opt-in is
// the one thing that opens that state, so the operator still has a documented
// way forward rather than a dead end.
func TestInitGuard_NoProjectID_DataDirPresent_RecreateMissingAllows(t *testing.T) {
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
oldAllow := initAllowRecreateMissing
initAllowRecreateMissing = true
defer func() { initAllowRecreateMissing = oldAllow }()
beadsDir := startProjectServerModeGuardFixture(t, "myproject")
stripProjectID(t, beadsDir)
if err := checkExistingBeadsDataAt(beadsDir, "myproject"); err != nil {
t.Fatalf("--recreate-missing must still permit init for a pre-project_id workspace; got:\n%v", err)
}
}
// stripProjectID rewrites the fixture's metadata.json without project_id,
// reproducing a workspace initialized before GH#2372 minted the field.
func stripProjectID(t *testing.T, beadsDir string) {
t.Helper()
path := filepath.Join(beadsDir, "metadata.json")
raw, err := os.ReadFile(path) // #nosec G304 -- test fixture path
if err != nil {
t.Fatal(err)
}
var meta map[string]interface{}
if err := json.Unmarshal(raw, &meta); err != nil {
t.Fatal(err)
}
delete(meta, "project_id")
out, err := json.Marshal(meta)
if err != nil {
t.Fatal(err)
}
if err := os.WriteFile(path, out, 0600); err != nil {
t.Fatal(err)
}
}
// TestInitGuard_ReinitLocal_NoProjectID_DataDirPresent_StillBlocks is the
// --reinit-local/--force mirror of
// TestInitGuard_NoProjectID_DataDirPresent_StillBlocks, and closes ADR-0004
// follow-up 1: the two guards must agree about a pre-GH#2372 workspace whose
// local database was lost.
//
// guardMissingServerDatabaseAt used to return nil on an empty project_id
// BEFORE it ever reached its per-database probe, so such a workspace was
// protected under plain `bd init` (which probes first) and waved straight
// through under --reinit-local/--force — the one guard whose entire purpose is
// to be that flag pair's safety net. The flags an operator reaches for in a
// panic were the weaker path.
func TestInitGuard_ReinitLocal_NoProjectID_DataDirPresent_StillBlocks(t *testing.T) {
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
oldAllow := initAllowRecreateMissing
initAllowRecreateMissing = false
defer func() { initAllowRecreateMissing = oldAllow }()
beadsDir := startProjectServerModeGuardFixture(t, "myproject")
stripProjectID(t, beadsDir)
err := guardMissingServerDatabaseAt(beadsDir, "myproject")
if err == nil {
t.Fatal("--reinit-local/--force must not wave through a workspace with local Dolt storage " +
"whose database is gone, just because it predates project_id")
}
if !strings.Contains(err.Error(), "not found on server") {
t.Errorf("expected the missing-database refusal, got:\n%v", err)
}
// Negative half of the evidence pin (twin of the assertion in
// TestInitGuard_ExistingProjectMissingServerDB_Refuses): this cell is
// reached precisely BECAUSE metadata.json carries no project_id — only the
// local Dolt storage proves prior use. A refusal that cites project_id
// evidence here sends an operator auditing metadata.json mid-recovery
// looking for something that was never there. Asserting the absence of the
// false claim rather than the presence of particular prose, so rewording
// the message cannot make this stale.
if strings.Contains(err.Error(), "metadata.json has a project_id") {
t.Errorf("refusal must not assert project_id evidence in the no-project_id cell, got:\n%s", err)
}
}
// TestInitGuard_ReinitLocal_NoProjectID_NoDataDir_Allows is the positive
// control: with nothing local at all, this really is a fresh clone and
// --reinit-local must still work. It pins the coarse-directory permit
// condition, so the fix above cannot be over-applied into refusing every
// pre-GH#2372 workspace.
func TestInitGuard_ReinitLocal_NoProjectID_NoDataDir_Allows(t *testing.T) {
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
oldAllow := initAllowRecreateMissing
initAllowRecreateMissing = false
defer func() { initAllowRecreateMissing = oldAllow }()
beadsDir := startProjectServerModeGuardFixture(t, "myproject")
stripProjectID(t, beadsDir)
// Remove the local Dolt data directory the fixture created, leaving the
// genuine fresh-clone shape: tracked metadata.json and nothing else.
if err := os.RemoveAll(doltserver.ResolveDoltDir(beadsDir)); err != nil {
t.Fatal(err)
}
if err := guardMissingServerDatabaseAt(beadsDir, "myproject"); err != nil {
t.Fatalf("a fresh clone with no local Dolt storage and no project_id must not be refused; got:\n%v", err)
}
}
// TestInitGuard_ReinitLocal_NoProjectID_RecreateMissingAllows pins that the
// documented resolution path still opens the state the first test refuses.
func TestInitGuard_ReinitLocal_NoProjectID_RecreateMissingAllows(t *testing.T) {
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
oldAllow := initAllowRecreateMissing
initAllowRecreateMissing = true
defer func() { initAllowRecreateMissing = oldAllow }()
beadsDir := startProjectServerModeGuardFixture(t, "myproject")
stripProjectID(t, beadsDir)
if err := guardMissingServerDatabaseAt(beadsDir, "myproject"); err != nil {
t.Fatalf("--recreate-missing must still permit --reinit-local for a pre-project_id workspace; got:\n%v", err)
}
}

View file

@ -41,6 +41,15 @@ FLAG SURFACE
bd init --force Deprecated alias for --reinit-local.
Kept working for ≥2 releases.
bd init --recreate-missing Authorize creating a fresh, empty database
when this project's configured server-mode
database is missing or unreachable. Opt-in
per invocation only: never implied by
--force/--reinit-local, config, or env.
Without it, bd init REFUSES rather than
silently recreating a lost database as
empty (be-5up5).
bd init --from-jsonl Import from configured import.path. If
origin has Dolt data, this refuses unless
--discard-remote authorizes replacing that

View file

@ -0,0 +1,45 @@
package main
import (
"testing"
"github.com/spf13/cobra"
)
// TestNoSubcommandShadowsRootJSONFlag guards the root --json contract.
//
// --json is a persistent flag on rootCmd. When a subcommand registers its own
// --json (local or persistent), pflag keeps that one and drops the inherited
// one, so rootCmd.PersistentFlags().Changed("json") stays false for that
// command. The PersistentPreRun then treats the flag as unset and overwrites
// jsonOutput with the configured default, and `bd <cmd> --json` prints text
// unless the config also says json. Every command must inherit the root flag
// instead.
//
// The check reads Flags() and PersistentFlags() only. LocalNonPersistentFlags()
// and InheritedFlags() call mergePersistentFlags, which copies every root
// persistent flag into the command's Flags() for the rest of the process and
// breaks tests that pin a command's exact flag set (TestServeFlags).
func TestNoSubcommandShadowsRootJSONFlag(t *testing.T) {
rootJSON := rootCmd.PersistentFlags().Lookup("json")
if rootJSON == nil {
t.Fatal("root command must register persistent --json")
}
var offenders []string
var walk func(cmd *cobra.Command)
walk = func(cmd *cobra.Command) {
for _, sub := range cmd.Commands() {
local := sub.Flags().Lookup("json")
if (local != nil && local != rootJSON) || sub.PersistentFlags().Lookup("json") != nil {
offenders = append(offenders, sub.CommandPath())
}
walk(sub)
}
}
walk(rootCmd)
for _, path := range offenders {
t.Errorf("%q registers a local --json flag that shadows the root persistent flag", path)
}
}

View file

@ -419,12 +419,12 @@ func runListCore(cmd *cobra.Command, _ []string) error {
}
func init() {
listCmd.Flags().StringP("status", "s", "", "Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress. Note: repeating -s/--status silently overwrites the previous value — always use the comma-separated form for multi-status filters.")
listCmd.Flags().String("state", "", "Alias for --status")
listCmd.Flags().VarP(&listStatusFlag, "status", "s", "Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated or repeated for multiple: --status open,in_progress")
listCmd.Flags().Var(&listStateFlag, "state", "Alias for --status")
_ = listCmd.Flags().MarkHidden("state")
registerPriorityFlag(listCmd, "")
listCmd.Flags().StringP("assignee", "a", "", "Filter by assignee")
listCmd.Flags().StringP("type", "t", "", "Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate, convoy). Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision")
listCmd.Flags().VarP(&listAssigneeFlag, "assignee", "a", "Filter by assignee")
listCmd.Flags().VarP(&listTypeFlag, "type", "t", "Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate, convoy). Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision")
listCmd.Flags().StringSliceP("label", "l", []string{}, "Filter by labels (AND: must have ALL). Can combine with --label-any")
listCmd.Flags().StringSlice("label-any", []string{}, "Filter by labels (OR: must have AT LEAST ONE). Can combine with --label")
listCmd.Flags().StringSlice("exclude-label", []string{}, "Exclude issues that have ANY of these labels")
@ -432,7 +432,7 @@ func init() {
listCmd.Flags().String("label-regex", "", "Filter by label regex pattern (e.g., 'tech-(debt|legacy)')")
listCmd.Flags().String("title", "", "Filter by title text (case-insensitive substring match)")
listCmd.Flags().String("spec", "", "Filter by spec_id prefix")
listCmd.Flags().String("id", "", "Filter by specific issue IDs (comma-separated, e.g., bd-1,bd-5,bd-10)")
listCmd.Flags().Var(&listIDFlag, "id", "Filter by specific issue IDs (comma-separated or repeated, e.g., bd-1,bd-5,bd-10)")
listCmd.Flags().IntP("limit", "n", workapi.DefaultListLimit, "Limit results (an explicit --limit always wins, 0 meaning unlimited; otherwise --all is unlimited; otherwise a configured list.limit applies; otherwise unlimited when piped, else 20 in agent mode at a terminal, else 50)")
listCmd.Flags().Int("offset", 0, "Skip the first N matching results (0-based). Only supported under --proxied-server.")
listCmd.Flags().String("format", "", "Export the dependency graph of the listed issues: 'digraph' (edge list for golang.org/x/tools/cmd/digraph), 'dot' (Graphviz), or a Go template rendered once per edge over .IssueID, .DependsOnID, .Type, .Issue, .Dependency. 'json' is the exception and does not export the graph: it is equivalent to --json, which also wins when both flags are given. 'digraph' and templates print nothing when no listed issue depends on another; 'dot' still prints the nodes")

101
cmd/bd/list_filter_flags.go Normal file
View file

@ -0,0 +1,101 @@
package main
import (
"fmt"
"slices"
"strings"
"github.com/spf13/pflag"
)
// unionStringFlag accumulates repeated flag occurrences into a comma-joined
// set: `--status open --status closed` means the same union as
// `--status open,closed`. Setting the empty string clears it — `bd children`
// resets listCmd's flags that way after borrowing them, and gatherListInput
// resets after each read so in-process callers that Execute() more than once
// do not inherit the previous command's filter.
type unionStringFlag struct {
value string
}
func (f *unionStringFlag) Set(s string) error {
switch {
case s == "":
f.value = ""
case f.value == "":
f.value = s
default:
for _, tok := range strings.Split(s, ",") {
if !slices.Contains(strings.Split(f.value, ","), tok) {
f.value += "," + tok
}
}
}
return nil
}
func (f *unionStringFlag) String() string { return f.value }
// Type reports "string" so cmd.Flags().GetString keeps working on flags
// registered with this value.
func (f *unionStringFlag) Type() string { return "string" }
// onceStringFlag refuses a repeated occurrence outright. It belongs on
// filters that are single-valued all the way down (--type, --assignee),
// where comma-joining would either fail type validation on the joined value
// or exact-match nothing and return an empty result that reads as a clean
// answer. Empty-string reset semantics match unionStringFlag.
type onceStringFlag struct {
name string
value string
set bool
}
func (f *onceStringFlag) Set(s string) error {
if s == "" {
f.value = ""
f.set = false
return nil
}
if f.set {
return fmt.Errorf("--%s given more than once (already %q); pass a single value", f.name, f.value)
}
f.set = true
f.value = s
return nil
}
func (f *onceStringFlag) String() string { return f.value }
func (f *onceStringFlag) Type() string { return "string" }
var (
listStatusFlag unionStringFlag
listStateFlag unionStringFlag
listIDFlag unionStringFlag
listTypeFlag = onceStringFlag{name: "type"}
listAssigneeFlag = onceStringFlag{name: "assignee"}
)
// resetListFilterFlags returns listCmd's five filter flags to their unparsed
// state: the values are cleared AND pflag's Changed bit is lowered on the
// given flag set, so an in-process caller that Execute()s listCmd twice sees
// neither the previous filter nor a stale "the user passed --status" signal.
// It takes the flag set as an argument rather than reading listCmd so that
// listCmd's initializer (via runListCore -> gatherListInput) does not refer
// back to itself.
func resetListFilterFlags(flags *pflag.FlagSet) {
_ = listStatusFlag.Set("")
_ = listStateFlag.Set("")
_ = listIDFlag.Set("")
_ = listTypeFlag.Set("")
_ = listAssigneeFlag.Set("")
if flags == nil {
return
}
for _, name := range []string{"status", "state", "type", "assignee", "id"} {
if fl := flags.Lookup(name); fl != nil {
fl.Changed = false
}
}
}

View file

@ -0,0 +1,237 @@
package main
import (
"strings"
"testing"
"github.com/steveyegge/beads/internal/workapi"
)
// resetListFilterFlagState restores listCmd's filter flags to their unparsed
// state so these tests leave nothing behind for the rest of the package.
func resetListFilterFlagState(t *testing.T) {
t.Helper()
t.Cleanup(func() { resetListFilterFlags(listCmd.Flags()) })
}
func TestListRepeatedStatusUnions(t *testing.T) {
resetListFilterFlagState(t)
if err := listCmd.ParseFlags([]string{"--status", "open", "--status", "closed", "-s", "pinned"}); err != nil {
t.Fatalf("ParseFlags: %v", err)
}
got, err := listCmd.Flags().GetString("status")
if err != nil {
t.Fatalf("GetString(status): %v", err)
}
if got != "open,closed,pinned" {
t.Fatalf("repeated --status = %q, want union %q", got, "open,closed,pinned")
}
}
func TestListSingleAndCommaStatusUnchanged(t *testing.T) {
resetListFilterFlagState(t)
if err := listCmd.ParseFlags([]string{"--status", "open"}); err != nil {
t.Fatalf("ParseFlags: %v", err)
}
if got, _ := listCmd.Flags().GetString("status"); got != "open" {
t.Fatalf("single --status = %q, want %q", got, "open")
}
resetListFilterFlags(listCmd.Flags())
if err := listCmd.ParseFlags([]string{"--status", "open,in_progress"}); err != nil {
t.Fatalf("ParseFlags: %v", err)
}
if got, _ := listCmd.Flags().GetString("status"); got != "open,in_progress" {
t.Fatalf("comma --status = %q, want %q", got, "open,in_progress")
}
}
func TestListRepeatedIDUnions(t *testing.T) {
resetListFilterFlagState(t)
if err := listCmd.ParseFlags([]string{"--id", "bd-1", "--id", "bd-2,bd-3"}); err != nil {
t.Fatalf("ParseFlags: %v", err)
}
if got, _ := listCmd.Flags().GetString("id"); got != "bd-1,bd-2,bd-3" {
t.Fatalf("repeated --id = %q, want %q", got, "bd-1,bd-2,bd-3")
}
}
func TestListRepeatedTypeRefused(t *testing.T) {
resetListFilterFlagState(t)
for _, args := range [][]string{
{"--type", "bug", "--type", "epic"},
{"-t", "bug", "-t", "epic"},
} {
resetListFilterFlags(listCmd.Flags())
err := listCmd.ParseFlags(args)
if err == nil {
t.Fatalf("ParseFlags(%v) accepted a repeated --type", args)
}
if !strings.Contains(err.Error(), "type") || !strings.Contains(err.Error(), "more than once") {
t.Fatalf("ParseFlags(%v) error %q does not name the repeated flag", args, err)
}
}
}
func TestListRepeatedAssigneeRefused(t *testing.T) {
resetListFilterFlagState(t)
err := listCmd.ParseFlags([]string{"--assignee", "alice", "--assignee", "bob"})
if err == nil {
t.Fatal("ParseFlags accepted a repeated --assignee")
}
if !strings.Contains(err.Error(), "assignee") || !strings.Contains(err.Error(), "more than once") {
t.Fatalf("error %q does not name the repeated flag", err)
}
}
func TestListSingleTypeAndAssigneeUnchanged(t *testing.T) {
resetListFilterFlagState(t)
if err := listCmd.ParseFlags([]string{"--type", "bug", "--assignee", "alice"}); err != nil {
t.Fatalf("ParseFlags: %v", err)
}
if got, _ := listCmd.Flags().GetString("type"); got != "bug" {
t.Fatalf("single --type = %q, want %q", got, "bug")
}
if got, _ := listCmd.Flags().GetString("assignee"); got != "alice" {
t.Fatalf("single --assignee = %q, want %q", got, "alice")
}
}
// bd children borrows listCmd's status flag with Set("all") and a deferred
// Set(""); an empty Set must fully reset both value kinds.
func TestEmptySetResetsFilterFlags(t *testing.T) {
resetListFilterFlagState(t)
fl := listCmd.Flags()
_ = fl.Set("status", "all")
_ = fl.Set("status", "")
_ = fl.Set("status", "open")
if got, _ := fl.GetString("status"); got != "open" {
t.Fatalf("status after reset = %q, want %q", got, "open")
}
_ = fl.Set("type", "bug")
_ = fl.Set("type", "")
if err := fl.Set("type", "epic"); err != nil {
t.Fatalf("Set(type) after reset refused: %v", err)
}
if got, _ := fl.GetString("type"); got != "epic" {
t.Fatalf("type after reset = %q, want %q", got, "epic")
}
}
// Two parses in one process must not bleed into each other once
// resetListFilterFlags has run between them, the way gatherListInput does.
func TestFilterFlagsDoNotLeakAcrossParses(t *testing.T) {
resetListFilterFlagState(t)
if err := listCmd.ParseFlags([]string{"--status", "open", "--status", "closed"}); err != nil {
t.Fatalf("ParseFlags: %v", err)
}
resetListFilterFlags(listCmd.Flags())
if err := listCmd.ParseFlags([]string{"--status", "pinned"}); err != nil {
t.Fatalf("ParseFlags: %v", err)
}
if got, _ := listCmd.Flags().GetString("status"); got != "pinned" {
t.Fatalf("status after second parse = %q, want %q (leaked prior parse)", got, "pinned")
}
}
func TestListRepeatedStatusDedupes(t *testing.T) {
resetListFilterFlagState(t)
if err := listCmd.ParseFlags([]string{"--status", "open", "--status", "open,closed", "--status", "closed"}); err != nil {
t.Fatalf("ParseFlags: %v", err)
}
got, err := listCmd.Flags().GetString("status")
if err != nil {
t.Fatalf("GetString(status): %v", err)
}
if got != "open,closed" {
t.Fatalf("repeated --status with duplicates = %q, want %q", got, "open,closed")
}
}
func TestResetListFilterFlagsLowersChanged(t *testing.T) {
resetListFilterFlagState(t)
if err := listCmd.ParseFlags([]string{"--status", "open", "--type", "bug"}); err != nil {
t.Fatalf("ParseFlags: %v", err)
}
for _, name := range []string{"status", "type"} {
if !listCmd.Flags().Changed(name) {
t.Fatalf("precondition: --%s should read as Changed after parse", name)
}
}
resetListFilterFlags(listCmd.Flags())
for _, name := range []string{"status", "state", "type", "assignee", "id"} {
if listCmd.Flags().Changed(name) {
t.Fatalf("--%s still reads as Changed after resetListFilterFlags", name)
}
}
}
// TestListStateAndStatusArms pins the three reachable arms of the new flag
// registration that the existing cases do not reach: the hidden --state alias
// unions like --status, a union that includes "all" is refused downstream
// rather than silently narrowing, and --status wins over --state when both are
// given (gatherListInput only consults --state when --status is empty).
func TestListStateAndStatusArms(t *testing.T) {
t.Run("repeated --state unions", func(t *testing.T) {
resetListFilterFlagState(t)
if err := listCmd.ParseFlags([]string{"--state", "open", "--state", "closed"}); err != nil {
t.Fatalf("ParseFlags: %v", err)
}
got, err := listCmd.Flags().GetString("state")
if err != nil {
t.Fatalf("GetString(state): %v", err)
}
if got != "open,closed" {
t.Fatalf("repeated --state = %q, want union %q", got, "open,closed")
}
})
t.Run("union including all is refused, not narrowed", func(t *testing.T) {
resetListFilterFlagState(t)
if err := listCmd.ParseFlags([]string{"--status", "all", "--status", "open"}); err != nil {
t.Fatalf("ParseFlags: %v", err)
}
in, err := gatherListInput(listCmd)
if err != nil {
t.Fatalf("gatherListInput: %v", err)
}
if in.Status != "all,open" {
t.Fatalf("unioned status = %q, want %q", in.Status, "all,open")
}
// The union is what makes this reachable: before this PR the repeat
// kept only "open" and the combination never reached the guard.
if _, err := workapi.BuildListFilter(in.ListRequest, workapi.ListConfig{}); err == nil {
t.Fatal("BuildListFilter accepted a union containing \"all\", want a refusal")
} else if !strings.Contains(err.Error(), "cannot be combined") {
t.Fatalf("BuildListFilter error = %v, want a \"cannot be combined\" refusal", err)
}
})
t.Run("--status outranks --state", func(t *testing.T) {
resetListFilterFlagState(t)
if err := listCmd.ParseFlags([]string{"--status", "open", "--state", "closed"}); err != nil {
t.Fatalf("ParseFlags: %v", err)
}
in, err := gatherListInput(listCmd)
if err != nil {
t.Fatalf("gatherListInput: %v", err)
}
if in.Status != "open" {
t.Fatalf("in.Status = %q, want %q (--state must not merge into a non-empty --status)", in.Status, "open")
}
})
}

View file

@ -43,6 +43,10 @@ type listInput struct {
func gatherListInput(cmd *cobra.Command) (listInput, error) {
in := listInput{}
// The custom filter values persist across in-process Execute() calls;
// clear them once this read has copied them out.
defer resetListFilterFlags(cmd.Flags())
in.Status, _ = cmd.Flags().GetString("status")
if in.Status == "" {
in.Status, _ = cmd.Flags().GetString("state")

View file

@ -917,22 +917,18 @@ func init() {
migrateCmd.Flags().Bool("dry-run", false, "Show what would be done without making changes")
migrateCmd.Flags().Bool("update-repo-id", false, "Update repository ID (use after changing git remote)")
migrateCmd.Flags().Bool("inspect", false, "Show migration plan and database state for AI agent analysis")
migrateCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output migration statistics in JSON format")
// --force bypasses the remote-migrate gate (#4259) as the single designated
// migrator. No -f shorthand: deliberate typing for a fork-risk bypass.
migrateCmd.Flags().Bool("force", false, "Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1)")
migrateSyncCmd.Flags().Bool("dry-run", false, "Show what would be done without making changes")
migrateSyncCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output in JSON format")
migrateCmd.AddCommand(migrateSyncCmd)
migrateHooksCmd.Flags().Bool("dry-run", false, "Show what would be done without making changes")
migrateHooksCmd.Flags().Bool("apply", false, "Apply planned hook migration changes")
migrateHooksCmd.Flags().Bool("yes", false, "Skip confirmation prompt for --apply")
migrateHooksCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output in JSON format")
migrateCmd.AddCommand(migrateHooksCmd)
migrateSchemaCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output in JSON format")
// --force on migrate schema mirrors the parent command's flag; both trip the
// same isForcedMigrate check in main.go's PersistentPreRunE.
migrateSchemaCmd.Flags().Bool("force", false, "Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1)")

View file

@ -17,18 +17,19 @@ import (
// TestFormatDBList removed: formatDBList and dbInfo types were removed.
func TestMigrateSchemaFlagBoundaries(t *testing.T) {
// Registration only: strict subprocess tests use the unique root persistent
// --format=json alias because duplicate local --json registration can shadow
// whether PersistentPreRunE sees the root flag as explicitly set.
// Registration only. --json must come from the root persistent flag: a
// local duplicate shadows it, so PersistentPreRunE never sees the root
// flag as explicitly set and resets jsonOutput from config.
for _, name := range []string{"inspect", "dry-run"} {
if flag := migrateSchemaCmd.Flags().Lookup(name); flag != nil {
t.Errorf("migrate schema unexpectedly registers local --%s", name)
}
}
for _, name := range []string{"json", "force"} {
if flag := migrateSchemaCmd.Flags().Lookup(name); flag == nil {
t.Errorf("migrate schema must register local --%s", name)
}
if f := migrateSchemaCmd.Flags().Lookup("json"); f != nil && f != rootCmd.PersistentFlags().Lookup("json") {
t.Error("migrate schema must not register a local --json; it inherits the root flag")
}
if flag := migrateSchemaCmd.Flags().Lookup("force"); flag == nil {
t.Error("migrate schema must register local --force")
}
if flag := rootCmd.PersistentFlags().Lookup("json"); flag == nil {
t.Error("root command must register persistent --json")

View file

@ -3,6 +3,7 @@ package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"os"
"os/exec"
@ -26,6 +27,13 @@ type CheckResult struct {
Warning bool `json:"warning,omitempty"`
Output string `json:"output,omitempty"`
Command string `json:"command"`
// Dir is the directory Command was resolved and run in. The --check probes
// do not all share one scope: lint and format run at the repository root
// while tests run in the caller's working directory, so a run started from
// a subdirectory mixes a repo-wide verdict with a subtree-only one.
// Reporting the directory keeps the two distinguishable and makes the
// reported command reproducible from somewhere other than the root.
Dir string `json:"dir,omitempty"`
}
// PreflightResult represents the overall preflight check results.
@ -60,16 +68,17 @@ Examples:
RunE: runPreflight,
}
const beadsPRLintDriverCommand = "go run -mod=readonly -tags=gms_pure_go ./scripts/pr-lint"
// lintCancellationGrace bounds how long Wait keeps reading the output pipe
// after the lint deadline fires. Descendants of the driver can hold the write
// end open indefinitely, so this is what turns the deadline into a real bound
// on the call rather than only on the direct child.
const lintCancellationGrace = 10 * time.Second
func init() {
preflightCmd.Flags().Bool("check", false, "Run checks automatically")
preflightCmd.Flags().Bool("fix", false, "Auto-fix issues where possible (vendorHash, version sync)")
// Bound to the package global like every other command's local --json.
// commandJSONFlagChanged suppresses the config-driven default whenever a
// local --json is set, so a flag that does not write the global would
// leave `bd preflight --json` with jsonOutput=false — inverting JSON mode
// for everything that reads the global, including the front-door error
// renderers.
preflightCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output results as JSON")
preflightCmd.Flags().Bool("skip-lint", false, "Skip lint check explicitly")
rootCmd.AddCommand(preflightCmd)
@ -97,12 +106,7 @@ func runPreflight(cmd *cobra.Command, args []string) error {
// Static checklist mode — tailor the checklist to the detected project
// stack so non-Go projects don't get a misleading Go/Nix checklist (GH#4364).
root := git.GetRepoRoot()
if root == "" {
if wd, err := os.Getwd(); err == nil {
root = wd
}
}
root := preflightProjectRoot()
fmt.Println("PR Readiness Checklist:")
fmt.Println()
@ -136,7 +140,7 @@ func buildPreflightChecklist(dir string) []string {
if isBeadsRepo(dir) {
return []string{
"Tests pass: go test -tags gms_pure_go -short ./...",
"Lint passes: golangci-lint run --build-tags=gms_pure_go ./...",
"Lint passes: make ci-pr-lint",
"Formatting: gofmt -l .",
"No beads pollution: check .beads/issues.jsonl diff",
"Nix hash current: go.sum unchanged or vendorHash updated",
@ -281,6 +285,9 @@ func runChecks(jsonOutput, skipLint bool) error {
fmt.Printf("✗ %s\n", r.Name)
}
fmt.Printf(" Command: %s\n", r.Command)
if r.Dir != "" {
fmt.Printf(" Directory: %s\n", r.Dir)
}
if r.Skipped && r.Output != "" {
fmt.Printf(" Reason: %s\n", r.Output)
} else if r.Warning && r.Output != "" {
@ -302,23 +309,45 @@ func runChecks(jsonOutput, skipLint bool) error {
return nil
}
// runTestCheck runs go test -short ./... and returns the result.
// runTestCheck runs go test -short ./... and returns the result. Unlike the
// lint and format checks it is deliberately left in the caller's working
// directory, so ./... stays the subtree the caller asked about; the reported
// Dir is what keeps that narrower scope visible beside the rooted checks.
func runTestCheck() CheckResult {
command := "go test -tags gms_pure_go -short ./..."
cmd := exec.Command("go", "test", "-tags", "gms_pure_go", "-short", "./...")
output, err := cmd.CombinedOutput()
dir, err2 := os.Getwd()
if err2 != nil {
dir = "."
}
return CheckResult{
Name: "Tests pass",
Passed: err == nil,
Output: string(output),
Command: command,
Dir: dir,
}
}
// runLintCheck runs golangci-lint and returns the result.
type lintInvocation struct {
display string
executable string
args []string
dir string
timeout time.Duration
}
// runLintCheck runs the checkout-owned Beads lint driver in the Beads source
// tree and retains a direct, generic golangci-lint check elsewhere.
func runLintCheck(skipLint bool) CheckResult {
command := "golangci-lint run --build-tags=gms_pure_go ./..."
return runLintCheckAt(preflightProjectRoot(), skipLint)
}
func runLintCheckAt(root string, skipLint bool) CheckResult {
invocation := lintInvocationForRoot(root)
if skipLint {
return CheckResult{
Name: "Lint passes",
@ -326,33 +355,86 @@ func runLintCheck(skipLint bool) CheckResult {
Skipped: true,
Warning: true,
Output: "lint check explicitly skipped by --skip-lint",
Command: command,
Command: invocation.display,
Dir: invocation.dir,
}
}
// Check if golangci-lint is available
if _, err := exec.LookPath("golangci-lint"); err != nil {
if _, err := exec.LookPath(invocation.executable); err != nil {
return CheckResult{
Name: "Lint passes",
Passed: false,
Output: "golangci-lint not found in PATH (install it or rerun with --skip-lint)",
Command: command,
Output: fmt.Sprintf("%s not found in PATH (install it or rerun with --skip-lint)", invocation.executable),
Command: invocation.display,
Dir: invocation.dir,
}
}
cmd := exec.Command("golangci-lint", "run", "--build-tags=gms_pure_go", "./...")
ctx, cancel := context.WithTimeout(context.Background(), invocation.timeout)
defer cancel()
// Cancellation targets the direct command. For the Beads go run invocation,
// it does not provide process-tree ownership: descendants may outlive it.
cmd := exec.CommandContext(ctx, invocation.executable, invocation.args...)
cmd.Dir = invocation.dir
// CombinedOutput collects through a pipe that every descendant inherits, so
// killing the direct child on deadline does not close the write end while a
// golangci-lint grandchild still holds it. Without a WaitDelay the deadline
// therefore cannot bound this call at all, and the message appended below
// never prints in the one case it exists to report.
cmd.WaitDelay = lintCancellationGrace
output, err := cmd.CombinedOutput()
// Report the deadline only when it actually decided the result: a child that
// wins the race exits cleanly just as the context expires, and that is a
// pass, not a timeout.
if err != nil && errors.Is(ctx.Err(), context.DeadlineExceeded) {
output = append(output, []byte(fmt.Sprintf("\nlint check exceeded %s", invocation.timeout))...)
}
return CheckResult{
Name: "Lint passes",
Passed: err == nil,
Output: string(output),
Command: command,
Command: invocation.display,
Dir: invocation.dir,
}
}
func lintInvocationForRoot(root string) lintInvocation {
if isBeadsRepo(root) {
return lintInvocation{
display: beadsPRLintDriverCommand,
executable: "go",
args: []string{"run", "-mod=readonly", "-tags=gms_pure_go", "./scripts/pr-lint"},
dir: root,
timeout: 13 * time.Minute,
}
}
return lintInvocation{
display: "golangci-lint run ./...",
executable: "golangci-lint",
args: []string{"run", "./..."},
dir: root,
timeout: 6 * time.Minute,
}
}
func preflightProjectRoot() string {
if root := git.GetRepoRoot(); root != "" {
return root
}
wd, err := os.Getwd()
if err != nil {
return "."
}
return wd
}
// runFmtCheck runs gofmt -l and fails if any files need formatting.
func runFmtCheck() CheckResult {
return runFmtCheckAt(preflightProjectRoot())
}
func runFmtCheckAt(root string) CheckResult {
command := "gofmt -l ."
// Check if gofmt is available
@ -362,10 +444,12 @@ func runFmtCheck() CheckResult {
Passed: false,
Output: "gofmt not found in PATH (install Go toolchain)",
Command: command,
Dir: root,
}
}
cmd := exec.Command("gofmt", "-l", ".")
cmd.Dir = root
output, err := cmd.CombinedOutput()
if err != nil {
@ -374,6 +458,7 @@ func runFmtCheck() CheckResult {
Passed: false,
Output: string(output),
Command: command,
Dir: root,
}
}
@ -384,6 +469,7 @@ func runFmtCheck() CheckResult {
Passed: false,
Output: fmt.Sprintf("Unformatted files:\n%s\nRun: gofmt -w .", unformatted),
Command: command,
Dir: root,
}
}
@ -391,6 +477,7 @@ func runFmtCheck() CheckResult {
Name: "Formatting",
Passed: true,
Command: command,
Dir: root,
}
}

View file

@ -1,9 +1,12 @@
package main
import (
"encoding/json"
"os"
"os/exec"
"path/filepath"
"reflect"
"runtime"
"strings"
"testing"
@ -224,58 +227,179 @@ func TestRunLintCheck_SkipLintFlag(t *testing.T) {
}
}
// gofmtForTest returns the gofmt to run: the one on PATH under go test, and
// under Bazel (no host toolchain) the Go SDK's, declared as data and named by
// BEADS_TEST_GOFMT.
func gofmtForTest(t *testing.T) string {
func TestLintInvocationForRootMatchesChecklistAndProjectType(t *testing.T) {
beads := writeMarkerDir(t, map[string]string{"go.mod": "module github.com/steveyegge/beads\n"})
beadsInvocation := lintInvocationForRoot(beads)
if beadsInvocation.display != beadsPRLintDriverCommand {
t.Fatalf("Beads command = %q, want %q", beadsInvocation.display, beadsPRLintDriverCommand)
}
if beadsInvocation.executable != "go" {
t.Fatalf("Beads executable = %q, want go", beadsInvocation.executable)
}
wantBeadsArgs := []string{"run", "-mod=readonly", "-tags=gms_pure_go", "./scripts/pr-lint"}
if !reflect.DeepEqual(beadsInvocation.args, wantBeadsArgs) {
t.Fatalf("Beads args = %#v, want %#v", beadsInvocation.args, wantBeadsArgs)
}
if beadsInvocation.dir != beads {
t.Fatalf("Beads command dir = %q, want %q", beadsInvocation.dir, beads)
}
if checklist := strings.Join(buildPreflightChecklist(beads), "\n"); !strings.Contains(checklist, "make ci-pr-lint") {
t.Fatalf("Beads checklist does not report supported lint entrypoint:\n%s", checklist)
}
generic := writeMarkerDir(t, map[string]string{"go.mod": "module example.com/generic\n"})
genericInvocation := lintInvocationForRoot(generic)
if genericInvocation.display != "golangci-lint run ./..." {
t.Fatalf("generic command = %q, want direct lint contract", genericInvocation.display)
}
if genericInvocation.executable != "golangci-lint" {
t.Fatalf("generic executable = %q, want golangci-lint", genericInvocation.executable)
}
if want := []string{"run", "./..."}; !reflect.DeepEqual(genericInvocation.args, want) {
t.Fatalf("generic args = %#v, want %#v", genericInvocation.args, want)
}
if checklist := strings.Join(buildPreflightChecklist(generic), "\n"); !strings.Contains(checklist, genericInvocation.display) {
t.Fatalf("generic checklist does not report executable lint command %q:\n%s", genericInvocation.display, checklist)
}
}
func TestRunLintCheckAtBeadsExecutesCheckoutDriverAndReportsJSONCommand(t *testing.T) {
helperDir := t.TempDir()
helperName := "go"
if runtime.GOOS == "windows" {
helperName += ".exe"
}
helperPath := filepath.Join(helperDir, helperName)
if bazeltest.IsBazel() {
fixture, err := bazeltest.RunfileEnv("BEADS_TEST_PREFLIGHT_GO")
if err != nil {
t.Fatal(err)
}
data, err := os.ReadFile(fixture)
if err != nil {
t.Fatal(err)
}
if err := os.WriteFile(helperPath, data, 0o755); err != nil {
t.Fatal(err)
}
} else {
realGo, err := exec.LookPath("go")
if err != nil {
t.Fatalf("locate Go toolchain for subprocess fixture: %v", err)
}
build := exec.Command(realGo, "build", "-o", helperPath, "testdata/preflight-go.go")
if output, err := build.CombinedOutput(); err != nil {
t.Fatalf("build fake Go executable: %v\n%s", err, output)
}
}
beads := writeMarkerDir(t, map[string]string{"go.mod": "module github.com/steveyegge/beads\n"})
marker := filepath.Join(t.TempDir(), "invocation.json")
t.Setenv("PATH", helperDir)
t.Setenv("PREFLIGHT_LINT_MARKER", marker)
result := runLintCheckAt(beads, false)
if !result.Passed {
t.Fatalf("checkout lint invocation failed: %s", result.Output)
}
if result.Command != beadsPRLintDriverCommand {
t.Fatalf("reported command = %q, want %q", result.Command, beadsPRLintDriverCommand)
}
if !strings.Contains(result.Output, "synthetic checkout lint success") {
t.Fatalf("missing subprocess output: %q", result.Output)
}
var invocation struct {
Args []string `json:"args"`
Dir string `json:"dir"`
}
markerData, err := os.ReadFile(marker)
if err != nil {
t.Fatalf("read invocation marker: %v", err)
}
if err := json.Unmarshal(markerData, &invocation); err != nil {
t.Fatalf("decode invocation marker: %v", err)
}
wantArgs := []string{"run", "-mod=readonly", "-tags=gms_pure_go", "./scripts/pr-lint"}
if !reflect.DeepEqual(invocation.Args, wantArgs) {
t.Fatalf("subprocess args = %#v, want %#v", invocation.Args, wantArgs)
}
if invocation.Dir != beads {
t.Fatalf("subprocess dir = %q, want checkout root %q", invocation.Dir, beads)
}
encoded, err := json.Marshal(result)
if err != nil {
t.Fatalf("marshal CheckResult: %v", err)
}
var reported CheckResult
if err := json.Unmarshal(encoded, &reported); err != nil {
t.Fatalf("unmarshal CheckResult: %v", err)
}
if reported.Command != beadsPRLintDriverCommand || !reported.Passed {
t.Fatalf("JSON evidence = %#v, want passing checkout driver command", reported)
}
}
// usePreflightGofmt preserves the SDK executable declared by the Bazel target
// while exercising the production PATH lookup in runFmtCheckAt.
func usePreflightGofmt(t *testing.T) {
t.Helper()
if !bazeltest.IsBazel() {
return "gofmt"
return
}
path, err := bazeltest.RunfileEnv("BEADS_TEST_GOFMT")
if err != nil {
t.Fatal(err)
}
return path
t.Setenv("PATH", filepath.Dir(path)+string(os.PathListSeparator)+os.Getenv("PATH"))
}
func TestRunFmtCheck_Formatted(t *testing.T) {
func TestRunFmtCheckAtFormattedRoot(t *testing.T) {
usePreflightGofmt(t)
dir := t.TempDir()
// Write a properly formatted Go file
err := os.WriteFile(filepath.Join(dir, "main.go"), []byte("package main\n\nfunc main() {}\n"), 0644)
if err != nil {
if err := os.WriteFile(filepath.Join(dir, "main.go"), []byte("package main\n\nfunc main() {}\n"), 0o644); err != nil {
t.Fatal(err)
}
// Run gofmt -l in the temp dir
cmd := exec.Command(gofmtForTest(t), "-l", ".")
cmd.Dir = dir
output, err := cmd.CombinedOutput()
if err != nil {
t.Fatalf("gofmt failed: %v: %s", err, output)
}
if strings.TrimSpace(string(output)) != "" {
t.Fatalf("expected no unformatted files, got: %s", output)
result := runFmtCheckAt(dir)
if !result.Passed {
t.Fatalf("formatted root failed: %s", result.Output)
}
}
func TestRunFmtCheck_Unformatted(t *testing.T) {
dir := t.TempDir()
// Write a poorly formatted Go file (extra spaces, no newline)
err := os.WriteFile(filepath.Join(dir, "bad.go"), []byte("package main\nfunc main( ) { }\n"), 0644)
if err != nil {
func TestRunFmtCheckAtFindsUnformattedFileOutsideCallerSubtree(t *testing.T) {
usePreflightGofmt(t)
root := t.TempDir()
callerDir := filepath.Join(root, "nested", "caller")
outsideCaller := filepath.Join(root, "sibling", "bad.go")
if err := os.MkdirAll(callerDir, 0o755); err != nil {
t.Fatal(err)
}
if err := os.MkdirAll(filepath.Dir(outsideCaller), 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(outsideCaller, []byte("package sibling\nfunc bad( ) { }\n"), 0o644); err != nil {
t.Fatal(err)
}
cmd := exec.Command(gofmtForTest(t), "-l", ".")
cmd.Dir = dir
output, _ := cmd.CombinedOutput()
unformatted := strings.TrimSpace(string(output))
if unformatted == "" {
t.Fatal("expected unformatted files to be listed")
originalDir, err := os.Getwd()
if err != nil {
t.Fatal(err)
}
if !strings.Contains(unformatted, "bad.go") {
t.Fatalf("expected bad.go in output, got: %s", unformatted)
if err := os.Chdir(callerDir); err != nil {
t.Fatal(err)
}
t.Cleanup(func() {
if err := os.Chdir(originalDir); err != nil {
t.Errorf("restore working directory: %v", err)
}
})
result := runFmtCheckAt(root)
if result.Passed {
t.Fatal("root formatting check passed despite unformatted sibling file")
}
if !strings.Contains(result.Output, "bad.go") {
t.Fatalf("root formatting check missed sibling file: %s", result.Output)
}
}
@ -420,30 +544,38 @@ func TestIsBeadsRepo(t *testing.T) {
}
}
// TestPreflightJSONFlagBindsGlobal pins both halves of preflight's --json
// binding, which is one flag serving two masters. Setting it must write the
// package global, or every jsonOutput reader (including the front-door refusal
// TestPreflightJSONInheritsRootFlag pins preflight's --json contract now that
// the command inherits the root persistent flag instead of registering a local
// copy. A local copy would shadow the inherited one and is what
// TestNoSubcommandShadowsRootJSONFlag forbids, so the first check rejects a
// local flag rather than requiring one.
//
// The binding this pins is unchanged, only re-keyed: the root flag is
// BoolVar'd to the same package global (main.go), so setting it must write
// jsonOutput, or every jsonOutput reader (including the front-door refusal
// renderers) stays in text mode while the user asked for JSON. Leaving it
// unset must report unchanged to commandJSONFlagChanged, which is what lets a
// config-file `json: true` reach preflight the way it reaches its siblings —
// a deliberate behavior change from the unbound shadow this replaced, and the
// reason the CHANGELOG calls it out.
// config-file `json: true` reach preflight the way it reaches its siblings.
//
// The last two subtests drive that config half rather than only asserting the
// negative direction. flag.Value.Set never sets Changed (only FlagSet.Set
// does), so the Changed==true branch of commandJSONFlagChanged needs its own
// case, and the behavior the CHANGELOG announces — configured `json: true`
// with no flag flipping jsonOutput — only happens inside
// refreshBoundCommandConfig, so it has to be driven through that function.
func TestPreflightJSONFlagBindsGlobal(t *testing.T) {
flag := preflightCmd.Flags().Lookup("json")
if flag == nil {
t.Fatal("preflight has no --json flag")
}
// case — driven through the root flag, which is the one an inheriting command
// now has — and the configured `json: true` with no flag flipping jsonOutput
// only happens inside refreshBoundCommandConfig, so it has to be driven
// through that function.
func TestPreflightJSONInheritsRootFlag(t *testing.T) {
rootJSON := preflightCmd.Root().PersistentFlags().Lookup("json")
if rootJSON == nil {
t.Fatal("root has no persistent --json flag")
}
// --json is inherited from rootCmd as a persistent flag; a local copy
// would shadow it (see TestNoSubcommandShadowsRootJSONFlag). Comparing
// against the root flag rather than requiring nil tolerates a sibling test
// having already merged the root persistent flags into this command's set.
if f := preflightCmd.Flags().Lookup("json"); f != nil && f != rootJSON {
t.Error("preflight must not register a local --json; it inherits the root flag")
}
// refreshBoundCommandConfig consults config only when neither --json nor
// its hidden --format alias was given, so this test owns that flag's
// Changed bit too.
@ -453,15 +585,13 @@ func TestPreflightJSONFlagBindsGlobal(t *testing.T) {
}
oldGlobal := jsonOutput
oldValue, oldChanged := flag.Value.String(), flag.Changed
oldRootChanged := rootJSON.Changed
oldValue, oldRootChanged := rootJSON.Value.String(), rootJSON.Changed
oldFormatChanged := rootFormat.Changed
// refreshBoundCommandConfig reapplies every config-backed default, not
// just json; restore the rest so this test cannot leak into siblings.
oldReadonly, oldActor, oldAutoCommit := readonlyMode, actor, doltAutoCommit
t.Cleanup(func() {
_ = flag.Value.Set(oldValue)
flag.Changed = oldChanged
_ = rootJSON.Value.Set(oldValue)
rootJSON.Changed = oldRootChanged
rootFormat.Changed = oldFormatChanged
jsonOutput = oldGlobal
@ -469,9 +599,9 @@ func TestPreflightJSONFlagBindsGlobal(t *testing.T) {
config.ResetForTesting()
})
t.Run("flag writes the package global", func(t *testing.T) {
t.Run("inherited flag writes the package global", func(t *testing.T) {
jsonOutput = false
if err := flag.Value.Set("true"); err != nil {
if err := rootJSON.Value.Set("true"); err != nil {
t.Fatal(err)
}
if !jsonOutput {
@ -480,7 +610,6 @@ func TestPreflightJSONFlagBindsGlobal(t *testing.T) {
})
t.Run("neither flag set reports unchanged", func(t *testing.T) {
flag.Changed = false
rootJSON.Changed = false
if commandJSONFlagChanged(preflightCmd) {
t.Fatal("preflight reported an explicit --json with neither flag set; the config-file json default would never apply")
@ -488,9 +617,8 @@ func TestPreflightJSONFlagBindsGlobal(t *testing.T) {
})
t.Run("explicit --json reports changed", func(t *testing.T) {
flag.Changed = false
rootJSON.Changed = false
if err := preflightCmd.Flags().Set("json", "true"); err != nil {
if err := preflightCmd.Root().PersistentFlags().Set("json", "true"); err != nil {
t.Fatal(err)
}
if !commandJSONFlagChanged(preflightCmd) {
@ -505,7 +633,6 @@ func TestPreflightJSONFlagBindsGlobal(t *testing.T) {
}
config.Set("json", true)
flag.Changed = false
rootJSON.Changed = false
rootFormat.Changed = false
jsonOutput = false

View file

@ -298,6 +298,11 @@ func primeWorkspaceDir() string {
//
// NOTE: the probes built here are not prime-only — see primeHasGitRemote for
// the auto-backup consumer that inherits this directory choice.
//
// NOTE: since GH#4927 every return path pairs with a nil error — the
// GetRepoContext() failure falls back to a cwd probe instead of propagating —
// so the err != nil arms at both call sites are unreachable today. The error
// result is retained for future callers that can genuinely fail.
func primeGitCmd(ctx context.Context, args ...string) (*exec.Cmd, error) {
if ws := primeWorkspaceDir(); ws != "" {
cmd := exec.CommandContext(ctx, "git", args...)
@ -306,7 +311,14 @@ func primeGitCmd(ctx context.Context, args ...string) (*exec.Cmd, error) {
}
rc, err := internalbeads.GetRepoContext()
if err != nil {
return nil, err
// GH#4927: an unusable BEADS_DIR must not be reported as "no git
// remote" / "ephemeral branch". An external BEADS_DIR under another
// account's home (common in agent sandboxes) makes buildRepoContext
// fail, but the process cwd is frequently a perfectly good git
// workspace, so probe it directly instead of giving up. The SEC-003
// boundary on BEADS_DIR stays enforced by the callers that consume
// BEADS_DIR itself; these probes only ask git about its own workspace.
return exec.CommandContext(ctx, "git", args...), nil
}
return rc.GitCmdCWD(ctx, args...), nil
}
@ -372,7 +384,9 @@ func isMCPActive() bool {
return false
}
// isEphemeralBranch detects if current branch has no upstream (ephemeral/local-only)
// isEphemeralBranch detects if current branch has no upstream (ephemeral/local-only).
// Runs through primeGitCmd, so it honors -C (#5509) and still falls back to the
// process CWD git workspace when BEADS_DIR is unusable (GH#4927).
var isEphemeralBranch = func() bool {
// git rev-parse --abbrev-ref --symbolic-full-name @{u}
// Returns error code 128 if no upstream configured
@ -405,6 +419,13 @@ var primeAgentProfile = func() config.AgentProfile {
// remote rather than the cwd's (#5509). That is the consistent answer, because
// the store being backed up is the -C-resolved one, but it is a behavior
// change beyond prime: check backup_auto before changing what this probes.
//
// GH#4927: this must not require a valid RepoContext / BEADS_DIR. An external
// BEADS_DIR under another account's home (common in agent sandboxes) fails to
// build a RepoContext and must not be misreported as "no git remote" when
// `git remote` in the workspace succeeds. primeGitCmd supplies that fallback,
// which keeps the -C behavior above intact. The SEC-003 boundary on BEADS_DIR
// remains enforced elsewhere.
var primeHasGitRemote = func() bool {
cmd, err := primeGitCmd(context.Background(), "remote")
if err != nil {
@ -417,6 +438,31 @@ var primeHasGitRemote = func() bool {
return len(strings.TrimSpace(string(out))) > 0
}
// gitCWDHasRemote reports whether the process CWD git repo has any remote.
// Delegates to gitDirHasRemote (no BEADS_DIR coupling). It is the
// BEADS_DIR-independent primitive the GH#4927 regression test drives directly,
// alongside primeHasGitRemote.
//
// This pair is a test-only oracle with no production callers: the production
// probes build their own command in primeGitCmd.
func gitCWDHasRemote() bool {
return gitDirHasRemote("")
}
// gitDirHasRemote reports whether the git repo at dir has any remote
// configured. dir == "" runs git in the process's current working directory
// (this is what gitCWDHasRemote uses); a non-empty dir lets tests probe an
// explicit fixture repo without chdir-ing the whole process.
func gitDirHasRemote(dir string) bool {
cmd := exec.Command("git", "remote")
cmd.Dir = dir
out, err := cmd.Output()
if err != nil {
return false
}
return len(strings.TrimSpace(string(out))) > 0
}
// primeHasSyncRemote detects if a Dolt sync remote is configured (stubbable for tests)
var primeHasSyncRemote = func() bool {
return resolveSyncRemote() != ""

View file

@ -0,0 +1,110 @@
package main
import (
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/git"
)
// GH#4927: prime's git probes must not depend on BEADS_DIR / RepoContext.
//
// buildRepoContext (internal/beads/context.go) can fail when FindBeadsDir()
// returns "" (context.go:107, e.g. BEADS_DIR doesn't exist). The pre-fix bug
// collapsed that GetRepoContext() error into "no git remote" / "ephemeral
// branch". This test poisons BEADS_DIR with a nonexistent path and verifies
// (a) that GetRepoContext() actually fails via FindBeadsDir()=="", and (b)
// that both probes the fix repairs -- primeHasGitRemote and isEphemeralBranch
// -- are unaffected by it.
//
// The probe assertions below use t.Error rather than t.Fatal so a regression
// in one probe does not mask the state of the others.
func TestPrimeGitProbes_IndependentOfBeadsDir(t *testing.T) {
dir := t.TempDir()
run := func(args ...string) {
t.Helper()
cmd := exec.Command(args[0], args[1:]...)
cmd.Dir = dir
if out, err := cmd.CombinedOutput(); err != nil {
t.Fatalf("%v: %v\n%s", args, err, out)
}
}
run("git", "init", "-q")
run("git", "config", "user.name", "fixture")
run("git", "config", "user.email", "fixture@example.com")
run("git", "config", "commit.gpgsign", "false")
// gitDirHasRemote is the test-only oracle described in prime.go; these two
// assertions check that the fixture itself is built correctly, not the fix.
if gitDirHasRemote(dir) {
t.Fatal("expected no remote after init")
}
run("git", "remote", "add", "origin", "https://example.invalid/repo.git")
if !gitDirHasRemote(dir) {
t.Fatal("expected remote after git remote add origin")
}
// A committed branch that has a remote but no upstream -- the state in
// which the branch genuinely is ephemeral. The fixed branch name avoids
// depending on init.defaultBranch.
run("git", "commit", "-q", "--allow-empty", "-m", "fixture")
run("git", "checkout", "-q", "-B", "fixture-branch")
t.Cleanup(func() {
beads.ResetCaches()
git.ResetCaches()
})
// CWD-based probe: chdir into the fixture repo
wd, err := os.Getwd()
if err != nil {
t.Fatal(err)
}
if err := os.Chdir(dir); err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = os.Chdir(wd) })
// BEADS_DIR points at a path that simply doesn't exist on disk — this is
// the FindBeadsDir()=="" failure mode (context.go:107). CWD is the
// fixture repo (no .beads anywhere in its ancestry), so the walk in
// FindBeadsDir also comes up empty.
t.Setenv("BEADS_DIR", filepath.Join(dir, "does-not-exist", ".beads"))
beads.ResetCaches()
git.ResetCaches()
if _, err := beads.GetRepoContext(); err == nil || !strings.Contains(err.Error(), "no .beads directory found") {
t.Fatalf("expected GetRepoContext() to fail via FindBeadsDir()==\"\", got err=%v", err)
}
if !gitCWDHasRemote() {
t.Error("gitCWDHasRemote should see origin even with a nonexistent BEADS_DIR set")
}
// The two probes the fix actually repairs. Both route through primeGitCmd,
// so both regress if its GetRepoContext() fallback is removed.
if !primeHasGitRemote() {
t.Error("primeHasGitRemote should see origin even with a nonexistent BEADS_DIR set")
}
// isEphemeralBranch, both polarities under the same poisoned BEADS_DIR.
// The branch has no upstream yet, so "ephemeral" is the correct answer
// here; this control is what proves the assertion below is reading git
// rather than returning a constant.
if !isEphemeralBranch() {
t.Error("isEphemeralBranch should report ephemeral while the branch has no upstream")
}
// Configure a real upstream -- entirely local, the remote is never
// contacted -- and the same probe must flip. Pre-fix it stayed true here,
// because the GetRepoContext() failure was itself reported as "ephemeral".
run("git", "update-ref", "refs/remotes/origin/fixture-branch", "HEAD")
run("git", "branch", "--set-upstream-to=origin/fixture-branch", "fixture-branch")
if isEphemeralBranch() {
t.Error("isEphemeralBranch should see the configured upstream even with a nonexistent BEADS_DIR set")
}
}

View file

@ -476,10 +476,6 @@ func init() {
repoCmd.AddCommand(repoListCmd)
repoCmd.AddCommand(repoSyncCmd)
repoAddCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output JSON")
repoRemoveCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output JSON")
repoListCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output JSON")
repoSyncCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output JSON")
repoSyncCmd.Flags().Bool("verbose", false, "Show detailed sync progress")
rootCmd.AddCommand(repoCmd)

View file

@ -176,7 +176,6 @@ func issueContentSize(issue *types.Issue) int {
}
func init() {
restoreCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output restore results in JSON format")
restoreCmd.Flags().BoolVar(&restoreApply, "apply", false, "Write the restored content back into the issue (default: display only)")
rootCmd.AddCommand(restoreCmd)
}

View file

@ -4,6 +4,7 @@ package main
import (
"context"
"encoding/json"
"fmt"
"os"
"os/exec"
@ -13,6 +14,7 @@ import (
"time"
"github.com/steveyegge/beads/internal/storage/embeddeddolt"
"github.com/steveyegge/beads/internal/types"
)
// bdRestore runs "bd restore" with extra args. Returns combined output.
@ -145,12 +147,16 @@ func TestEmbeddedRestore(t *testing.T) {
dir, beadsDir, _ := bdInit(t, bd, "--prefix", "rstjs")
id := simulateCompaction(t, bd, dir, beadsDir, "rstjs")
// NOTE: bd restore has a known issue where its local --json flag
// conflicts with the root command's --json persistent flag.
// Just verify the command runs successfully.
out := bdRestore(t, bd, dir, id)
if !strings.Contains(out, "long description") {
t.Errorf("expected restored description in output, got: %s", out)
out := bdRestore(t, bd, dir, id, "--json")
var restored types.Issue
if err := json.Unmarshal([]byte(out), &restored); err != nil {
t.Fatalf("bd restore --json must print a JSON issue, got error %v:\n%s", err, out)
}
if restored.ID != id {
t.Errorf("expected restored issue %s, got %q", id, restored.ID)
}
if !strings.Contains(restored.Description, "long description") {
t.Errorf("expected restored description in JSON, got: %q", restored.Description)
}
})
}

View file

@ -192,6 +192,37 @@ func TestProxiedServerServeBatchClose(t *testing.T) {
}
})
// The per-item twin of the single close's blocker-naming proof: the refused
// item carries its blockers, and its detail opens with the sentence `bd
// close` records for the same refusal.
t.Run("a blocked item names its blockers as the CLI does", func(t *testing.T) {
blocker := bdProxiedCreate(t, bd, p.dir, "a batch blocker", "-p", "1")
blocked := bdProxiedCreate(t, bd, p.dir, "a blocked batch item", "-p", "1")
if out, err := bdProxiedRun(t, bd, p.dir, "dep", "add", blocked.ID, blocker.ID); err != nil {
t.Fatalf("bd dep add: %v\n%s", err, out)
}
status, body := sp.batchClose(t, `{"actor":"http-agent","items":[{"id":"`+blocked.ID+`"}]}`)
if status != http.StatusOK {
t.Fatalf("status = %d, want 200: %v", status, body)
}
outcome := batchCloseOutcomes(t, body)[0]
if outcome["code"] != "not_closable" {
t.Fatalf("code = %v, want not_closable: %v", outcome["code"], outcome)
}
got, err := json.Marshal(outcome["blockers"])
if err != nil {
t.Fatalf("re-encode blockers: %v", err)
}
if want := `[{"id":"` + blocker.ID + `","kind":"local","type":"blocks"}]`; string(got) != want {
t.Errorf("blockers = %s, want %s", got, want)
}
cli := bdProxiedCloseFailedError(t, bd, p.dir, blocked.ID)
if want := cli + "; clear the blocker, or send `force`"; outcome["detail"] != want {
t.Errorf("detail = %q, want the CLI's failed[].error %q plus the HTTP hint", outcome["detail"], cli)
}
})
// A refused BODY means the batch never ran, which is the other half of the
// contract: nothing may be written by a request that earned a problem
// document.

View file

@ -471,9 +471,80 @@ func TestProxiedServerServeClose(t *testing.T) {
}
})
// THE BLOCKER-NAMING PROOF, against the CLI's own sentence. A live blocker
// refuses with a `blockers` member read from the refusing check's typed
// list, and `detail` opens with exactly what `bd close` records in
// failed[].error for the same refusal — so an HTTP client can render the
// direct route's message instead of an anonymous "blocked".
t.Run("a live blocker refusal names its blockers as the CLI does", func(t *testing.T) {
blocker := bdProxiedCreate(t, bd, p.dir, "the blocker", "-p", "1")
local := bdProxiedCreate(t, bd, p.dir, "blocked locally", "-p", "1")
if out, err := bdProxiedRun(t, bd, p.dir, "dep", "add", local.ID, blocker.ID); err != nil {
t.Fatalf("bd dep add: %v\n%s", err, out)
}
external := bdProxiedCreate(t, bd, p.dir, "blocked externally", "-p", "1")
const ref = "external:remote:payments"
if out, err := bdProxiedRun(t, bd, p.dir, "dep", "add", external.ID, ref); err != nil {
t.Fatalf("bd dep add external: %v\n%s", err, out)
}
for _, tc := range []struct {
id string
want string
}{
{local.ID, `[{"id":"` + blocker.ID + `","kind":"local","type":"blocks"}]`},
{external.ID, `[{"id":"` + ref + `","kind":"external"}]`},
} {
status, body := sp.closeIssue(t, tc.id, `{"actor":"http-agent"}`)
if status != http.StatusConflict || body["code"] != "not_closable" {
t.Fatalf("close %s: status = %d code = %v, want 409 not_closable: %v", tc.id, status, body["code"], body)
}
if _, present := body["open_children"]; present {
t.Errorf("close %s: open_children on the blocker refusal: %v", tc.id, body)
}
got, err := json.Marshal(body["blockers"])
if err != nil {
t.Fatalf("re-encode blockers: %v", err)
}
if string(got) != tc.want {
t.Errorf("close %s: blockers = %s, want %s", tc.id, got, tc.want)
}
cli := bdProxiedCloseFailedError(t, bd, p.dir, tc.id)
if want := cli + "; clear the blocker or close with force"; body["detail"] != want {
t.Errorf("close %s: detail = %q, want the CLI's failed[].error %q plus the HTTP hint", tc.id, body["detail"], cli)
}
}
})
sp.shutdown(t)
}
// bdProxiedCloseFailedError runs an unforced `bd close --json` of id that must
// be refused and returns the failed[].error it reports for id — the
// route-independent spelling of the refusal (see assertCloseFailedErrorIsTyped).
// A closable companion rides along because the failure report is the
// partial-batch shape: a lone refused id prints no failed[] array.
func bdProxiedCloseFailedError(t *testing.T, bd, dir, id string) string {
t.Helper()
companion := bdProxiedCreate(t, bd, dir, "closable companion", "-p", "2")
stdout, stderr, err := bdProxiedRunBuffers(t, bd, dir, "close", "--json", companion.ID, id)
if err == nil {
t.Fatalf("bd close %s succeeded; it must be refused\nstdout:\n%s", id, stdout)
}
var report struct {
Failed []struct {
ID string `json:"id"`
Error string `json:"error"`
} `json:"failed"`
}
line := lastJSONObjectLine(stderr)
if jsonErr := json.Unmarshal([]byte(line), &report); jsonErr != nil || len(report.Failed) != 1 || report.Failed[0].ID != id {
t.Fatalf("bd close %s failure report = %+v (%v)\nstderr:\n%s", id, report, jsonErr, stderr)
}
return report.Failed[0].Error
}
// bdProxiedCloseOneRaw runs `bd close --json` and decodes the one item it
// reports as a generic object rather than into types.Issue: the parity oracle
// compares the JSON both surfaces actually emit, and decoding through the

View file

@ -11,6 +11,7 @@ import (
"github.com/steveyegge/beads/internal/hooks"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/domain"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/issueops"
"github.com/steveyegge/beads/memoryops"
)
@ -113,6 +114,8 @@ func TestServeIssueRolesComeFromBeneathTheHookDecorator(t *testing.T) {
}
inner := stubs(nil)
middle := stubs(inner)
policyReadErr := errors.New("external dependency lookup failed")
middle.dependencyReadErr = policyReadErr
chained := wireStorageDecorators(middle, hooks.NewRunner(t.TempDir()), false)
if _, ok := chained.(*storage.HookFiringStore); !ok {
@ -232,8 +235,17 @@ func TestServeIssueRolesComeFromBeneathTheHookDecorator(t *testing.T) {
if storage.RoleFiresHooks(roles.readyClaimer) {
t.Error("bd serve would run this workspace's hooks on every HTTP ready claim")
}
if storage.RoleFiresHooks(roles.batchCloser) || roles.batchCloser != issueops.BatchCloser(middle.batchCloser) {
t.Errorf("batch closer came from %p, want the layer directly beneath the hooks (%p)", roles.batchCloser, middle.batchCloser)
if storage.RoleFiresHooks(roles.batchCloser) {
t.Error("bd serve would run this workspace's hooks on every HTTP batch close")
}
// A failed external-policy lookup must still refuse the served close.
// Peeling away that policy would reach the raw stub's ErrUnsupported instead.
_, err = roles.batchCloser.CloseBatch(context.Background(), issueops.CloseBatchRequest{
Actor: "serve-test",
Items: []issueops.BatchCloseItem{{IssueID: "bd-blocked"}},
})
if !errors.Is(err, policyReadErr) {
t.Errorf("served batch closer lost external policy: got %v, want %v", err, policyReadErr)
}
if storage.RoleFiresHooks(roles.batchCreator) || roles.batchCreator != issueops.BatchCreator(middle.batchCreator) {
t.Errorf("batch creator came from %p, want the layer directly beneath the hooks (%p)", roles.batchCreator, middle.batchCreator)
@ -419,6 +431,11 @@ var _ serveRoleSource = (*serveRolesStore)(nil)
type serveRolesDoltStore struct {
*serveRolesStore
serveStubRest
dependencyReadErr error
}
func (s *serveRolesDoltStore) GetAllDependencyRecords(context.Context) (map[string][]*types.Dependency, error) {
return nil, s.dependencyReadErr
}
// serveStubRest carries the remainder of storage.DoltStorage for a stub that

View file

@ -193,7 +193,13 @@ var showCmd = &cobra.Command{
// so hoisting the read decorates the header and the meta block
// without a second query. Best effort, as it always was: a failed
// read renders the issue undecorated rather than not at all.
depsWithMeta, _ := issueStore.GetDependenciesWithMetadata(ctx, issue.ID)
//
// Counts first — see readDepCounts for why the order matters. The
// listing's error is KEPT, not discarded: rendering stays best
// effort, but a FAILED listing and a SHORT one both leave the
// slice empty, and only the second is an unresolvable edge.
depCountsSnapshot := readDepCounts(ctx, issueStore, issue.ID)
depsWithMeta, depsErr := issueStore.GetDependenciesWithMetadata(ctx, issue.ID)
gates := types.GatesHolding(issue, depsWithMeta)
if idx > 0 {
@ -245,7 +251,7 @@ var showCmd = &cobra.Command{
}
// Show dependents - grouped by dependency type for clarity
dependentsWithMeta, _ := issueStore.GetDependentsWithMetadata(ctx, issue.ID) // Best effort: show issue even if dependents unavailable
dependentsWithMeta, dependentsErr := issueStore.GetDependentsWithMetadata(ctx, issue.ID) // Best effort: show issue even if dependents unavailable
for _, sec := range groupDepSections(dependentsWithMeta, false, relatedSeen) {
printDepSection(sec)
if sec.Type == types.DepParentChild && issue.IssueType == types.TypeEpic {
@ -253,6 +259,16 @@ var showCmd = &cobra.Command{
}
}
// Both listings above drop every edge whose far end has no row in
// this database, so a cross-repo or `external:` dependency renders
// as no dependency at all — indistinguishable from having none
// (be-lpi). --json says so in unresolvable_dependencies; say it
// here too, or `bd dep add x liveop-y` reports success and then
// `bd show x` shows nothing.
warnUnresolvableDepEdges(issue.ID, depCountsSnapshot,
depListing{rows: len(depsWithMeta), err: depsErr},
depListing{rows: len(dependentsWithMeta), err: dependentsErr})
printRelatedSection(relatedSeen)
// Show comments

View file

@ -2,6 +2,7 @@ package main
import (
"context"
"errors"
"fmt"
"os"
"os/signal"
@ -159,17 +160,28 @@ func displayShowIssueReturn(ctx context.Context, issueID string) *types.Issue {
// Dependencies (what this issue depends on)
relatedSeen := make(map[string]*types.IssueWithDependencyMetadata)
depsWithMeta, _ := issueStore.GetDependenciesWithMetadata(ctx, issue.ID)
// Counts first — see readDepCounts for why the order matters.
depCountsSnapshot := readDepCounts(ctx, issueStore, issue.ID)
depsWithMeta, depsErr := issueStore.GetDependenciesWithMetadata(ctx, issue.ID)
for _, sec := range groupDepSections(depsWithMeta, true, relatedSeen) {
printDepSection(sec)
}
// Dependents (what depends on this issue)
dependentsWithMeta, _ := issueStore.GetDependentsWithMetadata(ctx, issue.ID)
dependentsWithMeta, dependentsErr := issueStore.GetDependentsWithMetadata(ctx, issue.ID)
for _, sec := range groupDepSections(dependentsWithMeta, false, relatedSeen) {
printDepSection(sec)
}
// Shared with the non-watch path in show.go and with proxiedRenderIssue in
// show_proxied_server.go, so all THREE text renders of `bd show` disclose
// the same fact (be-lpi). --refs and --children are deliberately out of
// scope: they answer an alternate query with no count beside it to
// contradict.
warnUnresolvableDepEdges(issue.ID, depCountsSnapshot,
depListing{rows: len(depsWithMeta), err: depsErr},
depListing{rows: len(dependentsWithMeta), err: dependentsErr})
// Related (bidirectional, deduplicated)
printRelatedSection(relatedSeen)
@ -189,3 +201,127 @@ func displayShowIssueReturn(ctx context.Context, issueID string) *types.Issue {
fmt.Println()
return issue
}
// unresolvableDepCounter is the slice of the store warnUnresolvableDepEdges
// reads. Both counts are O(1) aggregate queries over the dependency tables.
// depListing is one direction's rendered edge list: how many rows reached the
// screen, and whether the read that produced them succeeded. The error is the
// load-bearing half — a failed read and a genuinely short one are both an
// empty slice, and only the second means an edge could not be represented.
type depListing struct {
rows int
err error
}
// depCount is one direction's aggregate, carried with its own error for the
// same reason depListing is.
type depCount struct {
n int64
err error
}
type depCounts struct {
deps depCount
dependents depCount
}
var errNoDepCounter = errors.New("no dependency counter available")
type unresolvableDepCounter interface {
CountDependencies(ctx context.Context, issueID string) (int64, error)
CountDependents(ctx context.Context, issueID string) (int64, error)
}
// readDepCounts and warnUnresolvableDepEdges are split so the COUNTS ARE READ
// BEFORE THE ROW LISTINGS, which all three call sites do. The store issues a
// connection per call, so a concurrent write can land between the count and the
// listing; counting first puts that skew on the safe side, because an edge
// ADDED in the window leaves the count stale-LOW and the difference goes
// negative and is suppressed. Counting afterwards would announce a freshly
// added local edge as unresolvable. A concurrent DELETE still produces a
// spurious notice — the residual, and the reason this is an ordering mitigation
// rather than a fix (be-lpi; the real fix is a shared snapshot or a direct
// count of edges whose target has no row).
//
// SCOPE OF THAT ORDER, because the split is easy to read as more than it is:
// it makes the order VISIBLE at the call sites, and does not enforce it.
// Nothing in this package fails if a later edit moves a readDepCounts call
// below its listings — measured, not assumed: moving it in all three of
// show.go, show_display.go and show_proxied_server.go leaves the whole cmd/bd
// selector green, including the embedded production-path test and the proxied
// integration test, because the unit test drives
// warnUnresolvableDepEdges directly and no CLI test can land a write inside
// the window. The only automated pin is one tier down, on
// TestBuildIssueDetails_ConcurrentAddIsNotReportedAsUnresolvable, which covers
// BuildIssueDetails rather than these three renders. Treat the order here as a
// convention carried by this comment.
//
// warnUnresolvableDepEdges prints a stderr-only notice when an issue has
// dependency edges that the rendered listings could not show.
//
// GetDependenciesWithMetadata and GetDependentsWithMetadata answer with the
// ISSUES on the far end of each edge and skip any whose id has no row in this
// database — a cross-repo id or an `external:` reference, both of which live
// in depends_on_external, the one target column carrying no foreign key into
// issues (issueops.IsExternalDepTarget). The count queries have no such join,
// so they keep those edges. The difference is exactly the set of edges that
// are real, stored, and unrenderable from here.
//
// Until be-lpi this difference was silent, and `bd dep add x liveop-y`
// reported success while the `bd show x` a caller ran straight after showed
// no dependency at all — indistinguishable from the edge never having been
// written. The JSON detail view publishes the same fact as
// unresolvable_dependencies / unresolvable_dependents.
//
// stderr only, so the rendered issue on stdout is byte-identical for the
// common fully-local case — the same choice warnDroppedDepEdges makes in
// dep.go for the same reason. Best effort: a count error is swallowed, since
// the issue has already been rendered successfully by the time this runs.
func readDepCounts(ctx context.Context, store unresolvableDepCounter, issueID string) depCounts {
if store == nil {
return depCounts{deps: depCount{err: errNoDepCounter}, dependents: depCount{err: errNoDepCounter}}
}
var c depCounts
c.deps.n, c.deps.err = store.CountDependencies(ctx, issueID)
c.dependents.n, c.dependents.err = store.CountDependents(ctx, issueID)
return c
}
func warnUnresolvableDepEdges(issueID string, counts depCounts, deps, dependents depListing) {
report := func(kind string, count int64, countErr error, listing depListing) bool {
// BOTH reads have to have succeeded. The count alone cannot tell a
// SHORT listing from a FAILED one — each leaves an empty slice — and
// warning on the second turns a transient backend error into a claim
// about the data, which is the more expensive of the two mistakes.
if countErr != nil || listing.err != nil {
return false
}
missing := count - int64(listing.rows)
if missing <= 0 {
return false
}
fmt.Fprintf(os.Stderr, "warning: %s has %d %s edge(s) whose far end has no row in this database (cross-repo/external) and are not shown above\n",
issueID, missing, kind)
return true
}
outbound := report("dependency", counts.deps.n, counts.deps.err, deps)
inbound := report("dependent", counts.dependents.n, counts.dependents.err, dependents)
// The recovery pointer is OUTBOUND-ONLY, because the command it names is.
// `bd dep list <id> <id>` reaches raw edge records through the duplicate-id
// form, which dep.go:1101 selects on `batchMode && direction == "down"`
// (--direction defaults to "down"); the other branch is the Relations
// query, which has the very far-end gap being reported here. dep.go:1144
// records in the repo's own words that "up" has the same gap and no
// inbound EdgeReader role exists to close it. Printing the pointer for an
// issue short only on DEPENDENT edges would hand the reader a command that
// cannot show them, so that case says what is actually true instead.
if outbound {
// Named once, after both directions, so an issue short on each gets
// one pointer rather than two.
fmt.Fprintf(os.Stderr, "For raw edge records, run: bd dep list %s %s\n", issueID, issueID)
}
if inbound {
fmt.Fprintln(os.Stderr, "The unrenderable dependent edges have no raw CLI listing yet: bd dep list is outbound-only.")
}
}

View file

@ -430,6 +430,58 @@ func TestProxiedServerShow2(t *testing.T) {
}
})
// be-lpi ROUTE COVERAGE. `bd show` has three text renders and this is the
// one a server-backed repo actually takes: usesProxiedServer() returns at
// show.go:45 before any of the direct path, and the shared issueops.Reader
// that carries unresolvable_dependencies is bound only for --json, so
// without an explicit call in proxiedRenderIssue plain text renders a
// cross-repo edge as no dependency at all — the exact symptom the change
// exists to remove, surviving on the route most exposed to it. The
// precedent this design follows, warnDroppedDepEdges, covers both of its
// own routes (dep.go:1148 and dep_proxied_server.go:457).
t.Run("show_discloses_unresolvable_dep_edges", func(t *testing.T) {
t.Parallel()
p := newSharedProxiedProject(t, bd, "sud")
subject := bdProxiedCreate(t, bd, p.dir, "Subject with a cross-repo edge", "--type", "task")
bdProxiedDep(t, bd, p.dir, "add", subject.ID, "liveop-kmf", "--type", "blocks")
stdout, stderr, err := bdProxiedRunBuffers(t, bd, p.dir, "show", subject.ID)
if err != nil {
t.Fatalf("bd show failed: %v\nstdout:\n%s\nstderr:\n%s", err, stdout, stderr)
}
if !strings.Contains(stderr, "no row in this database") {
t.Errorf("proxied bd show did not disclose the unrenderable edge:\nstderr:\n%s", stderr)
}
// Same contract as the direct route: stdout stays byte-identical for
// scripts, so assert on the streams apart or this passes on a build
// that prints the notice in the wrong place.
if strings.Contains(stdout, "no row in this database") {
t.Errorf("the notice reached stdout, which must stay unchanged:\n%s", stdout)
}
})
// The negative control for the case above, and the load-bearing half:
// without it every assertion there is satisfied by a build that warns
// unconditionally.
t.Run("show_stays_silent_on_a_fully_local_edge", func(t *testing.T) {
t.Parallel()
p := newSharedProxiedProject(t, bd, "sul")
blocker := bdProxiedCreate(t, bd, p.dir, "Local blocker", "--type", "task")
subject := bdProxiedCreate(t, bd, p.dir, "Fully local subject", "--type", "task")
bdProxiedDep(t, bd, p.dir, "add", subject.ID, blocker.ID, "--type", "blocks")
stdout, stderr, err := bdProxiedRunBuffers(t, bd, p.dir, "show", subject.ID)
if err != nil {
t.Fatalf("bd show failed: %v\nstdout:\n%s\nstderr:\n%s", err, stdout, stderr)
}
if strings.Contains(stderr, "no row in this database") {
t.Errorf("proxied bd show warned about a fully local edge:\nstderr:\n%s", stderr)
}
if !strings.Contains(stdout, blocker.ID) {
t.Errorf("expected the local dependency rendered on stdout:\n%s", stdout)
}
})
t.Run("show_not_found_json_envelope", func(t *testing.T) {
t.Parallel()
p := newSharedProxiedProject(t, bd, "snj")

View file

@ -162,6 +162,31 @@ func proxiedListDeps(ctx context.Context, uw uow.UnitOfWork, id string, isWisp b
return uw.DependencyUseCase().ListWithIssueMetadata(ctx, id, filter)
}
// proxiedDepCounter adapts the detail source's dependency aggregates onto
// unresolvableDepCounter, which the direct route satisfies with the store and
// which therefore carries no isWisp flag: the store seam resolves that routing
// internally, while the domain use cases behind a proxied unit of work are
// per-table and have to be told which side to read.
//
// The two queries are the same arithmetic either way — CountDependencyEdgesInTx
// counts `dependencies` plus `wisp_dependencies` with no join to `issues`,
// while the listing behind proxiedListDeps runs the very
// GetDependenciesWithMetadataInTx / GetDependentsWithMetadataInTx the direct
// route runs, so it drops the same unrenderable far ends. The difference
// therefore means here exactly what it means there.
type proxiedDepCounter struct {
src workapi.DetailSource
isWisp bool
}
func (c proxiedDepCounter) CountDependencies(ctx context.Context, id string) (int64, error) {
return c.src.CountDependencies(ctx, id, c.isWisp)
}
func (c proxiedDepCounter) CountDependents(ctx context.Context, id string) (int64, error) {
return c.src.CountDependents(ctx, id, c.isWisp)
}
func proxiedGetComments(ctx context.Context, uw uow.UnitOfWork, id string, isWisp bool) ([]*types.Comment, error) {
if isWisp {
return uw.CommentUseCase().GetCommentsForWisp(ctx, id)
@ -502,7 +527,13 @@ func proxiedRenderIssue(ctx context.Context, uw uow.UnitOfWork, issue *types.Iss
// (wy-j2upyy) is the gate-typed subset of this very set. Without it the
// proxied text route renders a plain OPEN header for a bead whose own
// --json already publishes gated_by. Best effort, as it always was.
depsWithMeta, _ := proxiedListDeps(ctx, uw, issue.ID, isWisp, domain.DepListFilter{Direction: domain.DepDirectionOut})
//
// Counts first — see readDepCounts for why the order matters. The
// listing's error is KEPT, not discarded: rendering stays best effort,
// but a FAILED listing and a SHORT one both leave the slice empty, and
// only the second is an unresolvable edge.
depCountsSnapshot := readDepCounts(ctx, proxiedDepCounter{src: workapi.NewUOWDetailSource(uw), isWisp: isWisp}, issue.ID)
depsWithMeta, depsErr := proxiedListDeps(ctx, uw, issue.ID, isWisp, domain.DepListFilter{Direction: domain.DepDirectionOut})
gates := types.GatesHolding(issue, depsWithMeta)
if idx > 0 {
@ -558,7 +589,7 @@ func proxiedRenderIssue(ctx context.Context, uw uow.UnitOfWork, issue *types.Iss
printDepSection(sec)
}
dependentsWithMeta, _ := proxiedListDeps(ctx, uw, issue.ID, isWisp, domain.DepListFilter{Direction: domain.DepDirectionIn})
dependentsWithMeta, dependentsErr := proxiedListDeps(ctx, uw, issue.ID, isWisp, domain.DepListFilter{Direction: domain.DepDirectionIn})
for _, sec := range groupDepSections(dependentsWithMeta, false, relatedSeen) {
printDepSection(sec)
if sec.Type == types.DepParentChild && issue.IssueType == types.TypeEpic {
@ -566,6 +597,21 @@ func proxiedRenderIssue(ctx context.Context, uw uow.UnitOfWork, issue *types.Iss
}
}
// The THIRD text render of `bd show`, and the one the first cut of be-lpi
// missed. usesProxiedServer() returns at show.go:45 before any of the
// direct-path code, and runShowProxiedDefault binds the shared
// issueops.Reader — hence BuildIssueDetails, hence
// unresolvable_dependencies — only `if jsonOutput && !in.shortMode`, so
// plain text falls through to here. Without this call a proxied
// `bd show <id>` still renders a cross-repo or `external:` dependency as
// no dependency at all: the exact symptom this change exists to remove,
// surviving on the route a server-backed repo actually uses. The
// precedent this design follows covers both of its own routes the same
// way — warnDroppedDepEdges at dep.go:1148 and dep_proxied_server.go:457.
warnUnresolvableDepEdges(issue.ID, depCountsSnapshot,
depListing{rows: len(depsWithMeta), err: depsErr},
depListing{rows: len(dependentsWithMeta), err: dependentsErr})
printRelatedSection(relatedSeen)
comments, _ := proxiedGetComments(ctx, uw, issue.ID, isWisp)

View file

@ -0,0 +1,120 @@
//go:build cgo
package main
import (
"os"
"os/exec"
"strings"
"testing"
)
// TestEmbeddedShowUnresolvableDeps drives the PRODUCTION path for be-lpi:
// `bd dep add` writing a real edge, then `bd show` reading it back. The unit
// coverage in internal/workapi constructs the count/row skew directly, which
// proves the arithmetic and says nothing about whether any real command can
// produce that state — this does the opposite, and the two together are the
// claim.
//
// The stored shape being pinned is the one the town's convoy beads carry:
// depends_on_external holds a target this database has no row for, so every
// listing path drops it (issueops.GetDependenciesWithMetadataInTx) while every
// count keeps it. Before the fix that left `dependency_count: 1` beside
// `dependencies: null` with nothing saying why, and `bd show` in text mode
// rendered no dependency section at all.
func TestEmbeddedShowUnresolvableDeps(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
t.Parallel()
bd := buildEmbeddedBD(t)
dir, _, _ := bdInit(t, bd, "--prefix", "ud")
anchor := bdCreate(t, bd, dir, "Anchor with an external edge", "--type", "task")
local := bdCreate(t, bd, dir, "Fully local blocker", "--type", "task")
// Both target shapes IsExternalDepTarget classifies as external: an
// explicit `external:` reference, and a bare id whose prefix names
// another repository. They land in the same column and fail the same
// way, so pinning only one would leave the commoner of the two —
// `bd dep add ud-x liveop-y` — uncovered.
for _, tc := range []struct {
name string
target string
depTyp string
}{
{"external_reference", "external:liveop:liveop-kmf", "tracks"},
{"cross_repo_prefix", "liveop-kmf", "blocks"},
} {
t.Run(tc.name, func(t *testing.T) {
subject := bdCreate(t, bd, dir, "Subject "+tc.name, "--type", "task")
bdDep(t, bd, dir, "add", subject.ID, tc.target, "--type", tc.depTyp)
details := bdShowDetails(t, bd, dir, subject.ID)
depCount, ok := details["dependency_count"].(float64)
if !ok || depCount != 1 {
t.Fatalf("dependency_count = %v, want 1 — the edge must still be counted",
details["dependency_count"])
}
if deps, present := details["dependencies"]; present && deps != nil {
if list, isList := deps.([]interface{}); isList && len(list) != 0 {
t.Fatalf("dependencies = %v, want empty: the target has no row in this database", deps)
}
}
unresolvable, ok := details["unresolvable_dependencies"].(float64)
if !ok || unresolvable != 1 {
t.Fatalf("unresolvable_dependencies = %v, want 1 — a count the caller cannot enumerate must say so (be-lpi)",
details["unresolvable_dependencies"])
}
// Text mode: the notice goes to stderr, so stdout stays
// byte-identical for scripts. Assert on stderr alone, or
// this passes on a build that prints nothing anywhere.
stdout, stderr := runShowSplit(t, bd, dir, subject.ID)
if !strings.Contains(stderr, "no row in this database") {
t.Errorf("bd show stderr did not disclose the unrenderable edge:\nstderr:\n%s", stderr)
}
if strings.Contains(stdout, "no row in this database") {
t.Errorf("the notice reached stdout, which must stay unchanged:\n%s", stdout)
}
})
}
// NEGATIVE CONTROL, and it is the load-bearing half: a fully local edge
// must leave the field unset and stderr silent. Without it every
// assertion above is satisfied by a build that reports every issue as
// having unresolvable edges.
t.Run("fully_local_control", func(t *testing.T) {
bdDep(t, bd, dir, "add", anchor.ID, local.ID, "--type", "blocks")
details := bdShowDetails(t, bd, dir, anchor.ID)
if v, present := details["unresolvable_dependencies"]; present {
t.Errorf("unresolvable_dependencies = %v on a fully local edge, want absent", v)
}
deps, _ := details["dependencies"].([]interface{})
if len(deps) != 1 {
t.Errorf("dependencies = %v, want the one local edge", details["dependencies"])
}
_, stderr := runShowSplit(t, bd, dir, anchor.ID)
if strings.Contains(stderr, "no row in this database") {
t.Errorf("bd show warned about a fully local edge:\nstderr:\n%s", stderr)
}
})
}
// runShowSplit runs `bd show <id>` keeping stdout and stderr apart, which the
// shared helpers deliberately merge. The split is the whole point here: the
// notice's contract is that it appears on stderr and nowhere else.
func runShowSplit(t *testing.T, bd, dir, id string) (stdout, stderr string) {
t.Helper()
cmd := exec.Command(bd, "show", id)
cmd.Dir = dir
cmd.Env = bdEnv(dir)
outBuf, errBuf, err := runCommandBuffers(t, cmd)
if err != nil {
t.Fatalf("bd show %s failed: %v\nstdout:\n%s\nstderr:\n%s", id, err, outBuf.String(), errBuf.String())
}
return outBuf.String(), errBuf.String()
}

View file

@ -0,0 +1,214 @@
package main
import (
"context"
"errors"
"strings"
"testing"
)
// fakeDepCounter answers the two aggregate queries readDepCounts makes,
// independently of any listing.
type fakeDepCounter struct {
depCount int64
depErr error
rdepCount int64
rdepErr error
}
func (f fakeDepCounter) CountDependencies(_ context.Context, _ string) (int64, error) {
return f.depCount, f.depErr
}
func (f fakeDepCounter) CountDependents(_ context.Context, _ string) (int64, error) {
return f.rdepCount, f.rdepErr
}
// TestWarnUnresolvableDepEdges covers the text-mode disclosure, and in
// particular the case a codex review caught on the first cut of this change:
// `bd show` renders dependencies best effort and discarded the listing error,
// so a FAILED listing beside a SUCCEEDING count reported every edge the issue
// has as cross-repo/external. That turns a transient backend error into a
// claim about the data, which is worse than staying quiet — the same
// distinction BuildIssueDetails draws with depsErr on the JSON side, and the
// text path did not draw at all.
func TestWarnUnresolvableDepEdges(t *testing.T) {
boom := errors.New("backend down")
tests := []struct {
name string
counter fakeDepCounter
deps depListing
dependents depListing
wantWarn bool
wantText string
// The recovery pointer follows the OUTBOUND direction alone, because
// `bd dep list <id> <id>` is outbound-only (dep.go:1101/1144). An
// issue short only on dependent edges gets the inbound note instead,
// and these two fields are what stop a later edit from quietly
// pointing a reader at a command that cannot answer.
wantPointer bool
wantInboundNak bool
}{
{
name: "one unrenderable outgoing edge",
counter: fakeDepCounter{depCount: 1},
deps: depListing{rows: 0},
wantWarn: true,
wantText: "1 dependency edge(s)",
wantPointer: true,
},
{
name: "one unrenderable incoming edge",
counter: fakeDepCounter{rdepCount: 3},
dependents: depListing{rows: 1},
wantWarn: true,
wantText: "2 dependent edge(s)",
wantPointer: false,
wantInboundNak: true,
},
{
// The negative control. Without it every assertion above is
// satisfied by a build that warns unconditionally.
name: "fully local, counts match the rows",
counter: fakeDepCounter{depCount: 2, rdepCount: 1},
deps: depListing{rows: 2},
dependents: depListing{rows: 1},
wantWarn: false,
},
{
name: "nothing at all",
counter: fakeDepCounter{},
wantWarn: false,
},
{
// The codex finding. The count is honest and the listing never
// ran; staying silent is the only correct answer.
name: "listing read FAILED, count succeeded",
counter: fakeDepCounter{depCount: 5},
deps: depListing{rows: 0, err: boom},
wantWarn: false,
},
{
name: "dependents listing FAILED, count succeeded",
counter: fakeDepCounter{rdepCount: 5},
dependents: depListing{rows: 0, err: boom},
wantWarn: false,
},
{
// Symmetric: the count is what failed. It yields 0, which cannot
// exceed any row total, but assert it rather than lean on the sign.
name: "count read FAILED",
counter: fakeDepCounter{depErr: boom},
deps: depListing{rows: 0},
wantWarn: false,
},
{
// One direction is diagnosable and the other is not: the healthy
// half must still be reported. It is the INBOUND half here, so the
// outbound-only pointer must stay away even though the outbound
// direction is the one that failed.
name: "outgoing failed, incoming still reportable",
counter: fakeDepCounter{depCount: 4, rdepCount: 2},
deps: depListing{rows: 0, err: boom},
dependents: depListing{rows: 0},
wantWarn: true,
wantText: "2 dependent edge(s)",
wantPointer: false,
wantInboundNak: true,
},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
counts := readDepCounts(context.Background(), tc.counter, "rp-1")
out := captureStderr(t, func() {
warnUnresolvableDepEdges("rp-1", counts, tc.deps, tc.dependents)
})
if tc.wantWarn {
if !strings.Contains(out, "no row in this database") {
t.Errorf("expected a warning, got:\n%q", out)
}
if tc.wantText != "" && !strings.Contains(out, tc.wantText) {
t.Errorf("warning did not mention %q, got:\n%q", tc.wantText, out)
}
wantPointers := 0
if tc.wantPointer {
wantPointers = 1
if !strings.Contains(out, "bd dep list rp-1 rp-1") {
t.Errorf("warning did not name the recovery command, got:\n%q", out)
}
}
// The pointer is printed once however many directions warn,
// and not at all when only the inbound direction did.
if n := strings.Count(out, "For raw edge records"); n != wantPointers {
t.Errorf("recovery pointer printed %d times, want %d:\n%q", n, wantPointers, out)
}
wantNaks := 0
if tc.wantInboundNak {
wantNaks = 1
}
if n := strings.Count(out, "bd dep list is outbound-only"); n != wantNaks {
t.Errorf("inbound no-listing note printed %d times, want %d:\n%q", n, wantNaks, out)
}
} else if out != "" {
t.Errorf("expected silence, got:\n%q", out)
}
})
}
t.Run("both directions warn but the pointer is printed once", func(t *testing.T) {
counts := readDepCounts(context.Background(), fakeDepCounter{depCount: 1, rdepCount: 1}, "rp-1")
out := captureStderr(t, func() {
warnUnresolvableDepEdges("rp-1", counts, depListing{rows: 0}, depListing{rows: 0})
})
if n := strings.Count(out, "no row in this database"); n != 2 {
t.Errorf("expected two warnings, got %d:\n%q", n, out)
}
if n := strings.Count(out, "For raw edge records"); n != 1 {
t.Errorf("recovery pointer printed %d times, want 1:\n%q", n, out)
}
// Both facts are true at once and both are said: the pointer covers
// the outbound edges it can list, the note covers the inbound ones no
// command can.
if n := strings.Count(out, "bd dep list is outbound-only"); n != 1 {
t.Errorf("inbound no-listing note printed %d times, want 1:\n%q", n, out)
}
})
// A nil store yields counts carrying errNoDepCounter in both directions,
// which the report gate treats exactly like any other failed count read.
t.Run("nil store is a no-op", func(t *testing.T) {
counts := readDepCounts(context.Background(), nil, "rp-1")
out := captureStderr(t, func() {
warnUnresolvableDepEdges("rp-1", counts, depListing{rows: 0}, depListing{rows: 0})
})
if out != "" {
t.Errorf("expected silence, got:\n%q", out)
}
})
// The arithmetic half of the concurrency mitigation: a count that is
// stale-LOW relative to the listing — what a count read BEFORE a
// concurrent add looks like — must be suppressed rather than reported.
//
// SCOPE, stated because it would otherwise read as more than it is: this
// pins the SUBTRACTION only. The call-site ORDER that produces the
// stale-low count lives in show.go, show_display.go and
// show_proxied_server.go, none of which this test exercises. The split
// into readDepCounts plus warnUnresolvableDepEdges makes that order
// READABLE at those call sites and does not pin it — reversing it at all
// three leaves this package green, and
// TestBuildIssueDetails_ConcurrentAddIsNotReportedAsUnresolvable, one tier
// down on BuildIssueDetails, is the only case that actually fails.
t.Run("a stale-low count is suppressed, not reported", func(t *testing.T) {
counts := readDepCounts(context.Background(), fakeDepCounter{depCount: 1}, "rp-1")
out := captureStderr(t, func() {
// The listing observed the edge the count predates, plus one more
// added in the window.
warnUnresolvableDepEdges("rp-1", counts, depListing{rows: 2}, depListing{})
})
if out != "" {
t.Errorf("a concurrent add must not be reported as unresolvable, got:\n%q", out)
}
})
}

View file

@ -1,10 +1,13 @@
package main
import (
"context"
"fmt"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/tracker"
"github.com/steveyegge/beads/internal/types"
)
// registerSelectiveSyncFlags adds --issues and --parent flags to a tracker sync command.
@ -44,3 +47,35 @@ func applySelectiveSyncFlags(cmd *cobra.Command, opts *tracker.SyncOptions, push
}
return nil
}
// buildSyncDescendantSet resolves opts.ParentID into the set of issue IDs
// --parent selects: the parent itself plus every bead reachable from it
// through parent-child dependency edges. A nil result means no subtree scope
// was requested; callers filtering by it must treat a non-nil set as a
// membership requirement.
//
// Shared by the GitLab and GitHub relationship passes so a subtree-scoped push
// and its relationship pass agree on what "in scope" means. The engine has its
// own copy for the content push (Engine.buildDescendantSet,
// internal/tracker/engine.go); these two must stay in agreement. The ADO
// relationship pass is not converted: pushADOLinks (ado.go) takes no sync
// options, so --parent and --issues do not narrow the ADO relations it writes.
func buildSyncDescendantSet(ctx context.Context, st storage.Storage, parentID string) (map[string]bool, error) {
result := map[string]bool{parentID: true}
queue := []string{parentID}
for len(queue) > 0 {
current := queue[0]
queue = queue[1:]
dependents, err := st.GetDependentsWithMetadata(ctx, current)
if err != nil {
return nil, fmt.Errorf("getting dependents of %s: %w", current, err)
}
for _, dep := range dependents {
if dep.DependencyType == types.DepParentChild && !result[dep.Issue.ID] {
result[dep.Issue.ID] = true
queue = append(queue, dep.Issue.ID)
}
}
}
return result, nil
}

View file

@ -611,15 +611,29 @@ func runGitHubPush(cmd *cobra.Command, args []string) error {
engine.OnWarning = func(msg string) { fmt.Fprintf(os.Stderr, "Warning: %s\n", msg) }
engine.PushHooks = buildGitHubPushHooks(gt)
result, err := engine.Sync(ctx, tracker.SyncOptions{
opts := tracker.SyncOptions{
Push: true,
Pull: false,
DryRun: dryRun,
IssueIDs: args,
})
}
result, err := engine.Sync(ctx, opts)
if err != nil {
return err
}
// Relationship push pass, matching `bd github sync`: converge beads
// epic/child links and "blocks" dependencies among the requested issues
// into GitHub sub-issues and issue dependencies.
warnLink := func(msg string) { fmt.Fprintf(os.Stderr, "Warning: %s\n", msg) }
linksPushed := pushGitHubDependencyLinks(ctx, gt, store, opts, dryRun, os.Stdout, warnLink)
// Under --dry-run PushLinks counts planned links in Created, so this line
// would affirm writes that never happened; the `bd github sync` twin gates
// it the same way.
if linksPushed > 0 && !dryRun && !jsonOutput {
fmt.Printf("✓ Synced %d relationship links\n", linksPushed)
}
outputSyncResult(result, dryRun)
return nil
}

View file

@ -64,6 +64,9 @@ const suiteRootPrefix = "beads-bd-tests-"
// Guardrail: ensure the cmd/bd test suite does not touch the real repo .beads state.
// Disable with BEADS_TEST_GUARD_DISABLE=1 (useful when running tests while actively using beads).
func TestMain(m *testing.M) {
if code, ok := runInitGatewayCredentialHelper(); ok {
os.Exit(code)
}
// Delegate to testMainInner so defers run before os.Exit.
os.Exit(testMainInner(m))
}

23
cmd/bd/testdata/preflight-go.go vendored Normal file
View file

@ -0,0 +1,23 @@
package main
import (
"encoding/json"
"fmt"
"os"
)
func main() {
dir, err := os.Getwd()
if err != nil {
panic(err)
}
marker, err := os.Create(os.Getenv("PREFLIGHT_LINT_MARKER"))
if err != nil {
panic(err)
}
defer marker.Close()
if err := json.NewEncoder(marker).Encode(map[string]any{"args": os.Args[1:], "dir": dir}); err != nil {
panic(err)
}
fmt.Println("synthetic checkout lint success")
}

View file

@ -285,7 +285,7 @@ pointless).`,
} else {
t, err := timeparsing.ParseRelativeTime(dueStr, time.Now())
if err != nil {
return HandleErrorRespectJSON("invalid --due format %q. Examples: +6h, tomorrow, next monday, 2025-01-15", dueStr)
return HandleErrorRespectJSON("invalid --due format %q. %s", dueStr, deferUntilFormatHint)
}
updates["due_at"] = t
}
@ -302,7 +302,7 @@ pointless).`,
} else {
t, err := timeparsing.ParseRelativeTime(deferStr, time.Now())
if err != nil {
return HandleErrorRespectJSON("invalid --defer format %q. Examples: +1h, tomorrow, next monday, 2025-01-15", deferStr)
return HandleErrorRespectJSON("invalid --defer format %q. %s", deferStr, deferUntilFormatHint)
}
// Warn if defer date is in the past (user probably meant future)
inPast := t.Before(time.Now())

View file

@ -176,7 +176,7 @@ func gatherUpdateInput(ctx context.Context, cmd *cobra.Command) (*updateInput, e
} else {
t, err := timeparsing.ParseRelativeTime(dueStr, time.Now())
if err != nil {
return nil, HandleErrorRespectJSON("invalid --due format %q. Examples: +6h, tomorrow, next monday, 2025-01-15", dueStr)
return nil, HandleErrorRespectJSON("invalid --due format %q. %s", dueStr, deferUntilFormatHint)
}
in.fields["due_at"] = t
}
@ -192,7 +192,7 @@ func gatherUpdateInput(ctx context.Context, cmd *cobra.Command) (*updateInput, e
} else {
t, err := timeparsing.ParseRelativeTime(deferStr, time.Now())
if err != nil {
return nil, HandleErrorRespectJSON("invalid --defer format %q. Examples: +1h, tomorrow, next monday, 2025-01-15", deferStr)
return nil, HandleErrorRespectJSON("invalid --defer format %q. %s", deferStr, deferUntilFormatHint)
}
inPast := t.Before(time.Now())
if inPast && !jsonOut {

View file

@ -140,7 +140,7 @@ func applyUpdateProxiedOne(ctx context.Context, id string, in *updateInput) (*ty
if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
return nil, nil, err
}
return nil, proxiedUpdateFailure(id, err), nil
return nil, proxiedUpdateFailure(id, in.claim, err), nil
}
updated := result.Issue
if updated == nil {
@ -237,11 +237,15 @@ func proxiedClaimPoolAliases(ctx context.Context) func() []string {
// proxiedUpdateFailure sorts a refused update into the per-id verdicts. A guard
// refusal sets GuardMismatch so the batch exits 13 rather than 1.
//
// A refused claim reads as the generic update failure, as it does on the direct
// route: the external claim guard ignores --force but shares ErrCloseBlocked
// with the close policy, so the hint could name an override that cannot work.
//
// The one verdict it cannot reproduce is stage attribution: "opening unit of
// work" and "committing" were told apart by watching the provider this path no
// longer owns, so both now read as the generic update failure. The id still
// fails, loudly and non-zero.
func proxiedUpdateFailure(id string, err error) *updateIDFailure {
func proxiedUpdateFailure(id string, claim bool, err error) *updateIDFailure {
switch {
case errors.Is(err, storage.ErrNotFound):
fmt.Fprintf(os.Stderr, "Issue %s not found\n", id)
@ -252,7 +256,7 @@ func proxiedUpdateFailure(id string, err error) *updateIDFailure {
case errors.Is(err, storage.ErrCloseOpenChildren):
fmt.Fprintf(os.Stderr, "%v\n", err)
return &updateIDFailure{ID: id, Error: err.Error()}
case errors.Is(err, storage.ErrCloseBlocked):
case errors.Is(err, storage.ErrCloseBlocked) && !claim:
fmt.Fprintf(os.Stderr, "%v (use --force to override)\n", err)
return &updateIDFailure{ID: id, Error: fmt.Sprintf("%v (use --force to override)", err)}
case uow.IsSerializationError(err):

View file

@ -17,6 +17,7 @@ import (
"github.com/steveyegge/beads/internal/storage/dolt"
"github.com/steveyegge/beads/internal/storage/schema"
"github.com/steveyegge/beads/issueops"
"golang.org/x/mod/module"
)
// localVersionFile is the gitignored file that stores the last bd version used locally.
@ -309,22 +310,30 @@ func autoMigrateOnVersionBump(beadsDir string) {
// recoverPreV56IfNeeded rebuilds a Dolt database left behind by the pre-0.56
// embedded mode (GH#2137) — which means deleting .dolt — but only when the
// recorded predecessor is an actual semantic version older than 0.56.0.
// recorded predecessor is a release older than 0.56.0.
//
// The validity check is not redundant with the comparison. CompareVersions
// scans every dot-separated part with %d and leaves whatever it cannot read at
// 0, so any non-semver string writeLocalVersion has recorded compares as
// pre-0.56 and routes a current workspace into this destructive path:
// Homebrew's "HEAD-<shortsha>" from a --HEAD install (#5603), and the
// v-prefixed Go pseudo-version a `go install`-built bd stamps (#5650). Neither
// is a pre-0.56 workspace; both would lose their database.
// Neither refusal below is redundant with the comparison:
//
// IsValidSemver rejects exactly the shapes CompareVersions misreads, so this
// gate can only remove predecessors from the recovery set, never add one: a
// stamp that reaches RecoverPreV56DoltDir today and still parses keeps its
// recovery unchanged.
// - CompareVersions scans every dot-separated part with %d and leaves
// whatever it cannot read at 0, so a stamp it cannot parse compares as
// pre-0.56: Homebrew's "HEAD-<shortsha>" from a --HEAD install (#5603).
// IsValidSemver rejects those shapes.
// - A Go pseudo-version parses, but its numbers do not name a release.
// "v0.55.5-0.<timestamp>-<hash>" is some commit after v0.55.4, and
// "v0.0.0-<timestamp>-<hash>" a build with no tag in reach at all: the
// prefix bounds the build from below, never from above, so it cannot show
// that the workspace predates 0.56. IsValidSemver used to refuse the
// v-prefixed ones some build paths stamp (#5650) only because it read
// the "v" as a malformed part. Since it accepts a leading "v" (GH#6152),
// a major-0 one can compare below 0.56.0, so pseudo-versions are refused
// here explicitly, however they are spelled.
//
// A v-prefixed release ("v0.55.4") is compared numerically and still
// recovers. The .bd-dolt-ok marker RecoverPreV56DoltDir checks is the last
// gate, but only bd 0.58.0 and later write it: a database that only 0.56.x or
// 0.57.x has served has none, so for it these refusals are the only gate.
func recoverPreV56IfNeeded(previousVersion, dbPath string) {
if !doctor.IsValidSemver(previousVersion) {
if !doctor.IsValidSemver(previousVersion) || isGoPseudoVersion(previousVersion) {
return
}
if doctor.CompareVersions(previousVersion, "0.56.0") >= 0 {
@ -340,6 +349,14 @@ func recoverPreV56IfNeeded(previousVersion, dbPath string) {
}
}
// isGoPseudoVersion reports whether a version stamp is a Go pseudo-version,
// with or without the leading "v". The module parser requires the "v", so the
// stamp is normalized the way the doctor version helpers read it (trimmed, one
// optional "v") and then given one.
func isGoPseudoVersion(version string) bool {
return module.IsPseudoVersion("v" + strings.TrimPrefix(strings.TrimSpace(version), "v"))
}
// noticeSharedMigrateRefusal turns the one failure autoMigrateOnVersionBump
// must not swallow into a one-line stderr notice.
//

View file

@ -548,11 +548,16 @@ func writePreV56DoltFixture(t *testing.T) (doltDir, sentinel string) {
}
// TestRecoverPreV56IfNeeded_OnlySemverPredecessorsAreRecovered pins the
// destructive edge from #5603/#5625: CompareVersions reads any unparsable
// version part as 0, so a non-semver predecessor compares as pre-0.56 and
// hands a live workspace to a path that deletes .dolt. The Homebrew --HEAD
// stamp and the v-prefixed Go pseudo-version from #5650 are both such
// predecessors and both reach this call today.
// destructive edge from #5603/#5625/#5650: only a release older than 0.56.0
// may hand its workspace to the path that deletes .dolt.
//
// - CompareVersions reads any unparsable version part as 0, so the Homebrew
// --HEAD stamp compares as pre-0.56 and must fail the validity check.
// - A Go pseudo-version passes the validity check since the GH#6152 fix,
// and a major-0 one can compare below 0.56.0, but its numbers only bound
// the build from below. It must be refused on its own, with or without
// the "v".
// - A v-prefixed release is a genuine predecessor and still recovers.
func TestRecoverPreV56IfNeeded_OnlySemverPredecessorsAreRecovered(t *testing.T) {
tests := []struct {
name string
@ -563,11 +568,16 @@ func TestRecoverPreV56IfNeeded_OnlySemverPredecessorsAreRecovered(t *testing.T)
{name: "bare brew HEAD stamp", previous: "HEAD"},
{name: "brew HEAD stamp with revision", previous: "HEAD-f925f3f_1"},
{name: "go pseudo-version", previous: "v1.1.1-0.20260805093327-bf97b73749ac"},
{name: "go pseudo-version with no tag in reach", previous: "v0.0.0-20260805093327-bf97b73749ac"},
{name: "go pseudo-version after a pre-0.56 tag", previous: "v0.55.5-0.20260101000000-abcdefabcdef"},
{name: "go pseudo-version without its v", previous: "0.0.0-20260805093327-bf97b73749ac"},
{name: "go pseudo-version with surrounding space", previous: " v0.0.0-20260805093327-bf97b73749ac\n"},
{name: "unreadable witness", previous: "not-a-version"},
{name: "no predecessor", previous: ""},
{name: "current release", previous: "1.1.2"},
{name: "0.56.0 itself", previous: "0.56.0"},
{name: "pre-0.56 release", previous: "0.55.4", wantRecovery: true},
{name: "v-prefixed pre-0.56 release", previous: "v0.55.4", wantRecovery: true},
{name: "pre-0.56 pre-release", previous: "0.55.4-rc.1", wantRecovery: true},
}

View file

@ -32,6 +32,8 @@ A curated list of community-built UIs, extensions, and integrations for Beads. R
- **[Maggie](https://github.com/mulgadc/maggie)** - Single Go binary with the SPA embedded, serving dashboard, table, board and dependency graph views. Text, id glob, priority, type, assignee, label and status filters compose in one filter bar. Uses the `bd` CLI for every read and write, keeping no store of its own. Runs from a container that bundles `bd` and `dolt`, against either a local `.beads/` directory or a shared Dolt SQL server. Built by [@mulgadc](https://github.com/mulgadc). (Go/React)
- **[beadcyte](https://gitlab.com/incytestudios/beadcyte)** - Local web app that draws two things that look alike and are not: what happened, which is measured, and what it expects to happen, which is a model's opinion. Three models drive the projection — a historical-median duration estimator, a greedy WIP-cap scheduler calibrated against your real throughput, and an eight-signal triage score — each shown with its own uncertainty rather than a flat number. Views for what to do next, the team's frontier, what-if plan diffs, and cost per week; a single self-contained SVG export with no server (`beadcyte --out gantt.svg`); and a changelog generated from closed beads that carry ship evidence. Reads and writes through the `bd` CLI (`bd list --all --json`, `bd show`, `bd history`); `beadcyte freeze` additionally reads the embedded Dolt database directly (read-only, opt out with `--no-dolt`) — never `.beads/issues.jsonl`. Run with `npx beadcyte start`. Built by [Incyte Studios](https://incytestudios.com) ([@treystout](https://github.com/treystout)). (Node.js/Vue)
## Editor Extensions
- **[vscode-beads](https://marketplace.visualstudio.com/items?itemName=planet57.vscode-beads)** - VS Code extension with issues panel and server management. Built by [@jdillon](https://github.com/jdillon). (TypeScript)

View file

@ -25,6 +25,7 @@ See also: `bd help init-safety`, and
- [init-force-refused — `bd init --force`/`--reinit-local` refused because origin has Dolt history](#init-force-refused)
- [init-token-missing — a destructive re-init refused because `--destroy-token` is missing or wrong](#init-token-missing)
- [init-local-exists — `bd init --reinit-local` refused because local data already exists](#init-local-exists)
- [init-missing-server-db — `bd init` refused because the configured server-side database is missing](#init-missing-server-db)
- [pk-fork-refused — `bd dolt pull`/`push` refused because a table has different primary keys in its common ancestor](#pk-fork-refused)
- [re-clone-gotchas — two gotchas hit during manual re-clone recovery: damaged stores left inside `data_dir`, and a fresh clone missing clone-local tables](#re-clone-gotchas)
@ -208,6 +209,109 @@ re-init won't fix.
---
## init-missing-server-db
**Symptom**
```
⚠ Database "myproject" not found on server at 127.0.0.1:3306 (or the server could not be reached to confirm).
This workspace was already initialized (metadata.json has a project_id from a prior
bd init), so this looks like a recovery situation, not a fresh clone
...
bd init will NOT create an empty database here — that would strand any existing
issue data behind a new, empty database of the same name.
```
**What happened**
This workspace is in server mode and `.beads/metadata.json` carries a
`project_id`, which is written only by a real prior `bd init`. So the project
was definitely initialized at some point — but its configured database is not
on the server, or the server could not be reached to confirm.
That is a **recovery** situation, not a fresh clone, and the two are otherwise
indistinguishable from the local filesystem alone: in server mode there is
normally no local database directory either way. `bd init` used to resolve the
ambiguity by assuming "fresh clone" and creating the database. When the
assumption was wrong, the result was a new, empty database sitting at the name
the real one used to occupy — the 2026-08-11 fleet-wide data loss.
`bd init` now refuses instead, and the refusal is **not** bypassed by
`--force` or `--reinit-local`. Those flags authorize destroying a database
that exists; they do not authorize inventing an empty one where the configured
database has gone missing.
### 1. Find out where the database went (do this first)
```
bd doctor # check project health
bd dolt status # inspect Dolt server state
```
A stopped server, a server started on the wrong port, or a wrong `--data-dir`
all present exactly like this — and none of them need a re-init. Fixing the
server brings the data back untouched.
### 2. Restore from an export
```
bd backup restore # if a local backup snapshot exists
```
Also check `.beads/backup/` for a JSONL export you can import manually.
### 3. Create a fresh empty database at this name
**Destructive to any unrecovered data.**
Only when you are certain no recoverable data exists:
```
bd init --recreate-missing --prefix myproject
```
`--recreate-missing` is per-invocation only. It is deliberately never implied
by `--force`, `--reinit-local`, a config key, or an environment variable,
because it authorizes the one thing this guard exists to prevent.
**Limits worth knowing**
- The guard keys on `project_id`, which was introduced by GH#2372. A workspace
initialized before that has no `project_id` and is indistinguishable from a
fresh clone, so it **fails open** — `bd init` will still create the database.
- The same `project_id` is inherited by a **fresh clone**, because
`.beads/metadata.json` is git-tracked by default. Cloning a beads-managed
repo whose server-side database does not exist yet therefore meets this
refusal rather than a plain first init. It fails in the safe direction —
nothing is created silently, and no existing data can be stranded — and
`--recreate-missing` above is the supported way through it. This is settled,
not pending: `engdocs/adr/0004-missing-database-guard-signal.md` records why
no purely-local signal can replace `project_id` here (absence of local state
cannot tell "never initialized here" from "initialized here, storage since
lost"), and why `--recreate-missing` is the permanent resolution path rather
than a stopgap.
- The guard applies equally to `bd init`, `bd init --reinit-local` and
`bd init --force`. If your workspace predates `project_id` and its local
Dolt storage is gone, all three refuse until you pass `--recreate-missing`;
a workspace with no local Dolt storage at all is treated as a fresh clone by
all three.
- Server mode only, and shared-server mode counts as server mode — the guard
tests for *this project's* database directory under the resolved Dolt data
dir, not for the data dir itself, which in shared mode is the machine-global
`~/.beads/shared-server/dolt` that is created on demand.
- Proxied-server mode does not reach the `--reinit-local`/`--force` guard —
the `--proxied-server` dispatch in `runInit` (`cmd/bd/init.go`) returns
before it. It does reach the plain-init guard, because
`runInitProxiedServer` calls `checkExistingBeadsData`, so
**`--recreate-missing` works under `--proxied-server` too**: the flag is
assigned beside its flag read, upstream of every dispatch in `runInit`.
Keep it there. It was previously assigned next to the guard it gates, which
is downstream of the proxied dispatch, and the flag was therefore inert on
that one route while the refusal still told the operator to pass it.
- `bd bootstrap` has its own separate mode-blind create path.
---
## pk-fork-refused
**Symptom**

View file

@ -5,7 +5,7 @@ description: Complete reference for bd configuration across config.yaml and data
Complete configuration reference for beads.
Last reviewed: 2026-08-28
Last reviewed: 2026-09-10
Freshness source: `cmd/bd/main.go`, `cmd/bd/config.go`, and `internal/configfile/`.
@ -126,6 +126,8 @@ Any key whose name contains `api_key`, `api-key`, `secret`, `token`, or `passwor
| `backup.interval` | — | `BD_BACKUP_INTERVAL` | `15m` | Minimum time between auto-backups |
| `backup.git-push` | — | — | `false` | Auto-push backup repo |
| `backup.git-repo` | — | `BD_BACKUP_GIT_REPO` | (none) | Backup git repo URL; when set, backups go to a `backup/` directory inside that repo |
| `backup.size-cap-mb` | — | `BD_BACKUP_SIZE_CAP_MB` | `2048` | Pause auto-backup once the destination directory reaches this size; `0` disables the cap (see [below](#auto-backup)) |
| `backup.size-warn-interval` | — | `BD_BACKUP_SIZE_WARN_INTERVAL` | `24h` | Minimum time between repeated "auto-backup paused" warnings |
| `audit.enabled` | — | `BD_AUDIT_ENABLED` | `false` | Enable the optional JSONL interaction sidecar at `.beads/interactions.jsonl`, written by `bd audit record` / `bd audit label`. While disabled, `bd init` does not create the file and `bd audit record` / `bd audit label` refuse to write. Issue history is always recorded in the database either way — see `bd history <id> --events` |
| `export.auto` | — | — | `false` | Refresh `.beads/issues.jsonl` export after every write; not cross-machine sync |
| `export.path` | — | — | `issues.jsonl` | Output filename relative to `.beads/` |
@ -224,15 +226,19 @@ Periodic Dolt-native backup to `.beads/backup/` provides a recovery path indepen
```yaml
backup:
enabled: true # Enable auto-backup after write commands
interval: 15m # Minimum time between auto-backups
enabled: true # Enable auto-backup after write commands
interval: 15m # Minimum time between auto-backups
size-cap-mb: 2048 # Pause auto-backup once the destination reaches this size; 0 disables the cap
size-warn-interval: 24h # Minimum time between repeated "paused" warnings
```
How it works:
- After each write command, `bd` compares the Dolt HEAD commit hash against the last backup state.
- If data changed and the throttle interval has passed, a Dolt-native backup is synced to `.beads/backup/` (or to a `backup/` directory inside `backup.git-repo` when configured).
- State is tracked in `backup_state.json` inside the backup directory.
- If data changed and the throttle interval has passed, `bd` checks the destination directory's on-disk size against `backup.size-cap-mb`. `CALL DOLT_BACKUP('sync', ...)` only ever adds new chunks to the destination — it never prunes ones that became unreachable on the source (history rewrites, superseded data), and Dolt exposes no supported way to GC a backup destination in place. Left uncapped, the destination can only grow until disk fills; this was the root cause of a 2026-06-19 outage where a 1.7GB store produced a 43GB backup directory. Once the cap is reached, auto-backup pauses — nothing is deleted, but no further syncs run until you raise `backup.size-cap-mb` or point to a fresh destination with `bd backup init <new-path>`. Set `size-cap-mb: 0` to disable the cap entirely.
- If the destination is under its cap, a Dolt-native backup is synced to `.beads/backup/` (or to a `backup/` directory inside `backup.git-repo` when configured).
- State is tracked in `backup_state.json` inside the backup directory. `bd backup status` prints `PAUSED (cap exceeded)` when the destination is over its cap, and its `--json` output reports the same state as `size_cap.exceeded: true` — so an agent/CI caller relying on `--json` or `--quiet` can see that auto-backup has stopped instead of reading a reassuring "Last backup" line while nothing further syncs.
- The cap applies only to auto-backup; manual `bd backup` / `bd backup sync` are not capped.
Manual commands (see [bd backup](/cli-reference/backup)):
@ -503,6 +509,7 @@ Selected commonly-used variables:
| `BEADS_ACTOR` | Actor identity (preferred over `BD_ACTOR`, which is a deprecated alias) |
| `BEADS_IDENTITY` | Sender identity for `bd mail` |
| `BEADS_FSCK_TIMEOUT` | Runtime-only timeout for the pre-push `dolt fsck --quiet` integrity check (default `30s`) |
| `BEADS_MIGRATION_WATCHDOG_INTERVAL` | Interval between soft WARN lines while a schema migration's SQL keeps running (default `5m`; accepts durations like `10m` or bare seconds like `90`). Observability only — it never aborts a migration |
| `BEADS_DOLT_SERVER_MODE`, `BEADS_DOLT_SHARED_SERVER`, `BEADS_DOLT_DATA_DIR`, `BEADS_DOLT_PORT`, ... | Embedded/server Dolt overrides |
| `BEADS_DOLT_BIN` | Pin the exact external `dolt` CLI binary managed proxied-server mode spawns, overriding PATH lookup (highest precedence; an explicit path that fails validation is an error, not a silent fallback to PATH). On Windows the executable extension may be omitted — `C:\tools\dolt` finds `C:\tools\dolt.exe` via PATHEXT, though a file at the exact spelled path wins if both exist |

View file

@ -3,8 +3,8 @@
Last reviewed: 2026-09-03
Freshness source: `engdocs/CI_TEST_SURFACE_AUDIT.md`, `.github/workflows/*.yml`,
`.buildflags`, `.golangci.yml`, `scripts/ci/pr-lint.sh`, `Makefile`, package test
manifests, and maintainer decision review.
`.buildflags`, `.golangci.yml`, `scripts/ci/pr-lint.sh`, `scripts/pr-lint/`,
`Makefile`, package test manifests, and maintainer decision review.
This document records the agreed target shape for CI cleanup. It is the policy
and roadmap layer; the current inventory remains in
@ -51,8 +51,11 @@ Every PR, including docs-only PRs, should run the required Linux baseline:
## Wrapper Conventions
Shell scripts under `scripts/ci/` are the source of truth. Make targets should
be aliases for discoverability, not a second implementation of command policy.
Repository-owned wrappers under `scripts/ci/` are the supported tier
entrypoints. Make targets should be aliases for discoverability, not a second
implementation of command policy. A wrapper may delegate shared policy to one
repository-owned Go driver when production tooling also needs the same
shell-free contract.
Wrapper rules:
@ -171,6 +174,10 @@ easy to identify and rerun. It includes:
cross-lints are compile-only passes on the Linux runner; they add no macOS or
Windows runner and do not change the platform column above.
All three lint passes and their target selection are owned by the
checkout-local `scripts/pr-lint` Go driver. The Bash wrapper retains formatting,
direct invocation, and aggregate timing without duplicating that policy.
All three passes are SCOPED BY LANE. On a PR the wrapper takes
`BD_LINT_NEW_FROM_MERGE_BASE` and reports only the findings that PR introduces,
matching the `only-new-issues` setting on the sibling `lint` job; on a push to

View file

@ -47,20 +47,32 @@ Current PR-related workflow names:
exports it as the `rbe-mode` / `rbe-enabled` outputs; every lane exports its
`job.status` as an output named after the job. `pr.yml`'s gate requires the
call's result (`BAZEL`) and `BAZEL_TEST`, `BAZEL_PURE`, `BAZEL_EMBEDDED`,
`BAZEL_DOLTSERVER`, `BAZEL_PROXIED` and `BAZEL_SERVER_STORAGE`. The legacy jobs these mirror stay required in `pr.yml`
and `pr-risk.yml`.
`BAZEL_INTEGRATION`, `BAZEL_DOLTSERVER`, `BAZEL_PROXIED` and
`BAZEL_SERVER_STORAGE`. The legacy jobs these mirror stay required in
`pr.yml` and `pr-risk.yml`.
`.github/scripts/bazel-gate.sh` reads the exported mode, never the variable
or the fork flag: mode `skip` allows every Bazel id to skip, mode `local`
allows only the remote-only `BAZEL_EMBEDDED`, `BAZEL_PROXIED` and
`BAZEL_SERVER_STORAGE` (fork and Dependabot PRs rely on `pr-risk.yml`'s
legacy tiers for those), and mode `remote` allows none.
allows only the remote-only `BAZEL_EMBEDDED`, `BAZEL_INTEGRATION`,
`BAZEL_PROXIED` and `BAZEL_SERVER_STORAGE` (fork and Dependabot PRs rely on
`pr-risk.yml`'s legacy tiers for the embedded, proxied and server-storage
tiers), and mode `remote` allows none.
A lane that should run and fails, is cancelled, or reports no result fails
the gate, and so does a missing or invalid mode.
`bazel-integration` is not part of the PR call (`pr.yml` passes
`integration: "off"`) and has no gate id: its legacy counterparts
(`main.yml`'s integration jobs) run only on push to `main`, and so does it
(plus dispatch and nightly). `scripts/ci_workflow_test.go` fails when a new
`bazel.yml` job has neither a gate id nor an advisory entry.
`bazel-integration` (`bazel test //... --config=integration`, the Bazel
twin of `main.yml`'s Linux integration shards) is required on same-repo
PRs: `pr.yml` passes `integration: "on"` (policy-pinned), so in mode
`remote` it runs, and a failure, cancellation or missing result turns the
gate red. Its legacy twins still run only on push to `main`, so this lane
is the only PR-time run of the full integration-tagged suite. Fork and
Dependabot PRs (mode `local`) skip it, with no legacy fallback on the PR:
they get integration coverage only after merge, from `main.yml`. Running it
for forks waits on a read-only remote cache they may use; that change is
making the lane local-capable for forks in `bazel.yml` and dropping
`BAZEL_INTEGRATION` from `bazel-gate.sh`'s mode-`local` skips. Its step
timeout (45 minutes) covers a cold compile plus the 1200 s per-action cap
(policy-tested against `.bazelrc`); warm runs take about 3.5 minutes.
`scripts/ci_workflow_test.go` fails when a new `bazel.yml` job has neither
a gate id nor an advisory entry.
Runbook: if `main`'s Bazel BUILD files drift (every PR's Bazel lanes go
red, and autofix only patches packages the PR itself changed), the RBE
farm is down, or the beads CI RBE client certificate expires (about
@ -152,7 +164,7 @@ fork PRs are unchanged.
- `farm` job: calls `bazel.yml` only when `authorize` allowed it, with
`contents: read`, exactly the four RBE secrets, `checkout-sha` =
`github.event.pull_request.head.sha`, `fork-farm: authorized`, and
`integration: "off"`. `bazel.yml` checks out that SHA in every lane with
`integration: "on"`. `bazel.yml` checks out that SHA in every lane with
`persist-credentials: false`. actions/checkout v7 refuses to check out a
fork PR's head on `pull_request_target` unless `allow-unsafe-pr-checkout`
is true. Each lane sets that input to
@ -170,7 +182,7 @@ fork PRs are unchanged.
- Gate: advisory. `pr.yml` is unchanged. Every fork PR, listed or not, still
runs the local Bazel lanes inside the enforced `CI Gate / Required`, and
the farm run adds a faster signal that also covers the remote-only
embedded, proxied-server and server-storage tiers.
embedded, integration, proxied-server and server-storage tiers.
- Policy tests: `scripts/bazel_farm_workflow_test.go` pins the trigger,
both jobs' conditions, the allowlist source, the pinned checkout, the
permissions, where secrets appear, and that no expression is interpolated

View file

@ -35,7 +35,7 @@ freshness source.
| `reference/json-schema.md` | `Last reviewed:` marker tied to `cmd/bd/output.go`, `cmd/bd/errors.go`, and protocol tests. (Mintlify port: was `JSON_SCHEMA.md`.) |
| `recovery/init-safety.md` | `Last reviewed:` marker tied to `cmd/bd/init*.go` safety code and tests. (Mintlify port: was `RECOVERY.md`.) |
| `ERROR_HANDLING.md` | `Last reviewed:` marker tied to current command error exits and JSON error helpers. |
| `LINTING.md` | `Last reviewed:` marker tied to `.golangci.yml`, `scripts/ci/pr-lint.sh`, the `Makefile` wrapper, and CI workflow wiring. |
| `LINTING.md` | `Last reviewed:` marker tied to `.golangci.yml`, `scripts/ci/pr-lint.sh`, `scripts/pr-lint/`, the `Makefile` wrapper, and CI workflow wiring. |
| `SERVE_RUNBOOK.md` | `Last reviewed:` marker tied to the operating-envelope constants in `internal/httpapi/server.go` and the log fields in its `event`/`request` emitters. |
| `CI_CLEANUP_PLAN.md` | `Last reviewed:` marker tied to the CI audit, workflow files, wrapper scripts, `Makefile`, package manifests, and maintainer decision review. |
| `design/otel/otel-data-model.md` | `Last reviewed:` marker tied to telemetry, Dolt storage, hooks, and AI call sites. |
@ -53,6 +53,7 @@ Follow-up automation should replace marker-only checks with generated or
| `adr/0001-multi-remote-approach.md` | Keep | ADR; historical decision record, not a live reference table. |
| `adr/0002-init-safety-invariants.md` | Keep | ADR backing `RECOVERY.md` and init safety code. |
| `adr/0003-provenance-event-log.md` | Keep | ADR; historical decision record for the `provenance_events` table and `bd provenance` command group. Status: Proposed pending a maintainer post on issue 4460. |
| `adr/0004-missing-database-guard-signal.md` | Keep | ADR; settles the proof-of-prior-init signal for the missing-database init guards. Extends `adr/0002`. Status: Proposed. |
| `ADVANCED.md` | Keep/revise as needed | User-facing advanced workflows; mixed command examples should defer to generated CLI reference when expanded. |
| `AIDER_INTEGRATION.md` | Keep | User-facing integration guide; evidence is setup/integration behaviour. |
| `ANTIVIRUS.md` | Keep | User-facing operational note; review vendor/version claims when touched. |

View file

@ -66,3 +66,63 @@ with `IsLitePartial == false`. This is correct-but-unoptimized (no lite
callers exist yet, so the difference is invisible today); wiring
`filter.Lite` through the domain/db stack is deferred to the CLI-wiring
follow-up (be-uwvs.2+), not part of this foundation.
## Summary projection — `store.SearchIssueSummaries`
`SearchIssueSummaries` is a third projection alongside the full and lite
shapes above. It returns `[]*types.IssueSummary` rather than
`[]*types.Issue`, selecting only `IssueSummaryColumns` — narrower than
`IssueSelectColumnsLite`, because it drops the routing/claim scalars
(`metadata`, `row_lock`, the `leases.*` overlay) a list-shaped render never
reads, not just the heavy TEXT bodies.
### Contract for callers
- **MAY** read every field `types.IssueSummary` declares. All of them come
from the row, so there is no `IsLitePartial` equivalent and no partial
state to detect — a field the type does not have is a compile error, not
a silent zero value. That is the difference from Lite: Lite returns a
full-shaped `*types.Issue` with some fields hollowed out, the summary
projection returns a narrower type.
- **MUST** call `store.SearchIssues` instead when dependencies are needed.
`types.IssueSummary` has no `Dependencies` field, so
`IssueFilter.IncludeDependencies` is a silent no-op on this path.
`SkipLabels` is honored exactly as it is on `SearchIssues`.
- **MAY** rely on wisps behaving identically. The issues+wisps merge in
`searchInTx` runs for any filter that does not set `SkipWisps`, and
`types.IssueSummary` carries the four wisp-plane markers (`Ephemeral`,
`NoHistory`, `WispType`, `StorageClass`), so a merged wisp row serializes
the same through either projection.
- **MAY** rely on identical ordering. `SortBy`/`SortDesc` render the same
SQL `ORDER BY`, and the post-merge re-sort uses `sqlbuild.LessSummary`,
which shares one comparator body with `sqlbuild.Less`.
### Where the contract is enforced
- Column list and scanner: `internal/storage/issueops/scan.go`
(`IssueSummaryColumns`, `ScanIssueSummaryFrom`).
- SELECT dispatch: `summaryProjection` in
`internal/storage/issueops/search.go` — a
`searchProjection[*types.IssueSummary]` literal on the same
`searchTableInTxT` core as the other two, so WHERE clauses, wisp merge,
dedup, trim and `MaxRows` cannot drift between them.
- Column/scanner guards:
`scan_test.go::TestIssueSummaryColumnsMatchScanner` (count agreement) and
`TestIssueSummaryColumnsAreRealIssueColumns` (every column exists on the
issues/wisps tables). Note `IssueSummaryColumns` is deliberately **not** a
subsequence of `IssueSelectColumns` in order, so it has no analogue of
`TestIssueSelectColumnsLite_IsFullMinusHeavyInOrder`.
- Wire-shape guards: `internal/types/issue_summary_test.go` pins
`IssueSummary`'s JSON tags against `Issue`'s field by field, including the
wisp markers.
- End-to-end parity: `internal/storage/dolt/search_parity_test.go` compares
`SearchIssues` against `SearchIssueSummaries` on a real database, across
filters and sort keys, and field by field for durable and wisp rows.
### Backend coverage
No in-tree caller reads `SearchIssueSummaries` yet — this is the storage
foundation, and the `bd list` wiring that spends it is tracked separately.
The proxied-server (`internal/storage/domain/db`) path does not implement
the narrow projection either, for the same reason `filter.Lite` is not
wired through it yet (above).

View file

@ -86,7 +86,7 @@ passes the tag inline (`-tags gms_pure_go`).
CI runs `scripts/check-build-tags.sh` on every PR (see the `Check build-tag
policy` job in `.github/workflows/pr.yml`). It fails if any tracked shell script,
CI workflow, git hook, or the Makefile contains a
git hook, or the Makefile contains a
`go build|test|run|generate|install` invocation that:
- does not carry `-tags=...gms_pure_go`, AND
@ -95,8 +95,19 @@ CI workflow, git hook, or the Makefile contains a
value contains `gms_pure_go`, AND
- is not a third-party tool install (`go install X@version` / `go run X@version`).
This is the source-time companion to `scripts/verify-cgo.sh` (runtime).
Between the two, an ICU regression cannot reach a release binary.
The required policy wrapper separately parses GitHub Actions YAML and checks
the first recognizable direct first-party Go command on each logical line in
`jobs.*.steps[*].run`. Each such command declares the literal `gms_pure_go` tag
in its own `-tags` argument;
sources and variables elsewhere in a workflow do not establish that source
convention. This is deliberately not shell control-flow analysis: dynamic
payloads, later compound-command segments, command substitutions, and
sourced-script internals are outside the check's contract. The pinned-tool
exception covers the repository's simple `go install path@version` and
`go run path@version` source forms.
These source-time guards complement `scripts/verify-cgo.sh`, which checks the
release binary at runtime.
To intentionally opt a file out (e.g. because it tests the ICU path),
add `# build-tags: allow-bare` within the first five lines of the file.

View file

@ -1,9 +1,9 @@
# Linting Policy
Last reviewed: 2026-09-03
Last reviewed: 2026-09-13
Freshness source: `.golangci.yml`, `scripts/ci/pr-lint.sh`, `Makefile`,
`.github/workflows/pr.yml`, and `.github/workflows/main.yml`.
Freshness source: `.golangci.yml`, `scripts/ci/pr-lint.sh`, `scripts/pr-lint/`,
`Makefile`, `.github/workflows/pr.yml`, and `.github/workflows/main.yml`.
This document explains the required Go lint gate for this codebase.
@ -37,14 +37,37 @@ answered.
The wrapper runs:
- `make fmt-check`;
- golangci-lint with `.golangci.yml`, readonly module downloads, a five-minute
timeout, the `gms_pure_go` build tag, and `--new-from-merge-base` when
`BD_LINT_NEW_FROM_MERGE_BASE` names a ref; and
- a second non-CGO Windows cross-lint pass, on the same scope, when the native
host does not already cover that target; and
- a third non-CGO darwin (arm64) cross-lint pass, on the same scope, under the
same rule, so `//go:build darwin` files are linted from the Linux runner.
- the shared `scripts/ci/fmt-check.sh` formatting check; and
- the checkout-owned `scripts/pr-lint` Go driver, which runs golangci-lint with
`.golangci.yml`, readonly module downloads, a five-minute timeout, the
`gms_pure_go` build tag, and `--new-from-merge-base` when
`BD_LINT_NEW_FROM_MERGE_BASE` names a ref, then runs the same scope for the
non-CGO Windows target and the non-CGO darwin (arm64) target when the native
host does not already cover them, so `//go:build windows && !cgo` and
`//go:build darwin` files are linted from the Linux runner.
The shell wrapper records one aggregate timing for the Go lint driver. The
driver prints a heading and result for each native or cross-target pass so
failures remain attributable without duplicating target-selection policy in
Bash.
The shared driver owns the lint passes used by `scripts/ci/pr-lint.sh` and
Beads-source `bd preflight`. The standalone workflow lint action and pre-commit
hook do not call it. The hook uses changed-lines scope, adds `--fix`, and omits
the Windows cross-lint pass. Workflow consolidation remains tracked in #5629.
The driver matches `.buildflags` when preparing `GOFLAGS`: appending
`-tags=gms_pure_go` can override an inherited bare-Go tags value; it does not
merge tag lists. Each lint process has a six-minute context and a five-minute
golangci-lint timeout. Cancelling preflight's outer `go run` command does not
guarantee immediate descendant cleanup.
On Windows, the driver checks each pass's selected Go SDK and prefers its
`bin` directory only in that linter child's PATH. This avoids an extra Go
auto-selection process surviving cancellation. Discovery shares the existing
30-second probe budget; custom SDKs that cannot be verified retain the original
PATH. Toolchain requests, formatting, and lint deadlines are unchanged. This
does not guarantee cleanup of compiler descendants or fix slow package loading.
## Policy
@ -66,7 +89,8 @@ test-fixture file reads, and documented security false positives.
`pr-lint` stays separate from `pr-policy` and `pr-core` so failures are easy to
identify and rerun. Its repository-owned wrapper is
`scripts/ci/pr-lint.sh`, exposed as `make ci-pr-lint`.
`scripts/ci/pr-lint.sh`, exposed as `make ci-pr-lint`; its lint policy is owned
by the shell-free `scripts/pr-lint` Go driver.
See [`CI_CLEANUP_PLAN.md`](CI_CLEANUP_PLAN.md) for the full CI tier policy.

View file

@ -152,6 +152,65 @@ external-dependency boundary. Keep new uses within the repository policy:
make check-testing-short
```
### Dolt Container Tests (podman-rootless)
Anything that does not carry `BEADS_TEST_SKIP=dolt` — including
`BEADS_TEST_ENV_RUN_DOLT=1` and a bare `go test` — reaches a real
`dolt sql-server`: by default through testcontainers-go where a container
runtime and the pinned image are present (otherwise those suites self-skip),
and from the local `dolt` CLI in the suites that use
`testutil.RequireDoltBinary`. Lanes that set
`BEADS_TEST_REQUIRE_DOLT_CONTAINER=1` fail instead of skipping. Two limitations
of the containerized path are worth recognizing before reading a failure as a
product bug. Neither failure mode manifests in production or on GitHub Actions:
CI exercises this same containerized path green on every risk-tier PR, and
`.github/workflows/pr-risk.yml` pulls the pinned image precisely to defeat the
self-skip. A hang there is a real bug, not this section's subject.
**Migration 0032 hangs over the wire protocol.** Migration `0032`
(`drop_schema_migrations_applied_at`) hangs indefinitely when applied through
the containerized sql-server. How it surfaces depends on the caller's context.
A `go test ./internal/storage/uow/... -count=1` with no `BEADS_TEST_SKIP`
passes `context.Background()`, so it sits in `initSchema` until the package
timeout rather than failing — that is the shape you will normally see, with no
deadline to cut it short. A caller that does supply one gets the hang reported
by the server-mode store open (`newServerMode` in
`internal/storage/dolt/store.go`) instead:
```
failed to initialize schema: context deadline exceeded
```
The cause is the podman-rootless container port-forwarding path, not migration
0032's SQL: the identical statement completes normally through the embedded/CLI
engine, and against a bare-host-process `dolt sql-server` matching the deployed
shape. Evidence chain in `be-j3szz`. Use `BEADS_TEST_SKIP=dolt` unless the
container path is what you are testing.
**Disabling Ryuk removes the container safety net.** This repository sets no
`TESTCONTAINERS_RYUK_DISABLED`, so CI runs with Ryuk — testcontainers-go's
orphan-reaper sidecar — enabled. The podman-rootless flow generally requires
turning it off by hand (`TESTCONTAINERS_RYUK_DISABLED=true`), because under
rootless podman Ryuk frequently cannot start: it wants the runtime socket. See
`be-w3n2m`. With Ryuk off, nothing reaps a container whose test process exited
without running its cleanup — `os.Exit` reached before a deferred
`TerminateDoltContainer`, for instance. `be-5kkk6` records the cost: 101 leaked
containers, and an exhausted swap. When running with Ryuk disabled, keep
teardown on the normal return path using the `testMainInner` pattern
(`beads_test.go`), and check for strays afterwards. Carry the rootless socket
this flow runs on — a bare `docker ps` talks to the CLI's default endpoint and
reports a false all-clear — and read the tag from the pin rather than copying
it, so the command cannot drift when the pin moves. An empty read would be the
same false all-clear (`ancestor=` matches nothing), so the command refuses to
run without a tag:
```bash
dolt_image=$(sed -n 's/.*DoltDockerImage = "\(.*\)".*/\1/p' \
"$(git rev-parse --show-toplevel)/internal/testutil/testdoltcommon.go")
DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock \
docker ps -a --filter "ancestor=${dolt_image:?could not read the Dolt image pin}"
```
## Test Design
### Seams, Scenarios, and Doubles

View file

@ -0,0 +1,172 @@
# ADR 0004 — missing-database init guard: proof-of-prior-init signal
## Status
Proposed — 2026-09-16.
Extends [ADR 0002](0002-init-safety-invariants.md), which established the
`bd init` safety invariants and the scope-bound `--force` / `--reinit-local`
rule. This ADR settles one question ADR 0002 left open: *what evidence proves
a workspace was initialized here before?*
## Context
Two places in `cmd/bd/init.go` must decide, with no opportunity to ask the
user, whether an apparently-missing server-side Dolt database means:
- **(a)** a genuine fresh clone, never initialized on this machine — safe to
create; or
- **(b)** a workspace that *was* initialized here and whose database is now
merely unreachable or lost — which must never be silently recreated.
The two sites are `checkExistingBeadsDataAt` (the default `bd init` path,
refuse-by-default) and `guardMissingServerDatabaseAt` (the safety net for
`--reinit-local` / `--force`, which bypass the first guard entirely).
Both used the same signal for the ambiguous case: `cfg.ProjectID != ""`, from
`.beads/metadata.json`, minted by `bd init` and originally added for
cross-project leak detection (GH#2372). That file is **git-tracked by
default** — `GitignoreTemplate` in `cmd/bd/doctor/gitignore.go` says so
explicitly — so a fresh clone inherits a `project_id` it never earned locally
(GH#2433). Worse, whether it is tracked depends on the consuming repo's own
`.gitignore`, so the signal's meaning varies per repository.
A prior fix in the same neighbourhood corrected a separate bug: both guards
were statting the Dolt **data directory** (`doltserver.ResolveDoltDir`) rather
than this project's own database inside it. That directory always exists once
anything has used the store — per-project mode `MkdirAll`s it in
`ensureDoltInit`, shared-server mode `MkdirAll`s the machine-global
`~/.beads/shared-server/dolt` in `SharedDoltDir()` — so the stat always
succeeded, the missing-vs-present branch was unreachable, and
`--recreate-missing`'s opt-in inside it was dead code. That fix introduced a
fine-grained probe of `<dolt-data-dir>/<database>/.dolt`.
### Why absence can never be promoted to proof
It is tempting to conclude that the fine-grained probe is the sound
replacement and `project_id` is legacy. That does not hold.
*Presence* of `<dolt-data-dir>/<database>/.dolt` is unambiguous proof: the
path is gitignored, so it can only exist because a real local process created
it. Its *absence* is consistent with two histories that must be treated
oppositely:
1. Genuine fresh clone — never initialized here. Safe to create.
2. Initialized here, and the local Dolt storage was subsequently lost — disk
wipe, volume reset, accidental `rm`, machine reimage. **This is the shape of
the 2026-08-11 fleet-wide data-loss incident** that motivated the guard.
Local filesystem state cannot distinguish these: it is the same "nothing here"
observation either way. There is no purely-local, low-friction fix.
### Local proof is structurally unavailable for remote hosts
The only code that creates a local `<dolt-data-dir>/<database>/.dolt` is
`doltserver.Start()` (via `ensureDoltInit`), called exclusively from
local-server-management sites. None reaches a remote host. So where
`isRemoteServerHost(host)` is true (`internal/doltserver/physical_root.go`),
the fine-grained probe is **permanently** silent — not only at fresh-clone
time but for the life of that workspace. The probe is a sound partial answer,
not a complete replacement.
## Decision
Formalize what the code already does for local hosts, keep `project_id` plus
`--recreate-missing` as the permanent answer where no local signal can exist,
and close one real gap between the two guards. No new mechanism, no new
persisted signal, no migration.
### Tier 1 — local per-database directory presence
`<dolt-data-dir>/<database>/.dolt`. Applicable whenever the configured host is
local, covering `ServerModeOwned` (local by construction) and `ServerModeExternal`
configurations resolving to loopback, including same-machine shared-server
mode. **Presence is unconditional proof, independent of `project_id`.**
### Tier 2 — `project_id`, gated behind Tier 1's absence
Retained unchanged in mechanism, as the sole signal once Tier 1 is silent or
inapplicable. Its weakness — inherited by clone, absent for pre-GH#2372
workspaces — is **accepted, not fixed**, because there is nothing purely local
to fix it with. The failure direction is deliberate: a false positive (fresh
clone refused) costs a documented flag; a false negative (real data silently
recreated) costs unrecoverable data.
### Resolution path — `--recreate-missing` is the design, not a stopgap
With its opt-in now reachable, reproducible and documented, handing the
operator an explicit per-invocation flag *is* the answer for every case where
no proof is available.
### Per-mode behaviour
| Configured host | Tier 1 applicable | Tier 1 present | Tier 1 absent, `project_id` present | Tier 1 absent, `project_id` absent |
|---|---|---|---|---|
| Local (Owned, or External resolving to loopback) | Yes | Proven | Refuse; `--recreate-missing` required | Coarse-directory permit condition (below) |
| Remote (External, non-loopback) | No — never populated | N/A | Refuse; `--recreate-missing` required | Allow (pre-GH#2372 carve-out) |
Embedded and proxied-server modes use their own existence checks and are out
of scope.
### The coarse-directory permit condition, and its accepted asymmetry
For the last cell, both guards apply a second, coarser local check: allow only
when the Dolt data directory itself is also absent. In `ServerModeOwned` that
directory is per-project, so it is a meaningful signal — "this project has
touched local Dolt storage before". In same-machine shared-server mode it is
the machine-global `~/.beads/shared-server/dolt`, created the moment *any*
project on the machine uses the shared server, so the cell is effectively
always conservative there.
This asymmetry is **accepted**. It fails toward refuse, it is resolved by the
same documented flag, and the affected population only shrinks — every
successful init or `--recreate-missing` run mints a `project_id`. Equalizing it
would need new mechanism for no safety gain.
## Consequences
- No new persisted signal, no schema change, no migration.
- `guardMissingServerDatabaseAt` gains one behavioural fix: it must run the
Tier 1 probe **unconditionally, before** consulting `project_id`, and apply
the same coarse-directory permit condition as `checkExistingBeadsDataAt`.
Previously it returned `nil` immediately on an empty `project_id`, so a
pre-GH#2372 workspace whose local database was lost was protected under
plain `bd init` but waved through under `--reinit-local` / `--force` — the
flags an operator reaches for in a panic were the weaker path.
- `checkExistingBeadsDataAt` does not change.
- The fresh-clone false positive (GH#2433) remains by design for the cells
where it is unavoidable.
- Both guards cite this ADR, so the question stops being re-litigated each
review round.
## Alternatives considered
- **A new local-only gitignored init marker.** Sound in principle, but fails
open across the entire pre-existing installed base until each workspace
re-inits under it — a real cost during a migration that has no defined end.
Rejected.
- **Repurposing `.local_version`.** Rejected outright: it is written by bd's
own `PersistentPreRunE` on any command that resolves a beads dir, including
the `bd init` invocation under test, before its own guard runs. It proves
"some bd command ran here", not "init succeeded here".
- **Dropping `project_id` in favour of the data-directory probe.** Rejected:
see "Why absence can never be promoted to proof".
- **Asking the server to distinguish an empty database from a populated one.**
Potentially a materially better signal for the fallback population, since it
asks something authoritative rather than something locally inherited. Out of
scope here: it needs a definition of "empty" that does not race with
`--from-jsonl` bootstrap import, and a decision on whether
`checkDatabaseOnServer`'s `Exists` becoming tri-state affects other callers.
Worth its own bead if pursued.
## References
- Decision bead: `be-5pjhd`, escalated from round-4 finding 2 on
[gastownhall/beads#5791](https://github.com/gastownhall/beads/pull/5791).
- Guard sites: `cmd/bd/init.go`, `checkExistingBeadsDataAt` and
`guardMissingServerDatabaseAt`.
- Guard matrix: `cmd/bd/init_guard_test.go`.
- Operator-facing limits: `docs/recovery/init-safety.md`.
- Host locality predicate: `isRemoteServerHost`,
`internal/doltserver/physical_root.go`.
- Prior init-safety decisions: [ADR 0002](0002-init-safety-invariants.md).

View file

@ -35,6 +35,11 @@ The decorator:
- rejects `parent-child` external edges: hierarchy has no foreign lifecycle
semantics, while scheduling edges have an explicit capability predicate;
- applies the same guard to checked close and batch blocked-state reads.
- guards explicit lifecycle claims (including `bd update --claim`) before any
accompanying edits, and carries external blockers into `bd close` batches.
Eligible items still close together in one local transaction; refused items
retain their positions in the results. `--force` waives close policy, but
never makes blocked work eligible for `--claim-next`.
- leaves non-blocking external relationships visible without allowing them to
gate readiness.
@ -54,6 +59,18 @@ existing atomic local `ClaimReadyIssue` operation. A concurrent foreign change
may therefore take effect on the next query, matching the historical SQLite
behavior without weakening local ready-selection or claim safety.
Direct batch closes pass an immutable external-blocker snapshot through an
internal policy-aware batch accessor. Hooks and telemetry forward that policy
to the existing batch executor, which applies both per-item refusals and claim
exclusions inside its one transaction. An unsupported decorator fails closed
instead of silently discarding the policy. The proxied UOW applies the same
guards through its decorated issue use case. Neither path adds a public request
field or persists foreign status locally.
Every non-forced batch close, and every batch close with a next claim, scans all
external blocking edges and resolves their foreign capabilities before the
local transaction. This shares the lookup-cost concern tracked in GH#6156.
## Verification
Regression tests cover unsatisfied and shipped capabilities, fail-closed

Some files were not shown because too many files have changed in this diff Show more