clickroom 0.3.3 → 0.3.5

package/cli/agents.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { execFile } from 'node:child_process';
 import { HOME, ROOT } from './config.js';
+import { execCmd } from './run.js';
 
 // `npx clickroom` also connects the coding agents on the computer to clickroom's feedback (the MCP
 // server, `clickroom mcp`, signed in with this computer's key): Claude Code for the project being
@@ -24,7 +24,7 @@ const SERVER = ['npx', '-y', VERSION ? `clickroom@${VERSION}` : 'clickroom', 'mc
 const DONE = path.join(HOME, 'agents.json');
 
 const run = (cmd, args, cwd) =>
-  new Promise((resolve) => execFile(cmd, args, { cwd, timeout: 20000, windowsHide: true }, (err, stdout) => resolve({ ok: !err, missing: err?.code === 'ENOENT', out: String(stdout || '') })));
+  new Promise((resolve) => execCmd(cmd, args, { cwd, timeout: 20000 }, (err, stdout) => resolve({ ok: !err, missing: err?.code === 'ENOENT', out: String(stdout || '') })));
 
 const AGENTS = [
   {

package/cli/gaps.js

@@ -1,9 +1,11 @@
 // "Find gaps with Claude" (Clarify): the project's clickroom terminal runs Claude Code headless in
 // the project folder. It may only read files and ask through clickroom's MCP server, so each gap it
 // finds lands in Clarify as a draft, live, while nothing in the folder changes.
+import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import { spawn, spawnSync } from 'node:child_process';
-import { ROOT } from './config.js';
+import { ROOT, credentials, isTeammate } from './config.js';
+import { onPath, spawnCmd } from './run.js';
 import { call } from './client.js';
 import { gapsPrompt } from '../worker/handoff.js';
 
@@ -11,25 +13,33 @@ const TOOLS = ['Read', 'Glob', 'Grep', 'mcp__clickroom__clickroom_ask', 'mcp__cl
 const NEVER = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Bash', 'WebFetch', 'WebSearch'];
 const LIMIT = 10 * 60 * 1000; // a run that hangs is stopped
 
-export const hasClaude = () => spawnSync(process.platform === 'win32' ? 'where' : 'which', ['claude'], { stdio: 'ignore' }).status === 0;
+export const hasClaude = () => onPath('claude');
+
+// Whose computer this is, for the review: the run is asked for from someone else's browser.
+const computer = () => (isTeammate() && credentials()?.name ? `${credentials().name}’s computer` : 'the computer');
 
 const questionCount = async (name) =>
   (await call('GET', `/__ps/api/projects/${encodeURIComponent(name)}/threads`)).threads.filter((t) => t.kind === 'question').length;
 
 // Resolves to the number of questions it added (drafts), or throws.
 export async function findGaps(name, root) {
-  if (!hasClaude()) throw new Error('Claude Code (`claude`) is not installed on the computer running `clickroom` for this project');
+  if (!hasClaude()) throw new Error(`Claude Code (\`claude\`) isn’t installed on ${computer()}, which runs \`clickroom\` for this project.`);
   const before = await questionCount(name);
-  const mcp = JSON.stringify({ mcpServers: { clickroom: { command: process.execPath, args: [path.join(ROOT, 'bin', 'clickroom.js'), 'mcp'] } } });
-  const args = ['-p', gapsPrompt(name), '--mcp-config', mcp, '--strict-mcp-config', '--tools', 'Read,Glob,Grep', '--allowedTools', TOOLS.join(','), '--disallowedTools', NEVER.join(','), '--no-session-persistence'];
+  // The MCP config as a file and the prompt through stdin: both survive Windows' shell.
+  const mcp = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'clickroom-gaps-')), 'mcp.json');
+  fs.writeFileSync(mcp, JSON.stringify({ mcpServers: { clickroom: { command: process.execPath, args: [path.join(ROOT, 'bin', 'clickroom.js'), 'mcp'] } } }));
+  const args = ['-p', '--mcp-config', mcp, '--strict-mcp-config', '--tools', 'Read,Glob,Grep', '--allowedTools', TOOLS.join(','), '--disallowedTools', NEVER.join(','), '--no-session-persistence'];
   await new Promise((resolve, reject) => {
-    const child = spawn('claude', args, { cwd: root, stdio: ['ignore', 'ignore', 'pipe'] });
+    const child = spawnCmd('claude', args, { cwd: root, stdio: ['pipe', 'ignore', 'pipe'] });
+    child.stdin.on('error', () => {});
+    child.stdin.end(gapsPrompt(name));
     let err = '';
     child.stderr.on('data', (d) => (err = (err + d).slice(-2000)));
     const timer = setTimeout(() => child.kill('SIGTERM'), LIMIT);
     child.on('error', reject);
     child.on('exit', (code) => {
       clearTimeout(timer);
+      fs.rmSync(path.dirname(mcp), { recursive: true, force: true });
       code === 0 ? resolve() : reject(new Error(err.trim().split('\n').pop() || `claude exited with ${code}`));
     });
   });

package/cli/note.js

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { spawnCmd } from './run.js';
 import { call } from './client.js';
 import { changedSource, folderChanges } from './changes.js';
 
@@ -55,7 +55,7 @@ function askClaude(input) {
     let out = '';
     let child;
     try {
-      child = spawn('claude', ['-p', '--model', 'haiku', '--tools', '', '--no-session-persistence', '--setting-sources', '', '--system-prompt', PROMPT], { stdio: ['pipe', 'pipe', 'ignore'] });
+      child = spawnCmd('claude', ['-p', '--model', 'haiku', '--tools', '', '--no-session-persistence', '--setting-sources', '', '--system-prompt', PROMPT], { stdio: ['pipe', 'pipe', 'ignore'] });
     } catch {
       return resolve(null);
     }

package/cli/process.js

@@ -2,7 +2,7 @@
 // answers to questions), writes one brief into the project and starts Claude Code on it.
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawn, spawnSync } from 'node:child_process';
+import { onPath, spawnCmd } from './run.js';
 import { call } from './client.js';
 import { buildBrief } from '../worker/handoff.js';
 
@@ -33,14 +33,14 @@ export function writeBrief(root, text) {
 }
 
 export function hasClaude() {
-  return spawnSync(process.platform === 'win32' ? 'where' : 'which', ['claude'], { stdio: 'ignore' }).status === 0;
+  return onPath('claude');
 }
 
 // Interactive Claude Code in the project, so the person watches and approves the changes.
 export function startClaude(root, name) {
   const prompt = `Process the clickroom feedback in ${BRIEF} for project "${name}". Read it first, then work through every item.`;
   return new Promise((resolve, reject) => {
-    const child = spawn('claude', [prompt], { cwd: root, stdio: 'inherit' });
+    const child = spawnCmd('claude', [prompt], { cwd: root, stdio: 'inherit' });
     child.on('error', reject);
     child.on('exit', (code) => resolve(code ?? 0));
   });

package/cli/push.js

@@ -7,6 +7,7 @@ import { BACKUP_DIR, copyBuild, cloudUrl, buildPages, baseUrl, localUrl, isTeamm
 import { call } from './client.js';
 import { dim } from './dev.js';
 import { rememberFolder } from './changes.js';
+import { serversInProject, probe } from './detect.js';
 
 const OUT_DIRS = ['dist', 'build', 'out', '.output/public'];
 
@@ -98,11 +99,16 @@ export async function push(name, local, { note, live = false, build, out, quiet
   } 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);
+    // No build step: a folder of plain web files (served by any little server) is its own snapshot.
+    const plain = !cmd && [pkgDir || dir, ...OUT_DIRS.map((d) => path.join(pkgDir || dir, d))].find((d) => fs.existsSync(path.join(d, 'index.html')));
+    if (plain) source = plain;
+    else if (!cmd) throw new NoSnapshot(`No build script in ${path.join(pkgDir || dir, 'package.json')}, so there's nothing to snapshot.`);
+    else {
+      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.`);
@@ -213,6 +219,59 @@ export async function backup(name) {
 }
 
 // Nearest folder with a package.json, from where clickroom was run up to the project root.
+// No dev server running (the owner's Live view): start the project's own (`npm run dev`, else
+// `start`) for as long as the session runs. { target, how, stop } once it answers in this project,
+// null without such a script.
+export async function startDevServer(root, { exclude = [] } = {}) {
+  const dir = packageDir(root, root);
+  if (!dir) return null;
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+  const script = ['dev', 'start'].find((s) => pkg.scripts?.[s]);
+  if (!script) return null;
+  const pm = packageManager(dir);
+  const cmd = `${pm} run ${script}`;
+  if (Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).length && !fs.existsSync(path.join(dir, 'node_modules'))) {
+    console.log(dim(`  Installing the project's packages (${pm} install; the first time only, this can take a minute)…`));
+    await run(`${pm} install`, dir).catch((err) => {
+      throw new FolderProblem(`Installing the project's packages failed.\n${err.message.replace(/^.*\n/, '')}`, `${pm} install fails in this project; please fix it, then run npx clickroom again.`);
+    });
+  }
+  console.log(dim(`  No dev server running, so clickroom starts it: ${cmd}`));
+  // Its own process group, so stopping it also stops what it started (vite, next, …).
+  const child = spawn(cmd, { cwd: dir, shell: true, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, BROWSER: 'none', FORCE_COLOR: '0' } });
+  let log = '';
+  const keep = (d) => (log = (log + d).slice(-4000));
+  child.stdout.on('data', keep);
+  child.stderr.on('data', keep);
+  let exited = false;
+  child.on('exit', () => (exited = true));
+  child.on('error', () => (exited = true));
+  const stop = () => {
+    try {
+      if (process.platform === 'win32') child.kill();
+      else process.kill(-child.pid, 'SIGTERM');
+    } catch {}
+  };
+  for (let i = 0; i < 90 && !exited; i++) {
+    await new Promise((r) => setTimeout(r, 1000));
+    const own = await serversInProject(root, { exclude });
+    for (const s of own) {
+      const p = await probe(s.port);
+      if (p.ok && p.html) return { target: `http://localhost:${s.port}`, how: `${cmd}, started by clickroom`, stop };
+    }
+  }
+  stop();
+  throw new FolderProblem(
+    `${exited ? `\`${cmd}\` stopped` : `\`${cmd}\` didn't start a web server within 90 seconds`}:\n${log.trim().split('\n').slice(-8).map((l) => '    ' + l).join('\n')}`,
+    `\`${cmd}\` doesn't start the dev server in this project; please fix it, then run npx clickroom again.`,
+  );
+}
+
 function packageDir(dir, root) {
   let d = path.resolve(dir);
   const stop = path.resolve(root || dir);

package/cli/run.js

@@ -0,0 +1,24 @@
+import { spawn, execFile, spawnSync } from 'node:child_process';
+
+// Starting the coding agents' commands (claude, codex) on every OS. On Windows they are often
+// npm's `.cmd` launchers, which Node only starts through the shell (cmd.exe): there each argument
+// is quoted, double quotes become single ones and line breaks spaces (cmd can't take them), so
+// anything long or multi-line goes in through stdin or a file instead.
+
+const WIN = process.platform === 'win32';
+const quote = (a) => {
+  const s = String(a).replace(/\r?\n/g, ' ').replace(/"/g, "'");
+  return s === '' || /[\s&|<>^()%!,;=]/.test(s) ? `"${s}"` : s;
+};
+const shellArgs = (args) => (WIN ? args.map(quote) : args);
+
+// Is the command there? (On Windows the shell can't tell us: a missing command just fails.)
+export const onPath = (cmd) => spawnSync(WIN ? 'where' : 'which', [cmd], { stdio: 'ignore', windowsHide: true }).status === 0;
+
+export const spawnCmd = (cmd, args, opts = {}) => spawn(cmd, shellArgs(args), { windowsHide: true, ...opts, shell: WIN });
+
+// execFile's callback, with `missing` when the command isn't installed (ENOENT elsewhere).
+export function execCmd(cmd, args, opts, cb) {
+  if (WIN && !onPath(cmd)) return cb(Object.assign(new Error(`${cmd} not found`), { code: 'ENOENT' }), '');
+  return execFile(cmd, shellArgs(args), { windowsHide: true, ...opts, shell: WIN }, cb);
+}

package/cli/share.js

@@ -6,7 +6,7 @@ import { readLocal, writeLocal, copyBuild, cloudUrl, baseUrl, isTeammate, adminT
 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, FolderProblem, prepareFolder, projectFolder } from './push.js';
+import { push, pushHint, backup, NoSnapshot, FolderProblem, prepareFolder, projectFolder, startDevServer } from './push.js';
 import { folderChanges } from './changes.js';
 import { connectAgents, agentsReport } from './agents.js';
 import { autoNote } from './note.js';
@@ -57,6 +57,17 @@ export async function share(arg, opts) {
     const what = await prepareFolder(cwd, root).catch(explain);
     target = what.kind === 'static' ? { kind: 'static', target: null, source: what.source, how: 'the files as they are' } : { kind: 'build', target: null, source: null, how: 'each push runs its build' };
   }
+  // Nothing running in this project: clickroom starts the project's own dev server (until q), and
+  // a folder of plain web files needs none: its files are the versions.
+  let dev = null;
+  if (!teammate && !arg && (!target || target.uncertain)) {
+    dev = await startDevServer(root, { exclude: [port, 9229, 9230] }).catch(explain);
+    if (dev) {
+      target = { kind: 'url', target: dev.target, how: dev.how };
+      process.on('exit', dev.stop); // also when the session ends with an error
+    }
+    else if (fs.existsSync(path.join(root, 'index.html'))) target = { kind: 'static', target: null, source: root, how: 'the files as they are' };
+  }
   if (!target) {
     throw new Error(
       'No running dev server found for this project.\n' +
@@ -79,8 +90,17 @@ export async function share(arg, opts) {
     console.log(dim(`  Sharing through ${cloud} as you`));
   } else if (cloud) {
     console.log(dim(`  Sharing through ${cloud}`));
+    // The Live view reaches this Mac through the local clickroom server (the relay). Not running
+    // (no `clickroom service`): this session runs it, until q.
     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`.'));
+    if (!relay && target.kind === 'url') {
+      console.log(dim('  Starting the local clickroom server for the Live view…'));
+      server = await startServer({ ...opts, port, tunnel: true }).catch((e) => {
+        console.log(dim(`  Couldn't start it (${e.message}), so the Live view is offline; pushed versions work.`));
+        return null;
+      });
+      delete process.env.CLICKROOM_URL; // startServer points the CLI at it; this session talks to the cloud
+    }
   } else if (await isUp()) {
     console.log(dim(`  Attaching to the clickroom server already running on :${port}`));
   } else {
@@ -253,10 +273,11 @@ export async function share(arg, opts) {
   watcher?.close();
   await call('DELETE', `/__ps/api/projects/${encodeURIComponent(name)}/session`).catch(() => {});
   await backup(name);
+  dev?.stop();
   if (server) {
     server.stop();
     await Promise.race([server.exited, new Promise((r) => setTimeout(r, 3000))]);
-    console.log(dim('\n  Tunnel closed.'));
+    console.log(dim(cloud ? '\n  Live view stopped (pushed versions stay online).' : '\n  Tunnel closed.'));
   }
   process.exit(0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clickroom",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Share prototype builds for review: pins, region comments, threads, versions, and agent hand-off (MCP). Teammates push builds to their team’s clickroom with `clickroom login`.",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "test": "node --test test/*.test.js",
     "screens": "node examples/screens/build.js",
     "demo:seed": "node examples/demo/seed.js",
+    "release": "npm version patch --no-git-tag-version && npm publish && git commit -am \"$(node -p 'require(\"./package.json\").version')\"",
     "prepublishOnly": "node --test test/detect.test.js test/changes.test.js test/webpush.test.js"
   },
   "engines": {