* fix(winget): require PortableCommandAlias for GasTownHall.Beads GasTownHall.Beads 1.1.0 on winget-pkgs only sets Commands: (search metadata) and never creates WinGet\Links\bd.exe, so already-running shells never see bd after install (GH#4908). - Add canonical GasTownHall.Beads.installer.yaml with PortableCommandAlias - update-winget.sh regenerates that package id for new releases - Document both package ids and the Links requirement in winget/README - Add check-winget-portable-alias.sh guard Fixes #4908 * fix(winget): address maphew's PR #5134 review (grep bug, guard, CI wiring) Maintainer commits requested by the PR author on the reviewer's behalf, addressing maphew's 2026-07-29 review of PR #5134: - scripts/update-winget.sh: `grep windows` matched both amd64 and arm64 checksum lines, corrupting InstallerSha256 into an unparseable two-line value. Narrow to `grep windows_amd64` (mirrors the existing arm64 grep on the next block). - scripts/update-winget.sh: quote the arm64 InstallerSha256 placeholder so 64 bare zero digits don't parse as a YAML integer, matching the quoting already used in the checked-in SteveYegge.beads.installer.yaml. - scripts/check-winget-portable-alias.sh: replace the bare `grep -q PortableCommandAlias:` substring check with a yq-based parse, so a corrupted manifest (like the one above) fails the guard instead of reporting OK; also fail closed on an empty winget/ glob instead of silently exiting 0. - .github/workflows/pr.yml, main.yml: run the guard in the existing check-build-tags job so it executes on every PR instead of only when someone remembers to invoke it by hand. Locally verified: guard passes against the current checked-in manifests, fails against a reproduction of the exact grep-bug corruption, fails on an empty winget/ dir, and the generator produces a yq-parseable manifest against a synthetic checksums.txt. shellcheck clean; both workflow files parse as valid YAML. * fix(winget): harden the PortableCommandAlias guard and its release docs Maintainer review fixups for the adopt-pr review of PR #5134 (iteration 1, synthesis approve / 0 blockers and 0 majors; all seven items were non-gating). Scorecard 961/1000, Required Changes: None. Every edit site below is a line this PR itself added. Finding 1 (minor, Error Handling) — `yq -e ... >/dev/null 2>&1` collapsed three distinct failures (yq absent at exit 127, unparseable manifest, alias genuinely missing) into "missing valid PortableCommandAlias", defeating the script's own stated rationale and pointing a debugger at manifests that are already correct. The guard now names a missing yq up front and no longer discards stderr, so yq's own diagnostic reaches the log of a required-gate job. yq is CI's first and only yq consumer, running in a bare actions/checkout job, and sits outside the host-tools inventory declared in scripts/BUILD.bazel; that is now stated where the dependency lives. Finding 4 (minor, Change Impact) — the glob is winget/*.installer.yaml but the assertion was unconditional on installer type, so a future msi/exe/msix manifest (no NestedInstallerFiles at all) would hard-fail a gate-feeding job with no opt-out. Non-portable manifests are now classified out with a SKIP line. The parse check deliberately precedes the class check: without that ordering an unparseable manifest fails the NestedInstallerType test and is silently skipped as "not portable", which is strictly worse than the behaviour being fixed. Finding 2 (minor, Error Handling) — amd64 and arm64 had opposite failure policies in one script: a missing amd64 checksum hard-fails, while a missing arm64 checksum substituted 64 zeros and continued to success, disclosed only in a source comment. The echoed "Next steps" block now ends in a loud "DO NOT PUBLISH" warning naming the placeholder, emitted only when the fallback actually fires. The finding's second arm — "teach the guard to reject an all-zero InstallerSha256" — is implemented as a WARNING rather than a failure, and that is a deliberate downgrade. winget/SteveYegge.beads.installer.yaml:15 already carries exactly that placeholder for its arm64 entry; that file is base-owned and is not in this PR's six-file diff, so a fatal tripwire would turn a required check red over pre-existing content the PR never touched. The legacy heredoc in update-winget.sh emits no arm64 entry at all, so the placeholder is stale hand-authored state that the next generator run removes. Verified: the guard still exits 0 on the real tree and reports the warning. Finding 3 (minor, Contract & Interface Fidelity) — a winget-pkgs version directory needs a version + defaultLocale + installer set, but the repo carries only GasTownHall.Beads.installer.yaml, so README step 2 as written produced a set winget-pkgs validation rejects. Took the documentation arm: GasTownHall is now steered to `wingetcreate update` (which supplies the other two manifests from the published set) and the hand-copy path is marked as applying only to the legacy id, which does have a complete three-file set. Generating two more manifests would have changed the contribution's deliverable scope. Finding 5 (nit, Architectural Consistency) — the first update-winget.sh run overwrote the checked-in manifest with a three-line header, deleting this PR's own GH#4908 rationale from the artifact whose purpose is to carry it. The heredoc now emits the same header, plus a fresh ReleaseDate. Verified by generating into a temp tree: the generated header is byte-identical to the checked-in file's first ten lines. Finding 6 (nit, Documentation Accuracy) — the README froze SteveYegge.beads at the "0.30.x era" while the script rewrites all three of its manifests to the new version. Note that the section already disclosed that both ids are refreshed, so the residual gap was narrower than the finding stated: what was missing is that the legacy id's version is bumped out of the era the table advertises. That clause is now explicit. Finding 7 (nit, Test Evidence Quality) — the guard's fail-closed behaviour was pinned by nothing in-repo. Adds scripts/check_winget_portable_alias_test.go with ten cases: alias present, alias missing, wrong alias, empty winget dir, unparseable manifest (asserting it is neither skipped nor misreported and that yq's stderr survives), missing yq, a skipped non-portable manifest, a violating portable sibling of a skipped manifest, and the advisory placeholder warning. Deviates from the prescribed `requireHostTool(t, "yq")` on purpose. requireHostTool fails rather than skips under Bazel because //scripts:scripts_test is tagged host-tools, and that tag's declared inventory is "git, python3, awk, sed, find, grep and timeout" — yq is not in it, so the prescription would red the shared target on hosts that keep the promise the tag actually makes. A skip-only gate is used and the reason is recorded at the helper. Fixtures are synthetic so the target needs no new data dependency; the real manifests are covered by the check-build-tags job, which runs this script against the actual checkout. Also fixed, found while editing and not raised by either lane: winget/README.md told readers to run `grep windows` over checksums.txt, which is the exact two-line ambiguity this PR fixed in the script (`grep windows` -> `grep windows_amd64`). Before this PR the script and doc agreed; after it they diverged, so the PR created the inconsistency. The doc now uses `grep windows_` and says which line feeds which architecture. Validation. `git diff --check` clean. The guard runs green on the real tree (both manifests OK, rc=0) and on a freshly generated tree. go test ./scripts/ ok 21.7s (the package whose tests pin workflow content). Each new pin was proven non-vacuous by reverting the corresponding fix and confirming the test reds: dropping the class check reds the non-portable case; dropping the placeholder tripwire reds the warning case; dropping the parse-before-classify check reds the unparseable case; dropping the yq preflight reds the missing-yq case; restoring `2>&1` reds the stderr assertion. All five arms red, and the guard was restored byte-identical (md5 verified) after each. The arm64 warning was exercised both ways against a stubbed curl: present arm64 checksum emits no warning, absent one emits DO NOT PUBLISH. New yq expressions stay inside the vocabulary shared by mikefarah yq v4 (what ubuntu-latest ships) and python-yq/jq — identity, `==`, `[]`, `select` and `-e`'s exit status — because only the pre-existing expression had been proven green on mikefarah in CI, and this host has python-yq. Builtins the two flavours spell differently (jq's `any(cond)` vs mikefarah's `any_c`) are avoided, and the placeholder tripwire uses grep precisely because it looks for a known-bad literal and so can only miss a bad value, never report OK on a manifest it failed to parse. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Bee <bee@ghosttrack.com> Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local> Co-authored-by: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com> |
||
|---|---|---|
| .. | ||
| bench-ready-indexes | ||
| ci | ||
| gitattributespolicy | ||
| hooks | ||
| internal/testbash | ||
| migration-test | ||
| prlintmake | ||
| repro-be-1he-slow-path | ||
| repro-dolt-hang | ||
| repro-dolt-prod-timeouts | ||
| 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 | ||
| pull_dolt_image_test.go | ||
| README.md | ||
| release.sh | ||
| release_script_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.
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.