scrollback 0.1.0__py3-none-any.whl

scrollback/store.py

@@ -0,0 +1,384 @@
+"""Unified store: query across all (or selected) source adapters.
+
+This is the single entry point the CLI and web app use. It composes the
+individual adapters, applies cross-source filtering/sorting, and resolves
+session selectors that may carry a `source:id` qualifier.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from .models import Message, Part, Session
+from .sources import registry
+from .sources.base import Source
+
+
+def _sort_key(s: Session) -> datetime:
+    return s.updated or s.created or datetime.min.replace(tzinfo=timezone.utc)
+
+
+@dataclass(frozen=True, slots=True)
+class SearchHit:
+    """A single search match within a session."""
+
+    session: Session
+    message: Message
+    part: Part
+    snippet: str
+
+
+@dataclass(frozen=True, slots=True)
+class Stats:
+    """Aggregate counts across sessions (see `Store.stats`)."""
+
+    sessions: int
+    per_source: dict[str, int]
+    per_project: dict[str, int]
+    total_messages: int
+    total_tokens_input: int
+    total_tokens_output: int
+    total_cost: float
+    oldest: datetime | None
+    newest: datetime | None
+
+
+class Store:
+    """Facade over one or more source adapters."""
+
+    def __init__(self, sources: list[Source] | None = None) -> None:
+        self._sources = sources if sources is not None else registry.available_sources()
+
+    @property
+    def sources(self) -> list[Source]:
+        return self._sources
+
+    def with_sources(self, names: list[str]) -> "Store":
+        """Return a Store narrowed to the named sources.
+
+        Filters THIS store's own sources rather than re-fetching from the
+        global registry, so an injected store (tests, demos) stays isolated
+        instead of silently picking up the machine's real adapters.
+        """
+        wanted = set(names)
+        chosen = [s for s in self._sources if s.name in wanted]
+        return Store(chosen)
+
+    # -- aggregate stats ----------------------------------------------------
+
+    def stats(self) -> "Stats":
+        """Aggregate session metadata across sources (metadata-only; cheap-ish).
+
+        Computes per-source and per-project session counts plus totals
+        (messages, tokens, cost) and the overall date span. Uses list-level
+        metadata only -- it does not load message bodies.
+        """
+        from collections import Counter
+
+        per_source: Counter[str] = Counter()
+        per_project: Counter[str] = Counter()
+        total_messages = 0
+        total_tokens_in = 0
+        total_tokens_out = 0
+        total_cost = 0.0
+        oldest: datetime | None = None
+        newest: datetime | None = None
+        n = 0
+
+        for s in self.list_sessions(fold_subagents=False):
+            n += 1
+            per_source[s.source] += 1
+            if s.directory:
+                per_project[s.directory] += 1
+            if s.message_count:
+                total_messages += s.message_count
+            if s.tokens_input:
+                total_tokens_in += s.tokens_input
+            if s.tokens_output:
+                total_tokens_out += s.tokens_output
+            if s.cost:
+                total_cost += s.cost
+            when = s.updated or s.created
+            if when is not None:
+                oldest = when if oldest is None or when < oldest else oldest
+                newest = when if newest is None or when > newest else newest
+
+        return Stats(
+            sessions=n,
+            per_source=dict(per_source),
+            per_project=dict(per_project),
+            total_messages=total_messages,
+            total_tokens_input=total_tokens_in,
+            total_tokens_output=total_tokens_out,
+            total_cost=total_cost,
+            oldest=oldest,
+            newest=newest,
+        )
+
+    # -- listing ------------------------------------------------------------
+
+    def list_sessions(
+        self,
+        *,
+        directory: str | None = None,
+        query: str | None = None,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        fold_subagents: bool = False,
+    ) -> list[Session]:
+        """List sessions across sources, newest first.
+
+        Args:
+          directory: keep only sessions whose directory contains this substring.
+          query: case-insensitive substring match on the title.
+          since / until: keep sessions whose updated (or created) time falls
+            within the range (inclusive).
+          limit / offset: pagination over the filtered, sorted result.
+          fold_subagents: nest subagent sessions under their parent (as
+            `.children`) instead of listing them at the top level.
+        """
+        results: list[Session] = []
+        for src in self._sources:
+            for sess in src.list_sessions():
+                if directory and (sess.directory is None or directory not in sess.directory):
+                    continue
+                if query and query.lower() not in (sess.title or "").lower():
+                    continue
+                when = sess.updated or sess.created
+                if since and (when is None or when < since):
+                    continue
+                if until and (when is None or when > until):
+                    continue
+                results.append(sess)
+        results.sort(key=_sort_key, reverse=True)
+
+        if fold_subagents:
+            results = _fold(results)
+
+        if offset:
+            results = results[offset:]
+        if limit is not None:
+            results = results[:limit]
+        return results
+
+    # -- single session -----------------------------------------------------
+
+    def _resolve(self, selector: str, source: str | None):
+        """Return (Source, full_id) for a selector, or (None, None)."""
+        src_name, sel = _split_selector(selector, source)
+        candidates = self._sources if src_name is None else [
+            s for s in self._sources if s.name == src_name
+        ]
+        for src in candidates:
+            full = src.resolve_session_id(sel)
+            if full:
+                return src, full
+        return None, None
+
+    def load_session_meta(self, selector: str, *, source: str | None = None) -> Session | None:
+        """Load only a session's metadata (no messages) -- cheap for huge ones."""
+        src, full = self._resolve(selector, source)
+        return src.load_session_meta(full) if src else None
+
+    def load_messages(
+        self, selector: str, *, source: str | None = None,
+        offset: int = 0, limit: int | None = None,
+    ) -> list[Message]:
+        """Load a windowed slice of a session's messages."""
+        src, full = self._resolve(selector, source)
+        return src.load_messages(full, offset=offset, limit=limit) if src else []
+
+    def load_session(self, selector: str, *, source: str | None = None) -> Session | None:
+        """Load one session (with all messages) by selector.
+
+        Selector may be `source:id`, a full id, a unique prefix, or 'latest'.
+        """
+        src, full = self._resolve(selector, source)
+        return src.load_session(full) if src else None
+
+    # -- search -------------------------------------------------------------
+
+    def search(
+        self,
+        query: str,
+        *,
+        directory: str | None = None,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        limit: int | None = None,
+        context: int = 80,
+        use_index: bool = True,
+    ) -> Iterator[SearchHit]:
+        """Yield hits where `query` appears in any message part.
+
+        If an FTS index exists (built via `scrollback index`) and
+        `use_index` is True, the fast indexed path is used. Otherwise this
+        falls back to a lexical scan over the live data -- zero setup, always
+        correct, but O(corpus) per query.
+        """
+        if use_index:
+            indexed = self._search_indexed(
+                query, directory=directory, since=since, until=until, limit=limit
+            )
+            if indexed is not None:
+                yield from indexed
+                return
+        yield from self._search_lexical(
+            query, directory=directory, since=since, until=until,
+            limit=limit, context=context,
+        )
+
+    def _search_indexed(
+        self, query, *, directory, since, until, limit
+    ) -> Iterator[SearchHit] | None:
+        """Indexed search. Returns None if the index is unavailable (caller
+        then falls back to lexical).
+
+        The FTS query itself is ~instant; the only expensive thing is mapping
+        a hit's session id back to session metadata. So we resolve metadata
+        *lazily* per distinct session that actually appears in results
+        (usually few), via the cheap per-adapter `load_session_meta`. We only
+        pay for a full `list_sessions` when directory/date filters are given.
+        """
+        from . import fts
+
+        index = fts.FtsIndex()
+        if not index.exists():
+            return None
+
+        source_names = [s.name for s in self._sources]
+        filtering = directory is not None or since is not None or until is not None
+        allowed: set[tuple[str, str]] | None = None
+        if filtering:
+            allowed = {
+                (s.source, s.id)
+                for s in self.list_sessions(directory=directory, since=since, until=until)
+            }
+
+        meta_cache: dict[tuple[str, str], Session | None] = {}
+
+        def meta_for(source: str, sid: str) -> Session | None:
+            k = (source, sid)
+            if k not in meta_cache:
+                src = next((s for s in self._sources if s.name == source), None)
+                meta_cache[k] = src.load_session_meta(sid) if src else None
+            return meta_cache[k]
+
+        def gen() -> Iterator[SearchHit]:
+            count = 0
+            for hit in index.search(query, sources=source_names):
+                key = (hit.source, hit.session_id)
+                if allowed is not None and key not in allowed:
+                    continue
+                meta = meta_for(hit.source, hit.session_id)
+                if meta is None:
+                    continue  # stale index entry (session deleted)
+                part = Part(id="", type=hit.part_type, text="", tool_name=hit.tool_name)
+                msg = Message(id=hit.message_id, role=hit.role, created=None, parts=(part,))
+                yield SearchHit(
+                    session=meta,
+                    message=msg,
+                    part=part,
+                    snippet=_clean_snippet(hit.text),
+                )
+                count += 1
+                if limit is not None and count >= limit:
+                    return
+
+        return gen()
+
+    def _search_lexical(
+        self, query, *, directory, since, until, limit, context
+    ) -> Iterator[SearchHit]:
+        ql = query.lower()
+        count = 0
+        for meta in self.list_sessions(directory=directory, since=since, until=until):
+            src = next((s for s in self._sources if s.name == meta.source), None)
+            if src is None:
+                continue
+            sess = src.load_session(meta.id)
+            if sess is None:
+                continue
+            for msg in sess.messages:
+                for part in msg.parts:
+                    if not part.text:
+                        continue
+                    pos = part.text.lower().find(ql)
+                    if pos == -1:
+                        continue
+                    yield SearchHit(
+                        session=sess,
+                        message=msg,
+                        part=part,
+                        snippet=_snippet(part.text, pos, len(query), context),
+                    )
+                    count += 1
+                    if limit is not None and count >= limit:
+                        return
+
+
+def _fold(sessions: list[Session]) -> list[Session]:
+    """Nest subagent sessions under their parent.
+
+    A session with a `parent_id` that matches another session's id becomes a
+    child of that parent (attached via `.children`). Subagents whose parent
+    is not in the list stay at top level so nothing is lost. Order among
+    top-level sessions is preserved; children keep newest-first order.
+    """
+    from dataclasses import replace
+
+    # Key on (source, id): ids are only unique within a source, so keying on
+    # the bare id could mis-link a parent in one source to a child in another.
+    def key(source: str, sid: str) -> tuple[str, str]:
+        return (source, sid)
+
+    by_key = {key(s.source, s.id): s for s in sessions}
+    children_of: dict[tuple[str, str], list[Session]] = {}
+    top: list[Session] = []
+    for s in sessions:
+        parent_key = key(s.source, s.parent_id) if s.parent_id else None
+        # Fold only when the parent exists AND isn't the session itself
+        # (a self-referential parent_id would otherwise drop the session).
+        if parent_key and parent_key != key(s.source, s.id) and parent_key in by_key:
+            children_of.setdefault(parent_key, []).append(s)
+        else:
+            top.append(s)
+    return [
+        replace(s, children=tuple(children_of.get(key(s.source, s.id), ())))
+        if key(s.source, s.id) in children_of
+        else s
+        for s in top
+    ]
+
+
+def _split_selector(selector: str, source: str | None) -> tuple[str | None, str]:
+    if source:
+        return source, selector
+    if ":" in selector:
+        head, _, tail = selector.partition(":")
+        if registry.get_source(head) is not None:
+            return head, tail
+    return None, selector
+
+
+def _snippet(text: str, pos: int, qlen: int, context: int) -> str:
+    start = max(0, pos - context)
+    end = min(len(text), pos + qlen + context)
+    prefix = "..." if start > 0 else ""
+    suffix = "..." if end < len(text) else ""
+    return (prefix + text[start:end] + suffix).replace("\n", " ")
+
+
+def _clean_snippet(snip: str) -> str:
+    """Normalize an FTS5 snippet for display.
+
+    The index requests snippets with \\x02/\\x03 wrapping the matched term
+    (so the frontend/CLI can re-highlight without re-searching). We strip the
+    markers here and collapse newlines; the consumers do their own
+    highlighting against the query, matching the lexical path's snippets.
+    """
+    return snip.replace("\x02", "").replace("\x03", "").replace("\n", " ").strip()

scrollback/termrender.py

@@ -0,0 +1,170 @@
+"""Optional rich-powered terminal rendering.
+
+If the `rich` package is installed and output is a TTY, these functions
+render colourful tables/transcripts; otherwise callers fall back to the
+plain renderers in cli.py. Importing this module never fails when rich is
+absent -- `available()` reports the capability.
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime
+
+from .models import Session
+from .store import SearchHit
+
+try:  # pragma: no cover - exercised indirectly
+    from rich.console import Console
+    from rich.markdown import Markdown
+    from rich.table import Table
+    from rich.text import Text
+
+    _RICH = True
+except ModuleNotFoundError:  # pragma: no cover
+    _RICH = False
+
+
+# Source -> accent colour, mirroring the web UI's source rails.
+_SRC_STYLE = {"opencode": "yellow", "claudecode": "dark_orange3"}
+
+
+def available(force: bool | None = None) -> bool:
+    """True if rich rendering should be used.
+
+    `force=True`/`False` overrides the auto-detection (used by --plain and
+    a future --color flag). Default: rich installed AND stdout is a TTY.
+    """
+    if force is not None:
+        return force and _RICH
+    return _RICH and sys.stdout.isatty()
+
+
+def _console() -> "Console":
+    return Console()
+
+
+def _src_style(source: str) -> str:
+    return _SRC_STYLE.get(source, "cyan")
+
+
+def _fmt_dt(dt: datetime | None) -> str:
+    return dt.strftime("%Y-%m-%d %H:%M") if dt else "?"
+
+
+def _fmt_tokens(n: int | None) -> str:
+    if n is None:
+        return ""
+    if n < 1000:
+        return str(n)
+    if n < 1_000_000:
+        return f"{n / 1000:.1f}k"
+    return f"{n / 1_000_000:.1f}M"
+
+
+def render_list(sessions: list[Session], *, show_usage: bool) -> None:
+    console = _console()
+    table = Table(show_header=True, header_style="bold", box=None, pad_edge=False)
+    table.add_column("source", no_wrap=True)
+    table.add_column("id", no_wrap=True, style="dim")
+    table.add_column("updated", no_wrap=True, style="dim")
+    table.add_column("msgs", justify="right", no_wrap=True)
+    if show_usage:
+        table.add_column("cost", justify="right", no_wrap=True)
+        table.add_column("tok in/out", justify="right", no_wrap=True)
+    table.add_column("title")
+
+    def add(s: Session, depth: int = 0) -> None:
+        prefix = ("  " * depth + "└ ") if depth else ""
+        row = [
+            Text(s.source, style=_src_style(s.source)),
+            s.short_id,
+            _fmt_dt(s.updated),
+            str(s.message_count if s.message_count is not None else "?"),
+        ]
+        if show_usage:
+            row.append(f"${s.cost:.2f}" if s.cost else "")
+            row.append(f"{_fmt_tokens(s.tokens_input)}/{_fmt_tokens(s.tokens_output)}")
+        row.append(Text(prefix + (s.title or "(untitled)"),
+                        style="dim" if depth else ""))
+        table.add_row(*row)
+        for child in s.children:
+            add(child, depth + 1)
+
+    for s in sessions:
+        add(s)
+    console.print(table)
+
+
+def render_search(hits: list[SearchHit], query: str) -> None:
+    console = _console()
+    ql = query.lower()
+    for h in hits:
+        head = Text()
+        head.append(f"{h.session.source}", style=_src_style(h.session.source))
+        head.append(f":{h.session.short_id} ", style="dim")
+        head.append(f"[{h.message.role}]", style="bold")
+        if h.part.tool_name:
+            head.append(f" {h.part.tool_name}", style="cyan")
+        console.print(head)
+        snippet = Text(h.snippet, style="dim")
+        # Manual highlight of all case-insensitive matches.
+        low = h.snippet.lower()
+        start = 0
+        styled = Text()
+        idx = low.find(ql, start)
+        if ql and idx != -1:
+            while idx != -1:
+                styled.append(h.snippet[start:idx], style="dim")
+                styled.append(h.snippet[idx:idx + len(query)], style="bold black on yellow")
+                start = idx + len(query)
+                idx = low.find(ql, start)
+            styled.append(h.snippet[start:], style="dim")
+            console.print("  ", styled)
+        else:
+            console.print("  ", snippet)
+
+
+def render_transcript(
+    sess: Session, *, include_reasoning: bool, include_tools: bool, markdown: bool = True
+) -> None:
+    console = _console()
+    title = Text(sess.title or "(untitled)", style="bold")
+    console.print(title)
+    meta = Text(
+        f"{sess.source}  {sess.short_id}  {_fmt_dt(sess.created)}  "
+        f"{len(sess.messages)} messages",
+        style="dim",
+    )
+    console.print(meta)
+    console.print()
+
+    for msg in sess.messages:
+        role_style = "cyan" if msg.role == "user" else "green"
+        printed_role = False
+
+        def ensure_role() -> None:
+            nonlocal printed_role
+            if not printed_role:
+                console.print(Text(msg.role.upper(), style=f"bold {role_style}"))
+                printed_role = True
+
+        for part in msg.parts:
+            if part.type == "text" and part.text:
+                ensure_role()
+                # Render assistant/user prose as Markdown (code, lists,
+                # headings, bold) when markdown is on; else plain text.
+                if markdown:
+                    console.print(Markdown(part.text))
+                else:
+                    console.print(part.text)
+            elif part.type == "reasoning" and include_reasoning and part.text:
+                ensure_role()
+                console.print(Text(part.text, style="dim italic"))
+            elif part.type == "tool" and include_tools and part.text:
+                label = part.tool_name or part.tool_status or "tool"
+                ensure_role()
+                console.print(Text(f"  $ {label}", style="yellow"))
+                console.print(Text("  " + part.text.replace("\n", "\n  "), style="dim"))
+        if printed_role:
+            console.print()

scrollback/web/__init__.py

@@ -0,0 +1 @@
+"""Local, read-only web app for browsing scrollback sessions."""