clickroom 0.0.0-stage → 0.2.0

package/cli/push.js

@@ -0,0 +1,198 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import { BACKUP_DIR, copyBuild, cloudUrl, buildPages, baseUrl, localUrl, isTeammate, authToken } from './config.js';
+import { call } from './client.js';
+import { dim } from './dev.js';
+import { rememberFolder } from './changes.js';
+
+const OUT_DIRS = ['dist', 'build', 'out', '.output/public'];
+
+export class NoSnapshot extends Error {}
+
+// Pushes a new version of a project: builds a frozen snapshot (static copy, or the
+// project's build output) and registers it. `live: true` pushes a label-only version
+// that shows the running dev server.
+//   local: the project's entry in clickroom.local.json ({ kind, source, target, cwd, dir, build, out })
+export async function push(name, local, { note, live = false, build, out, quiet = false } = {}) {
+  const enc = encodeURIComponent(name);
+  const { next } = await call('GET', `/__ps/api/projects/${enc}/versions`);
+  if (live && isTeammate()) throw new NoSnapshot('Only builds can be shared from this computer: the live dev server here isn\'t reachable from clickroom.');
+  if (live) {
+    const version = await call('POST', `/__ps/api/projects/${enc}/versions`, { n: next, kind: 'live', note });
+    await rememberFolder(name, projectFolder(local), version.n).catch(() => {});
+    await backup(name);
+    return version;
+  }
+
+  let source;
+  const command = build || local.build;
+  const dir = local.dir || local.cwd || process.cwd();
+  if (local.kind === 'static' && !command) {
+    source = local.source;
+  } else {
+    const pkgDir = packageDir(dir, local.cwd);
+    const cmd = command || buildScript(pkgDir);
+    if (!cmd) throw new NoSnapshot(`No build script in ${path.join(pkgDir || dir, 'package.json')}, so there's nothing to snapshot.`);
+    const started = Date.now();
+    if (!quiet) console.log(dim(`  Building v${next}: ${cmd}`));
+    await run(cmd, pkgDir || dir);
+    source = out || local.out ? path.resolve(pkgDir || dir, out || local.out) : findOutput(pkgDir || dir, started);
+    if (!source) throw new NoSnapshot(`The build finished, but no folder with an index.html was produced (looked in ${OUT_DIRS.join(', ')}).`);
+  }
+  if (!fs.existsSync(path.join(source, 'index.html'))) throw new NoSnapshot(`${source} has no index.html.`);
+  // A teammate's computer, or a cloud server that takes uploads: the files go up (only the ones
+  // it doesn't have yet), no deploy needed.
+  if (isTeammate() || (baseUrl() !== localUrl() && (await takesUploads()))) {
+    const files = await upload(name, source, { quiet });
+    const version = await call('POST', `/__ps/api/projects/${enc}/versions`, { n: next, kind: 'snapshot', note, pages: buildPages(source), files });
+    await rememberFolder(name, projectFolder(local), version.n).catch(() => {});
+    await backup(name);
+    return version;
+  }
+  copyBuild(name, source, next);
+  // In the cloud the snapshot ships with the worker: deploy first, then announce the version,
+  // so viewers only hear about it once it loads.
+  if (cloudUrl()) {
+    const { deploy } = await import('./deploy.js');
+    await deploy({ quiet });
+  }
+  const version = await call('POST', `/__ps/api/projects/${enc}/versions`, { n: next, kind: 'snapshot', note, pages: buildPages(source) });
+  await rememberFolder(name, projectFolder(local), version.n).catch(() => {});
+  await backup(name);
+  return version;
+}
+
+async function takesUploads() {
+  const res = await fetch(baseUrl() + '/__ps/api/health').catch(() => null);
+  return !!(res?.ok && (await res.json().catch(() => ({}))).uploads);
+}
+
+// Uploads a build's files: lists them with their SHA-256, then sends the ones the server is
+// missing (usually only what changed since the last push). Returns the file list for the version.
+export async function upload(name, source, { quiet = false } = {}) {
+  const enc = encodeURIComponent(name);
+  const files = listFiles(source);
+  if (!files.length) throw new NoSnapshot(`${source} is empty.`);
+  const big = files.find((f) => f.size > 25 * 1024 * 1024);
+  if (big) throw new NoSnapshot(`${big.path} is larger than 25 MB; leave it out of the build.`);
+  const { missing } = await call('POST', `/__ps/api/projects/${enc}/builds`, { files: files.map(({ path, hash, size }) => ({ path, hash, size })) });
+  const todo = files.filter((f, i, all) => missing.includes(f.hash) && all.findIndex((g) => g.hash === f.hash) === i);
+  const total = todo.reduce((n, f) => n + f.size, 0);
+  if (!quiet) console.log(dim(todo.length ? `  Uploading ${todo.length} of ${files.length} files (${mb(total)})…` : `  All ${files.length} files are uploaded already.`));
+  const send = async (f) => {
+    for (let attempt = 1; ; attempt++) {
+      const res = await fetch(`${baseUrl()}/__ps/api/projects/${enc}/blobs/${f.hash}`, {
+        method: 'PUT',
+        headers: { authorization: `Bearer ${authToken()}`, 'content-type': 'application/octet-stream' },
+        body: fs.readFileSync(f.abs),
+      }).catch((e) => ({ ok: false, status: 0, text: async () => e.message }));
+      if (res.ok) return;
+      if (attempt >= 3 || (res.status >= 400 && res.status < 500)) throw new Error(`uploading ${f.path} failed: ${(await res.text()).slice(0, 200)}`);
+      await new Promise((r) => setTimeout(r, 1000 * attempt));
+    }
+  };
+  const queue = [...todo];
+  await Promise.all(Array.from({ length: Math.min(6, queue.length) }, async () => {
+    while (queue.length) await send(queue.shift());
+  }));
+  return files.map(({ path, hash, size }) => ({ path, hash, size }));
+}
+
+const SKIP_FILES = new Set(['node_modules', '.git', '.DS_Store']);
+function listFiles(dir) {
+  const out = [];
+  const walk = (rel) => {
+    for (const e of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+      if (SKIP_FILES.has(e.name)) continue;
+      const file = rel ? `${rel}/${e.name}` : e.name;
+      const abs = path.join(dir, file);
+      if (e.isDirectory()) walk(file);
+      else if (e.isFile()) {
+        const bytes = fs.readFileSync(abs);
+        out.push({ path: file, abs, size: bytes.length, hash: crypto.createHash('sha256').update(bytes).digest('hex') });
+      }
+    }
+  };
+  walk('');
+  return out;
+}
+
+const mb = (n) => (n < 1024 * 1024 ? `${Math.max(1, Math.round(n / 1024))} KB` : `${(n / 1024 / 1024).toFixed(1)} MB`);
+
+// The folder whose changes count as "new since the last push": the project root.
+export function projectFolder(local) {
+  return local.cwd || local.dir || process.cwd();
+}
+
+export function pushHint(err) {
+  return (
+    `${err.message}\n` +
+    '  Tell clickroom how to build it:   clickroom push --build "npm run build" --out dist\n' +
+    '  Or push a label-only version that shows the live dev server:   clickroom push --live'
+  );
+}
+
+// Saves every thread and version of a project to ~/.clickroom/backups/<name>.json.
+export async function backup(name) {
+  try {
+    const enc = encodeURIComponent(name);
+    const [feedback, versions] = await Promise.all([
+      call('GET', `/__ps/api/projects/${enc}/feedback.json?status=all&kind=all`),
+      call('GET', `/__ps/api/projects/${enc}/versions`),
+    ]);
+    fs.mkdirSync(BACKUP_DIR, { recursive: true });
+    fs.writeFileSync(path.join(BACKUP_DIR, `${name}.json`), JSON.stringify({ ...feedback, versions: versions.versions }, null, 2) + '\n');
+  } catch {}
+}
+
+// Nearest folder with a package.json, from where clickroom was run up to the project root.
+function packageDir(dir, root) {
+  let d = path.resolve(dir);
+  const stop = path.resolve(root || dir);
+  for (;;) {
+    if (fs.existsSync(path.join(d, 'package.json'))) return d;
+    if (d === stop || path.dirname(d) === d) return null;
+    d = path.dirname(d);
+  }
+}
+
+function buildScript(dir) {
+  if (!dir) return null;
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!pkg.scripts?.build) return null;
+  // Nuxt's `build` makes a server app; `generate` makes the static site a snapshot needs.
+  const nuxt = pkg.dependencies?.nuxt || pkg.devDependencies?.nuxt;
+  const script = nuxt && pkg.scripts.generate ? 'generate' : 'build';
+  const has = (f) => fs.existsSync(path.join(dir, f));
+  const pm = has('pnpm-lock.yaml') ? 'pnpm' : has('yarn.lock') ? 'yarn' : has('bun.lockb') || has('bun.lock') ? 'bun' : 'npm';
+  return `${pm} run ${script}`;
+}
+
+function findOutput(dir, since) {
+  for (const d of OUT_DIRS) {
+    const index = path.join(dir, d, 'index.html');
+    if (fs.existsSync(index) && fs.statSync(index).mtimeMs >= since - 2000) return path.join(dir, d);
+  }
+  return null;
+}
+
+function run(cmd, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, { cwd, shell: true, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, FORCE_COLOR: '0' } });
+    let log = '';
+    child.stdout.on('data', (d) => (log += d));
+    child.stderr.on('data', (d) => (log += d));
+    child.on('error', (e) => reject(new NoSnapshot(`Could not run "${cmd}": ${e.message}`)));
+    child.on('exit', (code) => {
+      if (code === 0) resolve(log);
+      else reject(new NoSnapshot(`"${cmd}" failed (exit ${code}):\n${log.trim().split('\n').slice(-12).map((l) => '    ' + l).join('\n')}`));
+    });
+  });
+}

package/cli/service.js

@@ -0,0 +1,110 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawn } from 'node:child_process';
+import { ROOT, HOME, readLocal } from './config.js';
+import { bold, dim } from './dev.js';
+
+// `clickroom service …`: runs `clickroom dev --tunnel` as a macOS launchd agent, so the
+// server and tunnel start at login and restart if they crash. No terminal has to stay open.
+const LABEL = 'dev.clickroom.server';
+const PLIST = path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+const LOG_DIR = path.join(HOME, 'logs');
+const LOG = path.join(LOG_DIR, 'server.log');
+const DOMAIN = `gui/${process.getuid?.() ?? 501}`;
+
+export async function service(action = 'status') {
+  if (process.platform !== 'darwin') throw new Error('clickroom service uses launchd and only works on macOS. Run `clickroom dev --tunnel` instead.');
+  if (action === 'install') return install();
+  if (action === 'uninstall') return uninstall();
+  if (action === 'status') return status();
+  if (action === 'logs') return logs();
+  throw new Error('usage: clickroom service install|uninstall|status|logs');
+}
+
+function install() {
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+  fs.mkdirSync(path.dirname(PLIST), { recursive: true });
+  const nodeBin = path.dirname(process.execPath);
+  const env = {
+    PATH: [nodeBin, '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'].join(':'),
+    HOME: os.homedir(),
+  };
+  if (process.env.CLICKROOM_HOME) env.CLICKROOM_HOME = process.env.CLICKROOM_HOME;
+  const plist = `<?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>
+${[process.execPath, path.join(ROOT, 'bin', 'clickroom.js'), 'dev', '--tunnel'].map((a) => `    <string>${xml(a)}</string>`).join('\n')}
+  </array>
+  <key>WorkingDirectory</key><string>${xml(ROOT)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${Object.entries(env).map(([k, v]) => `    <key>${k}</key><string>${xml(v)}</string>`).join('\n')}
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>StandardOutPath</key><string>${xml(LOG)}</string>
+  <key>StandardErrorPath</key><string>${xml(LOG)}</string>
+</dict>
+</plist>
+`;
+  if (loaded()) launchctl(['bootout', `${DOMAIN}/${LABEL}`], { quiet: true });
+  fs.writeFileSync(PLIST, plist);
+  launchctl(['bootstrap', DOMAIN, PLIST]);
+  console.log(`${bold('✔')} clickroom now runs in the background (starts at login, restarts if it stops).`);
+  console.log(dim(`  Logs: clickroom service logs   ·   Stop: clickroom service uninstall`));
+}
+
+function uninstall() {
+  if (loaded()) launchctl(['bootout', `${DOMAIN}/${LABEL}`]);
+  if (fs.existsSync(PLIST)) fs.unlinkSync(PLIST);
+  console.log(`${bold('✔')} Background service removed. The server and tunnel are stopped.`);
+}
+
+async function status() {
+  if (!fs.existsSync(PLIST)) return console.log('Not installed. Run `clickroom service install`.');
+  const info = loaded() ? launchctl(['print', `${DOMAIN}/${LABEL}`], { quiet: true }) : '';
+  const state = info.match(/^\s*state = (.+)$/m)?.[1] || 'not loaded';
+  const pid = info.match(/^\s*pid = (\d+)$/m)?.[1];
+  const port = readLocal().port || 8787;
+  let health = 'not answering';
+  try {
+    const res = await fetch(`http://localhost:${port}/__ps/api/health`, { signal: AbortSignal.timeout(3000) });
+    if (res.ok) health = 'answering';
+  } catch {}
+  console.log(`service  ${state}${pid ? ` (pid ${pid})` : ''}`);
+  console.log(`server   http://localhost:${port} ${health}`);
+  console.log(dim(`logs     ${LOG}`));
+}
+
+function logs() {
+  if (!fs.existsSync(LOG)) return console.log('No logs yet.');
+  spawn('tail', ['-n', '40', '-f', LOG], { stdio: 'inherit' });
+}
+
+function loaded() {
+  try {
+    execFileSync('launchctl', ['print', `${DOMAIN}/${LABEL}`], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function launchctl(args, { quiet = false } = {}) {
+  try {
+    return execFileSync('launchctl', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (err) {
+    if (quiet) return '';
+    throw new Error(`launchctl ${args[0]} failed: ${(err.stderr || err.message).trim()}`);
+  }
+}
+
+function xml(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}

package/cli/share.js

@@ -0,0 +1,350 @@
+import fs from 'node:fs';
+import readline from 'node:readline';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { readLocal, writeLocal, copyBuild, cloudUrl, baseUrl, isTeammate, adminToken, ROOT } from './config.js';
+import { call, isUp, signinLink } from './client.js';
+import { projectRoot, projectName, parseTarget, detectTarget } from './detect.js';
+import { startServer, bold, dim } from './dev.js';
+import { push, pushHint, backup, NoSnapshot, projectFolder } from './push.js';
+import { folderChanges } from './changes.js';
+import { autoNote } from './note.js';
+import { findGaps } from './gaps.js';
+
+// `clickroom [port|url|dir]` inside any project: find what to share, make sure the
+// clickroom server + tunnel are running (start them, or attach to the running one),
+// register the project, make sure it has a pushed version, and hand out links.
+// The terminal then stays open as the project's session: p pushes a new version.
+export async function share(arg, opts) {
+  const cwd = process.cwd();
+  const root = projectRoot(cwd);
+  const cfg = readLocal();
+  cfg.projects ||= {};
+  // The same folder keeps its project name, even if package.json is renamed later.
+  const known = Object.entries(cfg.projects).find(([, p]) => p.cwd === root)?.[0];
+  let name = opts.name ? projectName(root, opts.name) : known || projectName(root);
+  const port = Number(opts.port || cfg.port || 8787);
+  // In cloud mode comments, versions and links live on the deployed worker; this Mac only
+  // relays Live views and API calls (the local server, usually the background service).
+  // A teammate's computer (`clickroom login`): their builds go to the team's clickroom server.
+  const teammate = isTeammate() && !opts.local;
+  if (!teammate && !adminToken() && !fs.existsSync(path.join(ROOT, 'node_modules', '.bin', 'wrangler'))) {
+    throw new Error('Not signed in. Run `clickroom login` first (it opens clickroom in your browser).');
+  }
+  const cloud = opts.local ? null : cloudUrl();
+  if (!cloud) process.env.CLICKROOM_URL = `http://localhost:${port}`;
+
+  let target = parseTarget(arg, cwd);
+  if (target) target.how = 'from the command line';
+  else target = await detectTarget(root, { exclude: [port, 9229, 9230] });
+  // From a teammate's computer only builds are shared, so a running dev server isn't needed:
+  // the project's build script makes each version.
+  if (teammate && (!target || target.kind === 'url')) target = { kind: 'build', target: null, source: null, how: 'each push runs its build' };
+  if (!target) {
+    throw new Error(
+      'No running dev server found for this project.\n' +
+        '  Start it first (e.g. `npm run dev`), or tell clickroom what to share:\n' +
+        '  clickroom 5173   ·   clickroom http://localhost:3000   ·   clickroom ./dist',
+    );
+  }
+  const label = target.kind === 'url' ? target.target : target.kind === 'build' ? 'its build' : target.source;
+  // A port that isn't proven to belong to this project could be any app on the machine:
+  // never publish it without an explicit yes.
+  if (target.uncertain) {
+    const hint = `Pass the port explicitly if that's the right app: \`clickroom ${new URL(target.target).port}\``;
+    if (!process.stdin.isTTY) throw new Error(`No dev server found running in this project. ${label} answers, but it may be a different app.\n  ${hint}`);
+    const answer = await ask(`No dev server found running in this project, but ${label} answers (could be another app).\nShare ${label} publicly? [y/N] `);
+    if (!/^y(es)?$/i.test(answer.trim())) throw new Error(`Cancelled. ${hint}`);
+  }
+
+  let server = null;
+  if (teammate) {
+    console.log(dim(`  Sharing through ${cloud} as you`));
+  } else if (cloud) {
+    console.log(dim(`  Sharing through ${cloud}`));
+    const relay = await fetch(`http://localhost:${port}/__ps/api/health`).then((r) => r.ok, () => false);
+    if (!relay) console.log(dim('  The local clickroom server is not running, so the Live view and app API calls are offline.\n  Start it in the background with `clickroom service install`.'));
+  } else if (await isUp()) {
+    console.log(dim(`  Attaching to the clickroom server already running on :${port}`));
+  } else {
+    console.log(dim(`  Starting clickroom${opts.local ? '' : ' + Cloudflare Tunnel'}…`));
+    server = await startServer({ ...opts, port, tunnel: !opts.local });
+  }
+
+  const project = await retry(() => call('POST', '/__ps/api/projects', {
+    name,
+    kind: target.kind,
+    target: target.target,
+    source: target.source || target.target,
+    root,
+  }));
+  if (project.name !== name) {
+    console.log(dim(project.renamed === 'name-taken' ? `  "${name}" is taken by another folder; sharing this one as "${project.name}".` : `  This folder is already shared as "${project.name}"; keeping that name so its comments stay together.`));
+    if (cfg.projects[name]?.cwd === root) delete cfg.projects[name];
+    name = project.name;
+  }
+  const prev = cfg.projects[name] || {};
+  const local = { ...prev, kind: target.kind, target: target.target || null, source: target.source || null, cwd: root, dir: cwd };
+  cfg.projects[name] = local;
+  cfg.port = port;
+  writeLocal(cfg);
+  if (target.kind === 'static' && !teammate) copyBuild(name, target.source);
+  console.log(`${bold('✔')} Sharing ${bold(name)} → ${label} ${dim(`(${target.how})`)}`);
+  if (target.others?.length) console.log(dim(`  Also listening: ${target.others.join(', ')}. Use \`clickroom <port>\` to pick another.`));
+
+  // Clients only ever see pushed versions. The first share pushes v1.
+  const { versions } = await call('GET', `/__ps/api/projects/${encodeURIComponent(name)}/versions`);
+  if (!versions.length) await doPush(name, local, { note: 'First share', first: true });
+  else console.log(dim(`  Latest version: v${versions[0].n}${versions[0].note ? ` · ${versions[0].note}` : ''} (${ago(versions[0].createdAt)})`));
+
+  const meta = teammate ? {} : await call('GET', '/__ps/api/meta');
+  let tunnelUrl = cloud || meta.tunnelUrl;
+  let base, teamUrl, clientUrl;
+  const links = () => {
+    base = tunnelUrl || `http://localhost:${port}`;
+    // The review's own address when the server has one (APP_URL/<name>), else /s/<name>.
+    teamUrl = project.reviewUrl || `${base}/s/${encodeURIComponent(name)}`;
+    clientUrl = `${project.reviewUrl || `${project.origin || base}/s/${encodeURIComponent(name)}`}?t=${project.token}`;
+    console.log('');
+    console.log(`  ${bold('Review (you, team)')}  ${teamUrl} ${dim('(press o to open it signed in)')}`);
+    console.log(`  ${bold('Client link')}         ${clientUrl}`);
+    console.log(`  ${bold('All sessions')}        ${base}/`);
+  };
+  // Opens the review signed in, with a one-time link (never the admin key).
+  const openTeam = () =>
+    signinLink(`/s/${encodeURIComponent(name)}`, cloud || baseUrl()).then(openUrl, (e) => console.log(dim(`  Could not open the review: ${e.message}`)));
+  links();
+  if (!tunnelUrl) {
+    console.log(dim(server ? '  Local only (--local).' : '  The running server has no tunnel (it was started with --local). Stop it and re-run to get a public link.'));
+  }
+  if (copy(clientUrl)) console.log(dim('  Client link copied to clipboard.'));
+  if (!opts['no-open'] && opts.open !== false) openTeam();
+
+  const watcher = target.kind === 'static' ? watchBuild(target.source) : null;
+  if (teammate) console.log(dim('  The team sees it on the dashboard and gets each version you push.'));
+  console.log('');
+  if (process.stdin.isTTY) console.log(`  ${bold('p')} push new version   ${bold('o')} open review   ${bold('c')} copy client link   ${bold('q')} quit`);
+  if (cloud) console.log(dim(`  Links stay up when you quit or your ${teammate ? 'computer' : 'Mac'} is off; quitting only ends this session.`));
+  else console.log(dim(server ? '  Quitting stops sharing (closes the tunnel for every project).' : '  Quitting detaches. The server and tunnel belong to the terminal that started them.'));
+
+  let pushing = false;
+  let changes; // what the folder has that the last push didn't (see changes.js)
+  // "Find gaps with Claude" from the review: one run at a time; its state goes out with each beat
+  // (the last result for 10 minutes), so the review can show it.
+  let clarify = null;
+  const gapsNow = async () => {
+    if (clarify?.status === 'running') return;
+    clarify = { status: 'running', found: 0, at: Date.now() };
+    console.log(dim('  Claude is looking for gaps in the prototype (Clarify)…'));
+    try {
+      const found = await findGaps(name, projectFolder(local));
+      clarify = { status: 'done', found, at: Date.now() };
+      console.log(`${bold('✔')} ${found} draft${found === 1 ? '' : 's'} added to Clarify`);
+    } catch (e) {
+      clarify = { status: 'failed', found: 0, at: Date.now(), error: e.message };
+      console.log(dim(`  Finding gaps failed: ${e.message}`));
+    }
+  };
+  // No note given (Push vN on the dashboard, Enter at the prompt): one is written for it.
+  const pushNow = async (note) => {
+    if (pushing) return;
+    pushing = true;
+    try {
+      if (!note) {
+        console.log(dim('  Writing the version note…'));
+        note = await autoNote(name, projectFolder(local)).catch(() => null);
+      }
+      await doPush(name, local, { note });
+      changes = await folderChanges(name, projectFolder(local)).catch(() => changes);
+    } finally {
+      pushing = false;
+    }
+  };
+
+  let heartbeat, keys;
+  await new Promise((resolve) => {
+    const done = () => resolve();
+    process.once('SIGINT', done);
+    process.once('SIGTERM', done);
+    server?.exited.then(() => {
+      console.log(dim('  clickroom server stopped.'));
+      resolve();
+    });
+    // Marks this project live on the sessions overview, picks up pushes requested from the
+    // dashboard, and notices when the owning terminal stops sharing.
+    // The server reopens a dropped tunnel itself (new URL); tolerate the restart window.
+    let misses = 0;
+    // Unpushed work in the folder, checked every 30 s (metadata only) and sent with the beat.
+    const look = () => folderChanges(name, projectFolder(local)).then((c) => (changes = c), () => {});
+    look();
+    const looking = setInterval(look, 30000);
+    process.once('exit', () => clearInterval(looking));
+    const beat = async () => {
+      try {
+        const recent = clarify && (clarify.status === 'running' || Date.now() - clarify.at < 10 * 60 * 1000) ? { clarify } : {};
+        const { pending } = await call('POST', `/__ps/api/projects/${encodeURIComponent(name)}/session`, { pid: process.pid, target: label, ...(changes ? { changes } : {}), ...recent });
+        if (misses >= 3) console.log(dim(`  Reconnected to ${baseUrl()}.`));
+        misses = 0;
+        for (const r of pending) {
+          if (r.type === 'push') pushNow(r.note || null);
+          if (r.type === 'clarify') gapsNow();
+        }
+        // Never announce a relay host as the address to share once a cloud site exists.
+        const { tunnelUrl: now } = cloud || cloudUrl() ? {} : await call('GET', '/__ps/api/meta');
+        if (now && now !== tunnelUrl) {
+          tunnelUrl = now;
+          console.log(`\n${bold('!')} The Cloudflare Tunnel was reopened with a new address. Old links no longer work; send these:`);
+          links();
+          if (copy(clientUrl)) console.log(dim('  New client link copied to clipboard.'));
+        }
+      } catch (e) {
+        if (++misses === 3) console.log(dim(`  Can't reach ${baseUrl()} (${e.message}). Retrying…`));
+        // A cloud deployment doesn't go away with a terminal: keep retrying through network blips.
+        if (!server && !cloud && misses >= 18 && !(await isUp())) {
+          console.log(dim('  The clickroom server was stopped by the terminal that started it. Run `clickroom` again to share.'));
+          resolve();
+        }
+      }
+    };
+    beat();
+    heartbeat = setInterval(beat, 5000);
+    if (process.stdin.isTTY) {
+      keys = onKeys(async (key) => {
+        if (key === 'quit') return resolve();
+        if (key === 'p') {
+          keys.pause();
+          const note = (await ask('  Version note (Enter: write one from the changes): ')).trim();
+          keys.resume();
+          await pushNow(note || null);
+        }
+        if (key === 'o') openTeam();
+        if (key === 'c' && copy(clientUrl)) console.log(dim('  Client link copied.'));
+      });
+    }
+  });
+  clearInterval(heartbeat);
+  keys?.stop();
+  watcher?.close();
+  await call('DELETE', `/__ps/api/projects/${encodeURIComponent(name)}/session`).catch(() => {});
+  await backup(name);
+  if (server) {
+    server.stop();
+    await Promise.race([server.exited, new Promise((r) => setTimeout(r, 3000))]);
+    console.log(dim('\n  Tunnel closed.'));
+  }
+  process.exit(0);
+}
+
+async function doPush(name, local, { note, first = false }) {
+  try {
+    const v = await push(name, local, { note });
+    console.log(`${bold('✔')} Pushed ${bold(`v${v.n}`)}${v.note ? ` · ${v.note}` : ''}. Viewers are told a new version is available.`);
+  } catch (err) {
+    if (!(err instanceof NoSnapshot)) throw err;
+    if (first && isTeammate()) {
+      console.log(`${bold('✘')} Couldn't build this project, so there's nothing to share yet.`);
+      throw new Error(pushHint(err).replace(/\n.*--live.*$/m, ''));
+    }
+    if (first) {
+      const v = await push(name, local, { note, live: true });
+      console.log(`${bold('!')} Couldn't snapshot this project, so v${v.n} shows your live dev server (clients see edits as you make them).`);
+      console.log(dim('  ' + pushHint(err).replace(/\n/g, '\n  ')));
+    } else {
+      console.log(`${bold('✘')} Push failed. ${pushHint(err)}`);
+    }
+  }
+}
+
+// Raw-mode keys for the session terminal: p / o / c / q (and Ctrl+C).
+function onKeys(handler) {
+  readline.emitKeypressEvents(process.stdin);
+  const listener = (str, key = {}) => {
+    if ((key.ctrl && key.name === 'c') || key.name === 'q') return handler('quit');
+    if (['p', 'o', 'c'].includes(key.name) && !key.ctrl && !key.meta) handler(key.name);
+  };
+  const resume = () => {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on('keypress', listener);
+  };
+  const pause = () => {
+    process.stdin.off('keypress', listener);
+    process.stdin.setRawMode(false);
+  };
+  resume();
+  return {
+    pause,
+    resume,
+    stop() {
+      pause();
+      process.stdin.pause();
+    },
+  };
+}
+
+// Retries network failures (DNS hiccups, Wi-Fi switching) a few times before giving up.
+async function retry(fn, tries = 5) {
+  for (let i = 1; ; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (!err.offline || i >= tries) throw err;
+      await new Promise((r) => setTimeout(r, 2000 * i));
+    }
+  }
+}
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+function ago(iso) {
+  const s = Math.round((Date.now() - new Date(iso).getTime()) / 1000);
+  if (s < 60) return 'just now';
+  if (s < 3600) return `${Math.round(s / 60)}m ago`;
+  if (s < 86400) return `${Math.round(s / 3600)}h ago`;
+  return `${Math.round(s / 86400)}d ago`;
+}
+
+// Static builds aren't re-published on change any more: changes wait for an explicit push.
+function watchBuild(source) {
+  let timer, notified = false;
+  try {
+    const w = fs.watch(source, { recursive: true }, () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        if (!notified) console.log(dim(`  Changes detected in ${source}. Press p to push them as a new version.`));
+        notified = true;
+        setTimeout(() => (notified = false), 60000);
+      }, 500);
+    });
+    return w;
+  } catch {
+    return null;
+  }
+}
+
+function copy(text) {
+  const cmd = process.platform === 'darwin' ? ['pbcopy'] : process.platform === 'win32' ? ['clip'] : ['wl-copy'];
+  try {
+    const p = spawn(cmd[0], cmd.slice(1), { stdio: ['pipe', 'ignore', 'ignore'] });
+    p.on('error', () => {});
+    p.stdin.end(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function openUrl(url) {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer' : 'xdg-open';
+  try {
+    spawn(cmd, [url], { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
+  } catch {}
+}

package/cli/vapid.js

@@ -0,0 +1,10 @@
+// Makes the key pair the server signs its notifications with (worker/push.js):
+// VAPID_PUBLIC_KEY goes in wrangler.cloud.jsonc's vars, VAPID_PRIVATE_KEY is a secret
+// (`npx wrangler secret put VAPID_PRIVATE_KEY -c wrangler.cloud.jsonc`, and .dev.vars locally).
+// Changing the pair ends every subscription: browsers have to turn notifications on again.
+import { webcrypto as crypto } from 'node:crypto';
+
+const pair = await crypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign', 'verify']);
+const pub = Buffer.from(await crypto.subtle.exportKey('raw', pair.publicKey)).toString('base64url');
+const { d } = await crypto.subtle.exportKey('jwk', pair.privateKey);
+console.log(`VAPID_PUBLIC_KEY=${pub}\nVAPID_PRIVATE_KEY=${d}`);