@thehammer/danx-dashboard-mcp 0.1.121 → 0.1.125

package/dist/handlers.js

@@ -413,6 +413,33 @@ function argCheckers(tool, mode) {
         },
     };
 }
+/**
+ * Every action-dispatched tool's args carry these three regardless of
+ * `action` — never action-specific, so every per-action allow-list passed to
+ * `refuseInapplicableFields` is unioned with this rather than repeating it.
+ */
+const STRUCTURAL_ACTION_FIELDS = ["id", "action", "board"];
+/**
+ * DX-3310 (code-review nit) — a field the caller sent that means nothing for
+ * the chosen `action` used to be silently ignored: `issue_solution`'s `add`
+ * built its `content` object from `title`/`body`/`pro`/`con`/`recommended`
+ * regardless of action, then simply never read it on `remove`/`add_step`/etc,
+ * and `issue_problem`'s `remove` never looked at `statement`/`context`/
+ * `solutions` at all. Either way the caller got a 200 with the field quietly
+ * discarded — no different from a typo. Refused loud instead, mirroring
+ * `argCheckers`' own wording: every ACTUALLY-SUPPLIED (`!== undefined`) key
+ * outside the action's own allow-list (plus `STRUCTURAL_ACTION_FIELDS`,
+ * always allowed) is named in one error, so a caller fixes every offending
+ * field in one round trip rather than one at a time.
+ */
+function refuseInapplicableFields(tool, mode, args, allowed) {
+    const offending = Object.keys(args)
+        .filter((key) => args[key] !== undefined && !STRUCTURAL_ACTION_FIELDS.includes(key) && !allowed.has(key))
+        .sort();
+    if (offending.length > 0) {
+        throw new Error(`${tool} ${mode} refuses fields that do not apply to this action: ${offending.join(", ")}`);
+    }
+}
 export async function issueComment(client, args) {
     const idEnc = encodeURIComponent(args.id);
     const board = args.board;
@@ -614,10 +641,25 @@ export async function issueChecklist(client, args) {
  *
  * No answer action, for the reason `issueSolution` gives.
  */
+/**
+ * DX-3310 (nit) — per-action allow-list for `refuseInapplicableFields`.
+ * `id`/`action`/`board` are structural and never listed (every action takes
+ * them). `type` is listed under `edit` even though it can never actually be
+ * SENT there (see the dedicated throw below) — that keeps the generic
+ * refusal from firing first with a less specific message than the one that
+ * already names the real reason.
+ */
+const PROBLEM_ACTION_FIELDS = {
+    list: [],
+    add: ["statement", "context", "type", "summary", "solutions"],
+    edit: ["problem_id", "base_hash", "statement", "context", "summary", "type"],
+    remove: ["problem_id", "base_hash"],
+};
 export async function issueProblem(client, args) {
     const idEnc = encodeURIComponent(args.id);
     const board = args.board;
     const need = argCheckers("issue_problem", `action=${args.action}`);
+    refuseInapplicableFields("issue_problem", `action=${args.action}`, args, new Set(PROBLEM_ACTION_FIELDS[args.action]));
     switch (args.action) {
         case "list":
             return client.request({ method: "GET", path: `/${idEnc}/problems`, board });
@@ -693,11 +735,24 @@ export async function issueProblem(client, args) {
  * question could release the very stop it set to wait for a human. The operator
  * answers in the dashboard.
  */
+const SOLUTION_ACTION_FIELDS = {
+    add: ["title", "body", "pro", "con", "recommended", "steps"],
+    edit: ["solution_id", "base_hash", "title", "body", "pro", "con", "recommended", "steps", "steps_base_hash"],
+    remove: ["solution_id", "base_hash"],
+    add_step: ["solution_id", "title", "description", "parent_step_id", "position"],
+    edit_step: ["solution_id", "step_id", "base_hash", "title", "description"],
+    remove_step: ["solution_id", "step_id", "base_hash"],
+};
 export async function issueSolution(client, args) {
     const need = argCheckers("issue_solution", `action=${args.action}`);
     // DX-2735: checked at runtime too, not only by the schema — a caller that skips
     // the MCP boundary must never build `/problems/undefined/solutions`.
     const problemId = need.id(args.problem_id, "problem_id");
+    // DX-3310 (nit) — `problem_id` is unioned in here rather than listed in
+    // every `SOLUTION_ACTION_FIELDS` entry: unlike `issue_problem` (where it
+    // only applies to edit/remove), `issue_solution` requires it for every
+    // action (checked above), so it is structural FOR THIS TOOL specifically.
+    refuseInapplicableFields("issue_solution", `action=${args.action}`, args, new Set(["problem_id", ...SOLUTION_ACTION_FIELDS[args.action]]));
     const base = `/${encodeURIComponent(args.id)}/problems/${problemId}/solutions`;
     const board = args.board;
     const content = {};
@@ -723,8 +778,14 @@ export async function issueSolution(client, args) {
             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)
+            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}`,

package/dist/index.js

@@ -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,43 +695,43 @@ 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)));
-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); absent → new, or matched by (parent, ordinal, title)"),
-    title: z.string().min(1),
-    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());
+// ---------------- issue_solution ----------------
 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); edit :sid {base_hash, ...only the changed fields, steps?}: `steps` " +
-    "omitted leaves the stored procedure untouched, an explicit array (including []) 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. 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 cannot be edited (409 — add a new " +
-    "one) but can be removed.\n\n" +
+    "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?} — parent_step_id omitted/null = top-level; position is 1-indexed " +
-    "among the parent's current live children, omitted = 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. A stale base_hash on " +
-    "a step → 409 `stale_step` with currentHash + currentStep (carrying its real derived `label`).", {
+    "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", "add_step", "edit_step", "remove_step"]),
     problem_id: z.number().int().positive(),
@@ -718,6 +740,11 @@ strictTool("issue_solution", "One problem's options via /api/issues/:id/problems
     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

package/package.json

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