fix: pnpm v10+ compatibility: Single-package binary distribution with GoReleaser

[leggetter]

Fix pnpm v10+ compatibility: Single-package binary distribution with GoReleaser

Problem

The current npm distribution approach relies on go-npm-next with postinstall scripts to download platform-specific binaries. This creates a poor developer experience with modern package managers, particularly pnpm v10+, which blocks lifecycle scripts by default for security reasons.

Impact:

• Users installing with pnpm v10+ get incorrect binaries (Linux x86-64 placeholder)
• Requires manual pnpm configuration workarounds (onlyBuiltDependencies, pnpm approve-builds)
• Breaks in environments where --ignore-scripts is used
• Poor experience in CI/CD environments with script restrictions

Related Issue: #166

Solution

Switched to a single-package approach that includes all platform binaries directly in the npm package, using GoReleaser's native post hooks to organize binaries during the build process.

Key Changes

1. JavaScript Wrapper Script (bin/hookdeck.js)

   • Detects platform/architecture at runtime
   • Executes the correct binary from binaries/ directory
   • No postinstall scripts required

2. Unified GoReleaser Config (.goreleaser/npm.yml)

   • Builds all 6 platforms in a single configuration
   • Uses post hooks to automatically organize binaries into binaries/{platform}-{arch}/ structure
   • No publishing sections (build-only for npm package)

3. Release Workflow Updates (.github/workflows/release.yml)

   • Builds all platform binaries directly in npm publish job
   • Uses Go cross-compilation (no need for separate platform runners)
   • Installs Windows cross-compilation tools (mingw) for Windows builds

4. Package Configuration (package.json)

   • Removed go-npm-next dependency
   • Removed postinstall/preuninstall scripts
   • Updated bin to point to wrapper script
   • Added binaries/ to files array

5. Testing Infrastructure

   • Created test-scripts/test-npm-build.sh for automated testing
   • Added test-npm-build.yml CI workflow
   • Updated README with testing instructions

Supported Platforms

• darwin-amd64 (macOS Intel)
• darwin-arm64 (macOS Apple Silicon)
• linux-amd64 (Linux x86-64)
• linux-arm64 (Linux ARM64)
• win32-amd64 (Windows x86-64)
• win32-386 (Windows 32-bit)

Benefits

✅ Works with pnpm v10+ - No postinstall scripts required
✅ Works with --ignore-scripts - All binaries included in package
✅ Better CI/CD compatibility - No script execution needed
✅ Offline support - Binaries included, no network requests
✅ Uses GoReleaser natively - Leverages existing tooling
✅ Simpler workflow - Single package, single build process
✅ Better developer experience - "Just works" with any package manager

Trade-offs

• Package size: ~30-60MB (includes all 6 platform binaries)
  • Acceptable for npm (well under 250MB limit)
  • One-time download per version
  • Better than broken installs

Testing

Local Testing

# Run automated test script
./test-scripts/test-npm-build.sh

# Or test manually
goreleaser build -f .goreleaser/npm.yml --snapshot --clean
node bin/hookdeck.js --version
npm pack --dry-run

CI Testing

• New test-npm-build.yml workflow runs on every PR
• Verifies all platforms build correctly
• Tests wrapper script functionality
• Validates npm package structure

Migration Notes

• No breaking changes for existing users
• Works with npm, yarn, pnpm, and bun
• Backward compatible with all package managers
• Existing installations will continue to work

Files Changed

Core Implementation

• .goreleaser/npm.yml - New unified GoReleaser config
• .github/workflows/release.yml - Added GoReleaser build step
• package.json - Removed go-npm-next, updated bin path
• .gitignore - Added binaries/, exception for hookdeck.js
• bin/hookdeck.js - New wrapper script

Testing & Documentation

• test-scripts/test-npm-build.sh - Automated test script
• .github/workflows/test-npm-build.yml - CI workflow
• README.md - Updated with testing instructions

Verification Checklist

• All 6 platform binaries build successfully
• Wrapper script detects platform correctly
• npm pack includes all required files
• Works with pnpm v10+ (no postinstall scripts)
• Works with --ignore-scripts flag
• CI workflow tests build process
• Documentation updated

Branch Classification

This PR is a feature/fix branch that will be merged to a feature branch (or next branch) for beta testing before promoting to main.

Next Steps: Beta Release Process

After this PR is merged, we'll create a beta release to test the new npm distribution approach:

1. Merge PR to Feature Branch

• Merge this PR to the target branch (e.g., feat/install-process or next)
• Ensure all CI checks pass

2. Create Beta Tag

From the merged branch, create and push a beta tag:

# Checkout the branch where PR was merged
git checkout <branch-name>
git pull origin <branch-name>

# Create a beta tag (increment from current version)
# Example: if current version is 1.6.0, use 1.6.1-beta.0
git tag v1.6.1-beta.0
git push origin v1.6.1-beta.0

Tag naming convention:

• Format: v<major>.<minor>.<patch>-beta.<number>
• Examples: v1.6.1-beta.0, v1.6.1-beta.1, v2.0.0-beta.0

3. Automated Release Process

The GitHub Actions release.yml workflow will automatically:

1. Detect the branch containing the tag (works from any branch)
2. Build all platform binaries using GoReleaser:
   • macOS (Intel & Apple Silicon)
   • Linux (amd64 & arm64)
   • Windows (amd64 & 386)
3. Build npm package with all binaries included:
   • Uses .goreleaser/npm.yml config
   • Builds binaries directly in CI (no downloads)
   • Includes all 6 platform binaries in package
4. Create GitHub pre-release:
   • Marked as "Pre-release" automatically
   • Includes all platform binaries and checksums
5. Publish to npm with beta tag:
   • Version: 1.6.1-beta.0
   • Tag: beta (extracted from pre-release identifier)
   • Installable via: npm install hookdeck-cli@beta -g
6. Publish beta packages:
   • Homebrew: hookdeck-beta formula
   • Scoop: hookdeck-beta package
   • Docker: Tagged with version (not latest)

4. Verify Beta Release

Test npm installation:

# Install beta version
npm install hookdeck-cli@beta -g

# Verify it works with pnpm v10+
pnpm add -g hookdeck-cli@beta

# Test the wrapper script
hookdeck --version
hookdeck --help

Verify package contents:

# Check npm package includes binaries
npm pack hookdeck-cli@beta
tar -tzf hookdeck-cli-1.6.1-beta.0.tgz | grep binaries

Test on different platforms:

• macOS (Intel & Apple Silicon)
• Linux (amd64 & arm64)
• Windows (amd64 & 32-bit)

5. After Beta Testing

Once beta testing is complete and verified:

1. Merge to main when ready for production release
2. Create production tag from main:

   git checkout main
   git pull origin main
   git tag v1.6.1
   git push origin v1.6.1

3. Production release will:
   • Publish to npm with latest tag
   • Create stable Homebrew/Scoop packages
   • Tag Docker image as latest

Important Notes

• The release workflow supports tagging from ANY branch - it automatically detects which branch contains the tag
• Pre-release detection is automatic - GoReleaser detects tags with -beta, -rc, etc. and marks them as pre-releases
• npm tag extraction - The workflow extracts the pre-release identifier (e.g., beta from 1.6.1-beta.0) and uses it as the npm distribution tag
• No manual intervention needed - The entire release process is automated once the tag is pushed

[leggetter]

@copilot review

[Copilot]

@leggetter I've opened a new pull request, #201, to work on those changes. Once the pull request is ready, I'll request review from you.