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

package/vendor/audits/prove-live.mjs

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+// prove-live.mjs — prove the DEPLOYED world IS the build you just published.
+//
+// A green local build says nothing about what players get. Neither does a 200 on the play
+// URL. This reads the world API, derives the live build number, and compares the entry
+// document the CDN is actually serving against the bytes in your local bundle.
+//
+//   helix world prove-live --url <playUrl> --world-api <worldUrl> --build <n> [--dist dist]
+//                       [--entry index.html] [--spot 5] [--timeout 15000]
+//                       [--perf qa/perf-gate.json] [--json]
+//
+// --url and --world-api are the values `helix publish` returned. Never construct either by
+// hand: a hand-built URL that happens to 200 proves nothing about your world.
+//
+// THIS SCRIPT FAILS WHEN IT CANNOT PROVE. An unreadable build number, an unreachable
+// bundle, a missing local bundle to compare against — every one of those is a non-zero
+// exit, not a warning. A readback that degrades to a WARN and exits 0 is the exact failure
+// this command exists to prevent: it looks like rigor and enforces nothing.
+//
+// It does NOT render the page. Rendering proof comes from `helix screenshot`, and
+// playability proof from driving the deployed URL in a browser. Three separate claims.
+
+import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, extname, relative, posix, sep } from 'node:path';
+
+const argv = process.argv.slice(2);
+const arg = (n, d) => { const i = argv.indexOf(`--${n}`); return i === -1 ? d : argv[i + 1]; };
+const has = (n) => argv.includes(`--${n}`);
+
+const URL_ = arg('url');
+const WORLD_API = arg('world-api');
+const EXPECT_BUILD = arg('build');
+const DIST = arg('dist', 'dist');
+const ENTRY = arg('entry', 'index.html');
+const SPOT = Number(arg('spot', '5'));
+const TIMEOUT_MS = Number(arg('timeout', '15000'));
+const PERF = arg('perf', 'qa/perf-gate.json');
+
+if (!URL_) {
+  console.error('prove-live: --url <playUrl> is required (the URL `helix publish` returned — never one you constructed by hand)');
+  process.exit(2);
+}
+
+const results = [];
+const fail = (id, m) => results.push({ level: 'FAIL', id, message: m });
+const warn = (id, m) => results.push({ level: 'WARN', id, message: m });
+const info = (id, m) => results.push({ level: 'INFO', id, message: m });
+
+// What was actually proven, as opposed to what was attempted. Nothing here defaults to true.
+const proof = { build: null, content: null };
+
+const sha = (buf) => createHash('sha256').update(buf).digest('hex');
+const short = (h) => h.slice(0, 16);
+
+async function req(url, init = {}) {
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { signal: ctl.signal, redirect: 'follow', ...init });
+    const buf = init.method === 'HEAD' ? Buffer.alloc(0) : Buffer.from(await res.arrayBuffer());
+    return {
+      ok: true,
+      status: res.status,
+      buf,
+      body: buf.toString('utf8'),
+      contentType: res.headers.get('content-type') ?? '',
+      contentLength: res.headers.get('content-length'),
+      contentEncoding: res.headers.get('content-encoding'),
+    };
+  } catch (err) {
+    return { ok: false, error: err.name === 'AbortError' ? `timed out after ${TIMEOUT_MS}ms` : err.message };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+// ── 1. the play URL is reachable and is a page ──────────────────────────────────────
+const play = await req(URL_);
+if (!play.ok) {
+  fail('play.unreachable', `${URL_}: ${play.error}`);
+} else {
+  info('play.status', `${URL_} → ${play.status} (${play.contentType.split(';')[0] || 'no content-type'})`);
+  if (play.status !== 200) fail('play.status', `expected 200, got ${play.status}`);
+  if (!/text\/html/.test(play.contentType)) fail('play.contenttype', `expected text/html, got "${play.contentType}"`);
+  if (play.body.length < 200) fail('play.empty', `response body is ${play.body.length} bytes — that is not a page`);
+  if (/not\s+found|world\s+unavailable|failed\s+to\s+load/i.test(play.body.slice(0, 4000))) {
+    warn('play.error-copy', 'the page body contains not-found / unavailable copy — open it and look before reporting success');
+  }
+}
+
+// ── 2. the world API — the readback, and it is not optional ─────────────────────────
+if (!WORLD_API) {
+  fail(
+    'api.missing',
+    '--world-api was not given, so nothing about build identity was read. Reachability is not proof: pass the api URL `helix publish` returned.',
+  );
+}
+
+let bundleUrl = null;
+
+if (WORLD_API) {
+  const api = await req(WORLD_API);
+  if (!api.ok) {
+    fail('api.unreachable', `${WORLD_API}: ${api.error}`);
+  } else if (api.status !== 200) {
+    fail('api.status', `${WORLD_API} → ${api.status}`);
+  } else {
+    let raw = null;
+    try { raw = JSON.parse(api.body); } catch { /* not json */ }
+    if (!raw) {
+      fail('api.unparseable', `${WORLD_API} did not return JSON — the readback is unproven`);
+    } else {
+      // The helix3 world API nests the document under `item`. Unwrap it, but keep working
+      // if a lane ever returns the document flat.
+      const doc = raw.item ?? raw.world ?? raw.data ?? raw;
+      bundleUrl = doc.bundleUrl ?? null;
+      info(
+        'api.shape',
+        `status=${doc.status ?? '?'} · hasActiveBuild=${doc.hasActiveBuild ?? '?'} · activeBuildId=${doc.activeBuildId ?? '?'}${raw.item ? ' (document nested under "item")' : ''}`,
+      );
+
+      if (doc.hasActiveBuild === false) fail('api.no-active-build', 'the world API reports hasActiveBuild=false — nothing is being served to players');
+      if (doc.status && doc.status !== 'published') warn('api.status-value', `world status is "${doc.status}", not "published"`);
+
+      if (!bundleUrl) {
+        fail('api.no-bundle-url', 'the world API returned no bundleUrl — the live build cannot be identified or fetched');
+      } else {
+        // Build number: the helix3 API carries it ONLY in the bundle path
+        // (…/instant-worlds/<worldId>/<build>/index.html). Explicit fields are checked too,
+        // in case a lane grows one — but a missing field is never a pass.
+        const fromPath = /\/(\d+)\/[^/]+$/.exec(bundleUrl)?.[1] ?? null;
+        const live = doc.buildNumber ?? doc.build?.number ?? doc.latestBuild?.buildNumber ?? fromPath;
+        info('api.build', `live build: ${live ?? 'UNREADABLE'}${fromPath && String(live) === fromPath ? ' (read from the bundleUrl path)' : ''} · ${bundleUrl}`);
+
+        if (live == null) {
+          fail('api.build-unreadable', `no build number in any known field and none in the bundleUrl path (${bundleUrl}) — build identity is unproven`);
+        } else if (EXPECT_BUILD == null) {
+          warn('api.build-not-compared', `--build was not given, so the live build (${live}) was read but not compared. The entry hash below is then the only identity proof.`);
+        } else if (String(live) !== String(EXPECT_BUILD)) {
+          proof.build = false;
+          fail('api.build-mismatch', `published build ${EXPECT_BUILD} but the live world reports ${live} — you proved a different build than the one you shipped`);
+        } else {
+          proof.build = true;
+          info('api.build-match', `live build ${live} === published build ${EXPECT_BUILD}`);
+        }
+      }
+    }
+  }
+}
+
+// ── 3. content identity — the deployed entry document vs the bundle you published ───
+const localEntry = join(DIST, ENTRY);
+let localBytes = null;
+if (!existsSync(localEntry)) {
+  fail('dist.missing', `no ${localEntry} to compare against — pass --dist pointing at the exact bundle you published. Without it, content identity cannot be proven.`);
+} else {
+  localBytes = readFileSync(localEntry);
+  info('entry.local', `${localEntry} → ${localBytes.length} bytes, sha256:${short(sha(localBytes))}`);
+}
+
+if (bundleUrl && localBytes) {
+  const deployed = await req(bundleUrl);
+  if (!deployed.ok) {
+    fail('entry.unreachable', `${bundleUrl}: ${deployed.error}`);
+  } else if (deployed.status !== 200) {
+    fail('entry.status', `${bundleUrl} → ${deployed.status}`);
+  } else {
+    const dh = sha(deployed.buf);
+    info('entry.deployed', `${bundleUrl} → ${deployed.status}, ${deployed.buf.length} bytes, sha256:${short(dh)}`);
+    if (dh !== sha(localBytes)) {
+      proof.content = false;
+      fail('entry.mismatch', 'the deployed entry document is NOT byte-identical to the bundle you published — the live world is some other build');
+    } else {
+      proof.content = true;
+      info('entry.match', `deployed entry is byte-identical to ${localEntry} (sha256:${short(dh)})`);
+    }
+
+    // Everything the entry references must be fetchable from the deployed bundle. This is
+    // where "the html landed but the JS 404s" gets caught.
+    const base = bundleUrl.replace(/[^/]+$/, '');
+    const refs = [...new Set([...deployed.body.matchAll(/(?:src|href)\s*=\s*"\.?\/?([^"]+)"/g)].map((m) => m[1]))]
+      .filter((r) => !/^(https?:|data:|#|\/\/)/.test(r));
+    let heaviest = [];
+    if (SPOT > 0 && existsSync(DIST)) {
+      const MEDIA = new Set(['.glb', '.gltf', '.bin', '.ktx2', '.png', '.jpg', '.jpeg', '.webp', '.mp3', '.ogg', '.wav']);
+      const walk = (dir, out = []) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+          const p = join(dir, e.name);
+          if (e.isDirectory()) walk(p, out);
+          else if (MEDIA.has(extname(p).toLowerCase())) out.push(p);
+        }
+        return out;
+      };
+      heaviest = walk(DIST)
+        .map((p) => ({ p, size: statSync(p).size }))
+        .sort((a, b) => b.size - a.size)
+        .slice(0, SPOT);
+    }
+
+    // Fetch independent CDN checks together, then report them in their original order so a
+    // slow missing asset does not multiply the timeout by every file.
+    const [entryHeads, mediaHeads] = await Promise.all([
+      Promise.all(refs.map((r) => req(base + r, { method: 'HEAD' }))),
+      Promise.all(
+        heaviest.map(({ p }) => {
+          const rel = relative(DIST, p).split(sep).join(posix.sep);
+          return req(base + rel, { method: 'HEAD', headers: { 'accept-encoding': 'identity' } });
+        }),
+      ),
+    ]);
+
+    let reachable = 0;
+    for (const [index, r] of refs.entries()) {
+      const head = entryHeads[index];
+      if (head.ok && head.status === 200) reachable += 1;
+      else fail('entry.asset-missing', `${r} → ${head.ok ? head.status : head.error}`);
+    }
+    info('entry.assets', `${reachable}/${refs.length} entry-referenced file(s) reachable on the CDN${refs.length ? `: ${refs.join(', ')}` : ''}`);
+
+    // Spot-check the heavy media too — derived from the bundle on disk, never from a list
+    // written by hand, so it cannot be shrunk by forgetting an asset.
+    if (heaviest.length) {
+      for (const [index, { p, size }] of heaviest.entries()) {
+        const rel = relative(DIST, p).split(sep).join(posix.sep);
+        const head = mediaHeads[index];
+        if (!head.ok || head.status !== 200) {
+          fail('media.missing', `${rel} is in your bundle but the CDN returns ${head.ok ? head.status : head.error}`);
+        } else if (head.contentLength == null) {
+          warn('media.no-length', `${rel} → 200, but the CDN sent no content-length — reachability proven, byte length not`);
+        } else if (Number(head.contentLength) === size) {
+          info('media.ok', `${rel} → 200, ${head.contentLength} bytes (matches local)`);
+        } else if (head.contentEncoding) {
+          warn('media.encoded', `${rel} → 200, ${head.contentLength} bytes but content-encoding: ${head.contentEncoding} — length is of the compressed body, so it was not compared`);
+        } else {
+          fail('media.size-mismatch', `${rel}: local ${size} bytes, CDN serves ${head.contentLength} bytes`);
+        }
+      }
+    }
+  }
+}
+
+// ── 3b. the world you published passed the frame-time gate ─────────────────────────
+// A world that is reachable, byte-identical and unplayable is still a failed release. The perf
+// artifact is bound to the bundle by the sha256 of its entry document, so this cannot be
+// satisfied with a green run from three builds ago — which is the only way a perf gate ever
+// gets routed around.
+if (!existsSync(PERF)) {
+  fail(
+    'perf.missing',
+    `${PERF} not found. A world does not ship without a passing frame-time gate: run helix world perf-gate against the built world with --json ${PERF} before publishing. There is no flag that turns this off.`,
+  );
+} else {
+  let perf = null;
+  try { perf = JSON.parse(readFileSync(PERF, 'utf8')); }
+  catch (err) { fail('perf.unparseable', `${PERF}: ${err.message}`); }
+  if (perf) {
+    const m = perf.metrics ?? {};
+    if (perf.failed > 0) {
+      fail('perf.failed', `${PERF} records ${perf.failed} blocking perf failure(s) — you are publishing a world you have measured and know is slow`);
+    }
+    let stale = false;
+    if (localBytes && perf.entrySha256 && perf.entrySha256 !== sha(localBytes)) {
+      stale = true;
+      fail(
+        'perf.stale',
+        `${PERF} measured a bundle whose entry document hashes ${short(perf.entrySha256)}, but you are publishing ${short(sha(localBytes))}. The frame times belong to a different build. Re-run the perf gate against this bundle.`,
+      );
+    } else if (localBytes && !perf.entrySha256) {
+      warn('perf.unbound', `${PERF} records no entrySha256, so it could not be tied to the bundle being published — re-run helix world perf-gate with --dist ${DIST}`);
+    }
+    // Only a green run on THIS bundle is a pass. Printing the numbers next to a stale-artifact
+    // failure is how "perf: pass" ends up in a release note for a build nobody measured.
+    if (perf.failed === 0 && !stale) {
+      info(
+        'perf.pass',
+        `${PERF}: p50 ${m.frame?.p50?.toFixed(2)} ms (${m.frame?.fps_p50?.toFixed(0)} fps) · p95 ${m.frame?.p95?.toFixed(2)} ms · ${m.lights?.punctual} punctual light(s) · ${m.drawingBufferPixels?.toLocaleString()} buffer px · measured on ${m.renderer ?? 'an unrecorded GPU'}`,
+      );
+    }
+    if (perf.unmeasured?.length) {
+      warn('perf.unmeasured', `${PERF} reports ${perf.unmeasured.length} perf gate(s) that measured NOTHING: ${perf.unmeasured.join(', ')} — carry that into the release note rather than letting a blank read as a pass`);
+    }
+  }
+}
+
+// ── 4. did anything actually get proven? ────────────────────────────────────────────
+if (proof.build !== true && proof.content !== true) {
+  fail(
+    'readback.unproven',
+    'neither the build number nor the entry-document hash was matched against what you published. Reachability was all that was measured, and reachability is not identity — do not report this world as proven.',
+  );
+} else {
+  info(
+    'readback.proven',
+    `identity proven by: ${[proof.build === true ? 'build number' : null, proof.content === true ? 'entry sha256' : null].filter(Boolean).join(' + ')}`,
+  );
+}
+
+const failures = results.filter((r) => r.level === 'FAIL');
+if (has('json')) {
+  console.log(JSON.stringify({ results, proof, failed: failures.length }, null, 2));
+} else {
+  for (const r of results) console.log(`${r.level.padEnd(4)} ${r.id.padEnd(24)} ${r.message}`);
+  console.log('');
+  console.log(failures.length ? `prove-live: ${failures.length} FAILURE(s)` : 'prove-live: pass');
+}
+process.exit(failures.length ? 1 : 0);