explainthisrepo 0.5.0 → 0.6.0

package/README.md

@@ -1,8 +1,8 @@
 # ExplainThisRepo
 
-ExplainThisRepo is a CLI that generates plain-English explanations of public GitHub repositories by analyzing repository structure, README content, and selected high signal files.
+ExplainThisRepo is a CLI that generates plain-English explanations of any codebase (GitHub repositories and local directories) by analyzing project structure, README content, and high signal files.
 
-It's helps developers understand unfamiliar repositories does by generating a structured `EXPLAIN.md` from real
+It helps developers quickly understand unfamiliar codebases by deriving architectural explanations from real project structure and code signals, producing a clear, structured `EXPLAIN.md`.
 
 [![PyPI Version](https://img.shields.io/pypi/v/explainthisrepo?color=blue)](https://pypi.org/project/explainthisrepo/)
 [![PyPI Downloads](https://static.pepy.tech/personalized-badge/explainthisrepo?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/explainthisrepo)
@@ -19,15 +19,15 @@ It's helps developers understand unfamiliar repositories does by generating a st
 
 ## Key Features
 
-- Understand unfamiliar repositories instantly through structural and architechural summaries by turning structure and code signals into a readable architectural summary
-- Fetches public GitHub repositories automatically
-- Analyzes real repository data including file tree, configs, entrypoints, and high signal source files
+- Generates architectural summaries from repository structure and code signals
+- Fetches public repositories by GitHub URLs (with or without https), `owner/repo` format, issue links, query strings, and SSH clone links
+- Analyzes repository data including file tree, configs, entrypoints, and high signal source files
 - Extracts repo signals from key files (package.json, pyproject.toml, config files, entrypoints)
 - Builds a file tree summary to understand project architecture
-- Detects programming languages via the GitHub API
-- Accepts repositories via owner/repo, GitHub URLs (with or without https), issue links, query strings, and SSH clone links
+- Detects programming languages with the GitHub API
+- Analyzes local project directories using the same pipeline as GitHub repositories
 - Generates a structured plain English explanation grounded in actual project files
-- Outputs an EXPLAIN.md file in your current directory (default mode)
+- Outputs the explanation to an `EXPLAIN.md` file in your current directory or print it directly in the terminal
 - Multi mode command-line interface
 
 ---
@@ -38,13 +38,13 @@ It's helps developers understand unfamiliar repositories does by generating a st
 
 - `--quick` → One-sentence summary
 
-- `--simple` → Short, easy explanation
+- `--simple` → Short, simplified explanation
 
 - `--detailed` → Deeper explanation including structure and architecture
 
 - `--stack` → Tech stack breakdown from repo signals
 
-- `--version` → Show CLI version
+- `--version` → Check installed CLI version
 
 - `--help` → Show usage guide
 
@@ -56,9 +56,9 @@ It's helps developers understand unfamiliar repositories does by generating a st
 
 ExplainThisRepo uses Gemini models for code analysis.
 
-Set your API key as an environment variable.
+Set your Google Gemini API key as an environment variable.
 
-macOS / Linux
+Linux / macOS
 
 ```bash
 export GEMINI_API_KEY="your_api_key_here"
@@ -74,7 +74,7 @@ Restart your terminal after setting the key.
 
 ## Installation
 
-### Option 1: install via pip (recommended):
+### Option 1: install with pip (recommended):
 
 Requirements: Python 3.9+
 
@@ -99,29 +99,32 @@ explainthisrepo owner/repo
 # or: npx explainthisrepo owner/repo
 ```
 
+Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`).
+
 ---
 
-## Flexible Repository Input
+## Flexible Repository and Local Directory Input
 
-You don’t need to reformat links anymore.
+Accepts various formats for repository input, full GitHub URLs, issue links, and SSH clone links.
 
-ExplainThisRepo accepts GitHub repositories the way you actually copy them.
 ```bash
 explainthisrepo https://github.com/owner/repo
 explainthisrepo github.com/owner/repo
 explainthisrepo https://github.com/owner/repo/issues/123
 explainthisrepo https://github.com/owner/repo?tab=readme
 explainthisrepo git@github.com:owner/repo.git
+explainthisrepo .
+explainthisrepo ./path/to/directory
 ```
 
-All inputs are normalized internally to owner/repo.
+All inputs are normalized internally to `owner/repo`.
 
 ---
 
 ## Usage
 
 ### Basic
-Generate a full explanation and saves it to `EXPLAIN.md`:
+Writes a full explanation to `EXPLAIN.md`:
 
 ```bash
 explainthisrepo owner/repo
@@ -134,7 +137,8 @@ explainthisrepo facebook/react
 
 ### Quick mode
 
-Get a one-sentence definition (prints only, no file created):
+Prints a one-sentence summary to stdout:
+
 ```bash
 explainthisrepo owner/repo --quick
 ```
@@ -148,7 +152,8 @@ explainthisrepo facebook/react --quick
 
 ### Detailed mode
 
-Generate a more detailed explanation (includes architecture / folder structure):
+Writes a more detailed explanation of repository structure and architecture:
+
 ```bash
 explainthisrepo owner/repo --detailed
 ```
@@ -159,7 +164,8 @@ explainthisrepo owner/repo --detailed
 
 ### Simple mode
 
-Prints only the simple output (no EXPLAIN.md)
+Prints a short, simplified explanation to stdout. No files are written.
+
 ```bash
 explainthisrepo owner/repo --simple
 ```
@@ -170,15 +176,43 @@ explainthisrepo owner/repo --simple
 
 ### Stack detector
 
-Get a tech stack breakdown detected from repo signals. No AI explanation. Prints only.
+Tech stack breakdown detected from repo signals. No LLM calls are made.
+
 ```bash
 explainthisrepo owner/repo --stack
 ```
 ![Stack detector Output](assets/stack-command-output.png)
 
+### Local Directory Analysis
+
+ExplainThisRepo can analyze local directories directly in the terminal, using the same modes and output formats as GitHub repositories
+
+```bash
+explainthisrepo .
+explainthisrepo ./path/to/directory
+```
+
+This works with all existing modes:
+
+```bash
+explainthisrepo . --quick
+explainthisrepo . --simple
+explainthisrepo . --detailed
+explainthisrepo . --stack
+```
+
+When analyzing a local directory:
+- Repository structure is derived from the filesystem
+- Key files (README, configs, entrypoints) are extracted locally
+- No GitHub APIs calls are made
+- All prompts and outputs remain identical
+
+This allows analysis of projects directly from the local filesystem, without requiring a GitHub repository.
+
 ### Version
 
-Print the installed version:
+Print the installed CLI version:
+
 ```bash
 explainthisrepo --version
 ```
@@ -187,12 +221,13 @@ explainthisrepo --version
 
 ### Doctor
 
-Check environment + connectivity (useful for debugging):
+Check environment and connectivity (useful for debugging):
+
 ```bash
 explainthisrepo --doctor
 ```
 
-## Termux (Android) install notes
+### Termux (Android) install notes
 
 Termux has some environment limitations that can make `pip install explainthisrepo` fail to create the `explainthisrepo` command in `$PREFIX/bin`.
 
@@ -216,7 +251,7 @@ If you do not want to modify PATH, you can run ExplainThisRepo as a module:
 python -m explain_this_repo owner/repo
 ```
 
-Gemini support on Termux (Optional)
+### Gemini support on Termux (Optional)
 
 Installing Gemini support may require building Rust-based dependencies on Android, which can take time on first install:
 
@@ -247,4 +282,4 @@ Caleb Wodi
 
 - Email: caleb@explainthisrepo.com
 - Twitter: [@calchiwo](https://x.com/calchiwo)
-- LinkedIn: [@calchiwo](https://linkedin.com/in/calchiwo)
+- LinkedIn: [@calchiwo](https://linkedin.com/in/calchiwo)

package/dist/cli.js

@@ -6,6 +6,8 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 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";
@@ -132,9 +134,9 @@ async function main() {
     const program = new Command();
     program
         .name("explainthisrepo")
-        .description("Explain GitHub repositories in plain English")
+        .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 path")
+        .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")
@@ -154,7 +156,16 @@ Examples:
   $ explainthisrepo ./path/to/directory
   $ explainthisrepo . --stack
   $ explainthisrepo --doctor`);
+    program
+        .command("init")
+        .description("Initialize configuration with Gemini API key")
+        .action(async () => {
+        await runInit();
+    });
     program.parse(process.argv);
+    if (process.argv[2] === "init") {
+        return;
+    }
     const options = program.opts();
     const repository = program.args[0];
     if (options.doctor) {
@@ -172,7 +183,7 @@ Examples:
         process.exit(1);
     }
     if (!repository) {
-        program.error("repository argument required");
+        program.error("repository argument required (or use `init` to set up API key)");
     }
     const local = fs.existsSync(repository);
     let owner = "";
@@ -191,20 +202,32 @@ Examples:
             console.error(`error: ${message}`);
             process.exit(1);
         }
-        console.log(`Fetching ${owner}/${repo}...`);
     }
     if (options.stack) {
         let read;
         let languages = {};
         if (local) {
-            read = readLocalRepoSignalFiles(localPath);
+            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);
@@ -223,10 +246,14 @@ Examples:
     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}`);
@@ -235,48 +262,66 @@ Examples:
             console.error("- Or set GITHUB_TOKEN to avoid rate limits");
             process.exit(1);
         }
-        try {
-            readme = await fetchReadme(owner, repo);
-        }
-        catch (e) {
-            const message = e instanceof Error ? e.message : String(e);
-            console.warn(`Warning: Could not fetch README: ${message}`);
-            readme = null;
-        }
     }
     if (options.quick) {
         let quickReadme = readme;
         const repoName = local ? localPath : (repoData?.full_name ?? "");
         const description = local ? null : (repoData?.description ?? null);
         if (local) {
-            const read = readLocalRepoSignalFiles(localPath);
-            const readmeKey = Object.keys(read.keyFiles).find((k) => k.toLowerCase().startsWith("readme"));
-            quickReadme = readmeKey !== undefined ? read.keyFiles[readmeKey] : null;
+            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);
-        console.log("Generating explanation...");
-        const output = await generateWithExit(prompt);
+        const spinner = ora("Generating explanation…").start();
+        const output = await generateWithExit(prompt).finally(() => spinner.stop());
         console.log("Quick summary 🎉");
         console.log(output.trim());
         return;
     }
     if (options.simple) {
-        const readResult = local
-            ? readLocalRepoSignalFiles(localPath)
-            : await safeReadRepoFiles(owner, repo);
+        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);
-        console.log("Generating explanation...");
-        const output = await generateWithExit(prompt);
+        const genSpinner = ora("Generating explanation…").start();
+        const output = await generateWithExit(prompt).finally(() => genSpinner.stop());
         console.log("Simple summary 🎉");
         console.log(output.trim());
         return;
     }
-    const readResult = local
-        ? readLocalRepoSignalFiles(localPath)
-        : await safeReadRepoFiles(owner, repo);
+    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);
-    console.log("Generating explanation...");
-    const output = await generateWithExit(prompt);
+    const genSpinner = ora("Generating explanation…").start();
+    const output = await generateWithExit(prompt).finally(() => genSpinner.stop());
     console.log("Writing EXPLAIN.md...");
     writeOutput(output);
     const wordCount = output.split(/\s+/).filter(Boolean).length;

package/dist/config.d.ts

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

package/dist/config.js

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+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");
+}

package/dist/init.d.ts

@@ -0,0 +1 @@
+export declare function runInit(): Promise<void>;

package/dist/init.js

@@ -0,0 +1,41 @@
+import readline from "node:readline";
+import process from "node:process";
+import { stdin as input, stderr as output } from "node:process";
+import chalk from "chalk";
+import { writeConfig } from "./config.js";
+const CONFIG_TEMPLATE = `[llm]
+provider = "gemini"
+api_key = "{api_key}"
+`;
+export async function runInit() {
+    output.write(chalk.yellow("WARNING: input is hidden. Paste your GEMINI_API_KEY and press Enter.\n"));
+    try {
+        const apiKey = (await promptHidden("Gemini API key: ")).trim();
+        if (!apiKey) {
+            output.write(chalk.red("error: API key cannot be empty\n"));
+            process.exit(1);
+        }
+        writeConfig(CONFIG_TEMPLATE.replace("{api_key}", apiKey));
+        output.write(chalk.green("Configuration written.\n"));
+        process.exit(0);
+    }
+    catch {
+        output.write(chalk.red("\nInterrupted.\n"));
+        process.exit(130);
+    }
+}
+function promptHidden(prompt) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input,
+            output,
+            terminal: true,
+        });
+        rl._writeToOutput = () => { };
+        rl.question(prompt, (answer) => {
+            rl.close();
+            output.write("\n");
+            resolve(answer);
+        });
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "explainthisrepo",
-  "version": "0.5.0",
-  "description": "A CLI developer tool to explain any GitHub repository in plain English",
+  "version": "0.6.0",
+  "description": "CLI that generates plain English explanations of any codebase",
   "license": "MIT",
   "type": "module",
   "author": "Caleb Wodi <calebwodi33@gmail.com>",
@@ -47,7 +47,8 @@
     "@google/generative-ai": "^0.24.1",
     "axios": "^1.13.2",
     "commander": "^14.0.3",
-    "dotenv": "^17.2.3"
+    "dotenv": "^17.2.3",
+    "ora": "^9.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",