contextzip 0.3.6__tar.gz → 0.3.8__tar.gz

{contextzip-0.3.6 → contextzip-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.3.6
+Version: 0.3.8
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -43,6 +43,8 @@ Every AI session starts the same way: hunt down the relevant files, manually ski
 
 contextzip eliminates that entirely. Run it from your project root — it detects your stack, applies smart exclusions, produces a lean ZIP, and opens your file manager with the archive already selected. One `Ctrl+C` and you're done.
 
+And when the AI tool hands you a ZIP back with the changes, `contextzip apply-zip` closes the loop — no manual unzip-and-hope, no losing track of what actually changed.
+
 ---
 
 ## Features
@@ -51,9 +53,10 @@ contextzip eliminates that entirely. Run it from your project root — it detect
 - **Respects `.gitignore`** — your existing ignore patterns are honoured automatically
 - **Git-aware packaging** — use `--git-changes` to package only modified, staged, and untracked files; perfect for incremental debugging and PR review sessions
 - **AI-powered file selection** — describe your task in plain English with `--prompt` and Gemini selects the minimum relevant files automatically, no manual hunting required
+- **Apply AI-returned changes back** — `contextzip apply-zip` takes the ZIP an AI tool hands you back and writes it into your project safely: diffed against what was actually sent, backed up before anything is overwritten, and never silently deleting anything
 - **Terminal error watcher** — wrap any dev server with `contextzip watch` to auto-detect errors and package a ready-to-upload debug context in one keypress
-- **Configurable workspace location** — `.contextzip/` lives at the git root by default, but you can pin it elsewhere per-machine (`contextzip config --set-workspace`) or for the whole team via a committed `.contextzip/config.json`
-- **Persistent workspace** — all generated ZIPs land in `.contextzip/output/`, discoverable, reusable, and git-ignored automatically
+- **Configurable workspace location** — `.contextzip/` lives at the git root by default, but you can pin it elsewhere per-machine (`contextzip config --set-workspace`) or for the whole team via a committed `.contextzip.json`
+- **Persistent workspace** — all generated ZIPs land in `.contextzip/`, discoverable, reusable, and git-ignored automatically
 - **Warns before it's a problem** — flags large (≥ 1 MB) and binary files that AI tools can't read, before you waste an upload
 - **Handles edge cases** — dangling symlinks, unreadable files, and paths outside the project tree are caught and reported, never silently dropped
 - **Full CLI control** — `--include`, `--exclude`, `--dry-run`, `--output`, all composable
@@ -95,7 +98,7 @@ contextzip will:
 
 1. Detect your framework (e.g. `Next.js + Node.js`)
 2. Apply the appropriate exclusion rules
-3. Create a compressed ZIP in `.contextzip/output/` at your project root
+3. Create a compressed ZIP in `.contextzip/` at your project root
 4. Open your file manager with the ZIP selected and ready to copy
 
 ---
@@ -106,8 +109,6 @@ contextzip will:
 contextzip [OPTIONS]
 ```
 
-> `cz` is a shorthand alias for `contextzip` — both commands are identical and support every option and subcommand shown below (e.g. `cz --git-changes`, `cz exclude node_modules`).
-
 | Option | Description |
 |---|---|
 | `-p`, `--prompt TEXT` | Describe your task in plain English — Gemini selects only the relevant files |
@@ -120,7 +121,7 @@ contextzip [OPTIONS]
 | `--no-clipboard` | Skip the clipboard / folder-open step |
 | `--no-gitignore` | Ignore the project's `.gitignore` |
 
-**Subcommands:** `exclude`, `include`, `watch`, `config` — run `contextzip --help` for full details.
+**Subcommands:** `exclude`, `include`, `apply-zip`, `watch`, `config` — run `contextzip --help` for full details.
 
 ---
 
@@ -147,6 +148,9 @@ contextzip --prompt "Refactor auth middleware" --dry-run
 
 # Save to a custom path
 contextzip --output ~/Desktop/project-context.zip
+
+# Apply the ZIP an AI tool handed back
+contextzip apply-zip
 ```
 
 ---
@@ -156,7 +160,7 @@ contextzip --output ~/Desktop/project-context.zip
 contextzip is also usable as a library. All CLI capabilities are available as plain Python functions — no Click, no Rich output, no `SystemExit`.
 
 ```python
-from contextzip import get_git_changes, get_files, create_zip
+from contextzip import get_git_changes, get_files, create_zip, apply_zip
 
 # Get changed files and use them directly
 collection = get_git_changes()
@@ -172,6 +176,10 @@ with open(pkg.zip_path, "rb") as f:
 collection = get_files(include=["src/"], exclude=["tests/"])
 pkg = create_zip(collection, output="/tmp/upload.zip")
 print(f"{pkg.file_count} files, {pkg.compressed_bytes} bytes")
+
+# Apply a ZIP an AI tool returned (auto-detects from .contextzip/inbox/)
+result = apply_zip()
+print(f"Wrote {len(result.written)} files, backup at {result.backup_dir}")
 ```
 
 | Function | Description |
@@ -179,9 +187,10 @@ print(f"{pkg.file_count} files, {pkg.compressed_bytes} bytes")
 | `get_git_changes(path?)` | Modified, added, and untracked files from git |
 | `get_files(path?, include?, exclude?)` | All project files after exclusion rules |
 | `create_zip(collection, output?)` | Write a `FileCollection` to a ZIP archive |
+| `apply_zip(zip_path?, project_dir?, manifest?)` | Apply an AI-returned ZIP back into the project |
 | `detect_ecosystem(path?)` | Detect framework and confidence level |
 
-All functions default `path` to `Path.cwd()`. Errors raise typed exceptions (`NotARepositoryError`, `GitNotFoundError`, `NoFilesError`, etc.) rather than exiting.
+All functions default `path` to `Path.cwd()`. Errors raise typed exceptions (`NotARepositoryError`, `GitNotFoundError`, `NoFilesError`, `ZipNotFoundError`, etc.) rather than exiting.
 
 ---
 
@@ -211,6 +220,61 @@ contextzip config --reset-key   # clear and re-run setup
 
 ---
 
+## Applying AI-returned changes
+
+Once an AI tool has made its edits and handed you back a ZIP, `contextzip apply-zip` writes those changes into your project — safely.
+
+```bash
+# Drop the AI's returned zip into .contextzip/inbox/, then:
+contextzip apply-zip
+
+# Or point at it directly, wherever it landed:
+contextzip apply-zip ~/Downloads/fixed-project.zip
+
+# Preview first, with full per-file detail:
+contextzip apply-zip --dry-run --verbose
+
+# Skip the confirmation prompt (e.g. in a script):
+contextzip apply-zip --yes
+```
+
+### How it knows what's safe to apply
+
+Every ZIP `contextzip` creates gets a small manifest written next to it in `.contextzip/output/` — a hash of each included file, taken at zip-time. This manifest is **never added to the ZIP itself**. It stays local, so it's never uploaded and never visible to whatever AI tool the ZIP is pasted into — nothing for a model, or a curious teammate, to notice or ask about.
+
+When you run `apply-zip`, it diffs the returned ZIP against that manifest and classifies every file:
+
+| Status | Meaning | Applied automatically? |
+|---|---|---|
+| **New** | Wasn't part of the original ZIP | Yes |
+| **Modified** | Was sent, content changed, and your local copy hasn't moved since | Yes |
+| **Unchanged** | Identical to what's already on disk | Skipped — nothing to do |
+| **Drifted** | Your local file changed (or was deleted) since you zipped it | No — flagged, asks first |
+| **Untracked** | In the returned ZIP but has no baseline to compare against | No — flagged, asks first |
+
+The common case — you zip some files, the AI edits them, nothing else touched your project meanwhile — applies straight through with just a summary printed, no prompt. Anything that could clobber your own work, or introduce a path you didn't expect, stops and asks before writing.
+
+If a ZIP arrives with no matching manifest at all (e.g. it wasn't produced by a `contextzip` round trip), every already-existing path is treated as untracked and you'll be asked to confirm the whole batch.
+
+### What it does and doesn't do
+
+- **Only adds and modifies files.** Deletions are never inferred from a ZIP's contents — a file that's simply missing from the returned ZIP is left alone.
+- **Backs up before overwriting.** Every file about to be touched is copied into `.contextzip/backups/<timestamp>/` first, preserving its relative path.
+- **Rejects unsafe paths outright.** Any ZIP entry that would resolve outside your project (`../../etc/passwd`-style path traversal) is refused before anything is written — no override flag, no exceptions.
+- **Archives what it consumes.** Once applied, the ZIP is moved to `.contextzip/inbox/applied/<timestamp>-name.zip` — it won't be picked up again by accident, and stays around as an audit trail. ZIPs applied via an explicit path outside the inbox are left where you put them.
+
+### Finding the right ZIP and manifest
+
+```bash
+contextzip apply-zip                    # exactly one *.zip in .contextzip/inbox/ → uses it
+contextzip apply-zip path/to/fix.zip    # explicit path always overrides the inbox
+contextzip apply-zip --manifest path/to/codebase.manifest.json   # override auto-detection
+```
+
+If `.contextzip/inbox/` has more than one ZIP and you don't specify which, `apply-zip` lists them and asks you to be explicit rather than guessing. Manifest auto-detection picks the most recently created `*.manifest.json` under `.contextzip/output/` — correct for the normal one-round-trip-at-a-time flow; pass `--manifest` explicitly if you've generated several ZIPs before getting a response back.
+
+---
+
 ## Terminal error watcher
 
 The `watch` command wraps your dev server, buffers its output, and packages a debug-ready ZIP the moment you spot an error — no manual file hunting, no copy-pasting stack traces.
@@ -278,7 +342,7 @@ detects both Node.js and Python from `root/`, without either marker existing at
 By default, `.contextzip/` is created at your git root — that's `_find_git_root()` walking up from the current directory until it finds a `.git` folder; outside a repo, it falls back to the current directory. This can be overridden two ways, in order of priority:
 
 1. **`CONTEXTZIP_WORKSPACE_LOCATION` environment variable** — for a one-off override on a single run
-2. **A committed `.contextzip/config.json` at the project root** — team-shared, applies to everyone who clones the repo:
+2. **A committed `.contextzip.json` at the project root** — team-shared, applies to everyone who clones the repo:
    ```json
    { "workspace_location": "git-root" }
    ```
@@ -292,64 +356,25 @@ By default, `.contextzip/` is created at your git root — that's `_find_git_roo
 
 Accepted values are `"git-root"`, `"cwd"`, or any path (absolute, or relative to the git root). Run `contextzip config` with no flags to see which value is currently active and where it came from.
 
-This matters most for monorepos where you sometimes run contextzip from a subdirectory (`cd frontend && contextzip`) — with the default `git-root` setting, the workspace still lands at the repo root no matter where you ran it from, so you don't end up with scattered `.contextzip/` folders across `frontend/`, `backend/`, etc. Set `workspace_location: "cwd"` in a project's `.contextzip/config.json` instead if you'd rather each subproject keep its own.
-
----
-
-## Project configuration
+This matters most for monorepos where you sometimes run contextzip from a subdirectory (`cd frontend && contextzip`) — with the default `git-root` setting, the workspace still lands at the repo root no matter where you ran it from, so you don't end up with scattered `.contextzip/` folders across `frontend/`, `backend/`, etc. Set `workspace_location: "cwd"` in a project's `.contextzip.json` instead if you'd rather each subproject keep its own.
 
-Every project gets a `.contextzip/` workspace at the project root:
+**Workspace layout:**
 
 ```
 .contextzip/
-├── config.json     # project preferences — commit this
-├── .gitignore       # keeps output/ untracked, config.json trackable
-└── output/          # generated ZIPs — never committed
-    ├── codebase.zip
-    ├── changes.zip       (--git-changes)
-    └── debug-context.zip (contextzip watch)
+  config.json               # team-shared preferences (committed)
+  .gitignore                # ignores everything below except itself + config.json
+  output/
+    codebase.zip            # what you generate and send out
+    codebase.manifest.json  # local-only — never uploaded, used by apply-zip
+  inbox/
+    <ai-returned>.zip        # drop AI-returned zips here for apply-zip to pick up
+    applied/
+      <timestamp>-name.zip   # archived after a successful apply-zip
+  backups/
+    <timestamp>/             # pre-overwrite copies, one folder per apply-zip run
 ```
 
-`.contextzip/` is **not** committed to Git by default — `.contextzip/.gitignore` is written automatically the first time you run contextzip in a repo, and it ignores everything in the folder *except* `config.json` and itself. That's deliberate: `output/` is per-machine, disposable scratch space, while `config.json` holds team-shared preferences you'll usually want everyone on the same page about.
-
-`config.json` currently supports:
-
-```json
-{
-  "workspace_location": "git-root",
-  "scan_depth": null,
-  "always_include": [],
-  "always_exclude": [],
-  "ai": {
-    "enabled": true,
-    "provider": "gemini",
-    "max_files": 10
-  }
-}
-```
-
-All keys are optional — start with just the ones you need.
-
-| Key | What it does |
-| --- | --- |
-| `workspace_location` | Same as `contextzip config --set-workspace`, but team-shared. See [Workspace location](#workspace-location). |
-| `scan_depth` | Reserved for a future bounded-depth scan mode. |
-| `always_include` | A standing "force include" list (gitwildmatch patterns). Files matching it are packaged even if an auto-rule or `.gitignore` would otherwise exclude them — e.g. `["docs/architecture.md"]` to always pull in a doc that lives in an otherwise-excluded folder. |
-| `always_exclude` | A standing exclusion list, applied on every run without retyping `-e`/`--exclude`. |
-| `ai.enabled` | Set to `false` to disable `--prompt` entirely for this project; contextzip will refuse with a clear message instead of silently ignoring it. |
-| `ai.provider` | Reserved for future AI providers. Only `"gemini"` is currently supported. |
-| `ai.max_files` | Caps how many files `--prompt` mode may return, for both the Gemini and keyword-heuristic paths. |
-
-`always_include`/`always_exclude` are additive on top of `--include`/`--exclude` for that run — an explicit `contextzip include PATH` still has the final say over what's actually packaged. Persistent preferences belong in `config.json` rather than an ever-growing list of CLI flags; CLI flags stay for one-off, explicit actions (`--dry-run`, `--prompt "…"`, `--output FILE`, etc.).
-
-A **web-based configuration UI** that generates `config.json` for you is on the roadmap — the schema above is designed to grow additively, so future preferences (including ones set visually) won't require another migration.
-
-### Deprecation: `.contextzip.json`
-
-Earlier versions of contextzip read a `.contextzip.json` file at the project root for `workspace_location`/`scan_depth`. That file is now **deprecated** in favor of `.contextzip/config.json` — contextzip still reads it automatically if `.contextzip/config.json` doesn't exist yet (so nothing breaks), and prints a one-time reminder to migrate. To migrate, just move its contents into the `"workspace_location"`/`"scan_depth"` keys of a new `.contextzip/config.json` and delete the old file.
-
-`~/.config/contextzip/config.json` (your personal, per-machine config — API key, personal workspace override) is unrelated and unaffected by any of this.
-
 ---
 
 ## Contributing

{contextzip-0.3.6 → contextzip-0.3.8}/README.md

@@ -14,6 +14,8 @@ Every AI session starts the same way: hunt down the relevant files, manually ski
 
 contextzip eliminates that entirely. Run it from your project root — it detects your stack, applies smart exclusions, produces a lean ZIP, and opens your file manager with the archive already selected. One `Ctrl+C` and you're done.
 
+And when the AI tool hands you a ZIP back with the changes, `contextzip apply-zip` closes the loop — no manual unzip-and-hope, no losing track of what actually changed.
+
 ---
 
 ## Features
@@ -22,9 +24,10 @@ contextzip eliminates that entirely. Run it from your project root — it detect
 - **Respects `.gitignore`** — your existing ignore patterns are honoured automatically
 - **Git-aware packaging** — use `--git-changes` to package only modified, staged, and untracked files; perfect for incremental debugging and PR review sessions
 - **AI-powered file selection** — describe your task in plain English with `--prompt` and Gemini selects the minimum relevant files automatically, no manual hunting required
+- **Apply AI-returned changes back** — `contextzip apply-zip` takes the ZIP an AI tool hands you back and writes it into your project safely: diffed against what was actually sent, backed up before anything is overwritten, and never silently deleting anything
 - **Terminal error watcher** — wrap any dev server with `contextzip watch` to auto-detect errors and package a ready-to-upload debug context in one keypress
-- **Configurable workspace location** — `.contextzip/` lives at the git root by default, but you can pin it elsewhere per-machine (`contextzip config --set-workspace`) or for the whole team via a committed `.contextzip/config.json`
-- **Persistent workspace** — all generated ZIPs land in `.contextzip/output/`, discoverable, reusable, and git-ignored automatically
+- **Configurable workspace location** — `.contextzip/` lives at the git root by default, but you can pin it elsewhere per-machine (`contextzip config --set-workspace`) or for the whole team via a committed `.contextzip.json`
+- **Persistent workspace** — all generated ZIPs land in `.contextzip/`, discoverable, reusable, and git-ignored automatically
 - **Warns before it's a problem** — flags large (≥ 1 MB) and binary files that AI tools can't read, before you waste an upload
 - **Handles edge cases** — dangling symlinks, unreadable files, and paths outside the project tree are caught and reported, never silently dropped
 - **Full CLI control** — `--include`, `--exclude`, `--dry-run`, `--output`, all composable
@@ -66,7 +69,7 @@ contextzip will:
 
 1. Detect your framework (e.g. `Next.js + Node.js`)
 2. Apply the appropriate exclusion rules
-3. Create a compressed ZIP in `.contextzip/output/` at your project root
+3. Create a compressed ZIP in `.contextzip/` at your project root
 4. Open your file manager with the ZIP selected and ready to copy
 
 ---
@@ -77,8 +80,6 @@ contextzip will:
 contextzip [OPTIONS]
 ```
 
-> `cz` is a shorthand alias for `contextzip` — both commands are identical and support every option and subcommand shown below (e.g. `cz --git-changes`, `cz exclude node_modules`).
-
 | Option | Description |
 |---|---|
 | `-p`, `--prompt TEXT` | Describe your task in plain English — Gemini selects only the relevant files |
@@ -91,7 +92,7 @@ contextzip [OPTIONS]
 | `--no-clipboard` | Skip the clipboard / folder-open step |
 | `--no-gitignore` | Ignore the project's `.gitignore` |
 
-**Subcommands:** `exclude`, `include`, `watch`, `config` — run `contextzip --help` for full details.
+**Subcommands:** `exclude`, `include`, `apply-zip`, `watch`, `config` — run `contextzip --help` for full details.
 
 ---
 
@@ -118,6 +119,9 @@ contextzip --prompt "Refactor auth middleware" --dry-run
 
 # Save to a custom path
 contextzip --output ~/Desktop/project-context.zip
+
+# Apply the ZIP an AI tool handed back
+contextzip apply-zip
 ```
 
 ---
@@ -127,7 +131,7 @@ contextzip --output ~/Desktop/project-context.zip
 contextzip is also usable as a library. All CLI capabilities are available as plain Python functions — no Click, no Rich output, no `SystemExit`.
 
 ```python
-from contextzip import get_git_changes, get_files, create_zip
+from contextzip import get_git_changes, get_files, create_zip, apply_zip
 
 # Get changed files and use them directly
 collection = get_git_changes()
@@ -143,6 +147,10 @@ with open(pkg.zip_path, "rb") as f:
 collection = get_files(include=["src/"], exclude=["tests/"])
 pkg = create_zip(collection, output="/tmp/upload.zip")
 print(f"{pkg.file_count} files, {pkg.compressed_bytes} bytes")
+
+# Apply a ZIP an AI tool returned (auto-detects from .contextzip/inbox/)
+result = apply_zip()
+print(f"Wrote {len(result.written)} files, backup at {result.backup_dir}")
 ```
 
 | Function | Description |
@@ -150,9 +158,10 @@ print(f"{pkg.file_count} files, {pkg.compressed_bytes} bytes")
 | `get_git_changes(path?)` | Modified, added, and untracked files from git |
 | `get_files(path?, include?, exclude?)` | All project files after exclusion rules |
 | `create_zip(collection, output?)` | Write a `FileCollection` to a ZIP archive |
+| `apply_zip(zip_path?, project_dir?, manifest?)` | Apply an AI-returned ZIP back into the project |
 | `detect_ecosystem(path?)` | Detect framework and confidence level |
 
-All functions default `path` to `Path.cwd()`. Errors raise typed exceptions (`NotARepositoryError`, `GitNotFoundError`, `NoFilesError`, etc.) rather than exiting.
+All functions default `path` to `Path.cwd()`. Errors raise typed exceptions (`NotARepositoryError`, `GitNotFoundError`, `NoFilesError`, `ZipNotFoundError`, etc.) rather than exiting.
 
 ---
 
@@ -182,6 +191,61 @@ contextzip config --reset-key   # clear and re-run setup
 
 ---
 
+## Applying AI-returned changes
+
+Once an AI tool has made its edits and handed you back a ZIP, `contextzip apply-zip` writes those changes into your project — safely.
+
+```bash
+# Drop the AI's returned zip into .contextzip/inbox/, then:
+contextzip apply-zip
+
+# Or point at it directly, wherever it landed:
+contextzip apply-zip ~/Downloads/fixed-project.zip
+
+# Preview first, with full per-file detail:
+contextzip apply-zip --dry-run --verbose
+
+# Skip the confirmation prompt (e.g. in a script):
+contextzip apply-zip --yes
+```
+
+### How it knows what's safe to apply
+
+Every ZIP `contextzip` creates gets a small manifest written next to it in `.contextzip/output/` — a hash of each included file, taken at zip-time. This manifest is **never added to the ZIP itself**. It stays local, so it's never uploaded and never visible to whatever AI tool the ZIP is pasted into — nothing for a model, or a curious teammate, to notice or ask about.
+
+When you run `apply-zip`, it diffs the returned ZIP against that manifest and classifies every file:
+
+| Status | Meaning | Applied automatically? |
+|---|---|---|
+| **New** | Wasn't part of the original ZIP | Yes |
+| **Modified** | Was sent, content changed, and your local copy hasn't moved since | Yes |
+| **Unchanged** | Identical to what's already on disk | Skipped — nothing to do |
+| **Drifted** | Your local file changed (or was deleted) since you zipped it | No — flagged, asks first |
+| **Untracked** | In the returned ZIP but has no baseline to compare against | No — flagged, asks first |
+
+The common case — you zip some files, the AI edits them, nothing else touched your project meanwhile — applies straight through with just a summary printed, no prompt. Anything that could clobber your own work, or introduce a path you didn't expect, stops and asks before writing.
+
+If a ZIP arrives with no matching manifest at all (e.g. it wasn't produced by a `contextzip` round trip), every already-existing path is treated as untracked and you'll be asked to confirm the whole batch.
+
+### What it does and doesn't do
+
+- **Only adds and modifies files.** Deletions are never inferred from a ZIP's contents — a file that's simply missing from the returned ZIP is left alone.
+- **Backs up before overwriting.** Every file about to be touched is copied into `.contextzip/backups/<timestamp>/` first, preserving its relative path.
+- **Rejects unsafe paths outright.** Any ZIP entry that would resolve outside your project (`../../etc/passwd`-style path traversal) is refused before anything is written — no override flag, no exceptions.
+- **Archives what it consumes.** Once applied, the ZIP is moved to `.contextzip/inbox/applied/<timestamp>-name.zip` — it won't be picked up again by accident, and stays around as an audit trail. ZIPs applied via an explicit path outside the inbox are left where you put them.
+
+### Finding the right ZIP and manifest
+
+```bash
+contextzip apply-zip                    # exactly one *.zip in .contextzip/inbox/ → uses it
+contextzip apply-zip path/to/fix.zip    # explicit path always overrides the inbox
+contextzip apply-zip --manifest path/to/codebase.manifest.json   # override auto-detection
+```
+
+If `.contextzip/inbox/` has more than one ZIP and you don't specify which, `apply-zip` lists them and asks you to be explicit rather than guessing. Manifest auto-detection picks the most recently created `*.manifest.json` under `.contextzip/output/` — correct for the normal one-round-trip-at-a-time flow; pass `--manifest` explicitly if you've generated several ZIPs before getting a response back.
+
+---
+
 ## Terminal error watcher
 
 The `watch` command wraps your dev server, buffers its output, and packages a debug-ready ZIP the moment you spot an error — no manual file hunting, no copy-pasting stack traces.
@@ -249,7 +313,7 @@ detects both Node.js and Python from `root/`, without either marker existing at
 By default, `.contextzip/` is created at your git root — that's `_find_git_root()` walking up from the current directory until it finds a `.git` folder; outside a repo, it falls back to the current directory. This can be overridden two ways, in order of priority:
 
 1. **`CONTEXTZIP_WORKSPACE_LOCATION` environment variable** — for a one-off override on a single run
-2. **A committed `.contextzip/config.json` at the project root** — team-shared, applies to everyone who clones the repo:
+2. **A committed `.contextzip.json` at the project root** — team-shared, applies to everyone who clones the repo:
    ```json
    { "workspace_location": "git-root" }
    ```
@@ -263,64 +327,25 @@ By default, `.contextzip/` is created at your git root — that's `_find_git_roo
 
 Accepted values are `"git-root"`, `"cwd"`, or any path (absolute, or relative to the git root). Run `contextzip config` with no flags to see which value is currently active and where it came from.
 
-This matters most for monorepos where you sometimes run contextzip from a subdirectory (`cd frontend && contextzip`) — with the default `git-root` setting, the workspace still lands at the repo root no matter where you ran it from, so you don't end up with scattered `.contextzip/` folders across `frontend/`, `backend/`, etc. Set `workspace_location: "cwd"` in a project's `.contextzip/config.json` instead if you'd rather each subproject keep its own.
-
----
-
-## Project configuration
+This matters most for monorepos where you sometimes run contextzip from a subdirectory (`cd frontend && contextzip`) — with the default `git-root` setting, the workspace still lands at the repo root no matter where you ran it from, so you don't end up with scattered `.contextzip/` folders across `frontend/`, `backend/`, etc. Set `workspace_location: "cwd"` in a project's `.contextzip.json` instead if you'd rather each subproject keep its own.
 
-Every project gets a `.contextzip/` workspace at the project root:
+**Workspace layout:**
 
 ```
 .contextzip/
-├── config.json     # project preferences — commit this
-├── .gitignore       # keeps output/ untracked, config.json trackable
-└── output/          # generated ZIPs — never committed
-    ├── codebase.zip
-    ├── changes.zip       (--git-changes)
-    └── debug-context.zip (contextzip watch)
+  config.json               # team-shared preferences (committed)
+  .gitignore                # ignores everything below except itself + config.json
+  output/
+    codebase.zip            # what you generate and send out
+    codebase.manifest.json  # local-only — never uploaded, used by apply-zip
+  inbox/
+    <ai-returned>.zip        # drop AI-returned zips here for apply-zip to pick up
+    applied/
+      <timestamp>-name.zip   # archived after a successful apply-zip
+  backups/
+    <timestamp>/             # pre-overwrite copies, one folder per apply-zip run
 ```
 
-`.contextzip/` is **not** committed to Git by default — `.contextzip/.gitignore` is written automatically the first time you run contextzip in a repo, and it ignores everything in the folder *except* `config.json` and itself. That's deliberate: `output/` is per-machine, disposable scratch space, while `config.json` holds team-shared preferences you'll usually want everyone on the same page about.
-
-`config.json` currently supports:
-
-```json
-{
-  "workspace_location": "git-root",
-  "scan_depth": null,
-  "always_include": [],
-  "always_exclude": [],
-  "ai": {
-    "enabled": true,
-    "provider": "gemini",
-    "max_files": 10
-  }
-}
-```
-
-All keys are optional — start with just the ones you need.
-
-| Key | What it does |
-| --- | --- |
-| `workspace_location` | Same as `contextzip config --set-workspace`, but team-shared. See [Workspace location](#workspace-location). |
-| `scan_depth` | Reserved for a future bounded-depth scan mode. |
-| `always_include` | A standing "force include" list (gitwildmatch patterns). Files matching it are packaged even if an auto-rule or `.gitignore` would otherwise exclude them — e.g. `["docs/architecture.md"]` to always pull in a doc that lives in an otherwise-excluded folder. |
-| `always_exclude` | A standing exclusion list, applied on every run without retyping `-e`/`--exclude`. |
-| `ai.enabled` | Set to `false` to disable `--prompt` entirely for this project; contextzip will refuse with a clear message instead of silently ignoring it. |
-| `ai.provider` | Reserved for future AI providers. Only `"gemini"` is currently supported. |
-| `ai.max_files` | Caps how many files `--prompt` mode may return, for both the Gemini and keyword-heuristic paths. |
-
-`always_include`/`always_exclude` are additive on top of `--include`/`--exclude` for that run — an explicit `contextzip include PATH` still has the final say over what's actually packaged. Persistent preferences belong in `config.json` rather than an ever-growing list of CLI flags; CLI flags stay for one-off, explicit actions (`--dry-run`, `--prompt "…"`, `--output FILE`, etc.).
-
-A **web-based configuration UI** that generates `config.json` for you is on the roadmap — the schema above is designed to grow additively, so future preferences (including ones set visually) won't require another migration.
-
-### Deprecation: `.contextzip.json`
-
-Earlier versions of contextzip read a `.contextzip.json` file at the project root for `workspace_location`/`scan_depth`. That file is now **deprecated** in favor of `.contextzip/config.json` — contextzip still reads it automatically if `.contextzip/config.json` doesn't exist yet (so nothing breaks), and prints a one-time reminder to migrate. To migrate, just move its contents into the `"workspace_location"`/`"scan_depth"` keys of a new `.contextzip/config.json` and delete the old file.
-
-`~/.config/contextzip/config.json` (your personal, per-machine config — API key, personal workspace override) is unrelated and unaffected by any of this.
-
 ---
 
 ## Contributing

{contextzip-0.3.6 → contextzip-0.3.8}/contextzip/__init__.py

@@ -1,6 +1,6 @@
 """contextzip — intelligent codebase packager for AI tools."""
 
-__version__ = "0.3.6"
+__version__ = "0.3.8"
 
 from contextzip.api import (
     FileCollection,
@@ -9,26 +9,32 @@ from contextzip.api import (
     GitNotFoundError,
     GitCommandError,
     NoFilesError,
+    ZipNotFoundError,
     get_git_changes,
     get_files,
     create_zip,
+    apply_zip,
     detect_ecosystem,
 )
 from contextzip.packager import PackageResult
+from contextzip.applier import ApplyResult
 
 __all__ = [
     # Functions
     "get_git_changes",
     "get_files",
     "create_zip",
+    "apply_zip",
     "detect_ecosystem",
     # Data types
     "FileCollection",
     "PackageResult",
+    "ApplyResult",
     # Exceptions
     "ContextzipError",
     "NotARepositoryError",
     "GitNotFoundError",
     "GitCommandError",
     "NoFilesError",
+    "ZipNotFoundError",
 ]

{contextzip-0.3.6 → contextzip-0.3.8}/contextzip/api.py

@@ -39,6 +39,7 @@ import os
 from dataclasses import dataclass, field
 from pathlib import Path
 
+from contextzip.applier import ApplyResult
 from contextzip.detector import DetectionResult, detect
 from contextzip.filters import (
     ResolveResult,
@@ -127,6 +128,10 @@ class NoFilesError(ContextzipError):
     """Raised when file resolution produces an empty result."""
 
 
+class ZipNotFoundError(ContextzipError):
+    """Raised when apply_zip() can't resolve which zip to apply."""
+
+
 # ---------------------------------------------------------------------------
 # Public API
 # ---------------------------------------------------------------------------
@@ -335,6 +340,82 @@ def create_zip(
     )
 
 
+def apply_zip(
+    zip_path: str | Path | None = None,
+    *,
+    project_dir: str | Path | None = None,
+    manifest: str | Path | None = None,
+) -> 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.
+    Every overwritten file is backed up first, under
+    ``.contextzip/backups/<timestamp>/``.
+
+    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``).
+
+    Parameters
+    ----------
+    zip_path:
+        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()``.
+    manifest:
+        Explicit manifest path to diff against, overriding auto-detection.
+
+    Returns
+    -------
+    ApplyResult
+        ``written`` (list of relative paths written), ``backup_dir``
+        (``Path`` or ``None`` if nothing needed backing up), and
+        ``applied_zip_path`` (where the consumed zip ended up).
+
+    Raises
+    ------
+    ZipNotFoundError
+        If no zip could be resolved — missing, or multiple candidates in
+        the inbox with none specified.
+
+    Example
+    -------
+    ::
+
+        from contextzip import apply_zip
+
+        result = apply_zip()  # picks up .contextzip/inbox/*.zip
+        print(f"Wrote {len(result.written)} files")
+        if result.backup_dir:
+            print(f"Backup at {result.backup_dir}")
+    """
+    from contextzip.applier import (
+        ApplyError,
+        build_plan,
+        execute_plan,
+        find_latest_manifest,
+        find_zip_to_apply,
+    )
+
+    pdir = _resolve_dir(project_dir)
+
+    try:
+        resolved_zip = find_zip_to_apply(pdir, zip_path)
+    except ApplyError as exc:
+        raise ZipNotFoundError(str(exc)) from exc
+
+    manifest_path = find_latest_manifest(pdir, manifest)
+    plan = build_plan(resolved_zip, pdir, manifest_path)
+    return execute_plan(plan, pdir)
+
+
 def detect_ecosystem(
     path: str | Path | None = None,
 ) -> DetectionResult: