@bli-cockpit/cli 0.2.241 → 0.2.243

package/dist/commands/docs.js

@@ -31,8 +31,17 @@ import { randomUUID } from "node:crypto";
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
 import { readDoc } from "./docs-read.js";
+import { searchDocs } from "./docs-search.js";
+import { favoriteDocs, listAllDocs, marksDocs, treeDocs } from "./docs-tree.js";
 import { exportDoc } from "./docs-export.js";
 import { linkDoc, syncStatusDocs } from "./docs-notion.js";
+import { restoreDocs, trashDocs, versionsDocs } from "./docs-recovery.js";
+import { commentDocs, readDocComments } from "./docs-comments.js";
+import { runDocsFiles } from "./docs-files.js";
+import { runDocsRefs } from "./docs-refs.js";
+import { runDocsSync } from "./docs-sync.js";
+import { runDocsFormatting } from "./docs-formatting.js";
+import { runDocsInbox } from "./docs-inbox.js";
 import { accessDocs, shareDocs } from "./docs-share.js";
 import { readNoteFile } from "./notes-file.js";
 import { cacheAgeLabel, cacheCoverage, readThroughCache } from "./read-cache.js";
@@ -45,12 +54,19 @@ export async function runDocs(command, io) {
     switch (command.action) {
         case "list":
             return listDocs(command, door);
+        case "search":
+            return searchDocs(command, door);
         case "tree":
             return treeDocs(door);
+        case "favorite":
+        case "unfavorite":
+            return favoriteDocs(command, door);
+        case "marks":
+            return marksDocs(door);
         case "read":
             return readDoc(command, door);
         case "create":
-            return createDoc(command, door);
+            return command.docsRefs?.templateId ? runDocsRefs(command, door) : createDoc(command, door);
         case "update":
             return updateDoc(command, door);
         case "delete":
@@ -67,6 +83,35 @@ export async function runDocs(command, io) {
             return shareDocs(command, door);
         case "access":
             return accessDocs(command, door);
+        case "comments":
+            return readDocComments(command, door);
+        case "comment":
+            return commentDocs(command, door);
+        case "inbox":
+        case "inbox-read":
+        case "subscribe":
+        case "unsubscribe":
+        case "notifications":
+            return runDocsInbox(command, door);
+        case "files":
+        case "file":
+            return runDocsFiles(command, door);
+        case "formatting":
+            return runDocsFormatting(command, door);
+        case "templates":
+        case "refs":
+        case "review":
+        case "maintenance":
+            return runDocsRefs(command, door);
+        case "sync-resolve":
+        case "manifest":
+            return runDocsSync(command, door);
+        case "trash":
+            return trashDocs(command, door);
+        case "restore":
+            return restoreDocs(command, door);
+        case "versions":
+            return versionsDocs(command, door);
     }
 }
 /** `--parent`, `--query`, `--word`, `--limit`, `--bodies` (BLI-10450) as the door's own query parameters (BLI-3737). */
@@ -82,10 +127,14 @@ export function docsListPath(command) {
         params.set("limit", String(command.limit));
     if (command.bodies)
         params.set("bodies", "true");
+    if (command.cursor)
+        params.set("cursor", command.cursor);
     const search = params.toString();
     return search.length > 0 ? `/api/docs/documents?${search}` : "/api/docs/documents";
 }
 async function listDocs(command, door) {
+    if (command.all)
+        return listAllDocs(command, door);
     const listPath = docsListPath(command);
     const answer = await readThroughCache({
         io: door.io,
@@ -125,32 +174,9 @@ async function listDocs(command, door) {
     }
     writeLine(door.io.stdout, "");
     writeLine(door.io.stdout, `${documents.length} document(s). Bodies come from \`cockpit docs read <id|slug>\`.`);
-    return 0;
-}
-function renderTree(nodes, io, depth) {
-    for (const node of nodes) {
-        writeLine(io.stdout, `${"  ".repeat(depth)}${node.title} (${node.slug ?? node.id})`);
-        if (node.children.length > 0)
-            renderTree(node.children, io, depth + 1);
-    }
-}
-async function treeDocs(door) {
-    const answer = await askAgentDoor(door, {
-        path: "/api/docs/tree",
-        method: "GET",
-        label: "docs tree",
-        timeoutMs: READ_DEADLINE_MS,
-    });
-    if (!answer.ok)
-        return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const tree = (answer.body.tree ?? []);
-    if (door.json)
-        return emitAgentDoor(door, { ok: true, tree });
-    if (tree.length === 0) {
-        writeLine(door.io.stdout, "No documents.");
-        return 0;
-    }
-    renderTree(tree, door.io, 0);
+    const nextCursor = answer.body.next_cursor;
+    if (nextCursor)
+        writeLine(door.io.stdout, `More: cockpit docs list --cursor ${nextCursor}  (or --all to walk every page)`);
     return 0;
 }
 /** Finds a document id by exact id or exact slug against the flat list. Never fuzzy. */
@@ -161,30 +187,39 @@ export async function resolveDocId(door, ref) {
     const id = resolved.ids.get(ref);
     return id ? { status: "ok", id } : { status: "not_found" };
 }
+const RESOLVE_CONCURRENCY = 8;
 /**
- * BLI-10450: `docs read <ref1> <ref2> ...` resolves every ref against ONE
- * `docs list` call, not one per ref — `resolveDocId` above is now this
- * function's single-ref case, so a bulk read pays one list call total.
+ * Resolves every ref with ONE exact lookup each (BLI-21657): `GET /api/docs/documents/<ref>?fields=revision`
+ * answers the real id for an id or a slug (slug match is exact, case-insensitive, never fuzzy). Never a scan
+ * of the capped list, so the oldest page resolves like the newest. At most 8 lookups in flight. A ref the
+ * door answers 404 for is simply absent from `ids`; any other failure is `list_failed` with the door's reason.
  */
 export async function resolveDocIds(door, refs) {
-    const answer = await askAgentDoor(door, {
-        path: "/api/docs/documents",
-        method: "GET",
-        label: "docs resolve",
-        timeoutMs: READ_DEADLINE_MS,
-    });
-    if (!answer.ok)
-        return { status: "list_failed", reason: answer.reason, detail: answer.detail };
-    const documents = (answer.body.documents ?? []);
-    const byId = new Map(documents.map((doc) => [doc.id, doc.id]));
-    const bySlug = new Map(documents.filter((doc) => doc.slug).map((doc) => [doc.slug, doc.id]));
+    const unique = [...new Set(refs)];
     const ids = new Map();
-    for (const ref of refs) {
-        const id = byId.get(ref) ?? bySlug.get(ref);
-        if (id)
-            ids.set(ref, id);
-    }
-    return { status: "ok", ids };
+    let failure = null;
+    let next = 0;
+    const worker = async () => {
+        while (failure === null && next < unique.length) {
+            const ref = unique[next++];
+            const answer = await askAgentDoor(door, {
+                path: `/api/docs/documents/${encodeURIComponent(ref)}?fields=revision`,
+                method: "GET",
+                label: "docs resolve",
+                timeoutMs: READ_DEADLINE_MS,
+            });
+            if (answer.ok) {
+                const id = answer.body.document?.id;
+                if (id)
+                    ids.set(ref, id);
+            }
+            else if (answer.reason !== "document_not_found_or_unreadable") {
+                failure = { reason: answer.reason, detail: answer.detail };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(RESOLVE_CONCURRENCY, unique.length) }, worker));
+    return failure ? { status: "list_failed", ...failure } : { status: "ok", ids };
 }
 /** Body on stdin, never argv (BLI-3706) — `--file` is the safest way on Windows, same as `cockpit notes paste`. */
 async function readBody(command, io) {
@@ -296,8 +331,7 @@ async function mutationStatusDocs(command, door) {
 /**
  * BLI‑10555: soft-deletes one or more documents — `DELETE
  * /api/docs/documents/[id]`, the same door the browser's own delete calls.
- * Recoverable (only a super_admin clearing `deleted_at` brings it back, no
- * self-service undo) and never cascades: a deleted document's children keep
+ * Recoverable (`cockpit docs trash` lists it, `docs restore <id>` brings it back) and never cascades: a deleted document's children keep
  * their own `parent_id` and stay exactly where they were.
  *
  * Mirrors `readDoc`'s multi-ref shape (BLI-10450): one shared `docs list`
@@ -319,7 +353,7 @@ async function deleteDocs(command, door) {
         }
         if (door.json)
             return emitAgentDoor(door, { ok: true, document_id: result.id });
-        writeLine(door.io.stdout, `Deleted ${result.id}. Recoverable by a super_admin; its children stay in place.`);
+        writeLine(door.io.stdout, `Deleted ${result.id}. Restore it with: cockpit docs restore ${result.id} (its children stay in place).`);
         return 0;
     }
     if (door.json) {
@@ -340,7 +374,7 @@ async function deleteDocs(command, door) {
         }
     });
     writeLine(door.io.stdout, "");
-    writeLine(door.io.stdout, `${results.length - failed.length}/${results.length} document(s) deleted. Recoverable by a super_admin; children stay in place.`);
+    writeLine(door.io.stdout, `${results.length - failed.length}/${results.length} document(s) deleted. Restore with: cockpit docs restore <id> (children stay in place).`);
     return failed.length === 0 ? 0 : 1;
 }
 async function deleteOneDocument(door, ref, id) {

package/dist/commands/doctor-update.js

@@ -51,8 +51,11 @@ export async function latestCliVersionFromNpm(context) {
         ? `@bli-cockpit/cli@${context.command.updateTag}`
         : "@bli-cockpit/cli";
     const result = await exec("npm", ["view", packageSpec, "version", "--json"]);
-    if (result.code !== 0)
+    if (result.code !== 0) {
+        // Ticket 21952: this branch was silent, so "npm could not even start" read the same as "npm is unreachable".
+        console.error("[doctor] npm latest unknown", JSON.stringify({ reason: "npm_view_failed", exit_code: result.code, stderr_bytes: result.stderr.length }));
         return null;
+    }
     return parseNpmVersion(result.stdout);
 }
 function parseNpmVersion(stdout) {

package/dist/commands/inbox-args.js

@@ -0,0 +1,81 @@
+/**
+ * `cockpit ticket inbox|read|unread|subscribe|unsubscribe` argument parsing (BLI-21703, P9). These are
+ * `issue` actions; their flags are read here so `local-args-tower-work.ts` only lists the names.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl } from "./local-arg-values.js";
+export const INBOX_ACTIONS = ["inbox", "read", "unread", "subscribe", "unsubscribe"];
+export const INBOX_VALUE_FLAGS = ["--kind", "--before"];
+export const INBOX_BOOLEAN_FLAGS = ["--unread"];
+export const INBOX_KINDS = ["assigned", "mentioned", "commented"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isInboxAction(action) {
+    return INBOX_ACTIONS.includes(action);
+}
+export function parseInboxArgs(values, action, rest) {
+    const given = (flag) => values.flags.has(flag) || values.booleans.has(flag);
+    if (action !== "inbox") {
+        for (const flag of [...INBOX_VALUE_FLAGS, ...INBOX_BOOLEAN_FLAGS, "--limit"]) {
+            if (given(flag))
+                throw new Error(`${flag} belongs to \`cockpit ticket inbox\`.`);
+        }
+    }
+    if (action !== "read" && action !== "inbox" && given("--all"))
+        throw new Error("--all belongs to `cockpit ticket read`.");
+    if (given("--request-id") || given("--expected-revision"))
+        throw new Error(`ticket ${action} takes no --request-id or --expected-revision.`);
+    const inbox = {};
+    if (action === "inbox") {
+        if (rest.length > 0)
+            throw new Error(`ticket inbox does not take "${rest[0]}".`);
+        if (given("--all"))
+            throw new Error("--all belongs to `cockpit ticket read`. Page the inbox with --before and --limit.");
+        if (values.booleans.has("--unread"))
+            inbox.unreadOnly = true;
+        const kind = optionalNonEmpty(values.flags.get("--kind"));
+        if (kind) {
+            if (!INBOX_KINDS.includes(kind))
+                throw new Error(`--kind must be ${INBOX_KINDS.join(", ")}.`);
+            inbox.kind = kind;
+        }
+        const before = optionalNonEmpty(values.flags.get("--before"));
+        if (before)
+            inbox.before = before;
+        const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+        if (limit !== undefined) {
+            if (limit > 100)
+                throw new Error("--limit is at most 100.");
+            inbox.limit = limit;
+        }
+    }
+    else if (action === "read" || action === "unread") {
+        if (action === "read" && given("--all")) {
+            if (rest.length > 0)
+                throw new Error("ticket read takes notification ids or --all, not both.");
+            inbox.all = true;
+        }
+        else {
+            if (rest.length === 0)
+                throw new Error(`ticket ${action} needs one or more notification ids${action === "read" ? " or --all" : ""}.`);
+            if (rest.length > 200)
+                throw new Error("Mark at most 200 items at a time.");
+            for (const id of rest) {
+                if (!UUID.test(id))
+                    throw new Error(`"${id.slice(0, 40)}" is not a notification id. Copy the id from \`cockpit ticket inbox --json\`.`);
+            }
+            inbox.ids = rest;
+        }
+    }
+    else {
+        if (rest.length !== 1)
+            throw new Error(`ticket ${action} takes exactly one ticket reference.`);
+        inbox.ref = rest[0];
+    }
+    return {
+        kind: "issue",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        json: values.booleans.has("--json"),
+        inbox,
+    };
+}

package/dist/commands/inbox.js

@@ -0,0 +1,88 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { READ_DEADLINE_MS, WRITE_DEADLINE_MS } from "./issue-contracts.js";
+const TAG = "[ticket inbox cli]";
+const unreadText = (counts) => counts ? `${counts.unread}${counts.capped ? "+" : ""} unread` : "unread count unavailable";
+export async function runInbox(command, io, door) {
+    void io;
+    const inbox = command.inbox;
+    switch (command.action) {
+        case "inbox":
+            return readInbox(command, door);
+        case "read":
+        case "unread": {
+            const read = command.action === "read";
+            const answer = await askAgentDoor(door, {
+                path: "/api/work/inbox/read",
+                method: "POST",
+                label: `ticket ${command.action}`,
+                timeoutMs: WRITE_DEADLINE_MS,
+                body: inbox.all ? { all: true, read: true } : { ids: inbox.ids, read },
+            });
+            if (!answer.ok)
+                return failAgentDoor(door, TAG, answer.reason, answer.detail);
+            const body = answer.body;
+            console.error(`${TAG} ${command.action} done`, JSON.stringify({ requested: body.requested, updated: body.updated }));
+            if (door.json)
+                return emitAgentDoor(door, { ok: true, ...body });
+            writeLine(door.io.stdout, `Marked ${body.updated ?? 0} item(s) ${read ? "read" : "unread"}. ${unreadText(body.counts)}.`);
+            return 0;
+        }
+        default: {
+            const follow = command.action === "subscribe";
+            const answer = await askAgentDoor(door, {
+                path: `/api/work/issues/${encodeURIComponent(inbox.ref ?? "")}/follow`,
+                method: follow ? "PUT" : "DELETE",
+                label: `ticket ${command.action}`,
+                timeoutMs: WRITE_DEADLINE_MS,
+            });
+            if (!answer.ok)
+                return failAgentDoor(door, TAG, answer.reason, answer.detail);
+            const body = answer.body;
+            console.error(`${TAG} ${command.action} done`, JSON.stringify({ following: body.follow?.following }));
+            if (door.json)
+                return emitAgentDoor(door, { ok: true, ...body });
+            writeLine(door.io.stdout, follow ? `Following ${inbox.ref}.` : `Unfollowed ${inbox.ref}. Direct assignments and @mentions still arrive.`);
+            return 0;
+        }
+    }
+}
+async function readInbox(command, door) {
+    const inbox = command.inbox;
+    const query = new URLSearchParams();
+    if (inbox.unreadOnly)
+        query.set("unread", "true");
+    if (inbox.kind)
+        query.set("kind", inbox.kind);
+    if (inbox.before)
+        query.set("before", inbox.before);
+    if (inbox.limit !== undefined)
+        query.set("limit", String(inbox.limit));
+    const suffix = query.toString();
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/inbox${suffix ? `?${suffix}` : ""}`,
+        method: "GET",
+        label: "ticket inbox",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    const out = door.io.stdout;
+    const items = body.items ?? [];
+    if (items.length === 0) {
+        writeLine(out, `${inbox.unreadOnly ? "No unread items" : "Your inbox is empty"}. ${unreadText(body.counts)}.`);
+    }
+    for (const item of items) {
+        writeLine(out, `${item.read_at ? " " : "*"} ${item.id}  ${item.kind.padEnd(9)}  ${item.identifier.padEnd(9)}  ${item.title}  (${item.created_at})`);
+    }
+    if (items.length > 0)
+        writeLine(out, `${unreadText(body.counts)}.`);
+    if (body.coverage?.dropped)
+        writeLine(out, `${body.coverage.dropped} item(s) are not shown: you cannot read their ticket.`);
+    if (body.has_more && body.next_cursor)
+        writeLine(out, `More items available. Continue with --before ${body.next_cursor}`);
+    return 0;
+}

package/dist/commands/issue-batch.js

@@ -0,0 +1,61 @@
+import { randomUUID } from "node:crypto";
+/**
+ * `cockpit ticket batch` (P5, BLI-21551): change up to 50 tickets in one call.
+ *
+ * Items come from stdin or `--file` (`{ "items": [...] }` or a bare array),
+ * never argv. The door applies each item as its own mutation and answers per
+ * item; this verb prints one stderr line per item and exits 0 only when every
+ * item committed. The batch request id is printed so a retry of the same body
+ * returns the first receipts instead of writing again.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { TAG, WRITE_DEADLINE_MS, readBody } from "./issue-contracts.js";
+export async function batchIssues(command, door) {
+    const body = await readBody(command, door.io);
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    if (body.text.trim() === "") {
+        return failAgentDoor(door, TAG, "invalid_body", "issue batch reads { \"items\": [...] } from stdin or --file; nothing was given.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body.text);
+    }
+    catch {
+        return failAgentDoor(door, TAG, "invalid_json_body", "issue batch needs JSON: { \"items\": [{ \"issue\": \"BLI-1\", \"priority\": 2 }] } or a bare array.");
+    }
+    const items = Array.isArray(parsed) ? parsed : parsed?.items;
+    if (!Array.isArray(items))
+        return failAgentDoor(door, TAG, "invalid_body", "issue batch needs a list of items.");
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} batch request ${JSON.stringify({ request_id: requestId, items: items.length })}`);
+    let answer;
+    try {
+        answer = await askAgentDoor(door, {
+            path: "/api/work/issues/batch", method: "POST", label: "issue batch", timeoutMs: WRITE_DEADLINE_MS,
+            body: { request_id: requestId, items },
+        });
+    }
+    catch {
+        console.error(`${TAG} batch response lost`, JSON.stringify({ reason: "mutation_unknown", request_id: requestId }));
+        answer = { ok: false, reason: "mutation_unknown", detail: "Result unknown. Retry the same input with the same --request-id." };
+    }
+    if (!answer.ok) {
+        writeLine(door.io.stderr, `${TAG} retry unchanged input with --request-id ${requestId}; nothing is written twice.`);
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    }
+    const result = answer.body;
+    for (const item of result.items ?? []) {
+        const why = item.reason ? `  ${item.reason}${item.message ? ` - ${item.message}` : ""}` : "";
+        writeLine(door.io.stderr, `${TAG} ${item.issue}  ${item.outcome}${why}`);
+    }
+    writeLine(door.io.stderr, `${TAG} ${result.committed} committed, ${result.refused} refused, ${result.unknown} unknown of ${result.requested}. batch request id ${result.request_id}`);
+    const allCommitted = result.committed === result.requested;
+    if (!allCommitted)
+        writeLine(door.io.stderr, `${TAG} to retry the same body use --request-id ${result.request_id}.`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: allCommitted, ...result }, allCommitted ? 0 : 1);
+    writeLine(door.io.stdout, `${result.committed} of ${result.requested} tickets changed.`);
+    return allCommitted ? 0 : 1;
+}

package/dist/commands/issue-relations.js

@@ -0,0 +1,151 @@
+import { randomUUID } from "node:crypto";
+/**
+ * `cockpit ticket relations|relate|unrelate` (BLI-21558, P6): what blocks what, over the same doors the
+ * browser uses (`/api/work/issues/<id>/relations`). A child is not a blocker; the parent link is `--parent`.
+ *
+ * `relate <id> --blocks B | --blocked-by B | --related B | --duplicate-of B` takes exactly one kind flag.
+ * `unrelate <id> --relation <relation-id>` or the same kind flag plus the other ticket, found through the read.
+ * Parsing lives here too, so `local-args-tower-work.ts` only lists the flag names.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { askTicketWrite, refuseWrite } from "./issue-write.js";
+import { READ_DEADLINE_MS, TAG, WRITE_DEADLINE_MS } from "./issue-contracts.js";
+export const RELATION_VALUE_FLAGS = ["--blocks", "--blocked-by", "--related", "--duplicate-of", "--relation"];
+const KIND_FLAGS = [
+    ["--blocks", "blocks"], ["--blocked-by", "blocked_by"], ["--related", "related"], ["--duplicate-of", "duplicate"],
+];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Reads the relation flags for one action; refuses a flag on the wrong verb, none, or several. */
+export function readRelationFlags(action, values) {
+    const given = KIND_FLAGS.filter(([flag]) => values.flags.has(flag));
+    const relationId = values.flags.get("--relation");
+    if (action !== "relate" && action !== "unrelate") {
+        if (given.length > 0 || relationId !== undefined)
+            throw new Error("--blocks, --blocked-by, --related, --duplicate-of and --relation belong to `cockpit ticket relate` and `unrelate`.");
+        return {};
+    }
+    if (given.length > 1)
+        throw new Error("Name exactly one of --blocks, --blocked-by, --related or --duplicate-of.");
+    if (relationId !== undefined && (action === "relate" || given.length > 0)) {
+        throw new Error("--relation names the edge to remove on `unrelate`; use it instead of a kind flag.");
+    }
+    if (relationId !== undefined && !UUID.test(relationId))
+        throw new Error("--relation must be a relation id (see `cockpit ticket relations <id> --json`).");
+    const [flag, kind] = given[0] ?? [];
+    if (!flag || !kind) {
+        if (action === "relate")
+            throw new Error("ticket relate needs one of --blocks <id>, --blocked-by <id>, --related <id> or --duplicate-of <id>.");
+        if (relationId === undefined)
+            throw new Error("ticket unrelate needs --relation <relation-id>, or a kind flag with the other ticket.");
+        return { relationId };
+    }
+    return { relation: { kind, target: values.flags.get(flag) ?? "" } };
+}
+const GROUPS = [
+    ["blocks", "Blocks"], ["blocked_by", "Blocked by"], ["related", "Related"], ["duplicate_of", "Duplicate of"], ["duplicates", "Duplicates"],
+];
+export async function showRelations(command, door) {
+    const ref = command.issueRef ?? "";
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/relations`, method: "GET", label: "issue relations", timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const relations = answer.body.relations;
+    if (!relations)
+        return failAgentDoor(door, TAG, "read_failed", "The door answered without relations.");
+    console.error(`${TAG} relations ${JSON.stringify(relations.coverage)}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, relations });
+    let printed = 0;
+    for (const [key, title] of GROUPS) {
+        const items = relations[key];
+        if (items.length === 0)
+            continue;
+        writeLine(door.io.stdout, `${title}:`);
+        for (const item of items)
+            writeLine(door.io.stdout, `  ${item.issue.identifier.padEnd(9)}  ${item.issue.state.padEnd(11)}  ${item.issue.title}  (${item.relation_id})`);
+        printed += items.length;
+    }
+    if (relations.unmapped.length > 0) {
+        writeLine(door.io.stdout, "Not in Tower (from Linear):");
+        for (const item of relations.unmapped)
+            writeLine(door.io.stdout, `  ${item.kind}  ${item.label}  (${item.relation_id})`);
+        printed += relations.unmapped.length;
+    }
+    if (printed === 0)
+        writeLine(door.io.stdout, `${ref} has no relations.`);
+    const { hidden, truncated, limit } = relations.coverage;
+    if (hidden > 0)
+        writeLine(door.io.stdout, `${hidden} relation(s) to tickets you cannot read or that were deleted are not shown.`);
+    if (truncated)
+        writeLine(door.io.stdout, `Showing the first ${limit} relations; there are more.`);
+    return 0;
+}
+export async function relateIssue(command, door) {
+    const ref = command.issueRef ?? "";
+    const relation = command.relation;
+    if (!relation)
+        return failAgentDoor(door, TAG, "invalid_body", "ticket relate needs a kind flag and the other ticket.");
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
+    const answer = await askTicketWrite(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/relations`, method: "POST", label: "issue relate", timeoutMs: WRITE_DEADLINE_MS,
+        body: { request_id: requestId, expected_revision: command.expectedRevision, kind: relation.kind, target: relation.target },
+    });
+    if (!answer.ok)
+        return refuseWrite(door, answer, requestId);
+    return finishWrite(door, answer.body, requestId, `${ref} ${relation.kind.replace("_", " ")} ${relation.target}: recorded.`, "related");
+}
+export async function unrelateIssue(command, door) {
+    const ref = command.issueRef ?? "";
+    let relationId = command.relationId;
+    if (!relationId && command.relation) {
+        const found = await findRelation(command, door);
+        if (typeof found === "number")
+            return found;
+        relationId = found;
+    }
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
+    const query = command.expectedRevision === undefined ? `?request_id=${requestId}` : `?request_id=${requestId}&expected_revision=${command.expectedRevision}`;
+    const answer = await askTicketWrite(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/relations/${encodeURIComponent(relationId ?? "")}${query}`,
+        method: "DELETE", label: "issue unrelate", timeoutMs: WRITE_DEADLINE_MS, body: { request_id: requestId },
+    });
+    if (!answer.ok)
+        return refuseWrite(door, answer, requestId);
+    return finishWrite(door, answer.body, requestId, `${ref}: relation removed.`, "unrelated");
+}
+function finishWrite(door, body, requestId, sentence, tag) {
+    writeLine(door.io.stderr, `${TAG} ${tag} ${JSON.stringify({ relation_id: body.relation_id ?? null })}`);
+    writeLine(door.io.stderr, `${TAG} local commit receipt ${JSON.stringify(body.mutation ?? { outcome: "unknown_check_again", request_id: requestId })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, issue: body.issue, relation_id: body.relation_id, mutation: body.mutation });
+    writeLine(door.io.stdout, sentence);
+    return 0;
+}
+/** `unrelate <id> --blocks B`: the edge id, found through the same read `relations` prints. */
+async function findRelation(command, door) {
+    const ref = command.issueRef ?? "";
+    const wanted = command.relation;
+    if (!wanted)
+        return failAgentDoor(door, TAG, "invalid_body", "ticket unrelate needs --relation or a kind flag.");
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/relations`, method: "GET", label: "issue relations", timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const relations = answer.body.relations;
+    const group = wanted.kind === "blocks" ? relations?.blocks : wanted.kind === "blocked_by" ? relations?.blocked_by
+        : wanted.kind === "related" ? relations?.related : relations?.duplicate_of;
+    const target = wanted.target.trim().toUpperCase();
+    const hit = (group ?? []).find((item) => item.issue.identifier.toUpperCase() === target || item.issue.id.toLowerCase() === target.toLowerCase())
+        ?? (relations?.unmapped ?? []).find((item) => item.label.toUpperCase() === target && item.kind === (wanted.kind === "blocked_by" ? "" : wanted.kind));
+    if (!hit) {
+        console.error(`${TAG} unrelate refused ${JSON.stringify({ reason: "relation_not_found", kind: wanted.kind })}`);
+        return failAgentDoor(door, TAG, "relation_not_found", `${ref} has no ${wanted.kind.replace("_", " ")} relation with ${wanted.target}.`);
+    }
+    return hit.relation_id;
+}