* 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 |
||
|---|---|---|
| .. | ||
| bench-ready-indexes | ||
| ci | ||
| hooks | ||
| migration-test | ||
| repro-be-1he-slow-path | ||
| repro-dolt-hang | ||
| repro-dolt-prod-timeouts | ||
| 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_doc_freshness_test.go | ||
| ci_workflow_test.go | ||
| clean-test-tmp.sh | ||
| 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 | ||
| install-hooks.sh | ||
| install.sh | ||
| migrate-jsonl-to-dolt.sh | ||
| migrate-sqlite-to-current.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 | ||
| update-nix-vendorhash.sh | ||
| update-versions.sh | ||
| update-winget.sh | ||
| upgrade-smoke-test.sh | ||
| 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.