@thehammer/danx-dashboard-mcp 0.1.79 → 0.1.81

package/dist/index.js

@@ -94,6 +94,7 @@
  */
 import { isEntrypointModule } from "./entrypoint.js";
 import { BRIDGE_SUBCOMMAND, runBridgeCommand } from "./bridge.js";
+import { PLAN_STATE_SUBCOMMAND, runPlanStateCommand } from "./plan-state.js";
 import { resolveDeclaredCredential } from "./credential.js";
 import { recordSessionConnectionAfterConnect } from "./session-connection.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -881,16 +882,25 @@ async function main() {
 // symlink-aware (DX-1647) so it holds under the symlinked `npx` bin the worker
 // spawns, not just a direct `node dist/index.js`.
 //
-// `bridge` is the one subcommand: the session event stream client the danxbot
-// plugin's plan event bridge runs. It never boots the MCP server; its only
-// input is `CLAUDE_CODE_SESSION_ID` (read from its environment) plus
-// `--resume-ids` — the dashboard URL, credential source, and credential itself
-// come from the session-connection record this server's own `plan_connect`
-// wrote (`session-connection.ts`), never from the bridge's own environment
-// (DX-2862: a bridge trusting its own ambient `DANXBOT_DISPATCH_TOKEN` is the
-// exact bug this repo fixed). Any OTHER argument is refused rather than
-// ignored, so a typo cannot silently start an MCP server on stdio where the
-// bridge was meant to run.
+// `bridge` and `plan-state` are the two subcommands. `bridge` is the session
+// event stream client the danxbot plugin's plan event bridge runs. It never
+// boots the MCP server; its only input is `CLAUDE_CODE_SESSION_ID` (read from
+// its environment) plus `--resume-ids` — the dashboard URL, credential source,
+// and credential itself come from the session-connection record this server's
+// own `plan_connect` wrote (`session-connection.ts`), never from the bridge's
+// own environment (DX-2862: a bridge trusting its own ambient
+// `DANXBOT_DISPATCH_TOKEN` is the exact bug this repo fixed).
+//
+// `plan-state` (DX-2921) is the ONE-SHOT client of
+// `GET /api/plan-sessions/me/turn-state`, run by the DX-2888 plugin's
+// turn-start / turn-end hooks — see `plan-state.ts`'s own doc comment for the
+// full contract. It ALWAYS exits 0 (success or failure alike: the hook must
+// stay silent), so even an unexpected rejection here is caught and reported
+// the same `{ok:false, reason}` way rather than propagating a non-zero exit
+// or an uncaught stack trace into the hook.
+//
+// Any OTHER argument is refused rather than ignored, so a typo cannot
+// silently start an MCP server on stdio where a subcommand was meant to run.
 if (isEntrypointModule(import.meta.url, process.argv[1])) {
     const [subcommand, ...rest] = process.argv.slice(2);
     if (subcommand === BRIDGE_SUBCOMMAND) {
@@ -899,8 +909,16 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             process.exit(1);
         });
     }
+    else if (subcommand === PLAN_STATE_SUBCOMMAND) {
+        runPlanStateCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[danx-dashboard-mcp] plan-state fatal: ${err.message}`);
+            process.stdout.write(`${JSON.stringify({ ok: false, reason: "fatal" })}\n`);
+            process.exit(0);
+        });
+    }
     else if (subcommand !== undefined) {
-        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only one is "${BRIDGE_SUBCOMMAND}")`);
+        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only ones are ` +
+            `"${BRIDGE_SUBCOMMAND}" and "${PLAN_STATE_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

package/dist/plan-state.js

@@ -0,0 +1,194 @@
+/**
+ * `danx-dashboard-mcp plan-state` — the ONE-SHOT client of
+ * `GET /api/plan-sessions/me/turn-state` (DX-2921).
+ *
+ * WHO RUNS IT. The danxbot Claude Code plugin's DX-2888 turn-start /
+ * turn-end hooks, via the plugin's existing `bridgeCommand()` npx path — the
+ * SAME package pin, no separate install, no deep import of this package's
+ * `dist/` internals (that was DX-2921's whole reason to exist: the DX-2888
+ * architecture review found the first build of this logic vendored a private
+ * copy of the MCP package and hardcoded the dashboard HTTP contract inside
+ * the PLUGIN). The plugin decides what to DO with the answer (inject plan
+ * numbers at turn start, refuse to let a turn end while the session could
+ * legally start work and has nothing running); this module only fetches it.
+ *
+ * THE CONTRACT (agreed with the DX-2888 plugin side, issue comment 4245 on
+ * DX-2921 — binding, because the plugin is already built against it):
+ *   - print EXACTLY ONE JSON line on stdout, and ALWAYS exit 0 — success or
+ *     failure alike, because the hook must stay silent rather than spam the
+ *     session's own turn with a stack trace;
+ *   - a session that is not connected to a plan prints
+ *     `{"ok":false,"reason":"session_not_connected"}` — that EXACT literal,
+ *     because the plugin keys its no-log-spam rule on it (it is also the
+ *     dashboard's own 409 error code for this case — see
+ *     `requireConnectedPlanId`, `plan-session-context.ts`);
+ *   - on success, every count is a finite number, `plan` carries `id` +
+ *     `name`, and every `startable` / `held` entry carries a string `id` +
+ *     `title` — the plugin rejects anything else as `bad_response`, so this
+ *     module validates the server's response BEFORE printing it, rather than
+ *     trusting a 200 status to mean a well-shaped body;
+ *   - human-readable diagnostics go to stderr only, never stdout.
+ *
+ * THE CREDENTIAL — the SAME resolver `bridge` uses (DX-2862 / DX-2921 AC),
+ * via `resolveBridgeOptions` (`bridge.ts`): the dashboard URL, credential
+ * source and credential all come from the connection record this session's
+ * OWN danx-dashboard MCP server wrote on its last successful `plan_connect`
+ * (`session-connection.ts`), never from this process's own ambient env. That
+ * is deliberate here for the identical reason it is deliberate for `bridge`:
+ * a hook process trusting whatever `DANXBOT_DISPATCH_TOKEN` happens to be in
+ * its environment is precisely the DX-2862 bug (a hook's ambient credential
+ * silently pointed at a different dashboard from the one the session's tools
+ * actually use).
+ *
+ * A HARD TIMEOUT (AC 30672) — `PLAN_STATE_REQUEST_TIMEOUT_MS`. This call
+ * blocks a turn boundary the plugin is holding open, so it must never hang:
+ * a slow or wedged dashboard is `{ok:false, reason:"timeout"}`, not a stuck
+ * hook.
+ */
+import { SESSION_ID_HEADER, resolveBridgeOptions } from "./bridge.js";
+export const PLAN_STATE_SUBCOMMAND = "plan-state";
+export const TURN_STATE_PATH = "/api/plan-sessions/me/turn-state";
+/** How long this one-shot call may take before it counts as a timeout. */
+export const PLAN_STATE_REQUEST_TIMEOUT_MS = 5_000;
+const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${PLAN_STATE_SUBCOMMAND}`;
+function errorCodeOf(body) {
+    return typeof body === "object" && body !== null && typeof body.error === "string"
+        ? body.error
+        : null;
+}
+function isFiniteNumber(v) {
+    return typeof v === "number" && Number.isFinite(v);
+}
+function isCardRef(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        typeof v.id === "string" &&
+        typeof v.title === "string");
+}
+/**
+ * The strict shape check the contract pins (comment 4245): finite counts, a
+ * `plan` with `id` + `name`, and a string `id` + `title` on every
+ * `startable` / `held` entry. `null` on anything short of that — a 200 whose
+ * body does not match is `bad_response`, exactly like a non-2xx.
+ */
+export function parseTurnStateBody(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const b = body;
+    const plan = b.plan;
+    if (typeof plan !== "object" || plan === null)
+        return null;
+    const p = plan;
+    if (!isFiniteNumber(p.id) || typeof p.name !== "string")
+        return null;
+    const counts = b.counts;
+    if (typeof counts !== "object" || counts === null)
+        return null;
+    const c = counts;
+    if (!isFiniteNumber(c.open) || !isFiniteNumber(c.inProgress) || !isFiniteNumber(c.needsYou))
+        return null;
+    if (!Array.isArray(b.startable) || !b.startable.every(isCardRef))
+        return null;
+    if (!Array.isArray(b.held) || !b.held.every(isCardRef))
+        return null;
+    return {
+        plan: { id: p.id, name: p.name },
+        counts: { open: c.open, inProgress: c.inProgress, needsYou: c.needsYou },
+        startable: b.startable,
+        held: b.held,
+    };
+}
+/**
+ * One authenticated GET, with a hard timeout, classified into the output
+ * shape this subcommand always prints — never a throw, never a non-2xx
+ * bubbling past this function.
+ */
+export async function fetchTurnState(options, deps) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.requestTimeoutMs);
+    let status;
+    let text;
+    try {
+        try {
+            const response = await deps.fetch(`${options.dashboardUrl}${TURN_STATE_PATH}`, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${options.token}`,
+                    Accept: "application/json",
+                    [SESSION_ID_HEADER]: options.sessionId,
+                },
+                signal: controller.signal,
+            });
+            status = response.status;
+            text = await response.text();
+        }
+        catch (err) {
+            return { ok: false, reason: controller.signal.aborted ? "timeout" : "request_failed" };
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let body = null;
+    try {
+        body = text === "" ? null : JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: "bad_response" };
+    }
+    // The exact literal the plugin's no-log-spam rule keys on (AC 30672 /
+    // comment 4245) — the dashboard's own 409 error code for an unconnected
+    // session, passed through verbatim rather than renamed.
+    if (status === 409 && errorCodeOf(body) === "session_not_connected") {
+        return { ok: false, reason: "session_not_connected" };
+    }
+    if (status === 401 || status === 403) {
+        return { ok: false, reason: "unauthorized" };
+    }
+    if (status < 200 || status >= 300) {
+        return { ok: false, reason: "http_error" };
+    }
+    const parsed = parseTurnStateBody(body);
+    if (parsed === null) {
+        return { ok: false, reason: "bad_response" };
+    }
+    return { ok: true, ...parsed };
+}
+/** The bin's `plan-state` subcommand, wired to the real process. Always resolves to exit code 0. */
+export async function runPlanStateCommand(argv, env = process.env, 
+/** Test seam: the home the session's connection record is read from. */
+resolveFrom = {}) {
+    const write = (output) => {
+        process.stdout.write(`${JSON.stringify(output)}\n`);
+    };
+    if (argv.length !== 0) {
+        // A malformed invocation is still a "the hook must stay silent" failure,
+        // not a crash — same ok:false/exit-0 contract as every other failure
+        // path here, with the usage line reserved for a human reading stderr.
+        write({ ok: false, reason: "usage" });
+        process.stderr.write(`${USAGE}\n`);
+        return 0;
+    }
+    const sessionId = env.CLAUDE_CODE_SESSION_ID;
+    if (!sessionId) {
+        write({ ok: false, reason: "no_session_id" });
+        process.stderr.write(`${USAGE}\n`);
+        return 0;
+    }
+    let options;
+    try {
+        options = resolveBridgeOptions({ sessionId, resumeIds: [] }, env, resolveFrom);
+    }
+    catch (err) {
+        const start = err;
+        write({ ok: false, reason: start.reason });
+        process.stderr.write(`${start.reason}: ${start.message}. Fix: ${start.fix}.\n`);
+        return 0;
+    }
+    const output = await fetchTurnState(options, {
+        fetch: (input, init) => fetch(input, init),
+        requestTimeoutMs: PLAN_STATE_REQUEST_TIMEOUT_MS,
+    });
+    write(output);
+    return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.79",
+  "version": "0.1.81",
   "description": "Stdio MCP server wrapping danxbot's dashboard /api/issues/* normalized DB-backed HTTP routes for dispatched agents (DX-704 Phase 2).",
   "license": "MIT",
   "type": "module",