carto-md 1.0.3 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carto-md",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "The context layer for AI-native development.",
   "bin": {
     "carto": "src/cli/index.js"

package/src/agents/formatter.js

@@ -1,3 +1,5 @@
+const path = require('path');
+
 /**
  * Converts extracted data into markdown sections for AGENTS.md.
  *
@@ -13,7 +15,7 @@
  *   9. Frontend API Calls (auto)
  *   10. Frontend Storage Keys (auto)
  */
-function formatSections({ routes, models, frontend, structure, warnings, fileMap, functions, dbTables, envVars, importGraph }) {
+function formatSections({ routes, models, frontend, structure, warnings, fileMap, functions, dbTables, envVars, importGraph, stackItems, entryPoints, highImpact }) {
   const sections = [];
 
   // 1. Project Structure
@@ -28,6 +30,22 @@ function formatSections({ routes, models, frontend, structure, warnings, fileMap
     sections.push('_No structure data available._');
   }
 
+  // Stack line — right after structure
+  if (stackItems && stackItems.length > 0) {
+    sections.push(`\n**Stack:** ${stackItems.join(', ')}`);
+  }
+
+  // Entry points
+  if (entryPoints && entryPoints.length > 0) {
+    sections.push(`**Entry points:** ${entryPoints.join(', ')}`);
+  }
+
+  // High impact files
+  if (highImpact && highImpact.length > 0) {
+    const items = highImpact.map(h => `${h.file} (${h.count} dependents)`);
+    sections.push(`**High impact:** ${items.join(', ')}`);
+  }
+
   // 2. File Map
   sections.push('\n## File Map (auto)\n');
   if (fileMap && fileMap.length > 0) {

package/src/agents/validator.js

@@ -14,7 +14,7 @@ function validateExtracted({ routes, models, functions, envVars, dbTables }) {
   };
 }
 
-const VALID_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']);
+const VALID_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS', 'ALL']);
 const VALID_HANDLER = /^[a-zA-Z_]\w*$|^\[anonymous\]$/;
 const VALID_CLASS_NAME = /^[A-Z][a-zA-Z0-9]*$/;
 const VALID_FIELD_NAME = /^[a-z_]\w*$/;

package/src/cli/init.js

@@ -12,7 +12,7 @@ async function run(projectRoot) {
   console.log(`[CARTO] Detected: ${detection.framework} (${detection.language})`);
 
   const isIgnored = parseCartoIgnore(projectRoot);
-  const files = discoverFiles(projectRoot, detection.framework, isIgnored);
+  const files = discoverFiles(projectRoot, detection.framework, isIgnored, detection.secondaryFramework);
 
   // Count files for reporting
   const pyCount = files.routeFiles.filter(f => f.endsWith('.py')).length;
@@ -55,11 +55,14 @@ async function run(projectRoot) {
     'utf-8'
   );
 
+  // Install pre-commit hook
+  installGitHook(projectRoot);
+
   // Run first sync
   const syncConfig = resolveConfig(projectRoot, config);
   await runFullSync(syncConfig);
 
-  console.log('[CARTO] AGENTS.md generated. Run "carto watch" to keep it live.');
+  console.log('[CARTO] AGENTS.md generated. Carto will sync on every git commit.');
 }
 
 /**
@@ -77,4 +80,29 @@ function resolveConfig(projectRoot, config) {
   };
 }
 
+function installGitHook(projectRoot) {
+  const gitDir = path.join(projectRoot, '.git');
+  if (!fs.existsSync(gitDir)) return;
+
+  const hooksDir = path.join(gitDir, 'hooks');
+  if (!fs.existsSync(hooksDir)) fs.mkdirSync(hooksDir, { recursive: true });
+
+  const hookPath = path.join(hooksDir, 'pre-commit');
+  const hookLine = 'carto sync\n';
+
+  if (fs.existsSync(hookPath)) {
+    const existing = fs.readFileSync(hookPath, 'utf-8');
+    if (existing.includes('carto sync')) {
+      console.log('[CARTO] Git hook already installed.');
+      return;
+    }
+    fs.appendFileSync(hookPath, '\n' + hookLine);
+  } else {
+    fs.writeFileSync(hookPath, '#!/bin/sh\n' + hookLine);
+  }
+
+  fs.chmodSync(hookPath, '755');
+  console.log('[CARTO] Git pre-commit hook installed.');
+}
+
 module.exports = { run, resolveConfig };

package/src/detector/files.js

@@ -4,17 +4,38 @@ const path = require('path');
 const MAX_FILES_PER_CATEGORY = 50;
 
 const PYTHON_IGNORE = new Set(['__pycache__', '.venv', 'venv', 'migrations', 'node_modules', '.git', '.carto']);
-const JS_IGNORE = new Set(['node_modules', '.git', 'dist', 'build', '.carto']);
+const JS_IGNORE = new Set(['node_modules', '.git', 'dist', 'build', '.carto', '.next', '.turbo', 'coverage', 'out', '.cache', 'generated', '__generated__', 'storybook-static', 'public', 'static']);
 const HTML_IGNORE = new Set(['node_modules', '.git', '.carto']);
 
 /**
- * discoverFiles(projectRoot, framework, isIgnored) → { routeFiles, modelFiles, frontendFiles }
+ * discoverFiles(projectRoot, framework, isIgnored, secondaryFramework) → { routeFiles, modelFiles, frontendFiles }
  *
  * isIgnored is an optional function (filePath) → boolean from the .cartoignore parser.
+ * If secondaryFramework is provided, discovers files for both and merges.
  */
-function discoverFiles(projectRoot, framework, isIgnored) {
+function discoverFiles(projectRoot, framework, isIgnored, secondaryFramework) {
   const ignoreFn = isIgnored || (() => false);
 
+  const primary = discoverForFramework(projectRoot, framework, ignoreFn);
+
+  if (secondaryFramework) {
+    const secondary = discoverForFramework(projectRoot, secondaryFramework, ignoreFn);
+    // Merge and deduplicate
+    const routeFiles = [...new Set([...primary.routeFiles, ...secondary.routeFiles])];
+    const modelFiles = [...new Set([...primary.modelFiles, ...secondary.modelFiles])];
+    const frontendFiles = [...new Set([...primary.frontendFiles, ...secondary.frontendFiles])];
+    return {
+      routeFiles: cap(routeFiles),
+      modelFiles: cap(modelFiles),
+      frontendFiles: cap(frontendFiles)
+    };
+  }
+
+  return primary;
+}
+
+function discoverForFramework(projectRoot, framework, ignoreFn) {
+
   if (['fastapi', 'django', 'flask', 'python-generic'].includes(framework)) {
     const pyFiles = findFilesRecursive(projectRoot, ['.py'], PYTHON_IGNORE, ignoreFn)
       .filter(f => {
@@ -81,12 +102,27 @@ function findFilesRecursive(dir, extensions, ignoreDirs, isIgnored, results = []
   return results;
 }
 
+function scoreFile(filePath) {
+  const p = filePath.toLowerCase().replace(/\\/g, '/');
+  const base = path.basename(p);
+  if (base === 'main.py' || base === 'app.py' || base === 'server.ts' ||
+      base === 'server.js' || base === 'app.ts' || base === 'index.ts' ||
+      base === 'route.ts' || base === 'routes.ts' || base === 'routes.js') return 10;
+  if (p.includes('/api/') || p.includes('/routes/') || p.includes('/route/')) return 9;
+  if (p.includes('/models/') || p.includes('/schemas/') || p.includes('/schema/')) return 8;
+  if (p.includes('/services/') || p.includes('/controllers/') || p.includes('/handlers/')) return 6;
+  if (p.includes('/lib/') || p.includes('/utils/') || p.includes('/helpers/')) return 2;
+  return 4;
+}
+
 function cap(files) {
-  if (files.length > MAX_FILES_PER_CATEGORY) {
-    console.warn(`[CARTO] Warning: Found ${files.length} files, capping at ${MAX_FILES_PER_CATEGORY}`);
-    return files.slice(0, MAX_FILES_PER_CATEGORY);
+  const scored = files.map(f => ({ f, score: scoreFile(f) }))
+                      .sort((a, b) => b.score - a.score);
+  if (scored.length > MAX_FILES_PER_CATEGORY) {
+    console.warn(`[CARTO] Warning: Found ${scored.length} files, capping at ${MAX_FILES_PER_CATEGORY}`);
+    return scored.slice(0, MAX_FILES_PER_CATEGORY).map(x => x.f);
   }
-  return files;
+  return scored.map(x => x.f);
 }
 
 module.exports = { discoverFiles };

package/src/detector/framework.js

@@ -3,40 +3,64 @@ const path = require('path');
 
 const IGNORE_DIRS = new Set(['node_modules', '.git', '__pycache__', '.venv', 'venv', '.idea', '.vscode', '.carto']);
 
+// Priority order: lower index = higher priority
+const PYTHON_PRIORITY = ['fastapi', 'django', 'flask', 'python-generic'];
+const JS_PRIORITY = ['nextjs', 'express', 'react', 'node-generic'];
+
 /**
- * detectFramework(projectRoot) → { framework, language, confidence }
- *
- * Search order (recursive up to 3 levels deep):
- * 1. requirements.txt → fastapi / django / flask / python-generic
- * 2. package.json → nextjs / express / react / node-generic
- * 3. pyproject.toml → same logic as requirements.txt
- * 4. Nothing found → { framework: 'unknown', language: 'unknown' }
+ * detectFramework(projectRoot) → { framework, language, confidence, secondaryFramework?, secondaryLanguage? }
  *
- * Returns first match found. Does not combine multiple detections.
+ * Collects all matches from requirements.txt, package.json, pyproject.toml.
+ * Picks the most specific Python and JS framework by priority.
+ * If both a Python and JS framework are detected, returns both
+ * (primary = highest priority overall, secondary = the other language).
  */
 function detectFramework(projectRoot) {
-  // Search for files up to 3 levels deep
   const candidates = findFile(projectRoot, ['requirements.txt', 'package.json', 'pyproject.toml'], 3);
 
-  // 1. Check requirements.txt
-  const reqFile = candidates.find(f => path.basename(f) === 'requirements.txt');
-  if (reqFile) {
-    const result = detectFromPythonDeps(reqFile);
-    if (result) return result;
+  const pythonDetections = new Set();
+  const jsDetections = new Set();
+
+  // Check requirements.txt
+  for (const f of candidates.filter(f => path.basename(f) === 'requirements.txt')) {
+    const results = detectAllFromPythonDeps(f);
+    for (const r of results) pythonDetections.add(r);
   }
 
-  // 2. Check package.json
-  const pkgFile = candidates.find(f => path.basename(f) === 'package.json');
-  if (pkgFile) {
-    const result = detectFromPackageJson(pkgFile);
-    if (result) return result;
+  // Check pyproject.toml
+  for (const f of candidates.filter(f => path.basename(f) === 'pyproject.toml')) {
+    const results = detectAllFromPythonDeps(f);
+    for (const r of results) pythonDetections.add(r);
   }
 
-  // 3. Check pyproject.toml
-  const pyprojectFile = candidates.find(f => path.basename(f) === 'pyproject.toml');
-  if (pyprojectFile) {
-    const result = detectFromPythonDeps(pyprojectFile);
-    if (result) return result;
+  // Check package.json
+  for (const f of candidates.filter(f => path.basename(f) === 'package.json')) {
+    const results = detectAllFromPackageJson(f);
+    for (const r of results) jsDetections.add(r);
+  }
+
+  // Pick best Python framework by priority
+  const bestPython = PYTHON_PRIORITY.find(fw => pythonDetections.has(fw)) || null;
+  // Pick best JS framework by priority
+  const bestJS = JS_PRIORITY.find(fw => jsDetections.has(fw)) || null;
+
+  if (bestPython && bestJS) {
+    // Both detected — Python is primary (higher priority in the global list)
+    return {
+      framework: bestPython,
+      language: 'python',
+      confidence: 'high',
+      secondaryFramework: bestJS,
+      secondaryLanguage: 'javascript'
+    };
+  }
+
+  if (bestPython) {
+    return { framework: bestPython, language: 'python', confidence: 'high' };
+  }
+
+  if (bestJS) {
+    return { framework: bestJS, language: 'javascript', confidence: 'high' };
   }
 
   return { framework: 'unknown', language: 'unknown', confidence: 'none' };
@@ -69,49 +93,46 @@ function findFile(dir, fileNames, maxDepth, currentDepth = 0) {
   return results;
 }
 
-function detectFromPythonDeps(filePath) {
+/**
+ * Returns all matching Python frameworks from a deps file.
+ */
+function detectAllFromPythonDeps(filePath) {
+  const detected = [];
   let content;
   try {
     content = fs.readFileSync(filePath, 'utf-8').toLowerCase();
   } catch {
-    return null;
+    return detected;
   }
 
-  if (content.includes('fastapi')) {
-    return { framework: 'fastapi', language: 'python', confidence: 'high' };
-  }
-  if (content.includes('django')) {
-    return { framework: 'django', language: 'python', confidence: 'high' };
-  }
-  if (content.includes('flask')) {
-    return { framework: 'flask', language: 'python', confidence: 'high' };
-  }
-  if (content.includes('pydantic')) {
-    return { framework: 'python-generic', language: 'python', confidence: 'medium' };
-  }
-  return null;
+  if (content.includes('fastapi')) detected.push('fastapi');
+  if (content.includes('django')) detected.push('django');
+  if (content.includes('flask')) detected.push('flask');
+  if (content.includes('pydantic') && !detected.length) detected.push('python-generic');
+
+  return detected;
 }
 
-function detectFromPackageJson(filePath) {
+/**
+ * Returns all matching JS frameworks from a package.json.
+ */
+function detectAllFromPackageJson(filePath) {
+  const detected = [];
   let pkg;
   try {
     pkg = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
   } catch {
-    return null;
+    return detected;
   }
 
   const deps = Object.assign({}, pkg.dependencies || {}, pkg.devDependencies || {});
 
-  if (deps['next']) {
-    return { framework: 'nextjs', language: 'javascript', confidence: 'high' };
-  }
-  if (deps['express']) {
-    return { framework: 'express', language: 'javascript', confidence: 'high' };
-  }
-  if (deps['react']) {
-    return { framework: 'react', language: 'javascript', confidence: 'high' };
-  }
-  return { framework: 'node-generic', language: 'javascript', confidence: 'medium' };
+  if (deps['next']) detected.push('nextjs');
+  if (deps['express']) detected.push('express');
+  if (deps['react'] && !deps['next']) detected.push('react');
+  if (!detected.length) detected.push('node-generic');
+
+  return detected;
 }
 
 module.exports = { detectFramework };

package/src/extractors/filemap.js

@@ -9,6 +9,15 @@ const path = require('path');
 function inferResponsibility(filename, functionCount, routeCount) {
   const base = path.basename(filename).toLowerCase();
 
+  // Skip barrel exports — index files with no routes and no functions
+  if (
+    (base === 'index.ts' || base === 'index.js' || base === 'index.tsx' || base === 'index.jsx') &&
+    functionCount === 0 &&
+    routeCount === 0
+  ) {
+    return null;
+  }
+
   // Skip __init__.py entirely
   if (base === '__init__.py') return null;
 

package/src/extractors/languages/javascript.js

@@ -73,13 +73,9 @@ function walk(node, visitor) {
 function extractExpressRoutes(ast, filename) {
   const routes = [];
 
-  // Check for Next.js route file pattern
-  const isNextRoute = isNextJSRouteFile(filename);
-
-  if (isNextRoute) {
-    const nextRoutes = extractNextJSRoutes(ast, filename);
-    routes.push(...nextRoutes);
-  }
+  // Check for Next.js Pages/App Router patterns (pages/api/... or app/api/...)
+  const nextRoutes = extractNextJSPagesRoutes(ast, filename);
+  routes.push(...nextRoutes);
 
   walk(ast, (node) => {
     if (node.type !== 'CallExpression') return;
@@ -128,48 +124,72 @@ function extractExpressRoutes(ast, filename) {
     });
   });
 
-  return routes;
-}
-
-function isNextJSRouteFile(filename) {
-  const base = path.basename(filename, path.extname(filename));
-  return (base === 'route' || base === 'Route');
+  // Deduplicate by method + path
+  const seen = new Set();
+  return routes.filter(r => {
+    const key = `${r.method}::${r.path}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
 }
 
-function extractNextJSRoutes(ast, filename) {
+/**
+ * Detects Next.js Pages Router pattern:
+ *   export default function handler(req, res) in files under pages/api/
+ *   Also handles App Router export default in app/api/ files
+ */
+function extractNextJSPagesRoutes(ast, filename) {
   const routes = [];
-  const httpExports = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']);
+  const normalizedPath = ('/' + filename).replace(/\\/g, '/');
+  const isApiFile = normalizedPath.includes('/pages/api/') || normalizedPath.includes('/app/api/');
+
+  if (!isApiFile) return routes;
+  if (!ast.program || !ast.program.body) return routes;
+
+  const HTTP_METHODS_UPPER = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']);
+
+  // Infer route path from filename
+  let routePath = '[inferred]';
+  const pagesMatch = normalizedPath.match(/\/pages(\/api\/.+)/);
+  const appMatch = normalizedPath.match(/\/app(\/api\/.+)/);
+  if (pagesMatch) {
+    routePath = pagesMatch[1].replace(/\/[^/]+$/, '').replace(/\/index$/, '');
+    if (!routePath || routePath === '/api') routePath = '/api';
+  } else if (appMatch) {
+    routePath = appMatch[1].replace(/\/[^/]+$/, '').replace(/\/route$/, '');
+    if (!routePath || routePath === '/api') routePath = '/api';
+  }
 
-  // Infer path from filename: app/api/users/route.js → /api/users
-  // We only have the basename, so we can't infer the full path
-  // This would need the full file path — for now use the filename
-  const routePath = '[inferred]';
+  for (const node of ast.program.body) {
+    // export default function handler(req, res)
+    if (node.type === 'ExportDefaultDeclaration' && node.declaration) {
+      const decl = node.declaration;
+      if (decl.type === 'FunctionDeclaration' || decl.type === 'ArrowFunctionExpression' || decl.type === 'FunctionExpression') {
+        const funcName = (decl.id && decl.id.name) || 'handler';
+        if (HTTP_METHODS_UPPER.has(funcName.toUpperCase())) {
+          routes.push({ method: funcName.toUpperCase(), path: routePath, functionName: funcName });
+        } else {
+          routes.push({ method: 'ALL', path: routePath, functionName: funcName });
+        }
+      }
+    }
 
-  walk(ast, (node) => {
-    // export async function GET(req) { ... }
+    // export function GET/POST/... (named exports in api files)
     if (node.type === 'ExportNamedDeclaration' && node.declaration) {
       const decl = node.declaration;
-      if (decl.type === 'FunctionDeclaration' && decl.id && httpExports.has(decl.id.name)) {
-        routes.push({
-          method: decl.id.name,
-          path: routePath,
-          functionName: decl.id.name
-        });
+      if (decl.type === 'FunctionDeclaration' && decl.id && HTTP_METHODS_UPPER.has(decl.id.name.toUpperCase())) {
+        routes.push({ method: decl.id.name.toUpperCase(), path: routePath, functionName: decl.id.name });
       }
-      // export const GET = async (req) => { ... }
       if (decl.type === 'VariableDeclaration') {
-        for (const declarator of decl.declarations) {
-          if (declarator.id && declarator.id.name && httpExports.has(declarator.id.name)) {
-            routes.push({
-              method: declarator.id.name,
-              path: routePath,
-              functionName: declarator.id.name
-            });
+        for (const vDecl of decl.declarations) {
+          if (vDecl.id && vDecl.id.name && HTTP_METHODS_UPPER.has(vDecl.id.name.toUpperCase())) {
+            routes.push({ method: vDecl.id.name.toUpperCase(), path: routePath, functionName: vDecl.id.name });
           }
         }
       }
     }
-  });
+  }
 
   return routes;
 }

package/src/extractors/languages/typescript.js

@@ -1,4 +1,5 @@
 const parser = require('@babel/parser');
+const path = require('path');
 const jsPlugin = require('./javascript');
 
 const TS_PARSE_OPTIONS = {
@@ -32,6 +33,100 @@ module.exports = {
   }
 };
 
+// ---------------------------------------------------------------------------
+// Next.js Pages Router route detection
+// ---------------------------------------------------------------------------
+
+const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']);
+
+/**
+ * Detects Next.js route patterns:
+ *
+ * Pages Router (pages/api/...):
+ *   export default function handler(req, res) — treated as ALL methods
+ *   export default async function handler(req, res)
+ *
+ * App Router (app/api/.../route.ts):
+ *   export function GET/POST/PUT/DELETE/PATCH
+ *   export async function GET/POST/PUT/DELETE/PATCH
+ *   export const GET/POST = ...
+ */
+function extractNextJSPagesRoutes(ast, filename) {
+  const routes = [];
+  const normalizedPath = ('/' + filename).replace(/\\/g, '/');
+  const isApiFile = normalizedPath.includes('/pages/api/') || normalizedPath.includes('/app/api/');
+
+  if (!isApiFile) return routes;
+  if (!ast.program || !ast.program.body) return routes;
+
+  // Infer route path from filename
+  // pages/api/users/[id].ts → /api/users/[id]
+  // app/api/users/route.ts → /api/users
+  let routePath = '[inferred]';
+  const pagesMatch = normalizedPath.match(/\/pages(\/api\/.+)/);
+  const appMatch = normalizedPath.match(/\/app(\/api\/.+)/);
+  if (pagesMatch) {
+    routePath = pagesMatch[1].replace(/\/[^/]+$/, '').replace(/\/index$/, '');
+    if (!routePath || routePath === '/api') routePath = '/api';
+  } else if (appMatch) {
+    routePath = appMatch[1].replace(/\/[^/]+$/, '').replace(/\/route$/, '');
+    if (!routePath || routePath === '/api') routePath = '/api';
+  }
+
+  for (const node of ast.program.body) {
+    // export default function handler(req, res) — Pages Router pattern
+    if (node.type === 'ExportDefaultDeclaration' && node.declaration) {
+      const decl = node.declaration;
+      if (decl.type === 'FunctionDeclaration' || decl.type === 'ArrowFunctionExpression' || decl.type === 'FunctionExpression') {
+        const funcName = (decl.id && decl.id.name) || 'handler';
+
+        // If the function name is an HTTP method, use it
+        if (HTTP_METHODS.has(funcName.toUpperCase())) {
+          routes.push({
+            method: funcName.toUpperCase(),
+            path: routePath,
+            functionName: funcName
+          });
+        } else {
+          // Pages Router default export — handles all methods
+          routes.push({
+            method: 'ALL',
+            path: routePath,
+            functionName: funcName
+          });
+        }
+      }
+    }
+
+    // export function GET/POST/... or export const GET = ... — App Router pattern
+    if (node.type === 'ExportNamedDeclaration' && node.declaration) {
+      const decl = node.declaration;
+
+      if (decl.type === 'FunctionDeclaration' && decl.id && HTTP_METHODS.has(decl.id.name.toUpperCase())) {
+        routes.push({
+          method: decl.id.name.toUpperCase(),
+          path: routePath,
+          functionName: decl.id.name
+        });
+      }
+
+      if (decl.type === 'VariableDeclaration') {
+        for (const vDecl of decl.declarations) {
+          if (vDecl.id && vDecl.id.name && HTTP_METHODS.has(vDecl.id.name.toUpperCase())) {
+            routes.push({
+              method: vDecl.id.name.toUpperCase(),
+              path: routePath,
+              functionName: vDecl.id.name
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return routes;
+}
+
 // ---------------------------------------------------------------------------
 // AST traversal helper
 // ---------------------------------------------------------------------------

package/src/extractors/stack.js

@@ -0,0 +1,172 @@
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Detects the tech stack from file contents and package manifests.
+ * Scans only files Carto already watches — no new file scanning.
+ * Returns deduplicated array of stack items, max 6.
+ */
+
+// Python: import/from patterns → stack name
+const PYTHON_STACK = {
+  'fastapi': 'FastAPI',
+  'django': 'Django',
+  'flask': 'Flask',
+  'sqlalchemy': 'SQLAlchemy',
+  'boto3': 'AWS',
+  'openai': 'OpenAI',
+  'anthropic': 'Claude API',
+  'google.generativeai': 'Gemini',
+  'google-generativeai': 'Gemini',
+  'redis': 'Redis',
+  'celery': 'Celery',
+  'pydantic': 'Pydantic',
+  'stripe': 'Stripe',
+};
+
+// JS/TS: import/require patterns → stack name
+const JS_STACK = {
+  'next': 'Next.js',
+  'express': 'Express',
+  'fastify': 'Fastify',
+  'react': 'React',
+  '@prisma/client': 'Prisma',
+  'prisma': 'Prisma',
+  'mongoose': 'MongoDB',
+  'sequelize': 'Sequelize',
+  'drizzle-orm': 'Drizzle',
+  'drizzle': 'Drizzle',
+  'redis': 'Redis',
+  'ioredis': 'Redis',
+  'openai': 'OpenAI',
+  '@anthropic-ai/sdk': 'Claude API',
+  'anthropic': 'Claude API',
+  'stripe': 'Stripe',
+  'firebase': 'Firebase',
+  'firebase-admin': 'Firebase',
+  '@supabase/supabase-js': 'Supabase',
+  'supabase': 'Supabase',
+  '@clerk/nextjs': 'Clerk',
+  '@clerk/clerk-sdk-node': 'Clerk',
+  'clerk': 'Clerk',
+  'next-auth': 'NextAuth',
+  'nextauth': 'NextAuth',
+};
+
+const MAX_STACK_ITEMS = 6;
+
+/**
+ * detectStackFromContent(content, filename) → Array<string>
+ * Scans a single file's content for known stack imports.
+ */
+function detectStackFromContent(content, filename) {
+  const ext = path.extname(filename).toLowerCase();
+  const detected = new Set();
+
+  if (ext === '.py') {
+    // Python imports: import X, from X import Y
+    for (const pkg of Object.keys(PYTHON_STACK)) {
+      // Match: import fastapi, from fastapi import ..., from fastapi.xxx import ...
+      const pattern = new RegExp(`(?:^|\\n)\\s*(?:import\\s+${escapeRegex(pkg)}|from\\s+${escapeRegex(pkg)}(?:\\.|\\s))`, 'm');
+      if (pattern.test(content)) {
+        detected.add(PYTHON_STACK[pkg]);
+      }
+    }
+  } else if (['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'].includes(ext)) {
+    // JS/TS imports: import ... from 'pkg', require('pkg')
+    for (const pkg of Object.keys(JS_STACK)) {
+      const escaped = escapeRegex(pkg);
+      // import ... from 'pkg' or import 'pkg'
+      const importPattern = new RegExp(`(?:from|import)\\s+['"]${escaped}(?:[/'"])`);
+      // require('pkg')
+      const requirePattern = new RegExp(`require\\s*\\(\\s*['"]${escaped}(?:[/'"])`);
+      if (importPattern.test(content) || requirePattern.test(content)) {
+        detected.add(JS_STACK[pkg]);
+      }
+    }
+  }
+
+  return [...detected];
+}
+
+/**
+ * detectStackFromPackageJson(projectRoot) → Array<string>
+ * Reads package.json dependencies for known stack packages.
+ */
+function detectStackFromPackageJson(projectRoot) {
+  const detected = new Set();
+  const pkgPath = path.join(projectRoot, 'package.json');
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    const allDeps = Object.assign({}, pkg.dependencies || {}, pkg.devDependencies || {});
+
+    for (const dep of Object.keys(allDeps)) {
+      const depLower = dep.toLowerCase();
+      if (JS_STACK[depLower]) {
+        detected.add(JS_STACK[depLower]);
+      }
+      // Also check without scope for scoped packages
+      if (JS_STACK[dep]) {
+        detected.add(JS_STACK[dep]);
+      }
+    }
+  } catch {
+    // No package.json or can't read — that's fine
+  }
+
+  return [...detected];
+}
+
+/**
+ * detectStackFromRequirements(projectRoot) → Array<string>
+ * Reads requirements.txt for known Python packages.
+ */
+function detectStackFromRequirements(projectRoot) {
+  const detected = new Set();
+  const reqPath = path.join(projectRoot, 'requirements.txt');
+
+  try {
+    const content = fs.readFileSync(reqPath, 'utf-8').toLowerCase();
+    for (const pkg of Object.keys(PYTHON_STACK)) {
+      // Match package name at start of line, possibly followed by ==, >=, etc.
+      const pattern = new RegExp(`^${escapeRegex(pkg.replace('.', '-'))}\\s*[=><~!\\[]`, 'm');
+      const simplePattern = new RegExp(`^${escapeRegex(pkg.replace('.', '-'))}\\s*$`, 'm');
+      if (pattern.test(content) || simplePattern.test(content)) {
+        detected.add(PYTHON_STACK[pkg]);
+      }
+    }
+  } catch {
+    // No requirements.txt — that's fine
+  }
+
+  return [...detected];
+}
+
+/**
+ * buildStackLine(fileContents, projectRoot) → string
+ * Aggregates stack detection across all watched files + manifests.
+ * Returns a comma-separated string of max 6 items, or empty string.
+ */
+function buildStackLine(fileContents, projectRoot) {
+  const allDetected = new Set();
+
+  // Scan manifests
+  for (const item of detectStackFromPackageJson(projectRoot)) allDetected.add(item);
+  for (const item of detectStackFromRequirements(projectRoot)) allDetected.add(item);
+
+  // Scan file contents
+  for (const { filePath, content } of fileContents) {
+    const items = detectStackFromContent(content, filePath);
+    for (const item of items) allDetected.add(item);
+  }
+
+  const sorted = [...allDetected].sort();
+  return sorted.slice(0, MAX_STACK_ITEMS);
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = { buildStackLine, detectStackFromContent };

package/src/sync.js

@@ -6,6 +6,7 @@ const { mergeIntoAgentsMd } = require('./agents/merger');
 const { inferResponsibility } = require('./extractors/filemap');
 const { validateExtracted } = require('./agents/validator');
 const { buildImportGraph } = require('./extractors/imports');
+const { buildStackLine } = require('./extractors/stack');
 
 const IGNORE_DIRS = new Set(['node_modules', '.git', '__pycache__', '.venv', 'venv', '.idea', '.vscode', '.carto', 'AGENTS.md']);
 
@@ -71,7 +72,7 @@ async function runFullSync(config) {
   // Routes per file for file map
   const routeCountMap = {};
   // Env vars: { varName: Set([filename, ...]) }
-  const envVarMap = {};
+  const envVarMap = new Map();
   // DB tables: [{ tableName, modelName, file }]
   const dbTableList = [];
 
@@ -89,6 +90,7 @@ async function runFullSync(config) {
     if (!content) continue;
 
     const basename = path.basename(filePath);
+    const relPath = path.relative(config.projectRoot, filePath);
     const plugin = getPluginForFile(plugins, filePath);
 
     if (!plugin) {
@@ -96,7 +98,7 @@ async function runFullSync(config) {
       continue;
     }
 
-    const result = plugin.extract(content, basename);
+    const result = plugin.extract(content, relPath);
 
     // Routes
     allRoutes = allRoutes.concat(result.routes);
@@ -112,8 +114,8 @@ async function runFullSync(config) {
 
     // Env vars
     for (const varName of result.envVars) {
-      if (!envVarMap[varName]) envVarMap[varName] = new Set();
-      envVarMap[varName].add(basename);
+      if (!envVarMap.has(varName)) envVarMap.set(varName, new Set());
+      envVarMap.get(varName).add(basename);
     }
 
     // DB tables
@@ -181,22 +183,47 @@ async function runFullSync(config) {
   }
   const importGraph = buildImportGraph(fileContentsForImports, config.projectRoot);
 
+  // Detect tech stack from watched files + manifests
+  const stackItems = buildStackLine(fileContentsForImports, config.projectRoot);
+
+  // Compute entry points and high impact files from import graph
+  const allValues = new Set();
+  for (const deps of Object.values(importGraph)) {
+    for (const dep of deps) allValues.add(dep);
+  }
+  // Entry points: files that import 3+ others but nothing imports them
+  const entryPoints = Object.keys(importGraph)
+    .filter(f => !allValues.has(f) && importGraph[f].length >= 3)
+    .sort();
+  // High impact: files imported by 3+ others, sorted descending by count
+  const depCount = {};
+  for (const deps of Object.values(importGraph)) {
+    for (const dep of deps) {
+      depCount[dep] = (depCount[dep] || 0) + 1;
+    }
+  }
+  const highImpact = Object.entries(depCount)
+    .filter(([, count]) => count >= 2)
+    .sort((a, b) => b[1] - a[1])
+    .map(([file, count]) => ({ file, count }));
+
   // Build file map
   const fileMap = [];
   for (const filePath of allCodeFiles) {
     const basename = path.basename(filePath);
+    const relPath = path.relative(config.projectRoot, filePath);
     const funcCount = (functionsMap[basename] || []).length;
     const routeCount = routeCountMap[filePath] || 0;
     const responsibility = inferResponsibility(basename, funcCount, routeCount);
     if (responsibility && responsibility !== '\u2014') {
-      fileMap.push({ file: basename, responsibility });
+      fileMap.push({ file: relPath, responsibility });
     }
   }
 
   // Aggregate env vars into sorted array
-  const envVars = Object.keys(envVarMap)
+  const envVars = [...envVarMap.keys()]
     .sort()
-    .map(name => ({ name, files: [...envVarMap[name]].sort() }));
+    .map(name => ({ name, files: [...envVarMap.get(name)].sort() }));
 
   // Scan project structure
   const structure = await scanStructure(config.projectRoot);
@@ -220,7 +247,10 @@ async function runFullSync(config) {
     functions: validated.functions,
     dbTables: validated.dbTables,
     envVars: validated.envVars,
-    importGraph
+    importGraph,
+    stackItems,
+    entryPoints,
+    highImpact
   });
 
   mergeIntoAgentsMd(config.output, autoContent);