incanto 0.68.0 → 0.70.0

package/bin/incanto-playtest.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
 /**
  * incanto-playtest — the engine plays your game and tells you whether it works.
  *
@@ -23,26 +23,50 @@ import { dirname, join, resolve } from 'node:path';
  * Exit code 1 when no run reached a win, so CI can gate on it.
  */
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
+import { behaviorFiles, behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
+import { readJson } from './_read-json.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const PKG_VERSION = readJson(join(PKG, 'package.json')).version;
+
+/**
+ * A numeric flag with a missing or non-numeric value is a TYPO.
+ *
+ * `--runs $RUNS` with RUNS unset swallowed the NEXT flag as its value and gave
+ * `Number(undefined)` = NaN, which ran ZERO runs and then printed a confident
+ * report asserting the opposite of the truth about the scene — exit 0.
+ */
+function num(raw, flag) {
+  const n = Number(raw);
+  if (raw === undefined || raw === '' || !Number.isFinite(n)) {
+    console.error(`${flag} needs a number, got ${raw === undefined ? 'nothing' : `'${raw}'`}`);
+    process.exit(1);
+  }
+  return n;
+}
 
 function parseArgs(argv) {
   const args = { runs: 20, seconds: 60, seed: 1, out: '.incanto/playtest' };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--behaviors') args.behaviors = argv[++i];
-    else if (a === '--runs') args.runs = Number(argv[++i]);
-    else if (a === '--seconds') args.seconds = Number(argv[++i]);
-    else if (a === '--seed') args.seed = Number(argv[++i]);
-    else if (a === '--fall-below') args.fallBelow = Number(argv[++i]);
-    else if (a === '--reach-radius') args.reachRadius = Number(argv[++i]);
+    // Repeatable: behaviours legitimately live in more than one file.
+    if (a === '--behaviors') args.behaviors = [...(args.behaviors ?? []), argv[++i]];
+    else if (a === '--runs') args.runs = num(argv[++i], '--runs');
+    else if (a === '--seconds') args.seconds = num(argv[++i], '--seconds');
+    else if (a === '--seed') args.seed = num(argv[++i], '--seed');
+    else if (a === '--fall-below') args.fallBelow = num(argv[++i], '--fall-below');
+    else if (a === '--reach-radius') args.reachRadius = num(argv[++i], '--reach-radius');
     else if (a === '--out') args.out = argv[++i];
     else if (a === '--no-replays') args.noReplays = true;
     else if (a === '--json') args.json = true;
     else if (a === '--help' || a === '-h') args.help = true;
     else if (a.startsWith('--')) {
+      // `invalid`, not `help`: printing usage and exiting 0 told an agent its
+      // typo was a request. `--runs=4`, `--behaviours`, `--no-replay` all landed
+      // here and looked like success — and with `--json` the machine path was
+      // literally silent (0 bytes on stdout).
       console.error(`unknown flag: ${a}`);
+      args.invalid = true;
       args.help = true;
     } else if (!args.scene) args.scene = a;
   }
@@ -60,24 +84,28 @@ if (args.help || !args.scene) {
                     3D, 1000 px under it in 2D — 2D counts DOWN the screen)
   --reach-radius R  how close counts as "reached" (default 2 in 3D, 32 px in 2D)
   --behaviors FILE  your Behavior subclasses (.ts works on node >= 23.6 / bun)
+                    comma-separate or repeat for several files
   --out DIR         where failing replays go (default .incanto/playtest)
   --no-replays      report only, write nothing
   --json            the full report as JSON instead of prose
 
-Exits 1 when no run reached a win.`);
-  process.exit(args.help && args.scene !== undefined ? 0 : 1);
+Exits 1 when a run THREW or left the world, or when a win is declared and no
+run reached it. A scene that declares no win, or has nobody to drive, exits 0 —
+the report marks those · rather than ✗, and the exit code says the same.`);
+  process.exit(!args.invalid && args.help && args.scene !== undefined ? 0 : 1);
 }
 
-const { playtest, playtestText, failingReplays } = await import(
+const { playtest, playtestText, playtestFailed, failingReplays } = await import(
   pathToFileURL(join(PKG, 'dist', 'test.js')).href
 );
 const incanto = await import(pathToFileURL(join(PKG, 'dist', 'index.js')).href);
 
 const behaviors = {};
-if (args.behaviors) {
+const behaviorSources = behaviorFiles(args.behaviors);
+for (const file of behaviorSources) {
   let mod;
   try {
-    mod = await import(pathToFileURL(resolve(args.behaviors)).href);
+    mod = await import(pathToFileURL(resolve(file)).href);
   } catch (e) {
     const why = e?.message ?? String(e);
     // NODE CANNOT IMPORT THE PATTERN WE TEACH. Every template's behaviors.ts
@@ -94,7 +122,7 @@ if (args.behaviors) {
     // `village-quest-3d` starter, and it breaks for any author who splits their
     // behaviours across files — which is most of them, eventually.
     reexecUnderBun(import.meta.url, why);
-    console.error(behaviorsHelp(args.behaviors, why));
+    console.error(behaviorsHelp(file, why));
     process.exit(1);
   }
   for (const [name, value] of Object.entries(mod)) {
@@ -102,13 +130,13 @@ if (args.behaviors) {
       behaviors[name] = value;
     }
   }
-  if (Object.keys(behaviors).length === 0) {
-    console.error(`warning: no Behavior subclasses exported from ${args.behaviors}`);
-  }
+}
+if (behaviorSources.length > 0 && Object.keys(behaviors).length === 0) {
+  console.error(`warning: no Behavior subclasses exported from ${behaviorSources.join(', ')}`);
 }
 
 const scenePath = resolve(args.scene);
-const sceneJson = JSON.parse(readFileSync(scenePath, 'utf-8'));
+const sceneJson = readJson(scenePath);
 const sceneDir = dirname(scenePath);
 
 let report;
@@ -118,11 +146,11 @@ try {
     seconds: args.seconds,
     seed: args.seed,
     behaviors,
-    stubMissingBehaviors: !args.behaviors,
+    stubMissingBehaviors: behaviorSources.length === 0,
     ...(Number.isFinite(args.fallBelow) ? { fallBelow: args.fallBelow } : {}),
     ...(Number.isFinite(args.reachRadius) ? { reachRadius: args.reachRadius } : {}),
     // sub-scenes resolve relative to the scene file, as the loader does
-    resolveScene: (p) => JSON.parse(readFileSync(resolve(sceneDir, p), 'utf-8')),
+    resolveScene: (p) => readJson(resolve(sceneDir, p)),
   });
 } catch (e) {
   console.error(`playtest failed: ${e?.message ?? e}`);
@@ -140,12 +168,27 @@ if (args.json) {
 if (!args.noReplays && !args.json) {
   const seen = new Set();
   const written = [];
+  /*
+   * Stamp WHICH GAME each recording is of.
+   *
+   * `.incanto/playtest` is keyed by `(outcome, seed)` and nothing else, and
+   * never cleaned. So the second playtest in a project either leaves a stale
+   * `stuck-seed3.json` from a scene that no longer exists sitting beside the
+   * current one, or silently overwrites another scene's — and
+   * `incanto-play --commands` happily replays any recording against any scene
+   * and reports success, because nothing in the file said what it was of.
+   */
+  const stamp = {
+    path: relative(process.cwd(), scenePath) || scenePath,
+    name: typeof sceneJson?.name === 'string' ? sceneJson.name : undefined,
+    engine: PKG_VERSION,
+  };
   for (const { seed, outcome, replay } of failingReplays(report)) {
     if (seen.has(outcome)) continue;
     seen.add(outcome);
     const file = join(resolve(args.out), `${outcome}-seed${seed}.json`);
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, JSON.stringify(replay, null, 2));
+    writeFileSync(file, JSON.stringify({ ...replay, scene: stamp }, null, 2));
     written.push(file);
   }
   if (written.length > 0) {
@@ -157,4 +200,4 @@ if (!args.noReplays && !args.json) {
 // asynchronously, and exiting discards whatever has not flushed. A --json
 // report read by another program came back truncated — silently, and only
 // when piped, which is the only way a program reads it.
-process.exitCode = report.runs.some((r) => r.outcome === 'won') ? 0 : 1;
+process.exitCode = playtestFailed(report) ? 1 : 0;

package/bin/incanto-serve.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, statSync } from 'node:fs';
+/**
+ * Serve a BUILT game, and let the inspect tools see it.
+ *
+ * `incanto-frame` and `incanto-logs` ask a dev server, which asks the page over
+ * vite's HMR channel. A production build has no HMR, so nothing could look at
+ * the artifact an author actually deploys:
+ *
+ *     $ node …/incanto-logs.mjs --port 8791      # dist/ on a static server
+ *     no incanto dev server found.
+ *     $ incanto-verify src/game.scene.json
+ *     ? draws — no incanto dev server found.
+ *     ? says  — no incanto dev server found.
+ *
+ * The boot path is the only code a BUILD adds over a SCENE — `main.ts`, the
+ * loading overlay, the asset base path, everything after `createGame*` resolves
+ * — and it was the one thing no rung could reach.
+ *
+ * This serves `dist/` as plain static files (no bundler, no transform) and adds
+ * exactly two things: the `/__incanto/*` endpoints the CLIs already speak, and
+ * one inline script injected into `index.html` that relays them to the page.
+ * Nothing is added to the files on disk, so what you measure is what you ship.
+ *
+ *     bunx incanto-serve                 # ./dist on :4180
+ *     bunx incanto-serve build --port 5050
+ *     bunx incanto-verify                # now measures the BUILT game
+ */
+import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = resolve(fileURLToPath(import.meta.url), '../..');
+const DIST = join(PKG, 'dist');
+if (!existsSync(join(DIST, 'vite.js'))) {
+  console.error('incanto: the package is not built (dist/vite.js missing).');
+  process.exit(1);
+}
+const { createStaticInspectHost, serveFrameEndpoints } = await import(
+  pathToFileURL(join(DIST, 'vite.js')).href
+);
+const VERSION = createRequire(import.meta.url)('../package.json').version;
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.error(`Usage: incanto-serve [dir] [--port N] [--host H]
+
+Serve a BUILT game (default ./dist) so \`incanto-frame\`, \`incanto-logs\` and
+\`incanto-verify\` can measure the artifact you actually deploy. Files are served
+byte-for-byte; the inspect client is injected into index.html at serve time and
+never written to disk.`);
+  process.exit(0);
+}
+const flag = (name, fallback) => {
+  const at = args.indexOf(name);
+  return at >= 0 && args[at + 1] ? args[at + 1] : fallback;
+};
+const port = Number(flag('--port', '4180'));
+const host = flag('--host', '127.0.0.1');
+const dir = resolve(
+  args.find(
+    (a) =>
+      !a.startsWith('--') &&
+      args[args.indexOf(a) - 1] !== '--port' &&
+      args[args.indexOf(a) - 1] !== '--host',
+  ) ?? 'dist',
+);
+
+if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+  console.error(
+    `incanto-serve: no such directory: ${dir}\n` +
+      '  Build first (`bun run build`), or name the output directory.',
+  );
+  process.exit(1);
+}
+if (!existsSync(join(dir, 'index.html'))) {
+  console.error(
+    `incanto-serve: ${dir} has no index.html — that is not a built game.\n` +
+      '  Point this at the directory your bundler wrote.',
+  );
+  process.exit(1);
+}
+
+const inspect = createStaticInspectHost(process.cwd());
+serveFrameEndpoints(inspect, VERSION);
+
+const TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.glb': 'model/gltf-binary',
+  '.gltf': 'model/gltf+json',
+  '.mp3': 'audio/mpeg',
+  '.ogg': 'audio/ogg',
+  '.wav': 'audio/wav',
+  '.wasm': 'application/wasm',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+};
+
+/** Inject the relay ahead of everything, so it exists before the game boots. */
+function withInspectClient(html) {
+  const tag = `<script>${inspect.clientScript()}</script>`;
+  if (html.includes('</head>')) return html.replace('</head>', `${tag}</head>`);
+  return tag + html;
+}
+
+const server = createServer((req, res) => {
+  const url = (req.url ?? '/').split('?')[0] ?? '/';
+  if (url.startsWith('/__incanto/')) {
+    // `originalUrl` is what the endpoints read for the query string; connect
+    // strips the mount path off `url` and these were written against that.
+    req.originalUrl = req.url;
+    if (inspect.handleInspect(req, res)) return;
+    res.statusCode = 404;
+    res.end('{}');
+    return;
+  }
+  // A path outside the served directory is a traversal attempt, not a typo.
+  const rel = normalize(decodeURIComponent(url)).replace(/^(\.\.[/\\])+/, '');
+  let file = join(dir, rel);
+  if (!file.startsWith(dir + sep) && file !== dir) file = dir;
+  if (!existsSync(file) || statSync(file).isDirectory()) file = join(dir, 'index.html');
+
+  const type = TYPES[extname(file)] ?? 'application/octet-stream';
+  if (file.endsWith('index.html')) {
+    const html = withInspectClient(readFileSync(file, 'utf8'));
+    res.statusCode = 200;
+    res.setHeader('content-type', TYPES['.html']);
+    res.end(html);
+    return;
+  }
+  res.statusCode = 200;
+  res.setHeader('content-type', type);
+  res.end(readFileSync(file));
+});
+
+server.on('error', (e) => {
+  if (e?.code === 'EADDRINUSE') {
+    console.error(`incanto-serve: port ${port} is already in use — pass --port N.`);
+    process.exit(1);
+  }
+  throw e;
+});
+
+server.listen(port, host, () => {
+  console.log(`incanto-serve  ${dir}`);
+  console.log(`  http://${host}:${port}/`);
+  console.log('  open it, then run `incanto-verify` / `incanto-frame` / `incanto-logs`.');
+});

package/bin/incanto-skills.mjs

@@ -22,8 +22,19 @@ function parseArgs(argv) {
     if (argv[i] === '--format') args.format = argv[++i];
     else if (argv[i] === '--out') args.out = argv[++i];
     else if (argv[i] === '--help' || argv[i] === '-h') args.help = true;
+    /*
+     * The bare word, because that is what everything tells you to type.
+     *
+     * `incanto-new`'s closing message — the last thing a scaffolded project
+     * prints, and the line that installs the skills the whole workflow depends
+     * on — said `bunx incanto-skills claude`, and that was an unknown argument.
+     * The flag form stays; this makes the printed line true.
+     */ else if (argv[i] === 'claude' || argv[i] === 'opencode') args.format = argv[i];
     else {
+      // Not `help`: printing usage and exiting 0 for a typo meant
+      // `incanto-skills --oops` installed ZERO skills and reported success.
       console.error(`unknown argument: ${argv[i]}`);
+      args.invalid = true;
       args.help = true;
     }
   }
@@ -32,7 +43,8 @@ function parseArgs(argv) {
 
 const args = parseArgs(process.argv.slice(2));
 if (args.help || !['claude', 'opencode'].includes(args.format)) {
-  console.log(`Usage: npx incanto-skills [--format claude|opencode] [--out <dir>]
+  console.log(`Usage: npx incanto-skills [claude|opencode] [--out <dir>]
+       npx incanto-skills [--format claude|opencode] [--out <dir>]
 
   claude    (default) Claude Code project skills:
             <out>/<skill-name>/SKILL.md          (default out: .claude/skills)
@@ -40,7 +52,7 @@ if (args.help || !['claude', 'opencode'].includes(args.format)) {
             <out>/<skill-name>.md                (default out: skills)
 
 Skills are read from the installed incanto package and match its version.`);
-  process.exit(args.help ? 0 : 1);
+  process.exit(!args.invalid && args.help ? 0 : 1);
 }
 
 const outRoot = resolve(args.out ?? (args.format === 'claude' ? '.claude/skills' : 'skills'));