scrollback 0.1.0__py3-none-any.whl

scrollback/minimd.py

@@ -0,0 +1,205 @@
+"""A tiny, safe, stdlib-only Markdown-to-HTML renderer.
+
+Scope is deliberately small -- the common constructs that appear in AI
+chat transcripts: fenced code blocks, ATX headings, unordered/ordered
+lists, blockquotes, horizontal rules, paragraphs, and inline spans
+(code, bold, italic, links). Everything is HTML-escaped first, so the
+output is safe to drop into an export without an external dependency and
+without risking HTML/script injection from transcript content.
+
+This is NOT a CommonMark implementation; it trades completeness for zero
+dependencies and predictable, safe output. The richer browser view uses
+the vendored `marked` + `highlight.js`; this module exists so the static
+HTML *export* renders nicely on its own (e.g. for printing/sharing).
+"""
+
+from __future__ import annotations
+
+import html as _html
+import re
+
+from . import highlight as _highlight
+from . import mathspan as _mathspan
+
+_HEADING = re.compile(r"^(#{1,6})\s+(.*)$")
+_UL_ITEM = re.compile(r"^[ \t]*[-*+]\s+(.*)$")
+_OL_ITEM = re.compile(r"^[ \t]*\d+[.)]\s+(.*)$")
+_HR = re.compile(r"^(?:-{3,}|\*{3,}|_{3,})\s*$")
+_FENCE = re.compile(r"^[ \t]*(`{3,}|~{3,})\s*([\w+-]*)\s*$")
+_BLOCKQUOTE = re.compile(r"^>\s?(.*)$")
+
+
+def render(text: str, *, math: str = "raw") -> str:
+    """Render Markdown `text` to a safe HTML fragment.
+
+    `math` controls how delimited-LaTeX spans (`$...$`, `$$...$$`,
+    `\\(...\\)`, `\\[...\\]`) are handled. In every mode the span is first
+    shielded from the Markdown pass so `\\`, `_`, `*`, `^` survive intact:
+
+    - ``"raw"``     -- restore the original delimited source verbatim
+      (default; matches the historical behaviour but no longer mangled).
+    - ``"latex"``   -- show the LaTeX source verbatim, wrapped so a renderer
+      will not typeset it; best for copying into a paper.
+    - ``"rendered"`` -- emit a placeholder element the client typesets with
+      KaTeX (the static export embeds KaTeX so this works offline).
+    """
+    masked, tokens = _mathspan.protect(text)
+    html = _render_blocks(masked)
+    return _mathspan.restore(html, tokens, lambda span: _math_html(span, math))
+
+
+def _math_html(span: _mathspan.Span, mode: str) -> str:
+    """Render one math span to HTML for the static export, per `mode`."""
+    if mode == "rendered":
+        # Emit the LaTeX in a span the client-side KaTeX pass typesets; the
+        # body is escaped so it is inert until KaTeX reads textContent.
+        cls = "math-tex math-display" if span.display else "math-tex"
+        disp = "true" if span.display else "false"
+        return f'<span class="{cls}" data-display="{disp}">{_html.escape(span.body)}</span>'
+    if mode == "latex":
+        # Verbatim source, never typeset, never mangled.
+        return f'<code class="math-src">{_html.escape(span.raw)}</code>'
+    # raw: restore the original delimited source verbatim, as inert text.
+    return _html.escape(span.raw)
+
+
+def _render_blocks(text: str) -> str:
+    """Render Markdown block structure (math already masked by `render`)."""
+    lines = text.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    out: list[str] = []
+    i = 0
+    n = len(lines)
+
+    while i < n:
+        line = lines[i]
+
+        # Fenced code block.
+        m = _FENCE.match(line)
+        if m:
+            fence = m.group(1)[0]
+            lang = m.group(2).strip()
+            j = i + 1
+            buf: list[str] = []
+            while j < n and not _is_closing_fence(lines[j], fence):
+                buf.append(lines[j])
+                j += 1
+            raw = "\n".join(buf)
+            if lang:
+                # Highlighter escapes internally and emits only safe spans.
+                code = _highlight.highlight(raw, lang)
+                cls = f' class="language-{_html.escape(lang)}"'
+            else:
+                code = _html.escape(raw)
+                cls = ""
+            out.append(f"<pre><code{cls}>{code}</code></pre>")
+            i = j + 1
+            continue
+
+        # Blank line.
+        if not line.strip():
+            i += 1
+            continue
+
+        # Horizontal rule.
+        if _HR.match(line):
+            out.append("<hr>")
+            i += 1
+            continue
+
+        # Heading.
+        m = _HEADING.match(line)
+        if m:
+            level = len(m.group(1))
+            out.append(f"<h{level}>{_inline(m.group(2).strip())}</h{level}>")
+            i += 1
+            continue
+
+        # Blockquote (consecutive '>' lines).
+        if _BLOCKQUOTE.match(line):
+            buf = []
+            while i < n and _BLOCKQUOTE.match(lines[i]):
+                buf.append(_BLOCKQUOTE.match(lines[i]).group(1))
+                i += 1
+            inner = _render_blocks("\n".join(buf))
+            out.append(f"<blockquote>{inner}</blockquote>")
+            continue
+
+        # Lists (unordered / ordered).
+        if _UL_ITEM.match(line) or _OL_ITEM.match(line):
+            ordered = bool(_OL_ITEM.match(line))
+            pat = _OL_ITEM if ordered else _UL_ITEM
+            items: list[str] = []
+            while i < n and pat.match(lines[i]):
+                items.append(_inline(pat.match(lines[i]).group(1).strip()))
+                i += 1
+            tag = "ol" if ordered else "ul"
+            li = "".join(f"<li>{it}</li>" for it in items)
+            out.append(f"<{tag}>{li}</{tag}>")
+            continue
+
+        # Paragraph: gather consecutive non-blank, non-special lines.
+        buf = [line]
+        i += 1
+        while i < n and lines[i].strip() and not _starts_block(lines[i]):
+            buf.append(lines[i])
+            i += 1
+        para = "<br>".join(_inline(b.strip()) for b in buf)
+        out.append(f"<p>{para}</p>")
+
+    return "\n".join(out)
+
+
+def _is_closing_fence(line: str, fence_char: str) -> bool:
+    m = _FENCE.match(line)
+    return bool(m and m.group(1)[0] == fence_char)
+
+
+def _starts_block(line: str) -> bool:
+    return bool(
+        _HEADING.match(line)
+        or _UL_ITEM.match(line)
+        or _OL_ITEM.match(line)
+        or _HR.match(line)
+        or _FENCE.match(line)
+        or _BLOCKQUOTE.match(line)
+    )
+
+
+# -- inline spans ----------------------------------------------------------
+
+# Process inline code first (and protect its contents), then links, then
+# emphasis. All raw text is escaped before markup substitution.
+_CODE_SPAN = re.compile(r"`([^`]+)`")
+_LINK = re.compile(r"\[([^\]]+)\]\((https?://[^\s)]+)\)")
+_BOLD = re.compile(r"\*\*([^*]+)\*\*|__([^_]+)__")
+_ITALIC = re.compile(r"(?<![*\w])\*([^*\n]+)\*(?![*\w])|(?<![_\w])_([^_\n]+)_(?![_\w])")
+
+
+def _inline(text: str) -> str:
+    # Extract code spans first so their contents are not touched by other
+    # rules; replace with placeholders, then restore at the end.
+    placeholders: list[str] = []
+
+    def _stash_code(m: re.Match) -> str:
+        placeholders.append(f"<code>{_html.escape(m.group(1))}</code>")
+        return f"\x00{len(placeholders) - 1}\x00"
+
+    tmp = _CODE_SPAN.sub(_stash_code, text)
+    tmp = _html.escape(tmp)
+
+    # Links: [label](url) -> escape both parts.
+    def _link(m: re.Match) -> str:
+        label = m.group(1)
+        url = m.group(2)
+        return f'<a href="{_html.escape(url, quote=True)}">{label}</a>'
+
+    # Note: tmp is already escaped, so the bracket/paren chars survive as-is.
+    tmp = _LINK.sub(_link, tmp)
+    tmp = _BOLD.sub(lambda m: f"<strong>{m.group(1) or m.group(2)}</strong>", tmp)
+    tmp = _ITALIC.sub(lambda m: f"<em>{m.group(1) or m.group(2)}</em>", tmp)
+
+    # Restore code spans.
+    def _restore(m: re.Match) -> str:
+        return placeholders[int(m.group(1))]
+
+    return re.sub(r"\x00(\d+)\x00", _restore, tmp)

scrollback/models.py

@@ -0,0 +1,135 @@
+"""Common data model shared by all source adapters.
+
+Every adapter normalizes its agent's on-disk representation into these
+immutable dataclasses, so the rest of the program (CLI, search, export,
+web) is agent-agnostic. Keeping these as plain data structures (rather
+than behavior-rich classes) follows the "functions over data structures"
+principle: many functions operate on these few shapes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Literal
+
+PartType = Literal[
+    "text",
+    "reasoning",
+    "tool",
+    "file",
+    "patch",
+    "step-start",
+    "step-finish",
+    "compaction",
+    "unknown",
+]
+
+Role = Literal["user", "assistant", "system", "tool"]
+
+
+def _to_dt(ms_or_iso: int | float | str | None) -> datetime | None:
+    """Best-effort conversion of a timestamp to an aware UTC datetime.
+
+    Accepts epoch milliseconds (opencode) or ISO-8601 strings (Claude Code).
+    Returns None when the input is missing or unparseable.
+    """
+    if ms_or_iso is None:
+        return None
+    if isinstance(ms_or_iso, (int, float)):
+        # opencode stores epoch milliseconds.
+        return datetime.fromtimestamp(ms_or_iso / 1000.0, tz=timezone.utc)
+    if isinstance(ms_or_iso, str):
+        s = ms_or_iso.strip()
+        if not s:
+            return None
+        try:
+            # Handle trailing Z.
+            if s.endswith("Z"):
+                s = s[:-1] + "+00:00"
+            dt = datetime.fromisoformat(s)
+        except ValueError:
+            return None
+        # Force tz-awareness: a timezone-less timestamp would otherwise be a
+        # naive datetime, which raises TypeError when sorted alongside the
+        # aware datetimes used elsewhere. Assume UTC when no offset is given.
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt
+    return None
+
+
+@dataclass(frozen=True, slots=True)
+class Part:
+    """A single content block within a message.
+
+    `text` holds a human-readable rendering of the part regardless of type
+    (the message body, the reasoning text, a tool's input/output summary).
+    `raw` preserves the adapter's original parsed object for fidelity.
+    """
+
+    id: str
+    type: PartType
+    text: str = ""
+    tool_name: str | None = None
+    tool_status: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class Message:
+    """One turn in a conversation, composed of ordered parts."""
+
+    id: str
+    role: Role
+    created: datetime | None
+    parts: tuple[Part, ...] = ()
+    model: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def text(self) -> str:
+        """Concatenated text of all textual parts (text + reasoning)."""
+        return "\n".join(p.text for p in self.parts if p.text)
+
+
+@dataclass(frozen=True, slots=True)
+class Session:
+    """A whole conversation: metadata plus (optionally) its messages.
+
+    Listing operations populate metadata only and leave `messages` empty
+    for speed; loading a single session populates `messages`.
+    """
+
+    id: str
+    source: str  # adapter name, e.g. "opencode" / "claudecode"
+    title: str
+    directory: str | None
+    created: datetime | None
+    updated: datetime | None
+    model: str | None = None
+    agent: str | None = None
+    parent_id: str | None = None
+    message_count: int | None = None
+    # Usage accounting (opencode tracks these; None when unknown).
+    cost: float | None = None
+    tokens_input: int | None = None
+    tokens_output: int | None = None
+    # Children populated when subagent folding is enabled.
+    children: tuple["Session", ...] = ()
+    messages: tuple[Message, ...] = ()
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def short_id(self) -> str:
+        """A compact id suitable for display and prefix selection."""
+        return self.id[:12]
+
+    @property
+    def is_subagent(self) -> bool:
+        """True if this session was spawned by another (has a parent)."""
+        return bool(self.parent_id)
+
+
+# Re-export the converter for adapters.
+__all__ = ["Part", "Message", "Session", "PartType", "Role", "_to_dt"]

scrollback/serialize.py

@@ -0,0 +1,83 @@
+"""Plain-dict serializers for the API layer.
+
+Kept separate from `export.py` (which renders human-facing documents) and
+from `models.py` (which stays behavior-free). These produce the JSON
+shapes the web frontend consumes.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .models import Message, Part, Session
+from .store import SearchHit
+
+
+def _iso(dt: datetime | None) -> str | None:
+    return dt.isoformat() if dt else None
+
+
+def session_summary(s: Session) -> dict[str, Any]:
+    """Lightweight session metadata for list views."""
+    return {
+        "id": s.id,
+        "source": s.source,
+        "short_id": s.short_id,
+        "title": s.title,
+        "directory": s.directory,
+        "created": _iso(s.created),
+        "updated": _iso(s.updated),
+        "model": s.model,
+        "agent": s.agent,
+        "parent_id": s.parent_id,
+        "is_subagent": s.is_subagent,
+        "message_count": s.message_count,
+        "cost": s.cost,
+        "tokens_input": s.tokens_input,
+        "tokens_output": s.tokens_output,
+        "git_branch": (s.raw or {}).get("git_branch"),
+        "children": [session_summary(c) for c in s.children],
+    }
+
+
+def part_dict(p: Part) -> dict[str, Any]:
+    return {
+        "id": p.id,
+        "type": p.type,
+        "text": p.text,
+        "tool_name": p.tool_name,
+        "tool_status": p.tool_status,
+    }
+
+
+def message_dict(m: Message) -> dict[str, Any]:
+    return {
+        "id": m.id,
+        "role": m.role,
+        "created": _iso(m.created),
+        "model": m.model,
+        "parts": [part_dict(p) for p in m.parts],
+    }
+
+
+def session_detail(s: Session) -> dict[str, Any]:
+    """Full session including messages/parts."""
+    data = session_summary(s)
+    data["messages"] = [message_dict(m) for m in s.messages]
+    return data
+
+
+def search_hit(h: SearchHit) -> dict[str, Any]:
+    return {
+        "source": h.session.source,
+        "session_id": h.session.id,
+        "short_id": h.session.short_id,
+        "title": h.session.title,
+        "directory": h.session.directory,
+        "message_id": h.message.id,
+        "role": h.message.role,
+        "part_type": h.part.type,
+        "tool_name": h.part.tool_name,
+        "snippet": h.snippet,
+    }

scrollback/serverconfig.py

@@ -0,0 +1,66 @@
+"""Single source of truth for the web server's host/port configuration.
+
+Resolution order for host and port (highest precedence first):
+1. an explicit CLI flag (`--host` / `--port`)
+2. an environment variable (`SCROLLBACK_HOST` / `SCROLLBACK_PORT`)
+3. the built-in default
+
+This lets launchers (which just call `scrollback web --window`) be
+configured without editing any script -- set the env var. It also keeps
+the default in exactly one place rather than scattered magic numbers.
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8765
+
+_ENV_HOST = "SCROLLBACK_HOST"
+_ENV_PORT = "SCROLLBACK_PORT"
+
+
+def default_host() -> str:
+    return os.environ.get(_ENV_HOST, DEFAULT_HOST)
+
+
+def default_port() -> int:
+    raw = os.environ.get(_ENV_PORT)
+    if raw:
+        try:
+            return int(raw)
+        except ValueError:
+            pass
+    return DEFAULT_PORT
+
+
+def is_port_free(host: str, port: int) -> bool:
+    """Return True if a TCP server can bind (host, port) right now."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            sock.bind((host, port))
+            return True
+        except OSError:
+            return False
+
+
+def resolve_port(host: str, port: int, *, strict: bool = False, tries: int = 20) -> int:
+    """Return a bindable port.
+
+    If `port` is free, use it. Otherwise, unless `strict`, scan upward for
+    the next free port (port+1, port+2, ...). Raises OSError if `strict`
+    and the port is taken, or if no free port is found within `tries`.
+    """
+    if is_port_free(host, port):
+        return port
+    if strict:
+        raise OSError(f"port {port} on {host} is already in use")
+    for candidate in range(port + 1, port + 1 + tries):
+        if is_port_free(host, candidate):
+            return candidate
+    raise OSError(
+        f"no free port found near {port} on {host} (tried {tries} ports)"
+    )

scrollback/sources/__init__.py

@@ -0,0 +1,6 @@
+"""Source adapters: one per supported AI agent.
+
+Each adapter implements `Source` (see base.py) and is registered in
+`registry.py`. Adding support for a new agent means writing one adapter
+and adding it to the registry -- nothing else in the program changes.
+"""