copilot-session-usage 0.1.0__py3-none-any.whl

copilot_session_usage/_internal/vscode.py

@@ -0,0 +1,242 @@
+"""VS Code Copilot session discovery logic.
+
+Implements workspace storage layout parsing, state.vscdb queries, and
+session directory resolution for the VS Code Copilot extension.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import sys
+from pathlib import Path
+from typing import Any
+
+# ─── Workspace DB cache ─────────────────────────────────────────────────────
+
+_WS_DB_CACHE: dict[str, list[dict]] = {}
+
+
+# ─── Workspace storage path resolution (cross-platform) ─────────────────────
+
+
+def default_workspace_storage_roots() -> list[Path]:
+    r"""Return all existing workspaceStorage directories for the current platform.
+
+    Checked locations:
+
+    - macOS:   ~/Library/Application Support/Code{,-Insiders}/User/workspaceStorage
+    - Windows: %APPDATA%\\Code{,-Insiders}\\User\\workspaceStorage
+    - Linux:   $XDG_CONFIG_HOME/Code{,-Insiders}/User/workspaceStorage
+               ~/.vscode-server{,-insiders}/data/User/workspaceStorage  (WSL2 / remote)
+
+    Only directories that actually exist are returned.
+    """
+    home = Path.home()
+    candidates: list[Path] = []
+
+    if sys.platform == "darwin":
+        base = home / "Library" / "Application Support"
+        for variant in ("Code", "Code - Insiders"):
+            candidates.append(base / variant / "User" / "workspaceStorage")
+
+    elif sys.platform == "win32":
+        appdata = Path(os.environ.get("APPDATA") or (home / "AppData" / "Roaming"))
+        for variant in ("Code", "Code - Insiders"):
+            candidates.append(appdata / variant / "User" / "workspaceStorage")
+
+    else:
+        xdg = Path(os.environ.get("XDG_CONFIG_HOME") or (home / ".config"))
+        for variant in ("Code", "Code - Insiders"):
+            candidates.append(xdg / variant / "User" / "workspaceStorage")
+        for variant in (".vscode-server", ".vscode-server-insiders"):
+            candidates.append(home / variant / "data" / "User" / "workspaceStorage")
+
+    return [p for p in candidates if p.is_dir()]
+
+
+def _get_workspace_folder(ws_dir: Path) -> str:
+    """Return the actual folder path for a workspace storage directory."""
+    ws_json = ws_dir / "workspace.json"
+    if ws_json.exists():
+        try:
+            data: dict[str, Any] = json.loads(ws_json.read_text(encoding="utf-8"))
+            folder = data.get("folder") or data.get("workspace", "")
+            if isinstance(folder, str):
+                return folder.removeprefix("file://") if folder.startswith("file://") else folder
+        except (json.JSONDecodeError, OSError):
+            pass
+    return ""
+
+
+def get_sessions_from_workspace(ws_dir: Path, use_cache: bool = True) -> list[dict]:
+    """Return session metadata from a workspace's state.vscdb.
+
+    When ``use_cache`` is True (the default), results are cached per
+    workspace directory so batch operations only read each DB once.
+    """
+    cache_key = str(ws_dir.resolve())
+    if use_cache and cache_key in _WS_DB_CACHE:
+        return _WS_DB_CACHE[cache_key]
+
+    db_path = ws_dir / "state.vscdb"
+    if not db_path.exists():
+        return []
+    try:
+        conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
+        cur = conn.execute("SELECT value FROM ItemTable WHERE key = 'chat.ChatSessionStore.index'")
+        row = cur.fetchone()
+        conn.close()
+    except (sqlite3.OperationalError, sqlite3.DatabaseError):
+        return []
+    if not row:
+        return []
+    try:
+        data = json.loads(row[0])
+    except json.JSONDecodeError:
+        return []
+
+    workspace_folder = _get_workspace_folder(ws_dir)
+    sessions = []
+    for v in data.get("entries", {}).values():
+        session_id = v.get("sessionId", "")
+        if not session_id:
+            continue
+        debug_log_dir = ws_dir / "GitHub.copilot-chat/debug-logs" / session_id
+        sessions.append(
+            {
+                "session_id": session_id,
+                "title": v.get("title", ""),
+                "workspace_folder": workspace_folder,
+                "workspace_hash": ws_dir.name,
+                "created_ms": v.get("timing", {}).get("created"),
+                "last_message_ms": v.get("lastMessageDate"),
+                "has_debug_logs": debug_log_dir.exists(),
+                "debug_log_dir": str(debug_log_dir),
+            }
+        )
+
+    if use_cache:
+        _WS_DB_CACHE[cache_key] = sessions
+    return sessions
+
+
+def find_session_dir_by_id(session_id: str, ws_roots: list[Path]) -> Path | None:
+    """Search ws_roots for a debug log directory matching session_id."""
+    for ws_dir in ws_roots:
+        if not ws_dir.is_dir():
+            continue
+        for candidate in ws_dir.iterdir():
+            if not candidate.is_dir():
+                continue
+            log_dir = candidate / "GitHub.copilot-chat" / "debug-logs" / session_id
+            if log_dir.exists():
+                return log_dir
+    return None
+
+
+def find_sessions_by_title(title: str, ws_roots: list[Path]) -> list[dict]:
+    """Search ws_roots for sessions whose title contains the given string."""
+    lower = title.lower()
+    matches: list[dict] = []
+    for ws_dir in ws_roots:
+        if not ws_dir.is_dir():
+            continue
+        for ws_sub in ws_dir.iterdir():
+            if not ws_sub.is_dir():
+                continue
+            for session in get_sessions_from_workspace(ws_sub, use_cache=True):
+                if lower in session.get("title", "").lower():
+                    matches.append(session)
+    return sorted(matches, key=lambda s: s.get("created_ms") or 0, reverse=True)
+
+
+def find_latest_session_dir(
+    ws_roots: list[Path], workspace_filter: str | None = None
+) -> Path | None:
+    """Return the most recently modified debug log directory across ws_roots."""
+    latest: Path | None = None
+    latest_mtime = 0.0
+    for ws_dir in ws_roots:
+        if not ws_dir.is_dir():
+            continue
+        for ws_sub in ws_dir.iterdir():
+            if not ws_sub.is_dir():
+                continue
+            if workspace_filter:
+                folder = _get_workspace_folder(ws_sub)
+                if workspace_filter not in folder:
+                    continue
+            debug_logs_base = ws_sub / "GitHub.copilot-chat" / "debug-logs"
+            if not debug_logs_base.exists():
+                continue
+            for session_dir in debug_logs_base.iterdir():
+                if not session_dir.is_dir():
+                    continue
+                mtime = session_dir.stat().st_mtime
+                if mtime > latest_mtime:
+                    latest_mtime = mtime
+                    latest = session_dir
+    return latest
+
+
+def list_recent_sessions(
+    ws_roots: list[Path],
+    limit: int = 20,
+    since_ms: int | None = None,
+    workspace_filter: str | None = None,
+    require_logs: bool = False,
+) -> list[dict]:
+    """List sessions from ws_roots, sorted most-recent first.
+
+    When ``require_logs`` is True, only sessions with existing debug logs
+    are returned (useful for batch analysis).
+    """
+    from copilot_session_usage._internal import core
+
+    all_sessions: list[dict] = []
+    for ws_dir in ws_roots:
+        if not ws_dir.is_dir():
+            continue
+        for ws_sub in ws_dir.iterdir():
+            if not ws_sub.is_dir():
+                continue
+            for session in get_sessions_from_workspace(ws_sub, use_cache=True):
+                if since_ms and (session.get("created_ms") or 0) < since_ms:
+                    continue
+                if workspace_filter and workspace_filter not in session.get("workspace_folder", ""):
+                    continue
+                if require_logs and not session.get("has_debug_logs"):
+                    continue
+                session["created_at"] = core.ts_to_iso(session.get("created_ms"))
+                session["last_activity_at"] = core.ts_to_iso(session.get("last_message_ms"))
+                all_sessions.append(session)
+    all_sessions.sort(key=lambda s: s.get("created_ms") or 0, reverse=True)
+    return all_sessions[:limit]
+
+
+def resolve_ws_roots(workspace_storage: str | None) -> list[Path]:
+    """Resolve workspaceStorage roots from an explicit override or auto-detection."""
+    if workspace_storage:
+        root = Path(workspace_storage)
+        if not root.is_dir():
+            msg = f"--workspace-storage path not found: {root}"
+            raise click.ClickException(msg)
+        return [root]
+    roots = default_workspace_storage_roots()
+    if not roots:
+        msg = (
+            "No workspaceStorage directory found for this platform.\n"
+            "Pass --workspace-storage PATH to specify the location manually.\n"
+            "Common paths:\n"
+            "  macOS:   ~/Library/Application Support/Code/User/workspaceStorage\n"
+            "  Linux:   ~/.config/Code/User/workspaceStorage\n"
+            "  Windows: %APPDATA%\\Code\\User\\workspaceStorage\n"
+            "  WSL2:    /mnt/c/Users/<you>/AppData/Roaming/Code/User/workspaceStorage"
+        )
+        raise click.ClickException(msg)
+    return roots
+
+
+import click  # noqa: E402

copilot_session_usage/api.py

@@ -0,0 +1,211 @@
+"""Public Python API for copilot-session-usage.
+
+All functions accept an optional ``agent`` parameter for future routing
+between VS Code and Copilot-CLI providers.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from copilot_session_usage._internal import core, vscode
+
+
+def analyze_session(path: Path, detail: str = "compact", agent: str = "vscode") -> dict:
+    """Analyze one session by its debug-log directory path.
+
+    Args:
+        path: Path to the session's debug-log directory.
+        detail: ``minimal``, ``compact`` (default), or ``full``.
+        agent: Provider to use (``vscode`` or ``cli``).
+
+    Returns:
+        Session analysis dict shaped to the requested detail level.
+
+    Raises:
+        NotImplementedError: If ``agent`` is ``"cli"``.
+    """
+    if agent == "cli":
+        raise NotImplementedError("Copilot-CLI support is not yet implemented.")
+    pricing = core.load_pricing()
+    result = core.analyze_session(Path(path), pricing)
+    return core.shape_session(result, detail)
+
+
+def list_sessions(
+    workspace_roots: list[Path] | None = None,
+    limit: int = 20,
+    since: str | None = None,
+    workspace_filter: str | None = None,
+    agent: str = "vscode",
+) -> list[dict]:
+    """List recent sessions (metadata only, no JSONL reads).
+
+    Args:
+        workspace_roots: Override workspaceStorage directories.
+            Auto-detected if None.
+        limit: Maximum sessions to return.
+        since: Only sessions created after this date (YYYY-MM-DD or ISO 8601).
+        workspace_filter: Only sessions from this workspace folder.
+        agent: Provider to use (``vscode`` or ``cli``).
+
+    Returns:
+        List of session metadata dicts, most-recent first.
+    """
+    if agent == "cli":
+        raise NotImplementedError("Copilot-CLI support is not yet implemented.")
+
+    if workspace_roots is None:
+        workspace_roots = vscode.default_workspace_storage_roots()
+
+    since_ms = core.parse_since_to_ms(since) if since else None
+    return vscode.list_recent_sessions(
+        workspace_roots,
+        limit=limit,
+        since_ms=since_ms,
+        workspace_filter=workspace_filter,
+    )
+
+
+def find_sessions_by_title(
+    title: str,
+    workspace_roots: list[Path] | None = None,
+    agent: str = "vscode",
+) -> list[dict]:
+    """Fuzzy-match sessions by title substring.
+
+    Args:
+        title: Substring to search for (case-insensitive).
+        workspace_roots: Override workspaceStorage directories.
+        agent: Provider to use (``vscode`` or ``cli``).
+
+    Returns:
+        Matching session metadata dicts, most-recent first.
+    """
+    if agent == "cli":
+        raise NotImplementedError("Copilot-CLI support is not yet implemented.")
+
+    if workspace_roots is None:
+        workspace_roots = vscode.default_workspace_storage_roots()
+
+    return vscode.find_sessions_by_title(title, workspace_roots)
+
+
+def find_session_by_id(
+    session_id: str, workspace_roots: list[Path] | None = None, agent: str = "vscode"
+) -> dict | None:
+    """Analyze a session by its exact UUID.
+
+    Args:
+        session_id: The session UUID.
+        workspace_roots: Override workspaceStorage directories.
+        agent: Provider to use (``vscode`` or ``cli``).
+
+    Returns:
+        Session analysis dict, or None if not found.
+    """
+    if agent == "cli":
+        raise NotImplementedError("Copilot-CLI support is not yet implemented.")
+
+    if workspace_roots is None:
+        workspace_roots = vscode.default_workspace_storage_roots()
+
+    session_dir = vscode.find_session_dir_by_id(session_id, workspace_roots)
+    if session_dir is None:
+        return None
+    pricing = core.load_pricing()
+    return core.analyze_session(session_dir, pricing)
+
+
+def analyze_latest(
+    workspace_roots: list[Path] | None = None,
+    detail: str = "compact",
+    workspace_filter: str | None = None,
+    agent: str = "vscode",
+) -> dict:
+    """Analyze the most recently modified session.
+
+    Args:
+        workspace_roots: Override workspaceStorage directories.
+        detail: ``minimal``, ``compact`` (default), or ``full``.
+        workspace_filter: Only sessions from this workspace folder.
+        agent: Provider to use (``vscode`` or ``cli``).
+
+    Returns:
+        Session analysis dict shaped to the requested detail level.
+
+    Raises:
+        ValueError: If no sessions are found.
+    """
+    if agent == "cli":
+        raise NotImplementedError("Copilot-CLI support is not yet implemented.")
+
+    if workspace_roots is None:
+        workspace_roots = vscode.default_workspace_storage_roots()
+
+    session_dir = vscode.find_latest_session_dir(workspace_roots, workspace_filter=workspace_filter)
+    if session_dir is None:
+        raise ValueError("No session debug logs found in workspace storage.")
+    pricing = core.load_pricing()
+    result = core.analyze_session(session_dir, pricing)
+    return core.shape_session(result, detail)
+
+
+def batch_analyze(
+    n: int,
+    workspace_roots: list[Path] | None = None,
+    detail: str = "compact",
+    since: str | None = None,
+    workspace_filter: str | None = None,
+    agent: str = "vscode",
+) -> dict:
+    """Analyze the N most recent sessions.
+
+    Args:
+        n: Number of sessions to analyze.
+        workspace_roots: Override workspaceStorage directories.
+        detail: ``minimal``, ``compact`` (default), or ``full``.
+        since: Only sessions created after this date.
+        workspace_filter: Only sessions from this workspace folder.
+        agent: Provider to use (``vscode`` or ``cli``).
+
+    Returns:
+        Dict with ``summary`` (aggregate) and ``sessions`` (per-session list).
+    """
+    if agent == "cli":
+        raise NotImplementedError("Copilot-CLI support is not yet implemented.")
+
+    if workspace_roots is None:
+        workspace_roots = vscode.default_workspace_storage_roots()
+
+    since_ms = core.parse_since_to_ms(since) if since else None
+    sessions = vscode.list_recent_sessions(
+        workspace_roots,
+        limit=n,
+        since_ms=since_ms,
+        workspace_filter=workspace_filter,
+        require_logs=True,
+    )
+    pricing = core.load_pricing()
+    results: list[dict] = []
+    for session in sessions:
+        session_dir = Path(session["debug_log_dir"])
+        if not session_dir.exists():
+            continue
+        result = core.analyze_session(session_dir, pricing)
+        result["title"] = session.get("title") or result.get("title")
+        results.append(result)
+    return core.shape_batch(results, detail)
+
+
+def load_pricing(ref_dir: Path | None = None) -> dict:
+    """Load pricing data.
+
+    Args:
+        ref_dir: Directory containing pricing YAML files. If None, uses
+            the bundled data directory shipped with the package.
+
+    Returns:
+        Pricing dict with model rates.
+    """
+    return core.load_pricing(ref_dir)