@thehammer/danx-dashboard-mcp 0.1.139 → 0.1.140

package/dist/index.js

@@ -97,6 +97,7 @@ import { isEntrypointModule } from "./entrypoint.js";
 import { BRIDGE_SUBCOMMAND, runBridgeCommand } from "./bridge.js";
 import { PLAN_STATE_SUBCOMMAND, runPlanStateCommand } from "./plan-state.js";
 import { BACKGROUND_WORK_SUBCOMMAND, runBackgroundWorkCommand } from "./background-work.js";
+import { MANTRA_SUBCOMMAND, runMantraCommand } from "./mantra.js";
 import { resolveDeclaredCredential } from "./credential.js";
 import { recordSessionConnectionAfterConnect } from "./session-connection.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -1188,9 +1189,20 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             process.exit(0);
         });
     }
+    else if (subcommand === MANTRA_SUBCOMMAND) {
+        // DX-3366 — unlike plan-state/background-work, a rejection here is a
+        // genuine fatal (never expected: runMantraCommand itself already
+        // classifies every network/shape failure into its own {ok:false} exit
+        // 1), so it exits 1 too rather than the "always 0, stay silent" contract
+        // those two hook-only subcommands use.
+        runMantraCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[danx-dashboard-mcp] mantra fatal: ${err.message}`);
+            process.exit(1);
+        });
+    }
     else if (subcommand !== undefined) {
         console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only ones are ` +
-            `"${BRIDGE_SUBCOMMAND}", "${PLAN_STATE_SUBCOMMAND}", and "${BACKGROUND_WORK_SUBCOMMAND}")`);
+            `"${BRIDGE_SUBCOMMAND}", "${PLAN_STATE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", and "${MANTRA_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

package/dist/mantra.js

@@ -0,0 +1,128 @@
+/**
+ * `danx-dashboard-mcp mantra` — the ONE-SHOT client of
+ * `GET /api/reminders/mantra.session_start` (DX-3366).
+ *
+ * WHO RUNS IT. The claude-plugins `danxbot` plugin's `mantra.sh` SessionStart
+ * hook, via the SAME `npx -y @thehammer/danx-dashboard-mcp@<pin>` path the
+ * plugin's other dashboard calls already use (`plan-state`, `bridge`) — never
+ * a separate install, never a deep import of this package's `dist/`
+ * internals.
+ *
+ * THE CREDENTIAL — the SAME resolver `bridge` / `plan-state` use
+ * (`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. The
+ * mantra is only ever fetched once a session is already connected (`mantra.sh`
+ * checks that first via `plan-connection.mjs` and stays with the short nudge
+ * otherwise), so a connection record always exists by the time this runs.
+ *
+ * THE CONTRACT — unlike `plan-state` (which must stay silent for a hook, so it
+ * always exits 0), this subcommand's caller (`mantra.sh`) needs to tell
+ * success from failure so it can fall back to the git-committed `mantra.md` +
+ * a one-line notice (DX-3366 AC: "Dashboard unreachable → the hook prints the
+ * committed file and says so in one line; never silently"). So:
+ *
+ *   - success: the reminder's EFFECTIVE text (`override_text ?? default_text`)
+ *     on stdout, nothing else, exit 0.
+ *   - failure (missing env, no connection record, network error, timeout,
+ *     non-2xx, 404, bad shape): NOTHING on stdout, one short reason on
+ *     stderr, exit 1. `mantra.sh` is the one that decides what to print for
+ *     a human — this module only reports whether the fetch worked.
+ *
+ * A HARD TIMEOUT (mirrors `plan-state.ts`) — a SessionStart hook must never
+ * hang on a wedged dashboard.
+ */
+import { SESSION_ID_HEADER, resolveBridgeOptions } from "./bridge.js";
+export const MANTRA_SUBCOMMAND = "mantra";
+export const MANTRA_REMINDER_KEY = "mantra.session_start";
+export const MANTRA_REQUEST_TIMEOUT_MS = 5_000;
+const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${MANTRA_SUBCOMMAND}`;
+function reminderPath(key) {
+    return `/api/reminders/${encodeURIComponent(key)}`;
+}
+/** One authenticated GET, with a hard timeout — never throws, never bubbles a non-2xx. */
+export async function fetchMantraText(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}${reminderPath(MANTRA_REMINDER_KEY)}`, {
+                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 {
+            return { ok: false, reason: controller.signal.aborted ? "timeout" : "request_failed" };
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (status === 401 || status === 403)
+        return { ok: false, reason: "unauthorized" };
+    if (status === 404)
+        return { ok: false, reason: "not_found" };
+    if (status < 200 || status >= 300)
+        return { ok: false, reason: "http_error" };
+    let body;
+    try {
+        body = text === "" ? null : JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: "bad_response" };
+    }
+    const effectiveText = typeof body === "object" && body !== null && typeof body.effective_text === "string"
+        ? body.effective_text
+        : null;
+    if (effectiveText === null)
+        return { ok: false, reason: "bad_response" };
+    return { ok: true, text: effectiveText };
+}
+/**
+ * The bin's `mantra` subcommand, wired to the real process. Success prints
+ * the effective text on stdout and returns 0; every failure prints nothing on
+ * stdout, one reason on stderr, and returns 1 — `mantra.sh` reads the exit
+ * code, never parses stdout to guess.
+ */
+export async function runMantraCommand(argv, env = process.env, 
+/** Test seam: the home the session's connection record is read from. */
+resolveFrom = {}) {
+    if (argv.length !== 0) {
+        process.stderr.write(`unrecognized arguments\n${USAGE}\n`);
+        return 1;
+    }
+    const sessionId = env.CLAUDE_CODE_SESSION_ID;
+    if (!sessionId) {
+        process.stderr.write(`no_session_id: CLAUDE_CODE_SESSION_ID is not set\n${USAGE}\n`);
+        return 1;
+    }
+    let options;
+    try {
+        options = resolveBridgeOptions({ sessionId, resumeIds: [] }, env, resolveFrom);
+    }
+    catch (err) {
+        const start = err;
+        process.stderr.write(`${start.reason}: ${start.message}. Fix: ${start.fix}.\n`);
+        return 1;
+    }
+    const output = await fetchMantraText(options, {
+        fetch: (input, init) => fetch(input, init),
+        requestTimeoutMs: MANTRA_REQUEST_TIMEOUT_MS,
+    });
+    if (!output.ok) {
+        process.stderr.write(`${output.reason}: could not fetch the effective mantra text from the dashboard\n`);
+        return 1;
+    }
+    process.stdout.write(output.text);
+    return 0;
+}

package/package.json

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