contextzip 0.4.2__tar.gz → 0.4.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.4.2
+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.2 → 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.2 → contextzip-0.4.4}/contextzip/__init__.py

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

{contextzip-0.4.2 → 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.2 → 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,
@@ -446,10 +555,28 @@ def build_plan(
     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 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
+            # that name merely happens to exist on disk. That on-disk check
+            # used to gate this whole branch, which backfired on the most
+            # common real case: an AI tool wraps the whole project in a
+            # folder named after the project itself (e.g. "contextzip/"),
+            # and the project's own top-level package/dir happens to share
+            # that exact name — so the wrapper looked "legitimate" and was
+            # never stripped, dumping a nested copy of the project instead
+            # of updating the real files. Comparing manifest match-rates
+            # with vs without stripping gets both cases right: a genuine
+            # wrapper matches far better once stripped, while a zip whose
+            # top-level folder is an intentional part of the project (e.g.
+            # updates confined to an existing "docs/" folder) matches
+            # 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
@@ -462,16 +589,53 @@ def build_plan(
                     f"project manifest after stripping vs {unstripped_rate:.0%} "
                     "before."
                 )
-        else:
+            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), but say so plainly since it's not manifest-verified.
+            # 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. 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)
@@ -520,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,
@@ -552,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:
@@ -621,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
@@ -632,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
@@ -646,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.2 → 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.2 → contextzip-0.4.4}/contextzip/cli.py

@@ -74,6 +74,7 @@ from contextzip.cli_ai import (
 )
 from contextzip.cli_onboard import onboard_api_key
 from contextzip import cleanup as cleanup_mod
+from contextzip import updater as updater_mod
 
 console = Console()
 
@@ -381,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)
@@ -688,6 +688,90 @@ def cmd_config(
     console.print()
 
 
+# ---------------------------------------------------------------------------
+# Subcommand: update
+# ---------------------------------------------------------------------------
+
+
+@main.command("update")
+@click.option(
+    "--check",
+    "check_only",
+    is_flag=True,
+    default=False,
+    help="Only check for a newer version — don't install anything.",
+)
+@click.option(
+    "--yes",
+    "-y",
+    is_flag=True,
+    default=False,
+    help="Skip the confirmation prompt and update immediately if available.",
+)
+def cmd_update(check_only: bool, yes: bool) -> None:
+    """
+    Check PyPI for a newer contextzip release and update in place.
+
+    \b
+    EXAMPLES
+      contextzip update              # check, then confirm before updating
+      contextzip update --yes        # update immediately if one is available
+      contextzip update --check      # only report the current/latest version
+      cz update                      # same command, short alias
+
+    \b
+    HOW IT WORKS
+      contextzip cuts frequent releases, so this beats remembering
+      `pip install --upgrade contextzip` by hand. It detects whether this
+      install came from pip, pipx, or uv tool and re-invokes the matching
+      one, upgrading the same interpreter that's currently running —
+      never a possibly-different "pip" found on PATH.
+    """
+    console.print()
+    with console.status("[cyan]Checking for updates…[/]", spinner="dots"):
+        check = updater_mod.check_latest_version()
+
+    if check.latest is None:
+        err(f"Could not check for updates: {check.error}")
+        info(f"You're on {check.current}. Try again later, or update manually:")
+        info("  pip install --upgrade contextzip")
+        console.print()
+        raise SystemExit(1)
+
+    if not check.update_available:
+        ok(f"You're up to date — contextzip {check.current}")
+        console.print()
+        return
+
+    info(f"Update available: {check.current} → {check.latest}")
+
+    if check_only:
+        info("Run contextzip update to install it.")
+        console.print()
+        return
+
+    if not yes:
+        proceed = click.confirm(f"  Update to {check.latest} now?", default=True)
+        if not proceed:
+            info("Not updating.")
+            console.print()
+            return
+
+    with console.status(f"[cyan]Updating to {check.latest}…[/]", spinner="dots"):
+        result = updater_mod.run_update()
+
+    console.print()
+    if result.ok:
+        ok(f"Updated to contextzip {check.latest}", f"via {result.method}")
+        info("Restart any running contextzip/watch sessions to pick it up.")
+    else:
+        err(f"Update via {result.method} failed")
+        if result.output:
+            console.print(f"[dim]{result.output}[/]")
+        info("You can also update manually: pip install --upgrade contextzip")
+    console.print()
+
+
 # Core execution logic (shared by main command + all subcommands)
 # ---------------------------------------------------------------------------
 
@@ -772,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.2 → 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.2 → 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.2 → 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.2 → 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.4/contextzip/updater.py

@@ -0,0 +1,165 @@
+"""
+updater.py — Self-update support for `contextzip update` / `cz update`.
+
+contextzip cuts frequent releases, so re-running
+`pip install --upgrade contextzip` by hand every time gets old fast.
+This module:
+
+  1. Asks PyPI's JSON API for the latest published version.
+  2. Compares it against the version actually running (contextzip.__version__).
+  3. If newer, re-invokes pip (or pipx, if that's how contextzip was
+     installed) to upgrade in place.
+
+Never raises on network failure — a broken connection or PyPI hiccup
+should degrade to "couldn't check right now", not crash the CLI.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+
+from contextzip import __version__ as installed_version
+
+PYPI_URL = "https://pypi.org/pypi/contextzip/json"
+_TIMEOUT_SECS = 5
+
+
+# ---------------------------------------------------------------------------
+# Version comparison (no `packaging` dependency)
+# ---------------------------------------------------------------------------
+
+
+def _parse_version(v: str) -> tuple[int, ...]:
+    """
+    Turn "1.2.3" into (1, 2, 3) for comparison. Ignores any pre-release /
+    build suffix after the numeric core (e.g. "1.2.3rc1" -> (1, 2, 3)) —
+    good enough for "is there a newer release" without pulling in the
+    `packaging` library just for this.
+    """
+    core = v.strip().lstrip("v")
+    parts: list[int] = []
+    for chunk in core.split("."):
+        digits = ""
+        for ch in chunk:
+            if ch.isdigit():
+                digits += ch
+            else:
+                break
+        parts.append(int(digits) if digits else 0)
+    return tuple(parts) if parts else (0,)
+
+
+def is_newer(latest: str, current: str) -> bool:
+    """True if *latest* is a strictly newer version than *current*."""
+    a, b = _parse_version(latest), _parse_version(current)
+    length = max(len(a), len(b))
+    a = a + (0,) * (length - len(a))
+    b = b + (0,) * (length - len(b))
+    return a > b
+
+
+# ---------------------------------------------------------------------------
+# PyPI lookup
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class VersionCheck:
+    current: str
+    latest: str | None  # None if the lookup failed
+    error: str | None = None
+
+    @property
+    def update_available(self) -> bool:
+        return bool(self.latest) and is_newer(self.latest, self.current)
+
+
+def check_latest_version(timeout: float = _TIMEOUT_SECS) -> VersionCheck:
+    """
+    Query PyPI for the latest published contextzip version.
+
+    Uses httpx (already a hard dependency) but never lets a network
+    problem escape as an exception — callers always get a VersionCheck
+    back, with `.error` set on failure.
+    """
+    try:
+        import httpx
+
+        resp = httpx.get(PYPI_URL, timeout=timeout)
+        resp.raise_for_status()
+        data = resp.json()
+        latest = data.get("info", {}).get("version")
+        if not latest:
+            return VersionCheck(
+                current=installed_version, latest=None, error="Malformed PyPI response"
+            )
+        return VersionCheck(current=installed_version, latest=latest)
+    except Exception as exc:  # noqa: BLE001 — any network/parsing failure
+        return VersionCheck(
+            current=installed_version, latest=None, error=f"{type(exc).__name__}: {exc}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Install-method detection
+# ---------------------------------------------------------------------------
+
+
+def _installed_via_pipx() -> bool:
+    """
+    Best-effort guess at whether this contextzip was installed with pipx
+    rather than plain pip — pipx installs live under a `pipx/venvs/...`
+    path, which shows up in the interpreter's own executable path.
+    """
+    exe = sys.executable.replace("\\", "/").lower()
+    return "pipx" in exe
+
+
+def _installed_via_uv_tool() -> bool:
+    exe = sys.executable.replace("\\", "/").lower()
+    return "/uv/tools/" in exe or "\\uv\\tools\\" in sys.executable.lower()
+
+
+@dataclass
+class UpdateResult:
+    ok: bool
+    method: str
+    output: str
+
+
+def run_update(timeout: float = 120) -> UpdateResult:
+    """
+    Upgrade the installed contextzip package to the latest PyPI release.
+
+    Picks the tool that matches how contextzip was installed:
+      - pipx, if this interpreter lives inside a pipx venv and the pipx
+        executable is on PATH
+      - uv tool, if this interpreter lives inside a uv tool install
+      - otherwise `python -m pip install --upgrade contextzip`, using
+        the *currently running* interpreter's pip — never a bare "pip"
+        off PATH, which could silently target the wrong Python.
+    """
+    if _installed_via_pipx() and shutil.which("pipx"):
+        cmd = ["pipx", "upgrade", "contextzip"]
+        method = "pipx"
+    elif _installed_via_uv_tool() and shutil.which("uv"):
+        cmd = ["uv", "tool", "upgrade", "contextzip"]
+        method = "uv tool"
+    else:
+        cmd = [sys.executable, "-m", "pip", "install", "--upgrade", "contextzip"]
+        method = "pip"
+
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        output = (proc.stdout or "") + (proc.stderr or "")
+        return UpdateResult(ok=proc.returncode == 0, method=method, output=output.strip())
+    except Exception as exc:  # noqa: BLE001
+        return UpdateResult(ok=False, method=method, output=f"{type(exc).__name__}: {exc}")

{contextzip-0.4.2 → contextzip-0.4.4}/contextzip/webui/assets.py

@@ -1148,6 +1148,17 @@ INDEX_HTML = r"""<!DOCTYPE html>
       document.getElementById("overlay").classList.add("show");
       setTimeout(function () {
         api("/api/shutdown", { method: "GET" }).catch(function () {});
+        // Try to close the tab automatically and hop back to the terminal.
+        // Browsers only allow script-initiated close on windows/tabs that
+        // were opened by a script, or ones whose entire session history is
+        // just this one page — which this config-UI tab always is, since
+        // it's a single page with no navigation. If the browser still
+        // blocks it (some do, regardless), window.close() is a silent
+        // no-op and the overlay's "you can close this tab" text — already
+        // on screen — is the fallback the user follows manually.
+        setTimeout(function () {
+          try { window.close(); } catch (e) { /* ignored — fallback is the overlay text */ }
+        }, 300);
       }, 900);
     }).catch(function () {
       btn.disabled = false;

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.4.2
+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.2 → contextzip-0.4.4}/contextzip.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ contextzip/packager.py
 contextzip/project_config.py
 contextzip/redact.py
 contextzip/report.py
+contextzip/updater.py
 contextzip/watcher.py
 contextzip.egg-info/PKG-INFO
 contextzip.egg-info/SOURCES.txt

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

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