High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: production hardening — proxy, dedup logic, env vars, .npmignore
Mario1dd17e0485f4
diff --git a/npm/.npmignore b/npm/.npmignorenew file mode 100644index 00000000..d7f8413c--- /dev/null+++ b/npm/.npmignore@@ -0,0 +1,31 @@+# Source files+src/+tests/+*.ts+tsconfig.json++# Build artifacts+dist/+*.map++# Dev dependencies+node_modules/+package-lock.json+.git+.github+.gitignore+.npmignore++# Docs+*.md+!LICENSE++# Config+.gitignore+.env*++# IDE+.vscode/+.idea/+*.swp+*.swodiff --git a/npm/README.md b/npm/README.mdindex 6ff362ca..d88752f2 100644--- a/npm/README.md+++ b/npm/README.md@@ -1,6 +1,6 @@-# Pinchtab+# Pinchtab npm-Browser control API for AI agents.+Browser control API for AI agents — Node.js SDK + CLI wrapper.## Installation@@ -8,8 +8,25 @@ Browser control API for AI agents.npm install pinchtab```+or globally:++```bash+npm install -g pinchtab+```+This downloads the Pinchtab binary for your platform (macOS, Linux, Windows) on install.+### Proxy Support++Works with corporate proxies. Set standard environment variables:++```bash+npm install --https-proxy https://proxy.company.com:8080 pinchtab+# or+export HTTPS_PROXY=https://user:[email protected]:8080+npm install pinchtab+```+## Quick Start### Start the server@@ -99,6 +116,44 @@ pinchtab --versionpinchtab --help```+### Using a Custom Binary++For Docker, development, or other custom setups:++```bash+PINCHTAB_BINARY_PATH=/path/to/pinchtab npx pinchtab serve+```++Or in code:++```typescript+const pinch = new Pinchtab();+const binaryPath = '/custom/path/to/pinchtab';+await pinch.start(binaryPath);+```++## Troubleshooting++**Binary not found after install:**+```bash+npm rebuild pinchtab+```++**Behind a proxy:**+```bash+export HTTPS_PROXY=https://proxy:port+npm rebuild pinchtab+```++**Using a pre-built binary:**+```bash+PINCHTAB_BINARY_PATH=/path/to/binary npm rebuild pinchtab+```++## Future: OptionalDependencies Pattern (v1.0)++In a future major version, we plan to migrate to the modern `optionalDependencies` pattern used by esbuild, Biome, Turbo, etc. This will split platform-specific binaries into separate npm packages (@pinchtab/cli-darwin-arm64, etc.) for zero postinstall network overhead and perfect offline support.+## LicenseMITdiff --git a/npm/bin/pinchtab b/npm/bin/pinchtabindex 3ad5efe8..57ec7a68 100755--- a/npm/bin/pinchtab+++ b/npm/bin/pinchtab@@ -3,6 +3,7 @@const path = require('path');const { spawn } = require('child_process');const os = require('os');+const fs = require('fs');function getBinaryName() {const platform = process.platform;@@ -19,7 +20,27 @@ function getBinaryName() {throw new Error(`Unsupported platform: ${platform}`);}-const binaryPath = path.join(os.homedir(), '.pinchtab', 'bin', getBinaryName());+function getBinaryPath() {+ // Allow override via environment variable+ if (process.env.PINCHTAB_BINARY_PATH) {+ return process.env.PINCHTAB_BINARY_PATH;+ }++ return path.join(os.homedir(), '.pinchtab', 'bin', getBinaryName());+}++const binaryPath = getBinaryPath();++// Check binary exists+if (!fs.existsSync(binaryPath)) {+ console.error('❌ Pinchtab binary not found at:');+ console.error(` ${binaryPath}`);+ console.error('\nTo fix this, run:');+ console.error(' npm rebuild pinchtab');+ console.error('\nOr set a custom binary path:');+ console.error(` PINCHTAB_BINARY_PATH=/path/to/binary pinchtab`);+ process.exit(1);+}const proc = spawn(binaryPath, process.argv.slice(2), {stdio: 'inherit',diff --git a/npm/scripts/postinstall.js b/npm/scripts/postinstall.jsindex e21c9822..3bb6193d 100644--- a/npm/scripts/postinstall.js+++ b/npm/scripts/postinstall.js@@ -42,13 +42,35 @@ function getBinaryName(platform) {return `pinchtab-${os}-${archName}`;}-function getBinDir() {- return path.join(os.homedir(), '.pinchtab', 'bin');+function getBinaryPath(binaryName) {+ // Allow override via environment variable (useful for Docker, dev, containers)+ if (process.env.PINCHTAB_BINARY_PATH) {+ return process.env.PINCHTAB_BINARY_PATH;+ }++ return path.join(os.homedir(), '.pinchtab', 'bin', binaryName);}function fetchUrl(url) {return new Promise((resolve, reject) => {- https.get(url, (response) => {+ const httpsOptions = new URL(url);++ // Proxy support for corporate environments+ if (process.env.HTTPS_PROXY || process.env.HTTP_PROXY) {+ const proxyUrl = process.env.HTTPS_PROXY || process.env.HTTP_PROXY;+ try {+ const proxy = new URL(proxyUrl);+ httpsOptions.agent = new https.Agent({+ host: proxy.hostname,+ port: proxy.port,+ keepAlive: true,+ });+ } catch (err) {+ console.warn(`Warning: Invalid proxy URL ${proxyUrl}, ignoring`);+ }+ }++ https.get(url, httpsOptions, (response) => {if (response.statusCode === 404) {reject(new Error(`Not found: ${url}`));return;@@ -106,8 +128,7 @@ function verifySHA256(filePath, expectedHash) {async function downloadBinary(platform, version) {const binaryName = getBinaryName(platform);- const binDir = getBinDir();- const binaryPath = path.join(binDir, binaryName);+ const binaryPath = getBinaryPath(binaryName);// Skip if already existsif (fs.existsSync(binaryPath)) {@@ -129,7 +150,8 @@ async function downloadBinary(platform, version) {const expectedHash = checksums.get(binaryName);const downloadUrl = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/${binaryName}`;- // Ensure directory exists+ // Ensure directory exists (unless using custom PINCHTAB_BINARY_PATH)+ const binDir = path.dirname(binaryPath);if (!fs.existsSync(binDir)) {fs.mkdirSync(binDir, { recursive: true });}@@ -193,6 +215,9 @@ async function downloadBinary(platform, version) {console.error(' • Check your internet connection');console.error(' • Verify the release exists: https://github.com/pinchtab/pinchtab/releases');console.error(' • Try again: npm rebuild pinchtab');+ if (process.env.HTTPS_PROXY || process.env.HTTP_PROXY) {+ console.error(' • Check proxy settings (HTTPS_PROXY / HTTP_PROXY)');+ }process.exit(1);}})();diff --git a/npm/src/download.ts b/npm/src/download.tsindex b74b5fbd..a005ed82 100644--- a/npm/src/download.ts+++ b/npm/src/download.ts@@ -2,6 +2,7 @@ import * as fs from 'fs';import * as path from 'path';import * as https from 'https';import * as crypto from 'crypto';+import { detectPlatform, getBinaryName, getBinaryPath } from './platform';const GITHUB_REPO = 'pinchtab/pinchtab';@@ -12,46 +13,27 @@ function getVersion(): string {return pkg.version;}-interface Platform {- os: 'darwin' | 'linux' | 'windows';- arch: 'x64' | 'arm64';-}--function detectPlatform(): Platform {- const platform = process.platform as any;- const arch = process.arch === 'arm64' ? 'arm64' : 'x64';-- const osMap: Record<string, 'darwin' | 'linux' | 'windows'> = {- darwin: 'darwin',- linux: 'linux',- win32: 'windows',- };-- const os = osMap[platform];- if (!os) {- throw new Error(`Unsupported platform: ${platform}`);- }-- return { os, arch };-}--function getBinaryName(platform: Platform): string {- const { os, arch } = platform;- const archName = arch === 'arm64' ? 'arm64' : 'x64';-- if (os === 'windows') {- return `pinchtab-${os}-${archName}.exe`;- }- return `pinchtab-${os}-${archName}`;-}--function getBinDir(): string {- return path.join(process.env.HOME || process.env.USERPROFILE || '', '.pinchtab', 'bin');-}-function fetchUrl(url: string): Promise<Buffer> {return new Promise((resolve, reject) => {- https.get(url, (response) => {+ let agent: https.Agent | undefined;++ // Proxy support for corporate environments+ const proxyUrl = process.env.HTTPS_PROXY || process.env.HTTP_PROXY;+ if (proxyUrl) {+ try {+ const proxy = new URL(proxyUrl);+ const proxyPort = proxy.port ? parseInt(proxy.port, 10) : 8080;+ agent = new https.Agent({+ host: proxy.hostname,+ port: proxyPort,+ keepAlive: true,+ });+ } catch (err) {+ console.warn(`Warning: Invalid proxy URL ${proxyUrl}, ignoring`);+ }+ }++ const request = https.get(url, agent ? { agent } : {}, (response) => {if (response.statusCode === 404) {reject(new Error(`Not found: ${url}`));return;@@ -66,7 +48,9 @@ function fetchUrl(url: string): Promise<Buffer> {response.on('data', (chunk) => chunks.push(chunk));response.on('end', () => resolve(Buffer.concat(chunks)));response.on('error', reject);- }).on('error', reject);+ });++ request.on('error', reject);});}@@ -105,10 +89,9 @@ function verifySHA256(filePath: string, expectedHash: string): boolean {return actualHash.toLowerCase() === expectedHash.toLowerCase();}-async function downloadBinary(platform: Platform, version: string): Promise<void> {+async function downloadBinary(platform: any, version: string): Promise<void> {const binaryName = getBinaryName(platform);- const binDir = getBinDir();- const binaryPath = path.join(binDir, binaryName);+ const binaryPath = getBinaryPath(binaryName);// Skip if already existsif (fs.existsSync(binaryPath)) {@@ -130,7 +113,8 @@ async function downloadBinary(platform: Platform, version: string): Promise<voidconst expectedHash = checksums.get(binaryName)!;const downloadUrl = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/${binaryName}`;- // Ensure directory exists+ // Ensure directory exists (unless using custom PINCHTAB_BINARY_PATH)+ const binDir = path.dirname(binaryPath);if (!fs.existsSync(binDir)) {fs.mkdirSync(binDir, { recursive: true });}@@ -185,7 +169,6 @@ export async function ensureBinary(): Promise<string> {await downloadBinary(platform, version);- const binDir = getBinDir();const binaryName = getBinaryName(platform);- return path.join(binDir, binaryName);+ return getBinaryPath(binaryName);}diff --git a/npm/src/index.ts b/npm/src/index.tsindex 763c1d14..0111039d 100644--- a/npm/src/index.ts+++ b/npm/src/index.ts@@ -1,6 +1,7 @@import { spawn, ChildProcess } from 'child_process';import * as path from 'path';import * as fs from 'fs';+import { detectPlatform, getBinaryName, getBinaryPath } from './platform';import {SnapshotParams,SnapshotResponse,@@ -13,6 +14,7 @@ import {} from './types';export * from './types';+export * from './platform';export class Pinchtab {private baseUrl: string;@@ -36,7 +38,7 @@ export class Pinchtab {}if (!binaryPath) {- binaryPath = await this.getBinaryPath();+ binaryPath = await this.getBinaryPathInternal();}this.binaryPath = binaryPath;@@ -136,38 +138,20 @@ export class Pinchtab {/*** Get the path to the Pinchtab binary*/- private async getBinaryPath(): Promise<string> {- const homedir = require('os').homedir();- const defaultPath = path.join(homedir, '.pinchtab', 'bin', this.getBinaryName());-- if (fs.existsSync(defaultPath)) {- return defaultPath;- }-- // Try relative to package- const relativePath = path.join(__dirname, '..', 'bin', this.getBinaryName());- if (fs.existsSync(relativePath)) {- return relativePath;- }-- throw new Error(- `Pinchtab binary not found. Please run: npm run postinstall or ensure the binary is in ~/.pinchtab/bin/`- );- }-- private getBinaryName(): string {- const platform = process.platform;- const arch = process.arch === 'arm64' ? 'arm64' : 'x64';-- if (platform === 'darwin') {- return `pinchtab-darwin-${arch}`;- } else if (platform === 'linux') {- return `pinchtab-linux-${arch}`;- } else if (platform === 'win32') {- return `pinchtab-windows-${arch}.exe`;+ private async getBinaryPathInternal(): Promise<string> {+ const platform = detectPlatform();+ const binaryName = getBinaryName(platform);+ const binaryPath = getBinaryPath(binaryName);++ if (!fs.existsSync(binaryPath)) {+ throw new Error(+ `Pinchtab binary not found at ${binaryPath}.\n` ++ `Please run: npm rebuild pinchtab\n` ++ `Or set PINCHTAB_BINARY_PATH=/path/to/binary`+ );}- throw new Error(`Unsupported platform: ${platform}`);+ return binaryPath;}}diff --git a/npm/src/platform.ts b/npm/src/platform.tsnew file mode 100644index 00000000..e8269675--- /dev/null+++ b/npm/src/platform.ts@@ -0,0 +1,48 @@+import * as path from 'path';+import * as os from 'os';++export interface Platform {+ os: 'darwin' | 'linux' | 'windows';+ arch: 'x64' | 'arm64';+}++export function detectPlatform(): Platform {+ const platform = process.platform as any;+ const arch = process.arch === 'arm64' ? 'arm64' : 'x64';++ const osMap: Record<string, 'darwin' | 'linux' | 'windows'> = {+ darwin: 'darwin',+ linux: 'linux',+ win32: 'windows',+ };++ const os_name = osMap[platform];+ if (!os_name) {+ throw new Error(`Unsupported platform: ${platform}`);+ }++ return { os: os_name, arch };+}++export function getBinaryName(platform: Platform): string {+ const { os, arch } = platform;+ const archName = arch === 'arm64' ? 'arm64' : 'x64';++ if (os === 'windows') {+ return `pinchtab-${os}-${archName}.exe`;+ }+ return `pinchtab-${os}-${archName}`;+}++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+ if (process.env.PINCHTAB_BINARY_PATH) {+ return process.env.PINCHTAB_BINARY_PATH;+ }++ return path.join(getBinDir(), binaryName);+}