handmux 0.5.0

package/src/cli/qr.js

@@ -0,0 +1,34 @@
+// Terminal QR using vertical half-blocks: each character stacks TWO module rows (top + bottom) in one cell,
+// one module wide. A terminal cell is ~2× taller than wide, so a 1-wide × 2-tall module pair renders as a
+// SQUARE module — the whole code comes out square and scans cleanly.
+//
+// (The earlier 2×2 "quadrant" packing was half the width, but putting 2 modules across a 2:1 cell made each
+// module twice as tall as wide, stretching the whole code vertically. Square + scannable beats narrow.)
+//
+// Polarity: a LIGHT module (quiet zone / non-ink) renders bright, a DARK (ink) module renders empty — so on
+// a dark terminal it reads as a black code on a white field, the quiet zone being the white border.
+//
+// matrix[r][c] === true means a DARK module. renderCompactQr is pure (no I/O) so it's unit-tested; the CLI
+// builds the matrix from qrcode-terminal's QR model and hands it here.
+
+export function renderCompactQr(matrix, { quiet = 2 } = {}) {
+  const n = matrix.length;
+  const side = n + quiet * 2;
+  // A module is LIGHT when it's outside the code (quiet zone, incl. a dangling final half-row) or the matrix
+  // cell is not dark.
+  const light = (r, c) => {
+    const mr = r - quiet, mc = c - quiet;
+    if (mr < 0 || mr >= n || mc < 0 || mc >= n) return true;
+    return !matrix[mr][mc];
+  };
+  let out = '';
+  for (let r = 0; r < side; r += 2) {
+    for (let c = 0; c < side; c++) {
+      const top = light(r, c);
+      const bottom = light(r + 1, c); // overflow row (odd side) is out-of-range → LIGHT, i.e. quiet border
+      out += top && bottom ? '█' : top ? '▀' : bottom ? '▄' : ' ';
+    }
+    out += '\n';
+  }
+  return out;
+}

package/src/cli/service.js

@@ -0,0 +1,98 @@
+// Boot/login autostart. The OS keeps the handmux SUPERVISOR (`__supervise`) alive; the supervisor
+// keeps server + tunnel alive — same model as a foreground run, just parented by launchd/systemd.
+// The intended config is baked into the service file as a base64 payload (self-contained: no reliance
+// on config.json). Text generators are pure (unit-tested); the launchctl/systemctl calls inject `exec`.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pocketHome, logPath } from './state.js';
+
+export const LABEL = 'com.handmux.agent';
+export const UNIT = 'handmux.service';
+
+export function plistPath(home) { return path.join(home, 'Library', 'LaunchAgents', `${LABEL}.plist`); }
+export function unitPath(home) { return path.join(home, '.config', 'systemd', 'user', UNIT); }
+
+const xmlEscape = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+// launchd LaunchAgent. args = full argv for the process (node, script, __supervise, --payload, b64).
+export function plistFor({ args, log, label = LABEL }) {
+  const items = args.map((a) => `    <string>${xmlEscape(a)}</string>`).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${label}</string>
+  <key>ProgramArguments</key>
+  <array>
+${items}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${xmlEscape(log)}</string>
+  <key>StandardErrorPath</key><string>${xmlEscape(log)}</string>
+</dict>
+</plist>
+`;
+}
+
+// systemd --user unit. ExecStart needs a single command line; args are space-joined (our args have no
+// spaces except an absolute path with none in practice — quote the script path defensively).
+export function unitFor({ args }) {
+  const cmd = args.map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ');
+  return `[Unit]
+Description=handmux — drive your tmux from your phone
+After=network-online.target
+
+[Service]
+ExecStart=${cmd}
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export function installService(args, { home, platform = process.platform, exec = spawnSync, log = console } = {}) {
+  if (platform === 'darwin') {
+    const p = plistPath(home);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, plistFor({ args, log: logPath(home) }));
+    exec('launchctl', ['unload', p], { stdio: 'ignore' }); // best-effort: clear any prior load
+    const r = exec('launchctl', ['load', '-w', p], { encoding: 'utf8' });
+    if (r.status !== 0) throw new Error(`launchctl load failed: ${r.stderr || r.status}`);
+    log.log?.(`installed launchd agent: ${p}`);
+    return p;
+  }
+  if (platform === 'linux') {
+    const p = unitPath(home);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, unitFor({ args }));
+    exec('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' });
+    const r = exec('systemctl', ['--user', 'enable', '--now', UNIT], { encoding: 'utf8' });
+    if (r.status !== 0) throw new Error(`systemctl enable failed: ${r.stderr || r.status}`);
+    log.log?.(`installed systemd --user unit: ${p}`);
+    log.log?.('(for autostart before login: loginctl enable-linger "$USER")');
+    return p;
+  }
+  throw new Error(`autostart not supported on ${platform} yet`);
+}
+
+export function uninstallService({ home, platform = process.platform, exec = spawnSync, log = console } = {}) {
+  if (platform === 'darwin') {
+    const p = plistPath(home);
+    exec('launchctl', ['unload', '-w', p], { stdio: 'ignore' });
+    try { fs.unlinkSync(p); } catch { /* already gone */ }
+    log.log?.(`removed launchd agent: ${p}`);
+    return;
+  }
+  if (platform === 'linux') {
+    exec('systemctl', ['--user', 'disable', '--now', UNIT], { stdio: 'ignore' });
+    try { fs.unlinkSync(unitPath(home)); } catch { /* already gone */ }
+    exec('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' });
+    log.log?.(`removed systemd --user unit: ${unitPath(home)}`);
+    return;
+  }
+  throw new Error(`autostart not supported on ${platform} yet`);
+}

package/src/cli/setupWizard.js

@@ -0,0 +1,248 @@
+// `handmux setup` wizard. Pure mappers (config shape, cloudflared config.yml, parsing tunnel create
+// output) are split out and unit-tested; the readline/spawn shell (runSetup, added in the next task) is
+// thin glue on top.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import webpush from 'web-push';
+import { configPath, pocketHome } from './state.js';
+import { resolveCloudflared } from './cloudflared.js';
+import { resolveTunlite, checkSshAuth } from './tunlite.js';
+
+// ~/.cloudflared/config.yml for a named tunnel: route the hostname to the local handmux port.
+export function cfConfigYaml({ tunnelName, credentialsFile, hostname, port }) {
+  return [
+    `tunnel: ${tunnelName}`,
+    `credentials-file: ${credentialsFile}`,
+    'ingress:',
+    `  - hostname: ${hostname}`,
+    `    service: http://localhost:${port}`,
+    '  - service: http_status:404',
+    '',
+  ].join('\n');
+}
+
+// Extract the tunnel UUID + credentials path from `cloudflared tunnel create <name>` stdout.
+export function parseTunnelCreate(out) {
+  const s = String(out || '');
+  const id = (s.match(/Created tunnel \S+ with id ([0-9a-fA-F-]+)/) || [])[1] || null;
+  const credentialsFile = (s.match(/credentials written to (\S+\.json)/i) || [])[1]?.replace(/\.$/, '') || null;
+  return { id, credentialsFile };
+}
+
+// Find an existing named tunnel's UUID in `cloudflared tunnel list --output json`. A named tunnel is a
+// PERSISTENT object in the Cloudflare account, so a second `setup` would hit `cloudflared tunnel create`'s
+// "tunnel with name X already exists" error — which used to force a rename and pile up junk tunnels in the
+// account. Looking it up first lets provisioning REUSE it idempotently. Tolerates non-JSON / errors → null.
+export function findTunnelId(listJsonOut, name) {
+  let arr;
+  try { arr = JSON.parse(String(listJsonOut || '')); } catch { return null; }
+  if (!Array.isArray(arr)) return null;
+  const hit = arr.find((t) => t && t.name === name);
+  return hit?.id || null;
+}
+
+// The config keys the wizard owns: everything it asks about. mergeConfig wipes these from the existing
+// config before re-applying the answers, so a blank answer (or an unselected tunnel) cleanly clears the
+// old value instead of leaving a stale field behind. Anything NOT here (token, staticDir, previewDomain…)
+// is preserved untouched.
+const WIZARD_KEYS = [
+  'name', 'port', 'tunnel',
+  'sshHost', 'remotePort', 'sshJump', 'cfHostname', 'cfTunnelName', 'publicUrl',
+  'vapid', 'xfyun',
+];
+
+// Wizard answers → the config fragment the user actually set (omit empty optional fields).
+export function configFromAnswers(a) {
+  const cfg = { tunnel: a.tunnel, port: a.port };
+  if (a.name) cfg.name = a.name;
+  if (a.tunnel === 'ssh') {
+    cfg.sshHost = a.sshHost;
+    cfg.remotePort = a.remotePort;
+    if (a.publicUrl) cfg.publicUrl = a.publicUrl;
+    if (a.sshJump) cfg.sshJump = a.sshJump;
+  }
+  if (a.tunnel === 'cloudflare-named') {
+    cfg.cfHostname = a.cfHostname;
+    cfg.cfTunnelName = a.cfTunnelName;
+  }
+  if (a.vapid) cfg.vapid = a.vapid;
+  if (a.xfyun) cfg.xfyun = a.xfyun;
+  return cfg;
+}
+
+// Fold this run's answers into an existing config: preserve every non-wizard field, replace the wizard's
+// own fields wholesale. This is why re-running `setup` to switch tunnels (or edit the name) never drops
+// your token / push keys / static dir, yet also never leaves the previous tunnel's stale keys around.
+export function mergeConfig(existing = {}, answers) {
+  const out = { ...existing };
+  for (const k of WIZARD_KEYS) delete out[k];
+  return { ...out, ...configFromAnswers(answers) };
+}
+
+const ask = (rl, q, dflt) => new Promise((res) =>
+  rl.question(dflt ? `${q} [${dflt}] ` : `${q} `, (a) => res((a.trim() || dflt || ''))));
+
+// [y/N] / [Y/n] prompt. `dfltYes` sets which way a bare Enter goes.
+const askYesNo = async (rl, q, dfltYes) => {
+  const a = (await ask(rl, `${q} ${dfltYes ? '[Y/n]' : '[y/N]'}`, '')).trim().toLowerCase();
+  if (a === '') return dfltYes;
+  return a === 'y' || a === 'yes';
+};
+
+function readExisting(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return {}; }
+}
+
+// Interactive wizard — the one place to configure handmux. Pre-fills from the existing config so a re-run
+// edits/switches rather than starts over, asks name → tunnel → push → voice, and merges the answers back
+// (preserving fields it didn't ask about). Returns the resolved config (or null on abort). `home` and the
+// write `target` are injectable for tests / `--config`.
+export async function runSetup({ home = homedir(), target = configPath(home), log = console } = {}) {
+  if (!process.stdin.isTTY) { log.error('handmux setup needs an interactive terminal'); return null; }
+  const cur = readExisting(target);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const name = await ask(rl, 'app name (shown in the browser tab / home-screen icon; blank = default)', cur.name || '');
+
+    log.log('How should your phone reach this machine?');
+    log.log('  1) none              — same Wi-Fi / LAN only');
+    log.log('  2) cloudflare        — instant, random temporary https URL');
+    log.log('  3) cloudflare-named  — your domain, stable HTTPS (most hands-off)');
+    log.log('  4) ssh (tunlite)     — your own server / edge');
+    const curPick = { none: '1', cloudflare: '2', 'cloudflare-named': '3', ssh: '4' }[cur.tunnel] || '3';
+    const pick = await ask(rl, 'choose 1-4', curPick);
+    const tunnel = { 1: 'none', 2: 'cloudflare', 3: 'cloudflare-named', 4: 'ssh' }[pick];
+    if (!tunnel) { log.error('invalid choice'); return null; }
+    const port = Number(await ask(rl, 'server port', String(cur.port || 19999)));
+
+    const answers = { name, tunnel, port };
+    if (tunnel === 'cloudflare-named') {
+      answers.cfHostname = await ask(rl, 'public hostname (e.g. handmux.example.com)', cur.cfHostname || '');
+      answers.cfTunnelName = await ask(rl, 'tunnel name', cur.cfTunnelName || 'handmux');
+      await provisionCloudflareNamed({ home, hostname: answers.cfHostname, tunnelName: answers.cfTunnelName, port, log });
+    } else if (tunnel === 'ssh') {
+      answers.sshHost = await ask(rl, 'ssh host (user@host[:port])', cur.sshHost || '');
+      answers.remotePort = Number(await ask(rl, 'remote port on the ssh host', String(cur.remotePort || port)));
+      answers.publicUrl = await ask(rl, 'public url (blank = http://host:remotePort)', cur.publicUrl || '');
+      await provisionSsh({ sshHost: answers.sshHost, log });
+    }
+
+    answers.vapid = await askPush(rl, cur.vapid, log);
+    answers.xfyun = await askVoice(rl, cur.xfyun, log);
+
+    const cfg = mergeConfig(cur, answers);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+    log.log(`✓ wrote ${target}`);
+    if (tunnel === 'ssh') printSshServerHelp(answers, log);
+    if (tunnel === 'cloudflare-named' || tunnel === 'ssh') printPreviewHelp(tunnel, log);
+    return cfg;
+  } finally { rl.close(); }
+}
+
+// Push notifications need a VAPID keypair. If one already exists we offer to keep it (regenerating would
+// invalidate every existing phone subscription); otherwise we generate one on the spot — the only painful
+// part of push setup, done for the user. Returns the vapid object, or undefined to leave push off.
+async function askPush(rl, existing, log) {
+  if (existing) {
+    if (await askYesNo(rl, 'keep push notifications configured?', true)) return existing;
+    return undefined;
+  }
+  if (!await askYesNo(rl, 'set up push notifications now? (generates VAPID keys)', false)) return undefined;
+  const { publicKey, privateKey } = webpush.generateVAPIDKeys();
+  const subject = await ask(rl, 'contact (mailto: or https URL, for the push service)', 'mailto:admin@example.com');
+  log.log('✓ generated VAPID keypair');
+  return { public: publicKey, private: privateKey, subject };
+}
+
+// Voice input (iFlytek/xfyun) — three credentials from their console; no generation possible, just paste.
+async function askVoice(rl, existing, log) {
+  if (existing) {
+    if (await askYesNo(rl, 'keep voice input configured?', true)) return existing;
+    return undefined;
+  }
+  if (!await askYesNo(rl, 'set up voice input now? (needs iFlytek/xfyun keys)', false)) return undefined;
+  const appId = await ask(rl, 'xfyun appId');
+  const apiKey = await ask(rl, 'xfyun apiKey');
+  const apiSecret = await ask(rl, 'xfyun apiSecret');
+  if (!appId || !apiKey || !apiSecret) { log.log('  (skipped — missing fields)'); return undefined; }
+  return { appId, apiKey, apiSecret };
+}
+
+// login (browser) → create → route dns → write config.yml. The only human step is the browser login.
+async function provisionCloudflareNamed({ home, hostname, tunnelName, port, log }) {
+  const bin = await resolveCloudflared(home);
+  const cfDir = path.join(home, '.cloudflared');
+  if (!fs.existsSync(path.join(cfDir, 'cert.pem'))) {
+    log.log('→ logging in to Cloudflare (a browser will open) …');
+    spawnSync(bin, ['tunnel', 'login'], { stdio: 'inherit' });
+  }
+  // Idempotent: reuse the tunnel if it already exists (re-running setup, or after a stop), else create it.
+  // Without this, `tunnel create` errors "already exists" and you'd have to keep renaming — leaving orphan
+  // tunnels piling up in the Cloudflare account.
+  const listed = spawnSync(bin, ['tunnel', 'list', '--output', 'json'], { encoding: 'utf8' });
+  let id = findTunnelId(listed.stdout, tunnelName);
+  let credentialsFile = null;
+  if (id) {
+    log.log(`✓ reusing existing tunnel ${tunnelName} (${id})`);
+    credentialsFile = path.join(cfDir, `${id}.json`);
+    if (!fs.existsSync(credentialsFile)) {
+      log.error(`⚠ credentials file ${credentialsFile} not found on this machine — the tunnel was likely`);
+      log.error(`  created elsewhere. Run \`${bin} tunnel delete ${tunnelName}\` and re-run setup to recreate it here.`);
+    }
+  } else {
+    log.log(`→ creating tunnel ${tunnelName} …`);
+    const created = spawnSync(bin, ['tunnel', 'create', tunnelName], { encoding: 'utf8' });
+    process.stdout.write(created.stdout || ''); process.stderr.write(created.stderr || '');
+    const parsed = parseTunnelCreate(`${created.stdout || ''}\n${created.stderr || ''}`);
+    id = parsed.id;
+    credentialsFile = parsed.credentialsFile;
+  }
+  log.log(`→ routing ${hostname} → tunnel …`);
+  // --overwrite-dns: re-running setup (or pointing a hostname already routed) must not error on the DNS step.
+  const routed = spawnSync(bin, ['tunnel', 'route', 'dns', '--overwrite-dns', tunnelName, hostname], { encoding: 'utf8' });
+  if (routed.status !== 0) {
+    process.stderr.write(routed.stderr || '');
+    log.error(`⚠ route dns failed — is ${hostname.split('.').slice(-2).join('.')}'s DNS hosted on Cloudflare?`);
+    log.error('  Add the domain on Cloudflare (free) and point its nameservers there, then re-run setup.');
+  }
+  fs.mkdirSync(cfDir, { recursive: true });
+  fs.writeFileSync(path.join(cfDir, 'config.yml'),
+    cfConfigYaml({ tunnelName, credentialsFile: credentialsFile || path.join(cfDir, `${id || tunnelName}.json`), hostname, port }));
+  log.log(`✓ wrote ${path.join(cfDir, 'config.yml')}`);
+}
+
+// drive tunlite passwordless setup inline (one password) if not already set up.
+async function provisionSsh({ sshHost, log }) {
+  const bin = resolveTunlite();
+  if (checkSshAuth(sshHost, { bin }) === 0) { log.log('✓ passwordless SSH already set up'); return; }
+  log.log(`→ setting up passwordless SSH to ${sshHost} (you'll enter the password once) …`);
+  spawnSync(bin, ['setup-key', sshHost], { stdio: 'inherit' });
+}
+
+function printSshServerHelp(a, log) {
+  log.log('');
+  log.log('Server side (one-time): point a reverse proxy at the forwarded loopback port.');
+  log.log(`  nginx:  proxy_pass http://127.0.0.1:${a.remotePort};  (add client_max_body_size 60m; proxy_read_timeout 90s;)`);
+  log.log(`  caddy:  ${a.publicUrl || '<your-domain>'} {  reverse_proxy 127.0.0.1:${a.remotePort}  }`);
+  log.log('');
+}
+
+// FYI on dynamic port preview: it's optional and NOT wired by this wizard (separate wildcard domain). Print
+// the requirement + a TLS note that fits the chosen tunnel — Cloudflare's free cert only covers one level
+// (so deeper needs ACM), whereas on the ssh/own-edge path the user serves their own wildcard cert. Shown
+// only for wildcard-capable tunnels (a quick tunnel can't do wildcards at all).
+function printPreviewHelp(tunnel, log) {
+  log.log('Optional — dynamic port preview (open a dev server by port on your phone):');
+  log.log('  set  "previewDomain": "..."  in the config, and route the wildcard preview domain to the gateway.');
+  if (tunnel === 'cloudflare-named') {
+    log.log("  TLS: Cloudflare's free cert covers ONE level (*.example.com); deeper (*.preview.example.com) needs Advanced Certificate Manager.");
+  } else {
+    log.log("  TLS: your edge serves the wildcard cert (e.g. a Let's Encrypt *.preview.your.domain).");
+  }
+  log.log('');
+}

package/src/cli/sshTunnel.js

@@ -0,0 +1,12 @@
+// Pure: detect tunlite `run --json` reaching the `connected` state from an NDJSON log chunk. tunlite
+// self-reconnects, so we only flip to "live" on a real connected event (mirrors cloudflare URL-scrape:
+// don't surface the public URL until the tunnel is actually up). Side-effect-free → unit-tested against
+// real captured NDJSON lines.
+export function isTunnelConnected(text) {
+  for (const line of String(text || '').split('\n')) {
+    const s = line.trim();
+    if (!s) continue;
+    try { if (JSON.parse(s).state === 'connected') return true; } catch { /* partial / non-json line */ }
+  }
+  return false;
+}

package/src/cli/state.js

@@ -0,0 +1,42 @@
+// Runtime state lives in ~/.handmux/ — a single state.json (pids + the live public URL) plus a log
+// file the detached supervisor writes to. `home` is injectable so this unit-tests in a temp dir.
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+
+export function pocketHome(home = homedir()) { return path.join(home, '.handmux'); }
+export function statePath(home) { return path.join(pocketHome(home), 'state.json'); }
+export function logPath(home) { return path.join(pocketHome(home), 'handmux.log'); }
+export function configPath(home) { return path.join(pocketHome(home), 'config.json'); }
+
+// The hook-maintained Claude state file, on a stable per-user path (survives a global reinstall, unlike
+// the package-internal server/data default). The CLI sets this as CLAUDE_STATE_FILE for the server child
+// and writes the same path into the hook's env, so both ends read/write one file.
+export function claudeStatePath(home) { return path.join(pocketHome(home), 'claude-state.json'); }
+
+// Push subscriptions and the dynamic-preview registry are mutable runtime data too, so they belong on the
+// same stable per-user path — NOT the package-internal server/data default, which a `npm i -g handmux`
+// reinstall replaces (silently dropping every saved subscription). The CLI injects these as PUSH_STORE /
+// PREVIEW_STORE for the server child.
+export function pushStorePath(home) { return path.join(pocketHome(home), 'push-subs.json'); }
+export function previewStorePath(home) { return path.join(pocketHome(home), 'previews.json'); }
+
+export function readState(home) {
+  try { return JSON.parse(fs.readFileSync(statePath(home), 'utf8')); } catch { return null; }
+}
+
+export function writeState(state, home) {
+  fs.mkdirSync(pocketHome(home), { recursive: true });
+  fs.writeFileSync(statePath(home), JSON.stringify(state, null, 2));
+}
+
+export function clearState(home) {
+  try { fs.unlinkSync(statePath(home)); } catch { /* already gone */ }
+}
+
+// pid liveness without sending a real signal: kill(pid, 0) throws ESRCH if dead, EPERM if alive but
+// not ours (still counts as running).
+export function isAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}

package/src/cli/supervisor.js

@@ -0,0 +1,172 @@
+// The single long-running supervisor. It owns the node server (and, for a process-backed tunnel like
+// cloudflare, the tunnel) as CHILD processes, restarts them with a small backoff on exit, and records
+// the live public URL into state.json. There is only ever one daemon here — cloudflared (and, later,
+// `tunlite run`) are just its children, exactly like the server is.
+import { spawn } from 'node:child_process';
+import net from 'node:net';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { getDriver } from './drivers.js';
+import { writeState, clearState, claudeStatePath, pushStorePath, previewStorePath } from './state.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const SERVER = path.resolve(here, '../server.js');
+
+// First non-internal IPv4 — the address a phone on the same wifi uses when there's no tunnel.
+export function lanUrl(port, ifaces = os.networkInterfaces()) {
+  for (const list of Object.values(ifaces)) {
+    for (const ni of list || []) {
+      if (ni.family === 'IPv4' && !ni.internal) return `http://${ni.address}:${port}`;
+    }
+  }
+  return null;
+}
+
+// The token rides in the query string so the first navigation (or a QR scan) authenticates in one shot.
+export function publicUrlWithToken(base, token) {
+  if (!base) return base;
+  return `${base.replace(/\/$/, '')}/?token=${encodeURIComponent(token)}`;
+}
+
+// Bare address with no token in it — printed/QR-encoded so a link can be shared or screenshotted without
+// leaking the secret; the token is shown separately for the user to paste in.
+export function bareUrl(base) {
+  if (!base) return base;
+  return `${base.replace(/\/$/, '')}/`;
+}
+
+export function supervise(cfg, { home, log = console } = {}) {
+  const driver = getDriver(cfg.tunnel);
+  const children = {};
+  let stopping = false;
+  let urlBuf = '';
+  let backoff = 500;
+
+  const state = {
+    supervisorPid: process.pid,
+    startedAt: Date.now(),
+    tunnel: cfg.tunnel,
+    port: cfg.port,
+    host: cfg.host,
+    token: cfg.token,
+    previewDomain: cfg.previewDomain || null,
+    localUrl: `http://localhost:${cfg.port}`,
+    lanUrl: lanUrl(cfg.port),
+    publicUrl: null,
+    ready: false,
+    error: null,
+  };
+  const persist = () => writeState(state, home);
+  persist();
+
+  // The server socket comes up a beat after spawn; don't report "ready" (and don't let the CLI print an
+  // access URL) until a TCP connect to it actually succeeds, or callers race an unbound port.
+  const waitListening = () => {
+    if (stopping || state.ready) return;
+    const s = net.connect({ port: cfg.port, host: '127.0.0.1' });
+    const retry = () => { s.destroy(); if (!stopping) setTimeout(waitListening, 200); };
+    s.setTimeout(500, retry);
+    s.once('error', retry);
+    s.once('connect', () => { s.destroy(); state.ready = true; persist(); });
+  };
+
+  const startServer = () => {
+    // The server reads only process.env (no .env files) — the CLI resolved the one config file and we
+    // hand the server everything it needs here. This is the single injection point: config.json fields →
+    // the env names the server already reads (HANDMUX_* / VAPID_* / XFYUN_*).
+    const env = {
+      ...process.env,
+      NODE_ENV: 'handmux',
+      HANDMUX_PORT: String(cfg.port),
+      HANDMUX_HOST: cfg.host,
+      HANDMUX_TOKEN: cfg.token,
+      CLAUDE_STATE_FILE: claudeStatePath(home),
+      PUSH_STORE: pushStorePath(home),
+      PREVIEW_STORE: previewStorePath(home),
+    };
+    if (cfg.previewDomain) env.HANDMUX_PREVIEW_DOMAIN = cfg.previewDomain;
+    if (cfg.name) env.HANDMUX_APP_NAME = cfg.name;
+    if (cfg.staticDir) env.HANDMUX_STATIC_DIR = cfg.staticDir;
+    if (cfg.uploadExts) env.HANDMUX_UPLOAD_EXTS = cfg.uploadExts;
+    if (cfg.previewTtl) env.HANDMUX_PREVIEW_TTL = String(cfg.previewTtl);
+    if (cfg.vapid) {
+      if (cfg.vapid.public) env.VAPID_PUBLIC = cfg.vapid.public;
+      if (cfg.vapid.private) env.VAPID_PRIVATE = cfg.vapid.private;
+      if (cfg.vapid.subject) env.VAPID_SUBJECT = cfg.vapid.subject;
+    }
+    if (cfg.xfyun) {
+      if (cfg.xfyun.appId) env.XFYUN_APPID = cfg.xfyun.appId;
+      if (cfg.xfyun.apiKey) env.XFYUN_APIKEY = cfg.xfyun.apiKey;
+      if (cfg.xfyun.apiSecret) env.XFYUN_APISECRET = cfg.xfyun.apiSecret;
+    }
+    const c = spawn(process.execPath, [SERVER], { env, stdio: ['ignore', 'inherit', 'inherit'] });
+    children.server = c;
+    state.serverPid = c.pid; persist();
+    c.on('exit', () => { if (!stopping) backoffRestart('server', startServer); });
+  };
+
+  const startTunnel = () => {
+    if (!driver.needsProcess) { // 'none' — reachable directly on LAN/localhost (or a tunnel you run yourself)
+      state.publicUrl = cfg.publicUrl || state.lanUrl || state.localUrl; persist(); return;
+    }
+    const spec = driver.proc(cfg);
+    const c = spawn(spec.cmd, spec.args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    children.tunnel = c;
+    state.tunnelPid = c.pid; persist();
+    const onData = (b) => {
+      const s = b.toString();
+      process.stdout.write(s);
+      if (state.publicUrl) return;
+      urlBuf = (urlBuf + s).slice(-4000);
+      const url = driver.matchUrl(urlBuf, cfg);
+      if (url) { state.publicUrl = url; state.error = null; backoff = 500; persist(); }
+    };
+    c.stdout.on('data', onData);
+    c.stderr.on('data', onData);
+    c.on('error', (e) => {
+      state.error = e.code === 'ENOENT'
+        ? (driver.notFoundHint || `${spec.cmd} not found`)
+        : String(e);
+      persist();
+    });
+    c.on('exit', () => { if (!stopping) { state.publicUrl = null; persist(); backoffRestart('tunnel', startTunnel); } });
+  };
+
+  const backoffRestart = (what, fn) => {
+    const d = Math.min(backoff, 15000);
+    backoff = Math.min(backoff * 2, 15000);
+    log.warn?.(`[handmux] ${what} exited; restarting in ${d}ms`);
+    setTimeout(() => { if (!stopping) fn(); }, d);
+  };
+
+  const shutdown = () => {
+    stopping = true;
+    const kids = Object.values(children).filter(Boolean);
+    for (const c of kids) { try { c.kill('SIGTERM'); } catch { /* already dead */ } }
+    clearState(home);
+    // Don't exit on a fixed timer — that orphans any child still shutting down (a SIGKILL'd or crashed
+    // supervisor was how a stray cloudflared kept running after `stop`). Poll until the children are gone,
+    // then SIGKILL any straggler so we NEVER leak a tunnel process. With --grace-period 0s, cloudflared
+    // exits near-instantly; the 3s ceiling is just a backstop.
+    const alive = () => kids.filter((c) => { try { process.kill(c.pid, 0); return true; } catch { return false; } });
+    let waited = 0;
+    const tick = () => {
+      const left = alive();
+      if (left.length === 0 || waited >= 3000) {
+        for (const c of left) { try { c.kill('SIGKILL'); } catch { /* already dead */ } }
+        process.exit(0);
+      }
+      waited += 150;
+      setTimeout(tick, 150);
+    };
+    tick();
+  };
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+
+  startServer();
+  startTunnel();
+  waitListening();
+  return { state };
+}