@thehammer/danx-dashboard-mcp 0.1.56 → 0.1.58

package/dist/handlers.js

@@ -710,7 +710,7 @@ export async function planList(client) {
 }
 /**
  * One plan, entire — its cards, the boards they cover, its goals + rules +
- * caveats, its architecture document, and the sessions working on it. ONE
+ * caveats, its architecture sections, and the sessions working on it. ONE
  * call rather than five, which is what keeps this tool surface small enough
  * to be worth an agent's context.
  */
@@ -861,25 +861,104 @@ export async function planRename(client, args) {
     });
 }
 /**
- * Write the connected plan's architecture document, under the same
- * optimistic-concurrency guard the dashboard editor uses: `base_hash` must be
- * the `contentHash` the last `plan_get` returned, and a stale base is refused
- * with `{error: "stale_plan_architecture", currentHash}` rather than
- * overwriting whoever wrote in between.
+ * Read ONE section of the plan this session is connected to, via
+ * `GET /api/plans/mine/architecture/sections/:sid`. TAKES NO PLAN ID: the
+ * plan is resolved from your connected session, same as `plan_add_record`.
+ * Useful for a targeted read (skip pulling the whole plan via `plan_get`)
+ * and for conflict recovery after a 409 `stale_plan_architecture_section` —
+ * though that refusal already carries `currentTitle`/`currentContent`, so a
+ * second read is rarely needed for that specific case. Not connected →
+ * `{error: "session_not_connected"}`. Unknown/foreign section id → 404.
  */
-export async function planSetArchitecture(client, args) {
+export async function planGetArchitectureSection(client, args) {
+    return client.request({
+        method: "GET",
+        path: `/mine/architecture/sections/${args.section_id}`,
+        basePath: PLANS_BASE_PATH,
+    });
+}
+/**
+ * Append a section to the connected plan's architecture, via
+ * `POST /api/plans/mine/architecture/sections`. TAKES NO PLAN ID, same as
+ * `plan_add_record`. The new section sorts after every existing live
+ * section — see `plan_reorder_architecture_section` to move it.
+ */
+export async function planAddArchitectureSection(client, args) {
+    return client.request({
+        method: "POST",
+        path: "/mine/architecture/sections",
+        basePath: PLANS_BASE_PATH,
+        body: { title: args.title, content: args.content },
+    });
+}
+/**
+ * Edit a section's title and/or content, via
+ * `PATCH /api/plans/mine/architecture/sections/:sid`. Both `title` and
+ * `content` are OPTIONAL — send only whichever changed. `base_hash` MUST be
+ * the section's `contentHash` from the immediately-prior `plan_get`/
+ * `plan_get_architecture_section`; the server compares it against the row's
+ * current hash and, on a mismatch, refuses the write ENTIRELY and fails loud
+ * with `{ok: false, status: 409, body: {error:
+ * "stale_plan_architecture_section", currentHash, currentTitle,
+ * currentContent}}` rather than overwriting whoever wrote in between —
+ * `currentTitle`/`currentContent` ride the SAME refusal so you can merge and
+ * retry in ONE round trip. TAKES NO PLAN ID: the plan is resolved from your
+ * connected session, same as `plan_add_record`.
+ */
+export async function planUpdateArchitectureSection(client, args) {
+    return client.request({
+        method: "PATCH",
+        path: `/mine/architecture/sections/${args.section_id}`,
+        basePath: PLANS_BASE_PATH,
+        body: {
+            base_hash: args.base_hash,
+            ...(args.title === undefined ? {} : { title: args.title }),
+            ...(args.content === undefined ? {} : { content: args.content }),
+        },
+    });
+}
+/**
+ * Soft-delete a section of the connected plan's architecture, via
+ * `DELETE /api/plans/mine/architecture/sections/:sid`. `base_hash` MUST be
+ * the section's `contentHash` from the immediately-prior read; a stale hash
+ * refuses the delete ENTIRELY (nothing is removed) with the same
+ * `{ok: false, status: 409, body: {error: "stale_plan_architecture_section",
+ * currentHash, currentTitle, currentContent}}` shape
+ * `plan_update_architecture_section` uses — on a mismatch, re-fetch and
+ * confirm this is still the section you meant to remove before retrying,
+ * never blindly re-send with the fresh hash. TAKES NO PLAN ID. Unknown/
+ * foreign/already-deleted section id → 404.
+ */
+export async function planDeleteArchitectureSection(client, args) {
+    return client.request({
+        method: "DELETE",
+        path: `/mine/architecture/sections/${args.section_id}`,
+        basePath: PLANS_BASE_PATH,
+        body: { base_hash: args.base_hash },
+    });
+}
+/**
+ * Reassign the connected plan's section display order, via
+ * `PUT /api/plans/mine/architecture/sections/reorder`. UNGUARDED by content
+ * hash, by design: moving a section never changes its (or any other
+ * section's) `contentHash`. `order` must name exactly the plan's current
+ * live section ids, each once — a partial or foreign list is refused with a
+ * 400 rather than silently reordering a subset or dropping a section from
+ * view. TAKES NO PLAN ID.
+ */
+export async function planReorderArchitectureSection(client, args) {
     return client.request({
         method: "PUT",
-        path: "/mine/architecture",
+        path: "/mine/architecture/sections/reorder",
         basePath: PLANS_BASE_PATH,
-        body: { content: args.content, base_hash: args.base_hash },
+        body: { order: args.order },
     });
 }
 /**
  * Create a new, empty plan via `POST /api/plans`. GLOBAL — a plan is not
  * board-scoped, so this takes no board and creates no membership; the caller
- * still owns zero cards, zero records and no architecture document until it
- * adds them. This does NOT connect any session to the new plan — call
+ * still owns zero cards, zero records and zero architecture sections until
+ * it adds them. This does NOT connect any session to the new plan — call
  * `plan_connect` separately (mirroring how creating a card does not add it to
  * a plan; these are two deliberately separate steps, same as everywhere else
  * in this tool surface).
@@ -920,8 +999,8 @@ export async function planGetRecord(client, args) {
  * currentBody, currentContext}}` rather than overwriting whoever wrote in
  * between. DX-2734: the hash covers body AND context, and `context` is sent
  * only when given (omitted keeps the stored context, `null` clears it).
- * `currentBody` rides the SAME refusal — unlike the architecture document's
- * `stale_plan_architecture`, which carries only `currentHash` — so you can
+ * `currentBody` rides the SAME refusal — the same richer shape
+ * `stale_plan_architecture_section` carries for a section — so you can
  * merge and retry in ONE round trip without a second `plan_get_record` call.
  * TAKES NO PLAN ID: the plan is resolved from your connected session, same as
  * `plan_add_record`. Not connected → `{error: "session_not_connected"}`.

package/dist/index.js

@@ -43,7 +43,11 @@
  *   - plan_add_card          POST   /api/plans/mine/cards
  *   - plan_remove_card       DELETE /api/plans/:plan_id/cards/:card_id (DX-2740)
  *   - plan_rename            PATCH  /api/plans/:plan_id (DX-2740)
- *   - plan_set_architecture  PUT    /api/plans/mine/architecture
+ *   - plan_get_architecture_section     GET    /api/plans/mine/architecture/sections/:sid (DX-2726)
+ *   - plan_add_architecture_section     POST   /api/plans/mine/architecture/sections (DX-2726)
+ *   - plan_update_architecture_section  PATCH  /api/plans/mine/architecture/sections/:sid (DX-2726)
+ *   - plan_delete_architecture_section  DELETE /api/plans/mine/architecture/sections/:sid (DX-2726)
+ *   - plan_reorder_architecture_section PUT    /api/plans/mine/architecture/sections/reorder (DX-2726)
  *
  * 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
@@ -84,7 +88,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, issueQualityGate, issueQualityGateVerdict, issueRequiresHuman, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, planAddCard, planAddRecord, planConnect, planCreate, planDeleteRecord, planGet, planGetRecord, planList, planRemoveCard, planRename, planSetArchitecture, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
+import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueQualityGate, issueQualityGateVerdict, issueRequiresHuman, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, planAddArchitectureSection, planAddCard, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteRecord, planGet, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -626,15 +630,15 @@ server.tool("brief_set_page", 'Write one Brief page via PUT /api/brief/page?slug
 // ---------------- plans (DX-2683) ----------------
 // THE BINDING ASYMMETRY IS IN THE SCHEMAS, NOT IN PROSE. `plan_get` takes an
 // optional `plan_id`; `plan_add_record`, `plan_get_record`,
-// `plan_update_record`, `plan_delete_record`, `plan_add_card` and
-// `plan_set_architecture` take NO plan id in any form, so a connected session
-// cannot even express "write to that other plan". `plan_connect` takes one
+// `plan_update_record`, `plan_delete_record`, `plan_add_card` and the five
+// `plan_*_architecture_section` tools take NO plan id in any form, so a
+// connected session cannot even express "write to that other plan". `plan_connect` takes one
 // because binding a session to a plan is the one operation that is ABOUT a
 // plan id — and it can only ever bind the caller's own session. `plan_create`
 // also takes no plan id, but for a different reason: it MAKES a plan rather
 // than acting on one, so there is no existing plan for an id to name yet.
 server.tool("plan_list", "List every plan via GET /api/plans (DX-2683), and learn which plan THIS session is connected to. Plans are GLOBAL, not board-scoped: a plan is a named, dated set of cards an operator assembled by hand, and its cards may come from any repository. Returns `{ok, status, body: {plans: [{id, name, createdAt, cardCount, boards}], session, sessionListenerAttached}}`. `session` is your own registration — `{sessionId, title, planId, planName, firstSeenAt, lastActiveAt}` — or `null` if this process is not running inside a Claude Code session. A `planId` of null means you are connected to no plan: read any plan with `plan_get`, then `plan_connect` to the one you are working on (or ask the operator to connect you from the Plans list). `sessionListenerAttached` says whether your event listener is running: `false` while connected to a plan means you will NOT hear about its cards — call `plan_connect` again and arm the Monitor it returns. NOTE this is NOT the board Brief (`brief_list`), which is a different feature entirely.", {}, async () => jsonResult(await planList(client)));
-server.tool("plan_get", "Read one plan WHOLE via GET /api/plans (DX-2683) — its member cards (with the boards they cover), its goals, rules and caveats, its architecture document, the sessions working on it, and your own session state. One call, not five. Pass `plan_id` to read ANY plan (browsing another plan is useful and changes nothing); OMIT it to read the plan this session is connected to. Omitting it while connected to no plan fails loud with `{error: \"session_not_connected\"}` — connect first. Returns `{plan, cards, boards, records: {goal, rule, caveat} (each `[{id, ref, body, context, contentHash}]` — `context` is markdown detail or null), architecture: {content, contentHash, updatedAt, updatedBy}, sessions, session, sessionListenerAttached}` — `sessionListenerAttached: false` while connected means your event listener is not running; call `plan_connect` again and arm the Monitor it returns. ALWAYS `plan_get` immediately before `plan_set_architecture` and pass the returned `architecture.contentHash` back as `base_hash`.", {
+server.tool("plan_get", "Read one plan WHOLE via GET /api/plans (DX-2683) — its member cards (with the boards they cover), its goals, rules and caveats, its architecture sections, the sessions working on it, and your own session state. One call, not five. Pass `plan_id` to read ANY plan (browsing another plan is useful and changes nothing); OMIT it to read the plan this session is connected to. Omitting it while connected to no plan fails loud with `{error: \"session_not_connected\"}` — connect first. Returns `{plan, cards, boards, records: {goal, rule, caveat} (each `[{id, ref, body, context, contentHash}]` — `context` is markdown detail or null), architecture: {sections: [{id, planId, contentHash, title, content, sortOrder, createdAt, updatedAt}]}, sessions, session, sessionListenerAttached}` — `sessionListenerAttached: false` while connected means your event listener is not running; call `plan_connect` again and arm the Monitor it returns. 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()
@@ -642,7 +646,7 @@ server.tool("plan_get", "Read one plan WHOLE via GET /api/plans (DX-2683) — it
         .optional()
         .describe("A plan id from `plan_list`. Omit to read the plan this session is connected to."),
 }, 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 document; 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, name, createdAt}}}`. Use the returned `plan.id` with `plan_connect` to start working on it, or with `plan_get({plan_id})` to browse it.", {
+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, name, createdAt}}}`. 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."),
 }, async (args) => jsonResult(await planCreate(client, args)));
 server.tool("plan_connect", "Connect THIS session to a plan via POST /api/plan-sessions/me/plan (DX-2683) — the same binding the operator's Connect action writes, through the same server-side path. A session is connected to AT MOST ONE plan (enforced by the schema, not by convention); connecting while already on another plan MOVES you, and the response says which plan you left: `{ok, status, body: {session, movedFrom: {id, name} | null}}`. `movedFrom: null` means you were on no plan, or already on this one. It can only ever bind your OWN session — `me` is resolved from the session id this server forwards, never from anything you pass. After this, every plan WRITE tool acts on this plan, and no plan id is accepted anywhere. THE REPLY ALSO CARRIES `listener: {command, persistent: true, instruction}` — arm it IMMEDIATELY with the Monitor tool (`command` as given, `persistent: true`): from then on every comment, answer, requires_human change and block/unblock on this plan's cards arrives as a notification line like `[DX-8 \"Title\" repo:board] newms87 answered: chose \"Pause E2E\" — note: \"…\"`. Never poll for these. The command carries a narrow stream ticket, not a credential; calling plan_connect again (same plan is fine) issues a new one and ends the old listener, which is how you re-arm after a session restart or after the Monitor reports it gave up. If the ticket cannot be issued the call fails with `listener_not_armed` even though the connect itself happened.", {
@@ -681,12 +685,29 @@ server.tool("plan_rename", "Rename a plan via PATCH /api/plans/:plan_id (DX-2740
     plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
     name: z.string().min(1).describe("The plan's new name."),
 }, async (args) => jsonResult(await planRename(client, args)));
-server.tool("plan_set_architecture", 'Write the ARCHITECTURE DOCUMENT of the plan this session is connected to, via PUT /api/plans/mine/architecture (DX-2683). One markdown document per plan — how the work is shaped, not a task list. `base_hash` MUST be the `architecture.contentHash` from the immediately-prior `plan_get`; the server compares it against the current hash and, on a mismatch, fails loud with `{ok: false, body: {error: "stale_plan_architecture", currentHash}}` rather than overwriting whoever wrote in between. On that refusal: re-`plan_get`, re-merge your changes into the fresh content, and retry with the new hash — never retry blindly. A never-written document reads as `contentHash: ""`, so a true first write passes `base_hash: ""`. Writing REPLACES the whole document, so send the full merged markdown, not a fragment. TAKES NO PLAN ID: the plan is resolved from your connected session.', {
-    content: z.string().describe("The complete markdown document, replacing what is stored."),
-    base_hash: z
-        .string()
-        .describe('The `architecture.contentHash` from the immediately-prior `plan_get` ("" for a true first write). Required — an absent hash is not read as "".'),
-}, async (args) => jsonResult(await planSetArchitecture(client, args)));
+server.tool("plan_get_architecture_section", "Read ONE section of the plan this session is connected to, via GET /api/plans/mine/architecture/sections/:sid (DX-2726). TAKES NO PLAN ID: the plan is resolved from your connected session, same as `plan_add_record`. Not connected → `{error: \"session_not_connected\"}`. Unknown or another plan's section id → 404. Returns `{section: {id, planId, contentHash, title, content, sortOrder, createdAt, updatedAt}}`.", {
+    section_id: z.number().int().positive().describe("A section id, from `plan_get` or `plan_add_architecture_section`."),
+}, async (args) => jsonResult(await planGetArchitectureSection(client, args)));
+server.tool("plan_add_architecture_section", "Append a section to your connected plan's architecture, via POST /api/plans/mine/architecture/sections (DX-2726). Architecture is SECTIONS, not one document — each section is independently editable and hash-guarded, so fixing one never stales a concurrent edit to another. The new section sorts after every existing live section; use `plan_reorder_architecture_section` to move it. `title` is the heading shown in the auto-generated navigation index; `content` is its markdown. Takes no plan id; `session_not_connected` → `plan_connect` first. Returns the new section plus the plan's full live section list.", {
+    title: z.string().min(1).describe("The section's heading, shown in the navigation index."),
+    content: z.string().describe("The section's markdown. May be empty — a section awaiting its first draft is a real state."),
+}, async (args) => jsonResult(await planAddArchitectureSection(client, args)));
+server.tool("plan_update_architecture_section", 'Edit a section\'s title and/or content, via PATCH /api/plans/mine/architecture/sections/:sid (DX-2726). Both `title` and `content` are OPTIONAL — send only whichever changed. `base_hash` MUST be the section\'s `contentHash` from your last read; the server compares it against the current hash and, on a mismatch, fails loud with `{ok: false, body: {error: "stale_plan_architecture_section", currentHash, currentTitle, currentContent}}` rather than overwriting whoever wrote in between — merge into those and retry with `base_hash: currentHash`, never blindly. Takes no plan id. Returns the edited section plus the plan\'s full live section list.', {
+    section_id: z.number().int().positive().describe("The section id to edit."),
+    base_hash: z.string().describe("The section's `contentHash` from your last read. Required."),
+    title: z.string().min(1).optional().describe("New heading. Omit to keep the stored title."),
+    content: z.string().optional().describe("New markdown. Omit to keep the stored content."),
+}, async (args) => jsonResult(await planUpdateArchitectureSection(client, args)));
+server.tool("plan_delete_architecture_section", 'Soft-delete a section of your connected plan\'s architecture, via DELETE /api/plans/mine/architecture/sections/:sid (DX-2726). `base_hash` must be the section\'s `contentHash` from your last read; a stale hash deletes nothing and returns `{error: "stale_plan_architecture_section", currentHash, currentTitle, currentContent}` — on that refusal, re-fetch and confirm this is still the section you meant to remove before retrying, never blindly re-send with the fresh hash. Takes no plan id. Unknown or already-deleted section id → 404. Returns the plan\'s remaining live section list.', {
+    section_id: z.number().int().positive().describe("The section id to delete."),
+    base_hash: z.string().describe("The section's `contentHash` from your last read. Required."),
+}, async (args) => jsonResult(await planDeleteArchitectureSection(client, args)));
+server.tool("plan_reorder_architecture_section", "Reassign your connected plan's section display order, via PUT /api/plans/mine/architecture/sections/reorder (DX-2726). UNGUARDED by content hash, by design: moving a section never changes its (or any other section's) `contentHash`, so no `base_hash` is needed. `order` must name EXACTLY the plan's current live section ids, each once — a partial or foreign list is refused with a 400 rather than silently reordering a subset or dropping a section from view. Takes no plan id. Returns the plan's full live section list in its new order.", {
+    order: z
+        .array(z.number().int().positive())
+        .min(1)
+        .describe("Every live section id of the connected plan, in the desired order — exactly once each."),
+}, async (args) => jsonResult(await planReorderArchitectureSection(client, args)));
 // ---------------- main ----------------
 async function main() {
     boot();

package/package.json

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