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/.gitignoreindex 70df2354..14fada16 100644--- a/.gitignore+++ b/.gitignore@@ -11,7 +11,6 @@ dist/# npm packagenpm/node_modules/-npm/package-lock.json# OpenClaw workspace files (should never be committed).openclaw/diff --git a/RELEASE.md b/RELEASE.mdindex 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 npmTriggered 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 publishDepends 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. DockerIndependent job. Pushes to Docker Hub if configured.diff --git a/npm/README.md b/npm/README.mdindex 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/pinchtabnpm rebuild pinchtab```diff --git a/npm/bin/pinchtab b/npm/bin/pinchtabindex 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 compatreturn path.join(os.homedir(), '.pinchtab', 'bin', getBinaryName());}diff --git a/npm/scripts/postinstall.js b/npm/scripts/postinstall.jsindex 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 existsif (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.tsindex 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 existsif (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.tsindex 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.tsindex 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 compatreturn path.join(getBinDir(), binaryName);}