@navipartner/demo-video 0.0.0-stage → 0.4.0

package/bin/encode.mjs

@@ -0,0 +1,187 @@
+// Turns the webm Playwright recorded into an MP4, then extracts review stills.
+// Used by bin/demo-video.mjs (encode, stills, render). Reads <out>/manifest.json
+// written by the runner for the webm path and the start/end offsets that trim
+// the load-in and the tail. Plain JS on purpose: no TS loader is needed.
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import ffmpegPath from "ffmpeg-static";
+
+const STILLS = 10;
+// One frame a second, six to a row: the whole video's pacing at a glance.
+const SHEET_COLUMNS = 6;
+
+const run = (args) => {
+  const result = spawnSync(
+    ffmpegPath,
+    ["-hide_banner", "-loglevel", "error", "-y", ...args],
+    { stdio: "inherit" },
+  );
+  if (result.status !== 0) {
+    throw new Error(
+      `ffmpeg failed (${result.status}): ffmpeg ${args.join(" ")}`,
+    );
+  }
+};
+
+// ffmpeg-static ships no ffprobe; decode to null and read the final timestamp
+// from ffmpeg's own progress output instead.
+const probeDuration = (file) => {
+  const result = spawnSync(
+    ffmpegPath,
+    ["-hide_banner", "-i", file, "-f", "null", "-"],
+    { encoding: "utf8" },
+  );
+  const matches = [...result.stderr.matchAll(/time=(\d+):(\d+):(\d+\.\d+)/g)];
+  if (matches.length === 0) {
+    throw new Error(`Could not read the duration of ${file}`);
+  }
+  const [, h, m, s] = matches[matches.length - 1];
+  return Number(h) * 3600 + Number(m) * 60 + Number(s);
+};
+
+const encode = (manifest, output) => {
+  const cut = [];
+  if (manifest.startAt != null) {
+    cut.push("-ss", manifest.startAt.toFixed(3));
+  }
+  if (manifest.endAt != null) {
+    cut.push("-to", manifest.endAt.toFixed(3));
+  }
+  run([
+    ...cut,
+    "-i",
+    manifest.source,
+    "-c:v",
+    "libx264",
+    "-preset",
+    "slow",
+    "-crf",
+    "16",
+    // Spends bits on flat, soft areas too, so gradients don't block.
+    "-aq-mode",
+    "3",
+    "-pix_fmt",
+    "yuv420p",
+    "-colorspace",
+    "bt709",
+    "-color_primaries",
+    "bt709",
+    "-color_trc",
+    "bt709",
+    "-color_range",
+    "tv",
+    "-r",
+    String(manifest.fps),
+    "-movflags",
+    "+faststart",
+    output,
+  ]);
+  return probeDuration(output);
+};
+
+const extractStills = (video, duration, reviewDir) => {
+  fs.rmSync(reviewDir, { recursive: true, force: true });
+  fs.mkdirSync(reviewDir, { recursive: true });
+  const stills = [];
+  for (let i = 0; i < STILLS; i++) {
+    const at = ((i + 0.5) / STILLS) * duration;
+    const still = path.join(
+      reviewDir,
+      `still-${String(i + 1).padStart(2, "0")}-${at.toFixed(1)}s.jpg`,
+    );
+    stills.push(still);
+    run([
+      "-ss",
+      at.toFixed(2),
+      "-i",
+      video,
+      "-frames:v",
+      "1",
+      "-q:v",
+      "3",
+      still,
+    ]);
+  }
+  return stills;
+};
+
+const contactSheet = (video, duration, reviewDir) => {
+  const sheet = path.join(reviewDir, "sheet.jpg");
+  const rows = Math.max(1, Math.ceil(duration / SHEET_COLUMNS));
+  run([
+    "-i",
+    video,
+    "-vf",
+    `fps=1,scale=320:-1,tile=${SHEET_COLUMNS}x${rows}:padding=4:color=white`,
+    "-frames:v",
+    "1",
+    "-q:v",
+    "3",
+    sheet,
+  ]);
+  return sheet;
+};
+
+const readManifest = (workDir) => {
+  const manifestPath = path.join(workDir, "manifest.json");
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`No recording in ${workDir}; record first`);
+  }
+  return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+};
+
+const outputPath = (outDir, manifest) =>
+  path.join(outDir, `${manifest.storyboard}-demo.mp4`);
+
+// ffmpeg-static downloads its binary in an install script. pnpm >= 10 skips
+// dependency install scripts unless they are allowed, which leaves the path
+// set but the file missing.
+const assertFfmpeg = () => {
+  if (!ffmpegPath || !fs.existsSync(ffmpegPath)) {
+    throw new Error(
+      `ffmpeg-static has no binary${ffmpegPath ? ` at ${ffmpegPath}` : " for this platform"}. ` +
+        'With pnpm >= 10, allow its install script ("pnpm": { "onlyBuiltDependencies": ["ffmpeg-static"] } in the root package.json) and reinstall.',
+    );
+  }
+};
+
+/**
+ * Encodes the recording in workDir to an MP4 in outDir, then writes review
+ * stills and a contact sheet. Returns { output, duration, stills, sheet }.
+ */
+export const encodeRecording = (workDir, outDir) => {
+  assertFfmpeg();
+  const manifest = readManifest(workDir);
+  if (!fs.existsSync(manifest.source)) {
+    throw new Error(`Recording ${manifest.source} is missing`);
+  }
+  const output = outputPath(outDir, manifest);
+  const duration = encode(manifest, output);
+  const reviewDir = path.join(outDir, "review");
+  const stills = extractStills(output, duration, reviewDir);
+  const sheet = contactSheet(output, duration, reviewDir);
+  return { output, duration, stills, sheet };
+};
+
+/** Re-extracts review stills from the newest MP4 in outDir. */
+export const extractStillsFrom = (outDir) => {
+  assertFfmpeg();
+  const videos = fs.existsSync(outDir)
+    ? fs
+        .readdirSync(outDir)
+        .filter((f) => f.endsWith("-demo.mp4"))
+        .map((f) => path.join(outDir, f))
+        .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs)
+    : [];
+  if (videos.length === 0) {
+    throw new Error(`No video in ${outDir}; render first`);
+  }
+  const output = videos[0];
+  const duration = probeDuration(output);
+  extractStills(output, duration, path.join(outDir, "review"));
+  contactSheet(output, duration, path.join(outDir, "review"));
+  return output;
+};

package/bin/init.d.mts

@@ -0,0 +1,24 @@
+export type Change = [status: string, what: string, detail: string];
+export interface InitResult {
+  changes: Change[];
+  todo: string[];
+}
+export const IGNORE_LINE: string;
+export const LABEL: string;
+export const CALLER_WORKFLOW: string;
+export function initRepo(
+  root: string,
+  options?: { dryRun?: boolean; label?: boolean },
+): InitResult;
+export function initApp(
+  appDir: string,
+  options?: { dryRun?: boolean },
+): InitResult;
+export function adapterSkeleton(options: {
+  app: string;
+  command?: string;
+  url?: string;
+  env: Record<string, string>;
+  mocks: { name: string; file: string }[];
+  demoDir: string;
+}): string;

package/bin/init.mjs

@@ -0,0 +1,447 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// `demo-video init` sets a pnpm project up for demo videos: .gitignore,
+// package.json, the skill, the label, the demo-video.yml caller (only when
+// missing) and a demo.config.ts skeleton. It never edits an existing
+// workflow. Safe to re-run; with dryRun it reports what it would change.
+
+const PKG = "@navipartner/demo-video";
+export const IGNORE_LINE = "**/demo/out/";
+export const LABEL = "demo video";
+
+const engineDir = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+const engineVersion = () =>
+  JSON.parse(fs.readFileSync(path.join(engineDir, "package.json"), "utf8"))
+    .version;
+
+export const CALLER_WORKFLOW = `name: Demo video
+# The "${LABEL}" label films the stories a PR adds or changes. A PR comment
+# "/demo-video [<story>] [in <brand> branding]", or Actions → Demo video →
+# Run workflow, films an existing story with a brand.
+on:
+  pull_request:
+    types: [labeled, synchronize]
+  issue_comment:
+    types: [created]
+  # Actions → Demo video → Run workflow: film a story with a brand.
+  workflow_dispatch:
+    inputs:
+      app:
+        description: "App folder, e.g. apps/retail-self-service (empty: the only app)"
+        default: ""
+      story:
+        description: "Story name (empty: the app's primary story)"
+        default: ""
+      brand:
+        description: "Brand (empty: the app's default)"
+        default: ""
+permissions: {}
+jobs:
+  render:
+    if: github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, '${LABEL}')
+    permissions:
+      contents: read
+      pull-requests: write
+    uses: navipartner/demo-video/.github/workflows/render.yml@v0
+  request:
+    if: github.event_name == 'workflow_dispatch' || (github.event_name == 'issue_comment' && github.event.issue.pull_request && startsWith(github.event.comment.body, '/demo-video'))
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+    uses: navipartner/demo-video/.github/workflows/request.yml@v0
+    with:
+      app: \${{ inputs.app }}
+      story: \${{ inputs.story }}
+      brand: \${{ inputs.brand }}
+`;
+
+const read = (file) =>
+  fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null;
+const eolOf = (text) => (text?.includes("\r\n") ? "\r\n" : "\n");
+
+const appendLines = (file, lines, dryRun) => {
+  const old = read(file) ?? "";
+  const eol = eolOf(old);
+  const sep = old && !old.endsWith("\n") ? eol : "";
+  if (!dryRun) {
+    fs.writeFileSync(file, old + sep + lines.join(eol) + eol);
+  }
+};
+
+/** Edits a JSON file in place, keeping its indent and line endings. */
+const editJson = (file, edit, dryRun) => {
+  const text = fs.readFileSync(file, "utf8");
+  const indent = /^([ \t]+)"/m.exec(text)?.[1] ?? "  ";
+  const json = JSON.parse(text);
+  edit(json);
+  const eol = eolOf(text);
+  if (!dryRun) {
+    fs.writeFileSync(
+      file,
+      JSON.stringify(json, null, indent).replace(/\n/g, eol) + eol,
+    );
+  }
+};
+
+/** Adds a key in alphabetical place when the object is sorted, else last. */
+const withKey = (object, key, value) => {
+  const keys = Object.keys(object);
+  const sorted = keys.every((k, i) => i === 0 || keys[i - 1] <= k);
+  const entries = Object.entries(object);
+  const at = sorted ? entries.findIndex(([k]) => k > key) : -1;
+  entries.splice(at === -1 ? entries.length : at, 0, [key, value]);
+  return Object.fromEntries(entries);
+};
+
+const sameTree = (a, b) => {
+  if (!fs.existsSync(b)) {
+    return false;
+  }
+  return fs.readdirSync(a, { withFileTypes: true }).every((entry) => {
+    const [x, y] = [path.join(a, entry.name), path.join(b, entry.name)];
+    return entry.isDirectory()
+      ? sameTree(x, y)
+      : fs.existsSync(y) && fs.readFileSync(x).equals(fs.readFileSync(y));
+  });
+};
+
+const gitIgnores = (root, file) =>
+  spawnSync("git", ["check-ignore", "-q", file], { cwd: root }).status === 0;
+
+const ensureLabel = (root, dryRun) => {
+  const list = spawnSync(
+    "gh",
+    // All labels, not --search: the search index can lag and miss one.
+    ["label", "list", "--limit", "1000", "--json", "name", "--jq", ".[].name"],
+    { cwd: root, encoding: "utf8" },
+  );
+  if (list.error || list.status !== 0) {
+    return {
+      todo: `Create the label: gh label create "${LABEL}" --color 1F5494`,
+    };
+  }
+  // GitHub label names are case-insensitive.
+  const names = list.stdout.split("\n").map((name) => name.toLowerCase());
+  if (names.includes(LABEL)) {
+    return { change: ["ok", "label", LABEL] };
+  }
+  if (!dryRun) {
+    const created = spawnSync(
+      "gh",
+      ["label", "create", LABEL, "--color", "1F5494"],
+      { cwd: root, encoding: "utf8" },
+    );
+    if (created.error || created.status !== 0) {
+      return {
+        todo: `Create the label (gh could not: ${(created.stderr ?? "").trim() || "no access?"}): gh label create "${LABEL}" --color 1F5494`,
+      };
+    }
+  }
+  return { change: ["added", "label", LABEL] };
+};
+
+/**
+ * Once per repo, from its root. `label` (default true) checks or creates the
+ * GitHub label with gh.
+ */
+export const initRepo = (root, { dryRun = false, label = true } = {}) => {
+  const changes = [];
+  const todo = [];
+
+  const gitignore = path.join(root, ".gitignore");
+  const ignored = read(gitignore);
+  // Only **/ reaches apps/<x>/demo/out/: a bare demo/out/ is anchored to
+  // the repo root.
+  if (/^\*\*\/demo\/out\/?$/m.test(ignored ?? "")) {
+    changes.push(["ok", ".gitignore", IGNORE_LINE]);
+  } else {
+    const comment = "# Demo video renders (@navipartner/demo-video)";
+    appendLines(
+      gitignore,
+      ignored ? ["", comment, IGNORE_LINE] : [comment, IGNORE_LINE],
+      dryRun,
+    );
+    changes.push(["added", ".gitignore", IGNORE_LINE]);
+  }
+
+  // pnpm 10 runs no install scripts unless allowed; ffmpeg-static needs its.
+  const pkgFile = path.join(root, "package.json");
+  const pkg = fs.existsSync(pkgFile)
+    ? JSON.parse(fs.readFileSync(pkgFile, "utf8"))
+    : null;
+  const pnpmMajor = Number(/^pnpm@(\d+)/.exec(pkg?.packageManager ?? "")?.[1]);
+  const workspaceYaml = read(path.join(root, "pnpm-workspace.yaml")) ?? "";
+  if (pkg && pnpmMajor >= 10) {
+    if (/^onlyBuiltDependencies:/m.test(workspaceYaml)) {
+      if (!/ffmpeg-static/.test(workspaceYaml)) {
+        todo.push(
+          "Add ffmpeg-static to onlyBuiltDependencies in pnpm-workspace.yaml.",
+        );
+      }
+    } else if (pkg.pnpm?.onlyBuiltDependencies?.includes("ffmpeg-static")) {
+      changes.push(["ok", "package.json", "pnpm.onlyBuiltDependencies"]);
+    } else {
+      editJson(
+        pkgFile,
+        (json) => {
+          json.pnpm ??= {};
+          json.pnpm.onlyBuiltDependencies = [
+            ...(json.pnpm.onlyBuiltDependencies ?? []),
+            "ffmpeg-static",
+          ];
+        },
+        dryRun,
+      );
+      changes.push(["added", "package.json", "pnpm.onlyBuiltDependencies"]);
+    }
+  } else if (pkg && !pnpmMajor) {
+    todo.push(
+      'No "packageManager" in package.json: with pnpm 10 or later, allow ffmpeg-static in onlyBuiltDependencies.',
+    );
+  }
+
+  // Claude Code loads .claude/skills/<name>/SKILL.md.
+  const skillSrc = path.join(engineDir, "skills", "np-demo-video");
+  const skillDest = path.join(root, ".claude", "skills", "np-demo-video");
+  const skillRel = ".claude/skills/np-demo-video/";
+  if (sameTree(skillSrc, skillDest)) {
+    changes.push(["ok", skillRel, "the np-demo-video skill"]);
+  } else {
+    const existed = fs.existsSync(skillDest);
+    if (!dryRun) {
+      fs.cpSync(skillSrc, skillDest, { recursive: true, force: true });
+    }
+    changes.push([
+      existed ? "updated" : "added",
+      skillRel,
+      "the np-demo-video skill",
+    ]);
+  }
+  const stray = read(path.join(root, ".claude", "skills", "SKILL.md"));
+  if (stray?.includes("name: np-demo-video")) {
+    todo.push(
+      "Delete .claude/skills/SKILL.md and look.md: a copy of the skill in the wrong folder.",
+    );
+  }
+  if (gitIgnores(root, skillRel)) {
+    todo.push(
+      "Git ignores .claude/ here, so the skill stays on this machine: each developer runs init, or add !.claude/skills/ to .gitignore to share it.",
+    );
+  }
+
+  if (label) {
+    const result = ensureLabel(root, dryRun);
+    if (result.change) {
+      changes.push(result.change);
+    } else {
+      todo.push(result.todo);
+    }
+  }
+
+  // The caller workflow is fixed, so it is written when missing. Existing
+  // workflows are never touched.
+  const callerFile = path.join(root, ".github", "workflows", "demo-video.yml");
+  if (
+    ["demo-video.yml", "demo-video.yaml"].some((f) =>
+      fs.existsSync(path.join(root, ".github", "workflows", f)),
+    )
+  ) {
+    changes.push(["ok", ".github/workflows/demo-video.yml", "exists"]);
+    // Written by an older init: it has the label job only.
+    const existing = ["demo-video.yml", "demo-video.yaml"]
+      .map((f) => read(path.join(root, ".github", "workflows", f)))
+      .find(Boolean);
+    if (existing && !existing.includes("request.yml@")) {
+      todo.push(
+        '.github/workflows/demo-video.yml predates the "request" job (/demo-video comments, the Run workflow form): delete it and re-run init to get the current one.',
+      );
+    }
+  } else {
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(callerFile), { recursive: true });
+      fs.writeFileSync(callerFile, CALLER_WORKFLOW);
+    }
+    changes.push([
+      "added",
+      ".github/workflows/demo-video.yml",
+      "render.yml@v0",
+    ]);
+  }
+
+  return { changes, todo };
+};
+
+/** The webServer block of a Playwright config, if one can be read. */
+const webServerOf = (configText) => {
+  const start = configText.indexOf("webServer");
+  const open = configText.indexOf("{", start);
+  if (start === -1 || open === -1) {
+    return {};
+  }
+  let depth = 0;
+  let end = open;
+  for (; end < configText.length; end++) {
+    depth += configText[end] === "{" ? 1 : configText[end] === "}" ? -1 : 0;
+    if (depth === 0) {
+      break;
+    }
+  }
+  const block = configText.slice(open, end + 1);
+  const str = (key) =>
+    new RegExp(`\\b${key}:\\s*["'\`]([^"'\`]+)["'\`]`).exec(block)?.[1];
+  const envBlock = /\benv:\s*\{([^}]*)\}/.exec(block)?.[1] ?? "";
+  const env = Object.fromEntries(
+    [...envBlock.matchAll(/(\w+):\s*["'`]([^"'`]*)["'`]/g)].map((m) => [
+      m[1],
+      m[2],
+    ]),
+  );
+  return { command: str("command"), url: str("url"), env };
+};
+
+/**
+ * e2e helpers that look like the app's mocks: in a file named *mock*, its
+ * exported class or function (`class ApiMocks`, `setupApiMocks`), not data.
+ */
+const findMocks = (appDir) => {
+  const found = [];
+  const walk = (dir, depth) => {
+    if (depth > 3 || !fs.existsSync(dir)) {
+      return;
+    }
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory() && entry.name !== "node_modules") {
+        walk(file, depth + 1);
+      } else if (/mock/i.test(entry.name) && /\.[cm]?[jt]s$/.test(entry.name)) {
+        const name = /^export\s+(?:class|(?:async\s+)?function)\s+(\w+)/m.exec(
+          read(file),
+        )?.[1];
+        if (name) {
+          found.push({ name, file });
+        }
+      }
+    }
+  };
+  walk(path.join(appDir, "e2e"), 0);
+  return found;
+};
+
+export const adapterSkeleton = ({ app, command, url, env, mocks, demoDir }) => {
+  const envLine = Object.keys(env).length
+    ? `\n    env: { ${Object.entries(env)
+        .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+        .join(", ")} },`
+    : "";
+  const mockHint = mocks.length
+    ? mocks
+        .map(({ name, file }) => {
+          const rel = path
+            .relative(demoDir, file)
+            .replace(/\\/g, "/")
+            .replace(/\.[cm]?[jt]s$/, "");
+          return `\n    //   import { ${name} } from "${rel.startsWith(".") ? rel : `./${rel}`}";`;
+        })
+        .join("")
+    : "";
+  return `import { defineDemo } from "@navipartner/demo-video";
+
+// Written by \`demo-video init\`. Finish it with Claude (the np-demo-video
+// skill) from the app's e2e tests: their mocks, unchanged, never new ones.
+
+export default defineDemo({
+  app: ${JSON.stringify(app)},${command && url ? "" : "\n  // TODO: the dev server the e2e tests use (playwright.config's webServer)."}
+  webServer: {
+    command: ${JSON.stringify(command ?? "pnpm dev")},
+    url: ${JSON.stringify(url ?? "http://localhost:5173")},${envLine}
+  },
+  // TODO: the path the e2e tests open, e.g. "/?tenant=test".
+  appPath: "/",
+  // TODO: a testid that is visible once the mocks have booted the app.
+  ready: "TODO",
+
+  async setup() {
+    // TODO: install the e2e mocks unchanged, then lay the brand over the
+    // response that carries the app's branding (overlayResponse).${mocks.length ? `\n    // Mocks found:${mockHint}` : ""}
+  },
+});
+`;
+};
+
+/** Once per app: the dependency and a demo.config.ts skeleton. */
+export const initApp = (appDir, { dryRun = false } = {}) => {
+  const changes = [];
+  const todo = [];
+  const pkgFile = path.join(appDir, "package.json");
+  if (!fs.existsSync(pkgFile)) {
+    throw new Error(`No package.json in ${appDir}`);
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgFile, "utf8"));
+  const version = engineVersion();
+
+  if (pkg.devDependencies?.[PKG] || pkg.dependencies?.[PKG]) {
+    changes.push(["ok", "package.json", PKG]);
+  } else {
+    // A prerelease is pinned exactly. A release gets a caret range, which on
+    // 0.x takes patch updates only (^0.2.0 is <0.3.0).
+    const range = version.includes("-") ? version : `^${version}`;
+    editJson(
+      pkgFile,
+      (json) => {
+        json.devDependencies = withKey(json.devDependencies ?? {}, PKG, range);
+      },
+      dryRun,
+    );
+    changes.push(["added", "package.json", `devDependencies ${PKG} ${range}`]);
+    todo.push("Run pnpm install to update the lockfile.");
+  }
+  if (
+    !pkg.devDependencies?.["@playwright/test"] &&
+    !pkg.dependencies?.["@playwright/test"]
+  ) {
+    todo.push(
+      "The app needs @playwright/test (1.59 or later): the demo runs on its Playwright.",
+    );
+  }
+
+  const demoDir = path.join(appDir, "demo");
+  const adapter = path.join(demoDir, "demo.config.ts");
+  if (fs.existsSync(adapter)) {
+    changes.push(["ok", "demo/demo.config.ts", "exists"]);
+  } else {
+    const configFile = ["ts", "mts", "js", "mjs"]
+      .map((ext) => path.join(appDir, `playwright.config.${ext}`))
+      .find((f) => fs.existsSync(f));
+    const webServer = configFile ? webServerOf(read(configFile)) : {};
+    const skeleton = adapterSkeleton({
+      app: (pkg.name ?? path.basename(appDir)).replace(/^@[^/]+\//, ""),
+      command: webServer.command,
+      url: webServer.url,
+      env: webServer.env ?? {},
+      mocks: findMocks(appDir),
+      demoDir,
+    });
+    if (!dryRun) {
+      fs.mkdirSync(demoDir, { recursive: true });
+      fs.writeFileSync(adapter, skeleton);
+    }
+    changes.push([
+      "added",
+      "demo/demo.config.ts",
+      webServer.command && webServer.url
+        ? `skeleton; webServer from ${path.basename(configFile)}`
+        : "skeleton; webServer to fill in (TODO)",
+    ]);
+  }
+  todo.push(
+    "Ask Claude for a demo video of this app: it finishes demo.config.ts and writes the primary story, then runs demo-video check.",
+  );
+  return { changes, todo };
+};

package/bin/pick.d.mts

@@ -0,0 +1,18 @@
+import type { StoryEntry } from "./args.mjs";
+
+export interface AppMenu {
+  dir: string;
+  name: string;
+  stories: StoryEntry[];
+  brands: string[];
+}
+export type Pick =
+  | { app: string; story: string; brand: string | null; menu?: undefined }
+  | { menu: true; reason: string; apps?: AppMenu[] };
+export function appMenu(appDir: string): AppMenu;
+export function pick(request: string, apps: AppMenu[]): Pick;
+export function menuMarkdown(apps: AppMenu[], reason: string): string;
+export function pickExact(
+  apps: AppMenu[],
+  names: { app?: string; story?: string; brand?: string },
+): Pick;