@maka/maka-cli 5.177.0 → 5.179.0

package/bundle/typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maka/maka-cli",
-  "version": "5.177.0",
+  "version": "5.179.0",
   "type": "module",
   "summary": "A command line tool for scaffolding Meteor 3.x applications using either React.",
   "description": "A command line tool for scaffolding Meteor 3.x applications using React.",

package/bundle/typescript/src/commands/game/sideQuest/commands/say.js

@@ -100,7 +100,14 @@ export class SayCommand extends Command {
             // comms visually reads as a different "space" than in-person speech.
             const inCall = !!currentPlayer.activeCallPartner || !!currentPlayer.crewChannel;
             const prefix = inCall ? `${CALL_ICON} ` : '';
-            this.logger.logWithColor(`${prefix}${message}`, inCall ? CALL_COLOR : 'yellow', { actor: currentPlayer.name });
+            const speech = {
+                speaker: currentPlayer.name,
+                text: message,
+                self: true,
+                ...(inCall ? { comms: true } : {}),
+                ...(currentPlayer.gender ? { gender: currentPlayer.gender } : {}),
+            };
+            this.logger.logWithColor(`${prefix}${message}`, inCall ? CALL_COLOR : 'yellow', { actor: currentPlayer.name }, { speech });
         }
         // "say" and "call" are deliberately similar -- once a call connects
         // (see call.ts), the two ends keep talking with the same "say" command

package/bundle/typescript/src/commands/game/sideQuest/factories/scene-chunks.js

@@ -458,10 +458,13 @@ ${JSON_ONLY}
     "plane"?: "meat"|"matrix", // "matrix" = paydata: only in a hasNode room, category
                                 // Datachip/Document. A matrix-plane winCondition item makes
                                 // the job a datarun (its room MUST have ice).
-    "forPuzzle"?: string // role "clue" only: which puzzle's passphrase this clue reveals.
-                          // EVERY puzzle needs exactly one clue item, category "Book",
-                          // placed in a DIFFERENT room than that puzzle (door puzzles: any
-                          // room). The clue's text is written in a later pass.
+    "forDevice"?: string // roles "clue" and "key" only: the devices[].name this item
+                          // opens. A "clue" reveals that panel's code -- EVERY panel needs
+                          // exactly one, category "Book", placed in a DIFFERENT room than
+                          // the panel (door panels: any room); its text is written in a
+                          // later pass. A "key" is what that lock takes -- EVERY lock
+                          // needs exactly one, category "Key", and the lock opens to
+                          // nothing else.
                           // ${isContinuation ? 'Role "starting" is FORBIDDEN in this scene -- the runner arrives fully equipped (see dossier).' : 'Role "starting" items are the fresh runner\'s basic kit.'}
   }],
   "winCondition": {
@@ -829,6 +832,60 @@ export function parseJsonReply(reply) {
  * tokens building on it. Deeper semantics (reachability, clue coverage,
  * matrix defense...) are still enforced by the assembled-scene validators.
  */
+/**
+ * WHICH KEY OPENS THIS LOCK -- the one answer the validator, the
+ * normalizer and assembleScene all have to agree on, so it lives once.
+ *
+ * In order of how much the skeleton actually SAID:
+ *   1. a key-role item whose `forDevice` names the lock (the field the
+ *      prompt asks for);
+ *   2. the `keyRequired` of the exit this lock holds (the older way of
+ *      saying the same thing);
+ *   3. a key whose name shares a real word with the lock's name or
+ *      concept ("Warehouse Fob" for "Warehouse Maglock") -- accepted
+ *      only when exactly one does;
+ *   4. the one unclaimed key in a scene with one unkeyed lock: the
+ *      model wrote "one key per lock" and simply never joined them.
+ *
+ * `claimed` lets a caller walking several locks keep one key from
+ * opening two of them by rule 3 or 4. Nothing here invents a key --
+ * that is normalizeSkeleton's call, capped, with a log line.
+ */
+export function resolveLockKey(skeleton, device, claimed = new Set()) {
+    const items = skeleton.items ?? [];
+    const keys = items.filter(i => i.role === 'key');
+    const declared = keys.find(i => i.forDevice === device.name);
+    if (declared)
+        return declared.name;
+    for (const room of skeleton.rooms ?? []) {
+        for (const e of room.exits ?? []) {
+            if (e.device !== device.name || !e.keyRequired)
+                continue;
+            const wanted = e.keyRequired.toLowerCase();
+            const hit = items.find(i => i.name.toLowerCase() === wanted);
+            if (hit)
+                return hit.name;
+        }
+    }
+    const free = keys.filter(k => !claimed.has(k.name) && !k.forDevice);
+    const words = (s) => new Set(s.toLowerCase().replace(/'s\b/g, '').split(/[^a-z0-9]+/).filter(w => w.length >= 4 && !GENERIC_LOCK_WORDS.has(w)));
+    const lockWords = new Set([...words(device.name), ...words(device.concept ?? '')]);
+    const named = free.filter(k => [...words(k.name)].some(w => lockWords.has(w)));
+    if (named.length === 1)
+        return named[0].name;
+    const locks = (skeleton.devices ?? []).filter(d => (d.kind ?? 'panel') === 'lock');
+    const unkeyed = locks.filter(l => !keys.some(k => k.forDevice === l.name)
+        && !(skeleton.rooms ?? []).some(r => (r.exits ?? []).some(e => e.device === l.name && e.keyRequired)));
+    if (free.length === 1 && unkeyed.length === 1 && unkeyed[0].name === device.name)
+        return free[0].name;
+    return undefined;
+}
+/** Words every lock and every key share, which therefore prove nothing
+ *  about which key opens which lock. */
+const GENERIC_LOCK_WORDS = new Set([
+    'lock', 'maglock', 'door', 'gate', 'grate', 'hatch', 'safe', 'vault', 'cage', 'shutter', 'padlock', 'cabinet', 'locker',
+    'keycard', 'card', 'passkey', 'access', 'security', 'back', 'front', 'side', 'room', 'office', 'main', 'inner', 'outer',
+]);
 export function validateSkeleton(skeleton, player, crew) {
     const fail = (msg) => { throw new Error(`Skeleton invalid: ${msg}`); };
     if (!Array.isArray(skeleton?.rooms) || skeleton.rooms.length === 0)
@@ -1004,17 +1061,19 @@ export function validateSkeleton(skeleton, player, crew) {
             }
         }
         else if (kind === 'lock') {
-            // A lock's findable way through is its KEY. Either the door it
-            // holds names one, or a key-role item exists for it.
+            // A lock's findable way through is its KEY -- and it has to be
+            // THIS lock's key, resolvable by resolveLockKey, because that is
+            // the exact question assembleScene asks when it writes the
+            // device's `keyItem`. "Some key-role item exists somewhere" used
+            // to pass here (8XDR2BCZoSmpqdkXG: Corvid's Fob existed, Yuri's
+            // Maglock shipped with no keyItem, and the fob opened nothing).
             const holdsDoor = refs > 0;
-            const keyed = skeleton.rooms.some(r => (r.exits ?? []).some(e => e.device === device.name && e.keyRequired));
-            const looseKey = skeleton.items.some(i => i.role === 'key');
             // The same floor for a lock that holds a PRIZE rather than a
             // door (a safe): its findable way in is a key, and "holdsDoor"
             // used to exempt it -- so a keyless safe passed here and then
             // stood in play with only breach options (bPiyyWu9TQ4pBfGbM).
-            if (!keyed && !looseKey) {
-                fail(`lock "${device.name}" ${holdsDoor ? 'holds a door with no "keyRequired"' : 'holds a prize'} and the scene has no "key"-role item -- a runner without locksmith has no way through it. Add a key.`);
+            if (!resolveLockKey(skeleton, device)) {
+                fail(`lock "${device.name}" ${holdsDoor ? 'holds a door' : 'holds a prize'} and no "key"-role item opens it -- add one with "forDevice": "${device.name}", so a runner without locksmith has a way through.`);
             }
         }
         // A WARD is the exception no clue can rescue: there is no findable
@@ -1673,6 +1732,56 @@ export function normalizeSkeleton(skeleton) {
         synthesized++;
         notes.push(`normalized: panel "${device.name}" had no clue item; synthesized Book clue "${name}" in "${safe[0]}" (reachable without passing the barrier).`);
     }
+    // EVERY LOCK HAS ITS KEY, BY NAME (8XDR2BCZoSmpqdkXG: "the Barrier
+    // explicitly states to use Corvid's Fob, I have Corvid's Fob, but
+    // doesn't unlock the maglock").
+    //
+    // The skeleton prompt has always asked for "one key per lock", and
+    // the model has always delivered one -- but nothing ever wrote WHICH
+    // lock a key opened onto the key, and assembleScene never wrote a
+    // `keyItem` onto the lock. The validator only asked whether a
+    // key-role item existed at all, so the pair shipped unrelated: a fob
+    // that opened nothing beside a maglock that took nothing, with every
+    // line of prose in between insisting they matched. The same shape as
+    // the panel clue above, one loop later: resolve the pair here,
+    // record it on the key so every later pass (and the log) can see it,
+    // and invent a key only when the model left a lock with none.
+    const SYNTHESIZED_KEY_CAP = 2;
+    let synthesizedKeys = 0;
+    const claimedKeys = new Set();
+    for (const device of skeleton.devices ?? []) {
+        if ((device.kind ?? 'panel') !== 'lock')
+            continue;
+        const items = skeleton.items ?? [];
+        const keyName = resolveLockKey(skeleton, device, claimedKeys);
+        if (keyName) {
+            claimedKeys.add(keyName);
+            const key = items.find(i => i.name === keyName);
+            if (key && key.forDevice !== device.name) {
+                const was = key.forDevice ? `pointed at "${key.forDevice}"` : 'named no device';
+                key.forDevice = device.name;
+                notes.push(`normalized: key "${key.name}" ${was}; it is the key to lock "${device.name}".`);
+            }
+            continue;
+        }
+        const safe = safeRoomsFor(skeleton, device);
+        if (safe.length === 0) {
+            notes.push(`could not synthesize a key for lock "${device.name}": nowhere is reachable without passing it.`);
+            continue;
+        }
+        if (synthesizedKeys >= SYNTHESIZED_KEY_CAP) {
+            notes.push(`declined to synthesize a key for lock "${device.name}": already invented ${SYNTHESIZED_KEY_CAP} this skeleton -- a fresh draft is the better bet.`);
+            continue;
+        }
+        let name = `${device.name} Key`;
+        for (let i = 2; items.some(it => it.name === name); i++)
+            name = `${device.name} Key ${i}`;
+        skeleton.items = items;
+        skeleton.items.push({ name, role: 'key', category: 'Key', forDevice: device.name, room: safe[0] });
+        claimedKeys.add(name);
+        synthesizedKeys++;
+        notes.push(`normalized: lock "${device.name}" had no key; synthesized Key "${name}" in "${safe[0]}" (reachable without passing the barrier).`);
+    }
     // REWARD-REFERENCE reconciliation. A rewardItem (a puzzle's, or the
     // winCondition's) must point at an UNPLACED role-"reward" item, but
     // models regularly point it at a placed loot/clue item instead -- and
@@ -2335,8 +2444,17 @@ export function assembleScene(skeleton, details, playerName) {
                 heldExit.set(canonical, e.direction);
         }
     }
+    // WHICH KEY EACH LOCK TAKES -- the field Device.offer actually reads.
+    // Same ruling as heldExit just above: the skeleton says it once (on
+    // the key's forDevice, or the held exit's keyRequired) and this is
+    // the only place it becomes the device's own `keyItem`. Without it
+    // the door never opens to its key (8XDR2BCZoSmpqdkXG).
+    const claimedKeys = new Set();
     const devices = (skeleton.devices ?? []).map(device => {
         const detail = deviceDetail.get(device.name);
+        const keyItem = (device.kind ?? 'panel') === 'lock' ? resolveLockKey(skeleton, device, claimedKeys) : undefined;
+        if (keyItem)
+            claimedKeys.add(keyItem);
         const guardsExit = device.room && detail?.guardsExit && roomExitDirsByName.get(device.room)?.has(detail.guardsExit.toLowerCase())
             ? detail.guardsExit.toLowerCase()
             : undefined;
@@ -2357,6 +2475,7 @@ export function assembleScene(skeleton, details, playerName) {
             opensExit: heldExit.get(device.name),
             description: detail?.description ?? device.concept,
             code,
+            keyItem,
             grantsItem: device.grantsItem,
             openMessage: detail?.openMessage ?? 'It opens.',
             refuseMessage: detail?.refuseMessage ?? 'Nothing happens.',

package/bundle/typescript/src/commands/game/sideQuest/factories/scene-factory.js

@@ -334,6 +334,47 @@ Key Locations: ${json.rooms.map(r => r.name).join(', ')}
             logger.write(`Scene "${json.name}": "${name}" resolved to item "${fuzzy}" by fuzzy match -- names generated apart drifted.`);
             return itemMap.get(fuzzy);
         };
+        // A LOCK THE SEED NEVER GAVE A KEY, WHOSE OWN PROSE NAMES ONE
+        // (8XDR2BCZoSmpqdkXG: "the Barrier explicitly states to use
+        // Corvid's Fob, I have Corvid's Fob, but doesn't unlock the
+        // maglock"). Until 2026-09-13 the generator never wrote `keyItem`
+        // onto a lock at all, so every generated run on the board carries a
+        // maglock with no key beside a Key-category item whose details say
+        // which door it opens. Those seeds are already stored on live
+        // sessions and will be rebuilt from as-is, so the repair has to
+        // happen HERE, on the shipped content, exactly like the fuzzy
+        // keyItem repair above: read the prose the player reads. A Key
+        // item whose text names the device, or whose name the device's
+        // description uses, is its key -- when exactly one does. Failing
+        // that, the one Key in a scene with one lock is that lock's key.
+        // Anything less certain stays unrepaired and logged, because
+        // guessing wrong hands a player a key that opens the wrong door.
+        const allDevices = json.rooms.flatMap(r => (r.devices ?? []).map(d => ({ ...d, roomName: r.name })));
+        const inferKeyItem = (d) => {
+            if (d.kind !== 'lock' || d.open)
+                return undefined;
+            const keys = [...itemMap.values()].filter(i => i.category === Category.Key);
+            const deviceName = d.name.toLowerCase();
+            const prose = (d.description ?? '').toLowerCase();
+            const mentions = keys.filter(k => `${k.description ?? ''} ${k.details ?? ''}`.toLowerCase().includes(deviceName)
+                || prose.includes(k.name.toLowerCase()));
+            let hit;
+            let how = '';
+            if (mentions.length === 1) {
+                hit = mentions[0];
+                how = 'its prose names';
+            }
+            else if (mentions.length === 0 && keys.length === 1 && allDevices.filter(x => x.kind === 'lock' && !x.keyItem && !x.open).length === 1) {
+                hit = keys[0];
+                how = 'the only key in the scene beside the only lock is';
+            }
+            if (!hit) {
+                logger.write(`Scene "${json.name}": lock "${d.name}" declares no keyItem and no single Key item can be read as its key -- it opens only to force.`);
+                return undefined;
+            }
+            logger.write(`Scene "${json.name}": lock "${d.name}" declared no keyItem; ${how} "${hit.name}", which now opens it.`);
+            return hit;
+        };
         // Step 4.9: DEVICES, and the doors they hold shut.
         // After items, because a device may hold a key or a reward.
         //
@@ -372,7 +413,7 @@ Key Locations: ${json.rooms.map(r => r.name).join(', ')}
                     name: d.name,
                     description: d.description,
                     code: d.code,
-                    keyItem: d.keyItem ? findItem(d.keyItem) : undefined,
+                    keyItem: d.keyItem ? findItem(d.keyItem) : inferKeyItem(d),
                     grantsItem: d.grantsItem ? findItem(d.grantsItem) : undefined,
                     atSpot: d.atSpot,
                     opensExit: d.opensExit,

package/bundle/typescript/src/commands/game/sideQuest/headless.js

@@ -84,13 +84,14 @@ export class EmitterLogger extends Logger {
         const actor = g?.scene.getPlayerByName(d.actorName);
         return actor?.currentLocation ? { room: actor.currentLocation.name } : { actor: d.actorName };
     }
-    log(message, scope) {
+    log(message, scope, data) {
         this.emit('log', message, scope ?? this.ambient('log'), {
             actor: currentSession()?.dispatch?.actorName,
+            ...(data ? { data } : {}),
         });
     }
-    logWithColor(message, color = 'white', scope) {
-        this.log(`{${color}-fg}${message}{/${color}-fg}`, scope);
+    logWithColor(message, color = 'white', scope, data) {
+        this.log(`{${color}-fg}${message}{/${color}-fg}`, scope, data);
     }
     meta(message, color, scope) {
         const text = color ? `{${color}-fg}${message}{/${color}-fg}` : message;

package/bundle/typescript/src/commands/game/sideQuest/models/npc.js

@@ -766,7 +766,8 @@ export class NPC extends Player {
             // SPEECH STAYS IN THE STORY. Someone on the other end of the bond
             // talking to you is fiction, and burying it in the Mechanics
             // ticker would mean missing "Rattle's not budging, need your call".
-            this.logger.logWithColor(`${style.icon} ${this.name}: "${spoken}"`, style.color);
+            const speech = { speaker: this.name, text: spoken, link: true, ...(this.gender ? { gender: this.gender } : {}) };
+            this.logger.logWithColor(`${style.icon} ${this.name}: "${spoken}"`, style.color, undefined, { speech });
         }
         else {
             // TELEMETRY GOES TO MECHANICS (player ruling 2026-08-25: the

package/bundle/typescript/src/commands/game/sideQuest/models/player.js

@@ -2821,11 +2821,22 @@ export class Player extends AbstractPlayer {
         // room -- a cross-room say over a call would render to the wrong
         // side, and two humans sharing a room would each see the line
         // twice. Solo Logger ignores the scope (inert third arg).
+        // SPOKEN LINES AS DATA (emitter.ts SpeechData): the words ride beside
+        // the text so the browser can hand them to a voice. Inert solo.
+        const speech = (comms) => ({
+            speech: {
+                speaker: actor.name,
+                text: message,
+                ...(actor === this ? { self: true } : {}),
+                ...(comms ? { comms: true } : {}),
+                ...(actor.gender ? { gender: actor.gender } : {}),
+            },
+        });
         if (this.activeCallPartner === actor && actor.currentLocation !== this.currentLocation) {
-            this.logger.logWithColor(`${CALL_ICON} ${actor.name} (over comms): ${message}`, CALL_COLOR, { actor: this.name });
+            this.logger.logWithColor(`${CALL_ICON} ${actor.name} (over comms): ${message}`, CALL_COLOR, { actor: this.name }, speech(true));
             return;
         }
-        this.logger.logWithColor(`{white-fg}${actor.name}:{/white-fg} ${message}`, (actor === this) ? 'yellow' : 'green', { actor: this.name });
+        this.logger.logWithColor(`{white-fg}${actor.name}:{/white-fg} ${message}`, (actor === this) ? 'yellow' : 'green', { actor: this.name }, speech(false));
     }
     see(actor, verb, details, quiet) {
         if (actor !== this && this.canPerceive(actor)) {

package/bundle/typescript/src/commands/game/sideQuest/utilities/logger.js

@@ -88,7 +88,7 @@ export class Logger {
     // solo screen shows the local player everything its callers already
     // gated for. A headless session's EmitterLogger reads it (or applies
     // the ambient dispatch default) to stamp per-player visibility.
-    log(message, _scope) {
+    log(message, _scope, _data) {
         const logBox = this.screen?.children.find(child => child.type === 'box' && child.options.id === 'logBox');
         if (logBox) {
             logBox.insertBottom(message); // Supports color tags
@@ -106,9 +106,11 @@ export class Logger {
         // not the system log (player request: two files).
         this.transcript(message);
     }
-    logWithColor(message, color = 'white', scope) {
+    // `data` rides the same way as `scope`: inert on the solo screen, stamped
+    // onto the event by a headless session's EmitterLogger (GameEvent.data).
+    logWithColor(message, color = 'white', scope, data) {
         const coloredMessage = `{${color}-fg}${message}{/${color}-fg}`;
-        this.log(coloredMessage, scope);
+        this.log(coloredMessage, scope, data);
     }
     /**
      * The MECHANICS ticker (readability pass): dice anatomy and resource

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maka/maka-cli",
-  "version": "5.177.0",
+  "version": "5.179.0",
   "type": "module",
   "summary": "A command line tool for scaffolding Meteor 3.x applications using either React.",
   "description": "A command line tool for scaffolding Meteor 3.x applications using React.",