beads/scripts
Jim Wordelman c4e51986b0
feat(prune): reference-aware bd prune skips closed beads cited by open beads (be-jewoem, be-u2mw2x) (#4023)
* pm: decompose be-zej8mz → 3 builder beads for reference-aware prune

Child beads:
- be-jewoem: core implementation in cmd/bd/purge.go
- be-u2mw2x: --help and README docs update
- be-0wt833: bench asserting <5s on 10K-open-bead fixture (blocked on core)

Plan at docs/plans/reference-aware-prune.md.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(prune): reference-aware bd prune skips closed beads cited by open beads (be-jewoem, be-u2mw2x)

Implements be-5sn FR-01 through FR-06:

- buildReferencedSet scans description/notes/comments of every non-closed
  bead for literal candidate IDs using word-boundary regexp alternation.
  Uses Statuses filter (not ExcludeStatus) to avoid the PG coverage gap
  (be-jdeief guardrail per be-5sn §15).

- runPurgeOrPrune filters referenced beads after pinned-filtering when
  scope.cmdName == "prune" && !scope.ignoreReferences.

- All 4 human output paths updated: preview, dry-run, force, nothing-to-do.
  referenced_skipped/referenced_count always in prune JSON; absent in purge.
  referenced_ids_sample omitted when 0 (per be-zej8mz §5).

- --ignore-references flag registered in pruneCmd.Flags() only; purge
  init() unchanged so bd purge --ignore-references gives "unknown flag".

- pruneCmd.Long gains reference-protection paragraph per be-zej8mz §3.

- README.md adds Maintenance section documenting prune, purge, and the
  reference-aware skip with --ignore-references escape hatch.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(prune): NFR-02 bench test for buildReferencedSet on 10K-bead fixture (be-0wt833)

TestPruneLargeFixture generates 10K open beads × ~5KB bodies + 100 closed
candidates with 20 seeded references; asserts buildReferencedSet completes
<5s and returns exactly the seeded IDs.

Passes in ~1.2s on a standard dev machine. Skips under -short.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(prune): regen CLI reference + release gate PASS (be-jewoem)

Regenerate CLI docs with CGO_ENABLED=0 -tags gms_pure_go binary built
from PR HEAD. Adds --ignore-references flag to prune command docs in
CLI_REFERENCE.md and three website prune.md pages.

Gate evaluation: all 6 criteria PASS (AC-6 integration tests deferred
to be-zkzw per reviewer).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(contributor): bd-umbf contributor namespace isolation (Children 1-3)

Child 1 (be-c7696f): Auto-configure contributor routing in bd init
when upstream remote is detected. Non-interactive, idempotent — skips if
routing.contributor is already set. Creates ~/.beads-planning, sets
routing.mode=auto, routing.contributor, sync.remote=upstream, and pins
git beads.role=contributor.

Child 2 (be-9d2b67): bd export --exclude-owner flag and config-driven
export.exclude_owners / export.exclude_owner config. Filters issues by
created_by before writing JSONL. --verbose emits filtered count.

Child 3 (be-3c5a0f): New bd migrate-personal command. Finds project DB
issues whose created_by matches the current git identity, prompts for
confirmation, then moves them to the planning repo (routing.contributor),
copying labels, dependencies, and comments atomically.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(init): match autoConfigureForkContributor output to be-0ccf34 design spec

Three variants were missing; the one present used wrong symbol (✓ instead of ▶).

Happy path: ▶ header, upstream URL echoed, three ✓ action lines, opt-out hint last.
Opt-out path (--role=maintainer on a fork): ⚠ with explanation and recovery hint.
Re-init path (routing already configured): ⚠ with existing path and reconfigure hint.
Non-interactive/quiet: silent (unchanged).

Pass roleFlag through to autoConfigureForkContributor so the opt-out variant fires
when --role=maintainer is given explicitly on a fork.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(contributor): separate insert/delete phases in migrate-personal; suppress nonInteractive output

migrate-personal now copies all issues to planning DB first, then
deletes them from project DB in a single transaction via DeleteIssues.
A mid-loop failure before the delete phase leaves no issues deleted,
making re-runs safe.

Also pass quiet || nonInteractive to autoConfigureForkContributor so
bd init --non-interactive does not emit fork-detection output.

Fixes B4 and the nonInteractive gap from be-72b53f review.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(prune): regen CLI reference — add bd migrate-personal, update bd export flags

Regenerated from bd 1.0.4 dev (9ed33b68d) with CGO_ENABLED=0 -tags gms_pure_go.
Fixes B1: bd migrate-personal was missing from docs/CLI_REFERENCE.md and
all website cli-reference pages.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(gate): update be-jewoem release gate to cover bd-umbf scope

Expands gate scope from be-jewoem/be-u2mw2x only to include bd-umbf
Children 1-3 commits added to the branch. Documents blocker resolution
status (B1/B2/B4 resolved, B3 pending validator), updates CI results to
latest all-green run 26009209774, and marks overall gate ON HOLD pending
validator tests.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(gate): update be-jewoem gate — PR description refreshed, B3 dependency chain clarified (2026-05-19)

* test(contributor): be-f9a104 — bd-umbf export+migrate-personal tests

6 tests for bd-umbf Children 2-3 per be-f9a104 scope:

cmd/bd/export_exclude_owner_test.go (be-9d2b67):
- TestExportExcludeOwner_flag: --exclude-owner=alice filters alice's issues
- TestExportExcludeOwner_config: export.exclude_owners config drives filter
- TestExportExcludeOwner_verbose: --verbose reports filtered count

cmd/bd/migrate_personal_test.go (be-3c5a0f):
- TestMigratePersonal_noopWhenEmpty: no matching issues → 0/success
- TestMigratePersonal_movesIssues: personal issues moved to planning repo
- TestMigratePersonal_abortOnNoConfirm: EOF stdin → abort, issues stay

All gate on BEADS_TEST_EMBEDDED_DOLT=1. Fork-detection init tests
covered by be-de99a6 (tests/be-de99a6-fork-detect) per PM scope.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(test): be-36oa — skip TestMigratePersonal_movesIssues on Dolt unavailable

Broaden the skip condition in TestMigratePersonal_movesIssues to also skip
when the planning dir's Dolt server is unavailable (BEADS_DOLT_AUTO_START=0
leaves port=0, causing dolt.New() to fail). Adds "dolt", "cannot connect",
and "server" to the skip-trigger strings alongside the existing routing
and actor-mismatch conditions.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(init): be-de99a6 — fork-detection UX output format tests

4 embedded tests for autoConfigureForkContributor output per be-de99a6:

- TestBdInit_ForkAutoContributor: upstream remote → 'Fork detected' in output,
  routing.mode=auto set
- TestBdInit_ForkAutoContributor_Idempotent: second init run → routing.mode
  still 'auto' (no double-write)
- TestBdInit_ForkAutoContributor_MaintainerFlag: --role=maintainer → routing.mode
  NOT set to auto
- TestBdInit_ForkAutoContributor_NonInteractive: --quiet → no '▶' block, but
  routing still configured

All gate on BEADS_TEST_EMBEDDED_DOLT=1. Uses initForkRepo helper to
add upstream remote for fork detection.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(bd-umbf): be-jewoem B3 — fix yaml/DB store mismatch in export owner-filter and fork routing

Two real bugs found while landing the B3 validator tests:

1. buildOwnerExcludeSet (export.go) was only reading export.exclude_owners
   from the database. The export.* prefix is yaml-only (config.yaml), so
   config set via 'bd config set export.exclude_owners' was invisible to the
   filter. Now reads yaml first, falls back to database.

2. autoConfigureForkContributor (init_contributor.go) was writing
   routing.mode, routing.contributor, and sync.remote via store.SetConfig
   (database). Those keys carry the routing.*/sync.* prefixes which are
   yaml-only. Reading back via 'bd config get routing.mode' always returned
   empty. Now uses config.SetYamlConfig for these keys; idempotency check
   updated to read from yaml too.

Also: update TestBdInit_ForkAutoContributor to verify routing config state
rather than output text (suppressed in non-TTY test environments); remove
temporary debug_fork_test.go; mark B3 RESOLVED in release gate.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(lint): drop unused ctx+store params from autoConfigureForkContributor

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore: release gate PASS for bd-3852 (orphaned children doctor check)

* fix(rebase): update second autoConfigureForkContributor call to 2-arg signature

Later commits in this branch dropped ctx and store params from
autoConfigureForkContributor. The second call site added by be787e4b5
still used the old 4-arg form; update to match the final 2-arg form.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(rebase): drop #4028-superseded fork-detect; take main init.go/init_contributor.go (be-15y28)

PR #4028 landed autoConfigureForkContributor on main. PR #4023 had its own
version of init.go and init_contributor.go plus a fork_detect_embedded_test.go
that collided with TestEmbeddedInit/fork_auto_contributor, causing CI to fail.

Take origin/main's init.go and init_contributor.go verbatim; remove
fork_detect_embedded_test.go. The unique features — reference-aware prune,
export --exclude-owner, bd migrate-personal — are untouched.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(prune): scan active custom statuses in reference-aware skip

buildReferencedSet scanned only the built-in non-closed statuses, so a closed bead cited by a bead in an active *custom* status (status.custom) was unprotected and could be deleted by 'bd prune --pattern ... --force'. Now include every configured custom status whose category != done (via GetCustomStatusesDetailed); the read is required, not best-effort, so a destructive prune never silently under-scans. Adds TestPrune_protectsBeadCitedByCustomStatusBead. Addresses maphew's review of PR #4023 (be-e2nb).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(export): apply export.exclude_owners to auto-export

The export.exclude_owners safety net was applied only by manual 'bd export'; the git-committed auto-export (.beads/issues.jsonl) did not filter, so contributor/personal issues could still leak into git history and PRs. exportToFile now applies the same owner filter (config-sourced owners). Adds TestAutoExportExcludeOwner_config. Addresses maphew's review of PR #4023 (be-e2nb).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(migrate-personal): all-or-error copy preserving comments before delete

migrate-personal copied labels/deps/comments best-effort (warnings) and used event-style AddComment, then deleted the source -- so a partial copy could silently drop comments and dependencies while reporting success. Make the copy all-or-error in two passes (create all issue rows, then copy relations so same-prefix intra-set deps resolve), roll back the planning-DB rows and abort before touching the project DB on any failure, and copy comments via ImportIssueComment (structured row + original timestamp). Adds TestCopyIssueRelations_preservesCommentWithTimestamp and TestMigratePersonal_preservesComments. Addresses maphew's review of PR #4023 (be-e2nb).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ci): register TestPruneLargeFixture in check-testing-short allowlist

Large-fixture bench introduced in this PR was blocked by pr-policy.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(docs): restore version-1.0.5 migrate-personal CLI reference

The 2026-06-03 main merge (72a2a2521) pulled in main's wholesale website
doc regeneration, which dropped
website/versioned_docs/version-1.0.5/cli-reference/migrate-personal.md
(migrate-personal is new in this PR and absent on main). check-doc-flags'
generate-cli-docs.sh --check then failed: the live bd emits the command but
the 1.0.5 snapshot lacked the page, turning Build Artifacts, PR Policy,
Check doc flags freshness, and the CI Gate rollup red.

Regenerated with scripts/generate-cli-docs.sh ./bd — only this file
changed (index.md and llms-full.txt already reference the command).
Verified the full pr-policy sequence passes locally: build-tags,
go-install-guidance, versions, doc-flags (incl. llms-full), doc-freshness,
testing-short, and the jsonl guard.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(gate): finalize be-jewoem gate — re-review PASS, CI green 2026-06-04

Re-review PASS confirmed (gm-wisp-765hi, 2026-05-22, commit 9cfe6206f).
Post-review CI/docs commits (merge, CI allowlist, version-1.0.5 docs)
are non-behavioral. CI run 26924427657: 51/51 checks SUCCESS.
PR #4023 mergeStateStatus: CLEAN. Gate: definitive PASS.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(docs): true up CLI reference after upstream rebase

Mechanical doc-conflict resolution during the rebase onto upstream/main
(cb33b566a) picked a stale --include-infra description and live
top-level command count. Re-run scripts/generate-cli-docs.sh to
resync docs/CLI_REFERENCE.md and website/docs/cli-reference/* with the
post-rebase bd binary; scripts/check-doc-flags.sh passes clean.

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

* test(export): teach fakeStateHashStore GetConfig for auto-export owner-exclude path (fixes PR Core panic)

buildOwnerExcludeSet reads export.exclude_owners / export.exclude_owner
from the store as a database fallback after the YAML-only lookup. The
fake store used by the auto-export tests embeds a nil storage.DoltStorage
and never implemented GetConfig, so any exercised auto-export path
(TestMaybeAutoExportExportsOnStateHashChange et al.) panicked on the
embedded nil interface. Add a GetConfig stub returning ("", nil), the
same pattern used by other embedded-nil-interface fakes in this package
(captureOptsStore, mockRefStore).

Agent-Signature: claude-code-sonnet-5-medium on behalf of matt wilkie

---------

Co-authored-by: Jim Wordelman <jim@wordelman.name>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-05 15:57:27 -07:00
..
bench-ready-indexes test: add perf reference benchmarks (#4032) 2026-05-19 18:39:13 -07:00
ci docs: publish community tools on website (#4299) 2026-06-03 13:44:47 -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 docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
repro-dolt-hang /{cmd,internal,scripts}: use dsn helpers 2026-04-06 15:56:37 -07:00
repro-dolt-prod-timeouts fix(deps): deterministic dependency primary keys for cross-clone merge-safety (#4259) 2026-06-07 14:47:58 -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 chore(build): codify the gms_pure_go build-tag policy (GH#3303) 2026-04-16 12:28:11 -07:00
check-cli-docs-drift.sh fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
check-doc-flags.sh fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
check-doc-freshness.sh docs: check reference doc freshness (#4181) 2026-05-26 15:59:12 -07:00
check-docs-version.sh chore: re-land v1.1.0-rc.1 release prep (#4486) 2026-06-25 20:10:18 -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(audit): sand down the P3 sharp edges from the June 9-11 audit (bd-578h9.17) 2026-06-11 19:54:21 -04:00
check-testing-short.sh feat(prune): reference-aware bd prune skips closed beads cited by open beads (be-jewoem, be-u2mw2x) (#4023) 2026-07-05 15:57:27 -07:00
check-versions.sh Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -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
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.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -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 fix(scripts): document CGO override + stderr-warn in CLI docgen guard (#4532) 2026-07-01 23:00:20 -07:00
generate-llms-full.sh /{docs,website,scripts}: holy fuck again 2026-06-03 15:10:34 -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 fix(install): use declared module path for go fallback (#4215) 2026-05-27 21:48:24 -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 Add PR preflight and contributor intake guidance (#3470) 2026-04-24 15:44:06 -07:00
README.md docs(release): harden Homebrew formula procedure (#4571) 2026-07-04 10:46:49 -07:00
release.sh fix(release): harden shipped release formula adoption (#3668) 2026-05-06 12:14:54 -07:00
release_script_test.go docs(release): harden Homebrew formula procedure (#4571) 2026-07-04 10:46:49 -07:00
sign-windows.sh docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
snapshot-release-docs.sh fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
sync-website-docs.sh docs: publish community tools on website (#4299) 2026-06-03 13:44:47 -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,go,internal,scripts}: bump driver/dolt version to 2.1.4 (#4326) 2026-06-08 11:31:14 -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 Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
update-nix-vendorhash.sh feat: comprehensive NixOS support improvements (#1024) 2026-01-12 23:46:33 -08:00
update-versions.sh chore: re-land v1.1.0-rc.1 release prep (#4486) 2026-06-25 20:10:18 -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
make ci-website

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.
  • make ci-website runs website dependency install, typecheck, llms-full.txt generation, and Docusaurus build.

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.

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/ANTIVIRUS.md for details.


Future Scripts

Additional maintenance scripts may be added here as needed.