spectoflow 0.22.4 → 0.23.0

package/bin/spectoflow.js

@@ -9,6 +9,8 @@ const adapters = require('../lib/adapters');
 const detect = require('../lib/detect');
 const ownership = require('../lib/ownership');
 const manifest = require('../lib/manifest');
+const registry = require('../lib/registry');
+const initLib = require('../lib/init');
 const mcp = require('../lib/mcp');
 const { startRun } = require('../templates/dashboard/runner');
 const { buildCustomizePrompt } = require('../templates/lib/customize-prompts');
@@ -93,125 +95,16 @@ function probeDashboard(port, timeoutMs = 500) {
   });
 }
 
-function copyDir(src, dst) {
-  fs.mkdirSync(dst, { recursive: true });
-  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
-    const s = path.join(src, e.name), d = path.join(dst, e.name);
-    if (e.isDirectory()) copyDir(s, d);
-    else if (!fs.existsSync(d)) fs.copyFileSync(s, d);
-  }
-}
-
-// Existing project: give id-less checkbox tasks a stable id, in place.
-const ID_RE = /^[A-Za-z]{1,5}-?\d+[A-Za-z]?$/;
-function normalizePlans(root, config) {
-  const dirName = store.resolvePlansDir(root, config || store.readConfig(root));
-  const dir = path.join(root, dirName);
-  if (!fs.existsSync(dir)) return 0;
-  let added = 0, seq = 1;
-  for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.md'))) {
-    const fp = path.join(dir, f);
-    const lines = fs.readFileSync(fp, 'utf8').split('\n');
-    let touched = false;
-    for (let i = 0; i < lines.length; i++) {
-      const m = lines[i].match(/^(\s*- \[[ xX]\]\s+)(\S+)(\s.*)?$/);
-      if (m && !ID_RE.test(m[2])) {
-        const id = 'T-' + String(seq++).padStart(3, '0');
-        lines[i] = `${m[1]}${id} ${m[2]}${m[3] || ''}`;
-        touched = true; added++;
-      } else if (m) { seq++; }
-    }
-    if (touched) fs.writeFileSync(fp, lines.join('\n'));
-  }
-  return added;
-}
-
 function init() {
   const target = path.resolve(argv[1] && !argv[1].startsWith('--') ? argv[1] : '.');
   const agentsArg = (argv.find((a) => a.startsWith('--agent=')) || '').split('=')[1];
-  fs.mkdirSync(target, { recursive: true });
-  const notes = [];
-
-  // explicit --agent wins; otherwise detect installed agents; otherwise fall back to claude + codex
-  let agents, detected = [];
-  if (agentsArg) {
-    agents = agentsArg.split(',');
-  } else {
-    detected = detect.detectAgents(target);
-    agents = detected.length ? detected : ['claude', 'codex'];
-    notes.push(detected.length
-      ? `Detected agent(s): ${detected.join(', ')} — active: ${agents[0]}.`
-      : 'No agent CLI detected — defaulted to claude + codex.');
-  }
-
-  // preserve an existing CLAUDE.md
-  const claude = path.join(target, 'CLAUDE.md');
-  if (fs.existsSync(claude) && !fs.existsSync(claude + '.tomerge')) {
-    fs.renameSync(claude, claude + '.tomerge');
-    notes.push('Existing CLAUDE.md preserved as CLAUDE.md.tomerge — your agent merges it on first run.');
-  }
-
-  // canonical framework → .spectoflow/
-  const spectoflowDir = path.join(target, '.spectoflow');
-  copyDir(TPL, spectoflowDir);
-
-  // record the install baseline so `update` can tell untouched framework files from user edits
-  const frameworkFiles = ownership.listFrameworkFiles(TPL);
-  manifest.writeManifest(spectoflowDir, {
-    version: VERSION,
-    files: manifest.hashFileMap(spectoflowDir, frameworkFiles),
-  });
-
-  // set the active agent and seed runner commands from the selected/detected agents
-  const cfgPath = path.join(spectoflowDir, 'config.json');
-  const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
-  cfg.agent = agents[0];
-  cfg.runners = { ...cfg.runners, ...adapters.defaultRunners(agents) };
-  fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
-
-  // artifact folders — reuse an existing differently-named folder (e.g. a project that already
-  // keeps its plans in `plan/`, singular) instead of always forcing the plans/specs convention;
-  // mkdir is a no-op when the resolved folder already exists.
-  const plansDirName = store.resolvePlansDir(target, cfg);
-  const specsDirName = store.resolveSpecsDir(target, cfg);
-  fs.mkdirSync(path.join(target, specsDirName), { recursive: true });
-  fs.mkdirSync(path.join(target, plansDirName), { recursive: true });
-  if (plansDirName !== 'plans') notes.push(`Using existing '${plansDirName}/' as the plans folder (set plansDir in config.json to override).`);
-  if (specsDirName !== 'specs') notes.push(`Using existing '${specsDirName}/' as the specs folder (set specsDir in config.json to override).`);
-
-  // existing project: id-normalize any plans already there
-  const added = normalizePlans(target, cfg);
-  if (added) notes.push(`Normalized ${added} existing task(s) with stable ids.`);
-
-  // per-agent shims
-  const written = adapters.generate(target, agents);
-
-  // wire Playwright MCP into the project's MCP config so the E2E agent can drive a real browser and
-  // generate/run Playwright tests. Idempotent + non-destructive: never touches an existing entry.
-  // npx fetches the server on first use, so this config IS the whole install — spectoflow stays
-  // zero-dep (this writes into the user's project, never into spectoflow).
-  const mcpTargets = [path.join(target, '.mcp.json')];
-  if (agents.includes('cursor')) mcpTargets.push(path.join(target, '.cursor', 'mcp.json'));
-  for (const fp of mcpTargets) {
-    const rel = path.relative(target, fp).split(path.sep).join('/');
-    const r = mcp.mergeMcpServer(fp, 'playwright', mcp.PLAYWRIGHT_MCP);
-    if (r === 'created' || r === 'added') notes.push(`Wired Playwright MCP into ${rel} (npx @playwright/mcp — for the E2E agent; commit it to share).`);
-    else if (r === 'skipped') notes.push(`Left ${rel} as-is (couldn't parse it) — add a 'playwright' MCP server yourself for browser-driven E2E.`);
-  }
-
-  // gitignore the volatile runtime
-  const gi = path.join(target, '.gitignore');
-  const giText = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
-  for (const line of ['.spectoflow/runtime.json', '.spectoflow/.dashboard.lock']) {
-    if (!giText.includes(line)) fs.appendFileSync(gi, ((fs.existsSync(gi) && fs.readFileSync(gi, 'utf8').length) ? '\n' : '') + line + '\n');
-  }
-
+  const r = initLib.runInit({ target, templatesDir: TPL, version: VERSION, agentsArg });
   console.log(logo());
-  console.log(`${c.g('✓')} installed in ${c.bold(target)}`);
+  console.log(`${c.g('✓')} installed in ${c.bold(r.target)}`);
   console.log(`  ${c.dim('.spectoflow/')}   framework — brain, workflow, agents, skills, policy, dashboard, config`);
   console.log(`  ${c.dim('specs/ plans/')}  markdown artifacts (your source of truth)`);
-  written.forEach((w) => console.log(`  ${c.cy('+')} ${w}`));
-  notes.forEach((n) => console.log(`  ${c.y('!')} ${c.dim(n)}`));
+  r.written.forEach((w) => console.log(`  ${c.cy('+')} ${w}`));
+  r.notes.forEach((n) => console.log(`  ${c.y('!')} ${c.dim(n)}`));
   const port = resolvePort(argv);
   console.log(`\n${c.bold('Next')}`);
   console.log(`  ${c.dim('1)')} Open your agent here — or just say what you want to build.`);
@@ -253,21 +146,27 @@ async function update() {
   if (r.newSidecar.length && !dryRun) console.log(`  ${c.y('→')} ${c.dim(`${r.newSidecar.length} *.new file(s) to review and merge — or re-run: spectoflow update --force`)}`);
   console.log('');
 
-  // A running dashboard has the OLD framework code loaded into memory (Node caches `require()`d
-  // modules at process start) — new bytes on disk change nothing until it restarts. Do that
-  // automatically so an update always actually takes effect, instead of leaving a confusing
-  // half-updated dashboard (new static files, stale server logic) until someone thinks to restart.
+  // A running hub has the OLD framework code loaded into memory (Node caches `require()`d modules
+  // per project on first open) — new bytes on disk change nothing until that project's cached code
+  // is invalidated. Do that via a surgical per-project reload so an update always actually takes
+  // effect, without restarting the whole hub (which would disturb every other project open in it).
   if (!dryRun && changed) {
-    const lock = path.join(root, '.spectoflow', '.dashboard.lock');
+    const lockPath = registry.hubLockPath();
     let info = null;
-    try { info = JSON.parse(fs.readFileSync(lock, 'utf8')); } catch {}
+    try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
     if (info && info.port && (await probeDashboard(info.port, 2000))) {
-      console.log(`  ${c.dim('Dashboard is running — restarting it on port ' + info.port + ' to apply the update…')}`);
-      // Restart on the SAME port it was already on, not resolvePort(argv)'s default — `update`
-      // itself was never given a --port, so a naive restartDashboard() would silently move a
-      // non-default-port dashboard back to 4319.
-      argv.push(`--port=${info.port}`);
-      await restartDashboard();
+      const entry = registry.findByPath(root);
+      if (entry) {
+        try {
+          const res = await fetch(`http://localhost:${info.port}/api/hub/reload/${entry.id}`, { method: 'POST' });
+          const body = await res.json().catch(() => ({}));
+          console.log(`  ${c.dim(body.reloaded
+            ? 'Hub is running — reloaded this project\'s server code (other open projects unaffected).'
+            : 'Hub is running, but this project wasn\'t loaded in it yet — nothing to reload.')}`);
+        } catch {
+          console.log(`  ${c.y('!')} Hub is running on port ${info.port} but the reload request failed — restart it yourself if changes don't seem to take effect: ${c.g('spectoflow dashboard restart')}`);
+        }
+      }
     }
   }
 }
@@ -283,6 +182,28 @@ async function dashboard() {
   return startDashboard();
 }
 
+// ---- projects: the multi-project registry's CLI surface (~/.spectoflow/projects.json) ----
+function projectsCmd() {
+  const sub = argv[1];
+  if (sub === 'remove') return projectsRemove(argv[2]);
+  return projectsList();
+}
+function projectsList() {
+  console.log(wordmark());
+  const rows = registry.listProjects();
+  if (!rows.length) {
+    console.log(c.dim('  no projects registered yet — run `spectoflow dashboard` inside one'));
+    return;
+  }
+  const w = Math.max(4, ...rows.map((r) => r.name.length));
+  rows.forEach((r) => console.log(`  ${c.g(r.id)}  ${r.name.padEnd(w)}  ${c.dim(r.path)}`));
+}
+function projectsRemove(id) {
+  if (!id) { console.log('Usage: spectoflow projects remove <id>'); return; }
+  const ok = registry.removeProject(id);
+  console.log(ok ? `${c.g('✓')} removed ${id}` : `${c.y('!')} no project registered with id ${id}`);
+}
+
 // ---- Customize: `spectoflow skill/agent/dashboard create` — the CLI mirror of the dashboard's
 // Settings → Customize UI. Both surfaces build the same natural-language prompt (customize-prompts.js)
 // and post it through the same pipeline (runner.js's startRun — the function /api/run itself calls),
@@ -335,26 +256,31 @@ async function runCustomize(kind) {
   process.exitCode = code;
 }
 
-// Start in the background and return control. Probes first so a second start just reports the running
-// one instead of spawning a duplicate (and never crashes on EADDRINUSE).
+// Start in the background and return control. Registers (or touches) the current folder in the
+// global registry first, then either joins an already-running hub or spawns a new one — probing first
+// so a second start just reports the running one instead of spawning a duplicate.
 async function startDashboard() {
-  const port = resolvePort(argv);
-  const url = `http://localhost:${port}`;
-  if (await probeDashboard(port)) {
-    console.log(`${c.g('●')} dashboard already running → ${c.bold(url)}`);
+  const root = process.cwd();
+  const entry = registry.addProject(root);
+  const boardUrl = (p) => `http://localhost:${p}/p/${entry.id}/board`;
+  const lockPath = registry.hubLockPath();
+  let info = null;
+  try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
+  if (info && info.port && await probeDashboard(info.port)) {
+    console.log(`${c.g('●')} hub already running → ${c.bold(boardUrl(info.port))}`);
     return printDashboardCommands();
   }
-  const local = path.resolve('.spectoflow', 'dashboard', 'server.js');
-  const bundled = path.join(TPL, 'dashboard', 'server.js');
+  const port = resolvePort(argv);
+  const hubPath = path.join(KIT, 'lib', 'hub-server.js');
   const env = Object.assign({}, process.env, { SPECTOFLOW_PORT: String(port) });
-  const child = spawn('node', [fs.existsSync(local) ? local : bundled], { detached: true, stdio: 'ignore', env });
-  child.unref();                                   // let this CLI exit while the server keeps running
+  const child = spawn('node', [hubPath], { detached: true, stdio: 'ignore', env });
+  child.unref();                                   // let this CLI exit while the hub keeps running
   // Confirm it actually came up (a still-releasing port from a just-stopped instance, or any other
   // startup error, would otherwise print a false "started" while the detached process silently died).
   let up = false;
   for (let i = 0; i < 20 && !up; i++) { await new Promise((r) => setTimeout(r, 250)); up = await probeDashboard(port, 300); }
-  if (up) console.log(`${c.g('✓')} dashboard started → ${c.bold(url)}  ${c.dim('(pid ' + child.pid + ')')}`);
-  else console.log(`${c.y('!')} spawned (pid ${child.pid}) but it isn't responding on ${url} yet — check ${c.g('spectoflow dashboard status')} in a moment, or its own output if something's wrong.`);
+  if (up) console.log(`${c.g('✓')} hub started → ${c.bold(boardUrl(port))}  ${c.dim('(pid ' + child.pid + ')')}`);
+  else console.log(`${c.y('!')} spawned (pid ${child.pid}) but it isn't responding on http://localhost:${port} yet — check ${c.g('spectoflow dashboard status')} in a moment, or its own output if something's wrong.`);
   printDashboardCommands();
 }
 
@@ -367,12 +293,13 @@ function printDashboardCommands() {
 }
 
 async function dashboardStatus() {
-  const port = resolvePort(argv);
+  const lockPath = registry.hubLockPath();
+  let info = null;
+  try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
+  const port = (info && info.port) || resolvePort(argv);
   const running = await probeDashboard(port);
-  let pid = null;
-  try { pid = JSON.parse(fs.readFileSync(path.join(process.cwd(), '.spectoflow', '.dashboard.lock'), 'utf8')).pid; } catch {}
-  if (running) console.log(`${c.g('●')} dashboard running → ${c.bold('http://localhost:' + port)}${pid ? c.dim(' (pid ' + pid + ')') : ''}`);
-  else console.log(`${c.dim('○')} dashboard not running`);
+  if (running) console.log(`${c.g('●')} hub running → ${c.bold('http://localhost:' + port)}${info && info.pid ? c.dim(' (pid ' + info.pid + ')') : ''}`);
+  else console.log(`${c.dim('○')} hub not running`);
 }
 
 async function restartDashboard() {
@@ -385,28 +312,27 @@ async function restartDashboard() {
   return startDashboard();
 }
 
-// Stop the running dashboard: read the pidfile it wrote, verify it's actually up, then terminate it
+// Stop the running hub: read the global lock it wrote, verify it's actually up, then terminate it
 // and clear the lock. Safe against a stale lock (a recycled pid) because it only kills when the port
 // still responds.
 async function stopDashboard() {
-  const root = process.cwd();
-  const lock = path.join(root, '.spectoflow', '.dashboard.lock');
+  const lockPath = registry.hubLockPath();
   let info = null;
-  try { info = JSON.parse(fs.readFileSync(lock, 'utf8')); } catch {}
+  try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
   const port = (info && info.port) || resolvePort(argv);
   const running = await probeDashboard(port);
   if (!running) {
-    if (info) { try { fs.unlinkSync(lock); } catch {} }   // stale lock
-    return console.log('No spectoflow dashboard is running.');
+    if (info) { try { fs.unlinkSync(lockPath); } catch {} }   // stale lock
+    return console.log('No spectoflow hub is running.');
   }
   if (info && info.pid) {
     try {
-      process.kill(info.pid);                  // SIGTERM → server clears its own lock (POSIX)
-      try { fs.unlinkSync(lock); } catch {}     // and we clear it too (Windows has no real signals)
-      return console.log(`spectoflow dashboard stopped (pid ${info.pid}, was on http://localhost:${port}).`);
+      process.kill(info.pid);                  // SIGTERM → hub clears its own lock (POSIX)
+      try { fs.unlinkSync(lockPath); } catch {}     // and we clear it too (Windows has no real signals)
+      return console.log(`spectoflow hub stopped (pid ${info.pid}, was on http://localhost:${port}).`);
     } catch {}
   }
-  console.log(`A dashboard is responding on http://localhost:${port} but isn't stoppable via the lock file — stop it where you launched it (Ctrl+C).`);
+  console.log(`A hub is responding on http://localhost:${port} but isn't stoppable via the lock file — stop it where you launched it (Ctrl+C).`);
 }
 
 async function status() {
@@ -422,7 +348,10 @@ async function status() {
   console.log(`${(p.config && p.config.projectType) || 'project'} — mode ${p.config.mode} · lang ${p.config.language}`);
   console.log(`${done}/${tasks.length} tasks done · ${p.specs.length} spec(s) · ${p.agents.length} agents · ${p.skills.length} skills`);
   tasks.filter((t) => t.status === 'in_progress').forEach((t) => console.log(`  > in progress: ${t.id} ${t.title}`));
-  const port = resolvePort(argv);
+  const lockPath = registry.hubLockPath();
+  let info = null;
+  try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
+  const port = (info && info.port) || resolvePort(argv);
   const running = await probeDashboard(port);
   console.log(`dashboard: ${running ? `running → http://localhost:${port}` : 'not running'}`);
 }
@@ -479,6 +408,7 @@ ${c.bold('Dashboard')}
   ${c.g('dashboard status')}             is it running? (url + pid)
   ${c.g('dashboard stop')}               stop it ${c.dim('(alias: stop)')}
   ${c.g('dashboard restart')}            stop then start
+  ${c.g('projects')} ${c.dim('[remove <id>]')}     list every project seen so far (~/.spectoflow/projects.json)
 
 ${c.bold('Customize')} ${c.dim('— same as Settings → Customize, from the terminal')}
   ${c.g('skill create')} ${c.dim('"<description>" | --auto')}      generate a project skill
@@ -522,6 +452,10 @@ const HELP = {
     ${c.g('stop')}      stop it            ${c.dim('(alias: spectoflow stop)')}
     ${c.g('restart')}   stop then start
     ${c.g('create')}    generate a custom dashboard, e.g. ${c.dim('spectoflow dashboard create "..." --auto')}`,
+  projects: `${c.bold('spectoflow projects')} ${c.dim('[remove <id>]')}\n
+  List every registered project in the global registry at ${c.dim('~/.spectoflow/projects.json')} (stored by
+  ${c.g('spectoflow dashboard')}) — id, name, path. ${c.g('remove <id>')} drops one (e.g. a project that moved
+  or was deleted) from this list only; it never touches that project's own files.`,
   skill: `${c.bold('spectoflow skill create')} ${c.dim('"<description>" [--agent=name]')}\n${c.bold('spectoflow skill create')} ${c.dim('--auto [--agent=name]')}\n
   Generate a project-specific skill — the CLI mirror of Settings → Customize → ${c.bold('Skills')} →
   ${c.bold('Add skill')} in the dashboard. Describe what it should do, or pass ${c.g('--auto')} to have
@@ -547,6 +481,7 @@ const showHelp = (name) => console.log('\n' + HELP[name].trim() + '\n');
 // ---- dispatch ---------------------------------------------------------------
 const fns = {
   init, update, dashboard, stop: stopDashboard, status, list: listAll, help, version,
+  projects: projectsCmd,
   agents: () => { console.log(wordmark()); printAgents(false); },
   skills: () => { console.log(wordmark()); printSkills(false); },
   workflow: () => { console.log(wordmark()); printWorkflow(false); },

package/lib/hub-server.js

@@ -0,0 +1,245 @@
+'use strict';
+/*
+ * The multi-project hub's server process — global (ships under lib/, never vendored into a
+ * project's .spectoflow/). Registry-driven: resolves a project's root + route logic on demand from
+ * ~/.spectoflow/projects.json (see lib/registry.js), keyed by the opaque id in /p/<id>/... URLs.
+ * Each project's own vendored handlers.js is require()'d dynamically by absolute path — Node's
+ * require cache keys by resolved path, so two different projects' identically-named handlers.js
+ * files are cached and run completely independently (see docs/multi-project-hub-design.md).
+ *
+ * URL scheme (settled in the design doc): pages use a path prefix (/p/<id>/board, bookmarkable on
+ * their own); every /api/* call instead takes a ?p=<id> query param (smaller client diff, and
+ * /api/events already needed a query-param shape for its per-project SSE subscription either way).
+ * A legacy no-prefix route (e.g. /board, a bookmark from before the hub existed) 302s to the
+ * most-recently-opened project, or to the hub root if none are registered yet.
+ *
+ * GET / serves hub.html — the landing page listing every registered project, with an "+ Add project"
+ * flow (browse the filesystem server-side, or paste a path; either way auto-inits a plain folder) —
+ * see /api/hub/* below and docs/multi-project-hub-design.md §3bis.
+ */
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const registry = require('./registry');
+
+const PORT = process.env.SPECTOFLOW_PORT ? Number(process.env.SPECTOFLOW_PORT) : 4319;
+const PUBLIC = path.join(__dirname, '..', 'templates', 'dashboard', 'public');
+const TEMPLATES = path.join(__dirname, '..', 'templates');
+const VERSION = require('../package.json').version;
+const MIME = { '.html':'text/html; charset=utf-8', '.css':'text/css; charset=utf-8', '.js':'application/javascript; charset=utf-8', '.png':'image/png', '.svg':'image/svg+xml', '.ico':'image/x-icon', '.woff2':'font/woff2', '.woff':'font/woff' };
+function sendJSON(res,code,obj){ res.writeHead(code,{'Content-Type':'application/json; charset=utf-8'}); res.end(JSON.stringify(obj)); }
+function body(req) { return new Promise((r) => { let b = ''; req.on('data', (c) => b += c); req.on('end', () => { try { r(JSON.parse(b || '{}')); } catch { r({}); } }); }); }
+
+// id -> { id, root, handlers, clients:Set, emit }, populated lazily on first request for that id and
+// kept alive for the process's life (registries are small; no need to tear down on last-tab-close).
+const projects = new Map();
+function getProject(id) {
+  if (projects.has(id)) return projects.get(id);
+  const entry = registry.listProjects().find((p) => p.id === id);
+  if (!entry) return null;
+  const handlersPath = path.join(entry.path, '.spectoflow', 'dashboard', 'handlers.js');
+  let createHandlers;
+  try { ({ createHandlers } = require(handlersPath)); }
+  catch { return null; } // project's folder moved/deleted, or predates the handlers.js split
+  const handlers = createHandlers(entry.path);
+  const clients = new Set();
+  const emit = (obj) => { const line = 'data: ' + JSON.stringify(obj) + '\n\n'; for (const res of clients) res.write(line); };
+  handlers.onBoot();
+  handlers.watchDirs.forEach((d) => {
+    const dir = path.join(entry.path, d);
+    if (fs.existsSync(dir)) { try { fs.watch(dir, { recursive: false }, () => emit({ type: 'change' })); } catch (_) {} }
+  });
+  const proj = { id, root: entry.path, handlers, clients, emit };
+  projects.set(id, proj);
+  return proj;
+}
+
+// Clears every require.cache entry under this project's own .spectoflow/ tree (its vendored
+// handlers.js and everything IT requires — orchestrator.js, runner.js, files.js, summarize.js,
+// lib/store.js, lib/agents-registry.js) and drops its cached Map entry. The require cache keys by
+// absolute path, so this can never touch another project's identically-named files. Returns false
+// (a harmless no-op, not an error) if this id was never loaded — nothing to invalidate.
+function reloadProject(id) {
+  const proj = projects.get(id);
+  if (!proj) return false;
+  const prefix = path.join(proj.root, '.spectoflow') + path.sep;
+  for (const key of Object.keys(require.cache)) {
+    if (key.startsWith(prefix)) delete require.cache[key];
+  }
+  projects.delete(id);
+  return true;
+}
+
+// ---- hub API: list/add/remove registered projects, browse the filesystem to find one ----
+function projectStats(root) {
+  // Best-effort — a moved/deleted/corrupt project must never break the whole listing.
+  try {
+    const store = require(path.join(root, '.spectoflow', 'lib', 'store.js'));
+    const plans = store.readPlans(root);
+    let total = 0, done = 0;
+    for (const pl of plans) for (const ph of pl.phases) for (const t of ph.tasks) { total++; if (t.status === 'done') done++; }
+    return { total, done };
+  } catch { return null; }
+}
+function listHubProjects() {
+  return registry.listProjects().map((p) => ({ ...p, stats: projectStats(p.path) }));
+}
+function listRoots() {
+  const home = os.homedir();
+  const roots = [{ name: path.basename(home) || home, path: home }];
+  if (process.platform === 'win32') {
+    for (const code of 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') {
+      const drive = `${code}:\\`;
+      if (fs.existsSync(drive)) roots.push({ name: drive, path: drive });
+    }
+  } else if (home !== '/') {
+    roots.push({ name: '/', path: '/' });
+  }
+  return roots;
+}
+function browseDirs(reqPath) {
+  if (!reqPath) return { entries: listRoots(), parent: null, current: null };
+  let abs;
+  try { abs = path.resolve(reqPath); } catch { return { error: 'Invalid path.' }; }
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return { error: 'Not a folder.' };
+  let names;
+  try { names = fs.readdirSync(abs, { withFileTypes: true }); } catch { return { error: 'Cannot read this folder.' }; }
+  const entries = names.filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+    .map((e) => ({ name: e.name, path: path.join(abs, e.name) }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const parent = path.dirname(abs) !== abs ? path.dirname(abs) : null;
+  return { entries, parent, current: abs };
+}
+function addHubProject(rawPath) {
+  let abs;
+  try { abs = path.resolve(rawPath); } catch { return { error: 'Invalid path.' }; }
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return { error: 'That folder does not exist.' };
+  const hasSpectoflow = fs.existsSync(path.join(abs, '.spectoflow'));
+  if (!hasSpectoflow) {
+    const { runInit } = require('./init');
+    runInit({ target: abs, templatesDir: TEMPLATES, version: VERSION });
+  }
+  const entry = registry.addProject(abs);
+  return { entry, initialized: !hasSpectoflow };
+}
+async function handleHubApi(req, res, u) {
+  const p = u.pathname;
+  if (p === '/api/hub/projects' && req.method === 'GET') { sendJSON(res, 200, { projects: listHubProjects() }); return true; }
+  if (p === '/api/hub/projects' && req.method === 'POST') {
+    const { path: rawPath } = await body(req);
+    if (!rawPath || !String(rawPath).trim()) { sendJSON(res, 400, { error: 'A folder path is required.' }); return true; }
+    const r = addHubProject(String(rawPath).trim());
+    if (r.error) { sendJSON(res, 400, r); return true; }
+    sendJSON(res, 200, r); return true;
+  }
+  if (/^\/api\/hub\/projects\/[^/]+$/.test(p) && req.method === 'DELETE') {
+    const id = decodeURIComponent(p.split('/')[4] || '');
+    const ok = registry.removeProject(id);
+    sendJSON(res, ok ? 200 : 404, ok ? { ok: true } : { error: 'No project registered with that id.' });
+    return true;
+  }
+  if (p === '/api/hub/browse' && req.method === 'GET') {
+    const reqPath = u.searchParams.get('path') || '';
+    const r = browseDirs(reqPath);
+    sendJSON(res, r.error ? 400 : 200, r);
+    return true;
+  }
+  if (/^\/api\/hub\/reload\/[^/]+$/.test(p) && req.method === 'POST') {
+    const id = decodeURIComponent(p.split('/')[4] || '');
+    const reloaded = reloadProject(id);
+    sendJSON(res, 200, { ok: true, reloaded });
+    return true;
+  }
+  return false;
+}
+
+// Serves one static asset (or the SPA index.html fallback for an extensionless path) from the
+// shared, globally-installed PUBLIC dir — identical logic to templates/dashboard/server.js's own,
+// just factored into a function since both the root-level and /p/<id>/-prefixed requests need it.
+function serveStatic(reqPath, req, res) {
+  const file = reqPath === '/' ? '/index.html' : reqPath;
+  const full = path.join(PUBLIC, path.normalize(file).replace(/^(\.\.[/\\])+/, ''));
+  if (!full.startsWith(PUBLIC)) { res.writeHead(403); return res.end('Forbidden'); }
+  const noCache = { 'Cache-Control': 'no-store, must-revalidate' };
+  fs.readFile(full, (err, data) => {
+    if (err) {
+      if (req.method === 'GET' && !path.extname(reqPath)) {
+        return fs.readFile(path.join(PUBLIC, 'index.html'), (e2, d2) => {
+          if (e2) { res.writeHead(404); return res.end('Not found'); }
+          res.writeHead(200, Object.assign({ 'Content-Type': MIME['.html'] }, noCache)); res.end(d2);
+        });
+      }
+      res.writeHead(404); return res.end('Not found');
+    }
+    const ext = path.extname(full);
+    const headers = ext === '.woff2' || ext === '.woff' ? { 'Cache-Control': 'public, max-age=604800' } : noCache;
+    res.writeHead(200, Object.assign({ 'Content-Type': MIME[ext] || 'application/octet-stream' }, headers)); res.end(data);
+  });
+}
+
+const PROJECT_PREFIX = /^\/p\/([0-9a-f]{6})(\/.*)?$/;
+
+const LOCK = registry.hubLockPath();
+function writeLock(){ try{ fs.mkdirSync(path.dirname(LOCK),{recursive:true}); fs.writeFileSync(LOCK, JSON.stringify({ pid:process.pid, port:PORT, url:`http://localhost:${PORT}`, startedAt:new Date().toISOString() })+'\n'); }catch{} }
+function clearLock(){ try{ const l=JSON.parse(fs.readFileSync(LOCK,'utf8')); if(l.pid===process.pid) fs.unlinkSync(LOCK); }catch{} }
+process.on('exit', clearLock);
+['SIGINT','SIGTERM'].forEach((s)=> process.on(s, ()=>{ clearLock(); process.exit(0); }));
+
+const server = http.createServer(async (req, res) => {
+  const u = new URL(req.url, `http://localhost:${PORT}`);
+  const p = u.pathname;
+  try {
+    const m = p.match(PROJECT_PREFIX);
+
+    if (p === '/api/events') {
+      const id = u.searchParams.get('p');
+      const proj = id && getProject(id);
+      if (!proj) return sendJSON(res, 404, { error: 'Unknown or unreachable project.' });
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+      res.write('data: ' + JSON.stringify({ type: 'hello' }) + '\n\n');
+      proj.clients.add(res); req.on('close', () => proj.clients.delete(res));
+      return;
+    }
+
+    if (p.startsWith('/api/hub/')) {
+      const handled = await handleHubApi(req, res, u);
+      if (handled) return;
+      res.writeHead(404); return res.end('Not found');
+    }
+
+    if (p.startsWith('/api/')) {
+      const id = u.searchParams.get('p');
+      const proj = id && getProject(id);
+      if (!proj) return sendJSON(res, 404, { error: 'Unknown or unreachable project.' });
+      const handled = await proj.handlers.handleApi(req, res, u, proj.emit);
+      if (handled) return;
+      res.writeHead(404); return res.end('Not found');
+    }
+
+    if (m) {
+      const id = m[1];
+      const proj = getProject(id);
+      if (!proj) { res.writeHead(404); return res.end('Unknown project.'); }
+      registry.touchProject(id);
+      return serveStatic(m[2] || '/', req, res);
+    }
+
+    if (p === '/') {
+      return serveStatic('/hub.html', req, res);
+    }
+
+    if (!path.extname(p)) {
+      // legacy no-prefix bookmark (e.g. /board from before the hub existed)
+      const rows = registry.listProjects();
+      const dest = rows.length ? `/p/${rows[0].id}/board` : '/';
+      res.writeHead(302, { Location: dest }); return res.end();
+    }
+
+    // a real static asset (styles.css, app.js, fonts) requested without a /p/<id> prefix — every
+    // page's own asset links are root-absolute, so this is the common case for every page load.
+    return serveStatic(p, req, res);
+  } catch (e) { sendJSON(res, 500, { error: String(e && e.message || e) }); }
+});
+
+server.listen(PORT, () => { writeLock(); console.log(`spectoflow · hub → http://localhost:${PORT}`); });