@thehammer/danx-dashboard-mcp 0.1.92 → 0.1.93

package/dist/bridge.js

@@ -42,9 +42,15 @@
  *   5. Streams through `runListener` (`listen.ts`), which reconnects within the
  *      ticket, and re-mints when that ticket's lease runs out or a fresh ticket
  *      is refused once.
- *   6. Writes JSON Lines to stdout: ONE `{type:"ready"}` once a ticket has been
- *      minted and streaming is about to start, `{type:"event", id, text}` per
- *      event, and ONE final `{type:"stopped", reason, detail, fix}` before exiting.
+ *   6. Writes JSON Lines to stdout: ONE `{type:"ready", boards, cardCount, degraded}`
+ *      once a ticket has been minted and streaming is about to start —
+ *      DX-2970's `fetchPlanInventory`, a single BEST-EFFORT (never a gate)
+ *      read of the connected plan's real board/card counts, purely so a
+ *      consumer can tell "healthy, connected plan has cards" apart from
+ *      "degraded — the connected plan has no cards, or its inventory
+ *      couldn't be read" instead of both reading as an absent/empty field —
+ *      then `{type:"event", id, text}` per event, and ONE final
+ *      `{type:"stopped", reason, detail, fix}` before exiting.
  *
  * TERMINAL OUTCOMES — each ends the process with its stop record, never a retry:
  *   - `no_connection_record`  this session has no connection record to read;
@@ -156,6 +162,12 @@ function formatDigest(entries) {
 }
 export const BRIDGE_SUBCOMMAND = "bridge";
 export const STREAM_TICKET_PATH = "/api/plan-sessions/me/stream-ticket";
+// DX-2970 — the bare (no `fields=`) cheap-scalars read, used ONLY to report the
+// connected plan's real `boards`/`cardCount` on the `ready` record (see
+// `fetchPlanInventory`). This is NOT a revival of DX-2920's deleted
+// `verifyPlanBoardsReadable` gate — it never refuses a mint, never blocks
+// streaming, and is best-effort (one attempt, no retry/backoff).
+export const PLAN_MINE_PATH = "/api/plans/mine";
 export const SESSION_ID_HEADER = "x-danx-session-id";
 /** How long one dashboard request may take before it counts as a transient failure. */
 export const REQUEST_TIMEOUT_MS = 10_000;
@@ -427,6 +439,44 @@ export async function mintTicket(options, deps) {
         leaseMs: ticket.leaseMs,
     };
 }
+/** What is wrong with a 2xx bare `/api/plans/mine` body, or `null` when it carries a usable inventory. */
+function badInventoryReason(body) {
+    if (typeof body !== "object" || body === null)
+        return "the body is not a JSON object";
+    const b = body;
+    if (!Array.isArray(b.boards) || b.boards.some((x) => typeof x !== "string"))
+        return "boards is not a string array";
+    if (typeof b.cardCount !== "number" || !Number.isSafeInteger(b.cardCount) || b.cardCount < 0) {
+        return "cardCount is not a non-negative integer";
+    }
+    return null;
+}
+/**
+ * DX-2970 — a single BEST-EFFORT read of the connected plan's real
+ * `boards`/`cardCount`, purely for accurate `ready`-record reporting. NEVER a
+ * gate: unlike DX-2920's deleted `verifyPlanBoardsReadable`, a failure here
+ * (network, timeout, non-2xx, unusable body) is NOT retried and NEVER blocks
+ * or delays streaming — `runBridge` reports `degraded: true` with `boards`/
+ * `cardCount` both `null` and proceeds exactly as it would have before this
+ * read existed. The bare (no `fields=`) call is deliberately the cheapest
+ * read the route offers — the plan's own "cheap scalars," always present on
+ * every `GET /api/plans/mine` response regardless of `fields`.
+ */
+export async function fetchPlanInventory(options, deps) {
+    const outcome = await request(options, deps, "plan inventory read", `${options.dashboardUrl}${PLAN_MINE_PATH}`);
+    if (outcome.kind === "transient")
+        return { kind: "unavailable", detail: outcome.detail };
+    const { status, text, body } = outcome;
+    if (status < 200 || status >= 300) {
+        return { kind: "unavailable", detail: `plan inventory read HTTP ${status} ${oneLine(text, 300)}` };
+    }
+    const bad = badInventoryReason(body);
+    if (bad !== null) {
+        return { kind: "unavailable", detail: `plan inventory read HTTP ${status}: ${bad}` };
+    }
+    const b = body;
+    return { kind: "ok", boards: b.boards, cardCount: b.cardCount };
+}
 /**
  * DX-2920 — a stream admission refusal (`listen.ts`'s STRUCTURED `refused`
  * outcome — `{status, errorCode, body}`, parsed once in `connectOnce`) whose
@@ -579,9 +629,24 @@ export async function runBridge(options, deps) {
         // board reach is proven by the dashboard's own mint refusal rather than a
         // client-side check run here (see the module docblock + the deleted
         // `verifyPlanBoardsReadable`). A re-mint (a lapsed lease) never repeats it.
+        // DX-2970 — the inventory read (`fetchPlanInventory`) runs on this SAME
+        // first-mint-only path, for the same reason: it is a property of the
+        // credential and the plan, and a re-mint changes neither. Best-effort —
+        // never gates the `for(;;)` loop, never retried, never delays streaming.
         if (!readyEmitted) {
             readyEmitted = true;
-            deps.write({ type: "ready" });
+            const inventory = await fetchPlanInventory(options, deps);
+            if (inventory.kind === "ok") {
+                deps.write({
+                    type: "ready",
+                    boards: inventory.boards,
+                    cardCount: inventory.cardCount,
+                    degraded: inventory.boards.length === 0 || inventory.cardCount === 0,
+                });
+            }
+            else {
+                deps.write({ type: "ready", boards: null, cardCount: null, degraded: true });
+            }
         }
         backoff = MINT_INITIAL_BACKOFF_MS;
         const run = { stopped: null, emitted: false };

package/dist/handlers.js

@@ -70,6 +70,15 @@ export const LIST_PAGE_MAX_LIMIT = 1000;
  * `__tests__/handlers.test.ts` asserts the two agree.
  */
 export const PLAN_GET_CARDS_DEFAULT_LIMIT = 200;
+/**
+ * DX-3027 — `plan_get`'s `events_limit` default/max — mirrors the server's
+ * `src/issues/plans-routes.ts#PLAN_GET_EVENTS_DEFAULT_LIMIT` /
+ * `PLAN_GET_EVENTS_MAX_LIMIT`. Deliberately smaller than `LIST_PAGE_MAX_LIMIT`
+ * above — an event page is read far more often, and a wide page defeats the
+ * point of a cursor. `__tests__/handlers.test.ts` asserts the two agree.
+ */
+export const PLAN_GET_EVENTS_DEFAULT_LIMIT = 50;
+export const PLAN_GET_EVENTS_MAX_LIMIT = 200;
 /**
  * Fetch one card via `GET /api/issues/:id`, or many via
  * `GET /api/issues/batch?ids=...` (DX-2727) — a real batch read that keeps
@@ -857,7 +866,54 @@ export const PLAN_FIELD_GROUPS = [
     "architecture",
     "sessions",
     "notes",
+    "events",
+];
+/**
+ * DX-3027 — every kind `plan_get`'s `events_kinds` filter accepts. The ONE
+ * copy in this package (the `plan_get` zod enum in `index.ts` reads this
+ * const), duplicated from the server's `src/issues/db/plan-events.ts#PLAN_EVENT_KINDS`
+ * because the published package cannot import server source at runtime.
+ * `__tests__/handlers.test.ts` asserts the two are equal, so drift fails a
+ * test rather than a live call.
+ */
+export const PLAN_EVENT_KINDS = [
+    "comment_added",
+    "solution_answered",
+    "problem_added",
+    "problem_unanswered",
+    "problem_answer_changed",
+    "blocked",
+    "unblocked",
+    "transitioned",
+    "edited",
+    "dependency_added",
+    "dependency_removed",
+    "card_created",
+    "plan_created",
+    "plan_renamed",
+    "card_added_to_plan",
+    "card_removed_from_plan",
+    "record_added",
+    "record_updated",
+    "record_removed",
+    "note_added",
+    "note_updated",
+    "note_removed",
+    "architecture_section_added",
+    "architecture_section_updated",
+    "architecture_section_removed",
+    "architecture_sections_reordered",
+    "session_connected",
+    "session_switched_away",
+    "idle_nudge_sent",
 ];
+/**
+ * DX-3027 — every origin `plan_get`'s `events_origin` filter accepts.
+ * Mirrors the server's `src/issues/db/plan-events.ts#PlanEventOrigin`
+ * (itself `ActivityOrigin`) — same drift protection as `PLAN_EVENT_KINDS`
+ * above.
+ */
+export const PLAN_EVENT_ORIGINS = ["operator", "agent", "machine"];
 /**
  * DX-2834 — the plan-status taxonomy, mirroring `PLAN_FIELD_GROUPS` just
  * above: the ONE copy in this package (the `plan_list` zod enum in
@@ -892,6 +948,17 @@ export async function planGet(client, args = {}) {
         query.cards_offset = args.cards_offset;
     if (args.cards_limit !== undefined)
         query.cards_limit = args.cards_limit;
+    if (args.events_limit !== undefined)
+        query.events_limit = args.events_limit;
+    if (args.events_before !== undefined)
+        query.events_before = args.events_before;
+    if (args.events_kinds !== undefined && args.events_kinds.length > 0) {
+        query.events_kinds = args.events_kinds.join(",");
+    }
+    if (args.events_origin !== undefined)
+        query.events_origin = args.events_origin;
+    if (args.events_writer !== undefined)
+        query.events_writer = args.events_writer;
     return client.request({
         method: "GET",
         path: args.plan_id === undefined ? "/mine" : `/${args.plan_id}/full`,

package/dist/index.js

@@ -101,7 +101,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 { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueProblem, issueQualityGate, issueQualityGateVerdict, issueRetireBranch, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, failureCategoryCreate, failureCategoryList, failureCategoryUpdate, planAddArchitectureSection, planAddCard, planAddNote, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteNote, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, PLAN_STATUSES, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateNote, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
+import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueProblem, issueQualityGate, issueQualityGateVerdict, issueRetireBranch, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, failureCategoryCreate, failureCategoryList, failureCategoryUpdate, planAddArchitectureSection, planAddCard, planAddNote, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteNote, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, PLAN_EVENT_KINDS, PLAN_EVENT_ORIGINS, PLAN_STATUSES, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, PLAN_GET_EVENTS_DEFAULT_LIMIT, PLAN_GET_EVENTS_MAX_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateNote, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -723,7 +723,7 @@ server.tool("plan_list", "List every plan via GET /api/plans (DX-2683), and lear
         .optional()
         .describe("Filter to one computed status: awaiting-session, planning, building, complete. Omit for every plan."),
 }, async (args) => jsonResult(await planList(client, args)));
-server.tool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id` to read ANY plan; OMIT to read the plan this session is connected to — omitting while connected to none fails loud `{error: \"session_not_connected\"}`, connect first. A BARE call (no `fields`) returns ONLY the plan's cheap scalars: `{plan, boards, cardCount, bucketCounts, status, session, sessionListenerAttached, available_field_groups}` — no cards, records, or architecture body. `plan` carries `{id, ref, name, createdAt}`; `ref` is the plan's short reference (`PLN-<id>`) — cite that, not the bare id. `status` (DX-2834) is computed fresh on every read, never stored — see `plan_list` for the four values and what each means. Pass `fields` to opt into: `cards` (member cards, PAGED: `cards_offset` (default 0) and `cards_limit` (1.." + LIST_PAGE_MAX_LIMIT + ", default " + PLAN_GET_CARDS_DEFAULT_LIMIT + ") pick the page, in stable card-reference order (board prefix, then card number — pages never repeat/skip unless membership changes between reads); response carries `cards_total`/`cards_offset` — page while cards_offset + cards.length < cards_total; either paging arg without `fields: [\"cards\"]` is a 400), `records` (every goal+rule+caveat, keyed by kind) or `records:goal` / `records:rule` / `records:caveat` (one kind, cheaper), `architecture` (`{sections: [{id, planId, contentHash, title, content, sortOrder, createdAt, updatedAt}]}`), `sessions` (every session connected to the plan). `session`/`sessionListenerAttached` and `available_field_groups` ride every response regardless. `sessionListenerAttached` is `false` for a few seconds right after `plan_connect` while the plugin's event bridge starts; still `false` after that while connected means the plan's card events are not reaching you — tell the operator. ALWAYS `plan_get`/`plan_get_architecture_section` immediately before `plan_update_architecture_section`/`plan_delete_architecture_section` and pass the returned `contentHash` back as `base_hash`.", {
+server.tool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id` to read ANY plan; OMIT to read the plan this session is connected to — omitting while connected to none fails loud `{error: \"session_not_connected\"}`, connect first. A BARE call (no `fields`) returns ONLY the plan's cheap scalars: `{plan, boards, cardCount, bucketCounts, status, session, sessionListenerAttached, available_field_groups}` — no cards, records, or architecture body. `plan` carries `{id, ref, name, createdAt}`; `ref` is the plan's short reference (`PLN-<id>`) — cite that, not the bare id. `status` (DX-2834) is computed fresh on every read, never stored — see `plan_list` for the four values and what each means. Pass `fields` to opt into: `cards` (member cards, PAGED: `cards_offset` (default 0) and `cards_limit` (1.." + LIST_PAGE_MAX_LIMIT + ", default " + PLAN_GET_CARDS_DEFAULT_LIMIT + ") pick the page, in stable card-reference order (board prefix, then card number — pages never repeat/skip unless membership changes between reads); response carries `cards_total`/`cards_offset` — page while cards_offset + cards.length < cards_total; either paging arg without `fields: [\"cards\"]` is a 400), `records` (every goal+rule+caveat, keyed by kind) or `records:goal` / `records:rule` / `records:caveat` (one kind, cheaper), `architecture` (`{sections: [{id, planId, contentHash, title, content, sortOrder, createdAt, updatedAt}]}`), `sessions` (every session connected to the plan), `events` (DX-2987/DX-3027 — the plan's durable event ledger: every human action and every bridge message recorded on it, cursor-paged newest first via `events_limit` (1.." + PLAN_GET_EVENTS_MAX_LIMIT + ", default " + PLAN_GET_EVENTS_DEFAULT_LIMIT + ") and `events_before` (an opaque cursor — pass a previous page's `next_cursor` to read older; omit for the newest page); filter with `events_kinds` (one or more of " + PLAN_EVENT_KINDS.join(", ") + "), `events_origin` (one of " + PLAN_EVENT_ORIGINS.join(", ") + "), `events_writer` (exact writer name); every `events_*` param without `fields: [\"events\"]` is a 400, same as the `cards_*` params above; response carries `events: {items: [{id, at, kind, writer, origin, originSessionId, targetSessionId, cardId, cardTitle, boardId, detail}], next_cursor}` — `next_cursor` is `null` on the last page; an event on a card whose board you cannot read is left out, plan-level events are always visible). `session`/`sessionListenerAttached` and `available_field_groups` ride every response regardless. `sessionListenerAttached` is `false` for a few seconds right after `plan_connect` while the plugin's event bridge starts; still `false` after that while connected means the plan's card events are not reaching you — tell the operator. ALWAYS `plan_get`/`plan_get_architecture_section` immediately before `plan_update_architecture_section`/`plan_delete_architecture_section` and pass the returned `contentHash` back as `base_hash`.", {
     plan_id: z
         .number()
         .int()
@@ -733,7 +733,7 @@ server.tool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id
     fields: z
         .array(z.enum(PLAN_FIELD_GROUPS))
         .optional()
-        .describe("Opt-in field-GROUPS: cards, records (every kind) or records:goal/records:rule/records:caveat (one kind), architecture, sessions. Absent/empty = cheap scalars only (plan, boards, cardCount, bucketCounts) plus session state."),
+        .describe("Opt-in field-GROUPS: cards, records (every kind) or records:goal/records:rule/records:caveat (one kind), architecture, sessions, notes, events. Absent/empty = cheap scalars only (plan, boards, cardCount, bucketCounts) plus session state."),
     cards_offset: z
         .number()
         .int()
@@ -747,6 +747,31 @@ server.tool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id
         .max(LIST_PAGE_MAX_LIMIT)
         .optional()
         .describe("How many cards one page holds, 1.." + LIST_PAGE_MAX_LIMIT + " (default " + PLAN_GET_CARDS_DEFAULT_LIMIT + "). Requires `fields` to include `cards`."),
+    events_limit: z
+        .number()
+        .int()
+        .positive()
+        .max(PLAN_GET_EVENTS_MAX_LIMIT)
+        .optional()
+        .describe("DX-3027 — how many ledger events one page holds, 1.." + PLAN_GET_EVENTS_MAX_LIMIT + " (default " + PLAN_GET_EVENTS_DEFAULT_LIMIT + "). Requires `fields` to include `events`."),
+    events_before: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("DX-3027 — an opaque cursor from a previous page's `next_cursor`. Omit for the newest page. Requires `fields` to include `events`."),
+    events_kinds: z
+        .array(z.enum(PLAN_EVENT_KINDS))
+        .optional()
+        .describe("DX-3027 — only these event kinds. Omit for every kind. Requires `fields` to include `events`."),
+    events_origin: z
+        .enum(PLAN_EVENT_ORIGINS)
+        .optional()
+        .describe("DX-3027 — only events with this origin. Omit for every origin. Requires `fields` to include `events`."),
+    events_writer: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("DX-3027 — only events with this exact writer name. Omit for every writer. Requires `fields` to include `events`."),
 }, async (args) => jsonResult(await planGet(client, args)));
 server.tool("plan_create", "Create a new, empty plan via POST /api/plans (DX-2531). GLOBAL — a plan is not board-scoped, and this call adds no cards, no records, and no architecture sections; it does NOT connect any session to the new plan (call `plan_connect` separately, exactly as adding a card to a plan is its own separate step). Returns `{ok, status, body: {plan: {id, ref, name, createdAt}}}` — `ref` is the plan's short reference (`PLN-<id>`). Use the returned `plan.id` with `plan_connect` to start working on it, or with `plan_get({plan_id})` to browse it.", {
     name: z.string().min(1).describe("The plan's name — shown in the Plans list."),

package/package.json

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

package/dist/handlers.test.js

@@ -1,51 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { DashboardHttpClient } from "./http-client.js";
-import { issueList, issueTransition } from "./handlers.js";
-/**
- * `issue_list` query-param forwarding. A fake `fetch` captures the built
- * URL so each filter is asserted at the wire, through the real client's
- * URL builder (`?repo=` always stamped, extra query merged after).
- */
-function clientCapturing() {
-    const urls = [];
-    const fetchImpl = (async (url) => {
-        urls.push(url);
-        return new Response(JSON.stringify({ issues: [] }), { status: 200 });
-    });
-    const client = new DashboardHttpClient({ baseUrl: "http://localhost:5555", repo: "danxbot", token: "t" }, fetchImpl);
-    return { client, urls };
-}
-describe("issueList — query forwarding", () => {
-    it("forwards q as the server-side search needle", async () => {
-        const { client, urls } = clientCapturing();
-        await issueList(client, { q: "retire" });
-        expect(urls[0]).toContain("q=retire");
-    });
-    it("omits q when not provided", async () => {
-        const { client, urls } = clientCapturing();
-        await issueList(client, { include_closed: true });
-        expect(urls[0]).not.toContain("q=");
-        expect(urls[0]).toContain("include_closed=true");
-    });
-});
-describe("issueTransition — body forwarding", () => {
-    function clientCapturingBody() {
-        const bodies = [];
-        const fetchImpl = (async (_url, init) => {
-            bodies.push(JSON.parse(String(init?.body ?? "{}")));
-            return new Response(JSON.stringify({ issue: {} }), { status: 200 });
-        });
-        const client = new DashboardHttpClient({ baseUrl: "http://localhost:5555", repo: "danxbot", token: "t" }, fetchImpl);
-        return { client, bodies };
-    }
-    it("forwards manual: true on pickup (DX-946 operator self-pickup)", async () => {
-        const { client, bodies } = clientCapturingBody();
-        await issueTransition(client, { id: "DX-1", action: "pickup", manual: true });
-        expect(bodies[0]).toEqual({ action: "pickup", manual: true });
-    });
-    it("omits manual when not provided", async () => {
-        const { client, bodies } = clientCapturingBody();
-        await issueTransition(client, { id: "DX-1", action: "pickup" });
-        expect(bodies[0]).toEqual({ action: "pickup" });
-    });
-});