@thehammer/danx-dashboard-mcp 0.1.164 → 0.1.165

package/dist/handlers.js

@@ -62,23 +62,11 @@ export async function planConnect(client, args) {
         },
     });
 }
-// ---------------- resource_fields (DX-3426) ----------------
-const RESOURCES_BASE_PATH = "/api/resources";
-/**
- * `GET /api/resources/:resource/fields` — what a field TREE (the `fields`
- * arg on `GET /api/issues/:id`, and any later route built on the same shape)
- * may name for ONE resource: `{resource, description, always, hashes,
- * fields, relations}`. Install-global (no `board` — the failure-category
- * list route is board-less the same way: nothing server-side would read one).
- * Unknown resource → 404 `unknown_resource`.
- */
-export async function resourceFields(client, args) {
-    return client.request({
-        method: "GET",
-        path: `/${encodeURIComponent(args.resource)}/fields`,
-        basePath: RESOURCES_BASE_PATH,
-    });
-}
+// DX-3465 (code-architecture gate finding, at 275f82c0d) — the dedicated
+// `resource_fields` handler (DX-3426) was deleted from here: it was a thin
+// wrapper around `GET /api/resources/:resource/fields`, which `danxbot_api`
+// already reaches with nothing agent-specific in it. See `index.ts`'s own
+// note at the former tool-registration site.
 // ---------------- danxbot_api (DX-3465, PLN-11 R-25) ----------------
 export const DANXBOT_API_METHODS = ["GET", "POST", "PATCH", "PUT", "DELETE"];
 export function isDanxbotApiMethod(value) {

package/dist/http-client.js

@@ -102,7 +102,16 @@ export class DashboardHttpClient {
             for (const [k, v] of Object.entries(extraQuery)) {
                 if (v === undefined || v === null)
                     continue;
-                params.set(k, String(v));
+                // DX-3465 (code-quality gate finding, at 275f82c0d) — a field TREE
+                // (`fields`, and any other tree-shaped route param) arrives here as a
+                // real object/array, not a string; `String(v)` on either produces
+                // the useless literal "[object Object]" (objects) or a comma-joined
+                // list that drops all nesting (arrays). JSON-encode both so the
+                // server's own `fields=` query-string parser (which expects exactly
+                // this shape — see `src/dashboard/...` field-tree route handling)
+                // receives what it can actually parse; a plain scalar still
+                // stringifies the same way it always did.
+                params.set(k, typeof v === "object" ? JSON.stringify(v) : String(v));
             }
         }
         return `${base}${basePath}${cleanPath}?${params.toString()}`;

package/dist/index.js

@@ -23,19 +23,23 @@
  *                            first to find the route for something you need to do.
  *   - danxbot_api_spec       discovers the exact request/response shape of any route
  *                            `danxbot_api` can call, before calling it.
- *   - resource_fields        GET    /api/resources/:resource/fields (DX-3426 — what `fields` may
- *                            name for a resource; install-global, no `board`)
  *   - plan_connect           POST   /api/plan-sessions/me/plan — SESSION-BOUND (kept as a
- *                            dedicated tool; every other plan_* operation goes through
- *                            danxbot_api now)
+ *                            dedicated tool; every plan READ or WRITE operation goes
+ *                            through danxbot_api now, e.g. GET /api/plans/mine or
+ *                            POST /api/plans/mine/records)
  *
- * DX-2683 — THE PLAN TOOLS ARE SESSION-BOUND, and asymmetrically so. Reads
- * may name any plan; WRITES take no plan id at all and act on the plan this
- * session is connected to, resolved server-side from the session id this
- * package forwards on every request. A session therefore cannot modify a plan
- * it is not connected to, whatever id it believes. A write from an
- * unconnected session is refused loudly (`session_not_connected`), never
- * silently dropped and never guessed at.
+ * DX-2683, updated DX-3465 — PLAN WRITES ARE SESSION-BOUND, and
+ * asymmetrically so relative to reads. There is no dedicated plan-write
+ * tool any more (DX-3465 deleted every `plan_add_*`/`plan_update_*`/
+ * `plan_delete_*`/`plan_remove_card`/`plan_rename`/`plan_reorder_*` tool);
+ * a plan write is an ordinary `danxbot_api` call to a `/api/plans/mine/...`
+ * route. Reads may name any plan by id (`/api/plans/:id/...`); a WRITE
+ * route instead takes NO plan id at all and acts on the plan this session
+ * is connected to (`plan_connect`), resolved server-side from the session
+ * id this package forwards on every request. A session therefore cannot
+ * modify a plan it is not connected to, whatever id it believes. A write
+ * from an unconnected session is refused loudly (`session_not_connected`),
+ * never silently dropped and never guessed at.
  *
  * BOARD-ONLY (DX-1171): board is the first-level concept; repo is
  * DERIVED from board server-side, never passed. The package composes the
@@ -79,7 +83,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
-import { planConnect, resourceFields, danxbotApi, danxbotApiList, danxbotApiSpec, attachFile, DANXBOT_API_METHODS, } from "./handlers.js";
+import { planConnect, danxbotApi, danxbotApiList, danxbotApiSpec, attachFile, DANXBOT_API_METHODS, } from "./handlers.js";
 import { registerLifecycleTools, applyLifecycleVisibility, readLifecycleUrlsFromEnv, } from "./lifecycle.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -311,10 +315,14 @@ const boardField = {
         .optional()
         .describe("Board id `<repo>:<slug>`; omit for this dispatch's board. Unknown → 404."),
 };
-// ---------------- resource_fields ----------------
-strictTool("resource_fields", "DX-3426: what a field TREE (the `fields` arg on `GET /api/issues/:id` via `danxbot_api`, and any later tool that takes one) may name for one resource — `{resource, description, always: string[], hashes: string[], fields: [{name, description}], relations: [{name, description, resource, paging?: {default_limit, max_limit, page_field}}]}`. `always`/`hashes` ride every response regardless of `fields` (never request them). A relation's `resource` names what to call this same tool with next, to go one level deeper. Install-global, not board-scoped. `resource: \"issue\"` is the root; unknown resource → 404 `unknown_resource`.", {
-    resource: z.string().min(1).describe('Resource name, e.g. "issue", or a relation\'s own `resource` from a prior call.'),
-}, async (args) => jsonResult(await resourceFields(client, args)));
+// DX-3465 (code-architecture gate finding, at 275f82c0d) — `resource_fields`
+// (DX-3426) was deleted from here: it was a dedicated wrapper around a plain
+// `GET /api/resources/:resource/fields`, which `danxbot_api` already reaches
+// with no agent-specific behavior earning it its own tool (R-25 keeps a
+// dedicated tool only for what's genuinely agent-specific — session binding,
+// local-file reads, dispatch lifecycle). Call
+// `danxbot_api({method:"GET", path:"/api/resources/<resource>/fields"})`
+// instead; the route and its response shape are unchanged.
 // ---------------- danxbot_api (DX-3465, PLN-11 R-25) ----------------
 strictTool("danxbot_api", "Call any dashboard API route your credential may reach. `method` + `path` (a FULL path, e.g. " +
     '"/api/issues/DX-1/transition" — substitute real ids yourself, never a route template with `:id` in it) + ' +
@@ -329,7 +337,24 @@ strictTool("danxbot_api", "Call any dashboard API route your credential may reac
         .min(1)
         .startsWith("/api/")
         .describe('Full path starting with "/api/" — never a route template.'),
-    query: z.record(z.union([z.string(), z.number(), z.boolean(), z.null()])).optional(),
+    // DX-3465 (code-quality gate finding, at 275f82c0d) — a query value may
+    // be a field TREE (a plain object or array, e.g.
+    // `{"description":true,"comments":{"limit":20}}`), not just a scalar —
+    // SERVER_INSTRUCTIONS below says "ALWAYS pass `fields` … a field tree"
+    // and the OpenAPI spec agrees (`fields`'s schema is `{type:"object"}`),
+    // so the schema here must accept what those two tell the caller to
+    // send. `DashboardHttpClient#buildUrl` JSON-encodes an object/array
+    // value into the query string; a scalar serializes as before.
+    query: z
+        .record(z.union([
+        z.string(),
+        z.number(),
+        z.boolean(),
+        z.null(),
+        z.record(z.unknown()),
+        z.array(z.unknown()),
+    ]))
+        .optional(),
     body: z.unknown().optional(),
     ...boardField,
 }, async (args) => jsonResult(await danxbotApi(client, args)));

package/dist/lifecycle.js

@@ -38,7 +38,7 @@
  */
 import { z } from "zod";
 /**
- * The six canonical agent-visible `danxbot_complete` statuses. DX-3394
+ * The five canonical agent-visible `danxbot_complete` statuses. DX-3394
  * problem 1682 / Core Principle 1 — the pre-DX-770 deprecated aliases
  * (`completed`, `agent_blocked`) were already gone; this merge additionally
  * drops the `ready` / `archive` / `review` backward-compat aliases that
@@ -132,8 +132,15 @@ function parseOptionalAbsolutePathArray(field, value) {
  */
 export function registerLifecycleTools(strictTool) {
     // ---------------- danxbot_complete ----------------
-    // Always visible — every dispatch, of every kind, ends with this call.
-    strictTool("danxbot_complete", "Finalize the current dispatch. Releases the worker's per-dispatch scope and ends the dispatch row. " +
+    // DX-3465 (code-quality gate finding, at 275f82c0d) — this tool used to be
+    // unconditionally visible on the theory that "every dispatch ends with
+    // it", but an OPERATOR session is not a dispatch: it has no
+    // DANXBOT_STOP_URL, so `danxbot_complete` was always advertised there and
+    // every call threw. It is now gated on the stop URL exactly like every
+    // other lifecycle tool below (`applyLifecycleVisibility`) — a real
+    // dispatch always has the URL, so nothing is lost there; an operator
+    // session simply never sees a tool it could never successfully call.
+    const danxbotComplete = strictTool("danxbot_complete", "Finalize the current dispatch. Releases the worker's per-dispatch scope and ends the dispatch row. " +
         "Does NOT move any card — if you're working an issue-bound dispatch and want the card to move " +
         "(Done / Blocked / Cancelled / etc.), transition the card FIRST through danxbot_api " +
         "({method:'POST', path:'/api/issues/:id/transition', body:{action:...}}), then call this tool. " +
@@ -409,6 +416,7 @@ export function registerLifecycleTools(strictTool) {
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
     });
     return {
+        danxbotComplete,
         slackReply,
         slackPostUpdate,
         linkThreadToIssue,
@@ -424,8 +432,11 @@ export function registerLifecycleTools(strictTool) {
 /**
  * Disable every conditionally-visible lifecycle tool whose URL is absent
  * from `urls` — the same advertise-filter contract `buildActiveTools` used
- * to enforce in the old standalone server. `danxbot_complete` is never in
- * this map — it is unconditionally visible (every dispatch ends with it).
+ * to enforce in the old standalone server. `danxbot_complete` (DX-3465,
+ * code-quality gate finding, at 275f82c0d) is gated on `urls.stop` the same
+ * way — a real dispatch always carries `DANXBOT_STOP_URL`, so it stays
+ * visible there; an operator session (no stop URL) never advertises a tool
+ * it could never successfully call.
  */
 export function applyLifecycleVisibility(tools, urls) {
     const setVisible = (tool, visible) => {
@@ -434,6 +445,7 @@ export function applyLifecycleVisibility(tools, urls) {
         else
             tool.disable();
     };
+    setVisible(tools.danxbotComplete, !!urls.stop);
     setVisible(tools.slackReply, !!urls.slackReply);
     setVisible(tools.slackPostUpdate, !!urls.slackUpdate);
     setVisible(tools.linkThreadToIssue, !!urls.linkThreadToIssue);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.164",
-  "description": "Stdio MCP server wrapping danxbot's dashboard /api/issues/* normalized DB-backed HTTP routes for dispatched agents (DX-704 Phase 2).",
+  "version": "0.1.165",
+  "description": "Stdio MCP server fronting danxbot's dashboard API for agents (operator sessions and dispatched workers alike): the generic danxbot_api/danxbot_api_list/danxbot_api_spec tools reach any route the caller's credential may call, plus dedicated agent-specific tools (plan_connect, danxbot_complete, and other per-dispatch lifecycle callbacks) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",

package/dist/entrypoint.test.js

@@ -1,43 +0,0 @@
-import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import { mkdtempSync, writeFileSync, symlinkSync, rmSync, realpathSync, } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
-import { isEntrypointModule } from "./entrypoint.js";
-describe("isEntrypointModule (DX-1647)", () => {
-    let dir;
-    let real;
-    let link;
-    beforeAll(() => {
-        dir = mkdtempSync(join(tmpdir(), "entrypoint-test-"));
-        real = join(dir, "index.js");
-        writeFileSync(real, "// stub entry\n");
-        link = join(dir, "danx-dashboard-mcp"); // mimics node_modules/.bin symlink
-        symlinkSync(real, link);
-    });
-    afterAll(() => {
-        rmSync(dir, { recursive: true, force: true });
-    });
-    // import.meta.url always reports the module REALPATH — model that here.
-    const moduleUrl = () => pathToFileURL(realpathSync(real)).href;
-    it("true when argv[1] is the real file (direct `node index.js`)", () => {
-        expect(isEntrypointModule(moduleUrl(), real)).toBe(true);
-    });
-    it("true when argv[1] is a SYMLINK to the file (npx / global bin) — the fleet regression", () => {
-        // The symlink path !== the realpath, but the entrypoint MUST still be
-        // detected, or npx imports the module and exits without booting the server.
-        expect(link).not.toBe(realpathSync(link));
-        expect(isEntrypointModule(moduleUrl(), link)).toBe(true);
-    });
-    it("false when argv[1] is undefined (module imported, not run as bin)", () => {
-        expect(isEntrypointModule(moduleUrl(), undefined)).toBe(false);
-    });
-    it("false when argv[1] is an empty string", () => {
-        expect(isEntrypointModule(moduleUrl(), "")).toBe(false);
-    });
-    it("false when argv[1] points at a different real file", () => {
-        const other = join(dir, "other.js");
-        writeFileSync(other, "// other\n");
-        expect(isEntrypointModule(moduleUrl(), other)).toBe(false);
-    });
-});

package/dist/mantra.js

@@ -1,128 +0,0 @@
-/**
- * `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;
-}