saga-cli 0.1.0__tar.gz

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

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install dev tools
+        run: uv sync --group dev
+      - name: Ruff lint
+        run: uv run ruff check .
+      - name: Ruff format
+        run: uv run ruff format --check .
+      - name: Type check
+        run: uv run ty check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: uv sync --group dev
+      - name: Run tests
+        run: uv run python -m pytest -q

saga_cli-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.coverage
+.venv/
+.DS_Store
+.ruff_cache
+*.pid
+*.pyc
+*.pyo
+*.pyd
+**/.vscode/*
+!**/.vscode/extensions.json
+
+dist/
+saga.html

saga_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing
+
+Thanks for your interest in Saga.
+
+## Development setup
+
+```sh
+git clone https://github.com/JakeBeresford/saga
+cd saga
+uv pip install -e . pytest   # or: pip install -e . pytest
+```
+
+Run the tests:
+
+```sh
+python -m pytest
+```
+
+Lint, format, and type-check (install the dev tools with `uv sync --group dev`):
+
+```sh
+uv run ruff check .          # lint
+uv run ruff format .         # auto-format
+uv run ty check .            # type check
+```
+
+To try the CLI against a real repo while developing, install it as an editable
+tool and run it from inside any git checkout:
+
+```sh
+uv tool install --editable .
+saga --base main --head my-feature
+```
+
+## Pull requests
+
+- Keep changes focused and match the existing style.
+- Add or update tests for any behavior change — the core model logic in
+  `saga/model.py` is unit-tested in `tests/test_model.py`.
+- Make sure `python -m pytest` passes and `ruff`/`ty` are clean before opening a
+  PR. CI runs the suite on Python 3.11–3.13 plus a lint/format/type-check job.
+
+## Reporting issues
+
+Open an issue at https://github.com/JakeBeresford/saga/issues with steps to
+reproduce, the command you ran, and what you expected to happen.

saga_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jake Beresford
+
+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.

saga_cli-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: saga-cli
+Version: 0.1.0
+Summary: Generate a self-contained static HTML saga of a git diff — a chapter-by-chapter guided tour of a change.
+Project-URL: Homepage, https://github.com/JakeBeresford/saga
+Project-URL: Repository, https://github.com/JakeBeresford/saga
+Project-URL: Issues, https://github.com/JakeBeresford/saga/issues
+Author: Jake Beresford
+License-Expression: MIT
+License-File: LICENSE
+Keywords: code-review,diff,documentation,git,html,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Requires-Dist: anthropic
+Requires-Dist: instructor
+Requires-Dist: openai
+Requires-Dist: typer>=0.26.8
+Description-Content-Type: text/markdown
+
+# Saga
+
+Generate a **chapter-by-chapter guided tour** of a code change as a single,
+self-contained static HTML page, a _saga_ of your diff. It partitions a diff into
+ordered chapters that tell one coherent story, each with a plain-language narration
+and just the hunks that belong to it. Large PRs become easy to review without
+losing the thread.
+
+The output is one HTML file with everything inlined (diff2html, syntax highlighting,
+the data). Open it offline, email it, commit it, or drop it on any static host.
+
+[**See an example saga**](https://jakeberesford.github.io/saga/example.html).
+
+## Requirements
+
+- Python 3.11+
+- `git`
+- An API key for your chosen provider, in the standard environment variable:
+  `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`
+
+Generation is one structured LLM call made through [`instructor`](https://python.useinstructor.com).
+
+## Install
+
+Install once and the `saga` command is available from any repo:
+
+```sh
+uv tool install saga-cli     # recommended
+# or
+pipx install saga-cli
+# or, into the current environment
+pip install saga-cli
+```
+
+Installing from a local checkout instead? Point the installer at this directory,
+e.g. `uv tool install /path/to/saga`. To upgrade: `uv tool install --force saga-cli`.
+
+## Usage
+
+From inside the repo you want to review:
+
+```sh
+saga --base main --head my-feature -o saga.html --open
+```
+
+Run it from anywhere with `--repo`:
+
+```sh
+saga --repo ~/src/some-project --base main --head my-feature -o out.html
+```
+
+| Flag                   | Default                     | Meaning                                                                                            |
+| ---------------------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
+| `--base`               | `main`                      | Base ref to diff against                                                                           |
+| `--head`               | current branch              | Head ref to walk through                                                                           |
+| `--intent PATH`        | —                           | Optional plan/spec describing the change's intent, for plan-aware narration and deviation flagging |
+| `--model`              | `anthropic/claude-opus-4-8` | `provider/model` string (see [Providers](#providers)); also `$SAGA_MODEL`                          |
+| `-o, --output`         | `saga.html`                 | Output file                                                                                        |
+| `--repo`               | cwd                         | A path inside the target git repo                                                                  |
+| `--open` / `--no-open` | on                          | Open the result in a browser (on by default; `--no-open` to disable)                               |
+
+## Providers
+
+The model is a single `provider/model` string, dispatched through `instructor`.
+Choose it with `--model` or the `SAGA_MODEL` environment variable, and set
+the matching API key:
+
+| Provider   | `--model` example                        | API key env var      |
+| ---------- | ---------------------------------------- | -------------------- |
+| Anthropic  | `anthropic/claude-opus-4-8`              | `ANTHROPIC_API_KEY`  |
+| OpenAI     | `openai/gpt-4o`                          | `OPENAI_API_KEY`     |
+| OpenRouter | `openrouter/anthropic/claude-3.5-sonnet` | `OPENROUTER_API_KEY` |
+
+```sh
+export SAGA_MODEL=openai/gpt-4o
+export OPENAI_API_KEY=sk-…
+saga --base main --head my-feature -o saga.html
+```
+
+## As a Claude Code skill
+
+The `skills/` directory contains two Claude Code skills. To install both:
+
+```sh
+cp -R "$(pwd)/skills" ~/.claude/skills/saga
+```
+
+- **`saga`** — say **"/saga"** (or "give me a walkthrough of this branch") to generate a
+  saga. It resolves the base/head refs and runs the tool for you.
+- **`saga-comments`** — say **"/saga-comments"** (or "address the saga comments") to read an
+  exported `saga.comments.json` and act on the reviewer's feedback in code.
+
+## Reviewing: comments
+
+The saga page is also a lightweight review surface. Open `saga.html` and leave three
+kinds of comments — **inline** (click a line's number in any chapter's diff), **per-file**
+(the "💬 File comment" control in each file header), and one **overall** review comment
+(the box at the top of the Chapters list). Comments are drafted in your browser's
+`localStorage`, so they survive a reload.
+
+When you're done, click **Export comments** to download a `saga.comments.json` sidecar next
+to the HTML. (Export is disabled in the [hosted example](https://jakeberesford.github.io/saga/example.html)
+so it never writes a file — every other part of the review UX works.) Two commands consume it:
+
+```sh
+# Post everything as a single PENDING review on the PR (you submit it on GitHub).
+saga comments push --comments saga.comments.json
+
+# Emit the comments as JSON on stdout — for a coding agent to act on.
+saga comments read --comments saga.comments.json
+```
+
+`push` uses the `gh` CLI: it finds the open PR for the sidecar's branch and creates one
+pending review (inline → line comments, per-file → a note anchored to the file's first
+changed line, overall → the review body). Nothing is submitted until you review and submit
+it on GitHub. Requires the [`gh`](https://cli.github.com) CLI, authenticated.
+
+## How it works
+
+1. `diff.py` computes `git diff base...head` (no checkout) and the commit list.
+2. `model.py` splits the diff into stable-id hunks (`h0, h1, …`).
+3. `generate.py` sends the labeled diff + commits (+ optional intent) to the chosen
+   model via `instructor`, which returns chapters as schema-validated JSON. Coverage
+   is **re-validated in code** — every hunk must belong to a chapter or generation fails.
+4. `render.py` reconstructs each chapter's diff and inlines everything into one
+   self-contained HTML file.
+
+## Not included (yet)
+
+- Support for Local LLMs via ollama / LM Studio
+- A GitHub Action to auto-generate saga on PRs.

saga_cli-0.1.0/README.md

@@ -0,0 +1,131 @@
+# Saga
+
+Generate a **chapter-by-chapter guided tour** of a code change as a single,
+self-contained static HTML page, a _saga_ of your diff. It partitions a diff into
+ordered chapters that tell one coherent story, each with a plain-language narration
+and just the hunks that belong to it. Large PRs become easy to review without
+losing the thread.
+
+The output is one HTML file with everything inlined (diff2html, syntax highlighting,
+the data). Open it offline, email it, commit it, or drop it on any static host.
+
+[**See an example saga**](https://jakeberesford.github.io/saga/example.html).
+
+## Requirements
+
+- Python 3.11+
+- `git`
+- An API key for your chosen provider, in the standard environment variable:
+  `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`
+
+Generation is one structured LLM call made through [`instructor`](https://python.useinstructor.com).
+
+## Install
+
+Install once and the `saga` command is available from any repo:
+
+```sh
+uv tool install saga-cli     # recommended
+# or
+pipx install saga-cli
+# or, into the current environment
+pip install saga-cli
+```
+
+Installing from a local checkout instead? Point the installer at this directory,
+e.g. `uv tool install /path/to/saga`. To upgrade: `uv tool install --force saga-cli`.
+
+## Usage
+
+From inside the repo you want to review:
+
+```sh
+saga --base main --head my-feature -o saga.html --open
+```
+
+Run it from anywhere with `--repo`:
+
+```sh
+saga --repo ~/src/some-project --base main --head my-feature -o out.html
+```
+
+| Flag                   | Default                     | Meaning                                                                                            |
+| ---------------------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
+| `--base`               | `main`                      | Base ref to diff against                                                                           |
+| `--head`               | current branch              | Head ref to walk through                                                                           |
+| `--intent PATH`        | —                           | Optional plan/spec describing the change's intent, for plan-aware narration and deviation flagging |
+| `--model`              | `anthropic/claude-opus-4-8` | `provider/model` string (see [Providers](#providers)); also `$SAGA_MODEL`                          |
+| `-o, --output`         | `saga.html`                 | Output file                                                                                        |
+| `--repo`               | cwd                         | A path inside the target git repo                                                                  |
+| `--open` / `--no-open` | on                          | Open the result in a browser (on by default; `--no-open` to disable)                               |
+
+## Providers
+
+The model is a single `provider/model` string, dispatched through `instructor`.
+Choose it with `--model` or the `SAGA_MODEL` environment variable, and set
+the matching API key:
+
+| Provider   | `--model` example                        | API key env var      |
+| ---------- | ---------------------------------------- | -------------------- |
+| Anthropic  | `anthropic/claude-opus-4-8`              | `ANTHROPIC_API_KEY`  |
+| OpenAI     | `openai/gpt-4o`                          | `OPENAI_API_KEY`     |
+| OpenRouter | `openrouter/anthropic/claude-3.5-sonnet` | `OPENROUTER_API_KEY` |
+
+```sh
+export SAGA_MODEL=openai/gpt-4o
+export OPENAI_API_KEY=sk-…
+saga --base main --head my-feature -o saga.html
+```
+
+## As a Claude Code skill
+
+The `skills/` directory contains two Claude Code skills. To install both:
+
+```sh
+cp -R "$(pwd)/skills" ~/.claude/skills/saga
+```
+
+- **`saga`** — say **"/saga"** (or "give me a walkthrough of this branch") to generate a
+  saga. It resolves the base/head refs and runs the tool for you.
+- **`saga-comments`** — say **"/saga-comments"** (or "address the saga comments") to read an
+  exported `saga.comments.json` and act on the reviewer's feedback in code.
+
+## Reviewing: comments
+
+The saga page is also a lightweight review surface. Open `saga.html` and leave three
+kinds of comments — **inline** (click a line's number in any chapter's diff), **per-file**
+(the "💬 File comment" control in each file header), and one **overall** review comment
+(the box at the top of the Chapters list). Comments are drafted in your browser's
+`localStorage`, so they survive a reload.
+
+When you're done, click **Export comments** to download a `saga.comments.json` sidecar next
+to the HTML. (Export is disabled in the [hosted example](https://jakeberesford.github.io/saga/example.html)
+so it never writes a file — every other part of the review UX works.) Two commands consume it:
+
+```sh
+# Post everything as a single PENDING review on the PR (you submit it on GitHub).
+saga comments push --comments saga.comments.json
+
+# Emit the comments as JSON on stdout — for a coding agent to act on.
+saga comments read --comments saga.comments.json
+```
+
+`push` uses the `gh` CLI: it finds the open PR for the sidecar's branch and creates one
+pending review (inline → line comments, per-file → a note anchored to the file's first
+changed line, overall → the review body). Nothing is submitted until you review and submit
+it on GitHub. Requires the [`gh`](https://cli.github.com) CLI, authenticated.
+
+## How it works
+
+1. `diff.py` computes `git diff base...head` (no checkout) and the commit list.
+2. `model.py` splits the diff into stable-id hunks (`h0, h1, …`).
+3. `generate.py` sends the labeled diff + commits (+ optional intent) to the chosen
+   model via `instructor`, which returns chapters as schema-validated JSON. Coverage
+   is **re-validated in code** — every hunk must belong to a chapter or generation fails.
+4. `render.py` reconstructs each chapter's diff and inlines everything into one
+   self-contained HTML file.
+
+## Not included (yet)
+
+- Support for Local LLMs via ollama / LM Studio
+- A GitHub Action to auto-generate saga on PRs.

saga_cli-0.1.0/RELEASING.md

@@ -0,0 +1,34 @@
+# Releasing
+
+Releases are published to PyPI **manually, by the sole maintainer**. There is
+no CI publish workflow by design — nothing but a local machine holding the
+maintainer's token can push a release.
+
+## One-time setup
+
+1. On [PyPI](https://pypi.org): create the account, enable **2FA**, and remain
+   the **sole Owner** of `saga-cli`. Do not add other Owners or Maintainers.
+2. For the **first** upload the project does not exist yet, so create an
+   **account-scoped** API token, publish once (below), then immediately create a
+   **project-scoped** token for `saga-cli` and delete the account-scoped one.
+3. Store the token locally only — e.g. `~/.pypirc`, or export it per release:
+   ```sh
+   export UV_PUBLISH_TOKEN=pypi-…
+   ```
+
+## Cutting a release
+
+```sh
+# 1. Bump the version in pyproject.toml, commit, and tag
+git tag v0.1.0 && git push origin main --tags
+
+# 2. Build clean and publish
+rm -rf dist
+uv build
+uv publish            # uses UV_PUBLISH_TOKEN, or ~/.pypirc
+
+# 3. Cut a matching GitHub Release for the tag (changelog / notes)
+```
+
+Verify the upload with `pip index versions saga-cli` or by visiting the PyPI
+project page.