@thehammer/danx-dashboard-mcp 0.1.31 → 0.1.33

package/README.md

@@ -26,9 +26,9 @@ 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) |
 | `issue_edit` | `PATCH /api/issues/:id/edit` | Prose + structured keys (`title`, `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 |
-| `issue_triage` | `POST /api/issues/:id/triage` | Verdicts: approve, cancel, keep, defer (with optional ICE + ttl_seconds) |
+| `issue_triage` | `POST /api/issues/:id/triage` | Verdicts: approve, cancel, keep, defer (with optional ICE + ttl_seconds). None of these are a cross-card ordering gate — a card held at Review via `keep` can still be readied independent of a sibling; use `issue_dependency` to sequence cards |
 | `issue_comment` | `POST/PATCH/DELETE /api/issues/:id/comments[/:cid]` | Author server-stamped, soft-delete preserved |
-| `issue_dependency` | `POST/DELETE /api/issues/:id/dependencies[/:did]` | `depends_on` cycle-checked; remove hardcodes `reason: "recorded_in_error"` |
+| `issue_dependency` | `POST/DELETE /api/issues/:id/dependencies[/:did]` | `depends_on` cycle-checked; remove hardcodes `reason: "recorded_in_error"`. The only mechanism the dispatch picker enforces to sequence one card after another — status alone is not a substitute |
 | `issue_requires_human` | `POST/DELETE /api/issues/:id/requires-human` | Set replaces step rows atomically; clear soft-deletes them |
 | `issue_retro` | `PUT /api/issues/:id/retro` | Requires terminal card; replace semantics |
 

package/dist/handlers.js

@@ -24,45 +24,40 @@
 import { readFile } from "node:fs/promises";
 import { basename, extname, isAbsolute } from "node:path";
 import { resolvePriority } from "./priority.js";
+/**
+ * `filter`/`fields`/`sort` are JSON/CSV-encoded onto the query string (the
+ * route parses `?filter=<JSON>`, `?fields=a,b`, `?sort=<JSON>` — see
+ * `src/issues/read/reader.ts#parseEnvelope`); each is omitted entirely when
+ * empty so the wire carries no `{}`/`[]` noise. `board` stays a flat
+ * top-level param, resolved by the HTTP client exactly as before.
+ */
 export async function issueList(client, args) {
-    // status_derived is display-only on the server but the route accepts
-    // it as a projection filter — passthrough verbatim. parent_id=null is
-    // the legitimate "root cards only" filter; the server reader treats
-    // the literal string "null" identically.
     const query = {};
-    if (args.type !== undefined)
-        query.type = args.type;
-    if (args.parent_id !== undefined) {
-        query.parent_id = args.parent_id === null ? "null" : args.parent_id;
+    if (args.filter !== undefined && Object.keys(args.filter).length > 0) {
+        query.filter = JSON.stringify(args.filter);
+    }
+    if (args.fields !== undefined && args.fields.length > 0) {
+        query.fields = args.fields.join(",");
     }
-    if (args.dispatchable_derived !== undefined) {
-        query.dispatchable_derived = args.dispatchable_derived;
+    if (args.sort !== undefined && args.sort.length > 0) {
+        query.sort = JSON.stringify(args.sort);
     }
-    if (args.assigned_agent !== undefined)
-        query.assigned_agent = args.assigned_agent;
-    if (args.include_closed !== undefined)
-        query.include_closed = args.include_closed;
-    if (args.status_derived !== undefined)
-        query.status_derived = args.status_derived;
-    if (args.q !== undefined)
-        query.q = args.q;
     if (args.limit !== undefined)
         query.limit = args.limit;
     if (args.offset !== undefined)
         query.offset = args.offset;
-    // DX-1163 — the agent surface is lean by default: opt the route into the
-    // `IssueListRowLeanV2` projection (id/type/title/status/parent_id/
-    // assigned_agent/children-ids/priority). The SPA omits this and keeps the
-    // rich board row; `issue_get` still returns the full card body.
-    query.lean = true;
     // DX-1171 — board-only: forward the qualified board id, no repo.
     return client.request({ method: "GET", path: "", query, board: args.board });
 }
-// ---------------- issue_get ----------------
 export async function issueGet(client, args) {
+    const query = {};
+    if (args.fields !== undefined && args.fields.length > 0) {
+        query.fields = args.fields.join(",");
+    }
     return client.request({
         method: "GET",
         path: `/${encodeURIComponent(args.id)}`,
+        query,
         board: args.board,
     });
 }

package/dist/handlers.test.js

@@ -0,0 +1,51 @@
+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" });
+    });
+});

package/dist/index.js

@@ -127,6 +127,36 @@ const EFFORT_VALUES = [
 ];
 const ISSUE_TYPES = ["Epic", "Bug", "Feature", "Story", "Chore"];
 const NON_EPIC_TYPES = ["Bug", "Feature", "Story", "Chore"];
+// DX-935 / DX-937 — field-group taxonomy for the nested read envelope,
+// hand-copied from `src/issues/read/field-groups.ts` (LIST_GROUPS / GET_GROUPS
+// — this package cannot import server source). Drift surfaces at runtime as a
+// server 400, not silently.
+const LIST_FIELD_GROUPS = [
+    "description",
+    "ac",
+    "comments",
+    "retro",
+    "dependencies",
+    "triage",
+    "requires_human",
+    "assignment",
+    "quality_gates",
+    "children",
+    "effort",
+];
+const GET_FIELD_GROUPS = [
+    ...LIST_FIELD_GROUPS,
+    "mirrors",
+    "code_review_items",
+];
+const SORT_ORDERS = ["asc", "desc"];
+const sortField = z
+    .array(z.object({
+    column: z.string().min(1),
+    order: z.enum(SORT_ORDERS),
+}))
+    .optional()
+    .describe("Multi-column sort — ordered list of {column, order}. Absent → the server's default order (priority desc, repo_name asc, with a numeric-id tiebreaker always appended).");
 // DX-1290 — the uniform 4-state checklist-item status. Terminal = passing|cancelled.
 const CHECKLIST_ITEM_STATUSES = [
     "incomplete",
@@ -162,21 +192,37 @@ const boardField = {
         .describe("Target another board by its qualified id `<repo>:<slug>` (e.g. `platform:the-supply-operations-hub`); omit to use this dispatch's board. Unknown board → 404."),
 };
 // ---------------- issue_list ----------------
-server.tool("issue_list", "List issues for the dispatch's board by default via GET /api/issues. Board-scoped; defaults to the dispatch's board. Pass `board` (a qualified id `<repo>:<slug>`) to list another board instead (unknown board → 404). Filters: q (free-text search matched case-insensitively over title + description — use this to find cards by keyword), type, parent_id (string id, null for root-only), dispatchable_derived (boolean — server-computed pickup-ready gate), assigned_agent, include_closed (default false — excludes completed_at/cancelled_at). Returns ALL matching cards (no row cap unless you pass limit). Response body shape: {issues: Issue[]} — LEAN agent rows (DX-1163): each row carries ONLY {id, type, title, status, parent_id, assigned_agent, children (ids), priority}. UI-only board fields (children_detail, counts, triage_ice_total, blocked_descendants, conflict_on, child_assignments, requires_human_child_count, latest_work_dispatch, primary_attachment) and the `description` body are NOT included — call issue_get for the full card. Server-side numeric-suffix ordering so DX-10 follows DX-9. Use this instead of grepping .danxbot/issues/ — the DB-backed route is the source of truth post-DX-704.", {
-    q: z.string().optional(),
-    status_derived: z.string().optional(),
-    type: z.enum(ISSUE_TYPES).optional(),
-    parent_id: z.string().nullable().optional(),
-    dispatchable_derived: z.boolean().optional(),
-    assigned_agent: z.string().optional(),
-    include_closed: z.boolean().optional(),
+server.tool("issue_list", "List issues for the dispatch's board by default via GET /api/issues. Board-scoped; defaults to the dispatch's board. Pass `board` (a qualified id `<repo>:<slug>`) to list another board instead (unknown board → 404). Nested envelope (DX-935 / DX-937 — hard-cut, no flat params): `filter` — the OLD flat filters, now nested (type, parent_id, dispatchable_derived, status_derived[], self_dispatchable_derived, assigned_agent, include_closed, include_deleted, and `q` — free-text over id+title+description, the former standalone `q` param now lives at `filter.q`). `fields` — opt-in named field-GROUPS (description, ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, effort); THE DEFAULT RESPONSE (no `fields`) IS MINIMAL — only cheap scalar columns (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent), zero joins. Point any heavy read (full description, comments[], retro, ac items, dependency edges, triage history, quality-gate rows, children ids) at the matching `fields` entry rather than assuming it's already on the row. `sort` — ordered [{column, order}] (id|priority|repo_name|title|type|status_derived|triage_ice_total|created_at|updated_at); absent → default order (priority desc, repo_name asc) with an always-appended numeric-id tiebreaker (DX-10 follows DX-9). `limit`/`offset` — optional paging (no cap by default). Use issue_get for a single fully-detailed card.", {
+    filter: z
+        .object({
+        q: z.string().optional(),
+        type: z.enum(ISSUE_TYPES).optional(),
+        parent_id: z.string().nullable().optional(),
+        dispatchable_derived: z.boolean().optional(),
+        status_derived: z.array(z.string()).optional(),
+        self_dispatchable_derived: z.boolean().optional(),
+        assigned_agent: z.string().optional(),
+        include_closed: z.boolean().optional(),
+        include_deleted: z.boolean().optional(),
+    })
+        .optional()
+        .describe("Nested list filters (DX-935) — the hard-cut replacement for the old flat top-level params, including the former standalone `q` (now `filter.q`). Omit entirely for no filtering."),
+    fields: z
+        .array(z.enum(LIST_FIELD_GROUPS))
+        .optional()
+        .describe("Opt-in field-GROUPS to add to the minimal default row: description, ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, effort. Absent/empty = minimal scalars only — no joins."),
+    sort: sortField,
     limit: z.number().int().positive().max(1000).optional(),
     offset: z.number().int().nonnegative().optional(),
     ...boardField,
 }, async (args) => jsonResult(await issueList(client, args)));
 // ---------------- issue_get ----------------
-server.tool("issue_get", 'Fetch a single hydrated issue via GET /api/issues/:id. Board-scoped; defaults to the dispatch\'s board. Issue ids are globally unique, so this resolves from any dispatch regardless of `board`. Returns the full card (every joined child collection: ac [the 2-state facade onto the default "Acceptance Criteria" checklist] + checklists [DX-1290: the full named-checklist model — each {name, items:[{label, detail, status: incomplete|failing|passing|cancelled}]}], comments, dependencies, requires_human steps, retro action items + commits, triage history, quality_gates — DX-1177: one row per registered quality gate {gate, required, status pending|pass|fail, completed_at, message}; a required PRE gate not yet `pass` pre-empts the work dispatch with the gate reviewer, and `issue_transition complete` refuses while a required POST gate row != pass) plus the ancestor chain walked via parent_id. 404 envelope on unknown id.', {
+server.tool("issue_get", "Fetch a single issue via GET /api/issues/:id. Board-scoped; defaults to the dispatch's board. Issue ids are globally unique, so this resolves from any dispatch regardless of `board`. DEFAULT RESPONSE IS MINIMAL (DX-935 / DX-937) — only cheap scalar columns (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent); no joined collections. Pass `fields` to opt into named field-GROUPS: description (full description body), ac (acceptance-criteria + checklists model), comments (comments[]), retro (retro good/bad/action_items/commits), dependencies (waiting_on/conflict_on/blocked gate state), triage (triage history + ICE), requires_human (the requires_human gate + steps), assignment (dispatch/assigned_agent/lifecycle timestamps), quality_gates (DX-1177 — one row per registered gate {gate, required, status pending|pass|fail, completed_at, message}; a required PRE gate not yet `pass` pre-empts the work dispatch, and `issue_transition complete` refuses while a required POST gate row != pass), children (child id list + rollups), mirrors (external mirror sync state), code_review_items (code-review findings). Point any heavy read at the matching `fields` entry rather than assuming it's already on the row. 404 envelope on unknown id.", {
     id: z.string().min(1),
+    fields: z
+        .array(z.enum(GET_FIELD_GROUPS))
+        .optional()
+        .describe("Opt-in field-GROUPS to add to the minimal default row: description, ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, mirrors, code_review_items. Absent/empty = minimal scalars only."),
     ...boardField,
 }, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- issue_create ----------------
@@ -262,7 +308,7 @@ server.tool("issue_transition", "Stamp a lifecycle transition via POST /api/issu
     ...boardField,
 }, async (args) => jsonResult(await issueTransition(client, args)));
 // ---------------- issue_triage ----------------
-server.tool("issue_triage", "Record a triage verdict via POST /api/issues/:id/triage. Verdicts: approve (stamps ready_at — moves to ToDo, clears triage TTL), cancel (stamps cancelled_at — terminal), keep (refreshes triage_expires_at by ttl_seconds — defaults 7 days, card stays at Review), defer (stamps archived_at, clears ready_at — parks to Backlog). ICE components optional but recorded when present (total = i+c+e). Reason is REQUIRED non-empty. REFUSES 409 on terminal cards.", {
+server.tool("issue_triage", "Record a triage verdict via POST /api/issues/:id/triage. Verdicts: approve (stamps ready_at — moves to ToDo, clears triage TTL), cancel (stamps cancelled_at — terminal), keep (refreshes triage_expires_at by ttl_seconds — defaults 7 days, card stays at Review), defer (stamps archived_at, clears ready_at — parks to Backlog). ICE components optional but recorded when present (total = i*c*e). Reason is REQUIRED non-empty. REFUSES 409 on terminal cards. None of these verdicts create a cross-card ordering gate — a card left at Review (via keep) is invisible to the plan-dependency gate's live-partner comparison and can be readied independent of any sibling's status. To sequence one card after another, use issue_dependency (kind: depends_on) — that is the only mechanism the dispatch picker actually enforces regardless of status.", {
     id: z.string().min(1),
     verdict: z.enum(TRIAGE_VERDICTS),
     reason: z.string().min(1),
@@ -310,7 +356,7 @@ server.tool("issue_checklist", "Targeted checklist CUD via /api/issues/:id/check
     ...boardField,
 }, async (args) => jsonResult(await issueChecklist(client, args)));
 // ---------------- issue_dependency ----------------
-server.tool("issue_dependency", 'Dependency CRUD via /api/issues/:id/dependencies[/:did]. action=add → POST {kind, target_id, reason} where kind ∈ {depends_on, conflict_on}. depends_on adds are CYCLE-CHECKED (BFS from target back to source — 409 if loop). Idempotent: re-adding a live triple returns the existing id. Self-loops refuse 409. action=remove → DELETE /:did. The server REQUIRES the literal reason="recorded_in_error" on removal (encodes "removal means NOT related, never satisfied") — this MCP boundary hardcodes it, so callers do not pass reason on remove.', {
+server.tool("issue_dependency", 'Dependency CRUD via /api/issues/:id/dependencies[/:did]. action=add → POST {kind, target_id, reason} where kind ∈ {depends_on, conflict_on}. depends_on adds are CYCLE-CHECKED (BFS from target back to source — 409 if loop). Idempotent: re-adding a live triple returns the existing id. Self-loops refuse 409. action=remove → DELETE /:did. The server REQUIRES the literal reason="recorded_in_error" on removal (encodes "removal means NOT related, never satisfied") — this MCP boundary hardcodes it, so callers do not pass reason on remove. This is the ONLY mechanism the dispatch picker enforces to sequence one card after another — leaving a card at a Review/held status (e.g. an issue_triage "keep" verdict) is NOT a substitute and provides no cross-card ordering protection.', {
     id: z.string().min(1),
     action: z.enum(["add", "remove"]),
     kind: z.enum(["depends_on", "conflict_on"]).optional(),

package/package.json

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