@navipartner/demo-video 0.4.0 → 0.5.1

package/README.md

@@ -1,109 +1,128 @@
-# @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`.
+# @navipartner/demo-video
+
+Marketing demo videos of React apps.
+
+- Filmed on the app's own e2e mocks.
+- NaviPartner look: camera pushes, serif cards.
+- Any customer's brand, chosen per video.
+- Smooth 60 fps, frame by frame.
+- pnpm repos, GitHub Actions, `@playwright/test` 1.59+.
+
+## Setup
+
+    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.
+
+## Get a video
+
+| Ask | Who | You get |
+|---|---|---|
+| @Linear "video of checkout from np-pos for Acme" | Linear users | that story in Acme's brand, attached |
+| @Linear "pitch draft of checkout for Northwind (northwind.example)" | Linear users | a researched brand, attached |
+| `/demo-video` on a PR | members | primary story, from the PR branch |
+| `/demo-video checkout in acme branding` | members | that story, that brand |
+| `/demo-video help` | members | menu of stories and brands |
+| `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.
+
+### In Linear
+
+- Ask @Linear in plain words.
+- Name the repo, story and customer.
+- Follows the skill's `linear.md`.
+- Brand in the repo: 60 fps video.
+- No brand yet: a pitch draft.
+- MP4 and contact sheet attached.
+- Nothing committed, nothing kept.
+- Linear AI credits, no API key.
+- Slow sandbox: ~15× video length.
+
+### Pitch drafts
+
+- @Linear researches the customer's own website.
+- Brand checked, then filmed at 30 fps.
+- Google Fonts stand-ins only.
+- That customer only; check before sending.
+
+## Stories and brands
+
+- **Story:** `demo/stories/<name>.json`, scenes as JSON.
+- Built only from the mocks.
+- One story per app is primary.
+- **Variant:** `checkout.acme.json`, customer's own words.
+- **Brand:** `demo/brands/<name>.json` plus assets.
+- `navipartner` ships as the default.
+- **Brand needs:** the adapter lists what brands need.
+- Missing needs fail `check`.
+- Customer brands need customer permission.
+- The skill has fields and the look.
+
+## Commands
+
+Run 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 |
+| `--brand <name>` | default: `navipartner` |
+| `--draft` | 30 fps, twice as fast |
+| `--brands <dir>` | extra brands folder, searched first |
+| `--app <dir>` | app folder, default `.` |
+| `--json` | machine-readable output |
+
+Output lands in `demo/out/`. Failures keep Playwright's output in `demo/out/failed/`.
+
+## Develop
+
+    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.
+
+## Compatibility
+
+- Projects pin the CLI version.
+- Their workflows follow `v0` immediately.
+- Workflows must support CLI 0.4+.
+- Breaking that means `v1`.

package/bin/args.d.mts

@@ -1,30 +1,39 @@
-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;
+export interface DemoArgs {
+  command:
+    | "check"
+    | "render"
+    | "record"
+    | "encode"
+    | "stills"
+    | "list"
+    | "brand-needs";
+  appDir: string;
+  demoDir: string;
+  adapterPath: string;
+  workDir: string;
+  runnerDir: string;
+  configPath: string;
+  outDir: string;
+  storyboardPath: string | null;
+  brand: string | null;
+  /** `--brands`: a brands folder outside the repo, searched first. */
+  brandsDir: 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

@@ -1,153 +1,158 @@
-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,
-  };
-};
+import fs from "node:fs";
+import path from "node:path";
+
+export const COMMANDS = [
+  "check",
+  "render",
+  "record",
+  "encode",
+  "stills",
+  "list",
+  "brand-needs",
+];
+const NEEDS_STORYBOARD = new Set(["check", "render", "record"]);
+const USAGE = `Usage: demo-video <${COMMANDS.join("|")}> [--app <dir>] [--story <name|file.json>] [--brand <name>] [--brands <dir>] [--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.
+--brands adds a brands folder outside the repo, searched first.
+brand-needs: what a brand must give this app (its adapter's brandNeeds).
+Setup: demo-video init [--app <dir>] [--dry-run]
+For a /demo-video request: demo-video pick --request "<text>" [--json] <app dir>...
+For a pitch draft (the skill's linear.md): demo-video pitch <proposal.json> [--app <dir>] [--story <name>] [--out <dir>] [--json]`;
+
+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", "--brands"].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" || command === "brand-needs" ? command : "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,
+    brandsDir: opts.brands ? path.resolve(cwd, opts.brands) : null,
+    json: opts.json,
+    draft: opts.draft,
+  };
+};