scrollback 0.1.0__tar.gz

scrollback-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (dev extra)
+        run: |
+          python -m pip install --upgrade pip
+          # The dev extra is self-sufficient for the full suite (fastapi +
+          # uvicorn + httpx for the web-API tests). pywebview is intentionally
+          # excluded -- it needs a GUI backend CI runners lack, and no test
+          # imports it.
+          python -m pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check src tests
+
+      - name: Test (pytest)
+        run: pytest -q
+
+  build:
+    name: build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Check artifacts contain data files
+        run: |
+          python - <<'PY'
+          import glob, zipfile
+          whl = sorted(glob.glob("dist/*.whl"))[-1]
+          names = zipfile.ZipFile(whl).namelist()
+          need = ["web/static/app.js", "web/static/vendor/marked.min.js",
+                  "web/static/vendor/katex/katex.min.js",
+                  "web/static/vendor/katex/fonts/KaTeX_Main-Regular.woff2",
+                  "launchers/scrollback.command", "assets/icon.icns"]
+          missing = [n for n in need if not any(n in x for x in names)]
+          assert not missing, f"wheel missing data files: {missing}"
+          print("wheel OK:", whl.split('/')[-1])
+          PY
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*

scrollback-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,98 @@
+name: Publish to PyPI
+
+# Tag-gated release. Push a version tag (e.g. `v0.1.0`) to build, validate, and
+# publish the sdist + wheel to PyPI via Trusted Publishing (OIDC) -- no API
+# token or password is stored in the repo. Configure the trusted publisher once
+# at https://pypi.org/manage/project/scrollback/settings/publishing/ (or via
+# "pending publisher" before the first upload), matching:
+#   owner = a-attia, repo = scrollback, workflow = publish.yml, env = pypi.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  # Re-run the full test matrix + lint before releasing, so a tag can never
+  # publish a red build.
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: pytest -q
+
+  build:
+    name: build + validate
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+      - name: Verify the tag matches the package version
+        run: |
+          python - <<'PY'
+          import os, tomllib, pathlib, re
+          # version is dynamic from src/scrollback/__init__.py
+          init = pathlib.Path("src/scrollback/__init__.py").read_text()
+          ver = re.search(r'__version__\s*=\s*["\']([^"\']+)["\']', init).group(1)
+          tag = os.environ["GITHUB_REF_NAME"]
+          assert tag == f"v{ver}", f"tag {tag!r} does not match package version v{ver}"
+          print(f"tag {tag} matches version {ver}")
+          PY
+      - name: Validate metadata (twine check)
+        run: python -m twine check dist/*
+      - name: Verify wheel ships its data files
+        run: |
+          python - <<'PY'
+          import glob, zipfile
+          whl = sorted(glob.glob("dist/*.whl"))[-1]
+          names = zipfile.ZipFile(whl).namelist()
+          need = ["web/static/app.js", "web/static/vendor/marked.min.js",
+                  "web/static/vendor/katex/katex.min.js",
+                  "web/static/vendor/katex/fonts/KaTeX_Main-Regular.woff2",
+                  "launchers/scrollback.command", "assets/icon.icns"]
+          missing = [n for n in need if not any(n in x for x in names)]
+          assert not missing, f"wheel missing data files: {missing}"
+          print("wheel OK:", whl.split('/')[-1])
+          PY
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/scrollback
+    permissions:
+      id-token: write   # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

scrollback-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Test / coverage / lint
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+
+# scrollback: never commit anyone's exported sessions
+*.session.md
+*.session.html
+*.session.json
+
+# Generated icon intermediates (the SVG source + .icns are kept)
+assets/icon.iconset/

scrollback-0.1.0/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to scrollback are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/), and the project aims to
+follow [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-30
+
+The first release. scrollback reads AI coding-agent session history
+(opencode + Claude Code) read-only and lets you browse, search, copy, and
+export it from a CLI and a local web app.
+
+### Added
+
+- **CLI** (`scrollback`): `sources`, `list`, `show`, `search`, `export`
+  (markdown / json / html / text), `copy`, `stats`, `resume`, `web`,
+  `index`, `doctor`, and `install-launcher`.
+- **Source adapters** (pluggable, read-only): opencode (SQLite), Claude Code
+  (JSONL, with subagent sidechains folded under their parent), Codex
+  (`rollout-*.jsonl`), and Aider (`.aider.chat.history.md`). More are queued
+  in `ROADMAP.md`.
+- `stats` aggregates session/message/token/cost totals plus top projects;
+  `resume` prints the native command to continue a session in its own agent.
+- Listing filters: `--source`, `--dir`, `--query`, `--since` / `--until`,
+  pagination (`--offset` / `--page`), usage columns (`--usage`), and
+  subagent folding (on by default; `--no-fold`). Optional coloured output
+  via `rich`.
+- **Web app** (`scrollback web`): local, read-only, served on
+  `127.0.0.1`. Session list with source filters, date filters, and a
+  `titles | contents` search scope; lazy, windowed transcript loading so
+  very large sessions open instantly; in-transcript find; per-message and
+  per-session copy; export and print; light/dark theme; keyboard
+  navigation; a frozen session header with a scrolling message body.
+- **Markdown rendering**: assistant/user text renders as Markdown with code
+  highlighting -- in the browser (vendored marked + highlight.js) and in
+  the static HTML export (a dependency-free Python renderer + highlighter).
+- **Math / equation rendering**: delimited LaTeX (`$...$`, `$$...$$`,
+  `\(...\)`, `\[...\]`) is detected and shielded from the Markdown pass so
+  `\`, `_`, `*`, `^` survive intact in both renderers. A render mode --
+  `raw` (verbatim source), `latex` (verbatim, never typeset, paste-ready),
+  or `rendered` (typeset) -- is a toggle in the web transcript header
+  (persisted like the theme) and an `--math {raw,latex,rendered}` flag on
+  `scrollback export` / `copy`. Typesetting uses vendored KaTeX (no CDN);
+  the self-contained HTML export embeds KaTeX with its fonts inlined so
+  saved/printed files typeset offline. The single-`$` form is recognised
+  conservatively so currency (`$5 to $10`) and code are left alone.
+- **Optional full-text search index** (`scrollback index`): SQLite FTS5,
+  incremental, stored in a disposable cache DB; the source data is never
+  modified, and search falls back to a lexical scan without it.
+- **Launching without the terminal**: `scrollback-web` / `scrollback-app`
+  console entry points; `install-launcher` drops a double-clickable
+  launcher (macOS `.command` / `.app`, Windows `.bat`, Linux `.desktop`);
+  a native desktop window via pywebview that frees the port on close.
+- App icon (macOS `.app` + web favicon) and macOS app identity (menu name,
+  About panel with version and a clickable repo link).
+- Configurable host/port via flags or `SCROLLBACK_HOST` / `SCROLLBACK_PORT`,
+  with automatic free-port selection.
+
+### Security
+
+- Sanitize rendered Markdown (DOMPurify) to prevent transcript content from
+  injecting scripts into the web UI.
+- Host-header allowlist guarding against DNS-rebinding (loopback-only by
+  default); loud warning on non-loopback binds.
+- Path-traversal containment for Claude subagent id resolution.
+
+### Performance
+
+- Cache Claude Code metadata scans by file mtime (repeated listings go from
+  ~1.2s to ~0.01s).
+- Byte-offset paging index for Claude transcripts (deep pages on a
+  31k-message session: ~1s to ~2ms).
+- Lazy per-session metadata resolution on the indexed search path.
+
+### Fixed
+
+- Timezone-naive timestamps no longer crash session sorting.
+- Subagent folding no longer drops self-referential or cross-source records.
+- Reliable downloads and printing from the native desktop window.
+- Negative pagination arguments are rejected; clearer errors for unknown
+  sources, failed exports, and unavailable data sources.
+
+[Unreleased]: https://github.com/a-attia/scrollback/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/a-attia/scrollback/releases/tag/v0.1.0

scrollback-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to scrollback
+
+Thanks for your interest. scrollback is a small, local-first, read-only
+tool, and contributions that keep it that way are very welcome.
+
+## Development setup
+
+```bash
+git clone https://github.com/a-attia/scrollback
+cd scrollback
+python -m pip install -e ".[web,dev]"   # editable install + web + dev tools
+```
+
+The bare package has **no runtime dependencies** (stdlib only); the web app
+and developer tooling come from extras. Requires Python 3.10+.
+
+## Running the checks
+
+```bash
+pytest -q          # the test suite
+ruff check src tests   # lint
+```
+
+Both must pass before a change is merged. The test suite is fast (~2s) and
+runs against synthetic fixtures plus, where present, your real local data
+(those tests skip gracefully when no data is available).
+
+## Project conventions
+
+- **Read-only, always.** Nothing in scrollback may write to, lock for
+  writing, or upload a user's agent data. The opencode SQLite DB is opened
+  with `mode=ro`; JSONL files are read-only. Tests assert this invariant.
+- **Lightest tool that does the job.** Prefer the stdlib. New runtime
+  dependencies for the core CLI are a hard sell; put optional features
+  behind extras (see `[project.optional-dependencies]`).
+- **Platform-agnostic.** Keep OS-specific code guarded by `sys.platform`
+  and best-effort (it must degrade, not crash, elsewhere). Window/icon
+  handling lives in Python, not baked into per-OS launcher scripts.
+- **Tests for fixes.** Bug fixes should come with a regression test;
+  numeric/parsing assertions should be backed by a known-correct value.
+
+## Adding a new agent source
+
+Implement the `Source` interface in `src/scrollback/sources/base.py` and
+register it in `src/scrollback/sources/registry.py`. Everything else (CLI,
+search, export, web, index) works against the common model automatically.
+See `opencode.py` (SQLite) and `claudecode.py` (JSONL) as references.
+
+## Regenerating the README screenshots
+
+The images in the README are generated from synthetic, sanitized demo data
+(`scripts/demo_data.py`) — never from real sessions — so they are safe to
+publish. To regenerate them after a UI change:
+
+```bash
+pip install -e ".[screenshots]"
+playwright install chromium       # one-time headless-browser download
+python scripts/screenshots.py     # writes assets/screenshots/{cli.svg,web.png}
+```
+
+The CLI image is rendered with `rich` (no browser); the web image is
+captured with headless Chromium via Playwright. Neither the `screenshots`
+extra nor the browser is needed to run scrollback.
+
+## Submitting changes
+
+1. Fork and branch.
+2. Make the change with a focused scope and a test.
+3. Run `pytest -q` and `ruff check src tests`.
+4. Open a pull request describing the change and how you verified it.

scrollback-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Attia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.