@bli-cockpit/mcp 0.1.69 → 0.1.70

package/dist/work-flag-census.d.ts

@@ -0,0 +1,22 @@
+/** Flags `parseIssueArgs` accepts a VALUE for (`--flag value`), read from its own `valueFlags` array. */
+export declare function issueValueFlags(): string[];
+/** The bare field names (`--parent` → `parent`) `cockpit issue create`/`update` actually write. */
+export declare function issueWriteFieldNames(): string[];
+export declare const WORK_WRITE_VERBS: readonly ["issue create", "issue update"];
+export type WorkWriteVerb = (typeof WORK_WRITE_VERBS)[number];
+export declare const MCP_TOOL_FOR_WRITE_VERB: Record<WorkWriteVerb, string>;
+/** The field names an MCP tool's REGISTERED zod shape actually carries. */
+export declare function mcpToolFieldNames(toolName: string): string[];
+/**
+ * A field on exactly one side ON PURPOSE, with why — a claim about shape,
+ * never a backlog (the same discipline `TERMINAL_ONLY` keeps in
+ * `verb-census.ts`). Anything asymmetric that is NOT listed here fails the
+ * test in `work-flag-census.test.ts`.
+ */
+export interface OneSidedField {
+    verb: WorkWriteVerb;
+    side: "cli" | "mcp";
+    field: string;
+    reason: string;
+}
+export declare const EXPECTED_ONE_SIDED_FIELDS: OneSidedField[];

package/dist/work-flag-census.js

@@ -0,0 +1,109 @@
+/**
+ * Flag-level parity for `cockpit issue create|update` against their MCP
+ * twins, `work_create_issue`/`work_update_issue` (BLI-10575).
+ *
+ * `verb-census.ts` proves every VERB has a twin — it never looks at a verb's
+ * FLAGS, by its own header ("What it deliberately does NOT see"): the
+ * extraction there only ever reads a noun's `action` union, never a shape's
+ * own fields. That is exactly how `work_create_issue` shipped with no
+ * `parent` while `cockpit issue create --parent` already had one (BLI-3716)
+ * — the VERB existed on both sides, its FLAGS did not, and nothing checked
+ * because nothing looked. `--size`, added in this same ticket, would have
+ * been the next one to drift silently were this test not written alongside
+ * it.
+ *
+ * This reads both real sources rather than trusting a hand-written list on
+ * either side:
+ *
+ *   - the collector's own `valueFlags` array for `parseIssueArgs`, a text
+ *     read the same way `verb-census.ts` reads the collector (this package
+ *     declares no dependency on it);
+ *   - the MCP tool's REGISTERED zod shape — `createServer(...)`'s
+ *     `_registeredTools[name].inputSchema.shape`, the same private field
+ *     `server.test.ts` already introspects, not a text scan of the source.
+ *
+ * `cockpit issue` has ONE shared flag vocabulary across every verb (`list`,
+ * `create`, `update`, `move`, ... all parse from the same `valueFlags`
+ * array — `local-args-tower-work.ts` gates a flag's MEANING per action, not
+ * its presence), so the CLI side of this comparison is the same set for
+ * `create` and `update` alike; only the filter list below narrows it to the
+ * fields that name something an issue's ROW carries, as opposed to a filter
+ * (`--state`, `--limit`) or a global (`--home`, `--dashboard-url`).
+ */
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createServer } from "./server.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const WORK_ARGS_FILE = resolve(HERE, "../../cockpit-local-collector/src/commands/local-args-tower-work.ts");
+/** Flags `parseIssueArgs` accepts a VALUE for (`--flag value`), read from its own `valueFlags` array. */
+export function issueValueFlags() {
+    const source = readFileSync(WORK_ARGS_FILE, "utf8");
+    const start = source.indexOf("export function parseIssueArgs");
+    const end = source.indexOf("export type ProjectAction", start);
+    if (start < 0 || end < 0) {
+        throw new Error("parseIssueArgs (or the point where it ends, ProjectAction) moved in local-args-tower-work.ts — "
+            + "work-flag-census.ts's extraction needs updating alongside it.");
+    }
+    const slice = source.slice(start, end);
+    const valueFlagsStart = slice.indexOf("valueFlags: [");
+    if (valueFlagsStart < 0)
+        throw new Error("parseIssueArgs's own valueFlags array not found.");
+    const valueFlagsEnd = slice.indexOf("]", valueFlagsStart);
+    return [...slice.slice(valueFlagsStart, valueFlagsEnd).matchAll(/"(--[a-z-]+)"/g)].map((match) => match[1]);
+}
+/**
+ * Flags that name a filter, a global, or a transport knob rather than a
+ * FIELD on the issue row itself — never counted as a "write field" either
+ * side owes the other. `--file` carries the same DESCRIPTION the MCP tools
+ * take as a plain `description` argument; see `EXPECTED_ONE_SIDED` below for
+ * why that one stays a documented asymmetry rather than a shared name.
+ */
+const NON_FIELD_FLAGS = new Set(["--home", "--dashboard-url", "--state", "--limit", "--file"]);
+/** The bare field names (`--parent` → `parent`) `cockpit issue create`/`update` actually write. */
+export function issueWriteFieldNames() {
+    return issueValueFlags()
+        .filter((flag) => !NON_FIELD_FLAGS.has(flag))
+        .map((flag) => flag.replace(/^--/, ""));
+}
+export const WORK_WRITE_VERBS = ["issue create", "issue update"];
+export const MCP_TOOL_FOR_WRITE_VERB = {
+    "issue create": "work_create_issue",
+    "issue update": "work_update_issue",
+};
+/** The field names an MCP tool's REGISTERED zod shape actually carries. */
+export function mcpToolFieldNames(toolName) {
+    const deps = {
+        resolveToken: async () => "token-not-used-by-registration",
+        baseUrl: "https://dashboard.example.test",
+        fetchImpl: (async () => new Response("{}")),
+    };
+    const server = createServer(deps);
+    const shape = server._registeredTools[toolName]?.inputSchema?.shape;
+    if (!shape) {
+        throw new Error(`${toolName} has no inputSchema shape — is it still registered under this name?`);
+    }
+    return Object.keys(shape);
+}
+export const EXPECTED_ONE_SIDED_FIELDS = [
+    {
+        verb: "issue update",
+        side: "mcp",
+        field: "id",
+        reason: "the issue being updated is a positional argument on the CLI (`cockpit issue update <id>`), never a flag — "
+            + "there is nothing for it to be symmetric WITH.",
+    },
+    {
+        verb: "issue create",
+        side: "mcp",
+        field: "description",
+        reason: "the CLI never takes a description on argv, by the sourcing-secrets discipline every body follows here — "
+            + "stdin or --file only. An MCP call has no stdin, so its tool takes description as a plain argument instead.",
+    },
+    {
+        verb: "issue update",
+        side: "mcp",
+        field: "description",
+        reason: "the same reason as issue create's: stdin/--file on the CLI, a plain argument on MCP.",
+    },
+];

package/dist/work-issue-rows.d.ts

@@ -19,11 +19,40 @@ export interface IssueRow {
     title: string;
     state: string;
     priority?: number | null;
+    estimate?: number | null;
     assignee_id?: string | null;
     project_id?: string | null;
     parent_id?: string | null;
     updated_at?: string | null;
 }
+/**
+ * `size` on `work_create_issue`/`work_update_issue` (BLI-10575) maps onto the
+ * existing `work_issues.estimate` numeric column — the CLI twin of this,
+ * `issue-contracts.ts` in the collector, carries the identical table and
+ * comment; kept as a second copy rather than a shared import for the same
+ * reason `work-directory.ts` duplicates `issue-directory.ts` instead of
+ * depending on the collector package.
+ */
+export declare const SIZE_ESTIMATES: {
+    readonly S: 1;
+    readonly M: 3;
+    readonly L: 5;
+};
+export type IssueSize = keyof typeof SIZE_ESTIMATES;
+export declare function estimateForSize(size: string): number;
+export declare function sizeForEstimate(estimate: number | null | undefined): IssueSize | null;
+/**
+ * `T extends object` rather than `T extends { estimate?: ... }` on purpose:
+ * a caller here often has `result.issue ?? {}` in hand, and TypeScript's
+ * excess-property check on an all-optional ("weak") object type refuses a
+ * `{}` that shares NO property with `{ estimate?: ... }` at all (TS2559) —
+ * exactly the shape `withAssigneeIdentity(... ?? {}, directory)` hands back
+ * when the issue itself is absent. Reading `estimate` off an `object` cast
+ * keeps the same runtime behaviour without that false refusal.
+ */
+export declare function withSizeLabel<T extends object>(row: T): T & {
+    size: IssueSize | null;
+};
 /**
  * The fields `work_list_issues` promises. The door's row carries the whole
  * description and a dozen bookkeeping columns; with no limit that was 1,000
@@ -36,6 +65,7 @@ export interface IssueListRow {
     title: string;
     state: string;
     priority: number | null;
+    estimate: number | null;
     assignee_id: string | null;
     project_id: string | null;
     parent_id: string | null;

package/dist/work-issue-rows.js

@@ -13,6 +13,44 @@
  * Every string moved verbatim.
  */
 import { assigneeLabel } from "./work-directory.js";
+/**
+ * `size` on `work_create_issue`/`work_update_issue` (BLI-10575) maps onto the
+ * existing `work_issues.estimate` numeric column — the CLI twin of this,
+ * `issue-contracts.ts` in the collector, carries the identical table and
+ * comment; kept as a second copy rather than a shared import for the same
+ * reason `work-directory.ts` duplicates `issue-directory.ts` instead of
+ * depending on the collector package.
+ */
+export const SIZE_ESTIMATES = { S: 1, M: 3, L: 5 };
+export function estimateForSize(size) {
+    const key = size.trim().toUpperCase();
+    if (key !== "S" && key !== "M" && key !== "L") {
+        throw new Error("size must be S, M, or L.");
+    }
+    return SIZE_ESTIMATES[key];
+}
+export function sizeForEstimate(estimate) {
+    if (estimate === null || estimate === undefined)
+        return null;
+    for (const key of Object.keys(SIZE_ESTIMATES)) {
+        if (SIZE_ESTIMATES[key] === estimate)
+            return key;
+    }
+    return null;
+}
+/**
+ * `T extends object` rather than `T extends { estimate?: ... }` on purpose:
+ * a caller here often has `result.issue ?? {}` in hand, and TypeScript's
+ * excess-property check on an all-optional ("weak") object type refuses a
+ * `{}` that shares NO property with `{ estimate?: ... }` at all (TS2559) —
+ * exactly the shape `withAssigneeIdentity(... ?? {}, directory)` hands back
+ * when the issue itself is absent. Reading `estimate` off an `object` cast
+ * keeps the same runtime behaviour without that false refusal.
+ */
+export function withSizeLabel(row) {
+    const estimate = row.estimate;
+    return { ...row, size: sizeForEstimate(estimate ?? null) };
+}
 export function issueListRow(row) {
     return {
         id: row.id,
@@ -20,6 +58,7 @@ export function issueListRow(row) {
         title: row.title,
         state: row.state,
         priority: row.priority ?? null,
+        estimate: row.estimate ?? null,
         assignee_id: row.assignee_id ?? null,
         project_id: row.project_id ?? null,
         parent_id: row.parent_id ?? null,
@@ -55,8 +94,9 @@ export function outsideNote(outside) {
 }
 export function renderOneIssue(result, directory) {
     const { issue, comments } = result;
+    const size = sizeForEstimate(issue?.estimate ?? null);
     const commentText = comments.map((comment) => `[${comment.created_at ?? ""}] ${comment.body_markdown ?? ""}`).join("\n\n");
-    return `${issue?.identifier ?? result.ref} ${issue?.title ?? ""} (${issue?.state ?? "?"})  ·  assignee ${assigneeLabel(issue?.assignee_id, directory)}`
+    return `${issue?.identifier ?? result.ref} ${issue?.title ?? ""} (${issue?.state ?? "?"})${size ? `  ·  size ${size}` : ""}  ·  assignee ${assigneeLabel(issue?.assignee_id, directory)}`
         + `\n\n${issue?.description ?? "(no description)"}`
         + (commentText ? `\n\n--- comments ---\n${commentText}` : "")
         + (result.commentsUnread ? "\n\n(comments could not be read on this call)" : "");

package/dist/work-tools.js

@@ -18,7 +18,7 @@ import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
 import { DEFAULT_LIST_LIMIT, doorFailureText, errorResult, moreNote, registrarFor, textResult, withSession, } from "./tool-result.js";
 import { assigneeLabel, resolveAssigneeDirectory, withAssigneeIdentity } from "./work-directory.js";
-import { historyChange, issueListRow, listCompleteness, outsideNote, outsideProject, renderOneIssue, } from "./work-issue-rows.js";
+import { estimateForSize, historyChange, issueListRow, listCompleteness, outsideNote, outsideProject, renderOneIssue, sizeForEstimate, withSizeLabel, } from "./work-issue-rows.js";
 /** The closed state vocabulary, verbatim from `lib/work/api-doors.ts` `WORK_ISSUE_STATES`. */
 export const WORK_ISSUE_STATES = [
     "backlog",
@@ -63,6 +63,24 @@ const ISSUE_REF = z
     .min(1)
     .max(200)
     .describe("A BLI-#### identifier (e.g. BLI-3654) or an issue's uuid. Both work.");
+/**
+ * A parent issue's uuid from any issue reference — the `create_id`/`update_id`
+ * bodies below need a uuid, and `[issueId]`'s own ref resolution
+ * (`lib/work/issue-ref.ts`) only runs on the PATH segment of `GET
+ * /api/work/issues/[issueId]`, never on a `parent_id` in a POST/PATCH body.
+ * `issue-contracts.ts#resolveIssueUuid` in the collector is the CLI's own
+ * copy of the identical resolve-then-write two-step.
+ */
+async function resolveParentId(deps, session, ref) {
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/work/issues/${encodeURIComponent(ref)}`);
+    if (!response.ok)
+        return { status: "failed", text: doorFailureText("work_get_issue", response) };
+    const parent = response.body.issue;
+    if (!parent?.id) {
+        return { status: "failed", text: `No issue matches "${ref}" — it may not exist, or you cannot read it.` };
+    }
+    return { status: "ok", id: parent.id };
+}
 export function registerWorkTools(server, deps) {
     const register = registrarFor(server);
     register("work_list_issues", {
@@ -111,12 +129,15 @@ export function registerWorkTools(server, deps) {
         // BLI-10450: one directory call for the whole page, never one per row.
         const directory = await resolveAssigneeDirectory(deps, session, issues.map((issue) => issue.assignee_id));
         const lines = issues
-            .map((issue) => `${issue.identifier}  ${issue.state}  ${issue.title}`
-            + `  [p${issue.priority ?? 0}, assignee ${assigneeLabel(issue.assignee_id, directory)}, project ${issue.project_id ?? "none"}]`)
+            .map((issue) => {
+            const size = sizeForEstimate(issue.estimate ?? null);
+            return `${issue.identifier}  ${issue.state}  ${issue.title}`
+                + `  [p${issue.priority ?? 0}${size ? `, size ${size}` : ""}, assignee ${assigneeLabel(issue.assignee_id, directory)}, project ${issue.project_id ?? "none"}]`;
+        })
             .join("\n");
         const totalNote = completeness?.total != null && completeness.total > issues.length ? ` ${completeness.total} match in all.` : "";
         return textResult(`${issues.length} issue(s).${totalNote}${moreNote(more, ISSUE_LIST_MAX)}${outsideNote(outside)}${lines ? `\n${lines}` : ""}`, {
-            issues: issues.map((issue) => withAssigneeIdentity(issueListRow(issue), directory)),
+            issues: issues.map((issue) => withSizeLabel(withAssigneeIdentity(issueListRow(issue), directory))),
             more,
             ...(completeness ? { total: completeness.total } : {}),
             ...(outside ? { outside_project: outside } : {}),
@@ -146,7 +167,7 @@ export function registerWorkTools(server, deps) {
             if (!result?.ok)
                 return errorResult(result?.text ?? "work_get_issue could not read that issue.");
             return textResult(renderOneIssue(result, directory), {
-                issue: withAssigneeIdentity(result.issue ?? {}, directory),
+                issue: withSizeLabel(withAssigneeIdentity(result.issue ?? {}, directory)),
                 comments: result.comments,
                 ...(result.commentsUnread ? { comments_unread: true } : {}),
             });
@@ -160,7 +181,7 @@ export function registerWorkTools(server, deps) {
                 ? {
                     ref: result.ref,
                     ok: true,
-                    issue: withAssigneeIdentity(result.issue ?? {}, directory),
+                    issue: withSizeLabel(withAssigneeIdentity(result.issue ?? {}, directory)),
                     comments: result.comments,
                     ...(result.commentsUnread ? { comments_unread: true } : {}),
                 }
@@ -175,6 +196,11 @@ export function registerWorkTools(server, deps) {
             description: z.string().max(200_000).optional().describe("The issue body, markdown."),
             project: z.string().min(1).max(200).optional().describe("A project name or uuid."),
             priority: z.number().int().min(0).max(4).optional().describe("0 none, 1 urgent, 2 high, 3 medium, 4 low."),
+            // BLI-10575: the CLI twin of this tool, `cockpit issue create`, has
+            // had --parent since BLI-3716; this field was missing, and nothing
+            // checked for the gap — see work-flag-census.test.ts.
+            parent: ISSUE_REF.optional().describe("Another issue's BLI-#### identifier or uuid — this issue becomes its sub-issue."),
+            size: z.enum(["S", "M", "L"]).optional().describe("Tower's own size scale, stored in the existing estimate column: S=1, M=3, L=5 (BLI-10575)."),
             assignee: z.string().min(1).max(100).optional().describe('"me" or a person\'s uuid.'),
         },
     }, async (args) => withSession(deps, async (session) => {
@@ -188,17 +214,26 @@ export function registerWorkTools(server, deps) {
             }
             projectId = resolved.id;
         }
+        let parentId;
+        if (args.parent) {
+            const resolved = await resolveParentId(deps, session, String(args.parent));
+            if (resolved.status === "failed")
+                return errorResult(resolved.text);
+            parentId = resolved.id;
+        }
         const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/work/issues", {
             title: args.title,
             ...(args.description === undefined ? {} : { description: args.description }),
             ...(projectId ? { project_id: projectId } : {}),
             ...(args.priority === undefined ? {} : { priority: args.priority }),
+            ...(args.size === undefined ? {} : { estimate: estimateForSize(String(args.size)) }),
             ...(args.assignee ? { assignee_id: args.assignee } : {}),
+            ...(parentId ? { parent_id: parentId } : {}),
         });
         if (!response.ok)
             return errorResult(doorFailureText("work_create_issue", response));
         const issue = response.body.issue;
-        return textResult(`Filed ${issue?.identifier ?? ""} — ${issue?.title ?? ""} (${issue?.id ?? ""}).`, { issue });
+        return textResult(`Filed ${issue?.identifier ?? ""} — ${issue?.title ?? ""} (${issue?.id ?? ""}).`, { issue: issue ? withSizeLabel(issue) : issue });
     }));
     register("work_update_issue", {
         title: "Update a Tower issue",
@@ -209,6 +244,10 @@ export function registerWorkTools(server, deps) {
             title: z.string().min(1).max(300).optional().describe("A new title."),
             description: z.string().max(200_000).nullable().optional().describe("The WHOLE new body, markdown; null clears it."),
             priority: z.number().int().min(0).max(4).optional().describe("0 none, 1 urgent, 2 high, 3 medium, 4 low."),
+            // BLI-10575: had no MCP twin at all — `cockpit issue update --parent`
+            // could re-parent a ticket and nothing on this server could.
+            parent: ISSUE_REF.optional().describe("Another issue's BLI-#### identifier or uuid — this issue becomes its sub-issue."),
+            size: z.enum(["S", "M", "L"]).optional().describe("Tower's own size scale, stored in the existing estimate column: S=1, M=3, L=5 (BLI-10575)."),
             assignee: z.string().min(1).max(100).nullable().optional().describe('"me", a uuid, or null to unassign.'),
             project: z.string().min(1).max(200).optional().describe("A project name or uuid."),
         },
@@ -224,17 +263,26 @@ export function registerWorkTools(server, deps) {
             }
             projectId = resolved.id;
         }
+        let parentId;
+        if (args.parent) {
+            const resolved = await resolveParentId(deps, session, String(args.parent));
+            if (resolved.status === "failed")
+                return errorResult(resolved.text);
+            parentId = resolved.id;
+        }
         const response = await callAgentDoor(session, deps.fetchImpl, "PATCH", `/api/work/issues/${encodeURIComponent(ref)}`, {
             ...(args.title !== undefined ? { title: args.title } : {}),
             ...(args.description !== undefined ? { description: args.description } : {}),
             ...(args.priority !== undefined ? { priority: args.priority } : {}),
+            ...(args.size === undefined ? {} : { estimate: estimateForSize(String(args.size)) }),
             ...(args.assignee !== undefined ? { assignee_id: args.assignee } : {}),
             ...(projectId ? { project_id: projectId } : {}),
+            ...(parentId ? { parent_id: parentId } : {}),
         });
         if (!response.ok)
             return errorResult(doorFailureText("work_update_issue", response));
         const issue = response.body.issue;
-        return textResult(`Updated ${issue?.identifier ?? ref} — ${issue?.title ?? ""}.`, { issue });
+        return textResult(`Updated ${issue?.identifier ?? ref} — ${issue?.title ?? ""}.`, { issue: issue ? withSizeLabel(issue) : issue });
     }));
     register("work_move_issue", {
         title: "Move a Tower issue",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.69",
+  "version": "0.1.70",
   "private": false,
   "description": "bli-tower: an MCP server over BLI Cockpit's agent doors: JARVIS (jarvis_*), documents (docs_*), channels (msg_*), issues (work_*), the daily page (brief_*), meeting notes (notes_*), the ops board (ops_status/slack_*), settings/team/model, Scout and the workbook, plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
   "type": "module",