animader-cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not limited
+to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

package/adapters/build-node.mjs

@@ -0,0 +1,261 @@
+// The Node adapter for the shared full build (plan section 4). It owns the
+// real producer ports the portable pipeline (`lib/pipeline.mjs`) calls —
+// the vendored PieceHost derivation, pngine's own reflection readers, the
+// real `pacer pack` CLI, and the vendored playback-only PacerRt the host
+// audit loads — plus `runFullBuild`, the operation `animader build` and
+// `animader dev`'s preflight run: one input snapshot this build owns
+// (outside the source tree, the same filter the export uses), the pipeline
+// stages over that consistent copy, and the three artifacts copied back
+// into the project's own out/. The export runs the same pipeline on its
+// own snapshot; neither trusts a stale out/.
+
+import { promises as fsp } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { packScore as realPackScore, reflectionOfPayload } from './export-node.mjs';
+import { listSnapshotInputFiles, snapshotProject } from './snapshot.mjs';
+import { createNodeIo, hashBytes } from './node-fs.mjs';
+import { buildError } from '../lib/errors.mjs';
+import { buildProject, assertProjectSnapshotsMatch } from '../lib/pipeline.mjs';
+import { BAKED_PAYLOAD, BUILD_RECEIPT, GENERATED_DIR, PACKED_SCORE, inspectProject } from '../lib/contract.mjs';
+import { resolveRoots } from '../toolchain/prepare.mjs';
+import { contributorToolchain } from '../src/toolchain.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+// The package root and the contributor workspace around it: the vendored
+// runtime bundle still lives under the checkout's demo/vendor, filled by
+// the contributor prepare (toolchain/prepare.mjs).
+const PKG = resolve(HERE, '..');
+const REPO = resolve(PKG, '..', '..');
+
+/** The generated artifacts a full build owns, in out/. */
+export const FULL_BUILD_ARTIFACTS = Object.freeze([BAKED_PAYLOAD, PACKED_SCORE, BUILD_RECEIPT]);
+
+async function importRuntimeModule(toolchain, relative, label, remedy) {
+  const source = await toolchain.runtime.requireFile(relative);
+  try {
+    return await import(pathToFileURL(source).href);
+  } catch (cause) {
+    throw buildError(
+      'vendor_module_missing',
+      `the runtime module ${relative} (${source}) could not be loaded for the ${label}`,
+      remedy,
+    );
+  }
+}
+
+/**
+ * The real build producer ports over the toolchain's runtime and native
+ * tools: the PieceHost score derivation, pngine's own payload reflection,
+ * the real `pacer pack` CLI (with its binary identity for the receipt),
+ * and the playback-only PacerRt plus pacer-rt.wasm the host audit loads.
+ * Tests inject the same shapes.
+ *
+ * The runtime comes from a toolchain descriptor (src/toolchain.mjs): the
+ * contributor workspace's vendored bundle by default, an installed package
+ * tree when the caller resolved one. The legacy {roots, vendorRoot} pair
+ * still constructs a contributor toolchain for the compat entries/tests.
+ *
+ * @param {{toolchain?: object, roots?: object, vendorRoot?: string}} [options]
+ */
+export function createBuildProducers({ toolchain = null, roots, vendorRoot } = {}) {
+  const chain = toolchain ?? contributorToolchain({ roots: roots ?? resolveRoots(), vendorRoot: vendorRoot ?? join(REPO, 'demo', 'vendor') });
+  let pieceHost = null;
+  let pacerRt = null;
+  let pacerRtWasm = null;
+  return {
+    async deriveScore(timelineText) {
+      if (pieceHost === null) {
+        const module = await importRuntimeModule(
+          chain,
+          'animader/piece.js',
+          'score derivation',
+          'Prepare the vendored runtime with node demo/prepare.mjs; the build never falls back to a second reader.',
+        );
+        const wasm = await fsp.readFile(chain.runtime.path('animader/animader.wasm')).catch((cause) => {
+          throw buildError(
+            'vendor_module_missing',
+            `the prepared animader.wasm could not be read for the score derivation: ${cause?.message ?? cause}`,
+            'Prepare the vendored runtime with node demo/prepare.mjs.',
+          );
+        });
+        pieceHost = await module.PieceHost.instantiate(wasm);
+      }
+      return pieceHost.score(timelineText);
+    },
+    reflectPayload(payloadBytes) {
+      return reflectionOfPayload({ payloadBytes, toolchain: chain });
+    },
+    async packScore({ scoreText, reflection, outPath, workDir }) {
+      return realPackScore({ scoreText, reflection, outPath, workDir, pacerCli: chain.pacer.cli });
+    },
+    async pacerRtWasm() {
+      if (pacerRtWasm === null) {
+        pacerRtWasm = await fsp.readFile(chain.runtime.path('pacer/pacer-rt.wasm')).catch((cause) => {
+          throw buildError(
+            'vendor_module_missing',
+            `the prepared pacer-rt.wasm could not be read for the playability audit: ${cause?.message ?? cause}`,
+            'Prepare the vendored runtime with node demo/prepare.mjs; the audit never runs against a guessed runtime.',
+          );
+        });
+      }
+      return pacerRtWasm;
+    },
+    async loadPacerRt(wasm, bytes, options) {
+      if (pacerRt === null) {
+        const module = await importRuntimeModule(
+          chain,
+          'pacer/rt.js',
+          'playability audit',
+          'Prepare the vendored runtime with node demo/prepare.mjs; the audit loads the same runtime the release ships.',
+        );
+        pacerRt = module.PacerRt;
+      }
+      return pacerRt.load(wasm, bytes, options);
+    },
+  };
+}
+
+/**
+ * One full build over a snapshot this build owns: clear the project's stale
+ * generated artifacts, copy the authored project outside the source tree
+ * (the export's own filter), refuse drift between the caller's inspection
+ * and the copy, hash the filtered snapshot for the receipt, run the shared
+ * pipeline there, then copy the three artifacts back into the project's
+ * out/ and verify them against the receipt. A failed stage leaves no
+ * out/ artifact behind, so no stale receipt can claim a validated score.
+ *
+ * @param {Object} options
+ * @param {{folder: string, files: Object}} options.project the inspected project
+ * @param {number} options.seconds resolved host show length
+ * @param {{folder: string, outDir: string, payload: string, score: string, receipt: string,
+ *          projectName: string}} options.paths the project's real out/ destinations
+ * @param {{outDir: string, stageDir: string, sizePath: string}} [options.snapshotPaths]
+ *   owned export/staging trees inside the project to exclude from the snapshot
+ * @param {Object} options.native the pngine adapter
+ * @param {Object} options.runtime `{ verify }` over the prepared bundle
+ * @param {Object} options.producers the build ports (see createBuildProducers)
+ * @param {Object} [options.io]
+ * @param {string} [options.workRoot] parent for the snapshot; default is the
+ *   OS temporary directory, always outside the source tree
+ */
+export async function runFullBuild({
+  project,
+  seconds,
+  paths,
+  snapshotPaths,
+  native,
+  runtime,
+  producers,
+  io = createNodeIo(),
+  workRoot,
+}) {
+  // A failed build must leave no valid-looking claim in out/: the stale
+  // artifacts go first, exactly like the legacy preflight cleared its own.
+  await fsp.mkdir(paths.outDir, { recursive: true });
+  for (const name of FULL_BUILD_ARTIFACTS) {
+    await fsp.rm(join(paths.outDir, name), { force: true });
+  }
+
+  const { built, work, workProject } = await runSnapshotBuild({
+    project,
+    seconds,
+    projectName: paths.projectName,
+    snapshotPaths,
+    native,
+    runtime,
+    producers,
+    io,
+    workRoot,
+  });
+
+  try {
+    const destinations = [
+      [join(workProject, GENERATED_DIR, BAKED_PAYLOAD), paths.payload, built.receipt.outputs.payload.sha256],
+      [join(workProject, GENERATED_DIR, PACKED_SCORE), paths.score, built.receipt.outputs.score.sha256],
+    ];
+    for (const [source, destination, expected] of destinations) {
+      const bytes = await fsp.readFile(source);
+      if (hashBytes(bytes) !== expected) {
+        throw buildError('build_output_drift', 'a built artifact does not match its own receipt after the copy', 'Re-run the build; the pipeline never publishes bytes it did not verify.');
+      }
+      await fsp.writeFile(destination, bytes);
+    }
+    await fsp.writeFile(paths.receipt, `${JSON.stringify(built.receipt, null, 2)}\n`);
+    return built;
+  } finally {
+    await fsp.rm(work, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The shared build-over-a-snapshot core (plan section 4 and 5): take one
+ * input snapshot outside the source tree, refuse drift between the
+ * caller's inspection and the copy, hash the filtered snapshot for the
+ * receipt, and run the pipeline stages there. The caller decides what the
+ * finished tree becomes: `runFullBuild` copies the artifacts back into the
+ * project's own out/ and removes the work tree; the dev session keeps the
+ * tree itself as one immutable generation. On any failure the work tree is
+ * removed and nothing else is touched.
+ *
+ * @param {Object} options
+ * @param {{folder: string, files: Object}} options.project the inspected source project
+ * @param {number} options.seconds resolved host show length
+ * @param {string} options.projectName the name the receipt records
+ * @param {{outDir: string, stageDir: string, sizePath: string}} [options.snapshotPaths]
+ * @param {Object} options.native the pngine adapter
+ * @param {Object} options.runtime `{ verify }` over the prepared bundle
+ * @param {Object} options.producers the build ports
+ * @param {Object} [options.io]
+ * @param {string} [options.workRoot] parent for the snapshot (the dev
+ *   session passes its own staging root)
+ * @returns {Promise<{built: Object, work: string, workProject: string}>}
+ *   `workProject` is the finished tree: the authored files plus out/ with
+ *   payload, score and receipt; `work` is the root to remove for it
+ */
+export async function runSnapshotBuild({
+  project,
+  seconds,
+  projectName,
+  snapshotPaths,
+  native,
+  runtime,
+  producers,
+  io = createNodeIo(),
+  workRoot,
+}) {
+  const { work, workProject } = await snapshotProject({ project, paths: snapshotPaths ?? {}, workRoot });
+  try {
+    const copied = await inspectProject({ folder: workProject, io });
+    await assertProjectSnapshotsMatch({ original: project, copied, what: 'build' });
+
+    const inputFiles = await listSnapshotInputFiles({ workProject, paths: snapshotPaths ?? {} });
+    const built = await buildProject({
+      project: copied,
+      seconds,
+      paths: {
+        folder: workProject,
+        outDir: join(workProject, GENERATED_DIR),
+        payload: join(workProject, GENERATED_DIR, BAKED_PAYLOAD),
+        score: join(workProject, GENERATED_DIR, PACKED_SCORE),
+        receipt: join(workProject, GENERATED_DIR, BUILD_RECEIPT),
+        workDir: work,
+        projectName,
+        payloadRelative: `${GENERATED_DIR}/${BAKED_PAYLOAD}`,
+        scoreRelative: `${GENERATED_DIR}/${PACKED_SCORE}`,
+        receiptRelative: `${GENERATED_DIR}/${BUILD_RECEIPT}`,
+      },
+      io,
+      native,
+      runtime,
+      hashBytes,
+      inputFiles,
+      producers,
+    });
+    return { built, work, workProject };
+  } catch (cause) {
+    await fsp.rm(work, { recursive: true, force: true });
+    throw cause;
+  }
+}