@a1knowhow/demo-maker 0.1.0

package/src/cli.ts

@@ -0,0 +1,226 @@
+/**
+ * CLI entry for `demo-maker run` / `demo-maker check`.
+ * Loads variables from --env-file if given; builds RunContext from env, runs scenario.
+ */
+
+import { basename, resolve } from "path";
+import {
+  loadScenario,
+  runScenario,
+  createDemoLogger,
+  type RunContext,
+} from "./index";
+import {
+  applyBaseUrlOverride,
+  buildRunVariables,
+  collectFlatPlaceholderKeys,
+  DEMO_BASE_URL_ENV_KEY,
+  loadEnvFile,
+} from "./env";
+import {
+  buildUrlCaptureHooks,
+  loadUrlCaptureRulesFile,
+  parseCaptureFromUrlArg,
+  type UrlCaptureRule,
+} from "./url-capture";
+
+/** Minimal delay overrides when --fast is used (quick tests, no video pacing). */
+const FAST_DELAYS = {
+  step_delay_ms: 0,
+  slow_mo_ms: 0,
+  typing_delay_ms: 0,
+  post_click_delay_ms: 0,
+  navigate_hold_ms: 100,
+  pre_action_delay_ms: 0,
+} as const;
+
+function parsePositiveInt(raw: string | undefined): number | undefined {
+  if (raw === undefined || raw === "") {
+    return undefined;
+  }
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+function parseCaptureFromUrlArgs(args: string[]): UrlCaptureRule[] {
+  const rules: UrlCaptureRule[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a.startsWith("--capture-from-url=")) {
+      rules.push(parseCaptureFromUrlArg(a.slice("--capture-from-url=".length)));
+      continue;
+    }
+    if (a === "--capture-from-url") {
+      const next = args[i + 1];
+      if (next && !next.startsWith("--")) {
+        rules.push(parseCaptureFromUrlArg(next));
+        i++;
+      }
+    }
+  }
+  return rules;
+}
+
+function parseUrlCaptureFile(args: string[]): string | undefined {
+  const eq = args.find((a) => a.startsWith("--url-capture-file="));
+  if (eq) return eq.slice("--url-capture-file=".length);
+  const idx = args.indexOf("--url-capture-file");
+  if (idx >= 0) {
+    const next = args[idx + 1];
+    if (next && !next.startsWith("--")) return next;
+  }
+  return undefined;
+}
+
+function parseArgs(argv: string[]) {
+  const args = argv.slice(2);
+  const positionals = args.filter((a) => !a.startsWith("--"));
+  const scenarioPath = positionals[0];
+  const baseUrl = args.find((a) => a.startsWith("--base-url="))?.slice("--base-url=".length);
+  const headless = args.includes("--headless");
+  const fast = args.includes("--fast");
+  const failFast = args.includes("--fail-fast");
+  const pauseAtEnd = args.includes("--pause-at-end");
+  const envFile =
+    args.find((a) => a.startsWith("--env-file="))?.slice("--env-file=".length) ?? positionals[1];
+  const storageState = args.find((a) => a.startsWith("--storage-state="))?.slice("--storage-state=".length);
+  const saveStorageState = args.find((a) => a.startsWith("--save-storage-state="))?.slice("--save-storage-state=".length);
+  const debugDir = args.find((a) => a.startsWith("--debug-dir="))?.slice("--debug-dir=".length);
+  const endStep =
+    parsePositiveInt(args.find((a) => a.startsWith("--end-step="))?.slice("--end-step=".length)) ??
+    (args.includes("--end-step") ? parsePositiveInt(args[args.indexOf("--end-step") + 1]) : undefined);
+  const captureFromUrl = parseCaptureFromUrlArgs(args);
+  const urlCaptureFile = parseUrlCaptureFile(args);
+  return {
+    scenarioPath,
+    baseUrl,
+    headless,
+    fast,
+    failFast,
+    pauseAtEnd,
+    envFile,
+    storageState,
+    saveStorageState,
+    debugDir,
+    endStep,
+    captureFromUrl,
+    urlCaptureFile,
+  };
+}
+
+export async function runMain(argv: string[] = process.argv): Promise<number> {
+  const logger = createDemoLogger("info");
+  const {
+    scenarioPath,
+    baseUrl,
+    headless,
+    fast,
+    failFast,
+    pauseAtEnd,
+    envFile,
+    storageState,
+    saveStorageState,
+    debugDir,
+    endStep,
+    captureFromUrl,
+    urlCaptureFile,
+  } = parseArgs(argv);
+
+  if (!scenarioPath) {
+    logger.error(
+      "Usage: demo-maker run <path-to-scenario.yaml> [env-file-path] [--base-url=URL] [--headless] [--fast] [--fail-fast] [--end-step=N] [--pause-at-end] [--debug-dir=path] [--env-file=path] [--storage-state=path] [--save-storage-state=path] [--capture-from-url VAR=regex] [--url-capture-file=path.json]"
+    );
+    return 1;
+  }
+
+  const resolvedPath = resolve(process.cwd(), scenarioPath);
+  let scenario;
+  try {
+    scenario = loadScenario(resolvedPath, { cwd: process.cwd() });
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    logger.error(`Failed to load scenario (${resolvedPath}):`, detail);
+    return 1;
+  }
+
+  const envFromFile = envFile ? loadEnvFile(envFile) : {};
+  applyBaseUrlOverride(scenario, { envFromFile, cliBaseUrl: baseUrl });
+  logger.info(`Base URL: ${scenario.base_url}`);
+  if (fast) {
+    Object.assign(scenario, FAST_DELAYS);
+    logger.info("Running in fast mode (minimal delays).");
+  }
+
+  if (failFast) {
+    logger.info("Fail-fast enabled (stop on first step failure).");
+  }
+  const emailEnv = scenario.auth?.email_env ?? "E2E_TEST_USER_EMAIL";
+  const passwordEnv = scenario.auth?.password_env ?? "E2E_TEST_USER_PASSWORD";
+  const email = envFromFile[emailEnv] ?? process.env[emailEnv];
+  const password = envFromFile[passwordEnv] ?? process.env[passwordEnv];
+
+  if (scenario.auth && (!email || !password)) {
+    logger.error(
+      `Missing credentials. Set ${emailEnv} and ${passwordEnv} (in env or via --env-file).`
+    );
+    return 1;
+  }
+
+  const allowFromProcess = [
+    emailEnv,
+    passwordEnv,
+    DEMO_BASE_URL_ENV_KEY,
+    ...collectFlatPlaceholderKeys(JSON.stringify(scenario)),
+  ];
+  const context: RunContext = {
+    auth: { email: email ?? "", password: password ?? "" },
+    variables: buildRunVariables({
+      envFromFile,
+      baseUrl: scenario.base_url,
+      allowFromProcess,
+    }),
+  };
+
+  let urlCaptureHooks;
+  try {
+    const fileRules = urlCaptureFile
+      ? loadUrlCaptureRulesFile(urlCaptureFile, process.cwd())
+      : [];
+    urlCaptureHooks = buildUrlCaptureHooks({
+      scenarioRules: scenario.url_capture,
+      cliRules: [...fileRules, ...captureFromUrl],
+    });
+  } catch (err) {
+    logger.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  const stepCount = endStep ? Math.min(endStep, scenario.steps.length) : scenario.steps.length;
+  logger.info(`Running scenario: ${scenario.name} (${stepCount}/${scenario.steps.length} steps)`);
+  const scenarioLabel = basename(resolvedPath, ".yaml");
+  const result = await runScenario(scenario, context, {
+    logger,
+    headless,
+    storageStatePath: storageState,
+    saveStorageStatePath: saveStorageState,
+    failFast,
+    endStep,
+    pauseAtEnd,
+    debugDir,
+    scenarioLabel,
+    urlCaptureHooks,
+  });
+
+  if (result.success) {
+    logger.info("Scenario completed successfully.");
+    if (result.videoPath) {
+      logger.info("Video saved:", result.videoPath);
+    }
+    if (result.timingPath) {
+      logger.info("Timing saved:", result.timingPath);
+    }
+    return 0;
+  }
+  logger.error("Scenario failed:", result.error);
+  return 1;
+}

package/src/env.ts

@@ -0,0 +1,112 @@
+/**
+ * Load .env-style files for auth and variables. Shared by run CLI and record CLI.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+
+/**
+ * Parse a .env-style file into key-value pairs. Supports KEY=VALUE, # comments, blank lines,
+ * and quoted values ("value" or 'value').
+ */
+export function loadEnvFile(filePath: string): Record<string, string> {
+  const resolved = resolve(process.cwd(), filePath);
+  if (!existsSync(resolved)) {
+    return {};
+  }
+  const content = readFileSync(resolved, "utf-8");
+  const result: Record<string, string> = {};
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) {
+      continue;
+    }
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1).replace(/\\(.)/g, "$1");
+    }
+    result[key] = value;
+  }
+  return result;
+}
+
+export const DEMO_BASE_URL_ENV_KEY = "BASE_URL";
+
+/** Single-segment `{{ NAME }}` placeholders (excludes nested paths like `auth.email`). */
+const FLAT_PLACEHOLDER_REGEX = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+
+/**
+ * Collect flat `{{ NAME }}` keys from text blobs (e.g. stringified scenario).
+ */
+export function collectFlatPlaceholderKeys(...texts: string[]): string[] {
+  const keys = new Set<string>();
+  for (const text of texts) {
+    FLAT_PLACEHOLDER_REGEX.lastIndex = 0;
+    for (const match of text.matchAll(FLAT_PLACEHOLDER_REGEX)) {
+      keys.add(match[1]!);
+    }
+  }
+  return [...keys];
+}
+
+/**
+ * Build template variables without copying the entire process environment.
+ * Includes: allowlisted process.env keys, --env-file entries (override), and BASE_URL.
+ */
+export function buildRunVariables(options: {
+  envFromFile: Record<string, string>;
+  baseUrl: string;
+  allowFromProcess: Iterable<string>;
+  processEnv?: Record<string, string | undefined>;
+}): Record<string, string> {
+  const processEnv = options.processEnv ?? process.env;
+  const fromProcess: Record<string, string> = {};
+  for (const key of options.allowFromProcess) {
+    const value = processEnv[key];
+    if (typeof value === "string") {
+      fromProcess[key] = value;
+    }
+  }
+  return {
+    ...fromProcess,
+    ...options.envFromFile,
+    BASE_URL: options.baseUrl,
+  };
+}
+
+/**
+ * Resolve demo base URL from env file (preferred) or process.env.
+ */
+export function resolveBaseUrlFromEnv(
+  envFromFile: Record<string, string>,
+  processEnv: Record<string, string | undefined> = process.env
+): string | undefined {
+  const fromFile = envFromFile[DEMO_BASE_URL_ENV_KEY]?.trim();
+  if (fromFile) {
+    return fromFile;
+  }
+  const fromProcess = processEnv[DEMO_BASE_URL_ENV_KEY]?.trim();
+  return fromProcess || undefined;
+}
+
+/**
+ * Override scenario.base_url from env file or CLI. CLI wins when set.
+ */
+export function applyBaseUrlOverride(
+  scenario: { base_url: string },
+  options: { envFromFile?: Record<string, string>; cliBaseUrl?: string }
+): void {
+  if (options.cliBaseUrl) {
+    scenario.base_url = options.cliBaseUrl;
+    return;
+  }
+  const resolved = resolveBaseUrlFromEnv(options.envFromFile ?? {});
+  if (resolved) {
+    scenario.base_url = resolved;
+  }
+}

package/src/export-chapters.ts

@@ -0,0 +1,99 @@
+/**
+ * Emit YouTube chapter timestamps from a demo-maker timing.json file.
+ *
+ * Usage:
+ *   npx tsx demo-maker/export-chapters.ts path/to/video.timing.json
+ *   npx tsx demo-maker/export-chapters.ts output/videos   # uses newest *.timing.json in dir
+ */
+
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join, resolve } from "path";
+import type { TimingExport } from "./types";
+
+function formatChapterTime(sec: number): string {
+  const total = Math.max(0, Math.floor(sec));
+  const m = Math.floor(total / 60);
+  const s = total % 60;
+  return `${m}:${String(s).padStart(2, "0")}`;
+}
+
+function chapterLabel(step: TimingExport["steps"][number]): string | undefined {
+  if (step.caption?.trim()) {
+    return step.caption.trim();
+  }
+  const msg = step.message?.trim() ?? "";
+  if (/pre-video/i.test(msg)) {
+    return undefined;
+  }
+  const scene = msg.match(/──\s*Scene\s*\d+:\s*(.+)/i);
+  if (scene?.[1]) {
+    return scene[1].trim();
+  }
+  if (msg.startsWith("──")) {
+    return msg.replace(/^──\s*/, "").trim();
+  }
+  return undefined;
+}
+
+export function formatYouTubeChapters(timing: TimingExport): string {
+  const lines: string[] = [];
+  const seen = new Set<number>();
+
+  for (const step of timing.steps) {
+    if (step.excluded) continue;
+    const label = chapterLabel(step);
+    if (!label) continue;
+    const at = Math.floor(step.startSec);
+    if (seen.has(at)) continue;
+    seen.add(at);
+    lines.push(`${formatChapterTime(step.startSec)} ${label}`);
+  }
+
+  if (lines.length === 0) {
+    return "# No chapter markers found (add caption: or Scene log messages on key steps)";
+  }
+  return lines.join("\n");
+}
+
+function findNewestTimingInDir(dir: string): string | undefined {
+  const files = readdirSync(dir)
+    .filter((f) => f.endsWith(".timing.json"))
+    .map((f) => join(dir, f));
+  if (files.length === 0) return undefined;
+  files.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+  return files[0];
+}
+
+export function exportChaptersMain(argv: string[] = process.argv): number {
+  const arg = argv[2];
+  if (!arg) {
+    console.error("Usage: npx tsx demo-maker/export-chapters.ts <timing.json | directory>");
+    return 1;
+  }
+
+  const resolved = resolve(process.cwd(), arg);
+  let timingPath = resolved;
+  try {
+    const st = statSync(resolved);
+    if (st.isDirectory()) {
+      const found = findNewestTimingInDir(resolved);
+      if (!found) {
+        console.error(`No *.timing.json files in ${resolved}`);
+        return 1;
+      }
+      timingPath = found;
+    }
+  } catch {
+    console.error(`Path not found: ${resolved}`);
+    return 1;
+  }
+
+  const raw = readFileSync(timingPath, "utf8");
+  const timing = JSON.parse(raw) as TimingExport;
+  console.log(`# ${timing.scenarioName} (${timing.durationSec}s)`);
+  console.log(`# source: ${timingPath}`);
+  console.log("");
+  console.log(formatYouTubeChapters(timing));
+  return 0;
+}
+

package/src/ffmpeg.ts

@@ -0,0 +1,168 @@
+/**
+ * ffmpeg helpers for demo-maker video post-processing (splice excluded ranges).
+ */
+
+import { spawnSync } from "child_process";
+
+export interface TimeRangeSec {
+  startSec: number;
+  endSec: number;
+}
+
+export interface KeepSegment {
+  startSec: number;
+  endSec: number;
+}
+
+/** Sort and merge overlapping exclude ranges. */
+export function normalizeExcludeRanges(ranges: TimeRangeSec[]): TimeRangeSec[] {
+  if (ranges.length === 0) {
+    return [];
+  }
+  const sorted = [...ranges]
+    .map((r) => ({
+      startSec: Math.max(0, r.startSec),
+      endSec: Math.max(r.startSec, r.endSec),
+    }))
+    .sort((a, b) => a.startSec - b.startSec);
+
+  const merged: TimeRangeSec[] = [];
+  for (const r of sorted) {
+    const last = merged[merged.length - 1];
+    if (last && r.startSec <= last.endSec) {
+      last.endSec = Math.max(last.endSec, r.endSec);
+    } else {
+      merged.push({ ...r });
+    }
+  }
+  return merged;
+}
+
+/** Build keep-segments from full duration and exclude ranges. */
+export function buildKeepSegments(durationSec: number, excludeRanges: TimeRangeSec[]): KeepSegment[] {
+  const excludes = normalizeExcludeRanges(excludeRanges);
+  const keeps: KeepSegment[] = [];
+  let cursor = 0;
+
+  for (const ex of excludes) {
+    if (ex.startSec > cursor + 0.01) {
+      keeps.push({ startSec: cursor, endSec: ex.startSec });
+    }
+    cursor = Math.max(cursor, ex.endSec);
+  }
+
+  if (cursor < durationSec - 0.01) {
+    keeps.push({ startSec: cursor, endSec: durationSec });
+  }
+
+  return keeps.filter((k) => k.endSec > k.startSec + 0.01);
+}
+
+/** Map a timestamp on the original timeline to the spliced timeline. */
+export function remapTimelineSec(tSec: number, excludeRanges: TimeRangeSec[]): number {
+  const excludes = normalizeExcludeRanges(excludeRanges);
+  let removed = 0;
+  for (const ex of excludes) {
+    if (tSec <= ex.startSec) {
+      break;
+    }
+    if (tSec >= ex.endSec) {
+      removed += ex.endSec - ex.startSec;
+    } else {
+      removed += tSec - ex.startSec;
+      break;
+    }
+  }
+  return Math.max(0, tSec - removed);
+}
+
+export interface SpliceResult {
+  ok: boolean;
+  stderr?: string;
+  removedSec?: number;
+}
+
+/**
+ * Remove exclude ranges from a video file using ffmpeg trim+concat.
+ * Re-encodes video (required for mid-stream cuts). No audio track is expected on Playwright webm.
+ */
+export function spliceVideoExcludingRanges(
+  inputPath: string,
+  outputPath: string,
+  durationSec: number,
+  excludeRanges: TimeRangeSec[]
+): SpliceResult {
+  const excludes = normalizeExcludeRanges(excludeRanges);
+  if (excludes.length === 0) {
+    return { ok: true, removedSec: 0 };
+  }
+
+  const keeps = buildKeepSegments(durationSec, excludes);
+  if (keeps.length === 0) {
+    return { ok: false, stderr: "splice would remove entire video" };
+  }
+
+  const removedSec = excludes.reduce((sum, r) => sum + (r.endSec - r.startSec), 0);
+
+  if (keeps.length === 1 && excludes.length === 1 && keeps[0]!.startSec === 0 && keeps[0]!.endSec >= durationSec - removedSec - 0.05) {
+    // Single leading or trailing keep only — use simple trim
+    const k = keeps[0]!;
+    const ff = spawnSync(
+      "ffmpeg",
+      [
+        "-y",
+        "-i",
+        inputPath,
+        "-ss",
+        String(k.startSec),
+        "-to",
+        String(k.endSec),
+        "-c:v",
+        "libvpx-vp9",
+        "-b:v",
+        "2M",
+        outputPath,
+      ],
+      { encoding: "utf8" }
+    );
+    if (ff.status === 0) {
+      return { ok: true, removedSec };
+    }
+    return { ok: false, stderr: ff.stderr?.slice(-800) ?? String(ff.error) };
+  }
+
+  const filterParts: string[] = [];
+  const labels: string[] = [];
+  for (let i = 0; i < keeps.length; i++) {
+    const k = keeps[i]!;
+    filterParts.push(
+      `[0:v]trim=start=${k.startSec}:end=${k.endSec},setpts=PTS-STARTPTS[v${i}]`
+    );
+    labels.push(`[v${i}]`);
+  }
+  filterParts.push(`${labels.join("")}concat=n=${keeps.length}:v=1:a=0[outv]`);
+
+  const ff = spawnSync(
+    "ffmpeg",
+    [
+      "-y",
+      "-i",
+      inputPath,
+      "-filter_complex",
+      filterParts.join(";"),
+      "-map",
+      "[outv]",
+      "-c:v",
+      "libvpx-vp9",
+      "-b:v",
+      "2M",
+      outputPath,
+    ],
+    { encoding: "utf8" }
+  );
+
+  if (ff.status === 0) {
+    return { ok: true, removedSec };
+  }
+  return { ok: false, stderr: ff.stderr?.slice(-800) ?? String(ff.error) };
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Entry point for CLI and local scripts. Exports parseScenario, loadScenario, runScenario, createDemoLogger, resolveVariables, and types.
+ */
+
+export type {
+  ActionType,
+  AuthConfig,
+  CaptionStyle,
+  DemoScenario,
+  DemoStep,
+  IDemoLogger,
+  IDemoRunner,
+  IScenarioParser,
+  Locator,
+  ParsedScenario,
+  RunContext,
+  RunResult,
+  StepImport,
+  StepOrImport,
+  StepResult,
+  TimingExport,
+  TimingStepEntry,
+  VideoConfig,
+} from "./types";
+export {
+  createDemoLogger,
+  formatLocalTimeHHMMSS,
+  formatStepFailedLogLine,
+  formatStepProgressLogLine,
+} from "./logger";
+export type { StepProgressLogParts } from "./logger";
+export { loadScenario } from "./load";
+export type { LoadScenarioOptions } from "./load";
+export { resolveVariables, defaultVariableResolver } from "./variables";
+export type { IVariableResolver } from "./variables";
+export { parseScenario, type ParseScenarioOptions } from "./parse";
+export { runScenario, runScenarioOnExistingPage, sliceScenarioByEndStep } from "./runner";
+export { formatYouTubeChapters } from "./export-chapters";
+export type {
+  RunScenarioOnPageOptions,
+  RunScenarioOnPageResult,
+  RunScenarioOptions,
+} from "./runner";
+
+export {
+  applyUrlCapture,
+  buildUrlCaptureHooks,
+  createRegexUrlCapture,
+  loadUrlCaptureRulesFile,
+  parseCaptureFromUrlArg,
+} from "./url-capture";
+export type { UrlCaptureHook } from "./url-capture";
+export type { UrlCaptureRule } from "./types";
+