@thehammer/danx-dashboard-mcp 0.1.120 → 0.1.123

package/dist/handlers.js

@@ -679,12 +679,13 @@ export async function issueProblem(client, args) {
     }
 }
 /**
- * One problem's candidate solutions via
- * `/api/issues/:id/problems/:pid/solutions[/:sid]` (DX-2735), action-dispatched
- * like `issue_checklist`. A missing required arg for the chosen action throws at
- * this boundary (no round-trip); the server's refusal envelopes
- * (`stale_solution` with the current row, a second recommendation on the same
- * problem, editing a chosen option, a solution id from another problem → 404)
+ * One problem's candidate solutions, AND (DX-3310) one solution's individual
+ * procedure steps, via `/api/issues/:id/problems/:pid/solutions[/:sid][/steps[/:stepId]]`
+ * — action-dispatched like `issue_checklist`. A missing required arg for the
+ * chosen action throws at this boundary (no round-trip); the server's
+ * refusal envelopes (`stale_solution`/`stale_step` with the current row, a
+ * second recommendation on the same problem, editing a chosen option, a
+ * solution/step id from the wrong scope → 404, nesting past depth 3 → 400)
  * pass through verbatim.
  *
  * There is deliberately NO answer action, on this tool or any other. Answering
@@ -708,11 +709,28 @@ export async function issueSolution(client, args) {
         case "add": {
             // DX-2735: the POST carries the CHECKED title, not a re-read of args.title.
             const title = need.string(args.title, "title");
+            // DX-3310 — omitted `steps` on add means "no steps", not "leave
+            // untouched" (there is nothing yet to leave untouched on a brand new
+            // solution) — sent through only when the caller actually supplied it,
+            // so an existing add-only caller that never heard of `steps` keeps
+            // creating exactly what it always created.
+            if (args.steps !== undefined)
+                content.steps = args.steps;
             return client.request({ method: "POST", path: base, body: { ...content, title }, board });
         }
         case "edit": {
             const solutionId = need.id(args.solution_id, "solution_id");
             const baseHash = need.string(args.base_hash, "base_hash");
+            // DX-3310 — omitted keeps the stored steps untouched; an explicit
+            // (including empty) array replaces them via the server's diff.
+            if (args.steps !== undefined) {
+                content.steps = args.steps;
+                // B2 (code-review fix) — REQUIRED alongside `steps`, checked here
+                // (not only by the server) so a caller gets the teaching error at
+                // this boundary rather than a round trip for something this client
+                // already knows is missing.
+                content.steps_base_hash = need.string(args.steps_base_hash, "steps_base_hash");
+            }
             return client.request({
                 method: "PATCH",
                 path: `${base}/${solutionId}`,
@@ -730,6 +748,42 @@ export async function issueSolution(client, args) {
                 board,
             });
         }
+        // DX-3310 (AC 35250) — granular single-step CUD, so changing one step
+        // never requires resending the whole `steps` tree.
+        case "add_step": {
+            const solutionId = need.id(args.solution_id, "solution_id");
+            const title = need.string(args.title, "title");
+            const body = { title };
+            if (args.description !== undefined)
+                body.description = args.description;
+            if (args.parent_step_id !== undefined)
+                body.parent_step_id = args.parent_step_id;
+            if (args.position !== undefined)
+                body.position = args.position;
+            return client.request({ method: "POST", path: `${base}/${solutionId}/steps`, body, board });
+        }
+        case "edit_step": {
+            const solutionId = need.id(args.solution_id, "solution_id");
+            const stepId = need.id(args.step_id, "step_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
+            const body = { base_hash: baseHash };
+            if (args.title !== undefined)
+                body.title = args.title;
+            if (args.description !== undefined)
+                body.description = args.description;
+            return client.request({ method: "PATCH", path: `${base}/${solutionId}/steps/${stepId}`, body, board });
+        }
+        case "remove_step": {
+            const solutionId = need.id(args.solution_id, "solution_id");
+            const stepId = need.id(args.step_id, "step_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
+            return client.request({
+                method: "DELETE",
+                path: `${base}/${solutionId}/steps/${stepId}`,
+                body: { base_hash: baseHash },
+                board,
+            });
+        }
     }
 }
 /**

package/dist/index.js

@@ -20,7 +20,7 @@
  *   - issue_comment          POST/PATCH/DELETE /api/issues/:id/comments[/:cid]
  *   - issue_checklist        POST/PATCH/DELETE /api/issues/:id/checklists[/:cid[/items[/:iid]]]
  *   - issue_problem          GET/POST/PATCH/DELETE /api/issues/:id/problems[/:pid] (DX-2735)
- *   - issue_solution         POST/PATCH/DELETE /api/issues/:id/problems/:pid/solutions[/:sid] (DX-2735)
+ *   - issue_solution         POST/PATCH/DELETE /api/issues/:id/problems/:pid/solutions[/:sid][/steps[/:stepId]] (DX-2735, steps DX-3310)
  *   - issue_dependency       POST/DELETE /api/issues/:id/dependencies[/:did]
  *   - issue_retire_branch    POST   /api/issues/:id/card-branch-retire (DX-2845)
  *   - issue_quality_gate     POST   /api/issues/:id/quality-gates/:gate
@@ -626,6 +626,28 @@ const SOLUTION_FIELDS = {
     con: z.string().optional(),
     recommended: z.boolean().optional(),
 };
+const STEP_INPUT = z.lazy(() => z
+    .object({
+    id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("present -> this node IS an existing step (matched on this id, 400 if it does not resolve to a live " +
+        "child of this exact parent scope — a supplied id is NEVER claimed by the positional/title fallback " +
+        "below); absent -> matched against unclaimed siblings by TITLE (first unclaimed match, in order), else " +
+        "created new. An id-less MIDDLE insert recreates every later id-less sibling's row unless you send ids " +
+        "for the ones you want preserved — send ids whenever an existing step's identity matters (checked " +
+        "progress, a later single-step edit)."),
+    title: z
+        .string()
+        .min(1)
+        .describe("one imperative line, the thing to do — labels (\"1.\", \"2a\") are DERIVED on read and must never appear " +
+        "in the title itself."),
+    description: z.string().nullable().optional().describe("markdown detail, or null/omitted for none"),
+    steps: z.array(STEP_INPUT).optional().describe("this step's own children, nested — refused past 3 levels total"),
+})
+    .strict());
 strictTool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pid]: one statement the operator must resolve (a question, or a flaw in the plan) OR an action only a person can carry out, each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human exactly while open_problem_count > 0 — there is no separate flag to set, adding a problem IS putting the card in front of a human. list → live problems in order, each {id, statement, context, type, summary, content_hash, open, solutions[], decisions[]}; add {statement, context?, type?, summary?, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus `problems_reminder: {open_problem_count, instruction}` naming each open problem's solution count; edit :pid {base_hash, statement, context?, summary?}; remove :pid {base_hash} — always allowed, even as the card's last open problem (removing it just means the card no longer needs a human). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. No answer action — the operator answers in the dashboard. `statement` is capped at 200 characters (a 400 names the actual length otherwise): write it as ONE plain sentence (a question for a question, the deed itself for an action), and put any investigation detail in `context` (markdown, no cap) instead of running it on. Good: statement \"Which cache should we use?\", context \"Redis fits the read-heavy path; see benchmark in #123. Memcached is simpler ops but no persistence.\" Bad: statement \"We looked at Redis vs Memcached, ran benchmarks showing Redis 3x faster on reads, but Memcached has simpler ops and we're not sure persistence matters here since the cache is fully rebuildable from Postgres...\" (too long, refused — move it to context). Every problem is also a `type`, with a `summary` distinct from `context`: read BOTH fields' own descriptions below before your first `add` — together they teach which type this is, and the three-field split (`statement` / `summary` / `context`) an action actually needs.", {
     id: z.string().min(1),
     action: z.enum(["list", "add", "edit", "remove"]),
@@ -659,9 +681,9 @@ strictTool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pi
         "WHY THE ACTION IS NEEDED AND WHY YOU CANNOT DO IT YOURSELF — that sentence is what tells the operator this " +
         "is not you being lazy (an add with no summary is refused 400); context is whatever additional detail the " +
         "person needs to carry it out; solutions[] are the possible ROUTES a person could take (e.g. \"rotate by " +
-        "hand in the console\" vs \"run the provisioning script\" vs \"ask the vendor\"), each carrying its own " +
-        "steps to completion once the operator picks one. Omitted defaults to \"question\" — decide deliberately " +
-        "every time."),
+        "hand in the console\" vs \"run the provisioning script\" vs \"ask the vendor\"), and EACH ONE MUST CARRY " +
+        "AT LEAST ONE STEP (refused 400 otherwise) — an action with no procedure is not yet actionable. Omitted " +
+        "defaults to \"question\" — decide deliberately every time."),
     summary: z
         .string()
         .nullable()
@@ -673,20 +695,71 @@ strictTool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pi
         "when given (omit/null on a question means none). edit: omit to keep the stored summary, null to clear it " +
         "(refused if the problem is a live action)."),
     solutions: z
-        .array(z.object({ title: z.string().min(1), ...SOLUTION_FIELDS }).strict())
+        .array(z.object({ title: z.string().min(1), ...SOLUTION_FIELDS, steps: z.array(STEP_INPUT).optional() }).strict())
         .optional()
-        .describe("add only; fields as issue_solution add"),
+        .describe("add only; fields as issue_solution add, INCLUDING steps (S6/AC 35332) — an ACTION problem's inline " +
+        "solutions must each carry at least one step (refused 400 otherwise); a QUESTION's may carry any number, " +
+        "including none."),
     ...boardField,
 }, async (args) => jsonResult(await issueProblem(client, args)));
 // ---------------- issue_solution ----------------
-strictTool("issue_solution", "One problem's options via /api/issues/:id/problems/:pid/solutions[/:sid]; `problem_id` is REQUIRED (from issue_problem list/add; another problem's solution id → 404). add {title, body?, pro?, con?, recommended?}: title names the option, body is its markdown detail, pro/con the case for and against; edit :sid {base_hash, ...only the changed fields}; remove :sid {base_hash}. A stale base_hash → 409 `stale_solution` with currentHash + currentSolution: merge, then retry. At most ONE live recommended per problem: a second → 409 naming `recommended_solution_id`. A chosen option cannot be edited (409 — add a new one) but can be removed.", {
+strictTool("issue_solution", "One problem's options via /api/issues/:id/problems/:pid/solutions[/:sid], AND (DX-3310) one solution's individual " +
+    "procedure steps via .../solutions/:sid/steps[/:stepId]; `problem_id` is REQUIRED (from issue_problem list/add; " +
+    "another problem's solution id → 404). add {title, body?, pro?, con?, recommended?, steps?}: title names the " +
+    "option/route, body is its markdown detail, pro/con the case for and against, `steps` is its WHOLE procedure " +
+    "authored in one call — an ordered array of {title, description?, steps?}, nestable to 3 levels (a 4th is refused " +
+    "400 naming the offending step and the limit). AC 35332 — under an ACTION problem, `steps` must be non-empty " +
+    "(refused 400 otherwise); under a QUESTION it may be omitted or empty. Labels (\"1\", \"2a\", \"2a.i\") are " +
+    "ALWAYS DERIVED on read from position — never put one in a title yourself. edit :sid {base_hash, ...only the " +
+    "changed fields, steps?, steps_base_hash?}: `steps` omitted leaves the stored procedure untouched, an explicit " +
+    "array (including [], refused if it would leave an action's solution with zero steps) DIFFS against it — send " +
+    "back an existing step's `id` (read from the card) to keep it (even while retitling/reordering it) and omit " +
+    "`id` for a genuinely new step; any existing step you don't include gets removed, and an id-less MIDDLE insert " +
+    "recreates every later id-less sibling's row unless you send ids for the ones whose identity matters. " +
+    "`steps_base_hash` is REQUIRED whenever `steps` is sent — the solution's current `steps_hash` (read it off the " +
+    "card first); a stale value → 409 `stale_steps` carrying the current tree, so a step added/removed since your " +
+    "read is never silently dropped. NEVER resend the whole tree just to fix one word — see add_step/edit_step/" +
+    "remove_step below. remove :sid {base_hash}. A stale base_hash → 409 `stale_solution` with currentHash + " +
+    "currentSolution: merge, then retry. At most ONE live recommended per problem: a second → 409 naming " +
+    "`recommended_solution_id`. A CHOSEN option's words are frozen (409 — add a new one instead), and so is its " +
+    "WHOLE PROCEDURE — every steps route below also refuses once a decision has chosen this solution.\n\n" +
+    "Granular single-step actions — change ONE step without resending the tree: add_step {solution_id, title, " +
+    "description?, parent_step_id?, position?} — title is ONE imperative line, never a label like \"1.\" or \"2a\" " +
+    "(derived on read); parent_step_id omitted/null = top-level; position is 1-indexed among the parent's current " +
+    "live children, omitted = append, and a position beyond the current sibling count is refused (400), never " +
+    "silently clamped to append; nesting past depth 3 → 400. edit_step {solution_id, step_id, base_hash, title?, " +
+    "description?} — never moves a step (no parent_step_id/position here). remove_step {solution_id, step_id, " +
+    "base_hash} — soft-deletes it AND its own live children; refused (409) if this solution belongs to an ACTION " +
+    "problem and removing it would leave zero live steps. A stale base_hash on a step → 409 `stale_step` with " +
+    "currentHash + currentStep (carrying its real derived `label`).", {
     id: z.string().min(1),
-    action: z.enum(["add", "edit", "remove"]),
+    action: z.enum(["add", "edit", "remove", "add_step", "edit_step", "remove_step"]),
     problem_id: z.number().int().positive(),
-    solution_id: z.number().int().positive().optional().describe("edit/remove"),
-    base_hash: z.string().min(1).optional().describe("content_hash last read; edit/remove"),
-    title: z.string().min(1).optional().describe("add"),
+    solution_id: z.number().int().positive().optional().describe("edit/remove/add_step/edit_step/remove_step"),
+    base_hash: z.string().min(1).optional().describe("content_hash last read; edit/remove/edit_step/remove_step"),
+    title: z.string().min(1).optional().describe("add; also add_step/edit_step"),
     ...SOLUTION_FIELDS,
+    steps: z.array(STEP_INPUT).optional().describe("add/edit only — see this tool's own description"),
+    steps_base_hash: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("edit only, REQUIRED whenever steps is sent — the solution's current steps_hash; a stale value is refused 409 stale_steps"),
+    description: z.string().nullable().optional().describe("add_step/edit_step; markdown detail, or null/omitted for none"),
+    step_id: z.number().int().positive().optional().describe("edit_step/remove_step"),
+    parent_step_id: z
+        .number()
+        .int()
+        .positive()
+        .nullable()
+        .optional()
+        .describe("add_step only; omitted/null = top-level step"),
+    position: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("add_step only; 1-indexed among the parent's current live children, omitted = append"),
     ...boardField,
 }, async (args) => jsonResult(await issueSolution(client, args)));
 // ---------------- issue_dependency ----------------

package/package.json

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