@thehammer/danx-dashboard-mcp 0.1.142 → 0.1.144

package/dist/handlers.js

@@ -336,6 +336,39 @@ 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.
+ */
+// A9 (code-review fix) — takes `object` rather than `Record<string, unknown>`
+// so every caller (each with its own specific `*Args` interface, no index
+// signature) passes `args` directly, with no `as unknown as Record<...>`
+// bridge cast at the call site. `Object.entries` reads the key/value pairs
+// without needing an index signature on the input type either.
+function refuseInapplicableFields(tool, mode, args, allowed) {
+    const offending = Object.entries(args)
+        .filter(([key, value]) => value !== undefined && !STRUCTURAL_ACTION_FIELDS.includes(key) && !allowed.has(key))
+        .map(([key]) => 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;
@@ -537,10 +570,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 });
@@ -621,11 +669,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 = {};

package/dist/index.js

@@ -192,9 +192,6 @@ function resolveCredentialOrDie() {
  * `CLAUDE_CODE_SESSION_ID` is set on every process an interactive Claude Code
  * session spawns — this server among them — so no launcher, no dispatch
  * overlay and no agent cooperation is needed for a session to be identifiable.
- * The same variable is what `src/agent/nested-claude-preflight.ts` already
- * relies on to detect a nested session, so this is an established fact about
- * the runtime rather than a new assumption.
  *
  * OPTIONAL, unlike every other env this package reads. A process running
  * outside a Claude Code session has no session to report; it sends no session
@@ -342,14 +339,14 @@ const boardField = {
         .string()
         .min(1)
         .optional()
-        .describe("Target another board by its qualified id `<repo>:<slug>`; omit for this dispatch's board. Unknown → 404."),
+        .describe("Board id `<repo>:<slug>`; omit for this dispatch's board. Unknown → 404."),
 };
 // The three prose fields of a card, each with ONE job. Shared by issue_create
 // (root + phase children) and issue_edit so the guidance an agent reads is
 // identical wherever it writes the field.
-const TITLE_DESCRIBE = 'Short, specific label naming the domain, so a reader recognises the card unopened (e.g. "Guest checkout rejects carts holding a gift card"). Never generic ("2 real decisions needed", "Fix bug", "Follow-up").';
-const SUMMARY_DESCRIBE = "1–3 plain-language sentences, no markdown/jargon, for someone new to this codebase: what the card is and why it matters. Always shown, never collapsed — not a second title, not a teaser for the description.";
-const DESCRIPTION_DESCRIBE = 'The full body ("Context"): evidence, examples, technical detail; markdown, collapsed by default. A question for the operator and its options go in issue_problem, not here. Style rules: see issue_comment\'s `text` param.';
+const TITLE_DESCRIBE = 'Short, specific label naming the domain (e.g. "Guest checkout rejects gift-card carts"). Never generic ("Fix bug", "Follow-up").';
+const SUMMARY_DESCRIBE = "1–3 plain-language sentences, no markdown/jargon: what the card is and why it matters. Always shown, never collapsed — not a second title, not a teaser.";
+const DESCRIPTION_DESCRIBE = 'The full body ("Context"): evidence, examples, technical detail; markdown, collapsed by default. Operator questions go in issue_problem. Style: see issue_comment\'s `text` param.';
 // DX-3335 — condensed from the now-deleted danxbot:comment-style skill (PLN-11
 // R-16: fold a skill's rule into the tool description it governs rather than
 // require a separate load). Shared by every prose-writing field below so an
@@ -412,7 +409,7 @@ strictTool("issue_get",
         .optional()
         .describe("Single-id form only. How many comments the page holds (server default 20), the window anchored at the " +
         "NEWEST comment. An out-of-range value (server max 200) is refused by the server with its own 400, " +
-        "never silently clamped here. Requires `fields` to include `comments`."),
+        "never silently clamped here. Requires `fields:[\"comments\"]`."),
     comments_offset: z
         .number()
         .int()
@@ -488,7 +485,7 @@ strictTool("issue_create", '`plan` is REQUIRED on every create — no default, n
     priority: z
         .union([z.enum(PRIORITY_TIER_WORDS), z.number()])
         .optional()
-        .describe('A tier word ("lowest"=0–1…"critical"=5–6; higher number = more urgent, prefer tier word) or number in [0,6); higher numbers are more urgent. Omit for the route\'s own default.'),
+        .describe('Tier word ("lowest"…"critical", prefer this) or number in [0,6); higher = more urgent. Omit for the route\'s own default.'),
     // DX-3238 — `assigned_agent` is DELIBERATELY left undeclared here, unlike
     // `priority` above. The route accepts it (`ALLOWED_CREATE_KEYS`,
     // create.ts:39-56) but it only matters for the create→`list_id`-lands-
@@ -525,7 +522,7 @@ strictTool("issue_edit", 'Patch a card. ALLOWED keys: title, summary, descriptio
         status: z
             .enum(CHECKLIST_ITEM_STATUSES)
             .optional()
-            .describe("Optional full status; omitted → from `checked`. `deferred` REQUIRES a non-empty `detail`; a 📡 item can never be `passing`."),
+            .describe("Optional full status; omitted → from `checked`. See tool description for the deferred/📡 rules."),
         detail: z
             .string()
             .optional()
@@ -552,7 +549,7 @@ strictTool("issue_edit", 'Patch a card. ALLOWED keys: title, summary, descriptio
     priority: z
         .union([z.enum(PRIORITY_TIER_WORDS), z.number()])
         .optional()
-        .describe('A tier word ("lowest"=0–1…"critical"=5–6; higher number = more urgent, prefer tier word) or number in [0,6); higher numbers are more urgent. The only way to set priority.'),
+        .describe('Tier word ("lowest"…"critical", prefer this) or number in [0,6); higher = more urgent — see tool description for why this is the only way to set it.'),
     list_id: z.string().min(1).nullable().optional(),
     triage_enabled: z
         .boolean()
@@ -647,15 +644,15 @@ const STEP_INPUT = z.lazy(() => z
         .int()
         .positive()
         .optional()
-        .describe("present -> this node IS an existing step (matched on this id; 400 if not a live child of this exact " +
-        "parent scope). absent -> matched against unclaimed siblings by TITLE (first match), else created new. " +
-        "An id-less MIDDLE insert recreates every later id-less sibling's row — send ids whenever an existing " +
-        "step's identity matters (checked progress, a later edit)."),
+        .describe("present -> matches an existing step by this id (400 if not a live child of this exact parent scope, " +
+        "never claimed by the fallback below); absent -> matches the first unclaimed same-titled sibling " +
+        "under the same parent, else creates new (title-based, never positional — keeps later id-less " +
+        "siblings' ids intact on a middle insert). Send ids anyway when identity matters (checked progress, " +
+        "a later edit) or siblings share a title."),
     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."),
+        .describe("one imperative line — labels (\"1.\", \"2a\") are DERIVED on read, never put one in the title."),
     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"),
 })
@@ -669,9 +666,7 @@ strictTool("issue_problem", "A card's PROBLEMS: one statement the operator must
         .string()
         .min(1)
         .optional()
-        .describe("add/edit; ONE plain sentence, at most 200 characters. For a question: the question itself. For an action: " +
-        "WHAT IS TO BE DONE — the deed itself, never phrased as a question (\"Rotate the staging DB credential\", " +
-        "not \"Should we rotate it?\")."),
+        .describe("add/edit; ONE plain sentence, at most 200 characters — see `type` below for question vs action phrasing."),
     context: z
         .string()
         .nullable()
@@ -697,16 +692,14 @@ strictTool("issue_problem", "A card's PROBLEMS: one statement the operator must
         .string()
         .nullable()
         .optional()
-        .describe("add/edit. Plain text, 1-3 sentences — never markdown detail (that's `context`'s job). For a question: " +
-        "optional, why it matters. For an action: REQUIRED and non-empty — why the action is needed AND why you " +
-        "(the agent raising it) cannot do it yourself; omitting it on an action add is refused 400 naming this " +
-        "field, and an edit that would clear it on a live action problem is refused the same way. add: sent only " +
-        "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)."),
+        .describe("add/edit. Plain text, 1-3 sentences — never markdown (that's `context`'s job). Required+non-empty for an " +
+        "action problem (why needed + why you can't do it yourself — see `type`; refused 400 if missing on add or " +
+        "cleared on a live action edit); optional for a question. add: sent only when given (omit/null on a " +
+        "question means none). edit: omit keeps the stored summary, null clears it."),
     solutions: z
         .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, INCLUDING steps (S6/AC 35332) — an ACTION problem's inline " +
+        .describe("add only; fields as issue_solution add, INCLUDING steps — 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,
@@ -715,27 +708,29 @@ strictTool("issue_problem", "A card's PROBLEMS: one statement the operator must
 strictTool("issue_solution", "One problem's options, AND one solution's individual " +
     "procedure steps; `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 its markdown detail, pro/con the case for and against; `steps` authors its WHOLE procedure " +
-    "in one call — an ordered array of {title, description?, steps?}, nestable to 3 levels (a 4th refused 400 " +
-    "naming the step and the limit). AC 35332 — under an ACTION problem `steps` must be non-empty (400 otherwise); " +
-    "under a QUESTION it may be empty/omitted. Labels (\"1\", \"2a\", \"2a.i\") are ALWAYS DERIVED on read from " +
-    "position — never put one in a title. edit :sid {base_hash, ...changed fields, steps?, steps_base_hash?}: " +
-    "`steps` omitted leaves the procedure untouched; an explicit array (including [], refused if it would leave " +
-    "an action's solution with zero steps) DIFFS against the stored tree the same way STEP_INPUT's own `id` field " +
-    "describes. `steps_base_hash` is REQUIRED whenever `steps` is sent — the solution's current `steps_hash`; " +
-    "stale → 409 `stale_steps` with the current tree. Prefer add_step/edit_step/remove_step below over resending " +
-    "the whole tree for a one-word fix. remove :sid {base_hash}. A stale base_hash → 409 `stale_solution` with " +
-    "currentHash + currentSolution: merge, then retry. At most ONE live recommended per problem (second → 409 " +
-    "naming `recommended_solution_id`). A CHOSEN option's words AND whole procedure are frozen — every route below " +
-    "also refuses once a decision has chosen this solution (add a new solution instead).\n\n" +
-    "Granular single-step edits: add_step {solution_id, title, " +
-    "description?, parent_step_id?, position?} — title is ONE imperative line, never a label (derived on read); " +
-    "parent_step_id omitted/null = top-level; position 1-indexed among current live children, omitted = append, " +
-    "beyond sibling count refused 400; nesting past depth 3 → 400. edit_step {solution_id, step_id, base_hash, " +
-    "title?, description?} — never moves a step. 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 (its " +
-    "derived `label`).", {
+    "option, body/pro/con its markdown detail and case for/against; `steps` authors the WHOLE procedure in one " +
+    "call — {title, description?, steps?}[], nestable to 3 levels (4th refused 400, naming the step + limit). " +
+    "ACTION problem: `steps` must be non-empty (400 otherwise); QUESTION: may be omitted/empty. Labels " +
+    "(\"1\", \"2a\", \"2a.i\") are DERIVED on read from position — never put one in a title. edit :sid {base_hash, " +
+    "...changed fields, steps?, steps_base_hash?}: `steps` omitted leaves the procedure untouched; an explicit " +
+    "array (incl. [], refused if it leaves an action's solution with zero steps) DIFFS against it — send an " +
+    "existing step's `id` to keep it (even while retitling/reordering), omit `id` for a new step; any existing " +
+    "step left out is removed. An id-less node matches the first unclaimed same-titled sibling under the same " +
+    "parent (never positional), so an id-less MIDDLE insert keeps later id-less siblings' ids — send ids anyway " +
+    "when identity matters. `steps_base_hash` REQUIRED whenever `steps` is sent — the solution's current " +
+    "`steps_hash`; stale → 409 `stale_steps` with the current tree. Never resend the whole tree to fix one word " +
+    "— use add_step/edit_step/remove_step below. remove :sid {base_hash}: stale → 409 `stale_solution` with " +
+    "currentHash + currentSolution, merge and retry. At most ONE live recommended per problem — a second → 409 " +
+    "naming `recommended_solution_id`. A CHOSEN option's words and WHOLE PROCEDURE are frozen (409 — add a new " +
+    "one instead); every steps route below refuses once a decision has chosen this solution.\n\n" +
+    "Granular single-step actions, no tree resend: add_step {solution_id, title, description?, parent_step_id?, " +
+    "position?} — title is one imperative line (labels derived, never typed); parent_step_id omitted/null = " +
+    "top-level; position 1-indexed among current live children, omitted = append, beyond sibling count → 400 " +
+    "(never clamped); nesting past depth 3 → 400. edit_step {solution_id, step_id, base_hash, title?, " +
+    "description?} — never moves a step. remove_step {solution_id, step_id, base_hash} — soft-deletes it and " +
+    "its live children; refused 409 if this solution belongs to an ACTION problem and removing it leaves zero " +
+    "live steps. Stale base_hash on a step → 409 `stale_step` with currentHash + currentStep (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(),
@@ -833,8 +828,8 @@ strictTool("quality_gate_instruction", "Fetch a named quality gate's current ins
 // ---------------- issue_retro ----------------
 strictTool("issue_retro", "Replace the retro block: {good, bad, correctable_danxbot_problem, correctable_danxbot_problem_description, action_item_ids[], commits[], tests[]}. Refuses 409 unless the card is terminal (completed_at or cancelled_at). good/bad upsert; the three list fields REPLACE (soft-delete prior live rows, fresh ordinals). action_item_ids[] entries match <PREFIX>-N. commits[] entries: {sha, subject?}. tests[] is required (empty array = ran none): one row per test GROUP that ran (name the group, not individual unit tests) or per e2e test (kind:'e2e', listed explicitly since few/expensive); each row {name, kind:'group'|'e2e', num_tests, num_passing_tests, duration_ms} required, num_assertions/num_passing_assertions nullable (omit when the runner has no assertion totals).", {
     id: z.string().min(1),
-    good: z.string().describe("Free-form markdown (prose or a list — pick whichever reads fastest, they render identically). Style rules: see issue_comment's `text` param."),
-    bad: z.string().describe("Free-form markdown (prose or a list — pick whichever reads fastest, they render identically). Style rules: see issue_comment's `text` param."),
+    good: z.string().describe("Free-form markdown (prose or list, they render identically). Style: see issue_comment's `text` param."),
+    bad: z.string().describe("Free-form markdown (prose or list, they render identically). Style: see issue_comment's `text` param."),
     correctable_danxbot_problem: z
         .boolean()
         .describe("Required. Did this dispatch hit a problem in danxbot's OWN code/configuration (not \"this card was hard\") that danxbot could change so it stops happening? A true+described answer starts exactly one automated repair (fix or a ready card) — the only reliable channel for a danxbot defect found mid-dispatch. Answer explicitly every time, never a default."),
@@ -947,14 +942,14 @@ strictTool("plan_get", "Read a plan. Pass `plan_id` to read ANY plan; OMIT to re
         .int()
         .nonnegative()
         .optional()
-        .describe("Where the `cards` page starts (default 0). Requires `fields` to include `cards`. Page with cards_offset while cards_offset + cards.length < cards_total."),
+        .describe("Where the `cards` page starts (default 0). Requires `fields:[\"cards\"]`. Page with cards_offset while cards_offset + cards.length < cards_total."),
     cards_limit: z
         .number()
         .int()
         .positive()
         .max(LIST_PAGE_MAX_LIMIT)
         .optional()
-        .describe("How many cards one page holds, 1.." + LIST_PAGE_MAX_LIMIT + " (default " + PLAN_GET_CARDS_DEFAULT_LIMIT + "). Requires `fields` to include `cards`."),
+        .describe("How many cards one page holds, 1.." + LIST_PAGE_MAX_LIMIT + " (default " + PLAN_GET_CARDS_DEFAULT_LIMIT + "). Requires `fields:[\"cards\"]`."),
     events_limit: z
         .number()
         .int()
@@ -1049,9 +1044,9 @@ strictTool("plan_update_note", 'Edit a plan note. `content_hash` must be the not
     content_hash: z.string().describe("The note's `contentHash` from your last read. Required."),
     title: z.string().min(1).optional().describe("New title, at most 60 characters. Omit to keep the stored title."),
     body: z.string().min(1).optional().describe("New wrap-up, at most 250 characters. Omit to keep the stored body."),
-    card_ids: z.array(z.string().min(1)).optional().describe("REPLACES the whole link set when sent (with record_refs/section_ids)."),
-    record_refs: z.array(z.string().min(1)).optional().describe("REPLACES the whole link set when sent (with card_ids/section_ids)."),
-    section_ids: z.array(z.number().int().positive()).optional().describe("REPLACES the whole link set when sent (with card_ids/record_refs)."),
+    card_ids: z.array(z.string().min(1)).optional().describe("Part of the link-set group — see tool description."),
+    record_refs: z.array(z.string().min(1)).optional().describe("Part of the link-set group — see tool description."),
+    section_ids: z.array(z.number().int().positive()).optional().describe("Part of the link-set group — see tool description."),
 }, async (args) => jsonResult(await planUpdateNote(client, args)));
 strictTool("plan_delete_note", 'Soft-delete a plan note. `content_hash` must be the note\'s last-read `contentHash` — stale deletes nothing, returns `{error: "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}` (same shape as `plan_update_note`). Takes an explicit `plan_id` (see `plan_add_note`). Unknown plan, note, or already-deleted note → 404. Returns `{notes_count}`.', {
     plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),

package/package.json

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