feat(HAI-109): add binary release infrastructure and dual-channel release workflow

- Add binary build verification step to CI workflow
- Add binary release job to release.yml for platform-specific builds
- Restore test-release workflow for pre-release validation
- Update CI workflow tests to cover binary release infrastructure
- Update RELEASING.md with dual-channel (npm + binary) release process

.github/workflows/ci.yml

@@ -30,5 +30,14 @@ jobs:
       - name: Build
         run: pnpm build
 
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v2
+
       - name: Test
         run: pnpm test
+
+      - name: Build standalone binary
+        run: pnpm --filter hai build:exe
+
+      - name: Verify binary exists
+        run: test -f packages/cli/dist/hai

.github/workflows/release.yml

@@ -0,0 +1,142 @@
+# Binary Release workflow
+#
+# This workflow builds platform-specific binaries and creates a GitHub Release
+# when a version tag (v*) is pushed. This is the second release channel —
+# npm publishing is handled separately by version.yml via changesets.
+#
+# Release channels:
+#   1. npm publish  — handled by version.yml (changesets/action)
+#   2. GitHub Release with binaries — handled by this workflow (release.yml)
+
+name: Binary Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  # ── Build platform-specific binaries ──────────────────────────────────
+  build-binaries:
+    name: Build ${{ matrix.target }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: bun-linux-x64
+            binary: hai-linux-x64
+          - os: macos-latest
+            target: bun-darwin-arm64
+            binary: hai-darwin-arm64
+          - os: macos-13
+            target: bun-darwin-x64
+            binary: hai-darwin-x64
+          - os: windows-latest
+            target: bun-windows-x64
+            binary: hai-windows-x64.exe
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build
+        run: pnpm build
+
+      - name: Build binary
+        run: pnpm --filter hai build:exe -- --target ${{ matrix.target }}
+
+      - name: Verify binary exists
+        shell: bash
+        run: test -f packages/cli/dist/${{ matrix.binary }}
+
+      - name: Sign macOS binary
+        if: runner.os == 'macOS'
+        env:
+          APPLE_CERTIFICATE_BASE64: ${{ secrets.APPLE_CERTIFICATE_BASE64 }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          APPLE_IDENTITY: ${{ secrets.APPLE_IDENTITY }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          APPLE_APP_PASSWORD: ${{ secrets.APPLE_APP_PASSWORD }}
+        run: bash scripts/sign-macos.sh packages/cli/dist/${{ matrix.binary }}
+
+      - name: Sign Windows binary
+        if: runner.os == 'Windows'
+        env:
+          WINDOWS_CERTIFICATE_BASE64: ${{ secrets.WINDOWS_CERTIFICATE_BASE64 }}
+          WINDOWS_CERTIFICATE_PASSWORD: ${{ secrets.WINDOWS_CERTIFICATE_PASSWORD }}
+        run: pwsh scripts/sign-windows.ps1 packages/cli/dist/${{ matrix.binary }}
+
+      - name: Generate checksum (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          cd packages/cli/dist
+          sha256sum ${{ matrix.binary }} > ${{ matrix.binary }}.sha256
+
+      - name: Generate checksum (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          cd packages/cli/dist
+          shasum -a 256 ${{ matrix.binary }} > ${{ matrix.binary }}.sha256
+
+      - name: Generate checksum (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          cd packages/cli/dist
+          $hash = (Get-FileHash ${{ matrix.binary }} -Algorithm SHA256).Hash.ToLower()
+          "$hash  ${{ matrix.binary }}" | Out-File -Encoding ascii ${{ matrix.binary }}.sha256
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.binary }}
+          path: |
+            packages/cli/dist/${{ matrix.binary }}
+            packages/cli/dist/${{ matrix.binary }}.sha256
+
+  # ── Create GitHub Release ─────────────────────────────────────────────
+  github-release:
+    name: Create GitHub Release
+    needs: build-binaries
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+
+      - name: Collect release files
+        run: |
+          mkdir release-files
+          find artifacts -type f \( -name "hai-*" -o -name "*.sha256" \) -exec cp {} release-files/ \;
+          ls -la release-files/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: release-files/*

.github/workflows/test-release.yml

@@ -0,0 +1,142 @@
+# Test Release workflow
+#
+# Manual workflow for testing binary builds without creating a real release.
+# Triggered via workflow_dispatch from the GitHub Actions UI.
+
+name: Test Release
+
+on:
+  workflow_dispatch:
+
+jobs:
+  # ── Build and test platform-specific binaries ─────────────────────────
+  build-binaries:
+    name: Build & Test ${{ matrix.target }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: bun-linux-x64
+            binary: hai-linux-x64
+          - os: macos-latest
+            target: bun-darwin-arm64
+            binary: hai-darwin-arm64
+          - os: macos-13
+            target: bun-darwin-x64
+            binary: hai-darwin-x64
+          - os: windows-latest
+            target: bun-windows-x64
+            binary: hai-windows-x64.exe
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build
+        run: pnpm build
+
+      - name: Build binary
+        run: pnpm --filter hai build:exe -- --target ${{ matrix.target }}
+
+      - name: Verify binary exists
+        shell: bash
+        run: test -f packages/cli/dist/${{ matrix.binary }}
+
+      - name: Smoke test (Linux/macOS)
+        if: runner.os != 'Windows'
+        run: |
+          chmod +x packages/cli/dist/${{ matrix.binary }}
+          packages/cli/dist/${{ matrix.binary }} --help
+
+      - name: Smoke test (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          & packages/cli/dist/${{ matrix.binary }} --help
+
+      - name: Sign macOS binary
+        if: runner.os == 'macOS' && env.APPLE_CERTIFICATE_BASE64 != ''
+        env:
+          APPLE_CERTIFICATE_BASE64: ${{ secrets.APPLE_CERTIFICATE_BASE64 }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          APPLE_IDENTITY: ${{ secrets.APPLE_IDENTITY }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          APPLE_APP_PASSWORD: ${{ secrets.APPLE_APP_PASSWORD }}
+        run: bash scripts/sign-macos.sh packages/cli/dist/${{ matrix.binary }}
+
+      - name: Sign Windows binary
+        if: runner.os == 'Windows' && env.WINDOWS_CERTIFICATE_BASE64 != ''
+        env:
+          WINDOWS_CERTIFICATE_BASE64: ${{ secrets.WINDOWS_CERTIFICATE_BASE64 }}
+          WINDOWS_CERTIFICATE_PASSWORD: ${{ secrets.WINDOWS_CERTIFICATE_PASSWORD }}
+        run: pwsh scripts/sign-windows.ps1 packages/cli/dist/${{ matrix.binary }}
+
+      - name: Generate checksum (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          cd packages/cli/dist
+          sha256sum ${{ matrix.binary }} > ${{ matrix.binary }}.sha256
+
+      - name: Generate checksum (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          cd packages/cli/dist
+          shasum -a 256 ${{ matrix.binary }} > ${{ matrix.binary }}.sha256
+
+      - name: Generate checksum (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          cd packages/cli/dist
+          $hash = (Get-FileHash ${{ matrix.binary }} -Algorithm SHA256).Hash.ToLower()
+          "$hash  ${{ matrix.binary }}" | Out-File -Encoding ascii ${{ matrix.binary }}.sha256
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.binary }}
+          path: |
+            packages/cli/dist/${{ matrix.binary }}
+            packages/cli/dist/${{ matrix.binary }}.sha256
+
+  # ── Collect all artifacts ─────────────────────────────────────────────
+  collect:
+    name: Collect Artifacts
+    needs: build-binaries
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+
+      - name: Combine artifacts
+        run: |
+          mkdir combined
+          find artifacts -type f \( -name "hai-*" -o -name "*.sha256" \) -exec cp {} combined/ \;
+          ls -la combined/
+
+      - name: Upload combined archive
+        uses: actions/upload-artifact@v4
+        with:
+          name: all-binaries
+          path: combined/*

RELEASING.md

@@ -1,6 +1,9 @@
 # Releasing
 
-This project uses [changesets](https://github.com/changesets/changesets) for automated versioning and release management.
+This project uses [changesets](https://github.com/changesets/changesets) for automated versioning and release management. Releases are distributed through two channels:
+
+1. **npm packages** — published automatically via `version.yml` using changesets
+2. **GitHub Release with platform binaries** — built and uploaded via `release.yml` when a version tag is pushed
 
 ## How it works
 
@@ -21,7 +24,7 @@ A markdown file will be created in the `.changeset/` directory. Commit this file
 
 ### 2. Version PR is created automatically
 
-When changesets are merged to `main`, a GitHub Actions workflow automatically opens (or updates) a **"Version Packages"** pull request. This PR:
+When changesets are merged to `main`, the `version.yml` workflow automatically opens (or updates) a **"Version Packages"** pull request. This PR:
 
 - Consumes all pending changeset files
 - Bumps package versions according to the changeset declarations
@@ -31,10 +34,38 @@ When changesets are merged to `main`, a GitHub Actions workflow automatically op
 
 When you merge the Version Packages PR:
 
-- The workflow detects that all changesets have been consumed
+- The `version.yml` workflow detects that all changesets have been consumed
+- It builds all packages and publishes them to **npm** with provenance attestation
 - It creates a git tag `v{version}` based on the `hai` CLI package version
-- The tag push triggers the existing release workflow (`.github/workflows/release.yml`)
+- The tag push triggers `release.yml`, which:
-- The release workflow builds binaries and creates a GitHub Release
+  - Builds platform-specific binaries for Linux x64, macOS x64, macOS arm64, and Windows x64
+  - Signs macOS binaries (codesign + notarization) and Windows binaries (Authenticode)
+  - Generates SHA256 checksums for all binaries
+  - Creates a **GitHub Release** with all binaries and checksums attached
+
+## Release channels
+
+| Channel | Workflow | Trigger | Output |
+|---------|----------|---------|--------|
+| npm | `version.yml` | Push to `main` | npm packages with provenance |
+| GitHub Release | `release.yml` | Version tag (`v*`) | Signed platform binaries + checksums |
+
+## Platform binaries
+
+| Platform | Binary name | Signed |
+|----------|------------|--------|
+| Linux x64 | `hai-linux-x64` | — |
+| macOS arm64 | `hai-darwin-arm64` | ✓ (codesign + notarization) |
+| macOS x64 | `hai-darwin-x64` | ✓ (codesign + notarization) |
+| Windows x64 | `hai-windows-x64.exe` | ✓ (Authenticode) |
+
+## Testing binary builds
+
+Use the **Test Release** workflow (`test-release.yml`) to manually test binary builds without creating a real release:
+
+1. Go to **Actions** → **Test Release** → **Run workflow**
+2. The workflow builds all 4 platform binaries, runs smoke tests, and uploads artifacts
+3. Download the `all-binaries` artifact to inspect the output
 
 ## Manual release (fallback)
 
@@ -45,7 +76,7 @@ git tag v0.2.0
 git push origin v0.2.0
 ```
 
-This will trigger the release workflow. Note: the workflow validates that the tag version matches `packages/cli/package.json`, so make sure they're in sync.
+This will trigger `release.yml` to build binaries and create a GitHub Release. Note: npm publishing is handled separately by `version.yml` and won't be triggered by a manual tag push.
 
 ## Available scripts
 
@@ -54,9 +85,13 @@ This will trigger the release workflow. Note: the workflow validates that the ta
 | `pnpm changeset` | Add a new changeset |
 | `pnpm changeset status` | Check pending changesets |
 | `pnpm release:version` | Apply changesets and bump versions (used by CI) |
+| `pnpm --filter hai build:exe` | Build binary for current platform |
+| `pnpm --filter hai build:exe -- --target <target>` | Cross-compile for a specific platform |
+| `pnpm --filter hai build:exe:all` | Build binaries for all platforms |
 
 ## Tips
 
 - Every user-facing change should have a changeset — CI will remind you if one is missing
 - You can add multiple changesets per PR if you're making changes to multiple packages
 - Changeset files are automatically deleted when versions are bumped
+- CI verifies binary compilation on every push/PR to catch build regressions early

packages/cli/src/__tests__/ci-workflow.test.ts

@@ -42,12 +42,16 @@ describe("CI workflow (.github/workflows/ci.yml)", () => {
     expect(content).toContain("pnpm build");
   });
 
-  it("does not include binary build step", () => {
+  it("includes binary build step", () => {
-    expect(content).not.toContain("pnpm build:exe");
+    expect(content).toContain("build:exe");
   });
 
-  it("does not include Bun setup", () => {
+  it("includes Bun setup", () => {
-    expect(content).not.toContain("oven-sh/setup-bun");
+    expect(content).toContain("oven-sh/setup-bun");
+  });
+
+  it("verifies binary exists after build", () => {
+    expect(content).toContain("test -f packages/cli/dist/hai");
   });
 
   it("includes pnpm test step", () => {
@@ -114,15 +118,153 @@ describe("Version & Release workflow (.github/workflows/version.yml)", () => {
   });
 });
 
-describe("Deleted binary workflows", () => {
+describe("Binary release workflow (.github/workflows/release.yml)", () => {
-  it("release.yml no longer exists", () => {
+  let workflow: any;
-    const path = join(workspaceRoot, ".github", "workflows", "release.yml");
+  let content: string;
-    expect(existsSync(path)).toBe(false);
+
+  beforeAll(() => {
+    const result = loadWorkflow("release.yml");
+    workflow = result.parsed;
+    content = result.content;
   });
 
-  it("test-release.yml no longer exists", () => {
+  it("is valid YAML", () => {
-    const path = join(workspaceRoot, ".github", "workflows", "test-release.yml");
+    expect(workflow).toBeDefined();
-    expect(existsSync(path)).toBe(false);
+    expect(typeof workflow).toBe("object");
+  });
+
+  it("triggers on version tags", () => {
+    expect(workflow.on.push.tags).toBeDefined();
+    expect(workflow.on.push.tags.some((t: string) => t.includes("v"))).toBe(true);
+  });
+
+  it("has build-binaries job with 4-target matrix", () => {
+    const matrix = workflow.jobs["build-binaries"].strategy.matrix.include;
+    expect(matrix).toHaveLength(4);
+    const targets = matrix.map((m: any) => m.target);
+    expect(targets).toContain("bun-linux-x64");
+    expect(targets).toContain("bun-darwin-arm64");
+    expect(targets).toContain("bun-darwin-x64");
+    expect(targets).toContain("bun-windows-x64");
+  });
+
+  it("has correct OS runners for each target", () => {
+    const matrix = workflow.jobs["build-binaries"].strategy.matrix.include;
+    const osMap: Record<string, string> = {};
+    matrix.forEach((m: any) => { osMap[m.target] = m.os; });
+    expect(osMap["bun-linux-x64"]).toBe("ubuntu-latest");
+    expect(osMap["bun-darwin-arm64"]).toBe("macos-latest");
+    expect(osMap["bun-darwin-x64"]).toBe("macos-13");
+    expect(osMap["bun-windows-x64"]).toBe("windows-latest");
+  });
+
+  it("uses softprops/action-gh-release", () => {
+    expect(content).toContain("softprops/action-gh-release");
+  });
+
+  it("references signing scripts", () => {
+    expect(content).toContain("scripts/sign-macos.sh");
+    expect(content).toContain("scripts/sign-windows.ps1");
+  });
+
+  it("generates checksums on all platforms", () => {
+    expect(content).toContain("sha256sum");
+    expect(content).toContain("shasum -a 256");
+    expect(content).toContain("Get-FileHash");
+  });
+
+  it("has contents: write permission", () => {
+    expect(workflow.permissions.contents).toBe("write");
+  });
+
+  it("has github-release job that depends on build-binaries", () => {
+    expect(workflow.jobs["github-release"].needs).toContain("build-binaries");
+  });
+});
+
+describe("Test-release workflow (.github/workflows/test-release.yml)", () => {
+  let workflow: any;
+  let content: string;
+
+  beforeAll(() => {
+    const result = loadWorkflow("test-release.yml");
+    workflow = result.parsed;
+    content = result.content;
+  });
+
+  it("is valid YAML", () => {
+    expect(workflow).toBeDefined();
+    expect(typeof workflow).toBe("object");
+  });
+
+  it("has workflow_dispatch trigger", () => {
+    expect(workflow.on).toHaveProperty("workflow_dispatch");
+  });
+
+  it("has 4-target build matrix", () => {
+    const matrix = workflow.jobs["build-binaries"].strategy.matrix.include;
+    expect(matrix).toHaveLength(4);
+    const targets = matrix.map((m: any) => m.target);
+    expect(targets).toContain("bun-linux-x64");
+    expect(targets).toContain("bun-darwin-arm64");
+    expect(targets).toContain("bun-darwin-x64");
+    expect(targets).toContain("bun-windows-x64");
+  });
+
+  it("includes smoke tests with --help", () => {
+    expect(content).toContain("--help");
+  });
+
+  it("has signing steps with secret-availability guards", () => {
+    expect(content).toContain("APPLE_CERTIFICATE_BASE64 != ''");
+    expect(content).toContain("WINDOWS_CERTIFICATE_BASE64 != ''");
+  });
+
+  it("uploads artifacts", () => {
+    expect(content).toContain("actions/upload-artifact");
+  });
+
+  it("has a collect job that combines artifacts", () => {
+    expect(workflow.jobs.collect).toBeDefined();
+    expect(workflow.jobs.collect.needs).toContain("build-binaries");
+    expect(content).toContain("all-binaries");
+  });
+});
+
+describe("Code signing — Release workflow secrets", () => {
+  let content: string;
+
+  beforeAll(() => {
+    const result = loadWorkflow("release.yml");
+    content = result.content;
+  });
+
+  it("references macOS signing secrets", () => {
+    expect(content).toContain("secrets.APPLE_CERTIFICATE_BASE64");
+    expect(content).toContain("secrets.APPLE_CERTIFICATE_PASSWORD");
+    expect(content).toContain("secrets.APPLE_IDENTITY");
+    expect(content).toContain("secrets.APPLE_ID");
+    expect(content).toContain("secrets.APPLE_TEAM_ID");
+    expect(content).toContain("secrets.APPLE_APP_PASSWORD");
+  });
+
+  it("references Windows signing secrets", () => {
+    expect(content).toContain("secrets.WINDOWS_CERTIFICATE_BASE64");
+    expect(content).toContain("secrets.WINDOWS_CERTIFICATE_PASSWORD");
+  });
+
+  it("generates checksums after signing", () => {
+    const signMacIdx = content.indexOf("Sign macOS binary");
+    const signWinIdx = content.indexOf("Sign Windows binary");
+    const checksumLinuxIdx = content.indexOf("Generate checksum (Linux)");
+    const checksumMacIdx = content.indexOf("Generate checksum (macOS)");
+    const checksumWinIdx = content.indexOf("Generate checksum (Windows)");
+
+    // All checksum steps come after all signing steps
+    expect(checksumLinuxIdx).toBeGreaterThan(signMacIdx);
+    expect(checksumLinuxIdx).toBeGreaterThan(signWinIdx);
+    expect(checksumMacIdx).toBeGreaterThan(signMacIdx);
+    expect(checksumWinIdx).toBeGreaterThan(signWinIdx);
   });
 });