contextzip 0.4.3__tar.gz → 0.4.4__tar.gz

{contextzip-0.4.3 → contextzip-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.4.3
+Version: 0.4.4
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -87,7 +87,7 @@ Full function reference: [contextzip.vercel.app/cli#python-api](https://contextz
 - [Packaging & detection](https://contextzip.vercel.app/features) — frameworks, exclusion rules, safety
 - [AI-powered file selection](https://contextzip.vercel.app/ai-selection) — `--prompt`, Gemini setup
 - [Terminal error watcher](https://contextzip.vercel.app/watch) — `contextzip watch`
-- [Applying changes back](https://contextzip.vercel.app/apply-zip) — `apply-zip`, backups, safety
+- [Applying changes back](https://contextzip.vercel.app/apply-zip) — `apply-zip`, manifest diffing, safety
 - [Configuration](https://contextzip.vercel.app/configuration) — personal & project config, visual config UI
 - [CLI & Python API reference](https://contextzip.vercel.app/cli)
 

{contextzip-0.4.3 → contextzip-0.4.4}/README.md

@@ -58,7 +58,7 @@ Full function reference: [contextzip.vercel.app/cli#python-api](https://contextz
 - [Packaging & detection](https://contextzip.vercel.app/features) — frameworks, exclusion rules, safety
 - [AI-powered file selection](https://contextzip.vercel.app/ai-selection) — `--prompt`, Gemini setup
 - [Terminal error watcher](https://contextzip.vercel.app/watch) — `contextzip watch`
-- [Applying changes back](https://contextzip.vercel.app/apply-zip) — `apply-zip`, backups, safety
+- [Applying changes back](https://contextzip.vercel.app/apply-zip) — `apply-zip`, manifest diffing, safety
 - [Configuration](https://contextzip.vercel.app/configuration) — personal & project config, visual config UI
 - [CLI & Python API reference](https://contextzip.vercel.app/cli)
 

{contextzip-0.4.3 → contextzip-0.4.4}/contextzip/__init__.py

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

{contextzip-0.4.3 → contextzip-0.4.4}/contextzip/api.py

@@ -354,8 +354,6 @@ def apply_zip(
     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
@@ -375,8 +373,7 @@ def apply_zip(
     Returns
     -------
     ApplyResult
-        ``written`` (list of relative paths written), ``backup_dir``
-        (``Path`` or ``None`` if nothing needed backing up), and
+        ``written`` (list of relative paths written) and
         ``applied_zip_path`` (where the consumed zip ended up).
 
     Raises
@@ -393,8 +390,6 @@ def 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,

{contextzip-0.4.3 → contextzip-0.4.4}/contextzip/applier.py

@@ -48,8 +48,86 @@ from pathlib import Path
 _MANIFEST_SUFFIX = ".manifest.json"
 _INBOX_DIRNAME = "inbox"
 _APPLIED_DIRNAME = "applied"
-_BACKUPS_DIRNAME = "backups"
 _OUTPUT_DIRNAME = "output"  # must match packager._OUTPUT_DIRNAME
+_INBOX_README_NAME = "README.txt"
+
+_INBOX_README_CONTENTS = """\
+Drop your zip here which you want to apply.
+============================================
+
+This folder is contextzip's inbox — the one place `apply-zip` looks for
+a zip to bring back into your project.
+
+HOW TO USE IT
+  1. Take the zip your AI tool (Claude, ChatGPT, etc.) gave you back,
+     after you sent it a codebase package contextzip made for you.
+  2. Drop that zip file directly into this folder — no need to rename
+     it or unzip it first.
+  3. Run:  contextzip apply-zip     (short alias:  cz apply-zip)
+  4. contextzip finds it automatically, compares every file inside it
+     against your project's manifest, and shows you exactly what's
+     new, modified, or unchanged before writing anything to disk.
+
+WHAT HAPPENS TO THE ZIP AFTERWARDS
+  Once applied, contextzip moves it into inbox/applied/ instead of
+  deleting it, so there's always a record of exactly what was applied
+  and when. Old entries there are pruned automatically over time — see
+  the `cleanup` and `applied_zip_retention` settings in
+  .contextzip/config.json if you'd like to keep more of them.
+
+A FEW THINGS WORTH KNOWING
+  - Only .zip files placed directly in this folder are picked up —
+    not ones inside a subfolder.
+  - If more than one zip ends up here at once, contextzip will ask you
+    to say which one: contextzip apply-zip <name>.zip
+  - You can also point apply-zip at a zip anywhere else on disk instead
+    of using this folder: contextzip apply-zip /path/to/file.zip
+  - This whole .contextzip/ folder is local to your machine and is
+    never committed to git (see .contextzip/.gitignore) — nothing here
+    leaves your computer unless you explicitly share it yourself.
+  - This file is just documentation — it's fine to edit it, and it
+    won't affect anything if you do. If it ever goes missing, though,
+    contextzip will put a fresh copy back the next time it touches this
+    folder; it never touches an actual pending zip, only this file.
+
+Full docs: https://contextzip.vercel.app/apply-zip
+"""
+
+
+def ensure_inbox_scaffolding(workspace: Path) -> None:
+    """
+    Make sure <workspace>/inbox/ exists, with its README.txt explaining
+    what the folder is for.
+
+    Called at the same moment the rest of the .contextzip/ workspace gets
+    set up (see packager.py's `_workspace_output_path[_silent]`), so the
+    inbox is ready and self-explanatory from the very first run — rather
+    than a bare, unexplained folder someone only discovers by reading the
+    docs, or worse, one that doesn't exist yet the first time `apply-zip`
+    goes looking for it.
+
+    Idempotent, same rule as the workspace .gitignore (see
+    `_ensure_workspace_gitignore` in packager.py): leaves an
+    already-correct README.txt untouched, and (re)writes it whenever it's
+    missing or doesn't match, so it stays reliable documentation rather
+    than something that quietly rots or disappears. Never touches
+    anything else already in the inbox — pending zips, `applied/`, past
+    reports.
+    """
+    inbox = workspace / _INBOX_DIRNAME
+    inbox.mkdir(parents=True, exist_ok=True)
+
+    readme_path = inbox / _INBOX_README_NAME
+    if readme_path.is_file():
+        try:
+            if readme_path.read_text(encoding="utf-8", errors="replace") == _INBOX_README_CONTENTS:
+                return
+        except OSError:
+            return
+    try:
+        readme_path.write_text(_INBOX_README_CONTENTS, encoding="utf-8")
+    except OSError:
+        pass
 
 # Files contextzip itself writes into outgoing ZIPs that should never be
 # written back into the project even if an AI tool echoes them back.
@@ -146,7 +224,6 @@ class ApplyPlan:
 @dataclass
 class ApplyResult:
     written: list[str]
-    backup_dir: Path | None
     applied_zip_path: Path
 
 
@@ -266,10 +343,17 @@ def find_zip_to_apply(
 
     inbox = inbox_dir(project_dir)
     if not inbox.is_dir():
+        # Normally created alongside the rest of .contextzip/ the first
+        # time any contextzip command runs (see
+        # ensure_inbox_scaffolding), so this only fires if apply-zip is
+        # somehow the very first command run in a project. Create it now
+        # rather than just describing where it should be — so the folder
+        # (and its README) are actually there for the person to drop a
+        # zip into right after reading this message.
+        ensure_inbox_scaffolding(_workspace_dir(project_dir))
         raise NoZipFoundError(
-            f"No zip found. Drop the AI-returned zip into {inbox} "
-            "(created the first time you run contextzip), or pass a path "
-            "directly: contextzip apply-zip <path>"
+            f"No zip found. Drop the AI-returned zip into {inbox}, "
+            "or pass a path directly: contextzip apply-zip <path>"
         )
 
     candidates = sorted(p for p in inbox.glob("*.zip") if p.is_file())
@@ -417,6 +501,31 @@ def _match_rate(names: list[str], manifest_files: dict) -> float:
 # ---------------------------------------------------------------------------
 
 
+def _top_level_dir_match_rate(names: list[str], project_dir: Path) -> float:
+    """
+    Fraction of *names*' unique top-level path segments that exist as a
+    real file or directory directly under *project_dir* right now.
+
+    Used as a fallback signal for wrapper-stripping when the manifest
+    can't settle it — e.g. the freshest manifest on disk is a narrow,
+    git-diff-scoped one (`.contextzip/output/git-changes/...`) that only
+    ever listed a handful of touched files, so a zip full of brand-new
+    files matches it at ~0% whether or not the wrapper is stripped. The
+    manifest is silent either way, but the project's actual top-level
+    layout — `app/`, `components/`, `lib/`, and so on — usually isn't:
+    a genuine wrapper's contents line up with it once stripped, while
+    the raw, unstripped paths (starting with the wrapper's own name)
+    essentially never do.
+    """
+    if not names:
+        return 0.0
+    tops = {n.split("/", 1)[0] for n in names}
+    if not tops:
+        return 0.0
+    existing = sum(1 for t in tops if t and (project_dir / t).exists())
+    return existing / len(tops)
+
+
 def build_plan(
     zip_path: Path,
     project_dir: Path,
@@ -447,6 +556,9 @@ def build_plan(
     wrapper_note: str | None = None
     candidate = _detect_common_wrapper(raw_names)
     if candidate:
+        stripped_names = [n[len(candidate) + 1:] for n in raw_names]
+        candidate_is_real_dir = (project_dir / candidate).is_dir()
+
         if manifest_files:
             # Decide using the manifest — actual ground truth about what
             # paths this project has — rather than whether a directory of
@@ -465,7 +577,6 @@ def build_plan(
             # better *unstripped*, since those paths are already in the
             # manifest as-is.
             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
@@ -478,18 +589,53 @@ def build_plan(
                     f"project manifest after stripping vs {unstripped_rate:.0%} "
                     "before."
                 )
-        elif not (project_dir / candidate).is_dir():
+            elif stripped_rate == unstripped_rate and not candidate_is_real_dir:
+                # The manifest didn't help decide either way — most often
+                # because the manifest in use is scoped to a small subset
+                # of the project (e.g. a git-diff manifest from
+                # output/git-changes/, which only ever tracked the files
+                # touched in one change) rather than the whole tree, so a
+                # zip of brand-new files matches it at 0% regardless of
+                # stripping. Fall back to checking whether the paths line
+                # up with the project's real, current top-level layout
+                # instead of giving up and leaving the wrapper in place.
+                dir_unstripped_rate = _top_level_dir_match_rate(raw_names, project_dir)
+                dir_stripped_rate = _top_level_dir_match_rate(stripped_names, project_dir)
+                if dir_stripped_rate > dir_unstripped_rate and dir_stripped_rate >= 0.5:
+                    strip_prefix = candidate
+                    wrapper_note = (
+                        f"Removed wrapping folder '{candidate}/' present in "
+                        "every zip entry — the project manifest in use didn't "
+                        "cover enough of these paths to tell either way "
+                        "(likely scoped to a specific change rather than the "
+                        "whole project), but "
+                        f"{dir_stripped_rate:.0%} of the stripped paths' "
+                        "top-level folders match this project's real layout "
+                        f"vs {dir_unstripped_rate:.0%} before — double-check "
+                        "the result before trusting it."
+                    )
+        elif not candidate_is_real_dir:
             # No manifest to confirm against, so this is a softer call —
             # still strip (matches how `tar` and GitHub's own zip downloads
             # behave) as long as the project doesn't already have a real
             # folder of that name, but say so plainly since it's not
-            # manifest-verified.
+            # manifest-verified. Where the on-disk layout backs it up, say
+            # that too rather than leaving the caveat maximally vague.
             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)."
-            )
+            dir_stripped_rate = _top_level_dir_match_rate(stripped_names, project_dir)
+            if dir_stripped_rate >= 0.5:
+                wrapper_note = (
+                    f"Removed wrapping folder '{candidate}/' present in every "
+                    f"zip entry — {dir_stripped_rate:.0%} of the stripped "
+                    "paths' top-level folders match this project's real "
+                    "layout (no manifest available to confirm further)."
+                )
+            else:
+                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, strip_prefix=strip_prefix)
@@ -538,16 +684,31 @@ def build_plan(
         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."
-            )
+            if strip_prefix and "top-level folders match" in (wrapper_note or ""):
+                # The wrapper was already resolved via the on-disk layout
+                # fallback above, so don't re-cast that as if the wrapper
+                # check itself came up empty — it didn't, the manifest just
+                # doesn't happen to cover these particular files.
+                structure_warning = (
+                    f"Only {known} of {len(entries)} files in this zip match "
+                    "paths from the project manifest. The wrapper folder was "
+                    "still resolved using the project's real directory "
+                    "layout (see above), but none of these exact files were "
+                    "in the manifest, so this may be new work the manifest "
+                    "predates rather than a mismatch — worth a quick look "
+                    "before applying."
+                )
+            else:
+                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,
@@ -570,29 +731,6 @@ def discard_plan(plan: ApplyPlan) -> None:
 # ---------------------------------------------------------------------------
 
 
-def _backup_entries(
-    entries: list[ApplyEntry], project_dir: Path, workspace_root: Path
-) -> Path | None:
-    """
-    Copy the current, pre-apply version of every existing file about to be
-    touched into .contextzip/backups/<timestamp>/, preserving relative
-    paths. Files that don't exist yet locally (new files) have nothing to
-    back up. Returns the backup directory, or None if nothing needed one.
-    """
-    to_backup = [e for e in entries if (project_dir / e.rel_path).is_file()]
-    if not to_backup:
-        return None
-
-    stamp = time.strftime("%Y%m%d-%H%M%S")
-    backup_dir = workspace_root / _BACKUPS_DIRNAME / stamp
-    for entry in to_backup:
-        src = project_dir / entry.rel_path
-        dst = backup_dir / entry.rel_path
-        dst.parent.mkdir(parents=True, exist_ok=True)
-        shutil.copy2(src, dst)
-    return backup_dir
-
-
 def _move_zip_to_applied(
     zip_path: Path, project_dir: Path, workspace_root: Path, retain: int = 1
 ) -> Path:
@@ -639,9 +777,14 @@ def execute_plan(plan: ApplyPlan, project_dir: Path, retain: int = 1) -> ApplyRe
     """
     Write every non-unchanged entry from *plan* into the project.
 
-    Backs up whatever's about to be overwritten first. Assumes the caller
-    has already decided to proceed — dry-run and confirmation prompts are
-    handled upstream (see cli.py's `apply-zip` command).
+    Assumes the caller has already decided to proceed — dry-run and
+    confirmation prompts are handled upstream (see cli.py's `apply-zip`
+    command). Files are overwritten directly, with no backup taken first:
+    `build_plan`'s manifest diff and the confirmation prompt it drives
+    (see `ApplyPlan.is_risky`) are the safety net here, and the zip you
+    just applied is itself always recoverable — it's archived to
+    `.contextzip/inbox/applied/` (or left wherever you pointed at it)
+    rather than deleted.
 
     *retain* caps how many applied zips are kept in
     .contextzip/inbox/applied/ — typically a project's
@@ -650,8 +793,6 @@ def execute_plan(plan: ApplyPlan, project_dir: Path, retain: int = 1) -> ApplyRe
     workspace_root = _workspace_dir(project_dir)
     to_write = plan.writable_entries
 
-    backup_dir = _backup_entries(to_write, project_dir, workspace_root)
-
     written: list[str] = []
     for entry in to_write:
         dest = project_dir / entry.rel_path
@@ -664,6 +805,4 @@ def execute_plan(plan: ApplyPlan, project_dir: Path, retain: int = 1) -> ApplyRe
     )
     shutil.rmtree(plan.extraction_dir, ignore_errors=True)
 
-    return ApplyResult(
-        written=written, backup_dir=backup_dir, applied_zip_path=applied_zip_path
-    )
+    return ApplyResult(written=written, applied_zip_path=applied_zip_path)

{contextzip-0.4.3 → contextzip-0.4.4}/contextzip/cleanup.py

@@ -2,21 +2,16 @@
 cleanup.py — Automatic workspace housekeeping for contextzip.
 
 .contextzip/ accumulates disposable artifacts over time: a zip+manifest+report
-set every run, a timestamped backup folder every risky `apply-zip`, and (until
-pruned) old archived applied-zips. None of it is precious — every zip is
-trivially reproducible by just re-running contextzip, and a backup only
-matters until the apply that made it is confirmed good. So cleanup here is
-deliberately brutal rather than cautious: it runs automatically after every
-successful command (see `_auto_cleanup` in cli.py), with no prompt and no
-separate command to remember, and keeps only the most recent
-`cleanup.keep_recent` item(s) in each category — everything else is deleted
-immediately, every time.
-
-The heavier caution used elsewhere in contextzip (backing up before overwrite
-in apply-zip, never inferring deletions) is reserved for the project's own
-files, where losing something can mean losing real work. Nothing here ever
-touches the project — only disposable metadata under .contextzip/ that costs
-nothing to regenerate.
+set every run, and (until pruned) old archived applied-zips and loose apply
+reports. None of it is precious — every zip is trivially reproducible by just
+re-running contextzip. So cleanup here is deliberately brutal rather than
+cautious: it runs automatically after every successful command (see
+`_auto_cleanup` in cli.py), with no prompt and no separate command to
+remember, and keeps only the most recent `cleanup.keep_recent` item(s) in
+each category — everything else is deleted immediately, every time.
+
+Nothing here ever touches the project — only disposable metadata under
+.contextzip/ that costs nothing to regenerate.
 
 Never touched, under any settings:
   - .contextzip/config.json (project preferences)
@@ -28,11 +23,22 @@ Never touched, under any settings:
 Kept only-the-most-recent-N, everything older deleted immediately:
   - zip/manifest/report sets under .contextzip/output/<mode>/, per mode
     folder
-  - timestamped folders under .contextzip/backups/
   - archived zips under .contextzip/inbox/applied/ (this is also governed
     by `applied_zip_retention`, already enforced on every apply-zip run —
     scanning it here too just catches the case where zips piled up before
     that setting existed, or the setting was since lowered)
+  - loose `*.apply-report.txt` files sitting directly in .contextzip/inbox/
+    (as opposed to inbox/applied/) — these are written next to wherever
+    apply-zip resolved its zip from, decoupled from the zip's own
+    lifecycle (a zip gets archived into applied/ or left where the user
+    put it; its report always lands in inbox/ itself), so nothing else
+    here would ever catch them piling up run after run
+
+Removed outright, no matter how recent:
+  - .contextzip/backups/ in its entirety. apply-zip no longer creates
+    per-run backups there at all — this only ever catches a leftover
+    folder from a project that used an older contextzip version, and it's
+    dead weight the moment that version is gone.
 
 Scanning only ever touches .contextzip/ directory listings and file mtimes —
 no hashing, no reading file contents — so this stays fast even called on
@@ -47,7 +53,7 @@ from pathlib import Path
 
 
 _OUTPUT_DIRNAME = "output"
-_BACKUPS_DIRNAME = "backups"
+_LEGACY_BACKUPS_DIRNAME = "backups"
 _INBOX_DIRNAME = "inbox"
 _APPLIED_DIRNAME = "applied"
 
@@ -60,7 +66,7 @@ _APPLIED_DIRNAME = "applied"
 @dataclass
 class CleanupItem:
     path: Path
-    kind: str  # "zip-set" | "backup" | "applied-zip"
+    kind: str  # "zip-set" | "applied-zip" | "apply-report" | "legacy-backups"
     size_bytes: int
 
 
@@ -160,14 +166,14 @@ def scan(
             for f in _zip_set_files(zp):
                 items.append(CleanupItem(path=f, kind="zip-set", size_bytes=_size_of(f)))
 
-    # ── backups/<timestamp>/ ─────────────────────────────────────────────
-    backups_root = workspace / _BACKUPS_DIRNAME
+    # ── backups/ — the feature that created these is gone entirely; wipe
+    #    the whole folder outright rather than pruning it, so upgrading
+    #    from an older contextzip version doesn't leave it behind forever ──
+    backups_root = workspace / _LEGACY_BACKUPS_DIRNAME
     if backups_root.is_dir():
-        backups = _newest_first([p for p in backups_root.iterdir() if p.is_dir()])
-        for backup_dir in backups[keep:]:
-            items.append(
-                CleanupItem(path=backup_dir, kind="backup", size_bytes=_size_of(backup_dir))
-            )
+        items.append(
+            CleanupItem(path=backups_root, kind="legacy-backups", size_bytes=_size_of(backups_root))
+        )
 
     # ── inbox/applied/ ───────────────────────────────────────────────────
     applied_root = workspace / _INBOX_DIRNAME / _APPLIED_DIRNAME
@@ -177,6 +183,19 @@ def scan(
         for zp in applied_zips[retain:]:
             items.append(CleanupItem(path=zp, kind="applied-zip", size_bytes=_size_of(zp)))
 
+    # ── inbox/*.apply-report.txt ─────────────────────────────────────────
+    # Loose report files written directly in the inbox root (see
+    # report.py's write_apply_report) — decoupled from any single zip's
+    # own path, so nothing above ever catches these. Every apply-zip run
+    # writes one, so left alone they'd accumulate forever.
+    inbox_root = workspace / _INBOX_DIRNAME
+    if inbox_root.is_dir():
+        reports = _newest_first(
+            [p for p in inbox_root.glob("*.apply-report.txt") if p.is_file()]
+        )
+        for rp in reports[keep:]:
+            items.append(CleanupItem(path=rp, kind="apply-report", size_bytes=_size_of(rp)))
+
     return CleanupPlan(workspace=workspace, items=items)
 
 

{contextzip-0.4.3 → contextzip-0.4.4}/contextzip/cli.py

@@ -382,8 +382,7 @@ def cmd_apply_zip(
       every file as new, modified, unchanged, or one needing a closer look
       (edited locally since zipping, or with no baseline at all) before
       writing anything. Only adds and modifies files — nothing is ever
-      deleted. Every overwritten file is backed up first, under
-      .contextzip/backups/<timestamp>/.
+      deleted.
     """
     project_dir = Path(os.getcwd()).resolve()
     project_cfg = load_project_config(project_dir)
@@ -857,9 +856,11 @@ def _auto_cleanup(project_dir: Path, project_cfg) -> None:
     to remember. Every zip is trivially reproducible by re-running
     contextzip, so this is deliberately brutal rather than cautious: it
     keeps only the `cleanup.keep_recent` most recent zip/manifest/report
-    set per mode folder, the most recent `cleanup.keep_recent` backup
-    folder(s), and the most recent `cleanup.keep_recent` archived
-    applied-zip(s) — everything else is deleted immediately, every run.
+    set per mode folder, the most recent `cleanup.keep_recent` archived
+    applied-zip(s), and the most recent `cleanup.keep_recent` loose
+    apply-report(s) in inbox/ — everything else is deleted immediately,
+    every run. Also wipes .contextzip/backups/ outright if a leftover one
+    still exists from an older contextzip version.
 
     Gated on `cleanup.enabled` (default True) — set to False in
     .contextzip/config.json to turn this off entirely.

{contextzip-0.4.3 → contextzip-0.4.4}/contextzip/cli_display.py

@@ -380,10 +380,8 @@ def print_apply_plan(
 
 
 def print_apply_result(result, *, con: Console = console) -> None:
-    """Two or three lines: what was written, backed up, and archived."""
+    """Two lines: what was written and archived."""
     ok(f"Applied {len(result.written)} files", con=con)
-    if result.backup_dir:
-        ok("Backed up to", str(result.backup_dir), con=con)
     ok("Archived zip to", str(result.applied_zip_path), con=con)
 
 

{contextzip-0.4.3 → contextzip-0.4.4}/contextzip/packager.py

@@ -663,6 +663,15 @@ def _workspace_output_path_silent(
     except OSError:
         return Path(tempfile.gettempdir()) / filename
 
+    # Lazy import: applier.py resolves the workspace dir via this module,
+    # so importing it at module load time would be circular.
+    from contextzip.applier import ensure_inbox_scaffolding
+
+    try:
+        ensure_inbox_scaffolding(workspace)
+    except OSError:
+        pass
+
     if is_git_repo:
         try:
             _ensure_workspace_gitignore(workspace)
@@ -704,6 +713,15 @@ def _workspace_output_path(
         )
         return Path(tempfile.gettempdir()) / filename
 
+    # Lazy import: applier.py resolves the workspace dir via this module,
+    # so importing it at module load time would be circular.
+    from contextzip.applier import ensure_inbox_scaffolding
+
+    try:
+        ensure_inbox_scaffolding(workspace)
+    except OSError:
+        pass
+
     # Handle .gitignore only when we're inside a git repo and the workspace
     # actually lives inside it (a custom absolute path outside the repo has
     # nothing for .gitignore to protect)

{contextzip-0.4.3 → contextzip-0.4.4}/contextzip/project_config.py

@@ -110,24 +110,25 @@ built-in default for the newer preference fields.
 
   cleanup
       Automatic housekeeping for `.contextzip/`, which otherwise only
-      grows over time (a zip+manifest+report set per run, a timestamped
-      folder under backups/ per risky apply-zip). See cleanup.py — after
-      every successful contextzip command, the workspace is pruned down
-      to only the most recent `keep_recent` item(s) per category, no
-      confirmation, no separate command needed. This is deliberately
-      brutal rather than cautious: every zip is trivially reproducible
-      by re-running contextzip, so there's little reason to let old ones
-      pile up.
+      grows over time (a zip+manifest+report set per run, archived zips
+      under inbox/applied/, loose apply-report.txt files in inbox/). See
+      cleanup.py — after every successful contextzip command, the
+      workspace is pruned down to only the most recent `keep_recent`
+      item(s) per category, no confirmation, no separate command needed.
+      This is deliberately brutal rather than cautious: every zip is
+      trivially reproducible by re-running contextzip, so there's little
+      reason to let old ones pile up.
         enabled       — if true (default), auto-cleanup runs after every
                         successful command. Set to false to keep
                         everything contextzip has ever generated.
         keep_recent   — how many most-recent item(s) are kept per
                         category before the rest are deleted: zip+manifest
                         +report sets per mode folder (output/codebase/,
-                        output/git-changes/, output/prompt/), timestamped
-                        folders under backups/, and archived zips under
-                        inbox/applied/. Default 1 — keep only the latest
-                        of each, delete everything older immediately.
+                        output/git-changes/, output/prompt/), archived
+                        zips under inbox/applied/, and loose
+                        apply-report.txt files in inbox/. Default 1 —
+                        keep only the latest of each, delete everything
+                        older immediately.
 
 The schema is intentionally a flat, easily-extended dict so future
 preferences can be added without another migration.

{contextzip-0.4.3 → contextzip-0.4.4}/contextzip/report.py

@@ -16,6 +16,7 @@ from pathlib import Path
 
 from contextzip.filters import summarise_exclusions
 from contextzip.cli_display import human_size
+from contextzip.applier import inbox_dir
 
 
 def report_path_for(zip_path: Path) -> Path:
@@ -140,8 +141,21 @@ def write_apply_report(
     result=None,
 ) -> Path | None:
     """
-    Write the full apply-zip report (every file + status) next to the
-    zip that was applied. Returns the report path, or None on failure.
+    Write the full apply-zip report (every file + status) into
+    .contextzip/inbox/ — always there, regardless of where the zip that
+    was applied actually lives. Returns the report path, or None on
+    failure.
+
+    `apply-zip <path>` accepts an explicit path anywhere on disk (not
+    just the inbox), and that path is meant to be left alone afterwards
+    rather than moved — see `archive_applied_zip`. The report used to
+    follow the same "leave it where the zip is" rule, which meant
+    pointing apply-zip at a zip sitting in the project root (or anywhere
+    else outside .contextzip/inbox/) dropped a stray
+    `<name>.apply-report.txt` right there, cluttering the repo as an
+    untracked file. The report itself doesn't need to travel with the
+    zip the way an archived copy would, so it always goes to the one
+    place these reports are expected to live.
     """
     lines: list[str] = []
     w = lines.append
@@ -161,11 +175,10 @@ def write_apply_report(
     if result is not None:
         w("Result")
         w(f"  written : {len(result.written)}")
-        w(f"  backup  : {result.backup_dir or 'none needed'}")
         w(f"  archived: {result.applied_zip_path}")
         w("")
 
-    report_path = plan.zip_path.with_name(plan.zip_path.stem + ".apply-report.txt")
+    report_path = inbox_dir(project_dir) / (plan.zip_path.stem + ".apply-report.txt")
     try:
         report_path.parent.mkdir(parents=True, exist_ok=True)
         report_path.write_text("\n".join(lines) + "\n", encoding="utf-8")

{contextzip-0.4.3 → contextzip-0.4.4}/contextzip.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.4.3
+Version: 0.4.4
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -87,7 +87,7 @@ Full function reference: [contextzip.vercel.app/cli#python-api](https://contextz
 - [Packaging & detection](https://contextzip.vercel.app/features) — frameworks, exclusion rules, safety
 - [AI-powered file selection](https://contextzip.vercel.app/ai-selection) — `--prompt`, Gemini setup
 - [Terminal error watcher](https://contextzip.vercel.app/watch) — `contextzip watch`
-- [Applying changes back](https://contextzip.vercel.app/apply-zip) — `apply-zip`, backups, safety
+- [Applying changes back](https://contextzip.vercel.app/apply-zip) — `apply-zip`, manifest diffing, safety
 - [Configuration](https://contextzip.vercel.app/configuration) — personal & project config, visual config UI
 - [CLI & Python API reference](https://contextzip.vercel.app/cli)
 

{contextzip-0.4.3 → contextzip-0.4.4}/pyproject.toml

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