contextzip 0.3.3__tar.gz → 0.3.5__tar.gz

{contextzip-0.3.3 → contextzip-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.3.3
+Version: 0.3.5
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -47,12 +47,13 @@ contextzip eliminates that entirely. Run it from your project root — it detect
 
 ## Features
 
-- **Smart framework detection** — automatically identifies Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby, applying the right exclusion rules for each
+- **Smart framework detection** — automatically identifies Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby, applying the right exclusion rules for each. Detection isn't limited to the project root: a shallow, bounded scan of subdirectories means a monorepo (`frontend/` + `backend/`, etc.) gets every ecosystem it contains detected and excluded correctly, not just whatever sits at the top level
 - **Respects `.gitignore`** — your existing ignore patterns are honoured automatically
 - **Git-aware packaging** — use `--git-changes` to package only modified, staged, and untracked files; perfect for incremental debugging and PR review sessions
 - **AI-powered file selection** — describe your task in plain English with `--prompt` and Gemini selects the minimum relevant files automatically, no manual hunting required
 - **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
-- **Persistent workspace** — all generated ZIPs land in `.contextzip/` at your project root, discoverable, reusable, and git-ignored automatically
+- **Configurable workspace location** — `.contextzip/` lives at the git root by default, but you can pin it elsewhere per-machine (`contextzip config --set-workspace`) or for the whole team via a committed `.contextzip.json`
+- **Persistent workspace** — all generated ZIPs land in `.contextzip/`, discoverable, reusable, and git-ignored automatically
 - **Warns before it's a problem** — flags large (≥ 1 MB) and binary files that AI tools can't read, before you waste an upload
 - **Handles edge cases** — dangling symlinks, unreadable files, and paths outside the project tree are caught and reported, never silently dropped
 - **Full CLI control** — `--include`, `--exclude`, `--dry-run`, `--output`, all composable
@@ -247,7 +248,7 @@ Press **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Y
 
 contextzip stacks exclusion rules based on your detected stack, on top of your `.gitignore`.
 
-**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), and common binary formats.
+**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), common binary formats, and contextzip's own `.contextzip/` working folder.
 
 **By framework:**
 
@@ -258,7 +259,38 @@ contextzip stacks exclusion rules based on your detected stack, on top of your `
 | Rust | `target/`, `Cargo.lock`, `*.rlib` |
 | Go | `vendor/`, `go.sum`, `bin/` |
 
-Detection is additive — a monorepo with both `package.json` and `pyproject.toml` gets both rule sets applied.
+Detection is additive — a monorepo with both `package.json` and `pyproject.toml` gets both rule sets applied. Marker files don't have to sit at the project root: contextzip also does a shallow, bounded scan of subdirectories (2 levels deep, skipping `node_modules/`, `.venv/`, `.git/`, and other dependency/build dirs it would never want to look inside anyway), so a layout like
+
+```
+root/
+  frontend/package.json
+  backend/requirements.txt
+```
+
+detects both Node.js and Python from `root/`, without either marker existing at the top level. Run with default output (not `--dry-run --verbose`) and you'll see which subdirectory each ecosystem came from, e.g. `Next.js (frontend/) + FastAPI (backend/)`.
+
+---
+
+## Workspace location
+
+By default, `.contextzip/` is created at your git root — that's `_find_git_root()` walking up from the current directory until it finds a `.git` folder; outside a repo, it falls back to the current directory. This can be overridden two ways, in order of priority:
+
+1. **`CONTEXTZIP_WORKSPACE_LOCATION` environment variable** — for a one-off override on a single run
+2. **A committed `.contextzip.json` at the project root** — team-shared, applies to everyone who clones the repo:
+   ```json
+   { "workspace_location": "git-root" }
+   ```
+3. **Your personal config** — a per-machine default that doesn't get committed:
+   ```bash
+   contextzip config --set-workspace cwd          # always use ./.contextzip wherever you run it
+   contextzip config --set-workspace git-root      # back to the default
+   contextzip config --set-workspace ~/zips        # a fixed custom location, anywhere
+   contextzip config --reset-workspace             # clear your personal override
+   ```
+
+Accepted values are `"git-root"`, `"cwd"`, or any path (absolute, or relative to the git root). Run `contextzip config` with no flags to see which value is currently active and where it came from.
+
+This matters most for monorepos where you sometimes run contextzip from a subdirectory (`cd frontend && contextzip`) — with the default `git-root` setting, the workspace still lands at the repo root no matter where you ran it from, so you don't end up with scattered `.contextzip/` folders across `frontend/`, `backend/`, etc. Set `workspace_location: "cwd"` in a project's `.contextzip.json` instead if you'd rather each subproject keep its own.
 
 ---
 

{contextzip-0.3.3 → contextzip-0.3.5}/README.md

@@ -18,12 +18,13 @@ contextzip eliminates that entirely. Run it from your project root — it detect
 
 ## Features
 
-- **Smart framework detection** — automatically identifies Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby, applying the right exclusion rules for each
+- **Smart framework detection** — automatically identifies Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby, applying the right exclusion rules for each. Detection isn't limited to the project root: a shallow, bounded scan of subdirectories means a monorepo (`frontend/` + `backend/`, etc.) gets every ecosystem it contains detected and excluded correctly, not just whatever sits at the top level
 - **Respects `.gitignore`** — your existing ignore patterns are honoured automatically
 - **Git-aware packaging** — use `--git-changes` to package only modified, staged, and untracked files; perfect for incremental debugging and PR review sessions
 - **AI-powered file selection** — describe your task in plain English with `--prompt` and Gemini selects the minimum relevant files automatically, no manual hunting required
 - **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
-- **Persistent workspace** — all generated ZIPs land in `.contextzip/` at your project root, discoverable, reusable, and git-ignored automatically
+- **Configurable workspace location** — `.contextzip/` lives at the git root by default, but you can pin it elsewhere per-machine (`contextzip config --set-workspace`) or for the whole team via a committed `.contextzip.json`
+- **Persistent workspace** — all generated ZIPs land in `.contextzip/`, discoverable, reusable, and git-ignored automatically
 - **Warns before it's a problem** — flags large (≥ 1 MB) and binary files that AI tools can't read, before you waste an upload
 - **Handles edge cases** — dangling symlinks, unreadable files, and paths outside the project tree are caught and reported, never silently dropped
 - **Full CLI control** — `--include`, `--exclude`, `--dry-run`, `--output`, all composable
@@ -218,7 +219,7 @@ Press **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Y
 
 contextzip stacks exclusion rules based on your detected stack, on top of your `.gitignore`.
 
-**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), and common binary formats.
+**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), common binary formats, and contextzip's own `.contextzip/` working folder.
 
 **By framework:**
 
@@ -229,7 +230,38 @@ contextzip stacks exclusion rules based on your detected stack, on top of your `
 | Rust | `target/`, `Cargo.lock`, `*.rlib` |
 | Go | `vendor/`, `go.sum`, `bin/` |
 
-Detection is additive — a monorepo with both `package.json` and `pyproject.toml` gets both rule sets applied.
+Detection is additive — a monorepo with both `package.json` and `pyproject.toml` gets both rule sets applied. Marker files don't have to sit at the project root: contextzip also does a shallow, bounded scan of subdirectories (2 levels deep, skipping `node_modules/`, `.venv/`, `.git/`, and other dependency/build dirs it would never want to look inside anyway), so a layout like
+
+```
+root/
+  frontend/package.json
+  backend/requirements.txt
+```
+
+detects both Node.js and Python from `root/`, without either marker existing at the top level. Run with default output (not `--dry-run --verbose`) and you'll see which subdirectory each ecosystem came from, e.g. `Next.js (frontend/) + FastAPI (backend/)`.
+
+---
+
+## Workspace location
+
+By default, `.contextzip/` is created at your git root — that's `_find_git_root()` walking up from the current directory until it finds a `.git` folder; outside a repo, it falls back to the current directory. This can be overridden two ways, in order of priority:
+
+1. **`CONTEXTZIP_WORKSPACE_LOCATION` environment variable** — for a one-off override on a single run
+2. **A committed `.contextzip.json` at the project root** — team-shared, applies to everyone who clones the repo:
+   ```json
+   { "workspace_location": "git-root" }
+   ```
+3. **Your personal config** — a per-machine default that doesn't get committed:
+   ```bash
+   contextzip config --set-workspace cwd          # always use ./.contextzip wherever you run it
+   contextzip config --set-workspace git-root      # back to the default
+   contextzip config --set-workspace ~/zips        # a fixed custom location, anywhere
+   contextzip config --reset-workspace             # clear your personal override
+   ```
+
+Accepted values are `"git-root"`, `"cwd"`, or any path (absolute, or relative to the git root). Run `contextzip config` with no flags to see which value is currently active and where it came from.
+
+This matters most for monorepos where you sometimes run contextzip from a subdirectory (`cd frontend && contextzip`) — with the default `git-root` setting, the workspace still lands at the repo root no matter where you ran it from, so you don't end up with scattered `.contextzip/` folders across `frontend/`, `backend/`, etc. Set `workspace_location: "cwd"` in a project's `.contextzip.json` instead if you'd rather each subproject keep its own.
 
 ---
 

{contextzip-0.3.3 → contextzip-0.3.5}/contextzip/__init__.py

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

{contextzip-0.3.3 → contextzip-0.3.5}/contextzip/cli.py

@@ -1,29 +1,5 @@
 """
 cli.py — contextzip entry point and command routing.
-
-Command surface
-───────────────
-  contextzip [OPTIONS]
-    -i / --include PATH      only include files under these paths (repeatable)
-    -e / --exclude PATTERN   extra exclusion patterns (repeatable)
-    -n / --dry-run           preview without creating ZIP
-    -o / --output FILE       custom output path
-    --no-clipboard           skip clipboard / folder-open step
-    --no-gitignore           ignore project .gitignore
-    --git-changes            only package files changed in git
-    -v / --verbose           show every file decision
-
-Subcommands:
-  contextzip exclude PATTERN… [OPTIONS]
-  contextzip include PATH…    [OPTIONS]
-  contextzip watch  -- COMMAND [ARGS]…
-  contextzip config [--reset-key] [--show-key-path]
-
-Business logic lives in the modules below — this file is routing only:
-  cli_display.py   — all Rich rendering (_print_* helpers)
-  cli_ai.py        — AI file selection orchestration + pattern normalisation
-  cli_onboard.py   — Gemini API key onboarding flow
-  watcher.py       — watch-mode process spawning and error detection
 """
 
 from __future__ import annotations
@@ -41,6 +17,8 @@ from contextzip.config import (
     delete_api_key,
     config_path,
     diagnose_api_key,
+    save_workspace_location,
+    delete_workspace_location,
 )
 from contextzip.detector import detect
 from contextzip.filters import build_spec, resolve_files, resolve_files_from_git
@@ -395,11 +373,6 @@ def cmd_watch(command: tuple[str, ...]) -> None:
     raise SystemExit(exit_code)
 
 
-# ---------------------------------------------------------------------------
-# Subcommand: config
-# ---------------------------------------------------------------------------
-
-
 @main.command("config")
 @click.option(
     "--reset-key",
@@ -407,25 +380,77 @@ def cmd_watch(command: tuple[str, ...]) -> None:
     default=False,
     help="Clear the stored Gemini API key and re-run the setup prompt.",
 )
+@click.option(
+    "--set-workspace",
+    default=None,
+    metavar="LOCATION",
+    help='Set your personal default for where .contextzip/ lives: "git-root", '
+    '"cwd", or a path.',
+)
+@click.option(
+    "--reset-workspace",
+    is_flag=True,
+    default=False,
+    help="Clear your personal workspace location override.",
+)
 @click.option(
     "--show-key-path",
     is_flag=True,
     default=False,
     help="Print the path to the config file and exit.",
 )
-def cmd_config(reset_key: bool, show_key_path: bool) -> None:
+def cmd_config(
+    reset_key: bool,
+    set_workspace: str | None,
+    reset_workspace: bool,
+    show_key_path: bool,
+) -> None:
     """
     Manage contextzip configuration.
 
     \b
     EXAMPLES
-      contextzip config --reset-key       # clear stored API key, re-onboard
-      contextzip config --show-key-path   # print config file location
+      contextzip config --reset-key                # clear Gemini key, re-onboard
+      contextzip config --set-workspace cwd         # always use ./.contextzip here
+      contextzip config --set-workspace git-root    # back to the default
+      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
+
+    \b
+    A workspace location can also be pinned for the whole team by committing
+    a .contextzip.json file at the project root:
+      {"workspace_location": "git-root"}
+    Project config (if present) takes priority over this personal setting —
+    see the README for the full precedence order.
     """
     if show_key_path:
         console.print(f"\n  [dim]Config file:[/] [cyan]{config_path()}[/]\n")
         return
 
+    if set_workspace is not None or reset_workspace:
+        if reset_workspace:
+            removed = delete_workspace_location()
+            if removed:
+                console.print(
+                    f"\n  [green]✓[/]  Workspace override removed from "
+                    f"[dim]{config_path()}[/]"
+                )
+            else:
+                console.print("\n  [dim]No personal workspace override was set.[/]")
+            if set_workspace is None:
+                return
+
+        if set_workspace is not None:
+            save_workspace_location(set_workspace)
+            console.print(
+                f"\n  [green]✓[/]  Personal workspace location set to "
+                f"[cyan]{set_workspace}[/] in [dim]{config_path()}[/]\n"
+                f"  [dim]A project-level .contextzip.json, if present, still "
+                f"takes priority over this.[/]"
+            )
+        return
+
     if reset_key:
         removed = delete_api_key()
         if removed:
@@ -475,10 +500,27 @@ def cmd_config(reset_key: bool, show_key_path: bool) -> None:
                 padding=(0, 2),
             )
         )
+
+    console.print()
+
+    from contextzip.packager import _resolve_workspace_location
+
+    ws_location, ws_source = _resolve_workspace_location(Path(os.getcwd()).resolve())
+    console.print(
+        Panel(
+            f"  [dim]Workspace location:[/]  [green]{ws_location}[/]  [dim]({ws_source})[/]\n\n"
+            "  [dim]Run [cyan]contextzip config --set-workspace <location>[/] to set "
+            "a personal default,\n"
+            "  or commit a [cyan].contextzip.json[/] at the project root to share "
+            "one with your team.[/]",
+            title="[bold]contextzip config[/]",
+            border_style="cyan",
+            padding=(0, 2),
+        )
+    )
     console.print()
 
 
-# ---------------------------------------------------------------------------
 # Core execution logic (shared by main command + all subcommands)
 # ---------------------------------------------------------------------------
 

{contextzip-0.3.3 → contextzip-0.3.5}/contextzip/cli_display.py

@@ -43,7 +43,14 @@ def print_detection(detection, *, con: Console = console) -> None:
             "Go": "cyan",
             "Ruby": "red",
         }
-        parts = [f"[{colours.get(n, 'white')}]{n}[/]" for n in detection.ecosystems]
+        parts = []
+        for n in detection.ecosystems:
+            colour = colours.get(n, "white")
+            src = detection.sources.get(n)
+            if src and src != ".":
+                parts.append(f"[{colour}]{n}[/] [dim]({src}/)[/]")
+            else:
+                parts.append(f"[{colour}]{n}[/]")
         ecosystem_line = " [dim]+[/] ".join(parts)
 
     conf_colour = {"high": "green", "medium": "yellow", "low": "dim"}.get(

{contextzip-0.3.3 → contextzip-0.3.5}/contextzip/clipboard.py

@@ -35,21 +35,16 @@ from pathlib import Path
 
 
 class Tier(Enum):
-    FILE_ON_CLIPBOARD = 1  # actual file object on clipboard — paste into browser
-    FOLDER_OPENED = 2  # folder opened / file highlighted in file manager
-    PATH_ONLY = 3  # nothing automatic; path printed for manual copy
+    FILE_ON_CLIPBOARD = 1
+    FOLDER_OPENED = 2
+    PATH_ONLY = 3
 
 
 @dataclass
 class ClipboardResult:
     tier: Tier
-    message: str  # human-readable outcome line
-    success: bool = True  # False only on unexpected errors worth surfacing
-
-
-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
+    message: str
+    success: bool = True
 
 
 def handle(zip_path: Path) -> ClipboardResult:
@@ -202,7 +197,7 @@ def _tier2_windows(zip_path: Path) -> ClipboardResult | None:
     try:
         # Use the Windows path format with backslashes
         win_path = str(zip_path).replace("/", "\\")
-        proc = subprocess.run(
+        subprocess.run(
             ["explorer", f"/select,{win_path}"],
             # explorer always exits 1 even on success — don't check returncode
             capture_output=True,
@@ -221,11 +216,6 @@ def _tier2_windows(zip_path: Path) -> ClipboardResult | None:
     return None
 
 
-# ---------------------------------------------------------------------------
-# Tier 3 — path only (always succeeds)
-# ---------------------------------------------------------------------------
-
-
 def _tier3(zip_path: Path) -> ClipboardResult:
     return ClipboardResult(
         tier=Tier.PATH_ONLY,

{contextzip-0.3.3 → contextzip-0.3.5}/contextzip/config.py

@@ -147,10 +147,60 @@ def config_path() -> Path:
 
 
 # ---------------------------------------------------------------------------
-# Internal helpers
+# Personal workspace location preference
+#
+# Where the .contextzip/ workspace (output zips + eod/handoff-era markers,
+# now just output zips) gets created, when nothing more specific overrides
+# it. This is a *personal*, per-machine preference — for a setting the whole
+# team should share, use the project-level config instead (project_config.py,
+# a .contextzip.json file meant to be committed to the repo).
+#
+# Resolution order (highest wins), enforced by packager.py, not here:
+#   CLI flag > CONTEXTZIP_WORKSPACE_LOCATION env var > project config
+#   > this personal config > built-in default ("git-root")
+#
+# Accepted values: "git-root", "cwd", or an explicit path (absolute, or
+# relative to the git root / project dir).
 # ---------------------------------------------------------------------------
 
 
+def get_workspace_location() -> str | None:
+    """Return the personally configured workspace location, or None if unset."""
+    try:
+        data = _read_config()
+        value = data.get("workspace_location", "").strip()
+        return value or None
+    except Exception:
+        return None
+
+
+def save_workspace_location(value: str) -> None:
+    """Persist *value* ("git-root" | "cwd" | a path) as the personal default."""
+    _CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    data = _read_config()
+    data["workspace_location"] = value.strip()
+    _CONFIG_FILE.write_text(
+        json.dumps(data, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+
+def delete_workspace_location() -> bool:
+    """Remove the personal workspace location override, reverting to default/project config."""
+    try:
+        data = _read_config()
+        if "workspace_location" not in data:
+            return False
+        del data["workspace_location"]
+        _CONFIG_FILE.write_text(
+            json.dumps(data, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        return True
+    except Exception:
+        return False
+
+
 def _read_config() -> dict:
     """Read and parse the config file. Returns {} if missing or malformed."""
     if not _CONFIG_FILE.is_file():

{contextzip-0.3.3 → contextzip-0.3.5}/contextzip/detector.py

@@ -3,6 +3,28 @@ detector.py — Analyses a project directory and identifies the ecosystem(s) pre
 
 Detection is additive: base rules always apply, and each detected framework
 stacks its own rules on top. A monorepo can match multiple ecosystems at once.
+
+Detection isn't limited to the project root. Marker files (package.json,
+requirements.txt, etc.) are looked for at the root AND in a shallow scan of
+subdirectories, so a layout like:
+
+    root/
+      frontend/package.json
+      backend/requirements.txt
+
+correctly detects BOTH Node.js and Python and stacks both rule sets — rather
+than finding nothing at root and only applying the universal base rules,
+which would leave node_modules/ and .venv/ unexcluded except by whatever
+.gitignore happens to catch.
+
+The scan is unconditional (not "only if root finds nothing") because a
+root-level marker (e.g. shared tooling's package.json) doesn't imply there's
+nothing else to find in sibling directories — it only tells you about root.
+
+The scan is bounded and cheap: max depth of 2, and it never descends into
+directories that are themselves dependency/build output (node_modules,
+.venv, .git, etc.) — the same names those directories' own rule modules
+would exclude from the zip, so we skip them before we even look inside.
 """
 
 from __future__ import annotations
@@ -25,6 +47,10 @@ class DetectionResult:
     ecosystems: list[str] = field(default_factory=list)  # e.g. ["Node.js", "Next.js"]
     rule_modules: list[str] = field(default_factory=list)  # e.g. ["base", "node"]
     confidence: str = "low"  # "low" | "medium" | "high"
+    # Maps ecosystem name -> relative dir it was found in ("." for root),
+    # e.g. {"Node.js": "frontend", "Python": "backend"}. Purely informational,
+    # shown in CLI output so a monorepo detection doesn't feel like magic.
+    sources: dict[str, str] = field(default_factory=dict)
 
     @property
     def display_name(self) -> str:
@@ -123,15 +149,91 @@ _RULES: list[_Rule] = [
 ]
 
 
+# ---------------------------------------------------------------------------
+# Subdirectory scan — bounded, cheap, skips dependency/build dirs
+# ---------------------------------------------------------------------------
+
+# Directories we never descend into while scanning for markers: they're
+# either dependency trees (huge, and full of nested package.json/pyproject
+# files that would produce false positives) or build/VCS output. This
+# mirrors the directory names the rule modules themselves exclude.
+_SKIP_DIR_NAMES = {
+    "node_modules",
+    ".git",
+    ".svn",
+    ".hg",
+    ".venv",
+    "venv",
+    "env",
+    "ENV",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".tox",
+    "vendor",
+    "target",
+    "dist",
+    "build",
+    "out",
+    ".next",
+    ".nuxt",
+    ".turbo",
+    ".vercel",
+    ".netlify",
+    "coverage",
+    ".nyc_output",
+    "site-packages",
+    ".idea",
+    ".vscode",
+    ".cache",
+    "tmp",
+    "temp",
+}
+
+_MAX_SCAN_DEPTH = 2
+
+
+def _scan_dirs(project_dir: Path, max_depth: int = _MAX_SCAN_DEPTH) -> list[Path]:
+    """
+    Return [project_dir] plus a bounded, shallow list of subdirectories worth
+    checking for ecosystem markers. Never descends into _SKIP_DIR_NAMES.
+    """
+    dirs = [project_dir]
+    if max_depth <= 0:
+        return dirs
+
+    frontier = [project_dir]
+    for _ in range(max_depth):
+        next_frontier: list[Path] = []
+        for d in frontier:
+            try:
+                children = [c for c in d.iterdir() if c.is_dir()]
+            except OSError:
+                continue
+            for child in children:
+                if child.name in _SKIP_DIR_NAMES or child.name.startswith("."):
+                    continue
+                dirs.append(child)
+                next_frontier.append(child)
+        frontier = next_frontier
+
+    return dirs
+
+
 # ---------------------------------------------------------------------------
 # Public API
 # ---------------------------------------------------------------------------
 
 
-def detect(project_dir: Path) -> DetectionResult:
+def detect(project_dir: Path, max_scan_depth: int = _MAX_SCAN_DEPTH) -> DetectionResult:
     """
     Analyse *project_dir* and return a :class:`DetectionResult`.
 
+    Checks project_dir itself plus a shallow, bounded scan of subdirectories
+    (see module docstring), so multi-framework monorepos are detected even
+    when no marker file sits at the root.
+
     Always includes "base" in rule_modules.
     """
     result = DetectionResult(rule_modules=["base"])
@@ -140,20 +242,28 @@ def detect(project_dir: Path) -> DetectionResult:
     seen_names: set[str] = set()
     total_weight = 0
 
-    for rule in _RULES:
-        try:
-            matched = rule.check(project_dir)
-        except Exception:
-            matched = False
+    for candidate_dir in _scan_dirs(project_dir, max_scan_depth):
+        for rule in _RULES:
+            if rule.name in seen_names:
+                continue  # already found this ecosystem elsewhere; don't re-check
+            try:
+                matched = rule.check(candidate_dir)
+            except Exception:
+                matched = False
 
-        if matched:
-            if rule.name not in seen_names:
+            if matched:
                 result.ecosystems.append(rule.name)
                 seen_names.add(rule.name)
-            if rule.module not in seen_modules:
-                result.rule_modules.append(rule.module)
-                seen_modules.add(rule.module)
-            total_weight += rule.weight
+                try:
+                    rel = candidate_dir.relative_to(project_dir)
+                    result.sources[rule.name] = str(rel) if str(rel) != "." else "."
+                except ValueError:
+                    result.sources[rule.name] = "."
+
+                if rule.module not in seen_modules:
+                    result.rule_modules.append(rule.module)
+                    seen_modules.add(rule.module)
+                total_weight += rule.weight
 
     # Confidence based on cumulative signal weight
     if total_weight >= 4:

{contextzip-0.3.3 → contextzip-0.3.5}/contextzip/git.py

@@ -57,19 +57,19 @@ class GitErrorKind(Enum):
 @dataclass
 class GitError:
     kind: GitErrorKind
-    message: str  # human-readable, ready to print
+    message: str
 
 
 @dataclass
 class GitChanges:
     """Successful result from :func:`get_changed_files`."""
 
-    files: list[Path] = field(default_factory=list)  # absolute paths
-    staged: list[str] = field(default_factory=list)  # rel paths (display)
-    unstaged: list[str] = field(default_factory=list)  # rel paths (display)
-    untracked: list[str] = field(default_factory=list)  # rel paths (display)
-    deleted: list[str] = field(default_factory=list)  # rel paths (skipped)
-    submodules: list[str] = field(default_factory=list)  # rel paths (skipped)
+    files: list[Path] = field(default_factory=list)
+    staged: list[str] = field(default_factory=list)
+    unstaged: list[str] = field(default_factory=list)
+    untracked: list[str] = field(default_factory=list)
+    deleted: list[str] = field(default_factory=list)
+    submodules: list[str] = field(default_factory=list)
 
     @property
     def is_empty(self) -> bool:
@@ -183,15 +183,15 @@ def _parse_porcelain(
         if not raw_line or len(raw_line) < 4:
             continue
 
-        xy = raw_line[:2]  # e.g. "M ", " M", "??", "A "
-        rel_path = raw_line[3:].strip()  # path relative to repo root
+        xy = raw_line[:2]
+        rel_path = raw_line[3:].strip()
 
         # Strip surrounding quotes git adds for paths with spaces/special chars
         if rel_path.startswith('"') and rel_path.endswith('"'):
             rel_path = rel_path[1:-1]
 
-        x = xy[0]  # staged status
-        y = xy[1]  # unstaged status
+        x = xy[0]
+        y = xy[1]
 
         # Skip ignored files
         if x == "!" and y == "!":

{contextzip-0.3.3 → contextzip-0.3.5}/contextzip/packager.py

@@ -265,13 +265,12 @@ def _find_git_root(start: Path) -> Path | None:
         current = parent
 
 
-def _ensure_gitignore(git_root: Path) -> None:
+def _ensure_gitignore(git_root: Path, entry: str = _GITIGNORE_ENTRY) -> None:
     """
-    Ensure .contextzip/ is listed in <git_root>/.gitignore.
+    Ensure *entry* is listed in <git_root>/.gitignore.
 
-    - If .gitignore exists and already contains the entry: do nothing.
-    - If .gitignore exists but lacks the entry: append it.
-    - If .gitignore does not exist: create it with just the entry.
+    Generalised beyond just .contextzip/ so other workspace-style folders
+    (e.g. exports/) can register themselves the same way.
     """
     gitignore_path = git_root / ".gitignore"
 
@@ -279,33 +278,93 @@ def _ensure_gitignore(git_root: Path) -> None:
         content = gitignore_path.read_text(encoding="utf-8", errors="replace")
         # Check for the entry on its own line (with or without trailing slash variants)
         lines = [line.strip() for line in content.splitlines()]
-        if _GITIGNORE_ENTRY in lines or _GITIGNORE_ENTRY.rstrip("/") in lines:
-            return  # Already present — nothing to do
-        # Append, ensuring there's a trailing newline before our entry
+        if entry in lines or entry.rstrip("/") in lines:
+            return
         separator = "\n" if content and not content.endswith("\n") else ""
         with gitignore_path.open("a", encoding="utf-8") as f:
-            f.write(f"{separator}\n# contextzip workspace\n{_GITIGNORE_ENTRY}\n")
+            f.write(f"{separator}\n# contextzip workspace\n{entry}\n")
     else:
         # .gitignore doesn't exist — create a minimal one
         gitignore_path.write_text(
-            f"# contextzip workspace\n{_GITIGNORE_ENTRY}\n",
+            f"# contextzip workspace\n{entry}\n",
             encoding="utf-8",
         )
 
 
+def _is_relative_to(path: Path, other: Path) -> bool:
+    """
+    True if *path* is inside *other*, after resolving both. Path.is_relative_to
+    exists from 3.9 onward (our floor), but resolving first avoids false
+    negatives from relative components or symlinks.
+    """
+    try:
+        path.resolve().relative_to(other.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def _resolve_workspace_location(project_dir: Path) -> tuple[str, str]:
+    """
+    Determine where the .contextzip/ workspace should live, and where that
+    decision came from (for diagnostics — see `contextzip config`).
+
+    Precedence, highest wins:
+      1. CONTEXTZIP_WORKSPACE_LOCATION env var
+      2. Project config (.contextzip.json at git root — team-shared, committed)
+      3. Personal config (~/.config/contextzip/config.json — per-machine)
+      4. Built-in default: "git-root"
+
+    Returns (location, source) where location is "git-root", "cwd", or an
+    explicit path string, and source is a human-readable label for where it
+    came from.
+    """
+    import os
+
+    env_val = os.environ.get("CONTEXTZIP_WORKSPACE_LOCATION", "").strip()
+    if env_val:
+        return env_val, "CONTEXTZIP_WORKSPACE_LOCATION env var"
+
+    from contextzip.project_config import load_project_config
+
+    project_cfg = load_project_config(project_dir)
+    if project_cfg.workspace_location:
+        return project_cfg.workspace_location, "project config (.contextzip.json)"
+
+    from contextzip.config import get_workspace_location
+
+    personal_val = get_workspace_location()
+    if personal_val:
+        return personal_val, "personal config"
+
+    return "git-root", "default"
+
+
 def _workspace_dir(project_dir: Path) -> tuple[Path, bool]:
     """
     Resolve the .contextzip/ workspace directory.
 
     Returns ``(workspace_path, is_git_repo)`` where:
-    - workspace_path is <git_root>/.contextzip/ when inside a git repo
-    - workspace_path is <project_dir>/.contextzip/ as a fallback
-    - is_git_repo indicates whether a git root was found
+    - workspace_path depends on the resolved workspace location (see
+      _resolve_workspace_location): under the git root by default, under
+      project_dir for "cwd", or an explicit path for anything else.
+    - is_git_repo indicates whether a git root was found (used to decide
+      whether .gitignore registration applies)
     """
     git_root = _find_git_root(project_dir)
-    if git_root is not None:
-        return git_root / ".contextzip", True
-    return project_dir / ".contextzip", False
+    location, _source = _resolve_workspace_location(project_dir)
+    anchor = git_root if git_root is not None else project_dir
+
+    if location == "git-root":
+        workspace = anchor / ".contextzip"
+    elif location == "cwd":
+        workspace = project_dir / ".contextzip"
+    else:
+        custom = Path(location).expanduser()
+        base = custom if custom.is_absolute() else (anchor / custom)
+        workspace = base / ".contextzip"
+
+    return workspace, git_root is not None
 
 
 def _workspace_output_path_silent(
@@ -327,11 +386,12 @@ def _workspace_output_path_silent(
         return Path(tempfile.gettempdir()) / filename
 
     if is_git_repo:
-        git_root = workspace.parent
-        try:
-            _ensure_gitignore(git_root)
-        except OSError:
-            pass
+        git_root = _find_git_root(project_dir)
+        if git_root is not None and _is_relative_to(workspace, git_root):
+            try:
+                _ensure_gitignore(git_root)
+            except OSError:
+                pass
 
     return workspace / filename
 
@@ -364,13 +424,16 @@ def _workspace_output_path(
         )
         return Path(tempfile.gettempdir()) / filename
 
-    # Handle .gitignore only when we're inside a git repo
+    # 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)
     if is_git_repo:
-        git_root = workspace.parent  # workspace is <git_root>/.contextzip
-        try:
-            _ensure_gitignore(git_root)
-        except OSError:
-            # Non-fatal: gitignore update failed, carry on silently
-            pass
+        git_root = _find_git_root(project_dir)
+        if git_root is not None and _is_relative_to(workspace, git_root):
+            try:
+                _ensure_gitignore(git_root)
+            except OSError:
+                # Non-fatal: gitignore update failed, carry on silently
+                pass
 
     return workspace / filename

contextzip-0.3.5/contextzip/project_config.py

@@ -0,0 +1,93 @@
+"""
+project_config.py — Project-level, team-shareable contextzip settings.
+
+Loaded from a `.contextzip.json` file at the project's git root (or the
+project directory itself outside a git repo) — the same location `.contextzip/`
+itself resolves to by default. Unlike config.py's personal, per-machine store
+(~/.config/contextzip/config.json, holds API keys, never committed), this file
+is meant to be committed to the repo so every contributor gets the same
+project defaults automatically — no per-machine setup required.
+
+Currently supports:
+
+    {
+      "workspace_location": "git-root" | "cwd" | "<path>",
+      "scan_depth": 2
+    }
+
+Both keys are optional. Missing or malformed values fall through to the next
+tier in the resolution order (see config.py's workspace_location docstring
+and packager.py's _resolve_workspace_location).
+
+Example — a monorepo that wants its workspace at the repo root explicitly
+(the default anyway, but pinned so it's obvious to contributors), committed
+alongside the code:
+
+    # .contextzip.json  (git-tracked)
+    { "workspace_location": "git-root" }
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+_PROJECT_CONFIG_FILENAME = ".contextzip.json"
+
+
+@dataclass
+class ProjectConfig:
+    workspace_location: str | None = None
+    scan_depth: int | None = None
+
+
+def project_config_path(project_dir: Path) -> Path:
+    """
+    Return where a project-level config file would live for *project_dir* —
+    the git root if inside a repo, otherwise project_dir itself. Does not
+    imply the file exists.
+    """
+    from contextzip.packager import _find_git_root
+
+    git_root = _find_git_root(project_dir)
+    base = git_root if git_root is not None else project_dir
+    return base / _PROJECT_CONFIG_FILENAME
+
+
+def load_project_config(project_dir: Path) -> ProjectConfig:
+    """
+    Load `.contextzip.json` for *project_dir*, if present.
+
+    Never raises — a missing, malformed, or unreadable file just yields an
+    empty ProjectConfig, so callers can fall through to the next tier
+    without special-casing errors.
+    """
+    path = project_config_path(project_dir)
+    if not path.is_file():
+        return ProjectConfig()
+
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return ProjectConfig()
+
+    if not isinstance(data, dict):
+        return ProjectConfig()
+
+    workspace_location = data.get("workspace_location")
+    if not isinstance(workspace_location, str) or not workspace_location.strip():
+        workspace_location = None
+
+    scan_depth = data.get("scan_depth")
+    if (
+        not isinstance(scan_depth, int)
+        or isinstance(scan_depth, bool)
+        or scan_depth < 0
+    ):
+        scan_depth = None
+
+    return ProjectConfig(
+        workspace_location=workspace_location,
+        scan_depth=scan_depth,
+    )

{contextzip-0.3.3 → contextzip-0.3.5}/contextzip/rules/base.py

@@ -56,7 +56,7 @@ PATTERNS = [
     "*.rar",
     # contextzip workspace directory — always excluded regardless of .gitignore state
     ".contextzip/",
-    # GitHub / repo governance (not useful as AI context)
+    "exports/",
     "CHANGELOG.md",
     "CHANGELOG",
     "CONTRIBUTING.md",

{contextzip-0.3.3 → contextzip-0.3.5}/contextzip.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.3.3
+Version: 0.3.5
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -47,12 +47,13 @@ contextzip eliminates that entirely. Run it from your project root — it detect
 
 ## Features
 
-- **Smart framework detection** — automatically identifies Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby, applying the right exclusion rules for each
+- **Smart framework detection** — automatically identifies Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby, applying the right exclusion rules for each. Detection isn't limited to the project root: a shallow, bounded scan of subdirectories means a monorepo (`frontend/` + `backend/`, etc.) gets every ecosystem it contains detected and excluded correctly, not just whatever sits at the top level
 - **Respects `.gitignore`** — your existing ignore patterns are honoured automatically
 - **Git-aware packaging** — use `--git-changes` to package only modified, staged, and untracked files; perfect for incremental debugging and PR review sessions
 - **AI-powered file selection** — describe your task in plain English with `--prompt` and Gemini selects the minimum relevant files automatically, no manual hunting required
 - **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
-- **Persistent workspace** — all generated ZIPs land in `.contextzip/` at your project root, discoverable, reusable, and git-ignored automatically
+- **Configurable workspace location** — `.contextzip/` lives at the git root by default, but you can pin it elsewhere per-machine (`contextzip config --set-workspace`) or for the whole team via a committed `.contextzip.json`
+- **Persistent workspace** — all generated ZIPs land in `.contextzip/`, discoverable, reusable, and git-ignored automatically
 - **Warns before it's a problem** — flags large (≥ 1 MB) and binary files that AI tools can't read, before you waste an upload
 - **Handles edge cases** — dangling symlinks, unreadable files, and paths outside the project tree are caught and reported, never silently dropped
 - **Full CLI control** — `--include`, `--exclude`, `--dry-run`, `--output`, all composable
@@ -247,7 +248,7 @@ Press **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Y
 
 contextzip stacks exclusion rules based on your detected stack, on top of your `.gitignore`.
 
-**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), and common binary formats.
+**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), common binary formats, and contextzip's own `.contextzip/` working folder.
 
 **By framework:**
 
@@ -258,7 +259,38 @@ contextzip stacks exclusion rules based on your detected stack, on top of your `
 | Rust | `target/`, `Cargo.lock`, `*.rlib` |
 | Go | `vendor/`, `go.sum`, `bin/` |
 
-Detection is additive — a monorepo with both `package.json` and `pyproject.toml` gets both rule sets applied.
+Detection is additive — a monorepo with both `package.json` and `pyproject.toml` gets both rule sets applied. Marker files don't have to sit at the project root: contextzip also does a shallow, bounded scan of subdirectories (2 levels deep, skipping `node_modules/`, `.venv/`, `.git/`, and other dependency/build dirs it would never want to look inside anyway), so a layout like
+
+```
+root/
+  frontend/package.json
+  backend/requirements.txt
+```
+
+detects both Node.js and Python from `root/`, without either marker existing at the top level. Run with default output (not `--dry-run --verbose`) and you'll see which subdirectory each ecosystem came from, e.g. `Next.js (frontend/) + FastAPI (backend/)`.
+
+---
+
+## Workspace location
+
+By default, `.contextzip/` is created at your git root — that's `_find_git_root()` walking up from the current directory until it finds a `.git` folder; outside a repo, it falls back to the current directory. This can be overridden two ways, in order of priority:
+
+1. **`CONTEXTZIP_WORKSPACE_LOCATION` environment variable** — for a one-off override on a single run
+2. **A committed `.contextzip.json` at the project root** — team-shared, applies to everyone who clones the repo:
+   ```json
+   { "workspace_location": "git-root" }
+   ```
+3. **Your personal config** — a per-machine default that doesn't get committed:
+   ```bash
+   contextzip config --set-workspace cwd          # always use ./.contextzip wherever you run it
+   contextzip config --set-workspace git-root      # back to the default
+   contextzip config --set-workspace ~/zips        # a fixed custom location, anywhere
+   contextzip config --reset-workspace             # clear your personal override
+   ```
+
+Accepted values are `"git-root"`, `"cwd"`, or any path (absolute, or relative to the git root). Run `contextzip config` with no flags to see which value is currently active and where it came from.
+
+This matters most for monorepos where you sometimes run contextzip from a subdirectory (`cd frontend && contextzip`) — with the default `git-root` setting, the workspace still lands at the repo root no matter where you ran it from, so you don't end up with scattered `.contextzip/` folders across `frontend/`, `backend/`, etc. Set `workspace_location: "cwd"` in a project's `.contextzip.json` instead if you'd rather each subproject keep its own.
 
 ---
 

{contextzip-0.3.3 → contextzip-0.3.5}/contextzip.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ contextzip/error_parser.py
 contextzip/filters.py
 contextzip/git.py
 contextzip/packager.py
+contextzip/project_config.py
 contextzip/watcher.py
 contextzip.egg-info/PKG-INFO
 contextzip.egg-info/SOURCES.txt

{contextzip-0.3.3 → contextzip-0.3.5}/pyproject.toml

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