contexta-ai 2.0.0__tar.gz

contexta_ai-2.0.0/.github/workflows/build-linux.yml

@@ -0,0 +1,43 @@
+name: Build Linux Executable
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build-linux:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install Linux GUI dependency
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y python3-tk
+
+      - name: Install runtime and build dependencies
+        run: python -m pip install --upgrade pip -r requirements-build.txt
+
+      - name: Build native Linux executable
+        run: |
+          chmod +x build.sh
+          ./build.sh
+
+      - name: Upload Linux package
+        uses: actions/upload-artifact@v4
+        with:
+          name: contexta-linux
+          path: dist/contexta-linux.tar.gz
+          if-no-files-found: error

contexta_ai-2.0.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

contexta_ai-2.0.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+venv/
+.venv/
+.venv-linux/
+.venvs/
+.pytest_cache/
+.mypy_cache/
+.DS_Store
+Thumbs.db
+*.swp
+resume - *.md
+tests/.tmp/
+nuitka-crash-report.xml

contexta_ai-2.0.0/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+Versioning: [Semantic Versioning](https://semver.org/)
+
+---
+
+## [1.6.0] - 2026-04-19
+
+### Added
+- **Token-Lean compression mode** - new `lean` option exports only file metadata and up to 5 signatures per file (~65 tokens/file). Best for quick orientation or tight API budget constraints
+- **Inline blob sanitization** - any line longer than 400 chars that looks like a base64/binary payload (e.g. embedded icons, encoded assets) is automatically collapsed into a one-line placeholder comment in every compression mode, including Full Content. A 15 000-char base64 constant adds zero review value to any export
+- **Multi-language project detection** - engine now correctly identifies Django (from imports alone, without `manage.py`), Kotlin Android, Spring Boot with Gradle, and more; fixes a long-standing bias where many projects were misclassified as PHP CRUD
+- **Kotlin, Swift, C++, C, Scala, Lua, R, Nim, Zig** - added to language weights and tech labels; Kotlin/Java JVM detection unified so Kotlin-only Android projects are recognized correctly
+- **Domain detection from directory names** - `boards/`, `sprints/`, `patients/`, `products/` and similar folder names now boost the domain classification without requiring manifest files
+- **Syntax-aware parsing foundation** - Contexta now ships with `tree-sitter` and a dedicated syntax layer for stronger multi-language symbol extraction
+- **Foundation runtime dependencies** - `pathspec`, `charset-normalizer`, `tiktoken`, and `rapidfuzz` are now part of the runtime analysis stack
+- **Linux install bundle** - Linux builds now ship as `contexta-linux.tar.gz` with an `install.sh` helper for user-local installs
+- **Optional Windows installer support** - `build.bat` now emits `contexta-setup.exe` whenever Inno Setup is available locally
+
+### Changed
+- **Gitignore handling** - scan filtering now uses Git-style pattern matching via `pathspec` instead of relying only on hand-rolled glob rules
+- **File decoding** - file reading now prefers `charset-normalizer` before strict encoding fallbacks, improving support for real-world mixed encodings
+- **Token estimation** - renderer token sizing now uses `tiktoken` instead of character heuristics alone when available
+- **Test relationship scoring** - related-test detection now uses stronger fuzzy matching instead of substring checks alone
+- **Windows build pipeline** - official Windows builds now use Nuitka onefile output
+- **Linux build pipeline** - Unix builds now package both a portable binary and an installable tarball bundle
+- **File role descriptions** - `requirements.txt`, `build.bat`, `build.sh` now show generic descriptions by default; project-specific text only appears when Contexta analyzes itself
+- **XML file roles** - `AndroidManifest.xml`, `beans.xml`, `web.xml`, `docker-compose.yml`, `logback.xml`, and CI/CD workflow files now get accurate role descriptions
+
+### Fixed
+- **Scope vs insights bug** - `compute_project_type_signals` and `detect_domain_label` were accidentally receiving test and doc files in their input, causing wrong project type scores; now correctly filtered to runtime files only
+- **Multi-language symbol extraction** - added better extraction coverage for Java, C#, Go, and Rust, plus tree-sitter-backed paths for supported languages
+- **Scanner robustness** - unreadable files and legacy encodings now fall back more gracefully instead of being discarded too early
+
+---
+
+## [1.3.1] - 2026-04-11
+
+### Changed
+- **Compact, resizable interface** - reduced the default window size, added proper resize behavior, and tightened spacing so the app feels lighter on smaller screens
+- **App branding refresh** - the GUI now uses the bundled `icon.ico` as the real window/app icon instead of the default feather-style fallback
+- **Safer diff flow** - diff mode now behaves more predictably when there are no changed files, instead of surprising the user with a full-project export
+
+### Added
+- **36 unit tests** - expanded coverage for hidden-file filtering, diff behavior, renderer output, and related safety cases
+
+### Fixed
+- **Hidden file filtering** - dotfiles such as `.env` stay excluded by default when hidden files are not enabled
+- **Git diff detection** - changed-file exports now better reflect staged, unstaged, and new-file workflows
+- **Clipboard reliability** - clipboard writes now happen on the Tk main thread to avoid intermittent GUI issues
+
+---
+
+## [1.3.0] - 2025-04-10
+
+### Changed
+- **Modular architecture** - split into `scanner.py`, `renderer.py`, `theme.py`, `ui.py`, `cli.py`; `mdcodebrief.py` is now a clean 20-line entry point
+- **Improved `.gitignore` parser** - now supports negation (`!`), rooted patterns (`/build`), directory-only patterns (`dist/`), and `**` wildcards
+- **Version consistency** - `__version__` unified across all modules
+
+### Added
+- **33 unit tests** - covering scanner, renderer, gitignore parser, token estimation, and tree building (`unittest`, zero extra dependencies)
+- Screenshot added to README with download button
+
+### Fixed
+- Windows SmartScreen false positive - removed `--add-data` from build scripts (`--noupx` retained)
+
+---
+
+## [1.2.0] - 2025-04-10
+
+### Added
+- Dark / Light theme toggle (instant switch, no rebuild)
+- Pill-style toggle switches replacing checkboxes
+- Two-column layout (AI Instruction + Options side by side)
+- Status pill indicator (shows Scanning... / Done / Error)
+
+### Fixed
+- White Entry field on Windows (readonly state color bug)
+- Progress bar style name incompatible with Python 3.14
+
+---
+
+## [1.1.0] - 2025-04-10
+
+### Added
+- Native `.gitignore` support
+- Copy to clipboard - GUI button + `--copy` / `-c` CLI flag
+- Token estimation with model hints in log and footer
+- Git diff mode - `--diff` and `--staged` flags
+- AI instruction injection - GUI text field + `-p / --prompt` CLI flag
+- Build scripts (`build.bat`, `build.sh`)
+
+---
+
+## [1.0.0] - 2025-04-10
+
+### Added
+- GUI with dark theme (tkinter, zero dependencies)
+- CLI mode
+- Recursive project scanner with smart filtering
+- ASCII directory tree
+- Syntax-highlighted code blocks for 50+ extensions
+- Multi-encoding file reader (UTF-8, latin-1, cp1252, UTF-16)
+- Safety limits: 1 000 lines/file, 2 000 files/scan
+- Cross-platform Desktop path detection
+- MIT License

contexta_ai-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing to Contexta
+
+Thank you for considering a contribution!
+
+## Ground rules
+
+- Runtime dependencies should stay small and high-leverage
+- Optional packaging tools such as **Nuitka** or **PyInstaller** must stay out of runtime code paths
+- Python **3.10+** syntax is acceptable
+- Every PR must keep the project runnable with `python contexta.py` after `python -m pip install -r requirements.txt`
+
+## How to contribute
+
+1. Fork and clone
+2. Create a branch: `git checkout -b feature/short-description`
+3. Commit: `git commit -m "feat: description"`
+4. Push and open a Pull Request against `main`
+
+## Adding language extensions
+
+```python
+# In contexta_app/scanner.py → CODE_EXTENSIONS dict
+".xyz": "xyz",
+```
+
+## Reporting bugs
+
+Open an issue with OS, Python version, and full error traceback.

contexta_ai-2.0.0/LICENSE

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

contexta_ai-2.0.0/PKG-INFO

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: contexta-ai
+Version: 2.0.0
+Summary: AI-native codebase context engine. Scans projects and serves intelligent context packs to Claude Code, Cursor, Windsurf, and any MCP-compatible tool.
+Project-URL: Homepage, https://github.com/pablokaua03/contexta
+Project-URL: Repository, https://github.com/pablokaua03/contexta
+Author-email: Pablo Kaua <help@spacegroupusa.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,codebase,context,cursor,developer-tools,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: charset-normalizer<4,>=3.4
+Requires-Dist: mcp[cli]<2,>=1.9
+Requires-Dist: pathspec<1.1,>=0.12
+Requires-Dist: rapidfuzz<4,>=3.14
+Requires-Dist: tiktoken<1,>=0.12
+Requires-Dist: tree-sitter-language-pack<2,>=1.6
+Requires-Dist: tree-sitter<0.26,>=0.25
+Provides-Extra: all-ai
+Requires-Dist: anthropic<1,>=0.52; extra == 'all-ai'
+Requires-Dist: google-genai<2,>=1.14; extra == 'all-ai'
+Requires-Dist: openai<2,>=1.82; extra == 'all-ai'
+Provides-Extra: claude
+Requires-Dist: anthropic<1,>=0.52; extra == 'claude'
+Provides-Extra: gemini
+Requires-Dist: google-genai<2,>=1.14; extra == 'gemini'
+Provides-Extra: gui
+Provides-Extra: openai
+Requires-Dist: openai<2,>=1.82; extra == 'openai'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Contexta
+
+**AI-native codebase context engine. Serves intelligent project context to Claude Code, Cursor, Windsurf, and any MCP-compatible tool — or generates curated context packs for manual use.**
+
+[![Python](https://img.shields.io/badge/Python-3.11%2B-blue?logo=python&logoColor=white)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)]()
+[![Version](https://img.shields.io/badge/Version-2.0.0-purple)]()
+[![MCP](https://img.shields.io/badge/MCP-Compatible-orange)]()
+
+<br>
+
+[<img src="https://img.shields.io/badge/pip%20install%20contexta--ai-3776AB?style=for-the-badge&logo=pypi&logoColor=white" height="42">](https://pypi.org/project/contexta-ai/)
+&nbsp;&nbsp;
+[<img src="https://img.shields.io/badge/Download%20for%20Windows-0078D4?style=for-the-badge&logo=windows&logoColor=white" height="42">](https://github.com/pablokaua03/Contexta/releases/latest/download/contexta.exe)
+&nbsp;&nbsp;
+[<img src="https://img.shields.io/badge/Download%20for%20Linux-E95420?style=for-the-badge&logo=linux&logoColor=white" height="42">](https://github.com/pablokaua03/Contexta/releases/latest/download/contexta-linux.tar.gz)
+
+> Install via pip, download the portable executable, or run from source.
+
+<br>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="assets/white.png">
+  <img alt="Contexta interface preview" src="assets/dark.png">
+</picture>
+
+</div>
+
+---
+
+## What is Contexta
+
+Contexta analyzes codebases and serves intelligent, curated context to AI tools. Instead of dumping files blindly, it understands project structure, detects frameworks, ranks files by importance, and delivers exactly what an AI needs.
+
+**Three ways to use it:**
+
+| Mode | Command | What it does |
+|---|---|---|
+| **MCP Server** | `contexta serve` | Runs as a tool server — Claude Code, Cursor, Windsurf call it automatically |
+| **CLI** | `contexta ./project --pack onboarding` | Generates a context pack Markdown file |
+| **GUI** | `contexta` | Desktop app with visual controls |
+
+---
+
+## MCP Server (recommended)
+
+The MCP server is the primary way to use Contexta. AI coding assistants call it as a tool to understand your project — no copy-paste needed.
+
+### Setup
+
+Add to your MCP configuration (Claude Code, Cursor, Windsurf, etc.):
+
+```json
+{
+  "mcpServers": {
+    "contexta": {
+      "command": "contexta",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+Or if running from source:
+
+```json
+{
+  "mcpServers": {
+    "contexta": {
+      "command": "python",
+      "args": ["/path/to/contexta_mcp.py"]
+    }
+  }
+}
+```
+
+### Available tools
+
+| Tool | What it does |
+|---|---|
+| `scan_project` | Quick fingerprint — type, language, frameworks, deps, entry points |
+| `get_architecture` | Module relationships, folder structure, risks, key patterns |
+| `generate_context` | Full AI-optimized context pack with all preset options |
+| `find_files` | Search files by name, extension, or keyword |
+| `read_files` | Read specific file contents |
+| `list_packs` | List available pack presets |
+| `cache_status` | Show cache hit/miss statistics |
+| `refresh_cache` | Force-refresh cached analysis |
+
+### Smart cache
+
+Results are cached in memory with automatic invalidation. First call analyzes the project (~700ms), subsequent calls return in ~2ms until files change on disk. The cache monitors file mtimes and manifest files — when you edit code, the next call recomputes automatically.
+
+---
+
+## Install
+
+### Option A: pip (recommended)
+
+```bash
+pip install contexta-ai
+```
+
+Optional AI API integrations:
+
+```bash
+pip install contexta-ai[claude]    # Claude API
+pip install contexta-ai[gemini]    # Gemini API
+pip install contexta-ai[openai]    # OpenAI API
+pip install contexta-ai[all-ai]    # All three
+```
+
+### Option B: Portable executables
+
+- **Windows**: download [`contexta.exe`](https://github.com/pablokaua03/Contexta/releases/latest/download/contexta.exe)
+- **Linux**: download [`contexta-linux.tar.gz`](https://github.com/pablokaua03/Contexta/releases/latest/download/contexta-linux.tar.gz)
+
+### Option C: From source
+
+```bash
+git clone https://github.com/pablokaua03/Contexta.git
+cd Contexta
+pip install -r requirements.txt
+python contexta.py
+```
+
+---
+
+## CLI usage
+
+```bash
+# Generate context packs
+contexta ./project                                          # default pack
+contexta ./project --pack onboarding                        # understand a new codebase
+contexta ./project --pack raw_files                         # clean path + content dump
+contexta ./project --pack pr_review --diff --copy           # review changes
+contexta ./project --mode debug --focus "auth flow"         # debug a specific area
+
+# AI API integration — send context + question directly to an AI
+contexta ./project --ask "what are the main security risks?"
+contexta ./project --ask "explain the architecture" --provider claude
+
+# Configure AI API keys
+contexta --configure-ai
+```
+
+### CLI flags
+
+| Flag | Description |
+|---|---|
+| `--pack` | Preset: `custom`, `chatgpt`, `onboarding`, `pr_review`, `risk_review`, `debug`, `backend`, `frontend`, `changes_related`, `raw_files` |
+| `--mode` | Context mode: `full`, `debug`, `feature`, `diff`, `onboarding`, `refactor` |
+| `--compression` | `full`, `balanced`, `focused`, `signatures`, `lean` |
+| `--ai` | Target AI profile: `generic`, `chatgpt`, `claude`, `gemini`, `copilot` |
+| `--task` | Task profile: `general`, `ai_handoff`, `bug_report`, `code_review`, `explain_project`, `risk_analysis`, `refactor_request`, `pr_summary`, `write_tests`, `find_dead_code` |
+| `--focus` | Bias scoring around a topic (e.g. `"auth flow"`, `"database"`) |
+| `--diff` / `--staged` | Use git changes as context |
+| `--ask` | Send context pack + prompt to an AI API |
+| `--provider` | AI provider: `claude`, `gemini`, `openai` |
+| `--api-key` | API key (also reads `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `OPENAI_API_KEY`) |
+| `--configure-ai` | Interactive AI API setup |
+| `-c` / `--copy` | Copy output to clipboard |
+| `-o` / `--output` | Custom output path |
+
+---
+
+## Context packs
+
+| Pack | Best for |
+|---|---|
+| `onboarding` | Understanding a new codebase fast |
+| `pr_review` | Code review with change context |
+| `risk_review` | Regression hotspots, missing coverage, broad-impact modules |
+| `debug` | Bug hunting with changed/suspicious files prioritized |
+| `backend` / `frontend` | Bias toward one side of the app |
+| `changes_related` | Git changes + nearby relevant files |
+| `raw_files` | Clean dump of important files — path + full content, no analysis |
+| `chatgpt` | General-purpose ChatGPT preset |
+| `custom` | Full manual control |
+
+---
+
+## What Contexta exports
+
+Depending on pack, mode, and task, the output can include:
+
+- Project summary with detected technologies, entry points, purpose, and central modules
+- Read-this-first path through the repository
+- Main execution flow narrative
+- Core files, supporting files, related tests, and changed-file context
+- Relationship maps and risk notes
+- Score breakdown explaining why each file was selected
+- Curated Markdown payload ready for any AI tool
+
+---
+
+## Main features
+
+| Feature | Detail |
+|---|---|
+| **MCP Server** | `contexta serve` — AI tools call it as a tool server with smart caching |
+| **AI API integration** | `--ask` sends context directly to Claude, Gemini, or OpenAI |
+| **Smart cache** | ~2ms cached responses with automatic mtime-based invalidation |
+| **Raw files pack** | Clean path + content dump for simple AI workflows |
+| **GUI + CLI** | Desktop app for visual use, CLI for scripting and automation |
+| **Project fingerprinting** | Detects stack, frameworks, domain, and project type automatically |
+| **Syntax-aware analysis** | tree-sitter + heuristic fallback for symbol extraction |
+| **Multi-language** | Python, JS/TS, Go, Rust, PHP, Java, C#, Kotlin, Swift, C++ and more |
+| **Token guidance** | tiktoken-backed estimates for pack sizing |
+| **Inline blob protection** | Collapses base64/binary literals automatically |
+| **PyPI package** | `pip install contexta-ai` with optional AI extras |
+
+---
+
+## Build from source
+
+```bash
+# Windows (requires Visual Studio C++ Build Tools)
+.\build.bat
+
+# Linux / macOS
+chmod +x build.sh && ./build.sh
+```
+
+Build outputs: `dist/contexta.exe` (Windows), `dist/contexta` (Linux/macOS), `dist/contexta-linux.tar.gz` (Linux bundle).
+
+---
+
+## Run tests
+
+```bash
+python -m pytest tests/ -k "not test_relation_score"
+```
+
+---
+
+## Security and behavior
+
+- Read-only: Contexta does not modify the scanned project
+- No runtime telemetry or network requirement (except optional `--ask` AI calls)
+- Scan limits prevent runaway exports
+- Embedded binary/blob payloads are suppressed automatically
+- AI API keys are stored locally in `~/.contexta/ai_config.json` when using `--configure-ai`
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+[MIT](LICENSE) © [pablokaua03](https://github.com/pablokaua03)