@scenar/cli 0.1.20-rc.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenar/cli",
-  "version": "0.1.20-rc.1",
+  "version": "0.2.0",
   "description": "Scenar CLI — validate scenarios, generate narration, and render videos.",
   "license": "Apache-2.0",
   "type": "module",
@@ -26,14 +26,26 @@
   },
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./api": {
+      "types": "./src/api.d.ts",
+      "import": "./src/api.js",
+      "default": "./src/api.js"
+    }
+  },
   "dependencies": {
     "@bufbuild/protobuf": "^2.2.2",
     "@connectrpc/connect": "^2.0.0",
     "@connectrpc/connect-node": "^2.0.0",
-    "@scenar/core": "0.1.20-rc.1",
-    "@scenar/preview": "0.1.20-rc.1",
-    "@scenar/sdk": "0.1.20-rc.1",
-    "@scenar/stubs": "0.1.20-rc.1",
+    "@scenar/core": "0.2.0",
+    "@scenar/preview": "0.2.0",
+    "@scenar/sdk": "0.2.0",
+    "@scenar/stubs": "0.2.0",
     "commander": "^13.0.0",
     "yaml": "^2.7.0"
   },

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

@@ -0,0 +1,46 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createProgram } from "../index.js";
+
+describe("scenar publish", () => {
+  let stderrOutput: string;
+
+  beforeEach(() => {
+    stderrOutput = "";
+    vi.spyOn(process.stderr, "write").mockImplementation((chunk) => {
+      stderrOutput += String(chunk);
+      return true;
+    });
+    process.exitCode = undefined;
+  });
+
+  it("registers the publish command", () => {
+    const program = createProgram();
+    const cmd = program.commands.find((c) => c.name() === "publish");
+    expect(cmd).toBeDefined();
+    expect(cmd!.description()).toContain("GitHub Pages");
+  });
+
+  it("accepts a bundle directory argument and exposes its options", () => {
+    const program = createProgram();
+    const cmd = program.commands.find((c) => c.name() === "publish");
+    expect(cmd!.registeredArguments[0]!.name()).toBe("bundleDir");
+    const opts = cmd!.options.map((o) => o.long);
+    expect(opts).toContain("--repo");
+    expect(opts).toContain("--path");
+    expect(opts).toContain("--org");
+    expect(opts).toContain("--private");
+    expect(opts).toContain("--message");
+  });
+
+  it("fails clearly when the bundle directory does not exist (no GitHub calls)", async () => {
+    const program = createProgram();
+    program.exitOverride();
+    try {
+      await program.parseAsync(["node", "scenar", "publish", "/tmp/__no_bundle__"]);
+    } catch {
+      // exitOverride throws on non-zero exit; assert on exitCode below.
+    }
+    expect(process.exitCode).toBe(1);
+    expect(stderrOutput).toContain("Error");
+  });
+});

package/src/__tests__/publish-flow.test.ts

@@ -0,0 +1,220 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  runPublishFlow,
+  validateRepoName,
+  validatePublishPath,
+  normalizePath,
+  pagesUrl,
+  repoUrl,
+  type PublishFlowDeps,
+} from "../publish/publish-flow.js";
+
+/** A deps double whose every method records its call order. */
+function makeDeps(overrides: Partial<PublishFlowDeps> = {}): {
+  deps: PublishFlowDeps;
+  calls: string[];
+} {
+  const calls: string[] = [];
+  const deps: PublishFlowDeps = {
+    ensureToolsAvailable: vi.fn(async () => {
+      calls.push("ensureTools");
+    }),
+    resolveOwner: vi.fn(async (org) => {
+      calls.push(`resolveOwner:${org ?? "<user>"}`);
+      return org ?? "octocat";
+    }),
+    repoExists: vi.fn(async () => {
+      calls.push("repoExists");
+      return false;
+    }),
+    createRepo: vi.fn(async (_owner, _repo, opts) => {
+      calls.push(`createRepo:${opts.private ? "private" : "public"}`);
+    }),
+    pushBundleToPages: vi.fn(async () => {
+      calls.push("push");
+    }),
+    enablePages: vi.fn(async () => {
+      calls.push("enablePages");
+    }),
+    log: () => {},
+    ...overrides,
+  };
+  return { deps, calls };
+}
+
+describe("runPublishFlow", () => {
+  it("creates a new repo, pushes, and enables pages in order", async () => {
+    const { deps, calls } = makeDeps();
+    const result = await runPublishFlow(deps, {
+      bundleDir: "/tmp/bundle",
+      repo: "welcome-tour",
+      path: "",
+      private: false,
+      message: "Publish Scenar embed",
+    });
+
+    expect(calls).toEqual([
+      "ensureTools",
+      "resolveOwner:<user>",
+      "repoExists",
+      "createRepo:public",
+      "push",
+      "enablePages",
+    ]);
+    expect(result).toEqual({
+      owner: "octocat",
+      repo: "welcome-tour",
+      path: "",
+      repoUrl: "https://github.com/octocat/welcome-tour",
+      pagesUrl: "https://octocat.github.io/welcome-tour/",
+      created: true,
+    });
+  });
+
+  it("publishes into a subpath and reflects it in the URL + push payload", async () => {
+    const { deps } = makeDeps({ repoExists: vi.fn(async () => true) });
+    const result = await runPublishFlow(deps, {
+      bundleDir: "/tmp/bundle",
+      repo: "scenar-embeds",
+      path: "welcome-tour",
+      private: false,
+      message: "m",
+    });
+
+    expect(deps.pushBundleToPages).toHaveBeenCalledWith(
+      expect.objectContaining({ repo: "scenar-embeds", path: "welcome-tour" }),
+    );
+    expect(result.path).toBe("welcome-tour");
+    expect(result.pagesUrl).toBe("https://octocat.github.io/scenar-embeds/welcome-tour/");
+  });
+
+  it("reuses an existing repo (no create) and reports created: false", async () => {
+    const { deps, calls } = makeDeps({
+      repoExists: vi.fn(async () => {
+        calls.push("repoExists");
+        return true;
+      }),
+    });
+    // calls array is the one closed over by the override too.
+    const result = await runPublishFlow(deps, {
+      bundleDir: "/tmp/bundle",
+      repo: "welcome-tour",
+      path: "",
+      private: false,
+      message: "m",
+    });
+    expect(deps.createRepo).not.toHaveBeenCalled();
+    expect(result.created).toBe(false);
+  });
+
+  it("passes the org through as the owner and creates a private repo when asked", async () => {
+    const { deps } = makeDeps();
+    const result = await runPublishFlow(deps, {
+      bundleDir: "/tmp/bundle",
+      repo: "demo",
+      path: "",
+      org: "acme-inc",
+      private: true,
+      message: "m",
+    });
+    expect(deps.resolveOwner).toHaveBeenCalledWith("acme-inc");
+    expect(deps.createRepo).toHaveBeenCalledWith(
+      "acme-inc",
+      "demo",
+      expect.objectContaining({ private: true }),
+    );
+    expect(result.owner).toBe("acme-inc");
+    expect(result.pagesUrl).toBe("https://acme-inc.github.io/demo/");
+  });
+
+  it("does not push or enable pages if tooling is unavailable", async () => {
+    const { deps } = makeDeps({
+      ensureToolsAvailable: vi.fn(async () => {
+        throw new Error("gh not installed");
+      }),
+    });
+    await expect(
+      runPublishFlow(deps, { bundleDir: "/x", repo: "r", path: "", private: false, message: "m" }),
+    ).rejects.toThrow(/gh not installed/);
+    expect(deps.pushBundleToPages).not.toHaveBeenCalled();
+    expect(deps.enablePages).not.toHaveBeenCalled();
+  });
+});
+
+describe("pagesUrl", () => {
+  it("serves a normal repo under its name as a path", () => {
+    expect(pagesUrl("octocat", "welcome-tour")).toBe("https://octocat.github.io/welcome-tour/");
+  });
+
+  it("lowercases the owner in the host", () => {
+    expect(pagesUrl("OctoCat", "demo")).toBe("https://octocat.github.io/demo/");
+  });
+
+  it("serves the user/org site repo at the apex", () => {
+    expect(pagesUrl("octocat", "octocat.github.io")).toBe("https://octocat.github.io/");
+  });
+
+  it("appends a non-empty subpath", () => {
+    expect(pagesUrl("octocat", "scenar-embeds", "welcome-tour")).toBe(
+      "https://octocat.github.io/scenar-embeds/welcome-tour/",
+    );
+  });
+
+  it("appends a subpath under the user/org site repo too", () => {
+    expect(pagesUrl("octocat", "octocat.github.io", "tour")).toBe(
+      "https://octocat.github.io/tour/",
+    );
+  });
+
+  it("ignores an empty/root path", () => {
+    expect(pagesUrl("octocat", "demo", "")).toBe("https://octocat.github.io/demo/");
+    expect(pagesUrl("octocat", "demo", "/")).toBe("https://octocat.github.io/demo/");
+  });
+});
+
+describe("normalizePath", () => {
+  it("strips leading/trailing/doubled slashes and dots", () => {
+    expect(normalizePath("/welcome-tour/")).toBe("welcome-tour");
+    expect(normalizePath("a//b/")).toBe("a/b");
+    expect(normalizePath("/")).toBe("");
+    expect(normalizePath(".")).toBe("");
+    expect(normalizePath(undefined)).toBe("");
+  });
+});
+
+describe("validatePublishPath", () => {
+  it("accepts root and safe segments", () => {
+    expect(validatePublishPath("")).toBeNull();
+    expect(validatePublishPath("welcome-tour")).toBeNull();
+    expect(validatePublishPath("demos/v2")).toBeNull();
+  });
+
+  it("rejects traversal and illegal characters", () => {
+    expect(validatePublishPath("..")).toMatch(/\.\./);
+    expect(validatePublishPath("a/../b")).toMatch(/\.\./);
+    expect(validatePublishPath("has space")).toMatch(/invalid path segment/);
+  });
+});
+
+describe("repoUrl", () => {
+  it("builds the repository web URL", () => {
+    expect(repoUrl("octocat", "demo")).toBe("https://github.com/octocat/demo");
+  });
+});
+
+describe("validateRepoName", () => {
+  it("accepts valid names", () => {
+    expect(validateRepoName("welcome-tour")).toBeNull();
+    expect(validateRepoName("my_demo.embed")).toBeNull();
+    expect(validateRepoName("a")).toBeNull();
+  });
+
+  it("rejects empty, over-long, dot, and illegal-character names", () => {
+    expect(validateRepoName("")).toMatch(/1-100/);
+    expect(validateRepoName("x".repeat(101))).toMatch(/1-100/);
+    expect(validateRepoName(".")).toMatch(/"\."/);
+    expect(validateRepoName("..")).toMatch(/"\."/);
+    expect(validateRepoName("has space")).toMatch(/invalid repo name/);
+    expect(validateRepoName("slash/name")).toMatch(/invalid repo name/);
+  });
+});

package/src/__tests__/read-viewport.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readBundleViewport } from "../bundle/read-viewport.js";
+import { DEFAULT_VIEWPORT } from "../pack/viewport.js";
+
+describe("readBundleViewport", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "scenar-viewport-"));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it("reads the recorded viewport from scenario.json", async () => {
+    await writeFile(
+      join(dir, "scenario.json"),
+      JSON.stringify({ schemaVersion: "1", id: "x", viewport: { width: 1280, height: 720 } }),
+      "utf-8",
+    );
+    expect(await readBundleViewport(dir)).toEqual({
+      viewport: { width: 1280, height: 720 },
+      recorded: true,
+    });
+  });
+
+  it("falls back to the default when scenario.json is absent", async () => {
+    expect(await readBundleViewport(dir)).toEqual({
+      viewport: DEFAULT_VIEWPORT,
+      recorded: false,
+    });
+  });
+
+  it("falls back to the default when the viewport is missing or malformed", async () => {
+    await writeFile(join(dir, "scenario.json"), JSON.stringify({ schemaVersion: "1" }), "utf-8");
+    expect(await readBundleViewport(dir)).toEqual({ viewport: DEFAULT_VIEWPORT, recorded: false });
+
+    await writeFile(join(dir, "scenario.json"), "{ not json", "utf-8");
+    expect(await readBundleViewport(dir)).toEqual({ viewport: DEFAULT_VIEWPORT, recorded: false });
+  });
+});

package/src/__tests__/run-publish.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runPublish } from "../publish/run-publish.js";
+import type { PublishFlowDeps } from "../publish/publish-flow.js";
+
+/** Fake gh/git deps: record calls, never touch the network. */
+function fakeDeps(): Omit<PublishFlowDeps, "log"> {
+  return {
+    ensureToolsAvailable: vi.fn(async () => {}),
+    resolveOwner: vi.fn(async (org) => org ?? "octocat"),
+    repoExists: vi.fn(async () => false),
+    createRepo: vi.fn(async () => {}),
+    pushBundleToPages: vi.fn(async () => {}),
+    enablePages: vi.fn(async () => {}),
+  };
+}
+
+describe("runPublish", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "scenar-publish-bundle-"));
+    await writeFile(join(dir, "index.html"), "<!doctype html><title>t</title>", "utf-8");
+    await writeFile(
+      join(dir, "scenario.json"),
+      JSON.stringify({ schemaVersion: "1", id: "welcome-tour", viewport: { width: 896, height: 480 } }),
+      "utf-8",
+    );
+    await writeFile(
+      join(dir, "pack-manifest.json"),
+      JSON.stringify({ schemaVersion: 1, scenarioId: "welcome-tour", files: [{ path: "index.html", sha256: "a".repeat(64), sizeBytes: 30, contentType: "text/html" }] }),
+      "utf-8",
+    );
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it("defaults to the shared repo + scenario-slug subpath and returns the URL + snippet", async () => {
+    const deps = fakeDeps();
+    const { result, snippet, recordedViewport } = await runPublish({ bundleDir: dir, deps });
+
+    expect(result.repo).toBe("scenar-embeds");
+    expect(result.path).toBe("welcome-tour");
+    expect(result.pagesUrl).toBe("https://octocat.github.io/scenar-embeds/welcome-tour/");
+    expect(deps.createRepo).toHaveBeenCalledWith(
+      "octocat",
+      "scenar-embeds",
+      expect.objectContaining({ private: false }),
+    );
+    expect(deps.pushBundleToPages).toHaveBeenCalledWith(
+      expect.objectContaining({ path: "welcome-tour" }),
+    );
+    expect(recordedViewport).toBe(true);
+    expect(snippet).toContain("https://octocat.github.io/scenar-embeds/welcome-tour/");
+    expect(snippet).toContain("aspect-ratio:896/480");
+  });
+
+  it("honors an explicit repo + org, defaulting the path to the slug", async () => {
+    const deps = fakeDeps();
+    const { result } = await runPublish({ bundleDir: dir, repo: "tours", org: "stigmer", deps });
+    expect(result.pagesUrl).toBe("https://stigmer.github.io/tours/welcome-tour/");
+  });
+
+  it("publishes at the repo root when --path is /", async () => {
+    const deps = fakeDeps();
+    const { result } = await runPublish({ bundleDir: dir, repo: "scenar-welcome-tour", org: "stigmer", path: "/", deps });
+    expect(result.path).toBe("");
+    expect(result.pagesUrl).toBe("https://stigmer.github.io/scenar-welcome-tour/");
+    expect(deps.pushBundleToPages).toHaveBeenCalledWith(expect.objectContaining({ path: "" }));
+  });
+
+  it("rejects an invalid explicit path before any GitHub call", async () => {
+    const deps = fakeDeps();
+    await expect(runPublish({ bundleDir: dir, path: "../escape", deps })).rejects.toThrow(/\.\./);
+    expect(deps.ensureToolsAvailable).not.toHaveBeenCalled();
+  });
+
+  it("rejects an invalid explicit repo name before any GitHub call", async () => {
+    const deps = fakeDeps();
+    await expect(runPublish({ bundleDir: dir, repo: "bad name", deps })).rejects.toThrow(/invalid repo name/);
+    expect(deps.ensureToolsAvailable).not.toHaveBeenCalled();
+  });
+
+  it("fails clearly when the bundle has no index.html", async () => {
+    await rm(join(dir, "index.html"));
+    await expect(runPublish({ bundleDir: dir, deps: fakeDeps() })).rejects.toThrow(/no index\.html/);
+  });
+});

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

@@ -0,0 +1,44 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createProgram } from "../index.js";
+
+describe("scenar serve", () => {
+  let stderrOutput: string;
+
+  beforeEach(() => {
+    stderrOutput = "";
+    vi.spyOn(process.stderr, "write").mockImplementation((chunk) => {
+      stderrOutput += String(chunk);
+      return true;
+    });
+    process.exitCode = undefined;
+  });
+
+  it("registers the serve command", () => {
+    const program = createProgram();
+    const cmd = program.commands.find((c) => c.name() === "serve");
+    expect(cmd).toBeDefined();
+    expect(cmd!.description()).toContain("embed URL");
+  });
+
+  it("accepts a bundle directory argument and exposes its options", () => {
+    const program = createProgram();
+    const cmd = program.commands.find((c) => c.name() === "serve");
+    expect(cmd!.registeredArguments[0]!.name()).toBe("bundleDir");
+    const opts = cmd!.options.map((o) => o.long);
+    expect(opts).toContain("--port");
+    expect(opts).toContain("--host");
+    expect(opts).toContain("--open");
+  });
+
+  it("fails clearly when the bundle directory does not exist", async () => {
+    const program = createProgram();
+    program.exitOverride();
+    try {
+      await program.parseAsync(["node", "scenar", "serve", "/tmp/__no_bundle__"]);
+    } catch {
+      // exitOverride throws on a non-zero exit; the assertion is on exitCode.
+    }
+    expect(process.exitCode).toBe(1);
+    expect(stderrOutput).toContain("Error");
+  });
+});

package/src/__tests__/serve-request-path.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { resolveStaticPath, contentTypeFor } from "../serve/request-path.js";
+
+describe("resolveStaticPath", () => {
+  it("maps the root and trailing-slash paths to index.html", () => {
+    expect(resolveStaticPath("/")).toBe("index.html");
+    expect(resolveStaticPath("/sub/")).toBe("sub/index.html");
+  });
+
+  it("returns clean relative paths for file requests", () => {
+    expect(resolveStaticPath("/assets/index-abc.js")).toBe("assets/index-abc.js");
+    expect(resolveStaticPath("/scenario.json")).toBe("scenario.json");
+    expect(resolveStaticPath("/narration/step-0.mp3")).toBe("narration/step-0.mp3");
+  });
+
+  it("strips a query string and fragment", () => {
+    expect(resolveStaticPath("/assets/app.js?v=2")).toBe("assets/app.js");
+    expect(resolveStaticPath("/index.html#top")).toBe("index.html");
+  });
+
+  it("percent-decodes path segments", () => {
+    expect(resolveStaticPath("/assets/logo%20art.png")).toBe("assets/logo art.png");
+  });
+
+  it("rejects parent-directory traversal in every form", () => {
+    expect(resolveStaticPath("/../secret")).toBeNull();
+    expect(resolveStaticPath("/assets/../../etc/passwd")).toBeNull();
+    expect(resolveStaticPath("/%2e%2e/secret")).toBeNull();
+    expect(resolveStaticPath("/foo/%2e%2e/%2e%2e/bar")).toBeNull();
+  });
+
+  it("rejects current-dir and empty (double-slash) segments", () => {
+    expect(resolveStaticPath("/./foo")).toBeNull();
+    expect(resolveStaticPath("/foo//bar")).toBeNull();
+  });
+
+  it("rejects backslash and NUL injection", () => {
+    expect(resolveStaticPath("/..\\windows")).toBeNull();
+    expect(resolveStaticPath("/foo\u0000.js")).toBeNull();
+  });
+
+  it("rejects malformed percent-encoding", () => {
+    expect(resolveStaticPath("/%zz")).toBeNull();
+  });
+
+  it("rejects non-absolute paths", () => {
+    expect(resolveStaticPath("relative")).toBeNull();
+    expect(resolveStaticPath("")).toBeNull();
+  });
+});
+
+describe("contentTypeFor", () => {
+  it("resolves canonical bundle content types by extension", () => {
+    expect(contentTypeFor("index.html")).toBe("text/html");
+    expect(contentTypeFor("assets/app.js")).toBe("text/javascript");
+    expect(contentTypeFor("assets/style.css")).toBe("text/css");
+    expect(contentTypeFor("scenario.json")).toBe("application/json");
+    expect(contentTypeFor("narration/step-0.mp3")).toBe("audio/mpeg");
+    expect(contentTypeFor("assets/logo.png")).toBe("image/png");
+    expect(contentTypeFor("fonts/inter.woff2")).toBe("font/woff2");
+  });
+
+  it("falls back to application/octet-stream for unknown extensions", () => {
+    expect(contentTypeFor("data.bin")).toBe("application/octet-stream");
+    expect(contentTypeFor("noext")).toBe("application/octet-stream");
+  });
+});

package/src/__tests__/serve-static-server.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { request } from "node:http";
+import { startBundleServer, type BundleServerHandle } from "../serve/static-server.js";
+
+/**
+ * Issue a GET with a verbatim request path. Unlike fetch/URL, node:http does not
+ * normalise the path, so an encoded "%2e%2e" traversal reaches the server intact
+ * — exactly what an attacker would send. Returns the response status code.
+ */
+function rawGetStatus(baseUrl: string, rawPath: string): Promise<number> {
+  const base = new URL(baseUrl);
+  return new Promise<number>((resolvePromise, reject) => {
+    const req = request(
+      { hostname: base.hostname, port: base.port, path: rawPath, method: "GET" },
+      (res) => {
+        res.resume();
+        resolvePromise(res.statusCode ?? 0);
+      },
+    );
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+describe("startBundleServer", () => {
+  let dir: string;
+  let server: BundleServerHandle;
+
+  beforeAll(async () => {
+    dir = await mkdtemp(join(tmpdir(), "scenar-serve-"));
+    await writeFile(join(dir, "index.html"), "<!doctype html><title>tour</title>", "utf-8");
+    await mkdir(join(dir, "assets"), { recursive: true });
+    await writeFile(join(dir, "assets", "app.js"), "console.log(1)", "utf-8");
+    // Port 0 → the OS assigns a free port (no fixed-port collisions in CI).
+    server = await startBundleServer({ rootDir: dir, port: 0 });
+  });
+
+  afterAll(async () => {
+    await server.close();
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it("serves index.html at the root with the right content type", async () => {
+    const res = await fetch(server.url);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("text/html");
+    expect(await res.text()).toContain("<title>tour</title>");
+  });
+
+  it("serves nested assets with the right content type", async () => {
+    const res = await fetch(new URL("assets/app.js", server.url));
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("text/javascript");
+    expect(await res.text()).toBe("console.log(1)");
+  });
+
+  it("sets Cache-Control: no-cache so a preview never serves stale assets", async () => {
+    const res = await fetch(server.url);
+    expect(res.headers.get("cache-control")).toBe("no-cache");
+  });
+
+  it("returns 404 for a missing file", async () => {
+    const res = await fetch(new URL("does-not-exist.js", server.url));
+    expect(res.status).toBe(404);
+  });
+
+  it("answers HEAD with headers but no body", async () => {
+    const res = await fetch(server.url, { method: "HEAD" });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("text/html");
+    expect(await res.text()).toBe("");
+  });
+
+  it("rejects non-GET/HEAD methods with 405", async () => {
+    const res = await fetch(server.url, { method: "POST" });
+    expect(res.status).toBe(405);
+    expect(res.headers.get("allow")).toBe("GET, HEAD");
+  });
+
+  it("rejects a raw encoded traversal attempt with 400 (never reaches disk)", async () => {
+    // Sent verbatim via node:http so the "%2e%2e" survives to the server.
+    expect(await rawGetStatus(server.url, "/%2e%2e/%2e%2e/secret")).toBe(400);
+    expect(await rawGetStatus(server.url, "/assets/%2e%2e/%2e%2e/etc/passwd")).toBe(400);
+  });
+});

package/src/api.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The programmatic API of the Scenar CLI — the same orchestration the commands
+ * run, exposed as plain functions so other tools (notably @scenar/mcp-server)
+ * can drive Scenar without shelling out. Each `run*` performs one operation and
+ * returns a structured result; none touch process.exit or the process streams
+ * (they accept an optional `onLog` for progress).
+ */
+export { runPack } from "./pack/run-pack.js";
+export type { RunPackOptions, PackResult } from "./pack/run-pack.js";
+export type { PackManifest } from "./pack/pack-manifest.js";
+export { runNarrate } from "./narrate/run-narrate.js";
+export type { RunNarrateOptions, NarrateResult, NarratedScenario } from "./narrate/run-narrate.js";
+export { runRender } from "./render/run-render.js";
+export type { RunRenderOptions, RenderResult } from "./render/run-render.js";
+export { runServe } from "./serve/run-serve.js";
+export type { RunServeOptions, ServeResult } from "./serve/run-serve.js";
+export { startBundleServer, createBundleServer } from "./serve/static-server.js";
+export type { BundleServerHandle, StartBundleServerOptions } from "./serve/static-server.js";
+export { runPublish } from "./publish/run-publish.js";
+export type { RunPublishOptions, PublishRunResult } from "./publish/run-publish.js";
+export { runPublishFlow, validateRepoName, validatePublishPath, normalizePath, pagesUrl, repoUrl, } from "./publish/publish-flow.js";
+export type { PublishFlowDeps, PublishOptions, PublishResult, } from "./publish/publish-flow.js";
+export { createGithubPublisher } from "./publish/github.js";
+export { validateScenario } from "./validate/scenario-validator.js";
+export { loadScenarioYaml } from "./util/load-yaml.js";
+export { readBundleViewport } from "./bundle/read-viewport.js";
+export type { BundleViewport } from "./bundle/read-viewport.js";
+export { buildEmbedSnippet } from "./deploy/embed-snippet.js";
+export { DEFAULT_VIEWPORT, parseViewport } from "./pack/viewport.js";
+export type { Viewport } from "./pack/viewport.js";
+//# sourceMappingURL=api.d.ts.map