@scenar/cli 0.1.20 → 0.2.0

package/src/commands/render.ts

@@ -1,11 +1,5 @@
-import { resolve, join } from "node:path";
-import { stat, mkdir, access, writeFile, rm } from "node:fs/promises";
-import { pathToFileURL } from "node:url";
 import { Command } from "commander";
-import { loadBundle, type CliBundle } from "../util/load-bundle.js";
-import { generateRemotionEntry } from "../render/generate-entry.js";
-import { resolveProvidersPath } from "../render/resolve-providers.js";
-import { detectRenderExport } from "../render/detect-render-export.js";
+import { runRender } from "../render/run-render.js";
 
 interface RenderOptions {
   out?: string;
@@ -22,13 +16,13 @@ export function registerRenderCommand(program: Command): void {
     .command("render")
     .description(
       "Render a scenario as an MP4 video using Remotion.\n\n" +
-      "Accepts a scenario directory containing steps.ts and an optional\n" +
-      "narration/ subfolder with manifest.json + audio clips.\n\n" +
-      "When the scenario directory contains an index.tsx that exports a\n" +
-      "renderStep function, the CLI auto-generates the Remotion entry\n" +
-      "point — no remotion/ directory or bundle.ts needed.\n\n" +
-      "Output defaults to ./<scenario-id>.mp4 in the current working\n" +
-      "directory. Use --out to write to a different path.",
+        "Accepts a scenario directory containing steps.ts and an optional\n" +
+        "narration/ subfolder with manifest.json + audio clips.\n\n" +
+        "When the scenario directory contains an index.tsx that exports a\n" +
+        "renderStep function, the CLI auto-generates the Remotion entry\n" +
+        "point — no remotion/ directory or bundle.ts needed.\n\n" +
+        "Output defaults to ./<scenario-id>.mp4 in the current working\n" +
+        "directory. Use --out to write to a different path.",
     )
     .argument("<dir>", "path to a scenario directory (must contain steps.ts)")
     .option("--out <path>", "output file path or directory for the MP4")
@@ -42,285 +36,24 @@ export function registerRenderCommand(program: Command): void {
       "path to a module that default-exports a Remotion WebpackOverrideFn",
     )
     .action(async (dir: string, options: RenderOptions) => {
-      const resolved = resolve(dir);
-
-      let info;
       try {
-        info = await stat(resolved);
-      } catch {
-        process.stderr.write(`\x1b[31mError:\x1b[0m ${dir} does not exist.\n`);
-        process.exitCode = 1;
-        return;
-      }
-
-      if (!info.isDirectory()) {
-        process.stderr.write(
-          `\x1b[31mError:\x1b[0m ${dir} is not a directory.\n` +
-          "The render command requires a scenario directory (with steps.ts).\n",
-        );
-        process.exitCode = 1;
-        return;
-      }
-
-      const fps = Number(options.fps) || 30;
-      const width = Number(options.width) || 1920;
-      const height = Number(options.height) || 1080;
-
-      let tempDir: string | undefined;
-
-      try {
-        const bundle = await loadBundle(resolved);
-        const scenarioId = bundle.id;
-        const compositionId = options.compositionId ?? scenarioId;
-        const outputPath = resolveOutputPath(options.out, scenarioId);
-
-        const { entryPoint, generated } = await resolveEntryPoint({
-          entryOption: options.entry,
-          scenarioDir: resolved,
-          scenarioId,
-          compositionId,
-          hasNarration: !!bundle.narrationManifest,
-          fps,
-          width,
-          height,
+        const result = await runRender({
+          scenarioDir: dir,
+          out: options.out,
+          fps: Number(options.fps) || 30,
+          width: Number(options.width) || 1920,
+          height: Number(options.height) || 1080,
+          compositionId: options.compositionId,
+          entry: options.entry,
+          webpackOverride: options.webpackOverride,
+          onLog: (message) => process.stderr.write(`${message}\n`),
         });
-        tempDir = generated?.tempDir;
-
-        const webpackOverride = options.webpackOverride
-          ? await loadWebpackOverride(options.webpackOverride)
-          : undefined;
-
-        process.stderr.write(`Scenario: ${scenarioId}\n`);
-        process.stderr.write(`Steps:    ${bundle.steps.length}\n`);
-        process.stderr.write(
-          `Audio:    ${bundle.narrationManifest ? "yes (manifest found)" : "none"}\n`,
-        );
-        process.stderr.write(`Entry:    ${generated ? "(auto-generated)" : entryPoint}\n`);
-        if (generated?.providersPath) {
-          process.stderr.write(`Providers: ${generated.providersPath}\n`);
-        }
-        if (webpackOverride) {
-          process.stderr.write(`Webpack:  custom override loaded\n`);
-        }
-        process.stderr.write(`Output:   ${outputPath}\n`);
-        process.stderr.write(`Config:   ${width}x${height} @ ${fps}fps\n\n`);
 
-        await renderScenario({
-          bundle,
-          entryPoint,
-          compositionId,
-          outputPath,
-          fps,
-          width,
-          height,
-          webpackOverride,
-        });
-
-        process.stderr.write(`\n\x1b[32m✓\x1b[0m Video saved to ${outputPath}\n`);
+        process.stderr.write(`\n\x1b[32m✓\x1b[0m Video saved to ${result.outputPath}\n`);
       } catch (error) {
         const msg = error instanceof Error ? error.message : String(error);
         process.stderr.write(`\x1b[31mError:\x1b[0m ${msg}\n`);
         process.exitCode = 1;
-      } finally {
-        if (tempDir) {
-          await rm(tempDir, { recursive: true, force: true }).catch(() => {});
-        }
       }
     });
 }
-
-// ---------------------------------------------------------------------------
-// Output path resolution
-// ---------------------------------------------------------------------------
-
-function resolveOutputPath(outOption: string | undefined, scenarioId: string): string {
-  if (!outOption) {
-    return resolve(`./${scenarioId}.mp4`);
-  }
-  if (outOption.endsWith(".mp4")) {
-    return resolve(outOption);
-  }
-  return resolve(join(outOption, `${scenarioId}.mp4`));
-}
-
-// ---------------------------------------------------------------------------
-// Entry point resolution
-// ---------------------------------------------------------------------------
-
-interface EntryResolutionInput {
-  entryOption: string | undefined;
-  scenarioDir: string;
-  scenarioId: string;
-  compositionId: string;
-  hasNarration: boolean;
-  fps: number;
-  width: number;
-  height: number;
-}
-
-interface EntryResolutionResult {
-  entryPoint: string;
-  generated?: {
-    tempDir: string;
-    providersPath: string | null;
-  };
-}
-
-async function resolveEntryPoint(
-  input: EntryResolutionInput,
-): Promise<EntryResolutionResult> {
-  // Explicit --entry: use as-is, no generation.
-  if (input.entryOption) {
-    const resolved = resolve(input.entryOption);
-    try {
-      await access(resolved);
-    } catch {
-      throw new Error(`Remotion entry point not found: ${input.entryOption}`);
-    }
-    return { entryPoint: resolved };
-  }
-
-  // Auto-generate: detect renderStep export, find providers, write temp entry.
-  const renderFilePath = await detectRenderExport(input.scenarioDir);
-  const providersPath = await resolveProvidersPath(input.scenarioDir);
-
-  const entrySource = generateRemotionEntry({
-    scenarioDir: input.scenarioDir,
-    renderFilePath,
-    scenarioId: input.scenarioId,
-    hasNarration: input.hasNarration,
-    providersPath,
-    fps: input.fps,
-    width: input.width,
-    height: input.height,
-    compositionId: input.compositionId,
-  });
-
-  // Write the entry inside the scenario directory so webpack's standard
-  // node_modules resolution walks up from here into the consumer project.
-  // A /tmp/ location would fail because no node_modules exist there.
-  const tempDir = join(input.scenarioDir, ".scenar-render");
-  await mkdir(tempDir, { recursive: true });
-
-  const entryPath = join(tempDir, "index.tsx");
-  await writeFile(entryPath, entrySource, "utf-8");
-
-  return {
-    entryPoint: entryPath,
-    generated: { tempDir, providersPath },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Webpack override loading
-// ---------------------------------------------------------------------------
-
-async function loadWebpackOverride(
-  overridePath: string,
-): Promise<(config: unknown) => unknown> {
-  const resolved = resolve(overridePath);
-
-  try {
-    await access(resolved);
-  } catch {
-    throw new Error(`Webpack override file not found: ${overridePath}`);
-  }
-
-  let mod: Record<string, unknown>;
-  try {
-    mod = await import(pathToFileURL(resolved).href) as Record<string, unknown>;
-  } catch (err) {
-    const detail = err instanceof Error ? err.message : String(err);
-    throw new Error(
-      `Failed to import webpack override from ${overridePath}:\n${detail}`,
-    );
-  }
-
-  const override = (mod.default ?? mod.webpackOverride) as unknown;
-  if (typeof override !== "function") {
-    throw new Error(
-      `${overridePath} does not export a webpack override function.\n\n` +
-      "Expected a default export or named 'webpackOverride' export:\n\n" +
-      '  import type { WebpackOverrideFn } from "@remotion/bundler";\n\n' +
-      "  const webpackOverride: WebpackOverrideFn = (config) => ({\n" +
-      "    ...config,\n" +
-      "    // your overrides\n" +
-      "  });\n\n" +
-      "  export default webpackOverride;\n",
-    );
-  }
-
-  return override as (config: unknown) => unknown;
-}
-
-// ---------------------------------------------------------------------------
-// Render orchestration
-// ---------------------------------------------------------------------------
-
-interface RenderConfig {
-  bundle: CliBundle;
-  entryPoint: string;
-  compositionId: string;
-  outputPath: string;
-  fps: number;
-  width: number;
-  height: number;
-  webpackOverride?: (config: unknown) => unknown;
-}
-
-async function renderScenario(config: RenderConfig): Promise<void> {
-  const bundler = await import("@remotion/bundler").catch(() => {
-    throw new Error(
-      "Could not load @remotion/bundler.\n" +
-      "Install it: pnpm add @remotion/bundler@4.0.448",
-    );
-  });
-
-  const renderer = await import("@remotion/renderer").catch(() => {
-    throw new Error(
-      "Could not load @remotion/renderer.\n" +
-      "Install it: pnpm add @remotion/renderer@4.0.448",
-    );
-  });
-
-  process.stderr.write("Bundling Remotion project...\n");
-
-  const bundleOptions: Record<string, unknown> = {
-    entryPoint: config.entryPoint,
-  };
-  if (config.webpackOverride) {
-    bundleOptions.webpackOverride = config.webpackOverride;
-  }
-  const serveUrl = await (bundler.bundle as (opts: Record<string, unknown>) => Promise<string>)(
-    bundleOptions,
-  );
-
-  process.stderr.write(`Selecting composition: ${config.compositionId}\n`);
-  const composition = await renderer.selectComposition({
-    serveUrl,
-    id: config.compositionId,
-  });
-
-  process.stderr.write(
-    `Composition: ${composition.width}x${composition.height} @ ${composition.fps}fps, ` +
-    `${composition.durationInFrames} frames ` +
-    `(${(composition.durationInFrames / composition.fps).toFixed(1)}s)\n`,
-  );
-
-  const outDir = resolve(config.outputPath, "..");
-  await mkdir(outDir, { recursive: true });
-
-  process.stderr.write("Rendering...\n");
-  await renderer.renderMedia({
-    composition,
-    serveUrl,
-    codec: "h264" as const,
-    outputLocation: config.outputPath,
-    onProgress: ({ progress }) => {
-      const pct = Math.round(progress * 100);
-      process.stderr.write(`\r  Progress: ${pct}%`);
-    },
-  });
-
-  process.stderr.write("\n");
-}

package/src/commands/serve.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerServeCommand(program: Command): void;
+//# sourceMappingURL=serve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../../src/commands/serve.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4D3D"}

package/src/commands/serve.js

@@ -0,0 +1,91 @@
+import { spawn } from "node:child_process";
+import { platform } from "node:process";
+import { runServe } from "../serve/run-serve.js";
+/** Vite's preview port — the conventional "serve a built site" port. */
+const DEFAULT_PORT = 4173;
+/** Bind to loopback by default; a preview is a single-developer tool. */
+const DEFAULT_HOST = "localhost";
+export function registerServeCommand(program) {
+    program
+        .command("serve")
+        .description("Serve a packed bundle locally and print its embed URL.\n\n" +
+        "Takes a bundle directory produced by `scenar pack` and serves it as a\n" +
+        "static site on http://localhost:4173 (override with --port/--host).\n" +
+        "Prints the URL plus a ready-to-paste responsive <iframe> snippet, then\n" +
+        "stays running until you press Ctrl+C.\n\n" +
+        "This is the zero-infrastructure way to view an embed: no backend, no\n" +
+        "account. For a permanent public URL, use `scenar publish` (GitHub\n" +
+        "Pages) or `scenar deploy` (Scenar Cloud).")
+        .argument("<bundleDir>", "path to a packed bundle directory (from scenar pack)")
+        .option("--port <number>", `port to listen on (default: ${DEFAULT_PORT})`, String(DEFAULT_PORT))
+        .option("--host <host>", `host/interface to bind (default: ${DEFAULT_HOST})`, DEFAULT_HOST)
+        .option("--open", "open the embed in your default browser")
+        .action(async (bundleDir, options) => {
+        try {
+            const port = Number(options.port);
+            if (!Number.isInteger(port) || port < 0 || port > 65535) {
+                throw new Error(`invalid --port "${options.port}"; expected an integer between 0 and 65535.`);
+            }
+            const host = options.host ?? DEFAULT_HOST;
+            let result;
+            try {
+                result = await runServe({ bundleDir, port, host });
+            }
+            catch (error) {
+                if (isAddrInUse(error)) {
+                    throw new Error(`port ${port} is already in use. Stop the other process or pass --port <number>.`);
+                }
+                throw error;
+            }
+            process.stderr.write(`\n\x1b[32m✓\x1b[0m Serving at ${result.url}\n`);
+            if (!result.recordedViewport) {
+                process.stderr.write("  Note: no recorded viewport; snippet uses the default " +
+                    `${result.viewport.width}x${result.viewport.height}. Re-pack with the current CLI ` +
+                    "to embed at the exact aspect ratio.\n");
+            }
+            process.stderr.write("\n  Embed snippet (paste into any page):\n\n");
+            process.stderr.write(`${indent(result.snippet)}\n`);
+            process.stderr.write("\n  Press Ctrl+C to stop.\n");
+            if (options.open) {
+                openInBrowser(result.url);
+            }
+            await runUntilInterrupted(result.handle);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`\x1b[31mError:\x1b[0m ${msg}\n`);
+            process.exitCode = 1;
+        }
+    });
+}
+/** Block until SIGINT/SIGTERM, then close the server cleanly. */
+function runUntilInterrupted(handle) {
+    return new Promise((resolvePromise) => {
+        const shutdown = () => {
+            process.stderr.write("\nStopping...\n");
+            void handle.close().finally(() => resolvePromise());
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+    });
+}
+/** Best-effort: launch the OS default browser. Failures are silent (non-fatal). */
+function openInBrowser(url) {
+    const command = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+    try {
+        const child = spawn(command, [url], { stdio: "ignore", detached: true, shell: platform === "win32" });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // Opening a browser is a convenience; never fail the command over it.
+    }
+}
+function isAddrInUse(error) {
+    return typeof error === "object" && error !== null && error.code === "EADDRINUSE";
+}
+/** Indent every line by two spaces (for nesting a block under a heading). */
+function indent(block) {
+    return block.replace(/^/gm, "  ");
+}
+//# sourceMappingURL=serve.js.map

package/src/commands/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../../src/commands/serve.ts"],"names":[],"mappings":"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"}

package/src/commands/serve.ts

@@ -0,0 +1,112 @@
+import { spawn } from "node:child_process";
+import { platform } from "node:process";
+import { Command } from "commander";
+import { runServe } from "../serve/run-serve.js";
+import type { BundleServerHandle } from "../serve/static-server.js";
+
+/** Vite's preview port — the conventional "serve a built site" port. */
+const DEFAULT_PORT = 4173;
+
+/** Bind to loopback by default; a preview is a single-developer tool. */
+const DEFAULT_HOST = "localhost";
+
+interface ServeOptions {
+  port?: string;
+  host?: string;
+  open?: boolean;
+}
+
+export function registerServeCommand(program: Command): void {
+  program
+    .command("serve")
+    .description(
+      "Serve a packed bundle locally and print its embed URL.\n\n" +
+        "Takes a bundle directory produced by `scenar pack` and serves it as a\n" +
+        "static site on http://localhost:4173 (override with --port/--host).\n" +
+        "Prints the URL plus a ready-to-paste responsive <iframe> snippet, then\n" +
+        "stays running until you press Ctrl+C.\n\n" +
+        "This is the zero-infrastructure way to view an embed: no backend, no\n" +
+        "account. For a permanent public URL, use `scenar publish` (GitHub\n" +
+        "Pages) or `scenar deploy` (Scenar Cloud).",
+    )
+    .argument("<bundleDir>", "path to a packed bundle directory (from scenar pack)")
+    .option("--port <number>", `port to listen on (default: ${DEFAULT_PORT})`, String(DEFAULT_PORT))
+    .option("--host <host>", `host/interface to bind (default: ${DEFAULT_HOST})`, DEFAULT_HOST)
+    .option("--open", "open the embed in your default browser")
+    .action(async (bundleDir: string, options: ServeOptions) => {
+      try {
+        const port = Number(options.port);
+        if (!Number.isInteger(port) || port < 0 || port > 65535) {
+          throw new Error(`invalid --port "${options.port}"; expected an integer between 0 and 65535.`);
+        }
+        const host = options.host ?? DEFAULT_HOST;
+
+        let result;
+        try {
+          result = await runServe({ bundleDir, port, host });
+        } catch (error) {
+          if (isAddrInUse(error)) {
+            throw new Error(
+              `port ${port} is already in use. Stop the other process or pass --port <number>.`,
+            );
+          }
+          throw error;
+        }
+
+        process.stderr.write(`\n\x1b[32m✓\x1b[0m Serving at ${result.url}\n`);
+        if (!result.recordedViewport) {
+          process.stderr.write(
+            "  Note: no recorded viewport; snippet uses the default " +
+              `${result.viewport.width}x${result.viewport.height}. Re-pack with the current CLI ` +
+              "to embed at the exact aspect ratio.\n",
+          );
+        }
+        process.stderr.write("\n  Embed snippet (paste into any page):\n\n");
+        process.stderr.write(`${indent(result.snippet)}\n`);
+        process.stderr.write("\n  Press Ctrl+C to stop.\n");
+
+        if (options.open) {
+          openInBrowser(result.url);
+        }
+
+        await runUntilInterrupted(result.handle);
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`\x1b[31mError:\x1b[0m ${msg}\n`);
+        process.exitCode = 1;
+      }
+    });
+}
+
+/** Block until SIGINT/SIGTERM, then close the server cleanly. */
+function runUntilInterrupted(handle: BundleServerHandle): Promise<void> {
+  return new Promise<void>((resolvePromise) => {
+    const shutdown = () => {
+      process.stderr.write("\nStopping...\n");
+      void handle.close().finally(() => resolvePromise());
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+  });
+}
+
+/** Best-effort: launch the OS default browser. Failures are silent (non-fatal). */
+function openInBrowser(url: string): void {
+  const command = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+  try {
+    const child = spawn(command, [url], { stdio: "ignore", detached: true, shell: platform === "win32" });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // Opening a browser is a convenience; never fail the command over it.
+  }
+}
+
+function isAddrInUse(error: unknown): boolean {
+  return typeof error === "object" && error !== null && (error as { code?: string }).code === "EADDRINUSE";
+}
+
+/** Indent every line by two spaces (for nesting a block under a heading). */
+function indent(block: string): string {
+  return block.replace(/^/gm, "  ");
+}

package/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,wBAAgB,aAAa,IAAI,OAAO,CAgBvC;AAED,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAGxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,wBAAgB,aAAa,IAAI,OAAO,CAkBvC;AAED,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAGxC"}

package/src/index.js

@@ -4,6 +4,8 @@ import { registerNarrateCommand } from "./commands/narrate.js";
 import { registerPreviewCommand } from "./commands/preview.js";
 import { registerRenderCommand } from "./commands/render.js";
 import { registerPackCommand } from "./commands/pack.js";
+import { registerServeCommand } from "./commands/serve.js";
+import { registerPublishCommand } from "./commands/publish.js";
 import { registerDeployCommand } from "./commands/deploy.js";
 export function createProgram() {
     const program = new Command();
@@ -16,6 +18,8 @@ export function createProgram() {
     registerRenderCommand(program);
     registerPreviewCommand(program);
     registerPackCommand(program);
+    registerServeCommand(program);
+    registerPublishCommand(program);
     registerDeployCommand(program);
     return 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;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,QAAQ,CAAC;SACd,WAAW,CAAC,8FAA8F,CAAC;SAC3G,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE/B,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;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,QAAQ,CAAC;SACd,WAAW,CAAC,8FAA8F,CAAC;SAC3G,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE/B,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

@@ -4,6 +4,8 @@ import { registerNarrateCommand } from "./commands/narrate.js";
 import { registerPreviewCommand } from "./commands/preview.js";
 import { registerRenderCommand } from "./commands/render.js";
 import { registerPackCommand } from "./commands/pack.js";
+import { registerServeCommand } from "./commands/serve.js";
+import { registerPublishCommand } from "./commands/publish.js";
 import { registerDeployCommand } from "./commands/deploy.js";
 
 export function createProgram(): Command {
@@ -19,6 +21,8 @@ export function createProgram(): Command {
   registerRenderCommand(program);
   registerPreviewCommand(program);
   registerPackCommand(program);
+  registerServeCommand(program);
+  registerPublishCommand(program);
   registerDeployCommand(program);
 
   return program;

package/src/narrate/run-narrate.d.ts

@@ -0,0 +1,43 @@
+/** Options for {@link runNarrate}. Paths may be relative; resolved here. */
+export interface RunNarrateOptions {
+    /** A scenario YAML file, a .ts steps file, or a directory of scenarios. */
+    readonly target: string;
+    /** TTS provider name: echogarden, edge-tts, or openai (default echogarden). */
+    readonly tts?: string;
+    /** Output directory for audio (default: alongside the scenario). */
+    readonly out?: string;
+    /** Voice name (provider-specific). */
+    readonly voice?: string;
+    /** URL path prefix for the `src` fields written into the manifest. */
+    readonly baseUrl?: string;
+    /** Progress sink for per-step/per-scenario messages. */
+    readonly onLog?: (message: string) => void;
+}
+/** Per-scenario narration outcome. */
+export interface NarratedScenario {
+    readonly id: string;
+    readonly generated: number;
+    readonly cached: number;
+    /** True when the scenario had no narration text (nothing to synthesize). */
+    readonly skipped: boolean;
+}
+/** Aggregate result of a narrate run. */
+export interface NarrateResult {
+    readonly mode: "file" | "directory";
+    readonly scenarios: NarratedScenario[];
+    readonly totalGenerated: number;
+    readonly totalCached: number;
+    readonly totalSkipped: number;
+    readonly errors: Array<{
+        id: string;
+        message: string;
+    }>;
+}
+/**
+ * Generate narration audio for a scenario file or a directory of scenarios —
+ * the pure orchestration behind `scenar narrate`. Resolves the TTS provider,
+ * synthesizes per-step audio (incremental via a content-hash cache), writes each
+ * scenario's manifest, and returns aggregate stats. No process/exit coupling.
+ */
+export declare function runNarrate(options: RunNarrateOptions): Promise<NarrateResult>;
+//# sourceMappingURL=run-narrate.d.ts.map

package/src/narrate/run-narrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-narrate.d.ts","sourceRoot":"","sources":["../../../src/narrate/run-narrate.ts"],"names":[],"mappings":"AAkBA,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,gBAAgB,EAAE,CAAC;IACvC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzD;AAkID;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CASnF"}