@thehammer/danx-dashboard-mcp 0.1.162 → 0.1.164

package/README.md

@@ -15,42 +15,20 @@ Each tool is a thin envelope over one HTTP route — Zod-validated at the MCP bo
 
 BOARD-ONLY (DX-1171): board is the first-level concept; repo is DERIVED from board server-side, never passed. At boot the package composes the dispatch's qualified board id `<repo>:<slug>` from `DANX_REPO_NAME` + `DANXBOT_BOARD_NAME` and appends it as `?board=<id>` (and `body.board` on create) to every `/api/issues/*` request. Each tool exposes an optional `board` arg — a FULL qualified id `<repo>:<slug>` (e.g. `platform:the-supply-operations-hub`) — that overrides it per-call for cross-board reads/writes (unknown board → 404). The dashboard owns board→repo resolution; this package never sends `repo`.
 
-## Tool surface
+## Tool surface (DX-3465 — one generic tool, not one per operation)
 
-All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `mcp.template.json`.
+All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `mcp.template.json`. There is no per-operation tool any more (no `issue_get`, `issue_create`, `plan_add_note`, …) — three tools cover the whole dashboard API:
 
-| Tool | HTTP | Notes |
-|---|---|---|
-| `issue_list` | `GET /api/issues` | filters: `type`, `parent_id` (null → root-only), `dispatchable_derived`, `assigned_agent`, `include_closed`, `limit`, `offset`. `fields` (DX-3427) is the SAME recursive field tree `issue_get` takes, against the same issue resource — list-row fields (`ac_total`, `comments_count`, `waiting_on`, `quality_gates`, `next_pre_gate`, …) sit alongside every detail field. See `resource_fields` |
-| `issue_get` | `GET /api/issues/:id` or `GET /api/issues/batch` | Pass `id` for one card, or `ids[]` (DX-2727, at most 100) to resolve many across boards in ONE call — global, so `ids` with `board` throws; per-id `not_found` rather than a whole-call 404. Minimal scalars by default; `fields` (DX-3426) opts in via a recursive field TREE — `{"description": true, "problems": {"solutions": true}, "comments": {"limit": 10}}` — not a flat group list; a cursor-paged relation (today only `comments`) takes its page args (`limit`/`before`) inside its own nested object, so paging now works on the batch form too. See `resource_fields` |
-| `resource_fields` | `GET /api/resources/:resource/fields` | DX-3426 — what an `issue_get`-style field tree may name for one resource: `{resource, description, always, hashes, fields, relations}`. Install-global, no `board`. `resource: "issue"` is the root; a relation's own `resource` in the response is what to call this again with, one level deeper |
-| `issue_create` | `POST /api/issues` | Epic REQUIRES non-empty `phase_children[]` (atomic insert). `title` = short domain-naming label; `summary` = 1–3 plain-language sentences, always shown; `description` = the collapsed "Context" body. Root and every phase child take their own `summary` |
-| `issue_edit` | `PATCH /api/issues/:id/edit` | Prose + structured keys (`title`, `summary` (null clears), `description`, `ac`, `checklists`, `effort_level`, `parent_id`, `priority`, `list_id`); semantic keys refused with 400 + pointer to dedicated handler. `priority` (DX-1532) takes a tier word (`low`/`high`/…) or a number in `[0,6)` — the ONLY way to set the numeric column the Trello label + dashboard badge read; never set priority via description prose |
-| `issue_transition` | `POST /api/issues/:id/transition` | Actions: ready, pickup, rollback_pickup, complete, cancel, block, unblock, archive, reopen. `block` is a dispatch hold only — it never marks the card as needing a human; use `issue_problem` add for that |
-| `issue_problem` | `GET/POST/PATCH/DELETE /api/issues/:id/problems[/:pid]` + `POST .../answer`, `change-answer`, `unanswer` | Actions list / add / edit / remove / answer / change_answer / unanswer (DX-3471). A problem is one statement the operator must resolve (a question or a plan flaw) with its own solutions and answers; `add` takes `statement` + optional `solutions[]` in one transaction and IS what puts the card in front of a human (`open_problem_count > 0`) — a successful add also returns a `reminders: [{key, text}]` array (DX-3365 — the reminder registry's middleware, DB-driven and operator-overridable from the dashboard). Edit + remove are hash-guarded (`base_hash`, 409 `stale_problem`); removing the card's last open problem is always allowed — it just means the card no longer needs a human. `answer` `{solution_id, note?}` \| `{freeform}` and `change_answer` (same + `base_hash` naming the live DECISION) / `unanswer` (`{base_hash}`) record or retract an operator's decision — server-refused 403 for a dispatched agent's machine credential (DX-2830), reachable from an OPERATOR SESSION relaying an in-chat decision, which also durably records the relaying session (`relayed_by_session`) via the same session header every call already carries |
-| `issue_solution` | `POST/PATCH/DELETE /api/issues/:id/problems/:pid/solutions[/:sid]` | Actions add / edit / remove, `problem_id` required (list via `issue_problem list`). Edit + remove are hash-guarded (`base_hash`, 409 `stale_solution` with the current row); at most one live `recommended` per problem; a chosen option cannot be edited. No answer action on THIS tool — see `issue_problem`'s answer / change_answer / unanswer actions |
-| `issue_triage` | `POST /api/issues/:id/triage` | Send `{confidence, reason}` — an integer 0-5 score; the server computes the verdict (approve/cancel/keep/defer) against the board's configured thresholds (DX-2086). `keep`/`defer` now block the card. None of these are a cross-card ordering gate; use `issue_dependency` to sequence cards |
-| `issue_comment` | `POST/PATCH/DELETE /api/issues/:id/comments[/:cid]` | Author server-stamped, soft-delete preserved |
-| `issue_dependency` | `POST/DELETE /api/issues/:id/dependencies[/:did]` | `depends_on` cycle-checked; remove hardcodes `reason: "recorded_in_error"`. The only mechanism the dispatch picker enforces to sequence one card after another — status alone is not a substitute |
-| `issue_retire_branch` | `POST /api/issues/:id/card-branch-retire` | Mark this card's own `card/<id>` branch RETIRED (unsafe to merge) — `{reason}`, `by` server-stamped. NO status/terminal gate (DX-2845): settable the instant an audit/split judges the branch unsafe, whatever the card's status. The dispatched worker reads this at its next bootstrap and forces `origin/main` instead of re-attaching to the retired content |
-| `issue_retro` | `PUT /api/issues/:id/retro` | Requires terminal card; replace semantics. `correctable_danxbot_problem` + `correctable_danxbot_problem_description` (DX-2794) are REQUIRED on every write, like `tests[]` — answer honestly whether THIS dispatch hit a fixable problem in danxbot's own code/configuration (not "the card was hard"); a true+described retro starts exactly one automated repair |
-
-## `plan_get` — cheap by default, opt-in for the rest (DX-2727)
-
-A bare `plan_get` (no `fields`) returns only the plan's cheap scalars — `plan`, `boards`, `cardCount`, `bucketCounts`, `status`, `session`, `sessionListenerAttached` — plus `available_field_groups` naming what else exists. Pass `fields` to opt into `cards` (paged: `cards_offset`, default 0, and `cards_limit`, 1..1000, default 200, pick the page; the response carries `cards_total` and `cards_offset`, so page with `cards_offset` while `cards_offset + cards.length < cards_total` — either paging arg without `cards` in `fields` is a 400), `records` (every goal/rule/caveat) or `records:goal` / `records:rule` / `records:caveat` (just one kind), `architecture`, and `sessions`. A `plan_get` made only to grab a hash before a one-line edit no longer pays for the architecture document or every member card.
-
-## `plan_list` / `plan_get` — computed `status` (DX-2834)
-
-Every plan carries a `status`, computed fresh on every read and never stored — no writer ever sets it:
-
-| Status | Meaning |
+| Tool | Purpose |
 |---|---|
-| `complete` | At least one card, and every card Done or Cancelled. Wins even with no session — a finished plan needs nobody. |
-| `awaiting-session` | Not complete, and no session is LIVE on the plan. A `plan_sessions` row is never released when a session merely ends (only when the plan itself is deleted), so this checks real liveness — `last_active_at` within the last minute — never just "has a session ever connected". A working session's event stream stamps that activity every 15 seconds on its own, so an open, idle session stays live with no tool calls. |
-| `building` | Not complete, a live session is connected, and at least one card is ToDo/In Progress, or carries an unnamed active state (Blocked, Needs Help — i.e. an OPEN problem, DX-2830 — and, once it exists, Verify): work started and is either moving or stuck. |
-| `planning` | Everything else: no cards, or only Review/Backlog/terminal cards with at least one not Done/Cancelled. |
+| `danxbot_api` | `{method, path, query?, body?}` — calls any dashboard route the caller's credential may reach (card/plan CRUD, comments, dependencies, problems/solutions, quality gates, retro, triage, transitions, …). Returns `{ok, status, body}`; `body` carries the route's own response, or its structured error verbatim when `ok:false`. |
+| `danxbot_api_list` | No args. Lists the routes this caller's credential may reach, one line each (`{method, path, summary, permission}`) — call this first when you don't know the route for what you need to do. |
+| `danxbot_api_spec` | `{endpoints}` (comma-joined `METHOD /path` list, required, min 1). Returns the exact OpenAPI contract for those routes — call this when you know the route but not its exact request/response shape. |
+| `resource_fields` | `GET /api/resources/:resource/fields` — what an opt-in field TREE may name for one resource: `{resource, description, always, hashes, fields, relations}`. Install-global, no `board`. `resource: "issue"` is the root; a relation's own `resource` in the response is what to call this again with, one level deeper. |
+
+A dedicated tool survives only for something about the agent itself, never a card/plan operation: `plan_connect` (binds the session to a plan; the event-bridge hook keys on it) and the per-dispatch worker callbacks (`danxbot_complete`, `danxbot_slack_reply`, `danxbot_slack_post_update`, `load_template_app`/`save_template_app`, `quality_gate_complete`, `link_thread_to_issue`, `attach_file`, the `slack_recovery_*` trio, `danxbot_set_evaluator_summary`) — see `src/lifecycle.ts`. The live list is always `tool-defs.json` in this package, regenerated by `npm run gen-tool-defs` — read it rather than trusting a list copied into prose.
 
-Evaluated in that order (`complete` > `awaiting-session` > `building` > `planning`) — first match wins. `plan_list` takes an optional `status` arg to filter to one of them (`GET /api/plans?status=`); `plan_get` always returns the one plan's own status, ungated.
+Card and plan reads/writes go through `danxbot_api` against the issue/plan route families documented in `GET /api/openapi` (via `danxbot_api_spec`) — `POST /api/issues`, `GET /api/issues/:id` (or `/batch` for many at once, DX-2727), `PATCH /api/issues/:id/edit`, `POST /api/issues/:id/transition`, the problems/solutions/dependencies/comments/quality-gates/retro sub-resource routes, and the equivalent `/api/plans/*` family (`GET /api/plans/:planId` — cheap scalars by default, `fields` opts into `cards`/`records`/`architecture`/`sessions`; `GET /api/plans` for the list, with an optional `status` filter over the same computed `complete`/`awaiting-session`/`building`/`planning` value `GET /api/plans/:planId` always returns ungated).
 
 ## `bridge` — a working session's event stream client
 

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/event-text.js

@@ -0,0 +1,137 @@
+/**
+ * `danx-dashboard-mcp event-text <event>` — the ONE-SHOT client of
+ * `GET /api/reminders/event/<event>` (DX-3421).
+ *
+ * WHO RUNS IT. The claude-plugins `danxbot` plugin's single event hook
+ * (`event-hook.sh`, SessionStart matcher "startup|resume|compact" plus
+ * SubagentStart matcher ".*") — replaces the old `mantra` subcommand's ONE
+ * consumer, `mantra.sh` (deleted, DX-3421, along with
+ * `plan-workflow-autoload.sh` and `compaction-skill-reload.sh`; all three
+ * collapse into the one hook + this one subcommand). `<event>` is one of
+ * `session_start` | `session_resume` | `after_compaction` |
+ * `sub_agent_start` — the SAME `npx -y @thehammer/danx-dashboard-mcp@<pin>`
+ * path the plugin's other dashboard calls already use (`plan-state`,
+ * `bridge`) — never a separate install, never a deep import of this
+ * package's `dist/` internals.
+ *
+ * THE CREDENTIAL — the SAME resolver `bridge` / `plan-state` use
+ * (`resolveBridgeOptions`, `bridge.ts`): the dashboard URL, credential source
+ * and credential all come from the connection record this session's OWN
+ * danx-dashboard MCP server wrote on its last successful `plan_connect`
+ * (`session-connection.ts`), never from this process's own ambient env. This
+ * is only ever called once a session is already connected (`event-hook.sh`
+ * checks that first via `plan-connection.mjs` and stays completely silent
+ * otherwise — DX-3421 comment 7748/7752 verdict: no output at all before a
+ * plan is connected), so a connection record always exists by the time this
+ * runs.
+ *
+ * THE CONTRACT — `event-hook.sh` needs to tell success from failure so it
+ * can print the operator-facing "could not load" notice (DX-3421 AC: no
+ * committed offline fallback exists any more — a fetch failure is ALWAYS
+ * reported to the agent, never silently swallowed and never a `mantra.md`
+ * reread). So:
+ *
+ *   - success: the event's EFFECTIVE text on stdout, nothing else, exit 0.
+ *   - failure (missing env, no connection record, network error, timeout,
+ *     non-2xx, 404, bad shape): NOTHING on stdout, one short reason on
+ *     stderr, exit 1. `event-hook.sh` is the one that decides what to print
+ *     for the agent — this module only reports whether the fetch worked.
+ *
+ * A HARD TIMEOUT (mirrors `plan-state.ts`) — a SessionStart hook must never
+ * hang on a wedged dashboard.
+ */
+import { SESSION_ID_HEADER, resolveBridgeOptions } from "./bridge.js";
+export const EVENT_TEXT_SUBCOMMAND = "event-text";
+export const EVENT_TEXT_REQUEST_TIMEOUT_MS = 5_000;
+const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${EVENT_TEXT_SUBCOMMAND} <event>`;
+function eventPath(event) {
+    return `/api/reminders/event/${encodeURIComponent(event)}`;
+}
+/** One authenticated GET, with a hard timeout — never throws, never bubbles a non-2xx. */
+export async function fetchEventText(event, options, deps) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.requestTimeoutMs);
+    let status;
+    let text;
+    try {
+        try {
+            const response = await deps.fetch(`${options.dashboardUrl}${eventPath(event)}`, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${options.token}`,
+                    Accept: "application/json",
+                    [SESSION_ID_HEADER]: options.sessionId,
+                },
+                signal: controller.signal,
+            });
+            status = response.status;
+            text = await response.text();
+        }
+        catch {
+            return { ok: false, reason: controller.signal.aborted ? "timeout" : "request_failed" };
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (status === 401 || status === 403)
+        return { ok: false, reason: "unauthorized" };
+    if (status === 404)
+        return { ok: false, reason: "not_found" };
+    if (status < 200 || status >= 300)
+        return { ok: false, reason: "http_error" };
+    let body;
+    try {
+        body = text === "" ? null : JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: "bad_response" };
+    }
+    const effectiveText = typeof body === "object" &&
+        body !== null &&
+        typeof body.effective_text === "string"
+        ? body.effective_text
+        : null;
+    if (effectiveText === null)
+        return { ok: false, reason: "bad_response" };
+    return { ok: true, text: effectiveText };
+}
+/**
+ * The bin's `event-text` subcommand, wired to the real process. Success
+ * prints the effective text on stdout and returns 0; every failure prints
+ * nothing on stdout, one reason on stderr, and returns 1 — `event-hook.sh`
+ * reads the exit code, never parses stdout to guess.
+ */
+export async function runEventTextCommand(argv, env = process.env, 
+/** Test seam: the home the session's connection record is read from. */
+resolveFrom = {}) {
+    const [event, ...rest] = argv;
+    if (rest.length !== 0 || typeof event !== "string" || event === "") {
+        process.stderr.write(`missing or extra arguments\n${USAGE}\n`);
+        return 1;
+    }
+    const sessionId = env.CLAUDE_CODE_SESSION_ID;
+    if (!sessionId) {
+        process.stderr.write(`no_session_id: CLAUDE_CODE_SESSION_ID is not set\n${USAGE}\n`);
+        return 1;
+    }
+    let options;
+    try {
+        options = resolveBridgeOptions({ sessionId, resumeIds: [] }, env, resolveFrom);
+    }
+    catch (err) {
+        const start = err;
+        process.stderr.write(`${start.reason}: ${start.message}. Fix: ${start.fix}.\n`);
+        return 1;
+    }
+    const output = await fetchEventText(event, options, {
+        fetch: (input, init) => fetch(input, init),
+        requestTimeoutMs: EVENT_TEXT_REQUEST_TIMEOUT_MS,
+    });
+    if (!output.ok) {
+        process.stderr.write(`${output.reason}: could not fetch the effective "${event}" text from the dashboard\n`);
+        return 1;
+    }
+    process.stdout.write(output.text);
+    return 0;
+}

package/dist/field-tree.js

@@ -1,8 +1,9 @@
 /**
  * DX-3426 — the shared recursive FIELD-TREE shape.
  *
- * The dashboard's single-card, batch card and plan reads (`issue_get`,
- * `issue_list`, `plan_get` — DX-3428) take a nested JSON tree instead of a
+ * The dashboard's single-card, batch card and plan reads (`danxbot_api`
+ * against `GET /api/issues/:id`, `GET /api/issues`, `GET /api/plans/:planId`
+ * — DX-3428) take a nested JSON tree instead of a
  * flat field-GROUP list: each key names a field or relation of the resource
  * at that level, and each value is either `true` (the field, or a relation's
  * child with its default fields), a non-negative integer (a cursor-paged
@@ -24,8 +25,8 @@
  * self-reference to a local `$ref` rather than unrolling it infinitely —
  * verified directly against the listed tool schema in
  * `__tests__/tool-defs.test.ts`, not assumed from reading the library's
- * source. `issue_solution`'s pre-existing `steps` field (DX-3310) is the
- * same `z.lazy` self-reference pattern already shipping on this server.
+ * source. The problem-solutions route's pre-existing `steps` field (DX-3310)
+ * is the same `z.lazy` self-reference pattern already shipping on this server.
  */
 import { z } from "zod";
 /**