@thehammer/danx-dashboard-mcp 0.1.309 → 0.1.311

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}` — 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 on an existing card (DX-4077, DX-5164). `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.
@@ -61,7 +61,7 @@ Card and plan reads/writes go through `danxbot_api` against the issue/plan route
 
 ## `plan_events_wait` — a working session's plan events (DX-4233)
 
-A program calls this, not a person: the danxbot Claude Code plugin's relay loop, inside the session, calls it over and over on the session's own danx-dashboard MCP server and hands every event it gets to the session. A plan-orchestrator dispatch (a headless session that works one plan) has no plugin relay, so it keeps ONE background waiter sub-agent that loops on this tool until events exist and returns them with the last cursor, and the orchestrator passes that cursor to the next waiter it arms (DX-4667); the `plan-orchestrator` profile alone is granted the tool on a dispatch (it is an opt-in tool). The `bridge` subcommand is gone: no process is spawned, no `npx` cold start, and nothing outlives the session, because the stream lives in the MCP server, which ends with its session.
+A program calls this, not a person: the danxbot Claude Code plugin's relay loop, inside the session, calls it over and over on the session's own danx-dashboard MCP server and hands every event it gets to the session. An orchestrator dispatch (a headless session that works one plan) has no plugin relay, so it keeps ONE background waiter sub-agent that loops on this tool until events exist and returns them with the last cursor, and the orchestrator passes that cursor to the next waiter it arms (DX-4667); the `orchestrator` profile alone is granted the tool on a dispatch (it is an opt-in tool). The `bridge` subcommand is gone: no process is spawned, no `npx` cold start, and nothing outlives the session, because the stream lives in the MCP server, which ends with its session.
 
 Input `{plan_id: number | null, cursor: string | null, timeout_ms: 1000..30000, transcript_path?: string}`. `plan_id` is `null` for a signed-in session on no plan (DX-4882): its stream still carries the pacing and resume messages of its Claude account, and it receives no plan events. A move between a plan and `null` starts clean like a move between plans: the plan-scoped records of the plan left are dropped, the session-scoped ones kept. Answer, one of:
 

package/dist/design-publish.js

@@ -1,16 +1,18 @@
 /**
  * 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 an existing card's design.
  *
  * 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.
+ *
+ * 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 +28,23 @@ 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;
+    const boardOrRefusal = await readCardBoard(client, cardId);
     if (!boardOrRefusal.ok)
         return boardOrRefusal;
     const { board } = boardOrRefusal;
@@ -87,19 +70,6 @@ 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");
-    }
     let published;
     try {
         published = await danxbotApi(client, {
@@ -118,8 +88,8 @@ 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 };

package/dist/index.js

@@ -170,7 +170,7 @@ let permissionRequests;
 // DX-4523 - late-bound with `access` and `client`; see `tool-surface.ts` and `permission-watch.ts`.
 let toolAccessSync;
 let permissionWatch;
-// DX-4233 - late-bound with `access`; see `plan-events-relay.ts`. The plugin's relay loop (a person's session) and a plan orchestrator's waiter sub-agent (DX-4667) call `plan_events_wait` on it.
+// DX-4233 - late-bound with `access`; see `plan-events-relay.ts`. The plugin's relay loop (a person's session) and an orchestrator's waiter sub-agent (DX-4667) call `plan_events_wait` on it.
 let planEventRelay;
 /**
  * Compose the dispatch's qualified board id (`<repo>:<slug>`) from the two env
@@ -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,16 @@ 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 a design on an existing card. " +
     "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. " +
+    "Returns `{card_id, 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 +666,8 @@ 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."),
+}, 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, " +
@@ -799,7 +791,7 @@ async (args) => {
 // ---------------- plan_events_wait (DX-4233) ----------------
 strictTool("plan_events_wait", 
 // DX-4882 - `plan_id` is null for a signed-in session on no plan: its stream still carries its account's pacing and resume messages.
-// DX-4233 - for the danxbot plugin's relay loop. DX-4667 - and for a background waiter sub-agent of a plan orchestrator, which
+// DX-4233 - for the danxbot plugin's relay loop. DX-4667 - and for a background waiter sub-agent of an orchestrator, which
 // loops on it until events exist and returns them (and the cursor) to the orchestrator it wakes. It answers `events` (each
 // `{cursor, text, urgent}`; empty after `timeout_ms`), the cursor to send being the last delivered event's, or `stopped` with the remedy
 // to tell the session. General-audience text (DX-4550): nothing here names our own setup.

package/dist/plan-events-relay.js

@@ -2,7 +2,7 @@
  * DX-4233 - the IN-PROCESS relay of a session's plan events: what the `plan_events_wait` tool serves.
  *
  * WHO CALLS IT. In a person's session, the danxbot plugin's relay loop calls `plan_events_wait` over and over on this
- * session's own danx-dashboard MCP server and hands every record it gets to the session. In a plan orchestrator's dispatch
+ * session's own danx-dashboard MCP server and hands every record it gets to the session. In an orchestrator's dispatch
  * (DX-4667), which loads no relay, a background waiter sub-agent calls it the same way and returns the records and the last
  * cursor to the orchestrator. This class is everything on the
  * server side of that call: it opens the session's dashboard event stream (the mint / stream / heartbeat contract of

package/dist/tool-access.js

@@ -48,9 +48,9 @@ export const TOOL_ACCESS = {
     design_publish: needs("cards.edit"),
     // DX-4233 - the plugin's relay waits on the session's plan events here: it opens the listener ticket
     // (`POST /api/plan-sessions/me/stream-ticket`) and heartbeats (`.../me/heartbeat`), both `plans.view`.
-    // DX-4667 - not operator-session-only: a plan orchestrator's dispatch calls it too, through a background waiter sub-agent that
+    // DX-4667 - not operator-session-only: an orchestrator's dispatch calls it too, through a background waiter sub-agent that
     // wakes the orchestrator when a person answers. What keeps it off every other dispatch is the opt-in (`MCP_SERVER_OPT_IN_TOOLS`,
-    // `src/tokens/tool-defs.ts`) granted to the `plan-orchestrator` profile alone, not this table.
+    // `src/tokens/tool-defs.ts`) granted to the `orchestrator` profile alone, not this table.
     plan_events_wait: needs("plans.view"),
     // DX-4632 - the plugin's session-start hook asks which plan the session this one replaced was working. A restarted session boots
     // signed out, so it holds no permission: like `plan_connect` it is a bootstrap tool, and a person's session's only (a dispatch

package/dist/urgent-records.js

@@ -1,7 +1,7 @@
 /**
  * DX-4721 - THE ONE PLACE that decides whether a relayed plan-event record is URGENT.
  *
- * Background. `plan_events_wait` hands the caller (the danxbot plugin's relay, or a plan orchestrator's waiter sub-agent) a
+ * Background. `plan_events_wait` hands the caller (the danxbot plugin's relay, or an orchestrator's waiter sub-agent) a
  * stream of records. The caller delivers an ordinary record after the session's running turn ends, and adds an URGENT one to
  * the running turn at once. Which record is which is decided here, by the record's KIND, and nowhere else: every site that
  * creates a record names its source and calls `isUrgent`; none writes an `urgent` literal of its own. The flag is a required

package/package.json

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