contextzip 0.3.8__tar.gz → 0.3.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.3.8
+Version: 0.3.9
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -58,6 +58,7 @@ And when the AI tool hands you a ZIP back with the changes, `contextzip apply-zi
 - **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
 
@@ -121,7 +122,7 @@ contextzip [OPTIONS]
 | `--no-clipboard` | Skip the clipboard / folder-open step |
 | `--no-gitignore` | Ignore the project's `.gitignore` |
 
-**Subcommands:** `exclude`, `include`, `apply-zip`, `watch`, `config` — run `contextzip --help` for full details.
+**Subcommands:** `exclude`, `include`, `watch`, `config` — run `contextzip --help` for full details.
 
 ---
 
@@ -160,7 +161,7 @@ contextzip apply-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, apply_zip
+from contextzip import get_git_changes, get_files, create_zip
 
 # Get changed files and use them directly
 collection = get_git_changes()
@@ -190,7 +191,7 @@ print(f"Wrote {len(result.written)} files, backup at {result.backup_dir}")
 | `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`, `ZipNotFoundError`, etc.) rather than exiting.
+All functions default `path` to `Path.cwd()`. Errors raise typed exceptions (`NotARepositoryError`, `GitNotFoundError`, `NoFilesError`, etc.) rather than exiting.
 
 ---
 
@@ -218,60 +219,7 @@ contextzip config               # show current key status
 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.
+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.
 
 ---
 
@@ -292,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:**
 
@@ -314,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:**
 

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

@@ -29,6 +29,7 @@ And when the AI tool hands you a ZIP back with the changes, `contextzip apply-zi
 - **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
 
@@ -92,7 +93,7 @@ contextzip [OPTIONS]
 | `--no-clipboard` | Skip the clipboard / folder-open step |
 | `--no-gitignore` | Ignore the project's `.gitignore` |
 
-**Subcommands:** `exclude`, `include`, `apply-zip`, `watch`, `config` — run `contextzip --help` for full details.
+**Subcommands:** `exclude`, `include`, `watch`, `config` — run `contextzip --help` for full details.
 
 ---
 
@@ -131,7 +132,7 @@ contextzip apply-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, apply_zip
+from contextzip import get_git_changes, get_files, create_zip
 
 # Get changed files and use them directly
 collection = get_git_changes()
@@ -161,7 +162,7 @@ print(f"Wrote {len(result.written)} files, backup at {result.backup_dir}")
 | `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`, `ZipNotFoundError`, etc.) rather than exiting.
+All functions default `path` to `Path.cwd()`. Errors raise typed exceptions (`NotARepositoryError`, `GitNotFoundError`, `NoFilesError`, etc.) rather than exiting.
 
 ---
 
@@ -189,60 +190,7 @@ contextzip config               # show current key status
 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.
+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.
 
 ---
 
@@ -263,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:**
 
@@ -285,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:**
 

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

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

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

@@ -47,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
 
 

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

@@ -112,6 +112,9 @@ class ApplyPlan:
     manifest_path: Path | None
     entries: list[ApplyEntry] = field(default_factory=list)
     extraction_dir: Path = None  # type: ignore[assignment]
+    wrapper_stripped: str | None = None
+    wrapper_note: str | None = None
+    structure_warning: str | None = None
 
     @property
     def has_manifest(self) -> bool:
@@ -133,7 +136,11 @@ class ApplyPlan:
     @property
     def is_risky(self) -> bool:
         """True if anything here warrants a confirmation prompt before writing."""
-        return bool(self.risky_entries) or not self.has_manifest
+        return (
+            bool(self.risky_entries)
+            or not self.has_manifest
+            or bool(self.structure_warning)
+        )
 
 
 @dataclass
@@ -316,20 +323,36 @@ def _is_within(path: Path, parent: Path) -> bool:
         return False
 
 
-def _safe_extract(zip_path: Path, dest: Path) -> None:
+def _safe_extract(zip_path: Path, dest: Path, strip_prefix: str | None = None) -> None:
     """
     Extract *zip_path* into *dest*, refusing to write anything if any entry
     would resolve outside *dest* (zip-slip protection). Validated in a full
     first pass before any file is written, so a malicious entry never
     causes a partial extraction.
+
+    If *strip_prefix* is given (see `_detect_common_wrapper`), that leading
+    path component is removed from every entry before it's resolved against
+    *dest* — e.g. `codebase/contextzip/config.py` extracts to
+    `contextzip/config.py` instead of recreating a `codebase/` folder.
     """
     dest = dest.resolve()
+    strip = f"{strip_prefix}/" if strip_prefix else None
     with zipfile.ZipFile(zip_path) as zf:
         targets: dict[str, Path] = {}
         for info in zf.infolist():
             if info.is_dir():
                 continue
-            target = (dest / info.filename).resolve()
+            name = info.filename
+            if strip:
+                if not name.startswith(strip):
+                    # Shouldn't happen given how strip_prefix is detected
+                    # (every entry shares it), but never silently misplace
+                    # a file if it somehow doesn't.
+                    continue
+                name = name[len(strip):]
+                if not name:
+                    continue
+            target = (dest / name).resolve()
             if not _is_within(target, dest):
                 raise UnsafeZipEntryError(
                     f"Refusing to apply: entry '{info.filename}' resolves "
@@ -340,12 +363,53 @@ def _safe_extract(zip_path: Path, dest: Path) -> None:
         for info in zf.infolist():
             if info.is_dir():
                 continue
-            target = targets[info.filename]
+            target = targets.get(info.filename)
+            if target is None:
+                continue
             target.parent.mkdir(parents=True, exist_ok=True)
             with zf.open(info) as src, target.open("wb") as out:
                 shutil.copyfileobj(src, out)
 
 
+# ---------------------------------------------------------------------------
+# Wrapper-folder detection ((1) in the apply-zip structure fix)
+# ---------------------------------------------------------------------------
+
+
+def _detect_common_wrapper(names: list[str]) -> str | None:
+    """
+    If every entry in *names* is nested one level under the exact same
+    single top-level directory, return that directory's name — otherwise
+    None. This is the shape produced by `zip -r out.zip myfolder`, GitHub's
+    "Download ZIP" (`repo-branch/...`), and similar: an incidental wrapper
+    around the real, root-relative paths, rather than an intentional part
+    of the project's structure.
+
+    Deliberately conservative: a single root-level file mixed in with the
+    rest (no wrapper actually applies), or more than one top-level
+    directory, both return None rather than guessing.
+    """
+    if not names:
+        return None
+    tops: set[str] = set()
+    for n in names:
+        if "/" not in n:
+            return None
+        tops.add(n.split("/", 1)[0])
+    if len(tops) != 1:
+        return None
+    candidate = next(iter(tops))
+    return candidate or None
+
+
+def _match_rate(names: list[str], manifest_files: dict) -> float:
+    """Fraction of *names* that appear as a path in *manifest_files*."""
+    if not names:
+        return 0.0
+    known = sum(1 for n in names if n in manifest_files)
+    return known / len(names)
+
+
 # ---------------------------------------------------------------------------
 # Building the plan
 # ---------------------------------------------------------------------------
@@ -360,12 +424,55 @@ def build_plan(
     Extract *zip_path* to a temp directory and classify every file against
     *manifest_path* (may be None). Caller is responsible for eventually
     calling `execute_plan` or `discard_plan` to clean up the temp dir.
+
+    Before extracting, checks whether every entry in the zip shares a
+    single wrapping top-level directory (e.g. `codebase/contextzip/...`)
+    that isn't actually part of the project — see `_detect_common_wrapper`.
+    If so, and stripping it would line paths up with the manifest better
+    than leaving them alone, it's stripped automatically. Separately, if a
+    manifest exists and almost none of the resulting paths match it,
+    `structure_warning` is set so the caller can make sure the person
+    actually looks before applying — a zip whose files come out looking
+    all-new is exactly what a silently-mismatched structure produces.
     """
     manifest = load_manifest(manifest_path) if manifest_path else {}
     manifest_files: dict = manifest.get("files", {}) if manifest else {}
 
+    with zipfile.ZipFile(zip_path) as zf:
+        raw_names = sorted(i.filename for i in zf.infolist() if not i.is_dir())
+
+    strip_prefix: str | None = None
+    wrapper_note: str | None = None
+    candidate = _detect_common_wrapper(raw_names)
+    if candidate and not (project_dir / candidate).is_dir():
+        if manifest_files:
+            unstripped_rate = _match_rate(raw_names, manifest_files)
+            stripped_names = [n[len(candidate) + 1:] for n in raw_names]
+            stripped_rate = _match_rate(stripped_names, manifest_files)
+            # Only strip when it clearly helps — meaningfully better match
+            # against paths we know this project actually has, not just a
+            # coincidental improvement on a tiny zip.
+            if stripped_rate > unstripped_rate and stripped_rate >= 0.5:
+                strip_prefix = candidate
+                wrapper_note = (
+                    f"Removed wrapping folder '{candidate}/' present in every "
+                    f"zip entry — {stripped_rate:.0%} of paths matched the "
+                    f"project manifest after stripping vs {unstripped_rate:.0%} "
+                    "before."
+                )
+        else:
+            # No manifest to confirm against, so this is a softer call —
+            # still strip (matches how `tar` and GitHub's own zip downloads
+            # behave), but say so plainly since it's not manifest-verified.
+            strip_prefix = candidate
+            wrapper_note = (
+                f"Removed wrapping folder '{candidate}/' present in every zip "
+                "entry (no manifest available to confirm — double-check the "
+                "result before trusting it)."
+            )
+
     extraction_dir = Path(tempfile.mkdtemp(prefix="contextzip-apply-"))
-    _safe_extract(zip_path, extraction_dir)
+    _safe_extract(zip_path, extraction_dir, strip_prefix=strip_prefix)
 
     entries: list[ApplyEntry] = []
     for extracted in sorted(extraction_dir.rglob("*")):
@@ -406,11 +513,30 @@ def build_plan(
             ApplyEntry(rel_path=rel, status=status, size=size, extracted_path=extracted)
         )
 
+    structure_warning: str | None = None
+    if manifest_files and len(entries) >= 3:
+        known = sum(1 for e in entries if e.rel_path in manifest_files)
+        rate = known / len(entries)
+        if rate < 0.1:
+            structure_warning = (
+                f"Only {known} of {len(entries)} files in this zip match paths "
+                "from the project manifest, even after checking for a wrapping "
+                "folder. That usually means the zip's internal structure "
+                "doesn't line up with this project — the wrong zip, or one "
+                "built with an unexpected layout. Applying it as-is will "
+                "likely create a pile of unrelated new files rather than "
+                "update the ones you meant to change. Double-check the zip "
+                "before proceeding."
+            )
+
     return ApplyPlan(
         zip_path=zip_path,
         manifest_path=manifest_path,
         entries=entries,
         extraction_dir=extraction_dir,
+        wrapper_stripped=strip_prefix,
+        wrapper_note=wrapper_note,
+        structure_warning=structure_warning,
     )
 
 
@@ -450,15 +576,28 @@ def _backup_entries(
 def _move_zip_to_applied(zip_path: Path, project_dir: Path, workspace_root: Path) -> Path:
     """
     Move a consumed inbox zip into .contextzip/inbox/applied/, timestamped,
-    so it can't be accidentally re-applied and stays around as an audit
-    trail. Zips passed by an explicit path outside the inbox are left where
-    the user put them rather than being moved unexpectedly.
+    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.
     """
     if zip_path.parent.resolve() != inbox_dir(project_dir).resolve():
         return zip_path
 
     applied_dir = workspace_root / _INBOX_DIRNAME / _APPLIED_DIRNAME
     applied_dir.mkdir(parents=True, exist_ok=True)
+
+    for old in applied_dir.glob("*.zip"):
+        try:
+            old.unlink()
+        except OSError:
+            pass  # best-effort — a leftover old zip isn't worth failing the apply over
+
     stamp = time.strftime("%Y%m%d-%H%M%S")
     dest = applied_dir / f"{stamp}-{zip_path.name}"
     try:

{contextzip-0.3.8 → contextzip-0.3.9}/contextzip/cli.py

@@ -424,9 +424,12 @@ def cmd_apply_zip(
         return
 
     if plan.is_risky and not yes:
-        proceed = click.confirm(
-            "  Some files above need a closer look — apply anyway?", default=False
+        prompt = (
+            "  This zip's structure doesn't look right — apply anyway?"
+            if plan.structure_warning
+            else "  Some files above need a closer look — apply anyway?"
         )
+        proceed = click.confirm(prompt, default=False)
         if not proceed:
             console.print("[dim]Cancelled — no files written.[/]")
             discard_plan(plan)

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

@@ -354,8 +354,21 @@ def print_apply_plan(
             "  [dim]Manifest:[/]  [yellow]none found[/] "
             "[dim](every existing path will be treated as untracked)[/]"
         )
+    if plan.wrapper_note:
+        con.print(f"  [dim]Note    :[/]  [cyan]{plan.wrapper_note}[/]")
     con.print()
 
+    if plan.structure_warning:
+        con.print(
+            Panel(
+                f"[bold yellow]{plan.structure_warning}[/]",
+                title="[bold yellow]⚠ Structure mismatch[/]",
+                border_style="yellow",
+                padding=(0, 1),
+            )
+        )
+        con.print()
+
     counts = Counter(e.status.value for e in plan.entries)
     table = Table(box=box.ROUNDED, show_header=False, padding=(0, 2))
     table.add_column(style="dim")

{contextzip-0.3.8 → contextzip-0.3.9}/contextzip/config.py

@@ -87,10 +87,7 @@ def save_api_key(key: str) -> None:
     _CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
     data = _read_config()
     data["gemini_api_key"] = key.strip()
-    _CONFIG_FILE.write_text(
-        json.dumps(data, indent=2) + "\n",
-        encoding="utf-8",
-    )
+    _write_config(data)
 
 
 def delete_api_key() -> bool:
@@ -105,10 +102,7 @@ def delete_api_key() -> bool:
         if "gemini_api_key" not in data:
             return False
         del data["gemini_api_key"]
-        _CONFIG_FILE.write_text(
-            json.dumps(data, indent=2) + "\n",
-            encoding="utf-8",
-        )
+        _write_config(data)
         return True
     except Exception:
         return False
@@ -179,10 +173,7 @@ def save_workspace_location(value: str) -> None:
     _CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
     data = _read_config()
     data["workspace_location"] = value.strip()
-    _CONFIG_FILE.write_text(
-        json.dumps(data, indent=2) + "\n",
-        encoding="utf-8",
-    )
+    _write_config(data)
 
 
 def delete_workspace_location() -> bool:
@@ -192,10 +183,7 @@ def delete_workspace_location() -> bool:
         if "workspace_location" not in data:
             return False
         del data["workspace_location"]
-        _CONFIG_FILE.write_text(
-            json.dumps(data, indent=2) + "\n",
-            encoding="utf-8",
-        )
+        _write_config(data)
         return True
     except Exception:
         return False
@@ -225,10 +213,30 @@ def save_config_ui_dismissed() -> None:
     _CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
     data = _read_config()
     data["config_ui_prompt_dismissed"] = True
+    _write_config(data)
+
+
+def _write_config(data: dict) -> None:
+    """
+    Write *data* to the config file and lock its permissions down to the
+    owner only (0600) on POSIX systems.
+
+    The file may hold a Gemini API key in plaintext, so it shouldn't be
+    left group/world-readable — other local accounts on a shared machine
+    could otherwise read it straight off disk. Applied on every write
+    (not just creation) since some platforms reset perms on rewrite, and
+    a pre-existing file from an older contextzip version may still have
+    the old default (umask-dependent) permissions.
+    """
     _CONFIG_FILE.write_text(
         json.dumps(data, indent=2) + "\n",
         encoding="utf-8",
     )
+    if os.name != "nt":
+        try:
+            os.chmod(_CONFIG_FILE, 0o600)
+        except OSError:
+            pass  # best-effort — never block a save over a chmod failure
 
 
 def _read_config() -> dict:

{contextzip-0.3.8 → contextzip-0.3.9}/contextzip/rules/base.py

@@ -36,6 +36,37 @@ PATTERNS = [
     "*.key",
     "*.p12",
     "*.pfx",
+    "*.pkcs12",
+    "*.jks",
+    "*.keystore",
+    "*.ppk",
+    # SSH private keys — no extension, so matched by exact basename.
+    # Public counterparts (id_rsa.pub etc.) are intentionally NOT excluded.
+    "id_rsa",
+    "id_dsa",
+    "id_ecdsa",
+    "id_ed25519",
+    # Credential files for common CLIs/package managers (auth tokens)
+    ".npmrc",
+    ".netrc",
+    ".pypirc",
+    ".pgpass",
+    ".dockercfg",
+    "docker/config.json",
+    ".docker/config.json",
+    # Cloud provider credential/config files
+    ".aws/credentials",
+    ".aws/config",
+    "*serviceaccount*.json",
+    "*service-account*.json",
+    "*credentials*.json",
+    "kubeconfig",
+    "*.kubeconfig",
+    # Infra-as-code state (Terraform state routinely contains plaintext
+    # secrets — resource passwords, keys — even for "just infra" resources)
+    "*.tfstate",
+    "*.tfstate.*",
+    ".terraform/",
     # Binaries & media (rarely useful for AI context)
     "*.exe",
     "*.dll",

{contextzip-0.3.8 → contextzip-0.3.9}/contextzip/webui/server.py

@@ -24,6 +24,7 @@ preview feeling instant even on larger projects.
 
 from __future__ import annotations
 
+import hmac
 import json
 import secrets
 import threading
@@ -90,7 +91,9 @@ class _ConfigUIState:
             gitignore_path=self.gitignore_path,
         )
         force_include = build_force_include_spec(always_include or None)
-        return classify_scanned_files(self.project_dir, self.all_files, spec, force_include)
+        return classify_scanned_files(
+            self.project_dir, self.all_files, spec, force_include
+        )
 
 
 def _make_handler(state: _ConfigUIState):
@@ -112,7 +115,10 @@ def _make_handler(state: _ConfigUIState):
             return self.headers.get("X-Contextzip-Token")
 
         def _authorized(self) -> bool:
-            return self._token_from_request() == state.token
+            token = self._token_from_request()
+            if not token:
+                return False
+            return hmac.compare_digest(token, state.token)
 
         def _send_json(self, status: int, payload: dict) -> None:
             body = json.dumps(payload).encode("utf-8")
@@ -158,7 +164,9 @@ def _make_handler(state: _ConfigUIState):
             except ValueError:
                 return None
 
-        def _build_payload(self, always_include: list[str], always_exclude: list[str]) -> dict:
+        def _build_payload(
+            self, always_include: list[str], always_exclude: list[str]
+        ) -> dict:
             classified = state.classify(always_include, always_exclude)
 
             root: dict = {"name": "", "path": "", "type": "dir", "children": {}}
@@ -279,7 +287,9 @@ def _make_handler(state: _ConfigUIState):
                 if not self._authorized():
                     self._send_json(403, {"error": "invalid token"})
                     return
-                payload = self._build_payload(state.always_include, state.always_exclude)
+                payload = self._build_payload(
+                    state.always_include, state.always_exclude
+                )
                 payload["project"] = {
                     "name": state.project_dir.name or str(state.project_dir),
                     "path": str(state.project_dir),
@@ -324,8 +334,12 @@ def _make_handler(state: _ConfigUIState):
                     self._send_json(403, {"error": "invalid token"})
                     return
                 body = self._read_json_body()
-                always_include = [p for p in body.get("always_include", []) if isinstance(p, str)]
-                always_exclude = [p for p in body.get("always_exclude", []) if isinstance(p, str)]
+                always_include = [
+                    p for p in body.get("always_include", []) if isinstance(p, str)
+                ]
+                always_exclude = [
+                    p for p in body.get("always_exclude", []) if isinstance(p, str)
+                ]
                 payload = self._build_payload(always_include, always_exclude)
                 self._send_json(200, payload)
                 return
@@ -336,10 +350,14 @@ def _make_handler(state: _ConfigUIState):
                     return
                 body = self._read_json_body()
                 always_include = [
-                    p.strip() for p in body.get("always_include", []) if isinstance(p, str) and p.strip()
+                    p.strip()
+                    for p in body.get("always_include", [])
+                    if isinstance(p, str) and p.strip()
                 ]
                 always_exclude = [
-                    p.strip() for p in body.get("always_exclude", []) if isinstance(p, str) and p.strip()
+                    p.strip()
+                    for p in body.get("always_exclude", [])
+                    if isinstance(p, str) and p.strip()
                 ]
                 with state.lock:
                     try:
@@ -404,7 +422,9 @@ def launch_config_ui(project_dir: Path, detection, *, con: Console = None) -> bo
 
     start = time.monotonic()
     try:
-        with con.status("[cyan]Waiting for you to finish in the browser…[/]", spinner="dots"):
+        with con.status(
+            "[cyan]Waiting for you to finish in the browser…[/]", spinner="dots"
+        ):
             while not state.should_stop.is_set() and not state.saved:
                 now = time.monotonic()
                 if now - state.last_activity > _IDLE_TIMEOUT_SECONDS:
@@ -419,7 +439,9 @@ def launch_config_ui(project_dir: Path, detection, *, con: Console = None) -> bo
         httpd.server_close()
 
     if state.saved:
-        con.print(f"  [green]✓[/]  Saved to [dim]{project_config_path(project_dir)}[/]\n")
+        con.print(
+            f"  [green]✓[/]  Saved to [dim]{project_config_path(project_dir)}[/]\n"
+        )
     else:
         con.print("  [dim]Config UI closed without saving.[/]\n")
 

{contextzip-0.3.8 → contextzip-0.3.9}/contextzip.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.3.8
+Version: 0.3.9
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -58,6 +58,7 @@ And when the AI tool hands you a ZIP back with the changes, `contextzip apply-zi
 - **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
 
@@ -121,7 +122,7 @@ contextzip [OPTIONS]
 | `--no-clipboard` | Skip the clipboard / folder-open step |
 | `--no-gitignore` | Ignore the project's `.gitignore` |
 
-**Subcommands:** `exclude`, `include`, `apply-zip`, `watch`, `config` — run `contextzip --help` for full details.
+**Subcommands:** `exclude`, `include`, `watch`, `config` — run `contextzip --help` for full details.
 
 ---
 
@@ -160,7 +161,7 @@ contextzip apply-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, apply_zip
+from contextzip import get_git_changes, get_files, create_zip
 
 # Get changed files and use them directly
 collection = get_git_changes()
@@ -190,7 +191,7 @@ print(f"Wrote {len(result.written)} files, backup at {result.backup_dir}")
 | `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`, `ZipNotFoundError`, etc.) rather than exiting.
+All functions default `path` to `Path.cwd()`. Errors raise typed exceptions (`NotARepositoryError`, `GitNotFoundError`, `NoFilesError`, etc.) rather than exiting.
 
 ---
 
@@ -218,60 +219,7 @@ contextzip config               # show current key status
 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.
+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.
 
 ---
 
@@ -292,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:**
 
@@ -314,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:**
 

{contextzip-0.3.8 → contextzip-0.3.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "contextzip"
-version = "0.3.8"
+version = "0.3.9"
 description = "Intelligently package your codebase for AI tools"
 readme = "README.md"
 requires-python = ">=3.9"