@bli-cockpit/mcp 0.1.65 → 0.1.67

package/README.md

@@ -103,7 +103,7 @@ about what an agent can reach.
 
 <!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
 
-**109 of 114 Tower verbs have an MCP twin.**
+**110 of 115 Tower verbs have an MCP twin.**
 Each tool goes through the SAME door its CLI verb calls, with the same
 collector device token — never a second route and never a service-role
 reader. `src/verb-census.test.ts` fails when a verb is in none of the
@@ -139,6 +139,7 @@ three tables below.
 | `cockpit careers takehome show` | `careers_takehome_show` | `GET /api/careers/takehomes/[role]` |
 | `cockpit correct` | `brief_correct` | `POST /api/jarvis/corrections` |
 | `cockpit docs create` | `docs_create` | `POST /api/docs/documents` |
+| `cockpit docs delete` | `docs_delete` | `DELETE /api/docs/documents/[id]` |
 | `cockpit docs link` | `docs_link` | `PUT /api/docs/documents/[id]/notion-link` |
 | `cockpit docs list` | `docs_list` | `GET /api/docs/documents` |
 | `cockpit docs read` | `docs_read` | `GET /api/docs/documents/[id]` |

package/dist/docs-delete-tool.d.ts

@@ -0,0 +1,7 @@
+import { type DocsMsgDeps } from "./docs-msg-helpers.js";
+import { type ToolResult } from "./tool-result.js";
+export interface DocsDeleteArgs {
+    id?: unknown;
+    ids?: unknown;
+}
+export declare function runDocsDeleteTool(deps: DocsMsgDeps, args: DocsDeleteArgs): Promise<ToolResult>;

package/dist/docs-delete-tool.js

@@ -0,0 +1,58 @@
+/**
+ * `docs_delete` (BLI‑10555) — the MCP twin of `cockpit docs delete`, the same
+ * `DELETE /api/docs/documents/[id]` door the browser's own delete calls.
+ *
+ * Soft delete only: the door sets `deleted_at` and never issues a real SQL
+ * `DELETE`, so it is recoverable (only a super_admin clearing `deleted_at`
+ * brings it back — there is no self-service undo) and never cascades: a
+ * deleted document's children keep their own `parent_id` and stay exactly
+ * where they were.
+ *
+ * Mirrors `docs-read-tool.ts`'s multi-ref shape: `resolveDocumentIds` runs
+ * ONE shared list read for every non-uuid ref, then one `DELETE` per
+ * document — one bad ref never loses the rest of the batch.
+ */
+import { callAgentDoor } from "./agent-door.js";
+import { resolveDocumentId } from "./docs-msg-helpers.js";
+import { resolveDocumentIds } from "./docs-read-tool.js";
+import { doorFailureText, errorResult, textResult, withSession } from "./tool-result.js";
+async function deleteOneDocument(deps, session, ref, id) {
+    if (!id)
+        return { ref, ok: false, text: `No document matches "${ref}" — check docs_list for the id or slug.` };
+    const response = await callAgentDoor(session, deps.fetchImpl, "DELETE", `/api/docs/documents/${encodeURIComponent(id)}`);
+    if (!response.ok)
+        return { ref, ok: false, text: doorFailureText("docs_delete", response) };
+    return { ref, ok: true, id };
+}
+export async function runDocsDeleteTool(deps, args) {
+    return withSession(deps, async (session) => {
+        const refs = Array.isArray(args.ids) && args.ids.length > 0 ? args.ids.map(String) : [String(args.id ?? "")];
+        if (refs.length === 1 && refs[0] === "")
+            return errorResult("docs_delete needs id or ids.");
+        const resolved = refs.length === 1
+            ? await (async () => {
+                const one = await resolveDocumentId(deps, session, refs[0]);
+                if (one.status === "list_failed")
+                    return { status: "list_failed", text: one.text };
+                const ids = new Map();
+                if (one.status === "ok")
+                    ids.set(refs[0], one.id);
+                return { status: "ok", ids };
+            })()
+            : await resolveDocumentIds(deps, session, refs);
+        if (resolved.status === "list_failed")
+            return errorResult(resolved.text);
+        const results = await Promise.all(refs.map((ref) => deleteOneDocument(deps, session, ref, resolved.ids.get(ref))));
+        const failed = results.filter((result) => !result.ok);
+        if (refs.length === 1) {
+            const [result] = results;
+            if (!result?.ok)
+                return errorResult(result?.text ?? "docs_delete could not delete that document.");
+            return textResult(`Deleted ${result.id}. Recoverable by a super_admin; its children stay in place.`, { document_id: result.id });
+        }
+        const lines = results.map((result) => (result.ok ? `Deleted ${result.ref} (${result.id}).` : `${result.ref}: ${result.text}`)).join("\n");
+        return textResult(`${results.length - failed.length}/${results.length} document(s) deleted. Recoverable by a super_admin; children stay in place.\n${lines}`, {
+            documents: results.map((result) => result.ok ? { ref: result.ref, ok: true, document_id: result.id } : { ref: result.ref, ok: false, error: result.text }),
+        });
+    });
+}

package/dist/docs-msg-tools.js

@@ -13,6 +13,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 { DOCS_LIST_MAX, slimTree, renderDocTree, countTree, docListRow, docListLine, resolveDocumentId, resolveChannelId, messageLine, docsListPath } from "./docs-msg-helpers.js";
+import { runDocsDeleteTool } from "./docs-delete-tool.js";
 import { runDocsReadTool } from "./docs-read-tool.js";
 export { docsListPath } from "./docs-msg-helpers.js";
 export function registerDocsMsgTools(server, deps) {
@@ -133,6 +134,18 @@ export function registerDocsMsgTools(server, deps) {
         const document = response.body.document;
         return textResult(`Updated "${document?.title ?? ""}" (${document?.id ?? resolved.id}).`, { document });
     }));
+    register("docs_delete", {
+        title: "Delete a Tower document",
+        description: "Soft-deletes one or more documents (id or slug — docs_list returns both), or several with ids. Sets "
+            + "deleted_at; never a real SQL delete. Recoverable — only a super_admin clearing deleted_at brings it back, "
+            + "there is no self-service undo. Deleting a parent does NOT delete its children; they keep their own "
+            + "parent_id and stay exactly where they were. One shared list resolves every ref, then one delete each — "
+            + "one bad ref never loses the rest.",
+        inputSchema: {
+            id: z.string().min(1).max(200).optional().describe("A document id, or its slug. Omit when passing ids."),
+            ids: z.array(z.string().min(1).max(200)).min(1).max(50).optional().describe("Several documents in one call."),
+        },
+    }, async (args) => runDocsDeleteTool(deps, args));
     register("msg_channels", {
         title: "List Tower channels",
         description: "Every channel you are a member of: id, name (a direct message has none and lists its participants instead), "

package/dist/docs-read-tool.d.ts

@@ -11,6 +11,20 @@ export declare function sliceDocRange(body: string, offset: number | undefined,
     truncated: boolean;
     totalChars: number;
 };
+/**
+ * One shared list read for every non-uuid ref, never one per ref. Exported
+ * for `docs-delete-tool.ts` (BLI‑10555), which resolves a batch the same way.
+ */
+export declare function resolveDocumentIds(deps: DocsMsgDeps, session: {
+    dashboardUrl: string;
+    deviceToken: string;
+}, refs: string[]): Promise<{
+    status: "ok";
+    ids: Map<string, string>;
+} | {
+    status: "list_failed";
+    text: string;
+}>;
 export interface DocsReadArgs {
     id?: unknown;
     ids?: unknown;

package/dist/docs-read-tool.js

@@ -70,8 +70,11 @@ function narrowBody(document, section, offset, limit, applyCharRange) {
     return { ok: true };
 }
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
-/** One shared list read for every non-uuid ref, never one per ref. */
-async function resolveDocumentIds(deps, session, refs) {
+/**
+ * One shared list read for every non-uuid ref, never one per ref. Exported
+ * for `docs-delete-tool.ts` (BLI‑10555), which resolves a batch the same way.
+ */
+export async function resolveDocumentIds(deps, session, refs) {
     const ids = new Map();
     const needsList = refs.filter((ref) => !UUID_PATTERN.test(ref));
     for (const ref of refs)

package/dist/tool-catalog.d.ts

@@ -21,7 +21,7 @@ export declare const DRY_RUN_TOOLS: readonly ["ops_recompile", "memory_requeue"]
  * candidates, share calendars. Never called by the smoke; covered by the unit
  * suites (`write-tools.test.ts` and each family's own).
  */
-export declare const WRITE_TOOLS: readonly ["emit_event", "docs_create", "docs_update", "docs_link", "msg_create_channel", "msg_dm", "msg_send", "work_create_issue", "work_update_issue", "work_move_issue", "work_comment_issue", "careers_rescreen", "careers_send_takehome", "careers_invite", "careers_grade", "careers_decide", "careers_takehome_set", "careers_settings_set", "mail_send", "mail_sync", "mail_detach", "cal_create", "cal_share", "cal_sync", "cal_detach", "jarvis_dispatch", "notes_mkdir", "notes_rmdir", "notes_rename", "notes_upload", "notes_paste", "notes_share", "notes_unshare", "notes_move", "notes_sync", "notes_detach", "memory_experience", "scout_start", "scout_dismiss", "scout_undo", "brief_rewrite", "brief_correct", "brief_done", "brief_undone", "settings_set", "settings_delete", "model_set", "team_invite", "team_role", "team_device_revoke"];
+export declare const WRITE_TOOLS: readonly ["emit_event", "docs_create", "docs_update", "docs_delete", "docs_link", "msg_create_channel", "msg_dm", "msg_send", "work_create_issue", "work_update_issue", "work_move_issue", "work_comment_issue", "careers_rescreen", "careers_send_takehome", "careers_invite", "careers_grade", "careers_decide", "careers_takehome_set", "careers_settings_set", "mail_send", "mail_sync", "mail_detach", "cal_create", "cal_share", "cal_sync", "cal_detach", "jarvis_dispatch", "notes_mkdir", "notes_rmdir", "notes_rename", "notes_upload", "notes_paste", "notes_share", "notes_unshare", "notes_move", "notes_sync", "notes_detach", "memory_experience", "scout_start", "scout_dismiss", "scout_undo", "brief_rewrite", "brief_correct", "brief_done", "brief_undone", "settings_set", "settings_delete", "model_set", "team_invite", "team_role", "team_device_revoke"];
 /** Reads that spend a model turn. The smoke's `--no-model` leaves these out. */
 export declare const MODEL_SPENDING_TOOLS: readonly ["jarvis_ask", "jarvis_check"];
 /**

package/dist/tool-catalog.js

@@ -85,6 +85,7 @@ export const WRITE_TOOLS = [
     "emit_event",
     "docs_create",
     "docs_update",
+    "docs_delete",
     "docs_link",
     "msg_create_channel",
     "msg_dm",

package/dist/verb-census.js

@@ -234,6 +234,7 @@ export const MCP_TWINS = {
     "docs read": { tool: "docs_read", door: "GET /api/docs/documents/[id]" },
     "docs create": { tool: "docs_create", door: "POST /api/docs/documents" },
     "docs update": { tool: "docs_update", door: "PATCH /api/docs/documents/[id]" },
+    "docs delete": { tool: "docs_delete", door: "DELETE /api/docs/documents/[id]" },
     "docs link": { tool: "docs_link", door: "PUT /api/docs/documents/[id]/notion-link" },
     "docs sync-status": { tool: "docs_sync_status", door: "GET /api/docs/notion-sync" },
     "msg channels": { tool: "msg_channels", door: "GET /api/msg/channels" },

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

@@ -0,0 +1,94 @@
+/**
+ * The row shapes the `work_*` tools read off `/api/work/**`, and the pure
+ * functions that turn them into what a tool answers with: the trimmed list
+ * row, the completeness and outside-project notes, one issue's text, one
+ * history line.
+ *
+ * Split out of `work-tools.ts` (BLI-10445) when that file crossed the
+ * 500-line readability ratchet. The seam: `work-tools.ts` registers the tools
+ * and calls the doors; nothing here calls a door or knows a session, so this
+ * module changes when a door's row shape or a rendered sentence does, and can
+ * be read without the registration code around it.
+ *
+ * Every string moved verbatim.
+ */
+import { type AssigneeIdentity } from "./work-directory.js";
+export interface IssueRow {
+    id: string;
+    identifier: string;
+    title: string;
+    state: string;
+    priority?: number | null;
+    assignee_id?: string | null;
+    project_id?: string | null;
+    parent_id?: string | null;
+    updated_at?: string | 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
+ * issues and 4.2 MB, 3.3 MB of it descriptions the tool said it never
+ * returned (BLI-10432). work_get_issue reads one issue in full.
+ */
+export interface IssueListRow {
+    id: string;
+    identifier: string;
+    title: string;
+    state: string;
+    priority: number | null;
+    assignee_id: string | null;
+    project_id: string | null;
+    parent_id: string | null;
+    updated_at: string | null;
+}
+export declare function issueListRow(row: IssueRow): IssueListRow;
+export interface ListCompleteness {
+    status: "complete" | "partial" | "unknown";
+    total: number | null;
+}
+export declare function listCompleteness(value: unknown): ListCompleteness | null;
+export interface OutsideProject {
+    status: string;
+    issues: {
+        identifier: string;
+        title: string;
+        project_id: string | null;
+        parent_identifier: string | null;
+    }[];
+}
+export declare function outsideProject(value: unknown): OutsideProject | null;
+/** BLI-10447: sub-issues of the listed issues that live in no project or another one. */
+export declare function outsideNote(outside: OutsideProject | null): string;
+export interface OneIssueOk {
+    ref: string;
+    ok: true;
+    issue?: IssueRow & {
+        description?: string | null;
+    };
+    comments: Array<{
+        body_markdown?: string;
+        created_at?: string;
+    }>;
+    commentsUnread?: boolean;
+}
+export interface OneIssueFailure {
+    ref: string;
+    ok: false;
+    text: string;
+}
+export declare function renderOneIssue(result: OneIssueOk, directory: Map<string, AssigneeIdentity>): string;
+export interface HistoryRow {
+    occurred_at?: string;
+    change_type?: string;
+    from_value?: string | null;
+    to_value?: string | null;
+    actor_name?: string | null;
+    source?: string;
+}
+/**
+ * A row the Linear import could not give state names to says which it is.
+ * Printing "(none) -> (none)" is honest and useless; naming the gap keeps
+ * nobody reading a real gap as a broken tool (`commands/issue.ts` says the
+ * same thing in the same words).
+ */
+export declare function historyChange(row: HistoryRow): string;

package/dist/work-issue-rows.js

@@ -0,0 +1,75 @@
+/**
+ * The row shapes the `work_*` tools read off `/api/work/**`, and the pure
+ * functions that turn them into what a tool answers with: the trimmed list
+ * row, the completeness and outside-project notes, one issue's text, one
+ * history line.
+ *
+ * Split out of `work-tools.ts` (BLI-10445) when that file crossed the
+ * 500-line readability ratchet. The seam: `work-tools.ts` registers the tools
+ * and calls the doors; nothing here calls a door or knows a session, so this
+ * module changes when a door's row shape or a rendered sentence does, and can
+ * be read without the registration code around it.
+ *
+ * Every string moved verbatim.
+ */
+import { assigneeLabel } from "./work-directory.js";
+export function issueListRow(row) {
+    return {
+        id: row.id,
+        identifier: row.identifier,
+        title: row.title,
+        state: row.state,
+        priority: row.priority ?? null,
+        assignee_id: row.assignee_id ?? null,
+        project_id: row.project_id ?? null,
+        parent_id: row.parent_id ?? null,
+        updated_at: row.updated_at ?? null,
+    };
+}
+export function listCompleteness(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    const status = record["status"];
+    if (status !== "complete" && status !== "partial" && status !== "unknown")
+        return null;
+    return { status, total: typeof record["total"] === "number" ? record["total"] : null };
+}
+export function outsideProject(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    if (!Array.isArray(record["issues"]))
+        return null;
+    return { status: String(record["status"] ?? "complete"), issues: record["issues"] };
+}
+/** BLI-10447: sub-issues of the listed issues that live in no project or another one. */
+export function outsideNote(outside) {
+    if (!outside)
+        return "";
+    const named = outside.issues.map((issue) => `${issue.identifier} (under ${issue.parent_identifier ?? "?"}, ${issue.project_id ? `project ${issue.project_id}` : "no project"})`);
+    const found = named.length > 0 ? ` ${named.length} sub-issue(s) of these sit outside the project: ${named.join(", ")}.` : "";
+    const gap = outside.status === "failed" ? " The outside-project check failed (read_failed)."
+        : outside.status === "capped" ? " The outside-project check was capped; more may exist." : "";
+    return found + gap;
+}
+export function renderOneIssue(result, directory) {
+    const { issue, comments } = result;
+    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)}`
+        + `\n\n${issue?.description ?? "(no description)"}`
+        + (commentText ? `\n\n--- comments ---\n${commentText}` : "")
+        + (result.commentsUnread ? "\n\n(comments could not be read on this call)" : "");
+}
+/**
+ * A row the Linear import could not give state names to says which it is.
+ * Printing "(none) -> (none)" is honest and useless; naming the gap keeps
+ * nobody reading a real gap as a broken tool (`commands/issue.ts` says the
+ * same thing in the same words).
+ */
+export function historyChange(row) {
+    if (row.from_value === null && row.to_value === null) {
+        return `(no state names recorded — imported from ${row.source ?? "elsewhere"})`;
+    }
+    return `${row.from_value ?? "(none)"} -> ${row.to_value ?? "(none)"}`;
+}

package/dist/work-tools.js

@@ -18,6 +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";
 /** The closed state vocabulary, verbatim from `lib/work/api-doors.ts` `WORK_ISSUE_STATES`. */
 export const WORK_ISSUE_STATES = [
     "backlog",
@@ -29,46 +30,6 @@ export const WORK_ISSUE_STATES = [
 ];
 /** `/api/work/issues`' own ceiling, and the most a caller may ask for here. */
 const ISSUE_LIST_MAX = 1000;
-function issueListRow(row) {
-    return {
-        id: row.id,
-        identifier: row.identifier,
-        title: row.title,
-        state: row.state,
-        priority: row.priority ?? null,
-        assignee_id: row.assignee_id ?? null,
-        project_id: row.project_id ?? null,
-        parent_id: row.parent_id ?? null,
-        updated_at: row.updated_at ?? null,
-    };
-}
-function listCompleteness(value) {
-    if (!value || typeof value !== "object")
-        return null;
-    const record = value;
-    const status = record["status"];
-    if (status !== "complete" && status !== "partial" && status !== "unknown")
-        return null;
-    return { status, total: typeof record["total"] === "number" ? record["total"] : null };
-}
-function outsideProject(value) {
-    if (!value || typeof value !== "object")
-        return null;
-    const record = value;
-    if (!Array.isArray(record["issues"]))
-        return null;
-    return { status: String(record["status"] ?? "complete"), issues: record["issues"] };
-}
-/** BLI-10447: sub-issues of the listed issues that live in no project or another one. */
-function outsideNote(outside) {
-    if (!outside)
-        return "";
-    const named = outside.issues.map((issue) => `${issue.identifier} (under ${issue.parent_identifier ?? "?"}, ${issue.project_id ? `project ${issue.project_id}` : "no project"})`);
-    const found = named.length > 0 ? ` ${named.length} sub-issue(s) of these sit outside the project: ${named.join(", ")}.` : "";
-    const gap = outside.status === "failed" ? " The outside-project check failed (read_failed)."
-        : outside.status === "capped" ? " The outside-project check was capped; more may exist." : "";
-    return found + gap;
-}
 /** One issue plus its comments — a comment read that fails does not lose the issue already in hand. */
 async function fetchOneIssue(deps, session, ref) {
     const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/work/issues/${encodeURIComponent(ref)}`);
@@ -87,26 +48,6 @@ async function fetchOneIssue(deps, session, ref) {
         ...(commentsResponse.ok ? {} : { commentsUnread: true }),
     };
 }
-function renderOneIssue(result, directory) {
-    const { issue, comments } = result;
-    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)}`
-        + `\n\n${issue?.description ?? "(no description)"}`
-        + (commentText ? `\n\n--- comments ---\n${commentText}` : "")
-        + (result.commentsUnread ? "\n\n(comments could not be read on this call)" : "");
-}
-/**
- * A row the Linear import could not give state names to says which it is.
- * Printing "(none) -> (none)" is honest and useless; naming the gap keeps
- * nobody reading a real gap as a broken tool (`commands/issue.ts` says the
- * same thing in the same words).
- */
-function historyChange(row) {
-    if (row.from_value === null && row.to_value === null) {
-        return `(no state names recorded — imported from ${row.source ?? "elsewhere"})`;
-    }
-    return `${row.from_value ?? "(none)"} -> ${row.to_value ?? "(none)"}`;
-}
 /** A project id from a project NAME or a uuid — exact after case-folding, never fuzzy. */
 async function resolveProjectId(deps, session, ref) {
     const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/work/projects?include_archived=true");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "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",