contextzip 0.3.3__tar.gz → 0.3.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.3.3
+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.
 
 ---
 
@@ -243,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.3 → 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.
 
 ---
 
@@ -214,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.3 → contextzip-0.3.4}/contextzip/__init__.py

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

contextzip-0.3.4/contextzip/brief.py

@@ -0,0 +1,280 @@
+"""
+brief.py — Orchestrates `contextzip eod` and `contextzip handoff`.
+
+Both commands share one pipeline:
+  1. Locate the latest conversation export
+  2. Best-effort fetch Claude's artifact files if missing (for case 2)
+  3. Resolve code changes (the three-case decision tree in code_changes.py)
+  4. Render the prompt — conversation inlined or attached depending on size,
+     code changes attached as a zip when there are any
+  5. Write the prompt text (+ zip) to .contextzip/, advance the marker
+
+`eod` and `handoff` differ only in the fixed instruction text and which
+marker they read/write — everything else is identical, so this module
+takes a `kind` parameter rather than having two near-duplicate pipelines.
+
+contextzip does no AI calls here. This produces a prompt for a human to
+paste into Claude or ChatGPT; the actual summarizing/continuing is the
+receiving chat's job, not contextzip's.
+"""
+
+from __future__ import annotations
+
+import zipfile
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+from contextzip.claude_artifacts import fetch_artifacts
+from contextzip.claude_export import (
+    DEFAULT_EXPORTS_DIR,
+    ConversationExport,
+    NoExportFoundError,
+    artifacts_dir_for,
+    find_latest_export,
+    should_inline,
+)
+from contextzip.code_changes import CodeChangesResult, resolve_code_changes
+from contextzip.config import get_session_key
+from contextzip.git import GitError
+from contextzip.markers import save_marker
+from contextzip.packager import _ensure_gitignore, _workspace_dir
+
+EOD_INSTRUCTION = "Create the work log table."
+
+HANDOFF_INTRO = (
+    "I've hit my usage limit in a previous chat and need to continue this "
+    "project in a new one."
+)
+HANDOFF_REVIEW_INLINE = "Here's the conversation so far — please review it and continue from where we left off."
+HANDOFF_REVIEW_ATTACHED = (
+    "I've attached the prior conversation export ({filename}) — please "
+    "review it and continue from where we left off."
+)
+
+
+class BriefError(Exception):
+    """Raised for hard failures — no export found, etc."""
+
+
+@dataclass
+class BriefResult:
+    kind: str  # "eod" | "handoff"
+    prompt_text: str
+    prompt_path: Path
+    changes_zip_path: Path | None
+    export: ConversationExport
+    conversation_inlined: bool
+    code_changes: CodeChangesResult | None
+    fetch_warnings: list[str] = field(default_factory=list)
+
+
+def run_brief(
+    *,
+    kind: str,
+    project_dir: Path,
+    exports_dir: Path | None = None,
+    auto_fetch_artifacts: bool = True,
+    dry_run: bool = False,
+) -> BriefResult:
+    if exports_dir is None:
+        exports_dir = project_dir / DEFAULT_EXPORTS_DIR
+
+    _ensure_exports_ignored(exports_dir, project_dir)
+
+    try:
+        export = find_latest_export(exports_dir)
+    except NoExportFoundError as exc:
+        raise BriefError(str(exc))
+
+    fetch_warnings: list[str] = []
+    claude_dir = artifacts_dir_for(export, exports_dir)
+
+    if auto_fetch_artifacts and not _has_any_file(claude_dir):
+        session_key = get_session_key()
+        if not session_key:
+            fetch_warnings.append(
+                "No Claude session key configured — skipping the diverged-from-Claude "
+                "check (case 2). Run `contextzip config --set-session-key` to enable it."
+            )
+        else:
+            _saved, errors = fetch_artifacts(export.text, claude_dir, session_key)
+            fetch_warnings.extend(errors)
+
+    code_changes = resolve_code_changes(
+        project_dir=project_dir,
+        kind=kind,
+        claude_artifacts_dir=claude_dir if _has_any_file(claude_dir) else None,
+    )
+    if isinstance(code_changes, GitError):
+        fetch_warnings.append(
+            f"Code changes skipped — {code_changes.message.splitlines()[0]}"
+        )
+        code_changes = None
+    elif code_changes.warnings:
+        fetch_warnings.extend(code_changes.warnings)
+
+    inline = should_inline(export)
+
+    changes_zip_path: Path | None = None
+    if code_changes and not code_changes.is_empty:
+        changes_zip_path = _build_changes_zip(code_changes, project_dir, kind)
+
+    prompt_text = _render_prompt(
+        kind=kind,
+        export=export,
+        inline=inline,
+        changes_zip_path=changes_zip_path,
+    )
+
+    prompt_path = _write_prompt(prompt_text, project_dir, kind)
+
+    if not dry_run:
+        from contextzip.git import get_commit_hash, get_current_branch
+
+        branch = get_current_branch(project_dir) or "HEAD"
+        head = get_commit_hash("HEAD", project_dir)
+        if head:
+            save_marker(kind, branch, head, project_dir)
+
+    return BriefResult(
+        kind=kind,
+        prompt_text=prompt_text,
+        prompt_path=prompt_path,
+        changes_zip_path=changes_zip_path,
+        export=export,
+        conversation_inlined=inline,
+        code_changes=code_changes,
+        fetch_warnings=fetch_warnings,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Prompt rendering
+# ---------------------------------------------------------------------------
+
+
+def _render_prompt(
+    *,
+    kind: str,
+    export: ConversationExport,
+    inline: bool,
+    changes_zip_path: Path | None,
+) -> str:
+    if kind == "eod":
+        return _render_eod(export, inline, changes_zip_path)
+    return _render_handoff(export, inline, changes_zip_path)
+
+
+def _render_eod(
+    export: ConversationExport, inline: bool, changes_zip_path: Path | None
+) -> str:
+    parts: list[str] = []
+
+    if inline:
+        parts.append(f"Conversation:\n{export.text}")
+    else:
+        parts.append(f"Conversation attached: {export.path.name}")
+
+    if changes_zip_path is not None:
+        parts.append(f"Code changes attached: {changes_zip_path.name}")
+
+    parts.append(EOD_INSTRUCTION)
+
+    return "\n\n".join(parts)
+
+
+def _render_handoff(
+    export: ConversationExport, inline: bool, changes_zip_path: Path | None
+) -> str:
+    parts: list[str] = [HANDOFF_INTRO]
+
+    if inline:
+        parts.append(f"{HANDOFF_REVIEW_INLINE}\n\n{export.text}")
+    else:
+        parts.append(HANDOFF_REVIEW_ATTACHED.format(filename=export.path.name))
+
+    if changes_zip_path is not None:
+        parts.append(
+            f"I've also attached the code changes since our last session "
+            f"({changes_zip_path.name}) so you have the current state without "
+            f"needing the full codebase."
+        )
+
+    return "\n\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Output writing
+# ---------------------------------------------------------------------------
+
+
+def _write_prompt(prompt_text: str, project_dir: Path, kind: str) -> Path:
+    workspace, is_git_repo = _workspace_dir(project_dir)
+    workspace.mkdir(parents=True, exist_ok=True)
+
+    if is_git_repo:
+        try:
+            _ensure_gitignore(workspace.parent)
+        except OSError:
+            pass
+
+    # eod is once-a-day (overwritable, like codebase.zip); handoff can fire
+    # multiple times in a day (you can hit the limit more than once), so it
+    # gets a timestamp instead of just a date.
+    if kind == "eod":
+        stamp = datetime.now().strftime("%Y-%m-%d")
+    else:
+        stamp = datetime.now().strftime("%Y-%m-%d-%H%M%S")
+
+    path = workspace / f"{kind}-{stamp}.txt"
+    path.write_text(prompt_text, encoding="utf-8")
+    return path
+
+
+def _build_changes_zip(
+    code_changes: CodeChangesResult, project_dir: Path, kind: str
+) -> Path:
+    workspace, _ = _workspace_dir(project_dir)
+    workspace.mkdir(parents=True, exist_ok=True)
+    zip_path = workspace / f"{kind}-changes.zip"
+
+    with zipfile.ZipFile(
+        zip_path, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=6
+    ) as zf:
+        for f in code_changes.files:
+            if f.content is not None:
+                zf.writestr(f"full/{f.rel_path}", f.content.encode("utf-8"))
+            if f.diff is not None:
+                zf.writestr(f"diffs/{f.rel_path}.patch", f.diff.encode("utf-8"))
+
+    return zip_path
+
+
+def _has_any_file(directory: Path) -> bool:
+    return directory.is_dir() and any(p.is_file() for p in directory.rglob("*"))
+
+
+def _ensure_exports_ignored(exports_dir: Path, project_dir: Path) -> None:
+    """
+    Register exports/ in .gitignore the first time it's used, same treatment
+    as .contextzip/. Conversation exports and fetched Claude artifacts are
+    personal working files, not something to accidentally commit — though
+    a team that *wants* to share them can simply remove the line.
+    """
+    from contextzip.packager import _find_git_root
+
+    git_root = _find_git_root(project_dir)
+    if git_root is None:
+        return
+
+    try:
+        rel = exports_dir.resolve().relative_to(git_root)
+    except ValueError:
+        return  # exports_dir lives outside the repo — nothing to register
+
+    entry = rel.as_posix().rstrip("/") + "/"
+    try:
+        _ensure_gitignore(git_root, entry)
+    except OSError:
+        pass

contextzip-0.3.4/contextzip/claude_artifacts.py

@@ -0,0 +1,150 @@
+"""
+claude_artifacts.py — Fetches Claude.ai artifact files referenced in a
+conversation export.
+
+This talks to an undocumented Claude.ai endpoint using the user's own
+session cookie (contextzip.config.get_session_key()). It is explicitly
+best-effort: a missing key, an expired cookie, or the endpoint changing
+shape should degrade gracefully — code_changes.py simply skips case 2
+(diverged-from-Claude) for affected files — rather than aborting the whole
+eod/handoff run. Nothing here should ever raise out to the caller for a
+single failed download; only total inability to attempt the fetch at all
+(httpx missing) is surfaced as an immediate empty result with an error.
+
+Known fragility, by design, not oversight: this is reverse-engineered from
+the claude.ai web app's own network calls, not a published API. It may stop
+working without notice, and depending on Cloudflare's bot-management state
+it may also simply fail unpredictably from a non-browser client regardless
+of how correct the request looks.
+"""
+
+from __future__ import annotations
+
+import re
+import urllib.parse
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    import httpx
+
+    _HTTPX_AVAILABLE = True
+except ImportError:
+    _HTTPX_AVAILABLE = False
+
+
+DOWNLOAD_LINK_RE = re.compile(
+    r"\[([^\]]+)\]\((https://claude\.ai/api/organizations/[^)\s]+"
+    r"/wiggle/download-file\?path=[^)\s]+)\)"
+)
+
+_BROWSER_HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+        "(KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
+    ),
+    "Accept": "*/*",
+    "Accept-Language": "en-US,en;q=0.9",
+}
+
+
+@dataclass
+class ArtifactLink:
+    label: str
+    url: str
+    filename: str
+
+
+def extract_links(export_text: str) -> list[ArtifactLink]:
+    """Pull every unique download-file link out of an export's raw text."""
+    seen: set[str] = set()
+    links: list[ArtifactLink] = []
+
+    for label, url in DOWNLOAD_LINK_RE.findall(export_text):
+        if url in seen:
+            continue
+        seen.add(url)
+
+        parsed = urllib.parse.urlparse(url)
+        query = urllib.parse.parse_qs(parsed.query)
+        raw_path = query.get("path", [""])[0]
+        decoded = urllib.parse.unquote(raw_path)
+        filename = Path(decoded).name or Path(label).name or "artifact"
+
+        links.append(ArtifactLink(label=label, url=url, filename=filename))
+
+    return links
+
+
+def fetch_artifacts(
+    export_text: str,
+    dest_dir: Path,
+    session_key: str,
+) -> tuple[list[Path], list[str]]:
+    """
+    Download every artifact link found in *export_text* into *dest_dir*.
+
+    Returns (saved_paths, errors). Never raises for an individual download
+    failure — each failure becomes a string in *errors* so callers (brief.py)
+    can surface them as warnings and continue with whatever did succeed.
+    """
+    if not _HTTPX_AVAILABLE:
+        return [], ["httpx is not installed — cannot fetch Claude artifacts."]
+
+    links = extract_links(export_text)
+    if not links:
+        return [], []
+
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    saved: list[Path] = []
+    errors: list[str] = []
+
+    session_key = session_key.strip().strip('"').strip("'")
+    headers_base = dict(_BROWSER_HEADERS)
+    headers_base["Cookie"] = f"sessionKey={session_key}"
+
+    with httpx.Client(timeout=30, follow_redirects=True) as client:
+        for link in links:
+            headers = dict(headers_base)
+            headers["Referer"] = _conversation_referer(link.url)
+            headers["Origin"] = "https://claude.ai"
+
+            try:
+                resp = client.get(link.url, headers=headers)
+            except httpx.RequestError as exc:
+                errors.append(f"{link.filename}: network error ({exc})")
+                continue
+
+            if resp.status_code in (401, 403):
+                errors.append(
+                    f"{link.filename}: auth failed ({resp.status_code}) — session key "
+                    "may be missing/expired, or this request was blocked before it "
+                    "even reached Claude's app (Cloudflare bot protection)."
+                )
+                continue
+            if resp.status_code == 404:
+                errors.append(
+                    f"{link.filename}: not found (404) — the file or conversation "
+                    "session may have expired."
+                )
+                continue
+            if resp.status_code != 200:
+                errors.append(f"{link.filename}: HTTP {resp.status_code}")
+                continue
+
+            dest = dest_dir / link.filename
+            try:
+                dest.write_bytes(resp.content)
+                saved.append(dest)
+            except OSError as exc:
+                errors.append(f"{link.filename}: could not write file ({exc})")
+
+    return saved, errors
+
+
+def _conversation_referer(url: str) -> str:
+    match = re.search(r"/conversations/([0-9a-fA-F-]+)/wiggle", url)
+    if match:
+        return f"https://claude.ai/chat/{match.group(1)}"
+    return "https://claude.ai/"

contextzip-0.3.4/contextzip/claude_export.py

@@ -0,0 +1,73 @@
+"""
+claude_export.py — Locates and prepares a Claude.ai conversation export for
+use in `eod` / `handoff` prompts.
+
+Pure text handling — no AI calls, no network. Finding "the latest export"
+and deciding whether it's short enough to paste inline are the only two
+responsibilities here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_EXPORTS_DIR = "exports"
+DEFAULT_ARTIFACTS_SUBDIR = "artifacts"
+
+# Conversations at or under this length get pasted directly into the
+# generated prompt; longer ones are referenced as an attachment instead,
+# since a full day's chat could otherwise burn through the next chat's
+# context budget before any actual work happens.
+INLINE_CHAR_THRESHOLD = 3500
+
+
+class NoExportFoundError(Exception):
+    """Raised when no .md export exists in the exports directory."""
+
+
+@dataclass
+class ConversationExport:
+    path: Path
+    text: str
+    conversation_name: str  # filename stem — used for the artifacts subfolder
+
+
+def find_latest_export(exports_dir: Path) -> ConversationExport:
+    """
+    Return the most recently modified .md file in *exports_dir*.
+
+    "Most recently modified" rather than "most recently created" — if you
+    re-export the same conversation later in the day, the newer copy wins
+    without needing a naming convention.
+    """
+    if not exports_dir.is_dir():
+        raise NoExportFoundError(
+            f"Exports folder not found: {exports_dir}. "
+            f"Export a conversation and drop the .md file there first."
+        )
+
+    candidates = list(exports_dir.glob("*.md"))
+    if not candidates:
+        raise NoExportFoundError(
+            f"No .md export files found in {exports_dir}. "
+            f"Export a conversation and drop the .md file there first."
+        )
+
+    candidates.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    path = candidates[0]
+    text = path.read_text(encoding="utf-8", errors="replace")
+
+    return ConversationExport(path=path, text=text, conversation_name=path.stem)
+
+
+def artifacts_dir_for(export: ConversationExport, exports_dir: Path) -> Path:
+    """Where this export's Claude-provided artifact files live (or will be fetched to)."""
+    return exports_dir / DEFAULT_ARTIFACTS_SUBDIR / export.conversation_name
+
+
+def should_inline(
+    export: ConversationExport, threshold: int = INLINE_CHAR_THRESHOLD
+) -> bool:
+    """True if the export is short enough to paste directly into the prompt."""
+    return len(export.text) <= threshold