animader-cli 0.0.0-stage → 0.1.1

package/lib/contract.mjs

@@ -0,0 +1,371 @@
+// The demo's project contract and CLI argument grammar. This module is
+// portable: it takes bytes and paths through injected functions and parses
+// no guest language. The exact folder names are data, not a second reader
+// of SJON; `pngine validate` and the payload bake are the program checks.
+//
+// Ownership: project input shape, host duration/port bounds, argument
+// decisions. IO and native execution belong to host adapters.
+
+import { projectError, usageError } from './errors.mjs';
+import { SOUNDTRACK_NAMES, soundtrackNamesText } from './soundtrack.mjs';
+
+export { SOUNDTRACK_NAMES, isSoundtrackName } from './soundtrack.mjs';
+
+export const PROJECT_FILES = Object.freeze({
+  program: 'program.sjon',
+  timeline: 'timeline.piece.sjon',
+  soundtrack: 'soundtrack.wav',
+});
+
+export const GENERATED_DIR = 'out';
+export const BAKED_PAYLOAD = 'show.png';
+export const PACKED_SCORE = 'score.pacb';
+export const BUILD_RECEIPT = 'build-receipt.json';
+export const SPLIT_PIECE = 'piece.sjon';
+
+// A show is a host policy, not a pacer transport field. The upper bound is
+// the demo's own known range; the lower bound is merely positive.
+export const MAX_SECONDS = 600;
+
+export const DEFAULT_LIMITS = Object.freeze({
+  program: 16 * 1024 * 1024,
+  timeline: 16 * 1024 * 1024,
+  soundtrack: 64 * 1024 * 1024,
+});
+
+const RANGE_WORDS = `a positive number at most ${MAX_SECONDS}`;
+
+function inFolder(folder, name) {
+  return `${String(folder).replace(/[\\/]+$/, '')}/${name}`;
+}
+
+function folderLabel(folder) {
+  return folder === '' ? 'the current folder' : folder;
+}
+
+export function parseSeconds(raw) {
+  if (raw === undefined) {
+    throw usageError(
+      'missing_seconds',
+      `--seconds is required and must be ${RANGE_WORDS}`,
+      'Pass the host show length, for example: node demo/show.mjs <folder> --seconds 8',
+    );
+  }
+  const text = typeof raw === 'number' ? String(raw) : String(raw).trim();
+  const value = Number(text);
+  if (text === '' || !Number.isFinite(value) || value <= 0 || value > MAX_SECONDS) {
+    throw usageError(
+      'invalid_seconds',
+      `--seconds must be ${RANGE_WORDS}; got ${JSON.stringify(String(raw))}`,
+      'Pass a positive finite host show length, for example --seconds 8',
+    );
+  }
+  return value;
+}
+
+export function parsePort(raw) {
+  if (raw === undefined) return 0;
+  const text = String(raw).trim();
+  if (!/^\d+$/.test(text)) {
+    throw usageError(
+      'invalid_port',
+      `--port must be an integer from 0 through 65535; got ${JSON.stringify(String(raw))}`,
+      'Use --port 0 to let the operating system choose a free port',
+    );
+  }
+  const value = Number(text);
+  if (value > 65535) {
+    throw usageError(
+      'invalid_port',
+      `--port must be an integer from 0 through 65535; got ${text}`,
+      'Use --port 0 to let the operating system choose a free port',
+    );
+  }
+  return value;
+}
+
+export function parseArgv(argv) {
+  if (!Array.isArray(argv)) {
+    throw usageError('invalid_argv', 'the CLI adapter must pass an argument array', 'Call node demo/show.mjs <folder> --seconds <n>');
+  }
+
+  let folder = null;
+  let secondsRaw;
+  let portRaw;
+  let open = true;
+  let preflightOnly = false;
+  let help = false;
+  let endOptions = false;
+
+  for (let index = 0; index < argv.length; index++) {
+    const argument = String(argv[index]);
+    if (!endOptions && argument === '--') {
+      endOptions = true;
+      continue;
+    }
+    if (!endOptions && (argument === '--help' || argument === '-h')) {
+      help = true;
+      continue;
+    }
+    if (!endOptions && argument.startsWith('--')) {
+      const equals = argument.indexOf('=');
+      const name = equals === -1 ? argument : argument.slice(0, equals);
+      const inline = equals === -1 ? undefined : argument.slice(equals + 1);
+      const takeValue = () => {
+        if (inline !== undefined) return inline;
+        if (index + 1 >= argv.length) {
+          throw usageError('missing_option_value', `${name} needs a value`, `Pass ${name} <value>`);
+        }
+        index++;
+        return String(argv[index]);
+      };
+      if (name === '--seconds') {
+        secondsRaw = takeValue();
+      } else if (name === '--port') {
+        portRaw = takeValue();
+      } else if (name === '--no-open') {
+        if (inline !== undefined) {
+          throw usageError('unexpected_option_value', '--no-open takes no value', 'Use --no-open by itself');
+        }
+        open = false;
+      } else if (name === '--preflight-only') {
+        if (inline !== undefined) {
+          throw usageError('unexpected_option_value', '--preflight-only takes no value', 'Use --preflight-only by itself');
+        }
+        preflightOnly = true;
+      } else {
+        throw usageError(
+          'unknown_option',
+          `unknown option ${name}`,
+          'The supported options are --seconds, --port, --no-open, --preflight-only and --help',
+        );
+      }
+      continue;
+    }
+    if (!endOptions && argument.startsWith('-') && argument !== '-') {
+      throw usageError(
+        'unknown_option',
+        `unknown option ${argument}`,
+        'The supported options are --seconds, --port, --no-open, --preflight-only and --help',
+      );
+    }
+    if (folder !== null) {
+      throw usageError('extra_argument', `extra folder argument ${JSON.stringify(argument)}`, 'Pass exactly one project folder');
+    }
+    folder = argument;
+  }
+
+  if (help) {
+    return { help: true, folder, seconds: undefined, port: 0, open, preflightOnly };
+  }
+  if (folder === null) {
+    throw usageError(
+      'missing_folder',
+      'exactly one project folder is required',
+      'Run: node demo/show.mjs <folder> --seconds 8 [--port N] [--no-open]',
+    );
+  }
+
+  return {
+    help: false,
+    folder,
+    seconds: parseSeconds(secondsRaw),
+    port: parsePort(portRaw),
+    open,
+    preflightOnly,
+  };
+}
+
+export function usageText() {
+  return [
+    'animader demo',
+    '',
+    'Usage:',
+    '  node demo/show.mjs <folder> --seconds S [--port N] [--no-open]',
+    '',
+    'The folder carries exactly:',
+    `  ${PROJECT_FILES.program}`,
+    `  ${PROJECT_FILES.timeline}   (inline-roots aggregate; a split ${SPLIT_PIECE} is refused)`,
+    `  exactly one of ${soundtrackNamesText()}`,
+    '    (.wav is browser-decodable WAV; .ogg is Ogg Vorbis or Ogg Opus;',
+    '     .opus is Ogg Opus — the browser decodes the actual bytes)',
+    '  plus any relative assets the program names.',
+    '',
+    'Options:',
+    `  --seconds S        required host show length, ${RANGE_WORDS}`,
+    '  --port N           127.0.0.1 port; 0 (the default) chooses a free one',
+    '  --no-open          do not attempt to launch Chromium',
+    '  --preflight-only   validate and bake, print the receipt, then exit',
+    '  -h, --help         this text',
+    '',
+    `Generated: ${GENERATED_DIR}/${BAKED_PAYLOAD} and ${GENERATED_DIR}/${BUILD_RECEIPT}`,
+  ].join('\n');
+}
+
+async function requireFile(statFile, path, name, seat, limits, folder) {
+  const stats = await statFile(path);
+  if (stats === null) {
+    throw projectError(
+      'missing_input',
+      `${name} is missing in ${folderLabel(folder)}`,
+      `Place ${name} in the project folder. The fixed inputs are ${PROJECT_FILES.program} and ${PROJECT_FILES.timeline}, plus one of ${soundtrackNamesText()}.`,
+    );
+  }
+  if (!stats.isFile) {
+    throw projectError(
+      'input_not_file',
+      `${name} is not a regular file in ${folderLabel(folder)}`,
+      `Replace ${name} with a file.`,
+    );
+  }
+  if (stats.size === 0) {
+    throw projectError(
+      'empty_input',
+      `${name} is empty in ${folderLabel(folder)}`,
+      `Write ${name} or regenerate the fixture with: node demo/prepare.mjs`,
+    );
+  }
+  if (stats.size > limits[seat]) {
+    throw projectError(
+      'input_too_large',
+      `${name} is ${stats.size} bytes; the demo limit is ${limits[seat]} bytes`,
+      `Use a smaller ${name}; the limit is a preflight guard, not a format restriction.`,
+    );
+  }
+  return stats;
+}
+
+/**
+ * The soundtrack seat's candidacy, decided on names exactly as the folder
+ * lists them: an entry is a candidate only under its exact spelling, never
+ * under what a case-folding filesystem (APFS is case-insensitive by
+ * default) resolves a fixed probe to. The allowlist order is stable.
+ *
+ * @param {string[]} entries the folder's own entry names
+ * @returns {string[]} the recognized candidates, in allowlist order
+ */
+export function soundtrackCandidates(entries) {
+  const listed = new Set(entries);
+  return SOUNDTRACK_NAMES.filter((name) => listed.has(name));
+}
+
+/**
+ * Resolve the soundtrack seat over the shared three-name allowlist. The
+ * folder is read once and candidacy comes from its listing by exact
+ * string equality; every candidate is then checked for file shape, size
+ * and emptiness: a directory or empty file with a recognized name is an
+ * input error and is never ignored in favor of another candidate. Among
+ * valid candidates exactly one must remain; the error names what is
+ * present and what is supported.
+ */
+async function resolveSoundtrack({ folder, io, limit }) {
+  const candidates = soundtrackCandidates(await io.listDir(folder));
+  const present = [];
+  for (const name of candidates) {
+    const stats = await io.statFile(inFolder(folder, name));
+    if (stats === null) continue;
+    if (!stats.isFile) {
+      throw projectError(
+        'input_not_file',
+        `${name} is not a regular file in ${folderLabel(folder)}`,
+        `Replace ${name} with a regular file; a directory with a recognized soundtrack name is an input error, not a skippable candidate.`,
+      );
+    }
+    if (stats.size === 0) {
+      throw projectError(
+        'empty_input',
+        `${name} is empty in ${folderLabel(folder)}`,
+        `Write audio bytes to ${name} or move it out of the project folder; exactly one recognized soundtrack is required.`,
+      );
+    }
+    if (stats.size > limit) {
+      throw projectError(
+        'input_too_large',
+        `${name} is ${stats.size} bytes; the demo limit is ${limit} bytes`,
+        `Use a smaller ${name}; the limit is a preflight guard, not a format restriction.`,
+      );
+    }
+    present.push(name);
+  }
+  if (present.length === 0) {
+    throw projectError(
+      'missing_input',
+      `no recognized soundtrack is present in ${folderLabel(folder)}: expected exactly one of ${soundtrackNamesText()}`,
+      `Place exactly one of ${soundtrackNamesText()} in the project folder; the browser decodes the actual bytes, not the extension.`,
+    );
+  }
+  if (present.length > 1) {
+    throw projectError(
+      'ambiguous_soundtrack',
+      `${present.length} recognized soundtracks are present in ${folderLabel(folder)}: ${present.join(', ')}; exactly one is required`,
+      `Keep exactly one of ${soundtrackNamesText()} and move or rename the rest outside the project root; the host never deletes author audio.`,
+    );
+  }
+  const name = present[0];
+  const bytes = await io.readFile(inFolder(folder, name));
+  return { name, bytes: bytes.byteLength, sha256: io.hashBytes(bytes) };
+}
+
+/**
+ * Inspect one project folder against the exact-name contract.
+ *
+ * @param {Object} options
+ * @param {string} options.folder
+ * @param {Object} options.io
+ * @param {(path: string) => Promise<null|{isFile: boolean, isDirectory: boolean, size: number}>} options.io.statFile
+ * @param {(path: string) => Promise<string[]>} options.io.listDir the folder's
+ *   own entry names — the soundtrack seat's candidacy is decided on these,
+ *   never on what a case-folding stat resolves
+ * @param {(path: string) => Promise<Uint8Array>} options.io.readFile
+ * @param {(bytes: Uint8Array) => string} options.io.hashBytes
+ * @param {Object} [options.limits]
+ * @returns {Promise<{folder: string, files: Object<string, {name: string, bytes: number, sha256: string}>}>}
+ */
+export async function inspectProject({ folder, io, limits }) {
+  if (typeof folder !== 'string' || folder === '') {
+    throw projectError('missing_folder', 'the project folder is empty', 'Pass the folder that holds the three exact input names.');
+  }
+  if (!io
+    || typeof io.statFile !== 'function'
+    || typeof io.readFile !== 'function'
+    || typeof io.hashBytes !== 'function'
+    || typeof io.listDir !== 'function') {
+    throw new TypeError('inspectProject needs io.statFile, io.listDir, io.readFile and io.hashBytes');
+  }
+  const effectiveLimits = limits ?? io.limits ?? DEFAULT_LIMITS;
+
+  const splitPath = inFolder(folder, SPLIT_PIECE);
+  const split = await io.statFile(splitPath);
+  if (split !== null) {
+    throw projectError(
+      'split_piece_unsupported',
+      `${SPLIT_PIECE} is a split piece and this demo has one derived seat`,
+      `Use ${PROJECT_FILES.timeline} with tempura's roots inline instead; a split piece has no authored fallback here.`,
+    );
+  }
+
+  const outStats = await io.statFile(inFolder(folder, GENERATED_DIR));
+  if (outStats !== null && !outStats.isDirectory) {
+    throw projectError(
+      'out_not_directory',
+      `${GENERATED_DIR}/ exists but is not a directory`,
+      `${GENERATED_DIR}/ is generated output; move the file out of the way so the demo can create it.`,
+    );
+  }
+
+  const files = {};
+  for (const seat of ['program', 'timeline']) {
+    const name = PROJECT_FILES[seat];
+    const path = inFolder(folder, name);
+    await requireFile(io.statFile, path, name, seat, effectiveLimits, folder);
+    const bytes = await io.readFile(path);
+    files[seat] = {
+      name,
+      bytes: bytes.byteLength,
+      sha256: io.hashBytes(bytes),
+    };
+  }
+  files.soundtrack = await resolveSoundtrack({ folder, io, limit: effectiveLimits.soundtrack });
+
+  return { folder, files };
+}

package/lib/errors.mjs

@@ -0,0 +1,51 @@
+// Named failures are the CLI's public vocabulary. This module is portable:
+// it carries no `node:` import, no process state and no DOM. Host adapters
+// add paths and causes; the decision and the exit class stay here.
+
+export const EXIT_CODES = Object.freeze({
+  usage: 2,
+  project: 3,
+  build: 4,
+  server: 5,
+});
+
+export class DemoError extends Error {
+  constructor(code, message, { exitCode = 1, remedy = '', stage = '', cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'DemoError';
+    this.code = code;
+    this.exitCode = exitCode;
+    this.remedy = remedy;
+    this.stage = stage;
+  }
+}
+
+export function usageError(code, message, remedy = '') {
+  return new DemoError(code, message, { exitCode: EXIT_CODES.usage, remedy });
+}
+
+export function projectError(code, message, remedy = '') {
+  return new DemoError(code, message, { exitCode: EXIT_CODES.project, remedy });
+}
+
+export function buildError(code, message, remedy = '') {
+  return new DemoError(code, message, { exitCode: EXIT_CODES.build, remedy });
+}
+
+export function serverError(code, message, remedy = '') {
+  return new DemoError(code, message, { exitCode: EXIT_CODES.server, remedy });
+}
+
+/**
+ * The exact stderr lines every demo entry point prints for a thrown error.
+ * The `animader` CLI bin shares this helper so the format has one owner;
+ * adding an export here changes no existing demo behaviour.
+ *
+ * @param {unknown} error
+ * @returns {string[]}
+ */
+export function errorLines(error) {
+  const lines = [`error: ${error.message}`];
+  if (error?.remedy) lines.push(`remedy: ${error.remedy}`);
+  return lines;
+}