@scenar/cli 0.1.19 → 0.1.20

package/src/pack/pack-manifest.js

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, writeFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { CONTENT_TYPE_BY_EXTENSION, finalExtension, validateRelativePath, validateScenarioJson, } from "./bundle-contract.js";
+/** Name of the manifest file written at the bundle root (not itself uploaded). */
+export const PACK_MANIFEST_FILE = "pack-manifest.json";
+/** Name of the required scenario descriptor at the bundle root. */
+export const SCENARIO_JSON_FILE = "scenario.json";
+/**
+ * Write the bundle's scenario.json — the required-at-root descriptor. Kept
+ * intentionally minimal (a validated metadata header) plus the canonical
+ * `viewport` baked into the bundle: the player reads its steps from the bundled
+ * JS, so the full serialized spec is still a follow-up, but `deploy` needs the
+ * viewport to derive a correctly-proportioned embed snippet (DD-004). The
+ * viewport mirrors `ViewportConfig { width, height }`. Validated against the
+ * backend rules before writing (which accept the extra `viewport` key).
+ */
+export async function writeScenarioJson(outDir, scenarioId, generatorVersion, viewport) {
+    const content = JSON.stringify({
+        schemaVersion: "1",
+        id: scenarioId,
+        generator: `@scenar/cli pack ${generatorVersion}`,
+        viewport: { width: viewport.width, height: viewport.height },
+    }, null, 2);
+    const error = validateScenarioJson(content);
+    if (error) {
+        throw new Error(`Generated scenario.json is invalid: ${error}`);
+    }
+    await writeFile(join(outDir, SCENARIO_JSON_FILE), content, "utf-8");
+}
+/**
+ * Walk the build output and produce the pack manifest: one validated entry per
+ * file (excluding the manifest itself), with a lowercase-hex SHA-256, byte size,
+ * and content type. Throws with a clear message if any file violates the bundle
+ * contract (e.g. a disallowed extension), so the failure is local and obvious.
+ */
+export async function buildPackManifest(outDir, scenarioId) {
+    const absPaths = await walkFiles(outDir);
+    const files = [];
+    for (const abs of absPaths) {
+        const rel = toPosix(relative(outDir, abs));
+        if (rel === PACK_MANIFEST_FILE) {
+            continue; // the manifest never lists itself.
+        }
+        const pathError = validateRelativePath(rel);
+        if (pathError) {
+            throw new Error(`Bundle contains a file that the deploy allowlist would reject:\n  ${pathError}\n\n` +
+                "The deploy allowlist covers HTML/JS/CSS/JSON, MP3 narration, raster images\n" +
+                "(png/jpg/jpeg/gif/webp/avif), and woff2/woff fonts. SVG is not a served type:\n" +
+                "inline it as a React component or a data URI rather than emitting an .svg file.");
+        }
+        const bytes = await readFile(abs);
+        files.push({
+            path: rel,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            sizeBytes: bytes.length,
+            contentType: CONTENT_TYPE_BY_EXTENSION[finalExtension(rel)],
+        });
+    }
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return { schemaVersion: 1, scenarioId, files };
+}
+/** Write pack-manifest.json at the bundle root. */
+export async function writePackManifest(outDir, manifest) {
+    await writeFile(join(outDir, PACK_MANIFEST_FILE), JSON.stringify(manifest, null, 2), "utf-8");
+}
+/** Recursively collect absolute file paths under a directory. */
+async function walkFiles(dir) {
+    const out = [];
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const abs = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...(await walkFiles(abs)));
+        }
+        else if (entry.isFile()) {
+            out.push(abs);
+        }
+    }
+    return out;
+}
+/** True if every listed file exists on disk under outDir with the recorded size. */
+export async function verifyManifestFilesExist(outDir, manifest) {
+    for (const file of manifest.files) {
+        const abs = join(outDir, ...file.path.split("/"));
+        const info = await stat(abs).catch(() => null);
+        if (!info || !info.isFile()) {
+            throw new Error(`pack-manifest lists a missing file: ${file.path}`);
+        }
+    }
+}
+function toPosix(p) {
+    return sep === "/" ? p : p.split(sep).join("/");
+}
+//# sourceMappingURL=pack-manifest.js.map

package/src/pack/pack-manifest.js.map

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

package/src/pack/pack-manifest.ts

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, writeFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import {
+  CONTENT_TYPE_BY_EXTENSION,
+  finalExtension,
+  validateRelativePath,
+  validateScenarioJson,
+} from "./bundle-contract.js";
+import type { Viewport } from "./viewport.js";
+
+/** One uploadable file, described exactly as the deploy session needs it. */
+export interface PackFile {
+  /** Bundle-relative POSIX path (e.g. "assets/index-abc.js"). */
+  readonly path: string;
+  /** Lowercase-hex SHA-256 of the bytes (64 chars). */
+  readonly sha256: string;
+  /** Byte length (> 0). */
+  readonly sizeBytes: number;
+  /** Content type the server binds into the presign and the edge serves. */
+  readonly contentType: string;
+}
+
+/** The deploy instruction file `scenar deploy` consumes. */
+export interface PackManifest {
+  readonly schemaVersion: number;
+  readonly scenarioId: string;
+  /** Files to upload — excludes the manifest itself. */
+  readonly files: PackFile[];
+}
+
+/** Name of the manifest file written at the bundle root (not itself uploaded). */
+export const PACK_MANIFEST_FILE = "pack-manifest.json";
+
+/** Name of the required scenario descriptor at the bundle root. */
+export const SCENARIO_JSON_FILE = "scenario.json";
+
+/**
+ * Write the bundle's scenario.json — the required-at-root descriptor. Kept
+ * intentionally minimal (a validated metadata header) plus the canonical
+ * `viewport` baked into the bundle: the player reads its steps from the bundled
+ * JS, so the full serialized spec is still a follow-up, but `deploy` needs the
+ * viewport to derive a correctly-proportioned embed snippet (DD-004). The
+ * viewport mirrors `ViewportConfig { width, height }`. Validated against the
+ * backend rules before writing (which accept the extra `viewport` key).
+ */
+export async function writeScenarioJson(
+  outDir: string,
+  scenarioId: string,
+  generatorVersion: string,
+  viewport: Viewport,
+): Promise<void> {
+  const content = JSON.stringify(
+    {
+      schemaVersion: "1",
+      id: scenarioId,
+      generator: `@scenar/cli pack ${generatorVersion}`,
+      viewport: { width: viewport.width, height: viewport.height },
+    },
+    null,
+    2,
+  );
+  const error = validateScenarioJson(content);
+  if (error) {
+    throw new Error(`Generated scenario.json is invalid: ${error}`);
+  }
+  await writeFile(join(outDir, SCENARIO_JSON_FILE), content, "utf-8");
+}
+
+/**
+ * Walk the build output and produce the pack manifest: one validated entry per
+ * file (excluding the manifest itself), with a lowercase-hex SHA-256, byte size,
+ * and content type. Throws with a clear message if any file violates the bundle
+ * contract (e.g. a disallowed extension), so the failure is local and obvious.
+ */
+export async function buildPackManifest(outDir: string, scenarioId: string): Promise<PackManifest> {
+  const absPaths = await walkFiles(outDir);
+  const files: PackFile[] = [];
+
+  for (const abs of absPaths) {
+    const rel = toPosix(relative(outDir, abs));
+    if (rel === PACK_MANIFEST_FILE) {
+      continue; // the manifest never lists itself.
+    }
+
+    const pathError = validateRelativePath(rel);
+    if (pathError) {
+      throw new Error(
+        `Bundle contains a file that the deploy allowlist would reject:\n  ${pathError}\n\n` +
+          "The deploy allowlist covers HTML/JS/CSS/JSON, MP3 narration, raster images\n" +
+          "(png/jpg/jpeg/gif/webp/avif), and woff2/woff fonts. SVG is not a served type:\n" +
+          "inline it as a React component or a data URI rather than emitting an .svg file.",
+      );
+    }
+
+    const bytes = await readFile(abs);
+    files.push({
+      path: rel,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+      sizeBytes: bytes.length,
+      contentType: CONTENT_TYPE_BY_EXTENSION[finalExtension(rel) as keyof typeof CONTENT_TYPE_BY_EXTENSION],
+    });
+  }
+
+  files.sort((a, b) => a.path.localeCompare(b.path));
+  return { schemaVersion: 1, scenarioId, files };
+}
+
+/** Write pack-manifest.json at the bundle root. */
+export async function writePackManifest(outDir: string, manifest: PackManifest): Promise<void> {
+  await writeFile(
+    join(outDir, PACK_MANIFEST_FILE),
+    JSON.stringify(manifest, null, 2),
+    "utf-8",
+  );
+}
+
+/** Recursively collect absolute file paths under a directory. */
+async function walkFiles(dir: string): Promise<string[]> {
+  const out: string[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...(await walkFiles(abs)));
+    } else if (entry.isFile()) {
+      out.push(abs);
+    }
+  }
+  return out;
+}
+
+/** True if every listed file exists on disk under outDir with the recorded size. */
+export async function verifyManifestFilesExist(outDir: string, manifest: PackManifest): Promise<void> {
+  for (const file of manifest.files) {
+    const abs = join(outDir, ...file.path.split("/"));
+    const info = await stat(abs).catch(() => null);
+    if (!info || !info.isFile()) {
+      throw new Error(`pack-manifest lists a missing file: ${file.path}`);
+    }
+  }
+}
+
+function toPosix(p: string): string {
+  return sep === "/" ? p : p.split(sep).join("/");
+}

package/src/pack/viewport.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Canonical embed dimensions, mirroring `ai.scenar.scenario.v1.ViewportConfig`:
+ * `width` is the canonical render width and `height` the shell/container height
+ * (the CLI's `--shell-height`). The engine renders at these fixed dimensions and
+ * CSS-zooms to fit the container, so they also define the embed's intrinsic
+ * aspect ratio.
+ *
+ * The proto owns the *concept and vocabulary*; in the code-authored CLI path
+ * there is no `ViewportConfig` instance to read, so `pack` resolves the
+ * dimensions (flags or these defaults), bakes them into the bundle via
+ * `DemoViewport`, and records them in `scenario.json` so `deploy` can derive a
+ * correctly-proportioned embed snippet without re-deriving them (DD-004). This
+ * one module is the single home for the defaults, consumed by both the bake
+ * (`pack`) and the fallback (`deploy`) so they cannot drift.
+ */
+export interface Viewport {
+    /** Canonical render width in px (ViewportConfig.width). */
+    readonly width: number;
+    /** Shell/container height in px (ViewportConfig.height; CLI `--shell-height`). */
+    readonly height: number;
+}
+/** Defaults matching `DemoViewport`: 896 canonical width, 480 shell height. */
+export declare const DEFAULT_VIEWPORT: Viewport;
+/**
+ * Narrow unknown JSON into a {@link Viewport}, or null if it is missing or
+ * malformed (non-object, non-positive, or non-finite dimensions). Lets `deploy`
+ * accept a recorded viewport while falling back cleanly for older bundles.
+ */
+export declare function parseViewport(value: unknown): Viewport | null;
+//# sourceMappingURL=viewport.d.ts.map

package/src/pack/viewport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport.d.ts","sourceRoot":"","sources":["../../../src/pack/viewport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,QAAQ;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,EAAE,QAAsC,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAK7D"}

package/src/pack/viewport.js

@@ -0,0 +1,19 @@
+/** Defaults matching `DemoViewport`: 896 canonical width, 480 shell height. */
+export const DEFAULT_VIEWPORT = { width: 896, height: 480 };
+/**
+ * Narrow unknown JSON into a {@link Viewport}, or null if it is missing or
+ * malformed (non-object, non-positive, or non-finite dimensions). Lets `deploy`
+ * accept a recorded viewport while falling back cleanly for older bundles.
+ */
+export function parseViewport(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const { width, height } = value;
+    if (!isPositiveInt(width) || !isPositiveInt(height))
+        return null;
+    return { width, height };
+}
+function isPositiveInt(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+//# sourceMappingURL=viewport.js.map

package/src/pack/viewport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport.js","sourceRoot":"","sources":["../../../src/pack/viewport.ts"],"names":[],"mappings":"AAsBA,+EAA+E;AAC/E,MAAM,CAAC,MAAM,gBAAgB,GAAa,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AAEtE;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,KAAgC,CAAC;IAC3D,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACjE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;AAC3E,CAAC"}

package/src/pack/viewport.ts

@@ -0,0 +1,40 @@
+/**
+ * Canonical embed dimensions, mirroring `ai.scenar.scenario.v1.ViewportConfig`:
+ * `width` is the canonical render width and `height` the shell/container height
+ * (the CLI's `--shell-height`). The engine renders at these fixed dimensions and
+ * CSS-zooms to fit the container, so they also define the embed's intrinsic
+ * aspect ratio.
+ *
+ * The proto owns the *concept and vocabulary*; in the code-authored CLI path
+ * there is no `ViewportConfig` instance to read, so `pack` resolves the
+ * dimensions (flags or these defaults), bakes them into the bundle via
+ * `DemoViewport`, and records them in `scenario.json` so `deploy` can derive a
+ * correctly-proportioned embed snippet without re-deriving them (DD-004). This
+ * one module is the single home for the defaults, consumed by both the bake
+ * (`pack`) and the fallback (`deploy`) so they cannot drift.
+ */
+export interface Viewport {
+  /** Canonical render width in px (ViewportConfig.width). */
+  readonly width: number;
+  /** Shell/container height in px (ViewportConfig.height; CLI `--shell-height`). */
+  readonly height: number;
+}
+
+/** Defaults matching `DemoViewport`: 896 canonical width, 480 shell height. */
+export const DEFAULT_VIEWPORT: Viewport = { width: 896, height: 480 };
+
+/**
+ * Narrow unknown JSON into a {@link Viewport}, or null if it is missing or
+ * malformed (non-object, non-positive, or non-finite dimensions). Lets `deploy`
+ * accept a recorded viewport while falling back cleanly for older bundles.
+ */
+export function parseViewport(value: unknown): Viewport | null {
+  if (typeof value !== "object" || value === null) return null;
+  const { width, height } = value as Record<string, unknown>;
+  if (!isPositiveInt(width) || !isPositiveInt(height)) return null;
+  return { width, height };
+}
+
+function isPositiveInt(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}

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

@@ -6,7 +6,7 @@ export declare function snakeToCamelKeys(value: unknown): unknown;
 /**
  * Reads a scenario YAML file from disk, parses it, and converts
  * snake_case field names to the camelCase convention used by the
- * SDK's `ProtoScenario` type.
+ * SDK's `ProtoScenarioSpec` type.
  *
  * @throws {Error} on file-not-found or YAML parse failure.
  */

package/src/util/load-yaml.js

@@ -23,7 +23,7 @@ function snakeToCamel(s) {
 /**
  * Reads a scenario YAML file from disk, parses it, and converts
  * snake_case field names to the camelCase convention used by the
- * SDK's `ProtoScenario` type.
+ * SDK's `ProtoScenarioSpec` type.
  *
  * @throws {Error} on file-not-found or YAML parse failure.
  */

package/src/util/load-yaml.ts

@@ -26,7 +26,7 @@ function snakeToCamel(s: string): string {
 /**
  * Reads a scenario YAML file from disk, parses it, and converts
  * snake_case field names to the camelCase convention used by the
- * SDK's `ProtoScenario` type.
+ * SDK's `ProtoScenarioSpec` type.
  *
  * @throws {Error} on file-not-found or YAML parse failure.
  */