contextzip 0.3.0__tar.gz → 0.3.2__tar.gz

{contextzip-0.3.0 → contextzip-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.3.0
+Version: 0.3.2
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -51,6 +51,7 @@ contextzip eliminates that entirely. Run it from your project root — it detect
 - **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
 - **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
@@ -116,7 +117,7 @@ contextzip [OPTIONS]
 | `--no-clipboard` | Skip the clipboard / folder-open step |
 | `--no-gitignore` | Ignore the project's `.gitignore` |
 
-**Subcommands:** `exclude`, `include`, `config` — run `contextzip --help` for full details.
+**Subcommands:** `exclude`, `include`, `watch`, `config` — run `contextzip --help` for full details.
 
 ---
 
@@ -173,6 +174,41 @@ contextzip config --reset-key   # clear and re-run setup
 
 ---
 
+## Terminal error watcher
+
+The `watch` command wraps your dev server, buffers its output, and packages a debug-ready ZIP the moment you spot an error — no manual file hunting, no copy-pasting stack traces.
+
+```bash
+contextzip watch -- npm run dev
+contextzip watch -- python manage.py runserver
+```
+
+contextzip starts your process normally. You see output exactly as you would without it. In the background, it watches the stream for errors. When one is detected, a prompt appears directly beneath the error output:
+
+```
+╭─ contextzip · error detected ─────────────────────╮
+│  Press [D] to package debug context  [S] to skip  │
+╰───────────────────────────────────────────────────╯
+```
+
+Press **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Your server keeps running — no restart, no interruption.
+
+**What's in the ZIP:**
+
+| File | Contents |
+|---|---|
+| `prompt.txt` | Auto-generated: detected framework, error type, and task description — ready to paste into any AI tool |
+| `terminal-error.txt` | The cleaned, noise-stripped error block and stack trace |
+| `source-files.zip` | Source files referenced in the stack trace, paths preserved |
+
+**On Ctrl+C:** If no errors were packaged during the session, contextzip offers one final prompt to capture the full session output — useful when something looked wrong but didn't match a known error pattern.
+
+**Supported frameworks:** Python, Django, FastAPI, Node.js, Next.js, React. Each has its own error detection patterns and noise filters so the output stays clean across stacks.
+
+> **Note:** `watch` works best with dev servers that don't read stdin interactively (`npm run dev`, `manage.py runserver`, etc.). PTY emulation is not used — on Windows, color passthrough may be limited.
+
+---
+
 ## What gets excluded
 
 contextzip stacks exclusion rules based on your detected stack, on top of your `.gitignore`.

{contextzip-0.3.0 → contextzip-0.3.2}/README.md

@@ -22,6 +22,7 @@ contextzip eliminates that entirely. Run it from your project root — it detect
 - **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
 - **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
@@ -87,7 +88,7 @@ contextzip [OPTIONS]
 | `--no-clipboard` | Skip the clipboard / folder-open step |
 | `--no-gitignore` | Ignore the project's `.gitignore` |
 
-**Subcommands:** `exclude`, `include`, `config` — run `contextzip --help` for full details.
+**Subcommands:** `exclude`, `include`, `watch`, `config` — run `contextzip --help` for full details.
 
 ---
 
@@ -144,6 +145,41 @@ contextzip config --reset-key   # clear and re-run setup
 
 ---
 
+## Terminal error watcher
+
+The `watch` command wraps your dev server, buffers its output, and packages a debug-ready ZIP the moment you spot an error — no manual file hunting, no copy-pasting stack traces.
+
+```bash
+contextzip watch -- npm run dev
+contextzip watch -- python manage.py runserver
+```
+
+contextzip starts your process normally. You see output exactly as you would without it. In the background, it watches the stream for errors. When one is detected, a prompt appears directly beneath the error output:
+
+```
+╭─ contextzip · error detected ─────────────────────╮
+│  Press [D] to package debug context  [S] to skip  │
+╰───────────────────────────────────────────────────╯
+```
+
+Press **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Your server keeps running — no restart, no interruption.
+
+**What's in the ZIP:**
+
+| File | Contents |
+|---|---|
+| `prompt.txt` | Auto-generated: detected framework, error type, and task description — ready to paste into any AI tool |
+| `terminal-error.txt` | The cleaned, noise-stripped error block and stack trace |
+| `source-files.zip` | Source files referenced in the stack trace, paths preserved |
+
+**On Ctrl+C:** If no errors were packaged during the session, contextzip offers one final prompt to capture the full session output — useful when something looked wrong but didn't match a known error pattern.
+
+**Supported frameworks:** Python, Django, FastAPI, Node.js, Next.js, React. Each has its own error detection patterns and noise filters so the output stays clean across stacks.
+
+> **Note:** `watch` works best with dev servers that don't read stdin interactively (`npm run dev`, `manage.py runserver`, etc.). PTY emulation is not used — on Windows, color passthrough may be limited.
+
+---
+
 ## What gets excluded
 
 contextzip stacks exclusion rules based on your detected stack, on top of your `.gitignore`.

contextzip-0.3.2/contextzip/__init__.py

@@ -0,0 +1,34 @@
+"""contextzip — intelligent codebase packager for AI tools."""
+
+__version__ = "0.3.2"
+
+from contextzip.api import (
+    FileCollection,
+    ContextzipError,
+    NotARepositoryError,
+    GitNotFoundError,
+    GitCommandError,
+    NoFilesError,
+    get_git_changes,
+    get_files,
+    create_zip,
+    detect_ecosystem,
+)
+from contextzip.packager import PackageResult
+
+__all__ = [
+    # Functions
+    "get_git_changes",
+    "get_files",
+    "create_zip",
+    "detect_ecosystem",
+    # Data types
+    "FileCollection",
+    "PackageResult",
+    # Exceptions
+    "ContextzipError",
+    "NotARepositoryError",
+    "GitNotFoundError",
+    "GitCommandError",
+    "NoFilesError",
+]

contextzip-0.3.2/contextzip/api.py

@@ -0,0 +1,400 @@
+"""
+api.py — Public Python API for contextzip.
+
+Exposes the same capabilities as the CLI but as plain Python functions:
+no Click, no Rich output, no SystemExit. All functions raise exceptions
+on failure so callers can handle errors in their own way.
+
+Quickstart
+──────────
+    from contextzip import get_git_changes, get_files, create_zip
+
+    # Get git-changed files and use them directly (no zip needed)
+    collection = get_git_changes()
+    for path in collection.files:
+        upload(path)                    # plain pathlib.Path objects
+
+    # Or zip them
+    pkg = create_zip(collection, output="/tmp/changes.zip")
+    with open(pkg.zip_path, "rb") as f:
+        upload_to_s3(f)
+
+    # Get all project files (respecting .gitignore and built-in rules)
+    collection = get_files()
+    for path in collection.files:
+        print(path)
+
+    # Narrow it down
+    collection = get_files(
+        include=["src/", "app/"],
+        exclude=["tests/", "*.log"],
+    )
+    pkg = create_zip(collection, output="/tmp/upload.zip")
+    print(f"Packed {pkg.file_count} files → {pkg.zip_path}")
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from contextzip.detector import DetectionResult, detect
+from contextzip.filters import (
+    ResolveResult,
+    build_spec,
+    resolve_files,
+    resolve_files_from_git,
+)
+from contextzip.git import GitChanges, GitError, GitErrorKind, get_changed_files
+from contextzip.packager import PackageResult, create_zip_silent
+
+
+# ---------------------------------------------------------------------------
+# Public result type
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class FileCollection:
+    """
+    A resolved set of files returned by :func:`get_git_changes` or
+    :func:`get_files`.
+
+    ``files`` is always a plain list of absolute :class:`pathlib.Path` objects
+    — use them directly for uploads, processing, or anything else.
+    Zipping is optional: pass this object to :func:`create_zip` if needed.
+
+    Attributes
+    ----------
+    files:
+        Absolute paths of all files in this collection. These are the
+        files that would be (or were) included in a ZIP.
+    skipped:
+        Files that were silently skipped during resolution, as
+        ``(path, reason)`` tuples (e.g. dangling symlinks, unreadable files).
+    large_files:
+        Files exceeding 1 MB, as ``(path, size_in_bytes)`` tuples.
+        They are still included in ``files`` — this is informational only.
+    binary_files:
+        Files that appear to be binary (contain null bytes). Still included
+        in ``files`` — informational only.
+    project_dir:
+        The project root used when resolving paths.
+    ecosystem:
+        Detected ecosystem string, e.g. ``"Next.js + Node.js"``.
+    """
+
+    files: list[Path] = field(default_factory=list)
+    skipped: list[tuple[Path, str]] = field(default_factory=list)
+    large_files: list[tuple[Path, int]] = field(default_factory=list)
+    binary_files: list[Path] = field(default_factory=list)
+    project_dir: Path = field(default_factory=Path.cwd)
+    ecosystem: str = "Unknown"
+
+    def __len__(self) -> int:
+        return len(self.files)
+
+    def __iter__(self):
+        return iter(self.files)
+
+    def __bool__(self) -> bool:
+        return bool(self.files)
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class ContextzipError(Exception):
+    """Base class for all contextzip API errors."""
+
+
+class NotARepositoryError(ContextzipError):
+    """Raised when the project directory is not inside a git repository."""
+
+
+class GitNotFoundError(ContextzipError):
+    """Raised when git is not installed or not on PATH."""
+
+
+class GitCommandError(ContextzipError):
+    """Raised when a git command fails unexpectedly."""
+
+
+class NoFilesError(ContextzipError):
+    """Raised when file resolution produces an empty result."""
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def get_git_changes(
+    path: str | Path | None = None,
+) -> FileCollection:
+    """
+    Return the files that git reports as modified, added, or untracked.
+
+    The git root is found automatically by walking up from *path* (or the
+    current working directory). Files are filtered through contextzip's base
+    safety rules so secrets, binaries, and similar files are always excluded.
+
+    Parameters
+    ----------
+    path:
+        Directory to start from. Defaults to ``Path.cwd()``. The actual
+        git root may be a parent of this directory.
+
+    Returns
+    -------
+    FileCollection
+        ``collection.files`` contains absolute :class:`~pathlib.Path` objects
+        for every changed file. Iterate over it or pass it to
+        :func:`create_zip`.
+
+    Raises
+    ------
+    GitNotFoundError
+        If git is not installed or not on PATH.
+    NotARepositoryError
+        If *path* is not inside a git repository.
+    GitCommandError
+        If ``git status`` fails for any other reason.
+
+    Example
+    -------
+    ::
+
+        from contextzip import get_git_changes
+
+        collection = get_git_changes()
+        for f in collection.files:
+            print(f)          # plain pathlib.Path — use however you like
+
+        # Only staged files
+        for rel in collection._git_changes.staged:
+            print(rel)
+    """
+    project_dir = _resolve_dir(path)
+    git_result = get_changed_files(project_dir)
+
+    if isinstance(git_result, GitError):
+        _raise_git_error(git_result)
+
+    if git_result.is_empty:
+        return FileCollection(project_dir=project_dir)
+
+    resolved = resolve_files_from_git(
+        git_files=git_result.files,
+        project_dir=project_dir,
+    )
+
+    detection = detect(project_dir)
+
+    collection = _resolve_result_to_collection(resolved, project_dir, detection)
+    # Stash the raw GitChanges on the collection for callers who want
+    # staged/unstaged/untracked breakdowns without accessing internals
+    collection._git_changes = git_result  # type: ignore[attr-defined]
+    return collection
+
+
+def get_files(
+    path: str | Path | None = None,
+    *,
+    include: list[str] | None = None,
+    exclude: list[str] | None = None,
+    use_gitignore: bool = True,
+) -> FileCollection:
+    """
+    Return all project files after applying contextzip's standard exclusion rules.
+
+    Parameters
+    ----------
+    path:
+        Project root to scan. Defaults to ``Path.cwd()``.
+    include:
+        If given, only files under these paths are returned (e.g.
+        ``["src/", "app/"]``). Matched as exact path prefixes.
+    exclude:
+        Extra exclusion patterns on top of the auto-detected rules
+        (gitignore syntax, e.g. ``["tests/", "*.log"]``).
+    use_gitignore:
+        Whether to apply the project's ``.gitignore`` file.
+        Defaults to ``True``.
+
+    Returns
+    -------
+    FileCollection
+        ``collection.files`` contains absolute :class:`~pathlib.Path` objects
+        for every included file.
+
+    Example
+    -------
+    ::
+
+        from contextzip import get_files
+
+        # All project files
+        collection = get_files()
+
+        # Only src/, excluding tests
+        collection = get_files(include=["src/"], exclude=["tests/"])
+
+        for f in collection.files:
+            process(f)
+    """
+    project_dir = _resolve_dir(path)
+    detection = detect(project_dir)
+
+    gitignore_path = (project_dir / ".gitignore") if use_gitignore else None
+
+    spec = build_spec(
+        rule_modules=detection.rule_modules,
+        extra_exclude=exclude or None,
+        gitignore_path=gitignore_path,
+    )
+
+    resolved = resolve_files(
+        project_dir=project_dir,
+        spec=spec,
+        include_only=include or None,
+    )
+
+    return _resolve_result_to_collection(resolved, project_dir, detection)
+
+
+def create_zip(
+    collection: FileCollection,
+    output: str | Path | None = None,
+) -> PackageResult:
+    """
+    Write *collection* into a ZIP archive and return the result.
+
+    Parameters
+    ----------
+    collection:
+        A :class:`FileCollection` returned by :func:`get_git_changes` or
+        :func:`get_files`.
+    output:
+        Where to write the ZIP. If omitted, the archive is written to the
+        ``.contextzip/`` workspace at the project root (same as the CLI).
+        Pass an explicit path to control where it lands — useful when you
+        want to write to a temp directory before uploading.
+
+    Returns
+    -------
+    PackageResult
+        Contains ``zip_path`` (a :class:`~pathlib.Path`), ``file_count``,
+        ``compressed_bytes``, ``uncompressed_bytes``, and ``skipped_in_zip``.
+
+    Raises
+    ------
+    NoFilesError
+        If *collection* is empty (nothing to zip).
+    OSError
+        If the ZIP file cannot be written.
+
+    Example
+    -------
+    ::
+
+        import tempfile
+        from contextzip import get_git_changes, create_zip
+
+        collection = get_git_changes()
+        with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as tmp:
+            pkg = create_zip(collection, output=tmp.name)
+
+        with open(pkg.zip_path, "rb") as f:
+            upload_to_s3(f.read())
+
+        print(f"Packed {pkg.file_count} files, {pkg.compressed_bytes} bytes compressed")
+    """
+    if not collection.files:
+        raise NoFilesError(
+            "The FileCollection is empty — nothing to zip. "
+            "Check get_git_changes() or get_files() returned files."
+        )
+
+    resolve_result = ResolveResult(
+        included=collection.files,
+        skipped=collection.skipped,
+        large_files=collection.large_files,
+        binary_files=collection.binary_files,
+    )
+
+    output_path = Path(output).resolve() if output is not None else None
+
+    return create_zip_silent(
+        resolve_result=resolve_result,
+        project_dir=collection.project_dir,
+        output_path=output_path,
+    )
+
+
+def detect_ecosystem(
+    path: str | Path | None = None,
+) -> DetectionResult:
+    """
+    Detect the ecosystem(s) present in a project directory.
+
+    Parameters
+    ----------
+    path:
+        Directory to inspect. Defaults to ``Path.cwd()``.
+
+    Returns
+    -------
+    DetectionResult
+        Has ``.ecosystems`` (list of strings like ``["Next.js", "Node.js"]``),
+        ``.display_name`` (e.g. ``"Next.js + Node.js"``), and
+        ``.confidence`` (``"low"`` / ``"medium"`` / ``"high"``).
+
+    Example
+    -------
+    ::
+
+        from contextzip import detect_ecosystem
+
+        result = detect_ecosystem("/path/to/project")
+        print(result.display_name)   # "Django + Python"
+        print(result.confidence)     # "high"
+    """
+    return detect(_resolve_dir(path))
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_dir(path: str | Path | None) -> Path:
+    if path is None:
+        return Path(os.getcwd()).resolve()
+    return Path(path).resolve()
+
+
+def _resolve_result_to_collection(
+    resolved: ResolveResult,
+    project_dir: Path,
+    detection: DetectionResult,
+) -> FileCollection:
+    return FileCollection(
+        files=resolved.included,
+        skipped=resolved.skipped,
+        large_files=resolved.large_files,
+        binary_files=resolved.binary_files,
+        project_dir=project_dir,
+        ecosystem=detection.display_name,
+    )
+
+
+def _raise_git_error(error: GitError) -> None:
+    if error.kind == GitErrorKind.GIT_NOT_FOUND:
+        raise GitNotFoundError(error.message)
+    if error.kind == GitErrorKind.NOT_A_REPO:
+        raise NotARepositoryError(error.message)
+    raise GitCommandError(error.message)