animader-cli 0.0.0-stage → 0.1.0

package/lib/new.mjs

@@ -0,0 +1,304 @@
+// Fresh-project authoring decisions. Portable: paths, starter metadata and the
+// exact write order live here; filesystem access and argv/process wiring come
+// from host adapters. The starter is the same tracked fixture the demo already
+// proves, so a new project needs no prepared vendor bundle or native producer.
+//
+// Honesty boundary: the emptiness check is point-in-time, not a lock. Files are
+// written one at a time with the adapter's atomic per-file write; a write-phase
+// failure leaves complete files behind and names them. The adapter removes only
+// the failed write's own temporary file; an empty parent directory may remain.
+// There is no rollback and no transaction claim.
+
+import { PROJECT_FILES } from './contract.mjs';
+import { DemoError, EXIT_CODES, projectError, usageError } from './errors.mjs';
+import { createTestTone } from './wav.mjs';
+
+const EMBER_STARTER = new URL('../starters/ember/', import.meta.url).href;
+const CIRCLE_STARTER = new URL('../starters/circle/', import.meta.url).href;
+
+const STARTER_FILES = [
+  { path: PROJECT_FILES.program, source: 'program.sjon' },
+  { path: PROJECT_FILES.timeline, source: 'timeline.piece.sjon' },
+  { path: 'kernels/curl.wgsl', source: 'kernels/curl.wgsl' },
+  { path: 'kernels/ember.wgsl', source: 'kernels/ember.wgsl' },
+  { path: 'kernels/hash.wgsl', source: 'kernels/hash.wgsl' },
+  { path: 'kernels/simplex.wgsl', source: 'kernels/simplex.wgsl' },
+  { path: 'bake/spans.bin', source: 'bake/spans.bin' },
+  { path: PROJECT_FILES.soundtrack, generate: 'test-tone' },
+].map((entry) => Object.freeze(entry));
+
+// The tutorial's end-of-step-6 circle: one kernel, an eight-second path
+// with beat pulses, a complete timeline, plus the project config, the
+// generated-output ignore entries and a README. `gitignore` is the tracked
+// source of the target's `.gitignore` so git does not interpret it here.
+const CIRCLE_FILES = [
+  { path: 'animader.json', source: 'animader.json' },
+  { path: PROJECT_FILES.program, source: 'program.sjon' },
+  { path: PROJECT_FILES.timeline, source: 'timeline.piece.sjon' },
+  { path: 'kernels/circle.wgsl', source: 'kernels/circle.wgsl' },
+  { path: '.gitignore', source: 'gitignore' },
+  { path: 'README.md', source: 'README.md' },
+  { path: PROJECT_FILES.soundtrack, generate: 'test-tone' },
+].map((entry) => Object.freeze(entry));
+
+export const STARTERS = Object.freeze({
+  circle: Object.freeze({
+    name: 'circle',
+    sourceRoot: CIRCLE_STARTER,
+    files: Object.freeze(CIRCLE_FILES),
+  }),
+  ember: Object.freeze({
+    name: 'ember',
+    sourceRoot: EMBER_STARTER,
+    files: Object.freeze(STARTER_FILES),
+  }),
+});
+
+export const STARTER_NAMES = Object.freeze(Object.keys(STARTERS));
+
+function starterList() {
+  return STARTER_NAMES.join(', ');
+}
+
+function inFolder(folder, name) {
+  return `${String(folder).replace(/[\\/]+$/, '')}/${name}`;
+}
+
+/**
+ * Parse the fresh-project argv without touching the filesystem.
+ *
+ * @param {string[]} argv
+ * @returns {{help: boolean, folder: string|null, starter: string}}
+ */
+export function parseNewArgv(argv) {
+  if (!Array.isArray(argv)) {
+    throw usageError('invalid_argv', 'the CLI adapter must pass an argument array', 'Call node demo/new.mjs <folder> [--starter ember]');
+  }
+
+  let folder = null;
+  let starter = 'ember';
+  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);
+      if (name === '--starter') {
+        if (inline !== undefined) {
+          starter = inline;
+        } else {
+          if (index + 1 >= argv.length) {
+            throw usageError('missing_option_value', `${name} needs a value`, `Pass ${name} ${starterList()}`);
+          }
+          index++;
+          starter = String(argv[index]);
+        }
+      } else {
+        throw usageError(
+          'unknown_option',
+          `unknown option ${name}`,
+          `The supported option is --starter (available: ${starterList()}); use --help for usage.`,
+        );
+      }
+      continue;
+    }
+    if (!endOptions && argument.startsWith('-') && argument !== '-') {
+      throw usageError(
+        'unknown_option',
+        `unknown option ${argument}`,
+        `The supported option is --starter (available: ${starterList()}); use --help for usage.`,
+      );
+    }
+    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, starter };
+  if (folder === null || folder === '') {
+    throw usageError(
+      'missing_folder',
+      'exactly one project folder is required',
+      'Run: node demo/new.mjs <folder> [--starter ember]',
+    );
+  }
+  if (!STARTER_NAMES.includes(starter)) {
+    throw usageError(
+      'unknown_starter',
+      `unknown starter ${JSON.stringify(starter)}`,
+      `Available starters: ${starterList()}`,
+    );
+  }
+  return { help: false, folder, starter };
+}
+
+export function newUsageText() {
+  return [
+    'animader demo new',
+    '',
+    'Usage:',
+    '  node demo/new.mjs <folder> [--starter ember]',
+    '',
+    'Create an editable project from a tracked starter. The folder must not',
+    'exist, or must be an empty directory.',
+    '',
+    'Files:',
+    `  ${PROJECT_FILES.program}`,
+    `  ${PROJECT_FILES.timeline}`,
+    `  ${PROJECT_FILES.soundtrack}          generated 8.0 s labeled test tone; replace with your audio`,
+    '                          (later, one of soundtrack.wav, soundtrack.ogg or',
+    '                           soundtrack.opus — exactly one may exist at a time)',
+    '  kernels/{curl,ember,hash,simplex}.wgsl',
+    '  bake/spans.bin',
+    '',
+    'Options:',
+    `  --starter NAME   starter to copy (default: ember; available: ${starterList()})`,
+    "  --               end options; the next argument is the folder even if it starts with '-'",
+    '  -h, --help       this text',
+    '',
+    'A folder symlink is followed. A target inside the tracked starter source is refused.',
+  ].join('\n');
+}
+
+export function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function targetInspectionFailure(error, folder) {
+  return new DemoError('target_inspection_failed', `could not inspect ${folder}: ${error?.message ?? String(error)}`, {
+    exitCode: EXIT_CODES.project,
+    remedy: 'Check the folder path and its permissions; no files were written.',
+    cause: error,
+  });
+}
+
+async function requireEmptyTarget({ folder, io }) {
+  let stats;
+  try {
+    stats = await io.statFile(folder);
+  } catch (error) {
+    throw targetInspectionFailure(error, folder);
+  }
+  if (stats === null) return;
+
+  if (!stats.isDirectory) {
+    throw projectError(
+      'project_folder_not_empty',
+      `${folder} exists but is not a directory`,
+      'Pass a folder that does not exist or an empty directory; no files were written.',
+    );
+  }
+
+  let entries;
+  try {
+    entries = await io.listDir(folder);
+  } catch (error) {
+    throw targetInspectionFailure(error, folder);
+  }
+  if (entries.length > 0) {
+    const first = [...entries].sort()[0];
+    throw projectError(
+      'project_folder_not_empty',
+      `the project folder is not empty: ${folder} (first conflicting entry: ${first})`,
+      'Choose a folder that does not exist or an empty directory; no files were written.',
+    );
+  }
+}
+
+/**
+ * Create one editable project from a frozen starter.
+ *
+ * @param {Object} options
+ * @param {string} options.folder
+ * @param {string} options.starter
+ * @param {Object} options.io
+ * @param {(path: string|URL) => Promise<null|{isFile: boolean, isDirectory: boolean, size: number}>} options.io.statFile
+ * @param {(path: string|URL) => Promise<Uint8Array>} options.io.readFile
+ * @param {(path: string, bytes: Uint8Array) => Promise<void>} options.io.writeFile
+ * @param {(path: string) => Promise<string[]>} options.io.listDir
+ * @param {(bytes: Uint8Array) => string} options.io.hashBytes
+ */
+export async function createProject({ folder, starter, io }) {
+  if (typeof folder !== 'string' || folder === '') {
+    throw projectError('missing_folder', 'the project folder is empty', 'Pass the folder to create.');
+  }
+  if (!STARTER_NAMES.includes(starter)) {
+    throw usageError('unknown_starter', `unknown starter ${JSON.stringify(starter)}`, `Available starters: ${starterList()}`);
+  }
+  if (!io
+    || typeof io.statFile !== 'function'
+    || typeof io.readFile !== 'function'
+    || typeof io.writeFile !== 'function'
+    || typeof io.listDir !== 'function'
+    || typeof io.hashBytes !== 'function') {
+    throw new TypeError('createProject needs io.statFile, io.readFile, io.writeFile, io.listDir and io.hashBytes');
+  }
+
+  await requireEmptyTarget({ folder, io });
+
+  const definition = STARTERS[starter];
+  const staged = [];
+  for (const entry of definition.files) {
+    let bytes;
+    try {
+      bytes = entry.generate === 'test-tone'
+        ? createTestTone()
+        : await io.readFile(new URL(entry.source, definition.sourceRoot));
+    } catch (error) {
+      throw new DemoError(
+        'starter_source_unreadable',
+        `could not read starter source ${entry.source ?? entry.path}: ${error?.message ?? String(error)}`,
+        {
+          exitCode: EXIT_CODES.project,
+          remedy: 'Restore the tracked starter source under the animader-cli package (npm/cli/starters); no files were written.',
+          cause: error,
+        },
+      );
+    }
+    if (!bytes || typeof bytes.byteLength !== 'number' || bytes.byteLength === 0) {
+      throw new DemoError('starter_source_empty', `starter source ${entry.source ?? entry.path} is empty`, {
+        exitCode: EXIT_CODES.project,
+        remedy: 'Restore the tracked starter source under the animader-cli package (npm/cli/starters); no files were written.',
+      });
+    }
+    staged.push({ path: entry.path, bytes, sha256: io.hashBytes(bytes) });
+  }
+
+  const created = [];
+  for (const file of staged) {
+    try {
+      await io.writeFile(inFolder(folder, file.path), file.bytes);
+    } catch (error) {
+      const complete = created.length > 0 ? created.map((entry) => entry.path).join(', ') : 'none';
+      throw new DemoError(
+        'project_write_failed',
+        `writing ${file.path} failed: ${error?.message ?? String(error)}. Complete files already written: ${complete}`,
+        {
+          exitCode: EXIT_CODES.project,
+          remedy: 'The complete files listed above remain on disk and are not rolled back. Inspect the folder and remove it yourself before retrying.',
+          cause: error,
+        },
+      );
+    }
+    created.push({ path: file.path, bytes: file.bytes.byteLength, sha256: file.sha256 });
+  }
+
+  const contract = {};
+  for (const [seat, name] of Object.entries(PROJECT_FILES)) {
+    const file = created.find((entry) => entry.path === name);
+    contract[seat] = { name, bytes: file.bytes, sha256: file.sha256 };
+  }
+  return { folder, starter: definition.name, files: created, contract };
+}

package/lib/pipeline.mjs

@@ -0,0 +1,247 @@
+// The shared full-build pipeline (plan section 4): the export's own stages
+// — graphics bake, program reflection, score derivation and Pacer packing —
+// composed once, plus the playable-by-this-host audit. `animader build`,
+// `animader dev`'s preflight and the release export all call
+// `buildProject`; each caller owns the input snapshot the stages run on and
+// the paths the artifacts land at. There is no second implementation and no
+// child process here: the bake is `bakeProject`, the join is the score
+// module's own `reflectedJoin`, and the audit IS `loadPackedShow` — the
+// same load the release player runs — so a successful `pacer pack` alone
+// can never be reported as a playable build.
+//
+// Every producer is an injected port (`producers.deriveScore`,
+// `reflectPayload`, `packScore`, `pacerRtWasm`, `loadPacerRt`), so this
+// module carries no `node:` import, no process state and no DOM. The audit
+// decision itself is not injectable: it always runs, and a `ShowError` it
+// answers keeps its own code, stage, document and diagnostics in the
+// `DemoError` the CLI reports — the host's identity, never a generic
+// "build failed".
+//
+// Ownership: stage order, the audit-before-receipt rule, the receipt
+// assembly, the drift check between an inspection and its snapshot. WASM
+// bytes, native processes and filesystem IO belong to the adapters.
+
+import { bakeProject } from './build.mjs';
+import { buildError } from './errors.mjs';
+import { loadPackedShow, reflectedJoin, ShowError } from './score.mjs';
+import { makeScoreBuildReceipt, serializeScoreBuildReceipt } from './receipt.mjs';
+
+/** The stages a full build walks, in order. */
+export const BUILD_STAGES = Object.freeze(['bake', 'derive', 'reflect', 'join', 'pack', 'audit', 'receipt']);
+
+/** The conservative input-coverage method this toolchain records today. */
+export const INPUT_SNAPSHOT_METHOD = 'input-snapshot';
+
+/**
+ * What the receipt's input rows mean when the compiler answers no
+ * dependency metadata of its own: every authored file of the filtered
+ * input snapshot the build consumed, with the generated output tree, VCS
+ * and dependency directories and owned export trees excluded. No second
+ * SJON reader exists to narrow this set.
+ */
+export const INPUT_SNAPSHOT_NOTE = 'every file of the filtered input snapshot the build consumed (generated out/, .git, node_modules and owned export trees excluded); the compiler answers no dependency metadata of its own, so this conservative set stands in for it';
+
+const AUDIT_REMEDY = 'Fix the timeline so the score is playable by this host: every score target must be one the reflected program declares, and automation must stay on the registries this show hosts. This audit is the same load the player runs; it is never skipped.';
+
+function wrapShowError(error, stageLabel) {
+  if (!(error instanceof ShowError)) return error;
+  return buildError(error.code, `${error.message} (${stageLabel} failed at stage '${error.stage}')`, AUDIT_REMEDY);
+}
+
+/**
+ * The playable-by-this-host audit: load the exact packed bytes through
+ * `loadPackedShow` with the playback-only runtime and the baked program's
+ * own reflection. A load the host refuses — an unknown target, an
+ * unsupported automation shape, a metadata gap — answers a `DemoError`
+ * carrying the host's own error code and message.
+ *
+ * @param {Object} options
+ * @param {string} [options.documentName] the artifact name failures keep
+ * @param {Uint8Array} options.bytes the packed 'PACB' score
+ * @param {Object<string, {type: string, elemCount: number}>} options.reflection
+ * @param {Uint8Array} options.pacerRtWasm
+ * @param {Function} options.loadPacerRt the `PacerRt.load` shape
+ */
+export async function auditPackedScore({ documentName = 'score.pacb', bytes, reflection, pacerRtWasm, loadPacerRt }) {
+  try {
+    return await loadPackedShow({
+      document: { name: documentName, bytes },
+      dep: { pacerRtWasm, reflection },
+      factories: { loadPacerRt },
+    });
+  } catch (error) {
+    const wrapped = wrapShowError(error, `the playable-by-this-host audit of ${documentName}`);
+    if (wrapped === error) throw error;
+    wrapped.cause = error;
+    throw wrapped;
+  }
+}
+
+/**
+ * Refuse a snapshot whose inspected rows drifted from the inspection the
+ * caller started from. One implementation for the export's and the build's
+ * drift checks; `what` names the failing operation in the error identity.
+ *
+ * @param {{original: {files: Object}, copied: {files: Object}, what: string}} options
+ */
+export async function assertProjectSnapshotsMatch({ original, copied, what }) {
+  for (const [seat, row] of Object.entries(original?.files ?? {})) {
+    const actual = copied?.files?.[seat];
+    if (!row || actual?.name !== row.name || actual?.sha256 !== row.sha256 || actual?.bytes !== row.bytes) {
+      throw buildError(
+        `${what}_project_drift`,
+        `${row?.name ?? seat} changed while the ${what} was preparing`,
+        `Re-run the ${what} from a quiet project folder.`,
+      );
+    }
+  }
+}
+
+function portCheck(producers) {
+  if (!producers
+    || typeof producers.deriveScore !== 'function'
+    || typeof producers.reflectPayload !== 'function'
+    || typeof producers.packScore !== 'function'
+    || typeof producers.pacerRtWasm !== 'function'
+    || typeof producers.loadPacerRt !== 'function') {
+    throw new TypeError('buildProject needs producers.deriveScore, reflectPayload, packScore, pacerRtWasm and loadPacerRt (the real or fake build ports)');
+  }
+}
+
+/**
+ * Walk the full build over one consistent input snapshot: bake the
+ * program, derive the score from the snapshot's timeline, reflect the
+ * baked payload, join exactly the targets the program declares, pack the
+ * score with the real pacer CLI, audit the packed bytes through the
+ * playback runtime, then — only after the audit passes — write the
+ * score-build receipt. A failed stage throws before any later stage runs,
+ * and a failed audit never leaves a receipt claiming a validated score.
+ *
+ * @param {Object} options
+ * @param {{folder: string, files: Object}} options.project the snapshot's inspection
+ * @param {number} options.seconds resolved host show length
+ * @param {{folder: string, outDir: string, payload: string, score: string, receipt: string,
+ *          workDir: string, projectName: string, payloadRelative: string,
+ *          scoreRelative: string, receiptRelative: string}} options.paths
+ * @param {Object} options.io
+ * @param {Object} options.native the pngine adapter
+ * @param {Object} options.runtime `{ verify }` over the prepared bundle
+ * @param {(bytes: Uint8Array) => string} options.hashBytes
+ * @param {Array<{path: string, bytes: number, sha256: string}>} options.inputFiles
+ *   the consumed-input rows the receipt records
+ * @param {object} options.producers the build ports
+ * @returns {Promise<{stages: string[], payloadBytes: Uint8Array, payloadSha256: string,
+ *           scoreBytes: Uint8Array, scoreSha256: string, reflection: Object,
+ *           join: Array<{name: string, ncomp: number}>, receipt: object}>}
+ */
+export async function buildProject({
+  project,
+  seconds,
+  paths,
+  io,
+  native,
+  runtime,
+  hashBytes,
+  inputFiles,
+  producers,
+}) {
+  portCheck(producers);
+
+  // bake: the shared graphics bake (verify, clear stale, validate, bake).
+  const baked = await bakeProject({
+    project,
+    paths,
+    staleFiles: [paths.payload, paths.score, paths.receipt],
+    io,
+    native,
+    runtime,
+    hashBytes,
+  });
+
+  // derive: the piece boundary derives the score from the snapshot's own
+  // timeline text; the pipeline never repairs or invents one.
+  const timelineBytes = await io.readFile(`${paths.folder}/${project.files.timeline.name}`);
+  const timelineText = new TextDecoder().decode(timelineBytes);
+  let scoreText;
+  try {
+    scoreText = await producers.deriveScore(timelineText);
+  } catch (error) {
+    if (error?.code === 'derive_failed' || error?.code === 'piece_host_failed') throw error;
+    throw buildError(
+      'derive_failed',
+      `the piece boundary refused the derivation: ${error?.message ?? String(error)}`,
+      'Run the same timeline through the dev player; the build never invents or repairs a score.',
+    );
+  }
+  if (typeof scoreText !== 'string' || scoreText === '') {
+    throw buildError('derive_failed', 'the piece boundary answered an empty derived score', 'Inspect the timeline; the build refuses an empty score.');
+  }
+
+  // reflect: the baked program's own uniform table, never a second reader.
+  const reflection = await producers.reflectPayload(baked.bytes);
+
+  // join: exactly the targets the reflection declares, in its table order.
+  let join;
+  try {
+    join = reflectedJoin(reflection, project.files.program.name);
+  } catch (error) {
+    const wrapped = wrapShowError(error, `the score join for ${project.files.program.name}`);
+    wrapped.cause = error;
+    throw wrapped;
+  }
+
+  // pack: the real pacer CLI compiles the derived score against that one
+  // registry; a refusal (an unknown or ill-typed target) is its own error.
+  const packed = await producers.packScore({ scoreText, reflection, outPath: paths.score, workDir: paths.workDir });
+  if (!(packed?.bytes instanceof Uint8Array) || packed.bytes.byteLength === 0) {
+    throw buildError('pack_failed', 'the pacer pack answered no packed score bytes', 'Inspect the pacer CLI run; a successful pack lands a PACB file.');
+  }
+  if (!packed.tool || typeof packed.tool.name !== 'string' || packed.tool.name === '' || !/^[0-9a-f]{64}$/.test(String(packed.tool.sha256 ?? ''))) {
+    throw buildError('pack_failed', 'the pacer pack answered no tool identity (name and sha256)', 'The pack port must name the CLI it ran; the receipt records it.');
+  }
+
+  // audit: load the exact packed bytes through the playback runtime with
+  // the baked program's reflection. Never skipped, never preceded by the
+  // receipt.
+  const pacerRtWasm = await producers.pacerRtWasm();
+  await auditPackedScore({
+    documentName: paths.scoreRelative,
+    bytes: packed.bytes,
+    reflection,
+    pacerRtWasm,
+    loadPacerRt: producers.loadPacerRt,
+  });
+
+  // receipt: proof of a validated score, written only after the audit.
+  const receipt = makeScoreBuildReceipt({
+    project,
+    projectName: paths.projectName,
+    seconds,
+    outputs: {
+      payload: { name: paths.payloadRelative, bytes: baked.bytes.byteLength, sha256: baked.sha256 },
+      score: { name: paths.scoreRelative, bytes: packed.bytes.byteLength, sha256: hashBytes(packed.bytes) },
+    },
+    inputs: {
+      method: INPUT_SNAPSHOT_METHOD,
+      note: INPUT_SNAPSHOT_NOTE,
+      files: inputFiles,
+    },
+    runtime: baked.runtime,
+    toolchain: {
+      pngine: baked.identity,
+      pacer: { name: packed.tool.name, sha256: packed.tool.sha256 },
+    },
+  });
+  await io.writeFile(paths.receipt, serializeScoreBuildReceipt(receipt));
+
+  return {
+    stages: [...BUILD_STAGES],
+    payloadBytes: baked.bytes,
+    payloadSha256: baked.sha256,
+    scoreBytes: packed.bytes,
+    scoreSha256: hashBytes(packed.bytes),
+    reflection,
+    join,
+    receipt,
+  };
+}