explainthisrepo 0.3.0 → 0.4.1

package/dist/cli.js

@@ -4,31 +4,15 @@ import process from "node:process";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { Command } from "commander";
 import { fetchRepo, fetchReadme } from "./github.js";
-import { buildPrompt, buildSimplePrompt } from "./prompt.js";
+import { buildPrompt, buildQuickPrompt, buildSimplePrompt } from "./prompt.js";
 import { generateExplanation } from "./generate.js";
 import { writeOutput } from "./writer.js";
 import { readRepoSignalFiles } from "./repo_reader.js";
 import { fetchLanguages } from "./github.js";
 import { detectStack } from "./stack-detector.js";
 import { printStack } from "./stack_printer.js";
-function usage() {
-    const version = getPkgVersion();
-    console.log(`ExplainThisRepo v${version}`);
-    console.log("Explain GitHub repositories in plain English.\n");
-    console.log("usage:");
-    console.log("  explainthisrepo owner/repo");
-    console.log("  explainthisrepo https://github.com/owner/repo");
-    console.log("  explainthisrepo github.com/owner/repo");
-    console.log("  explainthisrepo git@github.com:owner/repo.git");
-    console.log("  explainthisrepo owner/repo --detailed");
-    console.log("  explainthisrepo owner/repo --quick");
-    console.log("  explainthisrepo owner/repo --simple");
-    console.log("  explainthisrepo owner/repo --stack");
-    console.log("  explainthisrepo --doctor");
-    console.log("  explainthisrepo --version");
-    console.log("  explainthisrepo --help");
-}
 function resolveRepoTarget(target) {
     target = target.trim();
     if (target.startsWith("https//")) {
@@ -117,134 +101,170 @@ async function runDoctor() {
     console.log(`- github api: ${gh.msg}`);
     const gem = await checkUrl("https://generativelanguage.googleapis.com");
     console.log(`- gemini endpoint: ${gem.msg}`);
-    return gh.ok ? 0 : 1;
+    return gh.ok && gem.ok ? 0 : 1;
 }
 async function main() {
-    const args = process.argv.slice(2);
-    if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
-        usage();
-        process.exit(0);
-    }
-    if (args[0] === "--version") {
-        printVersion();
-        process.exit(0);
-    }
-    if (args[0] === "--doctor") {
+    const program = new Command();
+    program
+        .name("explainthisrepo")
+        .description("Explain GitHub repositories in plain English")
+        .version(getPkgVersion(), "-v, --version", "Show version")
+        .argument("[repository]", "GitHub repository (owner/repo or URL)")
+        .option("--doctor", "Run diagnostics")
+        .option("--quick", "Quick summary mode")
+        .option("--simple", "Simple summary mode")
+        .option("--detailed", "Detailed explanation mode")
+        .option("--stack", "Stack detection mode")
+        .addHelpText("after", `
+Examples:
+  $ explainthisrepo owner/repo
+  $ explainthisrepo https://github.com/owner/repo
+  $ explainthisrepo github.com/owner/repo
+  $ explainthisrepo git@github.com:owner/repo.git
+  $ explainthisrepo owner/repo --detailed
+  $ explainthisrepo owner/repo --quick
+  $ explainthisrepo owner/repo --simple
+  $ explainthisrepo owner/repo --stack
+  $ explainthisrepo --doctor`);
+    program.parse(process.argv);
+    const options = program.opts();
+    const repository = program.args[0];
+    if (options.doctor) {
         const code = await runDoctor();
         process.exit(code);
     }
-    let detailed = false;
-    let quick = false;
-    let simple = false;
-    let stack = false;
-    if (args.length === 2) {
-        if (args[1] === "--detailed")
-            detailed = true;
-        else if (args[1] === "--quick")
-            quick = true;
-        else if (args[1] === "--simple")
-            simple = true;
-        else if (args[1] === "--stack")
-            stack = true;
-        else {
-            usage();
-            process.exit(1);
-        }
-    }
-    else if (args.length !== 1) {
-        usage();
+    const modeFlags = [
+        options.quick,
+        options.simple,
+        options.detailed,
+        options.stack,
+    ].filter(Boolean);
+    if (modeFlags.length > 1) {
+        console.error("error: only one mode flag can be used at a time");
         process.exit(1);
     }
-    if ((quick && simple) ||
-        (detailed && simple) ||
-        (detailed && quick) ||
-        (stack && (quick || simple || detailed))) {
-        usage();
-        process.exit(1);
+    if (!repository) {
+        program.error("repository argument required");
     }
     let owner, repo;
     try {
-        ({ owner, repo } = resolveRepoTarget(args[0]));
+        ({ owner, repo } = resolveRepoTarget(repository));
     }
     catch (e) {
-        console.log(`error: ${e.message}`);
-        process.exit(1);
-    }
-    if (!owner || !repo) {
-        console.log("Invalid format. Use owner/repo");
+        console.error(`error: ${e.message}`);
         process.exit(1);
     }
     console.log(`Fetching ${owner}/${repo}...`);
-    if (stack) {
-        const languages = await fetchLanguages(owner, repo);
-        const read = await readRepoSignalFiles(owner, repo);
-        const report = detectStack({
-            languages,
-            tree: read.tree,
-            keyFiles: read.keyFiles,
-        });
-        printStack(report, owner, repo);
-        return;
-    }
-    try {
-        let repoData;
+    if (options.stack) {
         try {
-            repoData = await fetchRepo(owner, repo);
+            const languages = await fetchLanguages(owner, repo);
+            const read = await readRepoSignalFiles(owner, repo);
+            const report = detectStack({
+                languages,
+                tree: read.tree,
+                keyFiles: read.keyFiles,
+            });
+            printStack(report, owner, repo);
+            return;
         }
         catch (e) {
-            console.log("Failed to fetch repository data.");
-            console.log(`error: ${e?.message || e}`);
-            console.log("\nfix:");
-            console.log("- Ensure the repository exists and is public");
-            console.log("- Or set GITHUB_TOKEN to avoid rate limits");
+            console.error(`error: ${e?.message || e}`);
             process.exit(1);
         }
-        let readme = null;
+    }
+    let repoData;
+    try {
+        repoData = await fetchRepo(owner, repo);
+    }
+    catch (e) {
+        console.error("Failed to fetch repository data.");
+        console.error(`error: ${e?.message || e}`);
+        console.error("\nfix:");
+        console.error("- Ensure the repository exists and is public");
+        console.error("- Or set GITHUB_TOKEN to avoid rate limits");
+        process.exit(1);
+    }
+    let readme = null;
+    try {
+        readme = await fetchReadme(owner, repo);
+    }
+    catch (e) {
+        console.warn(`Warning: Could not fetch README: ${e?.message || e}`);
+        readme = null;
+    }
+    if (options.quick) {
+        const prompt = buildQuickPrompt(repoData.full_name, repoData.description, readme);
+        console.log("Generating explanation...");
+        let output;
         try {
-            readme = await fetchReadme(owner, repo);
+            output = await generateExplanation(prompt);
         }
-        catch {
-            readme = null;
+        catch (e) {
+            console.error("Failed to generate explanation.");
+            console.error(`error: ${e?.message || e}`);
+            console.error("\nfix:");
+            console.error("- Ensure GEMINI_API_KEY is set");
+            console.error("- Or run: explainthisrepo --doctor");
+            process.exit(1);
         }
+        console.log("Quick summary 🎉");
+        console.log(output.trim());
+        return;
+    }
+    if (options.simple) {
         let readResult = null;
-        if (!quick) {
-            try {
-                readResult = await readRepoSignalFiles(owner, repo);
-            }
-            catch {
-                readResult = null;
-            }
+        try {
+            readResult = await readRepoSignalFiles(owner, repo);
         }
-        const prompt = buildPrompt(repoData.full_name, repoData.description, readme, detailed, quick, readResult?.treeText ?? null, readResult?.filesText ?? null);
+        catch (e) {
+            console.warn(`Warning: Could not read repo files: ${e?.message || e}`);
+            readResult = null;
+        }
+        const prompt = buildSimplePrompt(repoData.full_name, repoData.description, readme, readResult?.treeText ?? null);
         console.log("Generating explanation...");
-        const output = await generateExplanation(prompt);
-        if (quick) {
-            console.log("Quick summary 🎉");
-            console.log(output.trim());
-            return;
+        let output;
+        try {
+            output = await generateExplanation(prompt);
         }
-        if (simple) {
-            console.log("Summarizing...");
-            const simplePrompt = buildSimplePrompt(output);
-            const simpleOutput = await generateExplanation(simplePrompt);
-            console.log("Simple summary 🎉");
-            console.log(simpleOutput.trim());
-            return;
+        catch (e) {
+            console.error("Failed to generate explanation.");
+            console.error(`error: ${e?.message || e}`);
+            console.error("\nfix:");
+            console.error("- Ensure GEMINI_API_KEY is set");
+            console.error("- Or run: explainthisrepo --doctor");
+            process.exit(1);
         }
-        console.log("Writing EXPLAIN.md...");
-        writeOutput(output);
-        const wordCount = output.split(/\s+/).filter(Boolean).length;
-        console.log("EXPLAIN.md generated successfully 🎉");
-        console.log(`Words: ${wordCount}`);
-        console.log("Open EXPLAIN.md to read it.");
+        console.log("Simple summary 🎉");
+        console.log(output.trim());
+        return;
+    }
+    let readResult = null;
+    try {
+        readResult = await readRepoSignalFiles(owner, repo);
+    }
+    catch (e) {
+        console.warn(`Warning: Could not read repo files: ${e?.message || e}`);
+        readResult = null;
+    }
+    const prompt = buildPrompt(repoData.full_name, repoData.description, readme, options.detailed || false, readResult?.treeText ?? null, readResult?.filesText ?? null);
+    console.log("Generating explanation...");
+    let output;
+    try {
+        output = await generateExplanation(prompt);
     }
     catch (e) {
-        console.log("Failed to generate explanation.");
-        console.log(`error: ${e?.message || e}`);
-        console.log("\nfix:");
-        console.log("- Ensure GEMINI_API_KEY is set");
-        console.log("- Or run: explainthisrepo --doctor");
+        console.error("Failed to generate explanation.");
+        console.error(`error: ${e?.message || e}`);
+        console.error("\nfix:");
+        console.error("- Ensure GEMINI_API_KEY is set");
+        console.error("- Or run: explainthisrepo --doctor");
         process.exit(1);
     }
+    console.log("Writing EXPLAIN.md...");
+    writeOutput(output);
+    const wordCount = output.split(/\s+/).filter(Boolean).length;
+    console.log("EXPLAIN.md generated successfully 🎉");
+    console.log(`Words: ${wordCount}`);
+    console.log("Open EXPLAIN.md to read it.");
 }
 main();

package/dist/prompt.d.ts

@@ -1,2 +1,3 @@
-export declare function buildPrompt(repoName: string, description: string | null, readme: string | null, detailed?: boolean, quick?: boolean, treeText?: string | null, filesText?: string | null): string;
-export declare function buildSimplePrompt(longExplanation: string): string;
+export declare function buildPrompt(repoName: string, description: string | null, readme: string | null, detailed?: boolean, treeText?: string | null, filesText?: string | null): string;
+export declare function buildQuickPrompt(repoName: string, description: string | null, readme: string | null): string;
+export declare function buildSimplePrompt(repoName: string, description: string | null, readme: string | null, treeText?: string | null): string;

package/dist/prompt.js

@@ -1,28 +1,4 @@
-export function buildPrompt(repoName, description, readme, detailed = false, quick = false, treeText = null, filesText = null) {
-    if (quick) {
-        const readmeSnippet = (readme || "").slice(0, 2000);
-        return `
-You are a senior software engineer.
-
-Write a ONE-SENTENCE plain-English definition of what this GitHub repository is.
-
-Repository:
-- Name: ${repoName}
-- Description: ${description || "No description provided"}
-
-README snippet:
-${readmeSnippet || "No README provided"}
-
-Rules:
-- Output MUST be exactly 1 sentence.
-- Plain English.
-- No markdown.
-- No quotes.
-- No bullet points.
-- No extra text.
-- Do not add features not stated in the description/README.
-`.trim();
-    }
+export function buildPrompt(repoName, description, readme, detailed = false, treeText = null, filesText = null) {
     let prompt = `You are a senior software engineer.
 
 Your task is to explain a GitHub repository clearly and concisely for a human reader.
@@ -34,10 +10,10 @@ Repository:
 README content:
 ${readme || "No README provided"}
 
-Repository structure:
-${treeText || "No tree provided"}
+Repo structure:
+${treeText || "No file tree provided"}
 
-Key files (snippets):
+Key code files:
 ${filesText || "No code files provided"}
 
 Instructions:
@@ -70,14 +46,46 @@ Output format:
 `;
     return prompt.trim();
 }
-export function buildSimplePrompt(longExplanation) {
-    return `
-You are a senior software engineer.
+export function buildQuickPrompt(repoName, description, readme) {
+    const readmeSnippet = (readme || "No README provided").slice(0, 2000);
+    const prompt = `You are a senior software engineer.
+
+Write a ONE-SENTENCE plain-English definition of what this GitHub repository is.
+
+Repository:
+- Name: ${repoName}
+- Description: ${description || "No description provided"}
+
+README snippet:
+${readmeSnippet}
+
+Rules:
+- Output MUST be exactly 1 sentence.
+- Plain English.
+- No markdown.
+- No quotes.
+- No bullet points.
+- No extra text.
+- Do not add features not stated in the description/README.
+`;
+    return prompt.trim();
+}
+export function buildSimplePrompt(repoName, description, readme, treeText = null) {
+    const readmeContent = (readme || "No README provided").slice(0, 4000);
+    const treeContent = (treeText || "No file tree provided").slice(0, 1500);
+    const prompt = `You are a senior software engineer.
+
+Summarize this GitHub repository in a concise bullet-point format.
+
+Repository:
+- Name: ${repoName}
+- Description: ${description || "No description provided"}
 
-Rewrite the long repository explanation below into a SIMPLE version in the exact style specified.
+README content:
+${readmeContent}
 
-Input explanation:
-${longExplanation}
+Repo structure:
+${treeContent}
 
 Output style rules:
 - Plain English.
@@ -89,13 +97,13 @@ Key points from the repo:
 - Each bullet MUST start with: ⬤
 - Each bullet title should be 1–3 words only (example: "Purpose", "Stack", "Entrypoints", "How it works", "Usage", "Structure").
 - Each bullet body should be 1–2 lines max.
-- If the input contains architecture/pipeline steps, capture them naturally.
-- If the input does NOT contain architecture/pipeline steps, do NOT invent them.
+- Base bullets strictly on the provided README and structure.
+- Do NOT invent features, architecture, or details not present in the input.
 - Optional: end with one extra line starting with:
 Also interesting:
-- Do NOT add features not present in the input.
 - No quotes.
 
 Make it feel like a human developer explaining to another developer in simple terms.
-`.trim();
+`;
+    return prompt.trim();
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "explainthisrepo",
-  "version": "0.3.0",
-  "description": "ExplainThisRepo is a CLI developer tool to explain any GitHub repository in plain English",
+  "version": "0.4.1",
+  "description": "A CLI developer tool to explain any GitHub repository in plain English",
   "license": "MIT",
   "type": "module",
   "author": "Caleb Wodi <calebwodi33@gmail.com>",
@@ -40,11 +40,12 @@
     "prepublishOnly": "npm run build"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "dependencies": {
     "@google/generative-ai": "^0.24.1",
     "axios": "^1.13.2",
+    "commander": "^14.0.3",
     "dotenv": "^17.2.3"
   },
   "devDependencies": {