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

saga_cli-0.3.1/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run *)",
+      "Bash(.venv/bin/python -m pytest tests/test_comments.py -q)"
+    ]
+  }
+}

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: saga-cli
-Version: 0.3.0
+Version: 0.3.1
 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
@@ -176,7 +176,7 @@ boots an agent per run) and subject to your subscription's usage limits.
 
 ## As a Claude Code skill
 
-The `skills/` directory contains two Claude Code skills. To install both:
+The `skills/` directory contains a Claude Code skill. To install it:
 
 ```sh
 cp -R "$(pwd)/skills" ~/.claude/skills/saga
@@ -184,8 +184,6 @@ 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
 
@@ -195,19 +193,20 @@ kinds of comments — **inline** (click a line's number in any chapter's diff),
 (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:
+When you're done, click one of the copy buttons. Each puts a ready-to-run command on your
+clipboard with the comments encoded inline (`--data`), so there's no file to find on disk —
+paste it wherever you need it:
 
 ```sh
-# Post everything as a single PENDING review on the PR (you submit it on GitHub).
-saga comments push --comments saga.comments.json
+# "Copy for GitHub" → post everything as a single PENDING review (you submit it on GitHub).
+saga comments push --data <base64>
 
-# Emit the comments as JSON on stdout — for a coding agent to act on.
-saga comments read --comments saga.comments.json
+# "Copy for agent" → emit the comments as JSON on stdout for a coding agent to act on.
+saga comments read --data <base64>
 ```
 
-`push` uses the `gh` CLI: it finds the open PR for the sidecar's branch and creates one
+Prefer a file? Both commands also accept `--comments <path>` for a `saga.comments.json` you
+write yourself (handy for scripting). `push` uses the `gh` CLI: it finds the open PR for the 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.

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

@@ -149,7 +149,7 @@ boots an agent per run) and subject to your subscription's usage limits.
 
 ## As a Claude Code skill
 
-The `skills/` directory contains two Claude Code skills. To install both:
+The `skills/` directory contains a Claude Code skill. To install it:
 
 ```sh
 cp -R "$(pwd)/skills" ~/.claude/skills/saga
@@ -157,8 +157,6 @@ 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
 
@@ -168,19 +166,20 @@ kinds of comments — **inline** (click a line's number in any chapter's diff),
 (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:
+When you're done, click one of the copy buttons. Each puts a ready-to-run command on your
+clipboard with the comments encoded inline (`--data`), so there's no file to find on disk —
+paste it wherever you need it:
 
 ```sh
-# Post everything as a single PENDING review on the PR (you submit it on GitHub).
-saga comments push --comments saga.comments.json
+# "Copy for GitHub" → post everything as a single PENDING review (you submit it on GitHub).
+saga comments push --data <base64>
 
-# Emit the comments as JSON on stdout — for a coding agent to act on.
-saga comments read --comments saga.comments.json
+# "Copy for agent" → emit the comments as JSON on stdout for a coding agent to act on.
+saga comments read --data <base64>
 ```
 
-`push` uses the `gh` CLI: it finds the open PR for the sidecar's branch and creates one
+Prefer a file? Both commands also accept `--comments <path>` for a `saga.comments.json` you
+write yourself (handy for scripting). `push` uses the `gh` CLI: it finds the open PR for the 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.

{saga_cli-0.3.0 → saga_cli-0.3.1}/docs/example.html

@@ -520,8 +520,8 @@ window.__sagaData = {"branch": "tui-gui", "base": "main", "verdict": {"chapters"
 // diff). This file renders it — a table of contents (the entry point) and a
 // chapter reader — tracks per-chapter mark-as-read in localStorage, and lets a
 // reviewer leave inline / per-file / overall comments (also drafted in
-// localStorage) that Export downloads as a saga.comments.json sidecar. No
-// server, no fetch.
+// localStorage) that the Copy buttons hand off to the `saga comments` CLI as a
+// base64 `--data` payload. No server, no fetch.
 
 (function () {
   const data = window.__sagaData || {chapters: [], verdict: null, branch: ''};
@@ -588,7 +588,7 @@ window.__sagaData = {"branch": "tui-gui", "base": "main", "verdict": {"chapters"
     localStorage.setItem(readKey(), JSON.stringify([...s]));
   }
 
-  // --- comments (localStorage draft, exported as a sidecar) ----------
+  // --- comments (localStorage draft, copied to the CLI as --data) ----
 
   let comments = {files: {}, overall: ''};
 
@@ -779,15 +779,64 @@ window.__sagaData = {"branch": "tui-gui", "base": "main", "verdict": {"chapters"
     });
   }
 
-  function exportComments() {
-    // Hosted demo: export is disabled so the example never writes a
-    // saga.comments.json sidecar. The button still confirms visually.
-    const btn = $('saga-export');
-    if (!btn) return;
-    const label = btn.textContent;
-    btn.textContent = 'Exported ✓';
-    btn.disabled = true;
-    setTimeout(() => { btn.textContent = label; btn.disabled = false; }, 1500);
+  // Assemble the comments payload — the same shape the CLI validates.
+  function buildPayload() {
+    const files = {};
+    Object.keys(comments.files).forEach((p) => {
+      const e = comments.files[p];
+      const inline = (e.inline || []).filter((c) => c.body && c.body.trim());
+      const fc = (e.file_comment || '').trim();
+      if (!inline.length && !fc) return;
+      const out = {};
+      if (fc) {
+        out.file_comment = fc;
+        if (e.file_anchor) out.file_anchor = e.file_anchor;
+      }
+      if (inline.length) out.inline = inline;
+      files[p] = out;
+    });
+    return {
+      branch: data.branch || '',
+      base: data.base || '',
+      overall: (comments.overall || '').trim(),
+      files: files,
+    };
+  }
+
+  // base64(UTF-8 JSON) — the payload rides inside the copied command as
+  // `--data`, so the reviewer never has to find a file on disk.
+  function encodePayload() {
+    const bytes = new TextEncoder().encode(JSON.stringify(buildPayload()));
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+  }
+
+  function copyText(text) {
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      return navigator.clipboard.writeText(text);
+    }
+    // file:// fallback where the async clipboard API is unavailable.
+    const ta = document.createElement('textarea');
+    ta.value = text;
+    ta.style.position = 'fixed';
+    ta.style.opacity = '0';
+    document.body.appendChild(ta);
+    ta.select();
+    try { document.execCommand('copy'); } finally { ta.remove(); }
+    return Promise.resolve();
+  }
+
+  // Copy a ready-to-run `saga comments <sub> --data …` command. The reviewer
+  // pastes it into their terminal (push) or coding agent (read).
+  function copyCommand(sub, btn) {
+    const cmd = 'saga comments ' + sub + ' --data ' + encodePayload();
+    copyText(cmd).then(() => {
+      const label = btn.dataset.label;
+      btn.textContent = 'Copied ✓';
+      btn.disabled = true;
+      setTimeout(() => { btn.textContent = label; btn.disabled = false; }, 1500);
+    });
   }
 
   // --- entry ----------------------------------------------------------
@@ -796,28 +845,65 @@ window.__sagaData = {"branch": "tui-gui", "base": "main", "verdict": {"chapters"
     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');
     }
   }
@@ -827,9 +913,9 @@ window.__sagaData = {"branch": "tui-gui", "base": "main", "verdict": {"chapters"
   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('');
   }
@@ -845,7 +931,8 @@ window.__sagaData = {"branch": "tui-gui", "base": "main", "verdict": {"chapters"
       '<textarea id="saga-overall" class="saga-cmt-input saga-overall" placeholder="Overall review comment…"></textarea>' +
       '<div class="saga-review-actions">' +
       '<span class="saga-cmt-count" id="saga-cmt-count"></span>' +
-      '<button class="saga-btn" id="saga-export">Export comments</button>' +
+      '<button class="saga-btn" id="saga-copy-agent" data-label="Copy for agent">Copy for agent</button>' +
+      '<button class="saga-btn" id="saga-copy-gh" data-label="Copy for GitHub">Copy for GitHub</button>' +
       '</div>' +
       '</div>' +
       '<h2 class="saga-toc-title">Chapters</h2>';
@@ -867,8 +954,10 @@ window.__sagaData = {"branch": "tui-gui", "base": "main", "verdict": {"chapters"
       overall.value = comments.overall || '';
       overall.addEventListener('input', () => { comments.overall = overall.value; persist(); });
     }
-    const exp = $('saga-export');
-    if (exp) exp.addEventListener('click', exportComments);
+    const agentBtn = $('saga-copy-agent');
+    if (agentBtn) agentBtn.addEventListener('click', () => copyCommand('read', agentBtn));
+    const ghBtn = $('saga-copy-gh');
+    if (ghBtn) ghBtn.addEventListener('click', () => copyCommand('push', ghBtn));
     updateCount();
   }
 
@@ -883,13 +972,13 @@ window.__sagaData = {"branch": "tui-gui", "base": "main", "verdict": {"chapters"
     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.3.0 → saga_cli-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "saga-cli"
-version = "0.3.0"
+version = "0.3.1"
 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.3.0 → saga_cli-0.3.1}/saga/assets/base.css

@@ -17,6 +17,12 @@ body { font-family: var(--font-sans); background: var(--bg); color: var(--text);
 .d2h-file-diff { background: var(--bg); }
 .d2h-code-line-ctn, .d2h-code-line { background: var(--bg) !important; color: var(--text) !important; }
 .d2h-code-linenumber { background: var(--surface) !important; color: var(--text-faint) !important; border-color: var(--line) !important; }
+/* Wrap long lines instead of overflowing the file wrapper (its overflow:hidden
+   was clipping them). diff2html defaults to a fixed-width nowrap/pre line; here
+   the code line fills its cell and wraps, hang-indented past the
+   absolutely-positioned line-number gutter (~7.5em wide). */
+.d2h-code-line { display: block; width: auto; padding: 0 1em 0 8em; white-space: normal; }
+.d2h-code-line-ctn { display: inline; width: auto; white-space: pre-wrap; overflow-wrap: anywhere; }
 .d2h-del { background: var(--diff-del-bg) !important; }
 .d2h-ins { background: var(--diff-add-bg) !important; }
 .d2h-del .d2h-code-line-ctn { background: var(--diff-del-bg) !important; }

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

@@ -237,6 +237,11 @@
 .saga-file-cmt-panel[hidden] { display: none; }
 .saga-file-cmt-panel .saga-cmt-input { flex: 1 1 240px; min-height: 44px; }
 
+/* The clickable file path in a diff header inherits diff2html's file-name colour;
+   only the hover underline distinguishes it, keeping the header uncluttered. */
+.saga-file-link { color: inherit; text-decoration: none; }
+.saga-file-link:hover { text-decoration: underline; }
+
 /* --- narrow screens: tighten the reader gutter (the 1000px max-width already
    goes fluid below that width) and shrink the chapter title. --- */
 @media (max-width: 640px) {

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

@@ -5,8 +5,8 @@
 // diff). This file renders it — a table of contents (the entry point) and a
 // chapter reader — tracks per-chapter mark-as-read in localStorage, and lets a
 // reviewer leave inline / per-file / overall comments (also drafted in
-// localStorage) that Export downloads as a saga.comments.json sidecar. No
-// server, no fetch.
+// localStorage) that the Copy buttons hand off to the `saga comments` CLI as a
+// base64 `--data` payload. No server, no fetch.
 
 (function () {
   const data = window.__sagaData || {chapters: [], verdict: null, branch: ''};
@@ -73,7 +73,7 @@
     localStorage.setItem(readKey(), JSON.stringify([...s]));
   }
 
-  // --- comments (localStorage draft, exported as a sidecar) ----------
+  // --- comments (localStorage draft, copied to the CLI as --data) ----
 
   let comments = {files: {}, overall: ''};
 
@@ -242,12 +242,44 @@
     btn.addEventListener('click', () => { panel.hidden = !panel.hidden; });
   }
 
+  // Build a link for a diff file path — a local editor/file URL or a GitHub blob
+  // URL, per data.file_links — or null when there is nothing to link to.
+  function fileURL(path) {
+    const fl = data.file_links;
+    if (!fl) return null;
+    // diff2html shows renames as "old → new"; link the new path.
+    const rel = path.split(' → ').pop().trim();
+    if (fl.type === 'github') {
+      return fl.base + '/' + rel.split('/').map(encodeURIComponent).join('/');
+    }
+    const abs = fl.root.replace(/\/+$/, '') + '/' + rel;
+    return (fl.scheme === 'file' ? 'file://' : fl.scheme + '://file') + encodeURI(abs);
+  }
+
+  // Turn a diff2html file name into a link that opens the file (editor/GitHub).
+  function linkifyFileName(fw, path) {
+    const url = fileURL(path);
+    if (!url) return;
+    const nameEl = fw.querySelector('.d2h-file-name');
+    if (!nameEl || nameEl.querySelector('a.saga-file-link')) return;
+    const a = document.createElement('a');
+    a.className = 'saga-file-link';
+    a.href = url;
+    a.target = '_blank';
+    a.rel = 'noopener';
+    a.title = 'Open ' + path;
+    a.textContent = nameEl.textContent;
+    nameEl.textContent = '';
+    nameEl.appendChild(a);
+  }
+
   // After a chapter's diff is drawn, make its lines and files commentable.
   function wireComments(container) {
     container.querySelectorAll('.d2h-file-wrapper').forEach((fw) => {
       const nameEl = fw.querySelector('.d2h-file-name');
       const path = nameEl ? nameEl.textContent.trim() : '';
       if (!path) return;
+      linkifyFileName(fw, path);
       wireFileComment(fw, path);
       fw.querySelectorAll('tr').forEach((tr) => {
         const lnCell = tr.querySelector('td.d2h-code-linenumber');
@@ -264,7 +296,8 @@
     });
   }
 
-  function exportComments() {
+  // Assemble the comments payload — the same shape the CLI validates.
+  function buildPayload() {
     const files = {};
     Object.keys(comments.files).forEach((p) => {
       const e = comments.files[p];
@@ -279,22 +312,48 @@
       if (inline.length) out.inline = inline;
       files[p] = out;
     });
-    const sidecar = {
+    return {
       branch: data.branch || '',
       base: data.base || '',
-      generated_at: new Date().toISOString(),
       overall: (comments.overall || '').trim(),
       files: files,
     };
-    const blob = new Blob([JSON.stringify(sidecar, null, 2)], {type: 'application/json'});
-    const url = URL.createObjectURL(blob);
-    const a = document.createElement('a');
-    a.href = url;
-    a.download = 'saga.comments.json';
-    document.body.appendChild(a);
-    a.click();
-    a.remove();
-    URL.revokeObjectURL(url);
+  }
+
+  // base64(UTF-8 JSON) — the payload rides inside the copied command as
+  // `--data`, so the reviewer never has to find a file on disk.
+  function encodePayload() {
+    const bytes = new TextEncoder().encode(JSON.stringify(buildPayload()));
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+  }
+
+  function copyText(text) {
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      return navigator.clipboard.writeText(text);
+    }
+    // file:// fallback where the async clipboard API is unavailable.
+    const ta = document.createElement('textarea');
+    ta.value = text;
+    ta.style.position = 'fixed';
+    ta.style.opacity = '0';
+    document.body.appendChild(ta);
+    ta.select();
+    try { document.execCommand('copy'); } finally { ta.remove(); }
+    return Promise.resolve();
+  }
+
+  // Copy a ready-to-run `saga comments <sub> --data …` command. The reviewer
+  // pastes it into their terminal (push) or coding agent (read).
+  function copyCommand(sub, btn) {
+    const cmd = 'saga comments ' + sub + ' --data ' + encodePayload();
+    copyText(cmd).then(() => {
+      const label = btn.dataset.label;
+      btn.textContent = 'Copied ✓';
+      btn.disabled = true;
+      setTimeout(() => { btn.textContent = label; btn.disabled = false; }, 1500);
+    });
   }
 
   // --- entry ----------------------------------------------------------
@@ -389,7 +448,8 @@
       '<textarea id="saga-overall" class="saga-cmt-input saga-overall" placeholder="Overall review comment…"></textarea>' +
       '<div class="saga-review-actions">' +
       '<span class="saga-cmt-count" id="saga-cmt-count"></span>' +
-      '<button class="saga-btn" id="saga-export">Export comments</button>' +
+      '<button class="saga-btn" id="saga-copy-agent" data-label="Copy for agent">Copy for agent</button>' +
+      '<button class="saga-btn" id="saga-copy-gh" data-label="Copy for GitHub">Copy for GitHub</button>' +
       '</div>' +
       '</div>' +
       '<h2 class="saga-toc-title">Chapters</h2>';
@@ -411,8 +471,10 @@
       overall.value = comments.overall || '';
       overall.addEventListener('input', () => { comments.overall = overall.value; persist(); });
     }
-    const exp = $('saga-export');
-    if (exp) exp.addEventListener('click', exportComments);
+    const agentBtn = $('saga-copy-agent');
+    if (agentBtn) agentBtn.addEventListener('click', () => copyCommand('read', agentBtn));
+    const ghBtn = $('saga-copy-gh');
+    if (ghBtn) ghBtn.addEventListener('click', () => copyCommand('push', ghBtn));
     updateCount();
   }
 

{saga_cli-0.3.0 → saga_cli-0.3.1}/saga/cli.py

@@ -21,6 +21,7 @@ Pass --intent PATH to give the model a plan/spec for richer, plan-aware narratio
 
 from __future__ import annotations
 
+import os
 import webbrowser
 from importlib.metadata import version as package_version
 from pathlib import Path
@@ -41,6 +42,29 @@ from .generate import generate
 from .model import SagaError
 from .render import render
 
+# GUI editors that register a URL protocol, so a browser can open a file in
+# them via <scheme>://file/<abs-path>. Keyed by the binary $EDITOR/$VISUAL names.
+_EDITOR_SCHEMES = {
+    "code": "vscode",
+    "code-insiders": "vscode-insiders",
+    "codium": "vscodium",
+    "cursor": "cursor",
+    "windsurf": "windsurf",
+}
+
+
+def _editor_scheme() -> str:
+    """URL scheme for the diff's file-path links, inferred from ``$VISUAL``/``$EDITOR``.
+
+    Only editors that register a URL protocol can be opened from a browser, so an
+    unrecognised or terminal editor (vim, nano, …) falls back to ``file`` — the OS
+    default handler. ``$EDITOR`` may carry a path and flags (``/usr/bin/code -w``),
+    so we match on the bare binary name.
+    """
+    raw = os.environ.get("VISUAL") or os.environ.get("EDITOR") or ""
+    binary = Path(raw.split()[0]).name if raw.strip() else ""
+    return _EDITOR_SCHEMES.get(binary, "file")
+
 
 class SagaGroup(TyperGroup):
     """Let the top-level command take an optional positional target (a PR URL)
@@ -151,6 +175,12 @@ def main(
             pr = pr_diff(target)
             diff = pr.diff
             resolved_base, resolved_head, commit_sha = pr.base, pr.head, pr.head_sha
+            # No local checkout, so link file paths to the file on GitHub at the
+            # PR's head commit (repo URL is the PR URL minus its /pull/<n> tail).
+            file_links = {
+                "type": "github",
+                "base": f"{pr.url.split('/pull/')[0]}/blob/{pr.head_sha}",
+            }
         else:
             # Local mode: diff two refs straight from git.
             repo_root = repo_root_from(repo)
@@ -161,6 +191,12 @@ def main(
             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)
+            # Link file paths to the local file, opened in the reader's editor.
+            file_links = {
+                "type": "local",
+                "root": str(repo_root),
+                "scheme": _editor_scheme(),
+            }
 
         typer.echo(f"Generating saga for {resolved_base}...{resolved_head} …", err=True)
         saga = generate(
@@ -171,7 +207,7 @@ def main(
             model=model,
             intent=intent_text,
         )
-        html = render(saga, diff)
+        html = render(saga, diff, file_links=file_links)
     except SagaError as e:
         typer.echo(f"error: {e}", err=True)
         raise typer.Exit(1) from e

{saga_cli-0.3.0 → saga_cli-0.3.1}/saga/comments.py

@@ -1,20 +1,24 @@
-"""The ``saga comments`` subcommands: sidecar IO, GitHub push, agent read.
+"""The ``saga comments`` subcommands: comment 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:
+A reviewer authors comments in the browser (see ``assets/saga.js``); the page's
+"Copy" buttons put a ready-to-run command on the clipboard, with the comments
+base64-encoded inline as ``--data`` — so nothing has to be found on disk. This
+module consumes those comments 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.
+Both accept the base64 ``--data`` payload or, as a scripting escape hatch, a
+``--comments`` file. 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 base64
+import binascii
 import json
 import subprocess
 import sys
@@ -30,35 +34,29 @@ _FILE_NOTE_PREFIX = "**File-level note:** "
 
 
 # ---------------------------------------------------------------------------
-# Sidecar IO
+# Comment IO
 # ---------------------------------------------------------------------------
 
 
-def load_sidecar(path: Path) -> dict:
-    """Read and validate a ``saga.comments.json`` sidecar.
+def _validate(data: object) -> dict:
+    """Validate a decoded comments object, whatever source it came from.
 
     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").
+    a non-object, a bad ``files`` map, or an inline comment lacking
+    ``line``/``body``.
     """
-    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.")
+        raise SagaError("comments 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", []):
+        inline = entry.get("inline", [])
+        if not isinstance(inline, list):
+            raise SagaError(f"'inline' for {fpath} must be a list.")
+        for c in 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'."
@@ -66,6 +64,48 @@ def load_sidecar(path: Path) -> dict:
     return data
 
 
+def load_sidecar(path: Path) -> dict:
+    """Read and validate a ``saga.comments.json`` file (the scripting fallback).
+
+    Callers handle a *missing* file themselves (it means "no comments yet"); an
+    unreadable or malformed file is a real error.
+    """
+    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
+    return _validate(data)
+
+
+def decode_payload(encoded: str) -> dict:
+    """Decode+validate the base64 comments payload from the page's Copy button."""
+    try:
+        raw = base64.b64decode(encoded, validate=True).decode("utf-8")
+    except (binascii.Error, ValueError, UnicodeDecodeError) as e:
+        raise SagaError(f"comments payload is not valid base64: {e}") from e
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise SagaError(f"comments payload is not valid JSON: {e}") from e
+    return _validate(data)
+
+
+def _resolve(data: str | None, sidecar_path: Path) -> dict:
+    """Resolve comments from the ``--data`` payload or a ``--comments`` file.
+
+    ``--data`` is the primary path and wins when present. A *missing* file means
+    "no comments yet" (empty dict); a bad payload or malformed file is an error.
+    """
+    if data is not None:
+        return decode_payload(data)
+    path = Path(sidecar_path)
+    return load_sidecar(path) if path.exists() else {}
+
+
 # ---------------------------------------------------------------------------
 # GitHub review payload (pure)
 # ---------------------------------------------------------------------------
@@ -167,10 +207,11 @@ def _pr_info(repo_root: Path, branch: str) -> tuple[int, str]:
 # ---------------------------------------------------------------------------
 
 
-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 {}
+def push(
+    sidecar_path: Path, repo_root: Path, *, data: str | None = None, web: bool = False
+) -> int:
+    """Post the reviewer's comments as a single pending review on the PR."""
+    sidecar = _resolve(data, sidecar_path)
 
     payload = build_review_payload(sidecar)
     if not payload:
@@ -207,15 +248,14 @@ def push(sidecar_path: Path, repo_root: Path, *, web: bool = False) -> int:
     return 0
 
 
-def read(sidecar_path: Path) -> int:
-    """Print the sidecar's comments as normalized JSON on stdout.
+def read(sidecar_path: Path, *, data: str | None = None) -> int:
+    """Print the reviewer'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).
+    This command feeds a coding agent, so *no comments* is not an error —
+    an absent ``--data`` and a missing file both report a valid, empty JSON
+    document. A payload or file that exists but is malformed still errors.
     """
-    path = Path(sidecar_path)
-    sidecar = load_sidecar(path) if path.exists() else {}
+    sidecar = _resolve(data, sidecar_path)
     print(json.dumps(_normalize_for_agent(sidecar), indent=2, ensure_ascii=False))
     return 0
 
@@ -226,8 +266,12 @@ comments_app = typer.Typer(
 )
 
 
+_DATA_HELP = "base64 comments payload from the saga page's Copy button"
+
+
 @comments_app.command("push")
 def push_cmd(
+    data: str = typer.Option(None, "--data", help=_DATA_HELP),
     comments: Path = typer.Option(_DEFAULT_SIDECAR, "--comments"),
     repo: Path = typer.Option(Path.cwd(), "--repo"),
     web: bool = typer.Option(
@@ -240,7 +284,7 @@ def push_cmd(
         typer.echo(f"error: {repo} is not inside a git repository.", err=True)
         raise typer.Exit(1)
     try:
-        push(comments, repo_root, web=web)
+        push(comments, repo_root, data=data, web=web)
     except SagaError as e:
         typer.echo(f"error: {e}", err=True)
         raise typer.Exit(1) from e
@@ -248,11 +292,12 @@ def push_cmd(
 
 @comments_app.command("read")
 def read_cmd(
+    data: str = typer.Option(None, "--data", help=_DATA_HELP),
     comments: Path = typer.Option(_DEFAULT_SIDECAR, "--comments"),
 ) -> None:
     """Print comments as JSON on stdout (for a coding agent)."""
     try:
-        read(comments)
+        read(comments, data=data)
     except SagaError as e:
         typer.echo(f"error: {e}", err=True)
         raise typer.Exit(1) from e

{saga_cli-0.3.0 → saga_cli-0.3.1}/saga/render.py

@@ -70,12 +70,14 @@ def _diffstat(diff_text: str) -> dict:
     return {"files": files, "added": added, "removed": removed}
 
 
-def build_payload(saga: Saga, diff: DiffResult) -> dict:
+def build_payload(saga: Saga, diff: DiffResult, file_links: dict | None = None) -> dict:
     """Attach each chapter's reconstructed diff to the saga for the client.
 
     The hunk map is built from the same *diff* generation used, so every stored
     hunk id resolves to its diff text — whether the diff came from local git or
-    a fetched PR.
+    a fetched PR. *file_links* tells the client how to turn each diff file path
+    into a link (a local editor/file URL, or a GitHub blob URL); ``None`` leaves
+    the paths as plain text.
     """
     hmap = {h.id: h for h in parse_hunks(diff.diff_text)}
     chapters = []
@@ -92,6 +94,7 @@ def build_payload(saga: Saga, diff: DiffResult) -> dict:
         "generated_at": saga.generated_at,
         "verdict": saga.verdict(),
         "stats": _diffstat(diff.diff_text),
+        "file_links": file_links,
         "chapters": chapters,
     }
 
@@ -105,9 +108,9 @@ def _json_for_script(payload: dict) -> str:
     return json.dumps(payload, ensure_ascii=False).replace("<", "\\u003c")
 
 
-def render(saga: Saga, diff: DiffResult) -> str:
+def render(saga: Saga, diff: DiffResult, file_links: dict | None = None) -> str:
     """Build the complete self-contained HTML document for *saga*."""
-    payload = build_payload(saga, diff)
+    payload = build_payload(saga, diff, file_links)
     title = f"{html.escape(saga.title) or 'Saga'} · {html.escape(saga.branch)}"
     styles = "\n".join(
         [

{saga_cli-0.3.0 → saga_cli-0.3.1}/tests/test_cli.py

@@ -36,8 +36,8 @@ def stub_pipeline(monkeypatch):
             chapters=[Chapter(id="c1", title="t", summary="s", narration="n")],
         )
 
-    def fake_render(saga, diff):
-        calls["render"] = dict(saga=saga, diff=diff)
+    def fake_render(saga, diff, file_links=None):
+        calls["render"] = dict(saga=saga, diff=diff, file_links=file_links)
         return "<html>saga</html>"
 
     monkeypatch.setattr(cli, "generate", fake_generate)
@@ -70,6 +70,33 @@ def test_main_happy_path_writes_output(git_repo: Path, tmp_path: Path, stub_pipe
     assert stub_pipeline["generate"]["intent"] is None
 
 
+def test_main_local_file_links_use_editor_scheme(
+    git_repo: Path, tmp_path, stub_pipeline, monkeypatch
+):
+    """A local saga links each path to the file, opened in the reader's editor."""
+    monkeypatch.setenv("EDITOR", "/usr/local/bin/code --wait")
+    monkeypatch.delenv("VISUAL", raising=False)
+    result = runner.invoke(
+        app, ["--repo", str(git_repo), "-o", str(tmp_path / "o.html"), "--no-open"]
+    )
+    assert result.exit_code == 0
+    fl = stub_pipeline["render"]["file_links"]
+    assert fl == {"type": "local", "root": str(git_repo), "scheme": "vscode"}
+
+
+def test_main_unknown_editor_falls_back_to_file_scheme(
+    git_repo: Path, tmp_path, stub_pipeline, monkeypatch
+):
+    """A terminal/unrecognised $EDITOR can't be opened from a browser, so file://."""
+    monkeypatch.setenv("EDITOR", "vim")
+    monkeypatch.delenv("VISUAL", raising=False)
+    result = runner.invoke(
+        app, ["--repo", str(git_repo), "-o", str(tmp_path / "o.html"), "--no-open"]
+    )
+    assert result.exit_code == 0
+    assert stub_pipeline["render"]["file_links"]["scheme"] == "file"
+
+
 def test_main_resolves_head_from_current_branch(
     git_repo: Path, tmp_path, stub_pipeline
 ):
@@ -209,6 +236,11 @@ def test_main_pr_url_uses_pr_metadata(tmp_path, stub_pipeline, monkeypatch):
     assert g["commit_sha"] == "f" * 40
     assert g["model"] == "openai/gpt-4o"
     assert out.read_text() == "<html>saga</html>"
+    # No local checkout, so file paths link to the file on GitHub at the head sha.
+    assert stub_pipeline["render"]["file_links"] == {
+        "type": "github",
+        "base": "https://github.com/o/r/blob/" + "f" * 40,
+    }
 
 
 def test_main_pr_error_maps_to_exit_1(tmp_path, monkeypatch):

{saga_cli-0.3.0 → saga_cli-0.3.1}/tests/test_comments.py

@@ -2,13 +2,25 @@
 GitHub review payload builder. The gh/subprocess paths are side-effectful and
 are not unit tested (matching the repo's test-the-pure-core convention)."""
 
+import base64
 import json
 
 import pytest
 
-from saga.comments import build_review_payload, load_sidecar, push, read
+from saga.comments import (
+    build_review_payload,
+    decode_payload,
+    load_sidecar,
+    push,
+    read,
+)
 from saga.model import SagaError
 
+
+def _encode(obj: dict) -> str:
+    return base64.b64encode(json.dumps(obj).encode()).decode()
+
+
 SIDECAR = {
     "branch": "feature",
     "base": "main",
@@ -143,3 +155,43 @@ def test_load_sidecar_rejects_inline_missing_line(tmp_path):
     p.write_text(json.dumps({"files": {"a.py": {"inline": [{"body": "x"}]}}}))
     with pytest.raises(SagaError, match="needs a 'line' and a 'body'"):
         load_sidecar(p)
+
+
+# --- decode_payload (the --data path) -------------------------------------
+
+
+def test_decode_payload_round_trips_the_sidecar():
+    assert decode_payload(_encode(SIDECAR))["branch"] == "feature"
+
+
+def test_decode_payload_validates_shape():
+    with pytest.raises(SagaError, match="needs a 'line' and a 'body'"):
+        decode_payload(_encode({"files": {"a.py": {"inline": [{"body": "x"}]}}}))
+
+
+def test_decode_payload_rejects_non_base64():
+    with pytest.raises(SagaError, match="not valid base64"):
+        decode_payload("not base64!!")
+
+
+def test_decode_payload_rejects_base64_of_non_json():
+    with pytest.raises(SagaError, match="not valid JSON"):
+        decode_payload(base64.b64encode(b"not json").decode())
+
+
+def test_read_from_data_ignores_missing_file(tmp_path, capsys):
+    # --data wins and no file is touched.
+    rc = read(tmp_path / "does-not-exist.json", data=_encode(SIDECAR))
+    assert rc == 0
+    out = json.loads(capsys.readouterr().out)
+    assert out["overall"] == "Overall this is solid."
+
+
+def test_push_empty_data_reports_no_comments(tmp_path, capsys):
+    rc = push(
+        tmp_path / "unused.json",
+        tmp_path,
+        data=_encode({"branch": "x", "base": "main", "overall": "", "files": {}}),
+    )
+    assert rc == 0
+    assert "No comments to push" in capsys.readouterr().err

{saga_cli-0.3.0 → saga_cli-0.3.1}/tests/test_render.py

@@ -78,6 +78,18 @@ def test_render_uses_saga_title_in_document_and_head(git_repo: Path, stub_vendor
     assert "<title>Add goal mailbox entry point · feature</title>" in html
 
 
+def test_build_payload_carries_file_links(git_repo: Path):
+    """file_links travels to the client verbatim (defaulting to None when absent)."""
+    assert (
+        render_mod.build_payload(_saga_for(), _feature_diff(git_repo))["file_links"]
+        is None
+    )
+
+    fl = {"type": "local", "root": "/repo", "scheme": "vscode"}
+    payload = render_mod.build_payload(_saga_for(), _feature_diff(git_repo), fl)
+    assert payload["file_links"] == fl
+
+
 def test_build_payload_skips_unknown_hunk_ids(git_repo: Path):
     """A chapter referencing a hunk id absent from the live diff must not crash;
     the unknown id is simply dropped from the reconstructed diff."""
@@ -109,7 +121,7 @@ def test_render_escapes_angle_brackets_in_payload(
     """A diff containing ``</script>`` must be escaped so it cannot break out of
     the inlined ``<script>`` tag."""
 
-    def fake_payload(saga, diff):
+    def fake_payload(saga, diff, file_links=None):
         return {
             "branch": "b",
             "base": "m",

{saga_cli-0.3.0 → saga_cli-0.3.1}/uv.lock

@@ -1207,7 +1207,7 @@ wheels = [
 
 [[package]]
 name = "saga-cli"
-version = "0.2.0"
+version = "0.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "anthropic" },

saga_cli-0.3.0/skills/read_saga_comments/SKILL.md

@@ -1,62 +0,0 @@
----
-name: saga-comments
-description: Read a reviewer's saga comments (inline, per-file, and overall) and act on them in code. Use when the user asks you to address or apply saga review comments, says "read the saga comments" or "/saga-comments", or points at a saga.comments.json file.
----
-
-# Saga comments
-
-A reviewer leaves comments on a saga (the HTML guided tour of a diff) in the browser and
-exports them as a `saga.comments.json` sidecar. This skill reads those comments so you can
-act on them. The CLI does the reading — your job is to run it, parse the JSON, and address
-each comment in code.
-
-## Steps
-
-1. **Check the command is installed.** Run `saga --help`. If it is missing, tell the user
-   to install it once (see the tool's README — e.g. `uv tool install saga-cli`), then
-   continue.
-
-2. **Locate the sidecar.** It defaults to `saga.comments.json` in the current directory. If
-   it lives elsewhere, pass `--comments <path>`. When the user names a saga HTML file, the
-   sidecar sits next to it (the reviewer's "Export comments" button downloads it).
-
-3. **Read the comments** from inside the target repo:
-
-   ```sh
-   saga comments read --comments saga.comments.json
-   ```
-
-   The output is JSON:
-
-   ```json
-   {
-     "branch": "my-feature",
-     "base": "main",
-     "overall": "overall review comment, or null",
-     "files": {
-       "<path>": {
-         "file_comment": "per-file note, or null",
-         "inline": [ { "line": 88, "side": "RIGHT", "body": "the note" } ]
-       }
-     }
-   }
-   ```
-
-   `side` is `RIGHT` (a line in the new/head version of the file) or `LEFT` (a line in the
-   old/base version). An empty `files` map with a null `overall` means no comments have been
-   authored yet — tell the user and stop.
-
-4. **Act on each comment** as review feedback to resolve:
-   - `overall` — the high-level ask; keep it in mind across every change.
-   - `file_comment` — a note scoped to the whole file at `<path>`.
-   - each `inline` — open `<path>` at `line` (use `side` to know which version the line
-     refers to) and address the note there.
-
-5. **Report** what you changed for each comment, and verify (run the tests / relevant
-   command) before handing back.
-
-## Notes
-
-- This consumes the local sidecar only — it does **not** fetch from GitHub. Posting the
-  comments to a PR is a separate, user-driven action (`saga comments push`).
-- If the sidecar exists but is malformed, relay the error (written to stderr).