@thehammer/danx-dashboard-mcp 0.1.134 → 0.1.138

package/README.md

@@ -26,7 +26,7 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | `issue_create` | `POST /api/issues` | Epic REQUIRES non-empty `phase_children[]` (atomic insert). `title` = short domain-naming label; `summary` = 1–3 plain-language sentences, always shown; `description` = the collapsed "Context" body. Root and every phase child take their own `summary` |
 | `issue_edit` | `PATCH /api/issues/:id/edit` | Prose + structured keys (`title`, `summary` (null clears), `description`, `ac`, `checklists`, `effort_level`, `parent_id`, `priority`, `list_id`); semantic keys refused with 400 + pointer to dedicated handler. `priority` (DX-1532) takes a tier word (`low`/`high`/…) or a number in `[0,6)` — the ONLY way to set the numeric column the Trello label + dashboard badge read; never set priority via description prose |
 | `issue_transition` | `POST /api/issues/:id/transition` | Actions: ready, pickup, rollback_pickup, complete, cancel, block, unblock, archive, reopen. `block` is a dispatch hold only — it never marks the card as needing a human; use `issue_problem` add for that |
-| `issue_problem` | `GET/POST/PATCH/DELETE /api/issues/:id/problems[/:pid]` | Actions list / add / edit / remove. A problem is one statement the operator must resolve (a question or a plan flaw) with its own solutions and answers; `add` takes `statement` + optional `solutions[]` in one transaction and IS what puts the card in front of a human (`open_problem_count > 0`) — a successful add also returns `problems_reminder: {open_problem_count, instruction}`. Edit + remove are hash-guarded (`base_hash`, 409 `stale_problem`); removing the card's last open problem is always allowed — it just means the card no longer needs a human |
+| `issue_problem` | `GET/POST/PATCH/DELETE /api/issues/:id/problems[/:pid]` | Actions list / add / edit / remove. A problem is one statement the operator must resolve (a question or a plan flaw) with its own solutions and answers; `add` takes `statement` + optional `solutions[]` in one transaction and IS what puts the card in front of a human (`open_problem_count > 0`) — a successful add also returns a `reminders: [{key, text}]` array (DX-3365 — the reminder registry's middleware, DB-driven and operator-overridable from the dashboard). Edit + remove are hash-guarded (`base_hash`, 409 `stale_problem`); removing the card's last open problem is always allowed — it just means the card no longer needs a human |
 | `issue_solution` | `POST/PATCH/DELETE /api/issues/:id/problems/:pid/solutions[/:sid]` | Actions add / edit / remove, `problem_id` required (list via `issue_problem list`). Edit + remove are hash-guarded (`base_hash`, 409 `stale_solution` with the current row); at most one live `recommended` per problem; a chosen option cannot be edited. No answer action on any tool — the operator answers in the dashboard |
 | `issue_triage` | `POST /api/issues/:id/triage` | Send `{confidence, reason}` — an integer 0-5 score; the server computes the verdict (approve/cancel/keep/defer) against the board's configured thresholds (DX-2086). `keep`/`defer` now block the card. None of these are a cross-card ordering gate; use `issue_dependency` to sequence cards |
 | `issue_comment` | `POST/PATCH/DELETE /api/issues/:id/comments[/:cid]` | Author server-stamped, soft-delete preserved |

package/dist/background-work.js

@@ -0,0 +1,156 @@
+/**
+ * `danx-dashboard-mcp background-work <count|clear>` — the ONE-SHOT client of
+ * `PUT /api/plan-sessions/me/background-work` (DX-3367).
+ *
+ * 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.
+ *
+ * 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
+ * this file):
+ *   - print EXACTLY ONE JSON line on stdout, and ALWAYS exit 0 — success or
+ *     failure alike, because a hook must stay silent rather than spam the
+ *     session's own turn with a stack trace;
+ *   - a session with no connection record (never `plan_connect`-ed, e.g. an
+ *     operator session that never joined a plan) is a silent, expected
+ *     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;
+ *   - human-readable diagnostics go to stderr only, never stdout.
+ *
+ * THE CREDENTIAL — the SAME resolver `bridge` and `plan-state` use, via
+ * `resolveBridgeOptions` (`bridge.ts`): the dashboard URL, credential
+ * source, and credential 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 identical DX-2862 reasoning `plan-state.ts` already gives for itself.
+ *
+ * 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.
+ */
+import { SESSION_ID_HEADER, resolveBridgeOptions } from "./bridge.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. */
+export const BACKGROUND_WORK_REQUEST_TIMEOUT_MS = 5_000;
+const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${BACKGROUND_WORK_SUBCOMMAND} <non-negative-integer|clear>`;
+/**
+ * Parse the ONE positional argument: `clear`, or a non-negative integer
+ * string. Anything else is a usage error — never guessed or floored.
+ */
+export function parseCountArg(raw) {
+    if (raw === "clear")
+        return null;
+    if (!/^\d+$/.test(raw))
+        return { error: `count must be "clear" or a non-negative integer, got "${raw}"` };
+    return Number.parseInt(raw, 10);
+}
+/**
+ * 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.
+ */
+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" };
+    }
+    if (status === 401 || status === 403) {
+        return { ok: false, reason: "unauthorized" };
+    }
+    if (status < 200 || status >= 300) {
+        return { ok: false, reason: "http_error" };
+    }
+    if (typeof body !== "object" ||
+        body === null ||
+        !("count" in body) ||
+        (body.count !== null && typeof body.count !== "number")) {
+        return { ok: false, reason: "bad_response" };
+    }
+    return { ok: true, count: body.count };
+}
+/** The bin's `background-work` subcommand, wired to the real process. Always resolves to exit code 0. */
+export async function runBackgroundWorkCommand(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 !== 1) {
+        write({ ok: false, reason: "usage" });
+        process.stderr.write(`${USAGE}\n`);
+        return 0;
+    }
+    const parsed = parseCountArg(argv[0]);
+    if (typeof parsed === "object" && parsed !== null && "error" in parsed) {
+        write({ ok: false, reason: "usage" });
+        process.stderr.write(`${parsed.error}\n${USAGE}\n`);
+        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;
+        // 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`);
+        return 0;
+    }
+    const output = await putBackgroundWork(options, count, {
+        fetch: (input, init) => fetch(input, init),
+        requestTimeoutMs: BACKGROUND_WORK_REQUEST_TIMEOUT_MS,
+    });
+    write(output);
+    return 0;
+}

package/dist/index.js

@@ -96,6 +96,8 @@
 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";
@@ -1180,9 +1182,27 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             process.exit(0);
         });
     }
+    else if (subcommand === BACKGROUND_WORK_SUBCOMMAND) {
+        runBackgroundWorkCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[danx-dashboard-mcp] background-work fatal: ${err.message}`);
+            process.stdout.write(`${JSON.stringify({ ok: false, reason: "fatal" })}\n`);
+            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}" and "${PLAN_STATE_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.134",
+  "version": "0.1.138",
   "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",