hookdeck-cli 1.5.0 → 1.6.1-beta.1

package/README.md

@@ -1011,6 +1011,46 @@ Then run the locally generated `hookdeck-cli` binary:
 ./hookdeck-cli
 ```
 
+### Testing the npm package build
+
+To test the npm package build process locally (including the wrapper script), you can use the automated test script:
+
+```sh
+# Run the automated test script (recommended)
+./test-scripts/test-npm-build.sh
+```
+
+The test script will:
+- Build all 6 platform binaries using GoReleaser
+- Verify the binaries directory structure
+- Test the wrapper script on your current platform
+- Verify npm pack includes all required files
+
+**Manual testing (if you prefer step-by-step):**
+
+```sh
+# Install GoReleaser (if not already installed)
+# Option 1: Using Homebrew (recommended on macOS)
+brew install goreleaser
+
+# Option 2: Download binary from GitHub releases
+# Visit https://github.com/goreleaser/goreleaser/releases/latest
+
+# Build all platform binaries for npm
+goreleaser build -f .goreleaser/npm.yml --snapshot --clean
+
+# Verify binaries directory structure
+ls -R binaries/
+
+# Test the wrapper script on your platform
+node bin/hookdeck.js --version
+
+# Test npm package creation (dry-run)
+npm pack --dry-run
+```
+
+This will create the `binaries/` directory with all 6 platform binaries, allowing you to test the wrapper script locally before publishing.
+
 ## Testing
 
 ### Running Acceptance Tests
@@ -1045,6 +1085,36 @@ In CI environments, set the `HOOKDECK_CLI_TESTING_API_KEY` environment variable
 
 For detailed testing documentation and troubleshooting, see [`test/acceptance/README.md`](test/acceptance/README.md).
 
+### Testing npm package and wrapper script
+
+The npm package includes a wrapper script (`bin/hookdeck.js`) that detects the platform and executes the correct binary. 
+
+**Quick test (using automated script):**
+
+```sh
+./test-scripts/test-npm-build.sh
+```
+
+**Manual testing:**
+
+```sh
+# Ensure GoReleaser is installed (see "Testing the npm package build" section above)
+
+# Build all platform binaries
+goreleaser build -f .goreleaser/npm.yml --snapshot --clean
+
+# Test wrapper script on current platform
+node bin/hookdeck.js version
+
+# Verify wrapper script can find binary
+node bin/hookdeck.js --help
+
+# Test npm pack includes all files
+npm pack --dry-run | grep -E "(bin/hookdeck.js|binaries/)"
+```
+
+**Note:** The wrapper script expects binaries in `binaries/{platform}-{arch}/hookdeck[.exe]`. When building locally, ensure all platforms are built or the wrapper will fail for missing platforms.
+
 ### Testing against a local API
 
 When testing against a non-production Hookdeck API, you can use the
@@ -1067,40 +1137,59 @@ docker run --rm -it \
 
 ## Releasing
 
-This section describes the branching strategy and release process for the Hookdeck CLI.
+This section describes the release process for the Hookdeck CLI.
+
+## Release Process
+
+The release workflow supports tagging from **ANY branch** - it automatically detects which branch contains the tag. This means you can create beta releases directly from feature branches for testing before merging to `main`.
 
-### Branching Strategy
+### Stable Release (Preferred Method: GitHub UI)
 
-The project uses two primary branches:
+1. Ensure all tests pass on `main`
+2. Go to the [GitHub Releases page](https://github.com/hookdeck/hookdeck-cli/releases)
+3. Click "Draft a new release"
+4. Create a new tag with a stable version (e.g., `v1.3.0`)
+5. Target the `main` branch
+6. Generate release notes or write them manually
+7. Publish the release
+
+The GitHub Actions workflow will automatically:
+- Build binaries for all platforms
+- Create a stable GitHub release
+- Publish to NPM with the `latest` tag
+- Update package managers:
+  - Homebrew: `hookdeck` formula
+  - Scoop: `hookdeck` package
+  - Docker: Updates both the version tag and `latest`
 
-- **`main`** - The stable, production-ready branch. All production releases are created from this branch.
-- **`next`** - The beta/pre-release branch. All new features are merged here first for testing before being promoted to `main`.
+**Alternative (Command Line):**
+```bash
+git checkout main
+git tag v1.3.0
+git push origin v1.3.0
+# Then create release notes on GitHub Releases page
+```
 
-### Beta Releases
+### Pre-release from Main (General Beta Testing)
 
-Beta releases allow you to publish pre-release versions for testing without blocking the `main` branch or affecting stable releases.
+For general beta testing of features that have been merged to `main`:
 
-**Process:**
+**Preferred Method: GitHub UI**
+1. Ensure `main` branch is in the desired state
+2. Go to the [GitHub Releases page](https://github.com/hookdeck/hookdeck-cli/releases)
+3. Click "Draft a new release"
+4. Create a new tag with pre-release version (e.g., `v1.3.0-beta.1`)
+5. Target the `main` branch
+6. Check "Set as a pre-release"
+7. Publish the release
+8. GitHub Actions will build and publish with npm tag `beta`
 
-1. Ensure all desired features are merged into the `next` branch
-2. Pull the latest changes locally:
-   ```sh
-   git checkout next
-   git pull origin next
-   ```
-3. Create and push a beta tag with a pre-release identifier:
-   ```sh
-   git tag v1.2.3-beta.0
-   git push origin v1.2.3-beta.0
-   ```
-4. The GitHub Actions workflow will automatically:
-   - Build binaries for all platforms (macOS, Linux, Windows)
-   - Create a GitHub pre-release (marked as "Pre-release")
-   - Publish to NPM with the `beta` tag
-   - Create beta packages:
-     - Homebrew: `hookdeck-beta` formula
-     - Scoop: `hookdeck-beta` package
-     - Docker: Tagged with the version (e.g., `v1.2.3-beta.0`), but not `latest`
+**Alternative (Command Line):**
+```bash
+git checkout main
+git tag v1.3.0-beta.1
+git push origin v1.3.0-beta.1
+```
 
 **Installing beta releases:**
 
@@ -1118,39 +1207,77 @@ brew install hookdeck/hookdeck/hookdeck-beta
 scoop install hookdeck-beta
 
 # Docker
-docker run hookdeck/hookdeck-cli:v1.2.3-beta.0 version
+docker run hookdeck/hookdeck-cli:v1.3.0-beta.1 version
 ```
 
-### Production Releases
+### Pre-release from Feature Branch (Feature-Specific Testing)
 
-Production releases are created from the `main` branch using GitHub's release interface.
+For testing a specific feature in isolation before merging to main:
 
-**Process:**
-
-1. Merge the `next` branch into `main`:
-   ```sh
-   git checkout main
-   git pull origin main
-   git merge next
-   git push origin main
-   ```
+**Preferred Method: GitHub UI**
+1. Ensure your feature branch is pushed to origin
 2. Go to the [GitHub Releases page](https://github.com/hookdeck/hookdeck-cli/releases)
 3. Click "Draft a new release"
-4. Create a new tag with a stable version (e.g., `v1.3.0`)
-5. Target the `main` branch
-6. Generate release notes or write them manually
-7. Publish the release
+4. Create a new tag with pre-release version (e.g., `v1.3.0-beta.1`)
+5. Target your feature branch (e.g., `feat/my-feature`)
+6. Check "Set as a pre-release"
+7. Add notes about what's being tested
+8. Publish the release
+9. GitHub Actions will automatically detect the branch and build from it
+
+**Alternative (Command Line):**
+```bash
+git checkout feat/my-feature
+git tag v1.3.0-beta.1
+git push origin v1.3.0-beta.1
+# Then create release notes on GitHub Releases page
+```
 
-The GitHub Actions workflow will automatically:
-- Build binaries for all platforms
-- Create a stable GitHub release
-- Publish to NPM with the `latest` tag
-- Update package managers:
-  - Homebrew: `hookdeck` formula
-  - Scoop: `hookdeck` package
-  - Docker: Updates both the version tag and `latest`
+**Installing beta releases:**
+
+```sh
+# NPM
+npm install hookdeck-cli@beta -g
+
+# Homebrew
+brew install hookdeck/hookdeck/hookdeck-beta
+
+# To force the symlink update and overwrite all conflicting files:
+# brew link --overwrite hookdeck-beta
+
+# Scoop
+scoop install hookdeck-beta
+
+# Docker
+docker run hookdeck/hookdeck-cli:v1.3.0-beta.1 version
+```
+
+**Note:** Only stable releases (without pre-release identifiers like `-beta`, `-alpha`) will update the `latest` tags across all distribution channels.
+
+## Repository Setup
+
+### GitHub Repository Settings
+
+To maintain code quality and protect the main branch, configure the following settings in your GitHub repository:
+
+**Default Branch:**
+1. Go to Settings → Branches
+2. Set default branch to `main` (if not already set)
+
+**Branch Protection Rules for `main`:**
+1. Go to Settings → Branches → Branch protection rules
+2. Add rule for `main` branch
+3. Enable the following settings:
+   - **Require a pull request before merging**
+     - Require approvals: 1 (or as needed for your team)
+   - **Require status checks to pass before merging**
+     - Require branches to be up to date before merging
+     - Add status check: `build-linux`, `build-mac`, `build-windows` (from test workflow)
+   - **Do not allow bypassing the above settings**
+   - **Restrict force pushes** (recommended)
+   - **Restrict deletions** (recommended)
 
-**Note:** Only stable releases (without pre-release identifiers) will update the `latest` tags across all distribution channels.
+These settings ensure that all changes to `main` go through proper review and testing before being merged.
 
 ## License
 

package/bin/hookdeck.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+const { execFileSync } = require('child_process');
+const { existsSync } = require('fs');
+const path = require('path');
+
+const platform = process.platform; // 'darwin', 'linux', 'win32'
+const arch = process.arch; // 'x64', 'arm64', 'ia32'
+
+// Map Node.js arch to Go arch naming
+const archMap = {
+  'x64': 'amd64',
+  'arm64': 'arm64',
+  'ia32': '386'
+};
+const goArch = archMap[arch] || arch;
+
+// Determine binary directory name and executable name
+const binaryDir = `${platform}-${goArch}`;
+const binaryName = platform === 'win32' ? 'hookdeck.exe' : 'hookdeck';
+
+// Path to the binary relative to this script
+const binaryPath = path.join(__dirname, '..', 'binaries', binaryDir, binaryName);
+
+if (!existsSync(binaryPath)) {
+  console.error(`Error: Unsupported platform: ${platform}-${arch}`);
+  console.error(`Expected binary at: ${binaryPath}`);
+  console.error(`Please report this issue at https://github.com/hookdeck/hookdeck-cli/issues`);
+  process.exit(1);
+}
+
+try {
+  execFileSync(binaryPath, process.argv.slice(2), { stdio: 'inherit' });
+} catch (error) {
+  // execFileSync will exit with the same code as the binary
+  // If there's an error executing, exit with code 1
+  process.exit(error.status || 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookdeck-cli",
-  "version": "1.5.0",
+  "version": "1.6.1-beta.1",
   "description": "Hookdeck CLI",
   "repository": {
     "type": "git",
@@ -16,19 +16,12 @@
   },
   "homepage": "https://github.com/hookdeck/hookdeck-cli#readme",
   "bin": {
-    "hookdeck": "./bin/hookdeck"
+    "hookdeck": "./bin/hookdeck.js"
   },
-  "files": [],
-  "scripts": {
-    "postinstall": "go-npm install",
-    "preuninstall": "go-npm uninstall"
-  },
-  "goBinary": {
-    "name": "hookdeck",
-    "path": "./bin",
-    "url": "https://github.com/hookdeck/hookdeck-cli/releases/download/v{{version}}/hookdeck_{{version}}_{{platform}}_{{arch}}.tar.gz"
-  },
-  "dependencies": {
-    "go-npm-next": "^1.1.0"
-  }
+  "files": [
+    "bin/",
+    "binaries/"
+  ],
+  "scripts": {},
+  "dependencies": {}
 }