@mhd-ghaith-abtah/flow 0.7.2-beta.0

package/lib/commands/doctor.js

@@ -0,0 +1,392 @@
+// lib/commands/doctor.js — `flow doctor` health check CLI.
+//
+// Headless equivalent of the interactive /flow-doctor skill. Runs the subset
+// of checks that don't require an LLM in the loop:
+//   - catalog.yaml parses + validates against schema
+//   - install-state.json exists + parses at each scope
+//   - flow.config.yaml exists + parses + has required keys
+//   - adapter files present at their expected paths
+//   - required CLIs in $PATH (per active adapters)
+//
+// LLM-dependent checks (probing MCP responsiveness via tool calls, parsing
+// recent review notes for severity labels) stay in the skill. CLI just gives
+// scriptable yes/no for CI gates.
+//
+// Exit codes:
+//   0 — all ✓ or only ℹ
+//   1 — at least one ⚠
+//   2 — at least one ✗
+
+import { existsSync, readFileSync, statSync, lstatSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import chalk from 'chalk';
+import { execaSync } from 'execa';
+import { parse as parseYaml } from 'yaml';
+import { loadCatalog } from '../catalog.js';
+import { resolveRepoRoot } from '../repo-root.js';
+
+/**
+ * @param {Object} args - yargs-parser args
+ * @param {Object} ctx
+ */
+export default async function doctor(args, ctx) {
+  const repoRoot = ctx.repoRoot ?? resolveRepoRoot(import.meta.url);
+  const json = Boolean(args.json);
+  const verbose = Boolean(args.verbose);
+  const repairUpstream = args['repair-upstream'];
+
+  // --repair-upstream <name>: side-quest before the normal probe. Reads the
+  // pinned version from install-state and prints the commands to reinstall it
+  // (does NOT auto-run; upstream installs touch user-scope state).
+  if (repairUpstream) {
+    return runRepairUpstream(repairUpstream, ctx);
+  }
+
+  const report = {
+    catalog: probeCatalog(repoRoot),
+    state: probeState(ctx),
+    config: probeConfig(ctx),
+    adapters: [],
+    clis: [],
+    upstreams: [],
+  };
+
+  // Adapter + CLI checks depend on a parsed config.
+  if (report.config.parsed) {
+    report.adapters = probeAdapters(repoRoot, report.config.parsed);
+    report.clis = probeClis(report.config.parsed, report.catalog.raw);
+  }
+
+  // Upstream presence — cheap detection from install-state.
+  report.upstreams = probeUpstreams(ctx, report.state.home);
+
+  if (json) {
+    // Strip the internal `raw` catalog payload — JSON consumers want doctor
+    // results, not the entire catalog dumped.
+    const sanitized = {
+      ...report,
+      catalog: { ...report.catalog, raw: undefined },
+    };
+    delete sanitized.catalog.raw;
+    console.log(JSON.stringify(sanitized, null, 2));
+  } else {
+    renderHuman(report, { verbose });
+  }
+
+  // Compute exit code.
+  const counts = countSeverities(report);
+  if (counts.fail > 0) return 2;
+  if (counts.warn > 0) return 1;
+  return 0;
+}
+
+function probeCatalog(repoRoot) {
+  const r = { path: join(repoRoot, 'catalog.yaml'), status: '✗', error: null, raw: null };
+  try {
+    r.raw = loadCatalog(repoRoot, { validate: true });
+    r.status = '✓';
+  } catch (err) {
+    r.error = err.message;
+  }
+  return r;
+}
+
+function probeState(ctx) {
+  const home = ctx.home || process.env.HOME;
+  const homePath = join(home, '.claude', 'flow', 'install-state.json');
+  const projectPath = join(ctx.cwd, '.claude', 'flow', 'install-state.json');
+  return {
+    home: probeJson(homePath, 'home'),
+    project: probeJson(projectPath, 'project'),
+  };
+}
+
+function probeJson(path, scope) {
+  const r = { path, scope, status: 'ℹ', error: null, parsed: null };
+  if (!existsSync(path)) {
+    r.error = 'not present (run /flow-init)';
+    return r;
+  }
+  try {
+    const content = readFileSync(path, 'utf-8').trim();
+    if (!content) {
+      r.status = '⚠';
+      r.error = 'empty file';
+      return r;
+    }
+    r.parsed = JSON.parse(content);
+    r.status = '✓';
+  } catch (err) {
+    r.status = '✗';
+    r.error = err.message;
+  }
+  return r;
+}
+
+function probeConfig(ctx) {
+  const path = join(ctx.cwd, 'flow.config.yaml');
+  const r = { path, status: '✗', error: null, parsed: null };
+  if (!existsSync(path)) {
+    r.status = 'ℹ';
+    r.error = 'not present (run /flow-init)';
+    return r;
+  }
+  try {
+    r.parsed = parseYaml(readFileSync(path, 'utf-8'));
+    if (!r.parsed || typeof r.parsed !== 'object') {
+      r.status = '✗';
+      r.error = 'parsed to non-object';
+      return r;
+    }
+    if (!r.parsed.adapters) {
+      r.status = '⚠';
+      r.error = "missing required 'adapters' section";
+      return r;
+    }
+    r.status = '✓';
+  } catch (err) {
+    r.error = err.message;
+  }
+  return r;
+}
+
+function probeAdapters(repoRoot, config) {
+  const families = ['issue_tracker', 'pr', 'e2e', 'verify'];
+  const results = [];
+  for (const family of families) {
+    const id = config.adapters?.[family];
+    if (!id) {
+      results.push({ family, id: null, status: 'ℹ', detail: 'not configured' });
+      continue;
+    }
+    const adapterPath = join(repoRoot, 'adapters', family.replace('_', '-'), `${id}.md`);
+    if (!existsSync(adapterPath)) {
+      results.push({
+        family,
+        id,
+        status: '⚠',
+        detail: `adapter file missing: ${adapterPath}`,
+      });
+      continue;
+    }
+    // Detect mixed-state (issue #28): project-side symlink vs regular file.
+    const projectAdapter = join(process.cwd(), '.claude', 'flow', 'adapters', `${family.replace('_', '-')}.md`);
+    let kind = 'absent';
+    if (existsSync(projectAdapter)) {
+      try {
+        kind = lstatSync(projectAdapter).isSymbolicLink() ? 'symlink' : 'regular_file';
+      } catch (e) {
+        kind = 'unknown';
+      }
+    }
+    results.push({
+      family,
+      id,
+      status: kind === 'regular_file' ? '⚠' : '✓',
+      kind,
+      detail: kind === 'regular_file'
+        ? 'project-side adapter is a regular file (not a Flow symlink); upstream updates will not propagate'
+        : `adapter file present at ${adapterPath}`,
+    });
+  }
+  return results;
+}
+
+function probeClis(config, catalog) {
+  if (!catalog) return [];
+  const required = new Set();
+  for (const family of ['issue_tracker', 'pr', 'e2e', 'verify']) {
+    const id = config.adapters?.[family];
+    if (!id) continue;
+    const adapter = catalog.adapters?.find((a) => a.id === id);
+    if (adapter?.needs_cli) {
+      for (const cli of adapter.needs_cli) required.add(cli);
+    }
+  }
+  const results = [];
+  for (const cli of required) {
+    let status = '✗';
+    let path = null;
+    try {
+      path = execaSync('which', [cli]).stdout.trim();
+      if (path) status = '✓';
+    } catch (e) { /* not in PATH */ }
+    results.push({ cli, status, path, detail: status === '✓' ? path : 'not in $PATH' });
+  }
+  return results;
+}
+
+function probeUpstreams(ctx, homeState) {
+  if (!homeState.parsed?.upstreams) return [];
+  const out = [];
+  for (const [name, rec] of Object.entries(homeState.parsed.upstreams)) {
+    out.push({
+      name,
+      status: rec.installed ? '✓' : 'ℹ',
+      subset: rec.subset,
+      version: rec.version || 'not pinned',
+    });
+  }
+  return out;
+}
+
+function countSeverities(report) {
+  const counts = { ok: 0, info: 0, warn: 0, fail: 0 };
+  const items = [
+    report.catalog,
+    report.state.home,
+    report.state.project,
+    report.config,
+    ...report.adapters,
+    ...report.clis,
+    ...report.upstreams,
+  ];
+  for (const item of items) {
+    if (!item) continue;
+    if (item.status === '✓') counts.ok++;
+    else if (item.status === 'ℹ') counts.info++;
+    else if (item.status === '⚠') counts.warn++;
+    else if (item.status === '✗') counts.fail++;
+  }
+  return counts;
+}
+
+function renderHuman(report, { verbose }) {
+  const lines = [];
+  lines.push(chalk.bold('━━━ flow doctor ━━━'));
+  lines.push('');
+  lines.push(`Catalog:    ${tag(report.catalog.status)}  ${report.catalog.path}`);
+  if (report.catalog.error) lines.push(`            ${chalk.dim(report.catalog.error)}`);
+
+  lines.push('');
+  lines.push('State:');
+  lines.push(`  Home:     ${tag(report.state.home.status)}  ${report.state.home.path}`);
+  if (report.state.home.error) lines.push(`            ${chalk.dim(report.state.home.error)}`);
+  lines.push(`  Project:  ${tag(report.state.project.status)}  ${report.state.project.path}`);
+  if (report.state.project.error) lines.push(`            ${chalk.dim(report.state.project.error)}`);
+  lines.push(`  Config:   ${tag(report.config.status)}  ${report.config.path}`);
+  if (report.config.error) lines.push(`            ${chalk.dim(report.config.error)}`);
+
+  if (report.adapters.length > 0) {
+    lines.push('');
+    lines.push('Adapters:');
+    for (const a of report.adapters) {
+      lines.push(`  ${a.family}:  ${tag(a.status)}  ${a.id || chalk.dim('—')}  ${chalk.dim(a.detail || '')}`);
+    }
+  }
+
+  if (report.clis.length > 0) {
+    lines.push('');
+    lines.push('CLIs:');
+    for (const c of report.clis) {
+      lines.push(`  ${c.cli}:  ${tag(c.status)}  ${chalk.dim(c.detail)}`);
+    }
+  }
+
+  if (report.upstreams.length > 0) {
+    lines.push('');
+    lines.push('Upstreams:');
+    for (const u of report.upstreams) {
+      lines.push(`  ${u.name}:  ${tag(u.status)}  subset=${u.subset || '—'}  version=${u.version}`);
+    }
+  }
+
+  const c = countSeverities(report);
+  lines.push('');
+  lines.push(chalk.bold(`Summary: ${c.ok} ✓ · ${c.info} ℹ · ${c.warn} ⚠ · ${c.fail} ✗`));
+
+  if (verbose) {
+    lines.push('');
+    lines.push(chalk.dim('For LLM-dependent checks (MCP responsiveness, severity-label preservation,'));
+    lines.push(chalk.dim('Caveman global-scope detection), run /flow-doctor inside Claude Code.'));
+  }
+
+  console.log(lines.join('\n'));
+}
+
+function tag(s) {
+  if (s === '✓') return chalk.green('✓');
+  if (s === '⚠') return chalk.yellow('⚠');
+  if (s === '✗') return chalk.red('✗');
+  if (s === 'ℹ') return chalk.cyan('ℹ');
+  return s;
+}
+
+/**
+ * --repair-upstream <name>: print the exact commands to reinstall the pinned
+ * version of an upstream after drift. Does NOT auto-run — upstream installs
+ * touch user-scope state and curl-pipe-bash should never be triggered
+ * implicitly by a CLI subcommand.
+ *
+ * Reads pinned version from $HOME/.claude/flow/install-state.json.
+ *
+ * @param {string} name - bmad | ecc | caveman
+ * @param {Object} ctx
+ * @returns {Promise<number>} exit code
+ */
+async function runRepairUpstream(name, ctx) {
+  const validNames = ['bmad', 'ecc', 'caveman'];
+  if (!validNames.includes(name)) {
+    console.error(chalk.red(`✗ Unknown upstream: ${name}`));
+    console.error(`  Available: ${validNames.join(', ')}`);
+    return 1;
+  }
+
+  const homePath = join(ctx.home || process.env.HOME, '.claude', 'flow', 'install-state.json');
+  if (!existsSync(homePath)) {
+    console.error(chalk.red(`✗ No install-state.json at ${homePath}`));
+    console.error('  Run /flow-init first.');
+    return 1;
+  }
+
+  let state;
+  try {
+    state = JSON.parse(readFileSync(homePath, 'utf-8'));
+  } catch (err) {
+    console.error(chalk.red(`✗ Could not parse install-state.json: ${err.message}`));
+    return 1;
+  }
+
+  const record = state.upstreams?.[name];
+  if (!record || !record.version) {
+    console.error(chalk.yellow(`⚠ No pinned version recorded for ${name}.`));
+    console.error('  Either /flow-init pre-dates pinning, or this upstream was never installed via Flow.');
+    console.error(`  Re-run /flow-init --update --pin-upstream ${name} to capture the current version.`);
+    return 1;
+  }
+
+  console.log(chalk.bold(`━━━ flow doctor --repair-upstream ${name} ━━━`));
+  console.log();
+  console.log(`Pinned version (from install-state): ${chalk.cyan(record.version)}`);
+  console.log(`Subset:                              ${record.subset || '—'}`);
+  console.log();
+  console.log(chalk.bold('Run these commands yourself to repair (Flow refuses to auto-run upstream installers):'));
+  console.log();
+
+  if (name === 'bmad') {
+    const v = record.version.replace(/^v/, '');
+    console.log(`  ${chalk.cyan(`npx bmad-method@${v} install --tools claude-code --yes`)}`);
+    console.log();
+    console.log(chalk.dim('  Notes:'));
+    console.log(chalk.dim(`  - npx will install the exact pinned version.`));
+    console.log(chalk.dim(`  - If the pinned version was a commit hash (e.g. "unknown@<date>"), use git checkout in _bmad/ instead.`));
+  } else if (name === 'ecc') {
+    console.log(`  ${chalk.cyan(`cd ~/.claude/rules && git fetch --all && git checkout ${record.version}`)}`);
+    console.log();
+    console.log(chalk.dim('  Notes:'));
+    console.log(chalk.dim(`  - ECC ships as a git checkout under ~/.claude/rules. The pinned value is a git ref.`));
+    console.log(chalk.dim(`  - If ~/.claude/rules/ isn't a git checkout, re-run the ECC installer:`));
+    console.log(chalk.dim(`    npx @everything-claude-code/ecc install --target claude --profile ${record.subset}`));
+  } else if (name === 'caveman') {
+    console.log(`  ${chalk.cyan(`curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash`)}`);
+    console.log();
+    console.log(chalk.dim('  Notes:'));
+    console.log(chalk.dim(`  - Caveman ships only via curl-pipe-bash. The pinned version (${record.version}) is informational; the installer always lands on main.`));
+    console.log(chalk.dim(`  - To inspect first: set FLOW_INSPECT_INSTALL_SCRIPTS=1 and re-run /flow-init.`));
+    console.log(chalk.dim(`  - Local hook patches (e.g., project-scope from PR #407) at ~/.claude/hooks/caveman-*.pre-scope-patch will be overwritten — reapply them after.`));
+  }
+
+  console.log();
+  console.log(chalk.dim('After repair, re-run `flow doctor` to verify the drift warning clears.'));
+  return 0;
+}

package/lib/commands/init.js

@@ -0,0 +1,86 @@
+// lib/commands/init.js — `flow init` headless entry point.
+//
+// v0.7 scope: the *interactive* installer lives in skills/flow-init/workflow.md
+// (Claude Code reads the workflow and runs it). The headless `flow init` CLI
+// path is intentionally thin — it prints the plan, then either:
+//   • dispatches to `claude` CLI to run /flow-init (if `claude` is in $PATH), or
+//   • prints clear instructions for running /flow-init manually.
+//
+// Why thin: porting the full interactive workflow to Node duplicates ~800 LOC
+// of decision logic already in workflow.md. Better to have one source of truth.
+
+import chalk from 'chalk';
+import { execa } from 'execa';
+import { loadCatalog, resolveProfile } from '../catalog.js';
+import { resolveRepoRoot } from '../repo-root.js';
+import plan from './plan.js';
+
+/**
+ * @param {Object} args
+ * @param {Object} ctx
+ */
+export default async function init(args, ctx) {
+  const repoRoot = ctx.repoRoot ?? resolveRepoRoot(import.meta.url);
+  loadCatalog(repoRoot);  // validate parseable; throws on bad catalog
+
+  const profileName = args.profile ?? 'standard';
+  const yes = Boolean(args.yes);
+  const dryRun = Boolean(args['dry-run']);
+
+  // Always show the plan first.
+  console.log(chalk.dim(`Resolving plan for profile '${profileName}'…`));
+  console.log();
+  await plan({ ...args, profile: profileName }, ctx);
+  console.log();
+
+  if (dryRun) {
+    console.log(chalk.dim('(--dry-run: stopping before execution)'));
+    return 0;
+  }
+
+  // Inside Claude Code: just tell the user to run /flow-init. Don't fork.
+  if (ctx.insideClaudeCode) {
+    console.log(chalk.bold('Inside Claude Code — run the slash command:'));
+    console.log(`  ${chalk.cyan('/flow-init')}${profileName !== 'standard' ? ` --profile ${profileName}` : ''}`);
+    return 0;
+  }
+
+  // Outside Claude Code: try to dispatch to `claude` CLI.
+  if (!yes) {
+    console.log(chalk.yellow('?'), `Run the interactive installer via the \`claude\` CLI? [y/N]`);
+    console.log(chalk.dim('  (Re-run with --yes to skip this prompt, or use --dry-run to preview only.)'));
+    return 0;  // Non-interactive default: stop. CI scripts use --yes.
+  }
+
+  const claudeAvailable = await hasClaudeCli();
+  if (!claudeAvailable) {
+    console.error(chalk.yellow('⚠'), 'The `claude` CLI is not on $PATH.');
+    console.error('  Install Claude Code (https://claude.com/claude-code), then:');
+    console.error(`    ${chalk.cyan('claude')}    # start a session`);
+    console.error(`    ${chalk.cyan('/flow-init')}  # inside the session`);
+    return 2;
+  }
+
+  // Dispatch: open `claude` with /flow-init prefilled.
+  console.log(chalk.dim('Dispatching to `claude` CLI…'));
+  try {
+    await execa('claude', ['/flow-init', ...(profileName !== 'standard' ? ['--profile', profileName] : [])], {
+      stdio: 'inherit',
+      env: { ...process.env, FLOW_REPO_ROOT: repoRoot }
+    });
+    return 0;
+  } catch (err) {
+    if (err.exitCode != null) return err.exitCode;
+    console.error(chalk.red(`✗ Failed to launch claude: ${err.message}`));
+    return 1;
+  }
+}
+
+async function hasClaudeCli() {
+  try {
+    await execa('which', ['claude']);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/commands/install.js

@@ -0,0 +1,181 @@
+// lib/commands/install.js — headless install path.
+//
+// `flow install` is the scriptable / CI version of /flow-init. Where /flow-init
+// asks ~8 questions, `flow install` takes everything via flags and either
+// executes (with --yes) or prints the plan (without).
+//
+// This covers the "core" operations from catalog.yaml:
+//   - copy flow_components into the target scope's skills/ dir
+//   - copy templates into flow-init's templates/ subdir
+//   - ensure $HOME/.claude/flow/install-state.json exists
+//   - write a starter flow.config.yaml in the project root
+//   - record an install-state.json entry per scope
+//
+// What this does NOT do (intentionally — too risky/interactive for a CLI):
+//   - install Caveman via curl-pipe-bash (run /flow-init or the upstream installer)
+//   - install BMad (run /flow-init or `npx bmad-method install`)
+//   - install ECC (run /flow-init or its install.sh)
+//   - register MCP servers (run `claude mcp add` yourself; the slash-command path
+//     surfaces auth prompts properly)
+//   - migrate BMad state (--migrate-bmad needs interactive confirmations)
+//
+// `flow install` prints a summary at the end pointing at /flow-init for the
+// interactive remainder.
+
+import { existsSync, mkdirSync, copyFileSync, writeFileSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import chalk from 'chalk';
+import { loadCatalog, resolveProfile, listProfiles } from '../catalog.js';
+import { resolveRepoRoot } from '../repo-root.js';
+
+/**
+ * @param {Object} args
+ * @param {Object} ctx
+ */
+export default async function install(args, ctx) {
+  const repoRoot = ctx.repoRoot ?? resolveRepoRoot(import.meta.url);
+  const catalog = loadCatalog(repoRoot);
+
+  const profileName = args.profile ?? 'standard';
+  if (!catalog.profiles[profileName]) {
+    console.error(chalk.red(`✗ Unknown profile: ${profileName}`));
+    console.error(`  Available: ${listProfiles(catalog).join(', ')}`);
+    return 1;
+  }
+
+  const profile = resolveProfile(catalog, profileName);
+  const yes = Boolean(args.yes);
+  const dryRun = Boolean(args['dry-run']);
+  const scope = args.scope ?? 'both';
+
+  const homeRoot = ctx.home || process.env.HOME;
+  const home = (p) => resolve(p.replace(/\$HOME/g, homeRoot));
+
+  // Build plan: list of file operations.
+  const operations = [];
+  for (const componentId of profile.flow_components) {
+    const component = catalog.flow_components.find((c) => c.id === componentId);
+    if (!component) {
+      console.error(chalk.yellow(`⚠ Component '${componentId}' referenced by profile but not in catalog`));
+      continue;
+    }
+    for (const op of component.operations || []) {
+      if (op.copy) {
+        operations.push({
+          kind: 'copy',
+          component: componentId,
+          from: join(repoRoot, op.copy.from),
+          to: home(op.copy.to),
+        });
+      } else if (op.ensure_dir) {
+        operations.push({ kind: 'ensure_dir', component: componentId, path: home(op.ensure_dir) });
+      } else if (op.touch) {
+        operations.push({ kind: 'touch', component: componentId, path: home(op.touch) });
+      }
+    }
+  }
+
+  // Plan summary.
+  console.log(chalk.bold(`━━━ flow install (profile: ${profileName}) ━━━`));
+  console.log();
+  console.log(`Scope:        ${scope}`);
+  console.log(`Components:   ${profile.flow_components.length}`);
+  console.log(`Adapters:     ${profile.adapters.length}  (${profile.adapters.join(', ')})`);
+  console.log(`MCPs:         ${profile.mcps.length}  (${profile.mcps.join(', ') || chalk.dim('none')})`);
+  console.log(`BMad subset:  ${profile.bmad_subset}  ${chalk.dim('(this CLI will NOT run BMad installer)')}`);
+  console.log(`ECC subset:   ${profile.ecc_subset}   ${chalk.dim('(this CLI will NOT run ECC installer)')}`);
+  console.log(`Caveman:      ${profile.caveman_subset}  ${chalk.dim('(this CLI will NOT run Caveman installer)')}`);
+  console.log();
+  console.log(`Operations:   ${operations.length}`);
+  if (args.verbose) {
+    for (const op of operations) {
+      console.log(`  ${chalk.green('+')} ${op.kind}  ${chalk.dim(op.path || `${op.from} → ${op.to}`)}`);
+    }
+  }
+
+  if (dryRun) {
+    console.log();
+    console.log(chalk.dim('--dry-run: stopping before execution. Re-run with --yes to execute.'));
+    return 0;
+  }
+
+  if (!yes) {
+    console.log();
+    console.log(chalk.yellow('?'), 'Execute? Re-run with --yes to confirm, or --dry-run to preview.');
+    return 0;
+  }
+
+  // Execute.
+  console.log();
+  console.log(chalk.bold('Executing:'));
+  let executed = 0;
+  let skipped = 0;
+  let failed = 0;
+
+  for (const op of operations) {
+    try {
+      if (op.kind === 'copy') {
+        if (!existsSync(op.from)) {
+          throw new Error(`source missing: ${op.from}`);
+        }
+        const isDir = statSync(op.from).isDirectory();
+        if (isDir) {
+          copyDirRecursive(op.from, op.to);
+        } else {
+          mkdirSync(dirname(op.to), { recursive: true });
+          copyFileSync(op.from, op.to);
+        }
+        console.log(`  ${chalk.green('✓')} copy  ${op.from} → ${op.to}`);
+      } else if (op.kind === 'ensure_dir') {
+        mkdirSync(op.path, { recursive: true });
+        console.log(`  ${chalk.green('✓')} ensure_dir  ${op.path}`);
+      } else if (op.kind === 'touch') {
+        mkdirSync(dirname(op.path), { recursive: true });
+        if (!existsSync(op.path)) writeFileSync(op.path, '{}');
+        console.log(`  ${chalk.green('✓')} touch  ${op.path}`);
+      }
+      executed++;
+    } catch (err) {
+      console.log(`  ${chalk.red('✗')} ${op.kind} failed: ${err.message}`);
+      failed++;
+    }
+  }
+
+  // Record state.
+  const statePath = home('$HOME/.claude/flow/install-state.json');
+  let state = { schema_version: 'flow.install.v1', upstreams: {} };
+  if (existsSync(statePath)) {
+    try { state = JSON.parse(readFileSync(statePath, 'utf-8')); } catch (e) { /* keep fresh */ }
+  }
+  state.schema_version = state.schema_version || 'flow.install.v1';
+  state.flow_version = ctx.pkg?.version || state.flow_version;
+  state.profile = profileName;
+  state.last_updated = new Date().toISOString();
+  state.scope = scope;
+  state.installed_via = 'flow install (headless)';
+  mkdirSync(dirname(statePath), { recursive: true });
+  writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
+
+  console.log();
+  console.log(chalk.bold(`Done: ${executed} executed, ${failed} failed, ${skipped} skipped.`));
+  console.log();
+  console.log(chalk.dim('Next steps (this CLI does NOT do these — too interactive for headless):'));
+  console.log(chalk.dim('  1. Install BMad / ECC / Caveman manually or run /flow-init for the interactive path'));
+  console.log(chalk.dim('  2. Register MCPs:  claude mcp add context7 npx @upstash/context7-mcp@latest'));
+  console.log(chalk.dim('  3. Write flow.config.yaml in your project root (see templates/flow.config.yaml.tmpl)'));
+
+  return failed > 0 ? 2 : 0;
+}
+
+function copyDirRecursive(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}