@axiomatic-labs/claudeflow 2.13.15 → 2.13.17

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

package/lib/doctor.js

@@ -0,0 +1,207 @@
+// `claudeflow doctor` — diagnose and optionally repair common local-machine
+// issues that don't surface until something silently fails.
+//
+// Scope (intentionally narrow):
+//   1. CDP port mismatch — `.mcp.json` ships a `--cdp-endpoint` derived from
+//      the path of whoever ran `claudeflow init`. After a clone, the local
+//      observer derives a different port from the new path, so the Playwright
+//      MCP can't reach the observer's Chrome.
+//   2. Stale browser PID lockfile — `openBrowser()` writes
+//      `.claudeflow/tmp/.browser-cdp-<port>.pid` and skips relaunch if the PID
+//      is alive. If Chrome is killed externally (pkill) the lockfile lingers
+//      and blocks subsequent launches.
+//
+// Read-only by default. `--fix` applies repairs after reporting them.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const ui = require('./ui.js');
+
+function deriveCdpPort(projectPath) {
+  const hash = crypto.createHash('sha1').update(projectPath).digest();
+  return 9200 + (hash.readUInt16BE(2) % 100);
+}
+
+function readPlaywrightCdpEndpoint(mcpPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(mcpPath, 'utf8');
+  } catch {
+    return { state: 'missing-file' };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { state: 'invalid-json', error: err.message };
+  }
+  const entry = parsed && parsed.mcpServers && parsed.mcpServers.playwright;
+  if (!entry || !Array.isArray(entry.args)) return { state: 'no-playwright' };
+  const flagIdx = entry.args.indexOf('--cdp-endpoint');
+  if (flagIdx === -1) return { state: 'no-flag', parsed };
+  const value = entry.args[flagIdx + 1];
+  const match = /localhost:(\d+)/.exec(value || '');
+  if (!match) return { state: 'unparseable', value, parsed };
+  return { state: 'ok', port: Number(match[1]), flagIdx, parsed };
+}
+
+function checkCdpPortMismatch(cwd) {
+  const mcpPath = path.join(cwd, '.mcp.json');
+  const expected = deriveCdpPort(cwd);
+  const reading = readPlaywrightCdpEndpoint(mcpPath);
+
+  switch (reading.state) {
+    case 'missing-file':
+      return { id: 'cdp-port', severity: 'info', message: 'No .mcp.json in cwd — skipping.' };
+    case 'invalid-json':
+      return { id: 'cdp-port', severity: 'error', message: `.mcp.json is invalid JSON: ${reading.error}` };
+    case 'no-playwright':
+      return { id: 'cdp-port', severity: 'info', message: '.mcp.json has no `playwright` entry — skipping.' };
+    case 'no-flag':
+      return { id: 'cdp-port', severity: 'info', message: 'Playwright MCP has no `--cdp-endpoint` flag — observer-MCP wiring not in use.' };
+    case 'unparseable':
+      return { id: 'cdp-port', severity: 'error', message: `Unparseable --cdp-endpoint value: ${reading.value}` };
+    case 'ok':
+      if (reading.port === expected) {
+        return { id: 'cdp-port', severity: 'ok', message: `CDP port matches (${expected}).` };
+      }
+      return {
+        id: 'cdp-port',
+        severity: 'mismatch',
+        message: `CDP port mismatch — .mcp.json has ${reading.port}, this machine derives ${expected} from ${cwd}.`,
+        fix: { mcpPath, expected, parsed: reading.parsed, flagIdx: reading.flagIdx },
+      };
+  }
+}
+
+function applyCdpPortFix(check) {
+  const { mcpPath, expected, parsed, flagIdx } = check.fix;
+  parsed.mcpServers.playwright.args[flagIdx + 1] = `http://localhost:${expected}`;
+  fs.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + '\n');
+}
+
+function listStaleLockfiles(cwd) {
+  const dir = path.join(cwd, '.claudeflow', 'tmp');
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const stale = [];
+  for (const name of entries) {
+    if (!/^\.browser-cdp-\d+\.pid$/.test(name)) continue;
+    const full = path.join(dir, name);
+    let pid;
+    try {
+      pid = parseInt(fs.readFileSync(full, 'utf8').trim(), 10);
+    } catch {
+      stale.push({ file: full, reason: 'unreadable' });
+      continue;
+    }
+    if (!Number.isFinite(pid) || pid <= 0) {
+      stale.push({ file: full, reason: 'invalid-pid', pid });
+      continue;
+    }
+    try {
+      process.kill(pid, 0);
+    } catch (err) {
+      if (err.code === 'ESRCH') stale.push({ file: full, reason: 'dead-pid', pid });
+      // EPERM means the PID exists but we can't signal it — treat as alive.
+    }
+  }
+  return stale;
+}
+
+function checkStaleLockfiles(cwd) {
+  const stale = listStaleLockfiles(cwd);
+  if (stale.length === 0) {
+    return { id: 'stale-lockfile', severity: 'ok', message: 'No stale browser lockfiles.' };
+  }
+  return {
+    id: 'stale-lockfile',
+    severity: 'mismatch',
+    message: `${stale.length} stale browser lockfile(s) — Chrome PIDs no longer alive.`,
+    detail: stale,
+    fix: { stale },
+  };
+}
+
+function applyStaleLockfileFix(check) {
+  for (const { file } of check.fix.stale) {
+    try { fs.unlinkSync(file); } catch {}
+  }
+}
+
+const SEVERITY_TAG = {
+  ok:       `${ui.GREEN}✓${ui.RESET}`,
+  info:     `${ui.DIM}·${ui.RESET}`,
+  mismatch: `${ui.YELLOW}!${ui.RESET}`,
+  error:    `${ui.RED}✗${ui.RESET}`,
+};
+
+function printCheck(check) {
+  const tag = SEVERITY_TAG[check.severity] || '?';
+  console.log(`  ${tag} [${check.id}] ${check.message}`);
+  if (check.detail && Array.isArray(check.detail)) {
+    for (const d of check.detail) {
+      console.log(`      ${ui.DIM}- ${d.file} (${d.reason}${d.pid ? `, pid=${d.pid}` : ''})${ui.RESET}`);
+    }
+  }
+}
+
+async function run(argv = []) {
+  const fixMode = argv.includes('--fix');
+  const cwd = process.cwd();
+
+  ui.banner();
+  console.log(`  Diagnosing ${ui.CYAN}${cwd}${ui.RESET}${fixMode ? ` ${ui.YELLOW}(--fix)${ui.RESET}` : ''}`);
+  console.log('');
+
+  const checks = [
+    checkCdpPortMismatch(cwd),
+    checkStaleLockfiles(cwd),
+  ];
+
+  for (const check of checks) printCheck(check);
+
+  const fixable = checks.filter(c => c.fix);
+  if (fixable.length === 0) {
+    console.log('');
+    console.log(`  ${ui.GREEN}All checks passed.${ui.RESET}`);
+    return 0;
+  }
+
+  if (!fixMode) {
+    console.log('');
+    console.log(`  ${ui.YELLOW}${fixable.length} issue(s) detected.${ui.RESET} Re-run with ${ui.CYAN}claudeflow doctor --fix${ui.RESET} to repair.`);
+    return 1;
+  }
+
+  console.log('');
+  console.log(`  ${ui.CYAN}Applying fixes...${ui.RESET}`);
+  for (const check of fixable) {
+    if (check.id === 'cdp-port') {
+      applyCdpPortFix(check);
+      console.log(`  ${ui.GREEN}✓${ui.RESET} Rewrote .mcp.json playwright --cdp-endpoint → ${check.fix.expected}`);
+      console.log(`      ${ui.YELLOW}Do NOT commit this change${ui.RESET} — the port is local to this machine's path.`);
+      console.log(`      Consider: ${ui.CYAN}git update-index --skip-worktree .mcp.json${ui.RESET}`);
+    } else if (check.id === 'stale-lockfile') {
+      applyStaleLockfileFix(check);
+      console.log(`  ${ui.GREEN}✓${ui.RESET} Removed ${check.fix.stale.length} stale lockfile(s).`);
+    }
+  }
+  console.log('');
+  console.log(`  ${ui.GREEN}Done.${ui.RESET} Reconnect MCP (${ui.CYAN}/mcp${ui.RESET} in Claude Code) to pick up changes.`);
+  return 0;
+}
+
+module.exports = run;
+module.exports.deriveCdpPort = deriveCdpPort;
+module.exports.checkCdpPortMismatch = checkCdpPortMismatch;
+module.exports.checkStaleLockfiles = checkStaleLockfiles;
+module.exports.readPlaywrightCdpEndpoint = readPlaywrightCdpEndpoint;
+module.exports.applyCdpPortFix = applyCdpPortFix;
+module.exports.applyStaleLockfileFix = applyStaleLockfileFix;

package/lib/install.js

@@ -15,6 +15,8 @@ const REQUIRED_TEMPLATE_RULES = [];
 const LEGACY_TEMPLATE_RULES = ['claudeflow-implementation.md', 'example-rules.md'];
 const SHARED_APPEND_PROMPT_TEMPLATE = path.join('.claudeflow', 'templates', 'claudeflow-core-system-prompt.md');
 const SHARED_APPEND_PROMPT_OUTPUT = 'append-system-prompt.md';
+const DEFAULT_CLAUDE_MD_TEMPLATE = path.join('.claudeflow', 'templates', 'claudeflow-default-claude-md.md');
+const DEFAULT_CLAUDE_MD_OUTPUT = 'CLAUDE.md';
 const TEMPLATE_MANAGED_SETTINGS_KEYS = ['$schema', 'enabledMcpjsonServers', 'env', 'permissions', 'hooks'];
 const SERENA_REPO = 'git+https://github.com/oraios/serena';
 const TEMPLATE_SEEDED_SETTINGS_KEYS = new Set(['statusLine']);
@@ -152,6 +154,7 @@ async function run() {
       copyDirSync(srcTemplates, dstTemplates);
     }
     materializeSharedAppendPrompt(cwd);
+    materializeDefaultClaudeMd(cwd);
     propagateTemplateRules(cwd, srcTemplates);
 
     // Copy template agents (only template-managed, preserve user agents)
@@ -988,6 +991,19 @@ function materializeSharedAppendPrompt(projectRoot) {
   fs.copyFileSync(templatePath, outputPath);
 }
 
+// Materialize the default CLAUDE.md only when the project has none.
+// CLAUDE.md is user-owned: customizations made by the user (or by other
+// frameworks) must survive `claudeflow update`. We therefore never
+// overwrite an existing file.
+function materializeDefaultClaudeMd(projectRoot) {
+  const templatePath = path.join(projectRoot, DEFAULT_CLAUDE_MD_TEMPLATE);
+  if (!fs.existsSync(templatePath)) return false;
+  const outputPath = path.join(projectRoot, DEFAULT_CLAUDE_MD_OUTPUT);
+  if (fs.existsSync(outputPath)) return false;
+  fs.copyFileSync(templatePath, outputPath);
+  return true;
+}
+
 function isTemplateManagedAgent(agentName) {
   return agentName.startsWith('claudeflow-');
 }
@@ -1020,6 +1036,7 @@ function copyDirSync(src, dst, skipNames) {
 module.exports = Object.assign(run, {
   assertRequiredTemplateRules,
   materializeSharedAppendPrompt,
+  materializeDefaultClaudeMd,
   isTemplateManagedAgent,
   listTemplateManagedAgents,
   mergeClaudeSettings,

package/package.json

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