beads/scripts
Aaron Lippold 49aed46c85
fix: harden SQLite→Dolt migration safety, old-schema compat, and doctor recovery (#2156)
* fix(configfile): respect backend field in metadata.json

GetBackend() was hardcoded to always return "dolt", ignoring the
backend field in metadata.json. This forced all SQLite users onto
Dolt with no migration path and no way to opt out.

- Add BackendSQLite constant and case-insensitive normalization
- GetBackend() reads backend field: sqlite → sqlite, empty/dolt → dolt
- DatabasePath() routes to SQLite or Dolt path based on backend
- BEADS_BACKEND env var override as escape hatch for corrupted configs
- CapabilitiesForBackend handles sqlite backend
- Warning on unrecognized BEADS_BACKEND values
- 55 tests covering all paths including env var, case normalization,
  roundtrip persistence, and DatabasePath routing

Fixes #2016.

Authored by: Aaron Lippold<lippold@gmail.com>

* feat(migrate): add shared migration safety functions

Extract reusable safety functions for SQLite→Dolt migration:
- backupSQLite: file copy with O_EXCL + 0600 permissions
- verifyServerTarget: TCP + SQL check to prevent wrong-server writes
- verifyMigrationCounts: source vs target count verification
- finalizeMigration: atomic metadata update (last step only)
- rollbackMetadata: restore original config on failure

22 unit tests covering all functions including counter overflow,
non-MySQL server detection, deps-only mismatch, nil config rollback,
server config preservation, and no-metadata scenarios.

Authored by: Aaron Lippold<lippold@gmail.com>

* refactor(migrate): use safety functions in auto-migration

Refactor both CGO and non-CGO auto-migration paths to use shared
safety functions instead of inline logic:

Phase 1 (pre-flight):
- Always backup SQLite before any migration attempt
- Verify server target to prevent writing to wrong Dolt server
- Skip migration when backend explicitly set to sqlite (GH#2016)
- Use GetBackend() for SQLite guard, strings.EqualFold for Dolt
  stale-leftover detection (preserves legacy empty-backend migration)

Phase 2 (import):
- Unchanged: extract from SQLite, create Dolt store, import data

Phase 3 (verify + finalize):
- Verify issue counts match before updating metadata
- Atomic finalization via finalizeMigration (metadata last)
- Rollback with warning on failure (not silent discard)

Clear, actionable error messages at every failure point showing
backup path. 13 unit tests including new SQLite backend guard test.

Authored by: Aaron Lippold<lippold@gmail.com>

* fix(main): clear error when SQLite backend detected

When GetBackend() returns "sqlite" (user opted to stay on SQLite or
migration was skipped), print a clear error with migration instructions
instead of falling through to dolt.New() which produces a confusing
Dolt connection failure.

Fixes #2016.

Authored by: Aaron Lippold<lippold@gmail.com>

* feat(doctor): detect and fix broken migration states

Add three new doctor checks for migration-related issues:

CheckBrokenMigrationState: detects metadata claiming Dolt backend
but no Dolt directory present (with server-mode awareness). Offers
bd doctor --fix to restore SQLite backend from beads.db or
beads.db.migrated files.

CheckSQLiteResidue: detects leftover beads.db after successful
migration. Fix renames to .migrated (with backend guard to prevent
accidentally renaming active SQLite database).

CheckEmbeddedModeConcurrency: detects embedded mode with lock
contention indicators (dolt-access.lock, noms LOCK files).
Recommends switching to server mode for multi-agent workflows.
Addresses #2086.

19 doctor tests covering all detection paths including server mode,
backup file detection, .migrated-only recovery, zero-byte files,
concurrent access with access locks and noms locks.

Fixes #2086.

Authored by: Aaron Lippold<lippold@gmail.com>

* test(migrate): add integration tests for migration safety

8 integration tests covering key business flows:
- Full migration lifecycle (SQLite → backup → Dolt → bd list works)
- Failed migration recovery (corrupt SQLite → backup exists → intact)
- Doctor detects broken state and fix restores SQLite backend
- Doctor fixes beads.db.migrated rename-back recovery
- Idempotent retry (second migration is no-op)
- SQLite guard prevents auto-migration (data intact, no backup)
- Backup content matches source byte-for-byte
- Metadata JSON valid with all required fields after migration

Authored by: Aaron Lippold<lippold@gmail.com>

* feat(scripts): add migrate-audit.sh for batch SQLite→Dolt migration

Utility script to audit and batch-migrate beads boards:
- Scans all .beads/ directories under a configurable root
- Reports backend state, issue count, and schema version for each board
- --dry-run: shows what --migrate would do without changes
- --migrate: batch converts eligible SQLite boards to Dolt
- --exclude PATTERN: skip projects matching regex (e.g., "backup|test")
- --port/--host: target a specific Dolt server

Safety features:
- Backs up metadata.json before modifying each board
- Restores original metadata.json on migration failure
- Skips boards with old schema (missing owner column)
- bd binary handles SQLite backup, server verification, count verification
- Uses jq for JSON (consistent with existing scripts, no python dependency)

Companion tool for the migration safety PR (GH#2016, GH#2086).

Authored by: Aaron Lippold<lippold@gmail.com>

* fix(migrate): handle all schema versions in SQLite extract

Databases from older beads versions are missing columns added over time
(owner, created_by, crystallizes, mol_type, work_type, quality_score,
source_system, and others). The extract functions hardcoded COALESCE
for all columns, causing "no such column" errors.

Fix: make ALL non-id columns use sqliteOptionalTextExpr via a DRY
opt() helper in both CGO extract and shim extract paths. Missing
columns default to empty/zero/null. Also adds empty/corrupt beads.db
handling to the migrate-audit.sh script.

Tested against 12 real-world databases spanning multiple beads versions,
from the earliest (~30 columns) to the current schema (50+ columns).
All 28 boards migrated successfully.

Authored by: Aaron Lippold<lippold@gmail.com>
2026-02-26 15:48:47 -08:00
..
hooks feat: Add post-push hook to auto-install bd CLI after git push 2025-10-14 17:23:43 -07:00
repro-dolt-hang fix: resolve gofmt and golangci-lint CI failures 2026-02-25 13:31:06 -08:00
bump-version.sh refactor: replace bump-version.sh with molecule pointer 2026-01-14 21:53:06 -08:00
check-versions.sh docs: update paths for claude-plugin subdirectory structure (GH#985) (#1007) 2026-01-10 22:49:29 -08:00
docs.md docs: Add comprehensive documentation for version reporting changes 2025-12-13 10:04:01 +11:00
gen-winres.sh feat: embed Windows PE version info to reduce antivirus false positives (bd-t4u1) 2026-02-06 17:51:11 -08:00
generate-llms-full.sh feat: add llms.txt standard support for AI agent discoverability (#784) 2025-12-30 18:27:50 -08: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
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: remove stale embedded Dolt references after server-only migration 2026-02-21 16:59:44 -08:00
migrate-audit.sh fix: harden SQLite→Dolt migration safety, old-schema compat, and doctor recovery (#2156) 2026-02-26 15:48:47 -08:00
README.md docs: remove stale daemon references from all documentation (GH#1982) 2026-02-22 17:57:53 -08:00
release.sh chore: Bump version to 0.55.2 2026-02-20 09:00:55 -08:00
sign-windows.sh feat: add Windows code signing infrastructure (bd-14v0) 2025-12-24 00:07:16 -08:00
test-cgo.sh docs+tooling: standardize CGO test workflow and ICU setup 2026-02-10 10:56:12 -05:00
test-git-remote.sh feat: add E2E test script for dolt git remote workflow (bd-v7ydv.2) 2026-02-12 10:20:08 -08:00
test.sh feat(testutil): reuse existing Dolt server via BEADS_DOLT_PORT (L1) 2026-02-24 16:16:56 -08:00
test_issue_gh1224.sh chore: move WSL2 test scripts to scripts directory 2026-01-21 16:54:24 -08:00
test_wsl2_wal.sh chore: move WSL2 test scripts to scripts directory 2026-01-21 16:54:24 -08:00
update-nix-vendorhash.sh feat: comprehensive NixOS support improvements (#1024) 2026-01-12 23:46:33 -08:00
update-versions.sh feat: embed Windows PE version info to reduce antivirus false positives (bd-t4u1) 2026-02-06 17:51:11 -08:00
update-winget.sh feat(packaging): add Windows winget manifest (fixes #524) 2025-12-20 03:38:31 -08:00
verify-cgo.sh fix(release): prevent non-CGO bd binaries from shipping (#1870) 2026-02-21 14:21:22 -08:00

Beads Scripts

Utility scripts for maintaining the beads project.

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. ✅ Updates Homebrew formula
  7. ✅ Upgrades local brew 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 steveyegge/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
  • Users can brew upgrade beads to get the new version
  • 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
  • claude-plugin/.claude-plugin/plugin.json - Plugin version
  • .claude-plugin/marketplace.json - 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.