saga-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{saga_cli-0.2.0 → saga_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: saga-cli
-Version: 0.2.0
+Version: 0.3.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
@@ -42,6 +42,8 @@ the data). Open it offline, email it, commit it, or drop it on any static host.
 
 - Python 3.11+
 - `git`
+- The [`gh`](https://cli.github.com) CLI, authenticated — only for reviewing a PR
+  by URL (`saga <pr-url>`) or pushing review comments
 - An API key for your chosen provider, in the standard environment variable:
   `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY` — or a running
   local server (Ollama / LM Studio) and no key, with a `local/` model
@@ -83,14 +85,32 @@ Run it from anywhere with `--repo`:
 saga --repo ~/src/some-project --base main --head my-feature -o out.html
 ```
 
+### From a GitHub PR URL
+
+Point saga straight at a pull request by passing its URL as the first argument.
+No checkout is needed and it works from any directory:
+
+```sh
+saga https://github.com/owner/repo/pull/5
+saga https://github.com/owner/repo/pull/5 --model openai/gpt-4o -o pr5.html
+```
+
+This fetches the PR's diff, commits, and branch names with the
+[`gh`](https://cli.github.com) CLI (so `gh` must be installed and authenticated),
+then builds the saga exactly as it would for a local branch. In this mode the PR
+defines the change set, so `--base`, `--head`, and `--repo` are ignored.
+
+The optional positional argument is a GitHub PR URL (as above); all flags below
+apply to both modes.
+
 | Flag                   | Default                     | Meaning                                                                                            |
 | ---------------------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
-| `--base`               | `main`                      | Base ref to diff against                                                                           |
-| `--head`               | current branch              | Head ref to walk through                                                                           |
+| `--base`               | auto-detected               | Base ref to diff against (defaults to the repo's default branch, e.g. `origin/main`); local mode only |
+| `--head`               | current branch              | Head ref to walk through; local mode only                                                          |
 | `--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                                                                  |
+| `--repo`               | cwd                         | A path inside the target git repo; local mode only                                                |
 | `--open` / `--no-open` | on                          | Open the result in a browser (on by default; `--no-open` to disable)                               |
 
 ## Providers
@@ -194,7 +214,8 @@ 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.
+1. `diff.py` computes `git diff base...head` (no checkout) and the commit list —
+   or, given a PR URL, fetches the same diff and metadata from GitHub via `gh`.
 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

{saga_cli-0.2.0 → saga_cli-0.3.0}/README.md

@@ -15,6 +15,8 @@ the data). Open it offline, email it, commit it, or drop it on any static host.
 
 - Python 3.11+
 - `git`
+- The [`gh`](https://cli.github.com) CLI, authenticated — only for reviewing a PR
+  by URL (`saga <pr-url>`) or pushing review comments
 - An API key for your chosen provider, in the standard environment variable:
   `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY` — or a running
   local server (Ollama / LM Studio) and no key, with a `local/` model
@@ -56,14 +58,32 @@ Run it from anywhere with `--repo`:
 saga --repo ~/src/some-project --base main --head my-feature -o out.html
 ```
 
+### From a GitHub PR URL
+
+Point saga straight at a pull request by passing its URL as the first argument.
+No checkout is needed and it works from any directory:
+
+```sh
+saga https://github.com/owner/repo/pull/5
+saga https://github.com/owner/repo/pull/5 --model openai/gpt-4o -o pr5.html
+```
+
+This fetches the PR's diff, commits, and branch names with the
+[`gh`](https://cli.github.com) CLI (so `gh` must be installed and authenticated),
+then builds the saga exactly as it would for a local branch. In this mode the PR
+defines the change set, so `--base`, `--head`, and `--repo` are ignored.
+
+The optional positional argument is a GitHub PR URL (as above); all flags below
+apply to both modes.
+
 | Flag                   | Default                     | Meaning                                                                                            |
 | ---------------------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
-| `--base`               | `main`                      | Base ref to diff against                                                                           |
-| `--head`               | current branch              | Head ref to walk through                                                                           |
+| `--base`               | auto-detected               | Base ref to diff against (defaults to the repo's default branch, e.g. `origin/main`); local mode only |
+| `--head`               | current branch              | Head ref to walk through; local mode only                                                          |
 | `--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                                                                  |
+| `--repo`               | cwd                         | A path inside the target git repo; local mode only                                                |
 | `--open` / `--no-open` | on                          | Open the result in a browser (on by default; `--no-open` to disable)                               |
 
 ## Providers
@@ -167,7 +187,8 @@ 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.
+1. `diff.py` computes `git diff base...head` (no checkout) and the commit list —
+   or, given a PR URL, fetches the same diff and metadata from GitHub via `gh`.
 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

{saga_cli-0.2.0 → saga_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "saga-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Generate a self-contained static HTML saga of a git diff — a chapter-by-chapter guided tour of a change."
 readme = "README.md"
 requires-python = ">=3.11"

{saga_cli-0.2.0 → saga_cli-0.3.0}/saga/assets/saga.css

@@ -13,16 +13,42 @@
 }
 .saga-theme-toggle:hover { border-color: var(--accent); color: var(--text); }
 
-.saga-crumbs { font-size: var(--fs-sm); color: var(--text-dim); margin-bottom: 10px; }
+.saga-crumbs { font-size: var(--fs-sm); color: var(--text-dim); margin-bottom: 8px; }
 .saga-crumbs a { color: var(--accent); text-decoration: none; }
 .saga-crumbs a:hover { color: var(--accent-bright); text-decoration: underline; }
-.saga-crumb-sep { margin: 0 8px; color: var(--text-faint); }
-.saga-crumb-current { color: var(--text); }
+
+.header h1 { line-height: 1.2; }
+
+.saga-summary {
+  color: var(--text-dim);
+  font-size: var(--fs-md);
+  line-height: 1.45;
+  margin-top: 4px;
+}
+
+.saga-statusline {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: 8px 24px;
+  flex-wrap: wrap;
+  margin-top: 10px;
+}
 
 .saga-verdict {
   color: var(--text-dim);
   font-size: var(--fs-sm);
-  margin-top: 6px;
+  font-family: var(--font-mono);
+  letter-spacing: var(--tracking-mono);
+}
+.saga-verdict .saga-flag { color: var(--warn); }
+/* diff add/remove hues, matching the diff body's green/red */
+.saga-verdict .saga-add { color: var(--ok); }
+.saga-verdict .saga-del { color: var(--danger); }
+
+.saga-meta {
+  color: var(--text-faint);
+  font-size: var(--fs-xs);
   font-family: var(--font-mono);
   letter-spacing: var(--tracking-mono);
 }
@@ -86,15 +112,11 @@
   border: 1px solid var(--line); color: var(--text-dim); background: var(--surface-2);
 }
 .saga-plan { color: var(--text-dim); }
-.saga-qa { color: var(--ok); border-color: var(--ok-solid); background: var(--ok-tint); }
 .saga-read { color: var(--accent); border-color: var(--accent-solid); background: var(--accent-tint); }
-/* Deviations must be loud. */
-.saga-dev {
-  color: var(--danger-ink); background: var(--danger-loud); border-color: var(--danger); font-weight: 600;
-}
-/* Low confidence flagged for close review (amber). */
-.saga-low {
-  color: var(--warn-ink); background: var(--warn); border-color: var(--warn-solid); font-weight: 600;
+/* Agent attention flags (QA, differs-from-plan, closer-look) share one calm
+   amber; the label carries the meaning, not the colour. */
+.saga-qa, .saga-dev, .saga-low {
+  color: var(--warn); border-color: var(--warn-solid); background: var(--warn-tint);
 }
 
 /* --- chapter reader --- */
@@ -120,10 +142,10 @@
 .saga-chapter-head { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
 .saga-chapter-title { font-size: var(--fs-xl); font-weight: 600; margin: 0; }
 
-/* Loud deviation banner. */
+/* Differs-from-plan banner (amber attention, same family as low-confidence). */
 .saga-deviation {
-  background: var(--danger-loud-bg); border: 1px solid var(--danger); border-left: 4px solid var(--danger);
-  color: var(--danger-ink); border-radius: var(--radius); padding: 12px 16px; margin: 14px 0; font-size: var(--fs-base);
+  background: var(--warn-tint); border: 1px solid var(--warn-solid); border-left: 4px solid var(--warn);
+  color: var(--warn); border-radius: var(--radius); padding: 12px 16px; margin: 14px 0; font-size: var(--fs-base);
 }
 .saga-lowconf {
   background: var(--warn-tint); border: 1px solid var(--warn-solid); border-left: 4px solid var(--warn);
@@ -139,7 +161,7 @@
   font-family: var(--font-mono); font-size: var(--fs-sm);
 }
 
-.saga-qanote { color: var(--ok); font-size: var(--fs-sm); margin: 8px 0; }
+.saga-qanote { color: var(--warn); font-size: var(--fs-sm); margin: 8px 0; }
 
 .saga-readmark {
   display: inline-flex; align-items: center; gap: 6px;

{saga_cli-0.2.0 → saga_cli-0.3.0}/saga/assets/saga.js

@@ -303,28 +303,65 @@
     chapters = data.chapters || [];
     comments = loadComments();
     initTheme();
-    renderVerdict(data.verdict);
+    renderHead();
+    renderVerdict(data.verdict, data.stats);
     renderTOC();
   }
 
+  // --- header (title, summary, provenance) ----------------------------
+
+  function renderHead() {
+    if (data.title) $('saga-title').textContent = data.title;
+    const sum = $('saga-summary');
+    if (sum && data.summary) { sum.textContent = data.summary; sum.hidden = false; }
+    const meta = $('saga-meta');
+    if (meta) {
+      const parts = [];
+      if (data.commit_sha) parts.push(data.commit_sha.slice(0, 7));
+      const rel = relativeTime(data.generated_at);
+      if (rel) parts.push('generated ' + rel);
+      meta.textContent = parts.join(' · ');
+    }
+  }
+
+  function relativeTime(iso) {
+    if (!iso) return '';
+    const then = new Date(iso).getTime();
+    if (isNaN(then)) return '';
+    const secs = Math.round((Date.now() - then) / 1000);
+    if (secs < 60) return 'just now';
+    const units = [['year', 31536000], ['month', 2592000], ['week', 604800],
+                   ['day', 86400], ['hour', 3600], ['minute', 60]];
+    for (const [name, size] of units) {
+      const n = Math.floor(secs / size);
+      if (n >= 1) return n + ' ' + name + (n === 1 ? '' : 's') + ' ago';
+    }
+    return 'just now';
+  }
+
   // --- verdict line --------------------------------------------------
 
-  function renderVerdict(v) {
+  function renderVerdict(v, stats) {
     if (!v) return;
-    const parts = [
-      v.chapters + (v.chapters === 1 ? ' chapter' : ' chapters'),
-      v.deviations + (v.deviations === 1 ? ' deviation' : ' deviations'),
-      v.low_confidence + ' low-confidence',
-    ];
-    if (v.qa && v.qa !== 'n/a') parts.push('QA ' + v.qa);
-    $('saga-verdict').textContent = parts.join(' · ');
-    // Shift the top status rail to the loudest state present:
-    // deviation (red) > attention (amber) > clear (green).
+    // Scope segments read neutral; attention flags echo the amber rail so a
+    // reviewer can spot what needs a look. All text is generated (no user
+    // content), so building innerHTML here is injection-safe.
+    const seg = [{ t: v.chapters + (v.chapters === 1 ? ' chapter' : ' chapters') }];
+    if (stats && stats.files) seg.push({ t: stats.files + (stats.files === 1 ? ' file' : ' files') });
+    if (stats && (stats.added || stats.removed)) {
+      seg.push({ html: '<span class="saga-add">+' + (stats.added || 0) + '</span> ' +
+                       '<span class="saga-del">−' + (stats.removed || 0) + '</span>' });
+    }
+    if (v.deviations > 0) seg.push({ t: v.deviations + (v.deviations === 1 ? ' differs from plan' : ' differ from plan'), flag: true });
+    if (v.low_confidence > 0) seg.push({ t: v.low_confidence + (v.low_confidence === 1 ? ' needs a closer look' : ' need a closer look'), flag: true });
+    $('saga-verdict').innerHTML = seg
+      .map((s) => (s.html ? s.html : s.flag ? '<span class="saga-flag">' + s.t + '</span>' : s.t))
+      .join(' · ');
+    // Two-tier status rail: amber when anything is flagged, else green.
     const rail = $('saga-rail');
     if (rail) {
-      rail.classList.remove('saga-rail-ok', 'saga-rail-attn', 'saga-rail-dev');
-      if (v.deviations > 0) rail.classList.add('saga-rail-dev');
-      else if (v.low_confidence > 0 || v.qa === 'attention') rail.classList.add('saga-rail-attn');
+      rail.classList.remove('saga-rail-ok', 'saga-rail-attn');
+      if (v.deviations > 0 || v.low_confidence > 0) rail.classList.add('saga-rail-attn');
       else rail.classList.add('saga-rail-ok');
     }
   }
@@ -334,9 +371,9 @@
   function badges(ch, read) {
     const out = [];
     if (ch.plan_step) out.push('<span class="saga-badge saga-plan">' + esc(ch.plan_step) + '</span>');
-    if (ch.deviation) out.push('<span class="saga-badge saga-dev">⚠ Deviation</span>');
-    if (ch.confidence === 'low') out.push('<span class="saga-badge saga-low">Low confidence</span>');
-    if (ch.qa && ch.qa.status === 'green') out.push('<span class="saga-badge saga-qa">✓ QA</span>');
+    if (ch.deviation) out.push('<span class="saga-badge saga-dev">Differs from plan</span>');
+    if (ch.confidence === 'low') out.push('<span class="saga-badge saga-low">Needs a closer look</span>');
+    if (ch.qa) out.push('<span class="saga-badge saga-qa">⚠ QA</span>');
     if (read) out.push('<span class="saga-badge saga-read">✓ Read</span>');
     return out.join('');
   }
@@ -390,13 +427,13 @@
     reader.hidden = false;
 
     const devBanner = ch.deviation
-      ? '<div class="saga-deviation"><strong>⚠ Deviation from plan.</strong> ' + esc(ch.deviation) + '</div>'
+      ? '<div class="saga-deviation"><strong>Differs from the plan.</strong> ' + esc(ch.deviation) + ' Worth confirming this was intentional.</div>'
       : '';
     const lowBanner = ch.confidence === 'low'
-      ? '<div class="saga-lowconf">Low confidence — this chapter needs close review.</div>'
+      ? '<div class="saga-lowconf"><strong>Needs a closer look.</strong> The walkthrough is unsure here — read the diff rather than just trusting the summary.</div>'
       : '';
-    const qaLine = ch.qa && ch.qa.note
-      ? '<div class="saga-qanote">' + (ch.qa.status === 'green' ? '✓ ' : '') + esc(ch.qa.note) + '</div>'
+    const qaLine = ch.qa
+      ? '<div class="saga-qanote">⚠ Manual QA: ' + esc(ch.qa) + '</div>'
       : '';
 
     // Class-based (not id-based) so the same nav can render at top and bottom.

{saga_cli-0.2.0 → saga_cli-0.3.0}/saga/assets/tokens.css

@@ -1,9 +1,9 @@
 /* Saga — design tokens ("instrument ink").
  *
  * Single source of truth for the saga page. A cool CYAN accent means
- * "a human can act here" (links, focus), and a strict three-light status system
- * — green (clear) · amber (attention) · red (deviation) — is reserved for the
- * agent's own state and never used as chrome.
+ * "a human can act here" (links, focus), and a two-light status system
+ * — green (clear) · amber (attention) — signals the agent's own state and is
+ * never used as chrome. Red is reserved for errors and destructive actions.
  *
  * Every colour is a light-dark(light, dark) pair. The page follows the OS by
  * default (color-scheme: light dark); the reader's toggle forces a scheme by
@@ -49,12 +49,11 @@
   --warn-ink:   light-dark(#ffffff, #1b1200);  /* text on a solid amber fill */
   --warn-tint:  light-dark(rgba(154,103,0,0.12), rgba(224,168,62,0.15));
 
-  --danger:        light-dark(#c62828, #f2685f);   /* deviation               */
+  --danger:        light-dark(#c62828, #f2685f);   /* errors, destructive     */
   --danger-bright: light-dark(#a51f1f, #ff9c94);
   --danger-ink:    light-dark(#5c1512, #ffe1de);   /* text on a loud red fill */
   --danger-tint:   light-dark(rgba(198,40,40,0.10), rgba(242,104,95,0.14));
-  --danger-loud:   light-dark(#fbe3e1, #b62324);   /* loud deviation fill     */
-  --danger-loud-bg:light-dark(#fdecea, #3d1518);   /* loud deviation panel bg */
+  --danger-loud-bg:light-dark(#fdecea, #3d1518);   /* error panel bg          */
   --danger-loud-border:light-dark(#c62828, #f2685f);
 
   /* --- diff shading (derived from status hues) --- */
@@ -129,7 +128,7 @@
 /* --- signature: the status rail ------------------------------------
  * A thin backlit edge across the top of the page. It shifts colour to
  * the most important state present:
- * accent (idle) · green (clear) · amber (attention) · red (deviation).
+ * accent (idle) · green (clear) · amber (attention).
  */
 .saga-rail {
   height: 2px;
@@ -138,4 +137,3 @@
 }
 .saga-rail-ok   { --rail: var(--ok); }
 .saga-rail-attn { --rail: var(--warn); }
-.saga-rail-dev  { --rail: var(--danger); }

saga_cli-0.3.0/saga/cli.py

@@ -0,0 +1,186 @@
+"""Generate a self-contained PR saga as a static HTML page.
+
+Installs a ``saga`` command usable from any repo. Needs Python 3, git, and
+an API key for the chosen provider (``ANTHROPIC_API_KEY`` / ``OPENAI_API_KEY`` /
+``OPENROUTER_API_KEY``) — or, with a ``local/`` model, a running Ollama or
+LM Studio server and no key, or the ``claude-cli`` model, a logged-in Claude
+Code CLI (e.g. a Claude subscription, no key). Run from inside the repo you
+want to review:
+
+    saga --base main --head my-feature -o saga.html --open
+
+Or point it straight at a pull request by URL (via the ``gh`` CLI; no checkout
+needed, works from any directory):
+
+    saga https://github.com/owner/repo/pull/5 --model openai/gpt-4o
+
+Defaults: base=auto-detected (e.g. origin/main), head=current branch (HEAD),
+output=saga.html, model=anthropic/claude-opus-4-8 (override --model or $SAGA_MODEL).
+Pass --intent PATH to give the model a plan/spec for richer, plan-aware narration.
+"""
+
+from __future__ import annotations
+
+import webbrowser
+from importlib.metadata import version as package_version
+from pathlib import Path
+
+import typer
+from typer.core import TyperArgument, TyperGroup
+
+from .comments import comments_app
+from .diff import (
+    compute_diff,
+    current_branch,
+    default_base,
+    pr_diff,
+    repo_root_from,
+    rev_parse,
+)
+from .generate import generate
+from .model import SagaError
+from .render import render
+
+
+class SagaGroup(TyperGroup):
+    """Let the top-level command take an optional positional target (a PR URL)
+    while still dispatching subcommands like ``saga comments``.
+
+    Click would otherwise make the group's positional argument swallow a
+    subcommand name, and it forbids options after a positional. So: when the
+    first token names a subcommand, drop the positional for that parse; otherwise
+    allow options to follow the target (``saga <url> --model …``).
+    """
+
+    def parse_args(self, ctx, args):
+        if args and args[0] in self.commands:
+            saved = self.params
+            self.params = [p for p in saved if not isinstance(p, TyperArgument)]
+            try:
+                return super().parse_args(ctx, args)
+            finally:
+                self.params = saved
+        ctx.allow_interspersed_args = True
+        return super().parse_args(ctx, args)
+
+
+app = typer.Typer(
+    name="saga",
+    help="Generate a self-contained PR saga as static HTML.",
+    add_completion=False,
+    cls=SagaGroup,
+)
+app.add_typer(comments_app, name="comments")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"saga {package_version('saga-cli')}")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    target: str | None = typer.Argument(
+        None,
+        help=(
+            "a GitHub PR URL to build a saga for "
+            "(e.g. https://github.com/owner/repo/pull/5); "
+            "omit to use local git refs"
+        ),
+    ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="show the installed saga version and exit",
+        is_eager=True,
+        callback=_version_callback,
+    ),
+    base: str | None = typer.Option(
+        None, help="base ref (default: auto-detected, e.g. origin/main)"
+    ),
+    head: str = typer.Option("HEAD", help="head ref to walk through (default: HEAD)"),
+    intent: Path | None = typer.Option(
+        None, help="optional path to a plan/spec describing the change's intent"
+    ),
+    model: str = typer.Option(
+        "anthropic/claude-opus-4-8",
+        envvar="SAGA_MODEL",
+        help=(
+            "provider/model to use, e.g. anthropic/claude-opus-4-8, openai/gpt-4o, "
+            "openrouter/anthropic/claude-3.5-sonnet, local/qwen2.5-coder:14b, "
+            "claude-cli or claude-cli/sonnet "
+            "(local/ targets Ollama or LM Studio; see $SAGA_LOCAL_BASE_URL. "
+            "claude-cli routes through your logged-in Claude Code CLI) "
+            "(default: $SAGA_MODEL or anthropic/claude-opus-4-8)"
+        ),
+    ),
+    output: Path = typer.Option(
+        Path("saga.html"),
+        "-o",
+        "--output",
+        help="output HTML path (default: saga.html)",
+    ),
+    repo: Path = typer.Option(
+        Path.cwd(), "--repo", help="path inside the target git repo (default: cwd)"
+    ),
+    open_browser: bool = typer.Option(
+        True,
+        "--open/--no-open",
+        help="open the result in a browser (default: on; use --no-open to disable)",
+    ),
+) -> None:
+    """Generate a self-contained PR saga as static HTML."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    intent_text = None
+    if intent is not None:
+        try:
+            intent_text = intent.read_text()
+        except OSError as e:
+            typer.echo(f"error: could not read intent file: {e}", err=True)
+            raise typer.Exit(1) from e
+
+    try:
+        if target is not None:
+            # PR mode: fetch the diff from GitHub; base/head/sha come from the PR,
+            # so --base/--head and a local checkout are not needed.
+            typer.echo(f"Fetching PR {target} …", err=True)
+            pr = pr_diff(target)
+            diff = pr.diff
+            resolved_base, resolved_head, commit_sha = pr.base, pr.head, pr.head_sha
+        else:
+            # Local mode: diff two refs straight from git.
+            repo_root = repo_root_from(repo)
+            if repo_root is None:
+                typer.echo(f"error: {repo} is not inside a git repository.", err=True)
+                raise typer.Exit(1)
+            resolved_base = base if base is not None else default_base(repo_root)
+            resolved_head = current_branch(repo_root) if head == "HEAD" else head
+            diff = compute_diff(repo_root, resolved_base, resolved_head)
+            commit_sha = rev_parse(repo_root, resolved_head)
+
+        typer.echo(f"Generating saga for {resolved_base}...{resolved_head} …", err=True)
+        saga = generate(
+            diff,
+            base=resolved_base,
+            head=resolved_head,
+            commit_sha=commit_sha,
+            model=model,
+            intent=intent_text,
+        )
+        html = render(saga, diff)
+    except SagaError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(1) from e
+
+    output.write_text(html)
+    typer.echo(f"Wrote {output} ({len(saga.chapters)} chapters).", err=True)
+    if open_browser:
+        webbrowser.open(output.resolve().as_uri())
+
+
+if __name__ == "__main__":
+    app()