beadboard/docs/prompts/2026-02-19-beads-cgo-fix-pr.md

Prompt: Fix CGO-Enabled Release Builds for steveyegge/beads

Mission

Submit a PR to https://github.com/steveyegge/beads that fixes issue #1856: "Install script binary has CGO_ENABLED=0 — Dolt embedded mode fails"

Background Context

The Problem

1. All release builds run on ubuntu-latest (see .github/workflows/release.yml)
2. Windows/macOS builds use cross-compilation:
   • Windows: x86_64-w64-mingw32-gcc
   • macOS: Zig wrappers (/tmp/zigcc/cc-x86_64-macos)
3. Only Linux ICU is installed: sudo apt-get install libicu-dev
4. CGO requires target-platform ICU headers/libraries
5. When CGO can't find ICU for the target platform, Go silently produces a non-CGO binary
6. Users get: Error: failed to open database: dolt backend requires CGO

Evidence

# From installed binary on macOS:
strings ~/.local/bin/bd | grep CGO_ENABLED
CGO_ENABLED=0  # <-- PROBLEM

# The .goreleaser.yml SAYS CGO_ENABLED=1, but cross-compilation fails silently

Affected Platforms

• Windows AMD64 (cross-compiled with mingw)
• Windows ARM64 (cross-compiled with Zig)
• macOS AMD64 (cross-compiled with Zig)
• macOS ARM64 (cross-compiled with Zig)

Linux builds work because they're native.

The Fix: Native Builds Per Platform

Approach

Instead of cross-compiling from Ubuntu, use native runners:

Platform	Runner	CGO Support
Linux AMD64	ubuntu-latest	Native gcc + libicu-dev
Linux ARM64	ubuntu-latest	Cross-compile (aarch64-linux-gnu-gcc)
macOS AMD64	macos-latest	Native clang + icu4c (brew)
macOS ARM64	macos-latest	Native clang + icu4c (brew)
Windows AMD64	windows-latest	Native gcc via MSYS2 UCRT64
Windows ARM64	windows-latest	Cross-compile with Zig

Why This Works

• Native builds have native ICU available via package managers
• CGO "just works" when the compiler can find headers/libs
• No fragile cross-compilation setup needed

TDD Approach (REQUIRED)

Step 1: Write Failing Test FIRST

Add a verification step in release.yml that checks for CGO:

- name: Verify CGO enabled in binary
  run: |
    # For each built binary, verify CGO is enabled
    for binary in dist/*/bd; do
      if strings "$binary" | grep -q "CGO_ENABLED=0"; then
        echo "ERROR: $binary was built without CGO support"
        exit 1
      fi
      echo "OK: $binary has CGO support"
    done

This test will FAIL on current main branch - proving the bug exists.

Step 2: Implement Fix

Split the release workflow into platform-specific jobs.

Step 3: Test Passes

After fix, the verification step passes on all platforms.

Files to Modify

1. .github/workflows/release.yml

Split into 3 jobs:

jobs:
  build-linux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with: { fetch-depth: 0 }
      - uses: actions/setup-go@v6
        with: { go-version-file: 'go.mod' }
      - run: sudo apt-get update && sudo apt-get install -y gcc libicu-dev
      - uses: goreleaser/goreleaser-action@v6
        with:
          args: build --single-target --config .goreleaser-linux.yml
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Verify CGO enabled
        run: |
          if strings dist/bd_linux_amd64/bd | grep -q "CGO_ENABLED=0"; then
            echo "ERROR: Linux binary lacks CGO"
            exit 1
          fi

  build-macos:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v6
        with: { fetch-depth: 0 }
      - uses: actions/setup-go@v6
        with: { go-version-file: 'go.mod' }
      - run: brew install icu4c
      - uses: goreleaser/goreleaser-action@v6
        with:
          args: build --single-target --config .goreleaser-macos.yml
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CGO_CFLAGS: "-I$(brew --prefix icu4c)/include"
          CGO_LDFLAGS: "-L$(brew --prefix icu4c)/lib"
      - name: Verify CGO enabled
        run: |
          for binary in dist/*/bd; do
            if strings "$binary" | grep -q "CGO_ENABLED=0"; then
              echo "ERROR: $binary lacks CGO"
              exit 1
            fi
          fi

  build-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v6
        with: { fetch-depth: 0 }
      - uses: actions/setup-go@v6
        with: { go-version-file: 'go.mod' }
      - uses: msys2/setup-msys2@v2
        with:
          msystem: UCRT64
          update: true
          install: mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-icu
      - uses: goreleaser/goreleaser-action@v6
        with:
          args: build --single-target --config .goreleaser-windows.yml
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CGO_ENABLED: 1
          CC: C:/msys64/ucrt64/bin/gcc.exe
          PATH: C:/msys64/ucrt64/bin;${{ env.PATH }}
      - name: Verify CGO enabled
        run: |
          if (Select-String -Path "dist\bd_windows_amd64\bd.exe" -Pattern "CGO_ENABLED=0" -Quiet) {
            Write-Error "ERROR: Windows binary lacks CGO"
            exit 1
          }

  release:
    needs: [build-linux, build-macos, build-windows]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Download all artifacts
        uses: actions/download-artifact@v4
      - uses: goreleaser/goreleaser-action@v6
        with:
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

2. Split .goreleaser.yml (optional, or use build IDs)

Either split into separate config files, or use build IDs with goos/goarch filters.

Best Practices for PR Acceptance

1. Be Respectful and Clear

• Open with: "Thank you for beads! It's an excellent tool."
• Acknowledge existing work: "I see the goreleaser config already specifies CGO_ENABLED=1"
• Frame as collaborative: "This PR proposes a fix for #1856"

2. Keep It Minimal

• Don't refactor unrelated code
• Don't add features
• Only change what's needed to fix the CGO issue

3. Explain the "Why"

In PR description:

• Cross-compilation + CGO + ICU is fragile
• Native builds are simpler and guaranteed to work
• This aligns with how Homebrew builds beads (native on macOS)

4. Reference Existing Issue

Fixes #1856

5. Test Evidence

Include in PR:

• Link to your fork's CI run showing test pass
• Or screenshots of strings bd.exe | grep CGO showing no CGO_ENABLED=0

PR Description Template

## Summary

Fixes #1856 - Release binaries were built with CGO_ENABLED=0, causing "Dolt backend requires CGO" errors for users.

## Problem

Cross-compilation from `ubuntu-latest` for Windows/macOS targets cannot find ICU headers for the target platform. Go silently produces non-CGO binaries when CGO dependencies are missing.

## Solution

Use native runners for each platform:
- `ubuntu-latest` for Linux (existing)
- `macos-latest` for macOS (native CGO with icu4c)
- `windows-latest` for Windows (native CGO with MSYS2/UCRT64)

## Testing

Added CI verification step that fails if binary contains `CGO_ENABLED=0`:
```yaml
- name: Verify CGO enabled
  run: |
    if strings dist/bd | grep -q "CGO_ENABLED=0"; then
      echo "ERROR: Binary built without CGO"
      exit 1
    fi

This test currently fails on main; passes with this fix.

Files Changed

• .github/workflows/release.yml - Split into platform-native jobs

Notes

• Homebrew already builds beads natively on macOS (and it works)
• This approach is more maintainable than fixing cross-compilation ICU paths
• Linux ARM64 still cross-compiles (no arm64 GitHub runner for free tiers)

## Fork Setup

1. Fork https://github.com/steveyegge/beads
2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/beads.git`
3. Create branch: `git checkout -b fix/cgo-native-builds`
4. Make changes
5. Push: `git push origin fix/cgo-native-builds`
6. Open PR against `steveyegge/beads:main`

## References

- Issue: https://github.com/steveyegge/beads/issues/1856
- Current release.yml: `.github/wo
rkflows/release.yml
- Current goreleaser: `.goreleaser.yml`
- Our local build succeeded with MSYS2 UCRT64 on Windows

## Related Bead

- `bb-zbt`: PR: Fix CGO-enabled release builds for beads (beadboard project)

---

Good luck! Be excellent to the maintainers.