codebrief 1.1.8 → 1.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebrief",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "description": "Generate AI context files for your project in seconds",
   "main": "src/index.js",
   "bin": {

package/src/ai.js

@@ -11,31 +11,57 @@ const IMPORTANT_PATTERNS = [
   "package.json",
   "tsconfig.json",
   "next.config.*",
+  "nuxt.config.*",
   "vite.config.*",
+  "webpack.config.*",
   "tailwind.config.*",
+  "postcss.config.*",
   "prisma/schema.prisma",
   "drizzle.config.*",
-  "README.md",
+  ".env.example",
+  "docker-compose.*",
+  "Dockerfile",
   "src/index.*",
   "src/main.*",
   "src/app.*",
   "src/server.*",
+  "src/config.*",
+  "src/routes.*",
+  "src/middleware.*",
   "lib/db.*",
   "lib/auth.*",
+  "lib/utils.*",
   "app/layout.*",
   "app/page.*",
+  "app/api/**/route.*",
+  "pages/_app.*",
+  "pages/index.*",
+  "server/index.*",
+  "server/api/**",
+  "controllers/*",
+  "models/*",
+  "services/*",
 ];
 
-function sampleSourceFiles(rootDir, fileTree, charBudget = 18000) {
+function sampleSourceFiles(rootDir, fileTree, charBudget = 32000) {
   const samples = [];
   let budget = charBudget;
 
-  // First pass: prioritised files
+  // Smart read: for large files, take head + tail to capture imports AND exports/env vars
+  function smartRead(filePath, maxChars) {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    if (raw.length <= maxChars) return raw;
+    const head = Math.floor(maxChars * 0.6);
+    const tail = maxChars - head - 20; // 20 for separator
+    return raw.slice(0, head) + "\n// ... (truncated) ...\n" + raw.slice(-tail);
+  }
+
+  // First pass: prioritised files (generous budget — these are the most important)
   for (const pattern of IMPORTANT_PATTERNS) {
     const full = path.join(rootDir, pattern);
     if (fs.existsSync(full)) {
       try {
-        const content = fs.readFileSync(full, "utf-8").slice(0, 3000);
+        const content = smartRead(full, 6000);
         samples.push({ file: pattern, content });
         budget -= content.length;
         if (budget <= 0) break;
@@ -68,18 +94,17 @@ function sampleSourceFiles(rootDir, fileTree, charBudget = 18000) {
     const ext = path.extname(entry.name).toLowerCase();
     if (!sourceExts.has(ext)) continue;
 
-    const full = path.join(rootDir, entry.relativePath || entry.name);
+    const full = path.join(rootDir, entry.path || entry.name);
     // Skip already-read files
     if (samples.some((s) => full.endsWith(s.file))) continue;
 
     try {
-      const raw = fs.readFileSync(full, "utf-8");
-      const snippet = raw.slice(0, 1500);
+      const content = smartRead(full, 4000);
       samples.push({
-        file: entry.relativePath || entry.name,
-        content: snippet,
+        file: entry.path || entry.name,
+        content,
       });
-      budget -= snippet.length;
+      budget -= content.length;
     } catch {
       /* skip */
     }
@@ -88,14 +113,80 @@ function sampleSourceFiles(rootDir, fileTree, charBudget = 18000) {
   return samples;
 }
 
+// ── Env var extractor ────────────────────────────────────────
+// Scans all source files for process.env.XXX references
+function extractEnvVars(rootDir, fileTree) {
+  const envVars = new Map(); // name → [files]
+  const sourceExts = new Set([".js", ".ts", ".jsx", ".tsx", ".vue", ".svelte", ".py", ".go", ".rs", ".rb", ".php"]);
+  const envRegex = /process\.env\.([A-Z_][A-Z0-9_]*)/g;
+  const dotenvRegex = /^([A-Z_][A-Z0-9_]*)=/gm;
+
+  for (const entry of fileTree) {
+    if (entry.type !== "file") continue;
+    const ext = path.extname(entry.name).toLowerCase();
+    const name = entry.name.toLowerCase();
+    if (!sourceExts.has(ext) && !name.startsWith(".env")) continue;
+
+    const full = path.join(rootDir, entry.path || entry.name);
+    try {
+      const raw = fs.readFileSync(full, "utf-8");
+      const regex = name.startsWith(".env") ? dotenvRegex : envRegex;
+      let match;
+      while ((match = regex.exec(raw)) !== null) {
+        const varName = match[1];
+        // Skip generic placeholder names
+        if (varName === "XXX" || varName.length < 3) continue;
+        if (!envVars.has(varName)) envVars.set(varName, []);
+        const file = entry.path || entry.name;
+        if (!envVars.get(varName).includes(file)) envVars.get(varName).push(file);
+      }
+    } catch { /* skip */ }
+  }
+
+  return envVars;
+}
+
+// ── Export extractor ─────────────────────────────────────────
+// Scans all source files for key function/class exports
+function extractExports(rootDir, fileTree) {
+  const exports = [];
+  const sourceExts = new Set([".js", ".ts", ".jsx", ".tsx"]);
+  const patterns = [
+    /(?:module\.exports\s*=\s*\{([^}]+)\})/g,
+    /(?:exports\.(\w+)\s*=)/g,
+    /(?:export\s+(?:default\s+)?(?:function|class|const|let|var)\s+(\w+))/g,
+  ];
+
+  for (const entry of fileTree) {
+    if (entry.type !== "file") continue;
+    const ext = path.extname(entry.name).toLowerCase();
+    if (!sourceExts.has(ext)) continue;
+
+    const full = path.join(rootDir, entry.path || entry.name);
+    try {
+      const raw = fs.readFileSync(full, "utf-8");
+      const file = entry.path || entry.name;
+      for (const regex of patterns) {
+        let match;
+        regex.lastIndex = 0;
+        while ((match = regex.exec(raw)) !== null) {
+          exports.push({ file, exports: match[1] || match[0] });
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  return exports;
+}
+
 // ── Prompt builder ───────────────────────────────────────────
-function buildPrompt(analysis, fileTree, fileSamples) {
+function buildPrompt(analysis, fileTree, fileSamples, envVars, fileExports) {
   const fileList = fileTree
-    .slice(0, 80)
+    .slice(0, 120)
     .map((e) =>
       e.type === "dir"
-        ? `  ${e.relativePath || e.name}/`
-        : `  ${e.relativePath || e.name}`,
+        ? `  ${e.path || e.name}/`
+        : `  ${e.path || e.name}`,
     )
     .join("\n");
 
@@ -108,77 +199,112 @@ function buildPrompt(analysis, fileTree, fileSamples) {
       .map(([k, v]) => `  ${k}: ${v}`)
       .join("\n") || "  (none)";
 
-  return `You are a senior software architect. A developer ran \`codebrief\` on their project and you must write a comprehensive, deeply detailed CONTEXT.md file that will help AI assistants (like GitHub Copilot or Cursor) understand this project perfectly.
+  const envVarsText = envVars.size > 0
+    ? Array.from(envVars.entries())
+        .map(([name, files]) => `- \`${name}\` — used in ${files.map((f) => "`" + f + "`").join(", ")}`)
+        .join("\n")
+    : "(none found)";
+
+  const exportsText = fileExports.length > 0
+    ? fileExports.slice(0, 30).map((e) => `- \`${e.file}\`: ${e.exports}`).join("\n")
+    : "(none found)";
+
+  const systemMessage = `You are a world-class software architect. You read source code and produce extremely precise, file-grounded documentation. You NEVER write generic advice. Every sentence you write must cite a real file path, function name, or pattern visible in the code you are given. If you cannot ground a claim in the actual source, you omit it entirely.`;
 
-## Auto-detected project info
+  const userMessage = `I ran \`codebrief\` and need you to write a CONTEXT.md that lets an AI code assistant (Cursor, Copilot) understand this project so well it can write production code immediately.
+
+---
+## HARD RULES (violating these = failure)
+
+1. **File-path grounding**: Every bullet in Architecture Notes, Rules for AI, and Never Do MUST reference at least one real file path or function/export name from the code samples. No exceptions.
+2. **No negatives**: NEVER write "X is not used", "the project does not have Y", "no database detected". If something doesn't exist, simply don't mention it.
+3. **No generic advice**: NEVER write vague statements like "follow best practices", "maintain code quality", "adhere to coding standards", "ensure security". These are worthless.
+4. **Omit, don't guess**: If you can't infer something from the actual code samples, omit that section/bullet entirely. Empty sections should be removed.
+5. **Specific > exhaustive**: 5 deeply specific bullets beat 15 vague ones.
+
+## BAD (never write like this)
+- "Authentication and session logic are not explicitly handled within the project"
+- "Adhere to the project's coding standards and best practices"
+- "Regular security audits are essential"
+- "Error handling mechanisms are crucial for a robust application"
+- "The project follows a modular structure, enhancing maintainability"
+
+## GOOD (write like this)
+- "CLI entry point is \`src/index.js:main()\` — parses flags via \`hasFlag()\`/\`getFlagValue()\`, calls \`scanDirectory()\` → \`analyzeProject()\` → \`generateContextFile()\` in sequence"
+- "AI enhancement in \`src/ai.js:enhanceWithAI()\` samples up to 32k chars of source via \`sampleSourceFiles()\`, builds a structured prompt, dispatches to the selected provider (Groq/OpenAI/Anthropic/Gemini/Grok/Ollama)"
+- "Never add npm dependencies — this project uses zero deps (native \`https\`, \`fs\`, \`path\` only). See \`package.json\` dependencies field is empty."
+- "All color output uses the \`c\` object from \`src/index.js\` (ANSI escape codes) — never use chalk or other color libraries"
+
+---
+## Project metadata
 - Name: ${analysis.name}
-- Type / Framework: ${analysis.type}
+- Framework / Type: ${analysis.type}
 - Language: ${analysis.language}
 - Package manager: ${analysis.packageManager}
 - Stack: ${analysis.stack.join(", ") || "unknown"}
-- CSS framework: ${analysis.cssFramework || "none detected"}
-- UI library: ${analysis.uiLibrary || "none detected"}
-- State management: ${analysis.stateManagement || "none detected"}
-- Database: ${analysis.database || "none detected"}
-- Test framework: ${analysis.testFramework || "none detected"}
-- Deployment: ${analysis.deployment || "unknown"}
+- CSS: ${analysis.cssFramework || "none"} · UI: ${analysis.uiLibrary || "none"} · State: ${analysis.stateManagement || "none"}
+- DB: ${analysis.database || "none"} · Tests: ${analysis.testFramework || "none"} · Deploy: ${analysis.deployment || "unknown"}
 - Monorepo: ${analysis.isMonorepo}
 
 ## Scripts
 ${scripts}
 
-## File tree (first 80 entries)
+## File tree
 ${fileList}
 
-## Key source file samples
+## Source code samples (READ CAREFULLY — this is your evidence)
 ${samplesText}
 
+## Environment variables found in code
+${envVarsText}
+
+## Module exports detected
+${exportsText}
+
 ---
 
-Now produce a CONTEXT.md file in this exact Markdown structure. Be as specific and detailed as possible — infer architecture from the actual code, don't be generic:
+Now produce the CONTEXT.md in EXACTLY this structure. Remove any section where you have nothing concrete to say. Keep the emoji in every section header EXACTLY as shown.
 
 # Project Context: ${analysis.name}
-> Auto-generated and AI-enhanced by **codebrief**
-> Generated: ${new Date().toISOString().split("T")[0]}
+> AI-enhanced by **codebrief** · ${new Date().toISOString().split("T")[0]}
 
 ---
 
 ## 🧱 Tech Stack
-(bullet list of every detected technology with brief description of its role in THIS project)
+Bullet list. Each bullet: technology name + its specific role citing where it's used.
+Example: "Node.js — runtime; entry point at \`src/index.js\`, all code is CommonJS with \`require()\`"
 
-## 📁 Folder Conventions
-(bullet list explaining what each main folder/directory is responsible for, inferred from the file tree and source)
+## 🚀 Key Files
+The 5–8 most important files to read first. Exact paths. One sentence each explaining what the file does and its key exports/functions.
 
-## 🔧 Available Scripts
-(bullet list of scripts and what they actually do in context)
+## 📁 Folder Structure
+One bullet per top-level directory, explaining its responsibility based on the actual files inside.
 
-## 🗂️ Project Structure
-\`\`\`
-(the file tree, neatly formatted)
-\`\`\`
+## 🔧 Scripts
+One bullet per script. Say what it actually does, not just its command.
 
 ## 🏗️ Architecture Notes
-(this is the most valuable section — write 8-15 detailed bullet points explaining:
-  - how data flows through the app
-  - where auth/session logic lives
-  - how the database/ORM is used
-  - how routing works
-  - key patterns or abstractions in the codebase
-  - anything a new developer MUST know before coding)
+8–15 bullets. Each MUST:
+- Name specific file(s), function(s), or export(s)
+- Describe a concrete data flow, dependency, or design decision
+- Be something useful for an AI about to write code in this project
 
 ## 🤖 Rules for AI
-(bullet list of 8-12 concrete rules the AI assistant must follow when generating code for THIS specific project — based on the actual patterns observed in the source)
+8–12 rules extracted from the actual code patterns. Format:
+- "Always/Never [specific action] — [file or pattern reference]"
 
 ## 🚫 Never Do
-(bullet list of 6-10 things an AI must NEVER do in this project — inferred from the stack and code style)
+6–10 prohibitions grounded in the codebase. Each must cite WHY (a file, pattern, or convention).
 
-## 🔐 Security & Environment
-(notes about environment variables, secrets, auth patterns seen in the code)
+## 🔐 Environment & Secrets
+List actual env var names found in the code (e.g. \`GROQ_API_KEY\`, \`OPENAI_API_KEY\`). Describe how they're loaded and used. If none found, omit this section.
 
 ---
-*Re-run \`codebrief\` after major refactors to keep this file current.*
+*Re-run \`codebrief --ai\` after major refactors to keep this file current.*
 
-Respond with ONLY the Markdown content. No explanations, no code fences around the whole output.`;
+Respond with ONLY the Markdown. No preamble, no wrapping code fences.`;
+
+  return { systemMessage, userMessage };
 }
 
 // ── HTTP helper (native, no deps) ────────────────────────────
@@ -224,6 +350,10 @@ async function callGroq(prompt, model) {
         "  Get a free key in ~30s at https://console.groq.com",
     );
 
+  const messages = typeof prompt === "string"
+    ? [{ role: "user", content: prompt }]
+    : [{ role: "system", content: prompt.systemMessage }, { role: "user", content: prompt.userMessage }];
+
   const res = await httpsPost(
     "api.groq.com",
     "/openai/v1/chat/completions",
@@ -233,9 +363,9 @@ async function callGroq(prompt, model) {
     },
     {
       model,
-      messages: [{ role: "user", content: prompt }],
-      temperature: 0.3,
-      max_tokens: 4096,
+      messages,
+      temperature: 0.2,
+      max_tokens: 8192,
     },
   );
   return res.choices?.[0]?.message?.content || "";
@@ -247,6 +377,10 @@ async function callOpenAI(prompt, model) {
   if (!apiKey)
     throw new Error("OPENAI_API_KEY environment variable is not set.");
 
+  const messages = typeof prompt === "string"
+    ? [{ role: "user", content: prompt }]
+    : [{ role: "system", content: prompt.systemMessage }, { role: "user", content: prompt.userMessage }];
+
   const res = await httpsPost(
     "api.openai.com",
     "/v1/chat/completions",
@@ -256,9 +390,9 @@ async function callOpenAI(prompt, model) {
     },
     {
       model,
-      messages: [{ role: "user", content: prompt }],
-      temperature: 0.3,
-      max_tokens: 4096,
+      messages,
+      temperature: 0.2,
+      max_tokens: 8192,
     },
   );
   return res.choices?.[0]?.message?.content || "";
@@ -270,6 +404,19 @@ async function callAnthropic(prompt, model) {
   if (!apiKey)
     throw new Error("ANTHROPIC_API_KEY environment variable is not set.");
 
+  const messages = typeof prompt === "string"
+    ? [{ role: "user", content: prompt }]
+    : [{ role: "user", content: prompt.userMessage }];
+
+  const system = typeof prompt === "string" ? undefined : prompt.systemMessage;
+
+  const body = {
+    model,
+    max_tokens: 8192,
+    messages,
+  };
+  if (system) body.system = system;
+
   const res = await httpsPost(
     "api.anthropic.com",
     "/v1/messages",
@@ -278,11 +425,7 @@ async function callAnthropic(prompt, model) {
       "x-api-key": apiKey,
       "anthropic-version": "2023-06-01",
     },
-    {
-      model,
-      max_tokens: 4096,
-      messages: [{ role: "user", content: prompt }],
-    },
+    body,
   );
   return res.content?.[0]?.text || "";
 }
@@ -296,13 +439,17 @@ async function callGemini(prompt, model) {
         "  Get a free key at https://aistudio.google.com/app/apikey",
     );
 
+  const fullText = typeof prompt === "string"
+    ? prompt
+    : `${prompt.systemMessage}\n\n${prompt.userMessage}`;
+
   const res = await httpsPost(
     "generativelanguage.googleapis.com",
     `/v1beta/models/${model}:generateContent?key=${apiKey}`,
     { "Content-Type": "application/json" },
     {
-      contents: [{ parts: [{ text: prompt }] }],
-      generationConfig: { temperature: 0.3, maxOutputTokens: 4096 },
+      contents: [{ parts: [{ text: fullText }] }],
+      generationConfig: { temperature: 0.2, maxOutputTokens: 8192 },
     },
   );
   return res.candidates?.[0]?.content?.parts?.[0]?.text || "";
@@ -317,6 +464,10 @@ async function callGrok(prompt, model) {
         "  Get a key at https://console.x.ai",
     );
 
+  const messages = typeof prompt === "string"
+    ? [{ role: "user", content: prompt }]
+    : [{ role: "system", content: prompt.systemMessage }, { role: "user", content: prompt.userMessage }];
+
   const res = await httpsPost(
     "api.x.ai",
     "/v1/chat/completions",
@@ -326,9 +477,9 @@ async function callGrok(prompt, model) {
     },
     {
       model,
-      messages: [{ role: "user", content: prompt }],
-      temperature: 0.3,
-      max_tokens: 4096,
+      messages,
+      temperature: 0.2,
+      max_tokens: 8192,
     },
   );
   return res.choices?.[0]?.message?.content || "";
@@ -338,7 +489,10 @@ async function callOllama(prompt, model) {
   model = model || getDefaultModel("ollama");
   // Ollama runs locally on port 11434 — use http
   const http = require("http");
-  const body = JSON.stringify({ model, prompt, stream: false });
+  const fullText = typeof prompt === "string"
+    ? prompt
+    : `${prompt.systemMessage}\n\n${prompt.userMessage}`;
+  const body = JSON.stringify({ model, prompt: fullText, stream: false });
 
   return new Promise((resolve, reject) => {
     const req = http.request(
@@ -387,7 +541,9 @@ async function enhanceWithAI(analysis, fileTree, rootDir, options = {}) {
   const { provider = "openai", model } = options;
 
   const fileSamples = sampleSourceFiles(rootDir, fileTree);
-  const prompt = buildPrompt(analysis, fileTree, fileSamples);
+  const envVars = extractEnvVars(rootDir, fileTree);
+  const fileExports = extractExports(rootDir, fileTree);
+  const prompt = buildPrompt(analysis, fileTree, fileSamples, envVars, fileExports);
 
   switch (provider.toLowerCase()) {
     case "groq":

package/src/index.js

@@ -278,19 +278,16 @@ async function runInitPrompts(contextPath) {
 async function main() {
   print("");
   print(bold(cyan("⚡ codebrief") + " — AI Context Generator"));
-  print(dim("  Scanning: " + rootDir));
   print("");
 
   // Step 1: Scan
-  startSpinner("Scanning project files...");
+  startSpinner("Scanning project...");
   const fileTree = scanDirectory(rootDir, maxDepth);
-  stopSpinner(`Found ${fileTree.length} files and folders`);
 
   // Step 2: Analyze
-  startSpinner("Analyzing stack and conventions...");
   const analysis = analyzeProject(rootDir);
   stopSpinner(
-    `Detected: ${analysis.stack.join(", ") || "Unknown project type"}`,
+    `${fileTree.length} files · ${analysis.stack.join(", ") || "unknown stack"}`,
   );
 
   // Step 3: Generate files
@@ -432,63 +429,12 @@ async function main() {
 
   // ── Summary ───────────────────────────────────────────────
   print("");
-  print(bold("  📄 Files Created:"));
-  filesCreated.forEach((f) => {
-    print(`     ${green("✅")} ${bold(f.label)}`);
-  });
-
-  print("");
-  print(bold("  🧱 Detected Stack:"));
-  if (analysis.stack.length > 0) {
-    analysis.stack.forEach((s) => print(`     ${cyan("→")} ${s}`));
-  } else {
-    print(
-      `     ${c.yellow}Could not auto-detect stack — check CONTEXT.md${c.reset}`,
-    );
-  }
-
-  if (analysis.conventions.length > 0) {
-    print("");
-    print(bold("  📁 Detected Conventions:"));
-    analysis.conventions.forEach((s) => print(`     ${cyan("→")} ${s}`));
-  }
+  filesCreated.forEach((f) => print(`  ${green("✔")} ${bold(f.label)}`));
 
-  if (analysis.isMonorepo && analysis.packages.length > 0) {
+  if (!aiMode) {
     print("");
-    print(bold("  📦 Monorepo Packages:"));
-    analysis.packages.forEach((p) =>
-      print(`     ${cyan("→")} ${bold(p.name)} ${dim("(" + p.path + ")")}`),
-    );
-  }
-
-  print("");
-  print(bold("  ✏️  Next Steps:"));
-  if (!initMode) {
-    print(
-      `     1. Open ${cyan("CONTEXT.md")} and fill in the ${bold("Architecture Notes")} section`,
-    );
-    print(`     2. Add your own rules to the ${bold("Never Do")} section`);
+    print(dim(`  Tip: use ${cyan("--ai")} for an AI-enhanced CONTEXT.md.`));
   }
-  if (!skipCursor) {
-    print(
-      `     3. In Cursor, open the Notepads panel and reference ${cyan("CONTEXT.md")}`,
-    );
-    print(
-      `     4. Your ${cyan(".cursor/rules/project.mdc")} is already active automatically`,
-    );
-  }
-  print(
-    dim(
-      `     Tip: use ${cyan("--update")} next time to preserve your notes on re-run.`,
-    ),
-  );
-  print(
-    dim(
-      `     Tip: use ${cyan("--ai")} for a deeply detailed AI-enhanced CONTEXT.md.`,
-    ),
-  );
-  print("");
-  print(dim("  Re-run codebrief after major refactors to keep context fresh."));
   print("");
 
   // ── Interactive --init prompts ───────────────────────────────