beads/internal/doltversion/version.go
matt wilkie 21834e720d
feat(doltversion): dolt CLI discovery, hardened version probe, and warn-only version policy (contract part 1) (#5092)
* feat(doltversion): own dolt CLI discovery, hardened probe, and version policy in a leaf package

PR-1 of the dolt CLI install/version contract (design:
mybd reports/2026-07-25-psxg4-dolt-cli-contract-design.md). The dolt
executable managed proxied-server mode spawns was discovered by a bare
exec.LookPath with no override, probed nowhere, and version-checked only
by one advisory archive_level probe; a missing binary erred after
.beads/ creation and an incompatible one died opaquely.

internal/doltversion (stdlib-only) now owns:
- resolution order BEADS_DOLT_BIN env > clone-local sidecar (hook point;
  the sidecar itself lands with identity threading in PR-2) > PATH.
  Explicit values are absolutized before validation (a bare name would
  otherwise validate the cwd file but exec a PATH lookup) and an
  explicitly-named broken binary is an error, never a silent
  fall-through;
- a hardened probe: timeout + process kill, 64KiB output caps,
  unconditional symlink resolution recording given and real paths,
  errno-based exec-format diagnostics naming the likely arch mismatch,
  and file identity captured for later change detection;
- version parsing generalized from the archive_level probe, tolerating
  prerelease/dev suffixes;
- policy: NO hard version floor (adversarial review rejected 2.2.0 as
  policy-without-evidence); RecommendedMin 2.0.0 warns only, backed by
  the 2026-07-25 cross-version matrix run (cross-read of module-written
  storage requires >= 2.0.0). An unparseable version string is likewise
  a warning, not a refusal - the only hard failures are a missing,
  non-executable, or probe-failing binary.

Wired at the two entry points: the managed proxied UOW factory replaces
its bare LookPath and derives archive-level support from the probe it
already ran (no second dolt-version fork on the per-command hot path;
warning is printed once, suppressed under --quiet/--json), and bd init's
proxied preflight fails before any .beads/ write when the binary is
missing or broken (external proxied config is exempt - bd never spawns
that server). doltserver.Start's own bare LookPath is deliberately
untouched here; identity threading through every spawn site is PR-2.

Agent-Signature: claude-fable-5-medium on behalf of matt wilkie
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AQHiBWVPSXDCcUSG9EGw9d

* fix(doltversion): fail closed on prerelease archive_level; dedupe dolt advisory

Two review findings on this PR (see reports/2026-07-26-reviewer-dispatch-sweep.md
#5092 for the adversarial-review reasoning):

1. archive_level fail-open regression (major, re gastownhall/beads#4986).
   newManagedProxiedServerUOWProvider derived archiveLevelSupported straight
   from doltID.Version.AtLeast(MinDoltVersionForArchiveLevelConfig), but
   AtLeast deliberately ignores Version.Prerelease (by design, for the
   separate warn-only RecommendedMin check). That meant a prerelease build
   at or above the floor, e.g. "1.52.1-rc1", satisfied the >= 1.52.1 gate
   and had auto_gc_behavior.archive_level written into the YAML — even
   though the old doltVersionAtLeast (gc_config.go) already failed closed
   for any prerelease-suffixed string via strconv.Atoi. If that prerelease
   build predates the field, dolt sql-server's yaml.UnmarshalStrict refuses
   to start: the exact #4986 regression. Extracted the derivation into
   doltArchiveLevelSupported(id) and added a Prerelease == "" gate, plus
   TestDoltArchiveLevelSupported (table test covering above/at/below the
   floor and prerelease-at/-above-floor) and
   TestDoltArchiveLevelSupported_UnparsedVersionFailsClosed.

2. Duplicate dolt-version advisory (major, UX). `bd init --proxied-server`
   probed and printed the version-recommendation warning twice: once in its
   own preflight (init_proxied_server.go) and again ~90 lines later when
   newProxiedServerUOWProvider reaches newManagedProxiedServerUOWProvider,
   which resolved+probed again. The existing doltVersionWarnOnce didn't
   cover init's own Fprintf. Extracted one shared resolveAndProbeDolt(ctx,
   errPrefix) helper (uow_factory.go) that does resolve + probe +
   once-gated warn, called from both sites; init_proxied_server.go no
   longer needs its own copy of the Resolve/ProbeWithPolicy/error-wrapping
   sequence. This also folds the two call sites' warning gates (previously
   !in.quiet vs !quietFlag && !jsonOutput) into one JSON-mode-safe gate.

Verified: CGO_ENABLED=1 go build -tags gms_pure_go ./... clean;
CGO_ENABLED=1 go vet -tags gms_pure_go ./cmd/bd/... clean; gofmt -l on all
changed files empty; targeted tests pass (TestDoltArchiveLevelSupported,
TestDoltArchiveLevelSupported_UnparsedVersionFailsClosed,
TestNewProxiedServerUOWProvider_RoutesExternalConfigToExternalProvider,
TestNewExternalProxiedServerUOWProvider_*, TestBuildProxiedServerClientInfo,
and internal/doltversion's own suite).

Agent-Signature: builder-unknown-model-unknown-reasoning on behalf of maphew

* test(doltversion): resolve symlinks in RealPath expectations (macOS fix)

TestProbeNormalOutput and TestProbeSymlink failed on macOS CI because
t.TempDir lives under /var/folders, itself a symlink to
/private/var/folders. Probe derives RealPath via filepath.EvalSymlinks,
so it correctly returned the /private/var form while the tests compared
against the raw TempDir path.

Map the expected path through the same EvalSymlinks resolution (new
resolveSymlinks test helper). Verified against a symlinked TMPDIR on
Linux, which reproduced the failure before this change.

Agent-Signature: claude-fable-5-high on behalf of maphew

* refactor(cmd/bd): narrow resolveAndProbeDolt to drop the unused identity return

Upstream removed the archive-level gate from proxied-server mode
(68afa3d51), which was the only consumer of the probed identity at these
call sites; returning it now trips unparam on the PR-introduced line.
PR-2's revalidation consumer re-widens the signature when it lands.

Agent-Signature: claude-fable-5-high on behalf of maphew

* fix(doltversion): cross-process probe cache, PATHEXT completion, daily warning dedup

Review fixes (all three MERGE-AFTER-FIXES items from the 2026-08-10 review):

1. The per-command `dolt version` fork on the store-open hot path is gone
   for the steady state: ProbeWithPolicyCached fronts the fork with a JSON
   cache in the user cache dir, keyed by the binary's (real path, size,
   mtime) fingerprint - the exact fields Identity documents for caching.
   A fingerprint hit costs a stat; any change to the binary re-probes.
   Hard probe errors are never cached, and every cache failure direction
   fails open to the uncached behavior.

2. Windows: an explicit BEADS_DOLT_BIN spelled without its extension now
   completes via exec.LookPath's PATHEXT handling (exact spelled path wins
   when both exist), and the behavioral tests run on Windows through .cmd
   stubs instead of skipping wholesale - plus a focused windows-latest CI
   job (test-windows-liveness pattern) so those branches actually execute
   at PR time. skipOnWindows remains only where the subject genuinely
   doesn't exist there (exec-bit check, symlink creation).

3. The old/unverifiable-version advisory now repeats at most once per day
   (warn stamp in the same cache file) instead of on every bd invocation;
   troubleshooting docs state the cadence.

Nits from the same review: Ctrl-C during the probe no longer prints the
misleading install hint (call site branches on context.Canceled); Probe's
stat branch now uses validateExplicitPath's not-found/not-executable
taxonomy split; ParseVersion documents its trailing-integer laxity and the
tightening required before part-2 enforcement.

Agent-Signature: claude-fable-5-high on behalf of maphew

* fix(doltversion): honor init's local --quiet for the advisory; defer sidecar claim in docs

Cross-vendor review follow-ups: bd init defines a local --quiet that
shadows the persistent flag, so resolveAndProbeDolt now takes quiet as a
parameter (init passes in.quiet || quietFlag) instead of reading the
global; and the troubleshooting entry no longer advertises the clone-local
sidecar resolution source, which is a part-2 hook not yet wired
(SidecarValue is always empty in this PR).

Agent-Signature: claude-fable-5-high on behalf of maphew

* test: stop the Windows counting stub double-counting forks

cmd.exe includes the space before a mid-line '>>' in the written text,
so the batch stub's 'set /p =x >> file' appended two bytes ('x ') per
invocation and forkCount — which counts bytes — read every fork as two.
All four Windows failures were exactly doubled expectations; the cache
itself hit and skipped forks correctly. Lead with the redirection so
exactly one byte lands per invocation.

Agent-Signature: claude-fable-5-high on behalf of maphew
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019CwiLhLbAGZdJtKYT76CPp

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-12 21:18:24 -07:00

160 lines
6.7 KiB
Go

// Package doltversion owns discovery, hardened probing, and version parsing
// for the external `dolt` CLI executable that managed proxied-server mode
// spawns. It exists as a stdlib-only leaf package (no dependency on
// internal/doltserver or internal/config) so it can be imported early — from
// preflight checks that must run before any beads state is written — without
// dragging in the rest of the storage stack.
//
// The package intentionally separates three concerns that used to be
// entangled at call sites: *where* the dolt binary comes from (Resolve),
// *whether it actually works* (Probe / ProbeWithPolicy), and *what version it
// claims to be* (ParseVersion). Splitting them lets each be tested and
// reasoned about independently, and lets callers report precisely which step
// failed instead of a single opaque "dolt not usable" error.
package doltversion
import (
"fmt"
"strconv"
"strings"
)
// Version is a comparable representation of a `dolt version` version string,
// e.g. "1.52.3" or "2.0.0-beta1". Segments holds the dotted numeric
// components in order (major, minor, patch, ...); Prerelease holds any
// suffix after a '-' (e.g. "beta1" or "dev"), preserved verbatim but ignored
// by AtLeast — a prerelease build of dolt 2.0.0 should still satisfy a >=
// 2.0.0 recommendation, since prerelease/dev builds are usually *newer* than
// the tagged version they're built from, not older. Raw retains the original
// input for error messages and display.
type Version struct {
Segments []int
Prerelease string
Raw string
}
// ParseVersion extracts and generalizes the version-parsing logic that
// previously lived only in internal/doltserver/gc_config.go
// (doltVersionAtLeast): it reads the first line of `dolt version` output
// (subsequent lines, such as "database storage format: ..." printed when run
// inside a Dolt repo, are ignored), takes the last whitespace-separated
// field of that line as the version token, and parses it as a dotted
// sequence of non-negative integers with an optional "-<prerelease>" suffix.
//
// This is deliberately more permissive than a strict semver parser: real
// `dolt version` output has taken forms like "dolt version 1.52.3" and (for
// dev builds) "dolt version 1.52.3-dev-abcdef", and the goal here is to
// extract a usable, comparable version from whatever dolt prints rather than
// to validate that dolt's own output is well-formed semver.
//
// A consequence worth naming: any first line whose last field parses as a
// dotted integer sequence passes — "dolt build 2023" yields version "2023",
// which sails over RecommendedMin. Acceptable while the consumer is
// warn-only policy; if a later change makes this the parser behind a hard
// enforcement floor (the part-2 revalidation contract), tighten it to
// require at least two dotted segments or an explicit "version" marker
// before the token, so a stray trailing integer cannot satisfy a gate.
func ParseVersion(output string) (Version, error) {
firstLine := output
if idx := strings.IndexByte(output, '\n'); idx >= 0 {
firstLine = output[:idx]
}
firstLine = strings.TrimSpace(firstLine)
fields := strings.Fields(firstLine)
if len(fields) == 0 {
return Version{}, fmt.Errorf("%w: empty version output", ErrUnparseableVersion)
}
return parseToken(fields[len(fields)-1])
}
// parseToken parses a single version token (e.g. "1.52.3" or
// "2.0.0-beta1") into a Version, with no notion of "first line" or
// "whitespace-separated fields" — that framing belongs to ParseVersion,
// which extracts a token from raw `dolt version` output before calling
// this. It is factored out so MustParse can validate a literal version
// string directly, without going through ParseVersion's
// output-line-scraping (which would otherwise require MustParse to
// synthesize fake surrounding "dolt version " text just to satisfy
// ParseVersion's parsing shape, and would silently accept garbage like
// "a b 1.2" by treating everything before the last field as ignorable
// prose).
func parseToken(token string) (Version, error) {
main, prerelease, _ := strings.Cut(token, "-")
if main == "" {
return Version{}, fmt.Errorf("%w: %q", ErrUnparseableVersion, token)
}
parts := strings.Split(main, ".")
segments := make([]int, 0, len(parts))
for _, p := range parts {
n, err := strconv.Atoi(p)
if err != nil || n < 0 {
return Version{}, fmt.Errorf("%w: %q", ErrUnparseableVersion, token)
}
segments = append(segments, n)
}
return Version{Segments: segments, Prerelease: prerelease, Raw: token}, nil
}
// MustParse parses s (a bare version token, e.g. "2.0.0" — not full `dolt
// version` command output) and panics on error. It exists for declaring
// policy constants (see RecommendedMin) where the input is a hardcoded
// literal and a parse failure would be a programming error caught
// immediately by any test or use of the package, not a runtime condition
// to handle gracefully. It calls parseToken directly rather than
// ParseVersion so a malformed literal like "a b 1.2" is rejected outright
// instead of ParseVersion's output-scraping treating "a b" as ignorable
// leading prose and silently accepting the trailing "1.2".
func MustParse(s string) Version {
v, err := parseToken(s)
if err != nil {
panic(fmt.Sprintf("doltversion: MustParse(%q): %v", s, err))
}
return v
}
// AtLeast reports whether v is greater than or equal to other, comparing
// Segments numerically position by position (a missing trailing segment is
// treated as 0, so "1.52" >= "1.52.0"). Prerelease/build suffixes are
// ignored for this comparison: policy floors in this package (see
// RecommendedMin) are about the underlying storage-format-relevant release,
// and a "-dev" or "-beta1" build of that release or later should not be
// treated as failing the floor just because it isn't a clean tagged release.
func (v Version) AtLeast(other Version) bool {
n := len(v.Segments)
if len(other.Segments) > n {
n = len(other.Segments)
}
for i := 0; i < n; i++ {
var a, b int
if i < len(v.Segments) {
a = v.Segments[i]
}
if i < len(other.Segments) {
b = other.Segments[i]
}
if a != b {
return a > b
}
}
return true
}
// String renders v back into a dotted-segment form with the prerelease
// suffix reattached (e.g. "1.52.3-dev"), for use in error and warning
// messages. It is reconstructed from Segments/Prerelease rather than
// returning Raw so that a Version built via MustParse (which has no Raw
// beyond what MustParse synthesizes) prints consistently.
func (v Version) String() string {
parts := make([]string, len(v.Segments))
for i, s := range v.Segments {
parts[i] = strconv.Itoa(s)
}
s := strings.Join(parts, ".")
if v.Prerelease != "" {
s += "-" + v.Prerelease
}
return s
}