spectoflow 0.23.0 → 0.23.1

package/lib/hub-server.js

@@ -55,6 +55,19 @@ function getProject(id) {
   return proj;
 }
 
+// Only called after getProject(id) already returned null — figures out WHY, so the 404 points the
+// user at the right fix instead of a bare "unknown project". The two common real causes: never
+// registered at all, vs. registered but this project predates handlers.js (needs `spectoflow
+// update`) or its folder moved/was deleted.
+function projectErrorMessage(id) {
+  const entry = registry.listProjects().find((p) => p.id === id);
+  if (!entry) return 'Unknown project.';
+  if (!fs.existsSync(entry.path)) return `Project "${entry.name}" is registered, but its folder no longer exists at ${entry.path}.`;
+  const handlersPath = path.join(entry.path, '.spectoflow', 'dashboard', 'handlers.js');
+  if (!fs.existsSync(handlersPath)) return `Project "${entry.name}" needs an update — run \`spectoflow update\` inside it, then reload this page.`;
+  return `Project "${entry.name}" is registered, but its dashboard code failed to load — check its .spectoflow/dashboard/handlers.js for errors.`;
+}
+
 // 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
@@ -195,7 +208,7 @@ const server = http.createServer(async (req, res) => {
     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.' });
+      if (!proj) return sendJSON(res, 404, { error: projectErrorMessage(id) });
       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));
@@ -211,7 +224,7 @@ const server = http.createServer(async (req, res) => {
     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.' });
+      if (!proj) return sendJSON(res, 404, { error: projectErrorMessage(id) });
       const handled = await proj.handlers.handleApi(req, res, u, proj.emit);
       if (handled) return;
       res.writeHead(404); return res.end('Not found');
@@ -220,7 +233,7 @@ const server = http.createServer(async (req, res) => {
     if (m) {
       const id = m[1];
       const proj = getProject(id);
-      if (!proj) { res.writeHead(404); return res.end('Unknown project.'); }
+      if (!proj) { res.writeHead(404); return res.end(projectErrorMessage(id)); }
       registry.touchProject(id);
       return serveStatic(m[2] || '/', req, res);
     }

package/package.json

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