@bli-cockpit/cli 0.2.135 → 0.2.140

package/dist/commands/docs-notion.js

@@ -0,0 +1,90 @@
+/**
+ * `cockpit docs link` and `cockpit docs sync-status` — the Notion half of the
+ * document library (BLI-10430). A sibling of `docs.ts` rather than more of it:
+ * that file is the five library verbs, and this one is the two-way sync's.
+ *
+ * `link <id|slug> <notion-url|page-id>` → `PUT /api/docs/documents/[id]/notion-link`
+ * `link <id|slug> --clear`             → `DELETE` on the same door
+ * `sync-status [<id|slug>]`            → `GET /api/docs/notion-sync`
+ *
+ * The door folds any Notion URL or id to the page id the importer stores, and
+ * refuses by name: `invalid_notion_page`, `notion_page_already_linked`,
+ * `document_not_writable`. A link means the page is the truth: the next sync
+ * pulls it over the Tower copy and keeps the copy as a version
+ * (`docs/architecture/docs.md`, "Two-way sync with Notion").
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { resolveDocId } from "./docs.js";
+const TAG = "[docs cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 60_000;
+/**
+ * `sync-status [<id|slug>]` → `GET /api/docs/notion-sync[?document_id=]`. Tower's
+ * half of the answer only (synced / tower_changed / never_synced); the door
+ * never claims anything about Notion it has not read.
+ */
+export async function syncStatusDocs(command, door) {
+    let path = "/api/docs/notion-sync";
+    if (command.docRef) {
+        const resolved = await resolveDocId(door, command.docRef);
+        if (resolved.status === "list_failed")
+            return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+        if (resolved.status === "not_found") {
+            return failAgentDoor(door, TAG, "document_not_found_or_unreadable", `That document does not exist, or you cannot read it: ${command.docRef}`);
+        }
+        path = `${path}?document_id=${encodeURIComponent(resolved.id)}`;
+    }
+    const answer = await askAgentDoor(door, { path, method: "GET", label: "docs sync-status", 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, counts: body.counts, documents: body.documents ?? [] });
+    const documents = body.documents ?? [];
+    for (const doc of documents) {
+        writeLine(door.io.stdout, `${doc.id}  ${doc.state.padEnd(13)}  ${(doc.notion_synced_at ?? "never").padEnd(25)}  ${doc.slug ?? "(no slug)"}  ${doc.title}`);
+    }
+    const byState = body.counts?.by_state ?? {};
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${body.counts?.linked ?? documents.length} linked: ${Object.entries(byState)
+        .map(([state, count]) => `${count} ${state}`)
+        .join(", ")}. A Notion edit shows up at the next pull, not here.`);
+    return 0;
+}
+export async function linkDoc(command, door) {
+    const ref = command.docRef ?? "";
+    const resolved = await resolveDocId(door, ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found") {
+        return failAgentDoor(door, TAG, "document_not_found_or_unreadable", `That document does not exist, or you cannot write to it: ${ref}`);
+    }
+    const path = `/api/docs/documents/${encodeURIComponent(resolved.id)}/notion-link`;
+    const answer = command.clearLink
+        ? await askAgentDoor(door, { path, method: "DELETE", label: "docs link", timeoutMs: WRITE_DEADLINE_MS })
+        : await askAgentDoor(door, {
+            path,
+            method: "PUT",
+            label: "docs link",
+            timeoutMs: WRITE_DEADLINE_MS,
+            body: { notion_page: command.notionPage ?? "" },
+        });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const result = answer.body;
+    const document = result.document ?? {};
+    writeLine(door.io.stderr, `${TAG} link ${JSON.stringify({ document_id: document["id"] ?? resolved.id, outcome: result.outcome ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, outcome: result.outcome, document });
+    const title = String(document["title"] ?? "");
+    const page = document["notion_page_id"];
+    const sentence = {
+        linked: `Linked ${title} to Notion page ${String(page)}. The next sync pulls the page over this copy and keeps the copy as a version.`,
+        already_linked: `${title} was already linked to Notion page ${String(page)}. Nothing changed.`,
+        unlinked: `Unlinked ${title} from Notion. It is a Tower-only document now.`,
+        already_unlinked: `${title} was not linked to Notion. Nothing changed.`,
+    };
+    writeLine(door.io.stdout, sentence[result.outcome ?? ""] ?? `Done: ${title}.`);
+    return 0;
+}

package/dist/commands/docs-read.js

@@ -0,0 +1,197 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { docsListPath, resolveDocIds } from "./docs.js";
+const TAG = "[docs cli]";
+const READ_DEADLINE_MS = 30_000;
+function headingsOf(markdown) {
+    const lines = markdown.split("\n");
+    const headings = [];
+    lines.forEach((line, lineIndex) => {
+        const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+        if (match?.[1] && match[2])
+            headings.push({ lineIndex, level: match[1].length, title: match[2] });
+    });
+    return headings;
+}
+/**
+ * The Markdown from a heading matching `wanted` (case-insensitively, exact)
+ * to the next heading at the same or shallower level. `null` means no
+ * heading matched — a wrong slice reads as the whole answer, so a miss is a
+ * refusal, never an empty string.
+ */
+export function sliceDocSection(markdown, wanted) {
+    const headings = headingsOf(markdown);
+    const target = headings.find((heading) => heading.title.toLowerCase() === wanted.trim().toLowerCase());
+    if (!target)
+        return null;
+    const lines = markdown.split("\n");
+    const next = headings.find((heading) => heading.lineIndex > target.lineIndex && heading.level <= target.level);
+    const endLine = next ? next.lineIndex : lines.length;
+    return { text: lines.slice(target.lineIndex, endLine).join("\n").trim(), headings: headings.map((h) => h.title) };
+}
+/** A character range of the body — `offset` defaults to 0, `limit` to "the rest". */
+export function sliceDocRange(body, offset, limit) {
+    const totalChars = body.length;
+    if (offset === undefined && limit === undefined)
+        return { text: body, truncated: false, totalChars };
+    const start = Math.min(offset ?? 0, totalChars);
+    const end = limit === undefined ? totalChars : Math.min(start + limit, totalChars);
+    return { text: body.slice(start, end), truncated: end < totalChars, totalChars };
+}
+/**
+ * Applies `--section` then, only when `applyCharRange` is true,
+ * `--offset`/`--limit` (as a CHARACTER range) to one document's body, in
+ * place. Returns a refusal reason when `--section` named a heading this
+ * document does not have — the only way this can fail.
+ *
+ * `applyCharRange` is false in `--parent --bodies` mode: there, `--limit`
+ * already means the DOCUMENT COUNT the door capped the list at (matching
+ * `list`'s own meaning) — applying it a second time as a character count
+ * here silently truncated every body to a handful of characters, a real bug
+ * a live-fire probe against production caught before this shipped (every
+ * body under a folder came back `""` once `--limit 3` meant "3 documents").
+ */
+function narrowBody(command, document, applyCharRange) {
+    let body = typeof document.body_markdown === "string" ? document.body_markdown : "";
+    if (command.section) {
+        const sliced = sliceDocSection(body, command.section);
+        if (!sliced) {
+            const known = headingsOf(body).map((heading) => heading.title);
+            return {
+                ok: false,
+                reason: "document_section_not_found",
+                detail: `No section "${command.section}" in ${document.id} (${known.join(", ") || "none"}).`,
+            };
+        }
+        body = sliced.text;
+    }
+    if (applyCharRange && (command.offset !== undefined || command.limit !== undefined)) {
+        body = sliceDocRange(body, command.offset, command.limit).text;
+    }
+    document.body_markdown = body;
+    return { ok: true };
+}
+async function fetchOneDocument(door, ref, id) {
+    if (!id) {
+        return {
+            ref,
+            ok: false,
+            reason: "document_not_found_or_unreadable",
+            detail: `That document does not exist, or you cannot read it: ${ref}`,
+        };
+    }
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(id)}`,
+        method: "GET",
+        label: "docs read",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return { ref, ok: false, reason: answer.reason, detail: answer.detail };
+    const document = (answer.body.document ?? { id });
+    return { ref, ok: true, document };
+}
+function writeDocumentBlock(io, document) {
+    writeLine(io.stdout, String(document["title"] ?? ""));
+    writeLine(io.stdout, `${document["slug"] ?? "(no slug)"}  ·  ${document["visibility"] ?? ""}  ·  ${document["source"] ?? ""}`);
+    writeLine(io.stdout, "");
+    writeLine(io.stdout, String(document["body_markdown"] ?? ""));
+}
+/** `--parent <id> --bodies`: every document under that parent, bodies included, in one call. */
+async function readParentBodies(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: docsListPath(command),
+        method: "GET",
+        label: "docs read (parent bodies)",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const documents = (answer.body.documents ?? []);
+    const failures = [];
+    for (const document of documents) {
+        // `--limit` here already picked the DOCUMENT COUNT (docsListPath, above);
+        // `false` keeps it from being reapplied as a character count.
+        const narrowed = narrowBody(command, document, false);
+        if (!narrowed.ok)
+            failures.push({ ref: document.id, reason: narrowed.reason, detail: narrowed.detail });
+    }
+    writeLine(door.io.stderr, `${TAG} read parent bodies ${JSON.stringify({ parent_id: command.parentId, count: documents.length, section_misses: failures.length })}`);
+    if (door.json) {
+        return emitAgentDoor(door, { ok: failures.length === 0, documents, ...(failures.length > 0 ? { section_misses: failures } : {}) }, failures.length === 0 ? 0 : 1);
+    }
+    if (documents.length === 0) {
+        writeLine(door.io.stdout, `No documents under ${command.parentId}.`);
+        return 0;
+    }
+    documents.forEach((document, index) => {
+        if (index > 0) {
+            writeLine(door.io.stdout, "");
+            writeLine(door.io.stdout, "---");
+            writeLine(door.io.stdout, "");
+        }
+        writeDocumentBlock(door.io, document);
+    });
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${documents.length} document(s).`);
+    return failures.length === 0 ? 0 : 1;
+}
+export async function readDoc(command, door) {
+    if (command.parentId && command.bodies)
+        return readParentBodies(command, door);
+    const refs = command.docRefs && command.docRefs.length > 0 ? command.docRefs : [command.docRef ?? ""];
+    // BLI-10450: ONE shared `docs list` resolves every ref — a bulk read used
+    // to pay a resolve call per ref, on top of a read call per ref.
+    const resolved = await resolveDocIds(door, refs);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    const results = await Promise.all(refs.map((ref) => fetchOneDocument(door, ref, resolved.ids.get(ref))));
+    for (const result of results) {
+        if (result.ok) {
+            // `--limit` here means a CHARACTER count (paired with --offset) —
+            // this is not `--parent --bodies` mode, so it is applied.
+            const narrowed = narrowBody(command, result.document, true);
+            if (!narrowed.ok)
+                Object.assign(result, { ok: false, reason: narrowed.reason, detail: narrowed.detail });
+        }
+    }
+    // A single ref keeps the exact pre-BLI-10450 shape and failure path.
+    if (refs.length === 1) {
+        const [result] = results;
+        if (!result || !result.ok) {
+            return failAgentDoor(door, TAG, result?.reason ?? "document_not_found_or_unreadable", result?.detail ?? "Not found.");
+        }
+        if (door.json)
+            return emitAgentDoor(door, { ok: true, document: result.document });
+        writeDocumentBlock(door.io, result.document);
+        return 0;
+    }
+    // Several refs: `{ ok, documents: [{ ref, ok, document|error }] }` — one bad
+    // ref never loses the rest of the batch.
+    const failed = results.filter((result) => !result.ok);
+    if (door.json) {
+        return emitAgentDoor(door, {
+            ok: failed.length === 0,
+            documents: results.map((result) => result.ok
+                ? { ref: result.ref, ok: true, document: result.document }
+                : { ref: result.ref, ok: false, error: result.reason, detail: result.detail }),
+        }, failed.length === 0 ? 0 : 1);
+    }
+    results.forEach((result, index) => {
+        if (index > 0) {
+            writeLine(door.io.stdout, "");
+            writeLine(door.io.stdout, "---");
+            writeLine(door.io.stdout, "");
+        }
+        if (result.ok) {
+            writeDocumentBlock(door.io, result.document);
+        }
+        else {
+            writeLine(door.io.stderr, `${TAG} refused ${JSON.stringify({ ref: result.ref, reason: result.reason })}`);
+            writeLine(door.io.stdout, `${result.ref}: ${result.detail}`);
+        }
+    });
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${results.length - failed.length}/${results.length} document(s) read.`);
+    return failed.length === 0 ? 0 : 1;
+}

package/dist/commands/docs.js

@@ -29,6 +29,8 @@
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { readDoc } from "./docs-read.js";
+import { linkDoc, syncStatusDocs } from "./docs-notion.js";
 import { readNoteFile } from "./notes-file.js";
 const TAG = "[docs cli]";
 const READ_DEADLINE_MS = 30_000;
@@ -47,17 +49,25 @@ export async function runDocs(command, io) {
             return createDoc(command, door);
         case "update":
             return updateDoc(command, door);
+        case "link":
+            return linkDoc(command, door);
+        case "sync-status":
+            return syncStatusDocs(command, door);
     }
 }
-/** `--parent`, `--query`, `--limit` as the door's own query parameters (BLI-3737). */
+/** `--parent`, `--query`, `--word`, `--limit`, `--bodies` (BLI-10450) as the door's own query parameters (BLI-3737). */
 export function docsListPath(command) {
     const params = new URLSearchParams();
     if (command.parentId)
         params.set("parent_id", command.parentId);
     if (command.query)
         params.set("query", command.query);
+    if (command.query && command.wholeWord)
+        params.set("word", "1");
     if (command.limit !== undefined)
         params.set("limit", String(command.limit));
+    if (command.bodies)
+        params.set("bodies", "true");
     const search = params.toString();
     return search.length > 0 ? `/api/docs/documents?${search}` : "/api/docs/documents";
 }
@@ -112,7 +122,19 @@ async function treeDocs(door) {
     return 0;
 }
 /** Finds a document id by exact id or exact slug against the flat list. Never fuzzy. */
-async function resolveDocId(door, ref) {
+export async function resolveDocId(door, ref) {
+    const resolved = await resolveDocIds(door, [ref]);
+    if (resolved.status === "list_failed")
+        return resolved;
+    const id = resolved.ids.get(ref);
+    return id ? { status: "ok", id } : { status: "not_found" };
+}
+/**
+ * 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.
+ */
+export async function resolveDocIds(door, refs) {
     const answer = await askAgentDoor(door, {
         path: "/api/docs/documents",
         method: "GET",
@@ -122,38 +144,15 @@ async function resolveDocId(door, ref) {
     if (!answer.ok)
         return { status: "list_failed", reason: answer.reason, detail: answer.detail };
     const documents = (answer.body.documents ?? []);
-    const byId = documents.find((doc) => doc.id === ref);
-    if (byId)
-        return { status: "ok", id: byId.id };
-    const bySlug = documents.find((doc) => doc.slug === ref);
-    if (bySlug)
-        return { status: "ok", id: bySlug.id };
-    return { status: "not_found" };
-}
-async function readDoc(command, door) {
-    const ref = command.docRef ?? "";
-    const resolved = await resolveDocId(door, ref);
-    if (resolved.status === "list_failed")
-        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
-    if (resolved.status === "not_found") {
-        return failAgentDoor(door, TAG, "document_not_found_or_unreadable", `That document does not exist, or you cannot read it: ${ref}`);
+    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 ids = new Map();
+    for (const ref of refs) {
+        const id = byId.get(ref) ?? bySlug.get(ref);
+        if (id)
+            ids.set(ref, id);
     }
-    const answer = await askAgentDoor(door, {
-        path: `/api/docs/documents/${encodeURIComponent(resolved.id)}`,
-        method: "GET",
-        label: "docs read",
-        timeoutMs: READ_DEADLINE_MS,
-    });
-    if (!answer.ok)
-        return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const document = answer.body.document ?? {};
-    if (door.json)
-        return emitAgentDoor(door, { ok: true, document });
-    writeLine(door.io.stdout, String(document["title"] ?? ""));
-    writeLine(door.io.stdout, `${document["slug"] ?? "(no slug)"}  ·  ${document["visibility"] ?? ""}  ·  ${document["source"] ?? ""}`);
-    writeLine(door.io.stdout, "");
-    writeLine(door.io.stdout, String(document["body_markdown"] ?? ""));
-    return 0;
+    return { 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) {

package/dist/commands/issue-directory.js

@@ -0,0 +1,63 @@
+/**
+ * BLI-10450: `issue list --json` carried only `assignee_id` (a uuid) and
+ * `issue show` printed the same uuid — answering "who owns what" cost a
+ * second call to `cockpit team members` and a join done by hand.
+ *
+ * `resolveAssigneeDirectory` is that join, done once per command (never once
+ * per row): the same `/api/team/members` door `cockpit team members` already
+ * calls, reused rather than a new door minted for this.
+ */
+import { askAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TEAM_DIRECTORY_TIMEOUT_MS = 30_000;
+/**
+ * One `/api/team/members` call however many issues are in hand. Best-effort:
+ * a directory that cannot be read still lets the issue(s) print their bare
+ * `assignee_id`, the pre-BLI-10450 behaviour, rather than failing the whole
+ * read over an enrichment nobody asked to gate on.
+ */
+export async function resolveAssigneeDirectory(door, assigneeIds) {
+    const wanted = new Set(assigneeIds.filter((id) => Boolean(id)));
+    const directory = new Map();
+    if (wanted.size === 0)
+        return directory;
+    const answer = await askAgentDoor(door, {
+        path: "/api/team/members",
+        method: "GET",
+        label: "issue assignee directory",
+        timeoutMs: TEAM_DIRECTORY_TIMEOUT_MS,
+    });
+    if (!answer.ok) {
+        writeLine(door.io.stderr, `[issue cli] assignee directory unread ${JSON.stringify({ reason: answer.reason, wanted: wanted.size })}`);
+        return directory;
+    }
+    const people = answer.body.people ?? [];
+    let resolved = 0;
+    for (const person of people) {
+        const userId = person.account?.userId;
+        if (!userId || !wanted.has(userId))
+            continue;
+        directory.set(userId, { name: person.name ?? userId, email: person.email ?? null });
+        resolved += 1;
+    }
+    writeLine(door.io.stderr, `[issue cli] assignee directory resolved ${JSON.stringify({ wanted: wanted.size, resolved })}`);
+    return directory;
+}
+/** `assignee_name`/`assignee_email` alongside the bare id, for JSON output. */
+export function withAssigneeIdentity(row, directory) {
+    const identity = row.assignee_id ? directory.get(row.assignee_id) : undefined;
+    return {
+        ...row,
+        assignee_name: identity?.name ?? null,
+        assignee_email: identity?.email ?? null,
+    };
+}
+/** The text-output assignee phrase: a name (and email) when resolved, the bare id otherwise. */
+export function assigneeLabel(assigneeId, directory) {
+    if (!assigneeId)
+        return "(nobody)";
+    const identity = directory.get(assigneeId);
+    if (!identity)
+        return assigneeId;
+    return identity.email ? `${identity.name} <${identity.email}>` : identity.name;
+}

package/dist/commands/issue-show.js

@@ -0,0 +1,147 @@
+/**
+ * `cockpit issue show <id> [<id>...]` (BLI-10450) — split out of `issue.ts`
+ * when `show` grew a second shape: several references read in one call
+ * (still one HTTP round trip per issue plus its comments; there is no bulk
+ * `/api/work/issues` body door), and the assignee's name/email alongside the
+ * bare `assignee_id` a uuid always was.
+ *
+ * A single ref keeps the EXACT pre-BLI-10450 JSON shape (`{ ok, issue,
+ * comments, ... }`) — nothing that already parses `docs_read`/`work_get_issue`
+ * output breaks. Several refs answer `{ ok, issues: [...] }`, one entry per
+ * ref, each carrying its own `ref` and either the issue or a `failed: true`
+ * reason — one bad id in a batch never loses the rest.
+ */
+import { mirroredTicketIdInTitle } from "@bli-cockpit/telemetry-core";
+import { askAgentDoor, emitAgentDoor, failAgentDoor, } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { assigneeLabel, resolveAssigneeDirectory, withAssigneeIdentity } from "./issue-directory.js";
+import { READ_DEADLINE_MS, TAG } from "./issue-contracts.js";
+async function fetchOneIssue(door, ref) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}`,
+        method: "GET",
+        label: "issue show",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return { ref, ok: false, reason: answer.reason, detail: answer.detail };
+    const issue = answer.body.issue;
+    if (!issue) {
+        return {
+            ref,
+            ok: false,
+            reason: "issue_not_found_or_unreadable",
+            detail: `That issue does not exist, or you cannot read it: ${ref}`,
+        };
+    }
+    // A comment read that fails does NOT fail the whole `show` — the issue is
+    // already in hand, and a named gap beats losing what was read.
+    const commentsAnswer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(issue.id)}/comments`,
+        method: "GET",
+        label: "issue show comments",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    const comments = commentsAnswer.ok ? (commentsAnswer.body.comments ?? []) : [];
+    if (!commentsAnswer.ok) {
+        writeLine(door.io.stderr, `${TAG} comments unread ${JSON.stringify({ reason: commentsAnswer.reason, issue_id: issue.id })}`);
+    }
+    // BLI-3779: during the dual-run a Tower-native row stands for a Linear
+    // ticket, and says so in its own title (`… [BLI-3779]`).
+    const linearTicketId = mirroredTicketIdInTitle(issue.title ?? "");
+    return {
+        ref,
+        ok: true,
+        issue,
+        comments,
+        ...(linearTicketId ? { linearTicketId } : {}),
+        ...(commentsAnswer.ok ? {} : { commentsUnreadReason: commentsAnswer.reason }),
+    };
+}
+function renderOneIssue(door, result, directory) {
+    const { issue, comments, linearTicketId } = result;
+    writeLine(door.io.stdout, `${issue.identifier}  ${issue.title}`);
+    writeLine(door.io.stdout, `${issue.state}  ·  priority ${issue.priority ?? 0}  ·  assignee ${assigneeLabel(issue.assignee_id, directory)}  ·  updated ${issue.updated_at}`);
+    writeLine(door.io.stdout, `id ${issue.id}${issue.parent_id ? `  ·  parent ${issue.parent_id}` : ""}`);
+    if (linearTicketId)
+        writeLine(door.io.stdout, `Linear: ${linearTicketId}`);
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, issue.description ?? "(no description)");
+    if (comments.length > 0) {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, `--- ${comments.length} comment(s) ---`);
+        for (const comment of comments) {
+            writeLine(door.io.stdout, "");
+            writeLine(door.io.stdout, `[${comment.created_at}] ${comment.author_name ?? comment.author_id ?? "unknown"}`);
+            writeLine(door.io.stdout, comment.body_markdown);
+        }
+    }
+    else if (result.commentsUnreadReason === undefined) {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, "No comments.");
+    }
+}
+export async function showIssue(command, door) {
+    const refs = command.issueRefs && command.issueRefs.length > 0
+        ? command.issueRefs
+        : [command.issueRef ?? ""];
+    const results = [];
+    for (const ref of refs)
+        results.push(await fetchOneIssue(door, ref));
+    // BLI-10450: one directory call for the whole batch, never one per issue.
+    const directory = await resolveAssigneeDirectory(door, results.filter((result) => result.ok).map((result) => result.issue.assignee_id));
+    // A single ref keeps the pre-BLI-10450 shape and failure path exactly.
+    if (refs.length === 1) {
+        const [result] = results;
+        if (!result || !result.ok) {
+            return failAgentDoor(door, TAG, result?.reason ?? "issue_not_found_or_unreadable", result?.detail ?? "That issue does not exist, or you cannot read it.");
+        }
+        if (door.json) {
+            return emitAgentDoor(door, {
+                ok: true,
+                issue: withAssigneeIdentity(result.issue, directory),
+                comments: result.comments,
+                ...(result.linearTicketId ? { linear_ticket_id: result.linearTicketId } : {}),
+                ...(result.commentsUnreadReason ? { comments_unread_reason: result.commentsUnreadReason } : {}),
+            });
+        }
+        renderOneIssue(door, result, directory);
+        return 0;
+    }
+    // Several refs: `{ ok, issues: [...] }`, one entry per ref in the order
+    // given, each carrying `ref` so a caller can match an answer back to what
+    // it asked for. One bad id never loses the rest of the batch.
+    const failed = results.filter((result) => !result.ok);
+    if (door.json) {
+        return emitAgentDoor(door, {
+            ok: failed.length === 0,
+            issues: results.map((result) => result.ok
+                ? {
+                    ref: result.ref,
+                    ok: true,
+                    issue: withAssigneeIdentity(result.issue, directory),
+                    comments: result.comments,
+                    ...(result.linearTicketId ? { linear_ticket_id: result.linearTicketId } : {}),
+                    ...(result.commentsUnreadReason ? { comments_unread_reason: result.commentsUnreadReason } : {}),
+                }
+                : { ref: result.ref, ok: false, error: result.reason, detail: result.detail }),
+        }, failed.length === 0 ? 0 : 1);
+    }
+    results.forEach((result, index) => {
+        if (index > 0) {
+            writeLine(door.io.stdout, "");
+            writeLine(door.io.stdout, "---");
+            writeLine(door.io.stdout, "");
+        }
+        if (result.ok) {
+            renderOneIssue(door, result, directory);
+        }
+        else {
+            writeLine(door.io.stderr, `${TAG} refused ${JSON.stringify({ ref: result.ref, reason: result.reason })}`);
+            writeLine(door.io.stdout, `${result.ref}: ${result.detail}`);
+        }
+    });
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${results.length - failed.length}/${results.length} issue(s) read.`);
+    return failed.length === 0 ? 0 : 1;
+}