@chappibunny/repolens 1.8.1 → 1.8.2

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.8.2
+
+### 🐛 Bug Fixes
+
+- **Uninstall crash fixed**: `repolens uninstall` crashed with `Cannot read properties of undefined (reading 'trim')` when run via `npx`. The readline prompt used the callback-based `node:readline` API incorrectly with `await`. Fixed by wrapping in a proper Promise with null guard.
+
+### ✨ AI Auto-Detection
+
+- **GITHUB_TOKEN auto-enables AI**: `demo`, `publish`, and `init` commands now detect `GITHUB_TOKEN` in the environment and automatically enable AI-enhanced docs via GitHub Models (free). No manual configuration needed.
+- **Workflow template enables AI by default**: The generated `.github/workflows/repolens.yml` now has `REPOLENS_AI_ENABLED`, `REPOLENS_AI_PROVIDER`, and `GITHUB_TOKEN` enabled (not commented out) since GitHub Models is free.
+- **Init auto-configures AI**: Non-interactive `repolens init` writes `ai.enabled: true` and `ai.provider: github` to `.repolens.yml` when `GITHUB_TOKEN` is detected.
+- **Better AI messaging**: Demo and publish commands show prominent status about AI mode (enabled/deterministic) with specific guidance on what AI adds.
+- **Sharper deterministic upsell**: All 6 fallback document types now explain exactly what AI adds (e.g., "adds plain-language explanations, strategic recommendations, and risk assessments") and mention `GITHUB_TOKEN` auto-detection.
+
+### 📖 Documentation
+
+- **Scoped package name everywhere**: All user-facing docs now use `npx @chappibunny/repolens` instead of bare `repolens`. Added warning about the squatted `repolens@0.0.1` placeholder package on npm.
+- Updated: README.md (commands table + warning), TROUBLESHOOTING.md, MIGRATION.md (6 instances), KNOWN_ISSUES.md (2 instances), bug report template.
+
 ## 1.8.1
 
 ### 📖 Documentation Refresh

package/README.md

@@ -148,16 +148,19 @@ Step-by-step setup for publishers, AI features, Notion, Confluence, GitHub Wiki,
 
 | Command | Description |
 |---|---|
-| `repolens init` | Scaffold config + GitHub Actions workflow |
-| `repolens init --interactive` | Step-by-step configuration wizard |
-| `repolens publish` | Scan, generate, and publish documentation |
-| `repolens demo` | Quick local preview — no API keys needed |
-| `repolens doctor` | Validate your setup |
-| `repolens watch` | Auto-regenerate docs on file changes |
-| `repolens migrate` | Upgrade from v0.3.0 workflows ([details](MIGRATION.md)) |
-| `repolens uninstall` | Remove all RepoLens files (config, docs, workflow) |
-| `repolens uninstall --force` | Remove without confirmation prompt |
-| `repolens feedback` | Send feedback to the team |
+| `npx @chappibunny/repolens init` | Scaffold config + GitHub Actions workflow |
+| `npx @chappibunny/repolens init --interactive` | Step-by-step configuration wizard |
+| `npx @chappibunny/repolens publish` | Scan, generate, and publish documentation |
+| `npx @chappibunny/repolens demo` | Quick local preview — no API keys needed |
+| `npx @chappibunny/repolens doctor` | Validate your setup |
+| `npx @chappibunny/repolens watch` | Auto-regenerate docs on file changes |
+| `npx @chappibunny/repolens migrate` | Upgrade from v0.3.0 workflows ([details](MIGRATION.md)) |
+| `npx @chappibunny/repolens uninstall` | Remove all RepoLens files (config, docs, workflow) |
+| `npx @chappibunny/repolens uninstall --force` | Remove without confirmation prompt |
+| `npx @chappibunny/repolens feedback` | Send feedback to the team |
+
+> **Note:** If you installed globally with `npm install -g @chappibunny/repolens`, you can use the shorter `repolens <command>` form.
+> **Warning:** Do not run bare `npx repolens` — there is an unrelated `repolens@0.0.1` placeholder package on npm. Always use the scoped name `@chappibunny/repolens`.
 
 ---
 
@@ -255,7 +258,7 @@ When you open a pull request, RepoLens posts:
 - **Report issues**: Share bugs, edge cases, or UX friction
 - **Request features**: Tell us what's missing
 - **Build plugins**: Extend RepoLens with custom renderers and publishers
-- **Share feedback**: `repolens feedback`
+- **Share feedback**: `npx @chappibunny/repolens feedback`
 
 ---
 

package/package.json

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

package/src/ai/generate-sections.js

@@ -245,7 +245,7 @@ The codebase follows ${context.patterns.length > 0 ? context.patterns.join(", ")
 
 ---
 
-*This summary is generated deterministically from repository structure. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for natural language insights tailored to non-technical readers.*`;
+*This summary was generated from repository structure analysis. Set \`GITHUB_TOKEN\` to auto-enable AI-enhanced summaries via GitHub Models (free) \u2014 adds plain-language explanations for non-technical readers, strategic recommendations, and risk assessments.*`;
 
   return output;
 }
@@ -353,7 +353,7 @@ ${context.domains.slice(0, 5).map((d, i) => `| ${i + 1} | ${d.name} | ${d.fileCo
 
   output += `---
 
-*This overview is generated deterministically. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for richer contextual explanations.*`;
+*This overview was generated from repository structure analysis. Set \`GITHUB_TOKEN\` to auto-enable AI via GitHub Models (free) \u2014 adds narrative context, architectural rationale, and technology trade-off analysis.*`;
 
   return output;
 }
@@ -412,7 +412,7 @@ function getFallbackBusinessDomains(context, enrichment = {}) {
     output += "\n";
   }
   
-  output += `---\n\n*Domain mapping is based on directory naming conventions. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for natural language descriptions aimed at non-technical stakeholders.*`;
+  output += `---\n\n*Domain mapping is based on directory naming conventions. Set \`GITHUB_TOKEN\` to auto-enable AI via GitHub Models (free) \u2014 adds business-language descriptions, stakeholder impact analysis, and cross-domain relationship narratives.*`;
   
   return output;
 }
@@ -533,7 +533,7 @@ The repository comprises **${context.project.filesScanned} files** organized int
 
   output += `---
 
-*This architecture overview is generated deterministically. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for deeper architectural narratives.*`;
+*This architecture overview was generated from repository structure analysis. Set \`GITHUB_TOKEN\` to auto-enable AI via GitHub Models (free) \u2014 adds architectural narratives, design rationale, scalability analysis, and refactoring recommendations.*`;
 
   return output;
 }
@@ -559,7 +559,7 @@ function getFallbackDataFlows(flows, context, enrichment = {}) {
 
   if (allFlows.length === 0) {
     output += `No data flows were detected. This typically means the system uses straightforward request–response patterns without distinct multi-step pipelines.\n\n`;
-    output += `---\n\n*Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for heuristic-based flow descriptions.*`;
+    output += `---\n\n*Set \`GITHUB_TOKEN\` to auto-enable AI via GitHub Models (free) \u2014 AI can infer data flows from import patterns even when heuristics find none.*`;
     return output;
   }
 
@@ -603,7 +603,7 @@ function getFallbackDataFlows(flows, context, enrichment = {}) {
     }
   }
   
-  output += `---\n\n*Flow detection is based on naming conventions and import patterns. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for natural language flow narratives.*`;
+  output += `---\n\n*Flow detection is based on naming conventions and import patterns. Set \`GITHUB_TOKEN\` to auto-enable AI via GitHub Models (free) \u2014 adds end-to-end flow narratives, failure mode analysis, and data transformation descriptions.*`;
   
   return output;
 }
@@ -715,7 +715,7 @@ ${context.topModules.slice(0, 10).map(m => `| \`${m.key}\` | ${m.fileCount} | ${
 
   output += `\n\n---
 
-*This onboarding guide is generated deterministically. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for a narrative-style guide with tips and common pitfalls.*`;
+*This onboarding guide was generated from repository structure analysis. Set \`GITHUB_TOKEN\` to auto-enable AI via GitHub Models (free) \u2014 adds narrative walkthroughs, common pitfalls, debugging tips, and contribution guidelines.*`;
 
   return output;
 }

package/src/cli.js

@@ -338,6 +338,14 @@ async function main() {
       process.exit(EXIT_VALIDATION);
     }
 
+    // Auto-detect GITHUB_TOKEN and enable AI with GitHub Models (free)
+    if (!cfg.ai?.enabled && process.env.REPOLENS_AI_ENABLED !== "true" && process.env.GITHUB_TOKEN) {
+      info("✨ GITHUB_TOKEN detected — enabling AI-enhanced docs via GitHub Models (free)");
+      cfg.ai = { enabled: true, provider: "github" };
+      process.env.REPOLENS_AI_ENABLED = "true";
+      process.env.REPOLENS_AI_PROVIDER = "github";
+    }
+
     // Load plugins
     let pluginManager;
     try {
@@ -472,6 +480,22 @@ async function main() {
       };
     }
     
+    // Auto-detect GITHUB_TOKEN and enable AI with GitHub Models (free)
+    const aiAlreadyConfigured = cfg.ai?.enabled || process.env.REPOLENS_AI_ENABLED === "true";
+    let aiAutoEnabled = false;
+    if (!aiAlreadyConfigured && process.env.GITHUB_TOKEN) {
+      info("\n✨ GITHUB_TOKEN detected — enabling AI-enhanced docs via GitHub Models (free)");
+      cfg.ai = { enabled: true, provider: "github" };
+      process.env.REPOLENS_AI_ENABLED = "true";
+      process.env.REPOLENS_AI_PROVIDER = "github";
+      aiAutoEnabled = true;
+    } else if (aiAlreadyConfigured) {
+      info("\n🤖 AI-enhanced documentation enabled");
+    } else {
+      info("\n📄 Running in deterministic mode (no GITHUB_TOKEN detected)");
+      info("   Set GITHUB_TOKEN to auto-enable free AI-enhanced docs via GitHub Models");
+    }
+    
     try {
       info("Scanning repository...");
       const scanTimer = startTimer("scan");
@@ -495,10 +519,24 @@ 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.");
+      if (aiAutoEnabled) {
+        info("\n🤖 AI-enhanced docs were generated using GitHub Models (free tier)");
+        info("   To keep AI enabled permanently, run: repolens init --interactive");
+      } else if (!cfg.ai?.enabled && process.env.REPOLENS_AI_ENABLED !== "true") {
+        info("\n─────────────────────────────────────────────────────────────────");
+        info("💡 Your docs are missing AI-enhanced sections:");
+        info("   • Executive Summary — plain language overview for leadership");
+        info("   • Business Domains — what the system does for stakeholders");
+        info("   • Architecture Overview — deeper narrative for architects");
+        info("   • Data Flows — how information moves through your system");
+        info("   • Developer Onboarding — getting started guide for new hires");
+        info("");
+        info("   To enable for FREE with GitHub Models:");
+        info("     export GITHUB_TOKEN=<your-token>");
+        info("     repolens demo");
+        info("");
+        info("   Or run: repolens init --interactive → select GitHub Models");
+        info("─────────────────────────────────────────────────────────────────");
       }
       
       printPerformanceSummary();
@@ -575,10 +613,12 @@ async function main() {
         info("\nCI/test environment detected — skipping confirmation (use --force to suppress this message).");
       } else {
         const rl = createInterface({ input: process.stdin, output: process.stdout });
-        const answer = await rl.question(`\nRemove ${found.length} item${found.length === 1 ? "" : "s"}? This cannot be undone. (y/N): `);
+        const answer = await new Promise((resolve) => {
+          rl.question(`\nRemove ${found.length} item${found.length === 1 ? "" : "s"}? This cannot be undone. (y/N): `, resolve);
+        });
         rl.close();
         
-        if (answer.trim().toLowerCase() !== "y") {
+        if (!answer || answer.trim().toLowerCase() !== "y") {
           info("Uninstall cancelled.");
           await closeTelemetry();
           return;

package/src/init.js

@@ -89,10 +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 }}
+          # AI-enhanced docs via GitHub Models (free)
+          REPOLENS_AI_ENABLED: true
+          REPOLENS_AI_PROVIDER: github
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
         run: npx @chappibunny/repolens@latest publish
 `;
 
@@ -324,9 +324,10 @@ function buildIgnorePatterns() {
   ];
 }
 
-function buildRepoLensConfig(projectName, detectedRoots) {
+function buildRepoLensConfig(projectName, detectedRoots, options = {}) {
   const includePatterns = buildIncludePatterns(detectedRoots);
   const ignorePatterns = buildIgnorePatterns();
+  const enableAI = options.enableAI || false;
 
   const lines = [
     `configVersion: 1`,
@@ -358,10 +359,35 @@ function buildRepoLensConfig(projectName, detectedRoots) {
     `#   owner: "your-username"`,
     `#   repo: "your-repo-name"`,
     ``,
-    `scan:`,
-    `  include:`
   ];
 
+  // AI configuration
+  if (enableAI) {
+    lines.push(`# AI-enhanced documentation (auto-detected GITHUB_TOKEN)`);
+    lines.push(`ai:`);
+    lines.push(`  enabled: true`);
+    lines.push(`  provider: github`);
+    lines.push(``);
+    lines.push(`features:`);
+    lines.push(`  executive_summary: true`);
+    lines.push(`  business_domains: true`);
+    lines.push(`  architecture_overview: true`);
+    lines.push(`  data_flows: true`);
+    lines.push(`  developer_onboarding: true`);
+    lines.push(`  change_impact: true`);
+    lines.push(``);
+  } else {
+    lines.push(`# AI-enhanced documentation (free via GitHub Models)`);
+    lines.push(`# Uncomment to enable — or set GITHUB_TOKEN and it auto-activates:`);
+    lines.push(`# ai:`);
+    lines.push(`#   enabled: true`);
+    lines.push(`#   provider: github`);
+    lines.push(``);
+  }
+
+  lines.push(`scan:`);
+  lines.push(`  include:`);
+
   if (includePatterns.length) {
     for (const pattern of includePatterns) {
       lines.push(`    - "${pattern}"`);
@@ -725,9 +751,12 @@ export async function runInit(targetDir = process.cwd(), options = {}) {
 
   const projectName = wizardAnswers?.projectName || detectProjectName(repoRoot);
   const detectedRoots = wizardAnswers ? [] : await detectRepoStructure(repoRoot);
+
+  // Auto-detect GITHUB_TOKEN for AI enablement
+  const hasGitHubToken = !!process.env.GITHUB_TOKEN;
   const configContent = wizardAnswers
     ? buildWizardConfig(wizardAnswers)
-    : buildRepoLensConfig(projectName, detectedRoots);
+    : buildRepoLensConfig(projectName, detectedRoots, { enableAI: hasGitHubToken });
 
   info(`Detected project name: ${projectName}`);
 
@@ -786,8 +815,11 @@ NOTION_VERSION=2022-06-28
   }
 
   info("\n✨ RepoLens initialization complete!\n");
-  
-  if (notionCredentials) {
+    if (hasGitHubToken && !wizardAnswers) {
+    info("🤖 Detected GITHUB_TOKEN — AI-enhanced docs enabled via GitHub Models (free)");
+    info("   Your workflow and config are pre-configured. No extra setup needed.\n");
+  }
+    if (notionCredentials) {
     info("🎉 Notion publishing is ready!");
     info("   Your credentials are stored in .env (gitignored)\n");
     info("Next steps:");
@@ -812,16 +844,18 @@ 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:");
-    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");
-    info("  4. Run 'npx @chappibunny/repolens publish' to test locally");
-    info("  5. Commit the generated files");
+    if (!hasGitHubToken) {
+      info("  3. (Optional) Enable AI features:");
+      info("     \u2500\u2500 FREE: GitHub Models (recommended for GitHub Actions) \u2500\u2500");
+      info("     REPOLENS_AI_ENABLED=true");
+      info("     REPOLENS_AI_PROVIDER=github");
+      info("     (Uses your GITHUB_TOKEN automatically \u2014 no API key signup needed)");
+      info("     \u2500\u2500 Or: OpenAI / Anthropic / Google \u2500\u2500");
+      info("     REPOLENS_AI_ENABLED=true");
+      info("     REPOLENS_AI_API_KEY=sk-...");
+      info("     See: https://github.com/CHAPIBUNNY/repolens/blob/main/AI.md");
+    }
+    info(`  ${hasGitHubToken ? "3" : "4"}. Run 'npx @chappibunny/repolens publish' to test locally`);
+    info(`  ${hasGitHubToken ? "4" : "5"}. Commit the generated files`);
   }
 }