@thehammer/danx-dashboard-mcp 0.1.310 → 0.1.312

package/README.md

@@ -50,7 +50,7 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | `danxbot_api_list` | No args. Lists the routes this caller's credential may reach as `{routes: ["METHOD /path"]}` (one bare string per route, exactly what `danxbot_api_spec` takes; a dispatch's own callbacks are in it) — call this first when you don't know the route for what you need to do. |
 | `danxbot_api_spec` | `{endpoints}` (comma-joined `METHOD /path` list, required, min 1). Returns the exact OpenAPI contract for those routes — call this when you know the route but not its exact request/response shape. |
 | `attach_file` | `{card_id, path, replaces?, primary?, filename?, content_type?}` — the server reads the LOCAL file at `path` (absolute, `/tmp/a.png` or `C:\x\a.png`) and uploads it, so its bytes never pass through the agent's context. `replaces: <attachment id>` swaps that attachment's file in place (`PUT /api/issues/:id/attachments/:aid`: same id, name and cover flag) instead of adding one; `primary: true` makes it the card's single cover, atomically with the write. Reply: `{issue: <compact row>, attachment_id, url, thumbnail_url, is_primary}`. Shown to a key holding `cards.edit` (DX-4523); a dispatch profile still receives it only when its catalog selection names it (`slack-agent` and `work`, DX-4386, through `extraTools`). A screenshot of browser-visible work: first `primary: true`, then `replaces` at each milestone. |
-| `design_publish` | `{target, dir, card_id?, board?, title?, summary?, description?}` — builds a design with the TARGET repo's own Vite (resolved from the target's root at run time: this package depends on neither `vite` nor `playwright`) and publishes it as a revision of a Design card (DX-4077). `target` names one of the repo's design targets, read from the dashboard (`GET /api/repos/<repo>`, edited in Settings > Board > General), never from a file; `dir` holds `Design.tsx` under the target's root. The repo is the board's `repo_name` (`GET /api/boards/<board>`). The build runs in `<root>/.danx-design/<build-id>/` (removed afterwards), in a short-lived `node` child process that exits when the build ends, so the server never holds the design's worktree files open and no esbuild outlives the publish (DX-4727), the page is written to `<tmpdir>/danx-design/<build-id>.html` before the upload, and a 1280x800 screenshot is taken when Playwright resolves from the target or this server's cwd (`screenshot: "none: <reason>"` otherwise, never a failed publish). Without `card_id` it creates the Design card first; a refused revision comes back verbatim with that `card_id`. Shown to a key holding `cards.edit`; opt-in, so a dispatch profile receives it only when its catalog selection names it (none does yet). |
+| `design_publish` | `{target, note, dir, card_id, design_no | design_title}` — builds a design with the TARGET repo's own Vite (resolved from the target's root at run time: this package depends on neither `vite` nor `playwright`) and publishes it as a revision of one of an existing card's designs, or as a new design on it (DX-4077, DX-5164, DX-5193): a card holds several designs, so pass exactly one of `design_no` (add a revision to that design, `POST /api/issues/<card>/designs/<no>/revisions`) or `design_title` (start a new design, `POST /api/issues/<card>/designs`; the title is fixed for good), both-or-neither is refused before anything is built; the answer carries `{card_id, design_no, revision_no, dashboard_url, local_html_path, screenshot}`. `target` names one of the repo's design targets, read from the dashboard (`GET /api/repos/<repo>`, edited in Settings > Board > General), never from a file; `dir` holds `Design.tsx` under the target's root. The repo is the board's `repo_name` (`GET /api/boards/<board>`). The build runs in `<root>/.danx-design/<build-id>/` (removed afterwards), in a short-lived `node` child process that exits when the build ends, so the server never holds the design's worktree files open and no esbuild outlives the publish (DX-4727), the page is written to `<tmpdir>/danx-design/<build-id>.html` before the upload, and a 1280x800 screenshot is taken when Playwright resolves from the target or this server's cwd (`screenshot: "none: <reason>"` otherwise, never a failed publish). `card_id` is required and names an existing card (any but an Epic or Feature); the tool never creates a card, and a refused revision comes back verbatim with the `card_id`. Shown to a key holding `cards.edit`; opt-in, so a dispatch profile receives it only when its catalog selection names it (none does yet). |
 | `request_permission` | `{permissions, reason}` — asks a person to grant this key ONE MORE permission (see "Asking for one more permission" above). Answers at once with the approval URL and confirm code; the grant is picked up in the background. |
 
 There is no dedicated `resource_fields` tool (removed DX-3465 — it was a thin wrapper `danxbot_api` already reaches with no agent-specific behavior earning it its own tool). What an opt-in field TREE may name for one resource (`{resource, description, always, hashes, fields, relations}`) is `danxbot_api({method:"GET", path:"/api/resources/<resource>/fields"})` — install-global, no `board`; `resource: "issue"` is the root, and a relation's own `resource` in the response is what to call this again with, one level deeper.

package/dist/design-publish.js

@@ -1,16 +1,21 @@
 /**
  * DX-4077 - the `design_publish` flow: build a design against the repo's real components with the repo's own Vite, and publish it as
- * a revision of a Design card.
+ * a revision of one of an existing card's designs, or as the first revision of a new design on it (DX-5193).
  *
  * It lives in this package, not behind `danxbot_api`, because it is agent-specific: the build runs where the source is (the agent's
  * own checkout or worktree) and the dashboard holds no connected repo's source and no Vite. Every dashboard call goes through the same
  * client `danxbot_api` uses, so it carries the session's credential, trace and session headers.
  *
- * ORDER, so a failure leaves as little behind as it can: the arguments, then the board and card, then the repo and its targets (the
- * dashboard answers; a refusal comes back verbatim), then the checkout and the build, then the screenshot, and only THEN the card is
- * created and the revision posted. A failed build or screenshot never leaves a card. The two writes are separate calls, so a refused
- * revision leaves a Design card with no revision: that is not hidden or undone, the refusal comes back verbatim WITH the new
- * `card_id`, and a retry with it adds revision 1 to the same card.
+ * The design goes on an EXISTING card (`card_id`, any card but an Epic or Feature, DX-5164): this tool never creates a card. To show
+ * options for work that has no card yet, create the card first.
+ *
+ * DX-5193: a card holds SEVERAL designs. `design_no` adds a revision to that existing design (`POST .../designs/<no>/revisions`);
+ * `design_title` starts a new design (`POST .../designs`, the title fixed for good). Exactly one of the two, refused before any call.
+ *
+ * ORDER, so a failure leaves as little behind as it can: the arguments, then the card's board, then the repo and its targets (the
+ * dashboard answers; a refusal comes back verbatim), then the checkout and the build, then the screenshot, and only THEN the revision is
+ * posted. A failed build or screenshot never leaves anything on the card; a refused revision comes back verbatim with the `card_id`
+ * and the built page's path.
  */
 import path from "node:path";
 import { buildDesign, newBuildId, writeLocalHtml } from "./design-build.js";
@@ -26,42 +31,30 @@ function field(body, name, where) {
         fail(`${where} answered without "${name}"`);
     return value;
 }
-/** The board the card lives on: the card's own (read from it), else the named one, else the server's, else a refusal naming `board`. */
-async function resolveBoard(client, args, deps) {
-    if (args.card_id === undefined) {
-        const board = args.board ?? deps.serverBoard;
-        if (board === undefined)
-            fail("no board: this server has none of its own, so name one in `board` (`<repo>:<slug>`)");
-        return { ok: true, board };
-    }
+/** The board the card lives on, read from the card: a revision goes on the card's own board. */
+async function readCardBoard(client, cardId) {
     const card = await danxbotApi(client, {
         method: "GET",
-        path: `/api/issues/${encodeURIComponent(args.card_id)}`,
+        path: `/api/issues/${encodeURIComponent(cardId)}`,
         query: { fields: { board_id: true } },
     });
     if (!card.ok)
         return card;
-    const board = field(card.body, "board_id", `GET /api/issues/${args.card_id}`);
-    if (args.board !== undefined && args.board !== board) {
-        fail(`card ${args.card_id} lives on board ${board}, not ${args.board}: a revision goes on the card's own board, so omit \`board\` or name ${board}`);
-    }
-    return { ok: true, board };
+    return { ok: true, board: field(card.body, "board_id", `GET /api/issues/${cardId}`) };
 }
 export async function designPublish(client, args, deps) {
-    // DX-4729: refused before any call, so a blank note never leaves a built page, a screenshot or a card behind.
+    // DX-4729: refused before any call, so a blank note never leaves a built page or a screenshot behind.
     if (args.note.trim() === "")
         fail("`note` is required: say what changed since the last revision, which decision note it answers and what is still open");
-    // With `card_id` the card already exists: its title, summary and description are not this call's to set, and silently ignoring them would hide the mistake.
-    if (args.card_id !== undefined) {
-        const given = ["title", "summary", "description"].filter((k) => args[k] !== undefined);
-        if (given.length > 0)
-            fail(`${given.map((k) => `\`${k}\``).join(", ")} name the card this call CREATES, so they cannot be combined with \`card_id\`: drop them to add a revision to ${args.card_id}`);
-    }
-    // No card to add to: it is created here, and a card needs a title and a summary. Refused before any call.
-    if (args.card_id === undefined && (args.title === undefined || args.summary === undefined)) {
-        fail("`title` and `summary` are required without `card_id` (they name the Design card this creates)");
-    }
-    const boardOrRefusal = await resolveBoard(client, args, deps);
+    const { card_id: cardId } = args;
+    // DX-5193: exactly one of design_no / design_title, refused before any call so a bad pair never builds a page.
+    const hasNo = args.design_no !== undefined;
+    const hasTitle = args.design_title !== undefined;
+    if (hasNo === hasTitle)
+        fail("pass exactly one of `design_no` (add a revision to that design of the card) or `design_title` (start a new design on the card)");
+    if (args.design_title?.trim() === "")
+        fail("`design_title` must not be blank");
+    const boardOrRefusal = await readCardBoard(client, cardId);
     if (!boardOrRefusal.ok)
         return boardOrRefusal;
     const { board } = boardOrRefusal;
@@ -87,25 +80,16 @@ export async function designPublish(client, args, deps) {
     const { html, buildId } = await buildDesign({ ...checked, buildId: newBuildId() });
     const localHtmlPath = await writeLocalHtml(buildId, html);
     const shot = await captureScreenshot(html, { rootAbs: checked.rootAbs, cwd: deps.cwd });
-    let cardId = args.card_id;
-    if (cardId === undefined) {
-        const created = await danxbotApi(client, {
-            method: "POST",
-            path: "/api/issues",
-            // `description` is a creation-time seed: the route requires a string.
-            body: { type: "Design", plan: "mine", board, title: args.title, summary: args.summary, description: args.description ?? "" },
-            board,
-        });
-        if (!created.ok)
-            return { ...created, local_html_path: localHtmlPath };
-        cardId = field(created.body?.issue, "id", "POST /api/issues");
-    }
+    const designRoute = hasTitle
+        ? `/api/issues/${encodeURIComponent(cardId)}/designs`
+        : `/api/issues/${encodeURIComponent(cardId)}/designs/${args.design_no}/revisions`;
     let published;
     try {
         published = await danxbotApi(client, {
             method: "POST",
-            path: `/api/issues/${encodeURIComponent(cardId)}/design/revisions`,
+            path: designRoute,
             body: {
+                ...(hasTitle ? { title: args.design_title } : {}),
                 note: args.note,
                 target: target.name,
                 entry: repoRelative(repoRoot, path.join(checked.dirAbs, DESIGN_FILE)),
@@ -118,17 +102,20 @@ export async function designPublish(client, args, deps) {
         });
     }
     catch (err) {
-        // A network or server fault after the card exists: the card id and the page still matter to the retry.
-        throw new Error(`${err.message} (card ${cardId} exists with no revision from this call; retry with card_id "${cardId}"; the page is at ${localHtmlPath})`);
+        // A network or server fault: the page is built and still matters to the retry.
+        throw new Error(`${err.message} (no revision was published to ${cardId}; the page is at ${localHtmlPath})`);
     }
     if (!published.ok)
         return { ...published, card_id: cardId, local_html_path: localHtmlPath };
-    const revisionNo = published.body?.revision_no;
-    if (typeof revisionNo !== "number")
-        fail(`POST /api/issues/${cardId}/design/revisions answered without a revision_no`);
+    const answer = published.body;
+    if (typeof answer?.design_no !== "number")
+        fail(`POST ${designRoute} answered without a design_no`);
+    if (typeof answer.revision_no !== "number")
+        fail(`POST ${designRoute} answered without a revision_no`);
     const body = {
         card_id: cardId,
-        revision_no: revisionNo,
+        design_no: answer.design_no,
+        revision_no: answer.revision_no,
         dashboard_url: `${deps.baseUrl.replace(/\/+$/, "")}/board/${cardId}`,
         local_html_path: localHtmlPath,
         screenshot: shot.screenshot,

package/dist/index.js

@@ -422,7 +422,7 @@ plain background (what the thing is, why it exists, what is wrong or what the ch
 Define each term a newcomer would not know. Cite exact ids, SHAs and paths. Be brief; never transcribe your
 reasoning. A title or summary alone must let the reader decide.
 
-DESIGN. UI designs and style options go on a Design card (\`design_publish\`), never an Artifact or HTML page.
+DESIGN. UI designs and style options go on the card they concern (\`design_publish\`), never an Artifact or HTML page.
 Decide choices yourself; show alternatives as design states, never ask.
 `;
 assertWithinTextLimit("the server instructions", SERVER_INSTRUCTIONS);
@@ -646,16 +646,17 @@ strictTool("attach_file", "Attach a LOCAL file to a card. This server reads and
 // `MCP_SERVER_OPT_IN_TOOLS`) and granted to no profile here: a default tool would add its schema to every default-all role's first
 // turn, and a role with no worktree or toolchain can only fail it. The package takes no `vite` or `playwright` dependency: both are
 // resolved from the target repo at run time (`design-build.ts`, `design-screenshot.ts`).
-strictTool("design_publish", "Build a design against this repo's REAL components with the repo's own Vite and publish it as a revision of a Design card. " +
+strictTool("design_publish", "Build a design against this repo's REAL components with the repo's own Vite and publish it as a revision of one of an existing card's designs, or as a new design on it. " +
     "The design is a directory holding `Design.tsx` (a default-exported React component) plus any helpers; it may be a whole " +
     "front-end app, and how to split its states is your call. Read the board's design prompt first: `danxbot_api` GET " +
     "/api/boards/<board> with fields {controls: true}, the row keyed `design.prompt`, field `value`. " +
-    "Without `card_id` this creates the Design card (needs `title` and `summary`, and a connected plan: it files the card with plan \"mine\", so connect one with plan_connect first); with `card_id`, the " +
-    "next revision goes on that card and `title`, `summary` and `description` are refused. Returns `{card_id, revision_no, dashboard_url, local_html_path, " +
+    "`card_id` names the card the design goes on (any card but an Epic or Feature); this tool never creates a card, so to show options for work that has no card yet, create the card first. " +
+    "A card holds several designs: pass `design_title` to start a NEW design, or `design_no` (from the card's `designs` relation) to add a revision to an existing one; exactly one. " +
+    "Returns `{card_id, design_no, revision_no, dashboard_url, local_html_path, " +
     "screenshot}`: `local_html_path` is the built page, written before the upload so you can open it yourself; `screenshot` is " +
     "`captured` (1280x800) or `none: <reason>` (no Playwright in the repo: the publish still succeeds). Build errors and a " +
-    "refused revision (400, 413) come back verbatim; a refusal after the card was created carries its `card_id`: fix the " +
-    "design and call again with it. Limits: the frame has no network, so a component that fetches its own data fails inside " +
+    "refused revision (400, 409, 413) come back verbatim with the `card_id`: fix the " +
+    "design and call again. Limits: the frame has no network, so a component that fetches its own data fails inside " +
     "it (use fixture props); React only; targets are a dashboard setting, read from `design_targets` of `GET /api/repos/<repo>`, never a file.", {
     target: z.string().min(1).describe("A design target's name, as listed in `design_targets` of `GET /api/repos/<repo>` (`danxbot_api`, fields {design_targets: true})."),
     note: z
@@ -666,16 +667,10 @@ strictTool("design_publish", "Build a design against this repo's REAL components
         .string()
         .min(1)
         .describe("The design directory: absolute, or relative to this server's cwd. Inside the target's root, holding `Design.tsx`."),
-    card_id: z.string().min(1).optional().describe("Add a revision to this Design card; omit to create one."),
-    title: z.string().min(1).optional().describe("The new card's title. Required without `card_id`; refused with it."),
-    summary: z.string().min(1).optional().describe("The new card's summary. Required without `card_id`; refused with it."),
-    description: z.string().optional().describe("The new card's description; default empty. Refused with `card_id`."),
-    board: z
-        .string()
-        .min(1)
-        .optional()
-        .describe("Board id `<repo>:<slug>` for the new card; omit for this server's board. With `card_id` the card's own board is used."),
-}, async (args) => guardedJson(() => designPublish(client, args, { serverBoard: config.board, baseUrl: config.baseUrl, cwd: process.cwd() })));
+    card_id: z.string().min(1).describe("The card this design goes on: any existing card but an Epic or Feature."),
+    design_no: z.number().int().positive().optional().describe("Add a revision to this existing design of the card (its `designs` relation). Not with `design_title`."),
+    design_title: z.string().min(1).optional().describe("Start a NEW design on the card with this title, fixed for good. Not with `design_no`."),
+}, async (args) => guardedJson(() => designPublish(client, args, { baseUrl: config.baseUrl, cwd: process.cwd() })));
 // ---------------- request_permission (DX-4434, parent DX-4432) ----------------
 strictTool("request_permission", "Ask a person to grant this key ONE MORE permission. Call it when a call was refused `403 forbidden` naming a " +
     "`permission`, or when you know you need one more. It returns AT ONCE with `{state, approvalUrl, confirmCode, " +

package/dist/listen.js

@@ -195,6 +195,10 @@ export function invalidEventReason(value) {
         case "design_decided": {
             if (typeof d.decision_id !== "number")
                 return "detail.decision_id is not a number";
+            if (typeof d.design_no !== "number")
+                return "detail.design_no is not a number";
+            if (typeof d.design_title !== "string")
+                return "detail.design_title is not a string";
             if (typeof d.revision_no !== "number")
                 return "detail.revision_no is not a number";
             if (!isDesignOutcome(d.outcome))
@@ -286,11 +290,12 @@ function describe(event) {
         // DX-4078: names the outcome, the revision and the note, and what the agent does next, so it never has to re-read the card to learn the verdict.
         case "design_decided": {
             const note = d.note;
-            const revision = `revision ${d.revision_no} of the design`;
+            // DX-5193: a card holds several designs, so the line names which one the verdict closes.
+            const revision = `revision ${d.revision_no} of design ${d.design_no} "${d.design_title}"`;
             if (d.outcome === "approved")
-                return `${who} APPROVED ${revision}${note === null ? "" : ` — note: ${quoted(note)}`}. The design is closed; build from it`;
+                return `${who} APPROVED ${revision}${note === null ? "" : ` — note: ${quoted(note)}`}. That design is closed; build from it`;
             if (d.outcome === "rejected")
-                return `${who} REJECTED ${revision} — reason: ${quoted(note)}. The design is closed; do not continue it`;
+                return `${who} REJECTED ${revision} — reason: ${quoted(note)}. That design is closed; do not continue it`;
             return `${who} requested changes on ${revision} — ${quoted(note)}. Publish a new revision that addresses it`;
         }
         default:

package/dist/tool-access.js

@@ -42,7 +42,7 @@ export const TOOL_ACCESS = {
     danxbot_api_spec: BOOTSTRAP,
     // `POST /api/issues/:id/attachments`
     attach_file: needs("cards.edit"),
-    // DX-4077 - builds in the agent's own checkout, then `POST /api/issues/:id/design/revisions` (`cards.edit`, DX-4076). The routes it
+    // DX-4077 - builds in the agent's own checkout, then `POST /api/issues/:id/designs` (a new design) or `POST /api/issues/:id/designs/:designNo/revisions` (the next revision), both `cards.edit` (DX-4076, DX-5193). The routes it
     // reads on the way (`GET /api/boards/:id`, `GET /api/repos/:id`, `GET /api/issues/:id`) and the card it creates are separate
     // checks on the dashboard whose refusals come back verbatim.
     design_publish: needs("cards.edit"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.310",
+  "version": "0.1.312",
   "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, request_permission, attach_file, and danxbot_slack_reply) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",