codesight 1.1.0 → 1.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 ### Your AI assistant wastes thousands of tokens every conversation just figuring out your project. codesight fixes that in one command.
 
-**Zero dependencies. 25+ framework detectors. 4 ORM parsers. MCP server. One `npx` call.**
+**Zero dependencies. 25+ framework detectors. 8 ORM parsers. 8 MCP tools. Blast radius analysis. One `npx` call.**
 
 [![npm version](https://img.shields.io/npm/v/codesight?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/codesight)
 [![npm downloads](https://img.shields.io/npm/dm/codesight?style=for-the-badge&logo=npm&color=blue&label=Monthly%20Downloads)](https://www.npmjs.com/package/codesight)
@@ -26,7 +26,7 @@
 ---
 
 ```
-0 dependencies · Node.js >= 18 · 27 tests · MIT
+0 dependencies · Node.js >= 18 · 27 tests · 8 MCP tools · MIT
 ```
 
 ## Works With
@@ -42,10 +42,12 @@ npx codesight
 That's it. Run it in any project root. No config, no setup, no API keys.
 
 ```bash
-npx codesight --init       # Also generate CLAUDE.md, .cursorrules, codex.md, AGENTS.md
-npx codesight --open       # Also open interactive HTML report in browser
-npx codesight --mcp        # Start as MCP server for Claude Code / Cursor
-npx codesight --benchmark  # Show detailed token savings breakdown
+npx codesight --init                # Generate CLAUDE.md, .cursorrules, codex.md, AGENTS.md
+npx codesight --open                # Open interactive HTML report in browser
+npx codesight --mcp                 # Start as MCP server (8 tools) for Claude Code / Cursor
+npx codesight --blast src/lib/db.ts # Show blast radius for a file
+npx codesight --profile claude-code # Generate optimized config for a specific AI tool
+npx codesight --benchmark           # Show detailed token savings breakdown
 ```
 
 ## What It Does
@@ -117,6 +119,35 @@ The files imported the most are the ones that break the most things when changed
 - `apps/api/src/lib/auth.ts` — imported by **7** files
 ```
 
+## Blast Radius
+
+See exactly what breaks if you change a file. BFS through the import graph finds all transitively affected files, routes, models, and middleware.
+
+```bash
+npx codesight --blast src/lib/db.ts
+```
+
+```
+  Blast Radius: src/lib/db.ts
+  Depth: 3 hops
+
+  Affected files (10):
+    src/routes/users.ts
+    src/routes/projects.ts
+    src/routes/billing.ts
+    ...
+
+  Affected routes (33):
+    POST /auth/login — src/routes/auth.ts
+    GET /api/users — src/routes/users.ts
+    ...
+
+  Affected models: users, projects, subscriptions
+  Affected middleware: authMiddleware
+```
+
+Your AI can also query blast radius through the MCP server before making changes.
+
 ## Environment Audit
 
 Every env var across your codebase, flagged as required or has default, with the exact file where it is referenced.
@@ -157,7 +188,7 @@ npx codesight --benchmark
 | Category | Supported |
 |---|---|
 | **Routes** | Hono, Express, Fastify, Next.js (App + Pages), Koa, NestJS, tRPC, Elysia, AdonisJS, SvelteKit, Remix, Nuxt, FastAPI, Flask, Django, Go (net/http, Gin, Fiber, Echo, Chi), Rails, Phoenix, Spring Boot, Actix, Axum, raw http.createServer |
-| **Schema** | Drizzle, Prisma, TypeORM, Mongoose, Sequelize, SQLAlchemy, ActiveRecord, Ecto |
+| **Schema** | Drizzle, Prisma, TypeORM, Mongoose, Sequelize, SQLAlchemy, ActiveRecord, Ecto (8 ORMs) |
 | **Components** | React, Vue, Svelte (auto-filters shadcn/ui and Radix primitives) |
 | **Libraries** | TypeScript, JavaScript, Python, Go, Ruby, Elixir, Java, Kotlin, Rust (exports with function signatures) |
 | **Middleware** | Auth, rate limiting, CORS, validation, logging, error handlers |
@@ -184,7 +215,7 @@ Generates ready-to-use instruction files for every major AI coding tool at once:
 
 Each file is pre-filled with your project's stack, architecture, high-impact files, and required env vars. Your AI reads it on startup and starts with full context from the first message.
 
-## MCP Server
+## MCP Server (8 Tools)
 
 ```bash
 npx codesight --mcp
@@ -203,7 +234,32 @@ Runs as a Model Context Protocol server. Claude Code and Cursor call it directly
 }
 ```
 
-Exposes one tool: `codesight_scan`. Your AI calls it whenever it needs to understand the project.
+Exposes 8 specialized tools, each returning only what your AI needs:
+
+| Tool | What it does |
+|---|---|
+| `codesight_scan` | Full project scan (~3K-5K tokens) |
+| `codesight_get_summary` | Compact overview (~500 tokens) |
+| `codesight_get_routes` | Routes filtered by prefix, tag, or method |
+| `codesight_get_schema` | Schema filtered by model name |
+| `codesight_get_blast_radius` | Impact analysis before changing a file |
+| `codesight_get_env` | Environment variables (filter: required only) |
+| `codesight_get_hot_files` | Most imported files with configurable limit |
+| `codesight_refresh` | Force re-scan (results are cached per session) |
+
+Your AI asks for exactly what it needs instead of loading the entire context map. Session caching means the first call scans, subsequent calls return instantly.
+
+## AI Tool Profiles
+
+```bash
+npx codesight --profile claude-code
+npx codesight --profile cursor
+npx codesight --profile codex
+npx codesight --profile copilot
+npx codesight --profile windsurf
+```
+
+Generates an optimized config file for a specific AI tool. Each profile includes your project summary, stack info, high-impact files, required env vars, and tool-specific instructions on how to use codesight outputs. For Claude Code, this includes MCP tool usage instructions. For Cursor, it points to the right codesight files. Each profile writes to the correct file for that tool.
 
 ## Visual Report
 
@@ -225,7 +281,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: npx codesight
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install -g codesight && codesight
       - uses: actions/upload-artifact@v4
         with:
           name: codesight
@@ -251,34 +310,37 @@ Context stays fresh without thinking about it.
 ## All Options
 
 ```bash
-npx codesight                       # Scan current directory
-npx codesight ./my-project          # Scan specific directory
-npx codesight --init                # Generate AI config files
-npx codesight --open                # Open visual HTML report
-npx codesight --html                # Generate HTML report without opening
-npx codesight --mcp                 # Start MCP server
-npx codesight --watch               # Watch mode
-npx codesight --hook                # Install git pre-commit hook
-npx codesight --benchmark           # Detailed token savings breakdown
-npx codesight --json                # Output as JSON
-npx codesight -o .ai-context        # Custom output directory
-npx codesight -d 5                  # Limit directory depth
+npx codesight                              # Scan current directory
+npx codesight ./my-project                 # Scan specific directory
+npx codesight --init                       # Generate AI config files
+npx codesight --open                       # Open visual HTML report
+npx codesight --html                       # Generate HTML report without opening
+npx codesight --mcp                        # Start MCP server (8 tools)
+npx codesight --blast src/lib/db.ts        # Show blast radius for a file
+npx codesight --profile claude-code        # Optimized config for specific tool
+npx codesight --watch                      # Watch mode
+npx codesight --hook                       # Install git pre-commit hook
+npx codesight --benchmark                  # Detailed token savings breakdown
+npx codesight --json                       # Output as JSON
+npx codesight -o .ai-context              # Custom output directory
+npx codesight -d 5                         # Limit directory depth
 ```
 
 ## How It Compares
 
 Most AI context tools dump your entire codebase into one file. codesight takes a different approach: it **parses** your code to extract structured information.
 
-| | codesight | File concatenation tools |
-|---|---|---|
-| **Output** | Structured routes, schema, components, deps | Raw file contents |
-| **Token cost** | ~3,000-5,000 tokens | 50,000-500,000+ tokens |
-| **Route detection** | 25+ frameworks auto-detected | None |
-| **Schema parsing** | ORM-aware with relations | None |
-| **Dependency graph** | Hot file detection | None |
-| **AI config generation** | CLAUDE.md, .cursorrules, etc. | None |
-| **MCP server** | Built-in | Varies |
-| **Dependencies** | Zero | Varies |
+| | codesight | File concatenation tools | AST-based tools |
+|---|---|---|---|
+| **Output** | Structured routes, schema, components, deps | Raw file contents | Call graphs, class diagrams |
+| **Token cost** | ~3,000-5,000 tokens | 50,000-500,000+ tokens | Varies |
+| **Route detection** | 25+ frameworks auto-detected | None | Limited |
+| **Schema parsing** | 8 ORMs with relations | None | Varies |
+| **Blast radius** | BFS through import graph | None | Some |
+| **AI tool profiles** | 5 tools (Claude, Cursor, Codex, Copilot, Windsurf) | None | None |
+| **MCP server** | 8 specialized tools with session caching | None | Some |
+| **Setup** | `npx codesight` (zero deps, zero config) | Copy/paste | Install compilers, runtimes |
+| **Dependencies** | Zero | Varies | Tree-sitter, SQLite, etc. |
 
 ## Contributing
 

package/dist/detectors/blast-radius.d.ts

@@ -0,0 +1,11 @@
+import type { ScanResult, BlastRadiusResult } from "../types.js";
+/**
+ * Blast radius analysis: given a file, find all transitively affected
+ * files, routes, models, and middleware using BFS through the import graph.
+ */
+export declare function analyzeBlastRadius(filePath: string, result: ScanResult, maxDepth?: number): BlastRadiusResult;
+/**
+ * Multi-file blast radius: given a list of changed files (e.g., from git diff),
+ * find the combined blast radius.
+ */
+export declare function analyzeMultiFileBlastRadius(files: string[], result: ScanResult, maxDepth?: number): BlastRadiusResult;

package/dist/detectors/blast-radius.js

@@ -0,0 +1,102 @@
+/**
+ * Blast radius analysis: given a file, find all transitively affected
+ * files, routes, models, and middleware using BFS through the import graph.
+ */
+export function analyzeBlastRadius(filePath, result, maxDepth = 3) {
+    const { graph, routes, schemas, middleware } = result;
+    // Build reverse adjacency map: file -> files that import it
+    const importedBy = new Map();
+    // Build forward adjacency map: file -> files it imports
+    const imports = new Map();
+    for (const edge of graph.edges) {
+        if (!importedBy.has(edge.to))
+            importedBy.set(edge.to, new Set());
+        importedBy.get(edge.to).add(edge.from);
+        if (!imports.has(edge.from))
+            imports.set(edge.from, new Set());
+        imports.get(edge.from).add(edge.to);
+    }
+    // BFS: find all files affected by changing this file
+    // "affected" = files that directly or transitively import this file
+    const affected = new Set();
+    const queue = [{ file: filePath, depth: 0 }];
+    while (queue.length > 0) {
+        const { file, depth } = queue.shift();
+        if (depth > maxDepth)
+            continue;
+        const dependents = importedBy.get(file);
+        if (!dependents)
+            continue;
+        for (const dep of dependents) {
+            if (!affected.has(dep)) {
+                affected.add(dep);
+                queue.push({ file: dep, depth: depth + 1 });
+            }
+        }
+    }
+    // Also include the file itself
+    affected.add(filePath);
+    // Find affected routes (routes whose handler file is in the affected set)
+    const affectedRoutes = routes.filter((r) => affected.has(r.file));
+    // Find affected models (schemas referenced in affected files)
+    const affectedModels = [];
+    for (const schema of schemas) {
+        for (const file of affected) {
+            // Check if any route/lib in this file touches this model
+            const routesInFile = routes.filter((r) => r.file === file);
+            if (routesInFile.some((r) => r.tags.includes("db"))) {
+                if (!affectedModels.includes(schema.name)) {
+                    affectedModels.push(schema.name);
+                }
+                break;
+            }
+        }
+    }
+    // Find affected middleware
+    const affectedMiddleware = middleware
+        .filter((m) => affected.has(m.file))
+        .map((m) => m.name);
+    return {
+        file: filePath,
+        affectedFiles: Array.from(affected).filter((f) => f !== filePath),
+        affectedRoutes,
+        affectedModels,
+        affectedMiddleware,
+        depth: maxDepth,
+    };
+}
+/**
+ * Multi-file blast radius: given a list of changed files (e.g., from git diff),
+ * find the combined blast radius.
+ */
+export function analyzeMultiFileBlastRadius(files, result, maxDepth = 3) {
+    const combined = new Set();
+    const combinedRoutes = [];
+    const combinedModels = new Set();
+    const combinedMiddleware = new Set();
+    for (const file of files) {
+        const br = analyzeBlastRadius(file, result, maxDepth);
+        for (const f of br.affectedFiles)
+            combined.add(f);
+        for (const r of br.affectedRoutes) {
+            if (!combinedRoutes.some((cr) => cr.path === r.path && cr.method === r.method)) {
+                combinedRoutes.push(r);
+            }
+        }
+        for (const m of br.affectedModels)
+            combinedModels.add(m);
+        for (const mw of br.affectedMiddleware)
+            combinedMiddleware.add(mw);
+    }
+    // Remove the input files from affected
+    for (const file of files)
+        combined.delete(file);
+    return {
+        file: files.join(", "),
+        affectedFiles: Array.from(combined),
+        affectedRoutes: combinedRoutes,
+        affectedModels: Array.from(combinedModels),
+        affectedMiddleware: Array.from(combinedMiddleware),
+        depth: maxDepth,
+    };
+}

package/dist/generators/ai-config.d.ts

@@ -1,2 +1,7 @@
 import type { ScanResult } from "../types.js";
 export declare function generateAIConfigs(result: ScanResult, root: string): Promise<string[]>;
+/**
+ * Generate a profile-specific config file optimized for a particular AI tool.
+ * Includes tool-specific instructions on how to use codesight outputs.
+ */
+export declare function generateProfileConfig(result: ScanResult, root: string, profile: string): Promise<string>;

package/dist/generators/ai-config.js

@@ -135,3 +135,100 @@ ${context}
     }
     return generated;
 }
+/**
+ * Generate a profile-specific config file optimized for a particular AI tool.
+ * Includes tool-specific instructions on how to use codesight outputs.
+ */
+export async function generateProfileConfig(result, root, profile) {
+    const { project, routes, schemas, graph, config } = result;
+    // Build a compact always-load summary (~1-2k tokens)
+    const summaryLines = [];
+    summaryLines.push(`# ${project.name} — Project Context\n`);
+    summaryLines.push(`**Stack:** ${project.frameworks.join(", ") || "generic"} | ${project.orms.join(", ") || "none"} | ${project.language}`);
+    if (project.isMonorepo) {
+        summaryLines.push(`**Monorepo:** ${project.workspaces.map((w) => w.name).join(", ")}`);
+    }
+    summaryLines.push(`\n${routes.length} routes | ${schemas.length} models | ${config.envVars.length} env vars | ${graph.edges.length} import links\n`);
+    // Top entry points
+    if (routes.length > 0) {
+        const areas = [...new Set(routes.map((r) => r.path.split("/").slice(0, 3).join("/")))].slice(0, 10);
+        summaryLines.push(`**API areas:** ${areas.join(", ")}`);
+    }
+    // High-impact files
+    if (graph.hotFiles.length > 0) {
+        summaryLines.push(`\n**High-impact files** (change carefully):`);
+        for (const hf of graph.hotFiles.slice(0, 5)) {
+            summaryLines.push(`- ${hf.file} (imported by ${hf.importedBy} files)`);
+        }
+    }
+    // Required env
+    const required = config.envVars.filter((e) => !e.hasDefault);
+    if (required.length > 0) {
+        summaryLines.push(`\n**Required env vars:** ${required.map((e) => e.name).join(", ")}`);
+    }
+    summaryLines.push(`\n---\n`);
+    // Profile-specific instructions
+    switch (profile) {
+        case "claude-code": {
+            summaryLines.push(`## Instructions for Claude Code\n`);
+            summaryLines.push(`Before exploring the repo, read these files in order:`);
+            summaryLines.push(`1. \`.codesight/CODESIGHT.md\` — full context map (routes, schema, components, deps)`);
+            summaryLines.push(`2. Use the codesight MCP server for targeted queries:\n`);
+            summaryLines.push(`   - \`codesight_get_summary\` — quick project overview`);
+            summaryLines.push(`   - \`codesight_get_routes --prefix /api/users\` — filtered routes`);
+            summaryLines.push(`   - \`codesight_get_blast_radius --file src/lib/db.ts\` — impact analysis before changes`);
+            summaryLines.push(`   - \`codesight_get_schema --model users\` — specific model details`);
+            summaryLines.push(`\nOnly open specific files after consulting codesight context. This saves ~${result.tokenStats.saved.toLocaleString()} tokens per conversation.`);
+            const outPath = join(root, "CLAUDE.md");
+            const existing = await fileExists(outPath) ? await readFile(outPath, "utf-8") : "";
+            if (existing && existing.includes("codesight")) {
+                await writeFile(outPath, existing.replace(/# AI Context.*?(?=\n#|\n$|$)/s, summaryLines.join("\n")));
+            }
+            else if (existing) {
+                await writeFile(outPath, existing + "\n\n" + summaryLines.join("\n"));
+            }
+            else {
+                await writeFile(outPath, summaryLines.join("\n"));
+            }
+            return "CLAUDE.md";
+        }
+        case "cursor": {
+            summaryLines.push(`## Instructions for Cursor\n`);
+            summaryLines.push(`When answering questions about this project:`);
+            summaryLines.push(`1. Read \`.codesight/CODESIGHT.md\` first for full project structure`);
+            summaryLines.push(`2. Use \`.codesight/routes.md\` to find relevant API handlers`);
+            summaryLines.push(`3. Use \`.codesight/schema.md\` to understand data models`);
+            summaryLines.push(`4. Use \`.codesight/graph.md\` to check blast radius before changes`);
+            summaryLines.push(`\nDo not crawl the file tree — the codesight context map already contains the full project structure.`);
+            await writeFile(join(root, ".cursorrules"), summaryLines.join("\n"));
+            return ".cursorrules";
+        }
+        case "codex": {
+            summaryLines.push(`## Instructions for OpenAI Codex\n`);
+            summaryLines.push(`This project uses codesight for structured context. Read .codesight/CODESIGHT.md before exploring files.`);
+            summaryLines.push(`Routes: .codesight/routes.md | Schema: .codesight/schema.md | Dependencies: .codesight/graph.md`);
+            await writeFile(join(root, "codex.md"), summaryLines.join("\n"));
+            return "codex.md";
+        }
+        case "copilot": {
+            summaryLines.push(`## Instructions for GitHub Copilot\n`);
+            summaryLines.push(`Project context is pre-generated in .codesight/. Consult CODESIGHT.md for full architecture.`);
+            const ghDir = join(root, ".github");
+            await fileExists(ghDir) || await (await import("node:fs/promises")).mkdir(ghDir, { recursive: true });
+            await writeFile(join(ghDir, "copilot-instructions.md"), summaryLines.join("\n"));
+            return ".github/copilot-instructions.md";
+        }
+        case "windsurf": {
+            summaryLines.push(`## Instructions for Windsurf\n`);
+            summaryLines.push(`Read .codesight/CODESIGHT.md for full project map before exploring files.`);
+            summaryLines.push(`Use .codesight/routes.md for API structure and .codesight/graph.md for dependency analysis.`);
+            await writeFile(join(root, ".windsurfrules"), summaryLines.join("\n"));
+            return ".windsurfrules";
+        }
+        default: {
+            // Generic profile — write all configs
+            const generated = await generateAIConfigs(result, root);
+            return generated.join(", ") || "all configs already exist";
+        }
+    }
+}

package/dist/index.js

@@ -14,7 +14,7 @@ import { calculateTokenStats } from "./detectors/tokens.js";
 import { writeOutput } from "./formatter.js";
 import { generateAIConfigs } from "./generators/ai-config.js";
 import { generateHtmlReport } from "./generators/html-report.js";
-const VERSION = "1.1.0";
+const VERSION = "1.2.0";
 const BRAND = "codesight";
 function printHelp() {
     console.log(`
@@ -33,6 +33,8 @@ function printHelp() {
     --mcp                Start as MCP server (for Claude Code, Cursor)
     --json               Output JSON instead of markdown
     --benchmark          Show detailed token savings breakdown
+    --profile <tool>     Generate optimized config (claude-code|cursor|codex|copilot|windsurf)
+    --blast <file>       Show blast radius for a file
     -v, --version        Show version
     -h, --help           Show this help
 
@@ -220,6 +222,8 @@ async function main() {
     let doOpen = false;
     let doMcp = false;
     let doBenchmark = false;
+    let doProfile = "";
+    let doBlast = "";
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if ((arg === "-o" || arg === "--output") && args[i + 1]) {
@@ -253,6 +257,12 @@ async function main() {
         else if (arg === "--benchmark") {
             doBenchmark = true;
         }
+        else if (arg === "--profile" && args[i + 1]) {
+            doProfile = args[++i];
+        }
+        else if (arg === "--blast" && args[i + 1]) {
+            doBlast = args[++i];
+        }
         else if (!arg.startsWith("-")) {
             targetDir = resolve(arg);
         }
@@ -329,6 +339,44 @@ async function main() {
   - 1.3x multiplier: AI revisits files during multi-turn exploration
 `);
     }
+    // Blast radius analysis
+    if (doBlast) {
+        const { analyzeBlastRadius } = await import("./detectors/blast-radius.js");
+        const br = analyzeBlastRadius(doBlast, result);
+        console.log(`\n  Blast Radius: ${doBlast}`);
+        console.log(`  Depth: ${br.depth} hops\n`);
+        if (br.affectedFiles.length > 0) {
+            console.log(`  Affected files (${br.affectedFiles.length}):`);
+            for (const f of br.affectedFiles.slice(0, 20)) {
+                console.log(`    ${f}`);
+            }
+            if (br.affectedFiles.length > 20)
+                console.log(`    ... +${br.affectedFiles.length - 20} more`);
+        }
+        if (br.affectedRoutes.length > 0) {
+            console.log(`\n  Affected routes (${br.affectedRoutes.length}):`);
+            for (const r of br.affectedRoutes) {
+                console.log(`    ${r.method} ${r.path} — ${r.file}`);
+            }
+        }
+        if (br.affectedModels.length > 0) {
+            console.log(`\n  Affected models: ${br.affectedModels.join(", ")}`);
+        }
+        if (br.affectedMiddleware.length > 0) {
+            console.log(`\n  Affected middleware: ${br.affectedMiddleware.join(", ")}`);
+        }
+        if (br.affectedFiles.length === 0) {
+            console.log("  No downstream dependencies. Minimal blast radius.");
+        }
+        console.log("");
+    }
+    // Profile-based AI config generation
+    if (doProfile) {
+        const { generateProfileConfig } = await import("./generators/ai-config.js");
+        process.stdout.write(`  Generating ${doProfile} profile...`);
+        const file = await generateProfileConfig(result, root, doProfile);
+        console.log(` ${file}`);
+    }
     // Watch mode (blocks)
     if (doWatch) {
         await watchMode(root, outputDirName, maxDepth);

package/dist/mcp-server.js

@@ -10,13 +10,20 @@ import { detectDependencyGraph } from "./detectors/graph.js";
 import { enrichRouteContracts } from "./detectors/contracts.js";
 import { calculateTokenStats } from "./detectors/tokens.js";
 import { writeOutput } from "./formatter.js";
+import { analyzeBlastRadius, analyzeMultiFileBlastRadius } from "./detectors/blast-radius.js";
 function send(msg) {
     const json = JSON.stringify(msg);
     const header = `Content-Length: ${Buffer.byteLength(json)}\r\n\r\n`;
     process.stdout.write(header + json);
 }
-async function runScan(directory) {
+// Cache scan results for the session to avoid re-scanning
+let cachedResult = null;
+let cachedRoot = null;
+async function getScanResult(directory) {
     const root = resolve(directory || process.cwd());
+    // Return cached if same directory
+    if (cachedResult && cachedRoot === root)
+        return cachedResult;
     const project = await detectProject(root);
     const files = await collectFiles(root, 10);
     const [rawRoutes, schemas, components, libs, config, middleware, graph] = await Promise.all([
@@ -42,10 +49,277 @@ async function runScan(directory) {
     };
     const outputContent = await writeOutput(tempResult, resolve(root, ".codesight"));
     const tokenStats = calculateTokenStats(tempResult, outputContent, files.length);
-    return outputContent.replace(/Saves ~\d[\d,]* tokens/, `Saves ~${tokenStats.saved.toLocaleString()} tokens`);
+    cachedResult = { ...tempResult, tokenStats };
+    cachedRoot = root;
+    return cachedResult;
 }
+// =================== TOOL IMPLEMENTATIONS ===================
+async function toolScan(args) {
+    const result = await getScanResult(args.directory);
+    const outputContent = await writeOutput(result, resolve(cachedRoot, ".codesight"));
+    return outputContent.replace(/Saves ~\d[\d,]* tokens/, `Saves ~${result.tokenStats.saved.toLocaleString()} tokens`);
+}
+async function toolGetRoutes(args) {
+    const result = await getScanResult(args.directory);
+    let routes = result.routes;
+    // Filter by prefix
+    if (args.prefix) {
+        routes = routes.filter((r) => r.path.startsWith(args.prefix));
+    }
+    // Filter by tag
+    if (args.tag) {
+        routes = routes.filter((r) => r.tags.includes(args.tag));
+    }
+    // Filter by method
+    if (args.method) {
+        routes = routes.filter((r) => r.method === args.method.toUpperCase());
+    }
+    const lines = routes.map((r) => {
+        const tags = r.tags.length > 0 ? ` [${r.tags.join(", ")}]` : "";
+        const params = r.params ? ` params(${r.params.join(", ")})` : "";
+        return `${r.method} ${r.path}${params}${tags} — ${r.file}`;
+    });
+    return lines.length > 0
+        ? `${lines.length} routes:\n${lines.join("\n")}`
+        : "No routes found matching filters.";
+}
+async function toolGetSchema(args) {
+    const result = await getScanResult(args.directory);
+    let models = result.schemas;
+    if (args.model) {
+        models = models.filter((m) => m.name.toLowerCase().includes(args.model.toLowerCase()));
+    }
+    const lines = [];
+    for (const model of models) {
+        lines.push(`### ${model.name} (${model.orm})`);
+        for (const field of model.fields) {
+            const flags = field.flags.length > 0 ? ` (${field.flags.join(", ")})` : "";
+            lines.push(`  ${field.name}: ${field.type}${flags}`);
+        }
+        if (model.relations.length > 0) {
+            lines.push(`  relations: ${model.relations.join(", ")}`);
+        }
+        lines.push("");
+    }
+    return lines.length > 0
+        ? `${models.length} models:\n${lines.join("\n")}`
+        : "No models found.";
+}
+async function toolGetBlastRadius(args) {
+    const result = await getScanResult(args.directory);
+    const maxDepth = args.depth || 3;
+    let br;
+    if (args.files && Array.isArray(args.files)) {
+        br = analyzeMultiFileBlastRadius(args.files, result, maxDepth);
+    }
+    else if (args.file) {
+        br = analyzeBlastRadius(args.file, result, maxDepth);
+    }
+    else {
+        return "Error: provide 'file' (string) or 'files' (array) parameter.";
+    }
+    const lines = [];
+    lines.push(`## Blast Radius for ${br.file}`);
+    lines.push(`Depth: ${br.depth} hops\n`);
+    if (br.affectedFiles.length > 0) {
+        lines.push(`### Affected Files (${br.affectedFiles.length})`);
+        for (const f of br.affectedFiles.slice(0, 30)) {
+            lines.push(`- ${f}`);
+        }
+        if (br.affectedFiles.length > 30) {
+            lines.push(`- ... +${br.affectedFiles.length - 30} more`);
+        }
+        lines.push("");
+    }
+    if (br.affectedRoutes.length > 0) {
+        lines.push(`### Affected Routes (${br.affectedRoutes.length})`);
+        for (const r of br.affectedRoutes) {
+            lines.push(`- ${r.method} ${r.path} — ${r.file}`);
+        }
+        lines.push("");
+    }
+    if (br.affectedModels.length > 0) {
+        lines.push(`### Potentially Affected Models (${br.affectedModels.length})`);
+        for (const m of br.affectedModels) {
+            lines.push(`- ${m}`);
+        }
+        lines.push("");
+    }
+    if (br.affectedMiddleware.length > 0) {
+        lines.push(`### Affected Middleware (${br.affectedMiddleware.length})`);
+        for (const m of br.affectedMiddleware) {
+            lines.push(`- ${m}`);
+        }
+        lines.push("");
+    }
+    if (br.affectedFiles.length === 0 && br.affectedRoutes.length === 0) {
+        lines.push("No downstream dependencies found. This file change has minimal blast radius.");
+    }
+    return lines.join("\n");
+}
+async function toolGetEnv(args) {
+    const result = await getScanResult(args.directory);
+    const envVars = result.config.envVars;
+    if (args.required_only) {
+        const required = envVars.filter((e) => !e.hasDefault);
+        const lines = required.map((e) => `${e.name} **required** — ${e.source}`);
+        return `${required.length} required env vars (no defaults):\n${lines.join("\n")}`;
+    }
+    const lines = envVars.map((e) => {
+        const status = e.hasDefault ? "(has default)" : "**required**";
+        return `${e.name} ${status} — ${e.source}`;
+    });
+    return `${envVars.length} env vars:\n${lines.join("\n")}`;
+}
+async function toolGetHotFiles(args) {
+    const result = await getScanResult(args.directory);
+    const limit = args.limit || 15;
+    const hotFiles = result.graph.hotFiles.slice(0, limit);
+    if (hotFiles.length === 0)
+        return "No import graph data. Run a full scan first.";
+    const lines = hotFiles.map((h) => `${h.file} — imported by ${h.importedBy} files`);
+    return `Top ${hotFiles.length} most-imported files (change carefully):\n${lines.join("\n")}`;
+}
+async function toolGetSummary(args) {
+    const result = await getScanResult(args.directory);
+    const { project, routes, schemas, components, config, middleware, graph, tokenStats } = result;
+    const fw = project.frameworks.join(", ") || "generic";
+    const orm = project.orms.join(", ") || "none";
+    const lines = [];
+    lines.push(`# ${project.name}`);
+    lines.push(`Stack: ${fw} | ${orm} | ${project.componentFramework} | ${project.language}`);
+    if (project.isMonorepo) {
+        lines.push(`Monorepo: ${project.workspaces.map((w) => w.name).join(", ")}`);
+    }
+    lines.push("");
+    lines.push(`${routes.length} routes | ${schemas.length} models | ${components.length} components | ${config.envVars.length} env vars | ${middleware.length} middleware | ${graph.edges.length} import links`);
+    lines.push(`Token savings: ~${tokenStats.saved.toLocaleString()} per conversation`);
+    lines.push("");
+    // Top routes summary
+    if (routes.length > 0) {
+        lines.push(`Key API areas: ${[...new Set(routes.map((r) => r.path.split("/").slice(0, 3).join("/")))].slice(0, 8).join(", ")}`);
+    }
+    // Hot files
+    if (graph.hotFiles.length > 0) {
+        lines.push(`High-impact files: ${graph.hotFiles.slice(0, 5).map((h) => h.file).join(", ")}`);
+    }
+    // Required env
+    const required = config.envVars.filter((e) => !e.hasDefault);
+    if (required.length > 0) {
+        lines.push(`Required env: ${required.slice(0, 8).map((e) => e.name).join(", ")}${required.length > 8 ? ` +${required.length - 8} more` : ""}`);
+    }
+    lines.push("");
+    lines.push("Use codesight_get_routes, codesight_get_schema, codesight_get_blast_radius for details.");
+    return lines.join("\n");
+}
+async function toolRefresh(args) {
+    cachedResult = null;
+    cachedRoot = null;
+    const result = await getScanResult(args.directory);
+    return `Refreshed. ${result.routes.length} routes, ${result.schemas.length} models, ${result.graph.edges.length} import links, ${result.config.envVars.length} env vars.`;
+}
+// =================== TOOL DEFINITIONS ===================
+const TOOLS = [
+    {
+        name: "codesight_scan",
+        description: "Full codebase scan. Returns complete AI context map with routes, schema, components, libraries, config, middleware, and dependency graph. Use this for initial project understanding.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                directory: { type: "string", description: "Directory to scan (defaults to cwd)" },
+            },
+        },
+        handler: toolScan,
+    },
+    {
+        name: "codesight_get_summary",
+        description: "Compact project summary (~500 tokens). Stack, key stats, high-impact files, required env vars. Use this first before diving deeper.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                directory: { type: "string", description: "Directory (defaults to cwd)" },
+            },
+        },
+        handler: toolGetSummary,
+    },
+    {
+        name: "codesight_get_routes",
+        description: "Get API routes with methods, paths, params, tags, and handler files. Supports filtering by prefix, tag, or HTTP method.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                directory: { type: "string", description: "Directory (defaults to cwd)" },
+                prefix: { type: "string", description: "Filter routes by path prefix (e.g., '/api/users')" },
+                tag: { type: "string", description: "Filter routes by tag (e.g., 'auth', 'db', 'payment', 'ai')" },
+                method: { type: "string", description: "Filter by HTTP method (e.g., 'GET', 'POST')" },
+            },
+        },
+        handler: toolGetRoutes,
+    },
+    {
+        name: "codesight_get_schema",
+        description: "Get database models with fields, types, constraints, and relations. Optionally filter by model name.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                directory: { type: "string", description: "Directory (defaults to cwd)" },
+                model: { type: "string", description: "Filter by model name (partial match)" },
+            },
+        },
+        handler: toolGetSchema,
+    },
+    {
+        name: "codesight_get_blast_radius",
+        description: "Blast radius analysis. Given a file (or list of files), returns all transitively affected files, routes, models, and middleware. Use before making changes to understand impact.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                directory: { type: "string", description: "Directory (defaults to cwd)" },
+                file: { type: "string", description: "Single file path (relative to project root)" },
+                files: { type: "array", items: { type: "string" }, description: "Multiple file paths for combined blast radius" },
+                depth: { type: "number", description: "Max traversal depth (default: 3)" },
+            },
+        },
+        handler: toolGetBlastRadius,
+    },
+    {
+        name: "codesight_get_env",
+        description: "Get environment variables across the codebase with required/default status and source file.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                directory: { type: "string", description: "Directory (defaults to cwd)" },
+                required_only: { type: "boolean", description: "Only show required vars (no defaults)" },
+            },
+        },
+        handler: toolGetEnv,
+    },
+    {
+        name: "codesight_get_hot_files",
+        description: "Get the most-imported files in the project. These have the highest blast radius — changes here affect the most other files.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                directory: { type: "string", description: "Directory (defaults to cwd)" },
+                limit: { type: "number", description: "Number of files to return (default: 15)" },
+            },
+        },
+        handler: toolGetHotFiles,
+    },
+    {
+        name: "codesight_refresh",
+        description: "Force re-scan the project. Use after making significant changes to get updated context.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                directory: { type: "string", description: "Directory (defaults to cwd)" },
+            },
+        },
+        handler: toolRefresh,
+    },
+];
+// =================== MCP PROTOCOL ===================
 async function handleRequest(req) {
-    // MCP initialize
     if (req.method === "initialize") {
         send({
             jsonrpc: "2.0",
@@ -53,47 +327,35 @@ async function handleRequest(req) {
             result: {
                 protocolVersion: "2024-11-05",
                 capabilities: { tools: {} },
-                serverInfo: { name: "codesight", version: "1.0.0" },
+                serverInfo: { name: "codesight", version: "1.2.0" },
             },
         });
         return;
     }
-    // MCP initialized notification
     if (req.method === "notifications/initialized") {
-        return; // no response for notifications
+        return;
     }
-    // List tools
     if (req.method === "tools/list") {
         send({
             jsonrpc: "2.0",
             id: req.id ?? null,
             result: {
-                tools: [
-                    {
-                        name: "codesight_scan",
-                        description: "Scans a codebase and returns a complete AI context map including routes, database schema, components, libraries, config, middleware, and dependency graph. Saves thousands of tokens vs manual exploration.",
-                        inputSchema: {
-                            type: "object",
-                            properties: {
-                                directory: {
-                                    type: "string",
-                                    description: "Directory to scan (defaults to current working directory)",
-                                },
-                            },
-                        },
-                    },
-                ],
+                tools: TOOLS.map(({ name, description, inputSchema }) => ({
+                    name,
+                    description,
+                    inputSchema,
+                })),
             },
         });
         return;
     }
-    // Call tool
     if (req.method === "tools/call") {
         const toolName = req.params?.name;
         const args = req.params?.arguments || {};
-        if (toolName === "codesight_scan") {
+        const tool = TOOLS.find((t) => t.name === toolName);
+        if (tool) {
             try {
-                const result = await runScan(args.directory || process.cwd());
+                const result = await tool.handler(args);
                 send({
                     jsonrpc: "2.0",
                     id: req.id ?? null,
@@ -107,7 +369,7 @@ async function handleRequest(req) {
                     jsonrpc: "2.0",
                     id: req.id ?? null,
                     result: {
-                        content: [{ type: "text", text: `Error scanning: ${err.message}` }],
+                        content: [{ type: "text", text: `Error: ${err.message}` }],
                         isError: true,
                     },
                 });
@@ -121,7 +383,6 @@ async function handleRequest(req) {
         });
         return;
     }
-    // Unknown method
     if (req.id !== undefined) {
         send({
             jsonrpc: "2.0",
@@ -131,13 +392,11 @@ async function handleRequest(req) {
     }
 }
 export async function startMCPServer() {
-    // Read Content-Length delimited JSON-RPC messages from stdin
     let buffer = "";
     process.stdin.setEncoding("utf-8");
     process.stdin.on("data", async (chunk) => {
         buffer += chunk;
         while (true) {
-            // Parse Content-Length header
             const headerEnd = buffer.indexOf("\r\n\r\n");
             if (headerEnd === -1)
                 break;
@@ -166,6 +425,5 @@ export async function startMCPServer() {
             }
         }
     });
-    // Keep alive
     await new Promise(() => { });
 }

package/dist/types.d.ts

@@ -81,6 +81,22 @@ export interface DependencyGraph {
         importedBy: number;
     }[];
 }
+export interface BlastRadiusResult {
+    file: string;
+    affectedFiles: string[];
+    affectedRoutes: RouteInfo[];
+    affectedModels: string[];
+    affectedMiddleware: string[];
+    depth: number;
+}
+export interface CodesightConfig {
+    disableDetectors?: string[];
+    customTags?: Record<string, string[]>;
+    maxDepth?: number;
+    outputDir?: string;
+    profile?: "claude-code" | "cursor" | "codex" | "copilot" | "windsurf" | "generic";
+    ignorePatterns?: string[];
+}
 export interface ScanResult {
     project: ProjectInfo;
     routes: RouteInfo[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codesight",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "See your codebase clearly. Universal AI context generator that maps routes, schema, components, dependencies, and more for Claude Code, Cursor, Copilot, Codex, and any AI coding tool.",
   "main": "dist/index.js",
   "bin": {