pr-docent 0.1.1 → 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) {

package/host/pr-docent-host.mjs

@@ -1,57 +1,68 @@
-// 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 { changedLineCount, checkTour, visibleLines } from "../src/diff.js";
 import { buildPrompt, checkBrevity, parseGuidelines } from "../src/guidelines.js";
 import { parseTour } from "../src/tour.js";
+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);
 });
 
+/** 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 }) {
-  // 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-")));
+  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(" / ")}`);
@@ -70,7 +81,7 @@ async function generate({ pr, title, body, headSha, diff, files, guidelines = ""
       "--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 {
@@ -88,32 +99,3 @@ async function generate({ pr, title, body, headSha, diff, files, guidelines = ""
     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(`Could not start Claude Code (${CONFIG.claude}): ${error.message}`)));
-    child.on("close", (code) => {
-      clearInterval(progress);
-      clearTimeout(timeout);
-      if (code === 0) resolvePromise();
-      else reject(new Error(`Claude Code exited with 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.1",
+  "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",
@@ -27,12 +27,17 @@
     "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/short-prompt.md

@@ -0,0 +1,63 @@
+You are writing a PR Docent short for pull request {{PR}}: a 30-45 second vertical explainer,
+played with narration in the reviewer's browser, for teammates who will not read the code, such as
+planners and people on other teams. It shows no code. Each scene is a simple picture of the idea
+(a flow, a before-and-after, a structure, or a few points) that builds up while one sentence is
+read aloud and subtitled.
+
+## Inputs
+
+- `{{OUT}}/tour.json`: the reviewers' tour of this PR. Start from it; it already knows what
+  matters and why.
+- `{{OUT}}/pr.json`: the PR's title, body and head commit.
+- `{{OUT}}/pr.diff` and the changed files in the current directory, if you need to check a detail.
+
+## Output
+
+Write the short to `{{OUT}}/short.json`, then run
+
+    node {{TOOLS}}/scripts/check-short.mjs {{OUT}}/short.json {{PR}}
+
+and fix every problem it reports until it prints `OK`. Then stop. Use these absolute paths as
+written and do not change directory: `{{OUT}}/short.json` is the only file you may write.
+
+## Format
+
+Write every text in the short in {{LANGUAGE}}: the title, hook, headlines, narration, labels,
+items and outro. The example below only shows the shape.
+
+```json
+{
+  "version": 1,
+  "pr": { "owner": "...", "repo": "...", "number": 0 },
+  "title": "Short title",
+  "hook": "One sentence on what changes and why",
+  "scenes": [
+    { "kind": "compare", "headline": "What changes", "narration": "One sentence",
+      "before": { "label": "Before", "items": ["..."] }, "after": { "label": "After", "items": ["..."] } },
+    { "kind": "flow", "headline": "How it works", "narration": "One sentence",
+      "steps": [{ "icon": "📝", "label": "Short name", "detail": "One-line detail", "status": "same" },
+                { "icon": "🤖", "label": "...", "detail": "...", "status": "new" }],
+      "links": ["Label on the arrow"] },
+    { "kind": "structure", "headline": "Where it fits", "narration": "One sentence",
+      "groups": [{ "label": "Layer or module", "items": [{ "icon": "📦", "label": "...", "status": "changed" }] }] },
+    { "kind": "points", "headline": "Remember", "narration": "One sentence",
+      "points": [{ "icon": "✅", "text": "Short point" }] }
+  ],
+  "outro": "One sentence on the impact or what to check"
+}
+```
+
+## Rules
+
+- Write in {{LANGUAGE}}. Plain words a non-developer understands: what changes for users, data,
+  operations or the team. Name a component only when the picture needs it, and call it by what
+  it does ("the tour checker", "the payment module") rather than by a class or file name.
+- 2 to 4 scenes that tell one story, usually: what changes (compare) → how it works (flow or
+  structure) → what it means (points). Pick the kinds that fit this PR; do not force all four.
+- Mark what this PR adds as `"status": "new"` and what it modifies as `"changed"`; leave the rest
+  as `"same"` so the eye goes to the change.
+- Keep it small enough for a phone: flow 2-5 steps, compare 1-3 items per side, structure 1-3
+  groups and at most 8 items, points 2-3. Headlines at most 24 characters, labels at most 16,
+  details at most 24, every sentence (hook, narration, outro) one sentence of at most 80.
+- One emoji per icon, chosen to be recognisable at a glance.
+- Never invent behaviour the PR does not have.

package/scripts/tour-prompt.md

@@ -24,16 +24,19 @@ change any other file. Use these absolute paths as written and do not change dir
 
 ## Format
 
+Write every text in the tour in {{LANGUAGE}}: the title, the summaries, chapter titles, notes,
+review points and skipped reasons. The example below only shows the shape.
+
 ```json
 {
   "version": 1,
   "pr": { "owner": "...", "repo": "...", "number": 0 },
-  "title": "한 줄 제목",
-  "summary": "PR이 무엇을 왜 바꾸는지 2~4문장",
+  "title": "One-line title",
+  "summary": "What the PR changes and why, in 2-4 sentences",
   "chapters": [
     {
-      "title": "1. 챕터 제목",
-      "summary": "한 문장",
+      "title": "1. Chapter title",
+      "summary": "One sentence",
       "steps": [
         {
           "file": "path/from/repo/root.kt",
@@ -41,15 +44,15 @@ change any other file. Use these absolute paths as written and do not change dir
           "side": "right",
           "level": "focus",
           "note": [
-            { "text": "이 문장이 설명하는 줄을 가리킵니다.", "lines": [41, 45] },
-            { "text": "다음 문장은 다른 줄을 가리킵니다.", "lines": [50, 58] }
+            { "text": "This sentence points at the lines it talks about.", "lines": [41, 45] },
+            { "text": "The next sentence points at other lines.", "lines": [50, 58] }
           ],
-          "point": "리뷰어가 확인할 구체적인 질문"
+          "point": "A specific question for the reviewer to check"
         }
       ]
     }
   ],
-  "skipped": [{ "file": "package-lock.json", "reason": "의존성 잠금 파일" }]
+  "skipped": [{ "file": "package-lock.json", "reason": "dependency lock file" }]
 }
 ```