@axiomatic-labs/claudeflow 2.30.0 → 2.32.0

package/bin/cli.js

@@ -19,7 +19,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const SUBCOMMANDS = new Set(['install', 'version', '--version', '-v', 'help', '--help', '-h', 'doctor', 'panel']);
+const SUBCOMMANDS = new Set(['install', 'version', '--version', '-v', 'help', '--help', '-h', 'doctor', 'panel', 'preview']);
 
 function inClaudeflowProject(startDir) {
   let dir = path.resolve(startDir);
@@ -57,6 +57,11 @@ async function runSubcommand(command) {
       await panel(process.argv.slice(3));
       return;
     }
+    case 'preview': {
+      const preview = require('../lib/preview.js');
+      await preview(process.argv.slice(3));
+      return;
+    }
     case 'help':
     case '--help':
     case '-h':
@@ -69,6 +74,7 @@ async function runSubcommand(command) {
       console.log(`    ${ui.CYAN}install${ui.RESET}    Install or update Claudeflow in the current project`);
       console.log(`    ${ui.CYAN}doctor${ui.RESET}     Diagnose local issues (CDP port, stale lockfiles); add --fix to repair`);
       console.log(`    ${ui.CYAN}panel${ui.RESET}      Open the local web dashboard for hooks, CLAUDE.md, and run state`);
+      console.log(`    ${ui.CYAN}preview${ui.RESET}    Live-reload server for prototypes (.claudeflow/tmp/prototypes/) — run once, leave it`);
       console.log(`    ${ui.CYAN}version${ui.RESET}    Show version info`);
       console.log(`    ${ui.CYAN}help${ui.RESET}       Show this message`);
       console.log('');

package/lib/preview.js

@@ -0,0 +1,335 @@
+// `claudeflow preview` — standing, decoupled live-preview server for prototypes.
+//
+// Serves .claudeflow/tmp/prototypes/ over http://127.0.0.1:<port>, watches the
+// files, and pushes live updates over SSE — CSS edits hot-swap (no flicker),
+// HTML edits reload only the changed document / the content iframe (the shell
+// stays). The user runs this ONCE and leaves it; the /claudeflow-prototype flow
+// just writes files into the watched dir and never touches this process. That
+// decoupling is the whole point: the fragility the project hit came from servers
+// the BUILD/observer flow spawned + killed — this one is user-owned (start it,
+// Ctrl-C to stop), so the flow adds no steps and manages no process.
+//
+// Zero runtime dependencies — Node built-ins only. Opened directly as file://,
+// a prototype is still a static snapshot; live-reload is purely this server's job
+// (the live client is INJECTED into served HTML, so prototype files stay pure).
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const ui = require('./ui.js');
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.map': 'application/json; charset=utf-8',
+};
+
+const SSE_PATH = '/__livereload';
+
+// Injected into every served .html. Connects to the SSE stream; CSS changes
+// hot-swap the <link>s (flicker-free), other changes reload the changed
+// document — or, if this doc is the shell (has an <iframe>), just its iframe
+// so navigation + the shell survive.
+const LIVE_CLIENT = `
+<script data-claudeflow-livereload>
+(function () {
+  try {
+    var es = new EventSource(${JSON.stringify(SSE_PATH)});
+    es.onmessage = function (e) {
+      var p = (e.data || '').trim();
+      if (!p) return;
+      if (/\\.css($|\\?)/.test(p)) {
+        document.querySelectorAll('link[rel="stylesheet"]').forEach(function (l) {
+          var u = l.href.split('?')[0];
+          l.href = u + '?t=' + Date.now();
+        });
+        return;
+      }
+      var here = decodeURIComponent(location.pathname.replace(/^\\//, ''));
+      if (p && here && (p === here || here.endsWith(p) || p.endsWith(here))) {
+        location.reload();
+        return;
+      }
+      var f = document.querySelector('iframe');
+      if (f) { try { f.contentWindow.location.reload(); return; } catch (_) {} }
+      location.reload();
+    };
+  } catch (_) {}
+})();
+</script>`;
+
+function listPrototypes(root) {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .filter((name) => fs.existsSync(path.join(root, name, 'index.html')))
+    .sort();
+}
+
+function listingPage(root) {
+  const protos = listPrototypes(root);
+  const items = protos.length
+    ? protos
+        .map((p) => `<li><a href="/${p}/index.html">${p}</a></li>`)
+        .join('\n')
+    : '<li class="muted">No prototypes yet — assemble one with /claudeflow-prototype (writes into .claudeflow/tmp/prototypes/).</li>';
+  return `<!doctype html><html><head><meta charset="utf-8"><title>claudeflow preview</title>
+<style>body{font:15px/1.5 -apple-system,system-ui,sans-serif;max-width:640px;margin:48px auto;padding:0 20px;color:#1c1c22}
+h1{font-size:18px}a{color:#5050d4}.muted{color:#717180}li{margin:6px 0}</style></head>
+<body><h1>claudeflow preview</h1><p class="muted">Serving <code>.claudeflow/tmp/prototypes/</code> with live reload.</p>
+<ul>${items}</ul></body></html>`;
+}
+
+// Resolve the requested URL to a file under root, blocking path traversal.
+function resolveFile(root, urlPath) {
+  const clean = decodeURIComponent(urlPath.split('?')[0]).replace(/\/+$/, '');
+  const abs = path.normalize(path.join(root, clean));
+  if (abs !== root && !abs.startsWith(root + path.sep)) return null; // traversal guard
+  return abs;
+}
+
+function injectLiveClient(html) {
+  const marker = /<\/body>/i;
+  return marker.test(html)
+    ? html.replace(marker, LIVE_CLIENT + '\n</body>')
+    : html + LIVE_CLIENT;
+}
+
+// Debounced recursive watcher with a polling fallback (recursive fs.watch is not
+// supported on every platform/Node). Calls onChange(relPath) on edits.
+function watch(root, onChange) {
+  let timer = null;
+  let lastPath = '';
+  const fire = (rel) => {
+    lastPath = rel || lastPath;
+    clearTimeout(timer);
+    timer = setTimeout(() => onChange(lastPath), 120);
+  };
+  try {
+    const w = fs.watch(root, { recursive: true }, (_evt, filename) => {
+      if (filename) fire(String(filename).split(path.sep).join('/'));
+    });
+    w.on('error', () => {});
+    return () => w.close();
+  } catch {
+    // Polling fallback: scan mtimes every second.
+    const seen = new Map();
+    const scan = (dir, base) => {
+      let ents = [];
+      try {
+        ents = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of ents) {
+        const abs = path.join(dir, e.name);
+        const rel = base ? base + '/' + e.name : e.name;
+        if (e.isDirectory()) {
+          scan(abs, rel);
+        } else {
+          let m = 0;
+          try {
+            m = fs.statSync(abs).mtimeMs;
+          } catch {
+            continue;
+          }
+          if (seen.has(rel) && seen.get(rel) !== m) fire(rel);
+          seen.set(rel, m);
+        }
+      }
+    };
+    scan(root, '');
+    const iv = setInterval(() => scan(root, ''), 1000);
+    return () => clearInterval(iv);
+  }
+}
+
+function openBrowser(url) {
+  const cmd =
+    process.platform === 'darwin'
+      ? { c: 'open', a: [url] }
+      : process.platform === 'win32'
+        ? { c: 'cmd', a: ['/c', 'start', '', url] }
+        : { c: 'xdg-open', a: [url] };
+  try {
+    const child = spawn(cmd.c, cmd.a, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch {
+    /* best-effort */
+  }
+}
+
+function parseArgs(argv) {
+  const out = { proto: null, port: null, open: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--port' || a === '-p') out.port = Number(argv[++i]);
+    else if (a === '--no-open') out.open = false;
+    else if (!a.startsWith('-')) out.proto = a;
+  }
+  return out;
+}
+
+async function preview(argv = []) {
+  const { proto, port: wantPort, open } = parseArgs(argv);
+  const cwd = process.cwd();
+  const protosRoot = path.join(cwd, '.claudeflow', 'tmp', 'prototypes');
+
+  // Root to serve: a specific prototype subdir, or the prototypes parent (listing).
+  let root = protosRoot;
+  if (proto) {
+    const sub = path.join(protosRoot, proto);
+    if (!fs.existsSync(sub)) {
+      console.error(
+        `${ui.RED}No prototype "${proto}" under ${protosRoot}${ui.RESET}`,
+      );
+      return 1;
+    }
+    root = sub;
+  }
+  try {
+    fs.mkdirSync(protosRoot, { recursive: true });
+  } catch {
+    /* best-effort — listing/watch handle a missing dir */
+  }
+
+  const clients = new Set();
+  const server = http.createServer((req, res) => {
+    const urlPath = (req.url || '/').split('?')[0];
+
+    if (urlPath === SSE_PATH) {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+      });
+      res.write(': connected\n\n');
+      clients.add(res);
+      req.on('close', () => clients.delete(res));
+      return;
+    }
+
+    // Listing at root when serving the prototypes parent and no index there.
+    if ((urlPath === '/' || urlPath === '') && !fs.existsSync(path.join(root, 'index.html'))) {
+      const body = listingPage(root);
+      res.writeHead(200, { 'Content-Type': MIME['.html'], 'Cache-Control': 'no-store' });
+      res.end(injectLiveClient(body));
+      return;
+    }
+
+    let file = resolveFile(root, urlPath);
+    if (!file) {
+      res.writeHead(403);
+      res.end('Forbidden');
+      return;
+    }
+    try {
+      if (fs.statSync(file).isDirectory()) file = path.join(file, 'index.html');
+    } catch {
+      /* fall through to 404 below */
+    }
+    let buf;
+    try {
+      buf = fs.readFileSync(file);
+    } catch {
+      res.writeHead(404, { 'Content-Type': MIME['.html'] });
+      res.end(injectLiveClient('<!doctype html><body style="font-family:system-ui;padding:40px">404 — not found</body>'));
+      return;
+    }
+    const ext = path.extname(file).toLowerCase();
+    const type = MIME[ext] || 'application/octet-stream';
+    if (ext === '.html') {
+      res.writeHead(200, { 'Content-Type': type, 'Cache-Control': 'no-store' });
+      res.end(injectLiveClient(buf.toString('utf8')));
+    } else {
+      res.writeHead(200, { 'Content-Type': type, 'Cache-Control': 'no-store' });
+      res.end(buf);
+    }
+  });
+
+  const stopWatch = watch(protosRoot, (rel) => {
+    for (const c of clients) {
+      try {
+        c.write(`data: ${rel}\n\n`);
+      } catch {
+        /* drop dead client */
+      }
+    }
+  });
+
+  const onPort = (actualPort) => {
+    const url = `http://127.0.0.1:${actualPort}/`;
+    console.log('');
+    console.log(`  ${ui.GREEN}claudeflow preview${ui.RESET} — live reload for prototypes`);
+    console.log(`  ${ui.CYAN}${url}${ui.RESET}  ${ui.DIM}(serving .claudeflow/tmp/prototypes/)${ui.RESET}`);
+    console.log(`  ${ui.DIM}CSS edits hot-swap (no flicker); HTML edits reload the changed view. Ctrl-C to stop.${ui.RESET}`);
+    console.log('');
+    if (open) openBrowser(proto ? url : url);
+  };
+
+  await new Promise((resolve) => {
+    const tryListen = (p, allowFallback) => {
+      server.once('error', (err) => {
+        if (err && err.code === 'EADDRINUSE' && allowFallback) {
+          tryListen(0, false); // OS-assigned free port
+        } else {
+          console.error(`${ui.RED}preview server error: ${err.message}${ui.RESET}`);
+          resolve();
+        }
+      });
+      server.listen(p, '127.0.0.1', () => {
+        onPort(server.address().port);
+        resolve();
+      });
+    };
+    tryListen(wantPort || 4321, !wantPort);
+  });
+
+  const shutdown = () => {
+    try {
+      stopWatch();
+    } catch {
+      /* ignore */
+    }
+    for (const c of clients) {
+      try {
+        c.end();
+      } catch {
+        /* ignore */
+      }
+    }
+    server.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 300).unref();
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  // Keep the process alive (standing server).
+  return new Promise(() => {});
+}
+
+module.exports = preview;
+module.exports.injectLiveClient = injectLiveClient;
+module.exports.resolveFile = resolveFile;
+module.exports.listPrototypes = listPrototypes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiomatic-labs/claudeflow",
-  "version": "2.30.0",
+  "version": "2.32.0",
   "description": "Claudeflow — AI-powered development toolkit for Claude Code. Skills, agents, hooks, and quality gates that ship production apps.",
   "bin": {
     "claudeflow": "./bin/cli.js"