explainthisrepo 0.4.2 → 0.4.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Caleb Wodi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,87 +1,250 @@
 # ExplainThisRepo
 
-This folder contains a high-performance, lightweight port of the ExplainThisRepo CLI tool.
-While the original Python implementation is the primary version of this tool, this Node.js port was created to provide a "zero-compilation" experience for users where Python C-extensions (like Pillow) can be difficult to build.
+ExplainThisRepo is a CLI that generates plain-English explanations of public GitHub repositories by analyzing repository structure, README content, and selected high signal files.
 
-## Features
-- **Automated Repository Analysis**: Seamlessly fetches repository data and documentation via the GitHub REST API.
-- **AI-Driven Contextualization**: Uses Google Gemini 2.5 Flash Lite to extract technical value and purpose from codebases.
-- **Senior Engineer Perspective**: Generates explanations tailored for developers, focusing on architecture, target audience, and execution.
-- **Markdown Generation**: Automatically outputs a clean, structured `EXPLAIN.md` file for immediate reading.
-- **TypeScript Core**: Built with type safety and modern asynchronous patterns for reliable performance.
+It's helps developers understand unfamiliar repositories does by generating a structured `EXPLAIN.md` from real
+
+[![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)
+[![Python](https://img.shields.io/pypi/pyversions/explainthisrepo?logo=python&logoColor=white)](https://pypi.org/project/explainthisrepo/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/explainthisrepo)](https://www.npmjs.com/package/explainthisrepo)
+[![Node](https://img.shields.io/node/v/explainthisrepo)](https://www.npmjs.com/package/explainthisrepo)
+[![Docs](https://img.shields.io/badge/docs-explainthisrepo.com-black)](https://explainthisrepo.com)
+
+---
+
+![demo](https://github.com/user-attachments/assets/837e0593-db64-4657-8855-bb1915011eb6)
+---
+
+## 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
+- 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
+- Generates a structured plain English explanation grounded in actual project files
+- Outputs an EXPLAIN.md file in your current directory (default mode)
+- Multi mode command-line interface
+
+---
+
+## Modes
+
+- (no flag) → Full repository explanation written to EXPLAIN.md
+
+- `--quick` → One-sentence summary
+
+- `--simple` → Short, easy explanation
+
+- `--detailed` → Deeper explanation including structure and architecture
+
+- `--stack` → Tech stack breakdown from repo signals
+
+- `--version` → Show CLI version
+
+- `--help` → Show usage guide
+
+- `--doctor` → Check environmental health and API connectivity
+
+---
+
+## Configuration
+
+ExplainThisRepo uses Gemini models for code analysis.
+
+Set your API key as an environment variable.
+
+macOS / Linux
+
+```bash
+export GEMINI_API_KEY="your_api_key_here"
+```
+
+Windows (PowerShell)
+
+```bash
+setx GEMINI_API_KEY "your_api_key_here"
+```
+
+Restart your terminal after setting the key.
 
 ## Installation
 
-Follow these steps to set up the project locally on your machine:
+### Option 1: install via pip (recommended):
+
+Requirements: Python 3.9+
+
+```bash
+pip install explainthisrepo
+explainthisrepo owner/repo
+```
 
-1. **Clone the Repository**
-   ```bash
-   git clone https://github.com/calchiwo/ExplainThisRepo.git
-   cd ExplainThisRepo/node_version
-   ```
+Alternatively,
 
-2. **Install Dependencies**
-   ```bash
-   npm install
-   ```
+```bash
+pipx install explainthisrepo
+explainthisrepo owner/repo
+```
 
-3. **Set Up Environment Variables**
-   Create a `.env` file in the root directory or export the variable directly in your terminal:
-   ```bash
-   export GEMINI_API_KEY=your_actual_api_key_here
-   ```
+### Option 2: Install with npm
 
-4. **Build the Project**
-   Compile the TypeScript source code into executable JavaScript:
-   ```bash
-   npm run build
-   ```
-5  **Link the command globally:**
+Install globally and use forever:
 ```bash
-   npm link
-   ```
+npm install -g explainthisrepo
+explainthisrepo owner/repo
+# or: npx explainthisrepo owner/repo
+```
+
+---
 
+## Flexible Repository Input
+
+You don’t need to reformat links anymore.
+
+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
+```
+
+All inputs are normalized internally to owner/repo.
+
+---
 
 ## Usage
 
-Once the project is built, you can use the CLI tool to analyze any public GitHub repository.
+### Basic
+Generate a full explanation and saves it to `EXPLAIN.md`:
+
+```bash
+explainthisrepo owner/repo
+```
+Example:
+```bash
+explainthisrepo facebook/react
+```
+---
+
+### Quick mode
+
+Get a one-sentence definition (prints only, no file created):
+```bash
+explainthisrepo owner/repo --quick
+```
+Example:
+```bash
+explainthisrepo facebook/react --quick
+```
+![Quick Mode Output](assets/quick-command-output.png)
+
+---
+
+### Detailed mode
+
+Generate a more detailed explanation (includes architecture / folder structure):
+```bash
+explainthisrepo owner/repo --detailed
+```
+
+![Detailed Mode Output](assets/detailed-command-output.png)
 
-### Running the CLI
-Execute the tool by passing the `owner/repo` string as an argument:
+---
 
+### Simple mode
+
+Prints only the simple output (no EXPLAIN.md)
+```bash
+explainthisrepo owner/repo --simple
+```
+
+![Simple Mode Output](assets/simple-command-output.png)
+
+---
+
+### Stack detector
+
+Get a tech stack breakdown detected from repo signals. No AI explanation. Prints only.
 ```bash
-node dist/cli.js facebook/react
+explainthisrepo owner/repo --stack
 ```
+![Stack detector Output](assets/stack-command-output.png)
+
+### Version
 
-### Expected Workflow
-1. The tool fetches the repository description and README from GitHub.
-2. It processes the information and sends a structured prompt to the Gemini AI.
-3. An `EXPLAIN.md` file is generated in your current working directory containing:
-   - Project Overview
-   - Functional Breakdown
-   - Target User Identification
-   - Setup/Execution Instructions
+Print the installed version:
+```bash
+explainthisrepo --version
+```
 
-### Scripts
-- `npm run build`: Compiles TypeScript to the `dist` folder.
-- `npm run format`: Formats the codebase using Prettier.
-- `npm start`: Runs the tool (requires the repository argument).
+---
 
-## Contributing
+### Doctor
 
-Contributions are what make the open-source community an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
+Check environment + connectivity (useful for debugging):
+```bash
+explainthisrepo --doctor
+```
 
--️ **Report Bugs**: Open an issue if you find any unexpected behavior.
-- **Feature Requests**: Proposals for new features are always welcome.
-- **Pull Requests**: Ensure your code follows the existing style and all linting passes.
+## Termux (Android) install notes
 
-> Note: Please run npm run format before submitting a Pull Request to ensure code consistency.
+Termux has some environment limitations that can make `pip install explainthisrepo` fail to create the `explainthisrepo` command in `$PREFIX/bin`.
+
+### Recommended install (Termux)
+
+```bash
+pip install --user -U explainthisrepo
+```
+
+Make sure your user bin directory is on your PATH:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+> Tip: Add the PATH export to your ~/.bashrc or ~/.zshrc so it persists.
+
+Alternative (No PATH changes)
+
+If you do not want to modify PATH, you can run ExplainThisRepo as a module:
+
+```bash
+python -m explain_this_repo owner/repo
+```
+
+Gemini support on Termux (Optional)
+
+Installing Gemini support may require building Rust-based dependencies on Android, which can take time on first install:
+
+```bash
+pip install --user -U "explainthisrepo[gemini]"
+```
+
+## Contributions
+
+Contributions are welcome!
+
+If you find a bug, have an idea, or want to improve the tool:
+- See [CONTRIBUTING](CONTRIBUTING.md) for setup and guidelines
+- Open an issue for bugs/feature requests
+- Or submit a pull request for fixes/improvements
+
+---
 
 ## License
-This project is licensed under the MIT License as specified in the package configuration.
 
-## Author Info
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+---
+
+## Author
 
-[**Caleb Wodi**](https://github.com/calchiwo)
+Caleb Wodi
 
-Node version contibuted by [@Spectra010s](https://github.com/spectra010s)
+- Email: caleb@explainthisrepo.com
+- Twitter: [@calchiwo](https://x.com/calchiwo)
+- LinkedIn: [@calchiwo](https://linkedin.com/in/calchiwo)

package/dist/cli.js

@@ -81,9 +81,11 @@ async function checkUrl(url, timeoutMs = 6000) {
     }
     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 (${e?.name || "Error"}: ${e?.message || e})`,
+            msg: `failed (${name}: ${message})`,
         };
     }
 }
@@ -108,7 +110,8 @@ async function safeReadRepoFiles(owner, repo) {
         return await readRepoSignalFiles(owner, repo);
     }
     catch (e) {
-        console.warn(`Warning: Could not read repo files: ${e?.message || e}`);
+        const message = e instanceof Error ? e.message : String(e);
+        console.warn(`Warning: Could not read repo files: ${message}`);
         return null;
     }
 }
@@ -117,8 +120,9 @@ async function generateWithExit(prompt) {
         return await generateExplanation(prompt);
     }
     catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
         console.error("Failed to generate explanation.");
-        console.error(`error: ${e?.message || e}`);
+        console.error(`error: ${message}`);
         console.error("\nfix:");
         console.error("- Ensure GEMINI_API_KEY is set");
         console.error("- Or run: explainthisrepo --doctor");
@@ -173,7 +177,8 @@ Examples:
         ({ owner, repo } = resolveRepoTarget(repository));
     }
     catch (e) {
-        console.error(`error: ${e.message}`);
+        const message = e instanceof Error ? e.message : String(e);
+        console.error(`error: ${message}`);
         process.exit(1);
     }
     console.log(`Fetching ${owner}/${repo}...`);
@@ -190,7 +195,8 @@ Examples:
             return;
         }
         catch (e) {
-            console.error(`error: ${e?.message || e}`);
+            const message = e instanceof Error ? e.message : String(e);
+            console.error(`error: ${message}`);
             process.exit(1);
         }
     }
@@ -199,8 +205,9 @@ Examples:
         repoData = await fetchRepo(owner, repo);
     }
     catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
         console.error("Failed to fetch repository data.");
-        console.error(`error: ${e?.message || e}`);
+        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");
@@ -211,7 +218,8 @@ Examples:
         readme = await fetchReadme(owner, repo);
     }
     catch (e) {
-        console.warn(`Warning: Could not fetch README: ${e?.message || e}`);
+        const message = e instanceof Error ? e.message : String(e);
+        console.warn(`Warning: Could not fetch README: ${message}`);
         readme = null;
     }
     if (options.quick) {

package/dist/prompt.js

@@ -1,23 +1,26 @@
+function escapeForPromptBlock(input) {
+    return input.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
 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.
 
 <repository_metadata>
-Name: ${repoName}
-Description: ${description || "No description provided"}
+Name: ${escapeForPromptBlock(repoName)}
+Description: ${escapeForPromptBlock(description || "No description provided")}
 </repository_metadata>
 
 <readme>
-${readme || "No README provided"}
+${escapeForPromptBlock(readme || "No README provided")}
 </readme>
 
 <repo_structure>
-${treeText || "No file tree provided"}
+${escapeForPromptBlock(treeText || "No file tree provided")}
 </repo_structure>
 
 <code_files>
-${filesText || "No code files provided"}
+${escapeForPromptBlock(filesText || "No code files provided")}
 </code_files>
 
 Instructions:
@@ -59,12 +62,12 @@ export function buildQuickPrompt(repoName, description, readme) {
 Write a ONE-SENTENCE plain-English definition of what this GitHub repository is.
 
 <repository_metadata>
-Name: ${repoName}
-Description: ${description || "No description provided"}
+Name: ${escapeForPromptBlock(repoName)}
+Description: ${escapeForPromptBlock(description || "No description provided")}
 </repository_metadata>
 
 <readme>
-${readmeSnippet}
+${escapeForPromptBlock(readmeSnippet)}
 </readme>
 
 Rules:
@@ -88,16 +91,16 @@ export function buildSimplePrompt(repoName, description, readme, treeText = null
 Summarize this GitHub repository in a concise bullet-point format.
 
 <repository_metadata>
-Name: ${repoName}
-Description: ${description || "No description provided"}
+Name: ${escapeForPromptBlock(repoName)}
+Description: ${escapeForPromptBlock(description || "No description provided")}
 </repository_metadata>
 
 <readme>
-${readmeContent}
+${escapeForPromptBlock(readmeContent)}
 </readme>
 
 <repo_structure>
-${treeContent}
+${escapeForPromptBlock(treeContent)}
 </repo_structure>
 
 Output style rules:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explainthisrepo",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "A CLI developer tool to explain any GitHub repository in plain English",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,8 @@
   "scripts": {
     "build": "tsc",
     "start": "node dist/cli.js",
-    "prepublishOnly": "npm run build"
+    "sync-meta": "cp ../README.md README.md && cp ../LICENSE LICENSE",
+    "prepublishOnly": "npm run sync-meta && npm run build"
   },
   "engines": {
     "node": ">=20"