@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/vendor/audits/world-audit.mjs

@@ -0,0 +1,439 @@
+#!/usr/bin/env node
+// world-audit.mjs — the blocking composition / budget / loader / provenance gate for a built
+// HELIX world.
+//
+// Reads artifacts, never prose: a world snapshot written by `helix world inspect --out`,
+// the built bundle on disk, and public/helix.assets.json. Exits non-zero on any FAIL so a
+// caller cannot mark QA done by describing it.
+//
+// Everything here is measured on the bundle a player downloads — the extension allowlist and
+// caps mirror the platform's own bundle-rules, the loader check parses the shipped models, and
+// the provenance table is verified in BOTH directions (declared→shipped and shipped→declared).
+//
+//   helix world audit --snapshot qa/snapshot.json --dist dist \
+//                        [--root world] [--assets public/helix.assets.json] [--json]
+//
+// Produce the snapshot with the CLI (the tool writes the file — strongest evidence):
+//   helix world inspect ./dist --out qa/snapshot.json
+
+import { readFileSync, existsSync, statSync, readdirSync, openSync, readSync, closeSync } from 'node:fs';
+import { join, extname, basename, relative, sep, posix } from 'node:path';
+
+const argv = process.argv.slice(2);
+const arg = (name, dflt) => {
+  const i = argv.indexOf(`--${name}`);
+  return i === -1 ? dflt : argv[i + 1];
+};
+const has = (name) => argv.includes(`--${name}`);
+
+const SNAPSHOT = arg('snapshot', 'qa/snapshot.json');
+const DIST = arg('dist', 'dist');
+const ROOT = arg('root', 'world');
+const ASSETS = arg('assets', 'public/helix.assets.json');
+
+// three.js built-in geometry constructors. A GLB loaded through GLTFLoader arrives as
+// BufferGeometry, so `geometry.type` cleanly separates authored primitives from real assets.
+const PRIMITIVE =
+  /^(Box|Plane|Sphere|Cylinder|Cone|Torus|TorusKnot|Capsule|Circle|Ring|Tetrahedron|Octahedron|Dodecahedron|Icosahedron|Polyhedron|Lathe|Extrude|Shape|Tube|Edges|Wireframe)Geometry$/;
+
+// Bundle rules the platform enforces at validate AND publish. These MIRROR
+// @hypersoniclabs/helix-manifest `bundle-rules.ts` — if they drift, this script starts either
+// failing files the platform accepts or passing files publish will reject.
+const MAX_FILES = 200;
+const MAX_FILE_BYTES = 25 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 50 * 1024 * 1024;
+const BUNDLE_PATH_PATTERN = /^(?!.*\.\.)(?!\/)[A-Za-z0-9._/-]{1,200}$/;
+const ALLOWED_EXT = new Set(
+  ('html js mjs css json map wasm png jpg jpeg gif webp svg ico ktx2 glb gltf bin mp3 ogg wav woff woff2 ttf txt md')
+    .split(' ')
+    .map((e) => `.${e}`),
+);
+// `.d.ts` is allowed by SUFFIX (system packages ship consumer types under helix_modules/), while
+// raw `.ts` source stays disallowed. Matching the platform here is not pedantry: an extname()
+// check reads `index.d.ts` as `.ts` and fails a file publish accepts.
+const isAllowedBundleFile = (relPath) =>
+  relPath.toLowerCase().endsWith('.d.ts') || ALLOWED_EXT.has(extname(relPath).toLowerCase());
+
+// Media extensions — the platform's ASSET_EXTENSIONS. These are the files that must stream from
+// the CDN when they belong to a platform package, and the files a provenance row must account for.
+const ASSET_EXT = new Set(['.glb', '.gltf', '.bin', '.ktx2', '.png', '.jpg', '.jpeg', '.webp', '.gif', '.mp3', '.ogg', '.wav']);
+
+// The provenance vocabulary helix-assets defines. Recorded in public/helix.assets.json `assets[]`.
+const PROVENANCE = new Set(['vault', 'generated', 'curated', 'procedural', 'declared, not shipped']);
+
+const results = [];
+const record = (level, id, message) => results.push({ level, id, message });
+const fail = (id, m) => record('FAIL', id, m);
+const warn = (id, m) => record('WARN', id, m);
+const info = (id, m) => record('INFO', id, m);
+
+const pct = (n, d) => (d === 0 ? 0 : Math.round((n / d) * 1000) / 10);
+
+// ── snapshot ────────────────────────────────────────────────────────────────────────
+function loadSnapshot() {
+  if (!existsSync(SNAPSHOT)) {
+    fail('snapshot.missing', `no snapshot at ${SNAPSHOT} — run \`world inspect ./${DIST} --out ${SNAPSHOT}\` first`);
+    return null;
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(SNAPSHOT, 'utf8'));
+  } catch (err) {
+    fail('snapshot.unparseable', `${SNAPSHOT}: ${err.message}`);
+    return null;
+  }
+  const snap = raw.snapshot ?? raw;
+  if (!Array.isArray(snap?.objects)) {
+    fail('snapshot.shape', `${SNAPSHOT} has no objects[] — is it a world snapshot?`);
+    return null;
+  }
+  if (snap.truncated) {
+    warn('snapshot.truncated', `roster capped at ${snap.truncated.emitted} of ${snap.truncated.total} objects — shares below are of the emitted subset`);
+  }
+  return snap;
+}
+
+function auditComposition(snap) {
+  const all = snap.objects.filter((o) => o.visible);
+  const scoped = all.filter((o) => o.path === ROOT || o.path.startsWith(`${ROOT}/`));
+  let objects = scoped;
+  let scopeNote = `under "${ROOT}/"`;
+
+  if (scoped.length === 0) {
+    // No world root. Fall back to everything, and say plainly that the streamed character
+    // body is now inside the denominator — a weaker measurement, honestly labelled.
+    objects = all;
+    scopeNote = 'whole scene (no world root found)';
+    warn(
+      'composition.noroot',
+      `no object under "${ROOT}/" — auditing the whole scene, so the streamed character body counts as a loaded model. ` +
+        `Put authored geometry under a Group named "${ROOT}" for an exact measurement.`,
+    );
+  }
+
+  if (objects.length === 0) {
+    fail('composition.empty', 'no visible meshes in the snapshot — the world renders nothing');
+    return;
+  }
+
+  const prims = objects.filter((o) => PRIMITIVE.test(o.geometry ?? ''));
+  const loaded = objects.filter((o) => (o.geometry ?? '') === 'BufferGeometry');
+  const share = pct(prims.length, objects.length);
+  const tris = objects.reduce((s, o) => s + (o.triangles ?? 0), 0);
+
+  info(
+    'composition.census',
+    `${objects.length} visible meshes ${scopeNote} · ${prims.length} primitive (${share}%) · ${loaded.length} loaded · ${tris.toLocaleString()} triangles`,
+  );
+
+  // The scaffold signature: what `scaffold_world` leaves behind, untouched.
+  if (objects.length <= 2 && loaded.length === 0) {
+    fail('composition.scaffold', `this is the scaffold — ${objects.length} primitive mesh(es), no loaded models. A box-and-plane world is a starting point, never shippable.`);
+  } else if (loaded.length === 0) {
+    fail('composition.no-loaded-models', 'zero loaded models — every visible mesh is a built-in primitive. Source or generate real assets (helix-assets).');
+  }
+  if (share > 60) {
+    fail('composition.primitive-dominant', `${share}% of visible meshes are built-in primitives (gate: 60%). Primitives are for collision proxies and blockout, not for a look.`);
+  } else if (share > 40) {
+    warn('composition.primitive-heavy', `${share}% primitive — under the 60% gate but visibly blockout-ish. Check the closing screenshot.`);
+  }
+
+  // Default-white check, applied ONLY to authored primitives: a GLB's baseColorFactor is
+  // legitimately [1,1,1] under a texture, so including loaded meshes would be a false positive.
+  const whitePrims = prims.filter((o) => (o.color ?? '').toLowerCase() === '#ffffff');
+  if (prims.length >= 4) {
+    const wshare = pct(whitePrims.length, prims.length);
+    info('materials.white-primitives', `${whitePrims.length}/${prims.length} primitive meshes use default white (${wshare}%)`);
+    if (wshare >= 60) {
+      fail('materials.default-dominant', `${wshare}% of authored primitives are default white MeshStandardMaterial (gate: 60%). Give surfaces real roughness/metalness/map.`);
+    }
+  }
+
+  const broken = objects.filter((o) => o.nonFinite);
+  if (broken.length) {
+    fail('geometry.nonfinite', `${broken.length} object(s) have NaN/Infinity transforms: ${broken.slice(0, 3).map((o) => o.path).join(', ')}`);
+  }
+  const zeroScale = objects.filter((o) => o.scale && [o.scale.x, o.scale.y, o.scale.z].some((v) => v === 0));
+  if (zeroScale.length) warn('geometry.degenerate', `${zeroScale.length} object(s) have a zero scale axis`);
+  if (tris > 400000) warn('budget.triangles', `${tris.toLocaleString()} triangles in scene — profile before shipping (mobile is the constraint)`);
+}
+
+// ── bundle ──────────────────────────────────────────────────────────────────────────
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) walk(p, out);
+    else out.push(p);
+  }
+  return out;
+}
+
+// Bundle-relative, forward-slashed — the form the platform validates and the CDN serves.
+const bundlePath = (f) => relative(DIST, f).split(sep).join(posix.sep);
+
+function auditBundle() {
+  if (!existsSync(DIST)) {
+    fail('bundle.missing', `no bundle at ${DIST} — run \`npm run build\` first`);
+    return [];
+  }
+  const files = walk(DIST);
+  const sizes = new Map(files.map((file) => [file, statSync(file).size]));
+  const total = files.reduce((sum, file) => sum + sizes.get(file), 0);
+  info('bundle.census', `${files.length} files · ${(total / 1024 / 1024).toFixed(2)} MB`);
+
+  if (files.length > MAX_FILES) fail('bundle.filecount', `${files.length} files (cap ${MAX_FILES})`);
+  if (total > MAX_TOTAL_BYTES) fail('bundle.total', `${(total / 1024 / 1024).toFixed(1)} MB total (cap 50 MB)`);
+  for (const f of files) {
+    const rel = bundlePath(f);
+    const size = sizes.get(f);
+    if (size > MAX_FILE_BYTES) fail('bundle.filesize', `${rel} is ${(size / 1024 / 1024).toFixed(1)} MB (cap 25 MB)`);
+    if (size === 0) fail('bundle.empty', `${rel} is empty`);
+    if (!BUNDLE_PATH_PATTERN.test(rel)) fail('bundle.path', `${rel} is not a legal bundle path (A-Z a-z 0-9 . _ / - only, no "..", no leading slash)`);
+    if (!isAllowedBundleFile(rel)) {
+      const ext = extname(rel).toLowerCase();
+      const hdri = ext === '.hdr' || ext === '.exr';
+      fail(
+        'bundle.ext',
+        hdri
+          ? `${rel} — .hdr/.exr are NOT in the platform extension allowlist. An HDRI cannot ship as-is: tone-map it to an equirect JPEG/PNG first (e.g. ffmpeg -i sky.hdr -vf "tonemap=hable,scale=2048:1024" sky.jpg) and PMREM that.`
+          : `${rel} has a disallowed extension (${ext || 'none'})`,
+      );
+    }
+  }
+
+  // Platform assets must stream from the CDN; only installed CODE lives in helix_modules. The
+  // platform's check covers EVERY asset extension, not just glb/ktx2 — a texture under
+  // helix_modules is the same licensing leak and the same publish rejection.
+  const bundledPlatformAssets = files.filter(
+    (f) => bundlePath(f).startsWith('helix_modules/') && ASSET_EXT.has(extname(f).toLowerCase()),
+  );
+  if (bundledPlatformAssets.length) {
+    fail(
+      'bundle.platform-assets',
+      `${bundledPlatformAssets.length} platform asset(s) bundled under helix_modules (${bundledPlatformAssets.slice(0, 2).map(bundlePath).join(', ')}). Publish rejects these — they stream from the CDN.`,
+    );
+  }
+  return files;
+}
+
+// ── loaders: the runtime has GLTFLoader + KTX2Loader and nothing else ───────────────
+// A Draco- or meshopt-compressed model does not degrade, it fails to load. This is checked on
+// the BUNDLE rather than left to a snippet the agent may or may not run, and it reads both
+// container forms: .glb (binary header) and .gltf (plain JSON, which is what Poly Haven ships).
+function gltfJson(file) {
+  if (extname(file).toLowerCase() === '.gltf') return JSON.parse(readFileSync(file, 'utf8'));
+  const fd = openSync(file, 'r');
+  try {
+    const head = Buffer.alloc(20);
+    readSync(fd, head, 0, 20, 0);
+    if (head.toString('utf8', 0, 4) !== 'glTF') throw new Error('not a glTF binary container');
+    const jsonLen = head.readUInt32LE(12);
+    const body = Buffer.alloc(jsonLen);
+    readSync(fd, body, 0, jsonLen, 20);
+    return JSON.parse(body.toString('utf8'));
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function auditLoaders(files) {
+  const models = files.filter((f) => ['.glb', '.gltf'].includes(extname(f).toLowerCase()));
+  if (models.length === 0) return;
+  let bad = 0;
+  for (const f of models) {
+    let doc;
+    try { doc = gltfJson(f); }
+    catch (err) { fail('loader.unreadable', `${bundlePath(f)}: ${err.message}`); continue; }
+    const required = doc.extensionsRequired ?? [];
+    const blocking = required.filter((x) => /draco|meshopt/i.test(x));
+    if (blocking.length) {
+      bad += 1;
+      fail(
+        'loader.unsupported-extension',
+        `${bundlePath(f)} requires ${blocking.join(', ')} — the runtime has GLTFLoader + KTX2Loader only, so this model is ABSENT at runtime, not degraded. Re-export without compression (gltf-transform: --compress false --instance false).`,
+      );
+    }
+  }
+  info('loader.census', `${models.length} glb/gltf in the bundle, ${bad} require an unsupported extension`);
+}
+
+// ── provenance: the whole table, not just the Vault rows ───────────────────────────
+// helix.assets.json carries TWO arrays and they answer different questions:
+//   vaultAssets[] — the locked machine contract the Vault session consumes at publish. Shape
+//                   unchanged; do not add fields to it.
+//   assets[]      — the provenance table for EVERY shipped asset, whatever its source. Without
+//                   it four of the five provenance values are unrecordable, and a world that is
+//                   entirely curated + generated + procedural honestly reports "no assets".
+function auditAssets(files) {
+  // Every media file a player downloads, minus the platform's own streamed code channel.
+  const media = files
+    .map(bundlePath)
+    .filter((p) => ASSET_EXT.has(extname(p).toLowerCase()) && !p.startsWith('helix_modules/'));
+
+  if (!existsSync(ASSETS)) {
+    if (media.length) {
+      fail(
+        'assets.unrecorded',
+        `${ASSETS} is absent but the bundle ships ${media.length} media file(s) (${media.slice(0, 3).join(', ')}…). Provenance for every one of them is unrecorded, so "where did this asset come from" has no answer a script can check.`,
+      );
+    } else {
+      info('assets.absent', `${ASSETS} not present, and the bundle ships no media — nothing to record`);
+    }
+    return;
+  }
+  let doc;
+  try {
+    doc = JSON.parse(readFileSync(ASSETS, 'utf8'));
+  } catch (err) {
+    fail('assets.unparseable', `${ASSETS}: ${err.message} — the provenance table cannot be read, so nothing about asset origin is proven`);
+    return;
+  }
+
+  // ── vaultAssets[]: the locked contract, verified exactly as before ────────────────
+  const vaultRows = Array.isArray(doc?.vaultAssets) ? doc.vaultAssets : [];
+  if (!Array.isArray(doc?.vaultAssets)) warn('assets.no-vault-key', `${ASSETS} has no vaultAssets[] — install_assets writes it; a hand-written file must still carry the key (an empty array is the correct value for "no Vault assets")`);
+  const shippedNames = new Set(files.map((f) => basename(f)));
+  const missingVault = vaultRows.filter((r) => r.artifactKey && !shippedNames.has(basename(r.artifactKey)));
+  info('assets.vault-census', `${vaultRows.length} Vault asset(s) declared, ${vaultRows.length - missingVault.length} present in ${DIST}`);
+  for (const r of missingVault) {
+    fail('assets.declared-not-shipped', `${r.assetId ?? '(no id)'} → ${r.artifactKey} is declared but absent from ${DIST}`);
+  }
+
+  // ── assets[]: the provenance table ───────────────────────────────────────────────
+  if (doc.assets !== undefined && !Array.isArray(doc.assets)) {
+    fail('assets.shape', `${ASSETS} "assets" must be an array of provenance rows`);
+    return;
+  }
+  const rows = Array.isArray(doc.assets) ? doc.assets : [];
+  if (rows.length === 0) {
+    if (media.length) {
+      fail(
+        'assets.table-empty',
+        `${ASSETS} records no assets[] rows but the bundle ships ${media.length} media file(s). vaultAssets[] alone cannot express curated / generated / procedural, so an honest world with no Vault assets currently reports "no assets" — record the table.`,
+      );
+    } else {
+      info('assets.table-empty', 'no assets[] rows and no shipped media — consistent');
+    }
+    return;
+  }
+
+  const dirs = new Set(files.map((f) => bundlePath(f)));
+  // A row's path covers: itself · everything under it when it names a directory · everything
+  // matching it when it contains `*`. A PBR texture set is one source and three files
+  // (`assets/materials/asphalt_*.jpg`), and both dogfooded worlds reached for exactly that.
+  const covers = (rowPath, filePath) => {
+    if (rowPath.includes('*')) {
+      const re = new RegExp(`^${rowPath.replace(/[.+^${}()|[\]\\?]/g, '\\$&').replace(/\*/g, '[^/]*')}$`);
+      return re.test(filePath);
+    }
+    return filePath === rowPath || filePath.startsWith(rowPath.endsWith('/') ? rowPath : `${rowPath}/`);
+  };
+
+  const counts = {};
+  const covered = new Set();
+  rows.forEach((r, i) => {
+    const where = `assets[${i}]${r.path ? ` (${r.path})` : ''}`;
+    if (!PROVENANCE.has(r.provenance)) {
+      fail('assets.bad-provenance', `${where} has provenance "${r.provenance ?? '(missing)'}" — must be one of: ${[...PROVENANCE].join(' · ')}`);
+      return;
+    }
+    counts[r.provenance] = (counts[r.provenance] ?? 0) + 1;
+
+    if (r.provenance === 'declared, not shipped') {
+      fail('assets.declared-not-shipped', `${where} is recorded as "declared, not shipped" — the world's code points at an asset that is not in the bundle. Ship it or remove the reference.`);
+      return;
+    }
+    // `procedural` means "authored by code or algorithm, no third-party source to attribute".
+    // That covers both the runtime-only case (no file ships — no path) and the baked case (a
+    // synthesised noise bed, a generated texture, written out to a file that does ship).
+    if (r.provenance === 'procedural') {
+      if (!r.path) return;
+      const hits = [...dirs].filter((f) => covers(r.path, f));
+      if (hits.length === 0) {
+        warn('assets.procedural-path-missing', `${where} is procedural and names "${r.path}", but nothing at that path is in ${DIST}. Omit the path for a runtime-only asset that ships no file.`);
+        return;
+      }
+      for (const h of hits) covered.add(h);
+      return;
+    }
+
+    if (!r.path) {
+      fail('assets.no-path', `${where} has provenance "${r.provenance}" but no path — every non-procedural row names the file or directory it ships as`);
+      return;
+    }
+    const hits = [...dirs].filter((f) => covers(r.path, f));
+    if (hits.length === 0) {
+      fail('assets.declared-not-shipped', `${where} declares "${r.path}" with provenance "${r.provenance}" but nothing at that path is in ${DIST}`);
+      return;
+    }
+    for (const h of hits) covered.add(h);
+
+    // Attribution is the point of the table. A curated row without a licence is a legal gap,
+    // not a formatting nit; a generated row without a source cannot be traced back to its job.
+    if (r.provenance === 'curated' && !r.licence && !r.license) {
+      fail('assets.no-licence', `${where} is curated but records no licence — the whole reason to name a curated source is that its licence is checkable`);
+    }
+    if (r.provenance === 'curated' && !r.source) {
+      fail('assets.no-source', `${where} is curated but names no source — "from the internet" is not provenance`);
+    }
+    if (r.provenance === 'generated' && !r.source) {
+      warn('assets.no-generation-source', `${where} is generated but records no source (the generation job/tool) — it cannot be traced`);
+    }
+    if (r.provenance === 'vault' && !r.assetId) {
+      warn('assets.no-asset-id', `${where} is a Vault asset with no assetId — it cannot be matched to vaultAssets[]`);
+    }
+  });
+
+  info(
+    'assets.census',
+    `${rows.length} provenance row(s): ${Object.entries(counts).map(([k, n]) => `${k}×${n}`).join(' · ') || 'none valid'}`,
+  );
+
+  // The reverse direction, which is the half that catches an asset nobody wrote down.
+  const unrecorded = media.filter((p) => !covered.has(p));
+  if (unrecorded.length) {
+    fail(
+      'assets.unrecorded',
+      `${unrecorded.length} shipped media file(s) are covered by no provenance row: ${unrecorded.slice(0, 5).join(', ')}${unrecorded.length > 5 ? ` … +${unrecorded.length - 5} more` : ''}. A row's path may name a directory to cover everything under it.`,
+    );
+  } else {
+    info('assets.coverage', `${media.length}/${media.length} shipped media file(s) covered by a provenance row`);
+  }
+}
+
+// ── the snapshot must describe THIS bundle ──────────────────────────────────────────
+// Every composition number is read from the snapshot while every budget number is read from
+// dist/. If the snapshot predates the bundle it describes a world that no longer exists, and
+// the whole composition half of this gate silently measures the wrong build.
+function auditSnapshotFreshness(files) {
+  if (!existsSync(SNAPSHOT) || files.length === 0) return;
+  const snapTime = statSync(SNAPSHOT).mtimeMs;
+  const newest = files.reduce((acc, f) => Math.max(acc, statSync(f).mtimeMs), 0);
+  const newestFile = files.find((f) => statSync(f).mtimeMs === newest);
+  if (snapTime < newest) {
+    fail(
+      'snapshot.stale',
+      `${SNAPSHOT} was written ${Math.round((newest - snapTime) / 1000)}s BEFORE the newest bundle file (${bundlePath(newestFile)}). Every composition number below describes a different build — re-run \`world inspect ./${DIST} --out ${SNAPSHOT}\` against the bundle you are auditing.`,
+    );
+  } else {
+    info('snapshot.fresh', `${SNAPSHOT} is newer than every file in ${DIST} — the composition numbers describe this bundle`);
+  }
+}
+
+// ── run ─────────────────────────────────────────────────────────────────────────────
+const snap = loadSnapshot();
+if (snap) auditComposition(snap);
+const files = auditBundle();
+auditSnapshotFreshness(files);
+auditLoaders(files);
+auditAssets(files);
+
+const failures = results.filter((r) => r.level === 'FAIL');
+if (has('json')) {
+  console.log(JSON.stringify({ results, failed: failures.length }, null, 2));
+} else {
+  for (const r of results) console.log(`${r.level.padEnd(4)} ${r.id.padEnd(34)} ${r.message}`);
+  console.log('');
+  console.log(failures.length ? `world-audit: ${failures.length} BLOCKING failure(s)` : 'world-audit: pass');
+}
+process.exit(failures.length ? 1 : 0);

package/vendor/installed-index.mjs

@@ -1,4 +1,4 @@
-// @helix/humanoid-character@0.2.2 — installed.json (install-index) validator.
+// @helix/humanoid-character@0.3.0 — installed.json (install-index) validator.
 // Consumer/loader contract: VERSIONED and NON-frozen (NOT ability-v1). Generated by emit-schemas; regenerate freely.
 
 // src/bundle/installedIndex.ts