@tandryukha/aidemo 0.8.0

package/src/embed.ts

@@ -0,0 +1,202 @@
+/**
+ * Always-fresh embeds at zero cost — pure snippet generation (no network, no
+ * render). The hosting story is GitHub itself: CI publishes rendered media to a
+ * dedicated orphan branch `demo-media` in the CONSUMING repo, at stable paths
+ * `media/<demo>/latest.mp4|latest.gif|stills/<name>.png`. The raw URLs below
+ * never change, so a README/blog/docs embed updates itself whenever CI
+ * re-renders. See docs/EMBEDS.md for the recipe + cache caveats and
+ * examples/workflows/demo-publish.yml for the publish workflow.
+ *
+ * This module only does string generation: it reads the repo's `origin` remote
+ * to derive owner/repo and takes the demo name from the directory. It never
+ * hits the network beyond the local `git` invocation, and never renders.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { resolve, isAbsolute, basename } from "node:path";
+import { exists } from "./util.js";
+import { UPSTREAM_REPO } from "./distribute.js";
+
+const execFileAsync = promisify(execFile);
+
+/** The dedicated orphan branch CI force-resets on each publish. */
+export const DEMO_MEDIA_BRANCH = "demo-media";
+/** Where the publish workflow lives inside a consuming repo. */
+export const PUBLISH_WORKFLOW_REL = ".github/workflows/demo-publish.yml";
+/** Copy-pasteable pointer to the workflow template in the engine repo. */
+export const PUBLISH_WORKFLOW_TEMPLATE = `https://github.com/${UPSTREAM_REPO}/blob/stable/examples/workflows/demo-publish.yml`;
+
+export interface EmbedOptions {
+  /** Consuming-repo dir to detect owner/repo from. Default: process.cwd(). */
+  repoDir?: string;
+  /** Still-frame basename under stills/ (no extension). Default: "poster". */
+  still?: string;
+}
+
+export interface EmbedResult {
+  owner: string;
+  repo: string;
+  /** Demo name = basename of the demo directory. */
+  demo: string;
+  branch: string;
+  still: string;
+  urls: {
+    /** raw.githubusercontent GIF — embeds in READMEs, comments, most sites. */
+    gif: string;
+    /** raw.githubusercontent MP4 — serves as application/octet-stream (see docs). */
+    mp4: string;
+    /** raw.githubusercontent still PNG. */
+    still: string;
+    /** GitHub Pages MP4 (correct video/mp4 MIME for <video>) — needs Pages on the branch. */
+    pagesMp4: string;
+    /** GitHub Pages project-site base. */
+    pagesBase: string;
+  };
+  snippets: {
+    /** Markdown animated-GIF embed — for READMEs, issues, PR comments. */
+    markdownGif: string;
+    /** Markdown still-image embed. */
+    markdownStill: string;
+    /** HTML <video> (docs sites / blogs) using the Pages MP4 URL. */
+    htmlVideo: string;
+  };
+  workflow: {
+    /** Path the publish workflow lives at inside the consuming repo. */
+    path: string;
+    /** Whether that file is already present. */
+    present: boolean;
+    /** Pointer to the template to copy if it isn't. */
+    template: string;
+  };
+}
+
+/**
+ * Parse an owner/repo slug out of a GitHub remote URL. Handles the common
+ * forms: scp-like `git@github.com:owner/repo.git`, `https://github.com/owner/repo(.git)`,
+ * and `ssh://git@github.com/owner/repo.git`. Returns null for non-github hosts.
+ */
+export function parseGitHubSlug(
+  remoteUrl: string
+): { owner: string; repo: string } | null {
+  const s = remoteUrl.trim().replace(/\/+$/, "");
+  const scp = s.match(/^[^@]+@([^:]+):(?<owner>[^/]+)\/(?<repo>.+?)(?:\.git)?$/);
+  const url = s.match(
+    /^(?:https?|ssh|git):\/\/(?:[^@/]+@)?(?<host>[^/]+)\/(?<owner>[^/]+)\/(?<repo>.+?)(?:\.git)?$/
+  );
+  const host = scp ? scp[1] : url?.groups?.host;
+  const m = scp ?? url;
+  if (!m?.groups || !host || !/(^|\.)github\.com$/i.test(host)) return null;
+  return { owner: m.groups.owner, repo: m.groups.repo };
+}
+
+async function detectSlug(
+  repoDir: string
+): Promise<{ owner: string; repo: string }> {
+  let url: string;
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["-C", repoDir, "remote", "get-url", "origin"],
+      { timeout: 5000 }
+    );
+    url = stdout.trim();
+  } catch {
+    throw new Error(
+      `could not read the 'origin' remote in ${repoDir} — run \`aidemo embed\` ` +
+        `inside the consuming repo, or pass --repo <dir>`
+    );
+  }
+  const slug = parseGitHubSlug(url);
+  if (!slug) {
+    throw new Error(
+      `origin remote is not a github.com repo (${url || "empty"}) — always-fresh ` +
+        `embeds use raw.githubusercontent.com URLs, which need a GitHub-hosted repo`
+    );
+  }
+  return slug;
+}
+
+/**
+ * Build the stable embed URLs + ready-to-paste snippets for one demo. Pure:
+ * the only side effect is reading git config + checking whether the publish
+ * workflow file exists.
+ */
+export async function buildEmbed(
+  dir: string,
+  opts: EmbedOptions = {}
+): Promise<EmbedResult> {
+  const demoDir = isAbsolute(dir) ? dir : resolve(process.cwd(), dir);
+  const demo = basename(demoDir);
+  const repoDir = opts.repoDir
+    ? resolve(process.cwd(), opts.repoDir)
+    : process.cwd();
+  const { owner, repo } = await detectSlug(repoDir);
+  const still = (opts.still ?? "poster").replace(/\.png$/i, "");
+
+  const rawBase = `https://raw.githubusercontent.com/${owner}/${repo}/${DEMO_MEDIA_BRANCH}/media/${demo}`;
+  const gif = `${rawBase}/latest.gif`;
+  const mp4 = `${rawBase}/latest.mp4`;
+  const stillUrl = `${rawBase}/stills/${still}.png`;
+  // GitHub Pages project-site host is the lowercased owner login.
+  const pagesBase = `https://${owner.toLowerCase()}.github.io/${repo}`;
+  const pagesMp4 = `${pagesBase}/media/${demo}/latest.mp4`;
+
+  const markdownGif = `![${demo} demo](${gif})`;
+  const markdownStill = `![${demo}](${stillUrl})`;
+  const htmlVideo =
+    `<video controls muted loop playsinline width="960" poster="${stillUrl}">\n` +
+    `  <source src="${pagesMp4}" type="video/mp4" />\n` +
+    `  <a href="${gif}">▶ Watch the ${demo} demo</a>\n` +
+    `</video>`;
+
+  const workflowPath = resolve(repoDir, PUBLISH_WORKFLOW_REL);
+  const present = await exists(workflowPath);
+
+  return {
+    owner,
+    repo,
+    demo,
+    branch: DEMO_MEDIA_BRANCH,
+    still,
+    urls: { gif, mp4, still: stillUrl, pagesMp4, pagesBase },
+    snippets: { markdownGif, markdownStill, htmlVideo },
+    workflow: {
+      path: PUBLISH_WORKFLOW_REL,
+      present,
+      template: PUBLISH_WORKFLOW_TEMPLATE,
+    },
+  };
+}
+
+/** Human-readable, copy-paste-friendly rendering of the snippets (stdout). */
+export function formatEmbed(r: EmbedResult): string {
+  const out: string[] = [];
+  out.push(`# Always-fresh embeds — ${r.owner}/${r.repo}, demo "${r.demo}"`);
+  out.push(
+    `# Media publishes to the '${r.branch}' branch; these URLs never change,`
+  );
+  out.push(`# so the embed updates itself whenever CI re-renders.`);
+  out.push("");
+  out.push("## Markdown — animated GIF (READMEs, issues, PR comments)");
+  out.push(r.snippets.markdownGif);
+  out.push("");
+  out.push("## Markdown — still image (poster)");
+  out.push(r.snippets.markdownStill);
+  out.push("");
+  out.push(
+    "## HTML — <video> (docs sites / blogs; needs GitHub Pages on the branch for correct mp4 MIME)"
+  );
+  out.push(r.snippets.htmlVideo);
+  out.push("");
+  if (r.workflow.present) {
+    out.push(
+      `# ✓ ${r.workflow.path} present — CI keeps these URLs fresh on every render.`
+    );
+  } else {
+    out.push(`# ⚠ ${r.workflow.path} is absent — the URLs won't populate yet.`);
+    out.push(`#   Add the publish workflow so CI keeps them fresh:`);
+    out.push(`#   ${r.workflow.template}`);
+  }
+  out.push(`# Recipe + cache caveats: docs/EMBEDS.md`);
+  return out.join("\n") + "\n";
+}

package/src/ffmpeg.ts

@@ -0,0 +1,83 @@
+import { spawn } from "node:child_process";
+
+/** Run ffmpeg with the given args; rejects with stderr tail on failure. */
+export function runFfmpeg(args: string[]): Promise<void> {
+  return run("ffmpeg", ["-hide_banner", "-loglevel", "error", "-y", ...args]);
+}
+
+function run(bin: string, args: string[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(bin, args, { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    proc.stderr.on("data", (d) => (stderr += d.toString()));
+    proc.on("error", reject);
+    proc.on("close", (code) => {
+      if (code === 0) resolve();
+      else
+        reject(
+          new Error(
+            `${bin} exited ${code}\n${stderr.split("\n").slice(-25).join("\n")}`
+          )
+        );
+    });
+  });
+}
+
+/** Probe a video file's frame dimensions. */
+export function probeVideoDims(
+  file: string
+): Promise<{ width: number; height: number }> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("ffprobe", [
+      "-v",
+      "quiet",
+      "-print_format",
+      "json",
+      "-select_streams",
+      "v:0",
+      "-show_streams",
+      file,
+    ]);
+    let out = "";
+    proc.stdout.on("data", (d) => (out += d.toString()));
+    proc.on("error", reject);
+    proc.on("close", (code) => {
+      if (code !== 0) return reject(new Error(`ffprobe exited ${code}`));
+      try {
+        const s = JSON.parse(out).streams?.[0];
+        if (!s?.width || !s?.height)
+          return reject(new Error(`No video stream in ${file}`));
+        resolve({ width: s.width, height: s.height });
+      } catch (e) {
+        reject(e);
+      }
+    });
+  });
+}
+
+/** Probe a media file's duration in milliseconds. */
+export function probeDurationMs(file: string): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("ffprobe", [
+      "-v",
+      "quiet",
+      "-print_format",
+      "json",
+      "-show_format",
+      file,
+    ]);
+    let out = "";
+    proc.stdout.on("data", (d) => (out += d.toString()));
+    proc.on("error", reject);
+    proc.on("close", (code) => {
+      if (code !== 0) return reject(new Error(`ffprobe exited ${code}`));
+      try {
+        const json = JSON.parse(out);
+        const sec = parseFloat(json.format?.duration ?? "0");
+        resolve(Math.round(sec * 1000));
+      } catch (e) {
+        reject(e);
+      }
+    });
+  });
+}

package/src/gif.ts

@@ -0,0 +1,65 @@
+import { promises as fs } from "node:fs";
+import { resolve, isAbsolute, dirname } from "node:path";
+import { Project } from "./project.js";
+import { runFfmpeg } from "./ffmpeg.js";
+import { ensureDir, exists, ok, step } from "./util.js";
+
+export interface GifOptions {
+  /** Output width in px (height keeps aspect). Default 960. */
+  width?: number;
+  /** GIF frame rate. Default 12. */
+  fps?: number;
+  /** Output path. Default <dir>/output/final-demo.gif. */
+  out?: string;
+}
+
+/**
+ * Convert the composed MP4 into a README-ready GIF (GIFs autoplay on GitHub;
+ * MP4s don't). Classic high-quality two-pass: palettegen → paletteuse, with
+ * ordered bayer dithering — flat UI colors stay clean instead of getting the
+ * error-diffusion "crawl". Both filters are baseline ffmpeg.
+ */
+export async function exportGif(
+  project: Project,
+  opts: GifOptions = {}
+): Promise<string> {
+  const input = project.outputPath;
+  if (!(await exists(input))) {
+    throw new Error(
+      `No final video at ${input} — run \`aidemo compose ${project.dir}\` first.`
+    );
+  }
+  const width = opts.width ?? 960;
+  const fps = opts.fps ?? 12;
+  const out = opts.out
+    ? isAbsolute(opts.out)
+      ? opts.out
+      : resolve(process.cwd(), opts.out)
+    : project.gifPath;
+  await ensureDir(dirname(out));
+
+  step(`Exporting GIF (${width}px @ ${fps}fps, two-pass palette)`);
+  const tmp = project.gifTmpDir;
+  await fs.rm(tmp, { recursive: true, force: true });
+  await ensureDir(tmp);
+  const palette = resolve(tmp, "palette.png");
+  const frames = `fps=${fps},scale=${width}:-1:flags=lanczos`;
+  await runFfmpeg(["-i", input, "-vf", `${frames},palettegen`, palette]);
+  await runFfmpeg([
+    "-i",
+    input,
+    "-i",
+    palette,
+    "-filter_complex",
+    `${frames}[x];[x][1:v]paletteuse=dither=bayer:bayer_scale=5`,
+    out,
+  ]);
+  // AIDEMO_KEEP_TMP=1 keeps .gif-tmp (palette) for debugging, like compose.
+  if (!process.env.AIDEMO_KEEP_TMP) {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+
+  const { size } = await fs.stat(out);
+  ok(`gif → ${out} (${(size / 1024 / 1024).toFixed(1)} MB)`);
+  return out;
+}

package/src/golden.ts

@@ -0,0 +1,109 @@
+import { promises as fs } from "node:fs";
+import type { Project } from "./project.js";
+import {
+  ProbeGoldenSchema,
+  type ProbeGolden,
+  type ProbeGoldenScene,
+  type Storyboard,
+} from "./types.js";
+import { writeJson, exists } from "./util.js";
+
+/**
+ * Golden probe/timeline diffing — a demo doubles as a regression test (vhs's
+ * golden-file pattern). `aidemo probe --update-golden` writes a NORMALIZED,
+ * deterministic projection of a probe run to golden/probe.json; `--golden`
+ * re-runs the probe, normalizes, and deep-compares. The projection is
+ * timing-free by construction (see ProbeActionOutcome — only op, resolved
+ * target, ok, found, and goto final URL), so it is stable across runs and a
+ * mismatch means a real change in the flow (a moved/renamed selector, a broken
+ * navigation), not clock jitter.
+ */
+
+/** Assemble the normalized golden from the storyboard + per-scene outcomes. */
+export function buildProbeGolden(
+  storyboard: Storyboard,
+  scenes: ProbeGoldenScene[]
+): ProbeGolden {
+  // Parse so the committed baseline and the freshly-built comparison are shaped
+  // identically (defaults applied, stray fields stripped) — the diff then only
+  // reflects genuine outcome drift.
+  return ProbeGoldenSchema.parse({
+    version: 1,
+    title: storyboard.title,
+    video: storyboard.video,
+    scenes,
+  });
+}
+
+export async function writeProbeGolden(
+  project: Project,
+  golden: ProbeGolden
+): Promise<void> {
+  await writeJson(project.goldenProbePath, golden);
+}
+
+/** Read + validate the committed baseline. Null when it doesn't exist yet. */
+export async function readProbeGolden(
+  project: Project
+): Promise<ProbeGolden | null> {
+  if (!(await exists(project.goldenProbePath))) return null;
+  const raw = JSON.parse(await fs.readFile(project.goldenProbePath, "utf8"));
+  return ProbeGoldenSchema.parse(raw);
+}
+
+/**
+ * A readable, field-level deep diff: each line is `path: expected X, got Y`
+ * (e.g. `$.scenes[2].actions[0].ok: expected true, got false`). Empty array =
+ * identical. Treats a missing key and an `undefined` value as equal so an
+ * omitted optional field never shows as a spurious diff.
+ */
+export function diffGolden(
+  expected: unknown,
+  actual: unknown,
+  path = "$"
+): string[] {
+  if (isScalar(expected) || isScalar(actual)) {
+    return valuesEqual(expected, actual)
+      ? []
+      : [`${path}: expected ${fmt(expected)}, got ${fmt(actual)}`];
+  }
+  const diffs: string[] = [];
+  if (Array.isArray(expected) || Array.isArray(actual)) {
+    const ea = Array.isArray(expected) ? expected : [];
+    const aa = Array.isArray(actual) ? actual : [];
+    if (ea.length !== aa.length) {
+      diffs.push(`${path}.length: expected ${ea.length}, got ${aa.length}`);
+    }
+    const n = Math.max(ea.length, aa.length);
+    for (let i = 0; i < n; i++) {
+      diffs.push(...diffGolden(ea[i], aa[i], `${path}[${i}]`));
+    }
+    return diffs;
+  }
+  const eo = (expected ?? {}) as Record<string, unknown>;
+  const ao = (actual ?? {}) as Record<string, unknown>;
+  const keys = [...new Set([...Object.keys(eo), ...Object.keys(ao)])].sort();
+  for (const k of keys) {
+    diffs.push(...diffGolden(eo[k], ao[k], `${path}.${k}`));
+  }
+  return diffs;
+}
+
+function isScalar(v: unknown): boolean {
+  return (
+    v == null ||
+    typeof v === "string" ||
+    typeof v === "number" ||
+    typeof v === "boolean"
+  );
+}
+
+function valuesEqual(a: unknown, b: unknown): boolean {
+  // Missing key vs explicit undefined/null read the same here.
+  if (a == null && b == null) return true;
+  return Object.is(a, b);
+}
+
+function fmt(v: unknown): string {
+  return v === undefined ? "(absent)" : JSON.stringify(v);
+}

package/src/i18n.ts

@@ -0,0 +1,86 @@
+import type { Card, Storyboard } from "./types.js";
+
+/**
+ * Multi-language renders from ONE take.
+ *
+ * The recorded take (raw video + timeline.json) is language-independent — it's
+ * a deterministic replay of the browser action-spec, which never mentions the
+ * spoken words. So a storyboard can carry translated narration (per scene) and
+ * translated card copy (intro/outro), and the engine can voice → caption →
+ * compose it once per language over the SAME footage. compose already stretches
+ * each scene's video to its own narration length, so a longer/shorter
+ * translation just retimes the shared take — no re-record.
+ *
+ * Translations are AUTHORED into the storyboard (scene `narrations`, card
+ * `i18n`); the engine never calls an LLM to translate. This keeps the capture
+ * loop — and the render pipeline — LLM-free.
+ */
+
+/**
+ * Every language code that appears in a storyboard's `narrations` / card `i18n`
+ * maps (the default `narration`/card copy is the implicit base language and is
+ * NOT listed). Order-stable, de-duplicated.
+ */
+export function storyboardLangs(sb: Storyboard): string[] {
+  const langs = new Set<string>();
+  for (const scene of sb.scenes)
+    for (const code of Object.keys(scene.narrations ?? {})) langs.add(code);
+  for (const card of [sb.intro, sb.outro])
+    for (const code of Object.keys(card?.i18n ?? {})) langs.add(code);
+  return [...langs];
+}
+
+/** Scene ids that have no translation for `lang` (fall back to the base narration). */
+export function missingNarrations(sb: Storyboard, lang: string): string[] {
+  return sb.scenes
+    .filter((s) => s.narrations?.[lang] == null)
+    .map((s) => s.id);
+}
+
+/** Apply a card's per-language title/subtitle override (untouched if none). */
+function localizeCard(card: Card | undefined, lang: string): Card | undefined {
+  if (!card) return card;
+  const override = card.i18n?.[lang];
+  if (!override) return card;
+  return {
+    ...card,
+    title: override.title ?? card.title,
+    subtitle: override.subtitle ?? card.subtitle,
+  };
+}
+
+/**
+ * A language-specific VIEW of the storyboard: each scene's `narration` becomes
+ * its `narrations[lang]` translation (falling back to the base narration where
+ * a scene isn't translated), and intro/outro cards pick up any `i18n` override.
+ * Everything else — actions, timing, voice/music/zoom — is identical, so the
+ * shared take composes unchanged. Pure and side-effect-free; the original
+ * storyboard is left intact.
+ */
+export function localizeStoryboard(sb: Storyboard, lang: string): Storyboard {
+  return {
+    ...sb,
+    intro: localizeCard(sb.intro, lang),
+    outro: localizeCard(sb.outro, lang),
+    scenes: sb.scenes.map((scene) => ({
+      ...scene,
+      narration: scene.narrations?.[lang] ?? scene.narration,
+    })),
+  };
+}
+
+/**
+ * The spoken language of a given render, for STT purposes (Whisper's
+ * `language` hint in src/captions.ts) — NOT the same lookup as
+ * `localizeStoryboard`'s translation selection. An active `--lang <code>`
+ * render wins (it names the translation being spoken); otherwise the
+ * storyboard's own optional `language` field describes the base narration
+ * (e.g. a monolingual non-English demo with no `narrations` translations at
+ * all). Undefined when neither is set — Whisper auto-detects.
+ */
+export function resolveNarrationLanguage(
+  sb: Storyboard | undefined,
+  lang?: string
+): string | undefined {
+  return lang ?? sb?.language;
+}