contextzip 0.3.7__tar.gz → 0.3.9__tar.gz

{contextzip-0.3.7 → contextzip-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.3.7
+Version: 0.3.9
 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,11 +53,12 @@ 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`
-- **Visual config UI** — `contextzip config --ui` opens a local browser tab to set include/exclude by clicking through your actual file tree, with live counts and one-click suggestions for PDFs, media, and other non-code files — nothing leaves your machine
-- **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
+- **Never packages secrets** — SSH keys, cloud credentials, keystores, Terraform state, and other credential files are always excluded, on top of your `.gitignore` (see [What gets excluded](#what-gets-excluded))
 - **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
 
@@ -96,7 +99,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
 
 ---
@@ -107,8 +110,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 |
@@ -148,6 +149,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
 ```
 
 ---
@@ -173,6 +177,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 |
@@ -180,6 +188,7 @@ 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.
@@ -210,6 +219,8 @@ contextzip config               # show current key status
 contextzip config --reset-key   # clear and re-run setup
 ```
 
+Saved keys live in your OS user-config directory (e.g. `~/.config/contextzip/config.json` on Linux/macOS), and that file's permissions are locked down to your user only (`0600`) on every save.
+
 ---
 
 ## Terminal error watcher
@@ -229,7 +240,7 @@ contextzip starts your process normally. You see output exactly as you would wit
 ╰───────────────────────────────────────────────────╯
 ```
 
-Press **D** and contextzip immediately writes `.contextzip/output/debug-context.zip`. Your server keeps running — no restart, no interruption.
+Press **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Your server keeps running — no restart, no interruption.
 
 **What's in the ZIP:**
 
@@ -251,7 +262,19 @@ Press **D** and contextzip immediately writes `.contextzip/output/debug-context.
 
 contextzip stacks exclusion rules based on your detected stack, on top of your `.gitignore`.
 
-**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), common binary formats, and contextzip's own `.contextzip/` working folder.
+**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), common binary formats, secrets and credential files (see below), and contextzip's own `.contextzip/` working folder.
+
+**Secrets & credentials — always excluded, regardless of framework:**
+
+| Category | Examples |
+|---|---|
+| SSH private keys | `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519` (public counterparts like `id_rsa.pub` are kept) |
+| Keystores & certs | `*.p12`, `*.pfx`, `*.pkcs12`, `*.jks`, `*.keystore`, `*.ppk`, `*.key` |
+| CLI / package manager credentials | `.npmrc`, `.netrc`, `.pypirc`, `.pgpass`, `.dockercfg`, Docker `config.json` |
+| Cloud provider credentials | `.aws/credentials`, `.aws/config`, `*serviceaccount*.json`, `*credentials*.json`, `kubeconfig` |
+| Infra-as-code state | `*.tfstate`, `*.tfstate.*`, `.terraform/` (Terraform state routinely contains plaintext secrets, even for "just infra" resources) |
+
+These patterns are applied on top of your `.gitignore` and can't be re-included, so a stray credential file lying around your project never accidentally ends up in a ZIP you paste into an AI tool.
 
 **By framework:**
 
@@ -279,7 +302,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" }
    ```
@@ -293,95 +316,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.
+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.
 
----
-
-## Project configuration
-
-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)
-```
-
-`.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.).
-
-You don't have to hand-write `config.json` — see [Visual config UI](#visual-config-ui) below for a point-and-click way to produce it.
-
-### 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.
-
----
-
-## Visual config UI
-
-```
-contextzip config --ui
+  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
 ```
 
-Opens a local browser tab for setting `always_include`/`always_exclude` by clicking through your actual file tree instead of hand-writing patterns — live file counts and packed size update as you go, and one-click chips suggest excluding things like PDFs, office docs, fonts, media, or anything over 1MB that isn't already covered by contextzip's default rules.
-
-It's also offered automatically the **first time** you run `contextzip` in a project that has no config at all:
-
-```
-$ contextzip
-╭─────────────────────────╮
-│  contextzip v0.3.5      │
-╰─────────────────────────╯
-...
-╭─ First run ─────────────────────────────────────╮
-│  No project config found yet.                   │
-│  contextzip can open a local browser tab...      │
-╰───────────────────────────────────────────────────╯
-  Set up include/exclude visually now? [Y/n]:
-```
-
-Decline once and it won't ask again (run `contextzip config --ui` any time you want it). It's also skipped automatically for non-interactive runs, when `CI` is set, or when `--prompt`/`--output` are passed — it only ever offers on a plain, interactive, first-ever run.
-
-**Nothing about your project leaves your machine.** The server binds to `127.0.0.1` only (never `0.0.0.0`), every request needs a random per-session token embedded in the URL (the same approach Jupyter Notebook uses), and the page itself makes no calls anywhere except back to that local server — no CDN scripts, no web fonts, no analytics. Saving writes straight to `.contextzip/config.json` on disk and the server shuts itself down; if you close the tab without saving, it also shuts down after a short idle period so a forgotten session doesn't linger as an open port.
-
-If you accept the first-run offer, the same `contextzip` invocation picks up whatever you saved and finishes packaging immediately — no need to run it again.
-
 ---
 
 ## Contributing

{contextzip-0.3.7 → contextzip-0.3.9}/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,11 +24,12 @@ 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`
-- **Visual config UI** — `contextzip config --ui` opens a local browser tab to set include/exclude by clicking through your actual file tree, with live counts and one-click suggestions for PDFs, media, and other non-code files — nothing leaves your machine
-- **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
+- **Never packages secrets** — SSH keys, cloud credentials, keystores, Terraform state, and other credential files are always excluded, on top of your `.gitignore` (see [What gets excluded](#what-gets-excluded))
 - **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
 
@@ -67,7 +70,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
 
 ---
@@ -78,8 +81,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 |
@@ -119,6 +120,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
 ```
 
 ---
@@ -144,6 +148,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 |
@@ -151,6 +159,7 @@ 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.
@@ -181,6 +190,8 @@ contextzip config               # show current key status
 contextzip config --reset-key   # clear and re-run setup
 ```
 
+Saved keys live in your OS user-config directory (e.g. `~/.config/contextzip/config.json` on Linux/macOS), and that file's permissions are locked down to your user only (`0600`) on every save.
+
 ---
 
 ## Terminal error watcher
@@ -200,7 +211,7 @@ contextzip starts your process normally. You see output exactly as you would wit
 ╰───────────────────────────────────────────────────╯
 ```
 
-Press **D** and contextzip immediately writes `.contextzip/output/debug-context.zip`. Your server keeps running — no restart, no interruption.
+Press **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Your server keeps running — no restart, no interruption.
 
 **What's in the ZIP:**
 
@@ -222,7 +233,19 @@ Press **D** and contextzip immediately writes `.contextzip/output/debug-context.
 
 contextzip stacks exclusion rules based on your detected stack, on top of your `.gitignore`.
 
-**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), common binary formats, and contextzip's own `.contextzip/` working folder.
+**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), common binary formats, secrets and credential files (see below), and contextzip's own `.contextzip/` working folder.
+
+**Secrets & credentials — always excluded, regardless of framework:**
+
+| Category | Examples |
+|---|---|
+| SSH private keys | `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519` (public counterparts like `id_rsa.pub` are kept) |
+| Keystores & certs | `*.p12`, `*.pfx`, `*.pkcs12`, `*.jks`, `*.keystore`, `*.ppk`, `*.key` |
+| CLI / package manager credentials | `.npmrc`, `.netrc`, `.pypirc`, `.pgpass`, `.dockercfg`, Docker `config.json` |
+| Cloud provider credentials | `.aws/credentials`, `.aws/config`, `*serviceaccount*.json`, `*credentials*.json`, `kubeconfig` |
+| Infra-as-code state | `*.tfstate`, `*.tfstate.*`, `.terraform/` (Terraform state routinely contains plaintext secrets, even for "just infra" resources) |
+
+These patterns are applied on top of your `.gitignore` and can't be re-included, so a stray credential file lying around your project never accidentally ends up in a ZIP you paste into an AI tool.
 
 **By framework:**
 
@@ -250,7 +273,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" }
    ```
@@ -264,95 +287,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.
+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.
 
----
-
-## Project configuration
-
-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)
-```
-
-`.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.).
-
-You don't have to hand-write `config.json` — see [Visual config UI](#visual-config-ui) below for a point-and-click way to produce it.
-
-### 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.
-
----
-
-## Visual config UI
-
-```
-contextzip config --ui
+  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
 ```
 
-Opens a local browser tab for setting `always_include`/`always_exclude` by clicking through your actual file tree instead of hand-writing patterns — live file counts and packed size update as you go, and one-click chips suggest excluding things like PDFs, office docs, fonts, media, or anything over 1MB that isn't already covered by contextzip's default rules.
-
-It's also offered automatically the **first time** you run `contextzip` in a project that has no config at all:
-
-```
-$ contextzip
-╭─────────────────────────╮
-│  contextzip v0.3.5      │
-╰─────────────────────────╯
-...
-╭─ First run ─────────────────────────────────────╮
-│  No project config found yet.                   │
-│  contextzip can open a local browser tab...      │
-╰───────────────────────────────────────────────────╯
-  Set up include/exclude visually now? [Y/n]:
-```
-
-Decline once and it won't ask again (run `contextzip config --ui` any time you want it). It's also skipped automatically for non-interactive runs, when `CI` is set, or when `--prompt`/`--output` are passed — it only ever offers on a plain, interactive, first-ever run.
-
-**Nothing about your project leaves your machine.** The server binds to `127.0.0.1` only (never `0.0.0.0`), every request needs a random per-session token embedded in the URL (the same approach Jupyter Notebook uses), and the page itself makes no calls anywhere except back to that local server — no CDN scripts, no web fonts, no analytics. Saving writes straight to `.contextzip/config.json` on disk and the server shuts itself down; if you close the tab without saving, it also shuts down after a short idle period so a forgotten session doesn't linger as an open port.
-
-If you accept the first-run offer, the same `contextzip` invocation picks up whatever you saved and finishes packaging immediately — no need to run it again.
-
 ---
 
 ## Contributing

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

@@ -1,6 +1,6 @@
 """contextzip — intelligent codebase packager for AI tools."""
 
-__version__ = "0.3.7"
+__version__ = "0.3.9"
 
 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.7 → contextzip-0.3.9}/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,
@@ -46,7 +47,7 @@ from contextzip.filters import (
     resolve_files,
     resolve_files_from_git,
 )
-from contextzip.git import GitChanges, GitError, GitErrorKind, get_changed_files
+from contextzip.git import GitError, GitErrorKind, get_changed_files
 from contextzip.packager import PackageResult, create_zip_silent
 
 
@@ -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: