* fix(scripts): update-nix-vendorhash no longer reports a build failure as success scripts/update-nix-vendorhash.sh treated the absence of a "got:" hash line as proof the vendorHash was already correct, so a build failure unrelated to a hash mismatch (e.g. a Go toolchain too old for a dependency) was misreported as success and the workflow went green on a broken build (#7496). Fixed by capturing the intentional-failure build's real exit status instead of discarding it with `|| true`, and using that exit status (not a "hash mismatch" string grep) to tell a genuine no-op apart from an unrelated build break. The step-5 verification build had the same shape of bug: piping through `tee` without pipefail meant the if-condition tested tee's exit status, not the build's, so a failing verification build still printed "Build successful!". Scoped `set -o pipefail` to just that one line rather than the whole script, since the earlier hash-extraction step legitimately relies on `grep -o` returning non-zero on no match. Fixes gastownhall/beads#7498. Added an independent `nix build .#default` step to update-vendor-hash.yml so the workflow no longer trusts the script's exit status alone, even if a future bug in the script reintroduces a false-success path. Fixes gastownhall/beads#7499. Added TestPinnedDoltCLIAtLeastRecommendedMin, asserting the pinned Dolt CLI version (scripts/ci/install-dolt.sh) is at least doltversion.RecommendedMin, so the two policies can't silently drift apart — RecommendedMin's own doc comment already claims this alignment but nothing enforced it. Fixes gastownhall/beads#7500. Verified by reproducing both update-nix-vendorhash.sh failure modes with a stub `nix` binary (a non-hash build failure, and a step-5 verification build failure) and confirming the intended successful hash-update path still works end to end. go build/vet clean, golangci-lint 0 issues, go test ./scripts/... passes except a pre-existing unrelated failure (TestControlQueryScriptPreservesReadyProbeFailure, tracked separately as beads#7293 and untouched by this change). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VN2SgXAHW1eTB1izwWwmyr * chore: empty commit to retrigger CI -- retrying after a 3-hour quota recovery window * chore: empty commit to retrigger CI -- isolated single retry after real-bug fixes landed on sibling PRs * fix(scripts): add missing BUILD.bazel dep, sharpen vendorhash diagnostics scripts_test now imports internal/doltversion (for TestPinnedDoltCLIAtLeastRecommendedMin) but scripts/BUILD.bazel had no matching dep row, which would fail the target's compile under rules_go once Bazel actually runs against this branch (the Bazel / jobs failing so far died in bazel.fork-cert, unrelated to this). Also, per review: scope set -o pipefail to just the step-5 verify block (turn it back off after, rather than leaving it on for the rest of the script with a comment claiming it's scoped when it isn't), and keep the old "hash mismatch" string check as a sub-case in the ACTUAL_HASH-empty branch, so a hash mismatch whose got: line fails to parse (e.g. a future Nix output-format change) is diagnosed differently from a build that failed for an unrelated reason. Re-verified all four failure/success paths with a stub nix binary (non-hash failure, hash-mismatch-with-unparseable-got-line, step-5-verify failure, and the genuine happy path). go build/vet clean, golangci-lint 0 issues. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VN2SgXAHW1eTB1izwWwmyr * fix(scripts): update-nix-vendorhash preserves operator backups, restores on any handled failure The script backed up default.nix to a fixed name in the repo root, default.nix.backup, before editing it -- but that is also the conventional name an operator gives their own manual backup. Running the script unconditionally overwrote (then later deleted) any such file. A failed step-5 verification build also left the candidate hash in default.nix with no backup at all to restore from, since the backup had already been deleted right after step 4 applied the real hash. Moved the backup into a private per-run scratch directory (mktemp -d, cleaned on every exit via an EXIT trap) instead of a fixed repo-root name, so it can never collide with an operator's own default.nix.backup. Copy with cp -p so a restore brings back the exact original bytes AND mode, not just content. Kept the backup around through step 5 instead of deleting it right after step 4, and added a restore on the step-5 verification-failure path, which previously left the unverified candidate hash in place. Also: the "no hash mismatch, already correct" exit-0 path previously inferred correctness purely from the fake-hash probe build's unexpected success, without ever building the real, restored file. It now runs a second build against the restored file and only exits 0 if that succeeds too, surfacing a diagnostic log if it doesn't. Fixes gastownhall/beads#7529. Verified with a stub nix binary across five scenarios: a pre-existing operator default.nix.backup (distinct content + mode 600) survives untouched in every one; a non-hash build failure restores the original (content + mode 640); the already-correct path now runs two builds and only succeeds if both do; the core bug repro (hash extracted, step-5 verify fails) now restores the original instead of leaving the unverified candidate hash with no backup; the genuine happy path still updates the hash correctly. No leftover scratch directories in any case. go build unaffected (shell-only change). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VN2SgXAHW1eTB1izwWwmyr * fix(scripts): update-nix-vendorhash restores the original on an interrupted run A SIGINT/SIGTERM during the probe build (the long step) reaches this script and its nix child as one process group; the child dies, this script exits through the EXIT trap with the placeholder hash still in default.nix. The plain `rm -rf "$SCRATCH_DIR"` trap deleted the only backup at that point, leaving no way back except `git checkout default.nix` -- which also discards any uncommitted operator edits. Worse than every handled failure case this file already restores from. The placeholder is never a valid end state, so the EXIT trap now checks for it and restores first, before dropping the scratch directory. Every handled exit path has already restored or verified default.nix by the time it runs, so this is a no-op there -- it only fires on an interrupted run. Found by review on PR #7504 (beads#7529's own follow-up): reproduced and confirmed with a stub nix that signals its own parent process group, matching a real Ctrl-C mid-build. Confirmed the bug first (plain trap: placeholder left in place, backup gone, matching the report exactly), then confirmed the fix (original hash and mode restored, operator backup untouched, no leftover scratch dir). Also re-ran the full existing scenario matrix (non-hash failure, hash mismatch with step-5 verify failure, genuine happy path) to confirm no regression. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VN2SgXAHW1eTB1izwWwmyr * fix(scripts): restore default.nix if vendorhash verification is interrupted The EXIT trap restored default.nix only while it still held the placeholder hash. A SIGINT/SIGTERM during the step-5 verification build therefore left the unverified candidate hash in place and deleted the only backup with the scratch dir. Track VERIFIED instead: until a build has verified default.nix as it stands, any exit restores the original. On handled paths this is a no-op, since they have already restored or verified the file. Write the build logs under ${TMPDIR:-/tmp} with per-run names. The verification log had a fixed /tmp name shared by every run and every user. Add the regression tests the #7498/#7499/#7529 fixes lacked: - TestUpdateNixVendorHashReportsTheRealBuildResult runs the script with a stub nix over a non-hash build failure, an unparseable mismatch, a failed verification, a half-parsed got: hash, a real update, and a probe that accepts the placeholder (restored file builds, or not). Every failure exits 1 with default.nix restored byte for byte and mode for mode, the operator's own default.nix.backup untouched and the named logs kept. Against main's script it reproduces each false success. - TestUpdateNixVendorHashInterruptRestoresOriginal signals the script's process group during the probe build and during verification. - TestUpdateVendorHashWorkflowBuildsIndependently pins the workflow's unconditional `nix build .#default` between the script and the match-report and push steps. The scenario matrix, operator-backup and file-mode fixture, and workflow ordering check are adapted from BlueboxC's correction of this PR in their fork (62e7718e), as described on #7498 and #7529. Refs #7504, #7496, #7498, #7499, #7500, #7529 Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen Co-authored-by: BlueboxC <david@blueboxcomputers.es> Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com> Co-authored-by: BlueboxC <david@blueboxcomputers.es> |
||
|---|---|---|
| .. | ||
| bench-ready-indexes | ||
| check-versions | ||
| checkworkflowtags | ||
| ci | ||
| gitattributespolicy | ||
| hooks | ||
| internal/testbash | ||
| migration-test | ||
| pr-lint | ||
| prlintmake | ||
| repochecks | ||
| repro-be-1he-slow-path | ||
| repro-dolt-hang | ||
| repro-dolt-prod-timeouts | ||
| workflowtags | ||
| bazel-autofix-push.sh | ||
| bazel_autofix_push_test.go | ||
| bazel_cache_mode_test.go | ||
| bazel_dolt_int_test.go | ||
| bazel_dolt_race_test.go | ||
| bazel_farm_workflow_test.go | ||
| bazel_fork_mode_test.go | ||
| bazel_go_repository_tools_test.go | ||
| bazel_hermetic_cc_test.go | ||
| bazel_invocations_test.go | ||
| bazel_policy_test.go | ||
| bazel_rbe_prewarm_test.go | ||
| bazel_rrc_test.go | ||
| bazel_skip_allowlist_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-workapi-frontend-boundary.sh | ||
| check_build_tags_test.go | ||
| check_doc_freshness_test.go | ||
| check_release_cross_compile_test.go | ||
| check_testing_short_test.go | ||
| check_winget_portable_alias_test.go | ||
| ci_actions_policy_test.go | ||
| ci_analytics_extract_test.go | ||
| ci_analytics_workflow_test.go | ||
| ci_blacksmith_runner_test.go | ||
| ci_f7b_review_test.go | ||
| ci_f7c_advisory_test.go | ||
| ci_merge_queue_test.go | ||
| ci_workflow_apt_get_timeout_test.go | ||
| ci_workflow_core_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 | ||
| embedded_shard_count_test.go | ||
| gen-winres.sh | ||
| generate-cli-docs.sh | ||
| generate-newsletter.py | ||
| generate-newsletter_README.md | ||
| gh-body-lint | ||
| host_tool_exec_policy_test.go | ||
| host_tool_shell_policy_test.go | ||
| host_tools_test.go | ||
| install-hooks.sh | ||
| install.sh | ||
| install_dolt_test.go | ||
| makefile_bazel_primary_test.go | ||
| managed_local_lane_test.go | ||
| migrate-jsonl-to-dolt.sh | ||
| migrate-legacy-to-current.sh | ||
| migration_corpus_bazel_test.go | ||
| mutation-equivalence.sh | ||
| nogo_integration_scan_test.go | ||
| nogo_integration_step_script_test.go | ||
| nogo_lint_policy_test.go | ||
| pinned_shards_helpers_test.go | ||
| pinned_shards_sources_test.go | ||
| pinned_shards_test.go | ||
| pr-preflight.sh | ||
| pr_lanes_bazel_coverage_test.go | ||
| pr_preflight_test.go | ||
| pr_risk_bazel_coverage_test.go | ||
| pre-push-suite.sh | ||
| pre_push_suite_test.go | ||
| proxied_lane_coverage_test.go | ||
| pull_dolt_image_test.go | ||
| rbe_worker_env_test.go | ||
| README.md | ||
| release.sh | ||
| release_script_test.go | ||
| repo_helpers_test.go | ||
| required_suite_test.go | ||
| resolve-docs-bd.sh | ||
| scripts_targets_test.go | ||
| shard_manifest_test.go | ||
| sign-windows.sh | ||
| test-cgo.sh | ||
| test-git-remote.sh | ||
| test-icu-path.sh | ||
| test.sh | ||
| test_script_test.go | ||
| testing_short_tree_test.go | ||
| tracked_files_test.go | ||
| update-nix-vendorhash.sh | ||
| update-versions.sh | ||
| update-winget.sh | ||
| update_nix_vendorhash_test.go | ||
| update_nix_vendorhash_unix_test.go | ||
| upgrade-smoke-test.sh | ||
| upgrade_smoke_loop_test.go | ||
| verify-cgo.sh | ||
| worker_env_autosync_test.go | ||
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-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 to the
checkout-owned scripts/pr-lint Go driver, which runs nogo (//tools/nogo)
under Bazel natively and cross-configured for windows/amd64 and darwin/arm64
(see engdocs/LINTING.md). 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-go 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.
scripts/check-testing-short.sh (make check-testing-short; CI runs it in
//scripts:go_sources_test) 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
- 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.