pairshell-cli 0.0.1

package/src/providers/devtunnel.js

@@ -0,0 +1,99 @@
+import { spawn } from "node:child_process";
+
+const TUNNEL_URL_RE = /https:\/\/[a-z0-9-]+\.devtunnels\.ms(?::\d+)?/i;
+const TUNNEL_ID_RE = /Tunnel ID[:\s]+\s*([^\r\n]+)/i;
+const TUNNEL_TIMEOUT_MS = 30000;
+
+async function execDevtunnel(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("devtunnel", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (c) => { stdout += c; });
+    child.stderr.on("data", (c) => { stderr += c; });
+    child.on("error", (err) => reject(new Error(`Cannot start devtunnel: ${err.message}`)));
+    child.on("exit", (code) => {
+      if (code === 0) resolve(stdout + stderr);
+      else reject(new Error(`devtunnel exited code ${code}: ${(stderr || stdout).slice(0, 200)}`));
+    });
+  });
+}
+
+export const provider = {
+  name: "devtunnel",
+  label: "Microsoft devtunnel",
+
+  checkSetup(config) {
+    const id = config?.devtunnel?.tunnelId;
+    if (id) return { ok: true, message: `Tunnel ID: ${id}` };
+    return { ok: false, message: "No tunnel configured. Run 'pairshell-cli setup devtunnel'" };
+  },
+
+  async setup(config) {
+    const output = await execDevtunnel(["create", "--allow-anonymous"]);
+    const match = output.match(TUNNEL_ID_RE);
+    if (!match) throw new Error("Could not parse tunnel ID from devtunnel output");
+    const id = match[1].trim().split(/\s+/)[0];
+    return { ...config, provider: "devtunnel", devtunnel: { ...config?.devtunnel, tunnelId: id } };
+  },
+
+  startTunnel(port, config) {
+    const tunnelId = config?.devtunnel?.tunnelId;
+    if (!tunnelId) throw new Error("No devtunnel ID configured. Run setup first.");
+
+    return new Promise((resolve, reject) => {
+      const child = spawn("devtunnel", ["host", tunnelId, "-p", String(port), "--allow-anonymous"], {
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+
+      let buffer = "";
+      let settled = false;
+
+      const fail = (msg) => {
+        if (settled) return;
+        settled = true;
+        try { child.kill("SIGTERM"); } catch {}
+        reject(new Error(msg));
+      };
+
+      child.on("error", (err) => fail(`Could not start devtunnel CLI: ${err.message}. Install from https://aka.ms/devtunnel/cli`));
+      child.on("exit", (code, signal) => {
+        if (!settled) fail(`devtunnel exited before URL (code ${code}, signal ${signal})`);
+      });
+
+      const feed = (chunk) => {
+        buffer += chunk.toString();
+        const m = buffer.match(TUNNEL_URL_RE);
+        if (m && !settled) {
+          settled = true;
+          resolve({ url: m[0], child });
+        }
+      };
+      child.stdout.on("data", feed);
+      child.stderr.on("data", feed);
+
+      setTimeout(() => fail("Timed out waiting for devtunnel URL"), TUNNEL_TIMEOUT_MS);
+    });
+  },
+
+  printGuide() {
+    console.log(`
+  ${this.label} Setup Guide
+  ───────────────────────
+
+  1. Install the devtunnel CLI:
+     https://aka.ms/devtunnel/cli
+
+  2. Log in with a Microsoft account:
+     devtunnel user login
+
+  3. Run setup:
+     pairshell-cli setup devtunnel
+
+  The tunnel ID persists in ~/.pairshell/config.json.
+  Every start reuses the same tunnel ID for a stable URL.
+`);
+  },
+};

package/src/providers/index.js

@@ -0,0 +1,24 @@
+import { provider as devtunnel } from "./devtunnel.js";
+import { provider as ngrok } from "./ngrok.js";
+import { provider as tailscale } from "./tailscale.js";
+
+const REGISTRY = { devtunnel, ngrok, tailscale };
+const DEFAULT = "devtunnel";
+
+export function resolve(name) {
+  const key = (name || DEFAULT).toLowerCase();
+  const prov = REGISTRY[key];
+  if (!prov) {
+    const available = Object.keys(REGISTRY).join(", ");
+    throw new Error(`Unknown provider "${name}". Available: ${available}`);
+  }
+  return prov;
+}
+
+export function listProviders() {
+  return Object.keys(REGISTRY);
+}
+
+export function defaultProvider() {
+  return DEFAULT;
+}

package/src/providers/ngrok.js

@@ -0,0 +1,185 @@
+import { spawn } from "node:child_process";
+import { access, mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { get } from "node:https";
+import { createWriteStream } from "node:fs";
+
+const BIN_DIR = join(homedir(), ".pairshell", "bin");
+const NGROK_PATH = join(BIN_DIR, process.platform === "win32" ? "ngrok.exe" : "ngrok");
+const TUNNEL_TIMEOUT_MS = 30000;
+
+function platformTag() {
+  switch (process.platform) {
+    case "win32": return "windows";
+    case "darwin": return "darwin";
+    default: return "linux";
+  }
+}
+
+function archTag() {
+  return process.arch === "arm64" ? "arm64" : "amd64";
+}
+
+function ngrokDownloadUrl() {
+  const tag = platformTag();
+  const arch = archTag();
+  const ext = tag === "windows" ? "zip" : "tgz";
+  const version = "3";
+  return `https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v${version}-${tag}-${arch}.${ext}`;
+}
+
+async function downloadNgrok() {
+  const url = ngrokDownloadUrl();
+  const tmp = join(BIN_DIR, `ngrok-dl.${process.platform === "win32" ? "zip" : "tgz"}`);
+
+  await mkdir(BIN_DIR, { recursive: true });
+  console.log(`  Downloading ngrok from ${url} ...`);
+
+  await new Promise((resolve, reject) => {
+    const file = createWriteStream(tmp);
+    get(url, (res) => {
+      if (res.statusCode !== 200) {
+        reject(new Error(`Download failed (HTTP ${res.statusCode})`));
+        return;
+      }
+      res.pipe(file);
+      file.on("finish", () => { file.close(); resolve(); });
+    }).on("error", reject);
+  });
+
+  if (tmp.endsWith(".zip")) {
+    await new Promise((resolve, reject) => {
+      const child = spawn("powershell", [
+        "-NoProfile", "-Command",
+        `Expand-Archive -Path "${tmp}" -DestinationPath "${BIN_DIR}" -Force`,
+      ], { stdio: "inherit" });
+      child.on("exit", (code) => code === 0 ? resolve() : reject(new Error("Extraction failed")));
+    });
+  } else {
+    await new Promise((resolve, reject) => {
+      const child = spawn("tar", ["-xzf", tmp, "-C", BIN_DIR], { stdio: "inherit" });
+      child.on("exit", (code) => code === 0 ? resolve() : reject(new Error("Extraction failed")));
+    });
+  }
+
+  try { await access(tmp); } catch {}
+}
+
+async function ngrokAuthtoken(config) {
+  const apiKey = config?.ngrok?.apiKey;
+  if (!apiKey) throw new Error("No ngrok API key configured. Run setup.");
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(NGROK_PATH, ["config", "add-authtoken", apiKey], {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let out = "";
+    child.stdout.on("data", (c) => { out += c; });
+    child.stderr.on("data", (c) => { out += c; });
+    child.on("exit", (code) => {
+      if (code === 0) resolve(out);
+      else reject(new Error(`ngrok authtoken failed: ${out.slice(0, 200)}`));
+    });
+  });
+}
+
+export const provider = {
+  name: "ngrok",
+  label: "ngrok",
+
+  checkSetup(config) {
+    const cfg = config?.ngrok;
+    if (!cfg?.apiKey) return { ok: false, message: "No API key configured. Run 'pairshell-cli setup ngrok'" };
+    return { ok: true, message: `API key: ${cfg.apiKey.slice(0, 8)}...` };
+  },
+
+  async setup(config) {
+    console.log("  ngrok setup requires a free ngrok account and API key.");
+    console.log("  Get your API key at https://dashboard.ngrok.com/api-keys\n");
+
+    const apiKey = config?.ngrok?.apiKey;
+    if (apiKey) {
+      console.log(`  Using existing API key: ${apiKey.slice(0, 8)}...`);
+      return { ...config, provider: "ngrok", ngrok: { ...config?.ngrok, apiKey } };
+    }
+
+    throw new Error(
+      "No API key found. Set it with:\n\n" +
+      "    pairshell-cli setup ngrok --api-key YOUR_KEY\n\n" +
+      "Or manually edit ~/.pairshell/config.json and add:\n" +
+      '  { "provider": "ngrok", "ngrok": { "apiKey": "YOUR_KEY" } }'
+    );
+  },
+
+  async startTunnel(port, config) {
+    try { await access(NGROK_PATH); } catch { await downloadNgrok(); }
+    await ngrokAuthtoken(config);
+
+    const domain = config?.ngrok?.domain;
+
+    return new Promise((resolve, reject) => {
+      const args = ["http", String(port), "--log=stdout", "--log-format=json"];
+      if (domain) args.push("--domain", domain);
+
+      const child = spawn(NGROK_PATH, args, { stdio: ["ignore", "pipe", "pipe"] });
+      let settled = false;
+
+      const fail = (msg) => {
+        if (settled) return;
+        settled = true;
+        try { child.kill("SIGTERM"); } catch {}
+        reject(new Error(msg));
+      };
+
+      child.on("error", (err) => fail(`Could not start ngrok: ${err.message}`));
+      child.on("exit", (code, signal) => {
+        if (!settled) fail(`ngrok exited (code ${code}, signal ${signal})`);
+      });
+
+      const feed = (chunk) => {
+        if (settled) return;
+        for (const line of chunk.toString().split("\n")) {
+          try {
+            const entry = JSON.parse(line);
+            if (entry.msg === "started tunnel") {
+              const url = entry.url;
+              if (url && !settled) {
+                settled = true;
+                resolve({ url, child });
+              }
+            }
+          } catch {}
+        }
+      };
+      child.stdout.on("data", feed);
+      child.stderr.on("data", feed);
+
+      setTimeout(() => fail("Timed out waiting for ngrok tunnel URL"), TUNNEL_TIMEOUT_MS);
+    });
+  },
+
+  printGuide() {
+    console.log(`
+  ${this.label} Setup Guide
+  ─────────────────
+
+  1. Sign up for a free ngrok account:
+     https://dashboard.ngrok.com/signup
+
+  2. Get your API key:
+     https://dashboard.ngrok.com/api-keys
+
+  3. Run setup with your API key:
+     pairshell-cli setup ngrok --api-key YOUR_KEY
+
+     Or edit ~/.pairshell/config.json:
+     { "provider": "ngrok", "ngrok": { "apiKey": "YOUR_KEY" } }
+
+  For a custom static domain (paid plan), add:
+  { "ngrok": { "apiKey": "YOUR_KEY", "domain": "your-domain.ngrok.io" } }
+
+  The ngrok binary auto-downloads on first use.
+`);
+  },
+};

package/src/providers/tailscale.js

@@ -0,0 +1,105 @@
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+
+const TAILSCALE_CMD = process.platform === "win32" ? "tailscale" : "tailscale";
+const TUNNEL_TIMEOUT_MS = 30000;
+
+async function getTailscaleStatus() {
+  return new Promise((resolve) => {
+    const child = spawn(TAILSCALE_CMD, ["status", "--json"], {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let out = "";
+    child.stdout.on("data", (c) => { out += c; });
+    child.on("close", () => {
+      try { resolve(JSON.parse(out)); } catch { resolve(null); }
+    });
+    child.on("error", () => resolve(null));
+  });
+}
+
+export const provider = {
+  name: "tailscale",
+  label: "Tailscale Funnel",
+
+  checkSetup(config) {
+    const enabled = config?.tailscale?.funnelEnabled;
+    if (enabled) return { ok: true, message: "Funnel is enabled" };
+    return { ok: false, message: "Funnel not configured. Run 'pairshell-cli setup tailscale'" };
+  },
+
+  async setup(config) {
+    const child = spawn(TAILSCALE_CMD, ["up"], {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+
+    await new Promise((resolve, reject) => {
+      child.on("close", (code) => {
+        if (code === 0) resolve();
+        else reject(new Error(`tailscale up failed (code ${code})`));
+      });
+      child.on("error", (err) => reject(new Error(`Cannot start tailscale: ${err.message}`)));
+    });
+
+    return { ...config, provider: "tailscale", tailscale: { ...config?.tailscale, funnelEnabled: true } };
+  },
+
+  async startTunnel(port, config) {
+    const serveArgs = ["funnel", "on", `--set-path=/`, String(port)];
+    await new Promise((resolve, reject) => {
+      const child = spawn(TAILSCALE_CMD, serveArgs, { stdio: ["ignore", "pipe", "pipe"] });
+      let out = "";
+      child.stdout.on("data", (c) => { out += c; });
+      child.stderr.on("data", (c) => { out += c; });
+      child.on("error", (err) => reject(new Error(`Cannot run tailscale funnel: ${err.message}`)));
+      child.on("exit", (code) => {
+        if (code === 0) resolve();
+        else reject(new Error(`tailscale funnel on failed: ${out.slice(0, 200)}`));
+      });
+    });
+
+    const url = await new Promise((resolve, reject) => {
+      const child = spawn(TAILSCALE_CMD, ["status", "--json"], {
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      let out = "";
+      child.stdout.on("data", (c) => { out += c; });
+      child.on("error", (err) => reject(new Error(`Cannot get tailscale status: ${err.message}`)));
+      child.on("exit", () => {
+        try {
+          const parsed = JSON.parse(out);
+          const dnsName = parsed?.Self?.DNSName?.replace(/\.$/, "") || "";
+          if (!dnsName) throw new Error("no DNSName");
+          resolve(`https://${dnsName}`);
+        } catch {
+          reject(new Error("Could not parse tailscale funnel URL"));
+        }
+      });
+    });
+
+    return { url, child: null };
+  },
+
+  printGuide() {
+    console.log(`
+  ${this.label} Setup Guide
+  ────────────────────────
+
+  1. Install Tailscale on this machine:
+     https://tailscale.com/download
+
+  2. Authenticate and connect to your tailnet:
+     tailscale up
+
+  3. Enable Funnel in the Tailscale admin console:
+     https://login.tailscale.com/admin/machines
+
+  4. Run setup:
+     pairshell-cli setup tailscale
+
+   The serve config persists across reboots. Traffic stays
+   within your tailnet; no third-party relay.
+`);
+  },
+};

package/src/pty-bridge.js

@@ -0,0 +1,78 @@
+import pty from "node-pty";
+import { encrypt, decrypt } from "./crypto.js";
+
+export function detectShell() {
+  if (process.platform === "win32") {
+    return process.env.COMSPEC || "cmd.exe";
+  }
+  return process.env.SHELL || "/bin/sh";
+}
+
+export function bridgeSession(ws, opts = {}) {
+  const shell = detectShell();
+  const cols = opts.cols && opts.cols > 0 ? opts.cols : 80;
+  const rows = opts.rows && opts.rows > 0 ? opts.rows : 24;
+  const sharedKey = opts.sharedKey || null;
+
+  const term = pty.spawn(shell, [], {
+    name: "xterm-256color",
+    cols,
+    rows,
+    cwd: process.cwd(),
+  });
+
+  let closed = false;
+  const cleanup = () => {
+    if (closed) return;
+    closed = true;
+    try { term.kill(); } catch {}
+    try { ws.close(); } catch {}
+  };
+
+  term.onData((data) => {
+    if (ws.readyState === ws.OPEN) {
+      if (sharedKey) {
+        ws.send(encrypt(data, sharedKey));
+      } else {
+        ws.send(Buffer.from(data));
+      }
+    }
+  });
+
+  term.onExit(() => cleanup());
+
+  const MAX_BINARY_FRAME = 1024 * 1024;
+
+  ws.on("message", (message) => {
+    if (Buffer.isBuffer(message)) {
+      if (message.length > MAX_BINARY_FRAME) return;
+      if (sharedKey) {
+        const plain = decrypt(message, sharedKey);
+        if (!plain) return;
+        term.write(plain);
+      } else {
+        term.write(message);
+      }
+      return;
+    }
+
+    let control;
+    try {
+      control = JSON.parse(message);
+    } catch {
+      return;
+    }
+    if (!control || typeof control.type !== "string") return;
+
+    if (control.type === "resize" && Number.isInteger(control.cols) && Number.isInteger(control.rows)) {
+      try { term.resize(control.cols, control.rows); } catch {}
+    } else if (control.type === "ping") {
+      try { ws.send(JSON.stringify({ type: "pong" })); } catch {}
+    }
+  });
+
+  ws.on("close", cleanup);
+  ws.on("error", cleanup);
+
+  return term;
+}

package/src/revoke.js

@@ -0,0 +1,55 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const ACTIVE_FILE = join(homedir(), ".pairshell", "active.json");
+
+function readActive() {
+  try {
+    return JSON.parse(readFileSync(ACTIVE_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export async function revokeCommand(opts) {
+  const active = readActive();
+  const port = opts.port || (active ? active.port : null);
+  if (!port) {
+    console.log("Cannot determine server port. Is a session running?\n");
+    console.log("  Start one with:  pairshell-cli start");
+    console.log("  Or specify:      pairshell-cli revoke --port <number>\n");
+    return;
+  }
+
+  const base = `http://127.0.0.1:${port}`;
+
+  const deviceId = opts.path;
+  if (deviceId) {
+    const res = await fetch(`${base}/revoke`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ deviceId }),
+    });
+    const data = await res.json();
+    if (data.revoked) {
+      console.log(`Revoked device: ${data.deviceId}`);
+    } else {
+      console.log(`Device not found: ${data.deviceId}`);
+    }
+    return;
+  }
+
+  console.log(`\n  Active sessions:\n`);
+  const res = await fetch(`${base}/sessions`);
+  const sessions = await res.json();
+  if (sessions.length === 0) {
+    console.log("  (no active sessions)\n");
+    return;
+  }
+  sessions.forEach((s, i) => {
+    const age = Math.floor((Date.now() - s.createdAt) / 1000);
+    console.log(`  [${i}] deviceId: ${s.deviceId}  (created ${age}s ago)`);
+  });
+  console.log(`\n  Revoke a device:  pairshell-cli revoke <device-id>\n`);
+}

package/src/session.js

@@ -0,0 +1,81 @@
+import { randomBytes } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const SESSION_FILE = join(homedir(), ".pairshell", "session-tokens.json");
+
+export class SessionStore {
+  constructor() {
+    this.sessions = new Map();
+    this._dirty = false;
+    this._load();
+  }
+
+  _load() {
+    try {
+      const data = JSON.parse(readFileSync(SESSION_FILE, "utf8"));
+      if (data && typeof data === "object") {
+        for (const [token, meta] of Object.entries(data)) {
+          if (token && meta?.deviceId) {
+            this.sessions.set(token, meta);
+          }
+        }
+      }
+    } catch {}
+  }
+
+  _save() {
+    if (!this._dirty) return;
+    const obj = Object.fromEntries(this.sessions.entries());
+    mkdirSync(join(homedir(), ".pairshell"), { recursive: true });
+    writeFileSync(SESSION_FILE, JSON.stringify(obj, null, 2), "utf8");
+    this._dirty = false;
+  }
+
+  create(deviceId) {
+    const token = randomBytes(32).toString("hex");
+    this.sessions.set(token, { deviceId, createdAt: Date.now() });
+    this._dirty = true;
+    this._save();
+    return token;
+  }
+
+  validate(token) {
+    if (!token) return null;
+    const meta = this.sessions.get(token);
+    return meta || null;
+  }
+
+  remove(token) {
+    if (this.sessions.delete(token)) {
+      this._dirty = true;
+      this._save();
+    }
+  }
+
+  list() {
+    const seen = new Map();
+    for (const [token, meta] of this.sessions) {
+      if (!seen.has(meta.deviceId)) {
+        seen.set(meta.deviceId, { ...meta, token });
+      }
+    }
+    return [...seen.values()];
+  }
+
+  revoke(deviceId) {
+    let removed = false;
+    for (const [token, meta] of this.sessions) {
+      if (meta.deviceId === deviceId) {
+        this.sessions.delete(token);
+        removed = true;
+      }
+    }
+    if (removed) {
+      this._dirty = true;
+      this._save();
+    }
+    return removed;
+  }
+}

package/src/setup.js

@@ -0,0 +1,44 @@
+import { readConfig, setProviderConfig, getProvider } from "./config.js";
+import { resolve } from "./providers/index.js";
+import { ok, info, warn, fail, header, kv, BOLD, RESET } from "./format.js";
+
+export async function setupCommand(opts) {
+  const providerName = opts.provider || getProvider();
+  const prov = resolve(providerName);
+
+  header(`PairShell Setup: ${prov.label}`);
+
+  const config = readConfig();
+  const existing = config[providerName];
+
+  if (existing && !opts.force) {
+    warn(`${prov.label} is already configured.`);
+    kv([[`${prov.name} config`, JSON.stringify(existing)]]);
+    console.log(`\n  Run ${BOLD}pairshell-cli start${RESET} to begin.\n`);
+    return;
+  }
+
+  info(`Setting up ${prov.label} ...`);
+
+  let newConfig;
+  try {
+    newConfig = await prov.setup(config);
+  } catch (err) {
+    fail(`Setup failed: ${err.message || err}`);
+    console.log();
+    prov.printGuide();
+    process.exit(1);
+  }
+
+  setProviderConfig(providerName, newConfig[providerName]);
+  ok(`${prov.label} configured and saved`);
+
+  header("Configuration");
+  kv([
+    ["Provider", prov.label],
+    [`${prov.name} config`, JSON.stringify(newConfig[providerName])],
+    ["Config file", "~/.pairshell/config.json"],
+  ]);
+
+  console.log(`\n  Run ${BOLD}pairshell-cli start${RESET} to begin.\n`);
+}