beads/scripts
Jim Wordelman a4bf13f042
Fix: test suites fail closed instead of open on the ambient Dolt port when no test container is started (be-napos) (#5885)
* 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>
2026-10-01 05:21:49 -07:00
..
bench-ready-indexes build(bazel): side-by-side Bazel scaffold + policy tests (#6798) 2026-09-27 03:41:02 -07:00
checkworkflowtags fix(ci): require direct workflow build tags (#5679) 2026-10-01 01:24:03 -07:00
ci fix(ci): require direct workflow build tags (#5679) 2026-10-01 01:24:03 -07:00
gitattributespolicy test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828) 2026-09-27 08:24:08 -07:00
hooks feat: Add post-push hook to auto-install bd CLI after git push 2025-10-14 17:23:43 -07:00
internal/testbash test(scripts): resolve Git Bash explicitly on Windows (#5727) (#5730) 2026-09-30 15:50:28 -07:00
migration-test fix(update): fence unforced --notes overwrites behind --force across all surfaces (#5946) 2026-10-01 05:02:40 -07:00
pr-lint fix(preflight): share checkout lint authority (#5780) 2026-09-30 22:41:55 -07:00
prlintmake fix(preflight): share checkout lint authority (#5780) 2026-09-30 22:41:55 -07:00
repro-be-1he-slow-path perf(dolt): eliminate 12s slow path on bd commands when .local_version is stale (#3710) 2026-07-24 00:53:06 -07:00
repro-dolt-hang build(bazel): side-by-side Bazel scaffold + policy tests (#6798) 2026-09-27 03:41:02 -07:00
repro-dolt-prod-timeouts test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828) 2026-09-27 08:24:08 -07:00
workflowtags fix(ci): require direct workflow build tags (#5679) 2026-10-01 01:24:03 -07:00
bazel-autofix-push.sh ci: auto-push Bazel BUILD sync fixes to PRs; harden docs autofix (#6907) 2026-09-28 17:23:27 -07:00
bazel_autofix_push_test.go ci: auto-push Bazel BUILD sync fixes to PRs; harden docs autofix (#6907) 2026-09-28 17:23:27 -07:00
bazel_farm_workflow_test.go ci(bazel): require the integration lane on same-repo PRs (#7069) 2026-09-30 23:56:33 -07:00
bazel_policy_test.go ci(bazel): server-Dolt storage and proxied tiers on remote execution (#6940) 2026-09-28 23:01:40 -07:00
build-examples.sh fix(examples): tidy both example modules and build them in CI (#5229) 2026-08-12 21:16:27 -07:00
BUILD.bazel ci: retire PR Risk's legacy embedded tier where the gated Bazel lane runs it (D2 step 1) (#7071) 2026-10-01 02:03:46 -07:00
bump-version.sh refactor: replace bump-version.sh with molecule pointer 2026-01-14 21:53:06 -08:00
check-build-tags.sh fix(ci): require direct workflow build tags (#5679) 2026-10-01 01:24:03 -07:00
check-cli-docs-drift.sh docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
check-doc-flags.sh fix(scripts): make check-doc-flags portable to BSD grep and fail loud on grep errors (#6026) 2026-09-02 17:25:53 -07:00
check-doc-freshness.sh fix(preflight): share checkout lint authority (#5780) 2026-09-30 22:41:55 -07:00
check-go-install-guidance.sh fix(install): use declared module path for go fallback (#4215) 2026-05-27 21:48:24 -07:00
check-migration-hygiene.sh fix(schema): CLI bundle never got migration 0065's wisp_comments widening (ga-61ruw) (#5910) 2026-08-20 23:38:48 -07:00
check-testing-short.sh Fix: check-testing-short.sh flags comments and misnames the offending function (round 2) (#5809) 2026-08-19 21:01:15 -07:00
check-versions.sh release: prep v1.3.0 — version bump, changelog rollup, release process docs, formula fixes (#6038) 2026-08-30 22:19:35 -07:00
check-winget-portable-alias.sh fix(winget): require PortableCommandAlias for GasTownHall.Beads (#5134) 2026-09-30 20:24:59 -07:00
check_build_tags_test.go fix(ci): require direct workflow build tags (#5679) 2026-10-01 01:24:03 -07:00
check_doc_freshness_test.go test(ci): make doc-freshness selection fail closed (#5729) 2026-10-01 01:05:12 -07:00
check_testing_short_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
check_winget_portable_alias_test.go fix(winget): require PortableCommandAlias for GasTownHall.Beads (#5134) 2026-09-30 20:24:59 -07:00
ci_capability_selector_test.go ci: retire PR Risk's legacy embedded tier where the gated Bazel lane runs it (D2 step 1) (#7071) 2026-10-01 02:03:46 -07:00
ci_workflow_apt_get_timeout_test.go fix: bound and retry apt-get calls in CI to avoid unbounded 15-minute job timeout (#5810) 2026-08-19 11:47:22 -07:00
ci_workflow_test.go ci: retire PR Risk's legacy embedded tier where the gated Bazel lane runs it (D2 step 1) (#7071) 2026-10-01 02:03:46 -07:00
clean-test-tmp.sh test(cmd/bd): route sync.Once test temp dirs through TestMain cleanup (#4108) 2026-05-22 16:48:22 -07:00
complexity_script_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
conformance.sh ci: give conformance explicit timeout budgets (#5073) 2026-07-28 09:01:39 -07:00
conformance_script_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
cross-version-smoke-test.sh docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
docs-autofix-push.sh ci: auto-push Bazel BUILD sync fixes to PRs; harden docs autofix (#6907) 2026-09-28 17:23:27 -07:00
docs.md Validate doc freshness max age (#5524) (#5606) 2026-08-10 21:02:23 -07:00
gen-winres.sh chore: re-land v1.1.0-rc.1 release prep (#4486) 2026-06-25 20:10:18 -07:00
generate-cli-docs.sh docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
generate-newsletter.py Newsletter dropped every commit made before the hour it ran (#6491) 2026-09-26 18:56:29 -07:00
generate-newsletter_README.md Newsletter dropped every commit made before the hour it ran (#6491) 2026-09-26 18:56:29 -07:00
gh-body-lint docs: align agent maintainer conventions (#4237) 2026-06-20 20:44:08 -07:00
host_tools_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
install-hooks.sh feat: Add post-push hook to auto-install bd CLI after git push 2025-10-14 17:23:43 -07:00
install.sh docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
install_dolt_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
migrate-jsonl-to-dolt.sh feat: add JSONL-to-Dolt migration script (GH#2276) 2026-03-02 22:05:38 -08:00
migrate-legacy-to-current.sh Guard and qualify historical upgrades to v1.2 (#4907) 2026-08-06 18:45:04 -07:00
mutation-equivalence.sh Fix a SIGPIPE in the mutation harness's worktree guard (#5434) 2026-08-08 08:28:08 -07:00
pr-preflight.sh fix(pr-preflight): warn when a PR-gate workflow is red for every PR while the base shows green (#5251) 2026-08-01 22:46:44 -07:00
pr_preflight_test.go test(scripts): resolve Git Bash explicitly on Windows (#5727) (#5730) 2026-09-30 15:50:28 -07:00
pr_risk_bazel_coverage_test.go ci: retire PR Risk's legacy embedded tier where the gated Bazel lane runs it (D2 step 1) (#7071) 2026-10-01 02:03:46 -07:00
pull_dolt_image_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
README.md fix(preflight): share checkout lint authority (#5780) 2026-09-30 22:41:55 -07:00
release.sh fix(release): harden shipped release formula adoption (#3668) 2026-05-06 12:14:54 -07:00
release_script_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
required_suite_test.go test(ci): make doc-freshness selection fail closed (#5729) 2026-10-01 01:05:12 -07:00
resolve-docs-bd.sh docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
sign-windows.sh docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
test-cgo.sh Rename ICU-only test path to explicit opt-in workflow (bd-b18) (#3291) 2026-04-16 08:54:24 -07:00
test-git-remote.sh /{.github,docs,engdocs,go,internal,scripts}: bump dolt 2026-07-15 13:14:34 -07:00
test-icu-path.sh Rename ICU-only test path to explicit opt-in workflow (bd-b18) (#3291) 2026-04-16 08:54:24 -07:00
test.sh Fix: test suites fail closed instead of open on the ambient Dolt port when no test container is started (be-napos) (#5885) 2026-10-01 05:21:49 -07:00
test_script_test.go test(scripts): report helper-only probe as skipped (#5599) 2026-08-10 20:58:58 -07:00
update-nix-vendorhash.sh fix(scripts): update-nix-vendorhash writes a stray default.nix'' on BSD sed (#6096) 2026-09-02 17:33:58 -07:00
update-versions.sh fix(release): version bumps now own the tracked .githooks markers 2026-08-11 14:06:28 -07:00
update-winget.sh fix(winget): require PortableCommandAlias for GasTownHall.Beads (#5134) 2026-09-30 20:24:59 -07:00
upgrade-smoke-test.sh fix(smoke): clear the version list before child dispatch (#6398) 2026-09-28 08:25:22 -07:00
upgrade_smoke_loop_test.go fix(smoke): clear the version list before child dispatch (#6398) 2026-09-28 08:25:22 -07:00
verify-cgo.sh fix: remove ICU runtime dependency from release binaries (#3066) 2026-04-07 09:48:44 -07:00

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-mcp builds or consumes a bd binary, puts it on PATH as bd, then runs locked MCP package uv sync, Ruff, mypy, pytest, and build checks.
  • make ci-package-npm builds or consumes the native binary expected by npm-package/bin/bd, runs the npm package test suite, and checks npm 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:

  1. ✅ Stops running Dolt servers (avoids version conflicts)
  2. ✅ Runs tests and linting
  3. ✅ Bumps version in all files
  4. ✅ Commits and pushes version bump
  5. ✅ Creates and pushes git tag
  6. ✅ Verifies or opens the Homebrew core formula PR
  7. ✅ Upgrades local Homebrew installation
  8. ✅ 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 beads to 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 constant
  • plugins/beads/.claude-plugin/plugin.json - Claude plugin version
  • plugins/beads/.codex-plugin/plugin.json - Codex plugin version
  • .claude-plugin/marketplace.json - Claude marketplace plugin version
  • integrations/beads-mcp/pyproject.toml - MCP server version
  • README.md - Alpha status version
  • PLUGIN.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:

  1. Decodes the PFX certificate from base64
  2. Signs the Windows executable using osslsigncode
  3. Timestamps the signature using DigiCert's RFC3161 server
  4. Replaces the original binary with the signed version
  5. Verifies the signature was applied correctly

Prerequisites

  • osslsigncode installed (apt install osslsigncode or brew install osslsigncode)
  • EV code signing certificate exported as PFX file
  • GitHub secrets configured:
    • WINDOWS_SIGNING_CERT_PFX_BASE64 - base64-encoded PFX file
    • WINDOWS_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.