fix(release): wire release workflow to scripts/build-binaries.sh (#986)

[Wirasm]

Summary

The release workflow built binaries by calling bun build --compile inline, bypassing scripts/build-binaries.sh — the only place that rewrites packages/paths/src/bundled-build.ts with BUNDLED_IS_BINARY=true. As a result, v0.2.13 and v0.3.0 binaries shipped with the dev defaults baked in, and archon version crashed with package.json not found (bad installation?).

Root Cause

PR #982 centralized the constants rewrite in scripts/build-binaries.sh but never updated release.yml to call it. CI kept using its own inline bun build --compile path, skipping the rewrite entirely.

Changes

File	Change
scripts/build-binaries.sh	Add single-target mode via TARGET/OUTFILE env vars; preserve multi-target local mode; always --minify; skip --bytecode on Windows; harden EXIT trap with || true
.github/workflows/release.yml	Replace inline bun build --compile with a call to scripts/build-binaries.sh; strip v prefix from tag, shorten SHA
.github/workflows/release.yml	New post-build smoke-test step (gated to bun-linux-x64) that asserts Build: binary + tag version, would have caught both broken releases
.claude/skills/test-release/SKILL.md	Document local CI-equivalent build invocation

Testing

• bash -n scripts/build-binaries.sh — syntax OK
• Single-target mode: VERSION=0.3.1-test GIT_COMMIT=test1234 TARGET=bun-darwin-arm64 OUTFILE=/tmp/test-single-target bash scripts/build-binaries.sh produced a 75 MB binary that reports Archon CLI v0.3.1-test, Build: binary, Git commit: test1234
• EXIT trap restored packages/paths/src/bundled-build.ts — git status clean afterwards
• Error path: invoking with only TARGET set fails fast with a clear message
• CI verification — trigger workflow_dispatch with a -rc tag after merge

Issue

Fixes #986

Summary by CodeRabbit

• Bug Fixes

  • Prevented released binaries from embedding development constants that caused crashes.

• Tests

  • Added post-build smoke tests to validate released binaries report correct version and build metadata.

• Documentation

  • Expanded release and QA guides with local pre-release build instructions, atomic update rules for package formulas, and end-to-end verification steps.

• Chores

  • Updated release workflow to use a unified build invocation ensuring consistent CI and local builds.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: df1b6a89-3eaa-4909-9ac8-f122ca52e2a7

📥 Commits

Reviewing files that changed from the base of the PR and between 30a85d5 and 73bead5.

📒 Files selected for processing (3)

• .claude/skills/test-release/SKILL.md
• .github/workflows/release.yml
• scripts/build-binaries.sh

---

📝 Walkthrough

Walkthrough

Refactors binary build to centralize compilation in scripts/build-binaries.sh, updates the GitHub release workflow to call the script with CI env vars, adds a Linux/x64 smoke test of the built binary, and expands release/testing documentation for CI-style local builds and post-release formula updates.

Changes

Cohort / File(s)	Summary
Issue Investigation & Plan \.claude/PRPs/issues/completed/issue-986.md	New investigation doc describing root cause (inline bun build in workflow), impact, implementation plan, validation steps, risks, and scope.
Build Script scripts/build-binaries.sh	Add CI single-target mode via TARGET/OUTFILE, preserve multi-target local mode, always --minify, conditional --bytecode, change outfile handling, suppress restore failures in EXIT trap, simplify completion output.
Release Workflow .github/workflows/release.yml	Remove inline bun build; compute/normalize VERSION and short GIT_COMMIT; invoke scripts/build-binaries.sh with TARGET/OUTFILE; add Linux/x64 post-build smoke tests validating archon version output and embedded constants before publishing.
Release & Test Docs \.claude/skills/release/SKILL.md, \.claude/skills/test-release/SKILL.md	Expand release steps (Steps 10–12) for waiting on workflow, downloading checksums, atomic version+sha256 updates and tap sync; add local CI-style build instructions and explicit /test-release verification guidance.

Sequence Diagram

sequenceDiagram
    actor Dev as Developer/Tag
    participant GHA as GitHub Actions (release.yml)
    participant Script as scripts/build-binaries.sh
    participant Bun as Bun Compiler
    participant Smoke as Smoke Test
    participant Art as Release Artifacts

    Dev->>GHA: trigger release (tag / workflow_dispatch)
    GHA->>Script: call with VERSION, GIT_COMMIT, TARGET, OUTFILE
    Script->>Bun: bun build --compile --minify (cond --bytecode)
    Bun->>Script: built binary (with embedded constants)
    Script->>Art: write binary to OUTFILE
    GHA->>Smoke: run "#{OUTFILE} version" on Linux/x64
    Smoke->>Art: inspect output for Build: binary and correct version
    alt smoke passes
        GHA->>Art: publish artifacts
    else smoke fails
        GHA->>Dev: fail workflow / block release
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• fix(build): use build-time constants for binary detection and pretty stream logger (replaces #962/#963) #979 — Modifies the same scripts/build-binaries.sh and bundled build-time constants; likely addressed by this PR's refactor and workflow change.

Poem

🐰
A hop, a script, a trimmed-up SHA,
Binaries now built the CI-way.
Smoke tests check the version song,
No dev defaults to steer us wrong.
Release carrots gleam — hop on along! 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly references the root cause (wiring release workflow to the build script) and the issue number, clearly summarizing the main change.
Description check	✅ Passed	The description provides a clear summary with root cause, changes table, testing checklist, and issue reference. It covers the core sections despite not following the full template structure.
Linked Issues check	✅ Passed	The PR implements all core objectives from issue #986: refactored scripts/build-binaries.sh for single-target CI mode, updated release.yml to invoke the script with proper version/commit handling, added post-build smoke-test, and documented local CI-equivalent steps.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #986: build script refactoring, workflow updates, smoke-test addition, and documentation. The Homebrew automation mentioned in objectives is separate from core issue requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/issue-986-release-build-script

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Wirasm]

PR Review Summary

Ran code-reviewer and silent-failure-hunter on the diff. Core fix (wiring release.yml to scripts/build-binaries.sh) is correct and solves the root cause, but there are a few issues worth addressing before merge.

Critical Issues

#	Issue	Location
1	workflow_dispatch embeds branch name as version — the Build step sets VERSION: ${{ github.ref_name }}, which on dispatch is the branch name (e.g. main), not inputs.version. The release job already handles this correctly on lines 123–128; the build job must too.	.github/workflows/release.yml:53
2	Smoke-test v-prefix mismatch — github.ref_name is v0.3.1 but the binary embeds the stripped 0.3.1. Depending on how archon version formats output, this grep can produce false negatives on good builds or false positives on broken ones. Strip v from ref_name before grepping.	.github/workflows/release.yml:87
3	EXIT trap silently swallows restore failures — 2>/dev/null || true hides both stderr and exit code. If git checkout fails (shallow clone, corrupt index, deleted file) the working tree is left dirty with BUNDLED_IS_BINARY=true and nothing in the log explains why. Drop 2>/dev/null so the failure reason is visible; || true alone is fine if the intent is "don't fail the step on restore errors."	scripts/build-binaries.sh:28

Important Issues

#	Issue	Location
4	test-release skill doc: single-target example uses OUTFILE=dist/test-archon-darwin-arm64 but then verifies via ./dist/binaries/archon-darwin-arm64 version — wrong path, the binary is at the OUTFILE.	.claude/skills/test-release/SKILL.md (Local build section)

Suggestions

• Add an explicit || { echo "::error::Binary failed to execute: $VERSION_OUTPUT"; exit 1; } after VERSION_OUTPUT=$(./dist/...) so a crash/segfault isn't masked by the later "wrong build type" error (release.yml:69).
• IFS=':' read -r target outfile splits on colons — safe today (no Windows absolute paths flow through), but worth a note if callers ever pass C:\... style paths (scripts/build-binaries.sh:69).

Strengths

• Fail-fast guard for partially-set TARGET/OUTFILE env vars is correct (no silent fallback).
• Negative grep for the known "Failed to read version" / "package.json not found" failure modes is a good explicit regression guard and would have caught both broken releases.
• ! grep -q "Build: binary" correctly catches Build: source regressions.
• Error messages in the script now route to stderr — improvement over the original.

Verdict

NEEDS FIXES — Issues 1 and 3 are real correctness/observability regressions; Issue 2 is a latent foot-gun in the very smoke test that was added to catch these bugs. Worth fixing before merging to keep the fix self-consistent.