scrollback 0.1.0__py3-none-any.whl

scrollback/clipboard.py

@@ -0,0 +1,34 @@
+"""Cross-platform clipboard copy using only stdlib + OS utilities.
+
+Falls back gracefully: on macOS uses `pbcopy`, on Linux `wl-copy`/`xclip`/
+`xsel`, on Windows `clip`. Returns True on success.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+
+
+def _candidates() -> list[list[str]]:
+    if sys.platform == "darwin":
+        return [["pbcopy"]]
+    if sys.platform == "win32":
+        return [["clip"]]
+    # Linux / BSD: prefer Wayland, then X11 tools.
+    return [["wl-copy"], ["xclip", "-selection", "clipboard"], ["xsel", "--clipboard", "--input"]]
+
+
+def copy(text: str) -> bool:
+    """Copy `text` to the system clipboard. Returns True if it worked."""
+    for cmd in _candidates():
+        if shutil.which(cmd[0]) is None:
+            continue
+        try:
+            proc = subprocess.run(cmd, input=text.encode("utf-8"), check=False)
+            if proc.returncode == 0:
+                return True
+        except OSError:
+            continue
+    return False

scrollback/export.py

@@ -0,0 +1,293 @@
+"""Render a Session to portable formats: markdown, json, html, text.
+
+These are pure functions from a Session to a string, so they are trivial
+to test and to reuse from both the CLI (export/copy) and the web app.
+"""
+
+from __future__ import annotations
+
+import html as _html
+import json
+from dataclasses import asdict
+from datetime import datetime
+
+from . import minimd
+from .models import Message, Part, Session
+
+_ROLE_LABEL = {
+    "user": "User",
+    "assistant": "Assistant",
+    "system": "System",
+    "tool": "Tool",
+}
+
+
+def _fmt_dt(dt: datetime | None) -> str:
+    return dt.strftime("%Y-%m-%d %H:%M:%S %Z").strip() if dt else "?"
+
+
+# -- markdown --------------------------------------------------------------
+
+
+def to_markdown(session: Session, *, include_reasoning: bool = True,
+                include_tools: bool = True, math: str = "raw") -> str:
+    # Markdown export is verbatim text, so delimited LaTeX is already
+    # preserved exactly; `math` is accepted for a uniform CLI/web surface
+    # but does not transform the source (there is nothing to typeset in a
+    # plain .md file).
+    del math
+    lines: list[str] = []
+    lines.append(f"# {session.title}")
+    lines.append("")
+    lines.append(f"- **Source**: {session.source}")
+    lines.append(f"- **Session**: `{session.id}`")
+    if session.directory:
+        lines.append(f"- **Directory**: `{session.directory}`")
+    if session.model:
+        lines.append(f"- **Model**: {session.model}")
+    if session.agent:
+        lines.append(f"- **Agent**: {session.agent}")
+    lines.append(f"- **Created**: {_fmt_dt(session.created)}")
+    lines.append(f"- **Updated**: {_fmt_dt(session.updated)}")
+    lines.append(f"- **Messages**: {len(session.messages)}")
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+
+    for msg in session.messages:
+        rendered = _markdown_message(msg, include_reasoning, include_tools)
+        if rendered:
+            lines.append(rendered)
+            lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _markdown_message(msg: Message, include_reasoning: bool, include_tools: bool) -> str:
+    blocks: list[str] = []
+    header = f"## {_ROLE_LABEL.get(msg.role, msg.role)}"
+    when = _fmt_dt(msg.created)
+    if when != "?":
+        header += f"  \n*{when}*"
+    blocks.append(header)
+    for part in msg.parts:
+        b = _markdown_part(part, include_reasoning, include_tools)
+        if b:
+            blocks.append(b)
+    # Only emit the message if it has content beyond the header.
+    return "\n\n".join(blocks) if len(blocks) > 1 else ""
+
+
+def _markdown_part(part: Part, include_reasoning: bool, include_tools: bool) -> str:
+    if part.type == "text":
+        return part.text
+    if part.type == "reasoning":
+        if not include_reasoning or not part.text:
+            return ""
+        return "> **reasoning**\n>\n" + "\n".join(f"> {ln}" for ln in part.text.splitlines())
+    if part.type == "tool":
+        if not include_tools or not part.text:
+            return ""
+        label = part.tool_name or part.tool_status or "tool"
+        status = f" ({part.tool_status})" if part.tool_status and part.tool_name else ""
+        return f"**tool: {label}{status}**\n\n```\n{part.text}\n```"
+    return ""
+
+
+# -- json ------------------------------------------------------------------
+
+
+def to_json(session: Session, *, indent: int = 2) -> str:
+    def default(o: object) -> object:
+        if isinstance(o, datetime):
+            return o.isoformat()
+        return str(o)
+
+    payload = asdict(session)
+    # Drop bulky raw blobs from the default JSON export for readability.
+    payload.pop("raw", None)
+    for m in payload.get("messages", []):
+        m.pop("raw", None)
+        for p in m.get("parts", []):
+            p.pop("raw", None)
+    return json.dumps(payload, indent=indent, default=default, ensure_ascii=False)
+
+
+# -- text ------------------------------------------------------------------
+
+
+def to_text(session: Session, *, include_reasoning: bool = False,
+            include_tools: bool = True, math: str = "raw") -> str:
+    # Plain-text export is verbatim; LaTeX is preserved as-is. `math` is a
+    # no-op here (kept for a uniform export surface).
+    del math
+    lines = [session.title, "=" * len(session.title), ""]
+    for msg in session.messages:
+        role = _ROLE_LABEL.get(msg.role, msg.role).upper()
+        chunk: list[str] = []
+        for part in msg.parts:
+            if part.type == "text" and part.text:
+                chunk.append(part.text)
+            elif part.type == "reasoning" and include_reasoning and part.text:
+                chunk.append(f"[reasoning] {part.text}")
+            elif part.type == "tool" and include_tools and part.text:
+                label = part.tool_name or part.tool_status or "tool"
+                chunk.append(f"[tool:{label}] {part.text}")
+        if chunk:
+            lines.append(f"--- {role} ---")
+            lines.append("\n".join(chunk))
+            lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+# -- html ------------------------------------------------------------------
+
+_HTML_TEMPLATE = """<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{title}</title>
+<style>
+:root {{ color-scheme: light dark; }}
+body {{ font: 15px/1.6 -apple-system, system-ui, sans-serif; max-width: 820px;
+        margin: 2rem auto; padding: 0 1rem; }}
+.meta {{ color: #888; font-size: 13px; margin-bottom: 1.5rem; }}
+.msg {{ border-radius: 10px; padding: .75rem 1rem; margin: .75rem 0; }}
+.user {{ background: rgba(120,140,255,.12); }}
+.assistant {{ background: rgba(140,140,140,.10); }}
+.role {{ font-weight: 600; font-size: 12px; text-transform: uppercase;
+         letter-spacing: .05em; opacity: .7; }}
+.reasoning {{ opacity: .65; font-style: italic; border-left: 3px solid #aaa;
+              padding-left: .75rem; margin: .5rem 0; }}
+.tool {{ background: rgba(0,0,0,.06); border-radius: 6px; padding: .5rem .75rem;
+         margin: .5rem 0; }}
+pre {{ white-space: pre-wrap; word-break: break-word; margin: .25rem 0; }}
+.tool-name {{ font-size: 12px; font-weight: 600; opacity: .7; }}
+/* rendered markdown */
+.md > *:first-child {{ margin-top: 0; }}
+.md > *:last-child {{ margin-bottom: 0; }}
+.md h1, .md h2, .md h3, .md h4 {{ line-height: 1.3; margin: 1em 0 .4em; }}
+.md h1 {{ font-size: 1.5em; }} .md h2 {{ font-size: 1.3em; }}
+.md h3 {{ font-size: 1.12em; }} .md h4 {{ font-size: 1em; }}
+.md p {{ margin: .5em 0; }}
+.md ul, .md ol {{ margin: .4em 0; padding-left: 1.5em; }}
+.md li {{ margin: .15em 0; }}
+.md a {{ color: #2a6fb0; }}
+.md blockquote {{ margin: .5em 0; padding: .15em 0 .15em 1em;
+                  border-left: 3px solid #ccc; color: #777; }}
+.md hr {{ border: none; border-top: 1px solid #ccc; margin: 1em 0; }}
+.md code {{ font-family: ui-monospace, Menlo, Consolas, monospace; font-size: .88em;
+            background: rgba(127,127,127,.18); border-radius: 4px; padding: .1em .35em; }}
+.md pre {{ background: rgba(127,127,127,.12); border: 1px solid rgba(127,127,127,.25);
+           border-radius: 8px; padding: .7rem .9rem; overflow-x: auto; }}
+.md pre code {{ background: none; padding: 0; }}
+.math-src {{ font-family: ui-monospace, Menlo, Consolas, monospace; font-size: .9em;
+             background: rgba(127,127,127,.18); border-radius: 4px; padding: .1em .35em; }}
+.math-display {{ display: block; text-align: center; margin: .6em 0; overflow-x: auto; }}
+{hl_css}
+@media print {{
+  body {{ max-width: none; }}
+  .msg {{ break-inside: avoid; }}
+  .tool, .md pre {{ break-inside: avoid; }}
+}}
+</style>
+{math_head}
+</head><body>
+<h1>{title}</h1>
+<div class="meta">{meta}</div>
+{body}
+{math_body}
+</body></html>
+"""
+
+
+def to_html(session: Session, *, include_reasoning: bool = True,
+            include_tools: bool = True, math: str = "raw") -> str:
+    meta_bits = [
+        f"source: {session.source}",
+        f"id: {session.id}",
+    ]
+    if session.directory:
+        meta_bits.append(f"dir: {session.directory}")
+    if session.model:
+        meta_bits.append(f"model: {session.model}")
+    meta_bits.append(f"created: {_fmt_dt(session.created)}")
+    meta_bits.append(f"messages: {len(session.messages)}")
+    meta = " &middot; ".join(_html.escape(b) for b in meta_bits)
+
+    body_parts: list[str] = []
+    for msg in session.messages:
+        inner = _html_message(msg, include_reasoning, include_tools, math)
+        if inner:
+            body_parts.append(inner)
+
+    # In `rendered` mode embed KaTeX so the static file typesets offline; in
+    # the other modes the math is inert source (no asset needed).
+    math_head = math_body = ""
+    if math == "rendered":
+        from . import katexbundle
+
+        math_head = katexbundle.head_assets()
+        math_body = katexbundle.autorender_script()
+
+    return _HTML_TEMPLATE.format(
+        title=_html.escape(session.title),
+        meta=meta,
+        body="\n".join(body_parts),
+        hl_css=minimd_highlight_css(),
+        math_head=math_head,
+        math_body=math_body,
+    )
+
+
+def minimd_highlight_css() -> str:
+    from . import highlight
+
+    return highlight.HL_CSS
+
+
+def _html_message(msg: Message, include_reasoning: bool, include_tools: bool,
+                  math: str = "raw") -> str:
+    inner: list[str] = []
+    for part in msg.parts:
+        if part.type == "text" and part.text:
+            # Render markdown (stdlib-only) so the static export reads nicely.
+            inner.append(f'<div class="md">{minimd.render(part.text, math=math)}</div>')
+        elif part.type == "reasoning" and include_reasoning and part.text:
+            inner.append(f'<div class="reasoning"><pre>{_html.escape(part.text)}</pre></div>')
+        elif part.type == "tool" and include_tools and part.text:
+            name = _html.escape(part.tool_name or part.tool_status or "tool")
+            inner.append(
+                f'<div class="tool"><div class="tool-name">{name}</div>'
+                f"<pre>{_html.escape(part.text)}</pre></div>"
+            )
+    if not inner:
+        return ""
+    role = _ROLE_LABEL.get(msg.role, msg.role)
+    cls = msg.role if msg.role in ("user", "assistant") else "assistant"
+    return (
+        f'<div class="msg {cls}"><div class="role">{_html.escape(role)}</div>'
+        + "\n".join(inner)
+        + "</div>"
+    )
+
+
+FORMATS = {
+    "markdown": to_markdown,
+    "md": to_markdown,
+    "json": to_json,
+    "html": to_html,
+    "text": to_text,
+    "txt": to_text,
+}
+
+# Math render modes for delimited-LaTeX spans (see minimd.render / katexbundle):
+#   raw      -- verbatim source, shielded from the Markdown pass
+#   latex    -- verbatim source, wrapped so it is never typeset (paste-ready)
+#   rendered -- typeset with KaTeX (HTML export embeds KaTeX to do so offline)
+MATH_MODES = ("raw", "latex", "rendered")
+
+
+def render(session: Session, fmt: str, **kwargs: object) -> str:
+    func = FORMATS.get(fmt)
+    if func is None:
+        raise ValueError(f"unknown format: {fmt!r}; choose from {sorted(set(FORMATS))}")
+    return func(session, **kwargs)  # type: ignore[arg-type]

scrollback/fts.py

@@ -0,0 +1,307 @@
+"""Optional full-text search index (SQLite FTS5).
+
+The default search path is a lexical scan over the live data (zero setup,
+always correct, but O(corpus) per query). For large histories this builds
+an opt-in inverted index in a *separate* cache database so queries are
+near-instant. The source data stores are never touched for writing -- the
+index is derived, disposable, and rebuilt from the read-only adapters.
+
+Design
+------
+* Index DB lives at ``~/.cache/scrollback/index.db`` (override with
+  ``SCROLLBACK_INDEX``). Deleting it just disables the fast path.
+* ``parts`` is an FTS5 table holding each searchable part's text plus the
+  metadata needed to reconstruct a hit (source, session id, message id,
+  role, part type, tool name).
+* ``synced`` records a per-session signature ``(updated_iso, message_count)``
+  so :func:`sync` only re-indexes new/changed sessions and prunes deleted
+  ones -- an incremental update, not a full rebuild.
+
+Availability degrades gracefully: if FTS5 is missing, :func:`available`
+returns False and callers fall back to the lexical scan.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def default_index_path() -> Path:
+    override = os.environ.get("SCROLLBACK_INDEX")
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".cache" / "scrollback" / "index.db"
+
+
+def fts5_available() -> bool:
+    """True if this Python's SQLite was built with FTS5."""
+    try:
+        conn = sqlite3.connect(":memory:")
+        try:
+            conn.execute("CREATE VIRTUAL TABLE _t USING fts5(x)")
+            return True
+        finally:
+            conn.close()
+    except sqlite3.OperationalError:
+        return False
+
+
+@dataclass(frozen=True, slots=True)
+class IndexHit:
+    """A raw FTS match -- enough to rebuild a SearchHit without re-scanning."""
+
+    source: str
+    session_id: str
+    message_id: str
+    role: str
+    part_type: str
+    tool_name: str | None
+    text: str
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS meta (
+    key TEXT PRIMARY KEY,
+    value TEXT
+);
+CREATE TABLE IF NOT EXISTS synced (
+    source TEXT NOT NULL,
+    session_id TEXT NOT NULL,
+    updated TEXT,
+    message_count INTEGER,
+    PRIMARY KEY (source, session_id)
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS parts USING fts5(
+    source UNINDEXED,
+    session_id UNINDEXED,
+    message_id UNINDEXED,
+    role UNINDEXED,
+    part_type UNINDEXED,
+    tool_name UNINDEXED,
+    text,
+    tokenize = 'unicode61'
+);
+"""
+
+
+class FtsIndex:
+    """Read/write wrapper around the cache index database."""
+
+    def __init__(self, path: Path | None = None) -> None:
+        self.path = path or default_index_path()
+
+    # -- lifecycle ----------------------------------------------------------
+
+    def exists(self) -> bool:
+        return self.path.is_file()
+
+    def _connect(self, *, write: bool) -> sqlite3.Connection:
+        if write:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            conn = sqlite3.connect(self.path)
+            conn.executescript(_SCHEMA)
+        else:
+            # Read-only open; raises if the file doesn't exist.
+            uri = f"file:{self.path}?mode=ro"
+            conn = sqlite3.connect(uri, uri=True)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    # -- sync ---------------------------------------------------------------
+
+    def sync(self, store, *, progress=None) -> dict[str, int]:
+        """Incrementally bring the index in line with `store`.
+
+        Returns counts: {"added", "updated", "removed", "unchanged"}.
+        `progress(done, total)` is called per session if provided.
+        """
+        stats = {"added": 0, "updated": 0, "removed": 0, "unchanged": 0}
+        with self._connect(write=True) as conn:
+            # Current signatures already in the index.
+            have = {
+                (r["source"], r["session_id"]): (r["updated"], r["message_count"])
+                for r in conn.execute(
+                    "SELECT source, session_id, updated, message_count FROM synced"
+                )
+            }
+            # Live sessions (metadata only; cheap). Don't fold -- we want every
+            # session, including subagents, individually indexed.
+            live = store.list_sessions(fold_subagents=False)
+            live_keys = {(s.source, s.id) for s in live}
+            total = len(live)
+
+            for i, meta in enumerate(live):
+                key = (meta.source, meta.id)
+                sig = (
+                    meta.updated.isoformat() if meta.updated else None,
+                    meta.message_count,
+                )
+                prev = have.get(key)
+                if prev == sig:
+                    stats["unchanged"] += 1
+                else:
+                    self._reindex_session(conn, store, meta, sig)
+                    stats["added" if prev is None else "updated"] += 1
+                if progress:
+                    progress(i + 1, total)
+
+            # Prune sessions that no longer exist on disk.
+            for key in set(have) - live_keys:
+                self._drop_session(conn, *key)
+                stats["removed"] += 1
+            # Record a sync marker: the newest source mtime we've indexed, so
+            # staleness can be checked cheaply later without re-listing.
+            conn.execute(
+                "INSERT OR REPLACE INTO meta (key, value) VALUES ('source_mtime', ?)",
+                (str(_max_source_mtime(store)),),
+            )
+            conn.commit()
+        return stats
+
+    def is_stale(self, store) -> bool:
+        """Cheap staleness check: True if any source file is newer than the
+        newest mtime recorded at the last sync.
+
+        Compares filesystem mtimes only (no full session enumeration), so it
+        is fast enough to call before a search.
+        """
+        if not self.exists():
+            return False
+        try:
+            with self._connect(write=False) as conn:
+                row = conn.execute(
+                    "SELECT value FROM meta WHERE key = 'source_mtime'"
+                ).fetchone()
+        except sqlite3.Error:
+            return False
+        if row is None or row[0] is None:
+            return True  # old index without a marker -> treat as stale
+        try:
+            recorded = float(row[0])
+        except (TypeError, ValueError):
+            return True
+        return _max_source_mtime(store) > recorded + 1.0  # 1s slack
+
+    def _drop_session(self, conn: sqlite3.Connection, source: str, sid: str) -> None:
+        conn.execute("DELETE FROM parts WHERE source = ? AND session_id = ?", (source, sid))
+        conn.execute("DELETE FROM synced WHERE source = ? AND session_id = ?", (source, sid))
+
+    def _reindex_session(self, conn, store, meta, sig) -> None:
+        self._drop_session(conn, meta.source, meta.id)
+        # Pass source explicitly (not "source:id"): the selector form only
+        # recognizes source prefixes registered in the global registry.
+        sess = store.load_session(meta.id, source=meta.source)
+        if sess is not None:
+            rows = []
+            for m in sess.messages:
+                for p in m.parts:
+                    if p.text:
+                        rows.append(
+                            (meta.source, meta.id, m.id, m.role, p.type,
+                             p.tool_name, p.text)
+                        )
+            if rows:
+                conn.executemany(
+                    "INSERT INTO parts (source, session_id, message_id, role, "
+                    "part_type, tool_name, text) VALUES (?, ?, ?, ?, ?, ?, ?)",
+                    rows,
+                )
+        conn.execute(
+            "INSERT OR REPLACE INTO synced (source, session_id, updated, message_count) "
+            "VALUES (?, ?, ?, ?)",
+            (meta.source, meta.id, sig[0], sig[1]),
+        )
+
+    # -- query --------------------------------------------------------------
+
+    def search(self, query: str, *, limit: int | None = None,
+               sources: list[str] | None = None) -> Iterator[IndexHit]:
+        """Yield IndexHits for an FTS query, most-recently-indexed first.
+
+        Ordering is by descending rowid: a session re-indexed after a change
+        is appended, so recently-updated sessions surface first -- a close
+        proxy for the lexical path's newest-session-first order (FTS5 does
+        not store the session's update time to sort on exactly).
+        """
+        if not self.exists() or not query.strip():
+            return iter(())
+        return self._search(query, limit, sources)
+
+    def _search(self, query, limit, sources) -> Iterator[IndexHit]:
+        match = _to_match_query(query)
+        sql = (
+            "SELECT source, session_id, message_id, role, part_type, tool_name, "
+            "  snippet(parts, 6, '\x02', '\x03', '…', 16) AS snip "
+            "FROM parts WHERE parts MATCH ?"
+        )
+        params: list[object] = [match]
+        if sources:
+            placeholders = ",".join("?" * len(sources))
+            sql += f" AND source IN ({placeholders})"
+            params.extend(sources)
+        sql += " ORDER BY rowid DESC"
+        if limit is not None:
+            sql += " LIMIT ?"
+            params.append(limit)
+        with self._connect(write=False) as conn:
+            for r in conn.execute(sql, params):
+                yield IndexHit(
+                    source=r["source"],
+                    session_id=r["session_id"],
+                    message_id=r["message_id"],
+                    role=r["role"],
+                    part_type=r["part_type"],
+                    tool_name=r["tool_name"],
+                    text=r["snip"],
+                )
+
+    def stats(self) -> dict[str, int]:
+        if not self.exists():
+            return {"sessions": 0, "parts": 0}
+        with self._connect(write=False) as conn:
+            sessions = conn.execute("SELECT COUNT(*) FROM synced").fetchone()[0]
+            parts = conn.execute("SELECT COUNT(*) FROM parts").fetchone()[0]
+        return {"sessions": sessions, "parts": parts}
+
+
+def _max_source_mtime(store) -> float:
+    """Newest mtime across all source locations (files + dirs).
+
+    For opencode this is the DB file's mtime; for Claude Code it walks the
+    projects tree. Cheap relative to parsing, and a good staleness signal.
+    """
+    newest = 0.0
+    for src in getattr(store, "sources", []):
+        loc = src.location()
+        if loc is None:
+            continue
+        try:
+            if loc.is_file():
+                newest = max(newest, loc.stat().st_mtime)
+            elif loc.is_dir():
+                for p in loc.rglob("*.jsonl"):
+                    try:
+                        newest = max(newest, p.stat().st_mtime)
+                    except OSError:
+                        continue
+        except OSError:
+            continue
+    return newest
+
+
+def _to_match_query(query: str) -> str:
+    """Turn a user query into a safe FTS5 MATCH expression.
+
+    We quote each whitespace-separated term as a phrase (doubling embedded
+    quotes) and AND them together. This avoids FTS5 operator-syntax errors
+    from arbitrary user input (e.g. a stray `*` or `:`), while still giving
+    multi-word AND semantics.
+    """
+    terms = query.split()
+    if not terms:
+        return '""'
+    return " ".join('"' + t.replace('"', '""') + '"' for t in terms)