@navipartner/demo-video 0.0.0-stage → 0.5.0

package/bin/demo-video.mjs

@@ -0,0 +1,425 @@
+#!/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 os from "node:os";
+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 { buildPitchBrand } from "./pitch.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_BRANDS: args.brandsDir ?? "",
+        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. Without --app: the repo, plus its app if it has exactly one.
+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 })
+    : initProject(root, { dryRun });
+  const what = app
+    ? `app ${app}`
+    : result.apps.length === 1
+      ? `repo and its app${result.apps[0] === "." ? " (the repo root)" : ` ${result.apps[0]}`}`
+      : "repo";
+  console.log(
+    `demo-video init${dryRun ? " (dry run: nothing written)" : ""}: ${what}`,
+  );
+  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;
+};
+
+// demo-video pitch <proposal.json> [--app <dir>] [--story <name>] [--out <dir>]
+// [--json]: a pitch draft from a researched proposal (the skill's pitch.md).
+// It builds the brand in a temp folder (pitch.mjs), checks the story with
+// it, films it at 30 fps and moves the video and its contact sheet to --out
+// (default: the proposal's folder). The brand and the repo's copies go.
+const runPitch = async (argv) => {
+  const flags = { app: ".", story: null, out: null };
+  let file = null;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (["--app", "--story", "--out"].includes(arg)) {
+      flags[arg.slice(2)] = argv[++i] ?? null;
+    } else if (arg !== "--json") {
+      file = arg;
+    }
+  }
+  if (!file) {
+    console.error(
+      "Usage: demo-video pitch <proposal.json> [--app <dir>] [--story <name>] [--out <dir>] [--json]",
+    );
+    return 2;
+  }
+  const proposalPath = path.resolve(file);
+  const out = path.resolve(flags.out ?? path.dirname(proposalPath));
+  const brandsDir = fs.mkdtempSync(path.join(os.tmpdir(), "demo-video-pitch-"));
+  try {
+    const built = await buildPitchBrand(
+      JSON.parse(fs.readFileSync(proposalPath, "utf8")),
+      brandsDir,
+    );
+    // --json keeps Playwright's output off stdout.
+    const common = [
+      "--app",
+      flags.app,
+      ...(flags.story ? ["--story", flags.story] : []),
+      "--brand",
+      built.brand,
+      "--brands",
+      brandsDir,
+      "--json",
+    ];
+    const check = parseArgs(["check", ...common], process.cwd());
+    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);
+    if (!report.ok || checked !== 0) {
+      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) {
+      finish(render, false);
+      throw new Error("Filming the pitch draft failed (see above)");
+    }
+    fs.mkdirSync(render.outDir, { recursive: true });
+    const result = encodeRecording(render.workDir, render.outDir);
+    finish(render, true);
+    // The video leaves the repo; its stills and sheet there go.
+    fs.mkdirSync(out, { recursive: true });
+    const video = path.join(out, path.basename(result.output));
+    const sheet = path.join(
+      out,
+      `${path.basename(result.output, ".mp4")}-sheet.jpg`,
+    );
+    fs.copyFileSync(result.output, video);
+    fs.copyFileSync(result.sheet, sheet);
+    for (const f of [result.output, result.sheet, ...result.stills]) {
+      fs.rmSync(f, { force: true });
+    }
+    const review = path.dirname(result.sheet);
+    if (fs.existsSync(review) && fs.readdirSync(review).length === 0) {
+      fs.rmdirSync(review);
+    }
+    const summary = { ...built, video, sheet, duration: result.duration };
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(summary));
+    } else {
+      console.log(
+        `Wrote ${video} (${result.duration.toFixed(1)} s) and ${sheet}`,
+      );
+    }
+    return 0;
+  } finally {
+    fs.rmSync(brandsDir, { recursive: true, force: true });
+  }
+};
+
+const run = () => {
+  if (process.argv[2] === "pitch") {
+    return runPitch(process.argv.slice(3));
+  }
+  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 workflows: 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;
+    case "brand-needs": {
+      const status = runPlaywright(args, "needs");
+      const needsPath = path.join(args.workDir, "needs.json");
+      const needs =
+        status === 0 && fs.existsSync(needsPath)
+          ? JSON.parse(fs.readFileSync(needsPath, "utf8"))
+          : null;
+      finish(args, Boolean(needs));
+      if (!needs) {
+        throw new Error("Couldn't read the adapter's brand needs (see above)");
+      }
+      if (args.json) {
+        console.log(JSON.stringify(needs, null, 2));
+        return 0;
+      }
+      const lines = (entries) =>
+        Object.entries(entries).map(
+          ([key, need]) =>
+            `  ${key}${need.optional ? " (optional)" : ""}: ${need.what}`,
+        );
+      console.log(`Every brand, for the video:`);
+      for (const [key, what] of Object.entries(needs.video)) {
+        console.log(`  ${key}: ${what}`);
+      }
+      const own = [
+        ...lines(
+          Object.fromEntries(
+            Object.entries(needs.appNeeds.config).map(([k, v]) => [
+              `config.${k}`,
+              v,
+            ]),
+          ),
+        ),
+        ...lines(
+          Object.fromEntries(
+            Object.entries(needs.appNeeds.assets).map(([k, v]) => [
+              `assets.${k}`,
+              v,
+            ]),
+          ),
+        ),
+      ];
+      console.log(`\n${needs.app} itself:`);
+      console.log(
+        own.length
+          ? own.join("\n")
+          : "  (nothing listed: the adapter has no brandNeeds)",
+      );
+      return 0;
+    }
+  }
+  return 2;
+};
+
+const main = async () => {
+  try {
+    return await 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 = await main();

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,30 @@
+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;
+/** The repo's apps (folders with a playwright.config), "." for the root. */
+export function findApps(root: string): string[];
+export function initProject(
+  root: string,
+  options?: { dryRun?: boolean; label?: boolean },
+): InitResult & { apps: string[] };
+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;