hookdeck-cli 1.6.0 → 1.7.0

package/README.md

@@ -394,7 +394,7 @@ hookdeck logout
 
 When forwarding events to an HTTPS URL as the first argument to `hookdeck listen` (e.g., `https://localhost:1234/webhook`), you might encounter SSL validation errors if the destination is using a self-signed certificate.
 
-For local development scenarios, you can instruct the `listen` command to bypass this SSL certificate validation by using its `--insecure` flag. You must provide the full HTTPS URL.
+For local development scenarios, you can instruct the `listen` command to bypass this SSL certificate validation by using its `--insecure` flag. You must provide the full HTTPS URL. This flag also applies to the periodic server health checks that the CLI performs.
 
 **This is dangerous and should only be used in trusted local development environments for destinations you control.**
 
@@ -404,6 +404,14 @@ Example of skipping SSL validation for an HTTPS destination:
 hookdeck listen --insecure https://<your-ssl-url-or-url:port>/ <source-alias?> <connection-query?>
 ```
 
+### Disable health checks
+
+The CLI periodically checks if your local server is reachable and displays warnings if the connection fails. If these health checks cause issues in your environment, you can disable them with the `--no-healthcheck` flag:
+
+```sh
+hookdeck listen --no-healthcheck 3000 <source-alias?>
+```
+
 ### Version
 
 Print your CLI version and whether or not a new version is available.
@@ -1011,6 +1019,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 +1093,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 +1145,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.
 
-### Branching Strategy
+## Release Process
 
-The project uses two primary branches:
+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`.
 
-- **`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`.
+### Stable Release (Preferred Method: GitHub UI)
 
-### Beta Releases
+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
 
-Beta releases allow you to publish pre-release versions for testing without blocking the `main` branch or affecting stable releases.
+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`
 
-**Process:**
+**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
+```
 
-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`
+### Pre-release from Main (General Beta Testing)
+
+For general beta testing of features that have been merged to `main`:
+
+**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`
+
+**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 +1215,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
-
-Production releases are created from the `main` branch using GitHub's release interface.
+### Pre-release from Feature Branch (Feature-Specific Testing)
 
-**Process:**
+For testing a specific feature in isolation before merging to main:
 
-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.6.0",
+  "version": "1.7.0",
   "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": {}
 }