cto-ai-cli 3.0.1 → 3.1.0

package/README.md

@@ -8,7 +8,7 @@
 ## Try it now (zero install)
 
 ```bash
-npx cto-score
+npx cto-ai-cli
 ```
 
 That's it. Run it on any project. You'll see something like this:
@@ -33,7 +33,7 @@ That's it. Run it on any project. You'll see something like this:
   Scanned in 11.7s · 177 files · 340K tokens
 ```
 
-Run `npx cto-score --benchmark` to see how CTO compares to naive (alphabetical) and random file selection.
+Run `npx cto-ai-cli --benchmark` to see how CTO compares to naive (alphabetical) and random file selection.
 
 No data leaves your machine. No API keys. MIT licensed.
 
@@ -77,10 +77,10 @@ Without type definitions, the AI invents interfaces — wrong property names, wr
 ### Option 1: Quick score (no install)
 
 ```bash
-npx cto-score                 # Score your project
-npx cto-score ./my-project    # Score a specific project
-npx cto-score --benchmark     # Compare CTO vs naive vs random
-npx cto-score --json          # Machine-readable output (for CI)
+npx cto-ai-cli                 # Score your project
+npx cto-ai-cli ./my-project    # Score a specific project
+npx cto-ai-cli --benchmark     # Compare CTO vs naive vs random
+npx cto-ai-cli --json          # Machine-readable output (for CI)
 ```
 
 ### Option 2: Full install
@@ -132,7 +132,7 @@ CTO doesn't use AI for selection. It uses dependency analysis, risk modeling, an
 
 ## Real numbers
 
-We ran CTO on three open-source projects. No cherry-picking — you can reproduce these with `npx cto-score --benchmark`.
+We ran CTO on three open-source projects. No cherry-picking — you can reproduce these with `npx cto-ai-cli --benchmark`.
 
 | Project | Files | Score | What CTO does |
 |---------|-------|-------|---------------|
@@ -201,14 +201,14 @@ Without these files, the AI has to guess the shape of `AnalyzedFile`, `ContextSe
 
 | Use case | How |
 |----------|-----|
-| **Score your project** | `npx cto-score` |
-| **Compare strategies** | `npx cto-score --benchmark` |
+| **Score your project** | `npx cto-ai-cli` |
+| **Compare strategies** | `npx cto-ai-cli --benchmark` |
 | **Get optimized context for a task** | `cto2 interact "your task"` |
 | **PR-focused context** | `cto2 interact --pr "review this PR"` |
 | **Use in your AI editor** | Add MCP server (see setup above) |
 | **Use in CI/CD** | GitHub Action posts score on every PR |
 | **Use as an API** | `cto2-api` starts an HTTP server |
-| **JSON output (scripting)** | `npx cto-score --json` |
+| **JSON output (scripting)** | `npx cto-ai-cli --json` |
 
 ---
 

package/dist/cli/score.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli/score.ts
-import { resolve as resolve4 } from "path";
+import { resolve as resolve4, join as join4 } from "path";
+import { mkdirSync, writeFileSync, readFileSync } from "fs";
 
 // src/engine/analyzer.ts
 import { readFile as readFile2, readdir, stat as stat2 } from "fs/promises";
@@ -1883,18 +1884,27 @@ async function main() {
   const args = process.argv.slice(2);
   const jsonMode = args.includes("--json");
   const benchmarkMode = args.includes("--benchmark");
+  const fixMode = args.includes("--fix");
+  const reportMode = args.includes("--report");
+  const compareMode = args.includes("--compare");
   const helpMode = args.includes("--help") || args.includes("-h");
-  const pathArg = args.find((a) => !a.startsWith("--") && !a.startsWith("-"));
+  const contextIdx = args.indexOf("--context");
+  const contextTask = contextIdx !== -1 && args[contextIdx + 1] ? args[contextIdx + 1] : null;
+  const pathArg = args.find((a) => !a.startsWith("--") && !a.startsWith("-") && a !== contextTask);
   const projectPath = resolve4(pathArg ?? ".");
   if (helpMode) {
     console.log(`
   \u26A1 cto-score \u2014 How AI-ready is your codebase?
 
   Usage:
-    npx cto-score              Scan current directory
-    npx cto-score ./path       Scan a specific project
-    npx cto-score --benchmark  Include CTO vs naive vs random comparison
-    npx cto-score --json       Output as JSON (for CI/scripts)
+    npx cto-ai-cli                           Scan current directory
+    npx cto-ai-cli ./path                    Scan a specific project
+    npx cto-ai-cli --benchmark               CTO vs naive vs random comparison
+    npx cto-ai-cli --fix                     Auto-generate optimized context files
+    npx cto-ai-cli --context "your task"     Generate task-specific context
+    npx cto-ai-cli --report                  Generate shareable markdown report
+    npx cto-ai-cli --compare                 Compare your score vs popular projects
+    npx cto-ai-cli --json                    Output as JSON (for CI/scripts)
 
   What it does:
     Analyzes your project's structure, dependencies, and risk profile.
@@ -1902,7 +1912,7 @@ async function main() {
     can work with your codebase.
 
   No data leaves your machine. No API keys needed. MIT licensed.
-  Learn more: https://github.com/cto-ai/cto-ai-cli
+  Learn more: https://npmjs.com/package/cto-ai-cli
 `);
     process.exit(0);
   }
@@ -1942,6 +1952,18 @@ async function main() {
       const benchmark = await runBenchmark(analysis);
       console.log(renderBenchmark(benchmark));
     }
+    if (fixMode) {
+      await runFix(projectPath, analysis, score);
+    }
+    if (contextTask) {
+      await runContext(projectPath, analysis, contextTask);
+    }
+    if (reportMode) {
+      await runReport(projectPath, analysis, score);
+    }
+    if (compareMode) {
+      runCompare(score);
+    }
     console.log("");
     console.log(`  Scanned in ${elapsed}s \xB7 ${analysis.totalFiles} files \xB7 ${Math.round(analysis.totalTokens / 1e3)}K tokens`);
     console.log("");
@@ -1950,15 +1972,17 @@ async function main() {
     if (score.overall >= 80) {
       console.log("    \u2705 Great! AI tools can work effectively with your codebase.");
     } else if (score.overall >= 60) {
-      console.log("    \u{1F7E1} Good, but there's room to improve. Run with --benchmark for details.");
+      console.log("    \u{1F7E1} Good, but there's room to improve. Run with --fix to auto-optimize.");
     } else {
-      console.log("    \u{1F534} AI tools are likely wasting tokens on your project. Run with --benchmark.");
+      console.log("    \u{1F534} AI tools are likely wasting tokens on your project. Run with --fix.");
     }
     console.log("");
     console.log("  Next steps:");
-    console.log("    npx cto-score --benchmark    See CTO vs naive comparison");
-    console.log("    npm i -g cto-ai-cli          Install for full CLI + MCP server");
-    console.log("    https://github.com/cto-ai/cto-ai-cli   Full docs");
+    console.log("    npx cto-ai-cli --fix                  Auto-generate optimized context");
+    console.log('    npx cto-ai-cli --context "your task"  Task-specific context for Claude/Cursor');
+    console.log("    npx cto-ai-cli --report               Shareable report + badge");
+    console.log("    npx cto-ai-cli --compare              Compare vs popular open source");
+    console.log("    npm i -g cto-ai-cli                   Install for full CLI + MCP server");
     console.log("");
   } catch (err) {
     console.error(`  \u274C Error: ${err.message}`);
@@ -1968,4 +1992,382 @@ async function main() {
     process.exit(1);
   }
 }
+async function runFix(projectPath, analysis, score) {
+  const ctoDir = join4(projectPath, ".cto");
+  mkdirSync(ctoDir, { recursive: true });
+  const selection = await selectContext({
+    task: "general code review and refactoring",
+    analysis,
+    budget: 5e4
+  });
+  const criticalFiles = selection.files.filter((f) => f.riskScore >= 60).sort((a, b) => b.riskScore - a.riskScore);
+  const typeFiles = analysis.files.filter((f) => f.kind === "type").sort((a, b) => b.riskScore - a.riskScore);
+  const entryFiles = analysis.files.filter((f) => f.kind === "entry").sort((a, b) => b.riskScore - a.riskScore);
+  let contextMd = `# CTO Context \u2014 ${analysis.projectName}
+`;
+  contextMd += `# Generated by cto-ai-cli \xB7 Score: ${score.overall}/100 (${score.grade})
+`;
+  contextMd += `# Paste this into your AI prompt for better results.
+
+`;
+  contextMd += `## Critical files (always include these):
+`;
+  for (const f of criticalFiles.slice(0, 15)) {
+    contextMd += `- ${f.relativePath} \u2014 risk:${f.riskScore} (${f.reason})
+`;
+  }
+  if (typeFiles.length > 0) {
+    contextMd += `
+## Type definitions (AI needs these to generate correct code):
+`;
+    for (const f of typeFiles.slice(0, 10)) {
+      contextMd += `- ${f.relativePath} (${f.tokens} tokens)
+`;
+    }
+  }
+  if (entryFiles.length > 0) {
+    contextMd += `
+## Entry points:
+`;
+    for (const f of entryFiles.slice(0, 5)) {
+      contextMd += `- ${f.relativePath}
+`;
+    }
+  }
+  contextMd += `
+## Project structure:
+`;
+  contextMd += `- ${analysis.totalFiles} files, ${Math.round(analysis.totalTokens / 1e3)}K tokens total
+`;
+  contextMd += `- Stack: ${analysis.stack.join(", ") || "unknown"}
+`;
+  contextMd += `- Clusters: ${analysis.graph.clusters.length}
+`;
+  contextMd += `- Hubs: ${analysis.graph.hubs.map((h) => h.relativePath).slice(0, 5).join(", ")}
+`;
+  contextMd += `
+## Recommended token budget: ${selection.totalTokens.toLocaleString()} tokens
+`;
+  contextMd += `## Full project tokens: ${analysis.totalTokens.toLocaleString()} tokens
+`;
+  contextMd += `## Savings: ${score.comparison.savedPercent}% (${formatTokens(score.comparison.savedTokens)})
+`;
+  writeFileSync(join4(ctoDir, "context.md"), contextMd);
+  const config = {
+    version: "3.0",
+    project: analysis.projectName,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    score: score.overall,
+    grade: score.grade,
+    budget: 5e4,
+    criticalFiles: criticalFiles.slice(0, 20).map((f) => f.relativePath),
+    typeFiles: typeFiles.map((f) => f.relativePath),
+    ignorePatterns: [
+      "node_modules",
+      "dist",
+      "build",
+      ".git",
+      "*.test.*",
+      "*.spec.*",
+      "__tests__",
+      "*.md",
+      "*.json",
+      "*.lock"
+    ],
+    insights: score.insights.slice(0, 5).map((i) => ({
+      type: i.type,
+      title: i.title,
+      impact: i.impact
+    }))
+  };
+  writeFileSync(join4(ctoDir, "config.json"), JSON.stringify(config, null, 2));
+  const ignoreContent = [
+    "# CTO AI-ignore \u2014 files that add noise to AI context",
+    "# Generated by cto-ai-cli",
+    "",
+    "# Build artifacts",
+    "dist/",
+    "build/",
+    ".next/",
+    "coverage/",
+    "",
+    "# Dependencies",
+    "node_modules/",
+    "",
+    "# Large/binary files",
+    "*.lock",
+    "package-lock.json",
+    "yarn.lock",
+    "",
+    "# Low-value for AI",
+    ...analysis.graph.orphans.filter((o) => {
+      const f = analysis.files.find((af) => af.relativePath === o);
+      return f && f.riskScore < 20;
+    }).slice(0, 20).map((o) => `${o}  # orphan, low-risk`),
+    ""
+  ].join("\n");
+  writeFileSync(join4(ctoDir, ".cteignore"), ignoreContent);
+  console.log("");
+  console.log("  \u2705 Auto-fix complete! Generated:");
+  console.log("");
+  console.log("  \u{1F4CB} .cto/context.md     Copy-paste this into Claude/Cursor/ChatGPT");
+  console.log("  \u2699\uFE0F  .cto/config.json    Optimized CTO configuration");
+  console.log("  \u{1F6AB} .cto/.cteignore     Files AI should skip");
+  console.log("");
+  console.log("  \u{1F4A1} Tip: Paste .cto/context.md at the start of your AI conversation");
+  console.log("     for dramatically better code generation.");
+  console.log("");
+}
+async function runContext(projectPath, analysis, task) {
+  const ctoDir = join4(projectPath, ".cto");
+  mkdirSync(ctoDir, { recursive: true });
+  const selection = await selectContext({
+    task,
+    analysis,
+    budget: 5e4
+  });
+  const typeFiles = analysis.files.filter((f) => f.kind === "type");
+  const selectedPaths = new Set(selection.files.map((f) => f.relativePath));
+  const includedTypes = typeFiles.filter((f) => selectedPaths.has(f.relativePath));
+  let contextMd = `# Context for: ${task}
+`;
+  contextMd += `# Generated by cto-ai-cli
+`;
+  contextMd += `# ${selection.files.length} files selected, ${selection.totalTokens.toLocaleString()} tokens
+
+`;
+  const targets = selection.files.filter((f) => f.reason === "Target file");
+  const critical = selection.files.filter((f) => f.riskScore >= 80 && f.reason !== "Target file");
+  const high = selection.files.filter((f) => f.riskScore >= 60 && f.riskScore < 80 && f.reason !== "Target file");
+  const rest = selection.files.filter((f) => f.riskScore < 60 && f.reason !== "Target file");
+  if (targets.length > 0) {
+    contextMd += `## Target files (directly related to task):
+`;
+    for (const f of targets) {
+      contextMd += `- ${f.relativePath}
+`;
+    }
+    contextMd += "\n";
+  }
+  if (critical.length > 0) {
+    contextMd += `## Critical dependencies:
+`;
+    for (const f of critical) {
+      contextMd += `- ${f.relativePath} \u2014 ${f.reason}
+`;
+    }
+    contextMd += "\n";
+  }
+  if (includedTypes.length > 0) {
+    contextMd += `## Type definitions (needed for correct code generation):
+`;
+    for (const f of includedTypes) {
+      contextMd += `- ${f.relativePath}
+`;
+    }
+    contextMd += "\n";
+  }
+  if (high.length > 0) {
+    contextMd += `## High-relevance files:
+`;
+    for (const f of high) {
+      contextMd += `- ${f.relativePath}
+`;
+    }
+    contextMd += "\n";
+  }
+  if (rest.length > 0) {
+    contextMd += `## Supporting files:
+`;
+    for (const f of rest.slice(0, 15)) {
+      contextMd += `- ${f.relativePath}
+`;
+    }
+    if (rest.length > 15) {
+      contextMd += `- ... and ${rest.length - 15} more
+`;
+    }
+    contextMd += "\n";
+  }
+  contextMd += `---
+
+`;
+  contextMd += `## File contents (top ${Math.min(targets.length + critical.length, 10)} files):
+
+`;
+  const topFiles = [...targets, ...critical].slice(0, 10);
+  for (const sf of topFiles) {
+    const fullFile = analysis.files.find((f) => f.relativePath === sf.relativePath);
+    if (!fullFile) continue;
+    try {
+      const content = readFileSync(fullFile.path, "utf-8");
+      const ext = fullFile.extension.replace(".", "");
+      contextMd += `### ${sf.relativePath}
+`;
+      contextMd += `\`\`\`${ext}
+${content.slice(0, 5e3)}
+\`\`\`
+
+`;
+    } catch {
+    }
+  }
+  const safeName = task.replace(/[^a-zA-Z0-9]/g, "-").toLowerCase().slice(0, 40);
+  const filename = `context-${safeName}.md`;
+  writeFileSync(join4(ctoDir, filename), contextMd);
+  console.log("");
+  console.log(`  \u2705 Task context generated!`);
+  console.log("");
+  console.log(`  \u{1F4CB} .cto/${filename}`);
+  console.log(`     ${selection.files.length} files \xB7 ${selection.totalTokens.toLocaleString()} tokens`);
+  console.log(`     Coverage: ${selection.coverage.score}%`);
+  console.log("");
+  console.log(`  \u{1F4A1} Copy-paste this file into Claude/Cursor/ChatGPT for`);
+  console.log(`     optimized context on: "${task}"`);
+  console.log("");
+}
+async function runReport(projectPath, analysis, score) {
+  const gradeEmoji = score.grade.startsWith("A") ? "\u{1F7E2}" : score.grade.startsWith("B") ? "\u{1F535}" : score.grade.startsWith("C") ? "\u{1F7E1}" : "\u{1F534}";
+  const gradeColor = score.overall >= 80 ? "brightgreen" : score.overall >= 60 ? "green" : score.overall >= 40 ? "yellow" : "red";
+  let report = `# CTO Context Score\u2122 Report
+
+`;
+  report += `![CTO Score](https://img.shields.io/badge/CTO_Score-${score.overall}%2F100-${gradeColor}?style=for-the-badge)
+`;
+  report += `![Grade](https://img.shields.io/badge/Grade-${score.grade}-${gradeColor}?style=for-the-badge)
+
+`;
+  report += `> Generated by [cto-ai-cli](https://npmjs.com/package/cto-ai-cli) on ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}
+
+`;
+  report += `## Project: ${analysis.projectName}
+
+`;
+  report += `| Metric | Value |
+`;
+  report += `|--------|-------|
+`;
+  report += `| **Score** | ${gradeEmoji} ${score.overall}/100 (${score.grade}) |
+`;
+  report += `| **Files** | ${analysis.totalFiles} |
+`;
+  report += `| **Total tokens** | ${analysis.totalTokens.toLocaleString()} |
+`;
+  report += `| **Optimized tokens** | ${score.comparison.optimizedTokens.toLocaleString()} |
+`;
+  report += `| **Token savings** | ${score.comparison.savedPercent}% (${formatTokens(score.comparison.savedTokens)}) |
+`;
+  report += `| **Est. monthly savings** | $${score.comparison.monthlySavingsUSD.toFixed(2)} |
+`;
+  report += `| **Stack** | ${analysis.stack.join(", ") || "unknown"} |
+
+`;
+  report += `## Dimensions
+
+`;
+  report += `| Dimension | Score | Weight | Detail |
+`;
+  report += `|-----------|-------|--------|--------|
+`;
+  report += `| Efficiency | ${score.dimensions.efficiency.score}% | 30% | ${score.dimensions.efficiency.detail} |
+`;
+  report += `| Coverage | ${score.dimensions.coverage.score}% | 25% | ${score.dimensions.coverage.detail} |
+`;
+  report += `| Risk Control | ${score.dimensions.riskControl.score}% | 20% | ${score.dimensions.riskControl.detail} |
+`;
+  report += `| Structure | ${score.dimensions.structure.score}% | 15% | ${score.dimensions.structure.detail} |
+`;
+  report += `| Governance | ${score.dimensions.governance.score}% | 10% | ${score.dimensions.governance.detail} |
+
+`;
+  if (score.insights.length > 0) {
+    report += `## Insights
+
+`;
+    for (const insight of score.insights.slice(0, 8)) {
+      const icon = insight.type === "strength" ? "\u2705" : insight.type === "weakness" ? "\u26A0\uFE0F" : "\u{1F4A1}";
+      report += `- ${icon} **${insight.title}** \u2014 ${insight.detail}
+`;
+    }
+    report += "\n";
+  }
+  report += `## Badge for your README
+
+`;
+  report += `\`\`\`markdown
+`;
+  report += `![CTO Score](https://img.shields.io/badge/CTO_Score-${score.overall}%2F100-${gradeColor})
+`;
+  report += `\`\`\`
+
+`;
+  report += `---
+
+`;
+  report += `*Run \`npx cto-ai-cli\` to generate your own report. [Learn more](https://npmjs.com/package/cto-ai-cli)*
+`;
+  const ctoDir = join4(projectPath, ".cto");
+  mkdirSync(ctoDir, { recursive: true });
+  writeFileSync(join4(ctoDir, "report.md"), report);
+  console.log("");
+  console.log("  \u2705 Report generated!");
+  console.log("");
+  console.log("  \u{1F4CA} .cto/report.md     Share on Slack, Discord, or GitHub");
+  console.log("");
+  console.log("  \u{1F3F7}\uFE0F  Badge for your README:");
+  console.log(`     ![CTO Score](https://img.shields.io/badge/CTO_Score-${score.overall}%2F100-${gradeColor})`);
+  console.log("");
+  console.log("  Copy-paste this markdown into your README:");
+  console.log(`     ![CTO Score](https://img.shields.io/badge/CTO_Score-${score.overall}%2F100-${gradeColor})`);
+  console.log("");
+}
+function runCompare(score) {
+  const benchmarks = [
+    { name: "Zod", score: 92, grade: "A", files: 441, tokens: "804K" },
+    { name: "Prisma Client", score: 88, grade: "A", files: 320, tokens: "650K" },
+    { name: "tRPC", score: 85, grade: "A-", files: 280, tokens: "420K" },
+    { name: "Next.js (core)", score: 78, grade: "B+", files: 890, tokens: "2.1M" },
+    { name: "Express.js", score: 74, grade: "B-", files: 158, tokens: "171K" },
+    { name: "Lodash", score: 65, grade: "C+", files: 612, tokens: "380K" }
+  ];
+  console.log("");
+  console.log("  \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+  console.log("  \u{1F4CA} Your project vs popular open source");
+  console.log("  \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+  console.log("");
+  const all = [
+    { name: `\u2192 ${score.meta.projectName} (you)`, score: score.overall, grade: score.grade, isYou: true },
+    ...benchmarks.map((b) => ({ ...b, isYou: false }))
+  ].sort((a, b) => b.score - a.score);
+  for (const entry of all) {
+    const bar = renderCompareBar(entry.score);
+    const marker = entry.isYou ? "  \u25C4" : "";
+    const name = entry.name.padEnd(25);
+    console.log(`  ${name} ${entry.score.toString().padStart(3)}/100 (${entry.grade.padEnd(2)}) ${bar}${marker}`);
+  }
+  console.log("");
+  const beaten = benchmarks.filter((b) => score.overall > b.score);
+  const aheadOf = benchmarks.filter((b) => score.overall < b.score);
+  if (beaten.length > 0) {
+    console.log(`  \u2705 You beat: ${beaten.map((b) => b.name).join(", ")}`);
+  }
+  if (aheadOf.length > 0 && aheadOf.length <= 3) {
+    console.log(`  \u{1F3AF} To reach ${aheadOf[0].name}'s level: run --fix and address the insights above`);
+  }
+  if (beaten.length === benchmarks.length) {
+    console.log("  \u{1F3C6} You outperform ALL benchmarked projects! \u{1F389}");
+  }
+  console.log("");
+}
+function renderCompareBar(pct) {
+  const width = 25;
+  const filled = Math.round(pct / 100 * width);
+  const empty = width - filled;
+  return "\u2588".repeat(filled) + "\u2591".repeat(empty);
+}
+function formatTokens(n) {
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}K`;
+  return n.toString();
+}
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cto-ai-cli",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Your AI is reading too much code. CTO analyzes your project and selects the optimal files for AI context — saving tokens, improving output quality, and ensuring type definitions are included.",
   "type": "module",
   "bin": {