aipromptdock 0.1.0__py3-none-any.whl

aipromptdock/__init__.py

@@ -0,0 +1,8 @@
+"""AI Prompt Dock — a local timeline for your AI CLI prompts."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("aipromptdock")
+except PackageNotFoundError:  # pragma: no cover - source tree without installation
+    __version__ = "0.0.0"

aipromptdock/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as `python -m aipromptdock`."""
+
+from aipromptdock.cli import app
+
+if __name__ == "__main__":
+    app()

aipromptdock/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API routes (filled in Phase 2)."""

aipromptdock/api/routes.py

@@ -0,0 +1,54 @@
+"""Versioned HTTP API."""
+
+from collections.abc import AsyncIterator
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Query, Request
+from sse_starlette.sse import EventSourceResponse
+
+from aipromptdock.core.events import EventBroadcaster
+from aipromptdock.core.models import PromptPage, ProviderId, ProviderInfo
+from aipromptdock.core.store import PromptStore
+
+router = APIRouter(prefix="/api/v1")
+
+
+def _store(request: Request) -> PromptStore:
+    store: PromptStore = request.app.state.store
+    # Fingerprint-cheap: stats a handful of files, rescans only what changed.
+    # Keeps responses correct even before the file watcher has fired.
+    store.refresh()
+    return store
+
+
+@router.get("/providers")
+def providers(request: Request) -> list[ProviderInfo]:
+    return _store(request).provider_infos()
+
+
+@router.get("/prompts")
+def prompts(
+    request: Request,
+    provider: Annotated[ProviderId | None, Query()] = None,
+    q: Annotated[str | None, Query(max_length=500)] = None,
+    before: Annotated[str | None, Query(max_length=200)] = None,
+    limit: Annotated[int, Query(ge=1, le=200)] = 50,
+) -> PromptPage:
+    return _store(request).page(provider=provider, q=q, before=before, limit=limit)
+
+
+@router.get("/events")
+async def events(request: Request) -> EventSourceResponse:
+    """Server-Sent Events: emits a `change` event whenever provider data changes."""
+    broadcaster: EventBroadcaster = request.app.state.broadcaster
+
+    async def stream() -> AsyncIterator[dict[str, Any]]:
+        queue = broadcaster.subscribe()
+        try:
+            while True:
+                provider_id = await queue.get()
+                yield {"event": "change", "data": provider_id}
+        finally:
+            broadcaster.unsubscribe(queue)
+
+    return EventSourceResponse(stream(), ping=15)

aipromptdock/cli.py

@@ -0,0 +1,82 @@
+"""Command-line interface for AI Prompt Dock."""
+
+from typing import Annotated
+
+import typer
+
+from aipromptdock import __version__
+
+app = typer.Typer(
+    name="aipromptdock",
+    help=(
+        "A local timeline for every prompt you've sent to Claude Code, Codex CLI, and Gemini CLI."
+    ),
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"aipromptdock {__version__}")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    port: Annotated[int, typer.Option("--port", "-p", help="Port to serve on.")] = 8745,
+    host: Annotated[
+        str, typer.Option("--host", help="Host to bind. Localhost-only by default.")
+    ] = "127.0.0.1",
+    no_browser: Annotated[
+        bool, typer.Option("--no-browser", help="Do not open the browser automatically.")
+    ] = False,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version", callback=_version_callback, is_eager=True, help="Show version and exit."
+        ),
+    ] = False,
+) -> None:
+    """Serve the AI Prompt Dock web app (default command)."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    if host not in {"127.0.0.1", "localhost", "::1"}:
+        typer.secho(
+            "Warning: binding to a non-loopback host exposes your prompt history "
+            "to the network without authentication.",
+            fg="yellow",
+            err=True,
+        )
+
+    from aipromptdock.server import serve
+
+    serve(host=host, port=port, open_browser=not no_browser)
+
+
+@app.command()
+def paths() -> None:
+    """Doctor: show detected CLIs, their data locations, and prompt counts."""
+    from rich.console import Console
+    from rich.table import Table
+
+    from aipromptdock.core.store import PromptStore
+    from aipromptdock.providers import default_adapters
+
+    store = PromptStore(default_adapters())
+    store.refresh()
+
+    table = Table(title="AI Prompt Dock — provider detection")
+    table.add_column("Provider", style="bold")
+    table.add_column("Detected")
+    table.add_column("Prompts", justify="right")
+    table.add_column("Data read from")
+    for info in store.provider_infos():
+        table.add_row(
+            info.name,
+            "[green]yes[/green]" if info.detected else "[red]no[/red]",
+            str(info.prompt_count),
+            "\n".join(info.paths),
+        )
+    Console().print(table)

aipromptdock/core/__init__.py

@@ -0,0 +1 @@
+"""Core domain: models, prompt store, file watcher (filled in Phase 1)."""

aipromptdock/core/events.py

@@ -0,0 +1,42 @@
+"""Fan-out of provider-change notifications to SSE subscribers."""
+
+import asyncio
+import logging
+
+from aipromptdock.core.models import ProviderId
+
+logger = logging.getLogger(__name__)
+
+
+class EventBroadcaster:
+    """Bridges watchdog worker threads to the asyncio SSE streams.
+
+    The watcher publishes from its own threads; ``publish_threadsafe`` hops
+    onto the server's event loop and fans the provider id out to every
+    subscribed queue.
+    """
+
+    def __init__(self) -> None:
+        self._queues: set[asyncio.Queue[ProviderId]] = set()
+        self._loop: asyncio.AbstractEventLoop | None = None
+
+    def bind_loop(self, loop: asyncio.AbstractEventLoop) -> None:
+        self._loop = loop
+
+    def publish_threadsafe(self, provider_id: ProviderId) -> None:
+        loop = self._loop
+        if loop is None or loop.is_closed():
+            return
+        loop.call_soon_threadsafe(self._publish, provider_id)
+
+    def _publish(self, provider_id: ProviderId) -> None:
+        for queue in self._queues:
+            queue.put_nowait(provider_id)
+
+    def subscribe(self) -> asyncio.Queue[ProviderId]:
+        queue: asyncio.Queue[ProviderId] = asyncio.Queue()
+        self._queues.add(queue)
+        return queue
+
+    def unsubscribe(self, queue: asyncio.Queue[ProviderId]) -> None:
+        self._queues.discard(queue)

aipromptdock/core/models.py

@@ -0,0 +1,63 @@
+"""Domain models shared across providers, store, and API."""
+
+import hashlib
+from datetime import UTC, datetime
+from typing import Literal
+
+from pydantic import BaseModel
+
+ProviderId = Literal["claude", "codex", "gemini"]
+
+
+def epoch_to_utc(value: float) -> datetime:
+    """Convert a Unix epoch in seconds *or* milliseconds to an aware UTC datetime.
+
+    Claude Code records milliseconds, Codex CLI records seconds; anything above
+    1e11 (~5138 AD in seconds) is treated as milliseconds.
+    """
+    if value > 1e11:
+        value /= 1000.0
+    return datetime.fromtimestamp(value, tz=UTC)
+
+
+def iso_to_utc(value: str) -> datetime:
+    """Parse an ISO-8601 string (Gemini/Claude transcripts use a trailing Z) to UTC."""
+    dt = datetime.fromisoformat(value)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return dt.astimezone(UTC)
+
+
+class PromptEvent(BaseModel):
+    """One prompt the user typed into an AI CLI."""
+
+    id: str
+    provider: ProviderId
+    text: str
+    timestamp: datetime
+    session_id: str | None = None
+    project: str | None = None
+    source: str
+
+    @staticmethod
+    def make_id(provider: str, session_id: str | None, timestamp: datetime, text: str) -> str:
+        """Stable identifier, identical across rescans of the same data."""
+        raw = f"{provider}|{session_id or ''}|{timestamp.isoformat()}|{text}"
+        return hashlib.sha1(raw.encode("utf-8", "replace")).hexdigest()[:16]
+
+
+class ProviderInfo(BaseModel):
+    """Detection status of one provider, shown in tabs and the doctor command."""
+
+    id: ProviderId
+    name: str
+    detected: bool
+    prompt_count: int
+    paths: list[str]
+
+
+class PromptPage(BaseModel):
+    """One page of timeline results."""
+
+    items: list[PromptEvent]
+    next_cursor: str | None

aipromptdock/core/store.py

@@ -0,0 +1,109 @@
+"""In-memory prompt store: merge, sort, search, paginate, cache."""
+
+import logging
+import threading
+from datetime import datetime
+
+from aipromptdock.core.models import PromptEvent, PromptPage, ProviderId, ProviderInfo
+from aipromptdock.providers.base import ProviderAdapter
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_PAGE_SIZE = 50
+
+
+def _sort_key(event: PromptEvent) -> tuple[datetime, str]:
+    return (event.timestamp, event.id)
+
+
+class PromptStore:
+    """Holds all prompts in memory, newest first.
+
+    ``refresh()`` is cheap when nothing changed: each adapter exposes a
+    stat-based fingerprint over the files it reads, and only adapters whose
+    fingerprint moved are rescanned. Thread-safe — the file watcher refreshes
+    from its own thread while the API reads.
+    """
+
+    def __init__(self, adapters: list[ProviderAdapter]) -> None:
+        self._adapters = adapters
+        self._lock = threading.Lock()
+        self._events: list[PromptEvent] = []
+        self._by_provider: dict[ProviderId, list[PromptEvent]] = {}
+        self._fingerprints: dict[ProviderId, object] = {}
+
+    @property
+    def adapters(self) -> list[ProviderAdapter]:
+        return self._adapters
+
+    def refresh(self, force: bool = False) -> bool:
+        """Rescan adapters whose data changed. Returns True if anything did."""
+        with self._lock:
+            changed = False
+            for adapter in self._adapters:
+                fingerprint = adapter.fingerprint()
+                if not force and self._fingerprints.get(adapter.id) == fingerprint:
+                    continue
+                try:
+                    events = adapter.scan()
+                except Exception:  # defensive: a broken adapter must not kill the app
+                    logger.exception("Provider %s failed to scan", adapter.id)
+                    events = []
+                events.sort(key=_sort_key, reverse=True)
+                self._by_provider[adapter.id] = events
+                self._fingerprints[adapter.id] = fingerprint
+                changed = True
+            if changed:
+                merged = [e for events in self._by_provider.values() for e in events]
+                merged.sort(key=_sort_key, reverse=True)
+                self._events = merged
+            return changed
+
+    def page(
+        self,
+        provider: ProviderId | None = None,
+        q: str | None = None,
+        before: str | None = None,
+        limit: int = DEFAULT_PAGE_SIZE,
+    ) -> PromptPage:
+        """Newest-first page. ``before`` is the opaque cursor from the previous page."""
+        with self._lock:
+            events = self._by_provider.get(provider, []) if provider else self._events
+
+        if q:
+            needle = q.lower()
+            events = [e for e in events if needle in e.text.lower()]
+
+        if before:
+            cursor = _decode_cursor(before)
+            if cursor:
+                events = [e for e in events if _sort_key(e) < cursor]
+
+        items = events[:limit]
+        next_cursor = _encode_cursor(items[-1]) if len(events) > limit else None
+        return PromptPage(items=items, next_cursor=next_cursor)
+
+    def provider_infos(self) -> list[ProviderInfo]:
+        with self._lock:
+            return [
+                ProviderInfo(
+                    id=adapter.id,
+                    name=adapter.name,
+                    detected=adapter.detected,
+                    prompt_count=len(self._by_provider.get(adapter.id, [])),
+                    paths=[str(p) for p in adapter.data_paths()[:3]] or [str(adapter.data_dir)],
+                )
+                for adapter in self._adapters
+            ]
+
+
+def _encode_cursor(event: PromptEvent) -> str:
+    return f"{event.timestamp.isoformat()}|{event.id}"
+
+
+def _decode_cursor(cursor: str) -> tuple[datetime, str] | None:
+    timestamp_raw, _, event_id = cursor.partition("|")
+    try:
+        return (datetime.fromisoformat(timestamp_raw), event_id)
+    except ValueError:
+        return None

aipromptdock/core/watcher.py

@@ -0,0 +1,67 @@
+"""Watch the providers' data directories and report (debounced) changes."""
+
+import logging
+import threading
+from collections.abc import Callable
+
+from watchdog.events import FileSystemEvent, FileSystemEventHandler
+from watchdog.observers import Observer
+
+from aipromptdock.core.models import ProviderId
+from aipromptdock.providers.base import ProviderAdapter
+
+logger = logging.getLogger(__name__)
+
+DEBOUNCE_SECONDS = 1.0
+
+
+class _Handler(FileSystemEventHandler):
+    def __init__(self, adapter: ProviderAdapter, notify: Callable[[ProviderId], None]) -> None:
+        self._adapter = adapter
+        self._notify = notify
+        self._timer: threading.Timer | None = None
+        self._timer_lock = threading.Lock()
+
+    def on_any_event(self, event: FileSystemEvent) -> None:
+        if event.is_directory:
+            return
+        path = str(event.src_path)
+        if not self._adapter.watch_filter(path):
+            return
+        # Debounce: CLIs write in bursts; fire once per quiet second.
+        with self._timer_lock:
+            if self._timer is not None:
+                self._timer.cancel()
+            self._timer = threading.Timer(DEBOUNCE_SECONDS, self._notify, args=(self._adapter.id,))
+            self._timer.daemon = True
+            self._timer.start()
+
+
+class DataWatcher:
+    """One watchdog observer over all detected providers' data directories.
+
+    ``on_change`` is called from a worker thread with the provider id after
+    each debounced burst of file events.
+    """
+
+    def __init__(
+        self, adapters: list[ProviderAdapter], on_change: Callable[[ProviderId], None]
+    ) -> None:
+        self._observer = Observer()
+        self._started = False
+        for adapter in adapters:
+            if not adapter.detected:
+                continue
+            handler = _Handler(adapter, on_change)
+            self._observer.schedule(handler, str(adapter.data_dir), recursive=True)
+            self._started = True
+
+    def start(self) -> None:
+        if self._started:
+            self._observer.start()
+            logger.info("Watching provider data directories for changes")
+
+    def stop(self) -> None:
+        if self._started and self._observer.is_alive():
+            self._observer.stop()
+            self._observer.join(timeout=3)

aipromptdock/providers/__init__.py

@@ -0,0 +1,34 @@
+"""Provider adapters for Claude Code, Codex CLI, and Gemini CLI."""
+
+import os
+from pathlib import Path
+
+from aipromptdock.providers.base import ProviderAdapter
+from aipromptdock.providers.claude import ClaudeAdapter
+from aipromptdock.providers.codex import CodexAdapter
+from aipromptdock.providers.gemini import GeminiAdapter
+
+__all__ = [
+    "ClaudeAdapter",
+    "CodexAdapter",
+    "GeminiAdapter",
+    "ProviderAdapter",
+    "default_adapters",
+]
+
+
+def _env_dir(var: str, default: Path) -> Path:
+    value = os.environ.get(var)
+    return Path(value).expanduser() if value else default
+
+
+def default_adapters() -> list[ProviderAdapter]:
+    """The three adapters, honoring each CLI's data-directory override."""
+    home = Path.home()
+    claude = ClaudeAdapter(_env_dir("CLAUDE_CONFIG_DIR", home / ".claude"))
+    codex = CodexAdapter(_env_dir("CODEX_HOME", home / ".codex"))
+    # Gemini directories are sha256(project path); paths known to Claude/Codex
+    # let us label Gemini prompts with real project names.
+    candidates = list(claude.iter_project_paths()) + list(codex.iter_project_paths())
+    gemini = GeminiAdapter(home / ".gemini", project_candidates=candidates)
+    return [claude, codex, gemini]

aipromptdock/providers/base.py

@@ -0,0 +1,74 @@
+"""Provider adapter contract."""
+
+import json
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+from aipromptdock.core.models import PromptEvent, ProviderId
+
+logger = logging.getLogger(__name__)
+
+
+class ProviderAdapter(ABC):
+    """Reads one CLI's on-disk prompt history.
+
+    Adapters must be defensive: the formats are undocumented internals of
+    third-party tools, so malformed lines are skipped (and logged at debug),
+    and a missing data directory simply means the provider is not detected.
+    Adapters never raise on bad data.
+    """
+
+    id: ProviderId
+    name: str
+
+    def __init__(self, data_dir: Path) -> None:
+        self.data_dir = data_dir
+
+    @property
+    def detected(self) -> bool:
+        return self.data_dir.is_dir()
+
+    @abstractmethod
+    def data_paths(self) -> list[Path]:
+        """Existing files this provider reads (doctor output + change fingerprint)."""
+
+    @abstractmethod
+    def scan(self) -> list[PromptEvent]:
+        """Parse all prompts from disk."""
+
+    def watch_filter(self, path: str) -> bool:
+        """Whether a filesystem event at ``path`` could change this provider's data."""
+        return True
+
+    def fingerprint(self) -> tuple[tuple[str, int, int], ...]:
+        """Cheap stat-based change token over everything ``scan()`` reads."""
+        stats = []
+        for p in self.data_paths():
+            try:
+                st = p.stat()
+            except OSError:
+                continue
+            stats.append((str(p), st.st_mtime_ns, st.st_size))
+        return tuple(sorted(stats))
+
+
+def iter_jsonl(path: Path) -> Iterator[dict[str, Any]]:
+    """Yield parsed objects from a JSON-Lines file, skipping malformed lines."""
+    try:
+        with path.open(encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except json.JSONDecodeError:
+                    logger.debug("Skipping malformed JSONL line in %s", path)
+                    continue
+                if isinstance(obj, dict):
+                    yield obj
+    except OSError as exc:
+        logger.debug("Cannot read %s: %s", path, exc)