clickroom 0.0.0-stage → 0.2.0

package/bin/clickroom.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { NAME_RE, readLocal, writeLocal, copyBuild, removeBuild, baseUrl } from '../cli/config.js';
+import { call } from '../cli/client.js';
+
+const HELP = `clickroom: multiplayer review for locally built prototypes
+
+On a teammate's computer
+  clickroom login <workspace> connect this computer to your team's workspace (acme → acme.clickroom.dev):
+                              approve it in the browser where you're signed in from your invite
+  clickroom                   then, in a project: builds it, uploads it as v1 and keeps the session open
+                              (p pushes the next version). The team sees it on the dashboard.
+  clickroom logout | whoami
+
+Share the project you're in (run inside any project folder)
+  clickroom [port|url|dir] [--name NAME] [--local] [--no-open] [--allow-email ADDR] [--tunnel-name NAME]
+      Finds the project's running dev server (or takes a port / URL / build folder), starts the review
+      server with a Cloudflare Quick Tunnel (or attaches to the one already running), opens the review
+      as team and copies the client link. Clients see pushed versions: the first share pushes v1
+      (a snapshot of your build), then press p in that terminal to push the next one. q quits.
+        clickroom               auto-detect (dev server started in this project, else common ports, else dist/)
+        clickroom 5173          a local port
+        clickroom ./dist        a static build
+        --local                  no tunnel, http://localhost only
+        --allow-email '*@acme.com'  Quick Tunnel that requires email login
+        --tunnel-name my-tunnel  named tunnel (stable hostname), remembered for next runs; 'none' to forget
+
+Versions
+  clickroom push [name] [note] [--build CMD] [--out DIR] [--live]
+      Snapshot the project as a new version (runs its build script, copies the output). Same as p in
+      the session terminal. --live pushes a label-only version that shows the live dev server.
+
+Process feedback
+  clickroom process [name] [--print] [--no-comments] [--no-questions]
+      Gathers what reviewers left that isn't in the prototype yet (open comments, answered questions),
+      writes it to .clickroom/process.md and starts Claude Code on it. The agent marks each item, and
+      the next push records the version it landed in. --print writes the brief to stdout instead.
+
+Other commands
+  clickroom dev [--tunnel] [--tunnel-name NAME] [--port 8787] [--lan] [--verbose]   serve all registered projects
+  clickroom add <name> <dir|url> [--watch]      register a project without sharing it yet
+  clickroom list                                projects: live sessions, latest version, feedback counts
+  clickroom links <name>                        print client links
+  clickroom sync <name> | remove <name>
+  clickroom feedback <name> [--status actionable|open|queued|in_progress|resolved|active|all] [--questions] [--json] [--out FILE]
+      --questions lists the questions asked to the client and their answers instead
+  clickroom questions import <name> <file.json> [--name AGENT]
+      adds questions and assumptions for the client from [{key, type, text, now, page, selector}];
+      running it again updates the items with the same key instead of adding them twice
+  clickroom resolve <name> <n> [--note TEXT] [--close]
+      marks a thread fixed: the reviewer checks it in the next pushed version. --close resolves it outright.
+  clickroom mcp                                 MCP server (stdio) for coding agents
+  clickroom service install|uninstall|status|logs   run the server + tunnel in the background (macOS launchd)
+  clickroom cloud setup | url <url> | off       host links on Cloudflare so they work while this Mac is off
+  clickroom deploy                              redeploy the cloud site (pushes do this automatically)
+`;
+
+const { values: opts, positionals } = parseArgs({
+  allowPositionals: true,
+  strict: false,
+  options: {
+    tunnel: { type: 'boolean' },
+    'tunnel-name': { type: 'string' },
+    'allow-email': { type: 'string', multiple: true },
+    'public-url': { type: 'string' },
+    port: { type: 'string' },
+    lan: { type: 'boolean' },
+    verbose: { type: 'boolean' },
+    watch: { type: 'boolean' },
+    status: { type: 'string' },
+    json: { type: 'boolean' },
+    questions: { type: 'boolean' },
+    out: { type: 'string' },
+    note: { type: 'string' },
+    name: { type: 'string' },
+    local: { type: 'boolean' },
+    close: { type: 'boolean' },
+    build: { type: 'string' },
+    live: { type: 'boolean' },
+    'no-open': { type: 'boolean' },
+    print: { type: 'boolean' },
+    'no-comments': { type: 'boolean' },
+    'no-questions': { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+  },
+});
+const [cmd, ...args] = positionals;
+const COMMANDS = new Set(['login', 'logout', 'whoami', 'push', 'dev', 'serve', 'add', 'sync', 'list', 'ls', 'links', 'remove', 'rm', 'feedback', 'questions', 'process', 'resolve', 'mcp', 'service', 'cloud', 'deploy']);
+
+try {
+  await main();
+} catch (err) {
+  console.error(`error: ${err.message}`);
+  process.exit(1);
+}
+
+// `<cmd> [name] [...]`: the name is optional inside a shared project folder.
+async function projectFromArgs(cfg, cmd) {
+  const { projectRoot } = await import('../cli/detect.js');
+  const here = projectRoot(process.cwd());
+  let [name, ...rest] = args;
+  if (!cfg.projects?.[name]) {
+    rest = args;
+    name = Object.entries(cfg.projects || {}).find(([, p]) => p.cwd === here)?.[0];
+    if (!name) throw new Error(`run this inside a shared project folder (run \`clickroom\` there first), or pass its name: clickroom ${cmd} <name>`);
+  }
+  return { name, rest, root: cfg.projects[name].cwd || here };
+}
+
+async function main() {
+  if (opts.help || cmd === 'help') return console.log(HELP);
+  if (!cmd || !COMMANDS.has(cmd)) {
+    const { share } = await import('../cli/share.js');
+    return share(cmd, opts);
+  }
+  switch (cmd) {
+    case 'login':
+    case 'logout':
+    case 'whoami': {
+      const m = await import('../cli/login.js');
+      return m[cmd](args[0]);
+    }
+    case 'push': {
+      const { push, pushHint, NoSnapshot } = await import('../cli/push.js');
+      const cfg = readLocal();
+      const { name, rest } = await projectFromArgs(cfg, 'push');
+      const note = opts.note || rest.join(' ') || null;
+      try {
+        const v = await push(name, cfg.projects[name], { note, live: !!opts.live, build: opts.build, out: opts.out });
+        return console.log(`pushed ${name} v${v.n}${v.note ? ` · ${v.note}` : ''}`);
+      } catch (err) {
+        if (err instanceof NoSnapshot) throw new Error(pushHint(err));
+        throw err;
+      }
+    }
+    case 'process': {
+      const { gather, buildBrief, writeBrief, hasClaude, startClaude } = await import('../cli/process.js');
+      const cfg = readLocal();
+      const { name, root } = await projectFromArgs(cfg, 'process');
+      const found = await gather(name, { comments: !opts['no-comments'], questions: !opts['no-questions'] });
+      const { comments, answers } = found;
+      if (!comments.count && !answers.count) return console.error(`${name}: nothing new to process`);
+      const brief = buildBrief(name, found, { root });
+      if (opts.print) return process.stdout.write(brief);
+      console.log(`${name}: ${comments.count} comment${comments.count === 1 ? '' : 's'}, ${answers.count} answer${answers.count === 1 ? '' : 's'} to work in`);
+      const file = writeBrief(root, brief);
+      console.log(`wrote ${file}`);
+      if (!hasClaude()) return console.log(`Claude Code isn't installed: hand ${file} to your agent, or run \`clickroom process --print\`.`);
+      console.log('starting Claude Code…');
+      process.exitCode = await startClaude(root, name);
+      return;
+    }
+    case 'dev':
+    case 'serve': {
+      const { dev } = await import('../cli/dev.js');
+      return dev(opts);
+    }
+    case 'add': {
+      const [name, target] = args;
+      if (!name || !target) throw new Error('usage: clickroom add <name> <dir|url> [--watch]');
+      if (!NAME_RE.test(name)) throw new Error('name must be lowercase letters, digits and dashes');
+      const cfg = readLocal();
+      cfg.projects ||= {};
+      if (/^https?:\/\//.test(target)) {
+        cfg.projects[name] = { kind: 'url', target };
+      } else {
+        const source = path.resolve(target);
+        copyBuild(name, source);
+        cfg.projects[name] = { kind: 'static', source, watch: !!opts.watch };
+      }
+      writeLocal(cfg);
+      const p = cfg.projects[name];
+      try {
+        const reg = await call('POST', '/__ps/api/projects', { name, kind: p.kind, target: p.target, source: p.source || p.target });
+        console.log(`added ${name}: ${baseUrl()}/s/${name}?t=${reg.token}`);
+        if (p.watch) console.log('note: --watch takes effect on the next `clickroom dev` start.');
+      } catch (e) {
+        if (!e.offline) throw e;
+        console.log(`added ${name}. It will be registered when you run \`clickroom dev\`.`);
+      }
+      return;
+    }
+    case 'sync': {
+      const [name] = args;
+      const p = readLocal().projects?.[name];
+      if (!p || p.kind !== 'static') throw new Error(`no static project named ${name}`);
+      copyBuild(name, p.source);
+      return console.log(`synced ${name} from ${p.source}`);
+    }
+    case 'list':
+    case 'ls': {
+      const { projects, meta } = await call('GET', '/__ps/api/projects');
+      if (!projects.length) return console.log('no projects. Add one with `clickroom add <name> <dir|url>`');
+      projects.sort((a, b) => (b.session?.live ? 1 : 0) - (a.session?.live ? 1 : 0) || a.name.localeCompare(b.name));
+      for (const p of projects) {
+        const c = p.counts;
+        const v = c.latestVersion ? `v${c.latestVersion.n}` : '-';
+        console.log(
+          `${p.session?.live ? '●' : '○'} ${p.name.padEnd(18)} ${v.padEnd(5)} ${(p.session?.live ? p.session.target || '' : 'offline').padEnd(24)} open ${c.open + c.queued + c.in_progress}  resolved ${c.resolved}${c.questions ? `  questions ${c.questions}` : ''}${c.drafts ? `  drafts ${c.drafts}` : ''}  viewers ${c.online}`,
+        );
+      }
+      if (meta.tunnelUrl) console.log(`\ntunnel: ${meta.tunnelUrl}`);
+      return;
+    }
+    case 'links': {
+      const [name] = args;
+      if (!name) throw new Error('usage: clickroom links <name>');
+      const { project, meta } = await call('GET', `/__ps/api/projects/${encodeURIComponent(name || '')}`);
+      if (meta?.tunnelUrl) console.log(`public: ${meta.tunnelUrl}/s/${name}?t=${project.token}`);
+      console.log(`local:  ${meta?.localUrl || baseUrl()}/s/${name}?t=${project.token}`);
+      return;
+    }
+    case 'remove':
+    case 'rm': {
+      const [name] = args;
+      if (!name) throw new Error('usage: clickroom remove <name>');
+      const cfg = readLocal();
+      delete cfg.projects?.[name];
+      writeLocal(cfg);
+      removeBuild(name);
+      try {
+        await call('DELETE', `/__ps/api/projects/${encodeURIComponent(name)}`);
+      } catch (e) {
+        if (!e.offline) throw e;
+      }
+      return console.log(`removed ${name}`);
+    }
+    case 'feedback': {
+      const [name] = args;
+      if (!name) throw new Error('usage: clickroom feedback <name>');
+      const status = opts.status || (opts.questions ? 'open' : 'actionable');
+      const ext = opts.json ? 'json' : 'md';
+      const kind = opts.questions ? '&kind=question' : '';
+      const data = await call('GET', `/__ps/api/projects/${encodeURIComponent(name)}/feedback.${ext}?status=${encodeURIComponent(status)}${kind}`);
+      const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2) + '\n';
+      if (opts.out) {
+        fs.writeFileSync(opts.out, text);
+        return console.log(`wrote ${opts.out}`);
+      }
+      return process.stdout.write(text);
+    }
+    case 'questions': {
+      const [sub, name, file] = args;
+      if (sub !== 'import' || !name || !file) throw new Error('usage: clickroom questions import <name> <file.json>');
+      const items = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (!Array.isArray(items)) throw new Error(`${file} must hold an array of questions`);
+      // Imported lists come from an agent or a script, so they're credited to one, like MCP questions.
+      const author = { name: opts.name || process.env.CLICKROOM_AGENT_NAME || 'Claude', role: 'agent', color: '#7c3aed' };
+      let created = 0, updated = 0;
+      for (const item of items) {
+        const t = await call('POST', `/__ps/api/projects/${encodeURIComponent(name)}/threads`, {
+          kind: 'question', body: item.text, type: item.type, now: item.now, key: item.key, page: item.page,
+          el: item.selector ? { selector: item.selector } : undefined, author, notify: false,
+        });
+        if (t.createdAt === t.updatedAt) created++;
+        else updated++;
+      }
+      return console.log(`${name}: ${created} question${created === 1 ? '' : 's'} added as drafts for the team to review, ${updated} updated`);
+    }
+    case 'resolve': {
+      const [name, n] = args;
+      if (!name || !n) throw new Error('usage: clickroom resolve <name> <n> [--note TEXT] [--close]');
+      const t = await call('PATCH', `/__ps/api/projects/${encodeURIComponent(name)}/threads/${Number(String(n).replace('#', ''))}`, {
+        status: opts.close ? 'resolved' : 'review',
+        note: opts.note,
+        author: { name: process.env.CLICKROOM_AGENT_NAME || 'CLI', role: 'agent' },
+      });
+      if (!opts.close && t.kind === 'question') return console.log(`#${t.seq} marked processed: ${t.fixedIn ? `in v${t.fixedIn}` : 'the next push records the version'}`);
+      return console.log(opts.close ? `resolved #${t.seq}` : `#${t.seq} marked fixed: the reviewer checks it ${t.fixedIn ? `in ${t.fixedIn === 'live' ? 'the live server' : 'v' + t.fixedIn}` : 'once you push a new version'}`);
+    }
+    case 'cloud': {
+      const { cloud } = await import('../cli/cloud.js');
+      return cloud(args[0], args[1]);
+    }
+    case 'deploy': {
+      const { deploy } = await import('../cli/deploy.js');
+      const { url } = await deploy();
+      return console.log(`deployed${url ? `: ${url}` : ''}`);
+    }
+    case 'service': {
+      const { service } = await import('../cli/service.js');
+      return service(args[0]);
+    }
+    case 'mcp': {
+      const { runMcp } = await import('../cli/mcp.js');
+      return runMcp();
+    }
+    default:
+      throw new Error(`unknown command "${cmd}". Run \`clickroom help\`.`);
+  }
+}

package/cli/changes.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { HOME } from './config.js';
+
+// "New changes since v15": at every push the CLI remembers the project folder's files (size
+// and modification time, plus git HEAD), and while a session runs it compares the folder with
+// that, so the dashboard can say there's something clients haven't seen yet. Only file
+// metadata is read, never contents. Kept in ~/.clickroom/folders/<name>.json.
+
+const DIR = path.join(HOME, 'folders');
+// Without git: folders that are never source (dependencies, build output, caches).
+const SKIP = new Set(['node_modules', 'dist', 'build', 'out', '.output', '.nuxt', '.next', '.svelte-kit', '.vercel', '.turbo', 'coverage']);
+const MAX_FILES = 20000;
+
+function git(args, cwd, env) {
+  return new Promise((resolve) => execFile('git', args, { cwd, env: env || process.env, timeout: 20000, maxBuffer: 64 * 1024 * 1024 }, (err, out) => resolve(err ? null : out)));
+}
+
+// A git tree of the whole working copy as it is (uncommitted and new files too, .gitignore
+// respected), made in a throwaway index so the repo's own index, branches and stash stay as
+// they are. Used to diff "what changed since the last push" exactly.
+async function workingTree(dir) {
+  const tmp = path.join(os.tmpdir(), `clickroom-index-${process.pid}-${Date.now()}`);
+  const env = { ...process.env, GIT_INDEX_FILE: tmp };
+  try {
+    await git(['read-tree', 'HEAD'], dir, env); // a head start; fails harmlessly in an empty repo
+    if ((await git(['add', '-A'], dir, env)) == null) return null;
+    return (await git(['write-tree'], dir, env))?.trim() || null;
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}
+
+async function listFiles(dir) {
+  const out = await git(['ls-files', '-co', '--exclude-standard', '-z'], dir);
+  if (out != null) return { files: out.split('\0').filter(Boolean).slice(0, MAX_FILES), git: true };
+  const files = [];
+  walk(dir, '', files);
+  return { files, git: false };
+}
+
+function walk(root, rel, acc) {
+  let entries;
+  try {
+    entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (acc.length >= MAX_FILES) return;
+    if (e.name.startsWith('.') || SKIP.has(e.name)) continue;
+    const r = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) walk(root, r, acc);
+    else if (e.isFile()) acc.push(r);
+  }
+}
+
+// The folder as it is now: { files: { path: "size:mtime" }, head }.
+export async function folderState(dir) {
+  const { files, git: isGit } = await listFiles(dir);
+  const out = {};
+  for (const f of files) {
+    try {
+      const st = fs.statSync(path.join(dir, f));
+      if (st.isFile()) out[f] = `${st.size}:${Math.round(st.mtimeMs)}`;
+    } catch {}
+  }
+  const head = isGit ? (await git(['rev-parse', 'HEAD'], dir))?.trim() || null : null;
+  return { files: out, head, git: isGit };
+}
+
+function statePath(name) {
+  return path.join(DIR, `${name}.json`);
+}
+
+// After a push (version n): this is what clients have now.
+export async function rememberFolder(name, dir, n = null) {
+  const now = await folderState(dir);
+  const tree = now.git ? await workingTree(dir) : null;
+  fs.mkdirSync(DIR, { recursive: true });
+  fs.writeFileSync(statePath(name), JSON.stringify({ ...now, tree, n, dir, at: Date.now() }));
+}
+
+// Never sent to Claude: lockfiles, minified and generated files, binaries.
+const NOT_SOURCE = ['*lock*', '*.min.*', '*.map', ...['png', 'jpg', 'jpeg', 'gif', 'webp', 'ico', 'pdf', 'woff', 'woff2', 'ttf', 'zip'].map((x) => `*.${x}`)].map((g) => `:(exclude,glob)**/${g}`);
+const DIFF_MAX = 40 * 1024;
+
+// The source changes since the last push, for writing its note: { stat, patch }, or null
+// when there's nothing to compare (no git, nothing pushed from here yet, nothing changed).
+// With a tree from the last push the diff is exact; without one (pushed before clickroom kept
+// trees) it falls back to the changed files against the last commit.
+export async function changedSource(name, dir) {
+  let base = null;
+  try {
+    base = JSON.parse(fs.readFileSync(statePath(name), 'utf8'));
+  } catch {}
+  if (!base || base.dir !== dir) return null;
+  let stat, patch;
+  if (base.tree) {
+    const now = await workingTree(dir);
+    if (!now || now === base.tree) return null;
+    stat = await git(['diff-tree', '-r', '-M', '--stat=120', base.tree, now, '--', '.', ...NOT_SOURCE], dir);
+    patch = await git(['diff-tree', '-r', '-M', '-p', '--no-color', base.tree, now, '--', '.', ...NOT_SOURCE], dir);
+  } else {
+    if ((await git(['rev-parse', 'HEAD'], dir)) == null) return null;
+    const { changed, added, removed } = compare(base.files, (await folderState(dir)).files);
+    const paths = [...changed, ...added, ...removed].slice(0, 200);
+    if (!paths.length) return null;
+    stat = await git(['diff', 'HEAD', '-M', '--stat=120', '--', ...paths], dir);
+    patch = await git(['diff', 'HEAD', '-M', '-p', '--no-color', '--', ...paths], dir);
+  }
+  if (!stat?.trim() && !patch?.trim()) return null;
+  return { stat: stat || '', patch: (patch || '').length > DIFF_MAX ? patch.slice(0, DIFF_MAX) + '\n[… diff cut off]' : patch || '' };
+}
+
+function compare(before, after) {
+  const changed = [], added = [], removed = [];
+  for (const [f, v] of Object.entries(after)) {
+    if (!(f in before)) added.push(f);
+    else if (before[f] !== v) changed.push(f);
+  }
+  for (const f of Object.keys(before)) if (!(f in after)) removed.push(f);
+  return { changed, added, removed };
+}
+
+// What changed in the folder since the last push. The first time (no record yet, or another
+// folder) the folder as it is becomes the starting point, so nothing is reported.
+export async function folderChanges(name, dir) {
+  let base = null;
+  try {
+    base = JSON.parse(fs.readFileSync(statePath(name), 'utf8'));
+  } catch {}
+  if (!base || base.dir !== dir) {
+    await rememberFolder(name, dir, base?.n ?? null);
+    return { files: 0, added: 0, removed: 0, paths: [], commits: [], since: base?.n ?? null };
+  }
+  const now = await folderState(dir);
+  const { changed, added, removed } = compare(base.files, now.files);
+  let commits = [];
+  if (base.head && now.head && base.head !== now.head) {
+    const log = await git(['log', '--format=%s', '-n', '5', `${base.head}..${now.head}`], dir);
+    commits = log ? log.split('\n').filter(Boolean) : [];
+  }
+  const paths = [...changed, ...added, ...removed];
+  return { files: paths.length, added: added.length, removed: removed.length, paths: paths.slice(0, 5), commits, since: base.n ?? null };
+}

package/cli/client.js

@@ -0,0 +1,86 @@
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { baseUrl, authToken, isTeammate } from './config.js';
+
+// HTTP client for the clickroom server, with the admin key (the owner's Mac) or a teammate's
+// own key (`clickroom login`).
+export async function call(method, pathname, body) {
+  const token = authToken();
+  if (!token) {
+    const err = new Error('Not signed in. Run `clickroom login` (or, on the owner\'s Mac, `clickroom dev` once).');
+    err.offline = true;
+    throw err;
+  }
+  let res;
+  try {
+    res = await fetch(baseUrl() + pathname, {
+      method,
+      headers: { authorization: `Bearer ${token}`, ...(body ? { 'content-type': 'application/json' } : {}) },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch {
+    const err = new Error(`clickroom is not running at ${baseUrl()}. Start it with \`clickroom dev\`.`);
+    err.offline = true;
+    throw err;
+  }
+  const text = await res.text();
+  let data = text;
+  try {
+    data = JSON.parse(text);
+  } catch {}
+  if (res.status === 401 && isTeammate()) throw new Error('Your clickroom sign-in has ended (revoked, or unused for 90 days). Run `clickroom login` again.');
+  if (!res.ok) throw new Error((data && data.error) || `${res.status} ${res.statusText}`);
+  return data;
+}
+
+// A one-time link (15 minutes) that signs the owner (or the signed-in teammate) into a browser
+// and then opens `next`.
+// The admin key itself never goes into a URL or a browser.
+export async function signinLink(next = '/', base = baseUrl()) {
+  const res = await fetch(base.replace(/\/$/, '') + '/__ps/api/signin-links', {
+    method: 'POST',
+    headers: { authorization: `Bearer ${authToken()}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ next, name: ownerName() }),
+  });
+  if (!res.ok) throw new Error(`could not make a sign-in link (${res.status})`);
+  return (await res.json()).url;
+}
+
+// The owner's name on first sign-in (it can be changed on the dashboard).
+function ownerName() {
+  try {
+    const name = execFileSync('git', ['config', 'user.name'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (name) return name;
+  } catch {}
+  return os.userInfo().username;
+}
+
+// Uploads a local file (e.g. a screenshot) with its content type.
+export async function callUpload(pathname, bytes, mime) {
+  const res = await fetch(baseUrl() + pathname, {
+    method: 'PUT',
+    headers: { authorization: `Bearer ${authToken()}`, 'content-type': mime },
+    body: bytes,
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data.error || `${res.status} ${res.statusText}`);
+  return data;
+}
+
+// A binary resource (e.g. a screenshot) as { mime, base64 }, or null when there is none.
+export async function callBinary(pathname) {
+  const token = authToken();
+  if (!token) return null;
+  const res = await fetch(baseUrl() + pathname, { headers: { authorization: `Bearer ${token}` } }).catch(() => null);
+  if (!res?.ok) return null;
+  return { mime: (res.headers.get('content-type') || '').split(';')[0], base64: Buffer.from(await res.arrayBuffer()).toString('base64') };
+}
+
+export async function isUp() {
+  try {
+    const res = await fetch(baseUrl() + '/__ps/api/health');
+    return res.ok;
+  } catch {
+    return false;
+  }
+}

package/cli/cloud.js

@@ -0,0 +1,100 @@
+import { readLocal, writeLocal, adminToken, localUrl } from './config.js';
+import { deploy, wrangler, CLOUD_CONFIG } from './deploy.js';
+import { bold, dim } from './dev.js';
+
+// `clickroom cloud …`: run the review site on Cloudflare so links work while this Mac is off.
+//   setup        deploy, set the admin token, copy every local project (token + history) up
+//   url <url>    talk to the cloud deployment at <url> (e.g. https://clickroom.dev)
+//   off          go back to the local server only
+export async function cloud(action, arg) {
+  if (action === 'setup') return setup();
+  if (action === 'url') return useUrl(arg);
+  if (action === 'off') return off();
+  const cfg = readLocal();
+  console.log(cfg.cloudUrl ? `cloud: ${cfg.cloudUrl}` : 'cloud: off (local server only). Run `clickroom cloud setup`.');
+}
+
+async function setup() {
+  const token = adminToken();
+  if (!token) throw new Error('No admin token yet. Run `clickroom dev` once first.');
+  console.log(dim(`  Deploying with ${CLOUD_CONFIG}…`));
+  const { url: workersDev } = await deploy({ quiet: true });
+  // Same admin token as the local server, so team links and dashboard cookies keep working.
+  await wrangler(['secret', 'put', 'ADMIN_TOKEN', '-c', CLOUD_CONFIG], { input: token + '\n' });
+  const cfg = readLocal();
+  const url = (cfg.cloudUrl || workersDev || '').replace(/\/$/, '');
+  if (!url) throw new Error('Deployed, but could not find the worker URL. Pass it with `clickroom cloud url <url>`.');
+  await waitHealthy(url);
+  // A new secret takes a few seconds to reach the running worker.
+  for (let i = 0; i < 30; i++) {
+    const res = await fetch(url + '/__ps/api/projects', { headers: { authorization: `Bearer ${token}` } }).catch(() => null);
+    if (res?.ok) break;
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+  await migrate(url, token);
+  writeLocal({ ...readLocal(), cloudUrl: url });
+  console.log(`${bold('✔')} Cloud ready at ${url}. Projects, comments, versions and links were copied.`);
+  console.log(dim('  Sessions, pushes, the dashboard and MCP now use the cloud. Keep the background service running for Live views.'));
+}
+
+async function migrate(url, token) {
+  const local = localUrl();
+  const get = async (base, p) => {
+    const res = await fetch(base + p, { headers: { authorization: `Bearer ${token}` } });
+    if (!res.ok) throw new Error(`${base}${p}: ${res.status}`);
+    return res.json();
+  };
+  let projects;
+  try {
+    ({ projects } = await get(local, '/__ps/api/projects'));
+  } catch {
+    throw new Error(`The local clickroom server (${local}) isn't answering, so there's nothing to copy. Start it (\`clickroom service install\`) and run setup again.`);
+  }
+  for (const p of projects) {
+    const data = await get(local, `/__ps/api/projects/${encodeURIComponent(p.name)}/export`);
+    const res = await fetch(url + '/__ps/api/import', {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+    if (res.status === 409) console.log(dim(`  ${p.name}: already in the cloud, left as is`));
+    else if (!res.ok) throw new Error(`importing ${p.name} failed: ${(await res.text()).slice(0, 200)}`);
+    else console.log(`  ${p.name}: ${data.room.threads.length} threads, ${data.room.versions.length} versions copied`);
+  }
+  await fetch(url + '/__ps/api/meta', {
+    method: 'POST',
+    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ tunnelUrl: url, localUrl: url }),
+  });
+}
+
+async function useUrl(url) {
+  if (!/^https:\/\//.test(url || '')) throw new Error('usage: clickroom cloud url https://share.example.com');
+  url = url.replace(/\/$/, '');
+  await waitHealthy(url, 1);
+  const token = adminToken();
+  await fetch(url + '/__ps/api/meta', {
+    method: 'POST',
+    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ tunnelUrl: url, localUrl: url }),
+  });
+  writeLocal({ ...readLocal(), cloudUrl: url });
+  console.log(`${bold('✔')} Using ${url}.`);
+}
+
+function off() {
+  const cfg = readLocal();
+  delete cfg.cloudUrl;
+  writeLocal(cfg);
+  console.log(`${bold('✔')} Back to the local server only. Data in the cloud is left as is.`);
+}
+
+async function waitHealthy(url, tries = 30) {
+  for (let i = 0; i < tries; i++) {
+    try {
+      if ((await fetch(url + '/__ps/api/health')).ok) return;
+    } catch {}
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+  throw new Error(`${url} is not answering yet.`);
+}