* ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files //scripts:scripts_test declared //:repo_files (the whole checkout), so every PR re-ran it, and it took ~181s on rbe-west. Most of that (60-79s) was TestBazelGatedLanesNeverRetryFlakyTests line-regexping the --run_under wrapper's pinned dolt binary (tools/bazel/hermetic_bin/dolt, in every test's runfiles); it now skips binary files, as git grep -I does. tools/bazel/go_srcs.py's per-package repo_files block now partitions each package's files into repo_go_srcs, repo_go_test_srcs, repo_doc_files and repo_other_files, aggregated at the root; //:repo_files is their union (same 4679 files). The //scripts tests are split into go_test targets by what they read (traced per test with strace over a runfiles-shaped tree): scripts_test CI/Bazel policy: //:repo_other_files (+1 Go file) shell_scripts_test script fixtures: //scripts files, a few root files go_test_sources_test _test.go scans: //:repo_go_test_srcs + shard files go_sources_test check-testing-short.sh: every .go file tracked_files_test every tracked file: //:repo_files Shared helpers move to helpers-only files; TestScriptsTestTargetsPartition- TheTests fails on a test file in no target or in two. //test/docsync and the //scripts/repochecks slices declare partitions or single files instead of //:repo_files where they can. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * ci(bazel): skip only the non-checkout hermetic_bin dir in the flaky-retry walk Skipping every binary file also stopped scanning tracked binaries (images, .binpb fixtures). Skip just tools/bazel/hermetic_bin, the --run_under wrapper's runfiles directory, which is not in the checkout, so the walk's coverage of tracked files is unchanged. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
276 lines
8.8 KiB
Markdown
276 lines
8.8 KiB
Markdown
# 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.
|
|
|
|
```bash
|
|
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](../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-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.
|
|
|
|
```bash
|
|
# 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`.
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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.
|