@genex-ai/cli-demo 1.5.2-dev.398 → 1.6.0-dev.403

package/templates/asset-viewer/tools/stamp-manifest.mjs

@@ -0,0 +1,134 @@
+// Phase 2 of the manifest: rewrite dist/genex-asset.json in place with the
+// measured geometry, the measured space and the gate block, so what ships is
+// what was actually measured rather than what the author claimed.
+//
+// Refuses to stamp a stale report (one taken against different source), and
+// re-validates the finished bytes - a build whose manifest cannot offer the two
+// dashboard buttons must not reach a deploy.
+//
+//   exit 0  stamped
+//   exit 1  refused (stale, failing, or invalid)
+//
+// Copied verbatim into every asset project and hashed by gate G13.
+//
+// Usage: node tools/stamp-manifest.mjs [--dist dist] [--report .gates/report.json]
+//                                      [--play-url <url>] [--allow-failed]
+
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  MANIFEST_FILENAME,
+  MANIFEST_MAX_BYTES,
+  defaultPlayUrl,
+  readAssetConfig,
+  validateManifest,
+} from "./emit-manifest.mjs";
+
+const PROJECT_DIR = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+
+function parseArgs(argv) {
+  const args = { dist: "dist", report: path.join(".gates", "report.json"), playUrl: null, allowFailed: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--dist") args.dist = argv[++i];
+    else if (a === "--report") args.report = argv[++i];
+    else if (a === "--play-url") args.playUrl = argv[++i];
+    else if (a === "--allow-failed") args.allowFailed = true;
+    else if (a === "--help" || a === "-h") args.help = true;
+    else throw new Error(`unknown flag: ${a}`);
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log("usage: node tools/stamp-manifest.mjs [--dist dist] [--report .gates/report.json] [--play-url <url>] [--allow-failed]");
+    return 0;
+  }
+
+  const distDir = path.resolve(PROJECT_DIR, args.dist);
+  const manifestPath = path.join(distDir, MANIFEST_FILENAME);
+  const reportPath = path.resolve(PROJECT_DIR, args.report);
+
+  if (!fs.existsSync(manifestPath)) throw new Error(`no ${MANIFEST_FILENAME} in ${args.dist} - run \`npm run build\` first`);
+  if (!fs.existsSync(reportPath)) throw new Error(`no gate report at ${args.report} - run \`npm run gates\` first`);
+
+  const config = readAssetConfig(PROJECT_DIR);
+  const manifest = JSON.parse(await fsp.readFile(manifestPath, "utf8"));
+  const report = JSON.parse(await fsp.readFile(reportPath, "utf8"));
+
+  // A report taken against different source text describes a different asset.
+  if (report.sourceSha256 !== manifest.source.sha256) {
+    throw new Error(
+      `gate report is stale: it was run against source ${String(report.sourceSha256).slice(0, 12)}… but dist holds ${manifest.source.sha256.slice(0, 12)}… - rebuild and re-run the gates`,
+    );
+  }
+  if (!report.allPassed && !args.allowFailed) {
+    const failed = (report.results ?? []).filter((r) => !r.passed).map((r) => r.id);
+    throw new Error(`gates failed (${failed.join(", ")}) - fix them, or pass --allow-failed to stamp a build that says so`);
+  }
+
+  const stamped = {
+    ...manifest,
+    geometry: report.geometry,
+    space: {
+      ...manifest.space,
+      boundingBox: report.space.boundingBox,
+      sizeMeters: report.space.sizeMeters,
+      statedSizeMeters: config.statedSizeMeters,
+      sizeDeltaPct: report.space.sizeDeltaPct,
+    },
+    gates: {
+      runAt: report.runAt,
+      runner: report.runner,
+      allPassed: Boolean(report.allPassed),
+      results: (report.results ?? []).map(({ id, name, threshold, measured, passed }) => ({
+        id,
+        name,
+        threshold,
+        measured,
+        passed,
+      })),
+    },
+    preview: {
+      ...manifest.preview,
+      playUrl: args.playUrl ?? manifest.preview?.playUrl ?? defaultPlayUrl(config.slug),
+    },
+  };
+
+  const body = JSON.stringify(stamped, null, 2) + "\n";
+  const bytes = Buffer.byteLength(body, "utf8");
+  const shape = validateManifest(stamped, { bytes });
+  if (!shape.ok) throw new Error(`refusing to stamp an invalid manifest:\n  - ${shape.errors.join("\n  - ")}`);
+  if (bytes > MANIFEST_MAX_BYTES) {
+    throw new Error(`refusing to stamp: ${bytes} bytes exceeds the ${MANIFEST_MAX_BYTES} byte ceiling`);
+  }
+
+  await fsp.writeFile(manifestPath, body, "utf8");
+
+  console.log(
+    [
+      "",
+      `  stamped ${path.relative(PROJECT_DIR, manifestPath)}  (${(bytes / 1024).toFixed(1)} KB)`,
+      `  ${stamped.geometry.triangles.toLocaleString("en-US")} tris · ${stamped.geometry.drawCalls} draws · ${stamped.geometry.materials} materials`,
+      `  ${stamped.space.sizeMeters.map((n) => n.toFixed(2)).join(" × ")} m`,
+      `  gates: ${stamped.gates.allPassed ? `all ${stamped.gates.results.length} passed` : `${stamped.gates.results.filter((r) => !r.passed).length} FAILED`}`,
+      `  preview: ${stamped.preview.playUrl}`,
+      "",
+    ].join("\n"),
+  );
+
+  return 0;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error) => {
+    console.error(`\n[stamp] ${error?.message ?? error}\n`);
+    process.exit(1);
+  },
+);

package/templates/asset-viewer/vite.config.js

@@ -0,0 +1,24 @@
+// Shared viewer build config. Copied verbatim into every asset project and
+// hashed by gate G13 - edit it in packages/asset-viewer-template/template.
+import { defineConfig } from "vite";
+import { emitManifest } from "./tools/emit-manifest.mjs";
+
+export default defineConfig({
+  // Games serve at the domain root, but relative keeps the build origin-agnostic.
+  base: "./",
+  build: {
+    // `dist` is the ONLY outDir name the Genex CLI's deployGame recognises;
+    // anything else uploads the whole source folder instead of the build.
+    outDir: "dist",
+    // Fingerprinted chunks opt into the serve worker's immutable cache dir.
+    // dist/genex-asset.json deliberately stays outside it, so a republish is
+    // always picked up.
+    assetsDir: "_immutable",
+    emptyOutDir: true,
+    target: "es2022",
+  },
+  server: {
+    port: Number(process.env.PORT) || 5190,
+  },
+  plugins: [emitManifest()],
+});

package/templates/skills/genex-asset-author/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: genex-asset-author
+description: Author and publish ONE asset to the free Genex asset library via `genex asset new` — STRICTLY user-initiated. Use ONLY when the user explicitly asks to publish something from their game as an asset, or to create a standalone asset for the library. Never suggest, offer, or trigger this lane on your own — building a game never requires it.
+---
+
+# Genex Asset Author
+
+Ship one procedural Three.js asset to the free, MIT-licensed Genex asset
+library: a standalone project whose build is a uniform orbitable viewer, whose
+only varying file is ONE self-contained TypeScript factory module, and whose
+quality bar is 17 machine-checked gates.
+
+## When this lane runs — and when it must not
+
+Run it ONLY when the user explicitly asks — the two real shapes:
+
+- **"Publish this <thing> from my game as an asset"** — extract an object out
+  of the game they're building.
+- **"I want to make an asset / assets"** — asset-first authoring.
+
+NEVER offer this unprompted. Finishing a game, noticing a nice prop, or
+wanting to showcase work is NOT a trigger; the user's request is. If they ask
+what publishing an asset means, explain (free, MIT, copyable by anyone from the
+dashboard, listed under the gallery's Assets tab) and let them decide.
+
+## The one non-negotiable before publish: MIT with THEIR name
+
+A published asset gets a **Copy code** button on its page — anyone can take the
+file. Publishing = releasing it under MIT. Before scaffolding, ask the user for
+their attribution name and pass it as `--holder "<name>"`. If it was skipped,
+set it before publish in BOTH places: `asset.config.json` → `license.holder`,
+and line 2 of the module (the MIT header). Never publish with the placeholder.
+
+## Scaffold
+
+```bash
+npx genex asset new <kebab-slug> --title "<Display Name>" \
+  --dims WxDxH --tri-band LOW-HIGH --holder "<user's name>"
+cd <kebab-slug>
+npm install
+npx playwright-core install chromium   # once per machine
+```
+
+One asset = one project = one turntable page. Several assets → run the command
+once per asset. `--dims` is width x depth x height in metres as a human states
+it (gate G4 measures the built model against it ±5%); tune it and the config
+honestly to the real object before gating, not to whatever the code produced.
+
+The viewer is hash-locked: never edit `index.html`, `src/viewer/*`, `src/main.js`
+or `tools/*` — gate G13 fails the build if you do. Your entire surface is
+`src/asset/<name>.ts` and `asset.config.json`.
+
+## The module contract
+
+`export function create<Name>Model(options): THREE.Group` — one self-contained
+file:
+
+- Core `three` ONLY. No `three/examples/jsm`, no `ShaderMaterial`, no
+  `CanvasTexture` (needs a DOM), no `fetch`, no external URL anywhere in the
+  file (gate G11 scans for `http` — comments included).
+- Real metres, Y-up, +Z forward, origin at base centre (y = 0).
+- Seeded determinism: same seed + options → identical vertex data (G10).
+- `userData.dispose()` returns the renderer to baseline (G12) — every
+  geometry, material and texture you create is released.
+- Textures are in-code `DataTexture`s; `MeshStandardMaterial` for surfaces.
+- Keep the 4-line header (name / MIT + holder / units / requires) — it is what
+  makes a copied file self-describing.
+
+Extracting from a game: COPY the code out (the game keeps its own), then strip
+every game dependency, re-origin to base centre, convert to real metres, seed
+the randomness, and add the dispose contract. The result must run in a project
+holding nothing but `three` — that is literally gate G8 (paste-and-run).
+
+## Gate loop
+
+```bash
+npm run verify        # vite build + 17 gates + manifest stamp, in one command
+```
+
+Iterate until 17/17. Each failure names its gate and what it measured. The
+gates are the design bar of the Assets tab — never loosen `asset.config.json`
+ceilings to sneak a failing model through; fix the model.
+
+Two measured traps: metalness 1.0 needs the viewer's environment map to read
+correctly — it renders BLACK in a game with no envmap, so prefer 0.2-0.9 for
+believable metals; and a mirrored basis can pass every numeric gate while
+being silently inside-out — LOOK at the turntable from several angles before
+calling it done.
+
+## Ship
+
+```bash
+npx genex init                          # create the project (sign-in if needed)
+npx genex preview --no-build            # staging turntable — show the user this link
+npx genex publish --no-build --categories assets   # only after the user says ship it
+```
+
+`--no-build` matters: `npm run verify` already built AND stamped the manifest
+into `dist/` — a plain preview/publish would rebuild and ship an unstamped
+manifest, and the dashboard's Copy-code button reads that manifest. Publish
+ONLY on the user's explicit go, with the licence holder set to their real name.

package/templates/skills/genex-game-director/references/routing-map.md

@@ -67,6 +67,7 @@ copy demo architecture.
 | players talking to each other by TEXT — chat, room chat, "let them type to each other" (`room.chat` + `npx genex controller chat`) | `$genex-threejs-multiplayer` |
 | players TALKING — voice chat, mic, "hear each other", proximity/positional voice (`room.voice` + `npx genex controller voice`; party-sized, max 6 per room — say that number out loud before building the feature) | `$genex-threejs-multiplayer` |
 | player identity, sign-in, guests, saves/progress, per-player state, shared persistent world, leaderboards—mandatory for every game | `$genex-threejs-embed-auth` |
+| the player EXPLICITLY asks to make an asset or publish something from their game as an asset for the free library | `$genex-asset-author` (`genex asset new`) — never offer this unprompted; no game duty routes here |
 
 ## Request-sized execution