explainthisrepo 0.9.6 → 0.20.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
@@ -27,7 +28,7 @@ Not blind AI summarization.
 
 ## Installation
 
-### Option 1: install with pip (recommended):
+### Option 1: install with pip (Python source version):
 
 Requirements: Python 3.9+
 
@@ -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,7 +64,9 @@ pip install explainthisrepo[anthropic]
 pip install explainthisrepo[groq]
 ```
 
-### Option 2: Install with npm
+Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`, `torvalds/linux`).
+
+### Option 2: Install with npm (prebuilt binary, no Python required)
 
 Install globally and use forever:
 
@@ -71,9 +82,19 @@ Or without install:
 
 ```bash
 npx explainthisrepo owner/repo
+
+# npx explainthisrepo .
 ```
 
-Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`).
+## How it works
+
+ExplainThisRepo uses a hybrid architecture:
+
+- Python → core implementaion (analysis, prompts, providers, output)
+- npm → ships prebuilt native binaries (no Python required)
+- pip → installs the full Python package
+
+> The npm and pip versions run the same core engine.
 
 ### Option 3: Download standalone binary
 
@@ -124,8 +145,22 @@ explainthisrepo init
 # or npx explainthisrepo init
 ```
 
-> For details about how initialization works, see [INIT.md](INIT.md).
+> For details about how initialization works, see [docs/INIT.md](docs/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 +182,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 +198,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 +318,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

@@ -1,383 +1,51 @@
 #!/usr/bin/env node
-import os from "node:os";
-import process from "node:process";
 import fs from "node:fs";
-import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import path from "node:path";
+import process from "node:process";
 import { fileURLToPath } from "node:url";
-import { Command } from "commander";
-import ora from "ora";
-import { runInit } from "./init.js";
-import { fetchRepo, fetchReadme } from "./github.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 { readLocalRepoSignalFiles } from "./local_reader.js";
-import { fetchLanguages } from "./github.js";
-import { detectStack } from "./stack-detector.js";
-import { printStack } from "./stack_printer.js";
-function resolveRepoTarget(target) {
-    target = target.trim();
-    if (target.startsWith("https//")) {
-        target = target.replace("https//", "https://");
-    }
-    if (target.startsWith("http//")) {
-        target = target.replace("http//", "http://");
-    }
-    if (target.startsWith("git@github.com:")) {
-        const p = target.replace("git@github.com:", "");
-        const [owner, repoRaw] = p.split("/", 2);
-        if (!owner || !repoRaw)
-            throw new Error("Invalid GitHub SSH URL");
-        return { owner, repo: repoRaw.replace(/\.git$/, "") };
-    }
-    if (target.startsWith("github.com/")) {
-        target = "https://" + target;
-    }
-    if (target.startsWith("http://") || target.startsWith("https://")) {
-        const url = new URL(target);
-        if (!["github.com", "www.github.com"].includes(url.hostname)) {
-            throw new Error("Only GitHub repository URLs are supported");
-        }
-        const parts = url.pathname.split("/").filter(Boolean);
-        if (parts.length < 2) {
-            throw new Error("URL must point to a repository");
-        }
-        return { owner: parts[0], repo: parts[1].replace(/\.git$/, "") };
-    }
-    const parts = target.split("/");
-    if (parts.length === 2 && parts[0] && parts[1]) {
-        return { owner: parts[0], repo: parts[1] };
-    }
-    throw new Error("Invalid format. Use owner/repo or a GitHub repo URL");
-}
-function getPkgVersion() {
-    try {
-        const __filename = fileURLToPath(import.meta.url);
-        const __dirname = path.dirname(__filename);
-        const pkgPath = path.join(__dirname, "..", "package.json");
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-        return pkg.version ?? "unknown";
-    }
-    catch {
-        return "unknown";
-    }
-}
-function hasEnv(key) {
-    const v = process.env[key];
-    return Boolean(v && v.trim());
-}
-async function checkUrl(url, timeoutMs = 6000) {
-    const controller = new AbortController();
-    const t = setTimeout(() => controller.abort(), timeoutMs);
+function getTargetKey() {
+    const platform = process.platform;
+    const arch = process.arch;
+    if (platform === "darwin" && arch === "x64")
+        return "darwin-x64";
+    if (platform === "darwin" && arch === "arm64")
+        return "darwin-arm64";
+    if (platform === "linux" && arch === "x64")
+        return "linux-x64";
+    if (platform === "linux" && arch === "arm64")
+        return "linux-arm64";
+    if (platform === "win32" && arch === "x64")
+        return "win-x64";
+    throw new Error(`Unsupported platform: ${platform} ${arch}`);
+}
+function getBinaryName() {
+    return process.platform === "win32" ? "explainthisrepo.exe" : "explainthisrepo";
+}
+function getBinaryPath() {
+    const launcherDir = path.dirname(fileURLToPath(import.meta.url));
+    const binaryPath = path.join(launcherDir, "native", getTargetKey(), getBinaryName());
+    if (!fs.existsSync(binaryPath)) {
+        throw new Error(`Bundled binary not found: ${binaryPath}`);
+    }
+    return binaryPath;
+}
+function main() {
     try {
-        const res = await fetch(url, {
-            method: "GET",
-            headers: { "User-Agent": "explainthisrepo" },
-            signal: controller.signal,
+        const binaryPath = getBinaryPath();
+        const result = spawnSync(binaryPath, process.argv.slice(2), {
+            stdio: "inherit",
+            windowsHide: true,
         });
-        clearTimeout(t);
-        return { ok: res.ok, msg: `ok (${res.status})` };
-    }
-    catch (e) {
-        clearTimeout(t);
-        const message = e instanceof Error ? e.message : String(e);
-        const name = e instanceof Error ? e.name : "Error";
-        return { ok: false, msg: `failed (${name}: ${message})` };
-    }
-}
-async function runDoctor(llmOverride) {
-    console.log("explainthisrepo doctor report\n");
-    console.log(`node: ${process.version}`);
-    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("\nnetwork checks:");
-    const gh = await checkUrl("https://api.github.com");
-    console.log(`- github api: ${gh.msg}`);
-    console.log("\nprovider diagnostics:");
-    let providerOk = true;
-    try {
-        const { getActiveProvider } = await import("./providers/registry.js");
-        const provider = await getActiveProvider(llmOverride);
-        const providerName = provider.name ?? llmOverride ?? "unknown";
-        console.log(`- active provider: ${providerName}`);
-        const doctorFn = provider.doctor;
-        if (typeof doctorFn === "function") {
-            const result = await doctorFn.call(provider);
-            if (typeof result === "boolean") {
-                console.log(`- ${providerName}: ${result ? "ok" : "checks did not pass"}`);
-                providerOk = result;
-            }
-            else if (Array.isArray(result)) {
-                if (result.length === 0) {
-                    console.log(`- ${providerName}: ok`);
-                }
-                else {
-                    for (const line of result) {
-                        console.log(`- ${providerName}: ${line}`);
-                    }
-                    providerOk = false;
-                }
-            }
-            else {
-                console.log(`- ${providerName}: ok`);
-            }
-        }
-        else {
-            console.log(`- ${providerName}: no diagnostics implemented`);
+        if (result.error) {
+            throw result.error;
         }
+        process.exit(result.status ?? 1);
     }
-    catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        if (llmOverride) {
-            console.log(`- provider '${llmOverride}' could not be resolved`);
-            console.log("- check that the provider name is correct and properly configured");
-        }
-        else {
-            console.log(`- provider registry error: ${message}`);
-            console.log("- run `explainthisrepo init` to configure a provider");
-        }
-        providerOk = false;
-    }
-    return gh.ok && providerOk ? 0 : 1;
-}
-async function safeReadRepoFiles(owner, repo) {
-    try {
-        return await readRepoSignalFiles(owner, repo);
-    }
-    catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        console.warn(`Warning: Could not read repo files: ${message}`);
-        return null;
-    }
-}
-async function generateWithExit(prompt, llm) {
-    try {
-        return await generateExplanation(prompt, llm);
-    }
-    catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        console.error("Failed to generate explanation.");
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
         console.error(`error: ${message}`);
-        console.error("\nfix:");
-        console.error("- Check that the provider name is correct (e.g. gemini, openai, ollama)");
-        console.error("- Ensure your API key is set for the selected provider");
-        console.error("- Or run: explainthisrepo --doctor");
-        process.exit(1);
-    }
-}
-async function runAnalysis(repository, options) {
-    if (options.doctor) {
-        const code = await runDoctor(options.llm);
-        process.exit(code);
-    }
-    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);
     }
-    const local = fs.existsSync(repository);
-    let owner = "";
-    let repo = "";
-    let localPath = "";
-    if (local) {
-        localPath = path.resolve(repository);
-        console.log(`Analyzing local directory: ${repository}`);
-    }
-    else {
-        try {
-            ({ owner, repo } = resolveRepoTarget(repository));
-        }
-        catch (e) {
-            const message = e instanceof Error ? e.message : String(e);
-            console.error(`error: ${message}`);
-            process.exit(1);
-        }
-    }
-    if (options.stack) {
-        let read;
-        let languages = {};
-        if (local) {
-            const spinner = ora("Reading repository files…").start();
-            try {
-                read = readLocalRepoSignalFiles(localPath);
-                spinner.stop();
-            }
-            catch (e) {
-                spinner.stop();
-                const message = e instanceof Error ? e.message : String(e);
-                console.error(`error: ${message}`);
-                process.exit(1);
-            }
-        }
-        else {
-            const spinner = ora(`Fetching ${owner}/${repo}…`).start();
-            try {
-                languages = await fetchLanguages(owner, repo);
-                read = await readRepoSignalFiles(owner, repo);
-                spinner.stop();
-            }
-            catch (e) {
-                spinner.stop();
-                const message = e instanceof Error ? e.message : String(e);
-                console.error(`error: ${message}`);
-                process.exit(1);
-            }
-        }
-        const report = detectStack({
-            languages,
-            tree: read.tree,
-            keyFiles: read.keyFiles,
-        });
-        const label = local ? repository : owner;
-        const sublabel = local ? "" : repo;
-        printStack(report, label, sublabel);
-        return;
-    }
-    let repoData = null;
-    let readme = null;
-    if (!local) {
-        const spinner = ora(`Fetching ${owner}/${repo}…`).start();
-        try {
-            repoData = await fetchRepo(owner, repo);
-            readme = await fetchReadme(owner, repo);
-            spinner.stop();
-        }
-        catch (e) {
-            spinner.stop();
-            const message = e instanceof Error ? e.message : String(e);
-            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("- Or set GITHUB_TOKEN to avoid rate limits");
-            process.exit(1);
-        }
-    }
-    if (options.quick) {
-        let quickReadme = readme;
-        const repoName = local ? localPath : (repoData?.full_name ?? "");
-        const description = local
-            ? null
-            : (repoData?.description ?? null);
-        if (local) {
-            const spinner = ora("Reading repository files…").start();
-            try {
-                const read = readLocalRepoSignalFiles(localPath);
-                spinner.stop();
-                const readmeKey = Object.keys(read.keyFiles).find((k) => k.toLowerCase().startsWith("readme"));
-                quickReadme = readmeKey !== undefined ? read.keyFiles[readmeKey] : null;
-            }
-            catch (e) {
-                spinner.stop();
-                throw e;
-            }
-        }
-        const prompt = buildQuickPrompt(repoName, description, quickReadme);
-        const spinner = ora("Generating explanation…").start();
-        const output = await generateWithExit(prompt, options.llm).finally(() => spinner.stop());
-        console.log("Quick summary 🎉");
-        console.log(output.trim());
-        return;
-    }
-    if (options.simple) {
-        let readResult;
-        const spinner = ora("Reading repository files…").start();
-        try {
-            readResult = local
-                ? readLocalRepoSignalFiles(localPath)
-                : await safeReadRepoFiles(owner, repo);
-            spinner.stop();
-        }
-        catch (e) {
-            spinner.stop();
-            throw e;
-        }
-        const prompt = buildSimplePrompt(local ? localPath : (repoData?.full_name ?? ""), local ? null : (repoData?.description ?? null), local ? null : readme, readResult?.treeText ?? null);
-        const genSpinner = ora("Generating explanation…").start();
-        const output = await generateWithExit(prompt, options.llm).finally(() => genSpinner.stop());
-        console.log("Simple summary 🎉");
-        console.log(output.trim());
-        return;
-    }
-    let readResult;
-    const readSpinner = ora("Reading repository files…").start();
-    try {
-        readResult = local
-            ? readLocalRepoSignalFiles(localPath)
-            : await safeReadRepoFiles(owner, repo);
-        readSpinner.stop();
-    }
-    catch (e) {
-        readSpinner.stop();
-        throw e;
-    }
-    const prompt = buildPrompt(local ? localPath : (repoData?.full_name ?? ""), local ? null : (repoData?.description ?? null), local ? null : readme, options.detailed || false, readResult?.treeText ?? null, readResult?.filesText ?? null);
-    const genSpinner = ora("Generating explanation…").start();
-    const output = await generateWithExit(prompt, options.llm).finally(() => genSpinner.stop());
-    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.");
 }
-const program = new Command();
-program
-    .name("explainthisrepo")
-    .description("CLI that generates plain English explanations of any codebase")
-    .version(getPkgVersion(), "-v, --version", "Show version")
-    .argument("[repository]", "GitHub repository (owner/repo or URL) or local directories")
-    .option("--doctor", "Run diagnostics")
-    .option("--quick", "Quick summary mode")
-    .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.")
-    .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 owner/repo --llm gemini
-  $ explainthisrepo owner/repo --llm openai
-  $ explainthisrepo owner/repo --llm ollama
-  $ explainthisrepo .
-  $ explainthisrepo ./path/to/directory
-  $ explainthisrepo . --stack
-  $ explainthisrepo --doctor
-  $ explainthisrepo --doctor --llm gemini
-  $ explainthisrepo --doctor --llm openai
-  $ explainthisrepo --doctor --llm ollama`)
-    .action(async (repository, options) => {
-    if (options.doctor) {
-        const code = await runDoctor(options.llm);
-        process.exit(code);
-    }
-    if (!repository) {
-        program.error("repository argument required (or use `explainthisrepo init` to configure a provider)");
-        return;
-    }
-    await runAnalysis(repository, options);
-});
-program
-    .command("init")
-    .description("Configure your LLM provider (Gemini, OpenAI, or Ollama)")
-    .action(async () => {
-    await runInit();
-});
-program.parseAsync(process.argv);
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explainthisrepo",
-  "version": "0.9.6",
+  "version": "0.20.0",
   "description": "The fastest way to understand any codebase in plain English. Not blind AI summarization",
   "license": "MIT",
   "type": "module",
@@ -46,14 +46,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@google/generative-ai": "^0.24.1",
-    "@iarna/toml": "^2.2.5",
-    "axios": "^1.13.2",
-    "commander": "^14.0.3",
-    "dotenv": "^17.2.3",
-    "openai": "^4.0.0",
-    "ora": "^9.3.0",
-    "toml": "^3.0.0"
+    "commander": "^14.0.3"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/dist/config.d.ts

@@ -1,5 +0,0 @@
-export declare function getConfigPath(): string;
-export declare function ensureConfigDir(): string;
-export declare function writeConfig(contents: string): void;
-export declare function readConfig(): string | null;
-export declare function loadConfig(): any;

package/dist/config.js

@@ -1,46 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { parse } from "@iarna/toml";
-const CONFIG_DIR_NAME = "ExplainThisRepo";
-const CONFIG_FILE_NAME = "config.toml";
-export function getConfigPath() {
-    if (process.platform === "win32") {
-        const appdata = process.env.APPDATA;
-        if (!appdata) {
-            throw new Error("APPDATA environment variable is not set");
-        }
-        return path.join(appdata, CONFIG_DIR_NAME, CONFIG_FILE_NAME);
-    }
-    const xdg = process.env.XDG_CONFIG_HOME;
-    const base = xdg ?? path.join(os.homedir(), ".config");
-    return path.join(base, "explainthisrepo", CONFIG_FILE_NAME);
-}
-export function ensureConfigDir() {
-    const configPath = getConfigPath();
-    const dir = path.dirname(configPath);
-    fs.mkdirSync(dir, { recursive: true });
-    return configPath;
-}
-export function writeConfig(contents) {
-    const path = ensureConfigDir();
-    fs.writeFileSync(path, contents, { encoding: "utf-8" });
-}
-export function readConfig() {
-    const path = getConfigPath();
-    if (!fs.existsSync(path))
-        return null;
-    return fs.readFileSync(path, "utf-8");
-}
-export function loadConfig() {
-    const raw = readConfig();
-    if (!raw) {
-        return {};
-    }
-    try {
-        return parse(raw);
-    }
-    catch (err) {
-        throw new Error("Invalid config.toml format");
-    }
-}

package/dist/generate.d.ts

@@ -1 +0,0 @@
-export declare function generateExplanation(prompt: string, providerOverride?: string): Promise<string>;

package/dist/generate.js

@@ -1,15 +0,0 @@
-import { getActiveProvider } from "./providers/registry.js";
-export async function generateExplanation(prompt, providerOverride) {
-    const provider = getActiveProvider(providerOverride);
-    try {
-        const output = await provider.generate(prompt);
-        if (!output || !output.trim()) {
-            throw new Error(`${provider.name} returned no output`);
-        }
-        return output.trim();
-    }
-    catch (err) {
-        const message = err?.message ? String(err.message) : String(err);
-        throw new Error(`${provider.name} generation failed: ${message}`);
-    }
-}

package/dist/github.d.ts

@@ -1,6 +0,0 @@
-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>;