cto-ai-cli 3.0.2 → 3.1.0

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/dist/govern/index.d.ts

@@ -0,0 +1,261 @@
+interface AuditEntry {
+    id: string;
+    timestamp: Date;
+    action: AuditAction;
+    user: string;
+    projectPath: string;
+    contextHash?: string;
+    filesIncluded?: number;
+    filesExcluded?: number;
+    tokensUsed?: number;
+    coverageScore?: number;
+    riskScore?: number;
+    model?: string;
+    estimatedCost?: number;
+    integrityHash: string;
+    details: Record<string, unknown>;
+}
+type AuditAction = 'init' | 'analyze' | 'interact' | 'snapshot-create' | 'snapshot-verify' | 'policy-change' | 'secret-detected' | 'integrity-check';
+interface PolicySet {
+    version: string;
+    name: string;
+    rules: PolicyRule[];
+}
+interface PolicyRule {
+    id: string;
+    type: PolicyRuleType;
+    pattern?: string;
+    threshold?: number;
+    category?: string;
+    reason: string;
+    enabled: boolean;
+}
+type PolicyRuleType = 'include-always' | 'exclude-always' | 'budget-limit' | 'coverage-minimum' | 'risk-maximum' | 'secret-block';
+interface PolicyValidation {
+    passed: boolean;
+    violations: PolicyViolation[];
+    warnings: PolicyWarning[];
+}
+interface PolicyViolation {
+    rule: PolicyRule;
+    message: string;
+    severity: 'error' | 'warning';
+}
+interface PolicyWarning {
+    rule: PolicyRule;
+    message: string;
+    currentValue: number;
+    threshold: number;
+}
+interface ContextSnapshot {
+    id: string;
+    name: string;
+    createdAt: Date;
+    hash: string;
+    projectHash: string;
+    analysisHash: string;
+    selectionHash: string;
+    files: SnapshotFile[];
+    totalTokens: number;
+    coverageScore: number;
+    riskScore: number;
+    metadata: Record<string, unknown>;
+}
+interface SnapshotFile {
+    relativePath: string;
+    hash: string;
+    tokens: number;
+    pruneLevel: string;
+}
+interface SnapshotVerification {
+    valid: boolean;
+    snapshotId: string;
+    filesChecked: number;
+    filesMatched: number;
+    filesMissing: string[];
+    filesChanged: string[];
+    integrityOk: boolean;
+}
+interface SecretFinding {
+    type: SecretType;
+    file: string;
+    line: number;
+    match: string;
+    redacted: string;
+    severity: 'critical' | 'high' | 'medium' | 'low';
+}
+type SecretType = 'api-key' | 'aws-key' | 'private-key' | 'password' | 'token' | 'connection-string' | 'env-variable' | 'custom';
+interface IntegrityManifest {
+    version: string;
+    createdAt: Date;
+    entries: IntegrityEntry[];
+}
+interface IntegrityEntry {
+    filePath: string;
+    hash: string;
+    size: number;
+    createdAt: Date;
+    type: 'snapshot' | 'audit' | 'config' | 'policy';
+}
+
+declare function logAudit(action: AuditAction, projectPath: string, details?: Record<string, unknown>): Promise<AuditEntry>;
+declare function getAuditEntries(options?: {
+    projectPath?: string;
+    action?: AuditAction;
+    since?: Date;
+    limit?: number;
+}): Promise<AuditEntry[]>;
+declare function verifyAuditEntry(entry: AuditEntry): boolean;
+declare function verifyAuditIntegrity(): Promise<{
+    totalEntries: number;
+    validEntries: number;
+    invalidEntries: AuditEntry[];
+}>;
+declare function purgeOldAuditEntries(retentionDays: number): Promise<number>;
+
+declare function scanContentForSecrets(content: string, filePath: string, customPatterns?: string[]): SecretFinding[];
+declare function scanFileForSecrets(filePath: string, projectPath: string, customPatterns?: string[]): Promise<SecretFinding[]>;
+declare function scanProjectForSecrets(projectPath: string, filePaths: string[], customPatterns?: string[]): Promise<SecretFinding[]>;
+declare function sanitizeContent(content: string, customPatterns?: string[]): string;
+
+interface AnalyzedFile {
+    path: string;
+    relativePath: string;
+    extension: string;
+    size: number;
+    tokens: number;
+    lines: number;
+    lastModified: Date;
+    kind: FileKind;
+    imports: string[];
+    importedBy: string[];
+    isHub: boolean;
+    complexity: number;
+    riskScore: number;
+    riskFactors: RiskFactor[];
+    exclusionImpact: ExclusionImpact;
+}
+type FileKind = 'source' | 'type' | 'test' | 'config' | 'entry' | 'asset';
+type ExclusionImpact = 'critical' | 'high' | 'medium' | 'low' | 'none';
+interface ProjectAnalysis {
+    projectPath: string;
+    projectName: string;
+    analyzedAt: Date;
+    hash: string;
+    files: AnalyzedFile[];
+    totalFiles: number;
+    totalTokens: number;
+    graph: ProjectGraph;
+    riskProfile: RiskProfile;
+    stack: string[];
+    tokenMethod: 'chars4' | 'tiktoken';
+}
+interface ProjectGraph {
+    nodes: string[];
+    edges: GraphEdge[];
+    hubs: HubNode[];
+    leaves: string[];
+    orphans: string[];
+    clusters: FileCluster[];
+}
+interface GraphEdge {
+    from: string;
+    to: string;
+    type: 'import' | 'export' | 're-export';
+}
+interface HubNode {
+    relativePath: string;
+    dependents: number;
+    dependencies: number;
+    score: number;
+}
+interface FileCluster {
+    id: string;
+    name: string;
+    files: string[];
+    totalTokens: number;
+    internalEdges: number;
+    externalEdges: number;
+    cohesion: number;
+}
+interface RiskProfile {
+    distribution: {
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+    };
+    topRiskFiles: AnalyzedFile[];
+    overallComplexity: number;
+}
+interface RiskFactor {
+    type: RiskFactorType;
+    score: number;
+    weight: number;
+    detail: string;
+}
+type RiskFactorType = 'hub' | 'type-provider' | 'complexity' | 'recency' | 'config' | 'churn';
+interface CoverageResult {
+    score: number;
+    relevantFiles: string[];
+    includedRelevant: string[];
+    missingRelevant: string[];
+    missingCritical: string[];
+    explanation: string;
+}
+interface ContextSelection {
+    files: SelectedFile[];
+    totalTokens: number;
+    budget: number;
+    usedPercent: number;
+    coverage: CoverageResult;
+    riskScore: number;
+    deterministic: boolean;
+    hash: string;
+    decisions: SelectionDecision[];
+}
+interface SelectedFile {
+    relativePath: string;
+    tokens: number;
+    originalTokens: number;
+    pruneLevel: PruneLevel;
+    riskScore: number;
+    reason: string;
+}
+type PruneLevel = 'full' | 'signatures' | 'skeleton' | 'excluded';
+interface SelectionDecision {
+    file: string;
+    action: 'include-full' | 'include-signatures' | 'include-skeleton' | 'exclude';
+    reason: string;
+    alternatives?: string;
+}
+
+declare const DEFAULT_POLICY: PolicySet;
+declare function validateSelection(selection: ContextSelection, policies: PolicySet, allFiles?: AnalyzedFile[]): PolicyValidation;
+declare function addRule(policies: PolicySet, rule: PolicyRule): PolicySet;
+declare function removeRule(policies: PolicySet, ruleId: string): PolicySet;
+declare function toggleRule(policies: PolicySet, ruleId: string, enabled: boolean): PolicySet;
+
+declare function createSnapshot(name: string, analysis: ProjectAnalysis, selection: ContextSelection, metadata?: Record<string, unknown>): ContextSnapshot;
+declare function verifySnapshot(snapshot: ContextSnapshot, currentAnalysis: ProjectAnalysis, currentSelection: ContextSelection): Promise<SnapshotVerification>;
+declare function compareSnapshots(older: ContextSnapshot, newer: ContextSnapshot): {
+    added: string[];
+    removed: string[];
+    changed: string[];
+    tokenDelta: number;
+    coverageDelta: number;
+    riskDelta: number;
+};
+
+declare function hashContent(content: Buffer | string): string;
+declare function hashFile(filePath: string): Promise<string | null>;
+declare function buildManifest(projectDir: string): Promise<IntegrityManifest>;
+declare function verifyManifest(manifest: IntegrityManifest): Promise<{
+    totalFiles: number;
+    validFiles: number;
+    invalidFiles: string[];
+    missingFiles: string[];
+}>;
+declare function securePermissions(dirPath: string): Promise<number>;
+
+export { DEFAULT_POLICY, addRule, buildManifest, compareSnapshots, createSnapshot, getAuditEntries, hashContent, hashFile, logAudit, purgeOldAuditEntries, removeRule, sanitizeContent, scanContentForSecrets, scanFileForSecrets, scanProjectForSecrets, securePermissions, toggleRule, validateSelection, verifyAuditEntry, verifyAuditIntegrity, verifyManifest, verifySnapshot };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cto-ai-cli",
-  "version": "3.0.2",
+  "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": {