@axiomatic-labs/claudeflow 2.13.19 → 2.13.21

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']);
+const SUBCOMMANDS = new Set(['install', 'version', '--version', '-v', 'help', '--help', '-h', 'doctor', 'panel']);
 
 function inClaudeflowProject(startDir) {
   let dir = path.resolve(startDir);
@@ -52,6 +52,11 @@ async function runSubcommand(command) {
       const code = await doctor(process.argv.slice(3));
       process.exit(code || 0);
     }
+    case 'panel': {
+      const panel = require('../lib/panel.js');
+      await panel(process.argv.slice(3));
+      return;
+    }
     case 'help':
     case '--help':
     case '-h':
@@ -63,6 +68,7 @@ async function runSubcommand(command) {
       console.log('  Claudeflow commands:');
       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}version${ui.RESET}    Show version info`);
       console.log(`    ${ui.CYAN}help${ui.RESET}       Show this message`);
       console.log('');

package/lib/hook-overrides.js

@@ -0,0 +1,177 @@
+// User hook overrides — toggle individual claudeflow hook handlers without
+// editing the template-managed `.claude/settings.json` directly.
+//
+// File: `.claudeflow/config/user-hook-overrides.json`
+// Shape:
+//   { "version": 1,
+//     "disabledHandlers": [
+//       { "event": "SessionStart", "matcher": "", "handler": "SessionStart/foo.js",
+//         "spec": { "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/SessionStart/foo.js\"" } } ] }
+//
+// The `spec` field captures the original hook entry verbatim so the panel
+// can re-enable a handler later without consulting an external snapshot.
+//
+// Two operations:
+//   - `applyHookOverrides(settings, overrides)`: pure function, returns a
+//     new settings object with disabled handlers removed. Called by
+//     install.js right after writing `.claude/settings.json` so the
+//     effective config respects the overrides on every install/update.
+//   - `toggleHookOverride(...)`: stateful, used by the panel server.
+//     Reads / writes the overrides file and the resolved settings file.
+
+const fs = require('fs');
+const path = require('path');
+
+const OVERRIDES_REL = path.join('.claudeflow', 'config', 'user-hook-overrides.json');
+const SETTINGS_REL = path.join('.claude', 'settings.json');
+const HOOK_PATH_REGEX = /\.claude\/hooks\/(.+?\.js)/;
+
+function readJsonSafe(absPath) {
+  try { return JSON.parse(fs.readFileSync(absPath, 'utf8')); } catch { return null; }
+}
+
+function writeJson(absPath, data) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, JSON.stringify(data, null, 2) + '\n');
+}
+
+function normalizeHandlerPath(command) {
+  if (!command) return '';
+  const m = HOOK_PATH_REGEX.exec(command);
+  return m ? m[1] : command.replace(/^node\s+/, '').replace(/^["']|["']$/g, '').trim();
+}
+
+function defaultOverrides() {
+  return { version: 1, disabledHandlers: [] };
+}
+
+function readOverrides(projectRoot) {
+  const data = readJsonSafe(path.join(projectRoot, OVERRIDES_REL));
+  if (!data || typeof data !== 'object') return defaultOverrides();
+  return {
+    version: data.version || 1,
+    disabledHandlers: Array.isArray(data.disabledHandlers) ? data.disabledHandlers : [],
+  };
+}
+
+function writeOverrides(projectRoot, overrides) {
+  writeJson(path.join(projectRoot, OVERRIDES_REL), overrides);
+}
+
+function matchesOverride(override, event, matcher, handlerCommand) {
+  if (override.event !== event) return false;
+  if ((override.matcher || '') !== (matcher || '')) return false;
+  return normalizeHandlerPath(handlerCommand) === override.handler;
+}
+
+// Returns a fresh settings object with handlers disabled by `overrides` removed.
+// Empty rules are pruned. The shape of `settings.hooks` is preserved otherwise.
+function applyHookOverrides(settings, overrides) {
+  const disabled = (overrides && overrides.disabledHandlers) || [];
+  if (!disabled.length || !settings || !settings.hooks) return settings;
+  const next = JSON.parse(JSON.stringify(settings));
+  const hooks = next.hooks;
+  for (const event of Object.keys(hooks)) {
+    const rules = Array.isArray(hooks[event]) ? hooks[event] : [];
+    for (let i = rules.length - 1; i >= 0; i--) {
+      const rule = rules[i] || {};
+      const matcher = rule.matcher || '';
+      const remaining = (rule.hooks || []).filter(
+        (h) => !disabled.some((d) => matchesOverride(d, event, matcher, h.command || '')),
+      );
+      if (remaining.length === 0) rules.splice(i, 1);
+      else rule.hooks = remaining;
+    }
+    hooks[event] = rules;
+  }
+  return next;
+}
+
+// Apply on disk: read settings.json + overrides, write the pruned settings
+// back. Idempotent — calling twice produces the same file.
+function applyOverridesToFile(projectRoot) {
+  const settingsPath = path.join(projectRoot, SETTINGS_REL);
+  const settings = readJsonSafe(settingsPath);
+  if (!settings) return false;
+  const overrides = readOverrides(projectRoot);
+  if (!overrides.disabledHandlers.length) return false;
+  const next = applyHookOverrides(settings, overrides);
+  fs.writeFileSync(settingsPath, JSON.stringify(next, null, 2) + '\n');
+  return true;
+}
+
+// Find a hook entry in current settings.json by event/matcher/handler.
+// Used when disabling: we capture the spec before removing it.
+function findHandlerInSettings(settings, event, matcher, handler) {
+  const rules = (settings.hooks && settings.hooks[event]) || [];
+  for (const rule of rules) {
+    if ((rule.matcher || '') !== (matcher || '')) continue;
+    for (const h of rule.hooks || []) {
+      if (normalizeHandlerPath(h.command || '') === handler) return h;
+    }
+  }
+  return null;
+}
+
+// Add an entry back to the live settings under the right event/matcher.
+function restoreHandlerInSettings(settings, event, matcher, spec) {
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks[event]) settings.hooks[event] = [];
+  const rules = settings.hooks[event];
+  let rule = rules.find((r) => (r.matcher || '') === (matcher || ''));
+  if (!rule) {
+    rule = { matcher, hooks: [] };
+    rules.push(rule);
+  }
+  // Avoid duplicate restoration if the spec is already present
+  const already = rule.hooks.some((h) => normalizeHandlerPath(h.command || '') === normalizeHandlerPath(spec.command || ''));
+  if (!already) rule.hooks.push(spec);
+}
+
+// Stateful toggle used by the panel.
+//   - disable=true: capture spec from current settings.json, append to
+//     overrides, remove from settings.json
+//   - disable=false: pop spec from overrides, restore to settings.json
+function toggleHookOverride(projectRoot, { event, matcher = '', handler, disable }) {
+  const settingsPath = path.join(projectRoot, SETTINGS_REL);
+  const settings = readJsonSafe(settingsPath) || { hooks: {} };
+  const overrides = readOverrides(projectRoot);
+  const matcherKey = matcher || '';
+
+  if (disable) {
+    const already = overrides.disabledHandlers.find(
+      (d) => d.event === event && (d.matcher || '') === matcherKey && d.handler === handler,
+    );
+    if (already) return { state: 'noop', reason: 'already-disabled' };
+    const spec = findHandlerInSettings(settings, event, matcherKey, handler);
+    if (!spec) return { state: 'error', reason: 'handler-not-found-in-settings' };
+    overrides.disabledHandlers.push({ event, matcher: matcherKey, handler, spec });
+    writeOverrides(projectRoot, overrides);
+    const next = applyHookOverrides(settings, overrides);
+    fs.writeFileSync(settingsPath, JSON.stringify(next, null, 2) + '\n');
+    return { state: 'disabled' };
+  }
+
+  const idx = overrides.disabledHandlers.findIndex(
+    (d) => d.event === event && (d.matcher || '') === matcherKey && d.handler === handler,
+  );
+  if (idx === -1) return { state: 'noop', reason: 'not-disabled' };
+  const [removed] = overrides.disabledHandlers.splice(idx, 1);
+  if (!removed.spec) return { state: 'error', reason: 'no-spec-recorded' };
+  restoreHandlerInSettings(settings, event, matcherKey, removed.spec);
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  writeOverrides(projectRoot, overrides);
+  return { state: 'enabled' };
+}
+
+module.exports = {
+  OVERRIDES_REL,
+  SETTINGS_REL,
+  applyHookOverrides,
+  applyOverridesToFile,
+  readOverrides,
+  writeOverrides,
+  toggleHookOverride,
+  normalizeHandlerPath,
+  matchesOverride,
+};

package/lib/install.js

@@ -4,6 +4,7 @@ const { execSync, execFileSync } = require('child_process');
 const { requireAuth } = require('./auth.js');
 const { getLatestRelease, downloadReleaseAsset } = require('./download.js');
 const { writeLocalVersion, readLocalVersion } = require('./version.js');
+const { applyOverridesToFile: applyHookOverridesToFile } = require('./hook-overrides.js');
 const ui = require('./ui.js');
 
 // Template skills are shipped inside the ZIP. Copy every managed
@@ -85,6 +86,10 @@ async function run() {
     fs.mkdirSync(path.join(cwd, '.claude'), { recursive: true });
     if (fs.existsSync(srcSettings)) {
       syncClaudeSettings(srcSettings, dstSettings);
+      // Re-apply user hook overrides (if any) so disabled handlers stay
+      // disabled across update — without this, every update would resurrect
+      // hooks the user explicitly turned off via `claudeflow panel`.
+      applyHookOverridesToFile(cwd);
     }
 
     // Upsert playwright entry in .mcp.json with project-specific CDP port.

package/lib/panel.js

@@ -0,0 +1,740 @@
+// `claudeflow panel` — local web dashboard for inspecting claudeflow state.
+//
+// Spawns a Node http server bound to 127.0.0.1 on a free port, opens the
+// system browser, and serves a single-page UI that calls JSON endpoints
+// to render: version, CLAUDE.md state, hooks, MCP/observer, setup-context,
+// active build run, and doctor checks.
+//
+// Zero runtime dependencies — Node built-ins only. The HTML/CSS/JS frontend
+// lives inline as a string template.
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { URL } = require('url');
+
+const ui = require('./ui.js');
+const {
+  deriveCdpPort,
+  checkCdpPortMismatch,
+  checkStaleLockfiles,
+  readPlaywrightCdpEndpoint,
+} = require('./doctor.js');
+const {
+  readOverrides,
+  toggleHookOverride,
+  normalizeHandlerPath,
+} = require('./hook-overrides.js');
+
+const IDLE_SHUTDOWN_MS = 30 * 60 * 1000; // 30 min
+
+// ─── data collectors ─────────────────────────────────────────────
+
+function getVersionInfo(cwd) {
+  let installed = null;
+  for (const rel of [path.join('.claudeflow', 'version'), path.join('.claude', '.claudeflow-version')]) {
+    try {
+      installed = fs.readFileSync(path.join(cwd, rel), 'utf8').trim().replace(/^v/, '');
+      if (installed) break;
+    } catch {}
+  }
+  return { installed: installed || 'unknown' };
+}
+
+function getClaudeMdInfo(cwd) {
+  const p = path.join(cwd, 'CLAUDE.md');
+  let stat;
+  try { stat = fs.statSync(p); } catch { return { exists: false, path: p }; }
+  const content = fs.readFileSync(p, 'utf8');
+  const lines = content.split('\n');
+  const begin = '<!-- claudeflow:default-rules:start';
+  const end = '<!-- claudeflow:default-rules:end -->';
+  const beginIdx = content.indexOf(begin);
+  const endIdx = content.indexOf(end);
+  let block = null;
+  let position = null;
+  if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+    const lineStart = content.slice(0, beginIdx).split('\n').length;
+    const lineEnd = content.slice(0, endIdx).split('\n').length;
+    block = { lineStart, lineEnd, bytes: endIdx + end.length - beginIdx };
+    const totalLines = lines.length;
+    if (lineStart <= 3) position = 'top';
+    else if (lineEnd >= totalLines - 3) position = 'bottom';
+    else position = 'middle';
+  }
+  const optOut = content.includes('claudeflow:default-rules:opt-out');
+  return {
+    exists: true,
+    path: p,
+    bytes: stat.size,
+    lines: lines.length,
+    block: block ? { present: true, position, ...block } : { present: false },
+    optOut,
+  };
+}
+
+function getAppendPromptInfo(cwd) {
+  const p = path.join(cwd, 'append-system-prompt.md');
+  try {
+    const stat = fs.statSync(p);
+    return { exists: true, path: p, bytes: stat.size };
+  } catch {
+    return { exists: false, path: p };
+  }
+}
+
+function getHooksInfo(cwd) {
+  const settingsPath = path.join(cwd, '.claude', 'settings.json');
+  let settings;
+  try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); }
+  catch { return { settingsFound: false, events: [] }; }
+
+  const overrides = readOverrides(cwd);
+  const disabledIndex = new Map();
+  for (const d of overrides.disabledHandlers || []) {
+    disabledIndex.set(`${d.event}|${d.matcher || ''}|${d.handler}`, d);
+  }
+
+  const hooks = settings.hooks || {};
+  const eventsMap = new Map();
+  let totalHandlers = 0;
+  let warnings = 0;
+  let disabledCount = 0;
+
+  for (const [event, rules] of Object.entries(hooks)) {
+    if (!eventsMap.has(event)) eventsMap.set(event, []);
+    for (const rule of rules) {
+      const matcher = rule.matcher || '';
+      for (const h of rule.hooks || []) {
+        const cmd = h.command || '';
+        const handlerPath = normalizeHandlerPath(cmd) || (cmd ? cmd : '');
+        const isEmpty = !handlerPath;
+        if (isEmpty) warnings++;
+        eventsMap.get(event).push({
+          handler: handlerPath || '(empty command)',
+          matcher: matcher || '',
+          matcherDisplay: matcher || '(any)',
+          empty: isEmpty,
+          disabled: false,
+          rawCommand: cmd,
+        });
+        totalHandlers++;
+      }
+    }
+  }
+
+  // Add disabled handlers (live in overrides, not in settings.json)
+  for (const d of overrides.disabledHandlers || []) {
+    if (!eventsMap.has(d.event)) eventsMap.set(d.event, []);
+    eventsMap.get(d.event).push({
+      handler: d.handler,
+      matcher: d.matcher || '',
+      matcherDisplay: d.matcher || '(any)',
+      empty: false,
+      disabled: true,
+      rawCommand: (d.spec && d.spec.command) || '',
+    });
+    disabledCount++;
+  }
+
+  const events = Array.from(eventsMap.entries()).map(([event, handlers]) => ({
+    event,
+    count: handlers.length,
+    handlers,
+  }));
+
+  return {
+    settingsFound: true,
+    events,
+    totalHandlers: totalHandlers + disabledCount,
+    activeHandlers: totalHandlers,
+    disabledHandlers: disabledCount,
+    warnings,
+  };
+}
+
+function getMcpInfo(cwd) {
+  const mcpPath = path.join(cwd, '.mcp.json');
+  let cfg;
+  try { cfg = JSON.parse(fs.readFileSync(mcpPath, 'utf8')); }
+  catch { return { configFound: false }; }
+
+  const servers = Object.keys(cfg.mcpServers || {});
+  const cdp = checkCdpPortMismatch(cwd);
+  const reading = readPlaywrightCdpEndpoint(mcpPath);
+  const observer = readObserverState(cwd, deriveCdpPort(cwd));
+  const lockfiles = checkStaleLockfiles(cwd);
+
+  return {
+    configFound: true,
+    servers,
+    playwright: {
+      configured: reading.state === 'ok' ? reading.port : null,
+      computed: deriveCdpPort(cwd),
+      match: cdp.severity === 'ok',
+      state: reading.state,
+      message: cdp.message,
+    },
+    observer,
+    staleLockfiles: lockfiles.severity === 'mismatch' ? lockfiles.detail : [],
+  };
+}
+
+function readObserverState(cwd, cdpPort) {
+  const lockfile = path.join(cwd, '.claudeflow', 'tmp', `.browser-cdp-${cdpPort}.pid`);
+  let pid = null;
+  try {
+    pid = parseInt(fs.readFileSync(lockfile, 'utf8').trim(), 10);
+  } catch {
+    return { running: false, pid: null, lockfile };
+  }
+  if (!Number.isFinite(pid) || pid <= 0) return { running: false, pid, lockfile };
+  let alive = false;
+  try { process.kill(pid, 0); alive = true; } catch (e) { alive = e.code === 'EPERM'; }
+  return { running: alive, pid, lockfile };
+}
+
+function getSetupContextInfo(cwd) {
+  const p = path.join(cwd, '.claudeflow', 'config', 'setup-context.json');
+  let ctx;
+  try { ctx = JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch { return { exists: false, path: p }; }
+
+  const canonicalToolingTypes = ['unit_test', 'integration_test', 'api_contract_test', 'e2e_test', 'security_test'];
+  const tooling = ctx.test_tooling || {};
+  const toolingComplete = canonicalToolingTypes.every((t) => {
+    const e = tooling[t];
+    return e && typeof e === 'object' && typeof e.command_pattern === 'string' && e.command_pattern.trim();
+  });
+  const missingTooling = canonicalToolingTypes.filter((t) => {
+    const e = tooling[t];
+    return !(e && typeof e === 'object' && e.command_pattern && e.command_pattern.trim());
+  });
+
+  return {
+    exists: true,
+    path: p,
+    selections: ctx.selections || null,
+    testTooling: tooling,
+    toolingComplete,
+    missingTooling,
+  };
+}
+
+function getActiveRunInfo(cwd) {
+  const p = path.join(cwd, '.claudeflow', 'tmp', 'workflow-state.json');
+  let state;
+  try { state = JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch { return { active: false }; }
+  const activeRunId = state.active_run;
+  if (!activeRunId) return { active: false };
+  const run = (state.runs || {})[activeRunId] || null;
+  return {
+    active: true,
+    runId: activeRunId,
+    kind: run?.kind || null,
+    topLevel: run?.top_level || null,
+    taskCount: run?.tasks ? Object.keys(run.tasks).length : 0,
+  };
+}
+
+function getDoctorInfo(cwd) {
+  const checks = [checkCdpPortMismatch(cwd), checkStaleLockfiles(cwd)];
+  const issues = checks.filter((c) => c.severity !== 'ok' && c.severity !== 'info');
+  return {
+    issueCount: issues.length,
+    checks: checks.map((c) => ({ id: c.id, severity: c.severity, message: c.message })),
+  };
+}
+
+function collectStatus(cwd) {
+  return {
+    cwd,
+    timestamp: new Date().toISOString(),
+    version: getVersionInfo(cwd),
+    claudeMd: getClaudeMdInfo(cwd),
+    appendPrompt: getAppendPromptInfo(cwd),
+    hooks: getHooksInfo(cwd),
+    mcp: getMcpInfo(cwd),
+    setupContext: getSetupContextInfo(cwd),
+    activeRun: getActiveRunInfo(cwd),
+    doctor: getDoctorInfo(cwd),
+  };
+}
+
+// ─── frontend (HTML + CSS + JS embedded) ──────────────────────────
+
+function renderHtml() {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1" />
+<title>claudeflow panel</title>
+<style>
+:root {
+  --bg: #0e1117;
+  --panel: #161b22;
+  --panel-2: #1c232c;
+  --border: #2a313c;
+  --fg: #e6edf3;
+  --muted: #8b949e;
+  --accent: #7c3aed;
+  --ok: #3fb950;
+  --warn: #d29922;
+  --err: #f85149;
+  --info: #58a6ff;
+  --mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--fg); font: 14px/1.5 system-ui, -apple-system, sans-serif; }
+header { display: flex; align-items: center; gap: 12px; padding: 14px 22px; border-bottom: 1px solid var(--border); background: var(--panel); position: sticky; top: 0; z-index: 10; }
+header .logo { color: var(--accent); font-size: 18px; }
+header .title { font-weight: 600; letter-spacing: 0.5px; }
+header .version { color: var(--muted); font-family: var(--mono); font-size: 12px; }
+header .cwd { color: var(--muted); font-family: var(--mono); font-size: 12px; flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+header .actions { display: flex; gap: 12px; align-items: center; color: var(--muted); font-size: 12px; }
+header button { background: var(--panel-2); border: 1px solid var(--border); color: var(--fg); padding: 6px 12px; border-radius: 6px; cursor: pointer; font: inherit; }
+header button:hover { border-color: var(--accent); }
+main { display: grid; grid-template-columns: 220px 1fr; min-height: calc(100vh - 56px); }
+nav { border-right: 1px solid var(--border); background: var(--panel); padding: 12px 0; }
+nav a { display: flex; align-items: center; gap: 10px; padding: 10px 22px; color: var(--fg); text-decoration: none; cursor: pointer; border-left: 3px solid transparent; font-size: 13px; }
+nav a:hover { background: var(--panel-2); }
+nav a.active { background: var(--panel-2); border-left-color: var(--accent); }
+nav .dot { display: inline-block; width: 8px; height: 8px; border-radius: 50%; }
+.dot.ok { background: var(--ok); }
+.dot.warn { background: var(--warn); }
+.dot.err { background: var(--err); }
+.dot.info { background: var(--muted); }
+section { padding: 22px 28px; max-width: 980px; }
+section h2 { font-size: 16px; margin: 0 0 6px; letter-spacing: 0.3px; }
+section .sub { color: var(--muted); font-size: 12px; margin-bottom: 18px; }
+.card { background: var(--panel); border: 1px solid var(--border); border-radius: 8px; padding: 14px 18px; margin-bottom: 14px; }
+.card-row { display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid var(--border); align-items: center; gap: 10px; }
+.card-row:last-child { border-bottom: 0; }
+.card-row .k { color: var(--muted); font-size: 13px; }
+.card-row .v { font-family: var(--mono); font-size: 13px; }
+.badge { display: inline-block; padding: 2px 8px; border-radius: 999px; font-size: 11px; font-family: var(--mono); }
+.badge.ok { background: rgba(63, 185, 80, 0.12); color: var(--ok); }
+.badge.warn { background: rgba(210, 153, 34, 0.12); color: var(--warn); }
+.badge.err { background: rgba(248, 81, 73, 0.12); color: var(--err); }
+.badge.info { background: rgba(139, 148, 158, 0.16); color: var(--muted); }
+pre { background: var(--panel-2); border: 1px solid var(--border); border-radius: 6px; padding: 12px 14px; overflow: auto; max-height: 480px; font: 12px/1.5 var(--mono); margin: 0; }
+details { background: var(--panel); border: 1px solid var(--border); border-radius: 8px; padding: 10px 14px; margin-bottom: 8px; }
+details summary { cursor: pointer; font-weight: 500; }
+details[open] summary { padding-bottom: 8px; border-bottom: 1px solid var(--border); margin-bottom: 8px; }
+.handler { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 8px; font-family: var(--mono); font-size: 12px; padding: 4px 0; align-items: center; }
+.matcher { color: var(--muted); font-size: 11px; }
+.muted { color: var(--muted); }
+.error { color: var(--err); }
+.success { color: var(--ok); }
+.warning { color: var(--warn); }
+.toggle { display: inline-flex; align-items: center; gap: 6px; cursor: pointer; user-select: none; }
+.toggle input { accent-color: var(--accent); }
+.disabled-row { opacity: 0.55; }
+.disabled-row .matcher { font-style: italic; }
+.toast { position: fixed; bottom: 18px; right: 18px; background: var(--panel); border: 1px solid var(--border); padding: 10px 14px; border-radius: 6px; font-size: 13px; box-shadow: 0 4px 12px rgba(0,0,0,0.4); }
+.toast.err { border-color: var(--err); }
+.toast.ok { border-color: var(--ok); }
+</style>
+</head>
+<body>
+<header>
+  <span class="logo">◆</span>
+  <span class="title">claudeflow panel</span>
+  <span class="version" id="version">…</span>
+  <span class="cwd" id="cwd">…</span>
+  <span class="actions">
+    <label class="toggle"><input type="checkbox" id="auto" checked /> auto-refresh 5s</label>
+    <button id="refresh">Refresh</button>
+  </span>
+</header>
+<main>
+  <nav id="nav"></nav>
+  <section id="content"><p class="muted">Loading…</p></section>
+</main>
+<script>
+const SECTIONS = [
+  { id: 'overview',     label: 'Overview' },
+  { id: 'claudeMd',     label: 'CLAUDE.md' },
+  { id: 'hooks',        label: 'Hooks' },
+  { id: 'mcp',          label: 'MCP & observer' },
+  { id: 'setupContext', label: 'Setup context' },
+  { id: 'activeRun',    label: 'Active run' },
+  { id: 'doctor',       label: 'Issues' },
+];
+
+let state = null;
+let active = 'overview';
+let timer = null;
+
+async function refresh() {
+  const r = await fetch('/api/status');
+  state = await r.json();
+  renderHeader();
+  renderNav();
+  renderContent();
+}
+
+function renderHeader() {
+  document.getElementById('version').textContent = 'v' + state.version.installed;
+  document.getElementById('cwd').textContent = state.cwd;
+}
+
+function severityFor(id) {
+  const s = state;
+  switch (id) {
+    case 'overview': return s.doctor.issueCount > 0 ? 'warn' : 'ok';
+    case 'claudeMd': return !s.claudeMd.exists ? 'err' : (s.claudeMd.optOut ? 'info' : 'ok');
+    case 'hooks':    return s.hooks.warnings > 0 ? 'warn' : 'ok';
+    case 'mcp':      return !s.mcp.configFound ? 'info' : (s.mcp.playwright.match && s.mcp.staleLockfiles.length === 0 ? 'ok' : 'warn');
+    case 'setupContext': return !s.setupContext.exists ? 'err' : (s.setupContext.toolingComplete ? 'ok' : 'warn');
+    case 'activeRun': return s.activeRun.active ? 'info' : 'info';
+    case 'doctor':   return s.doctor.issueCount > 0 ? 'warn' : 'ok';
+  }
+  return 'info';
+}
+
+function renderNav() {
+  const nav = document.getElementById('nav');
+  nav.innerHTML = SECTIONS.map(s => {
+    const sev = severityFor(s.id);
+    const cls = active === s.id ? 'active' : '';
+    return \`<a class="\${cls}" data-id="\${s.id}"><span class="dot \${sev}"></span>\${s.label}</a>\`;
+  }).join('');
+  nav.querySelectorAll('a').forEach(a => a.onclick = () => { active = a.dataset.id; renderNav(); renderContent(); });
+}
+
+function row(k, v, badge) {
+  const b = badge ? \`<span class="badge \${badge.kind}">\${escapeHtml(badge.text)}</span>\` : '';
+  return \`<div class="card-row"><span class="k">\${escapeHtml(k)}</span><span class="v">\${b}\${escapeHtml(v)}</span></div>\`;
+}
+
+function escapeHtml(s) {
+  return String(s == null ? '' : s)
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+function fmtBytes(n) {
+  if (n == null) return '—';
+  if (n < 1024) return n + ' B';
+  if (n < 1024 * 1024) return (n / 1024).toFixed(1) + ' KB';
+  return (n / 1024 / 1024).toFixed(2) + ' MB';
+}
+
+function renderContent() {
+  const el = document.getElementById('content');
+  if (!state) { el.innerHTML = '<p class="muted">Loading…</p>'; return; }
+  const fn = {
+    overview: renderOverview,
+    claudeMd: renderClaudeMd,
+    hooks: renderHooks,
+    mcp: renderMcp,
+    setupContext: renderSetup,
+    activeRun: renderRun,
+    doctor: renderDoctor,
+  }[active];
+  el.innerHTML = fn ? fn() : '';
+}
+
+function renderOverview() {
+  const s = state;
+  const cm = s.claudeMd;
+  const cmText = cm.exists
+    ? \`\${fmtBytes(cm.bytes)} / \${cm.lines} lines · block: \${cm.block.present ? cm.block.position : 'absent'}\${cm.optOut ? ' · OPT-OUT' : ''}\`
+    : 'missing';
+  const ap = s.appendPrompt.exists ? fmtBytes(s.appendPrompt.bytes) : 'missing';
+  const hk = \`\${s.hooks.events.length} events · \${s.hooks.totalHandlers} handlers\${s.hooks.warnings ? ' · ' + s.hooks.warnings + ' warnings' : ''}\`;
+  const mc = !s.mcp.configFound ? '(no .mcp.json)' :
+    \`Playwright \${s.mcp.playwright.match ? '✓' : '✗'} \${s.mcp.playwright.configured || '?'} \${s.mcp.playwright.match ? '' : '(expected ' + s.mcp.playwright.computed + ')'} · observer \${s.mcp.observer.running ? 'running pid '+s.mcp.observer.pid : 'stopped'}\`;
+  const sc = !s.setupContext.exists ? 'missing' : (s.setupContext.toolingComplete ? 'complete' : 'incomplete (' + s.setupContext.missingTooling.join(', ') + ')');
+  const ar = s.activeRun.active ? s.activeRun.runId : 'none';
+  const dc = s.doctor.issueCount === 0 ? '0 issues' : s.doctor.issueCount + ' issue(s) — run \`claudeflow doctor\`';
+  return \`<h2>Overview</h2>
+    <p class="sub">Snapshot at \${new Date(s.timestamp).toLocaleTimeString()}</p>
+    <div class="card">
+      \${row('CLAUDE.md', cmText, { kind: cm.exists ? (cm.optOut ? 'info' : 'ok') : 'err', text: cm.exists ? '✓' : '✗' })}
+      \${row('append-system-prompt.md', ap, { kind: s.appendPrompt.exists ? 'ok' : 'err', text: s.appendPrompt.exists ? '✓' : '✗' })}
+      \${row('Hooks', hk, { kind: s.hooks.warnings ? 'warn' : 'ok', text: s.hooks.warnings ? '!' : '✓' })}
+      \${row('MCP & observer', mc, { kind: !s.mcp.configFound ? 'info' : (s.mcp.playwright.match ? 'ok' : 'warn'), text: !s.mcp.configFound ? '·' : (s.mcp.playwright.match ? '✓' : '!') })}
+      \${row('Setup context', sc, { kind: s.setupContext.exists ? (s.setupContext.toolingComplete ? 'ok' : 'warn') : 'err', text: s.setupContext.exists ? (s.setupContext.toolingComplete ? '✓' : '!') : '✗' })}
+      \${row('Active run', ar, { kind: 'info', text: s.activeRun.active ? '·' : '·' })}
+      \${row('Doctor', dc, { kind: s.doctor.issueCount === 0 ? 'ok' : 'warn', text: s.doctor.issueCount === 0 ? '✓' : '!' })}
+    </div>\`;
+}
+
+function renderClaudeMd() {
+  const c = state.claudeMd;
+  if (!c.exists) return \`<h2>CLAUDE.md</h2><p class="error">File not found at \${escapeHtml(c.path)}</p>\`;
+  const blk = c.block.present
+    ? \`present at \${c.block.position} (lines \${c.block.lineStart}–\${c.block.lineEnd}, \${fmtBytes(c.block.bytes)})\`
+    : 'absent (no claudeflow:default-rules markers)';
+  return \`<h2>CLAUDE.md</h2>
+    <p class="sub">\${escapeHtml(c.path)}</p>
+    <div class="card">
+      \${row('Size', fmtBytes(c.bytes) + ' / ' + c.lines + ' lines')}
+      \${row('Default rules block', blk, { kind: c.block.present ? 'ok' : 'info', text: c.block.present ? '✓' : '·' })}
+      \${row('Opt-out marker', c.optOut ? 'present (block disabled)' : 'absent', { kind: c.optOut ? 'info' : 'ok', text: c.optOut ? '·' : '✓' })}
+    </div>
+    <details><summary>Preview content</summary><div id="claude-md-preview">Loading…</div></details>
+    <script>
+      fetch('/api/claude-md').then(r => r.text()).then(t => {
+        document.getElementById('claude-md-preview').innerHTML = '<pre>' + t.replace(/[&<>]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c])) + '</pre>';
+      });
+    </\${'script'}>
+  \`;
+}
+
+function renderHooks() {
+  const h = state.hooks;
+  if (!h.settingsFound) return '<h2>Hooks</h2><p class="error">.claude/settings.json not found</p>';
+  const items = h.events.map(ev => {
+    const handlers = ev.handlers.map(hd => {
+      const mark = hd.empty ? '<span class="warning">⚠ empty command</span>' : '';
+      const cls = hd.disabled ? 'handler disabled-row' : 'handler';
+      const checked = hd.disabled ? '' : 'checked';
+      const dataset = \`data-event="\${escapeHtml(ev.event)}" data-matcher="\${escapeHtml(hd.matcher)}" data-handler="\${escapeHtml(hd.handler)}"\`;
+      const status = hd.disabled ? '<span class="badge info">disabled</span>' : '';
+      return \`<div class="\${cls}">
+        <label class="toggle"><input type="checkbox" class="hook-toggle" \${dataset} \${checked} \${hd.empty ? 'disabled' : ''} />
+          <span>\${escapeHtml(hd.handler)} \${status} \${mark}</span></label>
+        <span class="matcher">\${escapeHtml(hd.matcherDisplay)}</span>
+      </div>\`;
+    }).join('');
+    return \`<details><summary>\${escapeHtml(ev.event)} <span class="muted">(\${ev.count})</span></summary>\${handlers}</details>\`;
+  }).join('');
+  return \`<h2>Hooks</h2>
+    <p class="sub">\${h.events.length} events · \${h.activeHandlers} active\${h.disabledHandlers ? ' · <span class="muted">' + h.disabledHandlers + ' disabled</span>' : ''}\${h.warnings ? ' · <span class="warning">' + h.warnings + ' warnings</span>' : ''}</p>
+    <p class="sub muted">Uncheck a handler to disable it. Disabled handlers are recorded in <code>.claudeflow/config/user-hook-overrides.json</code> and survive <code>claudeflow update</code>. Toggling rewrites <code>.claude/settings.json</code> immediately; reload Claude Code to pick up the change.</p>
+    \${items}\`;
+}
+
+function renderMcp() {
+  const m = state.mcp;
+  if (!m.configFound) return '<h2>MCP & observer</h2><p class="muted">.mcp.json not found</p>';
+  const lockfiles = m.staleLockfiles.length === 0
+    ? '<p class="muted">No stale lockfiles.</p>'
+    : '<ul>' + m.staleLockfiles.map(l => \`<li>\${escapeHtml(l.file)} (\${escapeHtml(l.reason)}\${l.pid ? ', pid='+l.pid : ''})</li>\`).join('') + '</ul>';
+  return \`<h2>MCP & observer</h2>
+    <p class="sub">Servers: \${m.servers.map(escapeHtml).join(', ') || 'none'}</p>
+    <div class="card">
+      \${row('Playwright --cdp-endpoint port', String(m.playwright.configured || 'n/a'))}
+      \${row('Computed port (from path)', String(m.playwright.computed))}
+      \${row('Match', m.playwright.match ? 'YES' : 'NO', { kind: m.playwright.match ? 'ok' : 'err', text: m.playwright.match ? '✓' : '✗' })}
+      \${row('Observer', m.observer.running ? 'running (pid '+m.observer.pid+')' : 'stopped', { kind: m.observer.running ? 'ok' : 'info', text: m.observer.running ? '✓' : '·' })}
+    </div>
+    <h2 style="margin-top:18px">Stale lockfiles</h2>
+    \${lockfiles}\`;
+}
+
+function renderSetup() {
+  const s = state.setupContext;
+  if (!s.exists) return '<h2>Setup context</h2><p class="error">setup-context.json not found</p>';
+  const sel = s.selections ? '<pre>' + escapeHtml(JSON.stringify(s.selections, null, 2)) + '</pre>' : '<p class="muted">No selections.</p>';
+  const tooling = '<pre>' + escapeHtml(JSON.stringify(s.testTooling, null, 2)) + '</pre>';
+  const missing = s.missingTooling.length ? '<p class="warning">Missing types: ' + s.missingTooling.map(escapeHtml).join(', ') + '</p>' : '<p class="success">All canonical tooling types defined.</p>';
+  return \`<h2>Setup context</h2>
+    <p class="sub">\${escapeHtml(s.path)}</p>
+    <h3>selections</h3>\${sel}
+    <h3>test_tooling</h3>\${missing}\${tooling}\`;
+}
+
+function renderRun() {
+  const r = state.activeRun;
+  if (!r.active) return '<h2>Active run</h2><p class="muted">No active build run.</p>';
+  return \`<h2>Active run</h2>
+    <div class="card">
+      \${row('Run ID', r.runId)}
+      \${row('Kind', r.kind || '—')}
+      \${row('Top-level subject', (r.topLevel && r.topLevel.subject) || '—')}
+      \${row('Tasks tracked', String(r.taskCount))}
+    </div>\`;
+}
+
+function renderDoctor() {
+  const d = state.doctor;
+  return \`<h2>Issues</h2>
+    <p class="sub">\${d.issueCount === 0 ? 'No issues detected.' : d.issueCount + ' issue(s) detected. Run <code>claudeflow doctor --fix</code> to repair.'}</p>
+    <div class="card">
+    \${d.checks.map(c => row(c.id, c.message, { kind: c.severity === 'ok' ? 'ok' : (c.severity === 'info' ? 'info' : 'warn'), text: c.severity })).join('')}
+    </div>\`;
+}
+
+function showToast(msg, kind) {
+  const el = document.createElement('div');
+  el.className = 'toast ' + (kind || 'ok');
+  el.textContent = msg;
+  document.body.appendChild(el);
+  setTimeout(() => el.remove(), 2400);
+}
+
+async function toggleHook(event, matcher, handler, disable) {
+  try {
+    const r = await fetch('/api/hooks/toggle', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ event, matcher, handler, disable }),
+    });
+    const result = await r.json();
+    if (!r.ok || result.state === 'error') {
+      showToast('Toggle failed: ' + (result.reason || result.error || 'unknown'), 'err');
+    } else if (result.state === 'noop') {
+      showToast('Already in target state (' + result.reason + ')', 'ok');
+    } else {
+      showToast(disable ? 'Disabled. Reload Claude Code to apply.' : 'Enabled. Reload Claude Code to apply.', 'ok');
+    }
+  } catch (e) {
+    showToast('Network error: ' + e.message, 'err');
+  }
+  await refresh();
+}
+
+document.addEventListener('change', (e) => {
+  const t = e.target;
+  if (t && t.classList && t.classList.contains('hook-toggle')) {
+    const event = t.dataset.event;
+    const matcher = t.dataset.matcher;
+    const handler = t.dataset.handler;
+    const disable = !t.checked;
+    toggleHook(event, matcher, handler, disable);
+  }
+});
+
+document.getElementById('refresh').onclick = refresh;
+document.getElementById('auto').onchange = (e) => {
+  if (timer) clearInterval(timer);
+  if (e.target.checked) timer = setInterval(refresh, 5000);
+};
+timer = setInterval(refresh, 5000);
+refresh();
+</script>
+</body>
+</html>`;
+}
+
+// ─── HTTP server ─────────────────────────────────────────────────
+
+function readClaudeMdSafe(cwd) {
+  try { return fs.readFileSync(path.join(cwd, 'CLAUDE.md'), 'utf8'); }
+  catch { return ''; }
+}
+
+function readRequestBody(req, limit = 64 * 1024) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    req.on('data', (c) => {
+      total += c.length;
+      if (total > limit) {
+        reject(new Error('Request body too large'));
+        req.destroy();
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+  });
+}
+
+function handler(cwd) {
+  return async (req, res) => {
+    try {
+      const url = new URL(req.url, 'http://localhost');
+      const route = url.pathname;
+
+      const send = (status, body, type) => {
+        res.writeHead(status, { 'Content-Type': type, 'Cache-Control': 'no-store' });
+        res.end(body);
+      };
+
+      if (req.method === 'GET') {
+        if (route === '/' || route === '/index.html') return send(200, renderHtml(), 'text/html; charset=utf-8');
+        if (route === '/api/status') return send(200, JSON.stringify(collectStatus(cwd)), 'application/json');
+        if (route === '/api/claude-md') return send(200, readClaudeMdSafe(cwd), 'text/plain; charset=utf-8');
+        if (route === '/healthz') return send(200, 'ok', 'text/plain');
+      }
+
+      if (req.method === 'POST' && route === '/api/hooks/toggle') {
+        const raw = await readRequestBody(req);
+        let payload;
+        try { payload = JSON.parse(raw); }
+        catch { return send(400, JSON.stringify({ error: 'invalid json' }), 'application/json'); }
+        const { event, matcher, handler: hdlr, disable } = payload;
+        if (typeof event !== 'string' || typeof hdlr !== 'string' || typeof disable !== 'boolean') {
+          return send(400, JSON.stringify({ error: 'event, handler, disable required' }), 'application/json');
+        }
+        const result = toggleHookOverride(cwd, { event, matcher: matcher || '', handler: hdlr, disable });
+        const status = result.state === 'error' ? 500 : 200;
+        return send(status, JSON.stringify(result), 'application/json');
+      }
+
+      send(404, JSON.stringify({ error: 'not found' }), 'application/json');
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+  };
+}
+
+function openInBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'start'
+    : 'xdg-open';
+  try {
+    spawn(cmd, [url], { detached: true, stdio: 'ignore' }).unref();
+  } catch {}
+}
+
+function start({ cwd = process.cwd(), port = 0, openBrowser = true } = {}) {
+  const server = http.createServer(handler(cwd));
+  let lastActivity = Date.now();
+  server.on('request', () => { lastActivity = Date.now(); });
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      const addr = server.address();
+      const url = `http://127.0.0.1:${addr.port}`;
+      const idleTimer = setInterval(() => {
+        if (Date.now() - lastActivity > IDLE_SHUTDOWN_MS) {
+          clearInterval(idleTimer);
+          server.close();
+          process.exit(0);
+        }
+      }, 60 * 1000);
+      idleTimer.unref();
+      if (openBrowser) openInBrowser(url);
+      resolve({ url, server });
+    });
+  });
+}
+
+async function run(argv = []) {
+  const cwd = process.cwd();
+  const noOpen = argv.includes('--no-open');
+  const portArg = argv.find((a) => a.startsWith('--port='));
+  const port = portArg ? parseInt(portArg.split('=')[1], 10) : 0;
+
+  ui.banner();
+  console.log(`  Starting panel for ${ui.CYAN}${cwd}${ui.RESET}`);
+  const { url } = await start({ cwd, port, openBrowser: !noOpen });
+  console.log('');
+  console.log(`  ${ui.GREEN}▸${ui.RESET} ${ui.CYAN}${url}${ui.RESET}`);
+  console.log(`  ${ui.DIM}Ctrl+C to stop. Auto-shutdown after 30 min idle.${ui.RESET}`);
+  console.log('');
+  return new Promise(() => {}); // keep alive
+}
+
+module.exports = run;
+module.exports.start = start;
+module.exports.collectStatus = collectStatus;
+module.exports.getClaudeMdInfo = getClaudeMdInfo;
+module.exports.getHooksInfo = getHooksInfo;
+module.exports.getMcpInfo = getMcpInfo;
+module.exports.getSetupContextInfo = getSetupContextInfo;
+module.exports.getActiveRunInfo = getActiveRunInfo;
+module.exports.getDoctorInfo = getDoctorInfo;
+module.exports.renderHtml = renderHtml;

package/package.json

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