animader-cli 0.0.0-stage → 0.1.1

package/lib/receipt.mjs

@@ -0,0 +1,331 @@
+// The build receipt is the minimal data artifact a later UI or export can
+// read without calling the CLI: what inputs were hashed, what payload was
+// produced, which prepared runtime was verified, and which native producer
+// baked it. It names relative output paths only and carries no timestamps.
+//
+// Ownership: receipt shape and validation. Writing it is host IO.
+
+import { PROJECT_FILES } from './contract.mjs';
+import { DemoError } from './errors.mjs';
+import { isSoundtrackName, soundtrackNamesText } from './soundtrack.mjs';
+
+export const RECEIPT_FORMAT = 'animader-demo-build/1';
+
+/**
+ * The full-build receipt format: the graphics-only receipt plus the packed
+ * score artifact, the toolchain that produced both, and the consumed input
+ * coverage. A `/1` receipt still parses through the `/1` path above, but
+ * only this format records a validated score — never treat a graphics-only
+ * receipt as proof the score compiled or plays.
+ */
+export const SCORE_RECEIPT_FORMAT = 'animader-demo-build/2';
+
+/** The input-coverage methods a score-build receipt may record. */
+export const SCORE_RECEIPT_INPUT_METHODS = Object.freeze(['input-snapshot', 'compiler-metadata']);
+
+function bad(message) {
+  return new DemoError('bad_build_receipt', message, {
+    remedy: 'Rebuild with: node demo/show.mjs <folder> --seconds <n> --preflight-only',
+  });
+}
+
+function badScore(message) {
+  return new DemoError('bad_build_receipt', message, {
+    remedy: 'Rebuild with: animader build [folder] [--seconds S]',
+  });
+}
+
+function cleanRelative(value, label, fail = bad) {
+  const text = String(value ?? '');
+  if (
+    text === '' || text.startsWith('/') || text.includes('\\')
+    || text.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')
+  ) {
+    throw fail(`${label} must be a clean relative path; got ${JSON.stringify(text)}`);
+  }
+  return text;
+}
+
+function digest(value, label, fail = bad) {
+  const text = String(value ?? '');
+  if (!/^[0-9a-f]{64}$/.test(text)) throw fail(`${label} must be a sha256 digest`);
+  return text;
+}
+
+function bytes(value, label, fail = bad) {
+  if (!Number.isInteger(value) || value <= 0) throw fail(`${label} must be a positive byte length`);
+  return value;
+}
+
+function fileRow(row, name, label, fail = bad) {
+  if (row === null || typeof row !== 'object') throw fail(`${label} is missing`);
+  // The soundtrack seat carries the actual selected name; the fixed seats
+  // keep their exact filenames. Old WAV records remain readable because the
+  // legacy name is still one of the recognized names.
+  const selected = label === 'project.files.soundtrack';
+  const valid = selected ? isSoundtrackName(row.name) : row.name === name;
+  if (!valid) {
+    const expected = selected ? `one of ${soundtrackNamesText()}` : name;
+    throw fail(`${label} must name ${expected}; got ${JSON.stringify(row.name)}`);
+  }
+  return {
+    name: selected ? row.name : name,
+    bytes: bytes(row.bytes, label, fail),
+    sha256: digest(row.sha256, label, fail),
+  };
+}
+
+function projectName(project, explicit) {
+  if (explicit !== undefined && explicit !== '') return String(explicit);
+  const folder = String(project?.folder ?? '');
+  const parts = folder.split(/[\\/]/).filter(Boolean);
+  return parts.at(-1) ?? 'untitled';
+}
+
+/**
+ * Build the receipt object. All fields are data; no folder is carried.
+ *
+ * @param {Object} options
+ * @param {{folder?: string, files: Object}} options.project
+ * @param {string} [options.projectName]
+ * @param {number} options.seconds
+ * @param {{name: string, bytes: number, sha256: string}} options.output
+ * @param {{format: string, digest: string, files: number}} options.runtime
+ * @param {{name: string, sha256: string}} options.tool
+ */
+export function makeBuildReceipt({ project, projectName: explicitName, seconds, output, runtime, tool }) {
+  if (!Number.isFinite(seconds) || seconds <= 0) throw bad('show.seconds must be positive and finite');
+  if (project?.files === null || typeof project?.files !== 'object') throw bad('project.files is missing');
+
+  const files = {};
+  for (const [seat, name] of Object.entries(PROJECT_FILES)) {
+    files[seat] = fileRow(project.files[seat], name, `project.files.${seat}`);
+  }
+
+  if (runtime === null || typeof runtime !== 'object') throw bad('runtime is missing');
+  if (runtime.format !== 'animader-demo-vendor/1') throw bad(`runtime.format is not the prepared bundle format; got ${JSON.stringify(runtime.format)}`);
+  if (!Number.isInteger(runtime.files) || runtime.files <= 0) throw bad('runtime.files must be a positive count');
+  if (tool === null || typeof tool !== 'object') throw bad('tool is missing');
+  const toolName = String(tool.name ?? '');
+  if (toolName === '') throw bad('tool.name is missing');
+
+  return {
+    format: RECEIPT_FORMAT,
+    show: { seconds },
+    project: {
+      name: projectName(project, explicitName),
+      files,
+    },
+    output: {
+      name: cleanRelative(output?.name, 'output.name'),
+      bytes: bytes(output?.bytes, 'output.bytes'),
+      sha256: digest(output?.sha256, 'output.sha256'),
+    },
+    runtime: {
+      format: runtime.format,
+      digest: digest(runtime.digest, 'runtime.digest'),
+      files: runtime.files,
+    },
+    tool: {
+      name: toolName,
+      sha256: digest(tool.sha256, 'tool.sha256'),
+    },
+  };
+}
+
+/**
+ * Validate a parsed receipt and return its normalized copy.
+ *
+ * @param {unknown} receipt
+ */
+export function validateReceipt(receipt) {
+  if (receipt === null || typeof receipt !== 'object' || receipt.format !== RECEIPT_FORMAT) {
+    throw bad(`receipt format must be ${RECEIPT_FORMAT}`);
+  }
+  return makeBuildReceipt({
+    project: receipt.project,
+    projectName: receipt.project?.name,
+    seconds: receipt.show?.seconds,
+    output: receipt.output,
+    runtime: receipt.runtime,
+    tool: receipt.tool,
+  });
+}
+
+export function serializeReceipt(receipt) {
+  return `${JSON.stringify(validateReceipt(receipt), null, 2)}\n`;
+}
+
+export function parseReceiptText(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(text));
+  } catch (error) {
+    throw bad(`receipt is not JSON: ${error.message}`);
+  }
+  return validateReceipt(parsed);
+}
+
+function toolRow(row, label) {
+  if (row === null || typeof row !== 'object') throw badScore(`${label} is missing`);
+  const name = String(row.name ?? '');
+  if (name === '') throw badScore(`${label}.name is missing`);
+  return { name, sha256: digest(row.sha256, `${label}.sha256`, badScore) };
+}
+
+function inputRow(row, label) {
+  if (row === null || typeof row !== 'object') throw badScore(`${label} is missing`);
+  return {
+    path: cleanRelative(row.path, `${label}.path`, badScore),
+    bytes: bytes(row.bytes, `${label}.bytes`, badScore),
+    sha256: digest(row.sha256, `${label}.sha256`, badScore),
+  };
+}
+
+function inputRows(rows) {
+  if (!Array.isArray(rows) || rows.length === 0) throw badScore('inputs.files must be a non-empty array of consumed input rows');
+  const normalized = rows.map((row, index) => inputRow(row, `inputs.files[${index}]`));
+  const paths = normalized.map((row) => row.path);
+  if (paths.some((path, index) => index > 0 && paths[index - 1] >= path)) {
+    throw badScore('inputs.files must be sorted by path with no duplicates');
+  }
+  return normalized;
+}
+
+function inputsBlock(inputs) {
+  if (inputs === null || typeof inputs !== 'object') throw badScore('inputs is missing');
+  if (!SCORE_RECEIPT_INPUT_METHODS.includes(inputs.method)) {
+    throw badScore(`inputs.method must be one of ${SCORE_RECEIPT_INPUT_METHODS.join(', ')}; got ${JSON.stringify(inputs.method ?? null)}`);
+  }
+  const note = String(inputs.note ?? '');
+  if (note === '') throw badScore('inputs.note must say which input-coverage method produced the rows');
+  return { method: inputs.method, note, files: inputRows(inputs.files) };
+}
+
+/**
+ * Build the score-build receipt: both artifacts, the resolved host
+ * settings, the producer toolchain and the consumed input coverage in one
+ * data artifact. All fields are data; no folder is carried.
+ *
+ * @param {Object} options
+ * @param {{folder?: string, files: Object}} options.project
+ * @param {string} [options.projectName]
+ * @param {number} options.seconds
+ * @param {{name: string, bytes: number, sha256: string}} options.outputs.payload
+ * @param {{name: string, bytes: number, sha256: string}} options.outputs.score
+ * @param {{method: string, note: string, files: Array<{path: string, bytes: number, sha256: string}>}} options.inputs
+ * @param {{format: string, digest: string, files: number}} options.runtime
+ * @param {{name: string, sha256: string}} options.toolchain.pngine
+ * @param {{name: string, sha256: string}} options.toolchain.pacer
+ */
+export function makeScoreBuildReceipt({
+  project,
+  projectName: explicitName,
+  seconds,
+  outputs,
+  inputs,
+  runtime,
+  toolchain,
+}) {
+  if (!Number.isFinite(seconds) || seconds <= 0) throw badScore('show.seconds must be positive and finite');
+  if (project?.files === null || typeof project?.files !== 'object') throw badScore('project.files is missing');
+
+  const files = {};
+  for (const [seat, name] of Object.entries(PROJECT_FILES)) {
+    files[seat] = fileRow(project.files[seat], name, `project.files.${seat}`, badScore);
+  }
+  if (runtime === null || typeof runtime !== 'object') throw badScore('runtime is missing');
+  if (runtime.format !== 'animader-demo-vendor/1') throw badScore(`runtime.format is not the prepared bundle format; got ${JSON.stringify(runtime.format)}`);
+  if (!Number.isInteger(runtime.files) || runtime.files <= 0) throw badScore('runtime.files must be a positive count');
+  if (outputs === null || typeof outputs !== 'object') throw badScore('outputs is missing');
+  if (toolchain === null || typeof toolchain !== 'object') throw badScore('toolchain is missing');
+
+  const payload = outputs.payload;
+  if (payload === null || typeof payload !== 'object') throw badScore('outputs.payload is missing');
+  const score = outputs.score;
+  if (score === null || typeof score !== 'object') throw badScore('outputs.score is missing');
+
+  return {
+    format: SCORE_RECEIPT_FORMAT,
+    show: { seconds },
+    project: {
+      name: projectName(project, explicitName),
+      files,
+    },
+    outputs: {
+      payload: {
+        name: cleanRelative(payload.name, 'outputs.payload.name', badScore),
+        bytes: bytes(payload.bytes, 'outputs.payload.bytes', badScore),
+        sha256: digest(payload.sha256, 'outputs.payload.sha256', badScore),
+      },
+      score: {
+        name: cleanRelative(score.name, 'outputs.score.name', badScore),
+        bytes: bytes(score.bytes, 'outputs.score.bytes', badScore),
+        sha256: digest(score.sha256, 'outputs.score.sha256', badScore),
+      },
+    },
+    inputs: inputsBlock(inputs),
+    runtime: {
+      format: runtime.format,
+      digest: digest(runtime.digest, 'runtime.digest', badScore),
+      files: runtime.files,
+    },
+    toolchain: {
+      pngine: toolRow(toolchain.pngine, 'toolchain.pngine'),
+      pacer: toolRow(toolchain.pacer, 'toolchain.pacer'),
+    },
+  };
+}
+
+/**
+ * Validate a parsed score-build receipt and return its normalized copy.
+ * A graphics-only (`/1`) receipt is not this format and is refused here;
+ * read it with `validateReceipt` and never as proof of a validated score.
+ *
+ * @param {unknown} receipt
+ */
+export function validateScoreBuildReceipt(receipt) {
+  if (receipt === null || typeof receipt !== 'object' || receipt.format !== SCORE_RECEIPT_FORMAT) {
+    throw badScore(`score-build receipt format must be ${SCORE_RECEIPT_FORMAT}`);
+  }
+  return makeScoreBuildReceipt({
+    project: receipt.project,
+    projectName: receipt.project?.name,
+    seconds: receipt.show?.seconds,
+    outputs: receipt.outputs,
+    inputs: receipt.inputs,
+    runtime: receipt.runtime,
+    toolchain: receipt.toolchain,
+  });
+}
+
+export function serializeScoreBuildReceipt(receipt) {
+  return `${JSON.stringify(validateScoreBuildReceipt(receipt), null, 2)}\n`;
+}
+
+export function parseScoreBuildReceiptText(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(text));
+  } catch (error) {
+    throw badScore(`score-build receipt is not JSON: ${error.message}`);
+  }
+  return validateScoreBuildReceipt(parsed);
+}
+
+/**
+ * Whether a parsed receipt proves a validated score. Only a well-formed
+ * score-build receipt (`animader-demo-build/2`) does; a graphics-only
+ * receipt parses but answers false, and anything malformed answers false.
+ *
+ * @param {unknown} receipt
+ * @returns {boolean}
+ */
+export function receiptValidatesScore(receipt) {
+  try {
+    validateScoreBuildReceipt(receipt);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/rmtree.mjs

@@ -0,0 +1,49 @@
+// The one retrying recursive tree removal: the disposal guard. A recursive
+// removal can answer a transient code when the directory is observed while
+// it changes underneath (an entry landing between the walk and the rmdir, a
+// tree swapped mid-walk); the fix for those is upstream — every tree has
+// one owner, and writers are quiesced before disposal — so this retry is
+// only the last guard, never the mechanism. The codes, the attempt count
+// and the backoff are the contract; do not lengthen them here.
+//
+// This module is portable: no `node:` import, no process state, no DOM.
+// The removal and the delay are injected ports; the Node binding every
+// caller uses lives in adapters/node-fs.mjs.
+
+/** The transient codes a recursive removal answers while it races an observer. */
+export const REMOVAL_RETRY_CODES = Object.freeze(new Set(['ENOTEMPTY', 'EBUSY', 'ENOTDIR']));
+/** A few short attempts: enough to clear a transient observer, never a leak. */
+export const REMOVAL_ATTEMPTS = 4;
+export const REMOVAL_BACKOFF_MS = 25;
+
+const defaultDelay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Remove one tree, retrying the transient codes a short fixed number of
+ * times and rejecting with the last observed error when they persist.
+ *
+ * @param {string} path the tree to remove
+ * @param {Object} ports
+ * @param {(path: string) => Promise<void>} ports.remove the recursive
+ *   removal port (Node binds `fsp.rm(path, { recursive: true, force: true })`)
+ * @param {(ms: number) => Promise<void>} [ports.delay] the backoff port
+ */
+export async function removeTree(path, { remove, delay = defaultDelay }) {
+  if (typeof remove !== 'function') {
+    throw new TypeError('removeTree needs an injected remove(path) port');
+  }
+  let lastError = null;
+  for (let attempt = 1; attempt <= REMOVAL_ATTEMPTS; attempt += 1) {
+    try {
+      await remove(path);
+      return;
+    } catch (cause) {
+      if (!REMOVAL_RETRY_CODES.has(cause?.code)) throw cause;
+      lastError = cause;
+      if (attempt < REMOVAL_ATTEMPTS) {
+        await delay(REMOVAL_BACKOFF_MS * attempt);
+      }
+    }
+  }
+  throw lastError;
+}

package/lib/routes.mjs

@@ -0,0 +1,170 @@
+// HTTP route decisions, portable. A request is mapped to the actual player,
+// the host config, the preflight health answer, or an asset under exactly one
+// of the narrow mounts. The player surface, the portable core modules and the
+// two hello files they import are allowlisted by name: a request never reaches
+// the rest of the checkout. The path is decoded once, then split; traversal,
+// encoded separators, NUL, backslashes and unknown MIME are refused rather
+// than guessed. Filesystem canonicalization is the host adapter's job.
+//
+// Ownership: route grammar and MIME vocabulary. No node:, process or DOM.
+
+import { SOUNDTRACK_EXTENSIONS } from './soundtrack.mjs';
+
+const MIME = Object.freeze({
+  '.sjon': 'text/plain; charset=utf-8',
+  '.wgsl': 'text/plain; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.wasm': 'application/wasm',
+  '.png': 'image/png',
+  ...SOUNDTRACK_EXTENSIONS,
+  '.bin': 'application/octet-stream',
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+});
+
+const PLAYER_FILES = new Set(['index.html', 'page.mjs', 'boot.mjs', 'controller.mjs', 'player.css', 'devchannel.mjs']);
+const APP_LIB_FILES = new Set(['score.mjs', 'show.mjs', 'soundtrack.mjs']);
+const APP_ADAPTER_FILES = new Set(['webaudio.mjs']);
+const HELLO_PLAYER_FILES = new Set(['run.js', 'join.js']);
+
+export const ROUTE = Object.freeze({
+  page: '/',
+  config: '/config.json',
+  health: '/healthz',
+  channel: '/dev',
+  generationPrefix: '/gen/',
+  project: '/project/',
+  runtime: '/runtime/',
+  player: '/player/',
+  appLib: '/app/lib/',
+  appAdapters: '/app/adapters/',
+  appHello: '/app/hello/',
+  examples: '/examples/hello/player/',
+});
+
+export function mimeFor(relative) {
+  const slash = relative.lastIndexOf('/');
+  const dot = relative.lastIndexOf('.');
+  if (dot <= slash) return null;
+  return MIME[relative.slice(dot).toLowerCase()] ?? null;
+}
+
+function failure(status, code, message) {
+  return { kind: 'error', status, code, message };
+}
+
+/**
+ * The path-tail grammar every asset mount shares: decode once, refuse NUL,
+ * backslashes, empty/dot segments and traversal, then answer the segments
+ * with their MIME decision. A mount may add its own filename allowlist.
+ */
+function assetSegments(tail, allow = null) {
+  const trimmed = tail.endsWith('/') ? tail.slice(0, -1) : tail;
+  if (trimmed === '') return failure(404, 'not_found', 'the mount has no asset name');
+
+  let decoded;
+  try {
+    decoded = decodeURIComponent(trimmed);
+  } catch {
+    return failure(400, 'bad_percent_encoding', 'the asset path has an invalid percent escape');
+  }
+  if (decoded.includes('\0') || decoded.includes('\\')) {
+    return failure(400, 'unsafe_path', 'the asset path carries a forbidden separator');
+  }
+  const segments = decoded.split('/');
+  if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    return failure(400, 'unsafe_path', 'the asset path must stay inside its mount');
+  }
+  if (allow !== null && (segments.length !== 1 || !allow.has(segments[0]))) {
+    return failure(404, 'not_found', `the demo does not serve ${decoded} from this mount`);
+  }
+  const relative = segments.join('/');
+  const mime = mimeFor(relative);
+  if (mime === null && segments.at(-1).includes('.')) {
+    return failure(415, 'unsupported_media_type', `the demo has no MIME mapping for ${relative}`);
+  }
+  return { kind: 'asset', segments, relative, mime };
+}
+
+/**
+ * @param {string} rawUrl the request target, assumed origin-form
+ * @returns {Object}
+ */
+export function resolveRequest(rawUrl) {
+  if (typeof rawUrl !== 'string' || !rawUrl.startsWith('/')) {
+    return failure(404, 'not_found', 'not a local demo route');
+  }
+  const query = rawUrl.indexOf('?');
+  const path = query === -1 ? rawUrl : rawUrl.slice(0, query);
+  if (path === ROUTE.page) return { kind: 'page' };
+  if (path === ROUTE.config) return { kind: 'config' };
+  if (path === ROUTE.health) return { kind: 'health' };
+  if (path === ROUTE.channel) return { kind: 'channel' };
+
+  // One generation's immutable mount: /gen/<id>/config.json and
+  // /gen/<id>/project/<relative>. The id is one unpadded positive number so
+  // every generation has exactly one spelling.
+  if (path.startsWith(ROUTE.generationPrefix)) {
+    const tail = path.slice(ROUTE.generationPrefix.length);
+    const slash = tail.indexOf('/');
+    if (slash === -1) return failure(404, 'not_found', 'a generation route needs its config or project path');
+    const idText = tail.slice(0, slash);
+    if (!/^[1-9][0-9]*$/.test(idText)) {
+      return failure(404, 'not_found', 'a generation route needs an unpadded positive generation id');
+    }
+    const generation = Number(idText);
+    const rest = tail.slice(slash + 1);
+    if (rest === 'config.json') return { kind: 'generation-config', generation };
+    const projectPrefix = ROUTE.project.slice(1); // 'project/', no leading slash
+    if (rest.startsWith(projectPrefix)) {
+      const resolved = assetSegments(rest.slice(projectPrefix.length));
+      if (resolved.kind === 'error') return resolved;
+      return { ...resolved, kind: 'generation-asset', generation, mount: 'project' };
+    }
+    return failure(404, 'not_found', 'only config.json and project/ sit under a generation');
+  }
+
+  let mount;
+  let tail;
+  let allow = null;
+  if (path.startsWith(ROUTE.project)) {
+    mount = 'project';
+    tail = path.slice(ROUTE.project.length);
+  } else if (path.startsWith(ROUTE.runtime)) {
+    mount = 'runtime';
+    tail = path.slice(ROUTE.runtime.length);
+  } else if (path.startsWith(ROUTE.player)) {
+    mount = 'player';
+    tail = path.slice(ROUTE.player.length);
+    allow = PLAYER_FILES;
+  } else if (path.startsWith(ROUTE.appLib)) {
+    mount = 'app-lib';
+    tail = path.slice(ROUTE.appLib.length);
+    allow = APP_LIB_FILES;
+  } else if (path.startsWith(ROUTE.appAdapters)) {
+    mount = 'app-adapters';
+    tail = path.slice(ROUTE.appAdapters.length);
+    allow = APP_ADAPTER_FILES;
+  } else if (path.startsWith(ROUTE.appHello)) {
+    // The package's lib modules import the hello player by their sibling
+    // layout ('../hello/run.js'), which a browser resolves from /app/lib/
+    // to /app/hello/ — the same two allowlisted files the examples mount
+    // serves, reached the way the page's own module graph asks for them.
+    mount = 'examples';
+    tail = path.slice(ROUTE.appHello.length);
+    allow = HELLO_PLAYER_FILES;
+  } else if (path.startsWith(ROUTE.examples)) {
+    mount = 'examples';
+    tail = path.slice(ROUTE.examples.length);
+    allow = HELLO_PLAYER_FILES;
+  } else {
+    return failure(404, 'not_found', 'not a local demo route');
+  }
+
+  const resolved = assetSegments(tail, allow);
+  if (resolved.kind === 'error') return resolved;
+  return { ...resolved, mount };
+}