dsh-hyperframes 0.1.1 → 0.3.0

package/skills/pr-to-video/scripts/captions.test.mjs

@@ -0,0 +1,219 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { brandFontFaces, buildFromSkin } from "./captions.mjs";
+
+const presetsDir = fileURLToPath(
+  new URL("../../hyperframes-creative/frame-presets/", import.meta.url),
+);
+const skins = readdirSync(presetsDir, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory())
+  .map((entry) => ({
+    name: entry.name,
+    source: readFileSync(
+      new URL(
+        `../../hyperframes-creative/frame-presets/${entry.name}/caption-skin.html`,
+        import.meta.url,
+      ),
+      "utf8",
+    ),
+  }))
+  .filter(({ source }) => source.includes(".caption-word.is-active"));
+
+for (const canvas of ["#f7f3e8", "#111827"]) {
+  for (const skin of skins) {
+    test(`${skin.name} preserves word-state rules on ${canvas}`, () => {
+      const active = skin.source.match(/\.caption-word\.is-active\s*\{[^}]*\}/s)?.[0];
+      const spoken = skin.source.match(/\.caption-word\.is-spoken\s*\{[^}]*\}/s)?.[0];
+      assert.ok(active, "skin must define an active-word rule");
+      assert.ok(spoken, "skin must define a spoken-word rule");
+
+      const output = buildFromSkin(
+        skin.source,
+        [],
+        1,
+        1920,
+        1080,
+        `:root { --cap-canvas: ${canvas}; --cap-ink: #111111; --cap-accent: #ffcc00; }`,
+        (message) => {
+          throw new Error(message);
+        },
+      );
+
+      assert.ok(output.includes(active));
+      assert.ok(output.includes(spoken));
+      assert.equal(output.match(/\.caption-word\.is-active\s*\{/g)?.length, 1);
+      assert.equal(output.match(/\.caption-word\.is-spoken\s*\{/g)?.length, 1);
+    });
+  }
+}
+
+// @font-face is document-global on purpose — the composition CSS scoper exempts it, and it
+// has to, since a face declaration cannot be scoped. That makes brandFontFaces the one part
+// of the captions sub-composition whose output reaches every sibling composition, so it has
+// to describe each face exactly: get an axis wrong and the whole document renders the brand
+// family wrong.
+function withFontProject(files, run) {
+  const dir = mkdtempSync(join(tmpdir(), "hf-captions-fonts-"));
+  try {
+    mkdirSync(join(dir, "assets/fonts"), { recursive: true });
+    for (const name of files) writeFileSync(join(dir, "assets/fonts", name), "");
+    writeFileSync(
+      join(dir, "frame.md"),
+      'typography:\n  display: { fontFamily: "Newsreader", weight: 400 }\n  body: { fontFamily: "Inter", weight: 400 }\n',
+    );
+    return run(join(dir, "frame.md"), dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("an italic file is declared italic, and never squats the family's upright slot", () => {
+  // Google Fonts' own Newsreader download. The italic sorts first, so before the style axis
+  // existed it claimed the family's only 400 slot, the upright was dropped as a duplicate,
+  // and the face shipped with no font-style — italicizing every sibling composition that
+  // used Newsreader.
+  const faces = withFontProject(
+    ["Newsreader-Italic-VariableFont_opsz,wght.ttf", "Newsreader-VariableFont_opsz,wght.ttf"],
+    brandFontFaces,
+  );
+  const lines = faces.split("\n").filter((line) => line.includes("Newsreader"));
+  assert.equal(lines.length, 2, "both the upright and the italic file must be declared");
+
+  const upright = lines.find((line) => line.includes("Newsreader-VariableFont"));
+  const italic = lines.find((line) => line.includes("Newsreader-Italic-VariableFont"));
+  assert.ok(upright, "the upright file must survive");
+  assert.match(upright, /font-style: normal/);
+  assert.ok(italic, "the italic file must survive");
+  assert.match(italic, /font-style: italic/);
+});
+
+test("a numeric weight in the filename is read as the weight", () => {
+  // Fontsource names every face numerically and carries no weight WORD, so word-only
+  // parsing scored the whole family 400 and shipped exactly one of its four faces.
+  const faces = withFontProject(
+    [
+      "inter-latin-400-normal.woff2",
+      "inter-latin-500-normal.woff2",
+      "inter-latin-600-italic.woff2",
+      "inter-latin-700-normal.woff2",
+    ],
+    brandFontFaces,
+  );
+  const lines = faces.split("\n").filter((line) => line.includes("Inter"));
+  assert.equal(lines.length, 4, "each face is a distinct weight/style pair");
+  for (const [file, weight, style] of [
+    ["inter-latin-400-normal", 400, "normal"],
+    ["inter-latin-500-normal", 500, "normal"],
+    ["inter-latin-600-italic", 600, "italic"],
+    ["inter-latin-700-normal", 700, "normal"],
+  ]) {
+    const line = lines.find((candidate) => candidate.includes(file));
+    assert.ok(line, `${file} must be declared`);
+    assert.match(line, new RegExp(`font-weight: ${weight};`));
+    assert.match(line, new RegExp(`font-style: ${style};`));
+  }
+});
+
+test("word-named weights still parse when the filename carries no numeric axis", () => {
+  const faces = withFontProject(
+    ["Newsreader_Bold.woff2", "Newsreader_Regular.woff2"],
+    brandFontFaces,
+  );
+  const lines = faces.split("\n").filter((line) => line.includes("Newsreader"));
+  assert.equal(lines.length, 2);
+  assert.match(
+    lines.find((line) => line.includes("Bold")),
+    /font-weight: 700; font-style: normal/,
+  );
+  assert.match(
+    lines.find((line) => line.includes("Regular")),
+    /font-weight: 400; font-style: normal/,
+  );
+});
+
+// build-frame.mjs stages captured brand fonts under a REWRITTEN name, and brandFontFaces
+// derives the face's axes back out of that name. The two are a contract, and it is easy to
+// break silently from either side: build-frame used to drop the style token while renaming,
+// so an italic file arrived as "Newsreader-Regular.ttf" and was declared upright — leaving
+// the document-global normal slot pointing at italic bytes even once brandFontFaces learned
+// about styles. These two tests pin both ends of that contract.
+test("the names build-frame.mjs stages round-trip back to the right face", () => {
+  const faces = withFontProject(
+    [
+      "Newsreader-Regular.ttf",
+      "Newsreader-Regular-Italic.ttf",
+      "Inter-400.woff2",
+      "Inter-600-Italic.woff2",
+    ],
+    brandFontFaces,
+  );
+  for (const [file, weight, style] of [
+    ["Newsreader-Regular.ttf", 400, "normal"],
+    ["Newsreader-Regular-Italic.ttf", 400, "italic"],
+    ["Inter-400.woff2", 400, "normal"],
+    ["Inter-600-Italic.woff2", 600, "italic"],
+  ]) {
+    const line = faces.split("\n").find((candidate) => candidate.includes(`/${file}'`));
+    assert.ok(line, `${file} must be declared`);
+    assert.match(line, new RegExp(`font-weight: ${weight};`));
+    assert.match(line, new RegExp(`font-style: ${style};`));
+  }
+});
+
+test("a weight token buried in a longer run is not read as a weight", () => {
+  // capture/assets/fonts commonly holds hash-named files, and a hash is not a weight.
+  const faces = withFontProject(
+    ["Newsreader-a1b200c3.woff2", "Inter-2100.woff2", "Inter900.woff2"],
+    brandFontFaces,
+  );
+  const weightOf = (file) =>
+    Number(/font-weight: (\d+);/.exec(faces.split("\n").find((l) => l.includes(file)))?.[1]);
+
+  // "200" sits mid-run (…b200c3), so the word path decides: Regular.
+  assert.equal(weightOf("Newsreader-a1b200c3.woff2"), 400);
+  // 4-digit guard: "2100" must not read as 100.
+  assert.equal(weightOf("Inter-2100.woff2"), 400);
+  // ...but a trailing weight with no separator is still a weight.
+  assert.equal(weightOf("Inter900.woff2"), 900);
+});
+
+// captions.mjs ships once per creation workflow because each skill installs standalone,
+// and the three copies are meant to be byte-identical. This PR alone had to land the same
+// two-axis fix in all three; a future one that lands in only one drifts silently.
+test("captions.mjs is byte-identical across the three workflows that ship it", () => {
+  const [first, ...rest] = ["product-launch-video", "faceless-explainer", "pr-to-video"].map(
+    (skill) => ({
+      skill,
+      source: readFileSync(new URL(`../../${skill}/scripts/captions.mjs`, import.meta.url), "utf8"),
+    }),
+  );
+  for (const other of rest) {
+    assert.equal(other.source, first.source, `${other.skill} drifted from ${first.skill}`);
+  }
+});
+
+test("every build-frame.mjs copy stages the style axis it promises", () => {
+  for (const skill of ["product-launch-video", "faceless-explainer", "pr-to-video"]) {
+    const source = readFileSync(
+      new URL(`../../${skill}/scripts/build-frame.mjs`, import.meta.url),
+      "utf8",
+    );
+    // The staged filename must carry the style, or the italic and upright faces of one
+    // weight collide on a single name and only whichever sorts first survives.
+    assert.match(
+      source,
+      /const clean = `\$\{fam\.replace\(\/\[\^A-Za-z0-9\]\/g, ""\)\}-\$\{w\}\$\{style === "italic" \? "-Italic" : ""\}\./,
+      `${skill}/build-frame.mjs must keep the style token in the staged name`,
+    );
+    // ...and the emitted descriptor must report the real style, not a hardcoded normal.
+    assert.doesNotMatch(
+      source,
+      /font-weight:\$\{n\};font-style:normal/,
+      `${skill}/build-frame.mjs must not assert font-style:normal over captured bytes`,
+    );
+  }
+});

package/skills/pr-to-video/scripts/fetch-people-avatars.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// Step 1 — contributor avatar fetch (NETWORK; orchestrator-invoked).
+//
+// The counterpart to ingest.mjs: ingest is a pure offline transform, THIS is the
+// one network step on the people front. It reads the people list ingest produced
+// and downloads each contributor's GitHub avatar into assets/<login>.png,
+// then rewrites people.json with `avatarFetched` flags so downstream (story-design)
+// knows which avatars actually exist.
+//
+// Avatars + a credits/shipped-by scene are the ONE place the faceless default is
+// relaxed. They are an OPTIONAL enhancement, so this script is best-effort:
+//   - a missing/deleted user, a network blip, an offline run → log + skip
+//   - it ALWAYS exits 0 (a failed avatar must never block the build)
+//
+// Network is constrained on purpose: only https GitHub avatar hosts are fetched
+// (SSRF guard), and bytes are only ever written under the project dir (no path
+// traversal), so a tampered people.json can't redirect the fetch or the write.
+//
+// Reads:
+//   --people <path>      capture/extracted/people.json (from ingest.mjs)
+// Writes:
+//   assets/<login>.png    one per contributor whose avatar resolved
+//   (rewrites people.json in place with avatarFetched: true/false)
+//
+// Flags: --project-dir .  --timeout 8000 (ms per request)
+//   Avatars are written to <project-dir>/<person.avatarFile>, where avatarFile is
+//   the project-root-relative "assets/<login>.png" — the SAME assets/ dir the frame
+//   workers reference and assemble-index stages (lib/assets.mjs). Anchor on the
+//   project root so the path stays under the project's assets/.
+//
+// Usage (orchestrator already cd'd into PROJECT_DIR, so --project-dir defaults to "."):
+//   node fetch-people-avatars.mjs --people ./capture/extracted/people.json
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
+import { resolve, join, dirname, sep } from "node:path";
+
+const argv = process.argv.slice(2);
+const flag = (name, def) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
+};
+
+const peoplePath = resolve(flag("people", "./capture/extracted/people.json"));
+const projectDir = resolve(flag("project-dir", "."));
+const TIMEOUT = parseInt(flag("timeout", "8000"), 10);
+
+// SSRF guard: avatars only ever come from GitHub's avatar hosts, so refuse any
+// other URL rather than fetching whatever string people.json happens to carry.
+// `github.com/<login>.png` 302s to avatars.githubusercontent.com (redirect stays
+// on-host, controlled by GitHub).
+const AVATAR_HOSTS = new Set(["avatars.githubusercontent.com", "github.com", "www.github.com"]);
+function isAllowedAvatarUrl(u) {
+  let parsed;
+  try {
+    parsed = new URL(u);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "https:") return false;
+  const host = parsed.hostname.toLowerCase();
+  return AVATAR_HOSTS.has(host) || host.endsWith(".githubusercontent.com");
+}
+
+// Path guard: the written file must stay inside the project dir, so a crafted
+// avatarFile ("../../etc/…") can't escape via join().
+function isUnderProject(p) {
+  const r = resolve(p);
+  return r === projectDir || r.startsWith(projectDir + sep);
+}
+
+// Soft-exit helper — avatars are optional, so every early-out is exit 0.
+function softExit(msg) {
+  console.log(`• fetch-avatars: ${msg}`);
+  process.exit(0);
+}
+
+if (!existsSync(peoplePath)) softExit(`no people.json at ${peoplePath} — skipping (no avatars)`);
+
+let doc;
+try {
+  doc = JSON.parse(readFileSync(peoplePath, "utf8"));
+} catch (e) {
+  softExit(`people.json unreadable (${e.message}) — skipping`);
+}
+
+const people = Array.isArray(doc.people) ? doc.people : [];
+if (!people.length) softExit("no contributors in people.json — skipping");
+
+async function fetchOne(person) {
+  const { login, avatarUrl } = person;
+  if (!login || !avatarUrl) return "skip";
+  if (!isAllowedAvatarUrl(avatarUrl)) {
+    person.avatarFetched = false;
+    console.log(`  (skip avatar @${login}: not a GitHub avatar URL)`);
+    return "fail";
+  }
+  // avatarFile is project-root-relative ("assets/<login>.png"); anchor on the
+  // project root so it stays under the project's assets/ dir.
+  const dest = join(projectDir, person.avatarFile || `assets/${login}.png`);
+  if (!isUnderProject(dest)) {
+    person.avatarFetched = false;
+    console.log(`  (skip avatar @${login}: avatar path escapes the project dir)`);
+    return "fail";
+  }
+  mkdirSync(dirname(dest), { recursive: true });
+  // Idempotent: a non-empty file from a prior run is reused (re-runs are free).
+  if (existsSync(dest) && statSync(dest).size > 0) {
+    person.avatarFetched = true;
+    return "cached";
+  }
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT);
+  try {
+    const res = await fetch(avatarUrl, {
+      signal: ctrl.signal,
+      redirect: "follow", // github.com/<login>.png redirects to avatars.githubusercontent.com
+      headers: { "User-Agent": "hyperframes-pr-to-video" },
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (!buf.length) throw new Error("empty body");
+    writeFileSync(dest, buf);
+    person.avatarFetched = true;
+    return "ok";
+  } catch (e) {
+    person.avatarFetched = false;
+    console.log(`  (skip avatar @${login}: ${e.message})`);
+    return "fail";
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+let ok = 0;
+let cached = 0;
+let fail = 0;
+// Sequential keeps it simple and gentle on github.com; the list is tiny (a PR's
+// contributors), so latency is not a concern.
+for (const person of people) {
+  const r = await fetchOne(person);
+  if (r === "ok") ok++;
+  else if (r === "cached") cached++;
+  else if (r === "fail") fail++;
+}
+
+// Persist avatarFetched flags so story-design can reference only real avatars.
+try {
+  writeFileSync(peoplePath, JSON.stringify(doc, null, 2) + "\n");
+} catch (e) {
+  console.log(`  (warn: could not rewrite people.json flags: ${e.message})`);
+}
+
+console.log(
+  `✓ fetch-avatars: ${ok + cached}/${people.length} avatar(s) in assets/` +
+    ` (${ok} new, ${cached} cached, ${fail} failed)`,
+);
+process.exit(0);

package/skills/pr-to-video/scripts/fetch-pr.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+// Step 1 — PR fetch (deterministic; runs gh; large-PR-safe; NO scratch dir).
+//
+// Replaces a bare `gh pr view … > capture/pr.json` in the orchestrator. It folds
+// the PR into the two artifacts ingest.mjs consumes:
+//   capture/pr.json    the gh pr view core (title, body, author, refs, commits,
+//                      reviews, comments, assignees, +/− stats, …) with its `files`
+//                      list COMPLETED via a paginated `gh api .../pulls/N/files`
+//                      call — `gh pr view --json files` truncates at ~100 files, so a
+//                      big PR would otherwise lose the tail. Commits keep gh pr view's
+//                      rich `authors[]` (co-authors) — only `files` needs the override.
+//                      For MERGED PRs it also stamps a best-effort `shipped_version`
+//                      (+ `version_source`) so the end card / cta doesn't invent one.
+//   capture/diff.patch the full unified diff (`gh pr diff`).
+//
+// gh runs HERE so auth / not-found / private-repo errors surface with gh's own stderr
+// and exit 1 (the orchestrator then stops). Intermediates are held in memory — this
+// writes ONLY the two files above, so there is no `_ingest_tmp/` scratch to clean up
+// (the previous "let the agent fetch in pieces" approach polluted videos/ and was
+// non-deterministic). ingest.mjs stays a pure offline transform downstream.
+//
+// Usage:
+//   node fetch-pr.mjs --pr "<url | owner/repo#N | N>" [--out-dir ./capture]
+//
+// Exit 0 = capture/pr.json + capture/diff.patch written + summary on stdout.
+// Exit 1 = gh not authenticated / PR not found / pr view failed.
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const argv = process.argv.slice(2);
+const flag = (name, def) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
+};
+function die(msg) {
+  console.error(`✗ fetch-pr.mjs: ${msg}`);
+  process.exit(1);
+}
+
+const prRef = flag("pr", null);
+if (!prRef) die('--pr "<url | owner/repo#N | N>" is required');
+const outDir = resolve(flag("out-dir", "./capture"));
+
+// Run gh, capture stdout. Returns { ok, stdout, stderr } — never throws (callers
+// decide whether a failure is fatal). 64 MB buffer covers large diffs / file lists.
+function ghTry(args) {
+  try {
+    const stdout = execFileSync("gh", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    return { ok: true, stdout, stderr: "" };
+  } catch (e) {
+    return {
+      ok: false,
+      stdout: (e.stdout || "").toString(),
+      stderr: (e.stderr || e.message || "").toString().trim(),
+    };
+  }
+}
+
+// ── 0. auth — fail fast with gh's own hint ───────────────────────────────────
+if (!ghTry(["auth", "status"]).ok) {
+  die("gh is not authenticated — run: gh auth login");
+}
+
+// ── 1. core PR object (gh pr view) ───────────────────────────────────────────
+const FIELDS = [
+  "number",
+  "title",
+  "body",
+  "author",
+  "url",
+  "baseRefName",
+  "headRefName",
+  "commits",
+  "files",
+  "additions",
+  "deletions",
+  "changedFiles",
+  "labels",
+  "reviews",
+  "latestReviews",
+  "comments",
+  "assignees",
+  "reviewDecision",
+  "mergedBy",
+  "state",
+  "mergedAt",
+].join(",");
+
+const view = ghTry(["pr", "view", prRef, "--json", FIELDS]);
+if (!view.ok) die(`gh pr view "${prRef}" failed (auth / not found / private?):\n${view.stderr}`);
+
+let pr;
+try {
+  pr = JSON.parse(view.stdout);
+} catch (e) {
+  die(`gh pr view returned unparseable JSON (${e.message})`);
+}
+
+// ── 2. complete the files list via paginated gh api (the truncation fix) ──────
+// gh pr view --json files caps at ~100 files; the REST endpoint paginates with no
+// cap. --jq runs per page, so the output is NDJSON (one file object per line).
+const number = pr.number;
+const m = /github\.com\/([^/]+)\/([^/]+)\/pull\/\d+/.exec(pr.url || "");
+const owner = m?.[1];
+const repo = m?.[2];
+let filesNote = `${Array.isArray(pr.files) ? pr.files.length : 0} (from pr view)`;
+if (owner && repo && number != null) {
+  const apiFiles = ghTry([
+    "api",
+    "--paginate",
+    `repos/${owner}/${repo}/pulls/${number}/files`,
+    "--jq",
+    ".[] | {path: .filename, additions, deletions, status}",
+  ]);
+  if (apiFiles.ok) {
+    const files = apiFiles.stdout
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => {
+        try {
+          return JSON.parse(l);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+    if (files.length) {
+      pr.files = files;
+      if (pr.changedFiles == null || files.length > pr.changedFiles) pr.changedFiles = files.length;
+      filesNote = `${files.length} (completed via gh api)`;
+    }
+  } else {
+    console.error(
+      `  (warn: gh api files failed — keeping pr view's files: ${apiFiles.stderr.split("\n")[0]})`,
+    );
+  }
+} else {
+  console.error("  (warn: could not parse owner/repo from PR url — keeping pr view's files)");
+}
+
+// ── 2.5 best-effort shipping version (MERGED PRs only) ───────────────────────
+// The end card / cta ("upgrade to vN", "what's new in vN") wants a real version;
+// a PR carries none, so the agent would otherwise guess. We resolve one here and
+// stamp it onto pr.json as `shipped_version` (+ a `version_source` note that keeps
+// it honest). `git tag --contains` isn't available on a remote-only fetch, so we
+// use gh api proxies: the first release published at/after the merge is the first
+// tag that can contain the merge commit; failing that, the default branch's
+// package manifest version (unreleased); else null. Always best-effort — a lookup
+// failure just leaves the fields null (the skill then falls back to the repo URL).
+pr.shipped_version = null;
+pr.version_source = null;
+if (pr.state === "MERGED") {
+  const mergedAt = pr.mergedAt ? Date.parse(pr.mergedAt) : NaN;
+
+  // (a) earliest non-draft release published on/after the merge.
+  if (owner && repo && !Number.isNaN(mergedAt)) {
+    const rel = ghTry([
+      "api",
+      "--paginate",
+      `repos/${owner}/${repo}/releases`,
+      "--jq",
+      ".[] | select(.draft == false) | {tag: .tag_name, published: .published_at}",
+    ]);
+    if (rel.ok) {
+      let best = null;
+      for (const line of rel.stdout.split("\n").filter(Boolean)) {
+        let r;
+        try {
+          r = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (!r?.tag || !r?.published) continue;
+        const t = Date.parse(r.published);
+        if (Number.isNaN(t) || t < mergedAt) continue;
+        if (!best || t < best.t) best = { tag: r.tag, t };
+      }
+      if (best) {
+        pr.shipped_version = best.tag;
+        pr.version_source = "first release published at/after merge";
+      }
+    } else {
+      console.error(`  (warn: gh api releases failed: ${rel.stderr.split("\n")[0]})`);
+    }
+  }
+
+  // (b) fallback — default branch's package manifest version (change merged but not
+  //     yet in a tagged release). Marked as unreleased so the skill doesn't present
+  //     it as a shipped tag.
+  if (pr.shipped_version == null && owner && repo) {
+    const pkg = ghTry(["api", `repos/${owner}/${repo}/contents/package.json`, "--jq", ".content"]);
+    if (pkg.ok && pkg.stdout.trim()) {
+      try {
+        const manifest = JSON.parse(Buffer.from(pkg.stdout.trim(), "base64").toString("utf8"));
+        if (manifest?.version) {
+          pr.shipped_version = String(manifest.version);
+          pr.version_source = "default-branch package.json (unreleased)";
+        }
+      } catch {
+        /* not JSON / no version — leave null */
+      }
+    }
+  }
+}
+
+// ── 3. write capture/pr.json + capture/diff.patch ────────────────────────────
+mkdirSync(outDir, { recursive: true });
+const prJsonPath = join(outDir, "pr.json");
+writeFileSync(prJsonPath, JSON.stringify(pr, null, 2) + "\n");
+
+const diff = ghTry(["pr", "diff", prRef]);
+const diffPath = join(outDir, "diff.patch");
+if (diff.ok) {
+  writeFileSync(diffPath, diff.stdout);
+} else {
+  // The brief still builds without the diff (ingest treats it as optional), so this
+  // is a warning, not fatal — but surface it.
+  console.error(
+    `  (warn: gh pr diff failed — brief builds without it: ${diff.stderr.split("\n")[0]})`,
+  );
+}
+
+// ── 4. summary ───────────────────────────────────────────────────────────────
+const repoLabel = owner && repo ? `${owner}/${repo}` : "(repo?)";
+console.log(
+  [
+    `✓ fetch-pr: ${repoLabel} PR #${number ?? "?"} — "${(pr.title || "").slice(0, 72)}"`,
+    `  files: ${filesNote}; diff: ${diff.ok ? `${diff.stdout.length} chars` : "MISSING"}`,
+    `  shipped_version: ${pr.shipped_version ?? "null"}${pr.version_source ? ` (${pr.version_source})` : ""}`,
+    `  wrote ${prJsonPath}${diff.ok ? ` + ${diffPath}` : ""}`,
+  ].join("\n"),
+);