codebrief 1.1.3 → 1.1.7

package/README.md

@@ -54,19 +54,20 @@ codebrief [options]
 
 ### All Options
 
-| Flag               | Description                                                          | Default          |
-| ------------------ | -------------------------------------------------------------------- | ---------------- |
-| `--depth <n>`      | Max folder depth to scan                                             | `4`              |
-| `--no-cursor`      | Skip `.cursor/rules/project.mdc` generation                          | cursor on        |
-| `--vscode`         | Also generate `.github/copilot-instructions.md`                      | off              |
-| `--output <dir>`   | Write output files to a different directory                          | cwd              |
-| `--update`         | Re-generate but **preserve** your Architecture Notes & Never Do      | —                |
-| `--init`           | Interactively fill in Architecture Notes & Never Do after generation | —                |
-| `--ai`             | Use AI to generate a deeply detailed `CONTEXT.md`                    | off              |
-| `--provider <p>`   | AI provider: `groq` (default), `openai`, `anthropic`, `ollama`       | `groq`           |
-| `--model <m>`      | Override the default model for the chosen provider                   | provider default |
-| `--version` / `-v` | Print version                                                        | —                |
-| `--help` / `-h`    | Show help                                                            | —                |
+| Flag               | Description                                                                      | Default          |
+| ------------------ | -------------------------------------------------------------------------------- | ---------------- |
+| `--depth <n>`      | Max folder depth to scan                                                         | `4`              |
+| `--no-cursor`      | Skip `.cursor/rules/project.mdc` generation                                      | cursor on        |
+| `--vscode`         | Also generate `.github/copilot-instructions.md`                                  | off              |
+| `--output <dir>`   | Write output files to a different directory                                      | cwd              |
+| `--update`         | Re-generate but **preserve** your Architecture Notes & Never Do                  | —                |
+| `--init`           | Interactively fill in Architecture Notes & Never Do after generation             | —                |
+| `--ai`             | Use AI to generate a deeply detailed `CONTEXT.md`                                | off              |
+| `--provider <p>`   | AI provider: `groq` (default), `openai`, `anthropic`, `gemini`, `grok`, `ollama` | `groq`           |
+| `--model <m>`      | Override the default model for the chosen provider                               | provider default |
+| `--models`         | List all available models for the chosen `--provider`                            | —                |
+| `--version` / `-v` | Print version                                                                    | —                |
+| `--help` / `-h`    | Show help                                                                        | —                |
 
 ---
 
@@ -95,14 +96,45 @@ codebrief --ai
 
 ### AI Providers
 
-| Provider    | Flag                   | Env Variable        | Cost       | Default Model                |
-| ----------- | ---------------------- | ------------------- | ---------- | ---------------------------- |
-| **Groq**    | `--provider groq`      | `GROQ_API_KEY`      | Free tier  | `llama-3.3-70b-versatile`    |
-| OpenAI      | `--provider openai`    | `OPENAI_API_KEY`    | Paid       | `gpt-4o`                     |
-| Anthropic   | `--provider anthropic` | `ANTHROPIC_API_KEY` | Paid       | `claude-3-5-sonnet-20241022` |
-| Ollama      | `--provider ollama`    | *(none)*            | Free/local | `llama3`                     |
+| Provider   | Flag                   | Env Variable        | Cost       | Default Model             |
+| ---------- | ---------------------- | ------------------- | ---------- | ------------------------- |
+| **Groq**   | `--provider groq`      | `GROQ_API_KEY`      | Free tier  | `llama-3.3-70b-versatile` |
+| **Gemini** | `--provider gemini`    | `GEMINI_API_KEY`    | Free tier  | `gemini-2.5-flash`        |
+| OpenAI     | `--provider openai`    | `OPENAI_API_KEY`    | Paid       | `gpt-4o`                  |
+| Anthropic  | `--provider anthropic` | `ANTHROPIC_API_KEY` | Paid       | `claude-sonnet-4-5`       |
+| Grok (xAI) | `--provider grok`      | `XAI_API_KEY`       | Paid       | `grok-4-fast`             |
+| Ollama     | `--provider ollama`    | *(none)*            | Free/local | `llama3.3`                |
 
-**Groq is the recommended default** — it's free, requires no credit card, and is the fastest inference available (~2–3s response time).
+**Groq and Gemini are both free** — no credit card required. Groq is fastest (~2–3s), Gemini offers Google's latest models.
+
+### Browsing Available Models
+
+Use `--models` to see all available models for any provider before running `--ai`:
+
+```bash
+# List all models for a provider
+codebrief --models --provider groq
+codebrief --models --provider gemini
+codebrief --models --provider openai
+
+# List all providers (no --provider given)
+codebrief --models
+```
+
+Example output:
+
+```
+  Models for groq:
+
+    meta-llama/llama-4-maverick-17b-128e-instruct
+    llama-3.3-70b-versatile (default)
+    llama-3.1-8b-instant
+    compound-beta
+
+  Usage: codebrief --ai --provider groq --model <model>
+```
+
+All available models are maintained in `src/models.js` — update that file when new models release or old ones are deprecated.
 
 ### Examples
 
@@ -110,13 +142,21 @@ codebrief --ai
 # Free (Groq, default)
 codebrief --ai
 
-# Specific provider
-codebrief --ai --provider anthropic
+# Free (Google Gemini)
+codebrief --ai --provider gemini
+
+# Paid providers
 codebrief --ai --provider openai
+codebrief --ai --provider anthropic
+codebrief --ai --provider grok
+
+# Use a specific model (see codebrief --models --provider <name>)
+codebrief --ai --provider groq --model llama-3.1-8b-instant
+codebrief --ai --provider gemini --model gemini-1.5-pro
 
 # Fully local, no API key (needs Ollama running)
 codebrief --ai --provider ollama
-codebrief --ai --provider ollama --model mistral
+codebrief --ai --provider ollama --model codellama
 
 # AI + preserve existing notes
 codebrief --ai --update
@@ -285,19 +325,19 @@ Now help me with: ...
 
 ## Detected Stacks
 
-| Category            | Detected                                                                                                      |
-| ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Category            | Detected                                                                                                     |
+| ------------------- | ------------------------------------------------------------------------------------------------------------ |
 | **Frameworks**      | Next.js, Remix, SvelteKit, Astro, Nuxt.js, React, Vue.js, Svelte, Angular, NestJS, Express.js, Fastify, Hono |
-| **Language**        | TypeScript (via `tsconfig.json` or dep), Python                                                               |
-| **CSS**             | Tailwind CSS, styled-components, Emotion, SASS                                                                |
-| **UI Libraries**    | shadcn/ui, Material UI, Ant Design, Chakra UI, Mantine                                                        |
-| **State**           | TanStack Query, Zustand, Jotai, Redux Toolkit, MobX                                                           |
-| **Database/ORM**    | Prisma, Drizzle, Mongoose, Supabase, Firebase                                                                 |
-| **Testing**         | Vitest, Jest, Playwright, Cypress                                                                             |
-| **Deployment**      | Vercel, Netlify, Railway, Docker                                                                              |
-| **Package Manager** | npm, pnpm, yarn, bun                                                                                          |
-| **Python**          | Django, FastAPI, Flask                                                                                        |
-| **Monorepo**        | pnpm workspaces, Turborepo, Lerna, npm workspaces                                                             |
+| **Language**        | TypeScript (via `tsconfig.json` or dep), Python                                                              |
+| **CSS**             | Tailwind CSS, styled-components, Emotion, SASS                                                               |
+| **UI Libraries**    | shadcn/ui, Material UI, Ant Design, Chakra UI, Mantine                                                       |
+| **State**           | TanStack Query, Zustand, Jotai, Redux Toolkit, MobX                                                          |
+| **Database/ORM**    | Prisma, Drizzle, Mongoose, Supabase, Firebase                                                                |
+| **Testing**         | Vitest, Jest, Playwright, Cypress                                                                            |
+| **Deployment**      | Vercel, Netlify, Railway, Docker                                                                             |
+| **Package Manager** | npm, pnpm, yarn, bun                                                                                         |
+| **Python**          | Django, FastAPI, Flask                                                                                       |
+| **Monorepo**        | pnpm workspaces, Turborepo, Lerna, npm workspaces                                                            |
 
 ---
 
@@ -322,6 +362,7 @@ codebrief/
     analyzer.js   ← Stack detection from package.json, lock files, config files
     generator.js  ← Markdown/MDC generators + section parser for --update
     ai.js         ← AI enhancement: file sampling, prompt builder, provider calls
+    models.js     ← All provider model lists — edit here to update/add models
   package.json
   README.md
   ROADMAP.md

package/package.json

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

package/src/ai.js

@@ -3,6 +3,7 @@
 const fs = require("fs");
 const path = require("path");
 const https = require("https");
+const { getDefaultModel, getAllProviders } = require("./models");
 
 // ── File sampler ─────────────────────────────────────────────
 // Reads the most informative source files up to a character budget
@@ -214,7 +215,8 @@ function httpsPost(hostname, path, headers, body) {
 }
 
 // ── Provider implementations ─────────────────────────────────
-async function callGroq(prompt, model = "llama-3.3-70b-versatile") {
+async function callGroq(prompt, model) {
+  model = model || getDefaultModel("groq");
   const apiKey = process.env.GROQ_API_KEY;
   if (!apiKey)
     throw new Error(
@@ -239,7 +241,8 @@ async function callGroq(prompt, model = "llama-3.3-70b-versatile") {
   return res.choices?.[0]?.message?.content || "";
 }
 
-async function callOpenAI(prompt, model = "gpt-4o") {
+async function callOpenAI(prompt, model) {
+  model = model || getDefaultModel("openai");
   const apiKey = process.env.OPENAI_API_KEY;
   if (!apiKey)
     throw new Error("OPENAI_API_KEY environment variable is not set.");
@@ -261,7 +264,8 @@ async function callOpenAI(prompt, model = "gpt-4o") {
   return res.choices?.[0]?.message?.content || "";
 }
 
-async function callAnthropic(prompt, model = "claude-3-5-sonnet-20241022") {
+async function callAnthropic(prompt, model) {
+  model = model || getDefaultModel("anthropic");
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey)
     throw new Error("ANTHROPIC_API_KEY environment variable is not set.");
@@ -283,7 +287,55 @@ async function callAnthropic(prompt, model = "claude-3-5-sonnet-20241022") {
   return res.content?.[0]?.text || "";
 }
 
-async function callOllama(prompt, model = "llama3") {
+async function callGemini(prompt, model) {
+  model = model || getDefaultModel("gemini");
+  const apiKey = process.env.GEMINI_API_KEY;
+  if (!apiKey)
+    throw new Error(
+      "GEMINI_API_KEY environment variable is not set.\n" +
+        "  Get a free key at https://aistudio.google.com/app/apikey",
+    );
+
+  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 },
+    },
+  );
+  return res.candidates?.[0]?.content?.parts?.[0]?.text || "";
+}
+
+async function callGrok(prompt, model) {
+  model = model || getDefaultModel("grok");
+  const apiKey = process.env.XAI_API_KEY;
+  if (!apiKey)
+    throw new Error(
+      "XAI_API_KEY environment variable is not set.\n" +
+        "  Get a key at https://console.x.ai",
+    );
+
+  const res = await httpsPost(
+    "api.x.ai",
+    "/v1/chat/completions",
+    {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    {
+      model,
+      messages: [{ role: "user", content: prompt }],
+      temperature: 0.3,
+      max_tokens: 4096,
+    },
+  );
+  return res.choices?.[0]?.message?.content || "";
+}
+
+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 });
@@ -339,16 +391,20 @@ async function enhanceWithAI(analysis, fileTree, rootDir, options = {}) {
 
   switch (provider.toLowerCase()) {
     case "groq":
-      return await callGroq(prompt, model || "llama-3.3-70b-versatile");
+      return await callGroq(prompt, model);
     case "openai":
-      return await callOpenAI(prompt, model || "gpt-4o");
+      return await callOpenAI(prompt, model);
     case "anthropic":
-      return await callAnthropic(prompt, model || "claude-3-5-sonnet-20241022");
+      return await callAnthropic(prompt, model);
+    case "gemini":
+      return await callGemini(prompt, model);
+    case "grok":
+      return await callGrok(prompt, model);
     case "ollama":
-      return await callOllama(prompt, model || "llama3");
+      return await callOllama(prompt, model);
     default:
       throw new Error(
-        `Unknown provider "${provider}". Use: groq (default), openai, anthropic, or ollama`,
+        `Unknown provider "${provider}". Available: ${getAllProviders().join(", ")}`,
       );
   }
 }

package/src/index.js

@@ -13,6 +13,32 @@ const {
   parseExistingContext,
 } = require("./generator");
 const { enhanceWithAI } = require("./ai");
+const {
+  getAvailableModels,
+  getDefaultModel,
+  getAllProviders,
+} = require("./models");
+
+// ── Load env files (no external deps) ────────────────────────
+// Reads KEY=VALUE lines from a file and sets missing process.env vars
+function loadEnvFile(filePath) {
+  if (!fs.existsSync(filePath)) return;
+  const lines = fs.readFileSync(filePath, "utf-8").split("\n");
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    const val = line.slice(eq + 1).trim().replace(/^['"]|['"]$/g, "");
+    if (key && !(key in process.env)) process.env[key] = val;
+  }
+}
+
+// Priority (lowest → highest): ~/.codebrief → .env → .env.local
+loadEnvFile(path.join(require("os").homedir(), ".codebrief"));
+loadEnvFile(path.join(process.cwd(), ".env"));
+loadEnvFile(path.join(process.cwd(), ".env.local"));
 
 // ── Simple CLI argument parser (no dependencies needed) ───────
 const args = process.argv.slice(2);
@@ -42,15 +68,18 @@ if (hasFlag("--help") || hasFlag("-h")) {
     --update          Re-generate but preserve your Architecture Notes & Never Do sections
     --init            Interactively fill in Architecture Notes & Never Do after generation
     --ai              Use AI to generate a deeply detailed CONTEXT.md (requires API key)
-    --provider <p>    AI provider: groq (default, free), openai, anthropic, or ollama
+    --provider <p>    AI provider: groq (default, free), openai, anthropic, gemini, grok, ollama
     --model <m>       Override the default model for the chosen provider
+    --models          List all available models for the chosen provider (use with --provider)
     --help            Show this help message
     --version         Show version
 
   AI environment variables:
     GROQ_API_KEY        Required for --provider groq (FREE at console.groq.com)
+    GEMINI_API_KEY      Required for --provider gemini (FREE at aistudio.google.com)
     OPENAI_API_KEY      Required for --provider openai
     ANTHROPIC_API_KEY   Required for --provider anthropic
+    XAI_API_KEY         Required for --provider grok (console.x.ai)
     (Ollama needs no key — just run ollama locally)
 
   Examples:
@@ -73,6 +102,34 @@ if (hasFlag("--version") || hasFlag("-v")) {
   process.exit(0);
 }
 
+if (hasFlag("--models")) {
+  const provider = getFlagValue("--provider", null);
+  if (!provider) {
+    console.log("\n  Usage: codebrief --models --provider <name>\n");
+    console.log(
+      "  Available providers: " + getAllProviders().join(", ") + "\n",
+    );
+  } else {
+    const list = getAvailableModels(provider);
+    if (list.length === 0) {
+      console.log(
+        `\n  Unknown provider "${provider}". Available: ${getAllProviders().join(", ")}\n`,
+      );
+    } else {
+      const def = getDefaultModel(provider);
+      console.log(`\n  Models for ${provider}:\n`);
+      list.forEach((m) => {
+        const tag = m === def ? " (default)" : "";
+        console.log(`    ${m}${tag}`);
+      });
+      console.log(
+        `\n  Usage: codebrief --ai --provider ${provider} --model <model>\n`,
+      );
+    }
+  }
+  process.exit(0);
+}
+
 const maxDepth = parseInt(getFlagValue("--depth", "4"), 10);
 const skipCursor = hasFlag("--no-cursor");
 const includeVSCode = hasFlag("--vscode");
@@ -278,7 +335,23 @@ async function main() {
     print("");
     const providerLabel =
       aiProvider.charAt(0).toUpperCase() + aiProvider.slice(1);
-    startSpinner(`Enhancing CONTEXT.md with AI (${providerLabel})...`);
+
+    // Validate --model against known list and warn if unrecognised
+    if (aiModel) {
+      const known = getAvailableModels(aiProvider);
+      if (known.length > 0 && !known.includes(aiModel)) {
+        print(
+          `${c.yellow}⚠${c.reset}  Unknown model "${aiModel}" for ${providerLabel}.`,
+        );
+        print(`   Known models: ${known.join(", ")}`);
+        print(`   ${dim("Proceeding anyway — the provider may accept it.")}`);
+        print("");
+      }
+    }
+
+    startSpinner(
+      `Enhancing CONTEXT.md with AI (${providerLabel} / ${aiModel || getDefaultModel(aiProvider)})...`,
+    );
     try {
       const enhanced = await enhanceWithAI(analysis, fileTree, rootDir, {
         provider: aiProvider,
@@ -307,14 +380,22 @@ async function main() {
             ? "ANTHROPIC_API_KEY"
             : aiProvider === "openai"
               ? "OPENAI_API_KEY"
-              : "GROQ_API_KEY";
+              : aiProvider === "gemini"
+                ? "GEMINI_API_KEY"
+                : aiProvider === "grok"
+                  ? "XAI_API_KEY"
+                  : "GROQ_API_KEY";
         const keyUrl =
           aiProvider === "anthropic"
             ? "https://console.anthropic.com"
             : aiProvider === "openai"
               ? "https://platform.openai.com/api-keys"
-              : "https://console.groq.com";
-        const isFree = aiProvider === "groq";
+              : aiProvider === "gemini"
+                ? "https://aistudio.google.com/app/apikey"
+                : aiProvider === "grok"
+                  ? "https://console.x.ai"
+                  : "https://console.groq.com";
+        const isFree = aiProvider === "groq" || aiProvider === "gemini";
 
         process.stdout.write(
           `\r${c.yellow}⚠${c.reset}  No API key found for ${bold(aiProvider)}.\n\n`,

package/src/models.js

@@ -0,0 +1,74 @@
+"use strict";
+
+const MODELS = {
+  groq: {
+    default: "llama-3.3-70b-versatile",
+    available: [
+      "meta-llama/llama-4-maverick-17b-128e-instruct",
+      "meta-llama/llama-4-scout-17b-16e-instruct",
+      "llama-3.3-70b-versatile",
+      "llama-3.1-8b-instant",
+      "compound-beta",
+    ],
+  },
+
+  gemini: {
+    default: "gemini-2.5-flash",
+    available: [
+      "gemini-2.5-pro",
+      "gemini-2.5-flash",
+      "gemini-2.0-flash",
+      "gemini-2.0-flash-lite",
+    ],
+  },
+
+  openai: {
+    default: "gpt-4o",
+    available: ["gpt-4o", "gpt-4o-mini", "o3", "o4-mini"],
+  },
+
+  anthropic: {
+    default: "claude-sonnet-4-5",
+    available: [
+      "claude-opus-4-5",
+      "claude-sonnet-4-5",
+      "claude-haiku-4-5-20251001",
+    ],
+  },
+
+  grok: {
+    default: "grok-4-fast",
+    available: ["grok-4", "grok-4-fast", "grok-3", "grok-3-mini"],
+  },
+
+  ollama: {
+    default: "llama3.3",
+    available: [
+      "llama4",
+      "llama3.3",
+      "gemma3",
+      "qwen3",
+      "mistral",
+      "codellama",
+    ],
+  },
+};
+
+function getDefaultModel(provider) {
+  return MODELS[provider.toLowerCase()]?.default || null;
+}
+
+function getAvailableModels(provider) {
+  return MODELS[provider.toLowerCase()]?.available || [];
+}
+
+function getAllProviders() {
+  return Object.keys(MODELS);
+}
+
+module.exports = {
+  MODELS,
+  getDefaultModel,
+  getAvailableModels,
+  getAllProviders,
+};