contextzip 0.4.7__tar.gz → 0.5.0__tar.gz

{contextzip-0.4.7 → contextzip-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.4.7
+Version: 0.5.0
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -120,6 +120,7 @@ contextzip --git-changes                    # only what you've changed
 contextzip --prompt "fix the login redirect bug"   # let AI pick the relevant files
 contextzip include src/ app/                # only these folders
 contextzip include src/ .env                # .env too, values redacted
+contextzip --here                           # only the folder you're in (monorepos)
 contextzip exclude tests/ '*.snap'          # everything except these
 contextzip apply-zip                        # write the AI's changes back
 ```
@@ -163,7 +164,7 @@ Describe your task in plain language and [Gemini](https://ai.google.dev/) picks
 
 - **Setup:** you need a free Gemini API key. contextzip walks you through it the first time you use `--prompt`, or you can set the `GEMINI_API_KEY` environment variable.
 - **What is sent:** only the list of file **paths and sizes** that already passed the exclusion rules, plus your prompt. File contents never leave your machine.
-- **Fallback:** if Gemini is rate-limited or unreachable, a local keyword-based selector takes over, so `--prompt` keeps working.
+- **Fallback:** if Gemini is rate-limited, a local keyword-based selector takes over, so `--prompt` keeps working. Other errors (a bad key, no network) stop with a clear message.
 - **Model:** `gemini-2.5-flash-lite` by default.
 
 ### Applying AI changes back
@@ -174,17 +175,25 @@ contextzip apply-zip fix.zip      # or point at one directly
 contextzip apply-zip --dry-run    # preview without writing anything
 ```
 
-Every ZIP contextzip creates gets a **local manifest** containing a hash of each file. It's stored next to the ZIP and never inside it, so the AI tool never sees it. When a ZIP comes back, `apply-zip` compares every file against that manifest:
+AI tools return ZIPs in every shape: wrapped in an extra folder, relative to a subfolder, flattened, with Windows separators. `apply-zip` matches each file to its real place in your project anyway, and new files follow their siblings.
 
-| Status | Meaning | Action |
+Every ZIP contextzip makes gets a **local snapshot** (a hash of each file, never uploaded). `apply-zip` picks the snapshot that best matches the returned ZIP and compares three versions of each file: what you sent, what's on disk now, and what came back.
+
+| Status | Meaning | Default |
 |---|---|---|
-| **New** | File didn't exist before | Written |
-| **Modified** | AI changed it, and you haven't touched it locally | Written |
-| **Unchanged** | Identical to what's on disk | Skipped |
-| **Drifted** | *You* edited it locally since zipping | ⚠️ Asks before overwriting |
-| **Untracked** | Exists locally but wasn't in the original ZIP | ⚠️ Asks before overwriting |
+| **New** / **Modified** | New file, or only the AI changed it | Written |
+| **Merged** | You both changed it, in different places | Written (three-way merge) |
+| **Unchanged** | Already matches — including changes you already applied | Skipped |
+| **Conflict** | You both changed the same lines | Needs your call |
+| **Partial** | The AI returned a cut-down file (`// ... rest unchanged`) | Needs your call |
+| **Moved** | The AI moved or renamed it | Written at the new path; the old file is kept unless you say otherwise |
+| **Drifted** / **Deleted** / **Untracked** / **Ambiguous** / **Delete requested** | Can't be applied safely without you | Needs your call |
+
+When something needs a decision you choose: apply the safe changes now, **review side by side in your browser** (`--review`), **resolve in VS Code's merge editor** (`--editor`), or apply everything. Line endings never count as a change, redacted secrets are never overwritten with placeholders, and **files are only removed with your explicit OK** — never one you've changed since.
+
+### Snapshots and CONTEXTZIP.md
 
-`apply-zip` only adds and modifies files. **It never deletes anything.** It also unwraps the extra top-level folder that AI tools and "Download ZIP" buttons often add.
+Every package is kept locally as a numbered **snapshot** (`#14`), so a reply can be merged against exactly what you sent, even after you've packaged again. Each ZIP also carries a short **`CONTEXTZIP.md`** for the AI: the snapshot ID, and how to reply so the answer applies cleanly (complete files, same paths, secrets left as `[REDACTED]`, moves and deletions listed). When the reply echoes it back, `apply-zip` knows the exact snapshot. `contextzip snapshots` lists them; turn the file off with `"zip_guide": false`.
 
 ### Terminal error watcher
 
@@ -266,6 +275,8 @@ This holds per-project settings. Edit it by hand or with `contextzip config --ui
   },
   "applied_zip_retention": 1,                  // past apply-zip archives to keep
   "cleanup": { "enabled": true, "keep_recent": 1 },
+  "snapshots": { "keep": 10, "max_age_days": 14 },  // history apply-zip merges against
+  "zip_guide": true,                           // add CONTEXTZIP.md to every ZIP
   "webui": { "auto_open": true, "port": null }
 }
 ```
@@ -328,11 +339,12 @@ contextzip keeps everything in a `.contextzip/` folder at your git root (change
 │   ├── git-changes/   changes.zip + manifest + report    (--git-changes)
 │   ├── prompt/        vibe.zip + manifest + report       (--prompt)
 │   └── watch/         debug-context.zip                  (contextzip watch)
+├── snapshots/         numbered copies of what you sent   (contextzip snapshots)
 ├── inbox/             drop AI-returned ZIPs here for apply-zip
 └── config.json        project config (optional)
 ```
 
-Old outputs are cleaned up automatically, and only the most recent set is kept. You can change this with the `cleanup` setting.
+Old outputs are cleaned up automatically: `output/` keeps the latest ZIP per mode (`cleanup`), and `snapshots/` keeps the newest 10 or anything under 14 days old (`snapshots`) — never one a reply in the inbox is waiting on.
 
 ## Python API
 

{contextzip-0.4.7 → contextzip-0.5.0}/README.md

@@ -91,6 +91,7 @@ contextzip --git-changes                    # only what you've changed
 contextzip --prompt "fix the login redirect bug"   # let AI pick the relevant files
 contextzip include src/ app/                # only these folders
 contextzip include src/ .env                # .env too, values redacted
+contextzip --here                           # only the folder you're in (monorepos)
 contextzip exclude tests/ '*.snap'          # everything except these
 contextzip apply-zip                        # write the AI's changes back
 ```
@@ -134,7 +135,7 @@ Describe your task in plain language and [Gemini](https://ai.google.dev/) picks
 
 - **Setup:** you need a free Gemini API key. contextzip walks you through it the first time you use `--prompt`, or you can set the `GEMINI_API_KEY` environment variable.
 - **What is sent:** only the list of file **paths and sizes** that already passed the exclusion rules, plus your prompt. File contents never leave your machine.
-- **Fallback:** if Gemini is rate-limited or unreachable, a local keyword-based selector takes over, so `--prompt` keeps working.
+- **Fallback:** if Gemini is rate-limited, a local keyword-based selector takes over, so `--prompt` keeps working. Other errors (a bad key, no network) stop with a clear message.
 - **Model:** `gemini-2.5-flash-lite` by default.
 
 ### Applying AI changes back
@@ -145,17 +146,25 @@ contextzip apply-zip fix.zip      # or point at one directly
 contextzip apply-zip --dry-run    # preview without writing anything
 ```
 
-Every ZIP contextzip creates gets a **local manifest** containing a hash of each file. It's stored next to the ZIP and never inside it, so the AI tool never sees it. When a ZIP comes back, `apply-zip` compares every file against that manifest:
+AI tools return ZIPs in every shape: wrapped in an extra folder, relative to a subfolder, flattened, with Windows separators. `apply-zip` matches each file to its real place in your project anyway, and new files follow their siblings.
 
-| Status | Meaning | Action |
+Every ZIP contextzip makes gets a **local snapshot** (a hash of each file, never uploaded). `apply-zip` picks the snapshot that best matches the returned ZIP and compares three versions of each file: what you sent, what's on disk now, and what came back.
+
+| Status | Meaning | Default |
 |---|---|---|
-| **New** | File didn't exist before | Written |
-| **Modified** | AI changed it, and you haven't touched it locally | Written |
-| **Unchanged** | Identical to what's on disk | Skipped |
-| **Drifted** | *You* edited it locally since zipping | ⚠️ Asks before overwriting |
-| **Untracked** | Exists locally but wasn't in the original ZIP | ⚠️ Asks before overwriting |
+| **New** / **Modified** | New file, or only the AI changed it | Written |
+| **Merged** | You both changed it, in different places | Written (three-way merge) |
+| **Unchanged** | Already matches — including changes you already applied | Skipped |
+| **Conflict** | You both changed the same lines | Needs your call |
+| **Partial** | The AI returned a cut-down file (`// ... rest unchanged`) | Needs your call |
+| **Moved** | The AI moved or renamed it | Written at the new path; the old file is kept unless you say otherwise |
+| **Drifted** / **Deleted** / **Untracked** / **Ambiguous** / **Delete requested** | Can't be applied safely without you | Needs your call |
+
+When something needs a decision you choose: apply the safe changes now, **review side by side in your browser** (`--review`), **resolve in VS Code's merge editor** (`--editor`), or apply everything. Line endings never count as a change, redacted secrets are never overwritten with placeholders, and **files are only removed with your explicit OK** — never one you've changed since.
+
+### Snapshots and CONTEXTZIP.md
 
-`apply-zip` only adds and modifies files. **It never deletes anything.** It also unwraps the extra top-level folder that AI tools and "Download ZIP" buttons often add.
+Every package is kept locally as a numbered **snapshot** (`#14`), so a reply can be merged against exactly what you sent, even after you've packaged again. Each ZIP also carries a short **`CONTEXTZIP.md`** for the AI: the snapshot ID, and how to reply so the answer applies cleanly (complete files, same paths, secrets left as `[REDACTED]`, moves and deletions listed). When the reply echoes it back, `apply-zip` knows the exact snapshot. `contextzip snapshots` lists them; turn the file off with `"zip_guide": false`.
 
 ### Terminal error watcher
 
@@ -237,6 +246,8 @@ This holds per-project settings. Edit it by hand or with `contextzip config --ui
   },
   "applied_zip_retention": 1,                  // past apply-zip archives to keep
   "cleanup": { "enabled": true, "keep_recent": 1 },
+  "snapshots": { "keep": 10, "max_age_days": 14 },  // history apply-zip merges against
+  "zip_guide": true,                           // add CONTEXTZIP.md to every ZIP
   "webui": { "auto_open": true, "port": null }
 }
 ```
@@ -299,11 +310,12 @@ contextzip keeps everything in a `.contextzip/` folder at your git root (change
 │   ├── git-changes/   changes.zip + manifest + report    (--git-changes)
 │   ├── prompt/        vibe.zip + manifest + report       (--prompt)
 │   └── watch/         debug-context.zip                  (contextzip watch)
+├── snapshots/         numbered copies of what you sent   (contextzip snapshots)
 ├── inbox/             drop AI-returned ZIPs here for apply-zip
 └── config.json        project config (optional)
 ```
 
-Old outputs are cleaned up automatically, and only the most recent set is kept. You can change this with the `cleanup` setting.
+Old outputs are cleaned up automatically: `output/` keeps the latest ZIP per mode (`cleanup`), and `snapshots/` keeps the newest 10 or anything under 14 days old (`snapshots`) — never one a reply in the inbox is waiting on.
 
 ## Python API
 

{contextzip-0.4.7 → contextzip-0.5.0}/contextzip/__init__.py

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

{contextzip-0.4.7 → contextzip-0.5.0}/contextzip/api.py

@@ -35,7 +35,6 @@ Quickstart
 
 from __future__ import annotations
 
-import os
 from dataclasses import dataclass, field
 from pathlib import Path
 
@@ -158,7 +157,7 @@ def get_git_changes(
     Parameters
     ----------
     path:
-        Directory to start from. Defaults to ``Path.cwd()``. The actual
+        Directory to start from. Defaults to the project root found from the current folder. The actual
         git root may be a parent of this directory.
     use_project_config:
         Apply the project's ``.contextzip/config.json``. Defaults to
@@ -234,7 +233,7 @@ def get_files(
     Parameters
     ----------
     path:
-        Project root to scan. Defaults to ``Path.cwd()``.
+        Project root to scan. Defaults to the project root found from the current folder.
     include:
         If given, only files under these paths are returned (e.g.
         ``["src/", "app/"]``). Matched as exact path prefixes.
@@ -358,10 +357,14 @@ def create_zip(
 
     output_path = Path(output).resolve() if output is not None else None
 
+    project_cfg = load_project_config(collection.project_dir)
     return create_zip_silent(
         resolve_result=resolve_result,
         project_dir=collection.project_dir,
         output_path=output_path,
+        redact_secrets_enabled=project_cfg.limits.redact_secrets,
+        ecosystem=collection.ecosystem,
+        guide=project_cfg.zip_guide,
     )
 
 
@@ -370,20 +373,23 @@ def apply_zip(
     *,
     project_dir: str | Path | None = None,
     manifest: str | Path | None = None,
+    include_risky: bool = False,
 ) -> ApplyResult:
     """
     Apply an AI-returned ZIP back into *project_dir* (defaults to cwd).
 
-    Diffs the zip against the local sidecar manifest most recently written
-    to ``.contextzip/output/`` (or the one at *manifest*, if given) to
-    classify every file as new, modified, unchanged, or one with no safe
-    baseline (locally edited since zipping, or never part of the original
-    manifest). Only adds and modifies files — nothing is ever deleted.
+    Each file is matched to its place in the project (even when the zip is
+    wrapped, relative to a subfolder, or flattened), then compared with the
+    snapshot of what was sent and with the file on disk. New, modified and
+    cleanly merged files are written. Files that need a decision —
+    conflicts, partial files, ones you deleted or that weren't sent, and
+    ambiguous ones — are left alone unless *include_risky* is True, in which
+    case the AI's version wins. Nothing is removed — moved files keep their
+    old copy and requested deletions are skipped; use
+    ``execute_plan(..., remove_moved=True, allow_delete=True)`` to opt in.
 
-    Unlike the CLI, this applies immediately and does not prompt — check
-    ``contextzip.applier.build_plan()`` yourself first if you want to
-    inspect risk before writing (see ``ApplyPlan.is_risky`` /
-    ``.risky_entries``).
+    Doesn't prompt. To inspect first, use ``contextzip.applier.build_plan()``
+    and ``execute_plan(..., decisions=...)`` directly.
 
     Parameters
     ----------
@@ -391,15 +397,20 @@ def apply_zip(
         Path to the returned zip. If omitted, auto-detects from
         ``.contextzip/inbox/`` — exactly one zip must be present there.
     project_dir:
-        Project root to apply into. Defaults to ``Path.cwd()``.
+        Project root to apply into. Defaults to the project root found from the current folder.
     manifest:
-        Explicit manifest path to diff against, overriding auto-detection.
+        Snapshot (manifest) to compare against. By default the one that
+        best matches the zip is picked automatically.
+    include_risky:
+        Also write files that need a decision, with the AI's version
+        winning. Defaults to False.
 
     Returns
     -------
     ApplyResult
-        ``written`` (list of relative paths written) and
-        ``applied_zip_path`` (where the consumed zip ended up).
+        ``written`` (relative paths written), ``skipped`` (paths left alone)
+        and ``applied_zip_path`` (where the zip ended up — it stays in the
+        inbox while something still needs a decision).
 
     Raises
     ------
@@ -431,9 +442,9 @@ def apply_zip(
     except ApplyError as exc:
         raise ZipNotFoundError(str(exc)) from exc
 
-    manifest_path = find_latest_manifest(pdir, manifest)
+    manifest_path = find_latest_manifest(pdir, manifest) if manifest is not None else None
     plan = build_plan(resolved_zip, pdir, manifest_path)
-    return execute_plan(plan, pdir)
+    return execute_plan(plan, pdir, include_risky=include_risky)
 
 
 def detect_ecosystem(
@@ -445,7 +456,7 @@ def detect_ecosystem(
     Parameters
     ----------
     path:
-        Directory to inspect. Defaults to ``Path.cwd()``.
+        Directory to inspect. Defaults to the project root found from the current folder.
 
     Returns
     -------
@@ -498,8 +509,16 @@ def _config_kwargs(cfg, extra_exclude: list[str] | None = None) -> dict:
 
 
 def _resolve_dir(path: str | Path | None) -> Path:
+    """
+    An explicit *path* is used exactly as given. Without one, resolve the
+    project root from the current folder — the same root the CLI uses (see
+    root.find_project_root) — so a script run from a subfolder of a
+    monorepo still works on the whole project with root-relative paths.
+    """
     if path is None:
-        return Path(os.getcwd()).resolve()
+        from contextzip.root import find_project_root
+
+        return find_project_root().root
     return Path(path).resolve()