claudex-setup 1.6.0 → 1.7.0

package/src/analyze.js

@@ -0,0 +1,397 @@
+/**
+ * Project scanner + recommendation layer for augment and suggest-only modes.
+ * Produces a structured repo-aware analysis without writing files.
+ */
+
+const path = require('path');
+const { audit } = require('./audit');
+const { ProjectContext } = require('./context');
+const { STACKS } = require('./techniques');
+
+const COLORS = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[36m',
+  magenta: '\x1b[35m',
+};
+
+function c(text, color) {
+  return `${COLORS[color] || ''}${text}${COLORS.reset}`;
+}
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function extractTomlSection(content, sectionName) {
+  const pattern = new RegExp(`\\[${escapeRegex(sectionName)}\\]([\\s\\S]*?)(?:\\n\\s*\\[|$)`);
+  const match = content.match(pattern);
+  return match ? match[1] : null;
+}
+
+function extractTomlValue(sectionContent, key) {
+  if (!sectionContent) return null;
+  const pattern = new RegExp(`^\\s*${escapeRegex(key)}\\s*=\\s*["']([^"']+)["']`, 'm');
+  const match = sectionContent.match(pattern);
+  return match ? match[1].trim() : null;
+}
+
+function detectProjectMetadata(ctx) {
+  const pkg = ctx.jsonFile('package.json');
+  if (pkg && (pkg.name || pkg.description)) {
+    return {
+      name: pkg.name || path.basename(ctx.dir),
+      description: pkg.description || '',
+    };
+  }
+
+  const pyproject = ctx.fileContent('pyproject.toml') || '';
+  if (pyproject) {
+    const projectSection = extractTomlSection(pyproject, 'project');
+    const poetrySection = extractTomlSection(pyproject, 'tool.poetry');
+    const name = extractTomlValue(projectSection, 'name') ||
+      extractTomlValue(poetrySection, 'name');
+    const description = extractTomlValue(projectSection, 'description') ||
+      extractTomlValue(poetrySection, 'description');
+
+    if (name || description) {
+      return {
+        name: name || path.basename(ctx.dir),
+        description: description || '',
+      };
+    }
+  }
+
+  return {
+    name: path.basename(ctx.dir),
+    description: '',
+  };
+}
+
+function detectMainDirs(ctx) {
+  const candidates = [
+    'src', 'lib', 'app', 'pages', 'components', 'api', 'routes', 'utils', 'helpers',
+    'services', 'models', 'controllers', 'views', 'public', 'assets', 'config', 'tests',
+    'test', '__tests__', 'spec', 'scripts', 'prisma', 'db', 'middleware', 'hooks',
+    'agents', 'chains', 'workers', 'jobs', 'dags', 'macros', 'migrations',
+    'src/components', 'src/app', 'src/pages', 'src/api', 'src/lib', 'src/hooks',
+    'src/utils', 'src/services', 'src/models', 'src/middleware', 'src/agents',
+    'src/chains', 'src/workers', 'src/jobs', 'src/app/api', 'app/api',
+    'models/staging', 'models/marts'
+  ];
+
+  const dirs = [];
+  for (const dir of candidates) {
+    if (ctx.hasDir(dir)) {
+      dirs.push(dir);
+    }
+  }
+  return dirs;
+}
+
+function collectClaudeAssets(ctx) {
+  const sharedSettings = ctx.jsonFile('.claude/settings.json');
+  const localSettings = ctx.jsonFile('.claude/settings.local.json');
+  const settings = sharedSettings || localSettings || null;
+
+  const assetFiles = {
+    claudeMd: ctx.fileContent('CLAUDE.md') ? 'CLAUDE.md' : (ctx.fileContent('.claude/CLAUDE.md') ? '.claude/CLAUDE.md' : null),
+    settings: sharedSettings ? '.claude/settings.json' : (localSettings ? '.claude/settings.local.json' : null),
+    commands: ctx.hasDir('.claude/commands') ? ctx.dirFiles('.claude/commands') : [],
+    rules: ctx.hasDir('.claude/rules') ? ctx.dirFiles('.claude/rules') : [],
+    hooks: ctx.hasDir('.claude/hooks') ? ctx.dirFiles('.claude/hooks') : [],
+    agents: ctx.hasDir('.claude/agents') ? ctx.dirFiles('.claude/agents') : [],
+    skills: ctx.hasDir('.claude/skills') ? ctx.dirFiles('.claude/skills') : [],
+  };
+
+  return {
+    files: assetFiles,
+    counts: {
+      commands: assetFiles.commands.length,
+      rules: assetFiles.rules.length,
+      hooks: assetFiles.hooks.length,
+      agents: assetFiles.agents.length,
+      skills: assetFiles.skills.length,
+      mcpServers: settings && settings.mcpServers ? Object.keys(settings.mcpServers).length : 0,
+    },
+    permissions: settings && settings.permissions ? {
+      defaultMode: settings.permissions.defaultMode || null,
+      hasDenyRules: Array.isArray(settings.permissions.deny) && settings.permissions.deny.length > 0,
+    } : null,
+    settingsSource: assetFiles.settings,
+  };
+}
+
+function detectMaturity(assets) {
+  let score = 0;
+  if (assets.files.claudeMd) score += 2;
+  if (assets.files.settings) score += 1;
+  if (assets.counts.rules > 0) score += 1;
+  if (assets.counts.commands > 0) score += 1;
+  if (assets.counts.hooks > 0) score += 1;
+  if (assets.counts.agents > 0) score += 1;
+  if (assets.counts.skills > 0) score += 1;
+
+  if (score === 0) return 'none';
+  if (score <= 2) return 'starter';
+  if (score <= 5) return 'developing';
+  return 'mature';
+}
+
+function riskFromImpact(impact) {
+  if (impact === 'critical') return 'high';
+  if (impact === 'high') return 'medium';
+  return 'low';
+}
+
+function moduleFromCategory(category) {
+  const map = {
+    memory: 'CLAUDE.md',
+    quality: 'verification',
+    git: 'safety',
+    workflow: 'commands-agents-skills',
+    security: 'permissions',
+    automation: 'hooks',
+    design: 'design-rules',
+    devops: 'ci-devops',
+    hygiene: 'project-hygiene',
+    performance: 'context-management',
+    tools: 'mcp-tools',
+    prompting: 'prompt-structure',
+    features: 'modern-claude-features',
+    'quality-deep': 'quality-deep',
+  };
+  return map[category] || category;
+}
+
+function toStrengths(results) {
+  return results
+    .filter(r => r.passed === true)
+    .sort((a, b) => {
+      const order = { critical: 3, high: 2, medium: 1, low: 0 };
+      return (order[b.impact] || 0) - (order[a.impact] || 0);
+    })
+    .slice(0, 6)
+    .map(r => ({
+      key: r.key,
+      name: r.name,
+      category: r.category,
+      note: `Already present and worth preserving: ${r.name}.`,
+    }));
+}
+
+function toGaps(results) {
+  return results
+    .filter(r => r.passed === false)
+    .sort((a, b) => {
+      const order = { critical: 3, high: 2, medium: 1, low: 0 };
+      return (order[b.impact] || 0) - (order[a.impact] || 0);
+    })
+    .slice(0, 8)
+    .map(r => ({
+      key: r.key,
+      name: r.name,
+      impact: r.impact,
+      category: r.category,
+      fix: r.fix,
+    }));
+}
+
+function toRecommendations(auditResult) {
+  const failed = auditResult.results
+    .filter(r => r.passed === false)
+    .sort((a, b) => {
+      const order = { critical: 3, high: 2, medium: 1, low: 0 };
+      return (order[b.impact] || 0) - (order[a.impact] || 0);
+    });
+
+  return failed.slice(0, 10).map((r, index) => ({
+    priority: index + 1,
+    key: r.key,
+    name: r.name,
+    impact: r.impact,
+    module: moduleFromCategory(r.category),
+    risk: riskFromImpact(r.impact),
+    why: r.fix,
+  }));
+}
+
+function buildOptionalModules(stacks, assets) {
+  const stackKeys = stacks.map(s => s.key);
+  const modules = [];
+
+  if (!assets.files.claudeMd) modules.push('CLAUDE.md baseline');
+  if (assets.counts.commands === 0) modules.push('Slash commands');
+  if (assets.counts.hooks === 0) modules.push('Hooks automation');
+  if (!assets.permissions || !assets.permissions.hasDenyRules) modules.push('Permission safety profile');
+  if (assets.counts.rules === 0) modules.push('Path-specific rules');
+  if (stackKeys.some(k => ['react', 'nextjs', 'vue', 'angular', 'svelte'].includes(k))) modules.push('Frontend pack');
+  if (stackKeys.some(k => ['node', 'python', 'django', 'fastapi', 'go', 'rust', 'java'].includes(k))) modules.push('Backend pack');
+  if (stackKeys.some(k => ['docker', 'terraform', 'kubernetes'].includes(k))) modules.push('DevOps pack');
+  if (assets.counts.agents === 0) modules.push('Specialized agents');
+
+  return [...new Set(modules)].slice(0, 8);
+}
+
+function buildRiskNotes(auditResult, assets, maturity) {
+  const notes = [];
+  if (!assets.files.claudeMd) notes.push('No CLAUDE.md exists yet, so Claude has no persistent project-specific guidance.');
+  if (assets.permissions && assets.permissions.defaultMode === 'bypassPermissions') {
+    notes.push('Current settings use bypassPermissions, which is risky for broader team adoption.');
+  }
+  if (!assets.permissions || !assets.permissions.hasDenyRules) {
+    notes.push('Permissions lack deny rules, so secret access and destructive commands are not strongly guarded.');
+  }
+  if (maturity === 'mature') {
+    notes.push('This repo already has meaningful Claude assets, so augment mode should preserve existing structure instead of overwriting it.');
+  }
+  if (auditResult.results.some(r => r.key === 'ciPipeline' && r.passed === false)) {
+    notes.push('Without CI enforcement, readiness can drift after setup.');
+  }
+  return notes.slice(0, 5);
+}
+
+function buildRolloutOrder(report) {
+  const steps = [];
+  if (!report.existingClaudeAssets.claudeMd) steps.push('Create a project-specific CLAUDE.md baseline');
+  if (report.gapsIdentified.some(g => g.category === 'security')) steps.push('Add safe settings and deny rules');
+  if (report.gapsIdentified.some(g => g.category === 'automation')) steps.push('Add hooks and automate verification');
+  if (report.gapsIdentified.some(g => g.category === 'workflow')) steps.push('Add commands, rules, and specialization modules');
+  if (report.gapsIdentified.some(g => g.category === 'devops')) steps.push('Connect CI threshold enforcement');
+  if (steps.length === 0) steps.push('Tighten quality-deep items and preserve the current setup');
+  return steps;
+}
+
+async function analyzeProject(options) {
+  const mode = options.mode || 'augment';
+  const ctx = new ProjectContext(options.dir);
+  const stacks = ctx.detectStacks(STACKS);
+  const auditResult = await audit({ ...options, silent: true });
+  const assets = collectClaudeAssets(ctx);
+  const metadata = detectProjectMetadata(ctx);
+  const maturity = detectMaturity(assets);
+  const mainDirs = detectMainDirs(ctx);
+
+  const report = {
+    mode,
+    writeBehavior: 'No files are written in this mode.',
+    projectSummary: {
+      name: metadata.name,
+      description: metadata.description,
+      directory: options.dir,
+      stacks: stacks.map(s => s.label),
+      maturity,
+      score: auditResult.score,
+      organicScore: auditResult.organicScore,
+      checkCount: auditResult.checkCount,
+    },
+    detectedArchitecture: {
+      repoType: stacks.length > 0 ? 'stack-detected repo' : 'generic repo',
+      mainDirectories: mainDirs,
+      stackSignals: stacks.map(s => s.key),
+    },
+    existingClaudeAssets: {
+      claudeMd: assets.files.claudeMd,
+      settings: assets.settingsSource,
+      commands: assets.files.commands,
+      rules: assets.files.rules,
+      hooks: assets.files.hooks,
+      agents: assets.files.agents,
+      skills: assets.files.skills,
+      mcpServers: assets.counts.mcpServers,
+    },
+    strengthsPreserved: toStrengths(auditResult.results),
+    gapsIdentified: toGaps(auditResult.results),
+    topNextActions: auditResult.quickWins,
+    recommendedImprovements: toRecommendations(auditResult),
+    riskNotes: buildRiskNotes(auditResult, assets, maturity),
+    optionalModules: buildOptionalModules(stacks, assets),
+  };
+
+  report.suggestedRolloutOrder = buildRolloutOrder(report);
+  return report;
+}
+
+function printAnalysis(report, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  const modeLabel = report.mode === 'suggest-only' ? 'suggest-only' : report.mode;
+  console.log('');
+  console.log(c(`  claudex-setup ${modeLabel}`, 'bold'));
+  console.log(c('  ═══════════════════════════════════════', 'dim'));
+  console.log(c(`  ${report.writeBehavior}`, 'dim'));
+  console.log('');
+
+  console.log(c('  Project Summary', 'blue'));
+  console.log(`  ${report.projectSummary.name}${report.projectSummary.description ? ` — ${report.projectSummary.description}` : ''}`);
+  console.log(c(`  Stack: ${report.projectSummary.stacks.join(', ') || 'Unknown'}`, 'dim'));
+  console.log(c(`  Maturity: ${report.projectSummary.maturity} | Score: ${report.projectSummary.score}/100 | Organic: ${report.projectSummary.organicScore}/100`, 'dim'));
+  console.log('');
+
+  console.log(c('  Detected Architecture', 'blue'));
+  console.log(c(`  Main directories: ${report.detectedArchitecture.mainDirectories.join(', ') || 'No strong structure detected yet'}`, 'dim'));
+  console.log('');
+
+  console.log(c('  Existing Claude Assets', 'blue'));
+  console.log(c(`  CLAUDE.md: ${report.existingClaudeAssets.claudeMd || 'missing'}`, 'dim'));
+  console.log(c(`  Settings: ${report.existingClaudeAssets.settings || 'missing'}`, 'dim'));
+  console.log(c(`  Commands: ${report.existingClaudeAssets.commands.length} | Rules: ${report.existingClaudeAssets.rules.length} | Hooks: ${report.existingClaudeAssets.hooks.length} | Agents: ${report.existingClaudeAssets.agents.length} | Skills: ${report.existingClaudeAssets.skills.length}`, 'dim'));
+  console.log('');
+
+  if (report.strengthsPreserved.length > 0) {
+    console.log(c('  Strengths Preserved', 'green'));
+    for (const item of report.strengthsPreserved) {
+      console.log(`  - ${item.name}`);
+    }
+    console.log('');
+  }
+
+  if (report.gapsIdentified.length > 0) {
+    console.log(c('  Gaps Identified', 'yellow'));
+    for (const item of report.gapsIdentified.slice(0, 5)) {
+      console.log(`  - [${item.impact}] ${item.name}`);
+      console.log(c(`    ${item.fix}`, 'dim'));
+    }
+    console.log('');
+  }
+
+  if (report.topNextActions.length > 0) {
+    console.log(c('  Top 5 Next Actions', 'magenta'));
+    report.topNextActions.slice(0, 5).forEach((item, index) => {
+      console.log(`  ${index + 1}. ${item.name}`);
+      console.log(c(`     ${item.fix}`, 'dim'));
+    });
+    console.log('');
+  }
+
+  if (report.riskNotes.length > 0) {
+    console.log(c('  Risk Notes', 'red'));
+    for (const note of report.riskNotes) {
+      console.log(`  - ${note}`);
+    }
+    console.log('');
+  }
+
+  if (report.optionalModules.length > 0) {
+    console.log(c('  Optional Modules', 'blue'));
+    console.log(c(`  ${report.optionalModules.join(' | ')}`, 'dim'));
+    console.log('');
+  }
+
+  if (report.suggestedRolloutOrder.length > 0) {
+    console.log(c('  Suggested Rollout Order', 'blue'));
+    report.suggestedRolloutOrder.forEach((item, index) => {
+      console.log(`  ${index + 1}. ${item}`);
+    });
+    console.log('');
+  }
+}
+
+module.exports = { analyzeProject, printAnalysis };

package/src/audit.js

@@ -29,17 +29,17 @@ function progressBar(score, max = 100, width = 20) {
   return colorize('█'.repeat(filled), color) + colorize('░'.repeat(empty), 'dim');
 }
 
-const EFFORT_ORDER = { critical: 0, high: 1, medium: 2 };
+const IMPACT_ORDER = { critical: 3, high: 2, medium: 1, low: 0 };
 
 function getQuickWins(failed) {
-  // Quick wins = medium impact items first (easiest), then high, sorted by name length (shorter = simpler)
-  return [...failed]
+  const prioritized = failed.filter(r => !(r.category === 'hygiene' && r.impact === 'low'));
+  const pool = prioritized.length > 0 ? prioritized : failed;
+
+  return [...pool]
     .sort((a, b) => {
-      const effortA = EFFORT_ORDER[a.impact] ?? 3;
-      const effortB = EFFORT_ORDER[b.impact] ?? 3;
-      // Prefer medium (easiest to fix), then high, then critical
-      if (effortA !== effortB) return effortB - effortA;
-      // Tie-break by fix length (shorter fix description = likely simpler)
+      const impactA = IMPACT_ORDER[a.impact] ?? 0;
+      const impactB = IMPACT_ORDER[b.impact] ?? 0;
+      if (impactA !== impactB) return impactB - impactA;
       return (a.fix || '').length - (b.fix || '').length;
     })
     .slice(0, 3);
@@ -90,10 +90,23 @@ async function audit(options) {
   const scaffoldedPassed = passed.filter(r => scaffoldedKeys.has(r.key));
   const organicEarned = organicPassed.reduce((sum, r) => sum + (weights[r.impact] || 5), 0);
   const organicScore = maxScore > 0 ? Math.round((organicEarned / maxScore) * 100) : 0;
+  const quickWins = getQuickWins(failed);
+  const result = {
+    score,
+    organicScore,
+    isScaffolded,
+    passed: passed.length,
+    failed: failed.length,
+    skipped: skipped.length,
+    checkCount: applicable.length,
+    stacks,
+    results,
+    quickWins: quickWins.map(({ key, name, impact, fix, category }) => ({ key, name, impact, category, fix })),
+  };
 
   // Silent mode: skip all output, just return result
   if (silent) {
-    return { score, passed: passed.length, failed: failed.length, stacks, results };
+    return result;
   }
 
   if (options.json) {
@@ -101,15 +114,9 @@ async function audit(options) {
     console.log(JSON.stringify({
       version,
       timestamp: new Date().toISOString(),
-      score,
-      stacks,
-      passed: passed.length,
-      failed: failed.length,
-      skipped: skipped.length,
-      checkCount: applicable.length,
-      results
+      ...result
     }, null, 2));
-    return { score, passed: passed.length, failed: failed.length, stacks, results };
+    return result;
   }
 
   // Display results
@@ -173,8 +180,7 @@ async function audit(options) {
 
   // Quick wins
   if (failed.length > 0) {
-    const quickWins = getQuickWins(failed);
-    console.log(colorize('  ⚡ Quick wins (easiest fixes first)', 'magenta'));
+    console.log(colorize('  ⚡ Best next fixes', 'magenta'));
     for (let i = 0; i < quickWins.length; i++) {
       const r = quickWins[i];
       console.log(`     ${i + 1}. ${colorize(r.name, 'bold')}`);
@@ -211,7 +217,6 @@ async function audit(options) {
   console.log('');
 
   // Send anonymous insights (opt-in, privacy-first, fire-and-forget)
-  const result = { score, passed: passed.length, failed: failed.length, stacks, results };
   sendInsights(result);
 
   return result;

package/src/benchmark.js

@@ -0,0 +1,176 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { version } = require('../package.json');
+const { audit } = require('./audit');
+const { setup } = require('./setup');
+
+function copyProject(sourceDir, targetDir) {
+  fs.mkdirSync(targetDir, { recursive: true });
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === '__pycache__') {
+      continue;
+    }
+    const from = path.join(sourceDir, entry.name);
+    const to = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      copyProject(from, to);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
+function summarizeAudit(result) {
+  return {
+    score: result.score,
+    organicScore: result.organicScore,
+    passed: result.passed,
+    failed: result.failed,
+    checkCount: result.checkCount,
+    quickWins: result.quickWins,
+  };
+}
+
+function buildExecutiveSummary(before, after) {
+  const scoreDelta = after.score - before.score;
+  const organicDelta = after.organicScore - before.organicScore;
+  return {
+    headline: scoreDelta > 0
+      ? `Benchmark improved readiness by ${scoreDelta} points without touching the original repo.`
+      : 'Benchmark did not improve the score in this run.',
+    scoreDelta,
+    organicDelta,
+    decisionGuidance: scoreDelta >= 20
+      ? 'Strong pilot candidate'
+      : scoreDelta >= 10
+        ? 'Promising but needs manual review'
+        : 'Use suggest-only mode before rollout',
+  };
+}
+
+function buildCaseStudy(before, after, applyResult) {
+  return {
+    initialState: `Baseline score ${before.score}/100, organic ${before.organicScore}/100.`,
+    chosenMode: 'benchmark-on-isolated-copy',
+    whatChanged: applyResult.writtenFiles,
+    whatWasPreserved: applyResult.preservedFiles,
+    measuredResults: {
+      scoreDelta: after.score - before.score,
+      organicDelta: after.organicScore - before.organicScore,
+      passedDelta: after.passed - before.passed,
+    },
+  };
+}
+
+function renderBenchmarkMarkdown(report) {
+  return [
+    '# Claudex Setup Benchmark Report',
+    '',
+    `- Generated by: ${report.generatedBy}`,
+    `- Created at: ${report.createdAt}`,
+    `- Source repo: ${report.directory}`,
+    '',
+    '## Methodology',
+    ...report.methodology.map(item => `- ${item}`),
+    '',
+    '## Before',
+    `- Score: ${report.before.score}/100`,
+    `- Organic score: ${report.before.organicScore}/100`,
+    `- Passing checks: ${report.before.passed}/${report.before.checkCount}`,
+    '',
+    '## After',
+    `- Score: ${report.after.score}/100`,
+    `- Organic score: ${report.after.organicScore}/100`,
+    `- Passing checks: ${report.after.passed}/${report.after.checkCount}`,
+    '',
+    '## Delta',
+    `- Score delta: ${report.delta.score}`,
+    `- Organic score delta: ${report.delta.organicScore}`,
+    `- Passed checks delta: ${report.delta.passed}`,
+    '',
+    '## Executive Summary',
+    `- ${report.executiveSummary.headline}`,
+    `- Recommendation: ${report.executiveSummary.decisionGuidance}`,
+    '',
+    '## Case Study',
+    `- Initial state: ${report.caseStudy.initialState}`,
+    `- Chosen mode: ${report.caseStudy.chosenMode}`,
+    `- What changed: ${report.caseStudy.whatChanged.join(', ') || 'none'}`,
+    `- What was preserved: ${report.caseStudy.whatWasPreserved.join(', ') || 'none'}`,
+    '',
+  ].join('\n');
+}
+
+async function runBenchmark(options) {
+  const before = await audit({ dir: options.dir, silent: true });
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'claudex-benchmark-'));
+  const sandboxDir = path.join(tempRoot, 'repo');
+
+  try {
+    copyProject(options.dir, sandboxDir);
+    const applyResult = await setup({ dir: sandboxDir, auto: true, silent: true });
+    const after = await audit({ dir: sandboxDir, silent: true });
+
+    return {
+      schemaVersion: 1,
+      generatedBy: `claudex-setup@${version}`,
+      createdAt: new Date().toISOString(),
+      directory: options.dir,
+      methodology: [
+        'Run a baseline audit on the source repo.',
+        'Copy the repo into a temporary isolated workspace.',
+        'Apply starter-safe Claude artifacts only on the isolated copy.',
+        'Re-run the audit and compare the results.',
+      ],
+      before: summarizeAudit(before),
+      after: summarizeAudit(after),
+      delta: {
+        score: after.score - before.score,
+        organicScore: after.organicScore - before.organicScore,
+        passed: after.passed - before.passed,
+        failed: after.failed - before.failed,
+      },
+      executiveSummary: buildExecutiveSummary(before, after),
+      caseStudy: buildCaseStudy(before, after, applyResult),
+    };
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+function printBenchmark(report, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log('  claudex-setup benchmark');
+  console.log('  ═══════════════════════════════════════');
+  console.log('  Runs in an isolated temp copy. Your current repo is not modified.');
+  console.log('');
+  console.log(`  Before:  ${report.before.score}/100 (organic ${report.before.organicScore}/100)`);
+  console.log(`  After:   ${report.after.score}/100 (organic ${report.after.organicScore}/100)`);
+  console.log(`  Delta:   score ${report.delta.score >= 0 ? '+' : ''}${report.delta.score}, organic ${report.delta.organicScore >= 0 ? '+' : ''}${report.delta.organicScore}`);
+  console.log('');
+  console.log(`  ${report.executiveSummary.headline}`);
+  console.log(`  Recommendation: ${report.executiveSummary.decisionGuidance}`);
+  console.log('');
+}
+
+function writeBenchmarkReport(report, outFile) {
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+  const content = path.extname(outFile).toLowerCase() === '.md'
+    ? renderBenchmarkMarkdown(report)
+    : JSON.stringify(report, null, 2);
+  fs.writeFileSync(outFile, content, 'utf8');
+}
+
+module.exports = {
+  runBenchmark,
+  printBenchmark,
+  writeBenchmarkReport,
+};