@navipartner/demo-video 0.4.0 → 0.5.0

package/README.md

@@ -1,109 +1,135 @@
-# @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 a React app, in the NaviPartner house look, with any
+customer's brand.
+
+- Filmed by Playwright on the app's **own e2e mocks**, unchanged.
+- For **pnpm** repos on **GitHub Actions**. Needs `@playwright/test` 1.59+.
+
+## Setup
+
+From the repo root:
+
+    npx --ignore-scripts @navipartner/demo-video init
+    pnpm install
+
+- Sets up the repo: `.gitignore`, the skill, the `demo video` label,
+  `.github/workflows/demo-video.yml`.
+- Finds the apps: folders with a `playwright.config` and a `package.json`.
+  - **One app** (most repos): set up too. Done.
+  - **Several apps:** listed. Run `init --app <folder>` for each one you want.
+- Safe to re-run. `--dry-run` previews.
+- Then ask Claude for a demo video of the app: it finishes
+  `demo/demo.config.ts` and writes the primary story.
+
+## Getting a video
+
+| Way | Who | Films | Video lands |
+|---|---|---|---|
+| **Run workflow form** (Actions → Demo video) | repo writers | a story + brand, from the chosen branch | the run's Summary |
+| **PR comment** `/demo-video checkout in acme branding` | members | a story + brand, from the PR branch | reply on the PR |
+| **Issue comment**, also from **Linear** | members, Linear's synced thread | a story + brand, from the default branch | reply on the issue (and in Linear) |
+| **`demo video` label** on a PR | whoever labels | every story the PR adds or changes | comment on the PR |
+| **Locally** `pnpm exec demo-video render` | a developer | any story | `demo/out/` |
+
+- **Pitch draft** for a customer without a brand here: ask @Linear (below).
+- The comment's first line is the request; `/demo-video help` lists the
+  stories and brands.
+- No story → the primary story. No brand → the app's default.
+- Unknown story or brand → a reply with the menu of stories and brands.
+- Requests only **choose** a story. New stories come from a developer's PR.
+
+### From Linear
+
+Through Linear's GitHub Issues Sync, both ways.
+
+1. **Once, a Linear admin:** Settings → Integrations → GitHub → link the team
+   to the repo with **Issues Sync**, two-way.
+2. In the issue's **synced thread**: `/demo-video help` for the menu, or
+   e.g. `/demo-video checkout in acme branding`.
+3. The reply syncs back with the video link (opens on GitHub: needs repo
+   read access).
+
+### Pitch drafts (in Linear)
+
+An existing story in a customer's branding before they have a brand here,
+for a sales pitch to that customer.
+
+- **Ask:** on a Linear issue, assign or mention @Linear: "pitch draft of
+  checkout for Hotel Royal (hotelroyal.dk)". Linear's GitHub integration
+  needs code access to the repo.
+- **What happens:** in a coding session, Linear's agent follows the skill's
+  `pitch.md`. It reads what the app needs (`brandNeeds`), researches the
+  brand from the customer's own website, and runs `demo-video pitch`, which
+  checks it, downloads the images and films at 30 fps. The MP4 and its
+  contact sheet are attached to the issue.
+- **Nothing kept:** no commit, no PR, no brand in the repo. The session
+  works in `/tmp/pitch` and deletes it.
+- **For that customer only:** Google Fonts stand-ins, and a person checks it
+  before sending. Any other use needs their permission and a brand in a PR.
+- **Cost and time:** Linear AI credits, no API key. Linear's sandbox films
+  slowly: about 8× the video's length at 30 fps (a 75 s story ≈ 10 min).
+- A `/demo-video … pitch …` comment on GitHub replies with these steps.
+
+## Stories and brands
+
+- **Story:** `demo/stories/<name>.json`, built only from what the mocks
+  return. One per app is `"primary": true`.
+- **Variant:** `checkout.acme.json`, the base story's steps in one
+  customer's words and brand.
+- **Brand:** `demo/brands/<name>.json` plus a folder of assets. The engine
+  ships `navipartner`, the default.
+- **Brand needs:** the adapter's `brandNeeds` lists what this app takes from
+  a brand (a background image, a secondary colour…). `check` fails on a
+  brand that lacks one.
+- The skill (`skills/np-demo-video/`) has the look and every field.
+
+## Commands
+
+In the app's folder: `pnpm exec demo-video <command>` (no command lists
+them all).
+
+| Command | Does |
+|---|---|
+| `list` | The stories, primary first. |
+| `check` | Dry run in seconds. Fails on anything that would film badly, and names the step. |
+| `render` | Films to `demo/out/<story>-<brand>-demo.mp4`, plus a contact sheet and ten stills. |
+| `brand-needs` | What a brand must give this app. |
+| `pitch <proposal.json>` | A pitch draft from a researched brand: check, film at 30 fps, video out of the repo. |
+
+Flags:
+
+- `--story <name>`: default the primary story.
+- `--brand <name>`: default `navipartner`.
+- `--draft`: 30 fps, about twice as fast, for tuning.
+- `--brands <dir>`: a brands folder outside the repo, searched first.
+
+## Developing
+
+    pnpm install
+    pnpm test && pnpm typecheck && pnpm build
+
+## Releasing
+
+1. Bump `version` in `package.json` on `main`.
+2. `git tag vX.Y.Z && git push origin vX.Y.Z`.
+
+- CI publishes to npm as `latest` (trusted publishing, no npm token) and
+  moves the `v0` tag.
+- Running `release.yml` by hand publishes a `next` prerelease.
+
+**What goes public:**
+
+- The package is public; this repo is not.
+- `scripts/check-public.mjs` checks every tarball, in CI and before
+  publishing: only allowed files, no source maps, nothing shaped like a
+  secret, email or local path.
+- It can't catch names: keep customers and people out of the skill and the
+  README.
+
+**Compatibility:**
+
+- Projects pin the CLI in their lockfile, 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). Anything else is `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;