@thehammer/danx-dashboard-mcp 0.1.285 → 0.1.287

package/dist/ready-cards.js

@@ -1,176 +0,0 @@
-/**
- * `danx-dashboard-mcp ready-cards` — DX-4534. The ONE-SHOT client the claude-plugins `danxbot`
- * plugin's Stop hook runs for a plan-connected session, to learn which of its plan's cards
- * anyone could pick up right now.
- *
- * WHY IT EXISTS. An orchestrating plan session must keep every unblocked card moving, and
- * nothing enforced it: on 2026-10-04 one builder ran while two readied, unblocked cards sat
- * untouched, because the session only looked for work when a builder reported back. The Stop
- * hook turns that check into something the harness runs. This is its read.
- *
- * NO DASHBOARD ROUTE IS ADDED. It composes existing reads on the session's own credential:
- *   1. `GET /api/plans/mine` answers the session's plan (`id`) and the boards its cards live on
- *      (`boards`) in one read; a session on no plan is a 409 `session_not_connected`.
- *   2. `GET /api/issues?board=<b>` with `filter.plan_id` + `filter.status_derived=ToDo` and the
- *      judged fields, once per board: a plan can span boards (PLAN-11 spans danxbot and
- *      gpt-manager), and an issues read without `board` sees only the default one.
- * Server-side filtering narrows the read; `isReadyCard` is the whole definition of "ready".
- *
- * READY means a card a dispatcher or a session could claim this minute: a Story, Bug or Chore
- * (Epic and Feature are containers, a Task is a leaf nobody dispatches), derived status ToDo,
- * nobody holding it (no assigned agent, no live dispatch), and nothing in its way: no hold
- * (`blocked`), no open problem (a human is needed), no unmet `depends_on`, no active
- * `conflict_on`. A card whose reason it cannot run is recorded on it therefore stops counting,
- * which is how the hook's "dispatch it, or record why not" instruction is satisfiable.
- *
- * THE CONTRACT, which the hook reads by exit code:
- *   - exit 0, one JSON line on stdout: `{"plan_id": <n|null>, "cards": [{"id","title"}...]}`;
- *     `plan_id` null (the dashboard has the session on no plan) comes with an empty list.
- *   - exit 1, one reason on stderr, nothing on stdout: credential, network, non-2xx, bad shape.
- */
-import { resolveSessionOptions, sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
-export const READY_CARDS_SUBCOMMAND = "ready-cards";
-export const READY_CARDS_REQUEST_TIMEOUT_MS = 5_000;
-/** `GET /api/issues` page size (its maximum): a plan's ToDo cards never approach it. */
-const CARDS_PAGE_SIZE = 1000;
-/** The dispatchable card types: Epic and Feature are containers, a Task is a leaf nobody dispatches. */
-const DISPATCHABLE_TYPES = new Set(["Story", "Bug", "Chore"]);
-/**
- * The fields `isReadyCard` judges beyond the always-returned row, each with the check a row's value
- * must pass: the one list the request's `fields` tree and the row parse both come from.
- */
-const JUDGED_FIELDS = {
-    dispatch: (v) => v !== undefined,
-    blocked: (v) => v !== undefined,
-    open_problem_count: (v) => typeof v === "number",
-    waiting_on: (v) => typeof v === "boolean",
-    conflict_on_active_count: (v) => typeof v === "number",
-};
-const CARD_FIELDS = Object.fromEntries(Object.keys(JUDGED_FIELDS).map((name) => [name, true]));
-const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${READY_CARDS_SUBCOMMAND}`;
-/** The row, or null when any field `isReadyCard` judges is missing or the wrong type: a card never counts on a guess. */
-function parseCardRow(raw) {
-    if (typeof raw !== "object" || raw === null)
-        return null;
-    const r = raw;
-    const assigned = r.assigned_agent;
-    if (typeof r.id !== "string" || typeof r.type !== "string" || typeof r.title !== "string")
-        return null;
-    if (!(assigned === null || typeof assigned === "string"))
-        return null;
-    if (!Object.entries(JUDGED_FIELDS).every(([name, valid]) => valid(r[name])))
-        return null;
-    return r;
-}
-/** Whether a ToDo card could be claimed right now (see the module banner). */
-export function isReadyCard(card) {
-    return (DISPATCHABLE_TYPES.has(card.type) &&
-        card.assigned_agent === null &&
-        card.dispatch === null &&
-        card.blocked === null &&
-        card.open_problem_count === 0 &&
-        !card.waiting_on &&
-        card.conflict_on_active_count === 0);
-}
-function classifyStatus(status) {
-    if (status === 401 || status === 403)
-        return "unauthorized";
-    if (status === 404)
-        return "not_found";
-    if (status < 200 || status >= 300)
-        return "http_error";
-    return null;
-}
-/** The session's plan and its boards, `null` when the dashboard has the session on no plan, or a failure. */
-async function readSessionPlan(options, deps) {
-    const sent = await sendSessionRequest(options, "/api/plans/mine", { method: "GET" }, deps);
-    if ("ok" in sent)
-        return sent;
-    const parsed = tryParseJsonBody(sent.text);
-    const body = parsed.ok ? parsed.body : null;
-    // A session on no plan is the ordinary answer, not a fault: a 409 `session_not_connected`.
-    if (sent.status === 409 && body?.error === "session_not_connected")
-        return { ok: true, plan: null };
-    const failed = classifyStatus(sent.status);
-    if (failed !== null)
-        return { ok: false, reason: failed };
-    if (body === null ||
-        typeof body.id !== "number" ||
-        !Array.isArray(body.boards) ||
-        !body.boards.every((b) => typeof b === "string")) {
-        return { ok: false, reason: "bad_response" };
-    }
-    return { ok: true, plan: { planId: body.id, boards: body.boards } };
-}
-/** The plan's ready cards on one board. */
-async function readBoardReadyCards(options, deps, planId, board) {
-    const filter = encodeURIComponent(JSON.stringify({ plan_id: planId, status_derived: "ToDo" }));
-    const fields = encodeURIComponent(JSON.stringify(CARD_FIELDS));
-    const sent = await sendSessionRequest(options, `/api/issues?board=${encodeURIComponent(board)}&filter=${filter}&fields=${fields}&limit=${CARDS_PAGE_SIZE}&sort=priority`, { method: "GET" }, deps);
-    if ("ok" in sent)
-        return sent;
-    const failed = classifyStatus(sent.status);
-    if (failed !== null)
-        return { ok: false, reason: failed };
-    const parsed = tryParseJsonBody(sent.text);
-    const body = parsed.ok ? parsed.body : null;
-    if (body === null || !Array.isArray(body.issues) || typeof body.total !== "number")
-        return { ok: false, reason: "bad_response" };
-    // A truncated read would silently miss ready cards: fail loudly instead.
-    if (body.total > body.issues.length)
-        return { ok: false, reason: "too_many_cards" };
-    const cards = [];
-    for (const raw of body.issues) {
-        const row = parseCardRow(raw);
-        if (row === null)
-            return { ok: false, reason: "bad_response" };
-        if (isReadyCard(row))
-            cards.push({ id: row.id, title: row.title });
-    }
-    return { ok: true, cards };
-}
-/** One authenticated read of the session's plan's ready cards, across every board the plan spans. Never throws. */
-export async function fetchReadyCards(options, deps) {
-    const read = await readSessionPlan(options, deps);
-    if (!read.ok)
-        return read;
-    if (read.plan === null)
-        return { ok: true, planId: null, cards: [] };
-    const { planId } = read.plan;
-    const perBoard = await Promise.all(read.plan.boards.map((board) => readBoardReadyCards(options, deps, planId, board)));
-    const cards = [];
-    for (const onBoard of perBoard) {
-        if (!onBoard.ok)
-            return onBoard;
-        cards.push(...onBoard.cards);
-    }
-    return { ok: true, planId: read.plan.planId, cards };
-}
-/** The bin's `ready-cards` subcommand, wired to the real process. */
-export async function runReadyCardsCommand(argv, env = process.env, 
-/** Test seams: the home the connection record is read from, and the HTTP client. */
-seams = {}) {
-    if (argv.length !== 0) {
-        process.stderr.write(`unexpected arguments\n${USAGE}\n`);
-        return 1;
-    }
-    // `resolveSessionOptions` words a missing session id as the usage text alone; every stderr line here starts with its reason.
-    if (!env.CLAUDE_CODE_SESSION_ID) {
-        process.stderr.write(`no_session_id: CLAUDE_CODE_SESSION_ID is not set\n${USAGE}\n`);
-        return 1;
-    }
-    const resolved = await resolveSessionOptions(env, { home: seams.home }, USAGE);
-    if (!resolved.ok) {
-        // `detail` names its reason except for a missing session id, where it is only the usage text.
-        const named = resolved.detail.startsWith(`${resolved.output.reason}:`);
-        process.stderr.write(named ? `${resolved.detail}\n` : `${resolved.output.reason}: CLAUDE_CODE_SESSION_ID is not set\n${resolved.detail}\n`);
-        return 1;
-    }
-    const output = await fetchReadyCards(resolved.options, seams.deps ?? { fetch: (input, init) => fetch(input, init), requestTimeoutMs: READY_CARDS_REQUEST_TIMEOUT_MS });
-    if (!output.ok) {
-        process.stderr.write(`${output.reason}: could not read the plan's ready cards from the dashboard\n`);
-        return 1;
-    }
-    process.stdout.write(`${JSON.stringify({ plan_id: output.planId, cards: output.cards })}\n`);
-    return 0;
-}