contextzip 0.3.9__tar.gz → 0.4.0__tar.gz

contextzip-0.4.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: contextzip
+Version: 0.4.0
+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.0/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.0}/contextzip/__init__.py

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

{contextzip-0.3.9 → contextzip-0.4.0}/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.0}/contextzip/applier.py

@@ -573,18 +573,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 +595,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 +615,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 +639,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.3.9 → contextzip-0.4.0}/contextzip/cli.py

@@ -373,6 +373,7 @@ def cmd_apply_zip(
       .contextzip/backups/<timestamp>/.
     """
     project_dir = Path(os.getcwd()).resolve()
+    project_cfg = load_project_config(project_dir)
 
     console.print()
     console.print(
@@ -436,7 +437,7 @@ def cmd_apply_zip(
             return
         console.print()
 
-    result = execute_plan(plan, project_dir)
+    result = execute_plan(plan, project_dir, retain=project_cfg.applied_zip_retention)
     print_apply_result(result)
 
 
@@ -922,6 +923,9 @@ def _run(
             resolved = resolve_files_from_git(
                 git_files=git_result.files,
                 project_dir=project_dir,
+                large_file_warn_bytes=int(
+                    project_cfg.limits.max_file_size_mb * 1024 * 1024
+                ),
             )
 
     else:
@@ -960,11 +964,18 @@ def _run(
                 spec=spec,
                 include_only=include_only if include_only else None,
                 force_include=force_include,
+                large_file_warn_bytes=int(
+                    project_cfg.limits.max_file_size_mb * 1024 * 1024
+                ),
             )
 
     # ── File scan summary + warnings ─────────────────────────────────────────
     print_scan_summary(resolved, project_dir, verbose, git_mode=git_changes)
-    print_file_warnings(resolved, project_dir)
+    print_file_warnings(
+        resolved,
+        project_dir,
+        large_file_warn_bytes=int(project_cfg.limits.max_file_size_mb * 1024 * 1024),
+    )
 
     # ── Dry run ──────────────────────────────────────────────────────────────
     if dry_run:
@@ -1026,6 +1037,7 @@ def _run(
             ecosystem=detection.display_name,
             api_key=api_key,
             max_files=project_cfg.ai.max_files,
+            prompt_template=project_cfg.ai.prompt_template,
         )
 
         if not selected_paths:

{contextzip-0.3.9 → contextzip-0.4.0}/contextzip/cli_ai.py

@@ -61,6 +61,7 @@ def run_ai_selection(
     ecosystem: str,
     api_key: str,
     max_files: int | None = None,
+    prompt_template: str = "",
     con: Console = console,
 ) -> tuple[list[Path], str]:
     """
@@ -70,6 +71,9 @@ def run_ai_selection(
     project's `ai.max_files` preference (.contextzip/config.json). None
     falls back to each backend's own built-in default.
 
+    *prompt_template*, if non-empty, is a project's `ai.prompt_template`
+    preference, prepended to the generated prompt.txt.
+
     Handles progress display, heuristic-fallback warning, and Gemini
     errors. Raises SystemExit(1) on hard failure.
     """
@@ -86,6 +90,7 @@ def run_ai_selection(
                 ecosystem=ecosystem,
                 api_key=api_key,
                 max_files=max_files,
+                prompt_template=prompt_template,
             )
         except GeminiError as exc:
             con.print(

{contextzip-0.3.9 → contextzip-0.4.0}/contextzip/cli_display.py

@@ -170,14 +170,25 @@ def print_scan_summary(
 # ---------------------------------------------------------------------------
 
 
-def print_file_warnings(resolved, project_dir: Path, *, con: Console = console) -> None:
-    """Render large-file, binary-file, and skipped-file warnings."""
+def print_file_warnings(
+    resolved,
+    project_dir: Path,
+    *,
+    large_file_warn_bytes: int = LARGE_FILE_WARN_BYTES,
+    con: Console = console,
+) -> None:
+    """Render large-file, binary-file, and skipped-file warnings.
+
+    *large_file_warn_bytes* only affects the displayed threshold text —
+    typically a project's `limits.max_file_size_mb` preference — the actual
+    filtering already happened in resolve_files()/resolve_files_from_git().
+    """
     if resolved.large_files:
         con.print()
         con.print(
             f"  [yellow]⚠[/]  [bold]{len(resolved.large_files)} large file"
             f"{'s' if len(resolved.large_files) != 1 else ''}[/] "
-            f"[dim](≥ {human_size(LARGE_FILE_WARN_BYTES)}) will be included:[/]"
+            f"[dim](≥ {human_size(large_file_warn_bytes)}) will be included:[/]"
         )
         for p, size in resolved.large_files[:5]:
             rel = p.relative_to(project_dir).as_posix()

{contextzip-0.3.9 → contextzip-0.4.0}/contextzip/filters.py

@@ -269,6 +269,7 @@ def resolve_files(
     spec: pathspec.PathSpec,
     include_only: list[str] | None = None,
     force_include: pathspec.PathSpec | None = None,
+    large_file_warn_bytes: int = LARGE_FILE_WARN_BYTES,
 ) -> ResolveResult:
     """
     Walk *project_dir* and classify every file.
@@ -281,6 +282,9 @@ def resolve_files(
     an explicit `contextzip include PATH` for this run still has the final
     say on what actually gets included.
 
+    *large_file_warn_bytes* overrides the module default (1 MB) — typically
+    a project's `limits.max_file_size_mb` preference (.contextzip/config.json).
+
     Returns a :class:`ResolveResult` with included/excluded/skipped/large/binary lists.
     """
     result = ResolveResult()
@@ -347,7 +351,7 @@ def resolve_files(
             continue
 
         # ── Large file warning ───────────────────────────────────────────────
-        if file_size >= LARGE_FILE_WARN_BYTES:
+        if file_size >= large_file_warn_bytes:
             result.large_files.append((abs_path, file_size))
 
         # ── Binary file detection ────────────────────────────────────────────
@@ -363,6 +367,7 @@ def resolve_files(
 def resolve_files_from_git(
     git_files: list[Path],
     project_dir: Path,
+    large_file_warn_bytes: int = LARGE_FILE_WARN_BYTES,
 ) -> ResolveResult:
     """
     Build a :class:`ResolveResult` from a pre-selected list of files reported
@@ -380,6 +385,9 @@ def resolve_files_from_git(
         :attr:`GitChanges.files`.
     project_dir:
         Absolute path to the project root (used for relative-path guards).
+    large_file_warn_bytes:
+        Overrides the module default (1 MB) — typically a project's
+        `limits.max_file_size_mb` preference (.contextzip/config.json).
     """
     # Build the base spec once — this is our safety floor regardless of what
     # git reports as changed. It blocks .env, secrets, binaries, etc.
@@ -423,7 +431,7 @@ def resolve_files_from_git(
             continue
 
         # ── Large file warning ───────────────────────────────────────────────
-        if file_size >= LARGE_FILE_WARN_BYTES:
+        if file_size >= large_file_warn_bytes:
             result.large_files.append((abs_path, file_size))
 
         # ── Binary file detection ────────────────────────────────────────────