pr-docent 0.1.0 → 0.2.0

package/host/claude.mjs

@@ -0,0 +1,78 @@
+// Running the user's own Claude Code (their subscription) on a pull request in a temporary
+// folder. Shared by tour generation and shorts.
+
+import { spawn } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+
+const TIMEOUT_MS = 15 * 60 * 1000;
+const CONFIG = readConfig();
+let child = null;
+
+/** Written by the installer; without it, use whatever claude is on PATH. */
+function readConfig() {
+  try {
+    return JSON.parse(readFileSync(join(homedir(), ".pr-docent", "config.json"), "utf8"));
+  } catch {
+    return { claude: "claude" };
+  }
+}
+
+/**
+ * A temporary folder with the PR's changed files under repo/ and its diff and details under out/.
+ * Real path: on macOS the temp folder is a symlink, and Claude's write rule must match exactly.
+ */
+export function prepareWorkspace({ files, diff, title, body, headSha }) {
+  const work = realpathSync(mkdtempSync(join(tmpdir(), "pr-docent-")));
+  const repo = join(work, "repo");
+  const out = join(work, "out");
+  mkdirSync(repo);
+  mkdirSync(out);
+  for (const [path, content] of Object.entries(files)) {
+    const target = resolve(repo, path);
+    if (!target.startsWith(repo + sep)) continue; // never write outside the folder
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, content);
+  }
+  writeFileSync(join(out, "pr.diff"), diff);
+  writeFileSync(join(out, "pr.json"), JSON.stringify({ title, body, headRefOid: headSha }, null, 2));
+  return { work, repo, out };
+}
+
+/**
+ * Why Claude Code failed, for the panel to say what to do: "claudeLoggedOut" when its output says
+ * it isn't signed in (Claude Code 2.1: "Not logged in · Please run /login"), otherwise undefined.
+ */
+export function failureCode(output) {
+  return /not logged in|please run \/login|invalid api key|oauth token has expired/i.test(output) ? "claudeLoggedOut" : undefined;
+}
+
+/** Runs `claude -p [prompt]` in [cwd]; reports elapsed seconds every 5s through [onProgress]. */
+export function runClaude(prompt, cwd, args, onProgress = () => {}) {
+  return new Promise((resolvePromise, reject) => {
+    const started = Date.now();
+    let output = "";
+    child = spawn(CONFIG.claude, ["-p", prompt, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    const keep = (chunk) => (output = (output + chunk).slice(-2000));
+    child.stdout.on("data", keep);
+    child.stderr.on("data", keep);
+    const progress = setInterval(() => onProgress(Math.round((Date.now() - started) / 1000)), 5000);
+    const timeout = setTimeout(() => child.kill(), TIMEOUT_MS);
+    child.on("error", (error) =>
+      reject(Object.assign(new Error(`Could not start Claude Code (${CONFIG.claude}): ${error.message}`), { code: "claudeMissing" })),
+    );
+    child.on("close", (code) => {
+      clearInterval(progress);
+      clearTimeout(timeout);
+      child = null;
+      if (code === 0) resolvePromise();
+      else reject(Object.assign(new Error(`Claude Code exited with code ${code}. ${output.trim().slice(-300)}`), { code: failureCode(output) }));
+    });
+  });
+}
+
+/** Stops a running Claude Code, e.g. when the extension disconnects. */
+export function stopClaude() {
+  child?.kill();
+}

package/host/native.mjs

@@ -3,8 +3,9 @@
 import { createHash } from "node:crypto";
 
 export const HOST_NAME = "dev.prdocent.host";
-// Extensions the host accepts by default: the unpacked install, whose ID manifest.json's key fixes.
-export const EXTENSION_IDS = ["hleefogoiedjahnmjgmmgonckaeicppc"];
+// Extensions the host accepts by default: the unpacked install, whose ID manifest.json's key fixes,
+// and the Chrome Web Store release.
+export const EXTENSION_IDS = ["hleefogoiedjahnmjgmmgonckaeicppc", "deejphpcfjilekklajdhdhfepjbenjii"];
 
 /** Chrome native messaging frames each message as a 32-bit little-endian length plus UTF-8 JSON. */
 export function encodeMessage(value) {
@@ -33,8 +34,3 @@ export function extensionIdFromKey(key) {
   const hex = createHash("sha256").update(Buffer.from(key, "base64")).digest("hex").slice(0, 32);
   return [...hex].map((c) => String.fromCharCode(97 + parseInt(c, 16))).join("");
 }
-
-/** Replaces {{NAME}} placeholders; unknown ones are left as they are. */
-export function fillTemplate(text, vars) {
-  return text.replace(/{{(\w+)}}/g, (match, name) => (name in vars ? String(vars[name]) : match));
-}

package/host/pr-docent-host.mjs

@@ -1,110 +1,101 @@
-// Local generator: Chrome starts this through native messaging when the panel asks for a tour.
-// It writes the PR's diff and changed files to a temporary folder, runs the user's own Claude
-// Code (their subscription, no API key) with the same prompt and checker as the GitHub Actions
-// workflow, and sends the checked tour back. Installed by `pr-docent install` (bin/pr-docent.mjs).
+// Local generator: Chrome starts this through native messaging when the panel asks for a tour,
+// a short script, or a video file. Tours: Claude Code (the user's own subscription, no API key)
+// writes one with the same prompt and checker as the GitHub Actions workflow. Shorts: see
+// short.mjs. Installed by `pr-docent install` (bin/pr-docent.mjs).
 
-import { spawn } from "node:child_process";
-import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
-import { dirname, join, resolve, sep } from "node:path";
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkTour, visibleLines } from "../src/diff.js";
+import { changedLineCount, checkTour, visibleLines } from "../src/diff.js";
+import { buildPrompt, checkBrevity, parseGuidelines } from "../src/guidelines.js";
 import { parseTour } from "../src/tour.js";
-import { createDecoder, encodeMessage, fillTemplate } from "./native.mjs";
+import { prepareWorkspace, runClaude, stopClaude } from "./claude.mjs";
+import { createDecoder, encodeMessage } from "./native.mjs";
+import { stopRendering } from "./render-short.mjs";
+import { saveShortVideo, writeShortScript } from "./short.mjs";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const CONFIG = readConfig();
-const TIMEOUT_MS = 15 * 60 * 1000;
-
-let child = null;
 const send = (message) => process.stdout.write(encodeMessage(message));
+// Writing after Chrome closed the pipe fails; there is no one left to tell.
+process.stdout.on("error", () => process.exit(0));
+let busy = false;
 
 process.stdin.on(
   "data",
   createDecoder((message) => {
-    if (message.type !== "generate") return;
-    generate(message)
-      .then((tour) => send({ type: "done", tour }))
-      .catch((error) => send({ type: "error", message: error.message }))
-      .finally(() => process.exit(0));
+    busy = true;
+    const reply = (promise, toMessage) =>
+      promise
+        .then((value) => send(toMessage(value)))
+        .catch((error) => send({ type: "error", message: error.message, code: error.code }))
+        // Exit once stdout has flushed: on macOS pipe writes are asynchronous.
+        .finally(() => process.stdout.write("", () => process.exit(0)));
+    if (message.type === "generate") {
+      reply(generate(message), (tour) => ({ type: "done", tour }));
+    } else if (message.type === "script") {
+      const onProgress = (progress) => send({ type: "progress", ...progress });
+      reply(writeShortScript({ ...message, onProgress }), (short) => ({ type: "done", short }));
+    } else if (message.type === "render") {
+      const onProgress = (progress) => send({ type: "progress", ...progress });
+      reply(saveShortVideo({ short: message.short, onProgress }), (path) => ({ type: "done", path }));
+    } else if (message.type === "reveal") {
+      reply(reveal(message.path), () => ({ type: "done" }));
+    }
   }),
 );
-// Chrome closes stdin when the extension disconnects (panel closed, tab gone): stop Claude too.
+// Chrome closes stdin when the extension disconnects (panel closed, tab gone): stop Claude or the
+// render too, and let the request finish failing so its temporary folder is removed, then exit
+// (from the reply above, or after a grace period).
 process.stdin.on("end", () => {
-  child?.kill();
-  process.exit(0);
+  stopClaude();
+  stopRendering();
+  if (!busy) process.exit(0);
+  setTimeout(() => process.exit(0), 5000);
 });
 
-async function generate({ pr, title, body, headSha, diff, files, model, language }) {
-  // Real path: on macOS the temp folder is a symlink, and the write rule must match exactly.
-  const work = realpathSync(mkdtempSync(join(tmpdir(), "pr-docent-")));
+/** Shows a saved video in Finder; only files this tool writes (pr-docent-*.mp4). */
+function reveal(path) {
+  if (!/\/pr-docent-[^/]+\.mp4$/.test(String(path)) || !existsSync(path)) return Promise.reject(new Error("Not a PR Docent video"));
+  return new Promise((done) => execFile("open", ["-R", path], () => done()));
+}
+
+async function generate({ pr, title, body, headSha, diff, files, guidelines = "", model, language }) {
+  const { work, repo, out } = prepareWorkspace({ files, diff, title, body, headSha });
   try {
-    const repo = join(work, "repo");
-    const out = join(work, "out");
-    mkdirSync(repo);
-    mkdirSync(out);
-    for (const [path, content] of Object.entries(files)) {
-      const target = resolve(repo, path);
-      if (!target.startsWith(repo + sep)) continue; // never write outside the folder
-      mkdirSync(dirname(target), { recursive: true });
-      writeFileSync(target, content);
-    }
-    writeFileSync(join(out, "pr.diff"), diff);
-    writeFileSync(join(out, "pr.json"), JSON.stringify({ title, body, headRefOid: headSha }, null, 2));
+    if (guidelines) writeFileSync(join(out, "guidelines.md"), guidelines);
+    const { limits, errors: guidelineErrors } = parseGuidelines(guidelines);
+    if (guidelineErrors.length) throw new Error(`.github/pr-docent.md: ${guidelineErrors.join(" / ")}`);
+    const changedLines = changedLineCount(diff);
 
     const prRef = `${pr.owner}/${pr.repo}#${pr.number}`;
-    const prompt = fillTemplate(readFileSync(join(ROOT, "scripts", "tour-prompt.md"), "utf8"), {
-      PR: prRef,
-      OUT: out,
-      TOOLS: ROOT,
-      LANGUAGE: language || "한국어",
+    const prompt = buildPrompt(readFileSync(join(ROOT, "scripts", "tour-prompt.md"), "utf8"), {
+      pr: prRef,
+      out,
+      tools: ROOT,
+      language: language || "한국어",
+      changedLines,
+      guidelinesText: guidelines,
     });
     await runClaude(prompt, repo, [
       "--model", model || "claude-opus-5-5",
       "--permission-mode", "dontAsk",
       "--allowedTools", `Read,Glob,Grep,Edit(/${out}/tour.json),Bash(node ${ROOT}/scripts/check-tour.mjs:*)`,
-    ]);
+    ], (seconds) => send({ type: "progress", seconds }));
 
     let raw;
     try {
       raw = JSON.parse(readFileSync(join(out, "tour.json"), "utf8"));
     } catch {
-      throw new Error("Claude가 투어 파일을 만들지 못했습니다.");
+      throw new Error("Claude did not write a tour file.");
     }
     const { tour, errors } = parseTour(raw);
-    const problems = errors.length ? errors : checkTour(tour, visibleLines(diff));
-    if (problems.length) throw new Error(`투어 검사를 통과하지 못했습니다: ${problems.slice(0, 3).join(" / ")}`);
+    const problems = errors.length
+      ? errors
+      : [...checkTour(tour, visibleLines(diff)), ...checkBrevity(tour, { changedLines, limits })];
+    if (problems.length) throw new Error(`The tour did not pass the checks: ${problems.slice(0, 3).join(" / ")}`);
     return raw;
   } finally {
     rmSync(work, { recursive: true, force: true });
   }
 }
-
-/** Written by the installer; without it, use whatever claude is on PATH. */
-function readConfig() {
-  try {
-    return JSON.parse(readFileSync(join(homedir(), ".pr-docent", "config.json"), "utf8"));
-  } catch {
-    return { claude: "claude" };
-  }
-}
-
-function runClaude(prompt, cwd, args) {
-  return new Promise((resolvePromise, reject) => {
-    const started = Date.now();
-    let output = "";
-    child = spawn(CONFIG.claude, ["-p", prompt, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"] });
-    const keep = (chunk) => (output = (output + chunk).slice(-2000));
-    child.stdout.on("data", keep);
-    child.stderr.on("data", keep);
-    const progress = setInterval(() => send({ type: "progress", seconds: Math.round((Date.now() - started) / 1000) }), 5000);
-    const timeout = setTimeout(() => child.kill(), TIMEOUT_MS);
-    child.on("error", (error) => reject(new Error(`Claude Code를 실행하지 못했습니다 (${CONFIG.claude}): ${error.message}`)));
-    child.on("close", (code) => {
-      clearInterval(progress);
-      clearTimeout(timeout);
-      if (code === 0) resolvePromise();
-      else reject(new Error(`Claude Code가 종료 코드 ${code}로 끝났습니다. ${output.trim().slice(-300)}`));
-    });
-  });
-}

package/host/render-short.mjs

@@ -0,0 +1,96 @@
+// Renders a short (see src/short.js) to a vertical MP4 on macOS. Each scene is drawn as HTML
+// diagrams captured by headless Chrome, one frame per element so the picture builds up while the
+// sentence is read; narration comes from `say` (speechSynthesis audio can't be recorded), and
+// ffmpeg joins everything.
+
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { FRAME_HEIGHT as HEIGHT, FRAME_WIDTH as WIDTH, SHORT_CSS, sceneList, sceneMarkup, sceneSteps } from "../src/short-scenes.js";
+
+// Aborted when the extension disconnects, which kills the say, Chrome or ffmpeg run in progress.
+const stopping = new AbortController();
+const run = (command, args) => promisify(execFile)(command, args, { signal: stopping.signal });
+const LEAD_IN = 0.3; // seconds of silence before each sentence
+const TAIL = 0.8; // and after it
+const CHROME_PATHS = [
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/Applications/Chromium.app/Contents/MacOS/Chromium",
+];
+const PREFERRED_VOICES = { ko: ["Yuna (Premium)", "Yuna (Enhanced)", "Yuna"], en: ["Samantha (Premium)", "Samantha (Enhanced)", "Samantha"] };
+
+/** Stops a render in progress: its current subprocess is killed and the render fails. */
+export function stopRendering() {
+  stopping.abort();
+}
+
+/** Writes the MP4 for [short] to [outPath], working in [workDir]. Calls onProgress(text) per scene. */
+export async function renderShort({ short, outPath, workDir, onProgress = () => {} }) {
+  const chrome = CHROME_PATHS.find(existsSync);
+  if (!chrome) throw new Error("Google Chrome was not found in /Applications.");
+  await requireTool("ffmpeg", ["-version"], "ffmpeg is required: brew install ffmpeg");
+  const voice = await pickSayVoice(/[가-힣]/.test(JSON.stringify(short)) ? "ko" : "en");
+  const scenes = sceneList(short);
+  mkdirSync(workDir, { recursive: true });
+
+  const clips = [];
+  for (const [i, scene] of scenes.entries()) {
+    onProgress(`${i + 1}/${scenes.length}`);
+    const base = join(workDir, `scene-${i}`);
+    await run("say", ["-v", voice, "-o", `${base}.aiff`, scene.narration]);
+    const audio = Number((await run("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", `${base}.aiff`])).stdout);
+
+    // One frame per revealed element, spread across the sentence.
+    const steps = sceneSteps(scene);
+    const frames = [];
+    for (let shown = 1; shown <= steps; shown++) {
+      const png = `${base}-${shown}.png`;
+      writeFileSync(`${base}.html`, pageHtml(scene, { short, shown }));
+      await run(chrome, [
+        "--headless=new", "--disable-gpu", "--hide-scrollbars", "--force-device-scale-factor=1",
+        `--user-data-dir=${join(workDir, "chrome-profile")}`, `--window-size=${WIDTH},${HEIGHT}`,
+        `--screenshot=${png}`, `file://${base}.html`,
+      ]);
+      const duration = audio / steps + (shown === 1 ? LEAD_IN : 0) + (shown === steps ? TAIL : 0);
+      frames.push(`file '${png}'\nduration ${duration.toFixed(3)}`);
+    }
+    frames.push(`file '${base}-${steps}.png'`); // the concat demuxer needs the last frame twice
+    writeFileSync(`${base}.txt`, frames.join("\n"));
+
+    const delay = Math.round(LEAD_IN * 1000);
+    await run("ffmpeg", [
+      "-y", "-f", "concat", "-safe", "0", "-i", `${base}.txt`, "-i", `${base}.aiff`,
+      "-filter_complex", `[0:v]fps=30,format=yuv420p[v];[1:a]adelay=${delay}|${delay},apad[a]`,
+      "-map", "[v]", "-map", "[a]", "-t", (LEAD_IN + audio + TAIL).toFixed(2),
+      "-c:v", "libx264", "-c:a", "aac", "-b:a", "160k", "-ar", "44100", "-ac", "2", `${base}.mp4`,
+    ]);
+    clips.push(`${base}.mp4`);
+  }
+
+  onProgress("…");
+  const list = join(workDir, "clips.txt");
+  writeFileSync(list, clips.map((clip) => `file '${clip}'`).join("\n"));
+  await run("ffmpeg", ["-y", "-f", "concat", "-safe", "0", "-i", list, "-c", "copy", "-movflags", "+faststart", outPath]);
+  return outPath;
+}
+
+async function requireTool(command, args, message) {
+  try {
+    await run(command, args);
+  } catch {
+    throw new Error(message);
+  }
+}
+
+async function pickSayVoice(language) {
+  const { stdout } = await run("say", ["-v", "?"]);
+  const names = stdout.split("\n").map((line) => line.split(/\s{2,}/)[0].trim());
+  return PREFERRED_VOICES[language].find((name) => names.includes(name)) ?? (language === "ko" ? "Yuna" : "Samantha");
+}
+
+/** A whole page for the screenshot: the shared frame with nothing around it. */
+function pageHtml(scene, options) {
+  return `<!doctype html><html><head><meta charset="utf-8"><style>body { margin: 0; } ${SHORT_CSS}</style></head>
+    <body><div class="short-frame">${sceneMarkup(scene, options)}</div></body></html>`;
+}

package/host/short-cli.mjs

@@ -0,0 +1,56 @@
+// `pr-docent short <PR>`: makes a short from the terminal with gh instead of the extension.
+// Uses the tour posted in the PR's comments (or --tour <file>).
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { visibleLines } from "../src/diff.js";
+import { findTourInBlocks, parseTour, tourLanguage } from "../src/tour.js";
+import { generateShort } from "./short.mjs";
+
+const gh = (...args) => execFileSync("gh", args, { encoding: "utf8", maxBuffer: 100e6 });
+
+/** "owner/repo#12" or a pull request URL → { owner, repo, number }, or null. */
+export function parsePullRequestRef(text) {
+  const match = String(text).match(/^(?:https:\/\/github\.com\/)?([^/\s#]+)\/([^/\s#]+)(?:#|\/pull\/)(\d+)/);
+  return match ? { owner: match[1], repo: match[2], number: Number(match[3]) } : null;
+}
+
+export async function shortCommand(args) {
+  const pr = parsePullRequestRef(args[0] ?? "");
+  if (!pr) throw new Error("usage: pr-docent short <owner/repo#number | pull request URL> [--tour <file>] [--out <file.mp4>]");
+  const option = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined);
+  const repoArg = `${pr.owner}/${pr.repo}`;
+
+  const details = JSON.parse(gh("pr", "view", String(pr.number), "-R", repoArg, "--json", "title,body,headRefOid,comments"));
+  let tour;
+  if (option("--tour")) {
+    tour = JSON.parse(readFileSync(option("--tour"), "utf8"));
+  } else {
+    const blocks = details.comments.flatMap((c) => [...c.body.matchAll(/```json\n([\s\S]*?)\n```/g)].map((m) => m[1]));
+    tour = findTourInBlocks(blocks, pr);
+    if (!tour) throw new Error("This PR has no tour comment. Generate a tour first, or pass --tour <file>.");
+  }
+  const parsed = parseTour(tour);
+  if (parsed.errors.length) throw new Error(`The tour is invalid: ${parsed.errors[0]}`);
+
+  console.log(`Fetching ${repoArg}#${pr.number}…`);
+  const diff = gh("pr", "diff", String(pr.number), "-R", repoArg);
+  const files = {};
+  for (const path of visibleLines(diff).keys()) {
+    try {
+      files[path] = gh("api", `repos/${repoArg}/contents/${path.split("/").map(encodeURIComponent).join("/")}?ref=${details.headRefOid}`, "-H", "Accept: application/vnd.github.raw");
+    } catch {
+      // deleted or binary at the head commit
+    }
+  }
+  const path = await generateShort({
+    pr, tour, title: details.title, body: details.body, headSha: details.headRefOid, diff, files,
+    language: tourLanguage(parsed.tour) === "ko" ? "한국어" : "English",
+    outPath: option("--out"),
+    onProgress: ({ stage, seconds, detail }) => {
+      if (stage === "script" && seconds % 15 === 0) console.log(`Claude Code is writing the script… ${seconds}s`);
+      if (stage === "render") console.log(`Rendering ${detail}`);
+    },
+  });
+  console.log(`Saved ${path}`);
+}

package/host/short.mjs

@@ -0,0 +1,71 @@
+// Shorts on this computer: Claude Code writes the script from the PR's tour (the panel plays it
+// live), and render-short.mjs turns a script into an MP4 when someone wants a file. Used by the
+// native host and by `pr-docent short` on the command line.
+
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkShort, parseShort } from "../src/short.js";
+import { prepareWorkspace, runClaude } from "./claude.mjs";
+import { renderShort } from "./render-short.mjs";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** Has Claude Code write and check a short script from the PR's tour; returns the raw JSON. */
+export async function writeShortScript({ pr, tour, title, body, headSha, diff, files, language, model, onProgress = () => {} }) {
+  const { work, repo, out } = prepareWorkspace({ files, diff, title, body, headSha });
+  try {
+    writeFileSync(join(out, "tour.json"), JSON.stringify(tour, null, 2));
+    const prRef = `${pr.owner}/${pr.repo}#${pr.number}`;
+    const prompt = readFileSync(join(ROOT, "scripts", "short-prompt.md"), "utf8").replace(/{{(\w+)}}/g, (match, name) =>
+      ({ PR: prRef, OUT: out, TOOLS: ROOT, LANGUAGE: language || "한국어" })[name] ?? match);
+    onProgress({ stage: "script", seconds: 0 });
+    await runClaude(prompt, repo, [
+      "--model", model || "claude-opus-5-5",
+      "--permission-mode", "dontAsk",
+      "--allowedTools", `Read,Glob,Grep,Edit(/${out}/short.json),Bash(node ${ROOT}/scripts/check-short.mjs:*)`,
+    ], (seconds) => onProgress({ stage: "script", seconds }));
+
+    let raw;
+    try {
+      raw = JSON.parse(readFileSync(join(out, "short.json"), "utf8"));
+    } catch {
+      throw new Error("Claude did not write a short script.");
+    }
+    const { short, errors } = parseShort(raw);
+    const problems = errors.length ? errors : checkShort(short);
+    if (problems.length) throw new Error(`The short did not pass the checks: ${problems.slice(0, 3).join(" / ")}`);
+    return raw;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** Renders a checked short script to an MP4 (Downloads unless [outPath]); returns its path. */
+export async function saveShortVideo({ short: raw, outPath, onProgress = () => {} }) {
+  const { short, errors } = parseShort(raw);
+  if (!short) throw new Error(`Invalid short: ${errors[0]}`);
+  const { pr } = short;
+  const work = realpathSync(mkdtempSync(join(tmpdir(), "pr-docent-render-")));
+  try {
+    const target = outPath ?? freePath(join(homedir(), "Downloads"), `pr-docent-${pr.owner}-${pr.repo}-${pr.number}`);
+    return await renderShort({ short, outPath: target, workDir: work, onProgress: (detail) => onProgress({ stage: "render", detail }) });
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** The script and then the video: what `pr-docent short` does. */
+export async function generateShort(options) {
+  const short = await writeShortScript(options);
+  return saveShortVideo({ short, outPath: options.outPath, onProgress: options.onProgress });
+}
+
+/** dir/name.mp4, or dir/name-2.mp4 and so on when that exists. */
+function freePath(dir, name) {
+  for (let i = 1; ; i++) {
+    const path = join(dir, `${name}${i === 1 ? "" : `-${i}`}.mp4`);
+    if (!existsSync(path)) return path;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-docent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Guided, narrated review tours on top of GitHub pull request diffs. This package installs the local tour generator for the PR Docent Chrome extension.",
   "license": "MIT",
@@ -26,12 +26,18 @@
     "bin/",
     "host/",
     "src/diff.js",
+    "src/guidelines.js",
+    "src/short.js",
+    "src/short-scenes.js",
     "src/tour.js",
+    "scripts/check-short.mjs",
     "scripts/check-tour.mjs",
+    "scripts/short-prompt.md",
     "scripts/tour-prompt.md"
   ],
   "scripts": {
     "test": "node --test tests/*.test.mjs",
-    "install-host": "node bin/pr-docent.mjs install"
+    "install-host": "node bin/pr-docent.mjs install",
+    "package": "node scripts/package-extension.mjs"
   }
 }

package/scripts/check-short.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// Validates a short (video script).
+//
+//   node scripts/check-short.mjs <short.json> [owner/repo#number]
+//
+// Prints every problem and exits 1, or prints a one-line summary and exits 0.
+
+import { readFileSync } from "node:fs";
+import { checkShort, parseShort } from "../src/short.js";
+
+const [shortPath, expectedPr] = process.argv.slice(2);
+if (!shortPath) {
+  console.error("usage: node scripts/check-short.mjs <short.json> [owner/repo#number]");
+  process.exit(2);
+}
+
+const fail = (errors) => {
+  console.error(`Short has ${errors.length} problem(s):`);
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+};
+
+let raw;
+try {
+  raw = JSON.parse(readFileSync(shortPath, "utf8"));
+} catch (error) {
+  fail([`${shortPath} is not valid JSON: ${error.message}`]);
+}
+const { short, errors } = parseShort(raw);
+if (errors.length) fail(errors);
+if (expectedPr) {
+  const actual = `${short.pr.owner}/${short.pr.repo}#${short.pr.number}`;
+  if (actual !== expectedPr) fail([`pr is ${actual}, expected ${expectedPr}`]);
+}
+const problems = checkShort(short);
+if (problems.length) fail(problems);
+console.log(`OK: ${short.scenes.length + 2} scenes`);

package/scripts/check-tour.mjs

@@ -1,18 +1,24 @@
 #!/usr/bin/env node
 // Validates a tour against a pull request diff.
 //
-//   node scripts/check-tour.mjs <tour.json> <pr.diff> [owner/repo#number]
+//   node scripts/check-tour.mjs <tour.json> <pr.diff> [owner/repo#number] [--guidelines <file>]
 //
 // Prints every problem and exits 1, or prints a one-line summary and exits 0.
 // The diff must use 3 lines of context (`gh pr diff` or `git diff -U3`), as GitHub does.
+// --guidelines points at a copy of the repository's .github/pr-docent.md; a missing file means
+// the default limits.
 
-import { readFileSync } from "node:fs";
-import { checkTour, visibleLines } from "../src/diff.js";
+import { existsSync, readFileSync } from "node:fs";
+import { changedLineCount, checkTour, visibleLines } from "../src/diff.js";
+import { checkBrevity, parseGuidelines } from "../src/guidelines.js";
 import { flattenSteps, parseTour } from "../src/tour.js";
 
-const [tourPath, diffPath, expectedPr] = process.argv.slice(2);
+const args = process.argv.slice(2);
+const flag = args.indexOf("--guidelines");
+const guidelinesPath = flag >= 0 ? args.splice(flag, 2)[1] : null;
+const [tourPath, diffPath, expectedPr] = args;
 if (!tourPath || !diffPath) {
-  console.error("usage: node scripts/check-tour.mjs <tour.json> <pr.diff> [owner/repo#number]");
+  console.error("usage: node scripts/check-tour.mjs <tour.json> <pr.diff> [owner/repo#number] [--guidelines <file>]");
   process.exit(2);
 }
 
@@ -37,7 +43,13 @@ if (expectedPr) {
   if (actual !== expectedPr) fail([`pr is ${actual}, expected ${expectedPr}`]);
 }
 
-const problems = checkTour(tour, visibleLines(readFileSync(diffPath, "utf8")));
+const diff = readFileSync(diffPath, "utf8");
+const guidelines = parseGuidelines(guidelinesPath && existsSync(guidelinesPath) ? readFileSync(guidelinesPath, "utf8") : "");
+if (guidelines.errors.length) fail(guidelines.errors.map((error) => `.github/pr-docent.md: ${error}`));
+const problems = [
+  ...checkTour(tour, visibleLines(diff)),
+  ...checkBrevity(tour, { changedLines: changedLineCount(diff), limits: guidelines.limits }),
+];
 if (problems.length) fail(problems);
 
 console.log(`OK: ${tour.chapters.length} chapters, ${flattenSteps(tour).length} steps, ${tour.skipped.length} skipped files`);