clickroom 0.0.0-stage → 0.2.0

package/cli/config.js

@@ -0,0 +1,140 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const SITE_P = path.join(ROOT, 'site', 'p');
+// Renamed from protoshare.local.json when the tool became clickroom.
+const OLD_LOCAL_CONFIG = path.join(ROOT, 'protoshare.local.json');
+if (!fs.existsSync(path.join(ROOT, 'clickroom.local.json')) && fs.existsSync(OLD_LOCAL_CONFIG)) fs.renameSync(OLD_LOCAL_CONFIG, path.join(ROOT, 'clickroom.local.json'));
+const DEV_VARS = path.join(ROOT, '.dev.vars');
+export const NAME_RE = /^[a-z0-9][a-z0-9-]{0,40}$/;
+
+// Comments and versions live outside the repo so cleaning it (e.g. deleting .wrangler)
+// can't lose feedback. CLICKROOM_HOME overrides the location.
+export const HOME = process.env.CLICKROOM_HOME || path.join(os.homedir(), '.clickroom');
+export const STATE_DIR = path.join(HOME, 'state');
+export const BACKUP_DIR = path.join(HOME, 'backups');
+// The projects shared from this computer: next to the clickroom code for the owner's checkout
+// (where it always was), in ~/.clickroom for an installed clickroom (npm i -g clickroom).
+const LOCAL_CONFIG = fs.existsSync(path.join(ROOT, 'clickroom.local.json')) || fs.existsSync(DEV_VARS) ? path.join(ROOT, 'clickroom.local.json') : path.join(HOME, 'config.json');
+// `clickroom login`: a teammate's own key for a clickroom server ({ url, token, name, email }).
+const CREDENTIALS = path.join(HOME, 'credentials.json');
+
+// Where the CLI, MCP server and project sessions talk to: the cloud deployment once
+// `clickroom cloud setup` has run, otherwise the local server. CLICKROOM_URL overrides both.
+export function baseUrl() {
+  return (process.env.CLICKROOM_URL || cloudUrl() || localUrl()).replace(/\/$/, '');
+}
+
+export function cloudUrl() {
+  return readLocal().cloudUrl || (isTeammate() && credentials()?.url) || null;
+}
+
+export function localUrl() {
+  return `http://localhost:${readLocal().port || 8787}`;
+}
+
+// What the CLI signs its calls with: the admin key on the owner's Mac, or else the key a
+// teammate got from `clickroom login`. CLICKROOM_TOKEN (a teammate's key) overrides both.
+export function authToken() {
+  return process.env.CLICKROOM_TOKEN || adminToken() || credentials()?.token || null;
+}
+
+// A teammate's CLI (not the owner's): pushes upload their builds and the project only shows
+// pushed versions.
+export function isTeammate() {
+  return !!process.env.CLICKROOM_TOKEN || (!adminToken() && !!credentials()?.token);
+}
+
+export function credentials() {
+  try {
+    return JSON.parse(fs.readFileSync(CREDENTIALS, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function saveCredentials(c) {
+  fs.mkdirSync(HOME, { recursive: true });
+  if (c) fs.writeFileSync(CREDENTIALS, JSON.stringify(c, null, 2) + '\n', { mode: 0o600 });
+  else fs.rmSync(CREDENTIALS, { force: true });
+}
+
+// Admin token shared by the worker (.dev.vars) and the CLI/MCP.
+export function adminToken({ create = false } = {}) {
+  if (process.env.CLICKROOM_ADMIN_TOKEN) return process.env.CLICKROOM_ADMIN_TOKEN;
+  if (fs.existsSync(DEV_VARS)) {
+    const m = fs.readFileSync(DEV_VARS, 'utf8').match(/^ADMIN_TOKEN\s*=\s*"?([^"\n]+)"?/m);
+    if (m) return m[1].trim();
+  }
+  if (!create) return null;
+  const token = crypto.randomBytes(18).toString('hex');
+  const prev = fs.existsSync(DEV_VARS) ? fs.readFileSync(DEV_VARS, 'utf8').replace(/\n?$/, '\n') : '';
+  fs.writeFileSync(DEV_VARS, `${prev}ADMIN_TOKEN=${token}\n`, { mode: 0o600 });
+  return token;
+}
+
+// Local-only bookkeeping: where static projects are copied from, and whether to watch them.
+export function readLocal() {
+  try {
+    return JSON.parse(fs.readFileSync(LOCAL_CONFIG, 'utf8'));
+  } catch {
+    return { projects: {} };
+  }
+}
+
+export function writeLocal(cfg) {
+  fs.mkdirSync(path.dirname(LOCAL_CONFIG), { recursive: true });
+  fs.writeFileSync(LOCAL_CONFIG, JSON.stringify(cfg, null, 2) + '\n');
+}
+
+const SKIP = new Set(['node_modules', '.git', '.DS_Store']);
+
+// Copies a build into site/p/<name> (unversioned) or site/p/<name>/v<version> (a pushed
+// snapshot). Snapshot folders are never touched by an unversioned copy.
+export function copyBuild(name, source, version = null) {
+  const src = path.resolve(source);
+  if (!fs.existsSync(src) || !fs.statSync(src).isDirectory()) throw new Error(`Not a directory: ${src}`);
+  if (!fs.existsSync(path.join(src, 'index.html'))) {
+    console.warn(`warning: ${src} has no index.html, so the review opens on a 404 until you navigate to a page.`);
+  }
+  const dest = version == null ? path.join(SITE_P, name) : path.join(SITE_P, name, `v${version}`);
+  const tmp = `${dest}.tmp-${process.pid}`;
+  fs.rmSync(tmp, { recursive: true, force: true });
+  fs.cpSync(src, tmp, { recursive: true, filter: (p) => !SKIP.has(path.basename(p)) });
+  if (version == null && fs.existsSync(dest)) {
+    for (const entry of fs.readdirSync(dest)) {
+      if (/^v\d+$/.test(entry)) fs.renameSync(path.join(dest, entry), path.join(tmp, entry));
+    }
+  }
+  fs.rmSync(dest, { recursive: true, force: true });
+  fs.renameSync(tmp, dest);
+  return dest;
+}
+
+// The HTML pages of a build, for the review's Pages list: [{ path: '/about/', title }].
+// index.html stands for its folder. Dependencies and dot folders are skipped.
+export function buildPages(dir, limit = 500) {
+  const out = [];
+  const walk = (rel) => {
+    for (const e of fs.readdirSync(path.join(dir, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (out.length >= limit || e.name.startsWith('.') || SKIP.has(e.name)) continue;
+      const file = path.posix.join(rel, e.name);
+      if (e.isDirectory()) walk(file);
+      else if (/\.html?$/i.test(e.name)) {
+        const html = fs.readFileSync(path.join(dir, file), 'utf8').slice(0, 20000);
+        const title = html.match(/<title[^>]*>([^<]*)<\/title>/i)?.[1].replace(/\s+/g, ' ').trim() || null;
+        out.push({ path: '/' + file.replace(/(^|\/)index\.html?$/i, '$1'), title });
+      }
+    }
+  };
+  walk('');
+  return out;
+}
+
+export function removeBuild(name) {
+  fs.rmSync(path.join(SITE_P, name), { recursive: true, force: true });
+}

package/cli/deploy.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { ROOT, HOME } from './config.js';
+import { dim } from './dev.js';
+
+export const CLOUD_CONFIG = path.join(ROOT, 'wrangler.cloud.jsonc');
+const LOCK = path.join(HOME, 'deploy.lock');
+const ASSET_LIMIT = 20000; // Workers static assets per version on the Free plan
+
+// Deploys the cloud worker with everything in site/: the review UI plus every pushed
+// snapshot. Uploads are content-hashed, so only new files travel. Deploys from several
+// terminals at once are queued with a lock file.
+export async function deploy({ quiet = false } = {}) {
+  await lock();
+  try {
+    const files = countFiles(path.join(ROOT, 'site'));
+    if (files > ASSET_LIMIT * 0.9) console.log(`warning: ${files} files in site/ (the Free plan allows ${ASSET_LIMIT}). Remove old snapshots under site/p/<name>/v*.`);
+    if (!quiet) console.log(dim('  Uploading to Cloudflare…'));
+    const out = await wrangler(['deploy', '-c', CLOUD_CONFIG]);
+    return { url: out.match(/https:\/\/[^\s]+\.workers\.dev/)?.[0] || null, log: out };
+  } finally {
+    fs.rmSync(LOCK, { force: true });
+  }
+}
+
+export function wrangler(args, { input } = {}) {
+  return new Promise((resolve, reject) => {
+    const bin = path.join(ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'wrangler.cmd' : 'wrangler');
+    const child = spawn(bin, args, { cwd: ROOT, env: { ...process.env, FORCE_COLOR: '0' }, stdio: ['pipe', 'pipe', 'pipe'] });
+    let log = '';
+    child.stdout.on('data', (d) => (log += d));
+    child.stderr.on('data', (d) => (log += d));
+    child.stdin.end(input ?? '');
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code === 0) resolve(log);
+      else reject(new Error(`wrangler ${args[0]} failed:\n${log.trim().split('\n').slice(-15).join('\n')}`));
+    });
+  });
+}
+
+async function lock() {
+  fs.mkdirSync(HOME, { recursive: true });
+  for (let i = 0; i < 600; i++) {
+    try {
+      fs.writeFileSync(LOCK, String(process.pid), { flag: 'wx' });
+      return;
+    } catch {
+      const pid = Number(fs.readFileSync(LOCK, 'utf8')) || 0;
+      if (!alive(pid)) fs.rmSync(LOCK, { force: true });
+      else await new Promise((r) => setTimeout(r, 1000));
+    }
+  }
+  throw new Error(`another deploy is still running (lock: ${LOCK})`);
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function countFiles(dir) {
+  let n = 0;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) n += e.isDirectory() ? countFiles(path.join(dir, e.name)) : 1;
+  return n;
+}

package/cli/detect.js

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+export const COMMON_PORTS = [5173, 5174, 3000, 3001, 4321, 4173, 4200, 8080, 8000, 6006];
+const BUILD_DIRS = ['dist', 'build', 'out', '.output/public'];
+
+// Project name: --name, package.json name (scope stripped), else the directory name.
+export function projectName(root, override) {
+  if (override) return slug(override);
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (pkg.name) return slug(pkg.name.replace(/^@[^/]+\//, ''));
+  } catch {}
+  return slug(path.basename(root));
+}
+
+export function slug(s) {
+  const out = String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 41)
+    .replace(/-+$/, '');
+  return out || 'prototype';
+}
+
+// The project root is the nearest enclosing git repo, else the current directory.
+export function projectRoot(cwd) {
+  let dir = path.resolve(cwd);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) return path.resolve(cwd);
+    dir = up;
+  }
+}
+
+// Explicit target: "5173" → localhost port, "http://…" → URL, a path → static build.
+export function parseTarget(arg, cwd) {
+  if (arg == null || arg === '') return null;
+  const s = String(arg);
+  if (/^\d{2,5}$/.test(s)) return { kind: 'url', target: `http://localhost:${s}` };
+  if (/^:\d{2,5}$/.test(s)) return { kind: 'url', target: `http://localhost${s}` };
+  if (/^https?:\/\//.test(s)) return { kind: 'url', target: new URL(s).toString() };
+  if (/^(localhost|127\.0\.0\.1):\d+/.test(s)) return { kind: 'url', target: `http://${s}` };
+  const dir = path.resolve(cwd, s);
+  if (fs.existsSync(dir) && fs.statSync(dir).isDirectory()) return { kind: 'static', source: dir };
+  throw new Error(`"${s}" is not a port, URL or directory`);
+}
+
+// Parses `lsof -nP -iTCP -sTCP:LISTEN -Fpcn` field output.
+export function parseLsofListen(out) {
+  const rows = [];
+  let pid = null, command = null;
+  for (const line of out.split('\n')) {
+    const tag = line[0], val = line.slice(1);
+    if (tag === 'p') pid = Number(val);
+    else if (tag === 'c') command = val;
+    else if (tag === 'n') {
+      const m = val.match(/:(\d+)$/);
+      if (m && pid) rows.push({ pid, command, port: Number(m[1]), addr: val });
+    }
+  }
+  const seen = new Set();
+  return rows.filter((r) => (seen.has(`${r.pid}:${r.port}`) ? false : seen.add(`${r.pid}:${r.port}`)));
+}
+
+// Parses `lsof -a -d cwd -p <pids> -Fpn` output into pid → cwd.
+export function parseLsofCwd(out) {
+  const map = new Map();
+  let pid = null;
+  for (const line of out.split('\n')) {
+    if (line[0] === 'p') pid = Number(line.slice(1));
+    else if (line[0] === 'n' && pid) map.set(pid, line.slice(1));
+  }
+  return map;
+}
+
+export function isInside(child, parent) {
+  const rel = path.relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+// Listening TCP servers whose process runs inside the project directory.
+export async function serversInProject(root, { exclude = [] } = {}) {
+  let listen;
+  try {
+    ({ stdout: listen } = await run('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN', '-Fpcn'], { maxBuffer: 8 << 20 }));
+  } catch (e) {
+    if (e.stdout) listen = e.stdout; // lsof exits 1 when some entries are inaccessible
+    else return [];
+  }
+  const rows = parseLsofListen(listen).filter((r) => !exclude.includes(r.port));
+  if (!rows.length) return [];
+  const pids = [...new Set(rows.map((r) => r.pid))];
+  let cwdOut = '';
+  try {
+    ({ stdout: cwdOut } = await run('lsof', ['-a', '-d', 'cwd', '-p', pids.join(','), '-Fpn'], { maxBuffer: 8 << 20 }));
+  } catch (e) {
+    cwdOut = e.stdout || '';
+  }
+  const cwds = parseLsofCwd(cwdOut);
+  return rows
+    .map((r) => ({ ...r, cwd: cwds.get(r.pid) }))
+    .filter((r) => r.cwd && isInside(r.cwd, root))
+    .sort((a, b) => a.port - b.port);
+}
+
+// Is something on this port answering HTTP? Prefers HTML pages.
+export async function probe(port) {
+  try {
+    const res = await fetch(`http://localhost:${port}/`, { signal: AbortSignal.timeout(1500), redirect: 'manual' });
+    res.body?.cancel().catch(() => {});
+    return { port, ok: true, html: /text\/html/.test(res.headers.get('content-type') || ''), status: res.status };
+  } catch {
+    return { port, ok: false };
+  }
+}
+
+// Finds what to share in `root`: a dev server started from the project, a common
+// dev port, or a build directory.
+export async function detectTarget(root, { exclude = [] } = {}) {
+  const own = await serversInProject(root, { exclude });
+  const probed = (await Promise.all(own.map(async (s) => ({ ...s, ...(await probe(s.port)) })))).filter((s) => s.ok);
+  const ranked = [...probed.filter((s) => s.html), ...probed.filter((s) => !s.html)];
+  if (ranked.length) {
+    const pick = ranked[0];
+    return {
+      kind: 'url',
+      target: `http://localhost:${pick.port}`,
+      how: `${pick.command || 'process'} (pid ${pick.pid}) running in this project`,
+      others: ranked.slice(1).map((s) => s.port),
+    };
+  }
+
+  const common = (await Promise.all(COMMON_PORTS.filter((p) => !exclude.includes(p)).map(probe))).filter((p) => p.ok && p.html);
+  if (common.length) {
+    return {
+      kind: 'url',
+      target: `http://localhost:${common[0].port}`,
+      how: 'common dev port (not confirmed to belong to this project)',
+      others: common.slice(1).map((p) => p.port),
+      uncertain: true,
+    };
+  }
+
+  for (const d of BUILD_DIRS) {
+    const dir = path.join(root, d);
+    if (fs.existsSync(path.join(dir, 'index.html'))) return { kind: 'static', source: dir, how: `build output in ${d}/` };
+  }
+  return null;
+}

package/cli/dev.js

@@ -0,0 +1,279 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn, execFileSync } from 'node:child_process';
+import { ROOT, HOME, STATE_DIR, cloudUrl, adminToken, readLocal, writeLocal, copyBuild } from './config.js';
+import { call, isUp, signinLink } from './client.js';
+
+// Quick Tunnel: one URL on the same line. Named tunnel: one or more hostnames on the next lines.
+const TUNNEL_RE = /Sharing via Cloudflare Tunnel:\s*(https:\/\/[^\s/]+)/;
+export const dim = (s) => (process.stdout.isTTY ? `\x1b[2m${s}\x1b[0m` : s);
+export const bold = (s) => (process.stdout.isTTY ? `\x1b[1m${s}\x1b[0m` : s);
+
+// Runs the worker under `wrangler dev`, optionally exposed through a Cloudflare
+// local dev tunnel (Quick Tunnel by default, named tunnel with --tunnel-name).
+// Resolves once the worker is up and, if requested, the tunnel URL is known.
+export async function startServer(opts = {}) {
+  const cfg = readLocal();
+  const port = Number(opts.port || cfg.port || 8787);
+  const token = adminToken({ create: true });
+  cfg.port = port;
+  // A named tunnel (stable hostname on your own domain) is remembered: once set up,
+  // every later `clickroom` uses it. `--tunnel-name none` goes back to Quick Tunnels.
+  if (opts['tunnel-name'] === 'none') delete cfg.tunnelName;
+  else if (opts['tunnel-name']) cfg.tunnelName = opts['tunnel-name'];
+  else if (cfg.tunnelName && opts.tunnel && !opts['allow-email']?.length) opts = { ...opts, 'tunnel-name': cfg.tunnelName };
+  if (opts['tunnel-name'] === 'none') opts = { ...opts, 'tunnel-name': undefined };
+  writeLocal(cfg);
+  process.env.CLICKROOM_URL = `http://localhost:${port}`;
+
+  if (await isUp() && killOrphan(port)) await new Promise((r) => setTimeout(r, 2000));
+  if (await isUp()) throw new Error(`Something is already serving on port ${port}. Stop it or pass --port.`);
+
+  // Refresh static builds before wrangler starts so the asset manifest is current.
+  for (const [name, p] of Object.entries(cfg.projects || {})) {
+    if (p.kind === 'static' && p.source && fs.existsSync(p.source)) copyBuild(name, p.source);
+  }
+
+  migrateState();
+  const args = ['dev', '--port', String(port), '--persist-to', STATE_DIR, '--show-interactive-dev-session=false'];
+  if (opts.lan) args.push('--ip', '0.0.0.0');
+  if (cloudUrl()) args.push('--var', `CLOUD_URL:${cloudUrl()}`);
+  if (opts['tunnel-name'] && cfg.tunnelName === opts['tunnel-name'] && cfg.tunnelPort && cfg.tunnelPort !== port) {
+    console.log(dim(`  Note: tunnel "${opts['tunnel-name']}" was set up for port ${cfg.tunnelPort}; its hostname won't reach port ${port}.`));
+  }
+  if (opts['tunnel-name']) {
+    cfg.tunnelPort ||= port;
+    writeLocal(cfg);
+  }
+  const tunnel = !!(opts.tunnel || opts['tunnel-name'] || opts['allow-email']?.length);
+  if (tunnel) args.push('--tunnel');
+  if (opts['tunnel-name']) args.push('--tunnel-name', opts['tunnel-name']);
+  for (const mail of [].concat(opts['allow-email'] || [])) args.push('--tunnel-allowed-mail', mail);
+  // Local only: every project gets its own origin (<name>.localhost), so prototype code can't
+  // reach the admin API. A tunnel has one hostname, so there prototypes share clickroom's origin.
+  if (!tunnel && !opts.lan && !cloudUrl()) args.push('--var', 'PROTO_HOST:{name}.localhost', '--var', `APP_URL:http://localhost:${port}`);
+  else if (tunnel && !cloudUrl() && !opts['public-url']) console.log(dim('  Note: over a tunnel, prototypes run on clickroom\'s own origin (not isolated per project).'));
+
+  const bin = path.join(ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'wrangler.cmd' : 'wrangler');
+  // The npm package leaves wrangler out: teammates share through a clickroom server (`clickroom login`).
+  if (!fs.existsSync(bin)) throw new Error('Running a clickroom server needs a checkout of clickroom with `npm install`. To share through your team\'s clickroom, run `clickroom login`.');
+  if (opts.verbose) console.log(dim(`$ wrangler ${args.join(' ')}`));
+
+  let child, buffer, tunnelFound, resolveTunnel, tunnelDied;
+  let stopped = false, restarting = false, probe = null;
+  let resolveExited;
+  const exited = new Promise((r) => (resolveExited = r));
+  const launch = () => {
+    // Own process group, so stopping also takes down workerd and the cloudflared tunnel.
+    child = spawn(bin, args, {
+      cwd: ROOT,
+      env: { ...process.env, FORCE_COLOR: '0' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    });
+    buffer = '';
+    tunnelFound = new Promise((r) => (resolveTunnel = r));
+    const onData = (chunk) => {
+      const text = chunk.toString().replace(/\x1b\[[0-9;]*m/g, '');
+      buffer += text;
+      if (opts.verbose) process.stdout.write(dim(text));
+      else for (const line of text.split('\n')) if (/✘|\berror\b/i.test(line) && !/cdn-cgi|cloudflared exited/.test(line)) console.log(dim(line));
+      const m = buffer.match(TUNNEL_RE);
+      if (m) resolveTunnel(m[1]);
+      if (/No Cloudflare Tunnel named/.test(text)) console.log(dim('  Create it in the Cloudflare dashboard (Networking → Tunnels), or run `npx wrangler tunnel list` to check the name.'));
+      if (/has no route|does not route to|ingress/i.test(text) && opts['tunnel-name']) console.log(dim(`  The tunnel's public hostname must point to http://localhost:${port} (Cloudflare dashboard → Tunnels → ${opts['tunnel-name']} → Routes).`));
+      if (/not authenticated|wrangler login/i.test(text) && opts['tunnel-name']) console.log(dim('  Named tunnels need wrangler logged in to your Cloudflare account: run `npx wrangler login` in the clickroom folder.'));
+      // wrangler keeps serving when its cloudflared connector dies, but never restarts it.
+      if (tunnel && !stopped && /cloudflared (exited|terminated)/.test(text)) tunnelDied?.();
+    };
+    child.stdout.on('data', onData);
+    child.stderr.on('data', onData);
+    const c = child;
+    c.on('exit', (code) => {
+      if (!restarting && c === child) resolveExited(code);
+    });
+  };
+  const kill = (c, sig = 'SIGTERM') => {
+    try {
+      if (process.platform === 'win32') c.kill(sig);
+      else process.kill(-c.pid, sig);
+    } catch {}
+  };
+  const stop = (sig = 'SIGTERM') => {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(probe);
+    kill(child, sig);
+  };
+  process.on('exit', () => stop());
+
+  const waitUp = async () => {
+    for (let i = 0; i < 120 && !(await isUp()); i++) {
+      if (child.exitCode !== null) break;
+      await new Promise((r) => setTimeout(r, 500));
+    }
+    return isUp();
+  };
+
+  launch();
+  if (!(await waitUp())) {
+    stop();
+    throw new Error(`wrangler did not start.\n${buffer.split('\n').slice(-15).join('\n')}`);
+  }
+
+  await call('POST', '/__ps/api/meta', {
+    localUrl: `http://localhost:${port}`,
+    cliPath: path.join(ROOT, 'bin', 'clickroom.js'),
+    tunnelUrl: opts['public-url'] || null,
+  });
+  for (const [name, p] of Object.entries(cfg.projects || {})) {
+    await call('POST', '/__ps/api/projects', { name, kind: p.kind, target: p.target, source: p.source || p.target, root: p.cwd || undefined });
+  }
+  startWatchers(cfg);
+
+  let publicUrl = opts['public-url'] ? String(opts['public-url']).replace(/\/$/, '') : null;
+  const awaitTunnel = async () => {
+    const url = await Promise.race([tunnelFound, new Promise((r) => setTimeout(() => r(null), 60000))]);
+    // In cloud mode the tunnel only carries the relay; the address to share is the cloud one,
+    // so that's what this server advertises (to sessions, `clickroom links`, the dashboard).
+    if (url) await call('POST', '/__ps/api/meta', { tunnelUrl: cloudUrl() || url });
+    return url;
+  };
+  if (tunnel && !publicUrl) {
+    publicUrl = await awaitTunnel();
+    if (!publicUrl) console.log('warning: no tunnel URL after 60s. Re-run with --verbose to see wrangler output.');
+  }
+
+  // Tunnel watchdog. A Quick Tunnel can drop (sleep, network change, Cloudflare recycling
+  // it) while wrangler keeps serving locally, which leaves every shared link dead. When the
+  // connector exits, or the public URL stops answering, restart wrangler for a new tunnel.
+  // State persists across the restart; session terminals pick up and print the new links.
+  if (tunnel && !opts['public-url']) {
+    const reopen = async (why) => {
+      if (restarting || stopped) return;
+      restarting = true;
+      console.log(dim(`  Cloudflare Tunnel lost (${why}). Reopening…`));
+      if (!cloudUrl()) await call('POST', '/__ps/api/meta', { tunnelUrl: null }).catch(() => {});
+      const old = child;
+      kill(old);
+      await Promise.race([new Promise((r) => old.on('exit', r)), new Promise((r) => setTimeout(r, 5000))]);
+      if (old.exitCode === null) kill(old, 'SIGKILL');
+      if (stopped) return;
+      launch();
+      restarting = false;
+      if (!(await waitUp())) {
+        console.log(`  wrangler did not come back.\n${buffer.split('\n').slice(-15).join('\n')}`);
+        return stop();
+      }
+      await call('POST', '/__ps/api/meta', { localUrl: `http://localhost:${port}`, cliPath: path.join(ROOT, 'bin', 'clickroom.js') }).catch(() => {});
+      publicUrl = await awaitTunnel();
+      console.log(publicUrl ? `${bold('✔')} Tunnel reopened: ${publicUrl}${opts['tunnel-name'] ? '' : ' (old links no longer work)'}` : 'warning: tunnel did not come back within 60s.');
+      failures = 0;
+    };
+    tunnelDied = () => reopen('connector exited');
+    let failures = 0;
+    probe = setInterval(async () => {
+      if (restarting || stopped || !publicUrl) return;
+      try {
+        const res = await fetch(`${publicUrl}/__ps/api/health`, { signal: AbortSignal.timeout(10000) });
+        failures = res.ok ? 0 : failures + 1;
+      } catch {
+        failures++;
+      }
+      if (failures >= 3) reopen('public URL not answering');
+    }, 30000);
+    probe.unref?.();
+  }
+  return { port, token, get publicUrl() { return publicUrl; }, localUrl: `http://localhost:${port}`, stop, exited };
+}
+
+// `clickroom dev`: run the server for all registered projects.
+export async function dev(opts) {
+  const server = await startServer(opts);
+  for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => server.stop(sig));
+  server.exited.then((code) => process.exit(code ?? 0));
+
+  console.log('');
+  const cloud = cloudUrl();
+  if (cloud) {
+    // Comments, versions and links live in the cloud; this server only relays Live views
+    // and app API calls from there to the dev servers on this Mac.
+    console.log(`${bold('clickroom')} relay running at ${server.localUrl}${server.publicUrl ? ` (${server.publicUrl})` : ''}`);
+    console.log(`  Review site and dashboard: ${cloud}/`);
+    console.log(`  Sign in (one-time link, 10 min): ${await signinLink('/', cloud).catch(() => 'run `clickroom` in a project and press o')}`);
+    if (!server.publicUrl) console.log(dim('  No tunnel: the cloud cannot reach this Mac. Start with `clickroom dev --tunnel`.'));
+    return;
+  }
+  console.log(`${bold('clickroom')} running at ${server.localUrl}`);
+  console.log(`  Team dashboard: ${server.localUrl}/`);
+  console.log(`  Sign in (one-time link, 10 min): ${await signinLink('/', server.localUrl)}`);
+  if (server.publicUrl) console.log(`  ${bold('Cloudflare Tunnel')} ${server.publicUrl}`);
+  const { projects } = await call('GET', '/__ps/api/projects');
+  if (!projects.length) console.log(dim('  No prototypes yet: run `clickroom` inside a project, or `clickroom add <name> <dir|url>`'));
+  for (const p of projects) {
+    console.log(`  ${bold(p.name.padEnd(16))} ${server.publicUrl || server.localUrl}/s/${encodeURIComponent(p.name)}?t=${p.token}`);
+  }
+  if (!server.publicUrl) console.log(dim('  Local only. Use `clickroom dev --tunnel` to share with clients over a Cloudflare Quick Tunnel.'));
+}
+
+// A clickroom server that died hard (kill -9, crash) leaves its wrangler running on the port
+// with no owner. Under launchd that would block every restart, so stop it if it's ours.
+function killOrphan(port) {
+  try {
+    const out = execFileSync('pgrep', ['-f', `wrangler-dist/cli.js dev --port ${port} `], { encoding: 'utf8' });
+    const pids = out.split('\n').map(Number).filter(Boolean);
+    let killed = false;
+    for (const pid of pids) {
+      // We spawn wrangler detached, so the group leader is the process we started. If that
+      // leader was reparented to launchd (ppid 1), its clickroom owner is gone.
+      const pgid = execFileSync('ps', ['-o', 'pgid=', '-p', String(pid)], { encoding: 'utf8' }).trim();
+      const [ppid, ...cmd] = execFileSync('ps', ['-o', 'ppid=,command=', '-p', pgid], { encoding: 'utf8' }).trim().split(/\s+/);
+      if (ppid !== '1' || !cmd.join(' ').includes(ROOT)) continue;
+      process.kill(-Number(pgid), 'SIGTERM');
+      console.log(dim(`  Stopped a leftover clickroom server (pid ${pid}) on port ${port}.`));
+      killed = true;
+    }
+    return killed;
+  } catch {
+    return false;
+  }
+}
+
+// Earlier versions kept state in <repo>/.wrangler/state. Copy it (never move) to the
+// clickroom home the first time, so existing comments carry over.
+function migrateState() {
+  // The tool used to be called protoshare and kept everything in ~/.protoshare.
+  const oldHome = path.join(os.homedir(), '.protoshare');
+  if (!process.env.CLICKROOM_HOME && !fs.existsSync(HOME) && fs.existsSync(oldHome)) {
+    fs.cpSync(oldHome, HOME, { recursive: true });
+    console.log(dim(`  Comments and backups are now in ${HOME} (copied from ${oldHome}, which is left in place).`));
+  }
+  const old = path.join(ROOT, '.wrangler', 'state');
+  if (fs.existsSync(STATE_DIR) || !fs.existsSync(old)) return;
+  fs.mkdirSync(path.dirname(STATE_DIR), { recursive: true });
+  fs.cpSync(old, STATE_DIR, { recursive: true });
+  console.log(dim(`  Comment storage is now in ${STATE_DIR} (copied from ${old}, which is left in place).`));
+}
+
+function startWatchers(cfg) {
+  for (const [name, p] of Object.entries(cfg.projects || {})) {
+    if (p.kind !== 'static' || !p.watch || !p.source) continue;
+    let timer;
+    try {
+      fs.watch(p.source, { recursive: true }, () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+          try {
+            copyBuild(name, p.source);
+            console.log(dim(`↻ ${name}: rebuilt from ${p.source}`));
+          } catch (e) {
+            console.error(e.message);
+          }
+        }, 300);
+      });
+    } catch (e) {
+      console.error(`could not watch ${p.source}: ${e.message}`);
+    }
+  }
+}