@navipartner/demo-video 0.6.0 → 0.7.1

package/README.md

@@ -1,132 +1,107 @@
 # @navipartner/demo-video
 
-Marketing demo videos of React apps.
+Marketing demo videos of React apps, in the NaviPartner look: brisk camera
+pushes and big serif cards that can show a snapshot of the result beside
+the words. A story is a showcase of an app's main journey (45–90 s) or a
+clip of one feature (15–30 s). The engine films an app on its own
+Playwright e2e mocks, frame by frame at 60 fps, so pans stay smooth. It
+works in pnpm repos on GitHub Actions, with `@playwright/test` 1.59 or later.
 
-- Filmed on the app's own e2e mocks.
-- NaviPartner look: camera pushes, serif cards.
-- NaviPartner's brand, the only one kept.
-- Customer brands researched per video, never saved.
-- Smooth 60 fps, frame by frame.
-- pnpm repos, GitHub Actions, `@playwright/test` 1.59+.
+NaviPartner's brand is the only one kept. A video in a customer's branding
+is made in Linear, where @Linear researches their brand for that one video
+and saves nothing.
 
 ## Setup
 
+From the repo root:
+
     npx --ignore-scripts @navipartner/demo-video init
     pnpm install
 
-- Adds the skill, label and workflow.
-- Finds apps with a `playwright.config`.
-- One app: set up directly.
-- Several apps: `init --app <folder>` each.
-- Safe to re-run; `--dry-run` previews.
-- Then ask Claude for a video.
+`init` adds the skill, the `demo video` label and the workflow, and finds
+the apps: folders with a `playwright.config`. A repo with one app is set up
+in one go; with several, it prints the `init --app <folder>` line to run
+for each.
+It's safe to re-run, and `--dry-run` previews. Then ask Claude for a demo
+video of the app: it writes the adapter and the primary story with you.
 
 ## Get a video
 
-| Ask | Who | You get |
+| Where | Ask | For |
 |---|---|---|
-| @Linear "video of checkout from np-pos for Northwind (northwind.example)" | Linear users | that story in Northwind's researched brand, attached |
-| @Linear "video of checkout from np-pos" | Linear users | that story, NaviPartner brand, attached |
-| `/demo-video` on a PR | members | primary story, from the PR branch |
-| `/demo-video checkout` | members | that story |
-| `/demo-video checkout in danish` | members | its translation |
-| `/demo-video help` | members | menu of stories |
-| `demo video` label on a PR | whoever labels | every changed story, each push |
-| Actions → Demo video → Run workflow | repo writers | any story, any branch |
-| `pnpm exec demo-video render` | developers | any story, locally |
-
-- Requests only pick existing stories.
-- New stories come via PRs.
-- PR comments: first line is the request.
-- Unknown names get the menu.
-- Customer branding only through @Linear.
+| Linear | @Linear "video of checkout from np-pos" | anyone who wants a video of an existing story |
+| Linear | @Linear "… for Northwind (northwind.example)" | the same, in a customer's researched brand |
+| A PR | the `demo video` label | reviewing the stories the PR adds or changes |
+| A PR | `/demo-video checkout` (`help` for the menu) | filming any story from the PR's branch |
+| Your machine | `pnpm exec demo-video render` | writing and tuning a story |
 
-### In Linear
+Requests only pick existing stories; new stories come through a developer's
+PR. In a PR comment, the first line is the request, a translation is found
+by its language (`checkout in danish`), and a name that doesn't match gets
+the menu.
 
-- Ask @Linear in plain words.
-- Name the repo, story and customer.
-- Follows the skill's `linear.md`.
-- NaviPartner itself: 60 fps video.
-- A customer: a pitch draft.
-- MP4 and contact sheet attached.
-- Nothing committed, nothing kept.
-- Linear AI credits, no API key.
-- Slow sandbox: ~15× video length.
+### In Linear
 
-### Pitch drafts
+Ask @Linear in plain words, naming the repo, the story and the customer. In
+a coding session it follows the skill's `linear.md`, attaches the MP4 and
+its contact sheet to the issue, and commits nothing. It runs on Linear's AI
+credits; its sandbox is slow, about 15× the video's length at 60 fps.
 
-- Researched from the customer's own website.
-- Checked, then filmed at 30 fps.
-- Google Fonts stand-ins only.
-- That customer only; check before sending.
-- Other use needs their written permission.
+For a customer, the video is a **pitch draft**. @Linear researches their
+brand from their own website, the engine checks it and films at 30 fps, and
+the brand is deleted afterwards. Fonts are Google Fonts stand-ins. A pitch
+draft is for that customer only: check it before sending it, and any other
+use needs their written permission.
 
 ## Stories and brands
 
-- **Story:** `demo/stories/<name>.json`, scenes as JSON.
-- Built only from the mocks.
-- One story per app is primary.
-- **Translation:** its own story, e.g. `checkout-da.json`.
-- Same flow, cards in that language.
-- **Brands:** only `navipartner`, shipped with the engine.
-- No `demo/brands/` in repos: `check` refuses it.
-- Stories never name a brand.
-- **Brand needs:** the adapter lists what a brand gives.
-- Pitch research fills exactly those.
-- The skill has fields and the look.
+A story is `demo/stories/<name>.json`: the scenes of one journey, built only
+from what the e2e mocks return. One story per app is its primary story. A
+translation is a story of its own, such as `checkout-da.json`, with the same
+flow and its cards in that language.
+
+Repos keep no brands. `navipartner` ships with the engine, `check` refuses a
+`demo/brands/` folder, and stories never name a brand. The adapter's
+`brandNeeds` lists what a brand gives the app (a background image, a
+secondary colour), which is exactly what a pitch draft researches. The skill
+(`skills/np-demo-video/`) has every field and the look.
 
 ## Commands
 
-Run in the app's folder: `pnpm exec demo-video <command>`.
+Run them in the app's folder: `pnpm exec demo-video <command>`.
 
 | Command | Does |
 |---|---|
-| `init` | sets up a repo or app |
-| `list` | stories, primary first |
-| `check` | dry run in seconds, names problems |
-| `render` | MP4, contact sheet, ten stills |
-| `record` / `encode` / `stills` | render in parts |
-| `brand-needs` | what a brand must give |
-| `pitch <proposal.json>` | pitch draft from a researched brand |
-| `pick` | what a request means (workflows) |
-
-| Flag | Means |
-|---|---|
-| `--story <name>` | default: primary story |
-| `--draft` | 30 fps, twice as fast |
-| `--app <dir>` | app folder, default `.` |
-| `--json` | machine-readable output |
-| `--brand`, `--brands <dir>` | used by `pitch` only |
-
-Output lands in `demo/out/`. Failures keep Playwright's output in `demo/out/failed/`.
-
-## Develop
+| `init` | sets up a repo or an app |
+| `list` | the stories, primary first |
+| `check` | a dry run in seconds that names what would film badly |
+| `render` | the MP4, a contact sheet and ten stills, in `demo/out/` (it checks first when cards show snapshots) |
+| `record`, `encode`, `stills` | `render` in parts |
+| `brand-needs` | what a brand must give this app |
+| `pitch <proposal.json>` | a pitch draft from a researched brand |
+| `pick` | what a request means (used by the workflows) |
+
+`--story <name>` picks a story (default: the primary one), `--draft` films
+at 30 fps in about half the time, `--app <dir>` names the app folder and
+`--json` gives machine-readable output. When something fails, Playwright's
+output is kept in `demo/out/failed/`.
+
+## Develop and release
 
     pnpm install
     pnpm test && pnpm typecheck && pnpm lint && pnpm build
 
-- CI runs tests, actionlint, smoke render.
-
-## Release
-
-1. Bump `version` on main.
-2. `git tag vX.Y.Z && git push origin vX.Y.Z`.
-
-- CI publishes to npm (`latest`).
-- Trusted publishing, no npm token.
-- `v0` tag moves along.
-- Manual `release.yml` run: `next` prerelease.
-
-## Public package, private repo
-
-- `check-public.mjs` checks every tarball.
-- Allowed files only, no source maps.
-- No secrets, emails or local paths.
-- Names aren't caught: keep customers out.
+CI runs the tests, actionlint and a smoke render of the fixture app. To
+release, bump `version` in `package.json` on main, then
+`git tag vX.Y.Z && git push origin vX.Y.Z`. CI publishes to npm as `latest`
+through trusted publishing (no npm token) and moves the `v0` tag. Running
+`release.yml` by hand publishes a `next` prerelease.
 
-## Compatibility
+The package is public; this repo is not. `scripts/check-public.mjs` checks
+every tarball for files outside the allowlist, source maps, secrets, emails
+and local paths. It can't catch names, so keep customers and people out of
+everything that ships.
 
-- Projects pin the CLI version.
-- Their workflows follow `v0` immediately.
-- Workflows must support CLI 0.4+.
-- Breaking that means `v1`.
+Projects pin the CLI in their lockfile, but their workflows follow `v0` at
+once. So `render.yml` and `request.yml` must work with every CLI from 0.4;
+anything that can't is `v1`.

package/bin/demo-video.mjs

@@ -8,8 +8,8 @@ import path from "node:path";
 
 import { listStories, parseArgs } from "./args.mjs";
 import { encodeRecording, extractStillsFrom } from "./encode.mjs";
-import { initApp, initProject } from "./init.mjs";
-import { appMenu, menuMarkdown, pick, pickExact } from "./pick.mjs";
+import { findApps, initApp, initProject } from "./init.mjs";
+import { appMenu, menuMarkdown, pick } from "./pick.mjs";
 import { buildPitchBrand } from "./pitch.mjs";
 import { writeRunner } from "./runner.mjs";
 
@@ -56,15 +56,85 @@ const runPlaywright = (args, mode) => {
         DEMO_OUT: args.outDir,
         DEMO_WORK: args.workDir,
         DEMO_DRAFT: args.draft ? "1" : "",
+        DEMO_STILLS: args.stillsDir ?? "",
       },
     },
   );
   return result.status ?? 1;
 };
 
+const readReport = (args) => {
+  const reportPath = path.join(args.workDir, "check.json");
+  return 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)",
+      };
+};
+
+// A card that shows a still of its chapter's result (`show`) needs the
+// still before filming: a check captures it, as the element last looks in
+// that chapter. Returns the check's run, whose folder holds the stills
+// until the take is filmed, or null when no card shows one.
+const captureStills = (args) => {
+  const story = JSON.parse(fs.readFileSync(args.storyboardPath, "utf8"));
+  const shows =
+    story.title?.show !== undefined ||
+    (story.steps ?? []).some((s) => s?.do === "card" && s.show !== undefined);
+  if (!shows) {
+    return null;
+  }
+  const workDir = path.join(path.dirname(args.workDir), "check");
+  const runnerDir = path.join(workDir, "runner");
+  const check = {
+    ...args,
+    command: "check",
+    workDir,
+    runnerDir,
+    configPath: path.join(runnerDir, "playwright.config.mjs"),
+    stillsDir: path.join(workDir, "stills"),
+  };
+  const status = runPlaywright(check, "check");
+  const report = readReport(check);
+  if (!report.ok || status !== 0) {
+    finish(check, false);
+    throw new Error(
+      `The story doesn't pass check, so its card stills can't be captured: ${report.error}`,
+    );
+  }
+  return check;
+};
+
+// Films the take, with the card stills when the story has any.
+const film = (args) => {
+  const check = captureStills(args);
+  const status = runPlaywright(
+    { ...args, stillsDir: check?.stillsDir },
+    "record",
+  );
+  if (check) {
+    finish(check, true);
+  }
+  return status;
+};
+
+// How long each kind runs (look.md, src/timing.ts KIND_SECONDS).
+const KIND_SECONDS = { showcase: [45, 90], feature: [15, 30] };
+
 const printReport = (report) => {
   if (report.ok) {
     console.log(`✓ story passes (${report.steps} steps)`);
+    const range = KIND_SECONDS[report.kind];
+    if (report.seconds !== undefined && range) {
+      const [low, high] = range;
+      const fits =
+        report.seconds < low ? "short" : report.seconds > high ? "long" : null;
+      console.log(
+        `  about ${report.seconds} s; a ${report.kind === "feature" ? "feature clip" : "showcase"} runs ${low}–${high} s${fits ? `, so this is ${fits}` : ""}`,
+      );
+    }
     return;
   }
   const where = report.step
@@ -100,6 +170,14 @@ const runInit = (argv) => {
     return 2;
   }
   const root = process.cwd();
+  if (app && !fs.existsSync(path.join(root, app, "package.json"))) {
+    // Name the folders that are apps, so the fix is a copy away.
+    const apps = findApps(root);
+    console.error(
+      `${app} isn't an app: it has no package.json.${apps.length ? `\nApps here: ${apps.join(", ")}` : ""}`,
+    );
+    return 2;
+  }
   const result = app
     ? initApp(path.resolve(root, app), { dryRun })
     : initProject(root, { dryRun });
@@ -124,35 +202,31 @@ const runInit = (argv) => {
   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).
+// demo-video pick [--request "<text>"] [--json] <app dir>...: which existing
+// story a request means (see pick.mjs): a /demo-video comment, or a request
+// to @Linear. No request: the primary story.
 const runPick = (argv) => {
-  const flags = {};
+  let request = "";
   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"].includes(arg)) {
-      flags[arg.slice(2)] = argv[++i] ?? "";
+    } else if (arg === "--request") {
+      request = argv[++i] ?? "";
     } else {
       dirs.push(arg);
     }
   }
   if (dirs.length === 0) {
     console.error(
-      'Usage: demo-video pick [--request "<text>" | --app <a> --story <s>] [--json] <app dir>...',
+      'Usage: demo-video pick [--request "<text>"] [--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 result = pick(request, apps);
   const out = result.menu
     ? {
         menu: true,
@@ -211,21 +285,25 @@ const runPitch = async (argv) => {
       brandsDir,
       "--json",
     ];
+    // The check also captures the card stills, in the customer's brand.
     const check = parseArgs(["check", ...common], process.cwd());
+    check.stillsDir = path.join(check.workDir, "stills");
     const checked = runPlaywright(check, "check");
-    const reportPath = path.join(check.workDir, "check.json");
-    const report = fs.existsSync(reportPath)
-      ? JSON.parse(fs.readFileSync(reportPath, "utf8"))
-      : { ok: false, error: "the dry run produced no report" };
-    finish(check, report.ok && checked === 0);
+    const report = readReport(check);
     if (!report.ok || checked !== 0) {
+      finish(check, false);
       throw new Error(
         `The researched brand doesn't film with this story: ${report.error}`,
       );
     }
     // A pitch is a draft for one customer: 30 fps, about half the time.
     const render = parseArgs(["render", ...common, "--draft"], process.cwd());
-    if (runPlaywright(render, "record") !== 0) {
+    const filmed = runPlaywright(
+      { ...render, stillsDir: check.stillsDir },
+      "record",
+    );
+    finish(check, true);
+    if (filmed !== 0) {
       finish(render, false);
       throw new Error("Filming the pitch draft failed (see above)");
     }
@@ -283,14 +361,7 @@ const run = () => {
     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 report = readReport(args);
       const ok = report.ok && status === 0;
       finish(args, ok);
       if (args.json) {
@@ -302,14 +373,14 @@ const run = () => {
     }
     case "record": {
       // The recording stays in the work folder for `encode`.
-      const status = runPlaywright(args, "record");
+      const status = film(args);
       if (status !== 0) {
         finish(args, false);
       }
       return status;
     }
     case "render": {
-      const status = runPlaywright(args, "record");
+      const status = film(args);
       if (status !== 0) {
         finish(args, false);
         return status;

package/bin/init.d.mts

@@ -5,6 +5,8 @@ export interface InitResult {
 }
 export const IGNORE_LINE: string;
 export const LABEL: string;
+/** How init is run before the package is installed. */
+export const INIT: string;
 export const CALLER_WORKFLOW: string;
 export function initRepo(
   root: string,

package/bin/init.mjs

@@ -9,6 +9,8 @@ import { fileURLToPath } from "node:url";
 // workflow. Safe to re-run; with dryRun it reports what it would change.
 
 const PKG = "@navipartner/demo-video";
+/** How init is run before the package is installed (the README's way). */
+export const INIT = `npx --ignore-scripts ${PKG} init`;
 export const IGNORE_LINE = "**/demo/out/";
 export const LABEL = "demo video";
 
@@ -22,23 +24,14 @@ const engineVersion = () =>
 
 export const CALLER_WORKFLOW = `name: Demo video
 # The "${LABEL}" label films the stories a PR adds or changes. A comment
-# "/demo-video [<story>]" on a PR, or Actions → Demo video → Run workflow,
-# films an existing story in NaviPartner's brand. A customer's branding: ask
+# "/demo-video [<story>]" on a PR films an existing story in NaviPartner's
+# brand. A customer's branding: ask
 # @Linear (the skill's linear.md); repos keep no brands.
 on:
   pull_request:
     types: [labeled, synchronize]
   issue_comment:
     types: [created]
-  # Actions → Demo video → Run workflow: film a story.
-  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: ""
 permissions: {}
 jobs:
   render:
@@ -48,15 +41,12 @@ jobs:
       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'))
+    if: 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 }}
 `;
 
 const read = (file) =>
@@ -257,7 +247,7 @@ export const initRepo = (root, { dryRun = false, label = true } = {}) => {
       .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.',
+        '.github/workflows/demo-video.yml predates the "request" job (/demo-video comments): delete it and re-run init to get the current one.',
       );
     }
   } else {
@@ -378,7 +368,7 @@ export const initApp = (appDir, { dryRun = false } = {}) => {
   const todo = [];
   const pkgFile = path.join(appDir, "package.json");
   if (!fs.existsSync(pkgFile)) {
-    throw new Error(`No package.json in ${appDir}`);
+    throw new Error(`${appDir} has no package.json, so it isn't an app.`);
   }
   const pkg = JSON.parse(fs.readFileSync(pkgFile, "utf8"));
   const version = engineVersion();
@@ -408,14 +398,19 @@ export const initApp = (appDir, { dryRun = false } = {}) => {
     );
   }
 
+  const configFile = ["ts", "mts", "js", "mjs", "cts", "cjs"]
+    .map((ext) => path.join(appDir, `playwright.config.${ext}`))
+    .find((f) => fs.existsSync(f));
+  if (!configFile) {
+    todo.push(
+      "Add a playwright.config to this folder: videos run on the app's e2e setup.",
+    );
+  }
   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(/^@[^/]+\//, ""),
@@ -504,12 +499,16 @@ export const initProject = (root, options = {}) => {
   }
   const todo = [...repo.todo];
   if (apps.length > 1) {
+    // Exactly what to run: one line per app, copied as is.
     todo.push(
-      `This repo has ${apps.length} apps with Playwright e2e tests: ${apps.join(", ")}. Set up each one you want videos of with init --app <folder>.`,
+      [
+        `${apps.length} apps found and none set up yet. Run this for each app you want videos of:`,
+        ...apps.map((app) => `    ${INIT} --app ${app}`),
+      ].join("\n"),
     );
   } else {
     todo.push(
-      "No app with a playwright.config found: the demo films an app on its Playwright e2e tests. Add them, then run init again (or init --app <folder>).",
+      `No app found (a folder with package.json and playwright.config). Run ${INIT} --app <folder> once it has both.`,
     );
   }
   return { apps, changes: repo.changes, todo };

package/bin/pick.d.mts

@@ -15,7 +15,3 @@ export type Pick =
 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 },
-): Pick;

package/bin/pick.mjs

@@ -171,42 +171,3 @@ export const menuMarkdown = (apps, reason) => {
   }
   return lines.join("\n");
 };
-
-/**
- * The form's version (Actions → Run workflow): app and story by name, no
- * guessing. Empty story = the primary story, empty app = the only app. A
- * name that doesn't exist gets the menu, so a typo never films something
- * else. `apps` in a menu result narrows it.
- */
-export const pickExact = (apps, { app = "", story = "" }) => {
-  const slashes = (p) => p.split("\\").join("/");
-  const wanted = slashes(app).replace(/\/+$/, "");
-  const candidates = wanted
-    ? apps.filter((a) => {
-        const dir = slashes(a.dir);
-        return (
-          a.name === wanted || dir === wanted || dir.endsWith(`/${wanted}`)
-        );
-      })
-    : apps;
-  if (candidates.length === 0) {
-    return { menu: true, reason: `No app \`${wanted}\`. The apps:` };
-  }
-  if (candidates.length > 1) {
-    return { menu: true, reason: "Which app? Fill in App with one of:" };
-  }
-  const chosen = candidates[0];
-  const found = story
-    ? chosen.stories.find((s) => s.name === story)
-    : chosen.stories.find((s) => s.primary);
-  if (!found) {
-    return {
-      menu: true,
-      reason: story
-        ? `No story \`${story}\` in ${chosen.name}. Pick one:`
-        : `${chosen.name} has no primary story. Pick one:`,
-      apps: [chosen],
-    };
-  }
-  return { app: chosen.dir, story: found.name };
-};