contextzip 0.3.2__tar.gz → 0.3.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.3.2
+Version: 0.3.4
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -52,6 +52,7 @@ contextzip eliminates that entirely. Run it from your project root — it detect
 - **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
+- **End-of-day / handoff prompts** — `contextzip eod` and `contextzip handoff` turn a Claude/ChatGPT conversation export plus today's code changes into a paste-ready prompt, copied straight to your clipboard
 - **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
@@ -117,7 +118,7 @@ contextzip [OPTIONS]
 | `--no-clipboard` | Skip the clipboard / folder-open step |
 | `--no-gitignore` | Ignore the project's `.gitignore` |
 
-**Subcommands:** `exclude`, `include`, `watch`, `config` — run `contextzip --help` for full details.
+**Subcommands:** `exclude`, `include`, `watch`, `config`, `eod`, `handoff` — run `contextzip --help` for full details.
 
 ---
 
@@ -148,6 +149,40 @@ contextzip --output ~/Desktop/project-context.zip
 
 ---
 
+## Python API
+
+contextzip is also usable as a library. All CLI capabilities are available as plain Python functions — no Click, no Rich output, no `SystemExit`.
+
+```python
+from contextzip import get_git_changes, get_files, create_zip
+
+# Get changed files and use them directly
+collection = get_git_changes()
+for f in collection.files:          # plain pathlib.Path objects
+    upload(f)                       # no zip required
+
+# Or zip them and upload the archive
+pkg = create_zip(collection, output="/tmp/changes.zip")
+with open(pkg.zip_path, "rb") as f:
+    upload_to_s3(f)
+
+# Full project scan with filters
+collection = get_files(include=["src/"], exclude=["tests/"])
+pkg = create_zip(collection, output="/tmp/upload.zip")
+print(f"{pkg.file_count} files, {pkg.compressed_bytes} bytes")
+```
+
+| Function | Description |
+|---|---|
+| `get_git_changes(path?)` | Modified, added, and untracked files from git |
+| `get_files(path?, include?, exclude?)` | All project files after exclusion rules |
+| `create_zip(collection, output?)` | Write a `FileCollection` to a ZIP archive |
+| `detect_ecosystem(path?)` | Detect framework and confidence level |
+
+All functions default `path` to `Path.cwd()`. Errors raise typed exceptions (`NotARepositoryError`, `GitNotFoundError`, `NoFilesError`, etc.) rather than exiting.
+
+---
+
 ## AI-powered file selection
 
 The `--prompt` flag lets you describe a task in plain English. contextzip scans your project, builds a lightweight file map, and asks Gemini to return the minimum set of files needed for that task — typically 2–5, never more than 10. The result is a tightly scoped ZIP with only what you'd actually open to make the change.
@@ -209,11 +244,49 @@ Press **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Y
 
 ---
 
+## End-of-day reports and chat handoffs
+
+If you work through a problem in a Claude or ChatGPT conversation and need to either (a) summarize what you did for an end-of-day report, or (b) continue the same work in a fresh chat after hitting a usage limit, `eod` and `handoff` build the prompt for you — contextzip does no summarizing itself; that's left to whichever AI tool you paste the result into.
+
+```bash
+contextzip eod
+contextzip handoff
+```
+
+**Setup:** export your conversation (any markdown export works) and drop the `.md` file into `exports/` at your project root. Both commands pick the most recently modified file there automatically.
+
+**What gets built:**
+
+- The conversation itself — pasted directly into the prompt if it's short, or referenced as an attachment if it's long enough that inlining it would burn through the next chat's context budget
+- Whatever code changed, resolved per file in priority order:
+  1. **Not pushed** — diffed against your upstream branch, plus the complete current file
+  2. **Diverged from Claude** — diffed against the version Claude last produced (if you've set up a session key — see below), plus the complete current codebase file
+  3. **Since last run** — diffed against a per-branch checkpoint that `eod`/`handoff` remember automatically, plus the complete current file
+- New, untracked files are included as full content (there's nothing to diff them against)
+- `eod` ends the prompt with a flat instruction to produce a work-log table; `handoff` frames it as continuing the project in a new chat
+
+The result is copied straight to your clipboard, and also saved to `.contextzip/` if you want to look it over first.
+
+**Optional — diffing against Claude's own version (case 2):** if you give contextzip your Claude.ai session key, `eod`/`handoff` will fetch the files Claude actually produced and compare them against your codebase, catching drift even after everything's pushed and in sync.
+
+```bash
+contextzip config --set-session-key
+```
+
+This is best-effort by design — it depends on an undocumented Claude.ai endpoint, so a missing key, an expired cookie, or the endpoint changing shape just skips this check with a warning rather than failing the whole command.
+
+```bash
+contextzip eod --dry-run        # preview without advancing the checkpoint
+contextzip handoff --no-fetch   # skip the Claude-artifact fetch for this run
+```
+
+---
+
 ## What gets excluded
 
 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/` and `exports/` working folders.
 
 **By framework:**
 

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

@@ -23,6 +23,7 @@ contextzip eliminates that entirely. Run it from your project root — it detect
 - **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
+- **End-of-day / handoff prompts** — `contextzip eod` and `contextzip handoff` turn a Claude/ChatGPT conversation export plus today's code changes into a paste-ready prompt, copied straight to your clipboard
 - **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
@@ -88,7 +89,7 @@ contextzip [OPTIONS]
 | `--no-clipboard` | Skip the clipboard / folder-open step |
 | `--no-gitignore` | Ignore the project's `.gitignore` |
 
-**Subcommands:** `exclude`, `include`, `watch`, `config` — run `contextzip --help` for full details.
+**Subcommands:** `exclude`, `include`, `watch`, `config`, `eod`, `handoff` — run `contextzip --help` for full details.
 
 ---
 
@@ -119,6 +120,40 @@ contextzip --output ~/Desktop/project-context.zip
 
 ---
 
+## Python API
+
+contextzip is also usable as a library. All CLI capabilities are available as plain Python functions — no Click, no Rich output, no `SystemExit`.
+
+```python
+from contextzip import get_git_changes, get_files, create_zip
+
+# Get changed files and use them directly
+collection = get_git_changes()
+for f in collection.files:          # plain pathlib.Path objects
+    upload(f)                       # no zip required
+
+# Or zip them and upload the archive
+pkg = create_zip(collection, output="/tmp/changes.zip")
+with open(pkg.zip_path, "rb") as f:
+    upload_to_s3(f)
+
+# Full project scan with filters
+collection = get_files(include=["src/"], exclude=["tests/"])
+pkg = create_zip(collection, output="/tmp/upload.zip")
+print(f"{pkg.file_count} files, {pkg.compressed_bytes} bytes")
+```
+
+| Function | Description |
+|---|---|
+| `get_git_changes(path?)` | Modified, added, and untracked files from git |
+| `get_files(path?, include?, exclude?)` | All project files after exclusion rules |
+| `create_zip(collection, output?)` | Write a `FileCollection` to a ZIP archive |
+| `detect_ecosystem(path?)` | Detect framework and confidence level |
+
+All functions default `path` to `Path.cwd()`. Errors raise typed exceptions (`NotARepositoryError`, `GitNotFoundError`, `NoFilesError`, etc.) rather than exiting.
+
+---
+
 ## AI-powered file selection
 
 The `--prompt` flag lets you describe a task in plain English. contextzip scans your project, builds a lightweight file map, and asks Gemini to return the minimum set of files needed for that task — typically 2–5, never more than 10. The result is a tightly scoped ZIP with only what you'd actually open to make the change.
@@ -180,11 +215,49 @@ Press **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Y
 
 ---
 
+## End-of-day reports and chat handoffs
+
+If you work through a problem in a Claude or ChatGPT conversation and need to either (a) summarize what you did for an end-of-day report, or (b) continue the same work in a fresh chat after hitting a usage limit, `eod` and `handoff` build the prompt for you — contextzip does no summarizing itself; that's left to whichever AI tool you paste the result into.
+
+```bash
+contextzip eod
+contextzip handoff
+```
+
+**Setup:** export your conversation (any markdown export works) and drop the `.md` file into `exports/` at your project root. Both commands pick the most recently modified file there automatically.
+
+**What gets built:**
+
+- The conversation itself — pasted directly into the prompt if it's short, or referenced as an attachment if it's long enough that inlining it would burn through the next chat's context budget
+- Whatever code changed, resolved per file in priority order:
+  1. **Not pushed** — diffed against your upstream branch, plus the complete current file
+  2. **Diverged from Claude** — diffed against the version Claude last produced (if you've set up a session key — see below), plus the complete current codebase file
+  3. **Since last run** — diffed against a per-branch checkpoint that `eod`/`handoff` remember automatically, plus the complete current file
+- New, untracked files are included as full content (there's nothing to diff them against)
+- `eod` ends the prompt with a flat instruction to produce a work-log table; `handoff` frames it as continuing the project in a new chat
+
+The result is copied straight to your clipboard, and also saved to `.contextzip/` if you want to look it over first.
+
+**Optional — diffing against Claude's own version (case 2):** if you give contextzip your Claude.ai session key, `eod`/`handoff` will fetch the files Claude actually produced and compare them against your codebase, catching drift even after everything's pushed and in sync.
+
+```bash
+contextzip config --set-session-key
+```
+
+This is best-effort by design — it depends on an undocumented Claude.ai endpoint, so a missing key, an expired cookie, or the endpoint changing shape just skips this check with a warning rather than failing the whole command.
+
+```bash
+contextzip eod --dry-run        # preview without advancing the checkpoint
+contextzip handoff --no-fetch   # skip the Claude-artifact fetch for this run
+```
+
+---
+
 ## What gets excluded
 
 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/` and `exports/` working folders.
 
 **By framework:**
 

{contextzip-0.3.2 → contextzip-0.3.4}/contextzip/__init__.py

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

contextzip-0.3.4/contextzip/ai/__init__.py

@@ -0,0 +1 @@
+"""contextzip.ai — AI-powered file selection for --prompt mode."""

contextzip-0.3.4/contextzip/ai/gemini.py

@@ -0,0 +1,282 @@
+"""
+ai/gemini.py — Thin Gemini API client for contextzip's prompt-aware mode.
+
+Makes a single POST to the Gemini generateContent endpoint and returns
+a ranked list of file paths relevant to the user's task description.
+
+Design principles:
+  - Raw httpx calls only — no Google SDK dependency
+  - Strict JSON output from the model — no markdown, no prose
+  - Validates every returned path against the real file tree
+  - Single responsibility: call API, parse response, validate paths
+"""
+
+from __future__ import annotations
+
+import json
+
+try:
+    import httpx
+
+    _HTTPX_AVAILABLE = True
+except ImportError:
+    _HTTPX_AVAILABLE = False
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_API_URL = (
+    "https://generativelanguage.googleapis.com/v1beta/models"
+    "/{model}:generateContent?key={key}"
+)
+
+DEFAULT_MODEL = "gemini-2.5-flash-lite"
+
+# Hard cap: never return more than this many files regardless of model output.
+# Minimum context is the goal — the prompt enforces this, but we double-guard.
+_MAX_FILES = 12
+
+_TIMEOUT_SECONDS = 30
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class GeminiError(Exception):
+    """Raised when the Gemini API call fails for any reason."""
+
+
+class GeminiUnavailable(GeminiError):
+    """Raised when httpx is not installed."""
+
+
+class GeminiRateLimitError(GeminiError):
+    """Raised specifically on HTTP 429 — allows callers to trigger fallback."""
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def select_files(
+    *,
+    api_key: str,
+    prompt: str,
+    file_tree: list[tuple[str, int]],  # [(rel_path, size_bytes), ...]
+    ecosystem: str,
+    model: str = DEFAULT_MODEL,
+) -> list[str]:
+    """
+    Ask Gemini which files are relevant to *prompt* and return their paths.
+
+    Parameters
+    ----------
+    api_key:
+        Gemini API key from Google AI Studio.
+    prompt:
+        The user's natural-language task description.
+    file_tree:
+        All candidate files as (relative_posix_path, size_bytes) tuples.
+        These should already have contextzip's standard exclusions applied —
+        no node_modules, no build artifacts, no .env files.
+    ecosystem:
+        Human-readable detected framework string, e.g. "Next.js + TypeScript".
+        Gives the model important context for relevance scoring.
+    model:
+        Gemini model identifier. Defaults to gemini-2.5-flash-lite.
+
+    Returns
+    -------
+    list[str]
+        Relative POSIX paths of the selected files, ordered by relevance
+        (most relevant first). Always a strict subset of the input file_tree
+        paths — hallucinated or non-existent paths are silently dropped.
+
+    Raises
+    ------
+    GeminiUnavailable
+        If httpx is not installed.
+    GeminiError
+        On any API or parsing failure.
+    """
+    if not _HTTPX_AVAILABLE:
+        raise GeminiUnavailable(
+            "httpx is required for AI-powered selection. "
+            "Install it with: pip install httpx"
+        )
+
+    system_prompt = _build_system_prompt()
+    user_message = _build_user_message(prompt, file_tree, ecosystem)
+
+    url = _API_URL.format(model=model, key=api_key)
+
+    payload = {
+        "contents": [
+            {
+                "role": "user",
+                "parts": [{"text": f"{system_prompt}\n\n{user_message}"}],
+            }
+        ],
+        "generationConfig": {
+            "temperature": 0.0,  # deterministic — this is a ranking task
+            "maxOutputTokens": 512,  # a list of paths needs very few tokens
+            "responseMimeType": "application/json",
+        },
+    }
+
+    try:
+        response = httpx.post(url, json=payload, timeout=_TIMEOUT_SECONDS)
+    except httpx.TimeoutException:
+        raise GeminiError("Request timed out after 30 seconds.")
+    except httpx.RequestError as exc:
+        raise GeminiError(f"Network error: {exc}")
+
+    if response.status_code == 400:
+        raise GeminiError("Invalid request — check your API key format.")
+    if response.status_code == 401 or response.status_code == 403:
+        raise GeminiError(
+            "API key rejected. Run [cyan]contextzip config --reset-key[/] to update it."
+        )
+    if response.status_code == 429:
+        raise GeminiRateLimitError(
+            "Rate limit reached on the free tier (15 req/min). "
+            "Wait a moment and try again, or your new key may still be activating — "
+            "Google can take up to 60 seconds after key creation."
+        )
+    if response.status_code != 200:
+        raise GeminiError(
+            f"Gemini API returned HTTP {response.status_code}: {response.text[:200]}"
+        )
+
+    return _parse_response(response.json(), file_tree)
+
+
+# ---------------------------------------------------------------------------
+# Prompt construction
+# ---------------------------------------------------------------------------
+
+
+def _build_system_prompt() -> str:
+    return """\
+You are a precise file relevance assistant for software projects.
+
+Your only job: given a developer's task description and a project file tree,
+return the MINIMUM set of files a developer would need to open to complete
+that task. Think like a senior engineer doing a surgical code change —
+open only what you must touch or read to understand the change.
+
+Rules you must follow:
+- Return ONLY a JSON array of file path strings. No explanation, no markdown,
+  no extra keys. Example: ["src/auth.ts", "components/Toast.tsx"]
+- Be ruthless about exclusion. If a file is not directly relevant to the
+  stated task, leave it out. Err heavily on the side of fewer files.
+- Prefer files that will be MODIFIED over files that are merely referenced.
+- Config files, test files, and documentation should only appear if the
+  task explicitly concerns them.
+- Never return more than 10 files. For most tasks 2–5 files is correct.
+- Order by relevance: most directly relevant file first.\
+"""
+
+
+def _build_user_message(
+    prompt: str,
+    file_tree: list[tuple[str, int]],
+    ecosystem: str,
+) -> str:
+    tree_lines = "\n".join(f"{path} ({_human_size(size)})" for path, size in file_tree)
+    return f"""\
+Framework: {ecosystem}
+
+Task: {prompt}
+
+Project files (exclusions already applied):
+{tree_lines}
+
+Return only a JSON array of the most relevant file paths for this task.\
+"""
+
+
+# ---------------------------------------------------------------------------
+# Response parsing and validation
+# ---------------------------------------------------------------------------
+
+
+def _parse_response(
+    data: dict,
+    file_tree: list[tuple[str, int]],
+) -> list[str]:
+    """
+    Extract and validate the file list from the Gemini API response.
+
+    - Parses the JSON array from the model's text output
+    - Drops any path the model hallucinated (not in the real file tree)
+    - Enforces the _MAX_FILES hard cap
+    - Warns (via exception) if the model returned mostly invalid paths
+    """
+    # Navigate the Gemini response structure
+    try:
+        text = data["candidates"][0]["content"]["parts"][0]["text"]
+    except (KeyError, IndexError) as exc:
+        raise GeminiError(f"Unexpected API response structure: {exc}\n{data}")
+
+    # Strip any accidental markdown fences the model might add
+    text = text.strip().strip("`").strip()
+    if text.startswith("json"):
+        text = text[4:].strip()
+
+    try:
+        raw_paths: list = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise GeminiError(
+            f"Model returned non-JSON output: {exc}\nRaw output: {text[:300]}"
+        )
+
+    if not isinstance(raw_paths, list):
+        raise GeminiError(
+            f"Expected a JSON array, got {type(raw_paths).__name__}: {text[:200]}"
+        )
+
+    # Build a set of valid paths for O(1) lookup
+    valid_paths: set[str] = {path for path, _ in file_tree}
+
+    validated: list[str] = []
+    hallucinated = 0
+
+    for item in raw_paths:
+        if not isinstance(item, str):
+            continue
+        # Normalise separators (model may return backslashes on Windows prompts)
+        normalised = item.replace("\\", "/").strip()
+        if normalised in valid_paths:
+            validated.append(normalised)
+        else:
+            hallucinated += 1
+
+    # Warn if the model was mostly making things up
+    total_returned = len(raw_paths)
+    if total_returned > 0 and hallucinated / total_returned > 0.5:
+        raise GeminiError(
+            f"Model returned {hallucinated}/{total_returned} non-existent paths. "
+            "This may indicate a model or prompt issue. Try a more specific prompt."
+        )
+
+    # Enforce hard cap
+    return validated[:_MAX_FILES]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _human_size(n: int) -> str:
+    for unit in ("B", "KB", "MB"):
+        if n < 1024:
+            return f"{n:.0f} {unit}"
+        n /= 1024
+    return f"{n:.1f} GB"