Skip to content

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/.npmignore
new file mode 100644
index 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
+*.swo
diff --git a/npm/README.md b/npm/README.md
index 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 --version
pinchtab --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.
+
## License
MIT
diff --git a/npm/bin/pinchtab b/npm/bin/pinchtab
index 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.js
index 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 exists
if (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.ts
index 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 exists
if (fs.existsSync(binaryPath)) {
@@ -130,7 +113,8 @@ async function downloadBinary(platform: Platform, version: string): Promise<void
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 });
}
@@ -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.ts
index 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.ts
new file mode 100644
index 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);
+}