@navipartner/demo-video 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @navipartner/demo-video
+
+Marketing demo videos of a React app, filmed by Playwright on the app's own
+e2e mocks, in the NaviPartner house look, with any customer's brand. For
+pnpm repos on GitHub Actions.
+
+## Setup
+
+The package is public on npm, so nothing needs a token or registry setup.
+
+### Once per project repo
+
+From the repo root:
+
+    npx --ignore-scripts @navipartner/demo-video init
+
+It sets up `.gitignore`, the skill, the `demo video` label and
+`.github/workflows/demo-video.yml`. Safe to re-run; `--dry-run` previews.
+(`--ignore-scripts` skips downloading ffmpeg, which `init` doesn't need.)
+
+### Per app
+
+    npx --ignore-scripts @navipartner/demo-video init --app apps/<name>
+    pnpm install
+
+Then ask Claude for a demo video of the app. It finishes
+`demo/demo.config.ts` from the e2e tests and writes the app's primary story.
+The app needs `@playwright/test` 1.59 or later.
+
+## Getting a video
+
+| Way | Who | Films | Where the video lands |
+|---|---|---|---|
+| **Run workflow form:** Actions → Demo video → Run workflow; fill in App, Story, Brand (each may be empty) | anyone who can write to the repo | an existing story with a brand, from the branch chosen | the run's Summary page |
+| **PR comment:** `/demo-video checkout in acme branding` | members, on any PR | an existing story with a brand, from the PR's branch | a reply on the PR |
+| **The `demo video` label** on a PR | whoever labels it | every story the PR adds or changes, on every push | a comment on the PR |
+| **Locally:** `pnpm --dir apps/<name> exec demo-video render [--story <name>] [--brand <name>]` | a developer | any story | `demo/out/` |
+
+- An empty story means the app's primary story; an empty brand, the app's
+  default. A request that doesn't name one existing story, or names a brand
+  that doesn't exist, gets the list of stories and brands instead (the form
+  run is then marked failed, so a typo is noticed).
+- The form and the comment only choose: they never write or change a story.
+  New stories are written by a developer, locally (ask Claude, which uses
+  the skill), and reviewed through the label. A PR has no default video.
+
+## Stories and brands
+
+- **Stories** are `<app>/demo/stories/<name>.json`, built only from what the
+  e2e mocks return. One per app is `"primary": true`: the journey the app
+  exists for.
+- **Variants** (`checkout.acme.json`) are a story in a customer's words:
+  the base story's steps, with its own title, closing and card text, filmed
+  with one brand. Asking for the story in that brand films the variant.
+- **Brands** are `<app>/demo/brands/<name>.json` plus a folder of assets;
+  the engine ships `navipartner`, the default.
+
+Claude writes both with the skill (`skills/np-demo-video/`), which also holds
+the look and every field.
+
+## Commands
+
+Run in the app: `pnpm --dir apps/<name> exec demo-video <command>`.
+
+| Command | |
+|---|---|
+| `list` | The stories, primary first. |
+| `check` | Dry run in seconds. Fails on anything that would film badly (a zoom on the wrong area, a click whose result is off-screen, code or unproven numbers on a card) and names the step. |
+| `render` | Films the story frame by frame (60 fps, about 5× its length) to `demo/out/<story>-<brand>-demo.mp4`, with a contact sheet (`review/sheet.jpg`, one frame a second) and ten stills. |
+| `record`, `encode`, `stills` | `render` in parts: record only, encode the last take, redo the stills. |
+
+`--story <name>` (default: primary), `--brand <name>` (default:
+`navipartner`), `--draft` (`render` at 30 fps in about half the time, while
+tuning), `--json` (machine-readable output).
+
+## Developing and releasing
+
+    pnpm install
+    pnpm test && pnpm typecheck && pnpm build
+
+**Release:** bump `version` in `package.json` on `main`, then
+`git tag vX.Y.Z && git push origin vX.Y.Z`. That publishes it to npm as
+`latest` and moves the `v0` tag, which every project's workflow follows.
+Running `release.yml` by hand publishes a `next` prerelease.
+
+**The first release, once, by an npm owner of the `navipartner` org:**
+trusted publishing can only be set up for a package that exists.
+
+1. On main at the release commit: `pnpm install && pnpm pack`, then
+   `node scripts/check-public.mjs navipartner-demo-video-*.tgz`.
+2. `npm login`, then `npm publish navipartner-demo-video-*.tgz --access public`.
+3. On npmjs.com, the package → Settings → Trusted publisher: GitHub Actions,
+   repository `navipartner/demo-video`, workflow `release.yml`. Then set
+   "Publishing access" to require trusted publishing (no tokens).
+4. Push the tag as usual: `release.yml` sees the version is already on npm,
+   skips publishing and moves `v0`.
+
+The package is public; this repo is not. `release.yml` publishes through npm
+trusted publishing (no npm token is stored), and only after
+`scripts/check-public.mjs` has checked the tarball: only the allowed files,
+no source maps, nothing shaped like a secret, an email or a local path. CI
+runs the same check on every PR. Names it can't catch: keep customers and
+people out of the skill and the README.
+
+Projects get a new CLI only with `pnpm up -r --latest @navipartner/demo-video`
+(their lockfile pins it), but their workflow follows `v0` at once. So
+`render.yml` and `request.yml` must work with every CLI
+from 0.4 (older ones get a reply asking for the update); a change that
+can't is `v1`.

package/bin/args.d.mts

@@ -0,0 +1,30 @@
+export interface DemoArgs {
+  command: "check" | "render" | "record" | "encode" | "stills" | "list";
+  appDir: string;
+  demoDir: string;
+  adapterPath: string;
+  workDir: string;
+  runnerDir: string;
+  configPath: string;
+  outDir: string;
+  storyboardPath: string | null;
+  brand: string | null;
+  json: boolean;
+  draft: boolean;
+}
+export const COMMANDS: readonly string[];
+export function parseArgs(argv: string[], cwd: string): DemoArgs;
+export interface StoryEntry {
+  name: string;
+  description: string | null;
+  primary: boolean;
+  /** A variant: the story it extends, and the brand it is for. */
+  extends?: string;
+  brand?: string | null;
+}
+export function listStories(demoDir: string): StoryEntry[];
+export function resolveStoryboard(
+  value: string,
+  cwd: string,
+  demoDir: string,
+): string;

package/bin/args.mjs

@@ -0,0 +1,153 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const COMMANDS = [
+  "check",
+  "render",
+  "record",
+  "encode",
+  "stills",
+  "list",
+];
+const NEEDS_STORYBOARD = new Set(["check", "render", "record"]);
+const USAGE = `Usage: demo-video <${COMMANDS.join("|")}> [--app <dir>] [--story <name|file.json>] [--brand <name>] [--draft] [--json]
+Without --story, check, render and record use the app's primary story.
+--draft renders at 30 fps (about half the time) to iterate on a story.
+Setup: demo-video init [--app <dir>] [--dry-run]
+For a /demo-video request: demo-video pick --request "<text>" [--json] <app dir>...`;
+
+export const resolveStoryboard = (value, cwd, demoDir) => {
+  if (value.endsWith(".json")) {
+    const file = path.resolve(cwd, value);
+    if (!fs.existsSync(file)) {
+      throw new Error(`Story file ${file} does not exist`);
+    }
+    return file;
+  }
+  const dir = path.join(demoDir, "stories");
+  const file = path.join(dir, `${value}.json`);
+  if (!fs.existsSync(file)) {
+    const known = fs.existsSync(dir)
+      ? fs
+          .readdirSync(dir)
+          .filter((f) => f.endsWith(".json"))
+          .map((f) => f.slice(0, -".json".length))
+      : [];
+    throw new Error(
+      `No story "${value}" in ${dir}. Known: ${known.join(", ") || "(none)"}`,
+    );
+  }
+  return file;
+};
+
+/**
+ * The app's stories, primary first, then by name. Reads only `description`
+ * and `primary`: the full check needs the adapter and runs in `check`.
+ */
+export const listStories = (demoDir) => {
+  const dir = path.join(demoDir, "stories");
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  const stories = fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => {
+      const story = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
+      return {
+        name: f.slice(0, -".json".length),
+        description: story.description ?? null,
+        primary: story.primary === true,
+        // A variant: the base story's flow, for one brand.
+        ...(story.extends
+          ? { extends: story.extends, brand: story.brand ?? null }
+          : {}),
+      };
+    })
+    .sort(
+      (a, b) =>
+        Number(b.primary) - Number(a.primary) || a.name.localeCompare(b.name),
+    );
+  const primaries = stories.filter((s) => s.primary).map((s) => s.name);
+  if (primaries.length > 1) {
+    throw new Error(
+      `Only one story can be primary; ${primaries.join(", ")} all are (in ${dir})`,
+    );
+  }
+  return stories;
+};
+
+export const parseArgs = (argv, cwd) => {
+  const [command, ...rest] = argv;
+  if (!COMMANDS.includes(command)) {
+    throw new Error(USAGE);
+  }
+  const opts = {
+    app: ".",
+    story: undefined,
+    brand: undefined,
+    json: false,
+    draft: false,
+  };
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--json") {
+      opts.json = true;
+    } else if (arg === "--draft") {
+      opts.draft = true;
+    } else if (["--app", "--story", "--brand"].includes(arg)) {
+      const value = rest[++i];
+      if (!value) {
+        throw new Error(`${arg} needs a value`);
+      }
+      opts[arg.slice(2)] = value;
+    } else {
+      throw new Error(`Unknown option ${arg}\n${USAGE}`);
+    }
+  }
+  const appDir = path.resolve(cwd, opts.app);
+  const demoDir = path.join(appDir, "demo");
+  const adapterPath = path.join(demoDir, "demo.config.ts");
+  if (!fs.existsSync(adapterPath)) {
+    throw new Error(`No demo adapter: expected ${adapterPath}`);
+  }
+  // Everything a run needs only while it runs (the generated Playwright
+  // config and spec, the check report, the raw recording, Playwright's
+  // results) goes here, inside demo/out/ (gitignored), and is deleted when
+  // the command ends. Only a failure's results are kept, in demo/out/failed/.
+  // `check` has its own folder, so it never touches the take that `record`
+  // leaves for `encode`.
+  const workDir = path.join(
+    demoDir,
+    "out",
+    ".work",
+    command === "check" ? "check" : "take",
+  );
+  const runnerDir = path.join(workDir, "runner");
+  let storyboardPath = null;
+  if (NEEDS_STORYBOARD.has(command)) {
+    // No --story: the app's primary story, its main journey.
+    const story =
+      opts.story ?? listStories(demoDir).find((s) => s.primary)?.name;
+    if (!story) {
+      throw new Error(
+        `No --story given and no primary story in ${path.join(demoDir, "stories")}. Name one with --story, or mark the app's main journey "primary": true.`,
+      );
+    }
+    storyboardPath = resolveStoryboard(story, cwd, demoDir);
+  }
+  return {
+    command,
+    appDir,
+    demoDir,
+    adapterPath,
+    workDir,
+    runnerDir,
+    configPath: path.join(runnerDir, "playwright.config.mjs"),
+    outDir: path.join(demoDir, "out"),
+    storyboardPath,
+    brand: opts.brand ?? null,
+    json: opts.json,
+    draft: opts.draft,
+  };
+};

package/bin/demo-video.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- a CLI; the console is its output */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { listStories, parseArgs } from "./args.mjs";
+import { encodeRecording, extractStillsFrom } from "./encode.mjs";
+import { initApp, initRepo } from "./init.mjs";
+import { appMenu, menuMarkdown, pick, pickExact } from "./pick.mjs";
+import { writeRunner } from "./runner.mjs";
+
+// Runs the app's own Playwright (resolved from the app, never from this
+// package) against the config this CLI writes into demo/out/.work/runner/.
+
+// A run's work folder goes when the command ends. A failure first keeps
+// Playwright's results (its error context) in demo/out/failed/; a success
+// clears an older failure, so what's there is always the latest.
+const finish = (args, ok) => {
+  const failed = path.join(args.outDir, "failed");
+  fs.rmSync(failed, { recursive: true, force: true });
+  const results = path.join(args.workDir, "test-results");
+  if (!ok && fs.existsSync(results)) {
+    fs.cpSync(results, failed, { recursive: true });
+    console.error(`Playwright's output for this failure: ${failed}`);
+  }
+  fs.rmSync(args.workDir, { recursive: true, force: true });
+  const work = path.dirname(args.workDir);
+  if (fs.existsSync(work) && fs.readdirSync(work).length === 0) {
+    fs.rmdirSync(work);
+  }
+};
+
+const runPlaywright = (args, mode) => {
+  const require = createRequire(path.join(args.appDir, "package.json"));
+  const cli = require.resolve("@playwright/test/cli");
+  fs.rmSync(args.workDir, { recursive: true, force: true });
+  fs.mkdirSync(args.workDir, { recursive: true });
+  writeRunner(args);
+  const result = spawnSync(
+    process.execPath,
+    [cli, "test", "-c", args.configPath],
+    {
+      cwd: args.appDir,
+      // With --json, Playwright's own output goes to stderr so stdout is pure JSON.
+      stdio: ["inherit", args.json ? 2 : "inherit", "inherit"],
+      env: {
+        ...process.env,
+        DEMO_MODE: mode,
+        DEMO_STORYBOARD: args.storyboardPath ?? "",
+        DEMO_BRAND: args.brand ?? "",
+        DEMO_OUT: args.outDir,
+        DEMO_WORK: args.workDir,
+        DEMO_DRAFT: args.draft ? "1" : "",
+      },
+    },
+  );
+  return result.status ?? 1;
+};
+
+const printReport = (report) => {
+  if (report.ok) {
+    console.log(`✓ story passes (${report.steps} steps)`);
+    return;
+  }
+  const where = report.step
+    ? `step ${report.step} (${report.do}${report.target ? ` ${report.target}` : ""})`
+    : "before the first step";
+  console.log(`✗ ${where}: ${report.error}`);
+  if (report.visible?.length) {
+    console.log(`  visible testids: ${report.visible.join(", ")}`);
+  }
+};
+
+// demo-video init [--app <dir>] [--dry-run]: needs no demo/ yet, so it skips
+// parseArgs.
+const runInit = (argv) => {
+  const dryRun = argv.includes("--dry-run");
+  const at = argv.indexOf("--app");
+  const value = at === -1 ? null : argv[at + 1];
+  // A flag after --app (--app --dry-run) is not its directory.
+  const appMissing = at !== -1 && (!value || value.startsWith("-"));
+  const app = appMissing ? null : value;
+  const unknown = argv.filter(
+    (a, i) =>
+      a !== "--dry-run" && a !== "--app" && !(app && argv[i - 1] === "--app"),
+  );
+  if (appMissing || unknown.length) {
+    // Name what was wrong: "-app" for "--app", or a second command on the line.
+    const problem = appMissing
+      ? "--app needs a directory right after it"
+      : `Unknown argument${unknown.length > 1 ? "s" : ""}: ${unknown.join(" ")}`;
+    console.error(
+      `${problem}\nUsage: demo-video init [--app <dir>] [--dry-run]`,
+    );
+    return 2;
+  }
+  const root = process.cwd();
+  const result = app
+    ? initApp(path.resolve(root, app), { dryRun })
+    : initRepo(root, { dryRun });
+  console.log(
+    `demo-video init${dryRun ? " (dry run: nothing written)" : ""}: ${app ?? "repo"}`,
+  );
+  const width = Math.max(...result.changes.map(([, what]) => what.length));
+  for (const [status, what, detail] of result.changes) {
+    console.log(`  ${status.padEnd(8)} ${what.padEnd(width)}  ${detail}`);
+  }
+  if (result.todo.length) {
+    console.log("\nBy hand:");
+    for (const item of result.todo) {
+      console.log(`  - ${item}`);
+    }
+  }
+  return 0;
+};
+
+// demo-video pick [--request "<text>" | --app <a> --story <s> --brand <b>]
+// [--json] <app dir>...: which existing story and brand a request means
+// (see pick.mjs). --request reads a sentence (a /demo-video comment); the
+// flags are exact names (the Run workflow form).
+const runPick = (argv) => {
+  const flags = {};
+  const dirs = [];
+  let json = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") {
+      json = true;
+    } else if (["--request", "--app", "--story", "--brand"].includes(arg)) {
+      flags[arg.slice(2)] = argv[++i] ?? "";
+    } else {
+      dirs.push(arg);
+    }
+  }
+  if (dirs.length === 0) {
+    console.error(
+      'Usage: demo-video pick [--request "<text>" | --app <a> --story <s> --brand <b>] [--json] <app dir>...',
+    );
+    return 2;
+  }
+  const apps = dirs.map((d) => appMenu(path.resolve(d)));
+  const result =
+    flags.request !== undefined
+      ? pick(flags.request, apps)
+      : pickExact(apps, flags);
+  const out = result.menu
+    ? {
+        menu: true,
+        reason: result.reason,
+        markdown: menuMarkdown(result.apps ?? apps, result.reason),
+      }
+    : result;
+  if (json) {
+    console.log(JSON.stringify(out));
+  } else if (out.menu) {
+    console.log(out.markdown);
+  } else {
+    console.log(
+      `${out.app}: story ${out.story}, brand ${out.brand ?? "(the app's default)"}`,
+    );
+  }
+  return 0;
+};
+
+const run = () => {
+  if (process.argv[2] === "init") {
+    return runInit(process.argv.slice(3));
+  }
+  if (process.argv[2] === "pick") {
+    return runPick(process.argv.slice(3));
+  }
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2), process.cwd());
+  } catch (error) {
+    console.error(error.message);
+    return 2;
+  }
+  switch (args.command) {
+    case "check": {
+      const status = runPlaywright(args, "check");
+      // The report comes back through the work folder and goes with it.
+      const reportPath = path.join(args.workDir, "check.json");
+      const report = fs.existsSync(reportPath)
+        ? JSON.parse(fs.readFileSync(reportPath, "utf8"))
+        : {
+            ok: false,
+            error:
+              "the dry run produced no report (Playwright did not run the demo test — see its output above)",
+          };
+      const ok = report.ok && status === 0;
+      finish(args, ok);
+      if (args.json) {
+        console.log(JSON.stringify(report, null, 2));
+      } else {
+        printReport(report);
+      }
+      return ok ? 0 : 1;
+    }
+    case "record": {
+      // The recording stays in the work folder for `encode`.
+      const status = runPlaywright(args, "record");
+      if (status !== 0) {
+        finish(args, false);
+      }
+      return status;
+    }
+    case "render": {
+      const status = runPlaywright(args, "record");
+      if (status !== 0) {
+        finish(args, false);
+        return status;
+      }
+      fs.mkdirSync(args.outDir, { recursive: true });
+      const result = encodeRecording(args.workDir, args.outDir);
+      finish(args, true);
+      if (args.json) {
+        // For CI: { output, duration, stills, sheet } on stdout, nothing else.
+        console.log(JSON.stringify(result));
+      } else {
+        console.log(`Wrote ${result.output} (${result.duration.toFixed(1)} s)`);
+        console.log(`Review: ${result.sheet} (one frame a second)`);
+      }
+      return 0;
+    }
+    case "encode": {
+      fs.mkdirSync(args.outDir, { recursive: true });
+      const { output, duration } = encodeRecording(args.workDir, args.outDir);
+      finish(args, true);
+      console.log(`Wrote ${output} (${duration.toFixed(1)} s)`);
+      return 0;
+    }
+    case "list": {
+      // For people and the Linear agent: which stories exist, which is primary.
+      const stories = listStories(args.demoDir);
+      if (args.json) {
+        console.log(JSON.stringify(stories));
+      } else if (stories.length === 0) {
+        console.log("No stories yet in demo/stories/.");
+      } else {
+        for (const s of stories) {
+          console.log(
+            `${s.primary ? "* " : "  "}${s.name}${s.description ? `: ${s.description}` : ""}${s.extends ? ` (${s.extends}, for ${s.brand})` : ""}`,
+          );
+        }
+      }
+      return 0;
+    }
+    case "stills":
+      console.log(`Stills from ${extractStillsFrom(args.outDir)}`);
+      return 0;
+  }
+  return 2;
+};
+
+const main = () => {
+  try {
+    return run();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (process.argv.includes("--json")) {
+      console.log(JSON.stringify({ ok: false, error: message }));
+    } else {
+      console.error(message);
+    }
+    return 1;
+  }
+};
+
+process.exitCode = main();