animader-cli 0.0.0-stage → 0.1.1

package/src/commands/build.mjs

@@ -0,0 +1,201 @@
+// The `animader build` command: its argv grammar and honesty rules. Build is
+// the real full build — the shared pipeline (graphics bake, score
+// derivation, payload reflection, the reflected target join, the real pacer
+// pack, the playable-by-this-host audit, the score-build receipt) over an
+// input snapshot this build owns. An unknown or ill-typed score target and
+// a packed score this host cannot play both fail the build by name; a green
+// build states the score was validated and names both artifacts. Build
+// still does not prove browser WebGPU availability or audio decoding — the
+// player page owns those diagnostics.
+//
+// The build operation and lib are the package's own adapters/ and lib/
+// (installed-toolchain plan, stage 1); the vendored runtime default still
+// points at the contributor checkout until stage 2's toolchain descriptor.
+
+import { realpath } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+import { createBuildProducers, runFullBuild } from '../../adapters/build-node.mjs';
+import { createNodeIo } from '../../adapters/node-fs.mjs';
+import { createPngineNative } from '../../adapters/pngine.mjs';
+import { DemoError, usageError } from '../../lib/errors.mjs';
+import { SCORE_RECEIPT_FORMAT } from '../../lib/receipt.mjs';
+import { contributorToolchain, resolveToolchain } from '../toolchain.mjs';
+import {
+  BAKED_PAYLOAD,
+  BUILD_RECEIPT,
+  GENERATED_DIR,
+  PACKED_SCORE,
+  inspectProject,
+} from '../../lib/contract.mjs';
+import { commandFolder, resolveConfiguredSeconds } from './project.mjs';
+
+
+/**
+ * Parse the `animader build` argv without touching the filesystem.
+ *
+ * @param {string[]} argv
+ * @returns {{help: boolean, folder: string|null, secondsRaw: string|undefined}}
+ */
+export function parseBuildCommandArgv(argv) {
+  if (!Array.isArray(argv)) {
+    throw usageError('invalid_argv', 'the CLI adapter must pass an argument array', 'Call animader build [folder] [--seconds S]');
+  }
+
+  let folder = null;
+  let secondsRaw;
+  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 === '--seconds') {
+        if (inline !== undefined) {
+          secondsRaw = inline;
+        } else {
+          if (index + 1 >= argv.length) {
+            throw usageError('missing_option_value', `${name} needs a value`, 'Pass --seconds <n>, for example --seconds 8');
+          }
+          index++;
+          secondsRaw = String(argv[index]);
+        }
+      } else {
+        throw usageError(
+          'unknown_option',
+          `unknown option ${name}`,
+          'The supported options are --seconds and --help; use --help for usage.',
+        );
+      }
+      continue;
+    }
+    if (!endOptions && argument.startsWith('-') && argument !== '-') {
+      throw usageError(
+        'unknown_option',
+        `unknown option ${argument}`,
+        'The supported options are --seconds and --help; use --help for usage.',
+      );
+    }
+    if (folder !== null) {
+      throw usageError('extra_argument', `extra folder argument ${JSON.stringify(argument)}`, 'Pass at most one project folder');
+    }
+    folder = argument;
+  }
+
+  return { help, folder, secondsRaw };
+}
+
+export function buildCommandUsageText() {
+  return [
+    'animader build — run the full build into out/',
+    '',
+    'Usage:',
+    '  animader build [folder] [--seconds S]',
+    '',
+    'The folder is the project folder relative to the invocation directory',
+    '(default: the current directory; parent folders are never searched).',
+    'The host duration comes from animader.json; an explicit --seconds wins',
+    'after the config has validated.',
+    '',
+    'build verifies the prepared runtime, validates and bakes the program',
+    'with pngine, derives the timeline score, joins exactly the targets the',
+    'baked program reflects, packs it with the real pacer CLI, audits the',
+    'packed score through the playback runtime (the same load the player',
+    'runs) and writes the score-build receipt. A green build means the',
+    'score compiled and this host can load it — not that a browser has',
+    'WebGPU or decodes the soundtrack.',
+    '',
+    'Options:',
+    '  --seconds S   explicit host duration, a positive number at most 600',
+    '  -h, --help    this text',
+    '',
+    `Generated: ${GENERATED_DIR}/${BAKED_PAYLOAD}, ${GENERATED_DIR}/${PACKED_SCORE} and ${GENERATED_DIR}/${BUILD_RECEIPT}`,
+  ].join('\n');
+}
+
+/**
+ * Run `animader build`: the shared full-build pipeline over an input
+ * snapshot this command owns, then the artifact lines.
+ *
+ * @param {string[]} argv
+ * @param {{out: (line: string) => void, err: (line: string) => void,
+ *          io?: object, native?: object, vendorRoot?: string,
+ *          producers?: object}} context
+ */
+export async function run(argv, context) {
+  const args = parseBuildCommandArgv(argv);
+  if (args.help) {
+    context.out(buildCommandUsageText());
+    return;
+  }
+
+  const folder = commandFolder(args);
+  const { seconds } = await resolveConfiguredSeconds({
+    folder,
+    secondsRaw: args.secondsRaw,
+    io: context.io ?? createNodeIo(),
+  });
+
+  let real;
+  try {
+    real = await realpath(folder);
+  } catch {
+    throw new DemoError('folder_missing', `the project folder does not exist: ${folder}`, {
+      exitCode: 3,
+      remedy: 'Pass the folder that holds program.sjon, timeline.piece.sjon and one of soundtrack.wav, soundtrack.ogg, soundtrack.opus.',
+    });
+  }
+
+  const io = context.io ?? createNodeIo();
+  const project = await inspectProject({ folder: real, io });
+  // The toolchain descriptor owns every artifact root: the contributor
+  // workspace's vendored bundle and checkout binaries, or the installed
+  // package tree's module-resolved artifacts (installed-toolchain plan,
+  // stage 2). A missing artifact fails inside it with its named remedy.
+  const toolchain = context.toolchain
+    ?? (context.vendorRoot !== undefined
+      ? contributorToolchain({ vendorRoot: context.vendorRoot })
+      : await resolveToolchain());
+
+  context.out('animader build — full build');
+  context.out(`project: ${real}`);
+  context.out(`show: ${seconds}s (host policy; no pacer transport is inferred)`);
+
+  const built = await runFullBuild({
+    project,
+    seconds,
+    paths: {
+      folder: real,
+      outDir: join(real, GENERATED_DIR),
+      payload: join(real, GENERATED_DIR, BAKED_PAYLOAD),
+      score: join(real, GENERATED_DIR, PACKED_SCORE),
+      receipt: join(real, GENERATED_DIR, BUILD_RECEIPT),
+      projectName: basename(real),
+    },
+    native: context.native ?? createPngineNative({ binary: toolchain.pngine.cli }),
+    runtime: { verify: () => toolchain.verifyRuntime() },
+    producers: context.producers ?? createBuildProducers({ toolchain }),
+    io,
+  });
+
+  context.out(`stages: ${built.stages.join(' -> ')}`);
+  context.out(`runtime: ${built.receipt.runtime.files} files, digest ${built.receipt.runtime.digest}`);
+  context.out(`payload: ${GENERATED_DIR}/${BAKED_PAYLOAD} (${built.receipt.outputs.payload.bytes} bytes, sha256 ${built.receipt.outputs.payload.sha256})`);
+  context.out(`score: ${GENERATED_DIR}/${PACKED_SCORE} (${built.receipt.outputs.score.bytes} bytes, sha256 ${built.receipt.outputs.score.sha256})`);
+  context.out('audit: playable by this host (loadPackedShow over the packed bytes and the baked reflection)');
+  context.out(`receipt: ${GENERATED_DIR}/${BUILD_RECEIPT} (${SCORE_RECEIPT_FORMAT}; score validated)`);
+  context.out(`inputs: ${built.receipt.inputs.files.length} files hashed (method ${built.receipt.inputs.method})`);
+  context.out(`pngine: ${built.receipt.toolchain.pngine.sha256}`);
+  context.out(`pacer: ${built.receipt.toolchain.pacer.sha256}`);
+}

package/src/commands/dev.mjs

@@ -0,0 +1,214 @@
+// The `animader dev` command: its argv grammar and the process-level
+// lifecycle around one dev session. The session itself is the demo's
+// `runDevSession`: the shared score-validating build (bake, derive,
+// reflect, join, pack, the playable-by-this-host audit, the score-build
+// receipt) staged as immutable generations outside the project tree, the
+// loopback server pinning every project byte to one generation, the
+// recursive watcher feeding a coalescing build loop, and the
+// development-only /dev channel reloading the page on successful builds.
+// `--no-watch` serves one build with no watcher.
+//
+// seconds and port rules: the host duration comes from the shared
+// animader.json resolution (--seconds wins after a present config
+// validates) re-resolved on every build, and the port keeps the demo's
+// free-port default and bounds.
+//
+// The session operation is the package's own adapters/devsession.mjs
+// (installed-toolchain plan, stage 1); its artifact roots come from the
+// contributor workspace until stage 2 installs the toolchain descriptor.
+
+import { createNodeIo } from '../../adapters/node-fs.mjs';
+import { parsePort } from '../../lib/contract.mjs';
+import { usageError } from '../../lib/errors.mjs';
+import { runDevSession } from '../../adapters/devsession.mjs';
+import { commandFolder, resolveConfiguredSeconds } from './project.mjs';
+import { resolve } from 'node:path';
+
+/**
+ * Parse the `animader dev` argv without touching the filesystem.
+ *
+ * @param {string[]} argv
+ * @returns {{help: boolean, folder: string|null, secondsRaw: string|undefined,
+ *            port: number, open: boolean, watch: boolean}}
+ */
+export function parseDevCommandArgv(argv) {
+  if (!Array.isArray(argv)) {
+    throw usageError('invalid_argv', 'the CLI adapter must pass an argument array', 'Call animader dev [folder] [--seconds S] [--port N] [--no-open] [--no-watch]');
+  }
+
+  let folder = null;
+  let secondsRaw;
+  let portRaw;
+  let open = true;
+  let watch = true;
+  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 === '--no-watch') {
+        if (inline !== undefined) {
+          throw usageError('unexpected_option_value', '--no-watch takes no value', 'Use --no-watch by itself');
+        }
+        watch = false;
+      } else {
+        throw usageError(
+          'unknown_option',
+          `unknown option ${name}`,
+          'The supported options are --seconds, --port, --no-open, --no-watch and --help; use --help for usage.',
+        );
+      }
+      continue;
+    }
+    if (!endOptions && argument.startsWith('-') && argument !== '-') {
+      throw usageError(
+        'unknown_option',
+        `unknown option ${argument}`,
+        'The supported options are --seconds, --port, --no-open, --no-watch and --help; use --help for usage.',
+      );
+    }
+    if (folder !== null) {
+      throw usageError('extra_argument', `extra folder argument ${JSON.stringify(argument)}`, 'Pass at most one project folder');
+    }
+    folder = argument;
+  }
+
+  if (help) {
+    return { help: true, folder, secondsRaw, port: 0, open, watch };
+  }
+  return { help: false, folder, secondsRaw, port: parsePort(portRaw), open, watch };
+}
+
+export function devCommandUsageText() {
+  return [
+    'animader dev — serve a project on loopback, watch edits and reload',
+    '',
+    'Usage:',
+    '  animader dev [folder] [--seconds S] [--port N] [--no-open] [--no-watch]',
+    '',
+    'The folder is the project folder relative to the invocation directory',
+    '(default: the current directory; parent folders are never searched).',
+    'The host duration comes from animader.json; an explicit --seconds wins',
+    'after the config has validated.',
+    '',
+    'dev runs the full build (bake, derive, reflect, join, pack, the host',
+    'audit and the score-build receipt) into staging outside the project,',
+    'serves it pinned to one immutable generation, watches the authored',
+    'tree (kernels and nested assets included; out/ and dist/ excluded)',
+    'and rebuilds on edits: bursts coalesce, a change during a build',
+    'discards that candidate and queues exactly one rebuild, and the page',
+    'is told to reload only on a successful build — a full reload into',
+    'READY, Start pressed again, no state preserved. A failed build keeps',
+    'serving the last successful generation and reports the error; before',
+    'the first successful build the root serves an error/recovery page.',
+    '',
+    'Options:',
+    `  --seconds S   explicit host duration, a positive number at most 600`,
+    '  --port N      127.0.0.1 port; 0 (the default) chooses a free one',
+    '  --no-open     do not attempt to launch the browser',
+    '  --no-watch    serve this one build without watching or reloading',
+    '  -h, --help    this text',
+    '',
+    "The player page, not the terminal, reports WebGPU and audio health:",
+    'READY is earned only in the browser\'s own semantic chain.',
+  ].join('\n');
+}
+
+/**
+ * Run `animader dev`. The preflight per build is the shared full build; a
+ * score this host cannot play never reaches a served generation. Serves
+ * until SIGINT/SIGTERM, then closes the watcher, the server, the channel
+ * connections and the generation store, and prints the stopping signal.
+ * If nothing was ever published, the last build error owns the exit code.
+ * `context.signals` may replace the default signal set (an empty array
+ * returns immediately with the live session so a test caller owns the
+ * wait).
+ *
+ * @param {string[]} argv
+ * @param {{out: (line: string) => void, err: (line: string) => void,
+ *          io?: object, native?: object, vendorRoot?: string,
+ *          producers?: object, launch?: object, signals?: string[]}} context
+ */
+export async function run(argv, context) {
+  const args = parseDevCommandArgv(argv);
+  if (args.help) {
+    context.out(devCommandUsageText());
+    return;
+  }
+
+  // The folder resolves once, against the invocation directory; the
+  // session and every per-build re-resolution use this absolute path, so
+  // a cwd change after the command starts can never move the project.
+  const folderPath = resolve(commandFolder(args));
+  const io = context.io ?? createNodeIo();
+  const session = await runDevSession({
+    folder: folderPath,
+    port: args.port,
+    open: args.open,
+    watch: args.watch,
+    resolveSeconds: () => resolveConfiguredSeconds({ folder: folderPath, secondsRaw: args.secondsRaw, io }),
+    out: context.out,
+    err: context.err,
+    hosts: { native: context.native, vendorRoot: context.vendorRoot, producers: context.producers, launch: context.launch },
+  });
+
+  const signals = context.signals ?? ['SIGINT', 'SIGTERM'];
+  if (signals.length === 0) {
+    return { served: session.served, session };
+  }
+  const signal = await new Promise((resolve) => {
+    const attached = [];
+    const stop = (name) => {
+      // Deregister every listener, including the one that fired, so no
+      // stray signal handlers survive this command in the host process.
+      for (const { name: other, handler } of attached) process.off(other, handler);
+      resolve(name);
+    };
+    for (const name of signals) {
+      const handler = () => stop(name);
+      process.once(name, handler);
+      attached.push({ name, handler });
+    }
+  });
+  const outcome = await session.stop();
+  context.out(`stopped (${signal})`);
+  if (!outcome.published && outcome.lastError !== null) {
+    // Nothing was ever served and a build actually failed: the last error
+    // keeps its exit class so scripts and CI see the same identity a
+    // pre-build failure had. A stop before the first publish with no
+    // failure — the operator interrupted the initial build, and the loop
+    // discarded the abandoned candidate — is a clean stop, not an error
+    // exit, so the process exit code is left alone.
+    process.exitCode = outcome.lastError.exitCode ?? 1;
+  }
+  return { served: session.served, session };
+}