explainthisrepo 0.9.6 → 0.10.0

package/README.md

@@ -20,6 +20,7 @@ ExplainThisRepo analyzes real project signals; configs, entrypoints, manifests,
 - Derives architectural summaries from repository structure and code signals.
 Not blind AI summarization.
 - Translates complex code structures into plain English
+- Speeds up understanding of unfamiliar codebases
 - Extract architecture signals from configs, entrypoints, and manifests
 - Works with GitHub repositories, local directories, private repositories, and monorepos
 - Outputs the explanation to an `EXPLAIN.md` file in your current directory or prints it directly in the terminal
@@ -46,6 +47,14 @@ pipx install explainthisrepo
 explainthisrepo owner/repo
 ```
 
+After installation, use any of the available commands:
+
+```bash
+explainthisrepo owner/repo
+explain-this-repo owner/repo
+etr owner/repo
+```
+
 To install support for specific models:
 
 ```bash
@@ -55,6 +64,8 @@ pip install explainthisrepo[anthropic]
 pip install explainthisrepo[groq]
 ```
 
+Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`, `torvalds/linux`).
+
 ### Option 2: Install with npm
 
 Install globally and use forever:
@@ -71,9 +82,9 @@ Or without install:
 
 ```bash
 npx explainthisrepo owner/repo
-```
 
-Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`).
+# npx explainthisrepo .
+```
 
 ### Option 3: Download standalone binary
 
@@ -126,6 +137,20 @@ explainthisrepo init
 
 > For details about how initialization works, see [INIT.md](INIT.md).
 
+## GitHub token Access (Private Repos & Rate Limits)
+
+ExplainThisRepo supports GitHub authentication for:
+
+- Accessing private repositories
+- Higher API rate limits on public repositories
+
+Run:
+
+```bash
+explainthisrepo init
+```
+
+For step-by-step instructions, see [docs/GITHUB_TOKEN.md](docs/GITHUB_TOKEN.md)
 
 ## Flag options
 
@@ -147,8 +172,6 @@ explainthisrepo init
 
 - `--llm` → Override provider selection
 
-- `--token/-t` → Set GitHub token for private repositories and to avoid rate limits
-
 ## Flexible Repository and Local Directory Input
 
 Accepts various formats for repository input, full GitHub URLs (with or without https), `owner/repo` format, issue links, query strings, and SSH clone links
@@ -165,6 +188,22 @@ explainthisrepo ./path/to/directory
 
 All inputs are normalized internally to `owner/repo`.
 
+## CLI aliases
+
+ExplainThisRepo ships with multiple command names that all map to the same entrypoint:
+
+- `explainthisrepo` → primary command
+- `explain-this-repo` → readable alias
+- `etr` → short alias for faster typing
+
+All three commands run the same tool and support the same flags and modes.
+
+```bash
+explainthisrepo owner/repo
+explain-this-repo owner/repo
+etr owner/repo
+```
+
 ## Model selection
 
 The `--llm` flag selects which configured model backend to use for the current command.
@@ -269,14 +308,6 @@ When analyzing a local directory:
 
 This allows analysis of projects directly from the local filesystem, without requiring a GitHub repository.
 
-### For private repositories, use the --token/-t option.
-
-Setting a `GITHUB_TOKEN` environment variable is recommended to avoid rate limits when analyzing public repositories.
-
-```bash
-export GITHUB_TOKEN=yourActualTokenHere
-```
-
 ### Version
 
 Check the installed CLI version:

package/dist/cli.js

@@ -93,8 +93,13 @@ async function runDoctor(llmOverride) {
     console.log(`os: ${os.type()} ${os.release()}`);
     console.log(`platform: ${process.platform} ${process.arch}`);
     console.log(`version: ${getPkgVersion()}`);
-    console.log("\nenvironment:");
-    console.log(`- GITHUB_TOKEN set: ${hasEnv("GITHUB_TOKEN")}`);
+    console.log("\ngithub auth:");
+    if (hasEnv("GITHUB_TOKEN") || hasEnv("GH_TOKEN")) {
+        console.log("-token: set");
+    }
+    else {
+        console.log("-token: not set (limited + no private repos)");
+    }
     console.log("\nnetwork checks:");
     const gh = await checkUrl("https://api.github.com");
     console.log(`- github api: ${gh.msg}`);
@@ -164,7 +169,7 @@ async function generateWithExit(prompt, llm) {
         console.error("Failed to generate explanation.");
         console.error(`error: ${message}`);
         console.error("\nfix:");
-        console.error("- Check that the provider name is correct (e.g. gemini, openai, ollama)");
+        console.error("- Check that the provider name is correct (e.g. gemini, openai, ollama, anthropic, openrouter)");
         console.error("- Ensure your API key is set for the selected provider");
         console.error("- Or run: explainthisrepo --doctor");
         process.exit(1);
@@ -258,7 +263,7 @@ async function runAnalysis(repository, options) {
             console.error("Failed to fetch repository data.");
             console.error(`error: ${message}`);
             console.error("\nfix:");
-            console.error("- Ensure the repository exists and is public");
+            console.error("- Run explainthisrepo init");
             console.error("- Or set GITHUB_TOKEN to avoid rate limits");
             process.exit(1);
         }
@@ -334,7 +339,7 @@ async function runAnalysis(repository, options) {
 const program = new Command();
 program
     .name("explainthisrepo")
-    .description("CLI that generates plain English explanations of any codebase")
+    .description("The fastest way to understand any codebase in plain English")
     .version(getPkgVersion(), "-v, --version", "Show version")
     .argument("[repository]", "GitHub repository (owner/repo or URL) or local directories")
     .option("--doctor", "Run diagnostics")
@@ -342,7 +347,7 @@ program
     .option("--simple", "Simple summary mode")
     .option("--detailed", "Detailed explanation mode")
     .option("--stack", "Stack detection mode")
-    .option("--llm <provider>", "LLM provider to use (e.g. gemini, openai, ollama). Overrides config default.")
+    .option("--llm <provider>", "LLM provider to use (e.g. gemini, openai, ollama, anthropic, openrouter). Overrides config default.")
     .addHelpText("after", `
 Examples:
   $ explainthisrepo owner/repo
@@ -362,7 +367,14 @@ Examples:
   $ explainthisrepo --doctor
   $ explainthisrepo --doctor --llm gemini
   $ explainthisrepo --doctor --llm openai
-  $ explainthisrepo --doctor --llm ollama`)
+  $ explainthisrepo --doctor --llm ollama
+  $ explainthisrepo --version
+  $ GitHub token:
+  $   Access private repos and higher rate limits
+  $   Run:
+  $     explainthisrepo init
+  $   Or set:
+  $     GITHUB_TOKEN=ghp_xxx explainthisrepo owner/repo`)
     .action(async (repository, options) => {
     if (options.doctor) {
         const code = await runDoctor(options.llm);

package/dist/github.d.ts

@@ -1,6 +1,6 @@
-export declare function fetchRepo(owner: string, repo: string): Promise<any>;
-export declare function fetchReadme(owner: string, repo: string): Promise<string | null>;
-export declare function fetchTree(owner: string, repo: string): Promise<any[]>;
-export declare function fetchFile(owner: string, repo: string, filePath: string): Promise<string>;
 export type RepoLanguageMap = Record<string, number>;
-export declare function fetchLanguages(owner: string, repo: string): Promise<RepoLanguageMap>;
+export declare function fetchRepo(owner: string, repo: string, token?: string): Promise<any>;
+export declare function fetchReadme(owner: string, repo: string, token?: string): Promise<string | null>;
+export declare function fetchTree(owner: string, repo: string, token?: string): Promise<any[]>;
+export declare function fetchFile(owner: string, repo: string, filePath: string, token?: string): Promise<string | null>;
+export declare function fetchLanguages(owner: string, repo: string, token?: string): Promise<RepoLanguageMap>;

package/dist/github.js

@@ -1,128 +1,300 @@
 import axios from "axios";
+import { loadConfig } from "./config.js";
 const GITHUB_API_BASE = "https://api.github.com";
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function getGithubHeaders() {
+function asNonEmptyString(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}
+function getGithubToken(overrideToken) {
+    const direct = asNonEmptyString(overrideToken);
+    if (direct) {
+        return direct;
+    }
+    try {
+        const cfg = (loadConfig() ?? {});
+        const githubCfg = cfg.github;
+        const configToken = asNonEmptyString(githubCfg?.token);
+        if (configToken) {
+            return configToken;
+        }
+    }
+    catch {
+    }
+    const envToken = asNonEmptyString(process.env.GITHUB_TOKEN || process.env.GH_TOKEN);
+    if (envToken) {
+        return envToken;
+    }
+    return null;
+}
+function createGithubClient(token) {
     const headers = {
-        Accept: "application/vnd.github.v3+json",
-        "User-Agent": "ExplainThisRepo",
+        Accept: "application/vnd.github+json",
+        "User-Agent": "explainthisrepo/1.0",
     };
-    const token = process.env.GITHUB_TOKEN || process.env.GITHUB_API_KEY;
-    if (token && token.trim()) {
-        headers.Authorization = `Bearer ${token.trim()}`;
+    const resolvedToken = getGithubToken(token);
+    if (resolvedToken) {
+        headers.Authorization = `Bearer ${resolvedToken}`;
     }
-    return headers;
+    return axios.create({
+        baseURL: GITHUB_API_BASE,
+        headers,
+        timeout: 10_000,
+    });
+}
+function isRateLimitText(text) {
+    const lower = typeof text === "string" ? text.toLowerCase() : "";
+    return (lower.includes("secondary rate limit") ||
+        lower.includes("rate limit"));
+}
+function rateLimitMessage(response) {
+    const reset = response?.headers?.["x-ratelimit-reset"];
+    if (typeof reset === "string" || typeof reset === "number") {
+        const resetTs = Number(reset);
+        if (!Number.isNaN(resetTs)) {
+            const waitSeconds = Math.max(0, resetTs * 1000 - Date.now()) / 1000;
+            const mins = Math.max(1, Math.ceil(waitSeconds / 60));
+            return ("GitHub API rate limit exceeded.\n" +
+                `Try again in ~${mins} minute(s).\n` +
+                "Fix:\n" +
+                "- Set GITHUB_TOKEN in config or environment\n" +
+                "- Or run `explainthisrepo init`\n");
+        }
+    }
+    return ("GitHub API rate limit exceeded.\n" +
+        "Fix:\n" +
+        "- Set GITHUB_TOKEN in config or environment\n" +
+        "- Or run `explainthisrepo init`\n");
+}
+function privateRepoMessage() {
+    return ("Repository not found.\n" +
+        "If this is a private repository, configure GitHub access:\n" +
+        "- Run `explainthisrepo init`\n" +
+        "- Or set GITHUB_TOKEN (see docs/GITHUB_TOKEN.md)\n");
 }
-const github = axios.create({
-    baseURL: GITHUB_API_BASE,
-    headers: getGithubHeaders(),
-    timeout: 12000,
-});
-function formatAxiosError(err) {
-    if (!axios.isAxiosError(err))
-        return "Unknown error";
+function formatJsonError(err) {
+    if (!axios.isAxiosError(err)) {
+        return `GitHub request failed: ${String(err)}`;
+    }
     const status = err.response?.status;
     const data = err.response?.data;
-    const msg = data?.message || err.message;
-    if (status === 404)
-        return "Repository not found (404). Check owner/repo.";
-    if (status === 401)
-        return "GitHub auth failed (401). Invalid GITHUB_TOKEN.";
-    if (status === 403 && typeof msg === "string" && msg.toLowerCase().includes("rate limit")) {
-        return "GitHub rate limit hit (403). Set GITHUB_TOKEN to increase limits.";
-    }
-    if (status === 429)
-        return "GitHub rate limit hit (429). Try again in a minute.";
-    if (status && status >= 500)
-        return `GitHub server error (${status}). Try again later.`;
-    return `GitHub request failed (${status ?? "no status"}): ${msg}`;
+    const message = typeof data?.message === "string" ? data.message : err.message;
+    if (status === 404) {
+        return privateRepoMessage();
+    }
+    if (status === 401) {
+        return "GitHub auth failed (401). Invalid GitHub token.";
+    }
+    if (status === 403) {
+        if (err.response?.headers?.["x-ratelimit-remaining"] === "0" ||
+            isRateLimitText(message)) {
+            return rateLimitMessage(err.response);
+        }
+        return "GitHub API access forbidden (403).";
+    }
+    if (status === 429) {
+        return rateLimitMessage(err.response);
+    }
+    if (status && status >= 500) {
+        return `GitHub API server error (${status}). Try again later.`;
+    }
+    if (status !== undefined) {
+        return `GitHub API request failed (${status}): ${message}`;
+    }
+    return `Network error while calling GitHub: ${message}`;
 }
-async function requestWithRetry(fn, opts) {
-    const maxRetries = opts?.maxRetries ?? 3;
+async function requestJson(client, url, opts) {
+    const maxRetries = opts?.maxRetries ?? 4;
     const baseDelayMs = opts?.baseDelayMs ?? 700;
     let attempt = 0;
-    while (true) {
+    let backoff = baseDelayMs;
+    while (attempt <= maxRetries) {
         try {
-            return await fn();
+            const response = await client.get(url, {
+                params: opts?.params,
+            });
+            return response.data;
         }
         catch (err) {
-            attempt += 1;
-            const isAxios = axios.isAxiosError(err);
-            const status = isAxios ? err.response?.status : undefined;
-            const retryable = status === 403 || status === 429 || (status !== undefined && status >= 500);
-            if (!retryable || attempt > maxRetries) {
-                throw new Error(formatAxiosError(err));
+            if (!axios.isAxiosError(err)) {
+                if (attempt >= maxRetries) {
+                    throw new Error(`Network error while calling GitHub: ${String(err)}`);
+                }
+                await sleep(backoff);
+                backoff *= 2;
+                attempt += 1;
+                continue;
+            }
+            const status = err.response?.status;
+            const data = err.response?.data;
+            const message = typeof data?.message === "string" ? data.message : err.message;
+            const remaining = err.response?.headers?.["x-ratelimit-remaining"];
+            if (status === 404) {
+                throw new Error(privateRepoMessage());
             }
-            const resetHeader = isAxios ? err.response?.headers?.["x-ratelimit-reset"] : undefined;
-            if ((status === 403 || status === 429) && resetHeader) {
-                const resetSeconds = Number(resetHeader);
-                if (!Number.isNaN(resetSeconds)) {
-                    const waitMs = Math.max(resetSeconds * 1000 - Date.now(), 1000);
-                    await sleep(Math.min(waitMs, 30_000));
+            if (status === 403 || status === 429) {
+                const rateLimited = remaining === "0" || isRateLimitText(message);
+                if (rateLimited) {
+                    if (attempt >= maxRetries) {
+                        throw new Error(rateLimitMessage(err.response));
+                    }
+                    await sleep(backoff);
+                    backoff *= 2;
+                    attempt += 1;
                     continue;
                 }
+                if (status === 429) {
+                    if (attempt >= maxRetries) {
+                        throw new Error(rateLimitMessage(err.response));
+                    }
+                    await sleep(backoff);
+                    backoff *= 2;
+                    attempt += 1;
+                    continue;
+                }
+                throw new Error("GitHub API access forbidden (403).");
+            }
+            if (status && status >= 500) {
+                if (attempt >= maxRetries) {
+                    throw new Error(`GitHub API server error (${status}). Try again later.`);
+                }
+                await sleep(backoff);
+                backoff *= 2;
+                attempt += 1;
+                continue;
+            }
+            if (status === undefined) {
+                if (attempt >= maxRetries) {
+                    throw new Error(`Network error while calling GitHub: ${message}`);
+                }
+                await sleep(backoff);
+                backoff *= 2;
+                attempt += 1;
+                continue;
             }
-            const delay = baseDelayMs * Math.pow(2, attempt - 1);
-            await sleep(Math.min(delay, 8000));
+            throw new Error(formatJsonError(err));
         }
     }
+    throw new Error("GitHub request failed unexpectedly.");
 }
-export async function fetchRepo(owner, repo) {
-    return requestWithRetry(async () => {
-        const res = await github.get(`/repos/${owner}/${repo}`);
-        return res.data;
-    });
-}
-export async function fetchReadme(owner, repo) {
-    try {
-        return await requestWithRetry(async () => {
-            const res = await github.get(`/repos/${owner}/${repo}/readme`, {
-                headers: {
-                    ...getGithubHeaders(),
-                    Accept: "application/vnd.github.v3.raw",
-                },
+async function requestText(client, url, opts) {
+    const accept = opts?.accept ?? "application/vnd.github.v3.raw";
+    const maxRetries = opts?.maxRetries ?? 4;
+    const baseDelayMs = opts?.baseDelayMs ?? 700;
+    let attempt = 0;
+    let backoff = baseDelayMs;
+    while (attempt <= maxRetries) {
+        try {
+            const response = await client.get(url, {
+                params: opts?.params,
+                headers: { Accept: accept },
+                responseType: "text",
+                transformResponse: [(data) => data],
             });
-            return res.data;
-        });
-    }
-    catch (err) {
-        if (axios.isAxiosError(err)) {
+            return typeof response.data === "string" ? response.data : String(response.data ?? "");
+        }
+        catch (err) {
+            if (!axios.isAxiosError(err)) {
+                if (attempt >= maxRetries) {
+                    return null;
+                }
+                await sleep(backoff);
+                backoff *= 2;
+                attempt += 1;
+                continue;
+            }
             const status = err.response?.status;
-            if (status === 404)
+            const data = err.response?.data;
+            const message = typeof data?.message === "string" ? data.message : err.message;
+            const remaining = err.response?.headers?.["x-ratelimit-remaining"];
+            if (status === 404) {
+                return null;
+            }
+            if (status === 403 || status === 429) {
+                const rateLimited = remaining === "0" || isRateLimitText(message);
+                if (rateLimited) {
+                    if (attempt >= maxRetries) {
+                        return null;
+                    }
+                    await sleep(backoff);
+                    backoff *= 2;
+                    attempt += 1;
+                    continue;
+                }
                 return null;
+            }
+            if (status && status >= 500) {
+                if (attempt >= maxRetries) {
+                    return null;
+                }
+                await sleep(backoff);
+                backoff *= 2;
+                attempt += 1;
+                continue;
+            }
+            return null;
         }
-        throw err;
     }
+    return null;
 }
-export async function fetchTree(owner, repo) {
-    return requestWithRetry(async () => {
-        const repoRes = await github.get(`/repos/${owner}/${repo}`);
-        const defaultBranch = repoRes.data?.default_branch;
-        const res = await github.get(`/repos/${owner}/${repo}/git/trees/${defaultBranch}`, {
-            params: { recursive: 1 },
-        });
-        return (res.data?.tree || []).map((item) => ({
-            path: item.path,
-            type: item.type,
-            size: item.size,
-        }));
-    });
+export async function fetchRepo(owner, repo, token) {
+    const client = createGithubClient(token);
+    return requestJson(client, `/repos/${owner}/${repo}`);
 }
-export async function fetchFile(owner, repo, filePath) {
-    return requestWithRetry(async () => {
-        const res = await github.get(`/repos/${owner}/${repo}/contents/${filePath}`, {
-            headers: {
-                ...getGithubHeaders(),
-                Accept: "application/vnd.github.v3.raw",
-            },
-        });
-        return res.data;
+export async function fetchReadme(owner, repo, token) {
+    const client = createGithubClient(token);
+    const apiUrl = `/repos/${owner}/${repo}/readme`;
+    const text = await requestText(client, apiUrl, {
+        accept: "application/vnd.github.v3.raw",
+        maxRetries: 4,
     });
+    if (text) {
+        return text;
+    }
+    const branches = ["main", "master"];
+    const filenames = ["README.md", "readme.md", "README.MD"];
+    for (const branch of branches) {
+        for (const name of filenames) {
+            const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${name}`;
+            const raw = await requestText(client, rawUrl, {
+                accept: "text/plain",
+                maxRetries: 2,
+            });
+            if (raw) {
+                return raw;
+            }
+        }
+    }
+    return null;
 }
-export async function fetchLanguages(owner, repo) {
-    return requestWithRetry(async () => {
-        const res = await github.get(`/repos/${owner}/${repo}/languages`);
-        return res.data;
+export async function fetchTree(owner, repo, token) {
+    const client = createGithubClient(token);
+    const repoMeta = await fetchRepo(owner, repo, token);
+    const defaultBranch = repoMeta?.default_branch || "main";
+    const data = await requestJson(client, `/repos/${owner}/${repo}/git/trees/${defaultBranch}`, { params: { recursive: 1 } });
+    const tree = data?.tree || [];
+    if (!Array.isArray(tree)) {
+        return [];
+    }
+    return tree.map((item) => ({
+        path: item.path,
+        type: item.type,
+        size: item.size,
+    }));
+}
+export async function fetchFile(owner, repo, filePath, token) {
+    const client = createGithubClient(token);
+    return requestText(client, `/repos/${owner}/${repo}/contents/${filePath}`, {
+        accept: "application/vnd.github.v3.raw",
+        maxRetries: 2,
     });
 }
+export async function fetchLanguages(owner, repo, token) {
+    const client = createGithubClient(token);
+    return requestJson(client, `/repos/${owner}/${repo}/languages`);
+}

package/dist/init.js

@@ -12,10 +12,11 @@ const PROVIDERS = {
 };
 export async function runInit() {
     const err = process.stderr;
-    err.write(chalk.yellow("WARNING: input is hidden where applicable. Configuration will be written once.\n\n"));
+    err.write(chalk.yellow("WARNING: input is hidden where applicable. Configuration will be written once.\n"));
     try {
         const provider = await promptProvider();
         const providerConfig = await promptProviderConfig(provider);
+        const githubToken = await promptGithubToken();
         const lines = [
             "[llm]",
             `provider = "${provider}"`,
@@ -25,6 +26,11 @@ export async function runInit() {
         for (const [k, v] of Object.entries(providerConfig)) {
             lines.push(`${k} = "${v}"`);
         }
+        if (githubToken) {
+            lines.push("");
+            lines.push("[github]");
+            lines.push(`token = "${githubToken}"`);
+        }
         const contents = lines.join("\n") + "\n";
         writeConfig(contents);
         err.write(chalk.green("Configuration written.\n"));
@@ -68,12 +74,6 @@ async function promptProviderConfig(provider) {
             throw new Error("API key cannot be empty");
         return { api_key: key };
     }
-    if (provider === "anthropic") {
-        const key = (await promptHidden("Anthropic (Claude) API key: ")).trim();
-        if (!key)
-            throw new Error("API key cannot be empty");
-        return { api_key: key };
-    }
     if (provider === "ollama") {
         const model = (await prompt("Ollama model (e.g. llama3, glm-5:cloud, gemma3:4b): ")).trim();
         if (!model)
@@ -82,6 +82,12 @@ async function promptProviderConfig(provider) {
             "http://localhost:11434";
         return { model, host };
     }
+    if (provider === "anthropic") {
+        const key = (await promptHidden("Anthropic (Claude) API key: ")).trim();
+        if (!key)
+            throw new Error("API key cannot be empty");
+        return { api_key: key };
+    }
     if (provider === "groq") {
         const key = (await promptHidden("Groq API key: ")).trim();
         if (!key)
@@ -142,6 +148,15 @@ async function promptProviderConfig(provider) {
     }
     throw new Error(`Unsupported provider: ${provider}`);
 }
+async function promptGithubToken() {
+    const err = process.stderr;
+    err.write(chalk.cyan("\nConfigure GitHub access for private repos and higher rate limits:\n"));
+    const token = (await promptHidden("GitHub token (leave empty to skip): ")).trim();
+    if (!token) {
+        return null;
+    }
+    return token;
+}
 function prompt(label) {
     const rl = readline.createInterface({
         input: process.stdin,

package/dist/repo_reader.js

@@ -134,6 +134,8 @@ export async function readRepoSignalFiles(owner, repo) {
             continue;
         try {
             const content = await fetchFile(owner, repo, path);
+            if (!content)
+                continue;
             keyFiles[path] = content.slice(0, 20000);
         }
         catch { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explainthisrepo",
-  "version": "0.9.6",
+  "version": "0.10.0",
   "description": "The fastest way to understand any codebase in plain English. Not blind AI summarization",
   "license": "MIT",
   "type": "module",