contextzip 0.3.9__tar.gz → 0.4.1__tar.gz

contextzip-0.4.1/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: contextzip
+Version: 0.4.1
+Summary: Intelligently package your codebase for AI tools
+Author-email: Deepesh <akadeepesh@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/akadeepesh/contextzip
+Project-URL: Repository, https://github.com/akadeepesh/contextzip
+Project-URL: Issues, https://github.com/akadeepesh/contextzip/issues
+Keywords: ai,cli,developer-tools,context,zip,llm,claude,chatgpt,code-packaging
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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 :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0
+Requires-Dist: pathspec>=0.12
+Requires-Dist: httpx>=0.27
+Dynamic: license-file
+
+# contextzip
+
+> Package exactly the right parts of your codebase and paste it into any AI tool — in one command.
+
+```bash
+pip install contextzip
+```
+
+**📖 Full docs, every flag, every config option: [contextzip.vercel.app](https://contextzip.vercel.app)**
+
+---
+
+## Why contextzip
+
+Every AI session starts the same way: hunt down the relevant files, skip `node_modules` and build artifacts by hand, zip it, find the zip, upload it — then do it all again next session.
+
+contextzip eliminates that. Run it from your project root — it detects your stack, applies smart exclusions, and produces a lean ZIP ready to paste into Claude, ChatGPT, or any AI tool. When the AI hands changes back, `contextzip apply-zip` writes them into your project safely.
+
+## Quick start
+
+```bash
+cd ~/projects/my-app
+contextzip
+```
+
+That's it — no flags required. contextzip detects your framework, excludes the noise, and writes a ZIP to `.contextzip/`.
+
+## The essentials
+
+| Command | What it does |
+|---|---|
+| `contextzip` | Detect stack, exclude noise, package the project |
+| `contextzip --prompt "task"` | Let Gemini pick only the files relevant to a task |
+| `contextzip --git-changes` | Package only modified/staged/untracked files |
+| `contextzip apply-zip` | Write an AI-returned ZIP back into your project, safely |
+| `contextzip watch -- npm run dev` | Auto-package debug context the moment an error appears |
+| `contextzip config --ui` | Set include/exclude rules visually in a local browser tab |
+
+Every command supports `--dry-run`, `--verbose`, `--include`, `--exclude`, and more — see the [full CLI reference](https://contextzip.vercel.app/cli).
+
+contextzip respects your `.gitignore`, detects Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby (including in monorepos), and never packages secrets — SSH keys, cloud credentials, and Terraform state are always excluded. Details: [contextzip.vercel.app/features](https://contextzip.vercel.app/features).
+
+## Also a Python library
+
+```python
+from contextzip import get_git_changes, create_zip
+
+collection = get_git_changes()
+pkg = create_zip(collection, output="/tmp/changes.zip")
+```
+
+Full function reference: [contextzip.vercel.app/cli#python-api](https://contextzip.vercel.app/cli#python-api)
+
+## Learn more
+
+- [Packaging & detection](https://contextzip.vercel.app/features) — frameworks, exclusion rules, safety
+- [AI-powered file selection](https://contextzip.vercel.app/ai-selection) — `--prompt`, Gemini setup
+- [Terminal error watcher](https://contextzip.vercel.app/watch) — `contextzip watch`
+- [Applying changes back](https://contextzip.vercel.app/apply-zip) — `apply-zip`, backups, safety
+- [Configuration](https://contextzip.vercel.app/configuration) — personal & project config, visual config UI
+- [CLI & Python API reference](https://contextzip.vercel.app/cli)
+
+## Contributing
+
+Contributions are welcome — especially new framework rule sets and edge-case fixes. See [CONTRIBUTING.md](https://github.com/akadeepesh/contextzip/blob/main/CONTRIBUTING.md). Please open an issue before starting a large PR.
+
+## License
+
+MIT — see [LICENSE](https://github.com/akadeepesh/contextzip/blob/main/LICENSE) for details.

contextzip-0.4.1/README.md

@@ -0,0 +1,69 @@
+# contextzip
+
+> Package exactly the right parts of your codebase and paste it into any AI tool — in one command.
+
+```bash
+pip install contextzip
+```
+
+**📖 Full docs, every flag, every config option: [contextzip.vercel.app](https://contextzip.vercel.app)**
+
+---
+
+## Why contextzip
+
+Every AI session starts the same way: hunt down the relevant files, skip `node_modules` and build artifacts by hand, zip it, find the zip, upload it — then do it all again next session.
+
+contextzip eliminates that. Run it from your project root — it detects your stack, applies smart exclusions, and produces a lean ZIP ready to paste into Claude, ChatGPT, or any AI tool. When the AI hands changes back, `contextzip apply-zip` writes them into your project safely.
+
+## Quick start
+
+```bash
+cd ~/projects/my-app
+contextzip
+```
+
+That's it — no flags required. contextzip detects your framework, excludes the noise, and writes a ZIP to `.contextzip/`.
+
+## The essentials
+
+| Command | What it does |
+|---|---|
+| `contextzip` | Detect stack, exclude noise, package the project |
+| `contextzip --prompt "task"` | Let Gemini pick only the files relevant to a task |
+| `contextzip --git-changes` | Package only modified/staged/untracked files |
+| `contextzip apply-zip` | Write an AI-returned ZIP back into your project, safely |
+| `contextzip watch -- npm run dev` | Auto-package debug context the moment an error appears |
+| `contextzip config --ui` | Set include/exclude rules visually in a local browser tab |
+
+Every command supports `--dry-run`, `--verbose`, `--include`, `--exclude`, and more — see the [full CLI reference](https://contextzip.vercel.app/cli).
+
+contextzip respects your `.gitignore`, detects Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby (including in monorepos), and never packages secrets — SSH keys, cloud credentials, and Terraform state are always excluded. Details: [contextzip.vercel.app/features](https://contextzip.vercel.app/features).
+
+## Also a Python library
+
+```python
+from contextzip import get_git_changes, create_zip
+
+collection = get_git_changes()
+pkg = create_zip(collection, output="/tmp/changes.zip")
+```
+
+Full function reference: [contextzip.vercel.app/cli#python-api](https://contextzip.vercel.app/cli#python-api)
+
+## Learn more
+
+- [Packaging & detection](https://contextzip.vercel.app/features) — frameworks, exclusion rules, safety
+- [AI-powered file selection](https://contextzip.vercel.app/ai-selection) — `--prompt`, Gemini setup
+- [Terminal error watcher](https://contextzip.vercel.app/watch) — `contextzip watch`
+- [Applying changes back](https://contextzip.vercel.app/apply-zip) — `apply-zip`, backups, safety
+- [Configuration](https://contextzip.vercel.app/configuration) — personal & project config, visual config UI
+- [CLI & Python API reference](https://contextzip.vercel.app/cli)
+
+## Contributing
+
+Contributions are welcome — especially new framework rule sets and edge-case fixes. See [CONTRIBUTING.md](https://github.com/akadeepesh/contextzip/blob/main/CONTRIBUTING.md). Please open an issue before starting a large PR.
+
+## License
+
+MIT — see [LICENSE](https://github.com/akadeepesh/contextzip/blob/main/LICENSE) for details.

{contextzip-0.3.9 → contextzip-0.4.1}/contextzip/__init__.py

@@ -1,6 +1,6 @@
 """contextzip — intelligent codebase packager for AI tools."""
 
-__version__ = "0.3.9"
+__version__ = "0.4.1"
 
 from contextzip.api import (
     FileCollection,

{contextzip-0.3.9 → contextzip-0.4.1}/contextzip/ai/selector.py

@@ -33,6 +33,7 @@ def ai_select(
     ecosystem: str,
     api_key: str,
     max_files: int | None = None,
+    prompt_template: str = "",
 ) -> tuple[list[Path], str, str]:
     """
     Select the minimum relevant files for *prompt* from *resolved.included*.
@@ -41,6 +42,10 @@ def ai_select(
     project's `ai.max_files` preference (.contextzip/config.json). None
     falls back to each backend's own built-in default cap.
 
+    *prompt_template*, if non-empty, is a project's `ai.prompt_template`
+    preference — house conventions prepended to the generated prompt.txt
+    ahead of the task description.
+
     Returns
     -------
     (selected_paths, prompt_txt, method)
@@ -78,14 +83,20 @@ def ai_select(
     }
     selected_paths = [rel_to_abs[rel] for rel in selected_rel if rel in rel_to_abs]
 
-    prompt_txt = _build_prompt_txt(prompt, selected_rel, ecosystem, method)
+    prompt_txt = _build_prompt_txt(
+        prompt, selected_rel, ecosystem, method, prompt_template=prompt_template
+    )
 
     return selected_paths, prompt_txt, method
 
 
-def build_prompt_only_txt(prompt: str, ecosystem: str) -> str:
+def build_prompt_only_txt(
+    prompt: str, ecosystem: str, prompt_template: str = ""
+) -> str:
     """Build a minimal prompt.txt when no AI selection was performed."""
-    return _build_prompt_txt(prompt, [], ecosystem, USED_GEMINI)
+    return _build_prompt_txt(
+        prompt, [], ecosystem, USED_GEMINI, prompt_template=prompt_template
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -125,12 +136,14 @@ def _build_prompt_txt(
     selected_rel: list[str],
     ecosystem: str,
     method: str,
+    prompt_template: str = "",
 ) -> str:
     """
     Build the prompt.txt to include inside the ZIP.
 
-    Any AI tool that receives the ZIP immediately sees the task description,
-    the framework, and exactly which files were selected and why.
+    Any AI tool that receives the ZIP immediately sees the project's own
+    conventions (if any are configured), the task description, the
+    framework, and exactly which files were selected and why.
     """
 
     selector_label = (
@@ -139,12 +152,21 @@ def _build_prompt_txt(
         else "contextzip (keyword heuristic — Gemini was rate limited)"
     )
 
-    lines: list[str] = [
-        f"Task: {prompt}",
-        "",
-        f"Framework: {ecosystem}",
-        "",
-    ]
+    lines: list[str] = []
+
+    if prompt_template:
+        lines.append("Project conventions:")
+        lines.append(prompt_template)
+        lines.append("")
+
+    lines.extend(
+        [
+            f"Task: {prompt}",
+            "",
+            f"Framework: {ecosystem}",
+            "",
+        ]
+    )
 
     if selected_rel:
         lines.append(f"Files selected by {selector_label}:")

{contextzip-0.3.9 → contextzip-0.4.1}/contextzip/applier.py

@@ -291,10 +291,12 @@ def find_latest_manifest(
     Resolve which manifest to diff against.
 
     An explicit path always wins (if it exists). Otherwise picks the most
-    recently modified *.manifest.json under .contextzip/output/ — in the
-    normal one-round-trip-at-a-time flow, that's the zip you most recently
-    generated, which is almost always the right baseline. Returns None if
-    nothing is found (apply-zip still works, just more conservatively).
+    recently modified *.manifest.json anywhere under .contextzip/output/
+    — including its per-mode subfolders (output/codebase/, output/git-changes/,
+    output/prompt/) — since in the normal one-round-trip-at-a-time flow,
+    that's the zip you most recently generated regardless of which mode
+    produced it, which is almost always the right baseline. Returns None
+    if nothing is found (apply-zip still works, just more conservatively).
     """
     if explicit_manifest is not None:
         path = Path(explicit_manifest).expanduser().resolve()
@@ -304,7 +306,7 @@ def find_latest_manifest(
     if not out_dir.is_dir():
         return None
 
-    candidates = [p for p in out_dir.glob(f"*{_MANIFEST_SUFFIX}") if p.is_file()]
+    candidates = [p for p in out_dir.rglob(f"*{_MANIFEST_SUFFIX}") if p.is_file()]
     if not candidates:
         return None
     return max(candidates, key=lambda p: p.stat().st_mtime)
@@ -573,18 +575,21 @@ def _backup_entries(
     return backup_dir
 
 
-def _move_zip_to_applied(zip_path: Path, project_dir: Path, workspace_root: Path) -> Path:
+def _move_zip_to_applied(
+    zip_path: Path, project_dir: Path, workspace_root: Path, retain: int = 1
+) -> Path:
     """
     Move a consumed inbox zip into .contextzip/inbox/applied/, timestamped,
     so it can't be accidentally re-applied. Zips passed by an explicit path
     outside the inbox are left where the user put them rather than being
     moved unexpectedly.
 
-    Only the most recently applied zip is kept: anything already in
-    applied/ from a prior run is removed first, so this folder holds one
-    zip at most and doesn't grow across sessions. If keeping a full
-    history ever matters, that's a deliberate future feature, not a
-    default behavior.
+    Keeps at most *retain* applied zips (default 1 — only the most recent).
+    Filenames are timestamp-prefixed, so a lexicographic sort is also a
+    chronological one; the oldest are pruned first, before this run's zip
+    is moved in, so the folder never holds more than *retain* at once.
+    Typically a project's `applied_zip_retention` preference
+    (.contextzip/config.json) — raise it to keep a longer audit trail.
     """
     if zip_path.parent.resolve() != inbox_dir(project_dir).resolve():
         return zip_path
@@ -592,7 +597,12 @@ def _move_zip_to_applied(zip_path: Path, project_dir: Path, workspace_root: Path
     applied_dir = workspace_root / _INBOX_DIRNAME / _APPLIED_DIRNAME
     applied_dir.mkdir(parents=True, exist_ok=True)
 
-    for old in applied_dir.glob("*.zip"):
+    retain = max(1, retain)
+    existing = sorted(applied_dir.glob("*.zip"))
+    # Keep room for the zip we're about to add: prune down to retain - 1
+    # existing entries before moving the new one in.
+    overflow = len(existing) - (retain - 1)
+    for old in existing[: max(0, overflow)]:
         try:
             old.unlink()
         except OSError:
@@ -607,13 +617,17 @@ def _move_zip_to_applied(zip_path: Path, project_dir: Path, workspace_root: Path
     return dest
 
 
-def execute_plan(plan: ApplyPlan, project_dir: Path) -> ApplyResult:
+def execute_plan(plan: ApplyPlan, project_dir: Path, retain: int = 1) -> ApplyResult:
     """
     Write every non-unchanged entry from *plan* into the project.
 
     Backs up whatever's about to be overwritten first. Assumes the caller
     has already decided to proceed — dry-run and confirmation prompts are
     handled upstream (see cli.py's `apply-zip` command).
+
+    *retain* caps how many applied zips are kept in
+    .contextzip/inbox/applied/ — typically a project's
+    `applied_zip_retention` preference (.contextzip/config.json).
     """
     workspace_root = _workspace_dir(project_dir)
     to_write = plan.writable_entries
@@ -627,7 +641,9 @@ def execute_plan(plan: ApplyPlan, project_dir: Path) -> ApplyResult:
         shutil.copy2(entry.extracted_path, dest)
         written.append(entry.rel_path)
 
-    applied_zip_path = _move_zip_to_applied(plan.zip_path, project_dir, workspace_root)
+    applied_zip_path = _move_zip_to_applied(
+        plan.zip_path, project_dir, workspace_root, retain=retain
+    )
     shutil.rmtree(plan.extraction_dir, ignore_errors=True)
 
     return ApplyResult(

contextzip-0.4.1/contextzip/cleanup.py

@@ -0,0 +1,207 @@
+"""
+cleanup.py — Automatic workspace housekeeping for contextzip.
+
+.contextzip/ accumulates disposable artifacts over time: a zip+manifest+report
+set every run, a timestamped backup folder every risky `apply-zip`, and (until
+pruned) old archived applied-zips. None of it is precious — every zip is
+trivially reproducible by just re-running contextzip, and a backup only
+matters until the apply that made it is confirmed good. So cleanup here is
+deliberately brutal rather than cautious: it runs automatically after every
+successful command (see `_auto_cleanup` in cli.py), with no prompt and no
+separate command to remember, and keeps only the most recent
+`cleanup.keep_recent` item(s) in each category — everything else is deleted
+immediately, every time.
+
+The heavier caution used elsewhere in contextzip (backing up before overwrite
+in apply-zip, never inferring deletions) is reserved for the project's own
+files, where losing something can mean losing real work. Nothing here ever
+touches the project — only disposable metadata under .contextzip/ that costs
+nothing to regenerate.
+
+Never touched, under any settings:
+  - .contextzip/config.json (project preferences)
+  - .contextzip/inbox/*.zip (zips waiting to be applied — never assumed
+    stale just because they've been sitting there; only inbox/applied/,
+    the archive of zips already consumed, is ever pruned)
+  - anything outside .contextzip/
+
+Kept only-the-most-recent-N, everything older deleted immediately:
+  - zip/manifest/report sets under .contextzip/output/<mode>/, per mode
+    folder
+  - timestamped folders under .contextzip/backups/
+  - archived zips under .contextzip/inbox/applied/ (this is also governed
+    by `applied_zip_retention`, already enforced on every apply-zip run —
+    scanning it here too just catches the case where zips piled up before
+    that setting existed, or the setting was since lowered)
+
+Scanning only ever touches .contextzip/ directory listings and file mtimes —
+no hashing, no reading file contents — so this stays fast even called on
+every command, on a large project.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+_OUTPUT_DIRNAME = "output"
+_BACKUPS_DIRNAME = "backups"
+_INBOX_DIRNAME = "inbox"
+_APPLIED_DIRNAME = "applied"
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CleanupItem:
+    path: Path
+    kind: str  # "zip-set" | "backup" | "applied-zip"
+    size_bytes: int
+
+
+@dataclass
+class CleanupPlan:
+    workspace: Path
+    items: list[CleanupItem] = field(default_factory=list)
+
+    @property
+    def total_bytes(self) -> int:
+        return sum(i.size_bytes for i in self.items)
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.items
+
+
+@dataclass
+class CleanupResult:
+    removed: list[Path] = field(default_factory=list)
+    failed: list[tuple[Path, str]] = field(default_factory=list)
+    freed_bytes: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _size_of(path: Path) -> int:
+    """Size of a file, or total size of everything under a directory."""
+    if path.is_file():
+        try:
+            return path.stat().st_size
+        except OSError:
+            return 0
+    if not path.is_dir():
+        return 0
+    total = 0
+    for p in path.rglob("*"):
+        if p.is_file():
+            try:
+                total += p.stat().st_size
+            except OSError:
+                pass
+    return total
+
+
+def _zip_set_files(zip_path: Path) -> list[Path]:
+    """The zip and any sidecar manifest/report files that sit next to it."""
+    files = [zip_path]
+    for suffix in (".manifest.json", ".report.txt", ".apply-report.txt"):
+        sidecar = zip_path.with_name(zip_path.stem + suffix)
+        if sidecar.is_file():
+            files.append(sidecar)
+    return files
+
+
+def _newest_first(paths: list[Path]) -> list[Path]:
+    return sorted(paths, key=lambda p: p.stat().st_mtime, reverse=True)
+
+
+# ---------------------------------------------------------------------------
+# Scan
+# ---------------------------------------------------------------------------
+
+
+def scan(
+    project_dir: Path,
+    *,
+    keep_recent: int = 1,
+    applied_zip_retention: int = 1,
+) -> CleanupPlan:
+    """
+    Build a plan of everything beyond the most recent `keep_recent` item(s)
+    per category. Read-only — never deletes anything itself; pass the
+    result to `execute()` to actually do so.
+    """
+    from contextzip.packager import _workspace_dir
+
+    workspace, _is_git_repo = _workspace_dir(project_dir)
+    items: list[CleanupItem] = []
+    keep = max(0, keep_recent)
+
+    # ── output/ — per-mode subfolders, plus any flat legacy files left
+    #    behind by a contextzip version predating the per-mode split ──────
+    output_root = workspace / _OUTPUT_DIRNAME
+    if output_root.is_dir():
+        for mode_dir in sorted(p for p in output_root.iterdir() if p.is_dir()):
+            zips = _newest_first([p for p in mode_dir.glob("*.zip") if p.is_file()])
+            for zp in zips[keep:]:
+                for f in _zip_set_files(zp):
+                    items.append(CleanupItem(path=f, kind="zip-set", size_bytes=_size_of(f)))
+
+        legacy_zips = _newest_first([p for p in output_root.glob("*.zip") if p.is_file()])
+        for zp in legacy_zips[keep:]:
+            for f in _zip_set_files(zp):
+                items.append(CleanupItem(path=f, kind="zip-set", size_bytes=_size_of(f)))
+
+    # ── backups/<timestamp>/ ─────────────────────────────────────────────
+    backups_root = workspace / _BACKUPS_DIRNAME
+    if backups_root.is_dir():
+        backups = _newest_first([p for p in backups_root.iterdir() if p.is_dir()])
+        for backup_dir in backups[keep:]:
+            items.append(
+                CleanupItem(path=backup_dir, kind="backup", size_bytes=_size_of(backup_dir))
+            )
+
+    # ── inbox/applied/ ───────────────────────────────────────────────────
+    applied_root = workspace / _INBOX_DIRNAME / _APPLIED_DIRNAME
+    if applied_root.is_dir():
+        applied_zips = _newest_first([p for p in applied_root.glob("*.zip") if p.is_file()])
+        retain = max(1, applied_zip_retention)
+        for zp in applied_zips[retain:]:
+            items.append(CleanupItem(path=zp, kind="applied-zip", size_bytes=_size_of(zp)))
+
+    return CleanupPlan(workspace=workspace, items=items)
+
+
+# ---------------------------------------------------------------------------
+# Execute
+# ---------------------------------------------------------------------------
+
+
+def execute(plan: CleanupPlan) -> CleanupResult:
+    """
+    Delete everything in *plan*, immediately, no confirmation. Best-effort:
+    one failure doesn't stop the rest, and every failure is reported rather
+    than silently swallowed.
+    """
+    result = CleanupResult()
+    for item in plan.items:
+        try:
+            if item.path.is_dir():
+                shutil.rmtree(item.path)
+            elif item.path.is_file():
+                item.path.unlink()
+            else:
+                continue  # already gone — nothing to do, not a failure
+            result.removed.append(item.path)
+            result.freed_bytes += item.size_bytes
+        except OSError as exc:
+            result.failed.append((item.path, str(exc)))
+    return result