contextzip 0.3.6__tar.gz → 0.3.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.3.6
+Version: 0.3.7
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -53,6 +53,7 @@ contextzip eliminates that entirely. Run it from your project root — it detect
 - **AI-powered file selection** — describe your task in plain English with `--prompt` and Gemini selects the minimum relevant files automatically, no manual hunting required
 - **Terminal error watcher** — wrap any dev server with `contextzip watch` to auto-detect errors and package a ready-to-upload debug context in one keypress
 - **Configurable workspace location** — `.contextzip/` lives at the git root by default, but you can pin it elsewhere per-machine (`contextzip config --set-workspace`) or for the whole team via a committed `.contextzip/config.json`
+- **Visual config UI** — `contextzip config --ui` opens a local browser tab to set include/exclude by clicking through your actual file tree, with live counts and one-click suggestions for PDFs, media, and other non-code files — nothing leaves your machine
 - **Persistent workspace** — all generated ZIPs land in `.contextzip/output/`, discoverable, reusable, and git-ignored automatically
 - **Warns before it's a problem** — flags large (≥ 1 MB) and binary files that AI tools can't read, before you waste an upload
 - **Handles edge cases** — dangling symlinks, unreadable files, and paths outside the project tree are caught and reported, never silently dropped
@@ -342,7 +343,7 @@ All keys are optional — start with just the ones you need.
 
 `always_include`/`always_exclude` are additive on top of `--include`/`--exclude` for that run — an explicit `contextzip include PATH` still has the final say over what's actually packaged. Persistent preferences belong in `config.json` rather than an ever-growing list of CLI flags; CLI flags stay for one-off, explicit actions (`--dry-run`, `--prompt "…"`, `--output FILE`, etc.).
 
-A **web-based configuration UI** that generates `config.json` for you is on the roadmap — the schema above is designed to grow additively, so future preferences (including ones set visually) won't require another migration.
+You don't have to hand-write `config.json` — see [Visual config UI](#visual-config-ui) below for a point-and-click way to produce it.
 
 ### Deprecation: `.contextzip.json`
 
@@ -352,6 +353,37 @@ Earlier versions of contextzip read a `.contextzip.json` file at the project roo
 
 ---
 
+## Visual config UI
+
+```
+contextzip config --ui
+```
+
+Opens a local browser tab for setting `always_include`/`always_exclude` by clicking through your actual file tree instead of hand-writing patterns — live file counts and packed size update as you go, and one-click chips suggest excluding things like PDFs, office docs, fonts, media, or anything over 1MB that isn't already covered by contextzip's default rules.
+
+It's also offered automatically the **first time** you run `contextzip` in a project that has no config at all:
+
+```
+$ contextzip
+╭─────────────────────────╮
+│  contextzip v0.3.5      │
+╰─────────────────────────╯
+...
+╭─ First run ─────────────────────────────────────╮
+│  No project config found yet.                   │
+│  contextzip can open a local browser tab...      │
+╰───────────────────────────────────────────────────╯
+  Set up include/exclude visually now? [Y/n]:
+```
+
+Decline once and it won't ask again (run `contextzip config --ui` any time you want it). It's also skipped automatically for non-interactive runs, when `CI` is set, or when `--prompt`/`--output` are passed — it only ever offers on a plain, interactive, first-ever run.
+
+**Nothing about your project leaves your machine.** The server binds to `127.0.0.1` only (never `0.0.0.0`), every request needs a random per-session token embedded in the URL (the same approach Jupyter Notebook uses), and the page itself makes no calls anywhere except back to that local server — no CDN scripts, no web fonts, no analytics. Saving writes straight to `.contextzip/config.json` on disk and the server shuts itself down; if you close the tab without saving, it also shuts down after a short idle period so a forgotten session doesn't linger as an open port.
+
+If you accept the first-run offer, the same `contextzip` invocation picks up whatever you saved and finishes packaging immediately — no need to run it again.
+
+---
+
 ## Contributing
 
 Contributions are welcome — especially new framework rule sets, edge case fixes, and platform-specific clipboard improvements.

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

@@ -24,6 +24,7 @@ contextzip eliminates that entirely. Run it from your project root — it detect
 - **AI-powered file selection** — describe your task in plain English with `--prompt` and Gemini selects the minimum relevant files automatically, no manual hunting required
 - **Terminal error watcher** — wrap any dev server with `contextzip watch` to auto-detect errors and package a ready-to-upload debug context in one keypress
 - **Configurable workspace location** — `.contextzip/` lives at the git root by default, but you can pin it elsewhere per-machine (`contextzip config --set-workspace`) or for the whole team via a committed `.contextzip/config.json`
+- **Visual config UI** — `contextzip config --ui` opens a local browser tab to set include/exclude by clicking through your actual file tree, with live counts and one-click suggestions for PDFs, media, and other non-code files — nothing leaves your machine
 - **Persistent workspace** — all generated ZIPs land in `.contextzip/output/`, discoverable, reusable, and git-ignored automatically
 - **Warns before it's a problem** — flags large (≥ 1 MB) and binary files that AI tools can't read, before you waste an upload
 - **Handles edge cases** — dangling symlinks, unreadable files, and paths outside the project tree are caught and reported, never silently dropped
@@ -313,7 +314,7 @@ All keys are optional — start with just the ones you need.
 
 `always_include`/`always_exclude` are additive on top of `--include`/`--exclude` for that run — an explicit `contextzip include PATH` still has the final say over what's actually packaged. Persistent preferences belong in `config.json` rather than an ever-growing list of CLI flags; CLI flags stay for one-off, explicit actions (`--dry-run`, `--prompt "…"`, `--output FILE`, etc.).
 
-A **web-based configuration UI** that generates `config.json` for you is on the roadmap — the schema above is designed to grow additively, so future preferences (including ones set visually) won't require another migration.
+You don't have to hand-write `config.json` — see [Visual config UI](#visual-config-ui) below for a point-and-click way to produce it.
 
 ### Deprecation: `.contextzip.json`
 
@@ -323,6 +324,37 @@ Earlier versions of contextzip read a `.contextzip.json` file at the project roo
 
 ---
 
+## Visual config UI
+
+```
+contextzip config --ui
+```
+
+Opens a local browser tab for setting `always_include`/`always_exclude` by clicking through your actual file tree instead of hand-writing patterns — live file counts and packed size update as you go, and one-click chips suggest excluding things like PDFs, office docs, fonts, media, or anything over 1MB that isn't already covered by contextzip's default rules.
+
+It's also offered automatically the **first time** you run `contextzip` in a project that has no config at all:
+
+```
+$ contextzip
+╭─────────────────────────╮
+│  contextzip v0.3.5      │
+╰─────────────────────────╯
+...
+╭─ First run ─────────────────────────────────────╮
+│  No project config found yet.                   │
+│  contextzip can open a local browser tab...      │
+╰───────────────────────────────────────────────────╯
+  Set up include/exclude visually now? [Y/n]:
+```
+
+Decline once and it won't ask again (run `contextzip config --ui` any time you want it). It's also skipped automatically for non-interactive runs, when `CI` is set, or when `--prompt`/`--output` are passed — it only ever offers on a plain, interactive, first-ever run.
+
+**Nothing about your project leaves your machine.** The server binds to `127.0.0.1` only (never `0.0.0.0`), every request needs a random per-session token embedded in the URL (the same approach Jupyter Notebook uses), and the page itself makes no calls anywhere except back to that local server — no CDN scripts, no web fonts, no analytics. Saving writes straight to `.contextzip/config.json` on disk and the server shuts itself down; if you close the tab without saving, it also shuts down after a short idle period so a forgotten session doesn't linger as an open port.
+
+If you accept the first-run offer, the same `contextzip` invocation picks up whatever you saved and finishes packaging immediately — no need to run it again.
+
+---
+
 ## Contributing
 
 Contributions are welcome — especially new framework rule sets, edge case fixes, and platform-specific clipboard improvements.

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

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

{contextzip-0.3.6 → contextzip-0.3.7}/contextzip/cli.py

@@ -409,11 +409,20 @@ def cmd_watch(command: tuple[str, ...]) -> None:
     default=False,
     help="Print the path to the config file and exit.",
 )
+@click.option(
+    "--ui",
+    "launch_ui",
+    is_flag=True,
+    default=False,
+    help="Open a local browser UI to set include/exclude preferences visually "
+    "and write .contextzip/config.json.",
+)
 def cmd_config(
     reset_key: bool,
     set_workspace: str | None,
     reset_workspace: bool,
     show_key_path: bool,
+    launch_ui: bool,
 ) -> None:
     """
     Manage contextzip configuration.
@@ -426,6 +435,7 @@ def cmd_config(
       contextzip config --set-workspace ~/zips      # a fixed custom location
       contextzip config --reset-workspace           # clear the personal override
       contextzip config --show-key-path             # print config file location
+      contextzip config --ui                        # visually set include/exclude
 
     \b
     A workspace location can also be pinned for the whole team by committing
@@ -434,6 +444,16 @@ def cmd_config(
     Project config (if present) takes priority over this personal setting —
     see the README for the full precedence order.
     """
+    if launch_ui:
+        from contextzip.detector import detect as _detect
+        from contextzip.webui.server import launch_config_ui
+
+        project_dir = Path(os.getcwd()).resolve()
+        with console.status("[cyan]Detecting project ecosystem…[/]", spinner="dots"):
+            detection = _detect(project_dir)
+        launch_config_ui(project_dir, detection, con=console)
+        return
+
     if show_key_path:
         console.print(f"\n  [dim]Config file:[/] [cyan]{config_path()}[/]\n")
         return
@@ -528,7 +548,9 @@ def cmd_config(
             "  [dim]Run [cyan]contextzip config --set-workspace <location>[/] to set "
             "a personal default,\n"
             "  or commit a [cyan].contextzip/config.json[/] at the project root to "
-            "share one with your team.[/]",
+            "share one with your team.\n"
+            "  Run [cyan]contextzip config --ui[/] to set include/exclude "
+            "preferences visually.[/]",
             title="[bold]contextzip config[/]",
             border_style="cyan",
             padding=(0, 2),
@@ -605,6 +627,69 @@ def _enforce_ai_config(ai_cfg) -> None:
         raise SystemExit(1)
 
 
+def _maybe_offer_config_ui(
+    project_dir: Path,
+    detection,
+    *,
+    prompt: str | None,
+    output: str | None,
+) -> bool:
+    """
+    On a project's very first run — no .contextzip/config.json and no
+    legacy .contextzip.json at all — offer to open the local config UI
+    instead of silently proceeding with bare defaults.
+
+    Deliberately conservative about when to ask:
+      - never if --prompt or --output were given (the user is mid-task,
+        not exploring — don't interrupt with a browser tab)
+      - never outside an interactive terminal, or with CI set (scripted/
+        automated runs must never block on a prompt)
+      - never again once declined once (persisted personally, not per
+        project — see config.get_config_ui_dismissed)
+
+    Returns True if the user saved a config during the offered session
+    (the caller should reload project config before continuing).
+    """
+    import sys
+
+    if prompt or output:
+        return False
+    if not (sys.stdin.isatty() and sys.stdout.isatty()):
+        return False
+    if os.environ.get("CI"):
+        return False
+
+    from contextzip.config import get_config_ui_dismissed, save_config_ui_dismissed
+
+    if get_config_ui_dismissed():
+        return False
+
+    console.print(
+        Panel.fit(
+            "[bold]No project config found yet.[/]\n\n"
+            "[dim]contextzip can open a local browser tab where you pick "
+            "exactly what\nto include/exclude — with live file counts and "
+            "one-click suggestions\nfor things like PDFs or other non-code "
+            "files. Nothing leaves your machine.[/]",
+            title="[cyan]First run[/]",
+            border_style="cyan",
+            padding=(0, 2),
+        )
+    )
+    console.print()
+
+    if not click.confirm("  Set up include/exclude visually now?", default=True):
+        save_config_ui_dismissed()
+        console.print(
+            "  [dim]No problem — run [cyan]contextzip config --ui[/] anytime.[/]\n"
+        )
+        return False
+
+    from contextzip.webui.server import launch_config_ui
+
+    return launch_config_ui(project_dir, detection, con=console)
+
+
 def _run(
     *,
     extra_exclude: list[str] | None,
@@ -652,6 +737,15 @@ def _run(
 
     print_detection(detection)
 
+    # ── First-run offer: visual config UI ────────────────────────────────────
+    if project_cfg.source_path is None:
+        saved = _maybe_offer_config_ui(
+            project_dir, detection, prompt=prompt, output=output
+        )
+        if saved:
+            project_cfg = load_project_config(project_dir)
+            console.print()
+
     # ── Git-changes mode ─────────────────────────────────────────────────────
     if git_changes:
         with console.status("[cyan]Querying git for changed files…[/]", spinner="dots"):

{contextzip-0.3.6 → contextzip-0.3.7}/contextzip/config.py

@@ -201,6 +201,36 @@ def delete_workspace_location() -> bool:
         return False
 
 
+# ---------------------------------------------------------------------------
+# "Don't offer the local config UI again" preference
+#
+# Set the first time a user declines the first-run offer to launch
+# `contextzip config --ui` (see cli.py's _maybe_offer_config_ui), so the
+# prompt genuinely asks only once per machine rather than nagging on every
+# run of every config-less project. Running `contextzip config --ui`
+# explicitly is never affected by this — it's just the unsolicited offer.
+# ---------------------------------------------------------------------------
+
+
+def get_config_ui_dismissed() -> bool:
+    """True if the user has previously declined the first-run config UI offer."""
+    try:
+        return bool(_read_config().get("config_ui_prompt_dismissed", False))
+    except Exception:
+        return False
+
+
+def save_config_ui_dismissed() -> None:
+    """Record that the user declined the first-run config UI offer."""
+    _CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    data = _read_config()
+    data["config_ui_prompt_dismissed"] = True
+    _CONFIG_FILE.write_text(
+        json.dumps(data, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+
 def _read_config() -> dict:
     """Read and parse the config file. Returns {} if missing or malformed."""
     if not _CONFIG_FILE.is_file():

{contextzip-0.3.6 → contextzip-0.3.7}/contextzip/filters.py

@@ -26,6 +26,7 @@ Force-include (Phase 7):
 from __future__ import annotations
 
 import importlib
+import os
 from pathlib import Path
 from dataclasses import dataclass, field
 
@@ -51,6 +52,40 @@ LARGE_FILE_WARN_BYTES = 1 * 1024 * 1024  # 1 MB
 # Peek this many bytes to detect binary files
 _BINARY_PEEK = 512
 
+# Directory names scan_all_files() prunes during the walk itself, before
+# even reading their contents. These are always dependency/build/VCS
+# noise that no ecosystem's rule module would ever include, and — for
+# .venv/venv especially — often contain symlinks to files well outside
+# the project tree (e.g. bin/python -> the system interpreter), which is
+# exactly the kind of thing that must never reach classify_scanned_files.
+# Kept intentionally small and generic (not ecosystem-specific — that's
+# what rules/*.py is for) since this list affects every project's scan.
+_ALWAYS_PRUNED_DIRNAMES = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        "node_modules",
+        ".venv",
+        "venv",
+        "env",
+        "__pycache__",
+        ".tox",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        "dist",
+        "build",
+        ".next",
+        ".nuxt",
+        ".cache",
+        "target",
+        "vendor",
+        "site-packages",
+        ".contextzip",
+    }
+)
+
 
 # ---------------------------------------------------------------------------
 # Result model
@@ -99,7 +134,9 @@ def build_spec(
                 encoding="utf-8", errors="ignore"
             ).splitlines()
             # Strip comments and blank lines; pathspec handles the rest
-            patterns.extend(l for l in lines if l.strip() and not l.startswith("#"))
+            patterns.extend(
+                line for line in lines if line.strip() and not line.startswith("#")
+            )
         except OSError:
             pass
 
@@ -122,6 +159,111 @@ def build_force_include_spec(patterns: list[str] | None) -> pathspec.PathSpec |
     return pathspec.PathSpec.from_lines("gitwildmatch", patterns)
 
 
+def scan_all_files(project_dir: Path) -> list[tuple[Path, int]]:
+    """
+    Lightweight full-tree walk that returns every regular file under
+    *project_dir* once, as (abs_path, size_bytes) tuples, without
+    classifying anything.
+
+    Meant for tools that need to classify the same file list against
+    several different specs without re-touching the filesystem each time
+    (the local config UI — see webui/server.py — scans once at startup,
+    then reclassifies purely in memory on every checkbox toggle). Pair
+    with classify_scanned_files().
+
+    Two things this does that a plain rglob() wouldn't:
+
+    - Prunes a fixed list of known-huge, always-irrelevant directories
+      (.venv, node_modules, .git, __pycache__, build output, etc.) during
+      the walk itself, not just at classification time. These can easily
+      be tens of thousands of files (a .venv's site-packages, in
+      particular) that would never end up in a ZIP anyway — walking into
+      them at all makes the scan needlessly slow and floods the UI's tree
+      with noise nobody wants to look at.
+    - Rejects symlinks whose real target resolves outside project_dir.
+      A virtualenv's bin/python is a classic example (symlinks to the
+      system interpreter) — without this check, relative_to() calls
+      downstream (see webui/server.py's _rel()) raise ValueError and
+      crash the request entirely.
+
+    Deliberately simpler than resolve_files()'s walk (no skipped/binary
+    bookkeeping) since callers here only need "does this file exist, and
+    how big is it" — resolve_files() remains the source of truth for an
+    actual packaging run, and still sees everything within the pruned
+    dirs is excluded via the normal rules (rules/base.py etc.) whether or
+    not the config UI ever looked at them.
+    """
+    files: list[tuple[Path, int]] = []
+
+    for dirpath, dirnames, filenames in os.walk(project_dir, topdown=True):
+        dirnames[:] = [d for d in dirnames if d not in _ALWAYS_PRUNED_DIRNAMES]
+
+        for filename in filenames:
+            abs_path = Path(dirpath) / filename
+
+            if abs_path.is_symlink():
+                try:
+                    real = abs_path.resolve(strict=True)
+                except (OSError, RuntimeError):
+                    continue  # dangling symlink — skip silently, this is best-effort
+                try:
+                    real.relative_to(project_dir)
+                except ValueError:
+                    continue  # resolves outside the project tree — never include
+                if not real.is_file():
+                    continue
+                abs_path = real
+            elif not abs_path.is_file():
+                continue
+
+            try:
+                size = abs_path.stat().st_size
+            except OSError:
+                continue
+
+            files.append((abs_path, size))
+
+    return files
+
+
+def classify_scanned_files(
+    project_dir: Path,
+    files: list[tuple[Path, int]],
+    spec: pathspec.PathSpec,
+    force_include: pathspec.PathSpec | None = None,
+) -> dict[Path, bool]:
+    """
+    Classify each (abs_path, size) from scan_all_files() against *spec*
+    (and optional *force_include*) without touching the filesystem again.
+
+    Mirrors resolve_files()'s force_include-then-spec precedence exactly,
+    reusing the same matching primitives, but works off an already-scanned
+    file list. Returns {abs_path: is_included}.
+    """
+    result: dict[Path, bool] = {}
+    for abs_path, _size in files:
+        try:
+            rel = abs_path.relative_to(project_dir)
+        except ValueError:
+            continue
+
+        rel_str = rel.as_posix()
+
+        forced = force_include is not None and (
+            force_include.match_file(rel_str)
+            or _any_parent_excluded(rel, force_include)
+        )
+
+        if forced:
+            result[abs_path] = True
+            continue
+
+        excluded = _any_parent_excluded(rel, spec) or spec.match_file(rel_str)
+        result[abs_path] = not excluded
+
+    return result
+
+
 def resolve_files(
     project_dir: Path,
     spec: pathspec.PathSpec,
@@ -176,7 +318,8 @@ def resolve_files(
 
         # ── force_include short-circuits the exclusion checks below ─────────
         forced = force_include is not None and (
-            force_include.match_file(rel_str) or _any_parent_excluded(rel, force_include)
+            force_include.match_file(rel_str)
+            or _any_parent_excluded(rel, force_include)
         )
 
         if not forced:

contextzip-0.3.7/contextzip/webui/__init__.py

@@ -0,0 +1,9 @@
+"""
+webui — Local-only browser UI for setting up .contextzip/config.json.
+
+Entry point: `launch_config_ui()` in server.py, invoked by
+`contextzip config --ui` and offered automatically on a project's first
+run (see cli.py's _maybe_offer_config_ui). Everything here runs a plain
+stdlib HTTP server bound to 127.0.0.1 — no new dependency, and no data
+about the project ever leaves the machine.
+"""