spectoflow 0.22.4 → 0.23.0

package/lib/init.js

@@ -0,0 +1,116 @@
+'use strict';
+/*
+ * Scaffolds .spectoflow/ into a target folder — the logic behind `spectoflow init`, extracted from
+ * bin/spectoflow.js so server code (the hub's Add Project auto-init step, sub-project 4) can call it
+ * too, without any CLI argv/console.log coupling. bin/spectoflow.js's init() is now a thin wrapper:
+ * parse argv, call runInit(), print the result.
+ */
+const fs = require('fs');
+const path = require('path');
+const detect = require('./detect');
+const adapters = require('./adapters');
+const ownership = require('./ownership');
+const manifest = require('./manifest');
+const mcp = require('./mcp');
+const store = require('../templates/lib/store');
+
+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 runInit({ target, templatesDir, version, agentsArg }) {
+  fs.mkdirSync(target, { recursive: true });
+  const notes = [];
+
+  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.');
+  }
+
+  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.');
+  }
+
+  const spectoflowDir = path.join(target, '.spectoflow');
+  copyDir(templatesDir, spectoflowDir);
+
+  const frameworkFiles = ownership.listFrameworkFiles(templatesDir);
+  manifest.writeManifest(spectoflowDir, {
+    version,
+    files: manifest.hashFileMap(spectoflowDir, frameworkFiles),
+  });
+
+  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');
+
+  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).`);
+
+  const added = normalizePlans(target, cfg);
+  if (added) notes.push(`Normalized ${added} existing task(s) with stable ids.`);
+
+  const written = adapters.generate(target, agents);
+
+  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.`);
+  }
+
+  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');
+  }
+
+  return { target, agents, detected, written, notes };
+}
+
+module.exports = { runInit };

package/lib/registry.js

@@ -0,0 +1,101 @@
+'use strict';
+/*
+ * The project registry — ~/.spectoflow/projects.json. Tracks every project spectoflow has seen (via
+ * `spectoflow dashboard`, wired in a later sub-project), so the multi-project hub knows what to list
+ * and switch between. This module owns only the registry file itself; it has no opinion about
+ * dashboards, ports, or servers, and nothing else in the codebase calls it yet.
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const REGISTRY_FILE = 'projects.json';
+
+// Resolution order: an explicit baseDir (unit tests) > SPECTOFLOW_HOME (CLI-level test isolation,
+// same convention as SPECTOFLOW_ROOT/SPECTOFLOW_PORT elsewhere in this codebase) > the real home dir.
+function registryDir(baseDir) {
+  return baseDir || process.env.SPECTOFLOW_HOME || path.join(os.homedir(), '.spectoflow');
+}
+function registryPath(baseDir) {
+  return path.join(registryDir(baseDir), REGISTRY_FILE);
+}
+function hubLockPath(baseDir) {
+  return path.join(registryDir(baseDir), 'hub.lock');
+}
+
+function readRegistry(baseDir) {
+  try { return JSON.parse(fs.readFileSync(registryPath(baseDir), 'utf8')); }
+  catch { return { projects: [] }; }
+}
+
+function writeRegistry(baseDir, data) {
+  const dir = registryDir(baseDir);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(registryPath(baseDir), JSON.stringify(data, null, 2) + '\n');
+}
+
+// 6 hex chars; regenerated on the rare collision against ids already in the registry. `randomFn` is
+// injectable (defaults to crypto.randomBytes) so collision handling is testable without depending on
+// genuine randomness to ever actually collide.
+function genId(existingIds, randomFn) {
+  const rand = randomFn || ((n) => crypto.randomBytes(n));
+  let id;
+  do { id = rand(3).toString('hex'); } while (existingIds.includes(id));
+  return id;
+}
+
+function findByPath(projectPath, baseDir) {
+  const target = path.resolve(projectPath);
+  return readRegistry(baseDir).projects.find((p) => path.resolve(p.path) === target) || null;
+}
+
+// Registers `projectPath` if it isn't already known (matched by normalized path); either way stamps
+// lastOpened to now and returns the entry. Never duplicates the same folder under a second id.
+function addProject(projectPath, baseDir) {
+  const reg = readRegistry(baseDir);
+  const target = path.resolve(projectPath);
+  let entry = reg.projects.find((p) => path.resolve(p.path) === target);
+  if (!entry) {
+    entry = {
+      id: genId(reg.projects.map((p) => p.id)),
+      path: target,
+      name: path.basename(target),
+      lastOpened: new Date().toISOString(),
+    };
+    reg.projects.push(entry);
+  } else {
+    entry.lastOpened = new Date().toISOString();
+  }
+  writeRegistry(baseDir, reg);
+  return entry;
+}
+
+function removeProject(id, baseDir) {
+  const reg = readRegistry(baseDir);
+  const before = reg.projects.length;
+  reg.projects = reg.projects.filter((p) => p.id !== id);
+  writeRegistry(baseDir, reg);
+  return reg.projects.length < before;
+}
+
+function touchProject(id, baseDir) {
+  const reg = readRegistry(baseDir);
+  const entry = reg.projects.find((p) => p.id === id);
+  if (!entry) return false;
+  entry.lastOpened = new Date().toISOString();
+  writeRegistry(baseDir, reg);
+  return true;
+}
+
+// Newest-first — the natural "what did I touch most recently" order for both `spectoflow projects
+// list` and (in a later sub-project) the hub landing page.
+function listProjects(baseDir) {
+  return readRegistry(baseDir).projects.slice()
+    .sort((a, b) => (b.lastOpened || '').localeCompare(a.lastOpened || ''));
+}
+
+module.exports = {
+  readRegistry, writeRegistry, genId, addProject, removeProject, touchProject,
+  findByPath, listProjects, registryPath, hubLockPath,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectoflow",
-  "version": "0.22.4",
+  "version": "0.23.0",
   "description": "Agent-agnostic spec-driven development framework + real-time local control plane. Markdown artifacts, intent router, workflow-by-scope.",
   "keywords": [
     "spec-driven-development",

package/templates/dashboard/handlers.js

@@ -0,0 +1,241 @@
+'use strict';
+/*
+ * spectoflow dashboard — per-project route logic, vendored into every project's
+ * .spectoflow/dashboard/ (copied by init/update, exactly like server.js). Split out of server.js so
+ * a single global hub process (lib/hub-server.js) can load a different project's routes on demand —
+ * see docs/multi-project-hub-design.md's "the server must split in two" addendum.
+ *
+ * createHandlers(root) returns the per-project surface a listener-owning process needs:
+ *   - handleApi(req, res, u, emit): Promise<boolean> — true if this request was an API route and was
+ *     handled (caller should not also try static/SPA fallback); false otherwise. Deliberately excludes
+ *     /api/events: SSE client registration stays owned by whichever file owns the HTTP listener.
+ *   - watchDirs: string[] — dirs (relative to root) whose changes should emit {type:'change'}. The
+ *     caller owns the actual fs.watch calls (it owns emit).
+ *   - onBoot(): call once, the first time this project is opened in a server's lifetime (creates the
+ *     custom-dashboards dir if missing, reconciles any stale in-flight orchestration).
+ */
+const fs = require('fs');
+const path = require('path');
+const store = require('../lib/store');
+const { startRun } = require('./runner');
+const { runSummarize } = require('./summarize');
+const orchestrator = require('./orchestrator');
+const agentsRegistry = require('../lib/agents-registry');
+const files = require('./files');
+
+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({}); } }); }); }
+
+function createHandlers(root) {
+  // Installed framework version: the manifest records it at init/update time. Fallback to the kit's
+  // own package.json — only reachable (and only used) when the server is run straight from templates/
+  // (dev/preview), never from an installed project whose sibling package.json belongs to the user.
+  function frameworkVersion() {
+    try { return JSON.parse(fs.readFileSync(path.join(root, '.spectoflow', '.manifest.json'), 'utf8')).version; } catch {}
+    try { const pk = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf8')); if (pk.name === 'spectoflow') return pk.version; } catch {}
+    return null;
+  }
+  function project() {
+    const p = store.readProject(root);
+    const v = frameworkVersion(); if (v) p.version = v;
+    p.projectName = path.basename(root);
+    p.knownAgents = agentsRegistry.KNOWN_AGENTS.map((a) => ({ id: a.id, label: a.label, headless: a.headless, docsUrl: a.docsUrl }));
+    p.installedAgents = agentsRegistry.installedAgents(root);
+    return p;
+  }
+  function findPlanFileForTask(id) { for (const pl of store.readPlans(root)) for (const ph of pl.phases) if (ph.tasks.find((t) => t.id === id)) return pl.file; return null; }
+
+  const configPath = () => path.join(root, '.spectoflow', 'config.json');
+  function writeConfig(patch) {
+    const cp = configPath(); const cfg = JSON.parse(fs.readFileSync(cp, 'utf8'));
+    if (patch.mode && ['autopilot', 'semi', 'manual'].includes(patch.mode)) cfg.mode = patch.mode;
+    if (typeof patch.language === 'string' && patch.language.trim()) cfg.language = patch.language.trim();
+    if (typeof patch.design === 'string' && /^[a-z0-9-]{1,40}$/.test(patch.design)) cfg.design = patch.design;
+    if (typeof patch.agent === 'string' && patch.agent.trim()) {
+      const id = patch.agent.trim();
+      // Never activate an agent whose CLI isn't actually there — a picked-but-absent agent would just
+      // fail silently the next time something tries to run it.
+      if (!agentsRegistry.isAgentInstalled(id, root)) {
+        const known = agentsRegistry.KNOWN_AGENTS.find((a) => a.id === id);
+        const label = known ? known.label : id;
+        throw new Error(`${label} isn't installed here (its command wasn't found on PATH). Install it, then try again.`);
+      }
+      cfg.agent = id;
+      const known = agentsRegistry.KNOWN_AGENTS.find((a) => a.id === id);
+      if (known && known.runner) { cfg.runners = cfg.runners || {}; if (!cfg.runners[id]) cfg.runners[id] = known.runner; }
+    }
+    fs.writeFileSync(cp, JSON.stringify(cfg, null, 2) + '\n');
+    return cfg;
+  }
+  function promoteAttention(item) {
+    return store.addTask(root, { phase: 'Attention', title: item.text, owner: 'user' });
+  }
+
+  async function handleApi(req, res, u, emit) {
+    const p = u.pathname;
+
+    if (p === '/api/project') { sendJSON(res, 200, project()); return true; }
+
+    if (p === '/api/agentfile' && req.method === 'GET') {
+      const rel = new URL(req.url, 'http://x').searchParams.get('path') || '';
+      const base = path.join(root, '.spectoflow');
+      const aDir = path.join(base, 'agents'), sDir = path.join(base, 'skills');
+      const abs = path.resolve(base, rel);
+      const okDir = abs.startsWith(aDir + path.sep) || abs.startsWith(sDir + path.sep);
+      if (!okDir || !abs.endsWith('.md') || !fs.existsSync(abs) || fs.statSync(abs).isDirectory())
+        { sendJSON(res, 400, { error: 'not an agent/skill file' }); return true; }
+      // Symlink guard: the resolved real path must stay within the (real) scope dirs.
+      let real; try { real = fs.realpathSync(abs); } catch { real = null; }
+      const realA = (() => { try { return fs.realpathSync(aDir); } catch { return aDir; } })();
+      const realS = (() => { try { return fs.realpathSync(sDir); } catch { return sDir; } })();
+      const okReal = real && (real.startsWith(realA + path.sep) || real.startsWith(realS + path.sep));
+      if (!okReal || !real.endsWith('.md') || fs.statSync(real).isDirectory())
+        { sendJSON(res, 400, { error: 'not an agent/skill file' }); return true; }
+      sendJSON(res, 200, { content: fs.readFileSync(real, 'utf8') }); return true;
+    }
+
+    if (p === '/api/files/tree' && req.method === 'GET') { sendJSON(res, 200, { tree: files.tree(root) }); return true; }
+    if (p === '/api/files/read' && req.method === 'GET') {
+      const rel = new URL(req.url, 'http://x').searchParams.get('path') || '';
+      const r = files.readFile(root, rel);
+      sendJSON(res, r.error ? 400 : 200, r); return true;
+    }
+    if (p === '/api/files/write' && req.method === 'POST') {
+      const { path: rel, content } = await body(req);
+      const r = files.writeFile(root, rel, content);
+      if (r.error) { sendJSON(res, 400, r); return true; }
+      emit({ type: 'change' }); sendJSON(res, 200, r); return true;
+    }
+    if (p === '/api/files/mkdir' && req.method === 'POST') {
+      const { path: rel } = await body(req);
+      const r = files.mkdir(root, rel);
+      if (r.error) { sendJSON(res, 400, r); return true; }
+      emit({ type: 'change' }); sendJSON(res, 200, r); return true;
+    }
+
+    if (p === '/api/task' && req.method === 'POST') {
+      const { title, phase, file, owner, level } = await body(req);
+      if (!title || !String(title).trim()) { sendJSON(res, 400, { error: 'A title is required.' }); return true; }
+      const t = store.addTask(root, { title: String(title).trim(), phase, file, owner, level });
+      emit({ type: 'change' }); sendJSON(res, 200, { task: t }); return true;
+    }
+    if (p.startsWith('/api/task/') && req.method === 'PATCH') {
+      const id = decodeURIComponent(p.split('/')[3] || ''); const patch = await body(req);
+      const file = findPlanFileForTask(id); if (!file) { sendJSON(res, 404, { error: `Task ${id} not found.` }); return true; }
+      store.updateTaskLine(root, file, id, patch); emit({ type: 'change' }); sendJSON(res, 200, { ok: true }); return true;
+    }
+    if (/^\/api\/task\/[^/]+\/comment$/.test(p) && req.method === 'POST') {
+      const id = decodeURIComponent(p.split('/')[3] || ''); const { text, action } = await body(req);
+      if (!text || !String(text).trim()) { sendJSON(res, 400, { error: 'Empty comment.' }); return true; }
+      const file = findPlanFileForTask(id); if (!file) { sendJSON(res, 404, { error: `Task ${id} not found.` }); return true; }
+      store.addTaskComment(root, file, id, String(text).trim(), 'me');
+      if (action === 'analyze') store.updateTaskLine(root, file, id, { status: 'to_analyze' });
+      emit({ type: 'change' }); sendJSON(res, 200, { ok: true }); return true;
+    }
+    if (p === '/api/workflow/toggle' && req.method === 'POST') {
+      const { name } = await body(req); const wf = path.join(root, '.spectoflow', 'workflow.md');
+      const lines = fs.readFileSync(wf, 'utf8').split('\n');
+      for (let i = 0; i < lines.length; i++) { const m = lines[i].match(/^(\s*- \[)( |x|X)(\]\s+)(.*)$/);
+        if (m && m[4].replace(/\s*\(optional\)\s*$/i, '').trim() === name) lines[i] = m[1] + (m[2].trim() ? ' ' : 'x') + m[3] + m[4]; }
+      fs.writeFileSync(wf, lines.join('\n')); emit({ type: 'change' }); sendJSON(res, 200, { ok: true }); return true;
+    }
+
+    if (p === '/api/run' && req.method === 'POST') {
+      const { prompt, agent } = await body(req);
+      if (!prompt || !String(prompt).trim()) { sendJSON(res, 400, { error: 'Empty request.' }); return true; }
+      const r = startRun(root, { prompt, agent }, emit);
+      if (r.error) { sendJSON(res, 400, { error: r.error }); return true; }
+      sendJSON(res, 200, { runId: r.runId }); return true;
+    }
+
+    if (p === '/api/chat/summarize' && req.method === 'POST') {
+      const { agent } = await body(req);
+      const r = runSummarize(root, { agent }, emit);
+      if (r.error) { sendJSON(res, 400, { error: r.error }); return true; }
+      sendJSON(res, 200, { ok: true }); return true;
+    }
+    if (p === '/api/chat/clear' && req.method === 'POST') {
+      const rt = store.readRuntime(root); rt.messages = []; store.writeRuntime(root, rt);
+      emit({ type: 'change' }); sendJSON(res, 200, { ok: true }); return true;
+    }
+
+    if (p === '/api/orchestrate' && req.method === 'POST') {
+      const { request } = await body(req);
+      if (!request || !String(request).trim()) { sendJSON(res, 400, { error: 'Empty request.' }); return true; }
+      const active = store.readRuntime(root).orchestration;
+      if (active && ['running', 'awaiting_approval'].includes(active.status))
+        { sendJSON(res, 409, { error: 'An orchestration is already active.' }); return true; }
+      const mode = store.readConfig(root).mode || 'semi';
+      orchestrator.runOrchestration({ root, request: String(request).trim(), mode,
+        runStep: orchestrator.defaultRunStep, confirm: orchestrator.defaultConfirm }, emit)
+        .catch((e) => emit({ type: 'message', message: { role: 'orchestrator', kind: 'status', text: 'orchestration error: ' + e.message } }));
+      const o = store.readRuntime(root).orchestration;
+      sendJSON(res, 200, { orchestrationId: o && o.id }); return true;
+    }
+    if (p === '/api/orchestrate/approve' && req.method === 'POST') {
+      const { decision, note } = await body(req);
+      const ok = orchestrator.submitDecision(decision, note);
+      sendJSON(res, ok ? 200 : 409, ok ? { ok: true } : { error: 'No pending approval.' }); return true;
+    }
+
+    if (p === '/api/settings' && req.method === 'POST') {
+      const patch = await body(req);
+      try { const cfg = writeConfig(patch); emit({ type: 'change' }); sendJSON(res, 200, { config: cfg }); }
+      catch (e) { sendJSON(res, 400, { error: String(e && e.message || e) }); }
+      return true;
+    }
+
+    if (p === '/api/attention' && req.method === 'POST') {
+      const { text } = await body(req);
+      if (!text || !String(text).trim()) { sendJSON(res, 400, { error: 'Empty note.' }); return true; }
+      const rt = store.readRuntime(root); rt.attention = rt.attention || [];
+      const item = { id: 'att' + Date.now().toString(36), at: new Date().toISOString(), by: 'me', source: 'user', status: 'open', text: String(text).trim() };
+      rt.attention.unshift(item); store.writeRuntime(root, rt); emit({ type: 'change' });
+      sendJSON(res, 200, { item }); return true;
+    }
+    if (/^\/api\/attention\/[^/]+\/promote$/.test(p) && req.method === 'POST') {
+      const id = decodeURIComponent(p.split('/')[3] || '');
+      const rt = store.readRuntime(root); const it = (rt.attention || []).find((x) => x.id === id);
+      if (!it) { sendJSON(res, 404, { error: 'Note not found.' }); return true; }
+      const t = promoteAttention(it); it.status = 'resolved'; it.promotedTo = t.id;
+      store.writeRuntime(root, rt); emit({ type: 'change' });
+      sendJSON(res, 200, { task: t }); return true;
+    }
+    if (/^\/api\/attention\/[^/]+$/.test(p) && req.method === 'PATCH') {
+      const id = decodeURIComponent(p.split('/')[3] || '');
+      const patch = await body(req);
+      const rt = store.readRuntime(root); const it = (rt.attention || []).find((x) => x.id === id);
+      if (!it) { sendJSON(res, 404, { error: 'Note not found.' }); return true; }
+      if (typeof patch.text === 'string' && patch.text.trim()) it.text = patch.text.trim();
+      if (patch.status && ['open', 'resolved'].includes(patch.status)) it.status = patch.status;
+      store.writeRuntime(root, rt); emit({ type: 'change' });
+      sendJSON(res, 200, { item: it }); return true;
+    }
+    if (/^\/api\/attention\/[^/]+$/.test(p) && req.method === 'DELETE') {
+      const id = decodeURIComponent(p.split('/')[3] || '');
+      const rt = store.readRuntime(root); rt.attention = (rt.attention || []).filter((x) => x.id !== id);
+      store.writeRuntime(root, rt); emit({ type: 'change' });
+      sendJSON(res, 200, { ok: true }); return true;
+    }
+
+    return false;
+  }
+
+  function onBoot() {
+    // A project that hasn't used Customize yet won't have this dir on disk, and `spectoflow init` on
+    // an older install won't have created it either.
+    try { fs.mkdirSync(path.join(root, '.spectoflow', 'dashboard', 'custom'), { recursive: true }); } catch (_) {}
+    // A process restart loses any in-flight orchestration; without this, a stale 'running' or
+    // 'awaiting_approval' status wedges the /api/orchestrate 409 guard forever. Not a real resume —
+    // just clears the wedge so a fresh orchestration can start.
+    try { orchestrator.reconcileOnBoot(root); } catch (_) {}
+  }
+
+  return {
+    handleApi,
+    watchDirs: ['plans', 'specs', '.spectoflow', '.spectoflow/dashboard/custom'],
+    onBoot,
+  };
+}
+
+module.exports = { createHandlers };