@piperace/cli 0.3.5 → 0.3.7

package/README.md

@@ -1,6 +1,10 @@
-# Piperace NPM Wrapper
+# Piperace
 
-NPM wrapper around the Piperace Go binaries.
+Expose your localhost to the internet in seconds — a self-hosted alternative to ngrok. Share a local server behind NAT or a firewall with a stable public URL and real TLS, using a single command.
+
+🌐 **[piperace.com](https://piperace.com)**
+
+![Expose localhost with a single command](https://piperace.com/images/piperace_noqr.jpg)
 
 ## Install
 
@@ -11,36 +15,36 @@ npm install -g @piperace/cli
 ## Usage
 
 ```bash
+piperace http 3000 -d myapp     # expose localhost:3000 → https://myapp.piperace.fun
+piperace login                  # keep the same subdomain + a permanent token
+piperace-gui                    # launch the desktop app
 piperace --version
-piperace http 3000 -d myapp
-piperace login
-piperace-gui
 ```
 
-## How it works
+Works out of the box — no account required. When a tunnel starts, a QR code is printed so you can open it on your phone. Run `piperace login` to keep a stable subdomain and a permanent token.
 
-On `npm install`, the `postinstall` script detects your platform/architecture and either:
+![Scan the QR code to open the tunnel on your phone](https://piperace.com/images/piperace_qr.png)
 
-1. Copies the matching binary from `../piperace_client/dist/` (when installed inside the Piperace monorepo), or
-2. Downloads it from `https://app.piperace.com/downloads/v<VERSION>/`.
+## Supported platforms
 
-The downloaded binary is stored in `binaries/` inside the package and is launched by the `bin/piperace` Node.js wrapper.
+Both the CLI and the desktop GUI are available for:
 
-## Supported platforms
+| OS      | Architecture           |
+|---------|------------------------|
+| macOS   | Apple Silicon (arm64)  |
+| macOS   | Intel (x64)            |
+| Linux   | arm64                  |
+| Linux   | x64                    |
+| Windows | x64                    |
+| Windows | ia32 (CLI only)        |
 
-| OS       | Arch  | Binary                         |
-|----------|-------|--------------------------------|
-| macOS    | arm64 | `piperace-darwin-arm64`        |
-| macOS    | x64   | `piperace-darwin-amd64`        |
-| Linux    | arm64 | `piperace-linux-arm64`         |
-| Linux    | x64   | `piperace-linux-amd64`         |
-| Windows  | x64   | `piperace-client.exe`          |
-| Windows  | ia32  | `piperace-client-386.exe`      |
+The desktop app (`piperace-gui`) is set up automatically the first time you launch it.
 
 ## Environment variables
 
-- `PIPERACE_BINARY_PATH` — path to a manually downloaded binary to use instead of downloading.
-- `PIPERACE_DOWNLOAD_URL` — override the base download URL (default: `https://app.piperace.com/downloads`).
+- `PIPERACE_ENV` — `development` or `production` (selects the API/tunnel endpoints).
+- `PIPERACE_BINARY_PATH` — use a specific Piperace executable instead of the managed one.
+- `PIPERACE_DOWNLOAD_URL` — override the base URL Piperace uses to fetch its components (default: `https://piperace.com/downloads`).
 
 ## Programmatic API
 
@@ -48,18 +52,14 @@ The downloaded binary is stored in `binaries/` inside the package and is launche
 const piperace = require('@piperace/cli');
 
 await piperace.run(['http', '3000', '-d', 'myapp'], {
-  env: { PIPERACE_ENV: 'production' }
+  env: { PIPERACE_ENV: 'production' },
 });
 ```
 
-## Publishing
-
-```bash
-npm version patch
-npm publish --access public
-```
-
 ## macOS note
 
-On macOS the downloaded binary may be quarantined. The install script automatically runs `xattr -cr` to remove the quarantine attribute. For a cleaner experience, distribute a code-signed and notarized binary.
+If macOS shows an “unidentified developer” warning, Piperace clears the quarantine flag automatically on first run so the app can start.
+
+## License
 
+MIT

package/lib/index.js

@@ -18,6 +18,8 @@ const BINARY_MAP = {
   gui: {
     'darwin arm64': 'piperace-gui-darwin-arm64',
     'darwin x64':   'piperace-gui-darwin-amd64',
+    'linux arm64':  'piperace-gui-linux-arm64',
+    'linux x64':    'piperace-gui-linux-amd64',
     'win32 x64':    'piperace-gui.exe'
   }
 };
@@ -26,26 +28,61 @@ function platformKey() {
   return `${os.platform()} ${os.arch()}`;
 }
 
-function getBinaryPath(kind = 'cli') {
+function binaryPathFor(kind) {
   const name = kind === 'gui' ? 'piperace-gui' : 'piperace';
-  const binaryPath = path.join(BIN_DIR, name + (os.platform() === 'win32' ? '.exe' : ''));
+  return path.join(BIN_DIR, name + (os.platform() === 'win32' ? '.exe' : ''));
+}
 
-  if (!fs.existsSync(binaryPath)) {
-    const expectedSource = BINARY_MAP[kind]?.[platformKey()];
-    throw new Error(
-      `Piperace ${kind} binary not found at ${binaryPath}.\n` +
-      `Expected source binary: ${expectedSource || 'none for ' + platformKey()}\n` +
-      `Try running: npm run postinstall\n` +
-      `Or set PIPERACE_BINARY_PATH to the downloaded binary.`
-    );
+function binaryExists(binaryPath) {
+  try {
+    return fs.statSync(binaryPath).size > 1000;
+  } catch {
+    return false;
   }
+}
+
+function missingBinaryError(kind, binaryPath) {
+  const expectedSource = BINARY_MAP[kind]?.[platformKey()];
+  return new Error(
+    `Piperace ${kind} binary not found at ${binaryPath}.\n` +
+    `Expected source binary: ${expectedSource || 'none for ' + platformKey()}\n` +
+    `Try running: npm run postinstall\n` +
+    `Or set PIPERACE_BINARY_PATH to the downloaded binary.`
+  );
+}
 
+function getBinaryPath(kind = 'cli') {
+  const binaryPath = binaryPathFor(kind);
+  if (!binaryExists(binaryPath)) {
+    throw missingBinaryError(kind, binaryPath);
+  }
+  return binaryPath;
+}
+
+// Ensure the binary is present, downloading it on demand. The GUI binary is not
+// fetched during `npm install`, so its first launch lazily downloads it here.
+async function ensureBinaryPath(kind = 'cli') {
+  const binaryPath = binaryPathFor(kind);
+  if (binaryExists(binaryPath)) return binaryPath;
+
+  if (kind === 'gui') {
+    console.log('[piperace] First GUI launch — downloading the desktop binary (one-time)...');
+  }
+
+  // Reuse the installer's download/retry logic. The require.main guard in
+  // install.js keeps this from re-running the CLI install as a side effect.
+  const { installBinary } = require('../scripts/install.js');
+  await installBinary(kind);
+
+  if (!binaryExists(binaryPath)) {
+    throw missingBinaryError(kind, binaryPath);
+  }
   return binaryPath;
 }
 
-function run(args = [], options = {}) {
+async function run(args = [], options = {}) {
   const kind = options.gui ? 'gui' : 'cli';
-  const binaryPath = getBinaryPath(kind);
+  const binaryPath = await ensureBinaryPath(kind);
   const child = spawn(binaryPath, args, {
     stdio: options.stdio || 'inherit',
     env: { ...process.env, ...options.env },
@@ -71,6 +108,7 @@ function run(args = [], options = {}) {
 
 module.exports = {
   getBinaryPath,
+  ensureBinaryPath,
   run,
   platformKey
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@piperace/cli",
-  "version": "0.3.5",
-  "description": "Piperace — self-hosted ngrok alternative. NPM wrapper for the Go binary.",
+  "version": "0.3.7",
+  "description": "Piperace — expose your localhost to the internet in seconds. A self-hosted ngrok alternative.",
   "main": "lib/index.js",
   "bin": {
     "piperace": "bin/piperace",

package/scripts/install.js

@@ -5,13 +5,15 @@ const path = require('path');
 const https = require('https');
 const http = require('http');
 const os = require('os');
-const crypto = require('crypto');
 const { execSync } = require('child_process');
 
 const VERSION = require('../package.json').version;
 const ROOT = path.join(__dirname, '..');
 const BIN_DIR = path.join(ROOT, 'binaries');
 
+const DOWNLOAD_TIMEOUT_MS = 30000; // per-attempt socket timeout
+const DOWNLOAD_RETRIES = 2;        // extra attempts after the first
+
 // Map Node platform/arch to the binary names produced by the Go build.
 const BINARY_MAP = {
   cli: {
@@ -25,6 +27,8 @@ const BINARY_MAP = {
   gui: {
     'darwin arm64': 'piperace-gui-darwin-arm64',
     'darwin x64':   'piperace-gui-darwin-amd64',
+    'linux arm64':  'piperace-gui-linux-arm64',
+    'linux x64':    'piperace-gui-linux-amd64',
     'win32 x64':    'piperace-gui.exe'
   }
 };
@@ -65,32 +69,76 @@ function findLocalBinary(sourceName) {
   return null;
 }
 
-function downloadFile(url, dest) {
+// Download a single file with a hard per-attempt timeout so a stalled origin
+// connection can never hang the install indefinitely.
+function downloadFile(url, dest, { timeout = DOWNLOAD_TIMEOUT_MS, redirects = 5 } = {}) {
   return new Promise((resolve, reject) => {
     const client = url.startsWith('https:') ? https : http;
     const file = fs.createWriteStream(dest);
+    let settled = false;
 
-    client.get(url, (res) => {
+    const cleanup = () => {
+      file.destroy();
+      try { fs.unlinkSync(dest); } catch {}
+    };
+    const fail = (err) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(err);
+    };
+
+    const req = client.get(url, (res) => {
       if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        file.destroy();
-        fs.unlinkSync(dest);
-        return downloadFile(res.headers.location, dest).then(resolve).catch(reject);
+        settled = true; // hand off to the redirect target
+        cleanup();
+        res.resume();
+        if (redirects <= 0) {
+          return reject(new Error(`too many redirects from ${url}`));
+        }
+        return downloadFile(res.headers.location, dest, { timeout, redirects: redirects - 1 })
+          .then(resolve).catch(reject);
       }
       if (res.statusCode !== 200) {
-        file.destroy();
-        fs.unlinkSync(dest);
-        return reject(new Error(`HTTP ${res.statusCode} from ${url}`));
+        res.resume();
+        return fail(new Error(`HTTP ${res.statusCode} from ${url}`));
       }
 
+      res.on('error', fail);
       res.pipe(file);
-      file.on('finish', () => file.close(resolve));
-    }).on('error', (err) => {
-      try { fs.unlinkSync(dest); } catch {}
-      reject(err);
+      file.on('finish', () => {
+        if (settled) return;
+        settled = true;
+        file.close((err) => (err ? reject(err) : resolve()));
+      });
+    });
+
+    // Fires on connection-establish AND idle-read stalls.
+    req.setTimeout(timeout, () => {
+      req.destroy(new Error(`download timed out after ${timeout}ms: ${url}`));
     });
+    req.on('error', fail);
+    file.on('error', fail);
   });
 }
 
+async function downloadWithRetry(url, dest, { timeout = DOWNLOAD_TIMEOUT_MS, retries = DOWNLOAD_RETRIES } = {}) {
+  let lastErr;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (attempt > 0) {
+      const delay = 1000 * attempt;
+      console.warn(`[piperace] download failed (${lastErr.message}); retry ${attempt}/${retries} in ${delay}ms...`);
+      await new Promise((r) => setTimeout(r, delay));
+    }
+    try {
+      return await downloadFile(url, dest, { timeout });
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  throw lastErr;
+}
+
 async function installBinary(kind = 'cli') {
   const sourceName = binaryName(kind);
   if (!sourceName) {
@@ -107,7 +155,6 @@ async function installBinary(kind = 'cli') {
     try {
       fs.chmodSync(target, 0o755);
     } catch {}
-    console.log(`[piperace] ${kind} binary already installed.`);
     return;
   }
 
@@ -122,12 +169,12 @@ async function installBinary(kind = 'cli') {
   }
 
   // 2. Fall back to downloading from the public CDN.
-  const baseUrl = process.env.PIPERACE_DOWNLOAD_URL || 'https://app.piperace.com/downloads';
+  const baseUrl = process.env.PIPERACE_DOWNLOAD_URL || 'https://piperace.com/downloads';
   const url = `${baseUrl}/v${VERSION}/${sourceName}`;
   console.log(`[piperace] Downloading ${kind} binary from ${url}`);
 
   try {
-    await downloadFile(url, target);
+    await downloadWithRetry(url, target);
     fs.chmodSync(target, 0o755);
     removeQuarantine(target);
     console.log(`[piperace] ${kind} binary installed successfully.`);
@@ -135,7 +182,8 @@ async function installBinary(kind = 'cli') {
     try { fs.unlinkSync(target); } catch {}
     console.error(`[piperace] Failed to download ${kind} binary: ${err.message}`);
     console.error(`[piperace] You can manually download ${sourceName} from ${baseUrl} and place it at ${target}`);
-    // Do not fail npm install; the launcher will print a helpful message later.
+    // Do not fail npm install; the launcher will retry lazily and print a
+    // helpful message if the binary is still missing at run time.
   }
 }
 
@@ -148,7 +196,20 @@ function removeQuarantine(filePath) {
   }
 }
 
-(async () => {
-  await installBinary('cli');
-  await installBinary('gui');
-})();
+module.exports = {
+  installBinary,
+  binaryName,
+  finalBinaryPath,
+  platformKey,
+  BINARY_MAP
+};
+
+// Only the lightweight CLI binary is fetched at install time. The much larger
+// GUI binary is downloaded lazily on the first `piperace-gui` run (see
+// lib/index.js), so `npm install` stays fast for the common CLI-only case.
+if (require.main === module) {
+  // Never let a failure here break `npm install`; the launcher retries lazily.
+  Promise.resolve()
+    .then(() => installBinary('cli'))
+    .catch((err) => console.error(`[piperace] install skipped: ${err.message}`));
+}