incanto 0.69.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-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'));

package/bin/incanto-verify.mjs

@@ -19,23 +19,20 @@
  * what to arrange, and says so in the summary.
  */
 import { spawnSync } from 'node:child_process';
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readJson } from './_read-json.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
-const { ladderText, ladderVerdict } = await import(
+const { firstLine, ladderText, ladderVerdict, saysRung } = await import(
   pathToFileURL(join(PKG, 'dist', 'test.js')).href
 );
 
 const argv = process.argv.slice(2);
 const asJson = argv.includes('--json');
-const flag = (name) => {
-  const i = argv.indexOf(name);
-  return i >= 0 ? argv[i + 1] : null;
-};
 if (argv.includes('--help') || argv.includes('-h')) {
-  console.log(`Usage: incanto verify [scene.json] [--behaviors FILE] [--json]
+  console.log(`Usage: incanto verify [scene.json] [--behaviors FILE[,FILE...]] [--json]
 
 Walks the whole ladder and tells you the ONE thing to do next:
 
@@ -111,7 +108,26 @@ const { scene, candidates } = findScene();
 if (!scene) {
   const report = ladderVerdict([], { candidates });
   console.log(asJson ? JSON.stringify(report, null, 2) : ladderText(report));
-  process.exit(0);
+  /*
+   * Exit 2, not 0.
+   *
+   * "Unmeasured is not a failure" is the rule for a RUNG — the game is fine and
+   * a question could not be asked. This is different: nothing was measured at
+   * ALL, and a CI step whose whole job is `incanto-verify` went green having
+   * looked at nothing:
+   *
+   *   2 scenes here, and guessing between them would verify the wrong one:
+   *     src/game.scene.json
+   *     src/title.scene.json
+   *   $ echo $?
+   *   0
+   *
+   * A distinct code rather than 1, so a script can still tell "your game is
+   * broken" from "tell me WHICH game" — and `verdict.measured` says the same
+   * thing to anything reading `--json`. Multi-scene is the shape of almost
+   * every real game, so this is not an edge case for long.
+   */
+  process.exit(2);
 }
 if (!existsSync(scene) || !statSync(scene).isFile()) {
   console.error(`no such scene: ${scene}`);
@@ -129,8 +145,20 @@ if (!existsSync(scene) || !statSync(scene).isFile()) {
  * path to a file sitting right next to the scene it had already found.
  */
 function findBehaviors(sceneFile) {
-  const named = flag('--behaviors');
-  if (named) return { file: named, guessed: false };
+  /*
+   * Every `--behaviors`, not the first one.
+   *
+   * The flag is repeatable in the bins this spawns, and reading only
+   * `argv.indexOf` would have silently dropped every file after the first —
+   * the CLI accepting an argument and then not using it, which is the shape
+   * this round keeps finding. Joined with commas, which is the other form the
+   * children take.
+   */
+  const named = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--behaviors' && argv[i + 1]) named.push(argv[++i]);
+  }
+  if (named.length > 0) return { file: named.join(','), guessed: false };
   const near = dirname(sceneFile);
   for (const dir of [near, join(near, '..'), process.cwd(), join(process.cwd(), 'src')]) {
     for (const base of ['behaviors', 'behaviours']) {
@@ -275,31 +303,62 @@ if (rungs[0].status === 'pass') {
           .join(', ') +
         ')' +
         (won > 0 ? ` — ${won} did finish it` : ''),
+      // The throw itself, not a command to go and find it. This rung used to
+      // say "read the throw: incanto-playtest …" — sending its reader to
+      // another tool for a line this JSON already carries.
+      notes: (out?.errorMessages ?? []).slice(0, 3),
       fix:
         tally('error') > 0
-          ? `read the throw: \`incanto-playtest ${scene}${behaviors ? ` --behaviors ${behaviors}` : ''}\`, and \`engine.stats().errors\` in your own harness`
+          ? `fix the script named above, then re-run \`incanto-verify ${scene}${behaviors ? ` --behaviors ${behaviors}` : ''}\``
           : tally('fell') > 0
             ? `the player left the world with nothing catching them — give the level a floor, walls, or a respawn (\`incanto-playtest ${scene}${behaviors ? ` --behaviors ${behaviors}` : ''}\` prints where)`
             : `nothing moved — check the input map and the controller: \`incanto-playtest ${scene}${behaviors ? ` --behaviors ${behaviors}` : ''}\``,
     });
-  } else if (r.status === 0) {
+  } else if (won > 0) {
+    /*
+     * `r.status === 0` used to stand in for "it finished the game", and the
+     * exit code stopped meaning that: `incanto-playtest` now exits 0 for a
+     * scene with nobody to drive, because never being asked is not a failure.
+     * This rung read that 0 and reported
+     *
+     *   ✓ plays — 0 of 8 seeded runs finished it
+     *
+     * on a scene with no character in it, right where it had been careful to
+     * say `? plays — nothing here is drivable`. The report has `runs`; ask it
+     * what happened rather than asking the child how it felt about it.
+     */
     rungs.push({
       name: 'plays',
       status: 'pass',
       summary: `${won} of ${total} seeded runs finished it`,
     });
   } else if (undrivable) {
+    /*
+     * "Nobody to move" was said about games the bot had PLAYED.
+     *
+     * The driver has driven the mouse for a while, and this rung only ever
+     * asked whether a character could walk — so a flip puzzle whose every tile
+     * the bot clicked, whose `clicked` wires all fired and whose board changed
+     * state, was told to add a character controller. A whole class of games —
+     * match-3, tower defense, cards, point-and-click, RTS, board games — has no
+     * character to add, and the advice was to add one anyway.
+     */
+    const clicks = (out?.runs ?? []).reduce((n, r) => n + (r.clicks ?? 0), 0);
     rungs.push({
       name: 'plays',
       status: 'unmeasured',
       summary:
-        out?.hasPlayer === false
-          ? `nothing here is drivable — ${total} runs had nobody to move`
-          : `${total} runs went nowhere, and your behaviours were not loaded — that is most of what moves a character`,
+        clicks > 0
+          ? `played with the MOUSE — ${clicks} click(s) across ${total} runs, and no win to reach`
+          : out?.hasPlayer === false
+            ? `nothing here is drivable — ${total} runs had nobody to move and nothing to click`
+            : `${total} runs went nowhere, and your behaviours were not loaded — that is most of what moves a character`,
       fix:
-        out?.hasPlayer === false
-          ? 'give the player a character controller, the `player` group, or the name Player — otherwise no seeded run can play this'
-          : `name them: \`incanto-verify ${scene} --behaviors src/behaviors.ts\``,
+        clicks > 0
+          ? 'a mouse game is played, not walked — emit `won`/`lost` and this rung can pass'
+          : out?.hasPlayer === false
+            ? 'give the player a character controller, the `player` group, or the name Player — or `Clickable` on what the cursor drives'
+            : `name them: \`incanto-verify ${scene} --behaviors src/behaviors.ts\``,
     });
   } else if (noGoal) {
     rungs.push({
@@ -317,9 +376,22 @@ if (rungs[0].status === 'pass') {
     rungs.push({
       name: 'plays',
       status: 'unmeasured',
+      // The parenthetical is only worth printing when it has something in it.
+      // It listed `lost` and `unfinished` and nothing else, so a game whose
+      // runs all ended at a SCENE SWAP — every tally zero — reported
+      // `8 runs played without reaching a win ()`, an empty bracket where the
+      // reason should be. `swapped` IS the reason, and it is the one outcome
+      // here that explains itself.
       summary:
         `${total} runs played without reaching a win` +
-        ` (${[count(tally('lost'), 'lost'), count(tally('unfinished'), 'ran out the clock')].filter(Boolean).join(', ')})`,
+        (() => {
+          const why = [
+            count(tally('lost'), 'lost'),
+            count(tally('unfinished'), 'ran out the clock'),
+            count(tally('swapped'), 'changed scene, where this bot stops measuring'),
+          ].filter(Boolean);
+          return why.length > 0 ? ` (${why.join(', ')})` : '';
+        })(),
       fix: 'nothing here is broken — a win that takes skill or a sequence is out of reach of random play. Judge it with a scripted run: `bun run verify`, or `runScript` from `incanto/test`',
     });
   }
@@ -363,13 +435,36 @@ if (rungs[0].status === 'pass') {
     // arithmetic that cannot be true: `✓ feels — 12 of 9 fired`. The number has
     // to add up with the `silent` list beside it.
     const firedDeclared = declaredPaths.length - silent.length;
+    /*
+     * A rung that exists because "wired but never triggered plays perfectly and
+     * feels dead, and every other rung here calls it healthy" — and which then
+     * called it healthy itself. `fired.size === 0` failed and ANYTHING else
+     * passed, so the flagship starter reported
+     *
+     *   ✓ feels — 13 of 26 fired — silent: /Game/Ward1/ChimeSfx …
+     *
+     * A tick next to thirteen emitters nobody heard is the same claim the rung
+     * was written to stop.
+     *
+     * It is not a FAILURE either: a random bot does not light three wards, so a
+     * win chime it never reached is not a broken wire. That is exactly what
+     * `unmeasured` means in this ladder — the tool did not get to look — and it
+     * is the one status that cannot be read as approval.
+     */
     rungs.push({
       name: 'feels',
-      status: 'pass',
-      summary:
-        silent.length === 0
-          ? `every one of the ${declared} sound/effect nodes fired`
-          : `${firedDeclared} of ${declared} fired — silent: ${silent.slice(0, 3).join(', ')}${silent.length > 3 ? ` +${silent.length - 3}` : ''}`,
+      ...(silent.length === 0
+        ? { status: 'pass', summary: `every one of the ${declared} sound/effect nodes fired` }
+        : {
+            status: 'unmeasured',
+            summary:
+              `${firedDeclared} of ${declared} fired — silent: ${silent.slice(0, 3).join(', ')}` +
+              `${silent.length > 3 ? ` +${silent.length - 3}` : ''}`,
+            fix:
+              'a silent emitter is either a broken wire or a moment random play never ' +
+              'reached — the two look identical from here. Reach it in a scripted run ' +
+              '(`runScript` from `incanto/test`), and this rung can tell you which.',
+          }),
     });
   }
 }
@@ -381,7 +476,7 @@ if (rungs[0].status === 'pass') {
 {
   const isMultiplayer = (() => {
     try {
-      const doc = JSON.parse(readFileSync(scene, 'utf-8'));
+      const doc = readJson(scene);
       return Boolean(doc?.multiplayer);
     } catch {
       return false;
@@ -528,21 +623,11 @@ if (rungs[0].status === 'pass') {
       summary: firstLine(r.stderr) ?? 'no page to ask',
       fix: 'open the preview page and run this again — the log buffer is in the browser',
     });
-  } else if (report.ok) {
-    rungs.push({ name: 'says', status: 'pass', summary: 'no errors, no failed assets' });
   } else {
-    const asset = report.assetErrors?.[0];
-    rungs.push({
-      name: 'says',
-      status: 'fail',
-      // A game whose grass and water are fine still fails here when its player
-      // never loaded — which is the case this rung exists for, and the one
-      // `draws` calls healthy.
-      summary: asset
-        ? `asset ${asset.ref} never loaded: ${asset.error}`
-        : (report.worst?.message ?? `${report.stats?.errors ?? 0} errors were swallowed`),
-      fix: 'read it in full: `incanto-logs`',
-    });
+    // What it MEANS lives in `verify-ladder` with the rest of the pure half —
+    // this rung was reading `ok` and dropping every warning the page reported,
+    // and there was nowhere to test that without a browser.
+    rungs.push(saysRung(report));
   }
 }
 
@@ -556,10 +641,6 @@ function safeJson(text) {
     return null;
   }
 }
-function firstLine(text) {
-  const line = (text ?? '').split('\n').find((l) => l.trim());
-  return line ? line.trim() : null;
-}
 
 const verdict = ladderVerdict(rungs);
 if (asJson) {
@@ -576,4 +657,4 @@ if (asJson) {
 // 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 = verdict.ok ? 0 : 1;
+process.exitCode = verdict.measured ? (verdict.ok ? 0 : 1) : 2;

package/bin/incanto.mjs

@@ -23,9 +23,10 @@
  * the SAME runtime that started this one, which matters because `--behaviors`
  * loads your TypeScript and bun and node disagree about what they can import.
  */
-import { readFileSync } from 'node:fs';
+
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readJson } from './_read-json.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -50,7 +51,7 @@ const COMMANDS = {
 
 function version() {
   try {
-    const pkg = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf-8'));
+    const pkg = readJson(join(HERE, '..', 'package.json'));
     return pkg.version ?? 'unknown';
   } catch {
     return 'unknown';