animader-cli 0.0.0-stage → 0.1.1

package/lib/export.mjs

@@ -0,0 +1,445 @@
+// The portable release-export contract: argument grammar, the exact shipped
+// file set, the safe staged write, the self-excluded manifest and the
+// detached size report. Every byte producer, native process, compression
+// codec and filesystem call is injected by the host adapter; this module
+// carries no node: import, no process state and no DOM.
+//
+// The export is deliberately not a global transaction. The target must not
+// exist (including a symlink), the tree is written under `<out>.next` and one
+// rename publishes it. The staging path is refused, never deleted, when it
+// already exists: a predictable `OUT.next` that this invocation did not
+// create is unowned, and no export may recursively remove someone else's
+// directory. On any failure before the rename, the staging directory this
+// invocation created is removed. A concurrent writer is not locked out, and
+// the detached report is written after the payload commit — the report is
+// outside OUT and never part of its own measurement.
+
+import { projectError, usageError } from './errors.mjs';
+import { MAX_SECONDS, parseSeconds } from './contract.mjs';
+import { isSoundtrackName, PLAYER_CONFIG_FORMATS, soundtrackNamesText } from './soundtrack.mjs';
+
+export const EXPORT_FORMAT = 'animader-release-manifest/1';
+export const EXPORT_SIZE_FORMAT = 'animader-release-size/1';
+
+/** The name-independent release files, sorted here for the manifest. */
+export const EXPORT_BASE_FILES = Object.freeze([
+  'app.mjs',
+  'assets/score.pacb',
+  'assets/show.png',
+  'config.json',
+  'index.html',
+  'LICENSES.txt',
+  'pacer-rt.wasm',
+  'player.css',
+]);
+
+/**
+ * The exact minimal root a release ships for one selected soundtrack name,
+ * sorted for the manifest. The audio path follows the selection; nothing
+ * else in the set depends on it.
+ */
+export function exportFileSet(soundtrackName) {
+  if (!isSoundtrackName(soundtrackName)) {
+    throw projectError(
+      'invalid_soundtrack',
+      `the export needs the inspected soundtrack selection; got ${JSON.stringify(soundtrackName ?? null)}`,
+      `Inspect the project first; the release ships exactly one of ${soundtrackNamesText()}.`,
+    );
+  }
+  return Object.freeze([...EXPORT_BASE_FILES, `assets/${soundtrackName}`].sort());
+}
+
+const SOUNDTRACK_PATH = /^assets\/soundtrack\.(wav|ogg|opus)$/;
+
+/**
+ * The inspected soundtrack selection an export or release config needs.
+ * The name comes from the project inspection; there is no fixed default.
+ */
+export function selectedSoundtrack(project) {
+  const selected = project?.files?.soundtrack?.name;
+  if (!isSoundtrackName(selected)) {
+    throw projectError(
+      'missing_soundtrack_selection',
+      `the export needs the inspected soundtrack selection; got ${JSON.stringify(selected ?? null)}`,
+      `Inspect the project folder first; the release ships exactly one of ${soundtrackNamesText()}.`,
+    );
+  }
+  return selected;
+}
+
+/**
+ * The generated release player config: version 2 with the explicit
+ * selection the loader requires for compressed audio.
+ */
+export function releasePlayerConfig({ seconds, soundtrackName }) {
+  if (!Number.isFinite(seconds) || seconds <= 0 || seconds > MAX_SECONDS) {
+    throw usageError('invalid_seconds', `--seconds must be a positive number at most ${MAX_SECONDS}`, 'Pass the host show length, for example --seconds 36');
+  }
+  if (!isSoundtrackName(soundtrackName)) {
+    throw projectError(
+      'invalid_soundtrack',
+      `the release config needs the selected soundtrack name; got ${JSON.stringify(soundtrackName ?? null)}`,
+      `The config carries exactly one of ${soundtrackNamesText()}.`,
+    );
+  }
+  return `${JSON.stringify({ format: PLAYER_CONFIG_FORMATS.release, seconds, soundtrack: soundtrackName })}\n`;
+}
+
+function cleanRelative(path) {
+  return typeof path === 'string'
+    && path !== ''
+    && !path.startsWith('/')
+    && !path.includes('\\')
+    && !path.includes('\0')
+    && path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}
+
+export function categoryOf(path, musicPath) {
+  if (path === musicPath) return 'music';
+  if (path === 'app.mjs') return 'runtime-js';
+  if (path === 'pacer-rt.wasm') return 'runtime-wasm';
+  if (path === 'index.html' || path === 'player.css') return 'ui';
+  if (path === 'assets/show.png') return 'program';
+  if (path === 'assets/score.pacb') return 'program-score';
+  if (path === 'config.json') return 'config';
+  if (path === 'manifest.json') return 'metadata';
+  if (path === 'LICENSES.txt') return 'licenses';
+  return 'other';
+}
+
+function emptySum() {
+  return { raw: 0, gzip9: 0, brotli11: 0 };
+}
+
+function add(sum, entry) {
+  sum.raw += entry.bytes;
+  sum.gzip9 += entry.gzip9;
+  sum.brotli11 += entry.brotli11;
+  return sum;
+}
+
+function display(sum) {
+  const round = (value) => Math.round(value * 1000) / 1000;
+  return {
+    rawKB: round(sum.raw / 1000),
+    rawKiB: round(sum.raw / 1024),
+    gzip9KB: round(sum.gzip9 / 1000),
+    gzip9KiB: round(sum.gzip9 / 1024),
+    brotli11KB: round(sum.brotli11 / 1000),
+    brotli11KiB: round(sum.brotli11 / 1024),
+  };
+}
+
+/**
+ * Build the one detached size-report shape shared by the export and the
+ * archive tool. `measured` rows are already encoded per file; `musicPath`
+ * is the release's actual selected audio path, never a fixed name.
+ */
+export function buildSizeReport(measured, musicPath) {
+  if (!SOUNDTRACK_PATH.test(musicPath)) {
+    throw projectError(
+      'invalid_soundtrack',
+      `the size report needs the release's selected audio path; got ${JSON.stringify(musicPath ?? null)}`,
+      `Pass the audio path the release actually ships: assets/ plus one of ${soundtrackNamesText()}.`,
+    );
+  }
+  const music = measured.filter((entry) => entry.category === 'music');
+  const nonMusic = measured.filter((entry) => entry.category !== 'music');
+  const sums = { all: emptySum(), music: emptySum(), withoutMusic: emptySum() };
+  for (const entry of measured) {
+    add(sums.all, entry);
+    add(entry.category === 'music' ? sums.music : sums.withoutMusic, entry);
+  }
+  const categories = {};
+  for (const entry of measured) {
+    if (!categories[entry.category]) {
+      categories[entry.category] = { files: 0, raw: 0, gzip9: 0, brotli11: 0 };
+    }
+    categories[entry.category].files += 1;
+    add(categories[entry.category], entry);
+  }
+
+  return {
+    format: EXPORT_SIZE_FORMAT,
+    metric: 'per-file encoded sums (not an archive or an HTTP wire measurement)',
+    units: {
+      decimalKB: 1000,
+      binaryKiB: 1024,
+      note: 'KB is 1000 bytes; KiB is 1024 bytes. Compressed values are per-file encoded sums, not an archive.',
+    },
+    scope: 'every file in OUT including manifest.json; this report is outside OUT and excluded from itself',
+    selfIncluded: false,
+    musicPath,
+    files: measured,
+    categories,
+    sums,
+    display: {
+      all: display(sums.all),
+      music: display(sums.music),
+      withoutMusic: display(sums.withoutMusic),
+    },
+  };
+}
+
+/**
+ * Parse the export command's argv. It is the same grammar family as
+ * `show.mjs`: one folder positional, required `--seconds`, required `--out`,
+ * `--` for a dash-leading folder, and named usage errors. There is no
+ * `--force` in this slice; an existing target is always refused.
+ */
+export function parseExportArgv(argv) {
+  if (!Array.isArray(argv)) {
+    throw usageError('invalid_argv', 'the CLI adapter must pass an argument array', 'Call node demo/export.mjs <folder> --seconds <n> --out <folder>');
+  }
+  let folder = null;
+  let secondsRaw;
+  let out = null;
+  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 === '--out') {
+        out = takeValue();
+      } else {
+        throw usageError(
+          'unknown_option',
+          `unknown option ${name}`,
+          'The supported options are --seconds, --out and --help; an existing target is refused',
+        );
+      }
+      continue;
+    }
+    if (!endOptions && argument.startsWith('-') && argument !== '-') {
+      throw usageError('unknown_option', `unknown option ${argument}`, 'The supported options are --seconds, --out 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, out };
+  if (folder === null) {
+    throw usageError('missing_folder', 'exactly one project folder is required', 'Run: node demo/export.mjs <folder> --seconds 36 --out <folder>');
+  }
+  const seconds = parseSeconds(secondsRaw);
+  if (out === null || out === '') {
+    throw usageError('missing_out', '--out is required', 'Pass the release folder, for example --out .agent/releases/meridian');
+  }
+  return { help: false, folder, seconds, out };
+}
+
+export function exportUsageText() {
+  return [
+    'animader demo export',
+    '',
+    'Usage:',
+    '  node demo/export.mjs <folder> --seconds S --out OUT',
+    '',
+    'The folder carries the fixed inputs and exactly one recognized soundtrack:',
+    '  program.sjon',
+    '  timeline.piece.sjon',
+    `  one of ${soundtrackNamesText()}`,
+    '',
+    'The export bakes the program, derives the score once, packs it offline',
+    'with the real pacer CLI over the reflected join, bundles app.mjs with the',
+    'owner esbuild, and writes a minimal static release plus manifest.json and',
+    'a detached OUT.size.json.',
+    '',
+    'Options:',
+    `  --seconds S   required host show length, a positive number at most ${MAX_SECONDS}`,
+    '  --out OUT     required release folder; it must not exist (including a symlink)',
+    '  -h, --help    this text',
+    '',
+    'No --force, no archive, no .gz/.br sidecars. The size report is outside OUT.',
+  ].join('\n');
+}
+
+/**
+ * Export one show.
+ *
+ * @param {object} options
+ * @param {{folder: string, files: object}} options.project inspected project
+ * @param {number} options.seconds host show length
+ * @param {{outDir: string, stageDir: string, sizePath: string, parentDir: string}} options.paths
+ * @param {object} options.io
+ * @param {(path: string) => Promise<null|{kind: string, size: number}>} options.io.inspect
+ * @param {(path: string) => Promise<void>} options.io.remove
+ * @param {(path: string) => Promise<void>} options.io.ensureDir
+ * @param {(path: string, bytes: Uint8Array) => Promise<void>} options.io.writeFile
+ * @param {(from: string, to: string) => Promise<void>} options.io.rename
+ * @param {(bytes: Uint8Array) => string} options.io.hashBytes
+ * @param {{prepare: (options: object) => Promise<{files: Object<string, Uint8Array>}>}} options.producer
+ *   the actual bake, derive, pack and bundle adapter
+ * @param {(bytes: Uint8Array) => {gzip9: number, brotli11: number}} options.measure
+ */
+export async function exportShow({ project, seconds, paths, io, producer, measure }) {
+  if (!io
+    || typeof io.inspect !== 'function'
+    || typeof io.remove !== 'function'
+    || typeof io.ensureDir !== 'function'
+    || typeof io.writeFile !== 'function'
+    || typeof io.rename !== 'function'
+    || typeof io.hashBytes !== 'function') {
+    throw new TypeError('exportShow needs the injected filesystem port (inspect, remove, ensureDir, writeFile, rename, hashBytes)');
+  }
+  if (!producer || typeof producer.prepare !== 'function') {
+    throw new TypeError('exportShow needs producer.prepare (the actual bake, derive, compile and bundle adapter)');
+  }
+  if (typeof measure !== 'function') throw new TypeError('exportShow needs a measure(bytes) codec port');
+  if (!Number.isFinite(seconds) || seconds <= 0 || seconds > MAX_SECONDS) {
+    throw usageError('invalid_seconds', `--seconds must be a positive number at most ${MAX_SECONDS}`, 'Pass the host show length, for example --seconds 36');
+  }
+
+  if (await io.inspect(paths.outDir) !== null) {
+    throw projectError(
+      'output_exists',
+      `the export target already exists: ${paths.outDir}`,
+      'Choose a fresh target; this slice has no --force and never overwrites an existing path.',
+    );
+  }
+  const selected = selectedSoundtrack(project);
+  const exportFiles = exportFileSet(selected);
+  const required = new Set(exportFiles);
+  const musicPath = `assets/${selected}`;
+  const parent = await io.inspect(paths.parentDir);
+  if (parent === null || parent.kind !== 'dir') {
+    throw projectError(
+      'output_parent_missing',
+      `the export target's parent folder does not exist: ${paths.parentDir}`,
+      'Create the parent folder first, then choose the fresh export target inside it.',
+    );
+  }
+
+  // The staging path is owned only when this invocation creates it. A
+  // pre-existing `<out>.next` — another export's debris or something else
+  // entirely — is refused, never recursively deleted on the strength of a
+  // predictable name.
+  if (await io.inspect(paths.stageDir) !== null) {
+    throw projectError(
+      'staging_exists',
+      `the export staging path already exists: ${paths.stageDir}`,
+      `This export never deletes a staging directory it did not create; remove ${paths.stageDir} yourself if you own it, or choose a fresh --out.`,
+    );
+  }
+  let committed = false;
+  try {
+    await io.ensureDir(paths.stageDir);
+    const prepared = await producer.prepare({ project, seconds, outDir: paths.outDir });
+    const files = prepared?.files;
+    if (files === null || typeof files !== 'object' || Array.isArray(files)) {
+      throw projectError('bad_export_payload', 'the producer answered no files object', 'Fix the export adapter; nothing was published.');
+    }
+
+    for (const [path, bytes] of Object.entries(files)) {
+      if (!cleanRelative(path)) {
+        throw projectError('export_path_unsafe', `the producer answered an unsafe export path: ${JSON.stringify(path)}`, 'Every export path must be a clean relative path.');
+      }
+      if (!(bytes instanceof Uint8Array)) {
+        throw projectError('bad_export_payload', `the producer answered no bytes for ${path}`, 'Every export file must be a Uint8Array.');
+      }
+    }
+    for (const path of exportFiles) {
+      if (!(path in files)) {
+        throw projectError('export_file_missing', `the producer did not answer ${path}`, 'The release file set is exact; fix the export adapter.');
+      }
+    }
+    for (const path of Object.keys(files)) {
+      if (!required.has(path)) {
+        const duplicate = SOUNDTRACK_PATH.test(path) && SOUNDTRACK_PATH.test(musicPath)
+          ? `; the release ships exactly one soundtrack asset (${musicPath}) and never a second spelling`
+          : '';
+        throw projectError(
+          'export_file_unexpected',
+          `the producer answered an unapproved export file: ${path}${duplicate}`,
+          'Keep the release minimal; no unbundled source mirror, debug file or extra soundtrack ships.',
+        );
+      }
+    }
+
+    const rows = [];
+    for (const path of [...exportFiles].sort()) {
+      const bytes = files[path];
+      const slash = path.lastIndexOf('/');
+      if (slash !== -1) await io.ensureDir(`${paths.stageDir}/${path.slice(0, slash)}`);
+      await io.writeFile(`${paths.stageDir}/${path}`, bytes);
+      rows.push({ path, bytes: bytes.byteLength, sha256: io.hashBytes(bytes) });
+    }
+
+    const index = rows.find((row) => row.path === 'index.html');
+    const manifest = {
+      format: EXPORT_FORMAT,
+      entry: 'index.html',
+      self: { excluded: true, path: 'manifest.json' },
+      index: { path: 'index.html', bytes: index.bytes, sha256: index.sha256 },
+      files: rows,
+    };
+    const manifestBytes = new TextEncoder().encode(`${JSON.stringify(manifest, null, 2)}\n`);
+    await io.writeFile(`${paths.stageDir}/manifest.json`, manifestBytes);
+
+    const measured = [];
+    for (const path of [...exportFiles, 'manifest.json'].sort()) {
+      const bytes = path === 'manifest.json' ? manifestBytes : files[path];
+      const encoded = await measure(bytes);
+      if (!Number.isInteger(encoded?.gzip9) || !Number.isInteger(encoded?.brotli11)) {
+        throw new TypeError(`measure answered no gzip9/brotli11 integer lengths for ${path}`);
+      }
+      measured.push({
+        path,
+        bytes: bytes.byteLength,
+        gzip9: encoded.gzip9,
+        brotli11: encoded.brotli11,
+        category: categoryOf(path, musicPath),
+      });
+    }
+
+    const report = buildSizeReport(measured, musicPath);
+    const reportBytes = `${JSON.stringify(report, null, 2)}\n`;
+
+    await io.rename(paths.stageDir, paths.outDir);
+    committed = true;
+    try {
+      await io.writeFile(paths.sizePath, new TextEncoder().encode(reportBytes));
+    } catch (cause) {
+      throw projectError(
+        'size_report_failed',
+        `the release was committed but its detached size report could not be written: ${cause?.message ?? cause}`,
+        `The OUT is complete at ${paths.outDir}; write the report beside it or re-export to a fresh target.`,
+      );
+    }
+
+    return {
+      outDir: paths.outDir,
+      sizePath: paths.sizePath,
+      manifest,
+      report,
+      reportBytes,
+      files: manifest.files,
+    };
+  } finally {
+    if (!committed) await io.remove(paths.stageDir);
+  }
+}