@scenar/cli 0.0.2

package/src/__tests__/scenario-validator.test.ts

@@ -0,0 +1,353 @@
+import { describe, it, expect } from "vitest";
+import { validateScenario } from "../validate/scenario-validator.js";
+
+function validScenario() {
+  return {
+    viewport: { width: 896, height: 540 },
+    steps: [
+      {
+        view: "intro",
+        delayMs: 0,
+        caption: "Welcome",
+        narrationText: "Welcome to the demo.",
+      },
+    ],
+  };
+}
+
+describe("validateScenario", () => {
+  // --- Happy path ---
+
+  it("accepts a valid scenario", () => {
+    const result = validateScenario(validScenario());
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it("accepts a scenario without viewport (optional)", () => {
+    const s = validScenario();
+    delete (s as Record<string, unknown>)["viewport"];
+    expect(validateScenario(s).valid).toBe(true);
+  });
+
+  it("accepts a step without interactions (optional)", () => {
+    expect(validateScenario(validScenario()).valid).toBe(true);
+  });
+
+  it("accepts a valid scenario with interactions", () => {
+    const s = validScenario();
+    s.steps[0] = {
+      ...s.steps[0]!,
+      interactions: [
+        { atPercent: 0.5, type: 5, target: "my-btn" },
+      ],
+    } as typeof s.steps[0];
+    expect(validateScenario(s).valid).toBe(true);
+  });
+
+  // --- Root-level errors ---
+
+  it("rejects null", () => {
+    const result = validateScenario(null);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]!.reason).toMatch(/must be an object/);
+  });
+
+  it("rejects non-object", () => {
+    const result = validateScenario("not an object");
+    expect(result.valid).toBe(false);
+  });
+
+  // --- Steps errors ---
+
+  it("rejects missing steps", () => {
+    const result = validateScenario({ viewport: { width: 800, height: 600 } });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "steps", reason: expect.stringMatching(/must be an array/) }),
+    );
+  });
+
+  it("rejects empty steps array", () => {
+    const result = validateScenario({ steps: [] });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "steps", reason: expect.stringMatching(/at least one/) }),
+    );
+  });
+
+  it("rejects step with missing view", () => {
+    const result = validateScenario({ steps: [{ delayMs: 0 }] });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "steps[0].view" }),
+    );
+  });
+
+  it("rejects step with empty view string", () => {
+    const result = validateScenario({ steps: [{ view: "", delayMs: 0 }] });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "steps[0].view" }),
+    );
+  });
+
+  it("rejects step with negative delayMs", () => {
+    const result = validateScenario({ steps: [{ view: "x", delayMs: -1 }] });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "steps[0].delayMs" }),
+    );
+  });
+
+  // --- Viewport errors ---
+
+  it("rejects viewport with zero width", () => {
+    const result = validateScenario({
+      viewport: { width: 0, height: 540 },
+      steps: [{ view: "x", delayMs: 0 }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "viewport.width" }),
+    );
+  });
+
+  it("rejects viewport with negative height", () => {
+    const result = validateScenario({
+      viewport: { width: 800, height: -10 },
+      steps: [{ view: "x", delayMs: 0 }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "viewport.height" }),
+    );
+  });
+
+  // --- Interaction errors ---
+
+  it("rejects interaction with atPercent below 0", () => {
+    const result = validateScenario({
+      steps: [{
+        view: "x",
+        delayMs: 0,
+        interactions: [{ atPercent: -0.1, type: 3, target: "btn" }],
+      }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "steps[0].interactions[0].atPercent" }),
+    );
+  });
+
+  it("rejects interaction with atPercent above 1", () => {
+    const result = validateScenario({
+      steps: [{
+        view: "x",
+        delayMs: 0,
+        interactions: [{ atPercent: 1.5, type: 3, target: "btn" }],
+      }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "steps[0].interactions[0].atPercent" }),
+    );
+  });
+
+  it("rejects interaction with unknown action type number", () => {
+    const result = validateScenario({
+      steps: [{
+        view: "x",
+        delayMs: 0,
+        interactions: [{ atPercent: 0.5, type: 99, target: "btn" }],
+      }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "steps[0].interactions[0].type" }),
+    );
+  });
+
+  it("rejects interaction with 'unspecified' action type (0)", () => {
+    const result = validateScenario({
+      steps: [{
+        view: "x",
+        delayMs: 0,
+        interactions: [{ atPercent: 0.5, type: 0, target: "btn" }],
+      }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({
+        path: "steps[0].interactions[0].type",
+        reason: expect.stringMatching(/unspecified/),
+      }),
+    );
+  });
+
+  it("accepts action type by string name", () => {
+    const result = validateScenario({
+      steps: [{
+        view: "x",
+        delayMs: 0,
+        interactions: [{ atPercent: 0.5, type: "click", target: "btn" }],
+      }],
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it("rejects unknown action type string", () => {
+    const result = validateScenario({
+      steps: [{
+        view: "x",
+        delayMs: 0,
+        interactions: [{ atPercent: 0.5, type: "explode", target: "btn" }],
+      }],
+    });
+    expect(result.valid).toBe(false);
+  });
+
+  it("rejects missing target for click action", () => {
+    const result = validateScenario({
+      steps: [{
+        view: "x",
+        delayMs: 0,
+        interactions: [{ atPercent: 0.5, type: 3 }],
+      }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "steps[0].interactions[0].target" }),
+    );
+  });
+
+  // --- Config validation ---
+
+  it("rejects type action without typeConfig", () => {
+    const result = validateScenario({
+      steps: [{
+        view: "x",
+        delayMs: 0,
+        interactions: [{ atPercent: 0.5, type: 4, target: "input" }],
+      }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({
+        path: "steps[0].interactions[0].typeConfig",
+        reason: expect.stringMatching(/required/),
+      }),
+    );
+  });
+
+  it("rejects typeConfig with empty text", () => {
+    const result = validateScenario({
+      steps: [{
+        view: "x",
+        delayMs: 0,
+        interactions: [{
+          atPercent: 0.5,
+          type: 4,
+          target: "input",
+          typeConfig: { text: "" },
+        }],
+      }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "steps[0].interactions[0].typeConfig.text" }),
+    );
+  });
+
+  it("rejects typeConfig with negative typeDelayMs", () => {
+    const result = validateScenario({
+      steps: [{
+        view: "x",
+        delayMs: 0,
+        interactions: [{
+          atPercent: 0.5,
+          type: 4,
+          target: "input",
+          typeConfig: { text: "hello", typeDelayMs: -10 },
+        }],
+      }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "steps[0].interactions[0].typeConfig.typeDelayMs" }),
+    );
+  });
+
+  it("rejects hoverConfig with negative hoverDurationMs", () => {
+    const result = validateScenario({
+      steps: [{
+        view: "x",
+        delayMs: 0,
+        interactions: [{
+          atPercent: 0.5,
+          type: 5,
+          target: "btn",
+          hoverConfig: { hoverDurationMs: -1 },
+        }],
+      }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "steps[0].interactions[0].hoverConfig.hoverDurationMs" }),
+    );
+  });
+
+  it("rejects drag action without dragConfig", () => {
+    const result = validateScenario({
+      steps: [{
+        view: "x",
+        delayMs: 0,
+        interactions: [{
+          atPercent: 0.5,
+          type: 6,
+          target: "source",
+        }],
+      }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({
+        path: "steps[0].interactions[0].dragConfig",
+        reason: expect.stringMatching(/required/),
+      }),
+    );
+  });
+
+  it("rejects dragConfig with empty dragTarget", () => {
+    const result = validateScenario({
+      steps: [{
+        view: "x",
+        delayMs: 0,
+        interactions: [{
+          atPercent: 0.5,
+          type: 6,
+          target: "source",
+          dragConfig: { dragTarget: "" },
+        }],
+      }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "steps[0].interactions[0].dragConfig.dragTarget" }),
+    );
+  });
+
+  // --- Collects multiple errors ---
+
+  it("collects multiple errors across steps and interactions", () => {
+    const result = validateScenario({
+      viewport: { width: -1, height: 0 },
+      steps: [
+        { view: "", delayMs: -1 },
+        { delayMs: 0 },
+      ],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThanOrEqual(4);
+  });
+});

package/src/__tests__/validate-command.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { runValidate } from "../commands/validate.js";
+
+vi.mock("../util/load-yaml.js", () => ({
+  loadScenarioYaml: vi.fn(),
+}));
+
+import { loadScenarioYaml } from "../util/load-yaml.js";
+
+const mockLoad = vi.mocked(loadScenarioYaml);
+
+describe("scenar validate", () => {
+  let stdoutData: string;
+  let stderrData: string;
+  let originalExitCode: number | undefined;
+
+  beforeEach(() => {
+    stdoutData = "";
+    stderrData = "";
+    originalExitCode = process.exitCode;
+    process.exitCode = undefined;
+
+    vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array) => {
+      stdoutData += String(chunk);
+      return true;
+    });
+    vi.spyOn(process.stderr, "write").mockImplementation((chunk: string | Uint8Array) => {
+      stderrData += String(chunk);
+      return true;
+    });
+  });
+
+  afterEach(() => {
+    process.exitCode = originalExitCode;
+    vi.restoreAllMocks();
+  });
+
+  it("prints success for a valid scenario", async () => {
+    mockLoad.mockResolvedValue({
+      steps: [{ view: "intro", delayMs: 0 }],
+    });
+
+    await runValidate("demo.yaml", {});
+
+    expect(stdoutData).toContain("valid");
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it("prints errors and sets exit code 1 for invalid scenario", async () => {
+    mockLoad.mockResolvedValue({ steps: [] });
+
+    await runValidate("bad.yaml", {});
+
+    expect(stderrData).toContain("error");
+    expect(process.exitCode).toBe(1);
+  });
+
+  it("outputs JSON when --json flag is set", async () => {
+    mockLoad.mockResolvedValue({
+      steps: [{ view: "intro", delayMs: 0 }],
+    });
+
+    await runValidate("demo.yaml", { json: true });
+
+    const output = JSON.parse(stdoutData);
+    expect(output.valid).toBe(true);
+    expect(output.errors).toEqual([]);
+  });
+
+  it("outputs JSON with errors and sets exit code 1", async () => {
+    mockLoad.mockResolvedValue({ steps: [] });
+
+    await runValidate("bad.yaml", { json: true });
+
+    const output = JSON.parse(stdoutData);
+    expect(output.valid).toBe(false);
+    expect(output.errors.length).toBeGreaterThan(0);
+    expect(process.exitCode).toBe(1);
+  });
+});

package/src/commands/narrate.d.ts

@@ -0,0 +1,15 @@
+import { Command } from "commander";
+import type { TtsProvider } from "../tts/types.js";
+interface NarrateOptions {
+    tts: string;
+    out: string;
+    voice?: string;
+}
+export declare function registerNarrateCommand(program: Command): void;
+/**
+ * Core narration logic, separated from provider resolution for testability.
+ * The command handler resolves the provider, then delegates here.
+ */
+export declare function runNarrate(file: string, options: NarrateOptions, provider: TtsProvider): Promise<void>;
+export {};
+//# sourceMappingURL=narrate.d.ts.map

package/src/commands/narrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"narrate.d.ts","sourceRoot":"","sources":["../../../src/commands/narrate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,KAAK,EAA4C,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE7F,UAAU,cAAc;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAY7D;AAOD;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,WAAW,GACpB,OAAO,CAAC,IAAI,CAAC,CAqEf"}

package/src/commands/narrate.js

@@ -0,0 +1,75 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadScenarioYaml } from "../util/load-yaml.js";
+import { validateScenario } from "../validate/scenario-validator.js";
+import { resolveProvider } from "../tts/resolve-provider.js";
+export function registerNarrateCommand(program) {
+    program
+        .command("narrate")
+        .description("Generate narration audio from a scenario YAML file.")
+        .argument("<file>", "path to scenario YAML file")
+        .option("--tts <provider>", "TTS provider: echogarden (default) or openai", "echogarden")
+        .option("--out <dir>", "output directory for audio files", "./narration")
+        .option("--voice <voice>", "voice name (provider-specific)")
+        .action(async (file, options) => {
+        const provider = await resolveProvider(options.tts);
+        await runNarrate(file, options, provider);
+    });
+}
+/**
+ * Core narration logic, separated from provider resolution for testability.
+ * The command handler resolves the provider, then delegates here.
+ */
+export async function runNarrate(file, options, provider) {
+    const scenario = await loadScenarioYaml(file);
+    const validation = validateScenario(scenario);
+    if (!validation.valid) {
+        process.stderr.write(`\x1b[31m✗\x1b[0m Scenario has ${validation.errors.length} error(s). Run 'scenar validate ${file}' for details.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const steps = scenario["steps"];
+    if (!steps) {
+        process.stderr.write("\x1b[31m✗\x1b[0m No steps found in scenario.\n");
+        process.exitCode = 1;
+        return;
+    }
+    const narratedSteps = [];
+    for (let i = 0; i < steps.length; i++) {
+        const text = steps[i]["narrationText"];
+        if (typeof text === "string" && text.length > 0) {
+            narratedSteps.push({ index: i, text });
+        }
+    }
+    if (narratedSteps.length === 0) {
+        process.stderr.write("\x1b[33m⚠\x1b[0m No steps contain narration text. Nothing to generate.\n");
+        return;
+    }
+    await mkdir(options.out, { recursive: true });
+    const manifestSteps = [];
+    for (let i = 0; i < narratedSteps.length; i++) {
+        const step = narratedSteps[i];
+        const fileName = `step-${step.index}.mp3`;
+        const outputPath = join(options.out, fileName);
+        process.stderr.write(`  [${i + 1}/${narratedSteps.length}] Generating audio for step ${step.index}...\n`);
+        const result = await provider.synthesize(step.text, {
+            voice: options.voice,
+        });
+        await writeFile(outputPath, result.audio);
+        manifestSteps.push({
+            index: step.index,
+            file: fileName,
+            durationMs: result.durationMs,
+            text: step.text,
+        });
+    }
+    const manifest = {
+        generatedAt: new Date().toISOString(),
+        ttsProvider: provider.name,
+        steps: manifestSteps,
+    };
+    const manifestPath = join(options.out, "manifest.json");
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+    process.stderr.write(`\n\x1b[32m✓\x1b[0m Generated ${manifestSteps.length} audio file(s) in ${options.out}/\n`);
+}
+//# sourceMappingURL=narrate.js.map

package/src/commands/narrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"narrate.js","sourceRoot":"","sources":["../../../src/commands/narrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAS7D,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACrD,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,qDAAqD,CAAC;SAClE,QAAQ,CAAC,QAAQ,EAAE,4BAA4B,CAAC;SAChD,MAAM,CAAC,kBAAkB,EAAE,8CAA8C,EAAE,YAAY,CAAC;SACxF,MAAM,CAAC,aAAa,EAAE,kCAAkC,EAAE,aAAa,CAAC;SACxE,MAAM,CAAC,iBAAiB,EAAE,gCAAgC,CAAC;SAC3D,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,OAAuB,EAAE,EAAE;QACtD,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACpD,MAAM,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;AACP,CAAC;AAOD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAY,EACZ,OAAuB,EACvB,QAAqB;IAErB,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAE9C,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,UAAU,CAAC,MAAM,CAAC,MAAM,mCAAmC,IAAI,kBAAkB,CAAC,CAAC;QACzI,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAI,QAAoC,CAAC,OAAO,CAA0C,CAAC;IACtG,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACvE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,aAAa,GAAwB,EAAE,CAAC;IAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,eAAe,CAAC,CAAC;QACxC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChD,aAAa,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0EAA0E,CAAC,CAAC;QACjG,OAAO;IACT,CAAC;IAED,MAAM,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE9C,MAAM,aAAa,GAA4B,EAAE,CAAC;IAElD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAG,aAAa,CAAC,CAAC,CAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,QAAQ,IAAI,CAAC,KAAK,MAAM,CAAC;QAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAE/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,MAAM,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,MAAM,+BAA+B,IAAI,CAAC,KAAK,OAAO,CACpF,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE;YAClD,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC,CAAC;QAEH,MAAM,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAE1C,aAAa,CAAC,IAAI,CAAC;YACjB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,QAAQ,GAAsB;QAClC,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrC,WAAW,EAAE,QAAQ,CAAC,IAAI;QAC1B,KAAK,EAAE,aAAa;KACrB,CAAC;IAEF,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IACxD,MAAM,SAAS,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAExE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,gCAAgC,aAAa,CAAC,MAAM,qBAAqB,OAAO,CAAC,GAAG,KAAK,CAC1F,CAAC;AACJ,CAAC"}

package/src/commands/narrate.ts

@@ -0,0 +1,111 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Command } from "commander";
+import { loadScenarioYaml } from "../util/load-yaml.js";
+import { validateScenario } from "../validate/scenario-validator.js";
+import { resolveProvider } from "../tts/resolve-provider.js";
+import type { NarrationManifest, NarrationManifestStep, TtsProvider } from "../tts/types.js";
+
+interface NarrateOptions {
+  tts: string;
+  out: string;
+  voice?: string;
+}
+
+export function registerNarrateCommand(program: Command): void {
+  program
+    .command("narrate")
+    .description("Generate narration audio from a scenario YAML file.")
+    .argument("<file>", "path to scenario YAML file")
+    .option("--tts <provider>", "TTS provider: echogarden (default) or openai", "echogarden")
+    .option("--out <dir>", "output directory for audio files", "./narration")
+    .option("--voice <voice>", "voice name (provider-specific)")
+    .action(async (file: string, options: NarrateOptions) => {
+      const provider = await resolveProvider(options.tts);
+      await runNarrate(file, options, provider);
+    });
+}
+
+interface StepWithNarration {
+  index: number;
+  text: string;
+}
+
+/**
+ * Core narration logic, separated from provider resolution for testability.
+ * The command handler resolves the provider, then delegates here.
+ */
+export async function runNarrate(
+  file: string,
+  options: NarrateOptions,
+  provider: TtsProvider,
+): Promise<void> {
+  const scenario = await loadScenarioYaml(file);
+  const validation = validateScenario(scenario);
+
+  if (!validation.valid) {
+    process.stderr.write(`\x1b[31m✗\x1b[0m Scenario has ${validation.errors.length} error(s). Run 'scenar validate ${file}' for details.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const steps = (scenario as Record<string, unknown>)["steps"] as Record<string, unknown>[] | undefined;
+  if (!steps) {
+    process.stderr.write("\x1b[31m✗\x1b[0m No steps found in scenario.\n");
+    process.exitCode = 1;
+    return;
+  }
+
+  const narratedSteps: StepWithNarration[] = [];
+  for (let i = 0; i < steps.length; i++) {
+    const text = steps[i]!["narrationText"];
+    if (typeof text === "string" && text.length > 0) {
+      narratedSteps.push({ index: i, text });
+    }
+  }
+
+  if (narratedSteps.length === 0) {
+    process.stderr.write("\x1b[33m⚠\x1b[0m No steps contain narration text. Nothing to generate.\n");
+    return;
+  }
+
+  await mkdir(options.out, { recursive: true });
+
+  const manifestSteps: NarrationManifestStep[] = [];
+
+  for (let i = 0; i < narratedSteps.length; i++) {
+    const step = narratedSteps[i]!;
+    const fileName = `step-${step.index}.mp3`;
+    const outputPath = join(options.out, fileName);
+
+    process.stderr.write(
+      `  [${i + 1}/${narratedSteps.length}] Generating audio for step ${step.index}...\n`,
+    );
+
+    const result = await provider.synthesize(step.text, {
+      voice: options.voice,
+    });
+
+    await writeFile(outputPath, result.audio);
+
+    manifestSteps.push({
+      index: step.index,
+      file: fileName,
+      durationMs: result.durationMs,
+      text: step.text,
+    });
+  }
+
+  const manifest: NarrationManifest = {
+    generatedAt: new Date().toISOString(),
+    ttsProvider: provider.name,
+    steps: manifestSteps,
+  };
+
+  const manifestPath = join(options.out, "manifest.json");
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+
+  process.stderr.write(
+    `\n\x1b[32m✓\x1b[0m Generated ${manifestSteps.length} audio file(s) in ${options.out}/\n`,
+  );
+}

package/src/commands/validate.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+interface ValidateOptions {
+    json?: boolean;
+}
+export declare function registerValidateCommand(program: Command): void;
+export declare function runValidate(file: string, options: ValidateOptions): Promise<void>;
+export {};
+//# sourceMappingURL=validate.d.ts.map

package/src/commands/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/commands/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAS9D;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/src/commands/validate.js

@@ -0,0 +1,33 @@
+import { loadScenarioYaml } from "../util/load-yaml.js";
+import { validateScenario } from "../validate/scenario-validator.js";
+export function registerValidateCommand(program) {
+    program
+        .command("validate")
+        .description("Validate a scenario YAML file against the proto schema.")
+        .argument("<file>", "path to scenario YAML file")
+        .option("--json", "output validation result as JSON")
+        .action(async (file, options) => {
+        await runValidate(file, options);
+    });
+}
+export async function runValidate(file, options) {
+    const scenario = await loadScenarioYaml(file);
+    const result = validateScenario(scenario);
+    if (options.json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        if (!result.valid)
+            process.exitCode = 1;
+        return;
+    }
+    if (result.valid) {
+        process.stdout.write(`\x1b[32m✓\x1b[0m Scenario is valid: ${file}\n`);
+        return;
+    }
+    process.stderr.write(`\x1b[31m✗\x1b[0m Scenario has ${result.errors.length} error(s): ${file}\n\n`);
+    for (const error of result.errors) {
+        process.stderr.write(`  \x1b[31m•\x1b[0m ${error.path}: ${error.reason}\n`);
+    }
+    process.stderr.write("\n");
+    process.exitCode = 1;
+}
+//# sourceMappingURL=validate.js.map