@a1knowhow/demo-maker 0.1.0

package/src/load.ts

@@ -0,0 +1,143 @@
+/**
+ * Load scenario from file with import expansion: resolves top-level imports and
+ * step-level import directives, flattens to a single steps array, detects circular imports.
+ */
+
+import { readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import type { DemoScenario, DemoStep, ParsedScenario, StepOrImport } from "./types";
+import { parseScenario } from "./parse";
+
+export interface LoadScenarioOptions {
+  /** Working directory for resolving the entry path. Default process.cwd(). */
+  cwd?: string;
+  /** Custom file reader (e.g. for tests). Default readFileSync. */
+  readFile?: (absolutePath: string) => string;
+}
+
+function isStepImport(s: StepOrImport): s is { import: string } {
+  return typeof s === "object" && s !== null && "import" in s && typeof (s as { import: string }).import === "string";
+}
+
+/**
+ * Load and expand a scenario from a file path. Resolves imports relative to each file's directory.
+ * Returns a DemoScenario with flattened steps (no import directives). Throws on circular import.
+ */
+export function loadScenario(
+  entryPath: string,
+  options: LoadScenarioOptions = {},
+  visited: Set<string> = new Set()
+): DemoScenario {
+  const cwd = options.cwd ?? process.cwd();
+  const readFile = options.readFile ?? ((path: string) => readFileSync(path, "utf-8"));
+  const absolutePath = resolve(cwd, entryPath);
+
+  if (visited.has(absolutePath)) {
+    throw new Error(`Circular import: ${absolutePath}`);
+  }
+  visited.add(absolutePath);
+
+  let content: string;
+  try {
+    content = readFile(absolutePath);
+  } catch (err) {
+    visited.delete(absolutePath);
+    throw new Error(
+      `Failed to read scenario file ${absolutePath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+
+  let parsed: ParsedScenario;
+  try {
+    parsed = parseScenario(content, { sourceFile: absolutePath });
+  } catch (err) {
+    visited.delete(absolutePath);
+    throw err;
+  }
+
+  const baseDir = dirname(absolutePath);
+  const effectiveSteps: DemoStep[] = [];
+
+  if (parsed.imports && parsed.imports.length > 0) {
+    for (const importPath of parsed.imports) {
+      const resolvedImport = resolve(baseDir, importPath);
+      const child = loadScenario(resolvedImport, { ...options, cwd: baseDir }, visited);
+      effectiveSteps.push(...child.steps);
+    }
+  }
+
+  for (const item of parsed.steps) {
+    if (isStepImport(item)) {
+      const resolvedImport = resolve(baseDir, item.import);
+      const child = loadScenario(resolvedImport, { ...options, cwd: baseDir }, visited);
+      effectiveSteps.push(...child.steps);
+    } else {
+      effectiveSteps.push(item);
+    }
+  }
+
+  visited.delete(absolutePath);
+
+  const scenario: DemoScenario = {
+    name: parsed.name,
+    description: parsed.description,
+    base_url: parsed.base_url,
+    steps: effectiveSteps,
+  };
+  if (parsed.title !== undefined) {
+    scenario.title = parsed.title;
+  }
+  if (parsed.seed_data !== undefined) {
+    scenario.seed_data = parsed.seed_data;
+  }
+  if (parsed.auth !== undefined) {
+    scenario.auth = parsed.auth;
+  }
+  if (parsed.video !== undefined) {
+    scenario.video = parsed.video;
+  }
+  if (parsed.screenshots !== undefined) {
+    scenario.screenshots = parsed.screenshots;
+  }
+  if (parsed.device_scale_factor !== undefined) {
+    scenario.device_scale_factor = parsed.device_scale_factor;
+  }
+  if (parsed.audio !== undefined) {
+    scenario.audio = parsed.audio;
+  }
+  if (parsed.action_timeout_ms !== undefined) {
+    scenario.action_timeout_ms = parsed.action_timeout_ms;
+  }
+  if (parsed.storage_state !== undefined) {
+    scenario.storage_state = parsed.storage_state;
+  }
+  if (parsed.save_storage_state !== undefined) {
+    scenario.save_storage_state = parsed.save_storage_state;
+  }
+  if (parsed.step_delay_ms !== undefined) {
+    scenario.step_delay_ms = parsed.step_delay_ms;
+  }
+  if (parsed.slow_mo_ms !== undefined) {
+    scenario.slow_mo_ms = parsed.slow_mo_ms;
+  }
+  if (parsed.typing_delay_ms !== undefined) {
+    scenario.typing_delay_ms = parsed.typing_delay_ms;
+  }
+  if (parsed.post_click_delay_ms !== undefined) {
+    scenario.post_click_delay_ms = parsed.post_click_delay_ms;
+  }
+  if (parsed.navigate_hold_ms !== undefined) {
+    scenario.navigate_hold_ms = parsed.navigate_hold_ms;
+  }
+  if (parsed.pre_action_delay_ms !== undefined) {
+    scenario.pre_action_delay_ms = parsed.pre_action_delay_ms;
+  }
+  if (parsed.metadata !== undefined) {
+    scenario.metadata = parsed.metadata;
+  }
+  if (parsed.url_capture !== undefined) {
+    scenario.url_capture = parsed.url_capture;
+  }
+
+  return scenario;
+}

package/src/logger.ts

@@ -0,0 +1,126 @@
+/**
+ * Node-safe logger for the demo-maker. No SvelteKit or $app imports.
+ */
+
+import type { IDemoLogger } from "./types";
+
+/** Local time `HH:mm:ss` for step progress lines. */
+export function formatLocalTimeHHMMSS(d = new Date()): string {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+function ansiColorEnabled(): boolean {
+  if (process.env.NO_COLOR != null && process.env.NO_COLOR !== "") {
+    return false;
+  }
+  if (process.env.FORCE_COLOR === "1" || process.env.FORCE_COLOR === "true") {
+    return true;
+  }
+  return process.stdout.isTTY === true;
+}
+
+/** Widest `ActionType` string (`expect_visible`) — pad so hint column lines up. */
+const STEP_ACTION_COLUMN_WIDTH = 14;
+
+function paddedStepCounter(stepIndex: number, stepTotal: number): string {
+  const w = Math.max(1, String(stepTotal).length);
+  return `${String(stepIndex).padStart(w, " ")}/${stepTotal}`;
+}
+
+function paddedActionVerb(action: string): string {
+  return action.padEnd(STEP_ACTION_COLUMN_WIDTH, " ");
+}
+
+const ANSI = {
+  reset: "\x1b[0m",
+  /** Timestamp */
+  time: "\x1b[2;36m",
+  /** Punctuation: ` - ` and `: ` between segments */
+  sep: "\x1b[2;90m",
+  /** `Step i/n` */
+  step: "\x1b[1;97m",
+  /** Action verb: click, fill, wait, … */
+  action: "\x1b[33m",
+  /** Locator / URL / caption tail after action */
+  detail: "\x1b[35m",
+  /** Errors */
+  err: "\x1b[31m",
+} as const;
+
+export interface StepProgressLogParts {
+  stepIndex: number;
+  stepTotal: number;
+  action: string;
+  hint?: string;
+}
+
+/**
+ * One-line step progress for the terminal: `22:45:59 - Step 8/37: wait - 3500ms`.
+ * Uses ANSI colors when stdout is a TTY and `NO_COLOR` is unset.
+ */
+export function formatStepProgressLogLine(parts: StepProgressLogParts): string {
+  const ts = formatLocalTimeHHMMSS();
+  const { stepIndex, stepTotal, action, hint } = parts;
+  const hintTrim = hint?.trim();
+  const hasHint = hintTrim !== undefined && hintTrim !== "";
+
+  const stepPart = paddedStepCounter(stepIndex, stepTotal);
+  const actionPart = paddedActionVerb(action);
+
+  if (!ansiColorEnabled()) {
+    const core = `Step ${stepPart}: ${actionPart}`;
+    return `${ts} - ${core}${hasHint ? ` - ${hintTrim}` : ""}`;
+  }
+
+  const { reset, time, sep, step, action: actStyle, detail } = ANSI;
+  let out = `${time}${ts}${reset}${sep} - ${reset}${step}Step ${stepPart}${reset}${sep}: ${reset}${actStyle}${actionPart}${reset}`;
+  if (hasHint) {
+    out += `${sep} - ${reset}${detail}${hintTrim}${reset}`;
+  }
+  return out;
+}
+
+export function formatStepFailedLogLine(stepIndex: number, message: string): string {
+  const ts = formatLocalTimeHHMMSS();
+  if (!ansiColorEnabled()) {
+    return `${ts} - Step ${stepIndex} failed: ${message}`;
+  }
+  const { reset, time, sep, step, err } = ANSI;
+  return `${time}${ts}${reset}${sep} - ${reset}${step}Step ${stepIndex} failed${reset}${sep}: ${reset}${err}${message}${reset}`;
+}
+
+const LEVEL_ORDER: Record<string, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+export function createDemoLogger(
+  level: "debug" | "info" | "warn" | "error" = "info"
+): IDemoLogger {
+  const minLevel = LEVEL_ORDER[level] ?? LEVEL_ORDER.info ?? 0;
+
+  function shouldLog(msgLevel: string): boolean {
+    return (LEVEL_ORDER[msgLevel] ?? 0) >= minLevel;
+  }
+
+  return {
+    log(...args: unknown[]) {
+      console.log(...args);
+    },
+    info(...args: unknown[]) {
+      if (shouldLog("info")) console.info(...args);
+    },
+    warn(...args: unknown[]) {
+      if (shouldLog("warn")) console.warn(...args);
+    },
+    error(...args: unknown[]) {
+      if (shouldLog("error")) console.error(...args);
+    },
+    debug(...args: unknown[]) {
+      if (shouldLog("debug")) console.debug(...args);
+    },
+  };
+}

package/src/main.ts

@@ -0,0 +1,68 @@
+/**
+ * Unified CLI: demo-maker <run|check|record|import|export-chapters> ...
+ */
+
+import { runMain } from "./cli";
+import { recordMain } from "./record-cli";
+import { exportChaptersMain } from "./export-chapters";
+
+function printHelp(): void {
+  console.log(`demo-maker — demo videos as code (YAML + Playwright → MP4)
+
+Usage:
+  demo-maker run <scenario.yaml> [options]
+  demo-maker check <scenario.yaml> [options]   # same as run --fail-fast --fast
+  demo-maker record [options]
+  demo-maker import <recording.json> -o <scenario.yaml>
+  demo-maker export-chapters <timing.json|dir>
+
+Run options include:
+  --env-file=PATH  --base-url=URL  --headless  --fast  --fail-fast
+  --end-step=N  --pause-at-end  --storage-state=PATH  --save-storage-state=PATH
+  --debug-dir=PATH  --capture-from-url VAR=regex  --url-capture-file=path.json
+
+Requires: Node 20+, Playwright Chromium, ffmpeg on PATH for MP4/splice.
+`);
+}
+
+export async function main(argv: string[] = process.argv): Promise<number> {
+  const args = argv.slice(2);
+  const cmd = args[0];
+
+  if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
+    printHelp();
+    return cmd ? 0 : 1;
+  }
+
+  if (cmd === "run") {
+    return runMain(["node", "demo-maker", ...args.slice(1)]);
+  }
+  if (cmd === "check") {
+    return runMain(["node", "demo-maker", ...args.slice(1), "--fail-fast", "--fast"]);
+  }
+  if (cmd === "record") {
+    return recordMain(["node", "demo-maker", ...args.slice(1)]);
+  }
+  if (cmd === "import") {
+    return recordMain(["node", "demo-maker", "--import", ...args.slice(1)]);
+  }
+  if (cmd === "export-chapters") {
+    return exportChaptersMain(["node", "demo-maker", ...args.slice(1)]);
+  }
+
+  // Back-compat: first arg is a yaml path (old ui script style)
+  if (cmd.endsWith(".yaml") || cmd.endsWith(".yml")) {
+    return runMain(argv);
+  }
+
+  console.error(`Unknown command: ${cmd}`);
+  printHelp();
+  return 1;
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

package/src/parse-errors.ts

@@ -0,0 +1,99 @@
+/**
+ * Format parse/validation errors with file and step context for composed scenarios.
+ */
+
+const SUMMARY_MAX = 120;
+
+export interface ParseScenarioContext {
+  /** Absolute or relative path to the YAML file being parsed. */
+  sourceFile?: string;
+  /** Scenario `name:` from the same file. */
+  scenarioName?: string;
+}
+
+function truncate(value: string, max = SUMMARY_MAX): string {
+  const oneLine = value.replace(/\s+/g, " ").trim();
+  if (oneLine.length <= max) {
+    return oneLine;
+  }
+  return `${oneLine.slice(0, max - 1)}…`;
+}
+
+/** One-line summary of raw YAML step fields for error messages. */
+export function summarizeRawStep(raw: Record<string, unknown>): string {
+  const parts: string[] = [];
+  if (typeof raw.action === "string") {
+    parts.push(`action=${raw.action}`);
+  }
+  if (typeof raw.import === "string") {
+    parts.push(`import=${raw.import}`);
+  }
+  if (typeof raw.url === "string") {
+    parts.push(`url=${truncate(raw.url)}`);
+  }
+  if (typeof raw.value === "string") {
+    parts.push(`value=${truncate(raw.value)}`);
+  }
+  if (typeof raw.message === "string") {
+    parts.push(`message=${truncate(raw.message)}`);
+  }
+  if (typeof raw.caption === "string") {
+    parts.push(`caption=${truncate(raw.caption)}`);
+  }
+  if (typeof raw.text === "string") {
+    parts.push(`text=${truncate(raw.text)}`);
+  }
+  if (raw.locator !== undefined) {
+    try {
+      parts.push(`locator=${truncate(JSON.stringify(raw.locator))}`);
+    } catch {
+      parts.push("locator=<unserializable>");
+    }
+  }
+  return parts.join(", ");
+}
+
+const VALID_LOCATOR_KEYS = new Set(["role", "label", "aria-label", "text", "placeholder", "title", "selector"]);
+
+/** Hint when `locator:` is present but did not map to a supported shape. */
+export function describeInvalidLocator(raw: unknown): string | undefined {
+  if (raw === undefined || raw === null) {
+    return undefined;
+  }
+  if (typeof raw !== "object") {
+    return `locator must be an object, got ${typeof raw}`;
+  }
+  const keys = Object.keys(raw as Record<string, unknown>);
+  if (keys.length === 0) {
+    return 'locator object is empty (use role, label, aria-label, text, placeholder, title, or selector)';
+  }
+  const unknown = keys.filter((k) => !VALID_LOCATOR_KEYS.has(k));
+  if (unknown.length > 0) {
+    return `unrecognized locator key(s): ${unknown.join(", ")} (use role, label, aria-label, text, placeholder, title, or selector)`;
+  }
+  return undefined;
+}
+
+export function formatStepParseError(
+  ctx: ParseScenarioContext,
+  stepIndex: number,
+  message: string,
+  rawStep?: Record<string, unknown>
+): string {
+  const stepNum = stepIndex + 1;
+  const where: string[] = [`Step ${stepNum}`];
+  if (ctx.sourceFile) {
+    where.push(`in ${ctx.sourceFile}`);
+  }
+  if (ctx.scenarioName) {
+    where.push(`(scenario "${ctx.scenarioName}")`);
+  }
+  let out = `${where.join(" ")}: ${message}`;
+  if (rawStep) {
+    const summary = summarizeRawStep(rawStep);
+    if (summary) {
+      out += `\n  step: ${summary}`;
+    }
+  }
+  return out;
+}