beads/scripts
matt wilkie 4983ec9c32
fix(schema,ci): prepared DML — not just prepared ALTER TABLE — silently no-ops on the Dolt CLI path (#5232)
* docs(schema)+ci: prepared DML, not just prepared ALTER TABLE, no-ops on the CLI path

cli_migrations.go's header documented the Dolt CLI batch-path limitation as
being about "some prepared ALTER TABLE statements". That understates it. Per
dolthub/dolt#11345 (verified on dolt 2.2.0 and 2.2.2), `dolt sql -q`/`-f`
silently no-ops EXECUTE of any prepared DML -- an UPDATE/INSERT/DELETE built
into a SET @sql string -- while reporting success; a prepared SELECT or a
direct statement on the same path runs correctly. Prepared ALTER TABLE is one
instance of that, not the scope of it.

Broaden the comment to say so, and add Check E to check-migration-hygiene.sh
so a NEW main-plane migration cannot quietly depend on a prepared write.
Prepared ALTER TABLE keeps its accepted-idiom status and is not flagged: only
the leading keyword inside the quoted text decides. Detection buffers a
statement across lines, because the common form here is a multi-line
`SET @sql = IF(cond, '...', '...')` whose PREPARE arrives several lines later,
so a single grep cannot correlate the two.

Deliberately new-files-only. Seven shipped migrations (0035, 0037, 0041, 0047,
0053, 0055, 0058) already PREPARE writes to real tables, and that is not a
latent bug: a shipped migration is frozen, and the only path this check is
about is the fresh-schema bundle, where an empty database makes a data
backfill a no-op whether or not the prepared write lands.
cliCompatibleMigrationSQL overrides just the subset whose prepared statements
change the committed schema shape, which is what the bundle actually promises.
The guard is there to stop the idiom spreading into a migration where the
write does matter.

Verified: hygiene script passes clean on the tree; a scratch migration
carrying a prepared ALTER TABLE, a prepared UPDATE and a multi-line prepared
INSERT flags exactly the two writes and not the ALTER.

Agent-Signature: claude-opus-5-high on behalf of matt wilkie

* fix(ci): the prepared-DML check rejected the pattern it recommends

Cross-vendor review (codex reviewer, gpt-5.6-sol) found two false positives in
Check E, both confirmed against source:

1. It flagged prepared writes to migration-local stand-in tables — which is
   exactly the remedy its own failure message hands out. Migration 0059
   (gastownhall/beads#4877) copies into __bd_0059_* throwaway tables with
   PREPARE and then has a direct statement read them, precisely so a silent
   no-op degrades gracefully instead of corrupting state. A new migration
   following that documented pattern would have been rejected by the check
   telling it to follow that pattern.

   Fixed by recognising the tree's stand-in naming convention: a double
   underscore prefix, which no real beads table uses (__bd_0059_* and
   __temp__* are the existing instances). The multi-table DELETE form yields
   an alias rather than the table, so it stays flagged — conservative in the
   right direction.

2. It scanned .down.sql files. Only migrations/*.up.sql is embedded into the
   CLI fresh bundle (//go:embed at schema.go:218), so a down migration can
   never meet the bug this check is about; scanning it rejects valid work for
   no reason.

Verified with three scratch migrations: the __bd_-targeted INSERT is not
flagged, a real-table UPDATE still is, and a .down.sql carrying prepared DML
is not. Clean pass on the tree throughout.

Agent-Signature: claude-opus-5-high on behalf of matt wilkie

* fix(ci): exempt a prepared statement only when EVERY DML branch is a stand-in

Second cross-vendor review round found the stand-in exemption checked only the
first DML target it matched. A single

    SET @sql = IF(cond, 'INSERT INTO __stage ...', 'UPDATE issues SET ...');

carries two branches and only one executes, so matching the stand-in INSERT
first waved through the real-table UPDATE sitting beside it — the exact
false negative the check exists to prevent, reachable by combining the
recommended pattern with an ordinary one. Reproduced before fixing.

Now extracts every INSERT/UPDATE/DELETE target in the statement and exempts
only when all of them are __-prefixed. Extracting nothing recognisable no
longer exempts either: the multi-table delete form (DELETE wd FROM ...) yields
an alias or nothing, and both stay flagged.

Verified: mixed IF flags, both-branches-stand-in passes, the 0059 shape still
passes, a plain real-table prepared write still flags, clean tree still passes.

Agent-Signature: claude-opus-5-high on behalf of matt wilkie

* fix(ci): exempt only the one prepared form whose write target is unambiguous

Third review round, third defect in the same exemption, and the pattern in the
failures is the point: I was trying to identify SQL write targets with a
regex, and SQL will not be identified that way.

    UPDATE __stage s JOIN issues i ON i.id = s.id SET i.priority = 0

writes to issues. Every version of this check so far extracted __stage and
exempted it. And 'ON DUPLICATE KEY UPDATE v = 2' read as a second write verb,
so a perfectly safe stand-in upsert was rejected.

Narrowed instead of patched again. A prepared UPDATE or DELETE is now NEVER
exempted -- their multi-table forms can move the modified table behind a JOIN,
so the target is not reliably knowable here. INSERT INTO is exempted when every
target is a __ stand-in, because its target is always the token after INTO
whatever the SELECT source does. ON DUPLICATE KEY UPDATE is neutralised before
the verb scan.

The cost is that a future conditional real-table-free UPDATE gets flagged and
has to be restructured the way 0059 does, or justified. That is the right side
to err on for a check whose whole purpose is refusing to guess about writes.

Verified across seven shapes: joined UPDATE to a real table flags, joined
DELETE flags, mixed IF with one real branch flags, INSERT into a real table
from a stand-in flags, the 0059 shape passes, a stand-in upsert with ON
DUPLICATE KEY UPDATE passes, clean tree passes.

Agent-Signature: claude-opus-5-high on behalf of matt wilkie

* fix(ci): match the write verb as a token anywhere, not at a fixed position

Fourth review round, and both findings are the round-4 mistake again in the
detector rather than the exemption: I was requiring a SQL construct to sit at
an exact position.

- 'SET @sql := ...' never started buffering, because the assignment regex only
  accepted bare '='. Dolt accepts both.
- The DML test required the verb immediately after the opening quote, so
  '/* conditional */ UPDATE issues ...' and 'WITH t AS (...) UPDATE issues ...'
  both sailed through — valid SQL performing exactly the prepared write this
  guard exists to reject.

Rather than add two more position cases, the verb is now matched as a whole
token anywhere in the statement. That is strictly more conservative, and the
stand-in exemption is what rescues the legitimate forms — the check no longer
depends on guessing where in a statement something will appear.

The one thing that widening could have broken is a prepared ALTER TABLE
carrying 'ON UPDATE CURRENT_TIMESTAMP', which is a column attribute and not a
write. Both that and 'ON DUPLICATE KEY UPDATE' are masked before the scan, in
one shared helper used by the detector and the exemption alike.

Verified across eight shapes: ':=' assignment, leading block comment, and
leading CTE all flag; prepared ALTER with ON UPDATE, stand-in upsert with ON
DUPLICATE KEY UPDATE, and the 0059 shape all pass; joined UPDATE to a real
table flags; clean tree passes.

Agent-Signature: claude-opus-5-high on behalf of matt wilkie

* docs(ci): state Check E's known limits instead of implying it is a parser

Fifth review round found two more bypasses: a multi-variable
'SET @guard = 1, @sql = ...' (only the first variable is tracked) and a
PREPARE split across lines. Both are valid SQL, both real.

Not fixing them here, and saying so in the script rather than shipping a
silent gap. The reasoning:

- Neither form occurs anywhere in the current migration tree. Verified: the
  only PREPARE-without-FROM hits are comments.
- Check E is advisory hygiene on NEW files, which a human reviews anyway.
- The convergent fix is statement-level scanning rather than a line-oriented
  state machine -- it subsumes all three known bypasses at once, exactly as
  rounds 3-5 kept teaching about position-anchored matching. Attempting that
  rewrite at round 5, with no remaining review budget to validate it, would
  ship an unvalidated parser. That is worse than a documented heuristic.

So the header now carries a KNOWN LIMITS block naming all three shapes and
telling a reviewer not to trust a green check when they see one. Tracked as
mybd-q8hy2.

A check that overstates its coverage is more dangerous than one that admits
where it stops.

Agent-Signature: claude-opus-5-high on behalf of matt wilkie

* fix(ci): cover PREPARE-from-literal, and refuse to exempt an unclassified INSERT

Sixth review round, and unlike the previous round's findings these two are not
exotica I was willing to document and defer:

- 'PREPARE stmt FROM ''UPDATE issues ...''' — the literal form, no user
  variable in play — was not checked at all. That is the most direct spelling
  of the hazard this guard exists for, and arguably the first thing an author
  writes. Now checked in place rather than through the assignment bookkeeping.

- The stand-in exemption counted classified targets but not INSERT verbs.
  MySQL and Dolt accept 'INSERT issues ...' with INTO omitted, so
  IF(c, 'INSERT INTO __stage ...', 'INSERT issues ...') produced exactly one
  stand-in target, looked unanimous, and exempted the real-table write in the
  other branch. The exemption now requires every INSERT verb to have produced
  a target, so anything it cannot classify blocks the exemption rather than
  silently missing from the tally.

That second one matters more than its severity label suggests: it is the
exemption granting safety it should not, which is worse than the detector
missing a shape. An exemption must fail closed.

The two bypasses documented last commit stand as documented -- multi-variable
SET and a PREPARE split across lines, neither of which occurs in the tree
(mybd-q8hy2). The KNOWN LIMITS block now notes that the literal PREPARE form
is covered, so the list is not read as broader than it is.

Verified across eight shapes, including both new ones and every previously
passing case: literal-PREPARE UPDATE flags, literal-PREPARE stand-in INSERT
passes, INTO-omitted mixed branch flags, and the 0059 / ON DUPLICATE KEY /
prepared-ALTER-with-ON-UPDATE cases all still pass.

Agent-Signature: claude-opus-5-high on behalf of matt wilkie

* docs(ci): apply the KNOWN LIMITS note the previous commit claimed to make

9850b8efc's message says "The KNOWN LIMITS block now notes that the literal
PREPARE form is covered". It does not — the edit was scripted, its assertion
failed on a wording mismatch, and because that step was not chained to the
commit the commit went ahead anyway with a message describing a change that
was not in the diff.

Applying it for real: the block now states that
'PREPARE ... FROM ''<literal>''' IS covered, so the three listed bypasses are
not read as broader than they are, and the round count says six rather than
five.

Recording the cause rather than quietly fixing it, because the failure mode is
worth knowing: a scripted edit that fails its own precondition, in a command
whose later steps are not gated on it, produces a commit that lies. Chain the
commit to the edit.

Agent-Signature: claude-opus-5-high on behalf of matt wilkie

* fix(ci): REPLACE is a write, and a PREPARE literal may be double-quoted

Two more from review, both ordinary MySQL rather than exotica:

- REPLACE INTO was not in the write-verb set at all, so a prepared
  'REPLACE INTO issues ...' passed the check entirely. It is now detected, and
  like UPDATE and DELETE it can never be exempted -- this function classifies
  INSERT INTO targets only, so any other write verb must block the exemption
  rather than go untallied. A REPLACE targeting a stand-in is therefore
  flagged too; that is the fail-closed direction and an author can restructure
  it as an INSERT.
- The literal-PREPARE branch matched only single-quoted strings, so
  PREPARE stmt FROM "UPDATE issues ..." slipped past.

Verified across eight shapes: double-quoted literal flags, REPLACE into a real
table flags, REPLACE into a stand-in flags (unclassified, fail-closed), and
the 0059 / literal-stand-in-INSERT / ON DUPLICATE KEY / prepared-ALTER-with-
ON-UPDATE cases all still pass.

Agent-Signature: claude-opus-5-high on behalf of matt wilkie

* fix(ci): match the non-INSERT verb boundary the same way the detector does

The exemption's UPDATE/DELETE/REPLACE rejection required whitespace after the
verb, while prepared_has_dml used a token boundary. Dolt accepts a comment as
a token separator, so

    IF(c, 'INSERT INTO __stage ...', 'UPDATE/*x*/ issues SET priority = 3')

was seen as DML by the detector, then sailed through the exemption: the
whitespace-anchored test never noticed the UPDATE, the INSERT verb and target
counts agreed, and the real-table write passed. Reproduced, then fixed by
using the same boundary in both predicates.

Two predicates that must agree on what a verb is should not spell it two
different ways; that divergence is the whole bug.

Verified: comment-separated UPDATE now flags, double-quoted literal REPLACE
flags, and the 0059 / ON DUPLICATE KEY / prepared-ALTER-with-ON-UPDATE cases
plus the clean tree all still pass.

Agent-Signature: claude-opus-5-high on behalf of matt wilkie
2026-08-01 23:28:45 -07:00
..
bench-ready-indexes feat: choose your own storage backend (Postgres / MySQL / SQLite) — rebased on main 2026-07-10 17:44:37 +00:00
ci ci: retry Dolt image pulls (bd-m0o1z) (#5228) 2026-08-01 08:18:41 -07:00
hooks feat: Add post-push hook to auto-install bd CLI after git push 2025-10-14 17:23:43 -07:00
migration-test test(migration): assert bd ready/blocked/close on migrated DB (mybd-ihg5) (#4584) 2026-07-07 13:32:37 -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 /{cmd,internal,scripts}: use dsn helpers 2026-04-06 15:56:37 -07:00
repro-dolt-prod-timeouts test: inspect benchmark command environments without exec (bd-l7i27) (#5261) 2026-08-01 19:50:10 -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 docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -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 sync: name a resolve command on conflict, fix -q asymmetry, close doc-flags hole, cover runSyncCommand (wy-j6q2z) 2026-07-25 19:28:31 -07:00
check-doc-freshness.sh fix(scripts): remove Python from doc freshness checks (#4978) (#4979) 2026-07-25 22:53:47 -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,ci): prepared DML — not just prepared ALTER TABLE — silently no-ops on the Dolt CLI path (#5232) 2026-08-01 23:28:45 -07:00
check-testing-short.sh fix(update): resolve metadata/note merges inside the mutation transaction (concurrent lost-update) (#4732) 2026-07-19 05:59:31 -07:00
check-versions.sh fix(release): regenerate and gate the MCP uv.lock on version bumps (#5082) 2026-07-26 12:53:58 -07:00
check_doc_freshness_test.go fix(scripts): remove Python from doc freshness checks (#4978) (#4979) 2026-07-25 22:53:47 -07:00
ci_workflow_test.go ci: decouple artifacts from duplicate checks (bd-4b1dt) (#5264) 2026-08-01 22:49:45 -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
conformance.sh ci: give conformance explicit timeout budgets (#5073) 2026-07-28 09:01:39 -07:00
conformance_script_test.go ci: give conformance explicit timeout budgets (#5073) 2026-07-28 09:01:39 -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 chore: purge deleted docs-pipeline references from release tooling, CI, and repo plumbing 2026-07-12 11:07:26 -07:00
docs.md fix(scripts): remove Python from doc freshness checks (#4978) (#4979) 2026-07-25 22:53:47 -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 generator: automated narrative summaries of releases 2026-01-22 16:09:29 -08:00
generate-newsletter_README.md Newsletter generator: automated narrative summaries of releases 2026-01-22 16:09:29 -08:00
gh-body-lint docs: align agent maintainer conventions (#4237) 2026-06-20 20:44:08 -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
migrate-jsonl-to-dolt.sh feat: add JSONL-to-Dolt migration script (GH#2276) 2026-03-02 22:05:38 -08:00
migrate-sqlite-to-current.sh docs: add cross-era migration instructions to upgrading guide (#3081) 2026-04-06 20:11:00 -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 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
pull_dolt_image_test.go ci: retry Dolt image pulls (bd-m0o1z) (#5228) 2026-08-01 08:18:41 -07:00
README.md 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
release.sh fix(release): harden shipped release formula adoption (#3668) 2026-05-06 12:14:54 -07:00
release_script_test.go test: port Windows hardening fixes (#4600) 2026-07-07 12:59:50 -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): prebuild bd for subprocess tests; fit cmd/bd inside the package deadline (wy-4mtr0) (#5067) 2026-07-27 15:10:21 -07:00
update-nix-vendorhash.sh feat: comprehensive NixOS support improvements (#1024) 2026-01-12 23:46:33 -08:00
update-versions.sh fix(release): regenerate and gate the MCP uv.lock on version bumps (#5082) 2026-07-26 12:53:58 -07:00
update-winget.sh docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
upgrade-smoke-test.sh test(upgrade-smoke): exercise dependency blocker paths on migrated DB (#4238) 2026-05-28 15:30:21 -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.

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.