Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix: critical — binary download safety, versioning, error handling

Mario3b9958abf8dd
diff --git a/.gitignore b/.gitignore
index 70df2354..14fada16 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,7 +11,6 @@ dist/
# npm package
npm/node_modules/
-npm/package-lock.json
# OpenClaw workspace files (should never be committed)
.openclaw/
diff --git a/RELEASE.md b/RELEASE.md
index e347ca41..c432aabb 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -70,17 +70,26 @@ If you need to re-release an existing tag:
## Pipeline details
-### 1. Goreleaser (Go binary)
+### 1. Goreleaser (Go binary) — CRITICAL for npm
Triggered on `v*` tag push. Builds binaries and creates GitHub release.
**What it does:**
-- Compiles for all platforms
-- Generates `checksums.txt` (SHA256)
-- Uploads to GitHub Releases
+- ✅ Compiles for all platforms (darwin-arm64, darwin-x64, linux-x64, linux-arm64, windows-x64)
+- ✅ Generates `checksums.txt` (SHA256)
+- ✅ **Uploads binaries to GitHub Releases** ← Required by npm postinstall!
+- Also: Docker images, changelog, etc.
+
+**⚠️ CRITICAL:** npm postinstall script downloads binaries from GitHub Releases. If the release doesn't have the binaries (e.g., only Docker images), `npm install pinchtab` will fail silently and the binary won't be available.
**Configured in:** `.goreleaser.yml`
+**Verify release has binaries:**
+```bash
+curl -s https://api.github.com/repos/pinchtab/pinchtab/releases/v0.7.0 | jq '.assets[].name'
+# Should output: pinchtab-darwin-arm64, pinchtab-darwin-x64, etc.
+```
+
### 2. npm publish
Depends on: `release` job (waits for goreleaser to finish)
@@ -89,17 +98,22 @@ Depends on: `release` job (waits for goreleaser to finish)
- Syncs version from tag (v0.7.0 → 0.7.0)
- Builds TypeScript (`npm run build`)
- Publishes to npm registry
-- Postinstall script will download binaries from GitHub Releases
+- Users get postinstall script that downloads binaries from GitHub Releases
-**Key point:** Users who `npm install pinchtab` will:
-```bash
-1. Download npm package
-2. Run postinstall script
-3. Postinstall fetches binary from GitHub releases
-4. Verifies checksum (SHA256)
-5. Makes executable
+**User flow on `npm install pinchtab`:**
+```
+1. npm downloads @pinchtab/cli package
+2. Runs postinstall script
+3. Script detects OS/arch (darwin-arm64, linux-x64, etc.)
+4. Downloads binary from GitHub release
+5. Verifies SHA256 checksum
+6. Stores in ~/.pinchtab/bin/0.7.0/pinchtab-<os>-<arch>
+7. Makes executable
+8. If ANY STEP fails → npm install fails (exit 1)
```
+**⚠️ REQUIRES:** Goreleaser must have successfully uploaded binaries to GitHub release. The npm postinstall will verify this and fail hard if binaries are missing.
+
### 3. Docker
Independent job. Pushes to Docker Hub if configured.
diff --git a/npm/README.md b/npm/README.md
index d88752f2..a81f9747 100644
--- a/npm/README.md
+++ b/npm/README.md
@@ -14,7 +14,17 @@ or globally:
npm install -g pinchtab
```
-This downloads the Pinchtab binary for your platform (macOS, Linux, Windows) on install.
+On install, the postinstall script automatically:
+1. Detects your OS and CPU architecture
+2. Downloads the precompiled Pinchtab binary from GitHub Releases
+3. Verifies integrity (SHA256 checksum)
+4. Stores in `~/.pinchtab/bin/<version>/` (version-specific to avoid conflicts)
+5. Makes it executable
+
+**Requirements:**
+- Internet connection on first install
+- Node.js 16+
+- macOS, Linux, or Windows
### Proxy Support
@@ -134,8 +144,22 @@ await pinch.start(binaryPath);
## Troubleshooting
-**Binary not found after install:**
+**Binary not found or "file not found" error:**
+
+Check if the release has binaries:
+```bash
+# Should show pinchtab-darwin-arm64, pinchtab-linux-x64, etc.
+curl -s https://api.github.com/repos/pinchtab/pinchtab/releases/latest | jq '.assets[].name'
+```
+
+If no binaries (only Docker images), rebuild with a newer release:
+```bash
+npm rebuild pinchtab
+```
+
+Or use a custom binary:
```bash
+export PINCHTAB_BINARY_PATH=/path/to/pinchtab
npm rebuild pinchtab
```
diff --git a/npm/bin/pinchtab b/npm/bin/pinchtab
index 57ec7a68..9db911eb 100755
--- a/npm/bin/pinchtab
+++ b/npm/bin/pinchtab
@@ -20,12 +20,26 @@ function getBinaryName() {
throw new Error(`Unsupported platform: ${platform}`);
}
+function getVersion() {
+ const pkgPath = path.join(__dirname, '..', 'package.json');
+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+ return pkg.version;
+}
+
function getBinaryPath() {
- // Allow override via environment variable
+ // Allow override via environment variable (for Docker, custom builds)
if (process.env.PINCHTAB_BINARY_PATH) {
return process.env.PINCHTAB_BINARY_PATH;
}
+ // Try version-specific path first: ~/.pinchtab/bin/0.7.0/pinchtab-darwin-arm64
+ const version = getVersion();
+ const versionedPath = path.join(os.homedir(), '.pinchtab', 'bin', version, getBinaryName());
+ if (fs.existsSync(versionedPath)) {
+ return versionedPath;
+ }
+
+ // Fallback to version-less for backwards compat
return path.join(os.homedir(), '.pinchtab', 'bin', getBinaryName());
}
diff --git a/npm/scripts/postinstall.js b/npm/scripts/postinstall.js
index 3bb6193d..f662f855 100644
--- a/npm/scripts/postinstall.js
+++ b/npm/scripts/postinstall.js
@@ -128,7 +128,9 @@ function verifySHA256(filePath, expectedHash) {
async function downloadBinary(platform, version) {
const binaryName = getBinaryName(platform);
- const binaryPath = getBinaryPath(binaryName);
+ const binDir = getBinDir();
+ const versionDir = path.join(binDir, version);
+ const binaryPath = path.join(versionDir, binaryName);
// Skip if already exists
if (fs.existsSync(binaryPath)) {
@@ -143,17 +145,17 @@ async function downloadBinary(platform, version) {
if (!checksums.has(binaryName)) {
throw new Error(
`Binary not found in checksums: ${binaryName}\n` +
- `Available: ${Array.from(checksums.keys()).join(', ')}`
+ `Available: ${Array.from(checksums.keys()).join(', ')}\n` +
+ `\nMake sure v${version} release has binaries compiled (not just Docker images).`
);
}
const expectedHash = checksums.get(binaryName);
const downloadUrl = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/${binaryName}`;
- // Ensure directory exists (unless using custom PINCHTAB_BINARY_PATH)
- const binDir = path.dirname(binaryPath);
- if (!fs.existsSync(binDir)) {
- fs.mkdirSync(binDir, { recursive: true });
+ // Ensure version-specific directory exists
+ if (!fs.existsSync(versionDir)) {
+ fs.mkdirSync(versionDir, { recursive: true });
}
// Download binary
@@ -205,7 +207,31 @@ async function downloadBinary(platform, version) {
try {
const platform = detectPlatform();
const version = getVersion();
- await downloadBinary(platform, version);
+
+ // Ensure binary was successfully downloaded
+ // (If PINCHTAB_BINARY_PATH is set, skip download but trust the binary exists)
+ if (!process.env.PINCHTAB_BINARY_PATH) {
+ const binaryPath = getBinaryPath(getBinaryName(platform));
+ const binDir = path.dirname(binaryPath);
+
+ // Create version-specific directory
+ const versionDir = path.join(binDir, version);
+ if (!fs.existsSync(versionDir)) {
+ fs.mkdirSync(versionDir, { recursive: true });
+ }
+
+ await downloadBinary(platform, version);
+
+ // Verify binary exists after download
+ const finalPath = path.join(versionDir, getBinaryName(platform));
+ if (!fs.existsSync(finalPath)) {
+ throw new Error(
+ `Binary was not successfully downloaded to ${finalPath}\n` +
+ `This usually means the GitHub release doesn't have the binary for your platform.`
+ );
+ }
+ }
+
console.log('✓ Pinchtab setup complete');
process.exit(0);
} catch (err) {
@@ -218,6 +244,9 @@ async function downloadBinary(platform, version) {
if (process.env.HTTPS_PROXY || process.env.HTTP_PROXY) {
console.error(' • Check proxy settings (HTTPS_PROXY / HTTP_PROXY)');
}
+ console.error('\nFor Docker or custom binaries:');
+ console.error(' export PINCHTAB_BINARY_PATH=/path/to/pinchtab');
+ console.error(' npm rebuild pinchtab');
process.exit(1);
}
})();
diff --git a/npm/src/download.ts b/npm/src/download.ts
index a005ed82..3d1efd32 100644
--- a/npm/src/download.ts
+++ b/npm/src/download.ts
@@ -91,7 +91,7 @@ function verifySHA256(filePath: string, expectedHash: string): boolean {
async function downloadBinary(platform: any, version: string): Promise<void> {
const binaryName = getBinaryName(platform);
- const binaryPath = getBinaryPath(binaryName);
+ const binaryPath = getBinaryPath(binaryName, version);
// Skip if already exists
if (fs.existsSync(binaryPath)) {
@@ -170,5 +170,5 @@ export async function ensureBinary(): Promise<string> {
await downloadBinary(platform, version);
const binaryName = getBinaryName(platform);
- return getBinaryPath(binaryName);
+ return getBinaryPath(binaryName, version);
}
diff --git a/npm/src/index.ts b/npm/src/index.ts
index 0111039d..0d98ebfc 100644
--- a/npm/src/index.ts
+++ b/npm/src/index.ts
@@ -141,7 +141,10 @@ export class Pinchtab {
private async getBinaryPathInternal(): Promise<string> {
const platform = detectPlatform();
const binaryName = getBinaryName(platform);
- const binaryPath = getBinaryPath(binaryName);
+
+ // Try version-specific path first
+ const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
+ const binaryPath = getBinaryPath(binaryName, pkg.version);
if (!fs.existsSync(binaryPath)) {
throw new Error(
diff --git a/npm/src/platform.ts b/npm/src/platform.ts
index e8269675..2c8ac172 100644
--- a/npm/src/platform.ts
+++ b/npm/src/platform.ts
@@ -38,11 +38,18 @@ export function getBinDir(): string {
return path.join(process.env.HOME || process.env.USERPROFILE || '', '.pinchtab', 'bin');
}
-export function getBinaryPath(binaryName: string): string {
- // Allow override via environment variable
+export function getBinaryPath(binaryName: string, version?: string): string {
+ // Allow override via environment variable (for Docker, custom builds, etc.)
if (process.env.PINCHTAB_BINARY_PATH) {
return process.env.PINCHTAB_BINARY_PATH;
}
+ // Version-specific path: ~/.pinchtab/bin/0.7.0/pinchtab-darwin-arm64
+ // This allows multiple versions to coexist and prevents silent overwrites
+ if (version) {
+ return path.join(getBinDir(), version, binaryName);
+ }
+
+ // Fallback to version-less for backwards compat
return path.join(getBinDir(), binaryName);
}