animader-cli 0.0.0-stage → 0.1.1

package/adapters/node-fs.mjs

@@ -0,0 +1,80 @@
+// Node filesystem adapter. Portable decisions receive these functions; this
+// file is the only place that touches node:fs for the project folder, the
+// prepared bundle and the generated output.
+
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import { removeTree as retryingRemoveTree } from '../lib/rmtree.mjs';
+
+export function hashBytes(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+export async function hashFile(path) {
+  return hashBytes(await readFile(path));
+}
+
+export async function statFile(path) {
+  try {
+    const info = await stat(path);
+    return { isFile: info.isFile(), isDirectory: info.isDirectory(), size: info.size };
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+    throw error;
+  }
+}
+
+export async function readFileBytes(path) {
+  return readFile(path);
+}
+
+export async function listDir(path) {
+  return (await readdir(path)).sort();
+}
+
+export async function ensureDir(path) {
+  await mkdir(path, { recursive: true });
+}
+
+export async function removeFile(path) {
+  await rm(path, { force: true });
+}
+
+/**
+ * The one recursive tree removal for work-tree disposal: `fsp.rm` under the
+ * shared transient-code retry (lib/rmtree.mjs). Every owner of a throwaway
+ * tree — the dev generation store, the full build's snapshot work tree, the
+ * export's work tree — disposes through this, never a bare rm.
+ */
+export async function removeTree(path) {
+  await retryingRemoveTree(path, { remove: (target) => rm(target, { recursive: true, force: true }) });
+}
+
+export async function writeFileAtomic(path, data) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  // The temporary file is owned by this write. Clean it up for a failed write
+  // as well as a failed rename; parent directories already created may remain.
+  try {
+    await writeFile(temporary, data);
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+export function createNodeIo() {
+  return {
+    hashBytes,
+    hashFile,
+    statFile,
+    readFile: readFileBytes,
+    listDir,
+    ensureDir,
+    removeFile,
+    writeFile: writeFileAtomic,
+  };
+}

package/adapters/pngine.mjs

@@ -0,0 +1,87 @@
+// Native pngine adapter. It runs the two checks this subslice owns, with an
+// argv array and no shell interpolation:
+//
+//   pngine validate <program>
+//   pngine render <program> -o <payload>
+//
+// It does not run pacer, compile a score, infer targets from diagnostics or
+// retry an unknown target. Those decisions belong to the browser's semantic
+// READY path in the next slice.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { DemoError } from '../lib/errors.mjs';
+import { hashFile, statFile } from './node-fs.mjs';
+
+const execFileAsync = promisify(execFile);
+const MAX_DIAGNOSTIC = 2000;
+
+function diagnostic(error) {
+  const text = String(error?.stderr ?? error?.message ?? error ?? '').trim();
+  if (text === '') return 'no diagnostic output';
+  return text.length > MAX_DIAGNOSTIC ? `…${text.slice(-MAX_DIAGNOSTIC)}` : text;
+}
+
+/**
+ * @param {Object} options
+ * @param {string} options.binary absolute pngine CLI path
+ * @param {Function} [options.exec] injected for tests; argv array, never a shell
+ * @param {number} [options.timeout]
+ */
+export function createPngineNative({ binary, exec = execFileAsync, timeout = 120000 }) {
+  if (typeof binary !== 'string' || binary === '') throw new TypeError('pngine binary path is required');
+  let identityPromise;
+
+  async function run(phase, args, { cwd }) {
+    try {
+      return await exec(binary, args, {
+        cwd,
+        timeout,
+        maxBuffer: 8 * 1024 * 1024,
+        windowsHide: true,
+      });
+    } catch (error) {
+      const missing = error?.code === 'ENOENT';
+      throw new DemoError(
+        'native_pngine_failed',
+        missing
+          ? `pngine is missing at ${binary}`
+          : `pngine ${phase} failed for ${args[1]} (exit ${error?.code ?? 'unknown'}): ${diagnostic(error)}`,
+        {
+          exitCode: 4,
+          remedy: missing
+            ? "Set PNGINE to the pngine CLI binary and build it if needed; the demo never installs it."
+            : `Run the same command by hand from the project folder with PNGINE=${binary}; no score target is inferred or retried.`,
+          cause: error,
+        },
+      );
+    }
+  }
+
+  return {
+    async identity() {
+      if (identityPromise === undefined) {
+        identityPromise = (async () => {
+          const info = await statFile(binary);
+          if (info === null || !info.isFile) {
+            throw new DemoError('missing_pngine', `pngine is missing at ${binary}`, {
+              exitCode: 4,
+              remedy: "Build pngine or set PNGINE to its CLI binary; ANIMADER_PNGINE names the checkout root.",
+            });
+          }
+          return { name: 'pngine', sha256: await hashFile(binary) };
+        })();
+      }
+      return identityPromise;
+    },
+
+    async validate({ cwd, program }) {
+      return run('validate', ['validate', program], { cwd });
+    },
+
+    async bake({ cwd, program, output }) {
+      return run('render', ['render', program, '-o', output], { cwd });
+    },
+  };
+}

package/adapters/snapshot.mjs

@@ -0,0 +1,143 @@
+// The input snapshot: one consistent copy of the authored project, taken
+// outside the source tree, that each build-shaped caller (the release
+// export, `animader build`, dev's preflight) owns for itself. The filter is
+// the one policy: generated `out/`, the caller's own output/staging trees
+// and detached reports when they sit inside the project, `.git`,
+// `node_modules` and legacy `.animader-export-work-*` debris never enter a
+// snapshot, and every excluded root is excluded as a whole subtree — no
+// file under it enters the copy or the receipt's rows either; `.gitignore`
+// is data for humans and git, never an asset allowlist.
+// `listSnapshotInputFiles` hashes the filtered snapshot into the receipt's
+// consumed-input rows — the conservative coverage the build receipt records
+// when the compiler answers no dependency metadata of its own.
+
+import { promises as fsp } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+
+import { GENERATED_DIR } from '../lib/contract.mjs';
+
+function hashBytes(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+/** Directories never copied into an input snapshot, at any depth. */
+export const SNAPSHOT_PRUNED_NAMES = Object.freeze(['.git', 'node_modules']);
+/** Leftovers of the pre-fix work-folder placement, never snapshot input. */
+export const LEGACY_WORK_PREFIX = '.animader-export-work-';
+
+/**
+ * Root-relative paths of the caller's own output, staging and size-report
+ * locations, but only those that sit inside the project folder. The
+ * project's own generated directory is always among them — the project
+ * root is known at copy time and `GENERATED_DIR` is a contract constant —
+ * whether or not the caller named any paths at all. These are owned
+ * generated trees and reports, not authored resources, so they never enter
+ * an input snapshot. The exclusion is this fixed list — the `.gitignore`
+ * file is data for humans and git, never an asset allowlist.
+ */
+function snapshotExclusions({ projectRoot, paths }) {
+  const insideProject = (path) => {
+    if (!path) return null;
+    const rel = relative(projectRoot, resolve(path));
+    if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return null;
+    return rel.split(sep).join('/');
+  };
+  const excluded = new Set([GENERATED_DIR]);
+  for (const path of [paths?.outDir, paths?.stageDir, paths?.sizePath]) {
+    const rel = insideProject(path);
+    if (rel !== null) excluded.add(rel);
+  }
+  return excluded;
+}
+
+export function snapshotFilter({ projectRoot, paths }) {
+  const excluded = snapshotExclusions({ projectRoot, paths });
+  return (source) => {
+    const rel = relative(projectRoot, source);
+    if (rel === '') return true;
+    const segments = rel.split(sep);
+    if (segments.some((name) => SNAPSHOT_PRUNED_NAMES.includes(name))) return false;
+    if (segments.some((name) => name.startsWith(LEGACY_WORK_PREFIX))) return false;
+    // Any excluded root-relative path is a subtree: a file or a deeper
+    // directory under it is excluded with it, in the copy filter and in the
+    // receipt's hashing walk alike — the same shape the watcher's filter
+    // keeps. An exact-path match alone would let a row under `out/` through
+    // whenever the walk meets a tree that still carries one.
+    for (let depth = 1; depth <= segments.length; depth += 1) {
+      if (excluded.has(segments.slice(0, depth).join('/'))) return false;
+    }
+    return true;
+  };
+}
+
+/**
+ * The input snapshot: a fresh copy of the authored project OUTSIDE
+ * the source tree, so an in-project output (`animader export --out dist`
+ * from the project root) never asks Node to copy a directory into its own
+ * subtree (ERR_FS_CP_EINVAL). The copy keeps every authored file at its
+ * relative path and excludes only the generated and caller-owned trees and
+ * reports plus VCS/dependency directories — each as a whole subtree: the
+ * project's own generated `out/` (a contract constant, named by the caller
+ * or not), the output, its `<out>.next` staging directory and detached
+ * `<out>.size.json` when they sit inside the project, `.git`,
+ * `node_modules`, and legacy `.animader-export-work-*` debris. `.gitignore`
+ * is not consulted.
+ *
+ * @param {Object} options
+ * @param {{folder: string}} options.project the inspected source project
+ * @param {{outDir: string, stageDir: string, sizePath: string}} options.paths
+ * @param {string} [options.workRoot] parent for the work folder; the
+ *   default is the OS temporary directory, always outside the source tree
+ * @returns {Promise<{work: string, workProject: string}>} `work` is owned by
+ *   the caller of this invocation and must be removed by it
+ */
+export async function snapshotProject({ project, paths, workRoot }) {
+  const root = workRoot ?? tmpdir();
+  await fsp.mkdir(root, { recursive: true });
+  const work = await fsp.mkdtemp(join(root, 'animader-export-work-'));
+  const workProject = join(work, 'project');
+  await fsp.cp(project.folder, workProject, {
+    recursive: true,
+    filter: snapshotFilter({ projectRoot: project.folder, paths }),
+  });
+  return { work, workProject };
+}
+
+/**
+ * The receipt's consumed-input rows: every authored file of the filtered
+ * snapshot, hashed, sorted by path. This is the conservative method the
+ * score-build receipt records (`inputs.method: input-snapshot`); no second
+ * SJON reader is written to guess includes, so shader files and other
+ * consumed resources are covered by hashing the whole filtered copy.
+ *
+ * @param {{workProject: string, paths?: {outDir: string, stageDir: string, sizePath: string}}} options
+ * @returns {Promise<Array<{path: string, bytes: number, sha256: string}>>}
+ */
+export async function listSnapshotInputFiles({ workProject, paths = {} }) {
+  const include = snapshotFilter({ projectRoot: workProject, paths });
+  const rows = [];
+
+  async function walk(folder) {
+    for (const entry of (await fsp.readdir(folder, { withFileTypes: true })).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      const path = join(folder, entry.name);
+      if (entry.isDirectory()) {
+        await walk(path);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (!include(path)) continue;
+      const bytes = await fsp.readFile(path);
+      rows.push({
+        path: path.slice(workProject.length + 1).split('\\').join('/'),
+        bytes: bytes.byteLength,
+        sha256: hashBytes(bytes),
+      });
+    }
+  }
+
+  await walk(workProject);
+  rows.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return rows;
+}

package/adapters/target.mjs

@@ -0,0 +1,104 @@
+// Target-path adapter for fresh-project creation: resolve every component
+// and symlink of the target folder, and refuse a target inside a tracked
+// starter source. This is the Node filesystem half of the guarantee; the
+// emptiness check and the write order stay in lib/new.mjs. The demo entry
+// point and the animader CLI share these helpers so both enforce the same
+// refusals.
+
+import { lstat, readlink, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { DemoError, EXIT_CODES } from '../lib/errors.mjs';
+import { STARTERS } from '../lib/new.mjs';
+
+const MAX_LINKS = 64;
+
+// Resolve every existing component and every symlink, including a dangling
+// link whose target does not exist yet. Missing components are resolved
+// lexically from their nearest resolved ancestor, so a target that does not
+// exist cannot hide a symlink alias into the pinned starter source.
+async function canonicalPath(path) {
+  const absolute = isAbsolute(path) ? path : `${process.cwd()}/${path}`;
+  const pending = absolute.split('/');
+  const resolved = [];
+  let links = 0;
+
+  for (let index = 0; index < pending.length; index++) {
+    const segment = pending[index];
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') {
+      resolved.pop();
+      continue;
+    }
+
+    const candidate = `/${[...resolved, segment].join('/')}`;
+    let info;
+    try {
+      info = await lstat(candidate);
+    } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') {
+        resolved.push(segment);
+        continue;
+      }
+      throw error;
+    }
+
+    if (info.isSymbolicLink()) {
+      links++;
+      if (links > MAX_LINKS) {
+        throw Object.assign(new Error(`too many symbolic links while resolving ${path}`), { code: 'ELOOP' });
+      }
+      const target = await readlink(candidate);
+      if (isAbsolute(target)) resolved.length = 0;
+      pending.splice(index + 1, 0, ...target.split('/'));
+      continue;
+    }
+    resolved.push(segment);
+  }
+
+  return `/${resolved.join('/')}`;
+}
+
+function inside(parent, candidate) {
+  const rel = relative(parent, candidate);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+export async function refuseStarterSource(folder, starter) {
+  let sourceRoot;
+  try {
+    sourceRoot = await realpath(fileURLToPath(STARTERS[starter].sourceRoot));
+  } catch (error) {
+    throw new DemoError('starter_source_unreadable', `could not resolve the ${starter} starter source: ${error?.message ?? String(error)}`, {
+      exitCode: EXIT_CODES.project,
+      remedy: 'Restore the tracked starter source; no files were written.',
+      cause: error,
+    });
+  }
+  if (inside(sourceRoot, folder)) {
+    throw new DemoError('target_inside_starter', `${folder} is inside the tracked ${starter} starter source (${sourceRoot})`, {
+      exitCode: EXIT_CODES.project,
+      remedy: `Choose a folder outside ${sourceRoot}; no files were written.`,
+    });
+  }
+}
+
+/**
+ * Resolve the requested target folder through every symlink, mapping a
+ * resolution failure to the shared named project error.
+ *
+ * @param {string} folder
+ * @returns {Promise<string>}
+ */
+export async function resolveTargetFolder(folder) {
+  try {
+    return await canonicalPath(folder);
+  } catch (error) {
+    throw new DemoError('target_inspection_failed', `could not resolve ${folder}: ${error?.message ?? String(error)}`, {
+      exitCode: EXIT_CODES.project,
+      remedy: 'Check the folder path and its permissions; no files were written.',
+      cause: error,
+    });
+  }
+}