repotrim 0.1.0__tar.gz

repotrim-0.1.0/LICENSE

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

repotrim-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: repotrim
+Version: 0.1.0
+Summary: Create minimal context packets for AI coding agents.
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.9
+Provides-Extra: semantic
+Requires-Dist: sentence-transformers>=2.7; extra == "semantic"
+Dynamic: license-file
+
+RepoTrim turns a messy codebase into a focused context packet for AI coding agents.
+
+# RepoTrim
+
+RepoTrim is a local CLI context engine for Codex, Claude Code, Cursor, and other AI coding tools. It scans a repository, filters out junk and risky files, understands the task, ranks the files most likely to matter, optionally applies semantic search, and writes an agent-ready context packet.
+
+## Why RepoTrim
+
+Most AI coding sessions start with too much context or the wrong context.
+
+| Before | After |
+| --- | --- |
+| Paste or attach a whole repo | Generate a focused packet |
+| Generated files, caches, lock files, and duplicates add noise | Junk and generated paths are ignored |
+| Secrets can slip into prompts | Secret-looking files are skipped |
+| The agent guesses where to start | RepoTrim ranks task-relevant entry points |
+| Context windows fill with unrelated files | Token count is usually reduced by 70-90% |
+| Hard to audit what was sent | Packet, token savings, and agent reports are written to disk |
+
+RepoTrim is a pre-step. Run it before opening Codex, Claude Code, or Cursor, then give the generated packet to the agent instead of the entire repository.
+
+## Install
+
+```bash
+pip install repotrim
+```
+
+Optional semantic search support:
+
+```bash
+pip install "repotrim[semantic]"
+```
+
+## Quick Start
+
+```bash
+repotrim task "restrict admin screens" --semantic
+```
+
+Sample output:
+
+```text
+RepoTrim Task Report
+
+Task:
+restrict admin screens
+
+Task type:
+Access control / RBAC
+
+Primary files:
+1. lib/rbac.ts
+   Score: 142
+   Tokens: 420
+   Why:
+   - prioritized core RBAC policy file
+
+2. middleware.ts
+   Score: 118
+   Tokens: 310
+   Why:
+   - prioritized middleware/protected route file
+
+Semantic search: 12 chunks from lexical-fallback (repotrim-lexical-fallback)
+context_packet.md written - paste into Claude or Codex to one-shot this.
+
+RepoTrim Token Savings
+----------------------
+Files counted:              184
+Full repo estimate:         154,963 tokens
+Context packet estimate:    15,994 tokens
+Tokens saved:               138,969 tokens
+Reduction:                  89.7%
+Compression ratio:          9.7x smaller
+```
+
+RepoTrim writes the main packet to:
+
+```text
+.repotrim/context_packet.md
+```
+
+## How It Works
+
+Pipeline:
+
+```text
+task -> scan -> classify -> rank -> semantic boost -> token fit -> packet -> agent report
+```
+
+Briefly:
+
+1. Parse the coding task and classify the intent.
+2. Scan the repo with shared ignore rules for caches, generated output, secrets, binaries, and oversized files.
+3. Extract lightweight file metadata: language, symbols, imports, comments, size, and token estimate.
+4. Rank files using deterministic task-aware scoring.
+5. Optionally chunk and semantically search source files, then blend those matches into the ranking.
+6. Fit selected files into a context budget.
+7. Write `context_packet.md`, token savings data, and agent planning artifacts.
+
+## Key Features
+
+- Local-first: no repo upload required
+- No AI API required for the core workflow
+- Deterministic ranking by default
+- Secret and generated-file filtering
+- Task-aware file ranking for common engineering work
+- Optional semantic search with local fallback
+- Token savings report
+- Agent plan report
+- JSON output for automation
+- Designed as a pre-step before Codex, Claude Code, and Cursor
+
+## Who It's For
+
+- Developers using AI agents on medium or large repositories
+- Teams that want repeatable context selection instead of ad hoc file picking
+- Maintainers who need to avoid sending secrets, caches, and generated output to AI tools
+- Engineers building automation around AI-assisted code changes
+- Anyone trying to keep agent prompts small enough to be useful
+
+## Roadmap
+
+- Better scoring for framework-specific project layouts
+- Evaluation benchmark for ranking quality and token reduction
+- Dedicated Codex, Claude Code, and Cursor output formats
+
+## Contributing
+
+Issues and pull requests are welcome. Keep changes focused, add tests for ranking or packet behavior, and include a real CLI example when changing user-facing output.
+
+For local development:
+
+```bash
+pip install -e .
+pytest
+```
+
+## License
+
+MIT

repotrim-0.1.0/README.md

@@ -0,0 +1,141 @@
+RepoTrim turns a messy codebase into a focused context packet for AI coding agents.
+
+# RepoTrim
+
+RepoTrim is a local CLI context engine for Codex, Claude Code, Cursor, and other AI coding tools. It scans a repository, filters out junk and risky files, understands the task, ranks the files most likely to matter, optionally applies semantic search, and writes an agent-ready context packet.
+
+## Why RepoTrim
+
+Most AI coding sessions start with too much context or the wrong context.
+
+| Before | After |
+| --- | --- |
+| Paste or attach a whole repo | Generate a focused packet |
+| Generated files, caches, lock files, and duplicates add noise | Junk and generated paths are ignored |
+| Secrets can slip into prompts | Secret-looking files are skipped |
+| The agent guesses where to start | RepoTrim ranks task-relevant entry points |
+| Context windows fill with unrelated files | Token count is usually reduced by 70-90% |
+| Hard to audit what was sent | Packet, token savings, and agent reports are written to disk |
+
+RepoTrim is a pre-step. Run it before opening Codex, Claude Code, or Cursor, then give the generated packet to the agent instead of the entire repository.
+
+## Install
+
+```bash
+pip install repotrim
+```
+
+Optional semantic search support:
+
+```bash
+pip install "repotrim[semantic]"
+```
+
+## Quick Start
+
+```bash
+repotrim task "restrict admin screens" --semantic
+```
+
+Sample output:
+
+```text
+RepoTrim Task Report
+
+Task:
+restrict admin screens
+
+Task type:
+Access control / RBAC
+
+Primary files:
+1. lib/rbac.ts
+   Score: 142
+   Tokens: 420
+   Why:
+   - prioritized core RBAC policy file
+
+2. middleware.ts
+   Score: 118
+   Tokens: 310
+   Why:
+   - prioritized middleware/protected route file
+
+Semantic search: 12 chunks from lexical-fallback (repotrim-lexical-fallback)
+context_packet.md written - paste into Claude or Codex to one-shot this.
+
+RepoTrim Token Savings
+----------------------
+Files counted:              184
+Full repo estimate:         154,963 tokens
+Context packet estimate:    15,994 tokens
+Tokens saved:               138,969 tokens
+Reduction:                  89.7%
+Compression ratio:          9.7x smaller
+```
+
+RepoTrim writes the main packet to:
+
+```text
+.repotrim/context_packet.md
+```
+
+## How It Works
+
+Pipeline:
+
+```text
+task -> scan -> classify -> rank -> semantic boost -> token fit -> packet -> agent report
+```
+
+Briefly:
+
+1. Parse the coding task and classify the intent.
+2. Scan the repo with shared ignore rules for caches, generated output, secrets, binaries, and oversized files.
+3. Extract lightweight file metadata: language, symbols, imports, comments, size, and token estimate.
+4. Rank files using deterministic task-aware scoring.
+5. Optionally chunk and semantically search source files, then blend those matches into the ranking.
+6. Fit selected files into a context budget.
+7. Write `context_packet.md`, token savings data, and agent planning artifacts.
+
+## Key Features
+
+- Local-first: no repo upload required
+- No AI API required for the core workflow
+- Deterministic ranking by default
+- Secret and generated-file filtering
+- Task-aware file ranking for common engineering work
+- Optional semantic search with local fallback
+- Token savings report
+- Agent plan report
+- JSON output for automation
+- Designed as a pre-step before Codex, Claude Code, and Cursor
+
+## Who It's For
+
+- Developers using AI agents on medium or large repositories
+- Teams that want repeatable context selection instead of ad hoc file picking
+- Maintainers who need to avoid sending secrets, caches, and generated output to AI tools
+- Engineers building automation around AI-assisted code changes
+- Anyone trying to keep agent prompts small enough to be useful
+
+## Roadmap
+
+- Better scoring for framework-specific project layouts
+- Evaluation benchmark for ranking quality and token reduction
+- Dedicated Codex, Claude Code, and Cursor output formats
+
+## Contributing
+
+Issues and pull requests are welcome. Keep changes focused, add tests for ranking or packet behavior, and include a real CLI example when changing user-facing output.
+
+For local development:
+
+```bash
+pip install -e .
+pytest
+```
+
+## License
+
+MIT

repotrim-0.1.0/__init__.py

@@ -0,0 +1,3 @@
+"""RepoTrim: minimal context packets for AI coding agents."""
+
+__version__ = "0.1.0"

repotrim-0.1.0/agents/__init__.py

@@ -0,0 +1,6 @@
+"""Deterministic agentic planning helpers for RepoTrim."""
+
+from .state import AgentState
+from .workflow import run_agent_plan
+
+__all__ = ["AgentState", "run_agent_plan"]

repotrim-0.1.0/agents/report.py

@@ -0,0 +1,64 @@
+"""Report writers for the agentic context builder."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..models import RankedFile
+from ..utils import ensure_cache_dir, write_json
+from .state import AgentState
+
+
+def _why_lines(items: list[RankedFile]) -> list[str]:
+    lines: list[str] = []
+    for item in items:
+        reason = item.reasons[0] if item.reasons else "selected by task relevance"
+        lines.append(f"- `{item.file.relative_path}`: {reason}")
+    return lines or ["- No files were selected."]
+
+
+def write_agent_report(repo_path: Path, state: AgentState, primary: list[RankedFile], related: list[RankedFile]) -> Path:
+    output_path = ensure_cache_dir(repo_path) / "agent_report.md"
+    lines = [
+        "# RepoTrim Agent Report",
+        "",
+        "## Task",
+        state.task,
+        "",
+        "## Task Interpretation",
+        state.interpretation or state.task_type,
+        "",
+        "## Agent Steps",
+    ]
+    lines.extend(f"{index}. {step}" for index, step in enumerate(state.steps_taken, start=1))
+    lines.extend(["", "## Selected Files", "### Primary"])
+    lines.extend(f"- {item.file.relative_path}" for item in primary)
+    if not primary:
+        lines.append("- None")
+    lines.extend(["", "### Related / Supporting"])
+    lines.extend(f"- {item.file.relative_path}" for item in related)
+    if not related:
+        lines.append("- None")
+    lines.extend(["", "## Why These Files Matter"])
+    lines.extend(_why_lines([*primary, *related]))
+    lines.extend(["", "## Missing Context / Warnings"])
+    lines.extend(f"- {warning}" for warning in state.warnings)
+    if not state.warnings:
+        lines.append("- None")
+    lines.extend([
+        "",
+        "## Context Quality Score",
+        f"{state.quality_score}/100",
+        "",
+        "## Suggested Prompt For Coding Agent",
+        "Use the selected context to implement the task. Pay special attention to the warnings above. Keep the patch minimal and add/update tests if possible.",
+        "",
+    ])
+    output_path.write_text("\n".join(lines), encoding="utf-8", newline="\n")
+    return output_path
+
+
+def write_agent_json(repo_path: Path, state: AgentState) -> Path:
+    output_path = ensure_cache_dir(repo_path) / "agent.json"
+    write_json(output_path, state.to_dict())
+    return output_path

repotrim-0.1.0/agents/reviewer.py

@@ -0,0 +1,227 @@
+"""Rule-based context review and quality scoring."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..models import RankedFile
+from ..reporter import INTERPRETATIONS
+from ..scanner import read_text_safely
+from ..task_analyzer import INTENT_LABELS
+from .state import AgentState
+
+
+CATEGORY_TERMS = {
+    "test": {"test", "tests", "spec", "fixture"},
+    "ui": {"component", "page", "view", "screen", "ui", "tsx", "jsx", "vue", "svelte", "css", "scss"},
+    "backend": {"api", "route", "routes", "controller", "service", "server", "middleware", "handler"},
+    "auth": {"auth", "role", "roles", "permission", "permissions", "rbac", "guard", "admin", "policy", "user"},
+    "route": {"route", "routes", "router", "routing", "page"},
+    "model": {"model", "schema", "entity", "repository", "migration", "prisma"},
+    "config": {"config", "settings", "env", "toml", "yaml", "json", "dockerfile"},
+    "docs": {"readme", "docs", "md"},
+}
+
+REQUIRED_BY_INTENT = {
+    "access_control": {"auth", "route", "test"},
+    "authentication": {"auth", "route", "test"},
+    "frontend_feature": {"ui", "route", "test"},
+    "backend_feature": {"backend", "model", "test"},
+    "database_feature": {"model", "config", "test"},
+    "config_deployment": {"config", "test"},
+    "testing_task": {"test"},
+}
+
+RBAC_REQUIRED_CATEGORIES = {
+    "rbac_rules",
+    "auth_role_source",
+    "middleware_routes",
+    "navigation_visibility",
+    "protected_pages",
+    "backend_enforcement",
+    "tests",
+}
+
+
+def _path_tokens(path: str) -> set[str]:
+    value = path.replace("\\", "/").lower()
+    name = Path(value).name
+    raw = value.replace(".", "/").replace("-", "/").replace("_", "/")
+    return {part for part in raw.split("/") if part} | {name}
+
+
+def covered_categories(paths: list[str]) -> set[str]:
+    covered: set[str] = set()
+    for path in paths:
+        tokens = _path_tokens(path)
+        for category, terms in CATEGORY_TERMS.items():
+            if tokens & terms or any(term in path.lower() for term in terms):
+                covered.add(category)
+    return covered
+
+
+def _selected_text(state: AgentState, ranked_files: list[RankedFile]) -> dict[str, str]:
+    text_by_path: dict[str, str] = {}
+    for item in ranked_files:
+        relative = item.file.relative_path
+        text = read_text_safely(Path(item.file.path))
+        if text is not None:
+            text_by_path[relative] = text
+    repo_path = Path(state.repo_path)
+    for relative in state.selected_files:
+        if relative in text_by_path:
+            continue
+        text = read_text_safely(repo_path / relative)
+        if text is not None:
+            text_by_path[relative] = text
+    return text_by_path
+
+
+def _is_rbac_review_task(state: AgentState) -> bool:
+    task = state.task.lower()
+    task_terms = {"rbac", "admin", "access", "access-control", "permission", "permissions", "role", "roles", "protected"}
+    return state.task_type == "access_control" or any(term in task for term in task_terms)
+
+
+def _has_app_page_path(path: str) -> bool:
+    parts = path.split("/")
+    return (
+        len(parts) >= 3
+        and parts[0] == "app"
+        and parts[1] == "app"
+        and parts[-1] in {"page.tsx", "page.jsx", "layout.tsx", "layout.jsx"}
+    )
+
+
+def _detect_rbac_categories(state: AgentState, ranked_files: list[RankedFile]) -> set[str]:
+    categories: set[str] = set()
+    text_by_path = _selected_text(state, ranked_files)
+    selected = state.selected_files or [item.file.relative_path for item in ranked_files]
+
+    for relative in selected:
+        path = relative.replace("\\", "/").lower()
+        name = Path(path).name
+        text = text_by_path.get(relative, "")
+        combined = f"{path}\n{text}".lower()
+
+        if name.endswith((".test.ts", ".test.tsx", ".spec.ts", ".spec.tsx", "_test.py")) or "/tests/" in f"/{path}" or "/__tests__/" in f"/{path}":
+            categories.add("tests")
+        if path.endswith("lib/rbac.ts") or "rbac" in path or "permission" in path or "role" in path or "canaccess" in combined or "policy" in combined:
+            categories.add("rbac_rules")
+        if "lib/auth" in path or "/auth/" in path or "session" in combined or "user.role" in combined or "getserversession" in combined:
+            categories.add("auth_role_source")
+        if name == "middleware.ts" or "middleware" in path or "protected route" in combined or "canaccesspath" in combined:
+            categories.add("middleware_routes")
+        if "sidebar" in path or "navigation" in path or "/nav" in path or "/menu" in path or "menuitem" in combined:
+            categories.add("navigation_visibility")
+        if _has_app_page_path(path) or (name in {"page.tsx", "page.jsx", "layout.tsx", "layout.jsx"} and any(term in path for term in ("/admin", "/dashboard", "/settings", "/tools"))):
+            categories.add("protected_pages")
+        is_server_surface = path.startswith("actions/") or "/actions/" in path or path.startswith("app/api/") or "/app/api/" in path
+        calls_server_guard = "requiretoolaccess" in combined or "canaccesspath" in combined or "canaccesstool" in combined
+        if is_server_surface or "use server" in combined or (calls_server_guard and name not in {"auth.ts", "rbac.ts"}):
+            categories.add("backend_enforcement")
+
+    return categories
+
+
+def _apply_rbac_review(state: AgentState, warnings: list[str], missing: list[str], score: int, ranked_files: list[RankedFile]) -> tuple[int, list[str], list[str]]:
+    categories = _detect_rbac_categories(state, ranked_files)
+    missing_categories = RBAC_REQUIRED_CATEGORIES - categories
+
+    if "protected_pages" in missing_categories:
+        warnings.append("Actual protected page/screen files may be missing.")
+        missing.append("actual protected page/screen file")
+        score = min(score, 85)
+    if "backend_enforcement" in missing_categories:
+        warnings.append("Backend/server action enforcement may be missing.")
+        missing.append("backend/server action/API enforcement file")
+        score = min(score, 85)
+    if "navigation_visibility" in categories and "backend_enforcement" in missing_categories:
+        warnings.append("Sidebar/UI hiding exists, but server-side enforcement should also be checked.")
+    if "tests" in missing_categories:
+        warnings.append("No test file found for this access-control task.")
+        missing.append("test or spec file")
+        score = min(score, 90)
+
+    ui_categories = categories & {"navigation_visibility", "protected_pages"}
+    backend_categories = categories & {"rbac_rules", "auth_role_source", "middleware_routes", "backend_enforcement"}
+    if ui_categories and not backend_categories:
+        score = min(score, 75)
+    if backend_categories and not ui_categories:
+        score = min(score, 85)
+    if missing_categories:
+        score = min(score, 99)
+    else:
+        score += 15
+
+    return score, warnings, missing
+
+
+def review_context(state: AgentState, ranked_files: list[RankedFile]) -> AgentState:
+    paths = state.selected_files
+    covered = covered_categories(paths)
+    warnings: list[str] = []
+    missing: list[str] = []
+
+    if not ranked_files:
+        warnings.append("No strong primary file was found for this task.")
+        missing.append("primary task-relevant source file")
+
+    required = REQUIRED_BY_INTENT.get(state.task_type, set())
+    for category in sorted(required - covered):
+        if category == "test":
+            warnings.append("No test file found for this task.")
+            missing.append("test or spec file")
+        elif category == "auth":
+            warnings.append("Auth, role, or permission file may be missing.")
+            missing.append("auth/role/permission file")
+        elif category == "backend":
+            warnings.append("Backend route/controller/service context may be missing.")
+            missing.append("backend route/controller/service file")
+        elif category == "route":
+            warnings.append("Route or navigation context may be missing.")
+            missing.append("route/navigation file")
+        elif category == "model":
+            warnings.append("Model/schema/repository context may be missing.")
+            missing.append("model/schema/repository file")
+        elif category == "config":
+            warnings.append("Configuration context may be missing.")
+            missing.append("config file")
+        elif category == "ui":
+            warnings.append("Frontend component/page context may be missing.")
+            missing.append("frontend component/page file")
+
+    if state.task_type in {"access_control", "authentication"}:
+        if "ui" in covered and "backend" not in covered:
+            warnings.append("Only UI files found; security-sensitive tasks usually need backend checks too.")
+        if "backend" not in covered:
+            warnings.append("Backend enforcement file may be missing.")
+
+    score = 0
+    if state.interpretation:
+        score += 30
+    if ranked_files:
+        score += 25
+    if state.added_related_files:
+        score += 15
+    if "test" in covered:
+        score += 10
+    if state.estimated_tokens <= state.token_budget:
+        score += 10
+    if required and len(required & covered) >= max(1, len(required) - 1):
+        score += 10
+    score -= 10 * len(warnings)
+
+    if _is_rbac_review_task(state):
+        score, warnings, missing = _apply_rbac_review(state, warnings, missing, score, ranked_files)
+
+    state.missing_context = list(dict.fromkeys(missing))
+    state.warnings = list(dict.fromkeys(warnings))
+    state.quality_score = max(0, min(100, score))
+    return state
+
+
+def task_interpretation(intent: str) -> str:
+    label = INTENT_LABELS.get(intent, "General code task")
+    detail = INTERPRETATIONS.get(intent, INTERPRETATIONS["general_code_task"])
+    return f"{label}. {detail}"

repotrim-0.1.0/agents/state.py

@@ -0,0 +1,30 @@
+"""State tracked by the deterministic agent context builder."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class AgentState:
+    repo_path: str
+    task: str
+    task_type: str = "general_code_task"
+    interpretation: str = ""
+    selected_files: list[str] = field(default_factory=list)
+    added_related_files: list[str] = field(default_factory=list)
+    missing_context: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    quality_score: int = 0
+    token_budget: int = 30000
+    estimated_tokens: int = 0
+    steps_taken: list[str] = field(default_factory=list)
+
+    @classmethod
+    def create(cls, repo_path: Path, task: str, token_budget: int) -> "AgentState":
+        return cls(repo_path=str(repo_path.resolve()), task=task, token_budget=token_budget)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)