* test(dolt): red — testdb_* leak onto production Dolt port when Docker absent (refs be-h2h25) * feat: green — Test suites create testdb_* on the PRODUCTION dolt server: harness fails open on the ambient port when Docker is absent (refs be-h2h25) * docs(release-gate): add be-napos gate — ambient Dolt port fail-open to fail-closed Deploy bead be-napos (build be-h2h25, review be-7fym1, verdict pass round 2). 7/7 gate criteria PASS; full independent evidence in the gate doc. refs be-napos, be-h2h25, be-7fym1 * docs(release-gate): record PR link for be-napos gate refs be-napos * test(testutil): make the fail-closed gate deterministic, not Docker-conditional The regression test skipped itself on every host that has Docker, by calling the real EnsureDoltContainerForTestMain and skipping when it succeeded. That asserted nothing on CI -- the only lane where it matters -- and on a Docker-having host it also started the shared singleton container purely to decide to skip, with no TestMain in internal/testutil to terminate it. Add checkDoltFn, a package-level seam over checkDolt, so the test can force a not-ready state without a Docker daemon and without starting a container. Only EnsureDoltContainerForTestMain routes through it; the neighbouring t.Skip call sites gate a skip rather than the fail-closed behaviour, so they keep calling checkDolt directly. The gate now covers all four not-ready states rather than the one the old test happened to hit, which also pins the intent that an explicit BEADS_TEST_SKIP=dolt opt-out must fail closed exactly as a Docker-less host does. Split into a platform-independent half (the helper's own contract, both variables cleared, idempotent) and a !windows half (the wiring, via the seam). Red/green: with the neutralizeAmbientDoltPort call removed from the not-ready branch, 4 of 4 subtests fail and 0 pass; restored, 4 of 4 pass in 0.06s with no Docker and no container. (refs be-napos) * fix(testutil): clear the ambient Dolt port on the Windows stub too The Windows EnsureDoltContainerForTestMain returned its error without touching BEADS_DOLT_SERVER_PORT / BEADS_DOLT_PORT, so the fail-open this branch fixes still shipped there -- unconditionally, since that stub never succeeds. Windows is a real lane: .github/workflows/pr.yml runs windows-latest on four jobs plus the cross-platform matrix. Gating it needed one pre-existing repair. testdoltserver_env_test.go has no build tag but calls checkDolt, which is !windows-only, so the internal/testutil test binary has never compiled for Windows -- reproduced identically on origin/main. Tagging that file !windows fixes the whole package's Windows test lane; without it a new Windows gate would compile nowhere and assert nothing, which is the same defect this branch is already correcting. Verified GOOS=windows go vet ./internal/testutil/ clean (it fails on origin/main), and GOOS=windows go build clean before and after. The Windows gate itself is compile-verified only -- no Windows host here to execute it. (refs be-napos) * docs(testing): state that ambient BEADS_DOLT_*_PORT is never honored The guard fires on every not-ready state, not only "Docker unavailable" -- a missing or wrong-version image and an explicit BEADS_TEST_SKIP=dolt opt-out clear the ambient port too. That is deliberate: the invariant is the absence of a test container, not the reason for it. Say so where the next person will look before investigating, and name the supported way to target a specific server. (refs be-napos) * chore: remove leaked internal release-gate doc from PR branch release-gates/be-napos-ambient-dolt-port-failclosed-gate.md Tracked our internal gc-management/beads-rig release-gate checklist and should never have been committed to this upstream branch -- it's process residue from our deploy tooling, not part of the change itself. Per maintainer bee-ghosttrack's request during review of PR #6571. The root cause (our deploy tooling auto-committing this file) is already fixed as of gm-qatxl1; this branch predates that fix, so this commit is cleanup only -- no other content on this branch is touched. Ref: be-lk7o3 * chore(bazel): enumerate the PR's new test files in BUILD.bazel Base added BUILD.bazel to internal/testutil and internal/storage/dolt after this PR was opened (#6881 made the Bazel lane real, and fork PRs always run it). The four new test files this PR adds were therefore absent from the go_test srcs lists, which the bazel lane's equivalence check reports as a missing target. Generated by 'make bazel-sync' (gazelle), not hand-edited, because the CI drift step diffs against exactly what gazelle emits. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(testutil): reconcile the shared-server harness with the fail-closed clear Review iterations 1-2 (adopt-pr, PR #5885): every gating finding from both review syntheses, plus their minors and nits. Iteration 1, Major 1 (Change Impact / Blast Radius). scripts/test.sh's BEADS_TEST_SHARED_SERVER=1 flow starts a dockerless `dolt sql-server` and exports BEADS_DOLT_PORT for every package to reuse. checkDolt() has no notion of an already-provisioned shared server, so on that flow's primary audience -- a host without Docker -- all 12 EnsureDoltContainerForTestMain callers erased the harness's own sanctioned port before m.Run(), turning green dockerless runs red, while engdocs/CI_TEST_SURFACE_AUDIT.md and the new TESTING.md paragraph advertised the two mechanisms unreconciled. Taken: a dedicated marker, BEADS_TEST_SHARED_DOLT_SERVER, exported by scripts/test.sh beside the port it allocated, which the helper's failure paths honor. Both docs state the reconciliation, including the precedence: a container, where one can be started, still overwrites both variables. Not taken: "skip the clear when BEADS_TEST_SHARED_SERVER=1 and a port var is already set". That flag is overloaded (cmd/bd/shared_server_integration_test.go reads it too), and the script starts no server when a port is already set, so the flag beside a port is exactly the case where the port is ambient. Iteration 2, blocker (Behavioral Correctness). Iteration 1 shipped that marker as a boolean ("1") which spared BOTH port variables, while the script vouched only for the BEADS_DOLT_PORT it exported and its entry guard never looked at BEADS_DOLT_SERVER_PORT -- the variable applyConfigDefaults resolves first. The runner's test environment (beads_test_env_enter) unsets both variables before the flow runs, so the hole needed that isolation skipped, e.g. with the documented BEADS_TEST_ENV_DISABLE=1; then an inherited BEADS_DOLT_SERVER_PORT reached `go test` beside the marker and outranked the shared server -- gm-2g3g5r, re-opened by its own fix. Measured with a fake `go` that prints its environment: SERVER_PORT=59999 PORT=<shared> MARKER=1 under the iteration-1 script. Now: - the marker's value is the port it vouches for, and the helper decides per variable (neutralizeUnvouchedDoltPorts): only a variable holding exactly that port survives, and says so on stderr; every other one is cleared, marker or not; - the flow starts only when neither port variable is set, and says on stderr when BEADS_TEST_SHARED_SERVER=1 is ignored for that reason. Not taken: also exporting BEADS_DOLT_SERVER_PORT from the flow. The widened guard means it is always unset there, so the export adds no safety, and five sites read that variable alone (internal/doltserver/doltserver.go:796, cmd/bd/init.go:773 and :1351, cmd/bd/bootstrap.go:857, internal/testutil/testdoltbranch.go:164) -- consumers the flow has never fed. Iteration 2, minor (Test Evidence Quality). The exception's second arm, a container that would not start, was reached by no test with its guard live. Both failure paths now share one clear, and the container start is a seam (startSharedContainerFn, pinned to startSharedContainer by identity) so tests reach that path without consuming doltServerOnce. TestEnsureDoltContainerForTestMain_KeepsHarnessProvisionedPort runs its whole table, marked_but_divergent_var included, through both paths. Iteration 2, minor (Contract & Interface Fidelity). The marker prose in TESTING.md, CI_TEST_SURFACE_AUDIT.md, test.sh and testdoltserver.go describes the per-port behavior the code now implements. Iteration 1, Major 2 (Contract & Interface Fidelity). neutralizeAmbientDoltPort's doc comment claimed "With no port resolvable, applyConfigDefaults' BEADS_TEST_MODE guard forces port 1". Clearing the env vars is not "no port resolvable": resolution falls through to the file chain and derives a directory from filepath.Dir(cfg.Path) when BeadsDir is empty (store.go:1661-1664), so a reachable .beads/dolt-server.port still yields a non-zero port and the ServerPort == 0 arm (store.go:1683-1687) never fires; production-port detection is strictly narrower than resolution. Narrowed to what the change actually guarantees -- no environment-named port is honored -- at all three sites carrying the claim: the helper doc, the TESTING.md paragraph, and TestApplyConfigDefaults_NoResolvablePortFailsClosed's own comment, whose fixture (an empty beadsDir) is what excludes the surviving path. The residual stays tracked in be-rl6tm. That test's stale cross-reference to a renamed test is corrected in the same pass. Iteration 1, minor (Test Evidence Quality). The Windows gate's comment claimed a CI lane it does not have; it now states the coverage exactly -- compile-checked, not CI-executed -- and lists the four windows-latest jobs' named selectors. Iteration 1, nits. doltServerErr is read under doltServerMu via sharedContainerErr(); TestCheckDoltFn_DefaultsToRealProbe pins function identity with reflect instead of asserting non-nil, which any leaked stub satisfied. Mutation ledger (scoped `go test ./internal/testutil/`, scrubbed env; every mutant restored from a copy and verified byte-identical): a set marker spares every marked_but_divergent_var, divergent_legacy_var, variable (the i2 blocker) marker_names_neither_var and boolean_marker red on BOTH failure paths the marker covers marked_but_divergent_var, marker_names_neither_var BEADS_DOLT_PORT only and boolean_marker red on both paths presence instead of value the same red set as the first row no clear after a failed the 5 container_start_failed cases that expect container start a clear red; every not_ready case stays green start attempted before the all four incumbent fail-closed subtests and probe every not_ready case red leak a wrapper into StartSharedContainerFn_DefaultsToRealStart red startSharedContainerFn delete the hermetic ClearsAmbientPortWhenNotReady red t.Setenv, marker ambient at the fixture's port Full package green with Docker, including the real-container EnsureDoltContainerForTestMain path (43 test and subtest passes, no skips); `go test ./scripts/`, which drives test.sh, green; `GOOS=windows go vet ./internal/testutil/` clean; `tools/bazel/go_srcs.py --check` clean, and no BUILD change is due (no new files, no new non-stdlib imports). Deferred deliberately: the iteration-1 synthesis's optional windows-latest step for ./internal/testutil/. It is newly feasible -- this branch is what made the package's Windows test binary compile -- but it would also newly execute four pre-existing test functions in this package that have never run on Windows, so it belongs in its own change. RequireDoltContainer's unsynchronized doltServerErr read is base-owned and left alone for the same reason. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Julian Knutsen <julian@gastownhall.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local> |
||
|---|---|---|
| .. | ||
| bench-ready-indexes | ||
| checkworkflowtags | ||
| ci | ||
| gitattributespolicy | ||
| hooks | ||
| internal/testbash | ||
| migration-test | ||
| pr-lint | ||
| prlintmake | ||
| repro-be-1he-slow-path | ||
| repro-dolt-hang | ||
| repro-dolt-prod-timeouts | ||
| workflowtags | ||
| bazel-autofix-push.sh | ||
| bazel_autofix_push_test.go | ||
| bazel_farm_workflow_test.go | ||
| bazel_policy_test.go | ||
| build-examples.sh | ||
| BUILD.bazel | ||
| bump-version.sh | ||
| check-build-tags.sh | ||
| check-cli-docs-drift.sh | ||
| check-doc-flags.sh | ||
| check-doc-freshness.sh | ||
| check-go-install-guidance.sh | ||
| check-migration-hygiene.sh | ||
| check-testing-short.sh | ||
| check-versions.sh | ||
| check-winget-portable-alias.sh | ||
| check_build_tags_test.go | ||
| check_doc_freshness_test.go | ||
| check_testing_short_test.go | ||
| check_winget_portable_alias_test.go | ||
| ci_capability_selector_test.go | ||
| ci_workflow_apt_get_timeout_test.go | ||
| ci_workflow_test.go | ||
| clean-test-tmp.sh | ||
| complexity_script_test.go | ||
| conformance.sh | ||
| conformance_script_test.go | ||
| cross-version-smoke-test.sh | ||
| docs-autofix-push.sh | ||
| docs.md | ||
| gen-winres.sh | ||
| generate-cli-docs.sh | ||
| generate-newsletter.py | ||
| generate-newsletter_README.md | ||
| gh-body-lint | ||
| host_tools_test.go | ||
| install-hooks.sh | ||
| install.sh | ||
| install_dolt_test.go | ||
| migrate-jsonl-to-dolt.sh | ||
| migrate-legacy-to-current.sh | ||
| mutation-equivalence.sh | ||
| pr-preflight.sh | ||
| pr_preflight_test.go | ||
| pr_risk_bazel_coverage_test.go | ||
| pull_dolt_image_test.go | ||
| README.md | ||
| release.sh | ||
| release_script_test.go | ||
| required_suite_test.go | ||
| resolve-docs-bd.sh | ||
| sign-windows.sh | ||
| test-cgo.sh | ||
| test-git-remote.sh | ||
| test-icu-path.sh | ||
| test.sh | ||
| test_script_test.go | ||
| update-nix-vendorhash.sh | ||
| update-versions.sh | ||
| update-winget.sh | ||
| upgrade-smoke-test.sh | ||
| upgrade_smoke_loop_test.go | ||
| verify-cgo.sh | ||
Beads Scripts
Utility scripts for maintaining the beads project.
ci/
Repository-owned CI command wrappers. These scripts are the source of truth for the target CI tiers; Make targets are aliases for local discoverability.
make ci-pr-core
make ci-pr-policy
make ci-pr-lint
make ci-package-mcp
make ci-package-npm
Each wrapper auto-detects the repository root, sources .buildflags when it
invokes Go in the default build mode, and records per-command timing through
scripts/ci/lib/timing.sh.
ci-pr-lint keeps its supported Bash/Make entrypoint but delegates native and
Windows/non-CGO target selection to the checkout-owned scripts/pr-lint Go
driver. This is the same shell-free lint authority used by bd preflight in a
Beads source checkout.
Broad Go test wrappers also source scripts/ci/lib/test-env.sh, which creates a
temporary HOME/XDG/Dolt root, isolates Git global/system config, clears runtime
Beads/Dolt environment variables, and sets BEADS_TEST_SKIP=dolt before tests
run. This keeps local make test and make ci-pr-core results comparable to
the fast PR-core contract even on shared agent hosts. Set
BEADS_TEST_ENV_RUN_DOLT=1 only when intentionally running the Dolt-dependent
tests through these broad wrappers, or BEADS_TEST_ENV_DISABLE=1 when debugging
against your real local configuration.
The broad Go wrappers also cap package and test parallelism to 4 by default
(GO_TEST_PKG_PARALLEL and GO_TEST_PARALLEL). This avoids turning high-core
shared hosts into a different test topology than GitHub Actions.
make ci-pr-policy includes scripts/check-testing-short.sh, which enforces
that testing.Short() is only used for runtime, stress, or large-fixture skips.
Use build tags, environment checks, or named wrappers for integration/e2e/API
boundaries.
Package gate wrappers validate publishable/package-adjacent surfaces:
make ci-package-mcpbuilds or consumes abdbinary, puts it onPATHasbd, then runs locked MCP packageuv sync, Ruff, mypy, pytest, and build checks.make ci-package-npmbuilds or consumes the native binary expected bynpm-package/bin/bd, runs the npm package test suite, and checksnpm pack --dry-run.
Set BEADS_TEST_BD_BINARY=/path/to/bd for MCP and npm package gates to reuse a
prebuilt candidate binary instead of rebuilding it inside the wrapper.
pr-preflight.sh
Read-only PR safety check for agents and maintainers.
# Before implementing or opening a related PR
./scripts/pr-preflight.sh --search "topic keywords" --repo gastownhall/beads
# Before changing, closing, or merging an existing PR
./scripts/pr-preflight.sh 123 --repo gastownhall/beads
It reports contributor/fork status, draft/review/merge/check state, risky diff
signals such as .beads/ changes or missing tests, and the required
contributor-protection next steps. It does not replace code review or local
validation.
Base-branch health is supplemented by a warn-only PR-gate sample: the last 60
completed pull_request-event runs, grouped per workflow. A single workflow
whose decisive runs (>= 5, across >= 3 distinct head branches) are all
failure-class is reported as a broken PR gate — the case where a job that
exists only in the PR workflow is red for every PR while the base branch shows
green. This detector never blocks (deliberately: automation classifies
unrecognized [block] lines as genuine merge blockers and would park merge
lanes on a false positive); it is skipped entirely while the base branch is
red.
gh-body-lint
Lint Markdown files before posting them with gh ... --body-file.
./scripts/gh-body-lint body.md
./scripts/gh-body-lint --fix body.md
The lint catches literal \n sequences, which render poorly on GitHub, and
GH#123 references, which do not auto-link like #123 or owner/repo#123.
release.sh (⭐ The Easy Button)
One-command release from version bump to local installation.
Usage
# Full release (does everything)
./scripts/release.sh 0.9.3
# Preview what would happen
./scripts/release.sh 0.9.3 --dry-run
What It Does
This master script automates the entire release process:
- ✅ Stops running Dolt servers (avoids version conflicts)
- ✅ Runs tests and linting
- ✅ Bumps version in all files
- ✅ Commits and pushes version bump
- ✅ Creates and pushes git tag
- ✅ Verifies or opens the Homebrew core formula PR
- ✅ Upgrades local Homebrew installation
- ✅ Verifies everything works
After this script completes, your system is running the new version!
Examples
# Release version 0.9.3
./scripts/release.sh 0.9.3
# Preview a release (no changes made)
./scripts/release.sh 1.0.0 --dry-run
Prerequisites
- Clean git working directory
- All changes committed
- golangci-lint installed
- Homebrew installed (for local upgrade)
- Push access to gastownhall/beads
Output
The script provides colorful, step-by-step progress output:
- 🟨 Yellow: Current step
- 🟩 Green: Step completed
- 🟥 Red: Errors
- 🟦 Blue: Section headers
What Happens Next
After the script finishes:
- GitHub Actions builds binaries for all platforms (~5 minutes)
- PyPI package is published automatically
- Homebrew core formula is verified or tracked through its canonical PR
- Users can
brew upgrade beadsto get the new version after Homebrew merges - GitHub Release is created with binaries and changelog
bump-version.sh
Bumps the version number across all beads components in a single command.
Usage
# Show usage
./scripts/bump-version.sh
# Update versions (shows diff, no commit)
./scripts/bump-version.sh 0.9.3
# Update versions and auto-commit
./scripts/bump-version.sh 0.9.3 --commit
What It Does
Updates version in all these files:
cmd/bd/version.go- bd CLI version constantplugins/beads/.claude-plugin/plugin.json- Claude plugin versionplugins/beads/.codex-plugin/plugin.json- Codex plugin version.claude-plugin/marketplace.json- Claude marketplace plugin versionintegrations/beads-mcp/pyproject.toml- MCP server versionREADME.md- Alpha status versionPLUGIN.md- Version requirements
Features
- Validates semantic versioning format (MAJOR.MINOR.PATCH)
- Verifies all versions match after update
- Shows git diff of changes
- Auto-commits with standardized message (optional)
- Cross-platform compatible (macOS and Linux)
Examples
# Bump to 0.9.3 and review changes
./scripts/bump-version.sh 0.9.3
# Review the diff, then manually commit
# Bump to 1.0.0 and auto-commit
./scripts/bump-version.sh 1.0.0 --commit
git push origin main
Why This Script Exists
Previously, version bumps only updated cmd/bd/version.go, leaving other components out of sync. This script ensures all version numbers stay consistent across the project.
Safety
- Checks for uncommitted changes before proceeding
- Refuses to auto-commit if there are existing uncommitted changes
- Validates version format before making any changes
- Verifies all versions match after update
- Shows diff for review before commit
sign-windows.sh
Signs Windows executables with an Authenticode certificate using osslsigncode.
Usage
# Sign a Windows executable
./scripts/sign-windows.sh path/to/bd.exe
# Environment variables required for signing:
export WINDOWS_SIGNING_CERT_PFX_BASE64="<base64-encoded-pfx>"
export WINDOWS_SIGNING_CERT_PASSWORD="<certificate-password>"
What It Does
This script is called automatically by GoReleaser during the release process:
- Decodes the PFX certificate from base64
- Signs the Windows executable using osslsigncode
- Timestamps the signature using DigiCert's RFC3161 server
- Replaces the original binary with the signed version
- Verifies the signature was applied correctly
Prerequisites
osslsigncodeinstalled (apt install osslsigncodeorbrew install osslsigncode)- EV code signing certificate exported as PFX file
- GitHub secrets configured:
WINDOWS_SIGNING_CERT_PFX_BASE64- base64-encoded PFX fileWINDOWS_SIGNING_CERT_PASSWORD- certificate password
Graceful Degradation
If the signing secrets are not configured:
- The script prints a warning and exits successfully
- GoReleaser continues without signing
- The release proceeds with unsigned Windows binaries
This allows releases to work before a certificate is acquired.
Why This Script Exists
Windows code signing helps reduce antivirus false positives that affect Go binaries.
Kaspersky and other AV software commonly flag unsigned Go executables as potentially
malicious due to heuristic detection. See docs/reference/antivirus.md for details.
Future Scripts
Additional maintenance scripts may be added here as needed.