demo-dev 0.0.1-alpha.0

package/src/lib/git.ts

@@ -0,0 +1,59 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { DiffContext } from "../types.js";
+
+const execFileAsync = promisify(execFile);
+
+const runGit = async (args: string[]) => {
+  const { stdout } = await execFileAsync("git", args, { maxBuffer: 1024 * 1024 * 10 });
+  return stdout.trim();
+};
+
+const resolveRange = async (baseRef: string) => {
+  try {
+    await runGit(["rev-parse", "--verify", baseRef]);
+    return `${baseRef}...HEAD`;
+  } catch {
+    try {
+      await runGit(["rev-parse", "--verify", "HEAD~1"]);
+      return "HEAD~1...HEAD";
+    } catch {
+      return undefined;
+    }
+  }
+};
+
+export const getCurrentBranch = async () => {
+  return runGit(["rev-parse", "--abbrev-ref", "HEAD"]);
+};
+
+export const getChangedFiles = async (baseRef: string) => {
+  const range = await resolveRange(baseRef);
+  const output = range
+    ? await runGit(["diff", "--name-only", range])
+    : await runGit(["status", "--porcelain"]);
+
+  return output
+    .split("\n")
+    .map((line) => (range ? line : line.slice(3)).trim())
+    .filter(Boolean);
+};
+
+export const getDiffPreview = async (baseRef: string, maxChars = 12000) => {
+  const range = await resolveRange(baseRef);
+  const diff = range ? await runGit(["diff", "--no-color", range]) : await runGit(["diff", "--no-color"]);
+  return diff.length > maxChars ? `${diff.slice(0, maxChars)}\n... (truncated)` : diff;
+};
+
+export const buildDiffContext = async (baseRef: string): Promise<DiffContext> => {
+  const currentBranch = await getCurrentBranch();
+  const changedFiles = await getChangedFiles(baseRef);
+  const diffPreview = await getDiffPreview(baseRef);
+
+  return {
+    currentBranch,
+    baseRef,
+    changedFiles,
+    diffPreview,
+  };
+};

package/src/lib/media.ts

@@ -0,0 +1,23 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export const getMediaDurationMs = async (path: string): Promise<number | undefined> => {
+  try {
+    const { stdout } = await execFileAsync("ffprobe", [
+      "-v",
+      "error",
+      "-show_entries",
+      "format=duration",
+      "-of",
+      "default=noprint_wrappers=1:nokey=1",
+      path,
+    ]);
+    const seconds = Number(stdout.trim());
+    if (!Number.isFinite(seconds) || seconds <= 0) return undefined;
+    return Math.round(seconds * 1000);
+  } catch {
+    return undefined;
+  }
+};

package/src/orchestrate.ts

@@ -0,0 +1,166 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { buildDiffContext } from "./lib/git.js";
+import { writeJson } from "./lib/fs.js";
+import type { DemoPlan } from "./types.js";
+import { buildDemoPlan } from "./planner/index.js";
+import { refineDemoPlan } from "./planner/refine.js";
+import { probePlanScenes } from "./probe/page-probe.js";
+import { capturePlanContinuous } from "./capture/continuous-capture.js";
+import { buildVoiceScript } from "./voice/script.js";
+import { synthesizeVoice } from "./voice/tts.js";
+import { buildVisualPlan } from "./render/visual-plan.js";
+import { composeVideo } from "./render/ffmpeg-compose.js";
+import { polishPresentationCopy } from "./presentation/polish.js";
+import { buildPromptPlan } from "./planner/prompt.js";
+import type { ProjectConfig } from "./config/project.js";
+
+export interface RunPipelineOptions {
+  baseRef: string;
+  baseUrl: string;
+  outputDir: string;
+  projectConfig?: ProjectConfig;
+  renderVideo?: boolean;
+  /** When set, skip diff-based planning and use prompt-driven planning instead. */
+  prompt?: string;
+  /** Video quality: "draft", "standard", "high". */
+  quality?: "draft" | "standard" | "high";
+  /** Wrap video in a browser frame with gradient background. */
+  frame?: boolean;
+}
+
+export const buildExecutablePlan = async (options: {
+  baseRef: string;
+  baseUrl: string;
+  outputDir: string;
+  projectConfig?: ProjectConfig;
+}) => {
+  const context = await buildDiffContext(options.baseRef);
+  await writeJson(join(options.outputDir, "demo-context.json"), context);
+
+  const initialPlan = await buildDemoPlan(context, options.projectConfig);
+  await writeJson(join(options.outputDir, "demo-plan.initial.json"), initialPlan);
+
+  const probes = await probePlanScenes(initialPlan, {
+    baseUrl: options.baseUrl,
+    outputDir: options.outputDir,
+  });
+  await writeJson(join(options.outputDir, "page-probes.json"), probes);
+
+  const refinedPlan = await refineDemoPlan({ initialPlan, probes });
+  await writeJson(join(options.outputDir, "demo-plan.json"), refinedPlan);
+
+  return { context, initialPlan, probes, plan: refinedPlan };
+};
+
+export const runPipelineFromPrompt = async (options: {
+  prompt: string;
+  baseUrl: string;
+  outputDir: string;
+  projectConfig?: ProjectConfig;
+  renderVideo?: boolean;
+  quality?: "draft" | "standard" | "high";
+  frame?: boolean;
+}) => {
+  await mkdir(options.outputDir, { recursive: true });
+
+  const plan = await buildPromptPlan({
+    prompt: options.prompt,
+    baseUrl: options.baseUrl,
+    outputDir: options.outputDir,
+    projectConfig: options.projectConfig,
+  });
+  await writeJson(join(options.outputDir, "demo-plan.json"), plan);
+
+  return runPipelineWithPlan({ plan, baseUrl: options.baseUrl, outputDir: options.outputDir, renderVideo: options.renderVideo, quality: options.quality, frame: options.frame });
+};
+
+export const runPipeline = async ({
+  baseRef,
+  baseUrl,
+  outputDir,
+  projectConfig,
+  renderVideo = true,
+  prompt,
+  quality,
+  frame,
+}: RunPipelineOptions) => {
+  await mkdir(outputDir, { recursive: true });
+
+  if (prompt) {
+    return runPipelineFromPrompt({ prompt, baseUrl, outputDir, projectConfig, renderVideo, quality, frame });
+  }
+
+  const { context, initialPlan, probes, plan } = await buildExecutablePlan({
+    baseRef,
+    baseUrl,
+    outputDir,
+    projectConfig,
+  });
+
+  return runPipelineWithPlan({ plan, baseUrl, outputDir, renderVideo, quality, frame });
+};
+
+const runPipelineWithPlan = async (options: {
+  plan: DemoPlan;
+  baseUrl: string;
+  outputDir: string;
+  renderVideo?: boolean;
+  quality?: "draft" | "standard" | "high";
+  frame?: boolean;
+}) => {
+  const { plan, baseUrl, outputDir, renderVideo = true } = options;
+
+  const captureResult = await capturePlanContinuous(plan, {
+    baseUrl,
+    outputDir: join(outputDir, "captures"),
+  });
+  await writeJson(join(outputDir, "continuous-capture.json"), {
+    videoPath: captureResult.videoPath,
+    sceneMarkers: captureResult.sceneMarkers,
+    interactions: captureResult.interactions,
+    totalDurationMs: captureResult.totalDurationMs,
+    viewport: captureResult.viewport,
+    cursorSamples: captureResult.cursorLog.length,
+  });
+
+  const visualPlan = buildVisualPlan(captureResult);
+  await writeJson(join(outputDir, "visual-plan.json"), visualPlan);
+
+  const polishedPlan = await polishPresentationCopy(plan);
+  const voiceScript = buildVoiceScript(polishedPlan);
+  const voicedLines = await synthesizeVoice(voiceScript, {
+    outputDir: join(outputDir, "audio"),
+  });
+  await writeJson(join(outputDir, "voice-script.json"), voicedLines);
+
+  const bgmPath = process.env.DEMO_BGM_PATH;
+  const bgmVolume = process.env.DEMO_BGM_VOLUME
+    ? Number(process.env.DEMO_BGM_VOLUME)
+    : undefined;
+
+  const videoPath = renderVideo
+    ? await composeVideo({
+        videoPath: captureResult.videoPath,
+        outputPath: join(outputDir, "pr-demo.mp4"),
+        visualPlan,
+        capture: captureResult,
+        voiceLines: voicedLines,
+        bgm: bgmPath ? { path: bgmPath, volume: bgmVolume } : undefined,
+        title: plan.title,
+        width: captureResult.viewport.width,
+        height: captureResult.viewport.height,
+        quality: options.quality,
+        frame: options.frame || undefined,
+      }).catch((error) => {
+        console.warn("FFmpeg composition failed:", error);
+        return undefined;
+      })
+    : undefined;
+
+  return {
+    plan: polishedPlan,
+    voiceScript: voicedLines,
+    videoPath,
+  };
+};

package/src/planner/heuristic.ts

@@ -0,0 +1,180 @@
+import type { ProjectConfig } from "../config/project.js";
+import type { DemoPlan, DemoScene, DiffContext } from "../types.js";
+
+const DEFAULT_VIEWPORT = { width: 1440, height: 900 };
+
+const isUserFacingFile = (file: string) => {
+  const normalized = file.replaceAll("\\", "/").toLowerCase();
+  if (normalized.startsWith(".")) return false;
+  if (/package(-lock)?\.json$/.test(normalized)) return false;
+  if (/readme\.md$/.test(normalized)) return false;
+  if (/^(src\/)?(lib|utils|server|scripts)\//.test(normalized)) return false;
+  return /(^app\/|^pages\/|^src\/app\/|^src\/pages\/|component|route|screen|view|layout)/.test(normalized);
+};
+
+const normalizeRoute = (route: string) => {
+  if (!route.startsWith("/")) return `/${route}`.replace(/\/+/g, "/");
+  return route.replace(/\/+/g, "/");
+};
+
+const routeFromFile = (file: string, projectConfig?: ProjectConfig) => {
+  const normalized = file.replaceAll("\\", "/");
+  const routeLike = normalized
+    .replace(/^src\//, "")
+    .replace(/^app\//, "")
+    .replace(/^pages\//, "")
+    .replace(/\/page\.(tsx|ts|jsx|js)$/, "")
+    .replace(/\.(tsx|ts|jsx|js|mdx)$/, "")
+    .replace(/\/index$/, "");
+
+  if (!routeLike || routeLike.startsWith("components/") || routeLike.startsWith("lib/")) {
+    return "/";
+  }
+
+  const inferredRoute = normalizeRoute(routeLike);
+  const hintedRoute = projectConfig?.preferredRoutes?.find((route) => inferredRoute.startsWith(normalizeRoute(route)));
+  return hintedRoute ?? inferredRoute;
+};
+
+const classifyScene = (file: string) => {
+  const lower = file.toLowerCase();
+
+  if (/(login|signin|auth)/.test(lower)) {
+    return {
+      title: "Authentication flow",
+      goal: "Show the user-facing authentication changes introduced by this PR.",
+      narration: "This update tightens the authentication experience so users can get into the product faster.",
+    };
+  }
+
+  if (/(signup|register|onboarding)/.test(lower)) {
+    return {
+      title: "First-run onboarding",
+      goal: "Show how the first-run user journey has improved.",
+      narration: "This scene focuses on a smoother first-run experience.",
+    };
+  }
+
+  if (/(dashboard|home|overview)/.test(lower)) {
+    return {
+      title: "Core workspace",
+      goal: "Show the main workspace where users feel the biggest product changes.",
+      narration: "This scene highlights the most visible product changes in the core workspace.",
+    };
+  }
+
+  if (/(settings|profile|account)/.test(lower)) {
+    return {
+      title: "Settings and personalization",
+      goal: "Show how configuration and account flows have improved.",
+      narration: "This section emphasizes clearer, more controllable settings.",
+    };
+  }
+
+  if (/(search|discover|explore)/.test(lower)) {
+    return {
+      title: "Search and discovery",
+      goal: "Show the updated discovery path for users.",
+      narration: "This scene focuses on how search and discovery feel better in the updated product.",
+    };
+  }
+
+  return {
+    title: "Feature overview",
+    goal: "Show the visible product changes introduced by this PR.",
+    narration: "This segment quickly summarizes the feature update.",
+  };
+};
+
+const dedupeByUrl = (scenes: DemoScene[]) => {
+  const seen = new Set<string>();
+  return scenes.filter((scene) => {
+    if (seen.has(scene.url)) return false;
+    seen.add(scene.url);
+    return true;
+  });
+};
+
+const buildSceneFromRoute = (route: string, index: number, hint?: string): DemoScene => ({
+  id: `scene-${String(index + 1).padStart(2, "0")}`,
+  title: hint ? `${hint} walkthrough` : "Feature walkthrough",
+  goal: hint ? `Show the ${hint} experience in the product.` : "Show a meaningful product surface from this PR.",
+  url: normalizeRoute(route),
+  viewport: DEFAULT_VIEWPORT,
+  actions: [
+    { type: "navigate", url: normalizeRoute(route) },
+    { type: "wait", ms: 1200 },
+    { type: "scroll", y: 320 },
+    { type: "wait", ms: 400 },
+  ],
+  narration: hint
+    ? `This scene highlights ${hint} inside the product.`
+    : "This scene captures a key product surface from the updated app.",
+  caption: hint ? `${hint} · ${normalizeRoute(route)}` : `Feature walkthrough · ${normalizeRoute(route)}`,
+  durationMs: 4200,
+  evidenceHints: hint ? [hint] : [],
+});
+
+export const buildHeuristicPlan = (context: DiffContext, projectConfig?: ProjectConfig): DemoPlan => {
+  const candidateFiles = context.changedFiles.filter(isUserFacingFile);
+
+  const scenes = dedupeByUrl(
+    candidateFiles.slice(0, 5).map((file, index) => {
+      const classification = classifyScene(file);
+      const url = routeFromFile(file, projectConfig);
+
+      return {
+        id: `scene-${String(index + 1).padStart(2, "0")}`,
+        title: classification.title,
+        goal: classification.goal,
+        url,
+        viewport: DEFAULT_VIEWPORT,
+        actions: [
+          { type: "navigate", url },
+          { type: "wait", ms: 1200 },
+          { type: "scroll", y: 420 },
+          { type: "wait", ms: 500 },
+        ],
+        narration: classification.narration,
+        caption: `${classification.title} · ${url}`,
+        durationMs: 4500,
+        evidenceHints: [file],
+      } satisfies DemoScene;
+    }),
+  );
+
+  const hintedScenes = scenes.length === 0
+    ? (projectConfig?.preferredRoutes ?? []).slice(0, 4).map((route, index) => buildSceneFromRoute(route, index, projectConfig?.featureHints?.[index]))
+    : scenes;
+
+  return {
+    title: `PR Demo · ${context.currentBranch}`,
+    summary:
+      hintedScenes.length > 0
+        ? `Generated a demo plan from ${hintedScenes.length} user-facing route${hintedScenes.length === 1 ? "" : "s"}.`
+        : "Could not infer a specific route from the diff, so the plan falls back to the home page.",
+    branch: context.currentBranch,
+    generatedAt: new Date().toISOString(),
+    scenes:
+      hintedScenes.length > 0
+        ? hintedScenes
+        : [
+            {
+              id: "scene-01",
+              title: "Home overview",
+              goal: "Capture the home surface when no stronger route signal is available.",
+              url: "/",
+              viewport: DEFAULT_VIEWPORT,
+              actions: [
+                { type: "navigate", url: "/" },
+                { type: "wait", ms: 1200 },
+                { type: "scroll", y: 300 },
+              ],
+              narration: "The diff does not expose a clear product route, so the demo starts from the home surface.",
+              caption: "Home overview",
+              durationMs: 4000,
+              evidenceHints: context.changedFiles,
+            },
+          ],
+  };
+};

package/src/planner/index.ts

@@ -0,0 +1,26 @@
+import type { ProjectConfig } from "../config/project.js";
+import type { DemoPlan, DiffContext } from "../types.js";
+import { buildHeuristicPlan } from "./heuristic.js";
+import { buildLlmPlan } from "./llm.js";
+
+const allowHeuristicFallback = process.env.DEMO_AI_MANDATORY === "false";
+
+export const buildDemoPlan = async (context: DiffContext, projectConfig?: ProjectConfig): Promise<DemoPlan> => {
+  try {
+    const llmPlan = await buildLlmPlan(context, projectConfig);
+    if (llmPlan) {
+      return llmPlan;
+    }
+  } catch (error) {
+    if (!allowHeuristicFallback) {
+      throw error;
+    }
+    console.warn("LLM planner failed, falling back to the heuristic planner", error);
+  }
+
+  if (!allowHeuristicFallback) {
+    throw new Error("AI provider did not return a plan. Set DEMO_AI_MANDATORY=false to allow heuristic fallback.");
+  }
+
+  return buildHeuristicPlan(context, projectConfig);
+};

package/src/planner/llm.ts

@@ -0,0 +1,85 @@
+import type { ProjectConfig } from "../config/project.js";
+import { summarizeProjectHints } from "../config/project.js";
+import type { DemoPlan, DiffContext } from "../types.js";
+import { requestAiJson } from "../ai/provider.js";
+import { demoPlanSchema } from "./schema.js";
+
+const buildPlannerPrompt = (context: DiffContext, projectConfig?: ProjectConfig) => {
+  return [
+    "You are a product demo director, not a QA engineer.",
+    "Goal: turn a git diff into a concise, recordable, voice-friendly demo plan.",
+    "Requirements:",
+    "1. Pick only 2-4 scenes that best represent visible user-facing changes.",
+    "2. Keep actions stable and executable. Prefer navigate / click / fill / waitForText / waitForUrl / scroll.",
+    "3. If the diff does not reveal specific elements, do not invent complex actions. Fall back to page-level presentation.",
+    "4. narration should sound like product storytelling, not a test report.",
+    "5. Output strict JSON only, with no markdown explanation.",
+    "6. All URLs must be in-app relative paths such as /dashboard.",
+    "7. Keep captions short enough for on-screen usage.",
+    "8. Keep durationMs between 3000 and 8000.",
+    "9. Prefer routes and feature surfaces hinted by the project config when relevant.",
+    "",
+    "Supported target examples:",
+    JSON.stringify(
+      {
+        strategy: "role",
+        role: "button",
+        name: "Sign in",
+      },
+      null,
+      2,
+    ),
+    JSON.stringify(
+      {
+        strategy: "label",
+        value: "Email",
+      },
+      null,
+      2,
+    ),
+    JSON.stringify(
+      {
+        strategy: "text",
+        value: "Welcome",
+      },
+      null,
+      2,
+    ),
+    "",
+    "Project hints:",
+    JSON.stringify(summarizeProjectHints(projectConfig ?? {}), null, 2),
+    "",
+    "Plan from the following context:",
+    JSON.stringify(
+      {
+        branch: context.currentBranch,
+        baseRef: context.baseRef,
+        changedFiles: context.changedFiles.slice(0, 20),
+        diffPreview: context.diffPreview,
+      },
+      null,
+      2,
+    ),
+  ].join("\n");
+};
+
+export const buildLlmPlan = async (context: DiffContext, projectConfig?: ProjectConfig): Promise<DemoPlan | null> => {
+  const normalized = await requestAiJson({
+    system: "You create concise, production-ready demo plans for product videos. Output strict JSON only.",
+    prompt: buildPlannerPrompt(context, projectConfig),
+    schema: demoPlanSchema,
+    temperature: 0.4,
+  });
+
+  if (!normalized) return null;
+
+  return {
+    ...normalized,
+    branch: context.currentBranch,
+    generatedAt: new Date().toISOString(),
+    scenes: normalized.scenes.map((scene) => ({
+      ...scene,
+      evidenceHints: scene.evidenceHints ?? [],
+    })),
+  };
+};

package/src/planner/openai.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+
+const responseSchema = z.object({
+  choices: z
+    .array(
+      z.object({
+        message: z.object({
+          content: z.string().nullable().optional(),
+        }),
+      }),
+    )
+    .min(1),
+});
+
+export const getPlannerConfig = () => {
+  const apiKey = process.env.DEMO_OPENAI_API_KEY;
+  const baseUrl = process.env.DEMO_OPENAI_BASE_URL ?? "https://api.openai.com/v1";
+  const model = process.env.DEMO_OPENAI_MODEL ?? "gpt-4.1-mini";
+  return { apiKey, baseUrl, model };
+};
+
+const extractJson = (text: string) => {
+  const fenced = text.match(/```json\s*([\s\S]*?)```/i)?.[1];
+  if (fenced) return fenced.trim();
+
+  const firstBrace = text.indexOf("{");
+  const lastBrace = text.lastIndexOf("}");
+  if (firstBrace !== -1 && lastBrace !== -1 && lastBrace > firstBrace) {
+    return text.slice(firstBrace, lastBrace + 1);
+  }
+
+  return text;
+};
+
+export const requestPlannerJson = async <T>(options: {
+  system: string;
+  prompt: string;
+  schema: z.ZodType<T>;
+  temperature?: number;
+}) => {
+  const config = getPlannerConfig();
+  if (!config.apiKey) return null;
+
+  const response = await fetch(`${config.baseUrl}/chat/completions`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${config.apiKey}`,
+    },
+    body: JSON.stringify({
+      model: config.model,
+      temperature: options.temperature ?? 0.4,
+      response_format: { type: "json_object" },
+      messages: [
+        {
+          role: "system",
+          content: options.system,
+        },
+        {
+          role: "user",
+          content: options.prompt,
+        },
+      ],
+    }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`planner request failed: ${response.status} ${errorText}`);
+  }
+
+  const payload = responseSchema.parse(await response.json());
+  const content = payload.choices[0]?.message.content;
+  if (!content) return null;
+
+  return options.schema.parse(JSON.parse(extractJson(content)));
+};