@bli-cockpit/cli 0.2.241 → 0.2.243

package/dist/commands/docs-comments-args.js

@@ -0,0 +1,85 @@
+/**
+ * `cockpit docs comments` and `cockpit docs comment` argument parsing (BLI-21701, docs parity step 7).
+ *
+ * `comments <doc> [--status open|resolved|all] [--cursor <c>] [--json]` reads the discussion.
+ * `comment <doc> "<text>" | -` starts a thread; exactly one of `--reply <thread>`, `--edit <comment>`,
+ * `--delete <comment>`, `--resolve <thread>` or `--reopen <thread>` changes the verb. Text is the second
+ * positional, or `-` for stdin. The door checks authority; this file only checks shape.
+ */
+import { optionalNonEmpty, parseNamedArgs } from "./local-arg-values.js";
+import { optionalUrl } from "./local-arg-values.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ACTION_FLAGS = ["--reply", "--edit", "--delete", "--resolve", "--reopen"];
+const VALUE_FLAGS = ["--home", "--dashboard-url", "--status", "--cursor", "--request-id", ...ACTION_FLAGS];
+function idFlag(flag, raw) {
+    const value = optionalNonEmpty(raw);
+    if (value !== undefined && !UUID.test(value))
+        throw new Error(`${flag} takes an id (a UUID), from \`cockpit docs comments <doc> --json\`.`);
+    return value;
+}
+export function parseDocsCommentsArgs(args) {
+    const reading = args[0] === "comments";
+    const values = parseNamedArgs(args, {
+        allowedFlags: [...VALUE_FLAGS, "--json"],
+        valueFlags: VALUE_FLAGS,
+    });
+    const rest = values.positionals.slice(1);
+    const docRef = optionalNonEmpty(rest[0]);
+    const verb = reading ? "comments" : "comment";
+    if (!docRef)
+        throw new Error(`docs ${verb} needs a document id or slug.`);
+    const base = {
+        kind: "docs",
+        action: reading ? "comments" : "comment",
+        docRef,
+        clearParent: false,
+        bodyStdin: false,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        json: values.booleans.has("--json"),
+    };
+    const chosen = ACTION_FLAGS.filter((flag) => values.flags.has(flag));
+    if (reading) {
+        if (chosen.length > 0 || values.flags.has("--request-id")) {
+            throw new Error("docs comments only reads. Use `cockpit docs comment` to write.");
+        }
+        if (rest.length > 1)
+            throw new Error(`docs comments takes one document reference, not ${rest.length}.`);
+        const status = optionalNonEmpty(values.flags.get("--status"));
+        if (status !== undefined && status !== "open" && status !== "resolved" && status !== "all") {
+            throw new Error(`--status takes open, resolved or all, not "${status}".`);
+        }
+        const cursor = optionalNonEmpty(values.flags.get("--cursor"));
+        return { ...base, ...(status ? { commentStatus: status } : {}), ...(cursor ? { cursor } : {}) };
+    }
+    if (values.flags.has("--status") || values.flags.has("--cursor"))
+        throw new Error("--status and --cursor belong to `cockpit docs comments`.");
+    if (chosen.length > 1)
+        throw new Error(`docs comment takes exactly one action, not ${chosen.join(" and ")}.`);
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    if (requestId && !UUID.test(requestId))
+        throw new Error("--request-id must be a UUID.");
+    const reply = idFlag("--reply", values.flags.get("--reply"));
+    const edit = idFlag("--edit", values.flags.get("--edit"));
+    const remove = idFlag("--delete", values.flags.get("--delete"));
+    const resolve = idFlag("--resolve", values.flags.get("--resolve"));
+    const reopen = idFlag("--reopen", values.flags.get("--reopen"));
+    const needsText = remove === undefined && resolve === undefined && reopen === undefined;
+    const text = rest.length > 1 ? rest.slice(1).join(" ") : undefined;
+    if (needsText && !text)
+        throw new Error('docs comment needs the text: `cockpit docs comment <doc> "<text>"`, or `-` to read it from stdin.');
+    if (!needsText && text)
+        throw new Error(`${chosen[0]} takes no text.`);
+    if (requestId && !(needsText && edit === undefined))
+        throw new Error("--request-id belongs to starting a thread or replying.");
+    return {
+        ...base,
+        ...(text ? { commentText: text } : {}),
+        ...(requestId ? { requestId } : {}),
+        ...(reply ? { commentReply: reply } : {}),
+        ...(edit ? { commentEdit: edit } : {}),
+        ...(remove ? { commentDelete: remove } : {}),
+        ...(resolve ? { commentResolve: resolve } : {}),
+        ...(reopen ? { commentReopen: reopen } : {}),
+    };
+}

package/dist/commands/docs-comments.js

@@ -0,0 +1,128 @@
+/**
+ * `cockpit docs comments` and `cockpit docs comment` — page discussions from a terminal (BLI-21701).
+ * A sibling of `docs.ts`, like `docs-share.ts`.
+ *
+ * `comments <id|slug> [--status open|resolved|all] [--cursor <c>]` → `GET    /api/docs/documents/[id]/comments`
+ * `comment <id|slug> "<text>" | -`                                → `POST   /api/docs/documents/[id]/comments`
+ * `comment <id|slug> "<text>" --reply <thread>`                   → `POST   .../comments` with thread_id
+ * `comment <id|slug> "<text>" --edit <comment>`                   → `PATCH  .../comments/[commentId]`
+ * `comment <id|slug> --delete <comment>`                          → `DELETE .../comments/[commentId]`
+ * `comment <id|slug> --resolve|--reopen <thread>`                 → `PATCH  .../threads/[threadId]`
+ *
+ * The door's `reason` labels (`not_commenter`, `not_comment_author`, `comment_not_found`, `thread_not_found`,
+ * `invalid_body`, ...) come back verbatim. Text is the second argument, or `-` for stdin.
+ */
+import { randomUUID } from "node:crypto";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { resolveDocId } from "./docs.js";
+const TAG = "[docs comments cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 60_000;
+const TEXT_MAX_CHARS = 10_000;
+async function resolveOrFail(command, door) {
+    const ref = command.docRef ?? "";
+    const resolved = await resolveDocId(door, ref);
+    if (resolved.status === "list_failed")
+        return { exit: failAgentDoor(door, TAG, resolved.reason, resolved.detail) };
+    if (resolved.status === "not_found") {
+        return { exit: failAgentDoor(door, TAG, "document_not_found_or_unreadable", `That document does not exist, or you cannot read it: ${ref}`) };
+    }
+    return { id: resolved.id };
+}
+export async function readDocComments(command, door) {
+    const target = await resolveOrFail(command, door);
+    if ("exit" in target)
+        return target.exit;
+    const params = new URLSearchParams({ status: command.commentStatus ?? "open" });
+    if (command.cursor)
+        params.set("cursor", command.cursor);
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(target.id)}/comments?${params.toString()}`,
+        method: "GET",
+        label: "docs comments",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} read ${JSON.stringify({ document_id: target.id, status: body.status, threads: body.threads.length, coverage: body.coverage })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    writeLine(door.io.stdout, `${body.counts.open ?? "?"} open, ${body.counts.resolved ?? "?"} resolved. Showing ${body.status}.`);
+    for (const thread of body.threads) {
+        writeLine(door.io.stdout, `thread ${thread.id}${thread.resolved ? ` (resolved by ${thread.resolved_by_name ?? "someone"}, ${thread.resolved_at ?? ""})` : " (open)"}`);
+        for (const comment of thread.comments) {
+            if (comment.deleted && comment.body === null) {
+                writeLine(door.io.stdout, `  ${comment.id}  ${comment.marker ?? "A comment was deleted."}`);
+                continue;
+            }
+            writeLine(door.io.stdout, `  ${comment.id}  ${comment.author_name ?? "Someone"}, ${comment.created_at}${comment.edited_at ? " (edited)" : ""}${comment.deleted ? ` (${comment.marker ?? "deleted"})` : ""}`);
+            for (const line of (comment.body ?? "").split("\n"))
+                writeLine(door.io.stdout, `    ${line}`);
+        }
+    }
+    if (body.coverage_note)
+        writeLine(door.io.stdout, body.coverage_note);
+    if (body.next_cursor)
+        writeLine(door.io.stdout, `More: --cursor ${body.next_cursor}`);
+    if (body.note)
+        writeLine(door.io.stdout, body.note);
+    return 0;
+}
+async function readText(command, door) {
+    if (command.commentText !== "-")
+        return { ok: true, text: command.commentText ?? "" };
+    if (isInteractiveStdin(door.io))
+        return { ok: false, detail: "`-` reads the comment from stdin, but nothing is piped in." };
+    try {
+        return { ok: true, text: await readPipedText(door.io.stdin, { maxChars: TEXT_MAX_CHARS * 2, overflowMessage: `A comment is limited to ${TEXT_MAX_CHARS} characters.` }) };
+    }
+    catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+export async function commentDocs(command, door) {
+    const target = await resolveOrFail(command, door);
+    if ("exit" in target)
+        return target.exit;
+    const base = `/api/docs/documents/${encodeURIComponent(target.id)}`;
+    let text = "";
+    if (command.commentText !== undefined) {
+        const read = await readText(command, door);
+        if (!read.ok)
+            return failAgentDoor(door, TAG, "invalid_body", read.detail);
+        text = read.text;
+    }
+    let request;
+    if (command.commentDelete) {
+        request = { path: `${base}/comments/${command.commentDelete}`, method: "DELETE", label: "docs comment delete" };
+    }
+    else if (command.commentResolve || command.commentReopen) {
+        request = {
+            path: `${base}/threads/${command.commentResolve ?? command.commentReopen}`, method: "PATCH",
+            label: command.commentResolve ? "docs comment resolve" : "docs comment reopen", body: { resolved: Boolean(command.commentResolve) },
+        };
+    }
+    else if (command.commentEdit) {
+        request = { path: `${base}/comments/${command.commentEdit}`, method: "PATCH", label: "docs comment edit", body: { body: text } };
+    }
+    else {
+        const requestId = command.requestId ?? randomUUID();
+        request = {
+            path: `${base}/comments`, method: "POST", label: command.commentReply ? "docs comment reply" : "docs comment",
+            body: { body: text, ...(command.commentReply ? { thread_id: command.commentReply } : {}), request_id: requestId }, requestId,
+        };
+    }
+    const answer = await askAgentDoor(door, { path: request.path, method: request.method, label: request.label, timeoutMs: WRITE_DEADLINE_MS, ...(request.body === undefined ? {} : { body: request.body }) });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} ${request.label} ${JSON.stringify({ document_id: target.id, outcome: body.outcome, reason: body.reason, request_id: body.request_id ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    writeLine(door.io.stdout, body.outcome === "unchanged"
+        ? `Nothing changed (${body.reason}).${body.comment_id ? ` Comment ${body.comment_id}.` : ""}`
+        : `Done (${request.label.replace("docs ", "")}).${body.comment_id ? ` Comment ${body.comment_id}` : ""}${body.thread_id ? ` in thread ${body.thread_id}` : ""}.`);
+    return 0;
+}

package/dist/commands/docs-files-args.js

@@ -0,0 +1,49 @@
+/**
+ * `cockpit docs files|file` argument parsing (BLI-21786, docs parity step 9).
+ *
+ * `files <id|slug>` lists a page's files. `file upload <id|slug> <path> [--alt <text>]` reserves, PUTs and finishes;
+ * it prints the Markdown to paste and edits no body. `file show|remove <fileId>`; `file download <fileId> [--out <path>]`.
+ * The door checks authority and type; this file only checks shape.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const VALUE_FLAGS = ["--home", "--dashboard-url", "--alt", "--out"];
+const VERBS = ["upload", "show", "download", "remove"];
+export function parseDocsFilesArgs(args) {
+    const values = parseNamedArgs(args, { allowedFlags: [...VALUE_FLAGS, "--json"], valueFlags: VALUE_FLAGS });
+    const base = {
+        kind: "docs",
+        clearParent: false,
+        bodyStdin: false,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        json: values.booleans.has("--json"),
+    };
+    const alt = optionalNonEmpty(values.flags.get("--alt"));
+    const out = optionalNonEmpty(values.flags.get("--out"));
+    if (args[0] === "files") {
+        const rest = values.positionals.slice(1);
+        if (alt !== undefined || out !== undefined)
+            throw new Error("--alt belongs to `cockpit docs file upload` and --out to `cockpit docs file download`.");
+        if (rest.length !== 1)
+            throw new Error("docs files needs exactly one page id or slug, e.g. `cockpit docs files runbook-x`.");
+        return { ...base, action: "files", docRef: rest[0] };
+    }
+    const verb = values.positionals[1];
+    const rest = values.positionals.slice(2);
+    if (!verb || !VERBS.includes(verb))
+        throw new Error(`docs file takes ${VERBS.join(", ")}, e.g. \`cockpit docs file upload <page> ./chart.png --alt "Q3 chart"\`.`);
+    if (alt !== undefined && verb !== "upload")
+        throw new Error("--alt belongs to `cockpit docs file upload`.");
+    if (out !== undefined && verb !== "download")
+        throw new Error("--out belongs to `cockpit docs file download`.");
+    if (verb === "upload") {
+        if (rest.length !== 2)
+            throw new Error("docs file upload needs a page (id or slug) and a file path: `cockpit docs file upload <page> <path> [--alt <text>]`.");
+        return { ...base, action: "file", docRef: rest[0], filePath: rest[1], docsFile: { verb, ...(alt ? { alt } : {}) } };
+    }
+    if (rest.length !== 1 || !UUID.test(rest[0] ?? "")) {
+        throw new Error(`docs file ${verb} needs one file id (a UUID, from \`cockpit docs files <page> --json\`).`);
+    }
+    return { ...base, action: "file", docsFile: { verb, fileId: rest[0].toLowerCase(), ...(out ? { outPath: out } : {}) } };
+}

package/dist/commands/docs-files.js

@@ -0,0 +1,179 @@
+/**
+ * `cockpit docs files|file` (BLI-21786): page files over the same doors the browser calls.
+ *
+ *   files <page>                       GET    /api/docs/documents/[id]/attachments
+ *   file upload <page> <path> [--alt]  POST   /api/docs/documents/[id]/attachments, PUT to storage, finalize
+ *   file show <fileId>                 GET    /api/docs/attachments/[id]
+ *   file download <fileId> [--out]     GET    /api/docs/attachments/[id]/download?format=json, then the signed link
+ *   file remove <fileId>               DELETE /api/docs/attachments/[id]
+ *
+ * The device token goes to Tower's own routes only; the PUT and the download go to the storage host with the
+ * signed URL and nothing else. Labels come back verbatim. File names are shown to the person, never written
+ * to a log line. Upload edits no body: it prints the Markdown to paste.
+ */
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { resolveDocId } from "./docs.js";
+const TAG = "[docs files cli]";
+const DEADLINE_MS = 30_000;
+/** A 25 MB transfer on a slow link; the signed URL itself lives two hours. */
+const TRANSFER_DEADLINE_MS = 10 * 60_000;
+const MAX_BYTES = 26_214_400;
+const MEDIA_TYPES = {
+    ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp",
+    ".pdf": "application/pdf", ".txt": "text/plain", ".md": "text/markdown", ".json": "application/json",
+    ".csv": "text/csv", ".zip": "application/zip", ".svg": "image/svg+xml",
+};
+const describe = (file) => `${file.id}  ${file.state}  ${file.byte_size} bytes  ${file.name}`;
+export async function runDocsFiles(command, door) {
+    if (command.action === "files")
+        return listFiles(command, door);
+    switch (command.docsFile?.verb) {
+        case "upload": return uploadFile(command, door);
+        case "show": return showFile(command, door);
+        case "download": return downloadFile(command, door);
+        case "remove": return removeFile(command, door);
+        default: return failAgentDoor(door, TAG, "invalid_body", "Try files, file upload, file show, file download or file remove.");
+    }
+}
+async function pageId(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}`);
+    }
+    return resolved.id;
+}
+async function listFiles(command, door) {
+    const id = await pageId(command, door);
+    if (typeof id === "number")
+        return id;
+    const answer = await askAgentDoor(door, { path: `/api/docs/documents/${encodeURIComponent(id)}/attachments`, method: "GET", label: "docs files", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} list ${JSON.stringify({ document_id: id, returned: body.returned, coverage: body.coverage })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    if (body.files.length === 0)
+        writeLine(door.io.stdout, "This page has no files.");
+    for (const file of body.files)
+        writeLine(door.io.stdout, describe(file));
+    writeLine(door.io.stdout, `${body.returned} file(s), coverage ${body.coverage}. ${body.can_edit ? "You can upload and remove files here." : "You can read and download these files."}`);
+    return 0;
+}
+async function uploadFile(command, door) {
+    const path = resolve(command.filePath ?? "");
+    let bytes;
+    try {
+        const info = await stat(path);
+        if (!info.isFile())
+            return failAgentDoor(door, TAG, "invalid_body", "That path is not a file.");
+        if (info.size > MAX_BYTES)
+            return failAgentDoor(door, TAG, "attachment_too_large", `A file can be at most ${MAX_BYTES.toLocaleString("en-US")} bytes (25 MB).`);
+        bytes = await readFile(path);
+    }
+    catch {
+        return failAgentDoor(door, TAG, "invalid_body", "Tower could not read that file. Check the path.");
+    }
+    const id = await pageId(command, door);
+    if (typeof id === "number")
+        return id;
+    const name = basename(path) || "file";
+    const mediaType = MEDIA_TYPES[extname(name).toLowerCase()];
+    const reserved = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(id)}/attachments`, method: "POST", label: "docs file reserve", timeoutMs: DEADLINE_MS,
+        body: { name, ...(mediaType ? { media_type: mediaType } : {}), byte_size: bytes.length, ...(command.docsFile?.alt ? { alt_text: command.docsFile.alt } : {}) },
+    });
+    if (!reserved.ok)
+        return failAgentDoor(door, TAG, reserved.reason, reserved.detail);
+    const { file, upload } = reserved.body;
+    let put;
+    try {
+        put = await door.io.fetch(upload.url, {
+            method: upload.method ?? "PUT", headers: upload.headers ?? {}, body: new Uint8Array(bytes),
+            signal: AbortSignal.timeout(TRANSFER_DEADLINE_MS),
+        });
+    }
+    catch (error) {
+        writeLine(door.io.stderr, `${TAG} put failed ${JSON.stringify({ attachment_id: file.id, reason: "storage_unreachable", bytes: bytes.length, error_name: error instanceof Error ? error.name : "error" })}`);
+        return failAgentDoor(door, TAG, "storage_unreachable", `Could not reach storage. Nothing was sent. Cancel with \`cockpit docs file remove ${file.id}\` or upload again.`, { attachment_id: file.id });
+    }
+    if (!put.ok) {
+        writeLine(door.io.stderr, `${TAG} put refused ${JSON.stringify({ attachment_id: file.id, reason: `storage_http_${put.status}`, bytes: bytes.length })}`);
+        return failAgentDoor(door, TAG, "storage_unreachable", `Storage refused the upload (HTTP ${put.status}). Cancel with \`cockpit docs file remove ${file.id}\` or upload again.`, { attachment_id: file.id });
+    }
+    const done = await askAgentDoor(door, { path: `/api/docs/attachments/${file.id}/finalize`, method: "POST", label: "docs file finalize", timeoutMs: DEADLINE_MS, body: {} });
+    if (!done.ok) {
+        writeLine(door.io.stderr, `${TAG} finish failed, safe to repeat: POST /api/docs/attachments/${file.id}/finalize`);
+        return failAgentDoor(door, TAG, done.reason, done.detail, { attachment_id: file.id });
+    }
+    const ready = done.body.file;
+    writeLine(door.io.stderr, `${TAG} uploaded ${JSON.stringify({ attachment_id: ready.id, document_id: id, bytes: bytes.length, state: ready.state })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, file: ready });
+    writeLine(door.io.stdout, `Uploaded ${describe(ready)}`);
+    writeLine(door.io.stdout, "Add this line to the page body (this command does not edit the body):");
+    writeLine(door.io.stdout, ready.markdown);
+    return 0;
+}
+async function showFile(command, door) {
+    const answer = await askAgentDoor(door, { path: `/api/docs/attachments/${encodeURIComponent(command.docsFile?.fileId ?? "")}`, method: "GET", label: "docs file show", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const file = answer.body.file;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, file });
+    writeLine(door.io.stdout, describe(file));
+    return 0;
+}
+async function removeFile(command, door) {
+    const answer = await askAgentDoor(door, { path: `/api/docs/attachments/${encodeURIComponent(command.docsFile?.fileId ?? "")}`, method: "DELETE", label: "docs file remove", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const file = answer.body.file;
+    writeLine(door.io.stderr, `${TAG} removed ${JSON.stringify({ attachment_id: file.id, state: file.state })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, file });
+    writeLine(door.io.stdout, `${file.state === "cancelled" ? "Cancelled" : "Removed"} ${describe(file)}`);
+    return 0;
+}
+async function downloadFile(command, door) {
+    const id = encodeURIComponent(command.docsFile?.fileId ?? "");
+    const described = await askAgentDoor(door, { path: `/api/docs/attachments/${id}`, method: "GET", label: "docs file show", timeoutMs: DEADLINE_MS });
+    if (!described.ok)
+        return failAgentDoor(door, TAG, described.reason, described.detail);
+    const file = described.body.file;
+    const link = await askAgentDoor(door, { path: `/api/docs/attachments/${id}/download?format=json`, method: "GET", label: "docs file link", timeoutMs: DEADLINE_MS });
+    if (!link.ok)
+        return failAgentDoor(door, TAG, link.reason, link.detail);
+    const { url } = link.body;
+    let bytes;
+    try {
+        const response = await door.io.fetch(url, { signal: AbortSignal.timeout(TRANSFER_DEADLINE_MS) });
+        if (!response.ok) {
+            writeLine(door.io.stderr, `${TAG} download refused ${JSON.stringify({ attachment_id: file.id, reason: `storage_http_${response.status}` })}`);
+            return failAgentDoor(door, TAG, "storage_unreachable", `Storage refused the download (HTTP ${response.status}).`);
+        }
+        bytes = Buffer.from(await response.arrayBuffer());
+    }
+    catch {
+        return failAgentDoor(door, TAG, "storage_unreachable", "Could not reach storage. Try again.");
+    }
+    const target = resolve(command.docsFile?.outPath ?? (basename(file.name) || file.id));
+    try {
+        await writeFile(target, bytes, { flag: "wx" });
+    }
+    catch {
+        return failAgentDoor(door, TAG, "out_exists", "Tower will not overwrite or could not write that path. Pick another with --out.");
+    }
+    writeLine(door.io.stderr, `${TAG} downloaded ${JSON.stringify({ attachment_id: file.id, bytes: bytes.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, file, path: target, bytes: bytes.length });
+    writeLine(door.io.stdout, `Saved ${bytes.length} bytes to ${target}`);
+    return 0;
+}

package/dist/commands/docs-formatting.js

@@ -0,0 +1,45 @@
+/**
+ * `cockpit docs formatting [--json]` (BLI-21814): the docs editor's formatting help over `GET /api/docs/formatting`,
+ * the same door the web page, MCP `docs_formatting` and JARVIS `readDocFormatting` use. It reads no document and
+ * changes nothing; to change a page's blocks, edit its Markdown with `docs update --expected-revision`.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const TAG = "[docs formatting cli]";
+const DEADLINE_MS = 30_000;
+export function parseDocsFormattingArgs(args) {
+    const values = parseNamedArgs(args, { allowedFlags: ["--home", "--dashboard-url", "--json"], valueFlags: ["--home", "--dashboard-url"] });
+    if (values.positionals.length !== 1)
+        throw new Error("docs formatting takes no arguments: `cockpit docs formatting [--json]`.");
+    return {
+        kind: "docs",
+        action: "formatting",
+        clearParent: false,
+        bodyStdin: false,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        json: values.booleans.has("--json"),
+    };
+}
+export async function runDocsFormatting(_command, door) {
+    const answer = await askAgentDoor(door, { path: "/api/docs/formatting", method: "GET", label: "docs formatting", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const help = answer.body.formatting;
+    writeLine(door.io.stderr, `${TAG} read ${JSON.stringify({ blocks: help.blocks.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, formatting: help });
+    writeLine(door.io.stdout, "Blocks (write the Markdown; keys: Mod is Cmd on macOS, Ctrl on Windows):");
+    for (const block of help.blocks) {
+        const keys = Object.entries(block.keys).map(([id, key]) => `${id} ${key}`);
+        writeLine(door.io.stdout, `- ${block.type}: ${block.markdown.replace(/\n/g, " ⏎ ")}${block.note ? ` (${block.note})` : ""}${keys.length > 0 ? ` [${keys.join("; ")}]` : ""}`);
+    }
+    for (const [title, notes] of [["Kept as text", help.kept_as_text], ["Dropped on save", help.dropped], ["Read-only", help.read_only], ["Unsupported", help.unsupported]]) {
+        writeLine(door.io.stdout, `${title}:`);
+        for (const note of notes)
+            writeLine(door.io.stdout, `- ${note.name}: ${note.note}`);
+    }
+    writeLine(door.io.stdout, `Block menu: ${help.menu_keys}. Change blocks by editing the page's Markdown with \`cockpit docs update\`.`);
+    return 0;
+}

package/dist/commands/docs-inbox-args.js

@@ -0,0 +1,93 @@
+/**
+ * `cockpit docs inbox|subscribe|unsubscribe|notifications` argument parsing (BLI-21741, docs parity step 8).
+ *
+ * `inbox [--unread] [--kind mentioned|commented|edited] [--before <cursor>] [--limit <n>]` reads the inbox.
+ * `inbox read <id>... | --all` and `inbox unread <id>...` mark items. `subscribe|unsubscribe <id|slug>` follow or
+ * stop following a page. `notifications [--mentions on|off] [--comments on|off] [--edits on|off]` reads the
+ * three docs notification kinds, or sets the ones named. The door checks authority; this file only checks shape.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const KINDS = ["mentioned", "commented", "edited"];
+const NOTIFY_FLAGS = ["--mentions", "--comments", "--edits"];
+const VALUE_FLAGS = ["--home", "--dashboard-url", "--kind", "--before", "--limit", ...NOTIFY_FLAGS];
+function onOff(flag, raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === "on")
+        return true;
+    if (raw === "off")
+        return false;
+    throw new Error(`${flag} takes on or off, not "${raw}".`);
+}
+export function parseDocsInboxArgs(args) {
+    const values = parseNamedArgs(args, { allowedFlags: [...VALUE_FLAGS, "--unread", "--all", "--json"], valueFlags: VALUE_FLAGS });
+    const verb = args[0];
+    const rest = values.positionals.slice(1);
+    const base = {
+        kind: "docs",
+        clearParent: false,
+        bodyStdin: false,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        json: values.booleans.has("--json"),
+    };
+    const stray = (allowed) => {
+        const bad = [...values.flags.keys(), ...values.booleans].find((flag) => !allowed.includes(flag) && flag !== "--json" && flag !== "--home" && flag !== "--dashboard-url");
+        if (bad)
+            throw new Error(`${bad} does not belong to \`cockpit docs ${verb === "inbox" && rest[0] ? `inbox ${rest[0]}` : verb}\`.`);
+    };
+    if (verb === "subscribe" || verb === "unsubscribe") {
+        stray([]);
+        if (rest.length !== 1)
+            throw new Error(`docs ${verb} needs exactly one document id or slug.`);
+        return { ...base, action: verb, docRef: rest[0] };
+    }
+    if (verb === "notifications") {
+        stray([...NOTIFY_FLAGS]);
+        if (rest.length > 0)
+            throw new Error("docs notifications takes flags only: --mentions, --comments, --edits (on or off).");
+        const set = {
+            mentions: onOff("--mentions", values.flags.get("--mentions")),
+            comments: onOff("--comments", values.flags.get("--comments")),
+            edits: onOff("--edits", values.flags.get("--edits")),
+        };
+        const given = Object.fromEntries(Object.entries(set).filter(([, value]) => value !== undefined));
+        return { ...base, action: "notifications", ...(Object.keys(given).length > 0 ? { notifySet: given } : {}) };
+    }
+    // inbox
+    if (rest[0] === "read" || rest[0] === "unread") {
+        const marking = rest[0];
+        stray(["--all"]);
+        const ids = rest.slice(1);
+        const all = values.booleans.has("--all");
+        if (all && marking === "unread")
+            throw new Error("--all only marks items read. Name the ids to mark unread.");
+        if (all && ids.length > 0)
+            throw new Error("docs inbox read takes ids or --all, not both.");
+        if (!all && ids.length === 0)
+            throw new Error(`docs inbox ${marking} needs one or more item ids (from \`cockpit docs inbox --json\`)${marking === "read" ? ", or --all" : ""}.`);
+        const bad = ids.find((id) => !UUID.test(id));
+        if (bad)
+            throw new Error(`"${bad}" is not an item id (a UUID); take it from \`cockpit docs inbox --json\`.`);
+        return { ...base, action: "inbox-read", inboxRead: marking === "read", ...(all ? { inboxAll: true } : { inboxIds: ids }) };
+    }
+    stray(["--unread", "--kind", "--before", "--limit"]);
+    if (rest.length > 0)
+        throw new Error(`docs inbox does not know "${rest[0]}". Use \`inbox read <id>...\`, \`inbox unread <id>...\`, or flags.`);
+    const kind = optionalNonEmpty(values.flags.get("--kind"));
+    if (kind !== undefined && !KINDS.includes(kind))
+        throw new Error(`--kind takes ${KINDS.join(", ")}, not "${kind}".`);
+    const before = optionalNonEmpty(values.flags.get("--before"));
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    if (limit !== undefined && limit > 100)
+        throw new Error("--limit takes a whole number from 1 to 100.");
+    return {
+        ...base,
+        action: "inbox",
+        ...(values.booleans.has("--unread") ? { inboxUnread: true } : {}),
+        ...(kind ? { inboxKind: kind } : {}),
+        ...(before ? { inboxBefore: before } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+    };
+}