@scenar/cli 0.0.2 → 0.0.4

package/src/commands/narrate.ts

@@ -1,111 +1,313 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdir, writeFile, stat } from "node:fs/promises";
+import { join, resolve, extname, basename, dirname } from "node:path";
 import { Command } from "commander";
 import { loadScenarioYaml } from "../util/load-yaml.js";
+import { loadStepsFromTs } from "../util/load-ts.js";
+import { discoverScenarios } from "../util/discover-scenarios.js";
+import {
+  computeHash,
+  loadCache,
+  saveCache,
+  fileExists,
+  isCached,
+  getCachedDuration,
+  buildCacheFile,
+} from "../util/narration-cache.js";
 import { validateScenario } from "../validate/scenario-validator.js";
 import { resolveProvider } from "../tts/resolve-provider.js";
-import type { NarrationManifest, NarrationManifestStep, TtsProvider } from "../tts/types.js";
+import type { TtsProvider } from "../tts/types.js";
 
 interface NarrateOptions {
   tts: string;
-  out: string;
+  out?: string;
   voice?: string;
+  baseUrl?: 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")
+    .description(
+      "Generate narration audio from scenario files.\n\n" +
+      "Accepts a YAML file, a TypeScript steps file, or a directory\n" +
+      "containing scenario subdirectories (each with a steps.ts).",
+    )
+    .argument("<file-or-dir>", "path to scenario file (.yaml/.ts) or directory")
+    .option("--tts <provider>", "TTS provider: echogarden, edge-tts, or openai", "echogarden")
+    .option("--out <dir>", "output directory for audio files")
     .option("--voice <voice>", "voice name (provider-specific)")
-    .action(async (file: string, options: NarrateOptions) => {
+    .option("--base-url <path>", "URL path prefix for src fields in manifest")
+    .action(async (fileOrDir: string, options: NarrateOptions) => {
       const provider = await resolveProvider(options.tts);
-      await runNarrate(file, options, provider);
+      const resolved = resolve(fileOrDir);
+      const info = await stat(resolved);
+
+      if (info.isDirectory()) {
+        await runNarrateDirectory(resolved, options, provider);
+      } else {
+        await runNarrateSingleFile(resolved, options, provider);
+      }
     });
 }
 
+// ---------------------------------------------------------------------------
+// Step extraction
+// ---------------------------------------------------------------------------
+
 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,
+function extractNarratedSteps(
+  steps: Array<{ narration?: string; narrationText?: string }>,
+): StepWithNarration[] {
+  const result: StepWithNarration[] = [];
+  for (let i = 0; i < steps.length; i++) {
+    const text = steps[i]!.narration ?? steps[i]!.narrationText;
+    if (typeof text === "string" && text.length > 0) {
+      result.push({ index: i, text });
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Runtime manifest (matches @scenar/core NarrationManifest)
+// ---------------------------------------------------------------------------
+
+interface RuntimeManifestEntry {
+  src: string;
+  durationMs: number;
+}
+
+interface RuntimeManifest {
+  steps: (RuntimeManifestEntry | null)[];
+}
+
+function buildRuntimeManifest(
+  totalSteps: number,
+  entries: Map<number, { src: string; durationMs: number }>,
+): RuntimeManifest {
+  const steps: (RuntimeManifestEntry | null)[] = Array.from(
+    { length: totalSteps },
+    () => null,
+  );
+  for (const [idx, entry] of entries) {
+    steps[idx] = entry;
+  }
+  return { steps };
+}
+
+// ---------------------------------------------------------------------------
+// Single-file narration
+// ---------------------------------------------------------------------------
+
+async function loadStepsFromFile(
+  filePath: string,
+): Promise<{ steps: Array<{ narration?: string; narrationText?: string }>; totalSteps: number }> {
+  const ext = extname(filePath).toLowerCase();
+
+  if (ext === ".ts" || ext === ".tsx") {
+    const steps = await loadStepsFromTs(filePath);
+    return { steps, totalSteps: steps.length };
+  }
+
+  const scenario = await loadScenarioYaml(filePath);
+  const validation = validateScenario(scenario);
+
+  if (!validation.valid) {
+    throw new Error(
+      `Scenario has ${validation.errors.length} error(s). Run 'scenar validate ${filePath}' for details.`,
+    );
+  }
+
+  const steps = (scenario as Record<string, unknown>)["steps"] as
+    | Array<Record<string, unknown>>
+    | undefined;
+  if (!steps) {
+    throw new Error("No steps found in scenario.");
+  }
+
+  return { steps: steps as Array<{ narrationText?: string }>, totalSteps: steps.length };
+}
+
+async function runNarrateSingleFile(
+  filePath: string,
   options: NarrateOptions,
   provider: TtsProvider,
 ): Promise<void> {
-  const scenario = await loadScenarioYaml(file);
-  const validation = validateScenario(scenario);
+  const { steps, totalSteps } = await loadStepsFromFile(filePath);
+  const narratedSteps = extractNarratedSteps(steps);
 
-  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;
+  if (narratedSteps.length === 0) {
+    process.stderr.write("\x1b[33m!\x1b[0m No steps contain narration text. Nothing to generate.\n");
     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;
+  const outDir = options.out ?? join(dirname(filePath), "narration");
+  const voice = options.voice ?? "";
+
+  await generateNarration({
+    scenarioId: basename(dirname(filePath)),
+    narratedSteps,
+    totalSteps,
+    outDir,
+    voice,
+    baseUrl: options.baseUrl,
+    provider,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Directory-mode narration
+// ---------------------------------------------------------------------------
+
+async function runNarrateDirectory(
+  dirPath: string,
+  options: NarrateOptions,
+  provider: TtsProvider,
+): Promise<void> {
+  const scenarios = await discoverScenarios(dirPath);
+
+  if (scenarios.length === 0) {
+    process.stderr.write("\x1b[33m!\x1b[0m No scenario directories with steps.ts found.\n");
     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 });
+  process.stderr.write(`Discovered ${scenarios.length} scenario(s)\n\n`);
+
+  let totalGenerated = 0;
+  let totalCached = 0;
+  let totalSkipped = 0;
+  let scenariosWithNarration = 0;
+  const errors: Array<{ id: string; error: unknown }> = [];
+
+  for (const scenario of scenarios) {
+    process.stderr.write(`  ${scenario.id}\n`);
+    try {
+      const steps = await loadStepsFromTs(scenario.stepsPath);
+      const narratedSteps = extractNarratedSteps(steps);
+
+      if (narratedSteps.length === 0) {
+        process.stderr.write("    (no narration)\n");
+        totalSkipped++;
+        continue;
+      }
+
+      scenariosWithNarration++;
+
+      const outDir = options.out
+        ? join(options.out, scenario.id)
+        : join(dirPath, scenario.id, "narration");
+
+      const stats = await generateNarration({
+        scenarioId: scenario.id,
+        narratedSteps,
+        totalSteps: steps.length,
+        outDir,
+        voice: options.voice ?? "",
+        baseUrl: options.baseUrl,
+        provider,
+      });
+
+      totalGenerated += stats.generated;
+      totalCached += stats.cached;
+    } catch (error) {
+      process.stderr.write(`    \x1b[31mfailed\x1b[0m: ${error}\n`);
+      errors.push({ id: scenario.id, error });
     }
   }
 
-  if (narratedSteps.length === 0) {
-    process.stderr.write("\x1b[33m⚠\x1b[0m No steps contain narration text. Nothing to generate.\n");
-    return;
+  process.stderr.write("\n");
+  process.stderr.write(`Scenarios with narration: ${scenariosWithNarration}\n`);
+  process.stderr.write(`Audio files generated:    ${totalGenerated}\n`);
+  process.stderr.write(`Audio files cached:       ${totalCached}\n`);
+  process.stderr.write(`Scenarios skipped:        ${totalSkipped}\n`);
+
+  if (errors.length > 0) {
+    process.stderr.write(`\n\x1b[31m${errors.length} scenario(s) failed:\x1b[0m\n`);
+    for (const { id, error } of errors) {
+      process.stderr.write(`  - ${id}: ${error}\n`);
+    }
+    process.exitCode = 1;
+  } else {
+    process.stderr.write("\nDone\n");
   }
+}
+
+// ---------------------------------------------------------------------------
+// Core generation logic (shared by single-file and directory modes)
+// ---------------------------------------------------------------------------
+
+interface GenerateOptions {
+  scenarioId: string;
+  narratedSteps: StepWithNarration[];
+  totalSteps: number;
+  outDir: string;
+  voice: string;
+  baseUrl?: string;
+  provider: TtsProvider;
+}
+
+interface GenerateStats {
+  generated: number;
+  cached: number;
+}
+
+async function generateNarration(opts: GenerateOptions): Promise<GenerateStats> {
+  const { scenarioId, narratedSteps, totalSteps, outDir, voice, baseUrl, provider } = opts;
 
-  await mkdir(options.out, { recursive: true });
+  await mkdir(outDir, { recursive: true });
 
-  const manifestSteps: NarrationManifestStep[] = [];
+  const existingCache = await loadCache(outDir);
+  const stats: GenerateStats = { generated: 0, cached: 0 };
+  const manifestEntries = new Map<number, { src: string; durationMs: number }>();
+  const cacheEntries = new Map<number, { hash: string; durationMs: number }>();
 
-  for (let i = 0; i < narratedSteps.length; i++) {
-    const step = narratedSteps[i]!;
+  for (const step of narratedSteps) {
+    const hash = computeHash(step.text, voice);
     const fileName = `step-${step.index}.mp3`;
-    const outputPath = join(options.out, fileName);
+    const mp3Path = join(outDir, fileName);
 
-    process.stderr.write(
-      `  [${i + 1}/${narratedSteps.length}] Generating audio for step ${step.index}...\n`,
-    );
+    const srcPrefix = baseUrl
+      ? `${baseUrl.replace(/\/$/, "")}/${scenarioId}`
+      : `.`;
+    const src = `${srcPrefix}/${fileName}`;
+
+    if (isCached(existingCache, step.index, hash, voice) && await fileExists(mp3Path)) {
+      const durationMs = getCachedDuration(existingCache!, step.index);
+      manifestEntries.set(step.index, { src, durationMs });
+      cacheEntries.set(step.index, { hash, durationMs });
+      stats.cached++;
+      process.stderr.write(`    step ${step.index}: cached\n`);
+      continue;
+    }
 
+    process.stderr.write(`    step ${step.index}: generating...\n`);
     const result = await provider.synthesize(step.text, {
-      voice: options.voice,
+      voice: voice || undefined,
     });
 
-    await writeFile(outputPath, result.audio);
-
-    manifestSteps.push({
-      index: step.index,
-      file: fileName,
-      durationMs: result.durationMs,
-      text: step.text,
-    });
+    await writeFile(mp3Path, result.audio);
+    manifestEntries.set(step.index, { src, durationMs: result.durationMs });
+    cacheEntries.set(step.index, { hash, durationMs: result.durationMs });
+    stats.generated++;
+    process.stderr.write(`    step ${step.index}: ${result.durationMs}ms (${result.audio.length} bytes)\n`);
   }
 
-  const manifest: NarrationManifest = {
-    generatedAt: new Date().toISOString(),
-    ttsProvider: provider.name,
-    steps: manifestSteps,
-  };
+  const manifest = buildRuntimeManifest(totalSteps, manifestEntries);
+  await writeFile(
+    join(outDir, "manifest.json"),
+    JSON.stringify(manifest, null, 2) + "\n",
+  );
 
-  const manifestPath = join(options.out, "manifest.json");
-  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+  const cache = buildCacheFile(voice, totalSteps, cacheEntries);
+  await saveCache(outDir, cache);
 
   process.stderr.write(
-    `\n\x1b[32m✓\x1b[0m Generated ${manifestSteps.length} audio file(s) in ${options.out}/\n`,
+    `\x1b[32m+\x1b[0m ${scenarioId}: ${stats.generated} generated, ${stats.cached} cached\n`,
   );
+
+  return stats;
 }

package/src/index.js

@@ -5,7 +5,7 @@ export function createProgram() {
     const program = new Command();
     program
         .name("scenar")
-        .description("Scenar CLI — validate scenario YAML and generate narration audio.")
+        .description("Scenar CLI — validate scenarios and generate narration audio.")
         .version("0.0.1");
     registerValidateCommand(program);
     registerNarrateCommand(program);

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,QAAQ,CAAC;SACd,WAAW,CAAC,mEAAmE,CAAC;SAChF,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAEhC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,IAAc;IAChC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,QAAQ,CAAC;SACd,WAAW,CAAC,+DAA+D,CAAC;SAC5E,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAEhC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,IAAc;IAChC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC"}

package/src/index.ts

@@ -7,7 +7,7 @@ export function createProgram(): Command {
 
   program
     .name("scenar")
-    .description("Scenar CLI — validate scenario YAML and generate narration audio.")
+    .description("Scenar CLI — validate scenarios and generate narration audio.")
     .version("0.0.1");
 
   registerValidateCommand(program);

package/src/tts/types.d.ts

@@ -25,7 +25,11 @@ export interface TtsResult {
     durationMs: number;
 }
 /**
- * Shape written to `manifest.json` alongside the narration audio files.
+ * @deprecated Legacy CLI manifest shape. The narrate command now writes
+ * manifests matching `@scenar/core`'s `NarrationManifest` type directly
+ * (positional array of `{ src, durationMs } | null`).
+ *
+ * Kept temporarily for test compatibility during the transition.
  */
 export interface NarrationManifest {
     generatedAt: string;

package/src/tts/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tts/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,qBAAqB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tts/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,qBAAqB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd"}

package/src/tts/types.ts

@@ -29,7 +29,11 @@ export interface TtsResult {
 }
 
 /**
- * Shape written to `manifest.json` alongside the narration audio files.
+ * @deprecated Legacy CLI manifest shape. The narrate command now writes
+ * manifests matching `@scenar/core`'s `NarrationManifest` type directly
+ * (positional array of `{ src, durationMs } | null`).
+ *
+ * Kept temporarily for test compatibility during the transition.
  */
 export interface NarrationManifest {
   generatedAt: string;

package/src/util/discover-scenarios.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Scan a directory for scenario subdirectories. A subdirectory
+ * qualifies if it contains a `steps.ts` file.
+ *
+ * Returns sorted scenario entries with the directory name (used as
+ * the scenario ID) and the absolute path to `steps.ts`.
+ */
+export declare function discoverScenarios(dir: string): Promise<Array<{
+    id: string;
+    stepsPath: string;
+}>>;
+//# sourceMappingURL=discover-scenarios.d.ts.map

package/src/util/discover-scenarios.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover-scenarios.d.ts","sourceRoot":"","sources":["../../../src/util/discover-scenarios.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAiBnD"}

package/src/util/discover-scenarios.js

@@ -0,0 +1,28 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Scan a directory for scenario subdirectories. A subdirectory
+ * qualifies if it contains a `steps.ts` file.
+ *
+ * Returns sorted scenario entries with the directory name (used as
+ * the scenario ID) and the absolute path to `steps.ts`.
+ */
+export async function discoverScenarios(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const scenarios = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const stepsPath = join(dir, entry.name, "steps.ts");
+        try {
+            const { access } = await import("node:fs/promises");
+            await access(stepsPath);
+            scenarios.push({ id: entry.name, stepsPath });
+        }
+        catch {
+            // No steps.ts — skip.
+        }
+    }
+    return scenarios.sort((a, b) => a.id.localeCompare(b.id));
+}
+//# sourceMappingURL=discover-scenarios.js.map

package/src/util/discover-scenarios.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover-scenarios.js","sourceRoot":"","sources":["../../../src/util/discover-scenarios.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAW;IAEX,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,MAAM,SAAS,GAA6C,EAAE,CAAC;IAE/D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;YAAE,SAAS;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;YACpD,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;YACxB,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,sBAAsB;QACxB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/src/util/discover-scenarios.ts

@@ -0,0 +1,30 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Scan a directory for scenario subdirectories. A subdirectory
+ * qualifies if it contains a `steps.ts` file.
+ *
+ * Returns sorted scenario entries with the directory name (used as
+ * the scenario ID) and the absolute path to `steps.ts`.
+ */
+export async function discoverScenarios(
+  dir: string,
+): Promise<Array<{ id: string; stepsPath: string }>> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const scenarios: Array<{ id: string; stepsPath: string }> = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const stepsPath = join(dir, entry.name, "steps.ts");
+    try {
+      const { access } = await import("node:fs/promises");
+      await access(stepsPath);
+      scenarios.push({ id: entry.name, stepsPath });
+    } catch {
+      // No steps.ts — skip.
+    }
+  }
+
+  return scenarios.sort((a, b) => a.id.localeCompare(b.id));
+}

package/src/util/load-ts.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Minimal shape extracted from each step object. The loader
+ * duck-types the exported array — any array of objects with
+ * `delayMs` qualifies as a steps array.
+ */
+export interface ImportedStep {
+    delayMs: number;
+    narration?: string;
+}
+/**
+ * Dynamically import a TypeScript steps file and extract the
+ * steps array by duck-typing (looks for the first exported array
+ * whose elements have a `delayMs` property).
+ *
+ * Requires the caller's Node process to have a TypeScript loader
+ * active (e.g. running via `tsx`). The CLI itself does not depend
+ * on any TS compilation tool.
+ */
+export declare function loadStepsFromTs(filePath: string): Promise<ImportedStep[]>;
+//# sourceMappingURL=load-ts.d.ts.map

package/src/util/load-ts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-ts.d.ts","sourceRoot":"","sources":["../../../src/util/load-ts.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAiB/E"}

package/src/util/load-ts.js

@@ -0,0 +1,25 @@
+import { pathToFileURL } from "node:url";
+/**
+ * Dynamically import a TypeScript steps file and extract the
+ * steps array by duck-typing (looks for the first exported array
+ * whose elements have a `delayMs` property).
+ *
+ * Requires the caller's Node process to have a TypeScript loader
+ * active (e.g. running via `tsx`). The CLI itself does not depend
+ * on any TS compilation tool.
+ */
+export async function loadStepsFromTs(filePath) {
+    const mod = await import(pathToFileURL(filePath).href);
+    const exports = mod.default ?? mod;
+    for (const value of Object.values(exports)) {
+        if (Array.isArray(value) &&
+            value.length > 0 &&
+            typeof value[0] === "object" &&
+            value[0] !== null &&
+            "delayMs" in value[0]) {
+            return value;
+        }
+    }
+    throw new Error(`No steps array found in ${filePath}`);
+}
+//# sourceMappingURL=load-ts.js.map

package/src/util/load-ts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-ts.js","sourceRoot":"","sources":["../../../src/util/load-ts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAYzC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB;IACpD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC;IAEnC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3C,IACE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACpB,KAAK,CAAC,MAAM,GAAG,CAAC;YAChB,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ;YAC5B,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI;YACjB,SAAS,IAAI,KAAK,CAAC,CAAC,CAAC,EACrB,CAAC;YACD,OAAO,KAAuB,CAAC;QACjC,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,2BAA2B,QAAQ,EAAE,CAAC,CAAC;AACzD,CAAC"}

package/src/util/load-ts.ts

@@ -0,0 +1,39 @@
+import { pathToFileURL } from "node:url";
+
+/**
+ * Minimal shape extracted from each step object. The loader
+ * duck-types the exported array — any array of objects with
+ * `delayMs` qualifies as a steps array.
+ */
+export interface ImportedStep {
+  delayMs: number;
+  narration?: string;
+}
+
+/**
+ * Dynamically import a TypeScript steps file and extract the
+ * steps array by duck-typing (looks for the first exported array
+ * whose elements have a `delayMs` property).
+ *
+ * Requires the caller's Node process to have a TypeScript loader
+ * active (e.g. running via `tsx`). The CLI itself does not depend
+ * on any TS compilation tool.
+ */
+export async function loadStepsFromTs(filePath: string): Promise<ImportedStep[]> {
+  const mod = await import(pathToFileURL(filePath).href);
+  const exports = mod.default ?? mod;
+
+  for (const value of Object.values(exports)) {
+    if (
+      Array.isArray(value) &&
+      value.length > 0 &&
+      typeof value[0] === "object" &&
+      value[0] !== null &&
+      "delayMs" in value[0]
+    ) {
+      return value as ImportedStep[];
+    }
+  }
+
+  throw new Error(`No steps array found in ${filePath}`);
+}

package/src/util/narration-cache.d.ts

@@ -0,0 +1,24 @@
+interface CacheEntry {
+    hash: string;
+    durationMs: number;
+}
+interface CacheFile {
+    voice: string;
+    steps: (CacheEntry | null)[];
+}
+export declare function computeHash(narration: string, voice: string): string;
+export declare function loadCache(outputDir: string): Promise<CacheFile | null>;
+export declare function saveCache(outputDir: string, cache: CacheFile): Promise<void>;
+export declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * Check whether a step's narration is already cached (matching hash
+ * and the MP3 file still exists on disk).
+ */
+export declare function isCached(cache: CacheFile | null, stepIndex: number, hash: string, voice: string): boolean;
+export declare function getCachedDuration(cache: CacheFile, stepIndex: number): number;
+export declare function buildCacheFile(voice: string, totalSteps: number, entries: Map<number, {
+    hash: string;
+    durationMs: number;
+}>): CacheFile;
+export {};
+//# sourceMappingURL=narration-cache.d.ts.map

package/src/util/narration-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"narration-cache.d.ts","sourceRoot":"","sources":["../../../src/util/narration-cache.ts"],"names":[],"mappings":"AAIA,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,SAAS;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,CAAC,UAAU,GAAG,IAAI,CAAC,EAAE,CAAC;CAC9B;AAID,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAO5E;AAED,wBAAsB,SAAS,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,SAAS,GAAG,IAAI,EACvB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAIT;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,CAER;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GACzD,SAAS,CASX"}