pi-bridge 0.1.1

package/README.md

@@ -0,0 +1,126 @@
+# pi-bridge
+
+Transparent filesystem bridge that makes [pi](https://github.com/badlogic/pi-mono) run natively on a remote machine — no internet required on the remote, no tools to install beyond Node.js.
+
+Pi runs on your local machine (needs internet for auth and Claude API). Your project lives on a remote Linux machine. `pi-bridge` intercepts all of pi's filesystem calls and redirects them over SSH to a tiny HTTP server running on the remote. Pi thinks it's running locally — it finds `AGENTS.md`, skills, context files, and git state natively, without knowing they're remote.
+
+## Prerequisites
+
+- Node.js ≥ 18 on the **local** machine
+- Node.js on the **remote** machine
+- SSH access to the remote machine with key-based auth (no password prompt)
+- `pi` installed locally
+
+## Installation
+
+```bash
+npm install -g pi-bridge
+```
+
+## Usage
+
+Use `pii` exactly like `pi`, adding `--ssh` to point at your remote project:
+
+```bash
+# Absolute path
+pii --ssh user@host:/root/projects/my-app
+
+# With SSH alias (configured in ~/.ssh/config)
+pii --ssh myserver:/root/projects/my-app
+
+# Tilde path (expanded by remote shell)
+pii --ssh user@host:~/projects/my-app
+```
+
+Everything works natively — pi discovers `AGENTS.md`, skills, and context files on the remote without any extra flags or extensions.
+
+## Updating
+
+```bash
+npm update -g pi-bridge
+```
+
+## How It Works
+
+```
+Local machine                          Remote (Linux)
+─────────────────────────────          ──────────────────────
+pii (bin/pii.js)
+  └─ node --require preload.js pi
+       ├─ upload server bundle via SSH
+       ├─ start HTTP server on remote
+       │    → prints PORT:TOKEN:PID to stdout
+       ├─ SSH port forward localhost:PORT
+       ├─ create fake local dir:
+       │    /tmp/pi-bridge/root/projects/my-app
+       ├─ process.chdir(fakeLocalCwd)
+       ├─ strip --ssh from process.argv
+       ├─ patch fs.*  (sync + promises)     remote/index.js
+       └─ patch child_process.*               listens on 127.0.0.1:PORT
+                                              validates token
+pi loads — unaware of bridge               restricts to remoteCwd
+  fs.readFileSync(...)  ──GET──→           reads real remote files
+  fs.readdirSync(...)   ──GET──→           ← returns data
+  spawn('git', ...)     ──SSH──→           runs on remote
+  → finds AGENTS.md ✓
+  → finds skills ✓
+  → git branch in footer ✓
+```
+
+## What Gets Patched
+
+| API | Covered |
+|---|---|
+| `fs` sync — read, write, stat, readdir, mkdir, rm, copy, rename, realpath, access, watch | ✓ |
+| `fs.promises` — all async equivalents | ✓ |
+| `fs/promises` module (ES module static imports) | ✓ |
+| `child_process.spawn` / `spawnSync` — runs in remote cwd via SSH | ✓ |
+| `fs.watch` / `fs.watchFile` — polls remote via HTTP (git branch updates) | ✓ |
+
+## Security
+
+| Layer | Protection |
+|---|---|
+| Loopback only | HTTP server binds `127.0.0.1` — not reachable from the network |
+| SSH tunnel | All HTTP traffic encrypted end-to-end |
+| Random token | 32-byte random token required on every request |
+| Path restriction | Server rejects paths outside `remoteCwd` (403) |
+| Token in stdout | Token never appears in `ps aux` args |
+
+## Development
+
+```bash
+git clone https://github.com/zeflq/pi-bridge
+cd pi-bridge
+npm install
+```
+
+Test against a real remote without installing pi:
+
+```bash
+SSH_TARGET=user@host:/root/projects/my-app npm run dev
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+## Troubleshooting
+
+**`Command failed: ssh … syntax error near unexpected token`**
+Your SSH alias requires `BatchMode=yes`. Add to `~/.ssh/config`:
+```
+Host myserver
+  BatchMode yes
+```
+
+**Files show as empty / ENOENT**
+The fake local directory (`/tmp/pi-bridge/…`) is intentionally empty — all reads go to the remote. If you see ENOENT, the bridge may not have started correctly. Check that Node.js is available on the remote (`node --version`).
+
+**Branch name not updating**
+The footer polls `.git` every second. Switching branches from outside a pi session is reflected within ~1s. If the branch is stuck, restart `pii`.
+
+**Windows: `pii` can't find `pi`**
+Ensure the OpenSSH client is enabled (Windows 10+: Settings → Apps → Optional Features → OpenSSH Client) and `pi` is installed globally (`npm install -g pi`).

package/bin/pii.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * pii — pi-bridge entry point installed as a global binary.
+ *
+ * Locates the `pi` CLI JS file and its bundled Node binary (if any), then
+ * respawns with --require preload.js so the bridge is active before pi loads.
+ *
+ * Resolution strategy (same on all platforms):
+ *   1. Get the wrapper script path from the system (which pi / Get-Command pi)
+ *   2. Derive basedir from the wrapper path
+ *   3. Find the actual CLI JS at basedir/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+ *   4. Use basedir/node.exe if present (pi ships its own Node on some installs),
+ *      otherwise fall back to the current Node binary
+ */
+
+const { spawnSync, execFileSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const preload = path.join(__dirname, '..', 'src', 'local', 'preload.js');
+
+const PI_CLI_REL = path.join('node_modules', '@mariozechner', 'pi-coding-agent', 'dist', 'cli.js');
+
+function getWrapperPath() {
+  if (os.platform() === 'win32') {
+    return execFileSync(
+      'powershell',
+      ['-NoProfile', '-Command', '(Get-Command pi -ErrorAction Stop).Source'],
+      { encoding: 'utf8' }
+    ).trim();
+  }
+  return execFileSync('which', ['pi'], { encoding: 'utf8' }).trim();
+}
+
+function findPiCli() {
+  const wrapper = getWrapperPath();
+  const basedir = path.dirname(wrapper);
+
+  const cli = path.join(basedir, PI_CLI_REL);
+  if (!fs.existsSync(cli)) {
+    throw new Error(
+      'Could not find pi CLI at ' + cli + '\n' +
+      'Make sure pi is installed: npm install -g @mariozechner/pi-coding-agent'
+    );
+  }
+
+  // Prefer the Node binary bundled alongside pi (some installs ship node.exe)
+  const localNode = path.join(basedir, 'node.exe');
+  const nodeExe = fs.existsSync(localNode) ? localNode : process.execPath;
+
+  return { cli, nodeExe };
+}
+
+let cli, nodeExe;
+try {
+  ({ cli, nodeExe } = findPiCli());
+} catch (err) {
+  process.stderr.write('pii: ' + err.message + '\n');
+  process.exit(1);
+}
+
+const result = spawnSync(
+  nodeExe,
+  ['--require', preload, cli, ...process.argv.slice(2)],
+  { stdio: 'inherit' }
+);
+
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "pi-bridge",
+  "version": "0.1.1",
+  "description": "Transparent filesystem bridge that makes pi run natively on a remote machine over SSH",
+  "type": "commonjs",
+  "bin": {
+    "pii": "bin/pii.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "test": "vitest --run",
+    "dev": "node dev.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "ssh",
+    "bridge",
+    "remote",
+    "filesystem"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "vitest": "^2.0.0"
+  }
+}

package/src/local/argv.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * Parse and strip --ssh user@host:/path from process.argv.
+ *
+ * Mutates process.argv in place, removing both '--ssh' and its value.
+ *
+ * @returns {{ remote: string, remoteCwd: string } | null}
+ *   remote    = 'user@host'
+ *   remoteCwd = '/path' (or '~/path' — remote shell will expand it)
+ *   Returns null if --ssh flag is not present.
+ */
+function parseAndStripSshArg() {
+  const argv = process.argv;
+  const idx = argv.indexOf('--ssh');
+  if (idx === -1) return null;
+
+  const value = argv[idx + 1];
+  if (!value) {
+    throw new Error('--ssh flag requires a value: user@host:/path');
+  }
+
+  // value format: user@host:/path  or  user@host:~/path
+  const colonIdx = value.indexOf(':');
+  if (colonIdx === -1) {
+    throw new Error('--ssh value must be in format user@host:/path, got: ' + value);
+  }
+
+  const remote = value.slice(0, colonIdx);
+  const remoteCwd = value.slice(colonIdx + 1);
+
+  if (!remote) {
+    throw new Error('--ssh value missing host portion: ' + value);
+  }
+  if (!remoteCwd) {
+    throw new Error('--ssh value missing path portion: ' + value);
+  }
+
+  // Strip both '--ssh' and its value from argv
+  argv.splice(idx, 2);
+
+  return { remote, remoteCwd };
+}
+
+module.exports = { parseAndStripSshArg };

package/src/local/child-process-patch.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const cp = require('child_process');
+const path = require('path');
+const { isFakePath, toRemotePath } = require('./path-mapper');
+
+/**
+ * Patch child_process.spawn and child_process.spawnSync so that commands
+ * whose cwd lands inside fakeRoot are transparently redirected to run on
+ * the remote machine via SSH.
+ *
+ * Pi's bash tool uses spawn/spawnSync exclusively, so this covers all shell
+ * command execution (ls, cat, grep, npm run, etc.).
+ *
+ * @param {string} fakeRoot - Local fake root directory (real path, no symlinks)
+ * @param {string} remote   - SSH target, e.g. 'user@host'
+ */
+function patchChildProcess(fakeRoot, remote) {
+  const origSpawn     = cp.spawn.bind(cp);
+  const origSpawnSync = cp.spawnSync.bind(cp);
+
+  /**
+   * Resolve the effective cwd from spawn options.
+   * Falls back to process.cwd() when opts.cwd is not set.
+   */
+  function effectiveCwd(opts) {
+    const c = opts && opts.cwd;
+    if (!c) return process.cwd();
+    return typeof c === 'string' ? path.resolve(c) : c.toString();
+  }
+
+  /**
+   * Build the SSH-redirected command: cd to remote cwd, then run the
+   * original command with its arguments, all shell-quoted.
+   */
+  function buildSshArgs(file, args, opts) {
+    const fakeCwd    = effectiveCwd(opts);
+    const remoteCwd  = toRemotePath(fakeCwd, fakeRoot);
+
+    // Reconstruct the command string with shell-safe quoting
+    const argStr = (args || [])
+      .map(function(a) { return "'" + String(a).replace(/'/g, "'\\''") + "'"; })
+      .join(' ');
+    const remoteCmd = 'cd ' + JSON.stringify(remoteCwd) + ' && ' + file + (argStr ? ' ' + argStr : '');
+
+    return ['-o', 'BatchMode=yes', remote, remoteCmd];
+  }
+
+  // ── spawn ────────────────────────────────────────────────────────────────────
+
+  cp.spawn = function patchedSpawn(file, args, opts) {
+    // Normalise overloaded signature: spawn(file) / spawn(file, opts) / spawn(file, args, opts)
+    if (!Array.isArray(args)) { opts = args; args = []; }
+    opts = opts || {};
+
+    const cwd = effectiveCwd(opts);
+    if (!isFakePath(cwd, fakeRoot)) return origSpawn(file, args, opts);
+
+    return origSpawn('ssh', buildSshArgs(file, args, opts), Object.assign({}, opts, { cwd: undefined }));
+  };
+
+  // ── spawnSync ────────────────────────────────────────────────────────────────
+
+  cp.spawnSync = function patchedSpawnSync(file, args, opts) {
+    if (!Array.isArray(args)) { opts = args; args = []; }
+    opts = opts || {};
+
+    const cwd = effectiveCwd(opts);
+    if (!isFakePath(cwd, fakeRoot)) return origSpawnSync(file, args, opts);
+
+    return origSpawnSync('ssh', buildSshArgs(file, args, opts), Object.assign({}, opts, { cwd: undefined }));
+  };
+}
+
+module.exports = { patchChildProcess };

package/src/local/cleanup.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const { removeFakeDir } = require('./fake-dir');
+const { sshExecSync } = require('./ssh');
+
+/**
+ * Register a process.on('exit') handler that tears down the bridge session.
+ *
+ * Cleanup actions (best-effort — errors are suppressed):
+ *   1. Remove the fake local directory
+ *   2. Kill the SSH tunnel process
+ *   3. Kill the remote server process (by PID) and remove its log file
+ *
+ * Each session has a unique sessionId so its log file does not clash with
+ * other sessions targeting the same remote working directory.
+ *
+ * @param {object} opts
+ * @param {string}   opts.fakeRoot      - Local fake root path to remove
+ * @param {object}   opts.tunnelProcess - SSH tunnel watchdog handle ({ kill() })
+ * @param {string}   opts.remote        - SSH target, e.g. 'user@host'
+ * @param {string}   opts.sessionId     - Random 8-char hex ID for this session
+ * @param {number}   opts.remotePid     - PID of the remote server process
+ */
+function registerCleanup({ fakeRoot, tunnelProcess, remote, sessionId, remotePid }) {
+  const remoteLog = sessionId ? '/tmp/pi-bridge-out-' + sessionId + '.txt' : null;
+
+  function cleanup() {
+    // 1. Remove fake local directory
+    if (fakeRoot) {
+      removeFakeDir(fakeRoot);
+    }
+
+    // 2. Kill tunnel watchdog
+    if (tunnelProcess) {
+      try {
+        if (typeof tunnelProcess.kill === 'function') tunnelProcess.kill();
+      } catch (_) {}
+    }
+
+    // 3. Kill the specific remote server process and clean up its log file
+    if (remote) {
+      try {
+        let cmd = '';
+        if (remotePid) cmd += 'kill ' + remotePid + ' 2>/dev/null; ';
+        if (remoteLog) cmd += 'rm -f ' + remoteLog;
+        if (cmd) sshExecSync(remote, cmd);
+      } catch (_) {}
+    }
+  }
+
+  process.on('exit', cleanup);
+  process.on('SIGINT', () => process.exit(130));
+  process.on('SIGTERM', () => process.exit(143));
+}
+
+module.exports = { registerCleanup };

package/src/local/fake-dir.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/**
+ * Create the fake local directory skeleton for the given remote path.
+ * The structure mirrors the remote path so that path-mapper can convert
+ * between fake local paths and remote paths deterministically.
+ *
+ * Example:
+ *   remoteCwd = '/root/project-x'
+ *   fakeRoot  = '/tmp/pi-bridge'
+ *   fakeLocalCwd = '/tmp/pi-bridge/root/project-x'
+ *
+ * @param {string} remoteCwd - Absolute remote path, e.g. '/root/project-x'
+ * @returns {{ fakeRoot: string, fakeLocalCwd: string }}
+ */
+function createFakeDir(remoteCwd) {
+  const fakeRootRaw = path.join(os.tmpdir(), 'pi-bridge');
+
+  // Build the local mirror path from the remote path segments
+  const segments = remoteCwd.split('/').filter(Boolean);
+  const fakeLocalCwdRaw = path.join(fakeRootRaw, ...segments);
+
+  fs.mkdirSync(fakeLocalCwdRaw, { recursive: true });
+
+  // Resolve symlinks so the prefix matches what process.cwd() returns after
+  // chdir — on macOS /var/folders/… is a symlink to /private/var/folders/…
+  const fakeRoot = fs.realpathSync(fakeRootRaw);
+  const fakeLocalCwd = fs.realpathSync(fakeLocalCwdRaw);
+
+  return { fakeRoot, fakeLocalCwd };
+}
+
+/**
+ * Remove the fake root directory and all its contents.
+ * Safe to call even if the directory does not exist.
+ *
+ * @param {string} fakeRoot - Path returned by createFakeDir
+ */
+function removeFakeDir(fakeRoot) {
+  try {
+    fs.rmSync(fakeRoot, { recursive: true, force: true });
+  } catch (_) {
+    // Best-effort removal — do not throw during cleanup
+  }
+}
+
+module.exports = { createFakeDir, removeFakeDir };