beads/cmd/bd/errors.go
Julian Knutsen 24a9da6cc7
test(proxy): topology-parameterized history and remote front-door matrix (#6269)
* feat(ga-p9iuv.22): add shared tracker proxy storage seam

* fix(ga-p9iuv.22): preserve tracker storage capabilities safely

* test(ga-p9iuv.22): cover tracker adapter label semantics

* test(ga-p9iuv.22): harden tracker adapter contracts

* fix(ga-p9iuv.22): reject invalid proxied tracker stores

* feat(ga-p9iuv.1): route Linear and Jira front doors through proxy store

* test(ga-p9iuv.1): exercise tracker mutations through UOW store

* fix(ga-p9iuv.1): preserve proxied Linear endpoint config

* test(ga-p9iuv.1): cover proxied Linear endpoint and direct config

* feat(ga-p9iuv.19): add typed proxied capability matrix

* feat(proxy): enforce typed capability matrix before provider

* test(proxy): cover command capability rows and claim caps

* test(proxy): check capability rows across topologies

* fix(proxy): validate capabilities before workspace side effects

* fix(proxy): refuse ready claim max rows caps

* feat(proxy): add shared maintenance capability policy

* fix(proxy): key maintenance refusals by command path

* test(proxy): cover nested maintenance refusals

* fix(proxy): enumerate nested maintenance command paths

* fix(proxy): refine compact and nested maintenance policy

* test(proxy): prove maintenance refusals preserve files

* fix(proxy): cover admin and remote maintenance refusals

* fix(proxy): refuse doctor before store initialization

* test(proxy): define history capability command matrix

* fix(proxy): wire history capability refusals to front door

* fix(proxy): refuse top-level sync history path

* fix(proxy): preserve maintenance refusal codes

* feat(proxy): classify history as supported UOW API

* feat(proxy): classify transform capability paths

* test(proxy): harden transform capability matrix

* fix(proxy): drive transform validation from exact rows

* fix(proxy): drive transform matrix from normalized flags

* fix(proxy): bound external backend dials per attempt

* test(proxy): cover bounded blocked backend dial

* fix(proxy): make transform capability policy row-driven

* fix(proxy): make transform capability policy row-driven

* fix(proxy): classify formula swarm and merge-slot refusals

* test(proxy): enforce workflow refusal contract

* fix(proxy): classify Dolt remote history boundaries

* test(proxy): enforce history refusal contract

* test(proxy): cover canceled backend dial cleanup

* test(proxy): cover real TCP blackhole cancellation

* test(proxy): cover external transport lifecycle matrix

* test(proxy): assert stable dial failure diagnostics

* test(proxy): add outage reconnect acceptance matrix

* test(proxy): make unix outage bridge restartable

* test(proxy): bound outage subprocess cleanup

* test(proxy): cover upstream restart with retained endpoint bridge

* test(proxy): stabilize managed-local outage contract

* fix(proxy): retire managed proxy when backend exits

* test(proxy): accept managed child retirement restart

* test(proxy): cover workflow refusals at bd front door

* test(proxy): cover history VC front doors

* test(proxy): pass valid workflow refusal arguments

* test(proxy): assert text and json refusal contracts

* test(proxy): assert exact workflow refusal codes

* test(proxy): guard refusal issue-row stability

* fix(proxy): expose non-mutating capability refusals

* test(proxy): match stable refusal text

* test(proxy): compare refusal artifact snapshots

* test(proxy): assert exact refusal messages

* test(proxy): retain direct workflow behavior

* test(proxy): match nested refusal messages

* test(proxy): cover direct-only front-door refusals

* test(proxy): provide valid direct-only command args

* fix(migrate): repair missing proxied sidecar on reentry

* fix: checkpoint Dolt mode migrations for safe retry

* fix: harden migration journal topology and retries

* fix: fsync migration journal removal

* fix: fail on migration journal directory sync errors

* fix: reject external ownership in every migration phase

* fix: enforce canonical shared migration topology

* fix: enforce live migration topology

* test: add migration front-door and topology regressions

* fix: require physical Dolt roots for migration

* test: strengthen migration front-door contracts

* fix: reject missing or invalid Dolt migration roots

* fix: keep shared migration dry-runs side-effect free

* fix: require Dolt repository identity for migrations

* fix: validate Dolt repository identity metadata

* fix: require typed Dolt repo state identity

* test: expand migration front-door CRUD assertions

* test: make migration JSON dry-run front-door safe

* test: sanitize Dolt environment for migration front door

* test: use cgo binary for migration front door

* test: omit empty Dolt overrides in migration front door

* test: isolate migration front door from test mode

* test: isolate home for migration front door

* test: stop supervised Dolt before reverse migration

* fix: reject empty Dolt head refs

* test: harden migration topology invariants

* test: harden external and shared topology refusals

* test: snapshot migration refusal artifacts

* test: cover external migration refusal phases

* fix: refuse stale proxied sidecars during migration

* test: strengthen migration artifact and external front door checks

* feat: type external migration refusals

* test: assert external refusal starts no proxy

* fix: validate migration journal sidecar topology

* fix: make sidecar recovery phase aware

* fix: honor persisted shared topology during migration

* test: exercise external journal migration front door matrix

* test(tracker): add shared conformance harness

* test: harden external migration matrix fixtures

* test: preserve durable dolt gate lock in matrix

* test: preseed gate lock for refusal matrix

* test: cover malformed migration state front door

* fix: type malformed migration config refusals

* fix: type migration preflight state errors

* test: separate migration JSON stdout from warnings

* test: reach typed malformed journal refusal

* test: assert migration retry phase and idempotence

* test: cover shared migration checkpoint retries

* fix: make reverse migration idempotent without sidecar

* test: cover proxied to shared retries

* fix: derive shared topology from persisted YAML

* fix: validate shared migration no-op state

* fix: allow completed proxied shared no-op

* fix: validate forward proxied no-op sidecar

* test: reject bad already-proxied sidecars

* fix: reject stale proxy controls on no-op

* fix: fail closed on malformed migration workspace yaml

* test: pin migration yaml topology precedence

* Cover forward migration no-op ownership refusals (ga-p9iuv.26.5.2)

Agent-Signature: unknown-model/unknown-reasoning

* Strengthen migration retry sentinel coverage (ga-p9iuv.26.1)

Agent-Signature: unknown-model/unknown-reasoning

* Expand migration fault retry artifact coverage (ga-p9iuv.26.1)

Agent-Signature: unknown-model/unknown-reasoning

* Add reverse migration frontdoor fault matrix (ga-p9iuv.26.1.1)

Agent-Signature: unknown-model/unknown-reasoning

* test: cover shared migration frontdoor fault matrices

* test: strengthen direct migration matrix assertions

* test: preserve migration dependency edges

* test: assert exact migration dependency edges

* test: parse migration dependency edges from batch list

* test: fix shared migration matrix compile

* test: verify shared dependencies before shutdown

* test(proxy): cover history remote front-door topology matrix

* docs: define direct-local ownership handoff contract

* fix(ci): repair pre-review CI failures on proxy parity branch

Five PR-introduced failures across the docs, PR Core, and Proxied Dolt Cmd
lanes. Each fix is scoped to the evidenced defect.

- test/docsync: TestEveryDocsPageIsPublished flagged
  docs/architecture/ownership-handoff-contract.md as unpublished. It is an
  internal Beads/Gas City handoff contract with no Mintlify frontmatter and
  no inbound links, so move it to engdocs/design/ beside its peers rather
  than publishing it.

- cmd/bd: TestProxyWorkflowRefusalContractAndNoMutation asserted on
  commandDidWrite, a process-wide atomic latch set by 71 non-test sites and
  never reset, so it reported an earlier test's write. Baseline and restore
  it around the assertion, matching the save/reset/restore idiom already
  used in proxied_lookup_failure_test.go and readonly_policy_test.go.

- cmd/bd: the new pre-provider gate short-circuited compact.go's refusal
  with new wording, breaking TestProxiedServerCompactDolt/non_dolt_mode_-
  rejected in an unchanged test. Restore the long-standing message; the
  proxy.compact.unsupported code is unchanged.

- internal/storage/dbproxy/proxy: the unix subtests bound sockets under
  t.TempDir(), whose embedded test name overflows macOS's ~104-byte
  sun_path limit ("bind: invalid argument"). Add unixSocketPath() to place
  them in a short temp dir.

- cmd/bd: migration topology compared recorded and canonical Dolt roots
  lexically, so macOS's /var -> /private/var symlink made equivalent paths
  compare unequal. Add sameMigrationRoot(), mirroring the existing
  resolveExistingPrefix idiom in cmd/bd/doctor/git.go.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(review): address blocker and major findings from adopt-pr review

Maintainer review fixup for the proxy parity branch, iterations 1-2.
Blockers and majors from the review synthesis and quality scorecard.

Blockers:

- cmd/bd/migrate_dolt_mode.go: resuming from migratePrepared rebuilt the
  migration plan from the current argv instead of replaying the recorded
  one. A resume that omitted or changed --idle-timeout wrote a sidecar the
  target_configured check then rejected, and because that check runs only
  after the phase advances past migratePrepared, the block never ran again
  — the workspace stayed wedged in proxied-server mode with no in-tool
  recovery. Replay j.Sidecar and warn when the supplied value is ignored.

- internal/tracker/store.go: NewStore double-wrapped already-adapted values.
  directStore embeds the storage.Storage interface, so *directStore also
  satisfies storage.Storage and was re-wrapped as
  &directStore{Storage: &directStore{...}}; the inner value can never
  satisfy storage.IssueLifecycleStore, which silently degraded
  ApplyIssueUpdate to a bare UpdateIssue — no labels, no lifecycle
  transaction. Match the tracker's own adapters by concrete type first.
  Testing value.(Store) first, as the review suggested, does not work:
  storage.Storage is a strict superset of Store, so a raw direct store
  satisfies Store too and would be returned un-adapted, relocating the same
  bug. The branch order is documented at the call site.

Majors:

- internal/tracker/store.go: directStore.ApplyIssueUpdate now calls
  syncIssueLabels, which normalizes both label sets (trim, drop empty) and
  restores the semantics the pull path had before this seam moved behind
  ApplyIssueUpdate. The un-normalized local copy churned remove+add on
  whitespace-only differences and let an empty label reach AddLabel; it is
  deleted rather than left as a second, divergent implementation.

- Both regressions were invisible to the suite. Adds
  TestNewEngineKeepsDirectStoreAdaptationIntact, TestNewStoreIsIdempotent,
  TestDirectStoreApplyIssueUpdateNormalizesLabels, and
  TestMigrateToProxiedServer_ResumeReplaysRecordedIdleTimeout (changed /
  omitted / never subtests, each also asserting the reverse-migration escape
  hatch still recovers). All four were verified to fail against the
  pre-fix production code with the predicted symptoms.

Non-gating follow-ups from the scorecard, fixed while nearby:

- cmd/bd/proxy_capability.go: treat ProxyOutcomeNA as "this command has no
  such flag" rather than a refusal, so an assert on an N/A row cannot return
  a non-nil error carrying an empty message.

- cmd/bd/errors.go: emit the rule's real Mutates value in the JSON refusal
  envelope instead of a hardcoded false.

- cmd/bd/main.go: the doctor pre-provider check returned unconditionally,
  so a nil result (every doctor subcommand) skipped the legacy-store guard
  and autocommit-mode resolution that other skipsStoreInit commands run.
  Return only on a real refusal.

- internal/tracker/engine.go: type NewEngine's store parameter as Store so
  the seam names its contract, and drop the now-dead applyPullIssueUpdate.

- CHANGELOG.md: record the proxied `bd ready --claim` row-cap refusal, which
  was a behavior change shipped without a release note.

Iteration 2 -- gating major (uowStore/directStore external_ref divergence):

- internal/tracker/uow_store.go: GetIssueByExternalRef resolved through a
  single merged search over both storage planes, which has no plane
  preference: it is a UNION ALL ordered by content and terminating in
  `id ASC`, so one external_ref present on both planes resolved to whichever
  row's id sorted first. The direct backend is explicitly issues-first --
  issueops.GetIssueByExternalRefInTx queries `issues` and falls through to
  `wisps` only on sql.ErrNoRows, and says why ("so that pushed ephemeral
  beads are found during pull dedup"). The consumer is the pull dedup, which
  updates whatever row comes back, so the divergence was a silent write to
  the wrong local bead under --proxied-server only. Query the issues plane
  first via SkipWisps, then fall back.

  The fallback is the merged search rather than the review's literal
  Ephemeral=true: that filter contributes an `ephemeral = 1` predicate the
  direct backend's `SELECT id FROM wisps WHERE external_ref = ?` does not
  have, and wisp-plane rows legitimately carry ephemeral=0 (NoHistory beads;
  see types.IssueFilter.EphemeralTier). Taking it literally would have traded
  one divergence for a narrower one. Verified: implementing the prescription
  fails the ephemeral_flag_clear subtest below.

- internal/tracker/uow_store_engine_test.go: the engine fake now models plane
  routing (SkipWisps / Ephemeral / merged) instead of one flat map, so the
  contract is expressible at all. Adds
  TestUOWStoreGetIssueByExternalRefPrefersIssuePlane, whose wisp id sorts
  first so "first merged hit" fails it, and
  TestUOWStoreGetIssueByExternalRefFallsBackToWispPlane over both ephemeral
  values. Verified to fail against the pre-fix uow_store.go.

- internal/tracker/conformance: the shared suite gains a Wisps plane and
  external_ref_resolution_prefers_issue_plane, so this is a contract both
  backends are held to rather than one adapter's unit test.

Iteration 2 -- non-gating follow-ups from the scorecard:

- cmd/bd/migrate_dolt_mode.go: scope the migratePrepared sidecar-equivalence
  check in runMigrateFromProxiedServer to reverse journals. A forward journal
  at that phase records the sidecar it is about to write, so a crash in the
  pre-write window leaves none on disk -- the correct state -- and the
  unscoped check refused the documented escape hatch by naming a missing
  file, stranding the workspace. Tested against TargetMode's forward value so
  the guard stays live for both reverse targets, "server" and
  "shared-server". Adds
  TestMigrateFromProxiedServer_ForwardJournalAtPreparedIsNotSidecarRefused,
  verified to fail against the unscoped guard.

- cmd/bd/linear.go: buildLinearClientAPIOnly returned the OAuth client inline
  and never reached the WithEndpoint block, so a configured
  linear.api_endpoint was honored for an API key and ignored for OAuth. Hoist
  the endpoint application after the branch, as Tracker.Init does, and add
  the OAuth mirror of the existing endpoint test.

- cmd/bd/ready_max_rows_proxied_test.go: pin the proxied --max-rows refusal
  on `bd ready --claim`. It lives in RunE above the dispatch and nothing
  below it can enforce a cap, but the existing coverage all sits below it.
  Covers both cap sources (--max-rows and BEADS_MAX_ROWS) and the negative
  case that the refusal is conditioned on a live cap, not on --claim.

- engdocs/design/ownership-handoff-contract.md: trim the trailing blank line
  at EOF flagged by `git diff --check`.

Iteration 3 -- non-gating residual on the iteration-2 fix:

- internal/tracker/uow_store.go: the issues-first fix above split one logical
  lookup across two read transactions. uow.RunTxRead opens a fresh unit of
  work per call, so calling s.SearchIssues twice left the wisp fallback's
  premise -- "the issues plane is already known empty" -- without a shared
  snapshot: a concurrent same-ref insert into the issues plane landing between
  the two reads could let the merged fallback return the wisp, re-creating the
  wrong-row write that ordering exists to prevent. The consumer is the pull
  dedup loop, so it runs per imported issue. Both plane reads now share a
  single RunTxRead, which is also the shape the direct backend uses (both
  planes inside one withReadTx). Plane ordering is unchanged.

- internal/tracker/uow_store_engine_test.go: the engine fake counts the units
  of work it hands out, and
  TestUOWStoreGetIssueByExternalRefUsesOneReadTransaction pins that count at 1
  across the two paths that actually perform both reads -- the wisp fallback
  and the miss. An issues-plane hit short-circuits after one read and would
  pass either way, so it is not a case. Verified to fail against the
  two-transaction version with "opened 2, want 1".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-05 08:25:49 -07:00

355 lines
14 KiB
Go

package main
import (
"encoding/json"
"errors"
"fmt"
"os"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/migration"
"github.com/steveyegge/beads/internal/ui"
)
type exitError struct {
Code int
}
func (e *exitError) Error() string {
return fmt.Sprintf("exit code %d", e.Code)
}
func exitCodeFromError(err error) (int, bool) {
var ee *exitError
if errors.As(err, &ee) {
return ee.Code, true
}
return 0, false
}
func activeWorkspaceNotFoundError() string {
return "no active beads workspace found"
}
func activeWorkspaceNotFoundMessage() string {
return "No active beads workspace found."
}
func diagHint() string {
return workspaceDiagHint(true)
}
func whereDiagHint() string {
return workspaceDiagHint(false)
}
func workspaceDiagHint(includeWhere bool) string {
if includeWhere {
if !usesSQLServer() {
return "run 'bd where' to inspect the resolved workspace, or 'bd init' to create a new database"
}
return "run 'bd where' to inspect the resolved workspace, run 'bd doctor' to diagnose, or 'bd init' to create a new database"
}
if !usesSQLServer() {
return "check BEADS_DIR/worktree setup, or run 'bd init' to create a new database"
}
return "check BEADS_DIR/worktree setup, run 'bd doctor' to diagnose, or run 'bd init' to create a new database"
}
func buildJSONError(message, hint string) interface{} {
inner := map[string]interface{}{
"error": message,
}
if hint != "" {
inner["hint"] = hint
}
if jsonEnvelopeEnabled() {
return map[string]interface{}{
"schema_version": JSONSchemaVersion,
"data": inner,
}
}
inner["schema_version"] = JSONSchemaVersion
return inner
}
func buildJSONCapabilityError(e *ProxyCapabilityError) interface{} {
inner := map[string]interface{}{"error": e.Message, "code": e.Code, "mutates": e.Mutates}
if jsonEnvelopeEnabled() {
return map[string]interface{}{"schema_version": JSONSchemaVersion, "data": inner}
}
inner["schema_version"] = JSONSchemaVersion
return inner
}
// HandleProxyCapabilityError renders a stable capability refusal while
// preserving the normal text/JSON front-door conventions.
func HandleProxyCapabilityError(err error) error {
var capErr *ProxyCapabilityError
if !errors.As(err, &capErr) {
return HandleErrorRespectJSON("%v", err)
}
code := capErr.ExitCode
if code == 0 {
code = 1
}
if jsonOutput {
enc := json.NewEncoder(os.Stdout)
enc.SetIndent("", " ")
_ = enc.Encode(buildJSONCapabilityError(capErr))
} else {
fmt.Fprintf(os.Stderr, "Error: %s\n", capErr.Message)
}
return &exitError{Code: code}
}
func jsonStderrError(message, hint string) {
encoder := json.NewEncoder(os.Stderr)
encoder.SetIndent("", " ")
_ = encoder.Encode(buildJSONError(message, hint))
}
func jsonStdoutError(message, hint string) {
encoder := json.NewEncoder(os.Stdout)
encoder.SetIndent("", " ")
_ = encoder.Encode(buildJSONError(message, hint))
}
func HandleError(format string, args ...interface{}) error {
fmt.Fprintf(os.Stderr, "Error: "+format+"\n", args...)
return &exitError{Code: 1}
}
func HandleErrorRespectJSON(format string, args ...interface{}) error {
if jsonOutput {
jsonStdoutError(fmt.Sprintf(format, args...), "")
return &exitError{Code: 1}
}
return HandleError(format, args...)
}
func HandleErrorWithHint(message, hint string) error {
if jsonOutput {
jsonStderrError(message, hint)
} else {
fmt.Fprintf(os.Stderr, "Error: %s\n", message) //nolint:gosec // G705: stderr, not a browser context
fmt.Fprintf(os.Stderr, "Hint: %s\n", hint) //nolint:gosec // G705: stderr, not a browser context
}
return &exitError{Code: 1}
}
func HandleErrorWithHintRespectJSON(message, hint string) error {
if jsonOutput {
jsonStdoutError(message, hint)
} else {
fmt.Fprintf(os.Stderr, "Error: %s\n", message)
fmt.Fprintf(os.Stderr, "Hint: %s\n", hint)
}
return &exitError{Code: 1}
}
func SilentExit() error {
return &exitError{Code: 1}
}
func WarnError(format string, args ...interface{}) {
fmt.Fprintf(os.Stderr, "Warning: "+format+"\n", args...)
}
// ExitMigrationFrozen is the exit code for a write refused because a
// migration freeze marker is active (dc-6jaq). Stable value so scripts can
// branch on "someone is migrating this workspace, come back later" without
// grep'ing stderr, instead of reading it as a generic failure (1) worth
// retrying immediately.
const ExitMigrationFrozen = 14
// CheckReadonly aborts the command when bd is running in read-only mode (the
// worker-sandbox posture, see readonlyMode), or when a migration freeze
// marker is active (dc-6jaq, folded in here rather than requiring every write
// command to remember a second call — see migrationFreezeError below). This
// is the chokepoint essentially every write command already calls first, so
// folding the freeze check in here covers the whole write surface at once,
// including commands added after this comment is written — not just a
// hand-picked list that rots (one concrete instance the hand-picked list
// missed: "bd q", cmd/bd/quick.go, the create alias). It exits via os.Exit
// and so cannot run the per-command deferred CloseEventAndAdd — a command
// blocked here records no cli_command event of its own (it never actually
// ran). It does flush metrics first, so events already queued earlier in this
// run are still written and scheduled for upload rather than stranded until
// the next clean exit. Callers that CAN return an error (the root
// PersistentPreRunE, runImport) call migrationFreezeError directly instead,
// so their deferred cleanup still runs.
func CheckReadonly(operation string) {
if readonlyMode {
fmt.Fprintf(os.Stderr, "Error: operation '%s' is not allowed in read-only mode\n", operation)
metrics.CloseAndFlush()
os.Exit(1)
}
if err := migrationFreezeError(operation); err != nil {
metrics.CloseAndFlush()
os.Exit(ExitMigrationFrozen)
}
}
// freezeSearchRoots returns the directories whose ancestry the freeze lookup
// must cover in addition to the working directory: the resolved workspace, so
// the gate keys on the store being written rather than on the caller's shell.
// Without it, `BEADS_DIR=/work/repo/.beads bd create` run from $HOME, `bd -C
// /work/repo create` (which sets BEADS_DIR and never chdirs), and any daemon
// or cron job with an unrelated cwd all walk the wrong tree and write straight
// through a freeze.
//
// PersistentPreRunE exports BEADS_DIR as part of selecting the workspace
// (prepareSelectedCommandContext), so by the time a command's RunE reaches
// CheckReadonly this is a cheap env read. The FindBeadsDir fallback covers the
// callers that run before that — and returns "" rather than erroring when
// there is no workspace at all, which Find skips.
func freezeSearchRoots() []string {
if dir := os.Getenv("BEADS_DIR"); dir != "" {
return []string{dir}
}
if dir := beads.FindBeadsDir(); dir != "" {
return []string{dir}
}
return nil
}
// migrationFreezeError reports the active migration freeze, if any: it
// returns nil when writes are not frozen, and otherwise prints the refusal to
// stderr and returns an ExitMigrationFrozen exit error. The refusal names the
// marker's own path, so the recovery instruction ("remove that file") is
// always actionable without knowing what created it.
//
// Three callers, each closing a different hole:
// 1. CheckReadonly above — the per-command chokepoint covering the write
// surface at large (create/update/close/... and everything that calls
// CheckReadonly, ~120 sites). Only that caller turns this error into an
// os.Exit, because its void signature leaves it nothing else to do.
// 2. The root PersistentPreRunE in main.go, before autoMigrateOnVersionBump
// and maybeAutoImportJSONL — those run as store-open side effects
// *before* any RunE, so waiting for a write command's own CheckReadonly
// call would let a version-bump migration or a JSONL auto-import slip
// through a freeze first (the most dangerous writes here, since they
// run against the very store the freeze protects).
// 3. import.go directly — bd import (runImport) is not gated by
// CheckReadonly at all today (a pre-existing, separate gap: readonlyMode
// doesn't block it either), so it cannot inherit the freeze check from
// caller 1 and needs its own explicit call.
func migrationFreezeError(operation string) error {
return migrationFreezeRefusal(operation, migration.Find(freezeSearchRoots()...))
}
// migrationFreezeRefusal renders an already-resolved lookup. Callers that
// need the same Result for more than the refusal — PersistentPreRunE, which
// also derives frozenForMaintenance from it — resolve once and pass it here,
// so a single walk answers the whole invocation and the two readings cannot
// disagree about a marker that appeared or vanished between them.
func migrationFreezeRefusal(operation string, res migration.Result) error {
if !res.Frozen() {
return nil
}
if res.Err != nil {
// Fail closed: bd could not tell whether a marker is present (a
// permission error on the marker or a directory above it). An
// undeterminable gate is not an open gate, and saying so beats
// writing into a workspace that may be mid-migration.
fmt.Fprint(os.Stderr, "⛔ ERROR: cannot determine whether this workspace is frozen for migration.\n")
fmt.Fprintf(os.Stderr, " %s\n", ui.SanitizeForTerminal(res.Err.Error()))
fmt.Fprintf(os.Stderr, " bd %s is blocked until the marker can be read.\n", operation)
fmt.Fprintf(os.Stderr, " Fix the permissions, or set %s to a path bd can stat.\n", migration.EnvFreezeFile)
return &exitError{Code: ExitMigrationFrozen}
}
// The marker can live in a directory bd does not control, so its payload
// is untrusted input on its way to a terminal. parse already keeps it to
// one line; sanitizing strips ANSI and control bytes on top of that.
operator := ""
reason := ""
if info := migration.ReadFile(res.Path); info != nil {
operator = ui.SanitizeForTerminal(info.Operator)
reason = ui.SanitizeForTerminal(info.Reason)
}
if operator != "" {
fmt.Fprintf(os.Stderr, "⛔ ERROR: workspace is frozen for migration (by %s).\n", operator)
} else {
// An empty or unparseable marker (a bare `touch`) records no
// operator; say nothing rather than printing "(by )".
fmt.Fprint(os.Stderr, "⛔ ERROR: workspace is frozen for migration.\n")
}
if reason != "" {
fmt.Fprintf(os.Stderr, " Reason: %s\n", reason)
}
fmt.Fprintf(os.Stderr, " bd %s is blocked by the freeze marker at %s.\n", operation, res.Path)
if res.FromEnv {
fmt.Fprintf(os.Stderr, " To resume writes, remove that file or unset %s.\n", migration.EnvFreezeFile)
} else {
// Name the variable on this path too: when the marker sits in a
// directory the caller cannot write to, pointing the variable
// elsewhere is the only recovery available to them.
fmt.Fprint(os.Stderr, " To resume writes, remove that file.\n")
fmt.Fprintf(os.Stderr, " If you cannot remove it, set %s to a path bd should check instead.\n", migration.EnvFreezeFile)
}
return &exitError{Code: ExitMigrationFrozen}
}
// migrationFreezeGate is the RunE-side entry point: it renders the refusal and,
// because the refusal has already said everything worth saying, suppresses
// cobra's own error and usage rendering for this invocation.
//
// Without the suppression a freeze refusal on any command that does not set
// SilenceErrors/SilenceUsage statically — duplicate, supersede, dep
// relate/unrelate, backup init/sync/remove/restore, ado sync, migrate-personal,
// batch — is followed by "Error: exit code 14" (exitError's placeholder text)
// and a full usage dump, so a clean refusal reads like a syntax error. Setting
// the flags here rather than on each command covers the ones added after this
// comment too. main() exits on the exitError before its own SilenceErrors
// branch, so nothing prints the placeholder.
func migrationFreezeGate(cmd *cobra.Command, operation string, res migration.Result) error {
err := migrationFreezeRefusal(operation, res)
if err != nil && cmd != nil {
cmd.SilenceErrors = true
cmd.SilenceUsage = true
}
return err
}
// migrationFreezeGateFor resolves the freeze and gates in one step, for the
// callers that have no Result to thread: the skip-store commands (bd init,
// bd bootstrap), which return from PersistentPreRunE long before it resolves
// one, and any command handed an explicit target path.
func migrationFreezeGateFor(cmd *cobra.Command, operation string, extraRoots ...string) error {
return migrationFreezeGate(cmd, operation, migration.Find(freezeRootsWith(extraRoots)...))
}
// migrationFreezeErrorFor is migrationFreezeError against extra roots, for
// callers that hold a target path but no *cobra.Command to silence — a command
// given a workspace to operate on that is not the one it was launched in.
func migrationFreezeErrorFor(operation string, extraRoots ...string) error {
return migrationFreezeRefusal(operation, migration.Find(freezeRootsWith(extraRoots)...))
}
// migrationFreezeActive is the print-nothing probe for code that must SKIP a
// write during a freeze rather than refuse the whole command — the diagnosis
// paths that keep running while frozen but must not apply version tracking or
// schema auto-migration.
func migrationFreezeActive() bool {
return migrationFreezeActiveFor()
}
// migrationFreezeActiveFor is migrationFreezeActive against extra roots — the
// probe half of the migrationFreezeErrorFor pair, for a diagnosis path handed a
// workspace that is not the one bd was launched in. `bd doctor /frozen/repo`
// skips its own maintenance writes on the strength of this, so it has to look
// at the tree it is about to write to and not just at the caller's cwd.
func migrationFreezeActiveFor(extraRoots ...string) bool {
return migration.Find(freezeRootsWith(extraRoots)...).Frozen()
}
func freezeRootsWith(extraRoots []string) []string {
return append(freezeSearchRoots(), extraRoots...)
}