@thehammer/danx-dashboard-mcp 0.1.26 → 0.1.28

package/dist/entrypoint.js

@@ -0,0 +1,35 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+/**
+ * True when this module is the process entrypoint (the published bin) rather
+ * than an `import` — the DX-1606 tool-defs generator + its drift test import
+ * the module to introspect tool schemas without booting the stdio server, so
+ * `boot()` + `server.connect()` must run ONLY for the real bin invocation.
+ *
+ * Why the realpath resolve matters (DX-1647): `import.meta.url` reports the
+ * module's REALPATH — Node resolves symlinks for ESM module URLs by default.
+ * When the bin runs via a SYMLINK — both `npx` and global installs link
+ * `node_modules/.bin/danx-dashboard-mcp` → `dist/index.js` — `process.argv[1]`
+ * is the symlink path, which `pathToFileURL` would NOT match against the
+ * realpath `import.meta.url` carries. So resolve argv[1]'s realpath first; then
+ * the entrypoint is detected under BOTH direct `node dist/index.js` and the
+ * symlinked `npx -y @thehammer/danx-dashboard-mcp` the worker spawns.
+ *
+ * Without this, npx imports the module, registers the tools, and exits 0
+ * WITHOUT starting the server — every dispatch then fails the worker's
+ * "MCP loaded" preflight (`declared-not-loaded=[danx-dashboard]`).
+ */
+export function isEntrypointModule(moduleUrl, argvPath) {
+    if (typeof argvPath !== "string" || argvPath.length === 0)
+        return false;
+    let resolved;
+    try {
+        resolved = realpathSync(argvPath);
+    }
+    catch {
+        // argv[1] may not resolve on disk (synthetic paths in tests) — fall back to
+        // the raw path so a non-symlinked match still holds.
+        resolved = argvPath;
+    }
+    return moduleUrl === pathToFileURL(resolved).href;
+}

package/dist/entrypoint.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, writeFileSync, symlinkSync, rmSync, realpathSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isEntrypointModule } from "./entrypoint.js";
+describe("isEntrypointModule (DX-1647)", () => {
+    let dir;
+    let real;
+    let link;
+    beforeAll(() => {
+        dir = mkdtempSync(join(tmpdir(), "entrypoint-test-"));
+        real = join(dir, "index.js");
+        writeFileSync(real, "// stub entry\n");
+        link = join(dir, "danx-dashboard-mcp"); // mimics node_modules/.bin symlink
+        symlinkSync(real, link);
+    });
+    afterAll(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    // import.meta.url always reports the module REALPATH — model that here.
+    const moduleUrl = () => pathToFileURL(realpathSync(real)).href;
+    it("true when argv[1] is the real file (direct `node index.js`)", () => {
+        expect(isEntrypointModule(moduleUrl(), real)).toBe(true);
+    });
+    it("true when argv[1] is a SYMLINK to the file (npx / global bin) — the fleet regression", () => {
+        // The symlink path !== the realpath, but the entrypoint MUST still be
+        // detected, or npx imports the module and exits without booting the server.
+        expect(link).not.toBe(realpathSync(link));
+        expect(isEntrypointModule(moduleUrl(), link)).toBe(true);
+    });
+    it("false when argv[1] is undefined (module imported, not run as bin)", () => {
+        expect(isEntrypointModule(moduleUrl(), undefined)).toBe(false);
+    });
+    it("false when argv[1] is an empty string", () => {
+        expect(isEntrypointModule(moduleUrl(), "")).toBe(false);
+    });
+    it("false when argv[1] points at a different real file", () => {
+        const other = join(dir, "other.js");
+        writeFileSync(other, "// other\n");
+        expect(isEntrypointModule(moduleUrl(), other)).toBe(false);
+    });
+});

package/dist/handlers.js

@@ -361,12 +361,18 @@ export async function issueRequiresHuman(client, args) {
  * here launches the gate when the board state is `required` OR `optional`;
  * it is inert ONLY when the board state is `disabled`. Source of truth:
  * `isGateEffectivelyRequired` in `src/issues/quality-gates/read.ts`.
+ *
+ * `effort_level` (DX-1760) is an independent sibling write: present (incl.
+ * `null`) sets `card_quality_gates.effort_level`; omitted leaves it untouched.
  */
 export async function issueQualityGate(client, args) {
+    const body = { required: args.required };
+    if (args.effort_level !== undefined)
+        body.effort_level = args.effort_level;
     return client.request({
         method: "POST",
         path: `/${encodeURIComponent(args.id)}/quality-gates/${encodeURIComponent(args.gate)}`,
-        body: { required: args.required },
+        body,
         board: args.board,
     });
 }

package/dist/index.js

@@ -48,7 +48,7 @@
  * agent reads `body.error` + structured fields to decide next action.
  * 5xx and network failures throw — never silently swallowed.
  */
-import { pathToFileURL } from "node:url";
+import { isEntrypointModule } from "./entrypoint.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -191,9 +191,10 @@ server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-sco
         gate: z.string().min(1),
         enabled: z.boolean(),
         note: z.string(),
+        effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
     }))
         .optional()
-        .describe('REQUIRED fail-closed quality-gate decisions (DX-1594 — replaces required_gates). One {gate, enabled, note} per board-OPTIONAL gate of the card\'s type: `enabled` answers whether the gate runs on this card, `note` records the rationale (persisted as the decision rationale, distinct from the reviewer verdict). The board requirement is TRI-STATE per gate (`board_quality_gate_settings.default_state`): `required` runs always (NO decision — auto-on); `optional` REQUIRES a decision here (unanswered → the create 400s); `disabled` never runs (NO decision). Omit this only on a board with no optional gates; otherwise the 400 body\'s `required_gate_decisions` lists exactly which gates to answer — retry with {enabled, note} for each. A decision naming a non-optional gate is rejected 400.'),
+        .describe('REQUIRED fail-closed quality-gate decisions (DX-1594 — replaces required_gates). One {gate, enabled, note} per board-OPTIONAL gate of the card\'s type: `enabled` answers whether the gate runs on this card, `note` records the rationale (persisted as the decision rationale, distinct from the reviewer verdict). The board requirement is TRI-STATE per gate (`board_quality_gate_settings.default_state`): `required` runs always (NO decision — auto-on); `optional` REQUIRES a decision here (unanswered → the create 400s); `disabled` never runs (NO decision). Omit this only on a board with no optional gates; otherwise the 400 body\'s `required_gate_decisions` lists exactly which gates to answer — retry with {enabled, note} for each. A decision naming a non-optional gate is rejected 400. DX-1760: each entry also takes an OPTIONAL `effort_level` — a per-`(card, gate)` reviewer-rung override for a `plan-*` gate, persisted at seed time; omit for no override.'),
     phase_children: z
         .array(z.object({
         type: z.enum(NON_EPIC_TYPES),
@@ -206,15 +207,16 @@ server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-sco
             gate: z.string().min(1),
             enabled: z.boolean(),
             note: z.string(),
+            effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
         }))
             .optional()
-            .describe("Per-child fail-closed gate decisions — same shape + rule as the root gate_decisions, resolved against THIS child's own type. Required when the child's type has board-optional gates."),
+            .describe("Per-child fail-closed gate decisions — same shape + rule as the root gate_decisions (incl. the optional per-gate effort_level, DX-1760), resolved against THIS child's own type. Required when the child's type has board-optional gates."),
     }))
         .optional(),
     ...boardField,
 }, async (args) => jsonResult(await issueCreate(client, args, config.board)));
 // ---------------- issue_edit ----------------
-server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues/:id/edit. ALLOWED keys: title, description, ac, checklists, effort_level, parent_id, priority, list_id. ANY OTHER KEY (lifecycle timestamps, triage state, dependencies, retro, requires_human, blocked/dispatch gates) returns 400 with offending_keys[] and a pointer to the dedicated semantic handler — use issue_transition / issue_triage / issue_comment / issue_dependency / issue_requires_human / issue_retro instead. PRIORITY (DX-1532): set card priority via the `priority` key — a tier WORD ("lowest"/"low"/"medium"/"high"/"very_high"/"critical", resolved to the tier midpoint) OR a raw number in [0,6). This is the ONLY way to change priority: the numeric `issues.priority` column is what the Trello priority label AND the dashboard badge read — editing a "Priority: <x>" line in the DESCRIPTION changes nothing downstream (a silent false-positive). To honor a "set priority" request, write `priority` here, do NOT edit description prose. CHECKLISTS (DX-1290): a card carries 0..N named checklists, each item ONE 4-state status `incomplete|failing|passing|cancelled` (terminal = passing|cancelled). `ac` is the 2-state CONVENIENCE onto the default "Acceptance Criteria" checklist (checked:true ↔ passing, false ↔ incomplete) — wholesale soft-delete + reinsert of that checklist\'s items. `checklists` is the GENERIC wholesale write path: it REPLACES every named checklist on the card with full 4-state control (each `{name, items:[{label, detail?, status}]}`) — use it to author named checklists like "Feature Tests". Send EITHER `ac` OR `checklists`, NOT both (400). list_id (DX-1192 / DX-1200) PINS the card to a specific board list. **Pass EITHER a board_lists id OR the list\'s display NAME (case-insensitive, e.g. a queue name like "⚙️ Fulfillment Queue") — the server resolves a name to its id.** Its type MUST match the card\'s CURRENT derived-status list-type (so to route a ToDo card into a `ready`-type queue, ready it first; mismatch / unknown name or id → 400); pass null to clear the pin (back to default-for-type).', {
+server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues/:id/edit. ALLOWED keys: title, description, ac, checklists, effort_level, parent_id, priority, list_id, triage_enabled. ANY OTHER KEY (lifecycle timestamps, triage state, dependencies, retro, requires_human, blocked/dispatch gates) returns 400 with offending_keys[] and a pointer to the dedicated semantic handler — use issue_transition / issue_triage / issue_comment / issue_dependency / issue_requires_human / issue_retro instead. PRIORITY (DX-1532): set card priority via the `priority` key — a tier WORD ("lowest"/"low"/"medium"/"high"/"very_high"/"critical", resolved to the tier midpoint) OR a raw number in [0,6). This is the ONLY way to change priority: the numeric `issues.priority` column is what the Trello priority label AND the dashboard badge read — editing a "Priority: <x>" line in the DESCRIPTION changes nothing downstream (a silent false-positive). To honor a "set priority" request, write `priority` here, do NOT edit description prose. CHECKLISTS (DX-1290): a card carries 0..N named checklists, each item ONE 4-state status `incomplete|failing|passing|cancelled` (terminal = passing|cancelled). `ac` is the 2-state CONVENIENCE onto the default "Acceptance Criteria" checklist (checked:true ↔ passing, false ↔ incomplete) — wholesale soft-delete + reinsert of that checklist\'s items. `checklists` is the GENERIC wholesale write path: it REPLACES every named checklist on the card with full 4-state control (each `{name, items:[{label, detail?, status}]}`) — use it to author named checklists like "Feature Tests". Send EITHER `ac` OR `checklists`, NOT both (400). list_id (DX-1192 / DX-1200) PINS the card to a specific board list. **Pass EITHER a board_lists id OR the list\'s display NAME (case-insensitive, e.g. a queue name like "⚙️ Fulfillment Queue") — the server resolves a name to its id.** Its type MUST match the card\'s CURRENT derived-status list-type (so to route a ToDo card into a `ready`-type queue, ready it first; mismatch / unknown name or id → 400); pass null to clear the pin (back to default-for-type).', {
     id: z.string().min(1),
     title: z.string().min(1).optional(),
     description: z.string().optional(),
@@ -241,6 +243,10 @@ server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues
         .optional()
         .describe('Card priority (DX-1532). A tier WORD ("lowest"/"low"/"medium"/"high"/"very_high"/"critical") resolved to the tier midpoint, OR a raw number in [0,6). Writes the numeric `issues.priority` column the Trello label + dashboard badge read — set priority HERE, never via description prose (which no system reads for priority).'),
     list_id: z.string().min(1).nullable().optional(),
+    triage_enabled: z
+        .boolean()
+        .optional()
+        .describe("DX-1895 — per-card opt-in for the DX-1886 auto-triage dispatcher. false (default) = the automatic dispatcher trigger never selects this card, even when every other eligibility condition holds. Operator-directed POST /api/triage and direct issue_triage calls are NOT gated by this flag."),
     ...boardField,
 }, async (args) => jsonResult(await issueEdit(client, args)));
 // ---------------- issue_transition ----------------
@@ -320,7 +326,7 @@ server.tool("issue_requires_human", "Set or clear the requires_human dispatch ga
     ...boardField,
 }, async (args) => jsonResult(await issueRequiresHuman(client, args)));
 // ---------------- issue_quality_gate ----------------
-server.tool("issue_quality_gate", "Toggle a single card's per-card quality-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the SAME write the dashboard drawer's Quality Gates tab performs (DX-1181). This is the ONLY post-create way to mark a gate required/not-required: `issue_create` carries `gate_decisions` at birth, and `issue_edit` REJECTS gate keys (400 offending_keys) — without this tool a card created without a gate can never have it turned on by an agent. `gate` is a registry name: `plan-dependency` | `plan-architecture` | `plan-tdd` | `code-test-quality` | `code-architecture` | `code-quality` (the PRE/plan- gates run before the work dispatch; the POST/code- gates block issue_transition complete). Unknown gate → 400 (never a silent no-op); a card with no seeded row for a registered gate → 500 (canonical corruption). NOTE board requirement is TRI-STATE per gate (`board_quality_gate_settings.default_state`, the Agents-tab surface), NOT a binary on/off: `required` = gate always runs (this flag irrelevant); `optional` = gate runs WHEN this per-card flag is true (per-card opt-in — `optional` is ENABLED, NOT off); `disabled` = never runs (this flag inert). So flipping `required:true` here LAUNCHES the gate when the board state is `required` OR `optional`; it is inert ONLY when the board state is `disabled`. Do not read `optional` as off. (Source of truth: `isGateEffectivelyRequired` in `src/issues/quality-gates/read.ts`.) Returns the hydrated issue. Board-scoped; pass `board` (`<repo>:<slug>`) to target another board.", {
+server.tool("issue_quality_gate", "Toggle a single card's per-card quality-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the SAME write the dashboard drawer's Quality Gates tab performs (DX-1181). This is the ONLY post-create way to mark a gate required/not-required: `issue_create` carries `gate_decisions` at birth, and `issue_edit` REJECTS gate keys (400 offending_keys) — without this tool a card created without a gate can never have it turned on by an agent. `gate` is a registry name: `plan-dependency` | `plan-architecture` | `plan-tdd` | `code-test-quality` | `code-architecture` | `code-quality` (the PRE/plan- gates run before the work dispatch; the POST/code- gates block issue_transition complete). Unknown gate → 400 (never a silent no-op); a card with no seeded row for a registered gate → 500 (canonical corruption). NOTE board requirement is TRI-STATE per gate (`board_quality_gate_settings.default_state`, the Agents-tab surface), NOT a binary on/off: `required` = gate always runs (this flag irrelevant); `optional` = gate runs WHEN this per-card flag is true (per-card opt-in — `optional` is ENABLED, NOT off); `disabled` = never runs (this flag inert). So flipping `required:true` here LAUNCHES the gate when the board state is `required` OR `optional`; it is inert ONLY when the board state is `disabled`. Do not read `optional` as off. (Source of truth: `isGateEffectivelyRequired` in `src/issues/quality-gates/read.ts`.) DX-1760: optionally pass `effort_level` — a per-`(card, gate)` reviewer-rung override for a `plan-*` gate, written alongside `required`; omit to leave it untouched, pass `null` to clear a prior override. Returns the hydrated issue. Board-scoped; pass `board` (`<repo>:<slug>`) to target another board.", {
     id: z.string().min(1),
     gate: z.enum([
         "plan-dependency",
@@ -331,6 +337,7 @@ server.tool("issue_quality_gate", "Toggle a single card's per-card quality-gate
         "code-quality",
     ]),
     required: z.boolean(),
+    effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
     ...boardField,
 }, async (args) => jsonResult(await issueQualityGate(client, args)));
 // ---------------- issue_retro ----------------
@@ -382,10 +389,10 @@ async function main() {
 // Boot the stdio server ONLY when run as the entrypoint (the published bin).
 // Importing this module (the tool-defs generator + its drift test) registers
 // the tools on `server` without reading env or attaching stdin — so the
-// schemas can be introspected without spawning a dispatch.
-const isEntrypoint = typeof process.argv[1] === "string" &&
-    import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isEntrypoint) {
+// schemas can be introspected without spawning a dispatch. The check is
+// symlink-aware (DX-1647) so it holds under the symlinked `npx` bin the worker
+// spawns, not just a direct `node dist/index.js`.
+if (isEntrypointModule(import.meta.url, process.argv[1])) {
     main().catch((err) => {
         console.error(`[danx-dashboard-mcp] fatal: ${err.message}`);
         process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "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",
@@ -22,6 +22,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
+    "verify:boot": "bash scripts/verify-boot.sh",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
     "gen-tool-defs": "tsx scripts/gen-tool-defs.ts",

package/dist/handlers.test.js

@@ -1,51 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { DashboardHttpClient } from "./http-client.js";
-import { issueList, issueTransition } from "./handlers.js";
-/**
- * `issue_list` query-param forwarding. A fake `fetch` captures the built
- * URL so each filter is asserted at the wire, through the real client's
- * URL builder (`?repo=` always stamped, extra query merged after).
- */
-function clientCapturing() {
-    const urls = [];
-    const fetchImpl = (async (url) => {
-        urls.push(url);
-        return new Response(JSON.stringify({ issues: [] }), { status: 200 });
-    });
-    const client = new DashboardHttpClient({ baseUrl: "http://localhost:5555", repo: "danxbot", token: "t" }, fetchImpl);
-    return { client, urls };
-}
-describe("issueList — query forwarding", () => {
-    it("forwards q as the server-side search needle", async () => {
-        const { client, urls } = clientCapturing();
-        await issueList(client, { q: "retire" });
-        expect(urls[0]).toContain("q=retire");
-    });
-    it("omits q when not provided", async () => {
-        const { client, urls } = clientCapturing();
-        await issueList(client, { include_closed: true });
-        expect(urls[0]).not.toContain("q=");
-        expect(urls[0]).toContain("include_closed=true");
-    });
-});
-describe("issueTransition — body forwarding", () => {
-    function clientCapturingBody() {
-        const bodies = [];
-        const fetchImpl = (async (_url, init) => {
-            bodies.push(JSON.parse(String(init?.body ?? "{}")));
-            return new Response(JSON.stringify({ issue: {} }), { status: 200 });
-        });
-        const client = new DashboardHttpClient({ baseUrl: "http://localhost:5555", repo: "danxbot", token: "t" }, fetchImpl);
-        return { client, bodies };
-    }
-    it("forwards manual: true on pickup (DX-946 operator self-pickup)", async () => {
-        const { client, bodies } = clientCapturingBody();
-        await issueTransition(client, { id: "DX-1", action: "pickup", manual: true });
-        expect(bodies[0]).toEqual({ action: "pickup", manual: true });
-    });
-    it("omits manual when not provided", async () => {
-        const { client, bodies } = clientCapturingBody();
-        await issueTransition(client, { id: "DX-1", action: "pickup" });
-        expect(bodies[0]).toEqual({ action: "pickup" });
-    });
-});