repobrief 0.1.1__tar.gz

repobrief-0.1.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug Report
+about: Report a bug in RepoBrief
+title: "[BUG] "
+labels: bug
+---
+
+**What happened?**
+A clear description of the bug.
+
+**What did you expect?**
+What should have happened instead.
+
+**Steps to reproduce:**
+1. Run `repobrief pack ...`
+2. ...
+
+**Environment:**
+- OS: [e.g., Windows 11, macOS 14, Ubuntu 24.04]
+- Python version: [e.g., 3.11.5]
+- RepoBrief version: [e.g., 0.1.0]
+- Backend: [cloud/ollama/none]
+
+**Error output:**
+```
+Paste any error messages here
+```

repobrief-0.1.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature Request
+about: Suggest a new feature for RepoBrief
+title: "[FEATURE] "
+labels: enhancement
+---
+
+**What problem does this solve?**
+A clear description of the problem.
+
+**What solution do you propose?**
+How should it work?
+
+**Alternatives considered:**
+Any other approaches you've thought about.

repobrief-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+
+    
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Test
+        run: pytest -v --tb=short
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: twine upload dist/*

repobrief-0.1.1/.gitignore

@@ -0,0 +1,68 @@
+#planning/
+planning/*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# MyPy
+.mypy_cache/
+
+# Ruff
+.ruff_cache/
+planning
+
+# Virtual environments
+fresh-test-env/
+venv/
+.venv/
+env/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/

repobrief-0.1.1/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to RepoBrief will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-09-02
+
+### Added
+- **Core scanner**: Recursive directory walker with `.gitignore` support and binary detection
+- **Secret detection**: Regex-based scanning for API keys, tokens, passwords, and credentials with `--redact` mode
+- **Token counting**: Accurate token counting via `tiktoken` with character-based fallback
+- **File scoring**: Multi-factor relevance scoring (git recency, file size, import centrality, keyword match)
+- **Budget selection**: Greedy file selector that fits files within configurable token budget
+- **Output formats**: Markdown, XML, and plain text digest generation
+- **Export mode**: `repobrief pack` command with file, clipboard, and stdout output
+- **Cloud backend**: Anthropic (Claude) and OpenAI (GPT) API integration with real-time streaming
+- **Ollama backend**: Fully offline local LLM chat via Ollama REST API
+- **Chat mode**: One-shot (`-q`) and interactive REPL modes
+- **GitHub URL support**: Direct packing from `https://github.com/user/repo` URLs
+- **Config file**: `.repobrief.yml` for persistent project-level settings
+- **Error handling**: Graceful degradation, helpful error messages, first-run setup guide
+- **Packaging & CI**: Full PyPI packaging configuration, GitHub Actions CI workflow, issue templates

repobrief-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to RepoBrief
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+1. **Fork and clone the repository**
+   ```bash
+   git clone https://github.com/yourusername/repobrief.git
+   cd repobrief
+   ```
+
+2. **Create a virtual environment**
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # Windows: .venv\Scripts\activate
+   ```
+
+3. **Install in development mode**
+   ```bash
+   pip install -e ".[dev,cloud]"
+   ```
+
+4. **Verify your setup**
+   ```bash
+   pytest                     # All tests should pass
+   ruff check src/ tests/     # No lint errors
+   ```
+
+## Making Changes
+
+1. **Create a feature branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Write tests first** — every new feature or bugfix should include tests.
+
+3. **Follow existing code style** — run `ruff format` before committing.
+
+4. **Keep commits focused** — one logical change per commit.
+
+## Running Tests
+
+```bash
+# All tests
+pytest
+
+# Specific module
+pytest tests/test_scanner/ -v
+
+# With coverage
+pytest --cov=repobrief --cov-report=html
+```
+
+## Code Style
+
+- **Formatter**: `ruff format` (line length: 100)
+- **Linter**: `ruff check` with rules: `E`, `F`, `W`, `I`, `N`, `UP`, `B`, `SIM`
+- **Type hints**: Use type hints for all public function signatures
+- **Docstrings**: Google-style docstrings for all public functions and classes
+
+## Pull Request Process
+
+1. Ensure all tests pass (`pytest`)
+2. Ensure linting passes (`ruff check src/ tests/`)
+3. Update the `CHANGELOG.md` if appropriate
+4. Open a PR against `main` with a clear description of the change
+
+## Adding a New LLM Backend
+
+RepoBrief is designed to make adding new backends easy:
+
+1. Create a new file in `src/repobrief/backends/` (e.g., `lmstudio.py`)
+2. Implement the `LLMBackend` abstract class from `base.py`
+3. Add the backend option to `cli.py`
+4. Write tests in `tests/test_backends/`
+5. Update the README
+
+The interface requires only two methods:
+- `generate(system_prompt, user_message, history) -> Iterator[str]`
+- `validate() -> Tuple[bool, str]`

repobrief-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RepoBrief Contributors
+
+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.

repobrief-0.1.1/Makefile

@@ -0,0 +1,36 @@
+.PHONY: help install dev test test-cov lint format typecheck build clean check
+
+help:  ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install:  ## Install the package
+	pip install -e .
+
+dev:  ## Install with all development dependencies
+	pip install -e ".[dev,cloud]"
+
+test:  ## Run all tests
+	pytest -v
+
+test-cov:  ## Run tests with coverage report
+	pytest --cov=repobrief --cov-report=html --cov-report=term-missing
+
+lint:  ## Run linter
+	ruff check src/ tests/
+
+format:  ## Format code
+	ruff format src/ tests/
+
+typecheck:  ## Run type checker
+	mypy src/
+
+build:  ## Build the package for PyPI
+	python -m build
+
+clean:  ## Clean build artifacts
+	rm -rf dist/ build/ *.egg-info src/*.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+check: lint typecheck test  ## Run all checks (lint + typecheck + test)

repobrief-0.1.1/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.5
+Name: repobrief
+Version: 0.1.1
+Summary: Pack any repo into clean LLM context, then chat with it — using Claude, GPT, or a fully offline Ollama model.
+Project-URL: Homepage, https://github.com/Saqlain-mushtaq-alamin/RepoBrief
+Project-URL: Repository, https://github.com/Saqlain-mushtaq-alamin/RepoBrief
+Project-URL: Issues, https://github.com/Saqlain-mushtaq-alamin/RepoBrief/issues
+Author-email: RepoBrief Maintainers <maintainers@repobrief.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,cli,codebase,context,llm,ollama
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: pathspec>=0.11.0
+Requires-Dist: pyperclip>=1.8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tiktoken>=0.5.0
+Provides-Extra: cloud
+Requires-Dist: anthropic>=0.25.0; extra == 'cloud'
+Requires-Dist: openai>=1.0; extra == 'cloud'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 🧠 RepoBrief
+
+**Pack any repo into clean LLM context, then chat with it.**
+
+*Using Claude, GPT, or a fully offline Ollama model. No vector DB. No GPU. One command.*
+
+[![PyPI version](https://img.shields.io/pypi/v/repobrief.svg)](https://pypi.org/project/repobrief/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+[Installation](#installation) • [Quick Start](#quick-start) • [Chat Mode](#chat-mode) • [Configuration](#configuration) • [How It Works](#how-it-works)
+
+</div>
+
+---
+
+## Why RepoBrief?
+
+You need to explain your codebase to an LLM — for code review, debugging, onboarding, or docs. Today, you either:
+- **Copy-paste files manually** — slow, error-prone, easy to forget files or include secrets
+- **Use a packing tool** (Repomix, Gitingest) — great, but they just dump text. No follow-up.
+- **Use a RAG chatbot** (ollama-chat, etc.) — needs ChromaDB, embeddings, GPU, and 16GB+ RAM
+
+**RepoBrief does both — packing AND chatting — without the RAM cost:**
+
+| Feature | Repomix | Gitingest | RAG chatbots | **RepoBrief** |
+|---------|---------|-----------|--------------|---------------|
+| Pack repo into LLM context | ✅ | ✅ | ❌ | ✅ |
+| Chat with codebase | ❌ | ❌ | ✅ | ✅ |
+| No vector DB / embeddings | ✅ | ✅ | ❌ | ✅ |
+| Works on 8GB RAM laptop | ✅ | ✅ | ❌ | ✅ |
+| Cloud + local LLM support | ❌ | ❌ | Partial | ✅ |
+| Secret detection & redaction | ✅ | ❌ | ❌ | ✅ |
+| GitHub repository pack/chat | ✅ | ✅ | ❌ | ✅ |
+
+---
+
+## Installation
+
+```bash
+pip install repobrief
+```
+
+For cloud LLM support (Claude/GPT):
+```bash
+pip install repobrief[cloud]
+```
+
+That's it. No Docker, no database, no GPU required.
+
+---
+
+## Quick Start
+
+### Pack a repo (export mode)
+
+```bash
+# Pack the current directory into a markdown digest
+repobrief pack .
+
+# Save to a file, limit to 50k tokens
+repobrief pack ./my-project --max-tokens 50000 -o context.md
+
+# XML format for structured parsing
+repobrief pack . --format xml -o context.xml
+
+# Copy directly to clipboard
+repobrief pack . --clipboard
+
+# Pack directly from a GitHub URL
+repobrief pack https://github.com/pallets/flask
+```
+
+### Chat with a repo
+
+```bash
+# Ask a question using Claude
+export ANTHROPIC_API_KEY=sk-ant-...
+repobrief chat . --backend cloud -q "Where is user authentication handled?"
+
+# Fully offline using Ollama (no API key needed)
+repobrief chat . --backend ollama --model llama3.2:3b -q "What does the payment module do?"
+
+# Interactive mode — ask follow-up questions
+repobrief chat . --backend ollama --model llama3.2:3b
+> Where is the rate limiter implemented?
+> How would I add a new middleware?
+> exit
+```
+
+---
+
+## Chat Mode
+
+RepoBrief's chat mode doesn't use RAG, embeddings, or vector databases. Instead, it:
+
+1. **Packs** your repo into a token-budgeted digest (like export mode)
+2. **Scores** files by relevance to your question (keyword matching, git recency, import centrality)
+3. **Sends** the digest + your question to the chosen LLM backend
+4. **Streams** the answer back to your terminal with real-time markdown rendering
+
+This means it works on any machine that can run Python — even an old laptop with 4GB of free RAM.
+
+### Supported Backends
+
+| Backend | Setup | Best For |
+|---------|-------|----------|
+| **Anthropic (Claude)** | `export ANTHROPIC_API_KEY=sk-ant-...` | Best quality, fast streaming |
+| **OpenAI (GPT)** | `export OPENAI_API_KEY=sk-...` | Great quality, widely available |
+| **Ollama (local)** | `ollama pull llama3.2:3b` | Free, 100% private, offline |
+
+---
+
+## Configuration
+
+### CLI Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--max-tokens` | Token budget for file selection | `100000` |
+| `--format` | Output format: `markdown`, `xml`, `plain` | `markdown` |
+| `-o, --output` | Write digest to file | stdout |
+| `--clipboard` | Copy digest to clipboard | off |
+| `--exclude` | Extra glob patterns to exclude (repeatable) | none |
+| `--redact / --no-redact` | Redact secrets vs exclude files | exclude |
+| `--backend` | LLM backend: `cloud` or `ollama` | `cloud` |
+| `--model` | Model identifier | `claude-sonnet-4-20250514` |
+| `-q, --question` | Question for one-shot chat mode | interactive |
+| `-v, --verbose` | Show detailed debug output | off |
+| `--quiet` | Suppress all output except errors | off |
+
+### Config File
+
+Create `.repobrief.yml` in your project root for persistent settings:
+
+```yaml
+backend: ollama
+model: llama3.2:3b
+max_tokens: 40000
+format: markdown
+exclude:
+  - "*.test.js"
+  - "docs/"
+```
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `REPOBRIEF_API_KEY` | Generic API key (auto-detects provider) |
+| `OLLAMA_HOST` | Ollama server URL (default: `http://localhost:11434`) |
+
+---
+
+## How It Works
+
+```
+repobrief pack/chat <path>
+        │
+        ▼
+  ┌─── SCAN ──────── Walk repo, respect .gitignore, skip binaries
+  │
+  ├─── SECRET SCAN ── Regex detection of API keys, tokens, passwords
+  │
+  ├─── SCORE ──────── Rank files by recency, size, centrality, keyword match
+  │
+  ├─── SELECT ─────── Greedily pick best files within token budget
+  │
+  ├─── PACK ───────── Build directory tree + concatenated file content
+  │
+  └─── OUTPUT
+        ├── Export: save to file / clipboard / stdout
+        └── Chat: send digest + question to Cloud API or local Ollama
+```
+
+### Secret Detection
+
+RepoBrief automatically detects and excludes files containing:
+- AWS access keys, GitHub PATs, OpenAI/Anthropic API keys
+- Private keys (RSA, EC, DSA, OPENSSH)
+- `.env` files with credentials
+- Hardcoded passwords and generic secret assignments
+- Slack tokens, Stripe keys
+
+Use `--redact` to include files with secrets replaced by `[REDACTED]` instead of excluding them entirely.
+
+---
+
+## Development
+
+```bash
+# Clone and setup
+git clone https://github.com/yourusername/repobrief.git
+cd repobrief
+python -m venv .venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+pip install -e ".[dev,cloud]"
+
+# Run tests
+pytest
+
+# Lint and format
+ruff check src/ tests/
+ruff format src/ tests/
+
+# Type check
+mypy src/
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.