@thehammer/danx-dashboard-mcp 0.1.136 → 0.1.139

package/dist/background-work.js

@@ -4,13 +4,19 @@
  *
  * WHO RUNS IT. The danxbot Claude Code plugin's `Stop` / `SubagentStop` /
  * `SessionStart` / `StopFailure` hooks (`danxbot/hooks/hooks.json` in
- * claude-plugins), via the SAME `npx -y @thehammer/danx-dashboard-mcp` pin
- * the plugin already uses for `bridge` and `plan-state` — no separate
- * install, no deep import of this package's `dist/` internals. The plugin
- * decides WHAT to report (parsing `Stop`/`SubagentStop`'s own
- * `background_tasks` snapshot, counting only `shell` / `subagent` /
- * `workflow` entries, sending `clear` on `SessionStart`/`StopFailure`); this
- * module only delivers the report.
+ * claude-plugins), via the SAME `npx -y @thehammer/danx-dashboard-mcp`
+ * MECHANISM the plugin already uses for `bridge` and `plan-state` — no
+ * separate install, no deep import of this package's `dist/` internals.
+ * DX-3367 fix-up — that does NOT mean the SAME PINNED VERSION: `npx -y
+ * <pkg>` resolves whatever version string that ONE hook's own invocation
+ * names, and this plugin's hooks pin each call independently (verified
+ * against production drift, comment 7102 on the card: the background-work
+ * hooks pinned `0.1.136` while `bridge` was still pinned `0.1.95`) — a
+ * version bump to one hook's pin never moves the others. The plugin decides
+ * WHAT to report (parsing `Stop`/`SubagentStop`'s own `background_tasks`
+ * snapshot, counting only `shell` / `subagent` / `workflow` entries,
+ * sending `clear` on `SessionStart`/`StopFailure`); this module only
+ * delivers the report.
  *
  * THE CONTRACT, mirroring `plan-state.ts`'s (binding the same way, so a
  * future plugin build against this module can trust it without re-reading
@@ -23,8 +29,10 @@
  *     no-op — `{"ok":false,"reason":"no_connection_record"}` — the plugin
  *     hook simply does not forward anything further in this case, exactly
  *     what "no-op when the session isn't plan-connected" means in practice;
- *   - on success, `{"ok":true,"count":<number|null>}` echoes what was
- *     stored;
+ *   - on success, `{"ok":true,"count":<number|null>}` echoes the `count`
+ *     that was SUBMITTED for storage, not a re-read of the row — see
+ *     `recordBackgroundWork`'s own doc (`db/plan-session-background-work.ts`)
+ *     for why a plain no-op write is indistinguishable from a real one here;
  *   - human-readable diagnostics go to stderr only, never stdout.
  *
  * THE CREDENTIAL — the SAME resolver `bridge` and `plan-state` use, via
@@ -37,8 +45,13 @@
  * A HARD TIMEOUT — `BACKGROUND_WORK_REQUEST_TIMEOUT_MS`. A `Stop` hook
  * blocks the session's turn boundary, so this call must never hang: a slow
  * or wedged dashboard is `{ok:false, reason:"timeout"}`, not a stuck hook.
+ *
+ * THE REQUEST/RUN SCAFFOLDING IS SHARED WITH `plan-state.ts`
+ * (`one-shot-session-request.ts`, DX-3367 fix-up) — the two subcommands no
+ * longer maintain independent copies of the authenticated-fetch-with-
+ * timeout logic or the session/credential resolution boilerplate.
  */
-import { SESSION_ID_HEADER, resolveBridgeOptions } from "./bridge.js";
+import { resolveSessionOptions, sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
 export const BACKGROUND_WORK_SUBCOMMAND = "background-work";
 export const BACKGROUND_WORK_PATH = "/api/plan-sessions/me/background-work";
 /** How long this one-shot call may take before it counts as a timeout. */
@@ -59,48 +72,30 @@ export function parseCountArg(raw) {
  * One authenticated PUT, with a hard timeout, classified into the output
  * shape this subcommand always prints — never a throw, never a non-2xx
  * bubbling past this function.
+ *
+ * DX-3367 fix-up — STATUS IS CHECKED BEFORE THE BODY IS EVER PARSED. A 5xx
+ * (or any other non-2xx) response can carry an HTML error page instead of
+ * JSON; parsing first would misreport that as `bad_response` when the true
+ * classification is `http_error`. Unlike `plan-state.ts`'s `fetchTurnState`,
+ * this subcommand has no status that needs the BODY inspected to classify
+ * (no `409 session_not_connected` equivalent), so status alone decides
+ * whether a body read is even attempted.
  */
 export async function putBackgroundWork(options, count, 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}${BACKGROUND_WORK_PATH}`, {
-                method: "PUT",
-                headers: {
-                    Authorization: `Bearer ${options.token}`,
-                    Accept: "application/json",
-                    "Content-Type": "application/json",
-                    [SESSION_ID_HEADER]: options.sessionId,
-                },
-                body: JSON.stringify({ count }),
-                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" };
-    }
+    const sent = await sendSessionRequest(options, BACKGROUND_WORK_PATH, { method: "PUT", body: JSON.stringify({ count }) }, deps);
+    if ("reason" in sent)
+        return sent;
+    const { status, text } = sent;
     if (status === 401 || status === 403) {
         return { ok: false, reason: "unauthorized" };
     }
     if (status < 200 || status >= 300) {
         return { ok: false, reason: "http_error" };
     }
+    const parsed = tryParseJsonBody(text);
+    if (!parsed.ok)
+        return { ok: false, reason: "bad_response" };
+    const body = parsed.body;
     if (typeof body !== "object" ||
         body === null ||
         !("count" in body) ||
@@ -128,26 +123,16 @@ resolveFrom = {}) {
         return 0;
     }
     const count = parsed;
-    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;
+    const resolved = await resolveSessionOptions(env, resolveFrom, USAGE);
+    if (!resolved.ok) {
         // A session that never `plan_connect`-ed has no connection record — this
         // is the ORDINARY "not plan-connected" case, not an error the plugin
         // should surface: it simply forwards nothing further this turn.
-        write({ ok: false, reason: start.reason });
-        process.stderr.write(`${start.reason}: ${start.message}. Fix: ${start.fix}.\n`);
+        write(resolved.output);
+        process.stderr.write(`${resolved.detail}\n`);
         return 0;
     }
-    const output = await putBackgroundWork(options, count, {
+    const output = await putBackgroundWork(resolved.options, count, {
         fetch: (input, init) => fetch(input, init),
         requestTimeoutMs: BACKGROUND_WORK_REQUEST_TIMEOUT_MS,
     });

package/dist/one-shot-session-request.js

@@ -0,0 +1,104 @@
+/**
+ * DX-3367 fix-up — shared scaffolding for a "one-shot session request"
+ * subcommand: `plan-state` (`GET /api/plan-sessions/me/turn-state`) and
+ * `background-work` (`PUT /api/plan-sessions/me/background-work`) each
+ * duplicated this exact shape independently (`fetchTurnState` /
+ * `putBackgroundWork`, `runPlanStateCommand` / `runBackgroundWorkCommand`).
+ * This module is the ONE place that shape lives now; a future one-shot
+ * subcommand extends it instead of copying either file again.
+ *
+ * Two pieces, matching the two duplicated concerns:
+ *   - `sendSessionRequest` — the authenticated HTTP call itself: bearer +
+ *     session header, a hard abort-timeout, and network-level failure
+ *     classification (`timeout` / `request_failed`). Returns the raw
+ *     `{status, text}` UNPARSED — each caller decides for itself which
+ *     statuses need the body inspected (e.g. `plan-state`'s 409
+ *     `session_not_connected`) and which don't, so a non-2xx status with an
+ *     unparseable (e.g. HTML) body is classified from the status alone
+ *     rather than colliding with "the JSON didn't parse" (`bad_response`).
+ *   - `resolveSessionOptions` — session-id + credential resolution via
+ *     `resolveBridgeOptions`, with `BridgeStartError` narrowed by
+ *     `instanceof` rather than an unchecked `as BridgeStartError` cast, so
+ *     an error of some OTHER shape (a bug in the resolver, a thrown
+ *     non-Error) still comes back as a reported reason instead of a value
+ *     whose `.reason`/`.message`/`.fix` fields are silently `undefined`.
+ */
+import { SESSION_ID_HEADER, resolveBridgeOptions, BridgeStartError } from "./bridge.js";
+/**
+ * One authenticated HTTP call to this session's dashboard, with a hard
+ * timeout. Never throws — a network failure or an abort is reported as
+ * `OneShotFailure`, exactly like any other classified failure the caller
+ * might produce from the status/body it gets back on success.
+ */
+export async function sendSessionRequest(options, path, init, deps) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.requestTimeoutMs);
+    try {
+        try {
+            const response = await deps.fetch(`${options.dashboardUrl}${path}`, {
+                method: init.method,
+                headers: {
+                    Authorization: `Bearer ${options.token}`,
+                    Accept: "application/json",
+                    ...(init.body !== undefined ? { "Content-Type": "application/json" } : {}),
+                    [SESSION_ID_HEADER]: options.sessionId,
+                },
+                body: init.body,
+                signal: controller.signal,
+            });
+            const text = await response.text();
+            return { status: response.status, text };
+        }
+        catch {
+            // DX-3367 fix-up — the caught value is never inspected (an aborted
+            // fetch's own rejection shape varies by runtime), so binding it to a
+            // name the code never reads was dead weight the linter never caught.
+            return { ok: false, reason: controller.signal.aborted ? "timeout" : "request_failed" };
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** `JSON.parse`, classified rather than thrown — the ONE shared parse point
+ *  every caller uses once it has decided (from `status`) that the body is
+ *  worth reading at all. */
+export function tryParseJsonBody(text) {
+    try {
+        return { ok: true, body: text === "" ? null : JSON.parse(text) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/**
+ * Resolve this process's session id + dashboard credential, the identical
+ * first step every one-shot subcommand's `runXCommand` takes before it can
+ * make its own request. `detail` is the stderr-only human-readable line the
+ * caller prints alongside `output` — never part of the stdout JSON contract.
+ */
+export async function resolveSessionOptions(env, resolveFrom, usage) {
+    const sessionId = env.CLAUDE_CODE_SESSION_ID;
+    if (!sessionId) {
+        return { ok: false, output: { ok: false, reason: "no_session_id" }, detail: usage };
+    }
+    try {
+        const options = resolveBridgeOptions({ sessionId, resumeIds: [] }, env, resolveFrom);
+        return { ok: true, options };
+    }
+    catch (err) {
+        // DX-3367 fix-up — `instanceof`, never an unchecked `as BridgeStartError`
+        // cast: `resolveBridgeOptions` throws exactly `BridgeStartError` today,
+        // but a cast reports a fabricated reason/message/fix (all `undefined`)
+        // for any OTHER thrown shape instead of a real one, silently.
+        if (err instanceof BridgeStartError) {
+            return {
+                ok: false,
+                output: { ok: false, reason: err.reason },
+                detail: `${err.reason}: ${err.message}. Fix: ${err.fix}.`,
+            };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, output: { ok: false, reason: "start_failed" }, detail: `start_failed: ${message}` };
+    }
+}

package/dist/plan-state.js

@@ -44,8 +44,11 @@
  * 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.
+ *
+ * THE REQUEST/RUN SCAFFOLDING IS SHARED WITH `background-work.ts`
+ * (`one-shot-session-request.ts`, DX-3367 fix-up).
  */
-import { SESSION_ID_HEADER, resolveBridgeOptions } from "./bridge.js";
+import { resolveSessionOptions, sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.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. */
@@ -102,45 +105,29 @@ export function parseTurnStateBody(body) {
  * 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.
+ *
+ * DX-3367 fix-up — status is checked BEFORE the body is parsed, except for
+ * the ONE status (`409`) whose classification genuinely depends on the body
+ * (`session_not_connected`). Any other non-2xx — including a 5xx that comes
+ * back as an HTML error page instead of JSON — is `http_error` without ever
+ * attempting to parse it, so a body-parse failure on those statuses can
+ * never be misreported as `bad_response`.
  */
 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();
+    const sent = await sendSessionRequest(options, TURN_STATE_PATH, { method: "GET" }, deps);
+    if ("reason" in sent)
+        return sent;
+    const { status, text } = sent;
+    if (status === 409) {
+        // 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. A 409 whose body
+        // does NOT carry that code falls through to the ordinary `http_error`
+        // classification below, same as any other non-2xx.
+        const parsed409 = tryParseJsonBody(text);
+        if (parsed409.ok && errorCodeOf(parsed409.body) === "session_not_connected") {
+            return { ok: false, reason: "session_not_connected" };
         }
-        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" };
@@ -148,11 +135,14 @@ export async function fetchTurnState(options, deps) {
     if (status < 200 || status >= 300) {
         return { ok: false, reason: "http_error" };
     }
-    const parsed = parseTurnStateBody(body);
-    if (parsed === null) {
+    const parsed = tryParseJsonBody(text);
+    if (!parsed.ok)
+        return { ok: false, reason: "bad_response" };
+    const turnState = parseTurnStateBody(parsed.body);
+    if (turnState === null) {
         return { ok: false, reason: "bad_response" };
     }
-    return { ok: true, ...parsed };
+    return { ok: true, ...turnState };
 }
 /** 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, 
@@ -169,23 +159,13 @@ resolveFrom = {}) {
         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`);
+    const resolved = await resolveSessionOptions(env, resolveFrom, USAGE);
+    if (!resolved.ok) {
+        write(resolved.output);
+        process.stderr.write(`${resolved.detail}\n`);
         return 0;
     }
-    const output = await fetchTurnState(options, {
+    const output = await fetchTurnState(resolved.options, {
         fetch: (input, init) => fetch(input, init),
         requestTimeoutMs: PLAN_STATE_REQUEST_TIMEOUT_MS,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.136",
+  "version": "0.1.139",
   "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",