@chappibunny/repolens 1.7.1 → 1.8.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.8.0
+
+### ✨ GitHub Models — First-Class AI Provider
+
+- **GitHub Models provider**: Added `github` as a native AI provider. Uses the OpenAI-compatible endpoint at `models.inference.ai.github.com` with automatic `GITHUB_TOKEN` authentication — no extra API keys needed in GitHub Actions.
+- **Zero-config AI in CI**: When `ai.provider: github` is set in `.repolens.yml`, RepoLens uses the default `GITHUB_TOKEN` injected by GitHub Actions. No secrets to create or manage.
+- **Config-driven AI settings**: `ai.enabled`, `ai.provider`, `ai.model`, `ai.temperature`, and `ai.base_url` in `.repolens.yml` are now fully respected at runtime (env vars still take precedence). Previously these config values were ignored.
+- **Init wizard fixes**: Provider selection now uses correct runtime values (`github`, `openai_compatible`, `anthropic`, `google`) instead of mismatched labels. The wizard now emits `ai.provider` to the generated YAML. Added `github_wiki` to publisher choices.
+- **Demo AI upsell**: `repolens demo` now shows a hint about GitHub Models (free) when AI is not enabled, guiding users to `repolens init --interactive`.
+- **Doctor validation**: `repolens doctor` now checks for `GITHUB_TOKEN` when provider is `github`, and `REPOLENS_AI_API_KEY` for other providers.
+
+### 📖 Documentation
+
+- Updated AI.md, ENVIRONMENT.md, ONBOARDING.md, README.md with GitHub Models as recommended provider
+- Init templates (.env.example, workflow, README) include GitHub Models setup instructions
+- Onboarding shows dual-track: Option A (GitHub Models, free) and Option B (OpenAI / other)
+
+### 🧪 Tests
+
+- 24 new tests: provider config fallbacks, `isAIEnabled` with config, `getAIConfig` with config, GitHub Models defaults, init wizard content, doctor env validation
+- **374 tests passing** across 22 test files
+
 ## 1.7.1
 
 ### 🛡️ AI Output Guardrails

package/README.md

@@ -83,7 +83,7 @@ Run `npx @chappibunny/repolens migrate` to automatically update your workflow fi
 | **Everyone** | System Overview · Developer Onboarding · Change Impact |
 | **Engineers** | Architecture Overview · Module Catalog · API Surface · Route Map · System Map |
 
-**Two modes:** Deterministic (free, fast, always works) or AI-Enhanced (optional — OpenAI, Anthropic, Azure, Ollama).
+**Two modes:** Deterministic (free, fast, always works) or AI-Enhanced (optional — GitHub Models, OpenAI, Anthropic, Google, Azure, Ollama).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",
   "type": "module",

package/src/ai/generate-sections.js

@@ -42,8 +42,8 @@ function sanitizeAIOutput(text) {
 /**
  * Try structured JSON mode first, fall back to plain-text AI, then deterministic.
  */
-async function generateWithStructuredFallback(key, promptText, maxTokens, fallbackFn) {
-  if (!isAIEnabled()) return fallbackFn();
+async function generateWithStructuredFallback(key, promptText, maxTokens, fallbackFn, config) {
+  if (!isAIEnabled(config)) return fallbackFn();
 
   const schema = AI_SCHEMAS[key];
 
@@ -58,6 +58,7 @@ async function generateWithStructuredFallback(key, promptText, maxTokens, fallba
       maxTokens,
       jsonMode: true,
       jsonSchema: schema,
+      config,
     });
 
     if (result.success && result.parsed) {
@@ -74,6 +75,7 @@ async function generateWithStructuredFallback(key, promptText, maxTokens, fallba
     system: SYSTEM_PROMPT,
     user: promptText,
     maxTokens,
+    config,
   });
 
   if (!result.success) {
@@ -84,57 +86,63 @@ async function generateWithStructuredFallback(key, promptText, maxTokens, fallba
   return sanitizeAIOutput(result.text);
 }
 
-export async function generateExecutiveSummary(context, enrichment = {}) {
+export async function generateExecutiveSummary(context, enrichment = {}, config) {
   return generateWithStructuredFallback(
     "executive_summary",
     createExecutiveSummaryPrompt(context),
     1500,
     () => getFallbackExecutiveSummary(context, enrichment),
+    config,
   );
 }
 
-export async function generateSystemOverview(context, enrichment = {}) {
+export async function generateSystemOverview(context, enrichment = {}, config) {
   return generateWithStructuredFallback(
     "system_overview",
     createSystemOverviewPrompt(context),
     1200,
     () => getFallbackSystemOverview(context, enrichment),
+    config,
   );
 }
 
-export async function generateBusinessDomains(context, enrichment = {}) {
+export async function generateBusinessDomains(context, enrichment = {}, config) {
   return generateWithStructuredFallback(
     "business_domains",
     createBusinessDomainsPrompt(context),
     2000,
     () => getFallbackBusinessDomains(context, enrichment),
+    config,
   );
 }
 
-export async function generateArchitectureOverview(context, enrichment = {}) {
+export async function generateArchitectureOverview(context, enrichment = {}, config) {
   return generateWithStructuredFallback(
     "architecture_overview",
     createArchitectureOverviewPrompt(context),
     1800,
     () => getFallbackArchitectureOverview(context, enrichment),
+    config,
   );
 }
 
-export async function generateDataFlows(flows, context, enrichment = {}) {
+export async function generateDataFlows(flows, context, enrichment = {}, config) {
   return generateWithStructuredFallback(
     "data_flows",
     createDataFlowsPrompt(flows, context),
     1800,
     () => getFallbackDataFlows(flows, context, enrichment),
+    config,
   );
 }
 
-export async function generateDeveloperOnboarding(context, enrichment = {}) {
+export async function generateDeveloperOnboarding(context, enrichment = {}, config) {
   return generateWithStructuredFallback(
     "developer_onboarding",
     createDeveloperOnboardingPrompt(context),
     2200,
     () => getFallbackDeveloperOnboarding(context, enrichment),
+    config,
   );
 }
 

package/src/ai/provider.js

@@ -20,11 +20,13 @@ export async function generateText({ system, user, temperature, maxTokens, confi
   }
   
   // Get provider configuration (env vars take precedence, then config, then defaults)
-  const provider = process.env.REPOLENS_AI_PROVIDER || "openai_compatible";
-  const baseUrl = process.env.REPOLENS_AI_BASE_URL;
-  const apiKey = process.env.REPOLENS_AI_API_KEY;
-  const model = process.env.REPOLENS_AI_MODEL || "gpt-5-mini";
-  const timeoutMs = parseInt(process.env.REPOLENS_AI_TIMEOUT_MS || DEFAULT_TIMEOUT_MS);
+  const provider = process.env.REPOLENS_AI_PROVIDER || aiConfig.provider || "openai_compatible";
+  const baseUrl = process.env.REPOLENS_AI_BASE_URL || aiConfig.base_url;
+  // For "github" provider, fall back to GITHUB_TOKEN when no explicit AI key is set
+  const apiKey = process.env.REPOLENS_AI_API_KEY
+    || (provider === "github" ? process.env.GITHUB_TOKEN : undefined);
+  const model = process.env.REPOLENS_AI_MODEL || aiConfig.model || getDefaultModel(provider);
+  const timeoutMs = parseInt(process.env.REPOLENS_AI_TIMEOUT_MS || aiConfig.timeout_ms || DEFAULT_TIMEOUT_MS);
   
   // Use config values as fallback for maxTokens; temperature only when explicitly set
   const resolvedTemp = temperature ?? aiConfig.temperature ?? undefined;
@@ -140,6 +142,18 @@ function validateSchema(obj, schema) {
   return null;
 }
 
+/**
+ * Get default model for a provider.
+ */
+function getDefaultModel(provider) {
+  switch (provider) {
+    case "anthropic": return "claude-sonnet-4-20250514";
+    case "google": return "gemini-pro";
+    case "github": return "gpt-4o-mini";
+    default: return "gpt-5-mini";
+  }
+}
+
 /**
  * Get default base URL for a provider.
  */
@@ -148,6 +162,7 @@ function getDefaultBaseUrl(provider) {
     case "anthropic": return "https://api.anthropic.com";
     case "azure": return process.env.REPOLENS_AI_BASE_URL || "https://api.openai.com/v1";
     case "google": return "https://generativelanguage.googleapis.com";
+    case "github": return "https://models.inference.ai.github.com/v1";
     default: return "https://api.openai.com/v1";
   }
 }
@@ -159,7 +174,7 @@ function getProviderAdapter(provider) {
   switch (provider) {
     case "anthropic": return callAnthropicAPI;
     case "google": return callGoogleAPI;
-    // "openai_compatible" and "azure" both use the OpenAI format
+    // "openai_compatible", "azure", and "github" all use the OpenAI chat/completions format
     default: return callOpenAICompatibleAPI;
   }
 }
@@ -334,21 +349,21 @@ async function callGoogleAPI({ baseUrl, apiKey, model, system, user, temperature
   });
 }
 
-export function isAIEnabled() {
-  return process.env.REPOLENS_AI_ENABLED === "true";
+export function isAIEnabled(config) {
+  return process.env.REPOLENS_AI_ENABLED === "true" || config?.ai?.enabled === true;
 }
 
-export function getAIConfig() {
-  const provider = process.env.REPOLENS_AI_PROVIDER || "openai_compatible";
-  const defaultModel = provider === "anthropic" ? "claude-sonnet-4-20250514"
-    : provider === "google" ? "gemini-pro"
-    : "gpt-5-mini";
+export function getAIConfig(config) {
+  const aiConfig = config?.ai || {};
+  const provider = process.env.REPOLENS_AI_PROVIDER || aiConfig.provider || "openai_compatible";
+  const hasApiKey = !!(process.env.REPOLENS_AI_API_KEY
+    || (provider === "github" ? process.env.GITHUB_TOKEN : undefined));
   return {
-    enabled: isAIEnabled(),
+    enabled: isAIEnabled(config),
     provider,
-    model: process.env.REPOLENS_AI_MODEL || defaultModel,
-    hasApiKey: !!process.env.REPOLENS_AI_API_KEY,
-    temperature: process.env.REPOLENS_AI_TEMPERATURE ? parseFloat(process.env.REPOLENS_AI_TEMPERATURE) : undefined,
-    maxTokens: parseInt(process.env.REPOLENS_AI_MAX_TOKENS || DEFAULT_MAX_TOKENS)
+    model: process.env.REPOLENS_AI_MODEL || aiConfig.model || getDefaultModel(provider),
+    hasApiKey,
+    temperature: process.env.REPOLENS_AI_TEMPERATURE ? parseFloat(process.env.REPOLENS_AI_TEMPERATURE) : (aiConfig.temperature != null ? aiConfig.temperature : undefined),
+    maxTokens: parseInt(process.env.REPOLENS_AI_MAX_TOKENS || aiConfig.max_tokens || DEFAULT_MAX_TOKENS)
   };
 }

package/src/cli.js

@@ -492,6 +492,12 @@ async function main() {
       info("Browse your docs: open the .repolens/ directory");
       info("\nTo publish to Notion, Confluence, or GitHub Wiki, run: repolens publish");
       
+      // Upsell AI enhancement when not already enabled
+      if (!cfg.ai?.enabled && process.env.REPOLENS_AI_ENABLED !== "true") {
+        info("\n💡 Want richer, AI-enhanced docs? Run: repolens init --interactive");
+        info("   Select GitHub Models (free) — uses your existing GITHUB_TOKEN, no extra keys needed.");
+      }
+      
       printPerformanceSummary();
       
       trackUsage("demo", "success", {

package/src/docs/generate-doc-set.js

@@ -189,16 +189,16 @@ async function generateDocument(docPlan, context) {
   
   switch (key) {
     case "executive_summary":
-      return await generateExecutiveSummary(aiContext, { depGraph, flows });
+      return await generateExecutiveSummary(aiContext, { depGraph, flows }, config);
       
     case "system_overview":
-      return await generateSystemOverview(aiContext, { depGraph });
+      return await generateSystemOverview(aiContext, { depGraph }, config);
       
     case "business_domains":
-      return await generateBusinessDomains(aiContext, { depGraph });
+      return await generateBusinessDomains(aiContext, { depGraph }, config);
       
     case "architecture_overview":
-      return await generateArchitectureOverview(aiContext, { depGraph, driftResult });
+      return await generateArchitectureOverview(aiContext, { depGraph, driftResult }, config);
       
     case "module_catalog":
       // Hybrid: deterministic skeleton + ownership info + dep-graph roles
@@ -213,7 +213,7 @@ async function generateDocument(docPlan, context) {
       return renderApiSurfaceOriginal(config, scanResult);
       
     case "data_flows":
-      return await generateDataFlows(flows, aiContext, { depGraph, scanResult, moduleContext });
+      return await generateDataFlows(flows, aiContext, { depGraph, scanResult, moduleContext }, config);
       
     case "arch_diff":
       if (!diffData) {
@@ -226,7 +226,7 @@ async function generateDocument(docPlan, context) {
       return renderSystemMap(scanResult, config, depGraph);
       
     case "developer_onboarding":
-      return await generateDeveloperOnboarding(aiContext, { flows, depGraph });
+      return await generateDeveloperOnboarding(aiContext, { flows, depGraph }, config);
       
     case "graphql_schema":
       return renderGraphQLSchema(graphqlResult);

package/src/doctor.js

@@ -182,9 +182,16 @@ export async function runDoctor(targetDir = process.cwd()) {
     }
 
     if (cfg.ai?.enabled || process.env.REPOLENS_AI_ENABLED === "true") {
-      envChecks.push(
-        { key: "REPOLENS_AI_API_KEY", required: true, publisher: "AI" },
-      );
+      const aiProvider = process.env.REPOLENS_AI_PROVIDER || "openai_compatible";
+      if (aiProvider === "github") {
+        envChecks.push(
+          { key: "GITHUB_TOKEN", required: true, publisher: "AI (GitHub Models)" },
+        );
+      } else {
+        envChecks.push(
+          { key: "REPOLENS_AI_API_KEY", required: true, publisher: "AI" },
+        );
+      }
     }
 
     if (envChecks.length === 0) {

package/src/init.js

@@ -3,8 +3,13 @@ import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { info, warn } from "./utils/logger.js";
 
-const PUBLISHER_CHOICES = ["markdown", "notion", "confluence"];
-const AI_PROVIDERS = ["openai", "anthropic", "azure", "ollama"];
+const PUBLISHER_CHOICES = ["markdown", "notion", "confluence", "github_wiki"];
+const AI_PROVIDERS = [
+  { value: "github",           label: "GitHub Models  (free in GitHub Actions)" },
+  { value: "openai_compatible", label: "OpenAI / Compatible  (GPT-5, GPT-4o, etc.)" },
+  { value: "anthropic",         label: "Anthropic  (Claude)" },
+  { value: "google",            label: "Google  (Gemini)" },
+];
 const SCAN_PRESETS = {
   nextjs: {
     include: [
@@ -84,6 +89,10 @@ jobs:
           CONFLUENCE_API_TOKEN: \${{ secrets.CONFLUENCE_API_TOKEN }}
           CONFLUENCE_SPACE_KEY: \${{ secrets.CONFLUENCE_SPACE_KEY }}
           CONFLUENCE_PARENT_PAGE_ID: \${{ secrets.CONFLUENCE_PARENT_PAGE_ID }}
+          # Uncomment to enable free AI-enhanced docs via GitHub Models:
+          # REPOLENS_AI_ENABLED: true
+          # REPOLENS_AI_PROVIDER: github
+          # GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
         run: npx @chappibunny/repolens@latest publish
 `;
 
@@ -106,6 +115,11 @@ CONFLUENCE_PARENT_PAGE_ID=
 # REPOLENS_AI_BASE_URL=https://api.openai.com/v1
 # REPOLENS_AI_MODEL=gpt-5-mini
 # REPOLENS_AI_MAX_TOKENS=2000
+
+# GitHub Models (free tier — zero-config in GitHub Actions)
+# REPOLENS_AI_PROVIDER=github
+# Uses GITHUB_TOKEN automatically — no separate API key needed
+# REPOLENS_AI_MODEL=gpt-4o-mini
 `;
 
 const DEFAULT_REPOLENS_README = `# RepoLens Documentation
@@ -194,7 +208,20 @@ Adds 5 natural language documents readable by non-technical audiences:
 
 AI features add natural language explanations for non-technical stakeholders.
 
-1. Get an OpenAI API key from https://platform.openai.com/api-keys
+### Option A: GitHub Models (Free — Recommended for GitHub Actions)
+
+Every GitHub repo gets free access to AI models. In your workflow:
+\`\`\`yaml
+env:
+  REPOLENS_AI_ENABLED: true
+  REPOLENS_AI_PROVIDER: github
+  GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+\`\`\`
+No API key signup needed. Uses \`gpt-4o-mini\` by default.
+
+### Option B: OpenAI / Other Providers
+
+1. Get an API key from your chosen provider
 2. Add to your \`.env\` file:
    \`\`\`bash
    REPOLENS_AI_ENABLED=true
@@ -214,7 +241,7 @@ AI features add natural language explanations for non-technical stakeholders.
      developer_onboarding: true
    \`\`\`
 
-**Cost estimate**: $0.10-$0.40 per run for typical projects
+**Cost estimate**: $0.10-$0.40 per run for typical projects (or free with GitHub Models)
 
 See [AI.md](https://github.com/CHAPIBUNNY/repolens/blob/main/AI.md) for full documentation
 - **Module Catalog** — Detected code modules
@@ -532,10 +559,15 @@ async function runInteractiveWizard(repoRoot) {
     let aiProvider = null;
     if (enableAi) {
       info("Select AI provider:");
-      AI_PROVIDERS.forEach((p, i) => info(`  ${i + 1}. ${p}`));
-      const aiInput = (await ask(`Provider [1] (default: 1 openai): `)).trim() || "1";
+      AI_PROVIDERS.forEach((p, i) => info(`  ${i + 1}. ${p.label}`));
+      const aiInput = (await ask(`Provider [1] (default: 1 GitHub Models — free): `)).trim() || "1";
       const idx = parseInt(aiInput, 10);
-      aiProvider = AI_PROVIDERS[(idx >= 1 && idx <= AI_PROVIDERS.length) ? idx - 1 : 0];
+      const chosen = AI_PROVIDERS[(idx >= 1 && idx <= AI_PROVIDERS.length) ? idx - 1 : 0];
+      aiProvider = chosen.value;
+      if (aiProvider === "github") {
+        info("\n  ✨ Great choice! GitHub Models uses your existing GITHUB_TOKEN — no extra API key needed.");
+        info("     Works automatically in GitHub Actions with the free tier.");
+      }
     }
 
     // 4. Scan preset
@@ -605,6 +637,9 @@ function buildWizardConfig(answers) {
     lines.push(`ai:`);
     lines.push(`  enabled: true`);
     lines.push(`  mode: hybrid`);
+    if (answers.aiProvider) {
+      lines.push(`  provider: ${answers.aiProvider}`);
+    }
     lines.push(``);
     lines.push(`features:`);
     lines.push(`  executive_summary: true`);
@@ -758,14 +793,18 @@ NOTION_VERSION=2022-06-28
     info("Next steps:");
     info("  1. Review .repolens.yml to customize your documentation");
     info("  2. Run 'npx @chappibunny/repolens publish' to generate your first docs (deterministic mode)");
-    info("  3. (Optional) Enable AI features by adding to .env:");
+    info("  3. (Optional) Enable AI features:");
+    info("     ── FREE: GitHub Models (recommended for GitHub Actions) ──");
+    info("     REPOLENS_AI_ENABLED=true");
+    info("     REPOLENS_AI_PROVIDER=github");
+    info("     (Uses your GITHUB_TOKEN automatically — no API key signup needed)");
+    info("     ── Or: OpenAI / Anthropic / Google ──");
     info("     REPOLENS_AI_ENABLED=true");
     info("     REPOLENS_AI_API_KEY=sk-...");
     info("     See AI.md for full guide: https://github.com/CHAPIBUNNY/repolens/blob/main/AI.md");
     info("  4. For GitHub Actions, add these repository secrets:");
     info("     - NOTION_TOKEN");
     info("     - NOTION_PARENT_PAGE_ID");
-    info("     - REPOLENS_AI_API_KEY (if using AI features)");
     info("  5. Commit the generated files (workflow will run automatically)");
   } else {
     info("Next steps:");
@@ -773,7 +812,12 @@ NOTION_VERSION=2022-06-28
     info("  2. To enable Notion publishing:");
     info("     - Copy .env.example to .env and add your credentials, OR");
     info("     - Add GitHub secrets: NOTION_TOKEN, NOTION_PARENT_PAGE_ID");
-    info("  3. (Optional) Enable AI features by adding to .env:");
+    info("  3. (Optional) Enable AI features:");
+    info("     ── FREE: GitHub Models (recommended for GitHub Actions) ──");
+    info("     REPOLENS_AI_ENABLED=true");
+    info("     REPOLENS_AI_PROVIDER=github");
+    info("     (Uses your GITHUB_TOKEN automatically — no API key signup needed)");
+    info("     ── Or: OpenAI / Anthropic / Google ──");
     info("     REPOLENS_AI_ENABLED=true");
     info("     REPOLENS_AI_API_KEY=sk-...");
     info("     See: https://github.com/CHAPIBUNNY/repolens/blob/main/AI.md");