saga-cli 0.1.0__py3-none-any.whl

saga/cli.py

@@ -0,0 +1,100 @@
+"""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``). Run from inside the repo you want to review:
+
+    saga --base main --head my-feature -o saga.html --open
+
+Defaults: base=main, head=current branch (HEAD), output=saga.html,
+model=anthropic/claude-opus-4-8 (override with --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 pathlib import Path
+
+import typer
+
+from .comments import comments_app
+from .diff import current_branch, repo_root_from
+from .generate import generate
+from .model import SagaError
+from .render import render
+
+app = typer.Typer(
+    name="saga",
+    help="Generate a self-contained PR saga as static HTML.",
+    add_completion=False,
+)
+app.add_typer(comments_app, name="comments")
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    base: str = typer.Option("main", help="base ref (default: 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 "
+            "(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
+
+    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)
+
+    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
+
+    resolved_head = current_branch(repo_root) if head == "HEAD" else head
+    typer.echo(f"Generating saga for {base}...{resolved_head} …", err=True)
+    try:
+        saga = generate(repo_root, base, resolved_head, model=model, intent=intent_text)
+        html = render(repo_root, saga)
+    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()

saga/comments.py

@@ -0,0 +1,258 @@
+"""The ``saga comments`` subcommands: sidecar IO, GitHub push, agent read.
+
+A reviewer authors comments in the browser (see ``assets/saga.js``); the page
+exports them as a sidecar ``saga.comments.json`` next to the saga HTML. This
+module consumes that sidecar two ways:
+
+* ``push`` bundles every comment into a single **pending** PR review via the
+  ``gh`` CLI (``event`` omitted ⇒ PENDING) — the reviewer submits it on GitHub.
+* ``read`` emits a normalized JSON view on stdout for a coding agent.
+
+The GitHub subprocess calls mirror ``diff._git`` — stdlib + the ``gh`` CLI only.
+``build_review_payload`` is a pure function so the payload shape is unit-tested
+without touching the network.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import typer
+
+from .diff import repo_root_from
+from .model import SagaError
+
+_DEFAULT_SIDECAR = Path("saga.comments.json")
+_FILE_NOTE_PREFIX = "**File-level note:** "
+
+
+# ---------------------------------------------------------------------------
+# Sidecar IO
+# ---------------------------------------------------------------------------
+
+
+def load_sidecar(path: Path) -> dict:
+    """Read and validate a ``saga.comments.json`` sidecar.
+
+    Raises ``SagaError`` with a reviewer-facing message on any malformed shape —
+    unreadable file, bad JSON, or an inline comment lacking ``line``/``body``.
+    Callers handle a *missing* sidecar themselves (it means "no comments yet").
+    """
+    try:
+        raw = Path(path).read_text()
+    except OSError as e:
+        raise SagaError(f"could not read comments file {path}: {e}") from e
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise SagaError(f"comments file {path} is not valid JSON: {e}") from e
+
+    if not isinstance(data, dict):
+        raise SagaError("comments file must be a JSON object.")
+    files = data.get("files", {})
+    if not isinstance(files, dict):
+        raise SagaError("'files' must be a JSON object keyed by file path.")
+    for fpath, entry in files.items():
+        if not isinstance(entry, dict):
+            raise SagaError(f"file entry for {fpath} must be an object.")
+        for c in entry.get("inline", []):
+            if not isinstance(c, dict) or "line" not in c or "body" not in c:
+                raise SagaError(
+                    f"inline comment on {fpath} needs a 'line' and a 'body'."
+                )
+    return data
+
+
+# ---------------------------------------------------------------------------
+# GitHub review payload (pure)
+# ---------------------------------------------------------------------------
+
+
+def build_review_payload(sidecar: dict) -> dict:
+    """Assemble the body for GitHub's create-review endpoint from a sidecar.
+
+    Inline comments map straight to ``{path, line, side, body}``. Per-file
+    comments are anchored to the file's first changed line (``file_anchor``) and
+    prefixed — GitHub's batch review API has no file-level comment type, so this
+    keeps them inside the one pending review. The overall comment becomes the
+    review ``body``. ``event`` is deliberately absent so the review is PENDING.
+    """
+    body = (sidecar.get("overall") or "").strip()
+    comments: list[dict] = []
+    for path, entry in sidecar.get("files", {}).items():
+        for c in entry.get("inline", []):
+            comments.append(
+                {
+                    "path": path,
+                    "line": c["line"],
+                    "side": c.get("side", "RIGHT"),
+                    "body": c["body"],
+                }
+            )
+        file_comment = (entry.get("file_comment") or "").strip()
+        if file_comment:
+            anchor = entry.get("file_anchor") or {}
+            comments.append(
+                {
+                    "path": path,
+                    "line": anchor.get("line", 1),
+                    "side": anchor.get("side", "RIGHT"),
+                    "body": _FILE_NOTE_PREFIX + file_comment,
+                }
+            )
+
+    payload: dict = {}
+    if body:
+        payload["body"] = body
+    if comments:
+        payload["comments"] = comments
+    return payload
+
+
+def _normalize_for_agent(sidecar: dict) -> dict:
+    """A lean, stable view for a coding agent — drops GitHub-only anchors."""
+    files = {}
+    for path, entry in sidecar.get("files", {}).items():
+        files[path] = {
+            "file_comment": (entry.get("file_comment") or None),
+            "inline": [
+                {"line": c["line"], "side": c.get("side", "RIGHT"), "body": c["body"]}
+                for c in entry.get("inline", [])
+            ],
+        }
+    return {
+        "branch": sidecar.get("branch", ""),
+        "base": sidecar.get("base", ""),
+        "overall": (sidecar.get("overall") or None),
+        "files": files,
+    }
+
+
+# ---------------------------------------------------------------------------
+# gh CLI shell
+# ---------------------------------------------------------------------------
+
+
+def _gh(
+    repo_root: Path, *args: str, input: str | None = None
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["gh", *args],
+        capture_output=True,
+        text=True,
+        cwd=repo_root,
+        input=input,
+    )
+
+
+def _pr_info(repo_root: Path, branch: str) -> tuple[int, str]:
+    """Return ``(pr_number, pr_url)`` for the PR whose head is *branch*."""
+    result = _gh(repo_root, "pr", "view", branch, "--json", "number,url")
+    if result.returncode != 0:
+        raise SagaError(
+            f"could not find an open PR for branch '{branch}': {result.stderr.strip()}"
+        )
+    try:
+        data = json.loads(result.stdout)
+        return int(data["number"]), str(data["url"])
+    except (json.JSONDecodeError, KeyError, ValueError) as e:
+        raise SagaError(f"unexpected gh pr view output: {e}") from e
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+def push(sidecar_path: Path, repo_root: Path, *, web: bool = False) -> int:
+    """Post the sidecar's comments as a single pending review on the PR."""
+    path = Path(sidecar_path)
+    sidecar = load_sidecar(path) if path.exists() else {}
+
+    payload = build_review_payload(sidecar)
+    if not payload:
+        print("No comments to push.", file=sys.stderr)
+        return 0
+
+    branch = sidecar.get("branch")
+    if not branch:
+        raise SagaError("comments file is missing 'branch'; cannot locate the PR.")
+
+    pr_number, pr_url = _pr_info(repo_root, branch)
+    result = _gh(
+        repo_root,
+        "api",
+        "--method",
+        "POST",
+        f"repos/{{owner}}/{{repo}}/pulls/{pr_number}/reviews",
+        "--input",
+        "-",
+        input=json.dumps(payload),
+    )
+    if result.returncode != 0:
+        raise SagaError(f"gh api failed: {result.stderr.strip()}")
+
+    n = len(payload.get("comments", []))
+    print(
+        f"Created a PENDING review on PR #{pr_number} "
+        f"({n} comment{'s' if n != 1 else ''}). Review and submit it on GitHub:\n"
+        f"  {pr_url}/files",
+        file=sys.stderr,
+    )
+    if web:
+        _gh(repo_root, "pr", "view", branch, "--web")
+    return 0
+
+
+def read(sidecar_path: Path) -> int:
+    """Print the sidecar's comments as normalized JSON on stdout.
+
+    This command feeds a coding agent, so a missing sidecar is not an error —
+    "no comments authored yet" is reported as a valid, empty JSON document. A
+    sidecar that exists but is malformed still errors (that is a real problem).
+    """
+    path = Path(sidecar_path)
+    sidecar = load_sidecar(path) if path.exists() else {}
+    print(json.dumps(_normalize_for_agent(sidecar), indent=2, ensure_ascii=False))
+    return 0
+
+
+comments_app = typer.Typer(
+    help="Push saga review comments to GitHub, or read them as JSON.",
+    no_args_is_help=True,
+)
+
+
+@comments_app.command("push")
+def push_cmd(
+    comments: Path = typer.Option(_DEFAULT_SIDECAR, "--comments"),
+    repo: Path = typer.Option(Path.cwd(), "--repo"),
+    web: bool = typer.Option(
+        False, "--web", help="open the PR in a browser after pushing"
+    ),
+) -> None:
+    """Post comments to the PR as a pending GitHub review."""
+    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)
+    try:
+        push(comments, repo_root, web=web)
+    except SagaError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(1) from e
+
+
+@comments_app.command("read")
+def read_cmd(
+    comments: Path = typer.Option(_DEFAULT_SIDECAR, "--comments"),
+) -> None:
+    """Print comments as JSON on stdout (for a coding agent)."""
+    try:
+        read(comments)
+    except SagaError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(1) from e

saga/diff.py

@@ -0,0 +1,79 @@
+"""Git-sourced diff computation for a saga.
+
+Computes the diff of a head ref against a base ref purely from git — no
+checkout, no working-tree changes. Stdlib + the ``git`` CLI only.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class DiffResult:
+    """The computed diff of a ref against a base: text, commit list, diffstat."""
+
+    diff_text: str
+    commits: list[str]
+    diffstat: str
+
+
+def _git(repo_root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args],
+        capture_output=True,
+        text=True,
+        cwd=repo_root,
+    )
+
+
+def compute_diff(repo_root: Path, base: str, ref: str) -> DiffResult:
+    """Compute the diff of *ref* against *base* purely from refs (no checkout).
+
+    ``git diff base...ref`` is a symmetric-difference diff, so it never touches
+    the working tree and works for any local ref, not just the checked-out
+    branch.
+    """
+    diff_result = _git(repo_root, "diff", f"{base}...{ref}")
+    if diff_result.returncode != 0:
+        raise RuntimeError(f"git diff failed: {diff_result.stderr.strip()}")
+
+    log_result = _git(repo_root, "log", "--oneline", f"{base}..{ref}")
+    commits = (
+        log_result.stdout.strip().splitlines() if log_result.returncode == 0 else []
+    )
+
+    stat_result = _git(repo_root, "diff", "--stat", f"{base}...{ref}")
+    diffstat = stat_result.stdout.strip() if stat_result.returncode == 0 else ""
+
+    return DiffResult(
+        diff_text=diff_result.stdout,
+        commits=commits,
+        diffstat=diffstat,
+    )
+
+
+def rev_parse(repo_root: Path, ref: str) -> str:
+    """Return the full SHA *ref* resolves to, or ``""`` if it does not resolve."""
+    result = _git(repo_root, "rev-parse", ref)
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def current_branch(repo_root: Path) -> str:
+    """The checked-out branch name, or ``"HEAD"`` when detached."""
+    result = _git(repo_root, "rev-parse", "--abbrev-ref", "HEAD")
+    name = result.stdout.strip() if result.returncode == 0 else ""
+    return name or "HEAD"
+
+
+def repo_root_from(path: Path) -> Path | None:
+    """The git top-level containing *path*, or ``None`` if not in a repo."""
+    result = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"],
+        capture_output=True,
+        text=True,
+        cwd=path,
+    )
+    return Path(result.stdout.strip()) if result.returncode == 0 else None

saga/generate.py

@@ -0,0 +1,182 @@
+"""Generate a saga for one change set via a single structured LLM call.
+
+The call takes the full diff (every hunk labeled by a stable id), the commit
+messages, and an optional intent document, and returns strict, schema-validated
+JSON. Coverage is re-validated in code before trusting it — nothing the model
+returns is assumed complete.
+
+Provider-agnostic: the model is chosen by a ``provider/model`` string (e.g.
+``anthropic/claude-opus-4-8``, ``openai/gpt-4o``,
+``openrouter/anthropic/claude-3.5-sonnet``) and dispatched through ``instructor``.
+The API key is read from the provider's standard environment variable
+(``ANTHROPIC_API_KEY`` / ``OPENAI_API_KEY`` / ``OPENROUTER_API_KEY``).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Literal
+
+import instructor
+from pydantic import BaseModel, Field
+
+from .diff import DiffResult, compute_diff, rev_parse
+from .model import (
+    Chapter,
+    Hunk,
+    Saga,
+    SagaError,
+    parse_hunks,
+    validate_coverage,
+)
+
+_MAX_TOKENS = 16000
+_OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+_PROMPT_PATH = Path(__file__).resolve().parent / "prompts" / "saga.md"
+
+
+# ---------------------------------------------------------------------------
+# LLM response schema — what the model must return (validated by instructor).
+# Mapped onto the persisted ``Chapter`` dataclass below so model.py's core,
+# validate_coverage, and render.py stay untouched.
+# ---------------------------------------------------------------------------
+
+
+class _QAOut(BaseModel):
+    status: str
+    note: str = ""
+
+
+class _ChapterOut(BaseModel):
+    id: str
+    title: str
+    summary: str
+    narration: str
+    hunks: list[str] = Field(default_factory=list)
+    plan_step: str | None = None
+    confidence: Literal["high", "medium", "low"] = "medium"
+    deviation: str | None = None
+    qa: _QAOut | None = None
+
+
+class _SagaOut(BaseModel):
+    chapters: list[_ChapterOut]
+
+
+def _to_chapter(c: _ChapterOut) -> Chapter:
+    return Chapter(
+        id=c.id,
+        title=c.title,
+        summary=c.summary,
+        narration=c.narration,
+        hunks=list(c.hunks),
+        plan_step=c.plan_step,
+        confidence=c.confidence,
+        deviation=c.deviation or None,
+        qa=c.qa.model_dump() if c.qa else None,
+    )
+
+
+def labeled_diff(hunks: list[Hunk]) -> str:
+    """Render the diff for the prompt with each hunk headed by its stable id."""
+    out: list[str] = []
+    for h in hunks:
+        first = h.body.splitlines()[0] if h.body else ""
+        out.append(f"### HUNK {h.id} — {h.file_path}  ({first.strip()})")
+        out.append(h.body.rstrip("\n"))
+    return "\n".join(out)
+
+
+def _build_message(diff: DiffResult, hunks: list[Hunk], intent: str | None) -> str:
+    """Assemble the user message: intent (optional), commits, and labeled diff."""
+    commits = "\n".join(diff.commits) or "(no commit messages)"
+    intent_block = (
+        ["# Intent (what this change set out to do)", intent.strip(), ""]
+        if intent and intent.strip()
+        else []
+    )
+    return "\n".join(
+        [
+            *intent_block,
+            "# Commits",
+            commits,
+            "",
+            "# Full diff (every hunk must be assigned to a chapter)",
+            labeled_diff(hunks),
+        ]
+    )
+
+
+def _build_client(model: str) -> instructor.Instructor:
+    """Build an instructor client for a ``provider/model`` string.
+
+    OpenRouter is OpenAI-compatible, so it needs an explicit base URL and its own
+    key; Anthropic and OpenAI resolve their keys from the SDK's standard env vars.
+    """
+    provider = model.split("/", 1)[0]
+    try:
+        if provider == "openrouter":
+            key = os.environ.get("OPENROUTER_API_KEY")
+            if not key:
+                raise SagaError("OPENROUTER_API_KEY is not set.")
+            return instructor.from_provider(
+                model, base_url=_OPENROUTER_BASE_URL, api_key=key
+            )
+        return instructor.from_provider(model)
+    except SagaError:
+        raise
+    except Exception as e:
+        raise SagaError(f"Could not initialize model {model!r}: {e}") from e
+
+
+def generate(
+    repo_root: Path,
+    base: str,
+    head: str,
+    *,
+    model: str,
+    intent: str | None = None,
+) -> Saga:
+    """Generate the saga for *base*...*head*.
+
+    Raises ``SagaError`` on an empty diff, a provider/model error, or a
+    coverage gap. The caller renders the error as a user-facing message.
+    """
+    diff = compute_diff(repo_root, base, head)
+    hunks = parse_hunks(diff.diff_text)
+    if not hunks:
+        raise SagaError("No reviewable hunks in this change set.")
+
+    client = _build_client(model)
+    system_prompt = _PROMPT_PATH.read_text()
+    kwargs: dict = {}
+    if model.split("/", 1)[0] == "openrouter":
+        # Ask OpenRouter to route only to providers that support the params we
+        # send (structured output), so schema enforcement is honored.
+        kwargs["extra_body"] = {"provider": {"require_parameters": True}}
+
+    try:
+        result: _SagaOut = client.create(
+            response_model=_SagaOut,
+            max_tokens=_MAX_TOKENS,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": _build_message(diff, hunks, intent)},
+            ],
+            **kwargs,
+        )
+    except SagaError:
+        raise
+    except Exception as e:
+        raise SagaError(f"Saga generation failed: {e}") from e
+
+    chapters = [_to_chapter(c) for c in result.chapters]
+    validate_coverage(chapters, hunks)
+
+    return Saga(
+        branch=head,
+        base=base,
+        commit_sha=rev_parse(repo_root, head),
+        chapters=chapters,
+    )