elliot-stack 1.0.17 → 1.0.19

package/skills/estack-read-claude-session-history/scripts/lib/paths.py

@@ -0,0 +1,234 @@
+"""Path resolution, project discovery, and time-spec parsing."""
+
+from __future__ import annotations
+
+import os
+import re
+from datetime import datetime, timedelta
+from pathlib import Path
+
+
+CLAUDE_DIR = Path.home() / ".claude"
+DEFAULT_LIVE_PROJECTS = CLAUDE_DIR / "projects"
+DEFAULT_BACKUPS_DIR = Path.home() / ".claude-backups"
+
+KNOWN_ROOTS = {"live", "mirror", "snapshot-24h", "snapshot-1w", "snapshot-1mo"}
+
+
+def encode_cwd(cwd: str) -> str:
+    """Convert an absolute path to the Claude project directory name.
+
+    Replaces colons, backslashes, forward slashes, and whitespace with hyphens.
+    Verified against the 34 real project dirs on this machine — no other chars
+    appear in encoded names.
+    """
+    return re.sub(r"[:\\/\s]", "-", cwd)
+
+
+def decode_project_name(encoded: str) -> str:
+    """Best-effort reverse for display.
+
+    Strips the `C--Users-<user>-` drive/home prefix when present, replaces
+    remaining hyphens with spaces, and joins path-like segments with " > ".
+
+    Falls back to the raw encoded name if the heuristic fails. Display only —
+    never use this to look up a real directory.
+    """
+    if not encoded:
+        return encoded
+
+    # Strip leading drive prefix `C--Users-<name>-`
+    m = re.match(r"^([A-Z])--Users-([^-]+)-(.+)$", encoded)
+    if m:
+        remainder = m.group(3)
+    else:
+        remainder = encoded
+
+    # Heuristic: every run of single hyphens is a path separator. The encoder
+    # mapped one `-` per separator char, so a single `-` in the original path
+    # is impossible to recover. We split on single `-` between word characters
+    # and treat the result as path segments. Multiple consecutive hyphens
+    # indicate the original had spaces+hyphens fused together — collapse to one.
+    # In practice this gives readable output like "Other Claude Code > Personal Brand Project".
+    cleaned = re.sub(r"-{2,}", "-", remainder)
+    # Words are likely separated by hyphens; segments by capitalized starts.
+    # Simple approach: just replace hyphens with spaces.
+    return cleaned.replace("-", " ").strip() or encoded
+
+
+def current_session_id() -> str | None:
+    """Return the current Claude Code session UUID from CLAUDE_SESSION_ID env var.
+
+    Returns None when called outside a Claude Code session.
+    """
+    val = os.environ.get("CLAUDE_SESSION_ID", "").strip()
+    return val or None
+
+
+def resolve_root(name: str | None) -> Path:
+    """Resolve a root name to its absolute projects directory.
+
+    - "live" (default, None) -> ~/.claude/projects
+    - "mirror" -> ~/.claude-backups/mirror/projects
+    - "snapshot-24h" -> ~/.claude-backups/snapshot-24h/projects
+    - "snapshot-1w" / "snapshot-1mo" -> analogous
+    - <absolute path> -> passes through unchanged
+    """
+    if not name or name == "live":
+        return DEFAULT_LIVE_PROJECTS
+    if name in KNOWN_ROOTS:
+        return DEFAULT_BACKUPS_DIR / name / "projects"
+    p = Path(name)
+    if p.is_absolute():
+        return p
+    raise ValueError(
+        f"Unknown root: {name!r}. Expected one of {sorted(KNOWN_ROOTS)} or an absolute path."
+    )
+
+
+def find_project_dir(cwd: str, root: Path | None = None) -> Path:
+    """Resolve a project directory under the given root.
+
+    Tries exact encoded match first, falls back to case-insensitive substring.
+    """
+    if root is None:
+        root = DEFAULT_LIVE_PROJECTS
+    encoded = encode_cwd(cwd)
+    candidate = root / encoded
+    if candidate.exists():
+        return candidate
+    if root.exists():
+        matches = [
+            d for d in root.iterdir()
+            if d.is_dir() and encoded.lower() in d.name.lower()
+        ]
+        if matches:
+            return matches[0]
+    raise FileNotFoundError(
+        f"No project directory found for cwd: {cwd}\nExpected: {candidate}"
+    )
+
+
+def list_projects(root: Path | None = None) -> list[Path]:
+    """All encoded-cwd dirs under the given root."""
+    if root is None:
+        root = DEFAULT_LIVE_PROJECTS
+    if not root.exists():
+        return []
+    return sorted([d for d in root.iterdir() if d.is_dir()], key=lambda d: d.name)
+
+
+def filter_projects(root: Path | None, name: str) -> list[Path]:
+    """Project dirs whose encoded or decoded name contains `name` (case-insensitive).
+
+    Matches against both forms so `--project "Keel Project"`, `--project
+    Keel-Project`, and `--project keel` all hit the same directory.
+    """
+    q = name.strip().lower()
+    q_encoded = q.replace(" ", "-")
+    out = []
+    for d in list_projects(root):
+        dname = d.name.lower()
+        decoded = decode_project_name(d.name).lower()
+        if q in dname or q_encoded in dname or q in decoded:
+            out.append(d)
+    return out
+
+
+def list_transcripts(
+    project_dir: Path,
+    since: datetime | None = None,
+    until: datetime | None = None,
+) -> list[Path]:
+    """Return .jsonl files in the project dir, newest first.
+
+    Excludes subagent transcripts (files starting with `agent-`).
+    """
+    if not project_dir.exists():
+        return []
+    files = [f for f in project_dir.glob("*.jsonl") if not f.name.startswith("agent-")]
+    # display_to_epoch (not .timestamp()) — naive bounds are in the display
+    # timezone, which differs from local under a --tz override.
+    from . import parser as _parser
+    if since is not None:
+        since_ts = _parser.display_to_epoch(since)
+        files = [f for f in files if f.stat().st_mtime >= since_ts]
+    if until is not None:
+        until_ts = _parser.display_to_epoch(until)
+        files = [f for f in files if f.stat().st_mtime <= until_ts]
+    files.sort(key=lambda f: f.stat().st_mtime, reverse=True)
+    return files
+
+
+def list_subagents(session_file: Path) -> list[Path]:
+    """Return subagent transcript files for a given parent session."""
+    uuid = session_file.stem
+    subagent_dir = session_file.parent / uuid / "subagents"
+    if not subagent_dir.exists():
+        return []
+    return sorted(
+        subagent_dir.glob("agent-*.jsonl"),
+        key=lambda f: f.stat().st_mtime,
+        reverse=True,
+    )
+
+
+_RELATIVE_RE = re.compile(r"^(\d+)\s*(m|h|d|w|mo)$", re.IGNORECASE)
+
+
+def parse_timespec(s: str) -> datetime:
+    """Parse a time spec into a naive datetime in the display timezone
+    (system local time unless --tz overrides it).
+
+    Accepts:
+      - ISO date: "2026-05-01"
+      - ISO datetime: "2026-05-01T14:30" or "2026-05-01 14:30"
+      - Relative: "30m", "24h", "7d", "1w", "1mo"
+      - Named: "today", "yesterday", "now"
+    """
+    if not s:
+        raise ValueError("Empty time spec")
+    s = s.strip()
+    lower = s.lower()
+    # "now" in the display timezone (== datetime.now() unless --tz is set),
+    # so that named/relative specs stay consistent with displayed times.
+    from . import parser as _parser
+    now = _parser.now_display()
+    if lower == "now":
+        return now
+    if lower == "today":
+        return now.replace(hour=0, minute=0, second=0, microsecond=0)
+    if lower == "yesterday":
+        return (now - timedelta(days=1)).replace(
+            hour=0, minute=0, second=0, microsecond=0
+        )
+    m = _RELATIVE_RE.match(s)
+    if m:
+        n = int(m.group(1))
+        unit = m.group(2).lower()
+        if unit == "m":
+            return now - timedelta(minutes=n)
+        if unit == "h":
+            return now - timedelta(hours=n)
+        if unit == "d":
+            return now - timedelta(days=n)
+        if unit == "w":
+            return now - timedelta(weeks=n)
+        if unit == "mo":
+            return now - timedelta(days=30 * n)
+    # ISO formats
+    for fmt in (
+        "%Y-%m-%dT%H:%M:%S",
+        "%Y-%m-%dT%H:%M",
+        "%Y-%m-%d %H:%M:%S",
+        "%Y-%m-%d %H:%M",
+        "%Y-%m-%d",
+    ):
+        try:
+            return datetime.strptime(s, fmt)
+        except ValueError:
+            continue
+    try:
+        return datetime.fromisoformat(s)
+    except ValueError as e:
+        raise ValueError(f"Unrecognized time spec: {s!r}") from e

package/skills/estack-read-claude-session-history/scripts/lib/search.py

@@ -0,0 +1,179 @@
+"""Unified search engine across sessions, projects, and roots."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections import namedtuple
+from datetime import datetime
+from pathlib import Path
+from typing import Iterator, Literal
+
+from . import parser as _parser
+from . import paths as _paths
+
+
+Match = namedtuple(
+    "Match",
+    ["session_path", "mtime", "role", "where", "timestamp", "window_text"],
+)
+
+
+def _block_text(block: dict, where: str) -> str:
+    """Extract searchable text for a given 'where' channel from one block."""
+    bt = block.get("type")
+    if where == "text" and bt == "text":
+        return block.get("text", "")
+    if where == "thinking" and bt == "thinking":
+        return block.get("thinking", "") or block.get("text", "")
+    if where == "tool_use" and bt == "tool_use":
+        name = block.get("name", "")
+        try:
+            inp = json.dumps(block.get("input", {}))
+        except (TypeError, ValueError):
+            inp = str(block.get("input", ""))
+        return f"[tool:{name}] {inp}"
+    if where == "tool_result" and bt == "tool_result":
+        inner = block.get("content", "")
+        if isinstance(inner, str):
+            return inner
+        if isinstance(inner, list):
+            parts = []
+            for item in inner:
+                if isinstance(item, dict) and item.get("type") == "text":
+                    parts.append(item.get("text", ""))
+            return "\n".join(parts)
+    return ""
+
+
+def _entry_search_text(obj: dict, in_channel: str) -> list[tuple[str, str]]:
+    """Return list of (where, text) for an entry filtered to in_channel."""
+    msg = obj.get("message", {})
+    if not isinstance(msg, dict):
+        return []
+    content = msg.get("content")
+    out: list[tuple[str, str]] = []
+    if isinstance(content, str):
+        if in_channel in ("text", "all"):
+            out.append(("text", content))
+        return out
+    if not isinstance(content, list):
+        return out
+    channels = ["text", "tool_use", "thinking", "tool_result"] if in_channel == "all" else [in_channel]
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        for ch in channels:
+            t = _block_text(block, ch)
+            if t:
+                out.append((ch, t))
+    return out
+
+
+def _window(text: str, q: str, n: int = 200) -> str:
+    """Return up to n chars of context around the first match of q."""
+    if not text or not q:
+        return ""
+    lower = text.lower()
+    idx = lower.find(q.lower())
+    if idx == -1:
+        return text[:n]
+    start = max(0, idx - n // 2)
+    end = min(len(text), idx + len(q) + n // 2)
+    window = text[start:end]
+    prefix = "…" if start > 0 else ""
+    suffix = "…" if end < len(text) else ""
+    return prefix + window + suffix
+
+
+def search_session(
+    path: Path,
+    query: str,
+    role: Literal["user", "assistant", "both"] = "both",
+    in_channel: Literal["text", "tool_use", "thinking", "all"] = "text",
+    since: datetime | None = None,
+    until: datetime | None = None,
+) -> list[Match]:
+    """Search one transcript file. Returns ordered matches."""
+    lines = _parser.parse_lines(path)
+    try:
+        mtime = path.stat().st_mtime
+    except OSError:
+        mtime = 0
+    matches: list[Match] = []
+    q = query.lower()
+    for obj in lines:
+        cls = _parser.classify_entry(obj)
+        if cls == "noise" or cls == "title":
+            continue
+        msg_role = "user" if cls in ("user", "compact") else "assistant"
+        if role != "both" and msg_role != role:
+            continue
+        ts = obj.get("timestamp")
+        ts_dt = None
+        if since is not None or until is not None:
+            ts_dt = _parser._parse_timestamp(ts)
+            if ts_dt is None:
+                continue
+            if ts_dt.tzinfo is not None:
+                ts_dt = ts_dt.replace(tzinfo=None)
+            if since is not None and ts_dt < since:
+                continue
+            if until is not None and ts_dt > until:
+                continue
+        for where, text in _entry_search_text(obj, in_channel):
+            if q in text.lower():
+                matches.append(Match(
+                    session_path=path,
+                    mtime=mtime,
+                    role=msg_role,
+                    where=where,
+                    timestamp=ts,
+                    window_text=_window(text, query),
+                ))
+    return matches
+
+
+def search_project(
+    project_dir: Path,
+    query: str,
+    role: Literal["user", "assistant", "both"] = "both",
+    in_channel: Literal["text", "tool_use", "thinking", "all"] = "text",
+    since: datetime | None = None,
+    until: datetime | None = None,
+    progress: bool = True,
+) -> Iterator[Match]:
+    """Search every transcript in a project directory, newest first."""
+    files = _paths.list_transcripts(project_dir, since=since, until=until)
+    for i, f in enumerate(files, 1):
+        if progress:
+            print(
+                f"Searching {i}/{len(files)}: {f.name}...",
+                file=sys.stderr,
+                end="\r",
+            )
+        try:
+            for m in search_session(f, query, role, in_channel, since, until):
+                yield m
+        except Exception as e:
+            print(f"\nError reading {f.name}: {e}", file=sys.stderr)
+    if progress:
+        print(file=sys.stderr)
+
+
+def search_all_projects(
+    root: Path,
+    query: str,
+    role: Literal["user", "assistant", "both"] = "both",
+    in_channel: Literal["text", "tool_use", "thinking", "all"] = "text",
+    since: datetime | None = None,
+    until: datetime | None = None,
+    progress: bool = True,
+) -> Iterator[Match]:
+    """Walk every project directory under root."""
+    for project_dir in _paths.list_projects(root):
+        if progress:
+            print(f"--- {project_dir.name} ---", file=sys.stderr)
+        yield from search_project(
+            project_dir, query, role, in_channel, since, until, progress
+        )

package/skills/estack-read-claude-session-history/scripts/lib/subagents.py

@@ -0,0 +1,88 @@
+"""Subagent transcript discovery and metadata loading."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from . import parser as _parser
+from . import paths as _paths
+from . import tools as _tools
+
+
+def load_meta(agent_path: Path) -> dict:
+    """Read the sibling agent-<id>.meta.json sidecar.
+
+    Returns {"agentType": "unknown", "description": ""} on miss.
+    """
+    meta_path = agent_path.with_suffix(".meta.json")
+    if not meta_path.exists():
+        # Some sidecars use .meta.json appended to full name
+        alt = agent_path.parent / f"{agent_path.stem}.meta.json"
+        if alt.exists():
+            meta_path = alt
+        else:
+            return {"agentType": "unknown", "description": ""}
+    try:
+        with open(meta_path, encoding="utf-8") as f:
+            data = json.load(f)
+        return {
+            "agentType": data.get("agentType", data.get("subagent_type", "unknown")),
+            "description": data.get("description", ""),
+        }
+    except (OSError, json.JSONDecodeError):
+        return {"agentType": "unknown", "description": ""}
+
+
+def _last_assistant_text(path: Path) -> str:
+    """Pull the last assistant text from a subagent transcript."""
+    lines = _parser.parse_lines(path)
+    messages = _parser.get_messages(lines)
+    for m in reversed(messages):
+        if m["role"] == "assistant" and m["texts"]:
+            return "\n".join(m["texts"])
+    return ""
+
+
+def agent_finals(parent_session: Path) -> list[tuple[str, dict, str]]:
+    """For each subagent of a session: (agent_id, meta, last_assistant_text)."""
+    out: list[tuple[str, dict, str]] = []
+    for sa in _paths.list_subagents(parent_session):
+        agent_id = sa.stem  # e.g., "agent-xxxx"
+        meta = load_meta(sa)
+        text = _last_assistant_text(sa)
+        out.append((agent_id, meta, text))
+    return out
+
+
+def agent_tools(agent_path: Path, tool_filter: Optional[set[str]] = None) -> list[dict]:
+    return _tools.extract_tool_calls(_parser.parse_lines(agent_path), tool_filter)
+
+
+def agent_files(agent_path: Path) -> dict[Path, list[str]]:
+    return _tools.files_touched(_parser.parse_lines(agent_path))
+
+
+def group_by_parent(
+    root: Path, agent_type_filter: Optional[str] = None
+) -> dict[Path, list[tuple[Path, dict]]]:
+    """For every parent session under root, list its subagents + meta.
+
+    Optionally filter by agentType.
+    """
+    out: dict[Path, list[tuple[Path, dict]]] = {}
+    for project_dir in _paths.list_projects(root):
+        for parent in _paths.list_transcripts(project_dir):
+            subs = _paths.list_subagents(parent)
+            if not subs:
+                continue
+            entries = []
+            for sa in subs:
+                meta = load_meta(sa)
+                if agent_type_filter and meta["agentType"] != agent_type_filter:
+                    continue
+                entries.append((sa, meta))
+            if entries:
+                out[parent] = entries
+    return out

package/skills/estack-read-claude-session-history/scripts/lib/tools.py

@@ -0,0 +1,144 @@
+"""Tool-call extraction, per-tool formatting, and tool-result lookup."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+
+def extract_tool_calls(
+    lines: list[dict], tool_filter: Optional[set[str]] = None
+) -> list[dict]:
+    """Every tool_use block with timestamp and parent line index.
+
+    Returns list of dicts: {name, input, id, timestamp, line_index}.
+    """
+    out = []
+    for i, obj in enumerate(lines):
+        msg = obj.get("message", {})
+        if not isinstance(msg, dict):
+            continue
+        content = msg.get("content")
+        if not isinstance(content, list):
+            continue
+        ts = obj.get("timestamp")
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") != "tool_use":
+                continue
+            name = block.get("name", "")
+            if tool_filter and name not in tool_filter:
+                continue
+            out.append({
+                "name": name,
+                "input": block.get("input", {}) or {},
+                "id": block.get("id", ""),
+                "timestamp": ts,
+                "line_index": i,
+            })
+    return out
+
+
+def _first_line(s: str, n: int = 200) -> str:
+    if not s:
+        return ""
+    line = s.splitlines()[0] if s.splitlines() else s
+    return line if len(line) <= n else line[: n - 1] + "…"
+
+
+def format_tool_call(call: dict) -> str:
+    """Per-tool human-readable one-liner."""
+    name = call.get("name", "?")
+    inp = call.get("input", {}) or {}
+
+    if name in ("Bash", "PowerShell"):
+        cmd = inp.get("command", "")
+        return f"{name}: {_first_line(cmd, 200)}"
+    if name == "Read":
+        fp = inp.get("file_path", "")
+        offset = inp.get("offset")
+        limit = inp.get("limit")
+        if offset is not None or limit is not None:
+            o = offset or 1
+            l = limit or 0
+            return f"Read {fp} (lines {o}-{o + l if l else '?'})"
+        return f"Read {fp}"
+    if name == "Edit":
+        fp = inp.get("file_path", "")
+        edits = inp.get("edits")
+        if isinstance(edits, list):
+            return f"Edit {fp} ({len(edits)} edits)"
+        return f"Edit {fp}"
+    if name == "Write":
+        fp = inp.get("file_path", "")
+        content = inp.get("content", "")
+        return f"Write {fp} ({len(content)} chars)"
+    if name in ("Agent", "Task"):
+        sub = inp.get("subagent_type") or inp.get("agentType") or "?"
+        desc = inp.get("description", "")
+        return f"{name}[{sub}]: {_first_line(desc, 200)}"
+    if name == "Skill":
+        sk = inp.get("skill", "")
+        args = inp.get("args", "")
+        if args:
+            return f"Skill: {sk} {_first_line(str(args), 100)}"
+        return f"Skill: {sk}"
+    if name == "Glob":
+        pat = inp.get("pattern", "")
+        return f"Glob: {pat}"
+    if name == "Grep":
+        pat = inp.get("pattern", "")
+        return f"Grep: {pat}"
+    try:
+        preview = json.dumps(inp)[:200]
+    except (TypeError, ValueError):
+        preview = str(inp)[:200]
+    return f"{name}: {preview}"
+
+
+def extract_tool_results(
+    lines: list[dict], tool_use_id: str
+) -> Optional[str]:
+    """Find the tool_result block whose tool_use_id matches the given id."""
+    if not tool_use_id:
+        return None
+    for obj in lines:
+        msg = obj.get("message", {})
+        if not isinstance(msg, dict):
+            continue
+        content = msg.get("content")
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") != "tool_result":
+                continue
+            if block.get("tool_use_id") != tool_use_id:
+                continue
+            inner = block.get("content", "")
+            if isinstance(inner, str):
+                return inner
+            if isinstance(inner, list):
+                parts = []
+                for sub in inner:
+                    if isinstance(sub, dict) and sub.get("type") == "text":
+                        parts.append(sub.get("text", ""))
+                return "\n".join(parts)
+    return None
+
+
+def files_touched(lines: list[dict]) -> dict[Path, list[str]]:
+    """Map of file paths to the list of operations performed on them."""
+    out: dict[str, list[str]] = {}
+    for call in extract_tool_calls(lines):
+        name = call["name"]
+        inp = call.get("input", {}) or {}
+        if name in ("Edit", "Write", "Read", "NotebookEdit"):
+            fp = inp.get("file_path") or inp.get("notebook_path", "")
+            if fp:
+                out.setdefault(fp, []).append(name)
+    # Convert to Path keys
+    return {Path(k): v for k, v in out.items()}