@maka/maka-cli 5.144.0 → 5.146.0

package/bundle/typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maka/maka-cli",
-  "version": "5.144.0",
+  "version": "5.146.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-backlog-mcp.sub.cmd.js

@@ -2,6 +2,89 @@ import fs from 'fs';
 import path from 'path';
 import { Command } from '../../command.js';
 import { UsageError } from '../../error.js';
+/**
+ * `maka play:backlog:mcp` -- an MCP server exposing the game-backlog
+ * admin actions as tools, so an AI agent can drive backlog resolution
+ * directly (list items, read one, attach evidence, advance status,
+ * request an AI-drafted bench) with a human approving the consequential
+ * calls through the MCP client's own tool-permission UI.
+ *
+ * SCOPED HERE, NOT AT THE CLI'S TOP LEVEL (user ruling 2026-09-08). A
+ * command whose only job is game-backlog administration does not belong
+ * as a generic top-level command just because an unrelated, unbuilt stub
+ * (`maka ai:mcp`) already claimed that shape in .claude/mcp.json -- that
+ * stub is left alone. This lives under the feature it actually serves,
+ * registered as a CHILD of `play:backlog` (see registerBacklogMcp below
+ * and its call site in sideQuest-backlog.sub.cmd.ts).
+ *
+ * RUNS AS THE M2M SERVICE ACCOUNT, NEVER A HUMAN'S SESSION. Every tool
+ * below is a thin wrapper over the exact same REST routes
+ * game-backlog-v1-rest-api.ts already exposes to the web board and the
+ * human CLI -- so every role check, evidence gate and audit log line
+ * those routes already enforce applies here unchanged. Nothing is
+ * bypassed or reimplemented; this command only adds a way to call them.
+ *
+ * STDOUT IS THE PROTOCOL, NOT A LOG (the one hard constraint worth
+ * repeating). StdioServerTransport owns process.stdout for the MCP
+ * JSON-RPC stream once connected -- anything else written there
+ * (including Log.* from this codebase's own logger, which writes via
+ * console.log) corrupts every message after it. Diagnostics in this
+ * file go to console.error (stderr) only, and Log is not imported here
+ * at all, on purpose.
+ *
+ * SECRETS COME FROM THE MAKA-CLI.COM PROJECT'S OWN CONFIG.
+ *
+ * `--site <path>` IS THE REAL ANSWER, NOT `cwd` (corrected 2026-09-08,
+ * after `cwd` alone shipped broken). The first cut relied entirely on
+ * `this.cfg.getAppConfigPath(env)` against `process.cwd()` -- the same
+ * mechanism `maka env:get` uses -- on the theory that an MCP client's
+ * server config setting `cwd` to a maka-cli.com checkout would make
+ * that resolve correctly. It does not, at least not for a server
+ * registered in Claude Code's GLOBAL config (~/.claude.json): the
+ * process spawns with the session's own working directory regardless
+ * of a `cwd` field there, `mustBeInMakaProject` fails immediately
+ * ("No maka project config file found"), and the process exits before
+ * the MCP handshake completes -- which surfaces to the client as a
+ * bare "Connection closed", not a readable error. `--site` sidesteps
+ * the whole question of what a given MCP client's `cwd` support
+ * actually is: the checkout path is a literal argument, not inferred
+ * from where the process happened to start.
+ *
+ * `cwd` STILL WORKS AS A CONVENIENCE, for a terminal or a client that
+ * does set it correctly (a project-scoped `.claude/mcp.json`, say):
+ * omitting `--site` falls back to the original cwd-based resolution.
+ * `mustBeInMakaProject` is OFF at the framework level either way --
+ * this command does its own check so both paths get the same clear
+ * error instead of the framework's for one and a hand-rolled one for
+ * the other.
+ *
+ * AUTHZERO_SECRET never leaves this lookup either way: it is used
+ * once, in-process, to mint an Auth0 token, and is never logged or
+ * forwarded anywhere.
+ */
+/**
+ * WHAT A CONNECTING SESSION IS TOLD, surfaced at MCP connection time.
+ * This is the loop as it actually runs, corrected in-session against
+ * real friction on the first item worked through it (2026-09-08/09) --
+ * not a policy written in advance of ever using the tool.
+ */
+const MCP_SERVER_INSTRUCTIONS = `This server exposes the game-backlog admin actions as tools. Every tool is a thin wrapper over the same REST routes the human web board and CLI already use -- role checks, evidence gates, and audit logging all apply exactly as they do for a human admin. Nothing here bypasses them.
+
+THE LOOP IS NEARLY AUTOMATED BY DESIGN -- that is the whole reason this server exists instead of a human doing this work by hand. For each item: read it in full (backlog_get), find the root cause in the relevant repo (maka-cli-src for the CLI/game engine, maka-cli.com for the site/backend -- see sources-1/CLAUDE.md for which repo owns what), fix it, write/run tests, build, lint, typecheck -- then commit, version-bump (maka-cli-src releases go through the full chain: push -> build -> publish -> GitHub release + site pin -> the pin auto-deploys the site; maka-cli.com-only changes need either the next pin or a manual "gh workflow run deploy.yml"), and once the fix is committed AND actually deployed live: backlog_advance(status: "ready-for-bench", commits: [sha]) -> backlog_draft_bench -> backlog_dry_run_bench (read the transcript it returns -- this is automated QA, not the reporter's confirmation, and needs no human) -> if the transcript demonstrates the fix, backlog_advance(status: "in-review", repro: <the same spec that just dry-ran clean>), which promotes the draft to a real bench AND notifies the reporter in one call. That is as far as automation goes: only the reporter can sign off or reject from here, in-game -- see "WHAT THIS SERVER DELIBERATELY DOES NOT EXPOSE" below for why that boundary is real and the bench-verification step is not.
+
+DO NOT PAUSE TO ASK PERMISSION for a routine step in that loop -- committing a clean, tested, single-purpose change, bumping a version, pushing, letting the release chain run, or dry-running a drafted bench. That is exactly the friction this tooling was built to remove. Reserve a real stop for a production-only action with no easy rollback, or a failure that genuinely needs human judgment to interpret.
+
+DESIGN DECISIONS THAT COME UP WHILE FIXING ARE NOT A STOP EITHER. Make the call, then record the decision and its reasoning as a backlog_comment (kind: "note") on the item itself -- that comment is the durable record a later reviewer or the reporter can read; a live question to the human is the thing this loop exists to avoid. Only escalate a design question directly to the human when the choice changes externally-visible behavior in a way nobody could reconstruct from the code and the note.
+
+SR5 CANON FIDELITY IS NOT OPTIONAL for anything in the side-quest game (see maka-cli-src/CLAUDE.md, "ALWAYS FOLLOW THE SHADOWRUN RULES"): a deviation from the rules is a defect, full stop -- check the shadowrun-rag MCP tool (ask_shadowrun_rules) rather than reasoning from memory, including when this item's own vetting text claims to summarize the rules; it has been wrong before. "The excerpt didn't mention X" is not "X doesn't exist."
+
+SWEEP THE FAMILY. If a root cause affects more than one open item (the same clamp, the same missing check, the same divergent code path), fix all of them in one pass and add a backlog_comment cross-referencing the shared cause on every affected item -- fixing one twin and leaving the other broken reproduces the same report one layer down.
+
+"ready-for-bench" MEANS COMMITTED *AND* DEPLOYED, not just committed -- a bench built against undeployed code would replay the old bug and report the fix as failed. Don't advance to ready-for-bench before confirming the deploy actually succeeded.
+
+WHAT THIS SERVER DELIBERATELY DOES NOT EXPOSE, and why: signoff/reject/close are the reporter's own verbs -- only the person who hit the bug can confirm it is actually gone in play, and an AI closing its own fix would be exactly the self-certification this project's design already rejects for human admins. grant/revoke/delete/top-priority are rarer, higher-blast-radius actions left to a human directly. NOTE THE DIFFERENCE FROM backlog_dry_run_bench: proving a bench SCRIPT replays correctly is a technical fact with no subjective side, and it needs no human -- it is not the same gate as the reporter deciding their own bug is gone, and must never be treated as though it were (that confusion cost a full stop the first time this loop ran for real).
+
+A "failed" vetting state means the automated vetting pipeline itself errored (no lore-search hits, or the model call failed) -- it is NOT a judgment that the item lacks merit. Treat those items as needing your own diagnosis from scratch, same as any other open item.`;
 export function registerBacklogMcp(parent) {
     return Command.create({
         name: 'mcp',
@@ -94,6 +177,7 @@ export function registerBacklogMcp(parent) {
         const { z } = await import('zod');
         const { ensureServiceSession } = await import('./sideQuest/utilities/service-account-auth.js');
         const { fetchBacklog, fetchBacklogItemById, patchBacklogItem, draftBacklogBench, postBacklogComment, BACKLOG_STATUSES, } = await import('./sideQuest/utilities/backlog.js');
+        const { dryRunRepro } = await import('./sideQuest/utilities/repro-launch.js');
         const statusEnum = BACKLOG_STATUSES;
         /** Every tool call goes through this: reuse the cached session, and
          *  on the first `expired` outcome, mint a fresh one and retry
@@ -117,7 +201,16 @@ export function registerBacklogMcp(parent) {
                 isError: value.outcome !== 'ok',
             };
         }
-        const server = new McpServer({ name: 'maka-play-backlog', version: '1.0.0' });
+        // SERVER INSTRUCTIONS -- surfaced by MCP clients at connection time
+        // as priority context, which is the point: this ships the workflow
+        // WITH the tool, for whichever Claude session connects, rather than
+        // depending on one session's own accumulated memory of how this is
+        // supposed to run. Written and revised in-session (2026-09-08/09)
+        // after the first real item exposed exactly the friction it warns
+        // against -- see MCP_SERVER_INSTRUCTIONS's own history if this ever
+        // needs updating again: keep it a record of what actually went
+        // wrong, not a wishlist.
+        const server = new McpServer({ name: 'maka-play-backlog', version: '1.0.0' }, { instructions: MCP_SERVER_INSTRUCTIONS });
         server.registerTool('backlog_list', {
             title: 'List backlog items',
             description: 'List game-backlog items, optionally filtered by status. Closed (complete) items are excluded unless a status is given explicitly.',
@@ -144,29 +237,75 @@ export function registerBacklogMcp(parent) {
         }, async ({ itemId, text, kind, awaitingReporter }) => toolResult(await withSession(async (token) => ({
             outcome: await postBacklogComment(itemId, text, { kind, awaitingReporter }, token),
         }))));
+        // MIRRORS IRepro (types/repro.ts), LOOSELY. `steps` is the one field
+        // that actually matters to this tool and to `dryRunRepro` -- the
+        // server's own validateRepro is the real authority on the rest, so
+        // `fixture`'s rich nested shape (barrier/npcs/items/level/host) is
+        // passed through as an opaque object rather than re-declared here.
+        // Re-mirroring a shape this deep in a second place is exactly the
+        // kind of drift this codebase's own comments repeatedly warn about;
+        // letting the server validate it is the one copy that matters.
+        const reproSchema = z.object({
+            fixture: z.record(z.string(), z.unknown()).optional(),
+            steps: z.array(z.string()).min(1),
+            premise: z.string().optional(),
+            expect: z.string().optional(),
+            minVersion: z.string().optional(),
+            live: z.string().optional(),
+        });
         server.registerTool('backlog_advance', {
             title: 'Advance a backlog item (attach evidence / change status)',
-            description: `Move a backlog item's status and/or attach fix-commit evidence. This is the
-        actual resolution action -- it will be refused by the server (with a message explaining
-        why) if you try to enter "in-review" or "complete" without at least one commit attached,
-        or "complete" without the reporter's sign-off already on the item. This tool never signs
-        off or rejects a fix on the reporter's behalf -- only the person who filed the item can
-        do that, in-game.`,
+            description: `Move a backlog item's status, attach fix-commit evidence, and/or promote a
+        dry-run-verified bench (see backlog_dry_run_bench) from reproDraft to a real repro. This
+        is the actual resolution action -- it will be refused by the server (with a message
+        explaining why) if you try to enter "in-review" or "complete" without at least one commit
+        attached, or "complete" without the reporter's sign-off already on the item. This tool
+        never signs off or rejects a fix on the reporter's behalf -- only the person who filed the
+        item can do that, in-game.`,
             inputSchema: {
                 itemId: z.string(),
                 status: z.enum(statusEnum),
                 commits: z.array(z.string()).optional()
                     .describe('Fix-commit SHAs to attach (merged with whatever is already there).'),
+                repro: reproSchema.optional()
+                    .describe('Promote a bench to real: pass the exact spec that just dry-ran clean via backlog_dry_run_bench. Clears any pending reproDraft.'),
             },
-        }, async ({ itemId, status, commits }) => toolResult(await withSession((token) => patchBacklogItem(itemId, { status, commits }, token))));
+        }, async ({ itemId, status, commits, repro }) => toolResult(await withSession((token) => patchBacklogItem(itemId, { status, commits, repro }, token))));
         server.registerTool('backlog_draft_bench', {
             title: 'Draft an AI bench for a backlog item',
-            description: 'Ask the server to AI-draft a two-room repro bench for one item (lands in reproDraft, not repro -- a human has to dry-run and promote it separately via backlog_advance with a repro body). Costs a model call server-side.',
+            description: 'Ask the server to AI-draft a two-room repro bench for one item (lands in reproDraft, not repro -- dry-run it with backlog_dry_run_bench, then promote it with backlog_advance\'s repro param). Costs a model call server-side.',
             inputSchema: {
                 itemId: z.string(),
                 verbs: z.array(z.string()).optional().describe('The verbs available to reference in the bench steps.'),
             },
         }, async ({ itemId, verbs }) => toolResult(await withSession((token) => draftBacklogBench(itemId, token, verbs))));
+        server.registerTool('backlog_dry_run_bench', {
+            title: 'Dry-run a backlog item\'s bench, headlessly',
+            description: `Replay a backlog item's bench steps against a real boot of the game engine
+        -- no terminal, no login, no human -- and return the transcript (including dice/mechanics
+        lines). Proves the drafted bench (or an already-attached one) reproduces the reported
+        behavior BEFORE it is promoted or shown to the reporter. Prefers the item's pending
+        reproDraft; falls back to its attached repro if there is no draft. This is technical
+        verification, not the reporter's in-play confirmation -- reading the transcript and
+        judging whether it demonstrates the fix is exactly the kind of judgment call this tool
+        exists to let you make yourself.`,
+            inputSchema: { itemId: z.string() },
+        }, async ({ itemId }) => {
+            const result = await withSession((token) => fetchBacklogItemById(itemId, token));
+            if (result.outcome !== 'ok' || !result.item)
+                return toolResult(result);
+            const spec = result.item.reproDraft?.spec ?? result.item.repro;
+            if (!spec || !Array.isArray(spec.steps) || spec.steps.length === 0) {
+                return toolResult({ outcome: 'rejected', message: 'No reproDraft or repro on this item yet -- call backlog_draft_bench first.' });
+            }
+            try {
+                const { lines, warnings } = await dryRunRepro(spec);
+                return toolResult({ outcome: 'ok', transcript: lines.join('\n'), warnings });
+            }
+            catch (e) {
+                return toolResult({ outcome: 'rejected', message: `Dry run failed to boot: ${e.message}` });
+            }
+        });
         const transport = new StdioServerTransport();
         await server.connect(transport);
         console.error('[play:backlog:mcp] ready');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maka/maka-cli",
-  "version": "5.144.0",
+  "version": "5.146.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.",