comcan-ctx 0.1.0__tar.gz

comcan_ctx-0.1.0/LICENSE

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

comcan_ctx-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: comcan-ctx
+Version: 0.1.0
+Summary: Context management for AI coding agents — state awareness + expertise memory.
+Author: Shriniwas Ramesh Suram
+License: MIT
+Keywords: ai,context,cursor,coding-agent,llm,git
+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 :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tiktoken>=0.5.0
+Requires-Dist: pathspec>=0.11.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: bandit>=1.7; extra == "dev"
+Dynamic: license-file
+
+# 🧠 ComCan — Context Manager for AI Coding Agents
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-green.svg)](https://www.python.org/downloads/)
+
+A **single Python package** that gives AI coding agents (Cursor, Claude Code, etc.) a complete cognitive architecture:
+
+- **🔄 State Engine (RAM)** — Auto-generates a context file on every commit/branch switch via Git hooks
+- **📚 Expertise Engine (Hard Drive)** — Structured JSONL records that accumulate project knowledge over time
+- **🛡️ Security First** — Zero network access, secret scrubbing, no post-install scripts
+
+Designed for **large codebases** where naive context dumps overwhelm LLM token windows.
+
+### Why not just use Cursor/Copilot's native indexing?
+Standard IDE indexing (RAG) is great at finding *where* code is, but terrible at knowing *why* it's there or how branches differ. 
+- **Indexing vs. State:** IDE vector indexes don't understand that you just switched branches. ComCan's `CURRENT_STATE.md` is instantly updated via Git hooks to represent your exact branch reality.
+- **RAG vs. Rules:** RAG discovers old code; it doesn't know what the *new* rules are. ComCan's `expertise` engine teaches agents the *current* architectural decisions.
+- **Static `.md` vs. Dynamic JSONL:** Giant `.cursorrules` files cause merge conflicts and token bloat. ComCan uses domain-sharded, lock-safe JSONL ledgers that agents query surgically.
+
+## Quick Start
+
+```bash
+pip install comcan-ctx
+cd your-project/
+comcan init
+```
+
+That's it. ComCan will:
+1. Create `.comcan/` directory with a `CURRENT_STATE.md` context file
+2. Install Git hooks to auto-update context on commits and branch switches
+3. Create `.cursorrules` so Cursor reads the context automatically
+
+## Usage
+
+### Record Expertise
+
+```bash
+# Quick convention recording
+comcan learn database "Always use WAL mode for SQLite"
+
+# Full record syntax
+comcan record api --type failure "Auth tokens not refreshed" --resolution "Added retry with exponential backoff"
+
+# Add a new domain
+comcan add frontend
+```
+
+### Query Knowledge
+
+```bash
+# View all database expertise
+comcan query database
+
+# Search across everything
+comcan search "authentication"
+
+# Full context dump for agent injection
+comcan prime
+```
+
+### Monitor State
+
+```bash
+# Dashboard
+comcan status
+
+# Manual sync (usually automatic via hooks)
+comcan sync
+
+# Health check
+comcan doctor
+```
+
+## How It Works
+
+```
+1. comcan init        → Creates .comcan/, hooks, .cursorrules
+2. You commit code    → Hook fires, CURRENT_STATE.md auto-updates
+3. AI reads context   → Agent starts with full project awareness
+4. AI solves problem  → You record the lesson with comcan learn
+7. git push           → Teammates' agents get smarter too
+```
+
+## Enterprise Features
+
+ComCan is purpose-built to solve the "AI Cold Start Problem" for large engineering teams:
+
+### 1. Iterative Knowledge Building 🧠
+Instead of pasting the same rules over and over, developers use `comcan learn` to permanently record patterns, bugs, and architectural decisions into domain-specific ledgers. AI agents query these automatically.
+
+### 2. Branch-Aware Context 🔀
+`CURRENT_STATE.md` regenerates on every `git checkout` and `git commit`. If Dev A is on `feature-auth` and Dev B is on `bugfix-ui`, their agents see completely different, branch-accurate contextual states.
+
+### 3. Conflict-Free Merging 🤝
+ComCan configures `.gitattributes` to use `merge=union` for expertise JSONL files. Multiple developers can record new knowledge on different branches simultaneously without ever triggering a merge conflict.
+
+### 4. Concurrent Agent Safety 🔒
+Multiple agents running in parallel? No problem. The expertise engine uses advisory file-locking with atomic temp-file rotation. Multiple IDE tools or CI scripts can write to the same domain simultaneously without data corruption.
+
+### 5. Token Budget Efficiency 📉
+Dumping an enterprise codebase into an LLM window causes hallucinations and massive API costs. ComCan uses a multi-model token budget engine (o200k_base tokenizer aware) to mathematically allocate context window limits across the directory tree, commits, diffs, and expertise records.
+
+## Architecture
+
+```
+.comcan/
+├── CURRENT_STATE.md           # Auto-generated (branch, commits, tree)
+├── comcan.config.yaml         # Configuration
+└── expertise/
+    ├── database.jsonl          # Domain expertise (one per domain)
+    ├── api.jsonl
+    └── frontend.jsonl
+```
+
+### Context Budget Profiles
+
+ComCan uses only ~5% of the model's context window, leaving 90%+ for actual work, via the `context_budget.py` engine (`tiktoken o200k_base`).
+
+| Profile | Context Window | ComCan Budget | Target Models |
+|---------|---------------|---------------|---------------|
+| `standard` | 128k | ~6,400 tokens | GPT-4o, Claude 3.5 Sonnet |
+| `large` | 200k | ~10,000 tokens | Claude 4, Cursor default |
+| `max` | 1M+ | ~50,000 tokens | Gemini 2.5 Pro Max, Claude Opus |
+
+*Note: Why use a budget? Without a token budget, dumping a large enterprise repo into an LLM causes severe "Lost in the Middle" syndrome and drains API credits. ComCan protects your context window by mathematically prioritizing recent commits, diffs, and surgical domain expertise.*
+
+### Native AI Skills & PR Workflows
+
+During `comcan init`, the CLI generates three native AI instruction files:
+1. `.cursorrules` (Legacy IDE rules)
+2. `.cursor/rules/comcan.mdc` (Cursor Rules format)
+3. `.comcan/comcan-skill.md` (Portable generic AI skill)
+
+**Human-in-the-Loop Security**: When an AI agent runs `comcan learn` to solve a problem, it writes directly to `.comcan/expertise/domain.jsonl`. Because this file is tracked in Git, the new "AI Skill" shows up in the Pull Request diff. If the AI hallucinates a bad rule, the Senior Engineer reviewing the PR rejects it. Bad AI knowledge never makes it to the `main` branch.
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `comcan init` | Interactive setup wizard |
+| `comcan sync` | Regenerate context state |
+| `comcan add <domain>` | Create expertise domain |
+| `comcan learn <domain> "lesson"` | Quick-record a convention |
+| `comcan record <domain> --type <type> "content"` | Full record syntax |
+| `comcan query [domain]` | View domain expertise |
+| `comcan search <query>` | Search all expertise |
+| `comcan prime [domains...]` | Full context for agent injection |
+| `comcan status` | Context dashboard |
+| `comcan forget <domain> <id>` | Delete a record |
+| `comcan doctor` | Health & security check |
+
+## Security
+
+ComCan is designed to **never trigger security scanners**:
+
+- ✅ No `shell=True` — all subprocess calls target only `git`
+- ✅ No `setup.py` — pure `pyproject.toml`, no post-install scripts
+- ✅ No network access — zero HTTP calls, no telemetry
+- ✅ No `eval()`/`exec()` — plain readable Python
+- ✅ Secret scrubbing — API keys stripped before writing state files
+- ✅ Path validation — all writes scoped to Git repo root
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

comcan_ctx-0.1.0/README.md

@@ -0,0 +1,169 @@
+# 🧠 ComCan — Context Manager for AI Coding Agents
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-green.svg)](https://www.python.org/downloads/)
+
+A **single Python package** that gives AI coding agents (Cursor, Claude Code, etc.) a complete cognitive architecture:
+
+- **🔄 State Engine (RAM)** — Auto-generates a context file on every commit/branch switch via Git hooks
+- **📚 Expertise Engine (Hard Drive)** — Structured JSONL records that accumulate project knowledge over time
+- **🛡️ Security First** — Zero network access, secret scrubbing, no post-install scripts
+
+Designed for **large codebases** where naive context dumps overwhelm LLM token windows.
+
+### Why not just use Cursor/Copilot's native indexing?
+Standard IDE indexing (RAG) is great at finding *where* code is, but terrible at knowing *why* it's there or how branches differ. 
+- **Indexing vs. State:** IDE vector indexes don't understand that you just switched branches. ComCan's `CURRENT_STATE.md` is instantly updated via Git hooks to represent your exact branch reality.
+- **RAG vs. Rules:** RAG discovers old code; it doesn't know what the *new* rules are. ComCan's `expertise` engine teaches agents the *current* architectural decisions.
+- **Static `.md` vs. Dynamic JSONL:** Giant `.cursorrules` files cause merge conflicts and token bloat. ComCan uses domain-sharded, lock-safe JSONL ledgers that agents query surgically.
+
+## Quick Start
+
+```bash
+pip install comcan-ctx
+cd your-project/
+comcan init
+```
+
+That's it. ComCan will:
+1. Create `.comcan/` directory with a `CURRENT_STATE.md` context file
+2. Install Git hooks to auto-update context on commits and branch switches
+3. Create `.cursorrules` so Cursor reads the context automatically
+
+## Usage
+
+### Record Expertise
+
+```bash
+# Quick convention recording
+comcan learn database "Always use WAL mode for SQLite"
+
+# Full record syntax
+comcan record api --type failure "Auth tokens not refreshed" --resolution "Added retry with exponential backoff"
+
+# Add a new domain
+comcan add frontend
+```
+
+### Query Knowledge
+
+```bash
+# View all database expertise
+comcan query database
+
+# Search across everything
+comcan search "authentication"
+
+# Full context dump for agent injection
+comcan prime
+```
+
+### Monitor State
+
+```bash
+# Dashboard
+comcan status
+
+# Manual sync (usually automatic via hooks)
+comcan sync
+
+# Health check
+comcan doctor
+```
+
+## How It Works
+
+```
+1. comcan init        → Creates .comcan/, hooks, .cursorrules
+2. You commit code    → Hook fires, CURRENT_STATE.md auto-updates
+3. AI reads context   → Agent starts with full project awareness
+4. AI solves problem  → You record the lesson with comcan learn
+7. git push           → Teammates' agents get smarter too
+```
+
+## Enterprise Features
+
+ComCan is purpose-built to solve the "AI Cold Start Problem" for large engineering teams:
+
+### 1. Iterative Knowledge Building 🧠
+Instead of pasting the same rules over and over, developers use `comcan learn` to permanently record patterns, bugs, and architectural decisions into domain-specific ledgers. AI agents query these automatically.
+
+### 2. Branch-Aware Context 🔀
+`CURRENT_STATE.md` regenerates on every `git checkout` and `git commit`. If Dev A is on `feature-auth` and Dev B is on `bugfix-ui`, their agents see completely different, branch-accurate contextual states.
+
+### 3. Conflict-Free Merging 🤝
+ComCan configures `.gitattributes` to use `merge=union` for expertise JSONL files. Multiple developers can record new knowledge on different branches simultaneously without ever triggering a merge conflict.
+
+### 4. Concurrent Agent Safety 🔒
+Multiple agents running in parallel? No problem. The expertise engine uses advisory file-locking with atomic temp-file rotation. Multiple IDE tools or CI scripts can write to the same domain simultaneously without data corruption.
+
+### 5. Token Budget Efficiency 📉
+Dumping an enterprise codebase into an LLM window causes hallucinations and massive API costs. ComCan uses a multi-model token budget engine (o200k_base tokenizer aware) to mathematically allocate context window limits across the directory tree, commits, diffs, and expertise records.
+
+## Architecture
+
+```
+.comcan/
+├── CURRENT_STATE.md           # Auto-generated (branch, commits, tree)
+├── comcan.config.yaml         # Configuration
+└── expertise/
+    ├── database.jsonl          # Domain expertise (one per domain)
+    ├── api.jsonl
+    └── frontend.jsonl
+```
+
+### Context Budget Profiles
+
+ComCan uses only ~5% of the model's context window, leaving 90%+ for actual work, via the `context_budget.py` engine (`tiktoken o200k_base`).
+
+| Profile | Context Window | ComCan Budget | Target Models |
+|---------|---------------|---------------|---------------|
+| `standard` | 128k | ~6,400 tokens | GPT-4o, Claude 3.5 Sonnet |
+| `large` | 200k | ~10,000 tokens | Claude 4, Cursor default |
+| `max` | 1M+ | ~50,000 tokens | Gemini 2.5 Pro Max, Claude Opus |
+
+*Note: Why use a budget? Without a token budget, dumping a large enterprise repo into an LLM causes severe "Lost in the Middle" syndrome and drains API credits. ComCan protects your context window by mathematically prioritizing recent commits, diffs, and surgical domain expertise.*
+
+### Native AI Skills & PR Workflows
+
+During `comcan init`, the CLI generates three native AI instruction files:
+1. `.cursorrules` (Legacy IDE rules)
+2. `.cursor/rules/comcan.mdc` (Cursor Rules format)
+3. `.comcan/comcan-skill.md` (Portable generic AI skill)
+
+**Human-in-the-Loop Security**: When an AI agent runs `comcan learn` to solve a problem, it writes directly to `.comcan/expertise/domain.jsonl`. Because this file is tracked in Git, the new "AI Skill" shows up in the Pull Request diff. If the AI hallucinates a bad rule, the Senior Engineer reviewing the PR rejects it. Bad AI knowledge never makes it to the `main` branch.
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `comcan init` | Interactive setup wizard |
+| `comcan sync` | Regenerate context state |
+| `comcan add <domain>` | Create expertise domain |
+| `comcan learn <domain> "lesson"` | Quick-record a convention |
+| `comcan record <domain> --type <type> "content"` | Full record syntax |
+| `comcan query [domain]` | View domain expertise |
+| `comcan search <query>` | Search all expertise |
+| `comcan prime [domains...]` | Full context for agent injection |
+| `comcan status` | Context dashboard |
+| `comcan forget <domain> <id>` | Delete a record |
+| `comcan doctor` | Health & security check |
+
+## Security
+
+ComCan is designed to **never trigger security scanners**:
+
+- ✅ No `shell=True` — all subprocess calls target only `git`
+- ✅ No `setup.py` — pure `pyproject.toml`, no post-install scripts
+- ✅ No network access — zero HTTP calls, no telemetry
+- ✅ No `eval()`/`exec()` — plain readable Python
+- ✅ Secret scrubbing — API keys stripped before writing state files
+- ✅ Path validation — all writes scoped to Git repo root
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

comcan_ctx-0.1.0/comcan/__init__.py

@@ -0,0 +1,3 @@
+"""ComCan — Context Manager for AI Coding Agents."""
+
+__version__ = "0.1.0"