pi-bridge 0.1.1

package/src/local/http-client.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+/**
+ * Synchronous HTTP GET to the local file server.
+ *
+ * The child process writes a JSON envelope to stdout:
+ *   { ok: true,  body: "..." }
+ *   { ok: false, status: 403, body: "..." }
+ *
+ * This keeps ALL output on stdout so execFileSync can capture it with
+ * stdio:'pipe', preventing HTTP error text from leaking into the terminal.
+ *
+ * @param {number} port    - Server port (127.0.0.1)
+ * @param {string} token   - Auth token for x-token header
+ * @param {string} urlPath - URL path + query string, e.g. '/list?path=%2Froot'
+ * @returns {string}       - Response body as a UTF-8 string
+ * @throws                 - On HTTP errors or non-2xx status codes
+ */
+const MAX_RETRIES = 5;
+const RETRY_DELAY_MS = 600;
+
+/**
+ * Run execFileSync with retries when the tunnel is reconnecting after sleep/wake.
+ * ECONNREFUSED (status 0, body contains "ECONNREFUSED") means the tunnel is not
+ * yet back up — wait and retry.
+ */
+function defaultSleep() {
+  try {
+    execFileSync(process.execPath, ['-e', `setTimeout(()=>{},${RETRY_DELAY_MS})`], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch (_) {}
+}
+
+/**
+ * @param {() => string} fn    - Returns a JSON envelope string
+ * @param {() => void}  sleep  - Injected sleep (defaults to real delay; override in tests)
+ */
+function withRetry(fn, sleep) {
+  sleep = sleep || defaultSleep;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    const raw = fn();
+    const result = JSON.parse(raw);
+    const isConnRefused = !result.ok && result.status === 0 &&
+      typeof result.body === 'string' && result.body.includes('ECONNREFUSED');
+    if (!isConnRefused || attempt === MAX_RETRIES) return raw;
+    sleep();
+  }
+}
+
+function httpGet(port, token, urlPath) {
+  const script = `
+const http = require('http');
+let body = '';
+let statusCode = 0;
+const req = http.get(
+  { hostname:'127.0.0.1', port:${JSON.stringify(port)}, path:${JSON.stringify(urlPath)},
+    headers:{'x-token':${JSON.stringify(token)}} },
+  (res) => {
+    statusCode = res.statusCode;
+    res.setEncoding('utf8');
+    res.on('data', (d) => { body += d; });
+    res.on('end', () => {
+      process.stdout.write(JSON.stringify({ ok: statusCode >= 200 && statusCode < 300, status: statusCode, body }));
+    });
+  }
+);
+req.on('error', (e) => {
+  process.stdout.write(JSON.stringify({ ok: false, status: 0, body: e.message }));
+});
+`;
+  const raw = withRetry(() => execFileSync(process.execPath, ['-e', script], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }));
+  const result = JSON.parse(raw);
+  if (!result.ok) {
+    const err = new Error('HTTP ' + result.status + ': ' + result.body);
+    err.statusCode = result.status;
+    throw err;
+  }
+  return result.body;
+}
+
+/**
+ * Synchronous HTTP POST to the local file server.
+ *
+ * @param {number} port    - Server port (127.0.0.1)
+ * @param {string} token   - Auth token for x-token header
+ * @param {string} urlPath - URL path + query string
+ * @param {string} body    - Request body (UTF-8 string)
+ * @returns {string}       - Response body
+ * @throws                 - On HTTP errors or non-2xx status codes
+ */
+function httpPost(port, token, urlPath, body) {
+  const script = `
+const http = require('http');
+const body = ${JSON.stringify(body)};
+const bodyBuf = Buffer.from(body, 'utf8');
+let resBody = '';
+let statusCode = 0;
+const req = http.request(
+  { method:'POST', hostname:'127.0.0.1', port:${JSON.stringify(port)}, path:${JSON.stringify(urlPath)},
+    headers:{'x-token':${JSON.stringify(token)},'Content-Type':'text/plain; charset=utf-8','Content-Length':bodyBuf.length} },
+  (res) => {
+    statusCode = res.statusCode;
+    res.setEncoding('utf8');
+    res.on('data', (d) => { resBody += d; });
+    res.on('end', () => {
+      process.stdout.write(JSON.stringify({ ok: statusCode >= 200 && statusCode < 300, status: statusCode, body: resBody }));
+    });
+  }
+);
+req.on('error', (e) => {
+  process.stdout.write(JSON.stringify({ ok: false, status: 0, body: e.message }));
+});
+req.write(bodyBuf);
+req.end();
+`;
+  const raw = withRetry(() => execFileSync(process.execPath, ['-e', script], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }));
+  const result = JSON.parse(raw);
+  if (!result.ok) {
+    const err = new Error('HTTP ' + result.status + ': ' + result.body);
+    err.statusCode = result.status;
+    throw err;
+  }
+  return result.body;
+}
+
+module.exports = { httpGet, httpPost, _withRetry: withRetry, _MAX_RETRIES: MAX_RETRIES };

package/src/local/path-mapper.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * Convert a remote POSIX path to a fake local path under fakeRoot.
+ * Handles OS path separators (backslash on Windows, forward slash on Linux/Mac).
+ *
+ * @param {string} remotePath - Absolute POSIX path on the remote, e.g. '/root/project/file.txt'
+ * @param {string} fakeRoot   - Local fake root directory, e.g. '/tmp/pi-bridge'
+ * @returns {string}          - Local path, e.g. '/tmp/pi-bridge/root/project/file.txt'
+ */
+function toFakePath(remotePath, fakeRoot) {
+  // Split on '/' and filter empty segments (leading slash produces one)
+  const segments = remotePath.split('/').filter(Boolean);
+  return path.join(fakeRoot, ...segments);
+}
+
+/**
+ * Convert a fake local path back to a remote POSIX path.
+ * Strips fakeRoot prefix and normalises separators to forward slashes.
+ *
+ * @param {string} fakePath - Local path, e.g. '/tmp/pi-bridge/root/project/file.txt'
+ * @param {string} fakeRoot - Local fake root directory, e.g. '/tmp/pi-bridge'
+ * @returns {string}        - Remote POSIX path, e.g. '/root/project/file.txt'
+ */
+function toRemotePath(fakePath, fakeRoot) {
+  // Ensure fakeRoot does not have a trailing separator for consistent slicing
+  const root = fakeRoot.endsWith(path.sep)
+    ? fakeRoot.slice(0, -1)
+    : fakeRoot;
+
+  const relative = fakePath.slice(root.length);
+  // On Windows path.sep is '\'; normalise to '/'
+  return relative.split(path.sep).join('/');
+}
+
+/**
+ * Check whether a given path is under the fake root.
+ *
+ * @param {string} p        - Path to test
+ * @param {string} fakeRoot - Local fake root directory
+ * @returns {boolean}
+ */
+function isFakePath(p, fakeRoot) {
+  // Normalise fakeRoot to not have trailing separator
+  const root = fakeRoot.endsWith(path.sep)
+    ? fakeRoot.slice(0, -1)
+    : fakeRoot;
+
+  return p === root || p.startsWith(root + path.sep);
+}
+
+module.exports = { toFakePath, toRemotePath, isFakePath };

package/src/local/preload.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * preload.js — Entry point for pi-bridge, loaded via node --require.
+ *
+ * When --ssh is not present in process.argv, this module is a no-op so that
+ * pi can still be used locally without the bridge.
+ *
+ * Orchestration (all synchronous from the caller's perspective):
+ *   1. Parse + strip --ssh user@host:/path from process.argv
+ *   2. spawnSync setup.js to upload + start remote server → { port, token, remoteCwd }
+ *   3. Create fake local directory skeleton
+ *   4. process.chdir to fake local cwd
+ *   5. Spawn SSH tunnel (local:port → remote:port)
+ *   6. Patch fs.* to intercept fake-root paths
+ *   7. Register cleanup handler on process exit
+ */
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const { parseAndStripSshArg } = require('./argv');
+const { createFakeDir } = require('./fake-dir');
+const { startTunnel } = require('./tunnel');
+const { patchFs } = require('./fs-patch');
+const { patchChildProcess } = require('./child-process-patch');
+const { registerCleanup } = require('./cleanup');
+
+// --- Step 1: Parse --ssh flag ---
+const sshArg = parseAndStripSshArg();
+if (!sshArg) {
+  // No --ssh flag → run pi locally, bridge is inactive
+  return;
+}
+
+const { remote, remoteCwd } = sshArg;
+
+// --- Step 2: Upload + start remote server via setup.js ---
+const setupScript = path.join(__dirname, 'setup.js');
+const setupResult = spawnSync(process.execPath, [setupScript, remote, remoteCwd], {
+  encoding: 'utf8',
+  timeout: 30000, // 30 seconds
+});
+
+if (setupResult.status !== 0) {
+  const errMsg = (setupResult.stderr || '').trim() || 'setup.js exited with status ' + setupResult.status;
+  throw new Error('pi-bridge: ' + errMsg);
+}
+
+let config;
+try {
+  config = JSON.parse(setupResult.stdout.trim());
+} catch (e) {
+  throw new Error('pi-bridge: Failed to parse setup output: ' + setupResult.stdout);
+}
+
+const { port, token, sessionId, remotePid } = config;
+
+// --- Step 3: Create fake local directory ---
+const { fakeRoot, fakeLocalCwd } = createFakeDir(remoteCwd);
+
+// --- Step 4: Change working directory to fake local cwd ---
+process.chdir(fakeLocalCwd);
+
+// --- Step 5: Start SSH tunnel ---
+const tunnelProcess = startTunnel(remote, port);
+
+// --- Step 6: Patch fs.* and child_process ---
+patchFs(fakeRoot, port, token);
+patchChildProcess(fakeRoot, remote);
+
+// --- Step 7: Register cleanup ---
+registerCleanup({ fakeRoot, tunnelProcess, remote, sessionId, remotePid });

package/src/local/setup.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * setup.js — Orchestrator called via spawnSync from preload.js
+ *
+ * Usage: node setup.js <remote> <remoteCwd>
+ *
+ * Steps:
+ *   1. Upload the bundled remote server script via SSH
+ *   2. Start the server on the remote (background process + poll for output)
+ *   3. Parse PORT:TOKEN:PID from remote stdout
+ *   4. Print { port, token, remoteCwd, sessionId, remotePid } as JSON to stdout
+ *
+ * Each session gets a unique ID to isolate its log file, preventing races
+ * when multiple pi sessions target the same remote working directory.
+ */
+
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const { uploadBundle } = require('./upload');
+
+const remote = process.argv[2];
+const remoteCwd = process.argv[3];
+
+if (!remote || !remoteCwd) {
+  process.stderr.write('Usage: node setup.js <remote> <remoteCwd>\n');
+  process.exit(1);
+}
+
+const REMOTE_SCRIPT = '/tmp/pi-bridge-server.js';
+
+// Unique per-session log file — prevents races when multiple sessions
+// target the same remote working directory simultaneously.
+const sessionId = crypto.randomBytes(4).toString('hex');
+const REMOTE_LOG = '/tmp/pi-bridge-out-' + sessionId + '.txt';
+
+try {
+  // Step 1: Upload the bundled server script
+  uploadBundle(remote, REMOTE_SCRIPT);
+
+  // Step 2: Start server in background on remote.
+  // The server prints "PORT:TOKEN:PID\n" on startup then stays alive.
+  // We poll the session-unique log file to avoid racing with other sessions.
+  const startCmd =
+    'node ' + REMOTE_SCRIPT + ' ' + remoteCwd + ' >' + REMOTE_LOG + ' 2>&1 & ' +
+    'disown; ' +
+    'for i in $(seq 1 30); do ' +
+    '  line=$(head -1 ' + REMOTE_LOG + ' 2>/dev/null); ' +
+    '  if [ -n "$line" ]; then echo "$line"; break; fi; ' +
+    '  sleep 0.1; ' +
+    'done';
+
+  const output = execFileSync('ssh', ['-o', 'BatchMode=yes', remote, startCmd], {
+    encoding: 'utf8',
+  }).trim();
+
+  if (!output) {
+    throw new Error('Remote server did not print PORT:TOKEN:PID within timeout');
+  }
+
+  const parts = output.split(':');
+  if (parts.length < 3) {
+    throw new Error('Unexpected remote output (expected PORT:TOKEN:PID): ' + output);
+  }
+
+  const port = parseInt(parts[0], 10);
+  const token = parts[1];
+  const remotePid = parseInt(parts[2], 10);
+
+  if (!port || !token || !remotePid) {
+    throw new Error('Failed to parse PORT:TOKEN:PID from: ' + output);
+  }
+
+  // Step 3: Print result as JSON so preload.js can parse it
+  process.stdout.write(JSON.stringify({ port, token, remoteCwd, sessionId, remotePid }) + '\n');
+} catch (err) {
+  process.stderr.write('pi-bridge setup failed: ' + err.message + '\n');
+  process.exit(1);
+}

package/src/local/ssh.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+/**
+ * Execute a shell command on a remote machine over SSH synchronously.
+ * Uses BatchMode=yes to prevent interactive prompts (fail fast if no key auth).
+ *
+ * @param {string} remote - SSH target, e.g. 'user@host'
+ * @param {string} cmd    - Shell command to run on remote
+ * @returns {string}      - stdout as a trimmed string
+ * @throws                - On non-zero exit or SSH error
+ */
+function sshExecSync(remote, cmd) {
+  return execFileSync('ssh', ['-o', 'BatchMode=yes', remote, cmd], {
+    encoding: 'utf8',
+  });
+}
+
+module.exports = { sshExecSync };

package/src/local/tunnel.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const { spawn, execFileSync } = require('child_process');
+
+const SSH_ARGS = (remote, port) => [
+  '-o', 'BatchMode=yes',
+  '-o', 'ExitOnForwardFailure=yes',
+  '-N',
+  '-L', `${port}:127.0.0.1:${port}`,
+  remote,
+];
+
+/**
+ * Start an SSH port-forward tunnel with auto-reconnect.
+ *
+ * If the tunnel process exits (sleep/wake, network drop, etc.) it is
+ * automatically restarted after a short back-off delay.  The returned
+ * handle exposes a `kill()` method used by cleanup.js to stop reconnecting
+ * and tear down the current process.
+ *
+ * @param {string} remote          - SSH target, e.g. 'user@host'
+ * @param {number} port            - Port number to forward (same port both sides)
+ * @param {object} [opts]
+ * @param {Function} [opts._spawn] - Override spawn (for testing)
+ * @returns {{ kill: () => void }}
+ */
+function startTunnel(remote, port, { _spawn = spawn } = {}) {
+  let child = null;
+  let stopped = false;
+  let backoff = 1000; // ms — resets to 1s on each successful reconnect
+
+  function spawn_() {
+    child = _spawn('ssh', SSH_ARGS(remote, port), {
+      stdio: ['ignore', 'ignore', 'ignore'],
+      detached: false,
+    });
+
+    child.on('exit', (code) => {
+      if (stopped) return;
+      // Back off up to 10s, then retry indefinitely
+      setTimeout(() => {
+        if (stopped) return;
+        backoff = Math.min(backoff * 2, 10000);
+        spawn_();
+      }, backoff);
+    });
+
+    // Reset backoff once the tunnel has been alive for a while
+    setTimeout(() => { backoff = 1000; }, 5000);
+  }
+
+  spawn_();
+
+  // Brief sync sleep so the tunnel is ready before the first HTTP call.
+  try {
+    execFileSync(process.execPath, ['-e', 'setTimeout(()=>{},500)'], {
+      encoding: 'utf8',
+    });
+  } catch (_) {}
+
+  return {
+    kill() {
+      stopped = true;
+      if (child) child.kill();
+    },
+  };
+}
+
+module.exports = { startTunnel };

package/src/local/upload.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// Root of the pi-bridge project (two levels up from src/local/)
+const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
+
+/**
+ * Read the remote source files and bundle them into a single self-contained
+ * CommonJS script.
+ *
+ * Each file's code is inlined directly — module.exports lines are removed,
+ * and const/let declarations are converted to var so they hoist to the
+ * top-level scope and are accessible by later files in the bundle.
+ *
+ * Dependency order:
+ *   1. shared/protocol.js  → exports: ENDPOINTS, TOKEN_HEADER, ERRORS
+ *   2. remote/auth.js      → exports: generateToken, createAuthMiddleware
+ *   3. remote/guard.js     → exports: createGuard
+ *   4. remote/handlers.js  → exports: createHandlers
+ *   5. remote/index.js     → entry point (no exports)
+ *
+ * @returns {string} The bundled script as a string
+ */
+function buildBundle() {
+  const files = [
+    path.join(PROJECT_ROOT, 'src', 'shared', 'protocol.js'),
+    path.join(PROJECT_ROOT, 'src', 'remote', 'auth.js'),
+    path.join(PROJECT_ROOT, 'src', 'remote', 'guard.js'),
+    path.join(PROJECT_ROOT, 'src', 'remote', 'handlers.js'),
+    path.join(PROJECT_ROOT, 'src', 'remote', 'index.js'),
+  ];
+
+  const parts = ["'use strict';\n"];
+
+  for (const filePath of files) {
+    let src = fs.readFileSync(filePath, 'utf8');
+
+    // 1. Remove 'use strict' — we add one at the top
+    src = src.replace(/^'use strict';\n?/gm, '');
+
+    // 2. Remove module.exports = { ... }; lines entirely
+    src = src.replace(/^module\.exports\s*=\s*\{[^}]+\};\s*\n?/gm, '');
+
+    // 3. Replace top-level const/let declarations with var so they hoist
+    //    to the bundle's top-level scope. Only replace declarations that
+    //    are at the start of a line (top-level, not inside functions/blocks).
+    src = src.replace(/^const\s+/gm, 'var ');
+    src = src.replace(/^let\s+/gm, 'var ');
+
+    parts.push('// --- ' + path.basename(filePath) + ' ---');
+    parts.push(src.trim());
+    parts.push('');
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * Upload the bundled remote server script to the remote machine via SSH.
+ * Uses base64 encoding to safely transfer content over the shell.
+ *
+ * @param {string} remote     - SSH target, e.g. 'user@host'
+ * @param {string} [destPath] - Remote destination path (default: /tmp/pi-bridge-server.js)
+ */
+function uploadBundle(remote, destPath) {
+  destPath = destPath || '/tmp/pi-bridge-server.js';
+  const bundle = buildBundle();
+  const encoded = Buffer.from(bundle, 'utf8').toString('base64');
+
+  // Use printf to write the base64 string then pipe through base64 -d
+  const cmd = "printf '%s' '" + encoded + "' | base64 -d > " + destPath;
+
+  execFileSync('ssh', ['-o', 'BatchMode=yes', remote, cmd], {
+    encoding: 'utf8',
+  });
+}
+
+module.exports = { buildBundle, uploadBundle };

package/src/remote/auth.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Generate a cryptographically random token.
+ * @returns {string} 64-character hex string
+ */
+function generateToken() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+/**
+ * Create an auth middleware that validates the x-token header.
+ * Returns a function (req, res, next) that calls next() on success or
+ * writes 401 on failure.
+ *
+ * @param {string} token - The expected token value
+ * @returns {function(req, res, next): void}
+ */
+function createAuthMiddleware(token) {
+  return function authMiddleware(req, res, next) {
+    const provided = req.headers['x-token'];
+    if (!provided || provided !== token) {
+      res.writeHead(401, { 'Content-Type': 'text/plain' });
+      res.end('Unauthorized');
+      return;
+    }
+    next();
+  };
+}
+
+module.exports = { generateToken, createAuthMiddleware };

package/src/remote/guard.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * Create a path guard middleware that restricts access to files within remoteCwd.
+ * Resolves the path from the query parameter 'path' (or 'from' for rename).
+ * Sends 403 if the resolved path is outside remoteCwd.
+ *
+ * @param {string} remoteCwd - Absolute path on the remote that is the allowed root
+ * @returns {function(req, res, next): void}
+ */
+function createGuard(remoteCwd) {
+  const normalizedCwd = path.resolve(remoteCwd);
+
+  return function guardMiddleware(req, res, next) {
+    const url = new URL(req.url, 'http://localhost');
+    // For rename we need to check both 'from' and 'to'
+    const pathsToCheck = [];
+
+    const p = url.searchParams.get('path');
+    if (p !== null) pathsToCheck.push(p);
+
+    const from = url.searchParams.get('from');
+    if (from !== null) pathsToCheck.push(from);
+
+    const to = url.searchParams.get('to');
+    if (to !== null) pathsToCheck.push(to);
+
+    // If no path params provided, let handler deal with it (will likely 400)
+    if (pathsToCheck.length === 0) {
+      next();
+      return;
+    }
+
+    for (const p of pathsToCheck) {
+      const resolved = path.resolve(p);
+      if (!resolved.startsWith(normalizedCwd + path.sep) && resolved !== normalizedCwd) {
+        res.writeHead(403, { 'Content-Type': 'text/plain' });
+        res.end('Forbidden');
+        return;
+      }
+    }
+
+    next();
+  };
+}
+
+module.exports = { createGuard };