@bli-cockpit/cli 0.2.242 → 0.2.243

package/dist/commands/docs-inbox.js

@@ -0,0 +1,126 @@
+/**
+ * `cockpit docs inbox|subscribe|unsubscribe|notifications` — the docs inbox from a terminal (BLI-21741).
+ * A sibling of `docs.ts`, like `docs-comments.ts`.
+ *
+ * `inbox [--unread] [--kind k] [--before c] [--limit n]` → `GET    /api/docs/inbox`
+ * `inbox read <id>... | --all`, `inbox unread <id>...`   → `POST   /api/docs/inbox/read`
+ * `subscribe <id|slug>`                                  → `PUT    /api/docs/documents/[id]/follow`
+ * `unsubscribe <id|slug>`                                → `DELETE /api/docs/documents/[id]/follow`
+ * `notifications [--mentions on|off] ...`                → `GET|PUT /api/docs/notifications/settings`
+ *
+ * The door's `reason` labels (`inbox_ids_invalid`, `inbox_too_many_ids`, `invalid_notification_setting`,
+ * `document_not_found_or_unreadable`, ...) come back verbatim, and the mention policy sentence is printed as the door says it.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { resolveDocId } from "./docs.js";
+const TAG = "[docs inbox cli]";
+const DEADLINE_MS = 30_000;
+function itemLine(item) {
+    const who = item.actor_name ?? "Someone";
+    const what = item.kind === "mentioned" ? `${who} mentioned you`
+        : item.kind === "commented" ? (item.event_count > 1 ? `${who} and others: ${item.event_count} comments` : `${who} commented`)
+            : (item.event_count > 1 ? `${who} edited: ${item.event_count} edits` : `${who} edited`);
+    return `${item.id}  ${item.read_at === null ? "unread" : "read  "}  ${item.title || "Untitled"}  ${what}  ${item.updated_at}  (page ${item.document_id})`;
+}
+function settingsLine(settings) {
+    const word = (on) => (on ? "on" : "off");
+    return `mentions ${word(settings.mentions)}, comments ${word(settings.comments)}, edits ${word(settings.edits)}`;
+}
+async function readInbox(command, door) {
+    const params = new URLSearchParams();
+    if (command.inboxUnread)
+        params.set("unread", "true");
+    if (command.inboxKind)
+        params.set("kind", command.inboxKind);
+    if (command.inboxBefore)
+        params.set("before", command.inboxBefore);
+    if (command.limit !== undefined)
+        params.set("limit", String(command.limit));
+    const query = params.toString();
+    const answer = await askAgentDoor(door, { path: `/api/docs/inbox${query ? `?${query}` : ""}`, method: "GET", label: "docs inbox", timeoutMs: 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({ returned: body.coverage.returned, dropped: body.coverage.dropped, unread: body.counts.unread })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    writeLine(door.io.stdout, `${body.counts.unread}${body.counts.capped ? "+" : ""} unread. Showing ${body.coverage.returned}.`);
+    if (body.items.length === 0)
+        writeLine(door.io.stdout, body.explanation ?? (command.inboxUnread ? "No unread activity." : "No activity yet."));
+    for (const item of body.items)
+        writeLine(door.io.stdout, itemLine(item));
+    if (body.coverage.dropped > 0)
+        writeLine(door.io.stdout, `${body.coverage.dropped} item(s) hidden because you can no longer read their page.`);
+    if (body.next_cursor)
+        writeLine(door.io.stdout, `More: --before ${body.next_cursor}`);
+    return 0;
+}
+async function markInbox(command, door) {
+    const read = command.inboxRead !== false;
+    const answer = await askAgentDoor(door, {
+        path: "/api/docs/inbox/read", method: "POST", label: read ? "docs inbox read" : "docs inbox unread", timeoutMs: DEADLINE_MS,
+        body: command.inboxAll ? { all: true, read: true } : { ids: command.inboxIds ?? [], read },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} mark ${JSON.stringify({ requested: body.requested, updated: body.updated, skipped: body.skipped, read: body.read })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    writeLine(door.io.stdout, `Marked ${body.updated} item(s) ${body.read ? "read" : "unread"}${body.skipped > 0 ? ` (${body.skipped} skipped: another unread item already covers that thread or page)` : ""}. ${body.counts.unread} unread.`);
+    return 0;
+}
+async function followDoc(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 follow = command.action === "subscribe";
+    const label = follow ? "docs subscribe" : "docs unsubscribe";
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(resolved.id)}/follow`, method: follow ? "PUT" : "DELETE", label, timeoutMs: DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} ${label} ${JSON.stringify({ document_id: body.document_id, following: body.following, reason: body.reason })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    writeLine(door.io.stdout, `${body.following ? "Following" : "Not following"} ${body.document_id} (${body.reason}).`);
+    writeLine(door.io.stdout, body.mention_policy);
+    return 0;
+}
+async function notifications(command, door) {
+    const set = command.notifySet;
+    const answer = await askAgentDoor(door, {
+        path: "/api/docs/notifications/settings", method: set ? "PUT" : "GET", label: set ? "docs notifications set" : "docs notifications", timeoutMs: DEADLINE_MS,
+        ...(set ? { body: set } : {}),
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} notifications ${JSON.stringify({ set: Boolean(set), ...body.settings })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    writeLine(door.io.stdout, settingsLine(body.settings));
+    if (body.explanation)
+        writeLine(door.io.stdout, body.explanation);
+    return 0;
+}
+export async function runDocsInbox(command, door) {
+    switch (command.action) {
+        case "inbox":
+            return readInbox(command, door);
+        case "inbox-read":
+            return markInbox(command, door);
+        case "subscribe":
+        case "unsubscribe":
+            return followDoc(command, door);
+        default:
+            return notifications(command, door);
+    }
+}

package/dist/commands/docs-notion.js

@@ -16,6 +16,7 @@
 import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
 import { writeLine } from "./cli-io.js";
 import { resolveDocId } from "./docs.js";
+import { printSyncDetail } from "./docs-sync.js";
 const TAG = "[docs cli]";
 const READ_DEADLINE_MS = 30_000;
 const WRITE_DEADLINE_MS = 60_000;
@@ -45,6 +46,10 @@ export async function syncStatusDocs(command, door) {
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
     const body = answer.body;
+    // BLI-21875: one page also answers with its receipts, losses and conflicts; those lines are the door's own sentences.
+    if (!door.json && command.docRef && answer.body.detail) {
+        return printSyncDetail(door, command.docRef, answer.body);
+    }
     if (door.json) {
         return emitAgentDoor(door, {
             ...answer.body,

package/dist/commands/docs-read.js

@@ -93,7 +93,8 @@ async function fetchOneDocument(door, ref, id) {
 }
 function writeDocumentBlock(io, document) {
     writeLine(io.stdout, String(document["title"] ?? ""));
-    writeLine(io.stdout, `${document["slug"] ?? "(no slug)"}  ·  ${document["visibility"] ?? ""}  ·  ${document["source"] ?? ""}`);
+    const revision = typeof document["revision"] === "number" ? `  ·  revision ${document["revision"]}` : "";
+    writeLine(io.stdout, `${document["slug"] ?? "(no slug)"}  ·  ${document["visibility"] ?? ""}  ·  ${document["source"] ?? ""}${revision}`);
     writeLine(io.stdout, "");
     writeLine(io.stdout, String(document["body_markdown"] ?? ""));
 }

package/dist/commands/docs-recovery.js

@@ -0,0 +1,173 @@
+/**
+ * `cockpit docs trash`, `docs restore` and `docs versions` — recovery from a terminal (BLI-21413).
+ * A sibling of `docs.ts`, like `docs-share.ts`.
+ *
+ * `trash [--cursor C] [--limit N]`                      → `GET  /api/docs/trash`
+ * `restore <id>`                                        → `POST /api/docs/documents/[id]/restore`
+ * `versions <id|slug> [--before N] [--limit N]`         → `GET  /api/docs/documents/[id]/versions`
+ * `versions <id|slug> --version V`                      → `GET  /api/docs/documents/[id]/versions/[V]` (one body)
+ * `restore <id|slug> --version V [--expected-revision N]` → `POST .../versions/[V]/restore`
+ *
+ * Every refusal keeps the door's own reason label (`not_restore_manager`, `not_in_trash`,
+ * `revision_conflict`, `version_not_found`, ...). A restore that had to change the page's address says
+ * so in plain words.
+ */
+import { randomUUID } from "node:crypto";
+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;
+export async function trashDocs(command, door) {
+    const params = new URLSearchParams();
+    if (command.limit !== undefined)
+        params.set("limit", String(command.limit));
+    if (command.cursor)
+        params.set("cursor", command.cursor);
+    const search = params.toString();
+    const answer = await askAgentDoor(door, {
+        path: search ? `/api/docs/trash?${search}` : "/api/docs/trash",
+        method: "GET",
+        label: "docs trash",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const documents = body.documents ?? [];
+    writeLine(door.io.stderr, `${TAG} trash ${JSON.stringify({ returned: documents.length, complete: body.complete === true })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body, documents });
+    if (documents.length === 0) {
+        writeLine(door.io.stdout, "Nothing to restore: the trash holds no page you may restore.");
+        return 0;
+    }
+    for (const doc of documents) {
+        writeLine(door.io.stdout, `${doc.id}  ${doc.deleted_at ?? "?"}  ${doc.slug ?? "(no slug)"}  ${doc.title}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${documents.length} deleted page(s). Restore one with \`cockpit docs restore <id>\`.`);
+    if (body.next_cursor)
+        writeLine(door.io.stdout, `More: cockpit docs trash --cursor ${body.next_cursor}`);
+    return 0;
+}
+export async function versionsDocs(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 base = `/api/docs/documents/${encodeURIComponent(resolved.id)}/versions`;
+    if (command.versionId) {
+        const one = await askAgentDoor(door, {
+            path: `${base}/${encodeURIComponent(command.versionId)}`,
+            method: "GET",
+            label: "docs version",
+            timeoutMs: READ_DEADLINE_MS,
+        });
+        if (!one.ok)
+            return failAgentDoor(door, TAG, one.reason, one.detail);
+        const version = one.body.version ?? {};
+        writeLine(door.io.stderr, `${TAG} version ${JSON.stringify({ document_id: resolved.id, version_id: command.versionId, chars: version.body_markdown?.length ?? 0 })}`);
+        if (door.json)
+            return emitAgentDoor(door, { ok: true, version });
+        writeLine(door.io.stdout, version.body_markdown ?? "");
+        return 0;
+    }
+    const params = new URLSearchParams();
+    if (command.limit !== undefined)
+        params.set("limit", String(command.limit));
+    if (command.before !== undefined)
+        params.set("before", String(command.before));
+    const search = params.toString();
+    const answer = await askAgentDoor(door, {
+        path: search ? `${base}?${search}` : base,
+        method: "GET",
+        label: "docs versions",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const versions = body.versions ?? [];
+    writeLine(door.io.stderr, `${TAG} versions ${JSON.stringify({ document_id: resolved.id, returned: versions.length, total: body.total ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document_id: resolved.id, ...body, versions });
+    if (versions.length === 0) {
+        writeLine(door.io.stdout, "No earlier version yet.");
+        return 0;
+    }
+    for (const version of versions) {
+        writeLine(door.io.stdout, `v${String(version.version_number).padEnd(5)} ${version.id}  ${version.created_at}${version.origin ? `  (${version.origin})` : ""}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${versions.length} of ${body.total ?? "?"} versions, newest first. Read one with --version <id>; restore one with \`cockpit docs restore ${ref} --version <id>\`.`);
+    if (body.next_before !== null && body.next_before !== undefined)
+        writeLine(door.io.stdout, `Older: cockpit docs versions ${ref} --before ${body.next_before}`);
+    return 0;
+}
+/** Says where the restore stands, then fails with the door's own reason (a conflict names the current revision). */
+function refuse(door, answer, requestId) {
+    const mutation = answer.body?.mutation;
+    writeLine(door.io.stderr, `${TAG} retry unchanged input with --request-id ${requestId}.`);
+    if (mutation?.current) {
+        writeLine(door.io.stderr, `${TAG} conflict ${JSON.stringify({ request_id: requestId, current_revision: mutation.current.revision ?? mutation.revision })}`);
+    }
+    return failAgentDoor(door, TAG, answer.reason, answer.detail, mutation ? { mutation } : {});
+}
+export async function restoreDocs(command, door) {
+    const requestId = command.requestId ?? randomUUID();
+    const ref = command.docRef ?? "";
+    if (!command.versionId) {
+        // Undelete: the page is not in the live list, so the argument is its id (the trash prints it).
+        writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId })}`);
+        const answer = await askAgentDoor(door, {
+            path: `/api/docs/documents/${encodeURIComponent(ref)}/restore`,
+            method: "POST",
+            label: "docs restore",
+            timeoutMs: WRITE_DEADLINE_MS,
+            body: { request_id: requestId },
+        });
+        if (!answer.ok)
+            return refuse(door, answer, requestId);
+        const result = answer.body;
+        writeLine(door.io.stderr, `${TAG} restored ${JSON.stringify({ document_id: result.document_id ?? ref, slug_changed: result.slug_changed === true })}`);
+        if (door.json)
+            return emitAgentDoor(door, { ok: true, ...result });
+        writeLine(door.io.stdout, `Restored ${result.document_id ?? ref} from the trash with the same id.`);
+        if (result.slug_changed) {
+            writeLine(door.io.stdout, `Its address changed: another page now uses ${result.old_slug ?? "the old address"}, so this page is now ${result.new_slug ?? "at a new address"}.`);
+        }
+        return 0;
+    }
+    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}`);
+    }
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(resolved.id)}/versions/${encodeURIComponent(command.versionId)}/restore`,
+        method: "POST",
+        label: "docs restore version",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            request_id: requestId,
+            ...(command.expectedRevision !== undefined ? { expected_revision: command.expectedRevision } : {}),
+        },
+    });
+    if (!answer.ok)
+        return refuse(door, answer, requestId);
+    const { document = {}, mutation } = answer.body;
+    writeLine(door.io.stderr, `${TAG} version restored ${JSON.stringify({ document_id: resolved.id, version_id: command.versionId, request_id: requestId, revision: mutation?.["revision"] ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document, mutation });
+    writeLine(door.io.stdout, mutation?.["reason"] === "unchanged"
+        ? `That version already matched the page; nothing changed (revision ${String(mutation?.["revision"] ?? "?")}).`
+        : `Restored the version as the current text of ${String(document["title"] ?? resolved.id)}, revision ${String(mutation?.["revision"] ?? "?")}. What was there before is kept as a version.`);
+    return 0;
+}

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

@@ -0,0 +1,104 @@
+/**
+ * `cockpit docs templates|refs|review|maintenance` and `docs create --template` argument parsing (BLI-21849, docs parity step 11).
+ *
+ * `templates` lists the curated templates. `create --template <id|slug> --title <t>` copies one into a new page (no body is accepted
+ * beside a template). `refs <id|slug>` shows links from and to a page. `review <id|slug>` shows the owner and review schedule;
+ * with `--owner <email|me|none>`, `--every <days>`, `--no-schedule` or `--reviewed` it changes them. `maintenance [--mine] [--state ...]`
+ * lists pages that are due, unowned or yours. The door checks authority; this file only checks shape.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const VALUE_FLAGS = ["--home", "--dashboard-url", "--template", "--title", "--parent", "--visibility", "--owner", "--every", "--state"];
+const BOOLEAN_FLAGS = ["--json", "--mine", "--no-schedule", "--reviewed"];
+const STATES = ["review_due", "unowned", "all"];
+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 isDocsRefsInvocation(args) {
+    return ["templates", "refs", "review", "maintenance"].includes(args[0] ?? "") || (args[0] === "create" && args.some((arg) => arg === "--template" || arg.startsWith("--template=")));
+}
+export function parseDocsRefsArgs(args) {
+    const values = parseNamedArgs(args, { allowedFlags: [...VALUE_FLAGS, ...BOOLEAN_FLAGS], 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 only = (allowed) => {
+        for (const flag of [...VALUE_FLAGS.slice(2), ...BOOLEAN_FLAGS.slice(1)]) {
+            const given = values.flags.has(flag) || values.booleans.has(flag);
+            if (given && !allowed.includes(flag))
+                throw new Error(`${flag} does not belong to \`cockpit docs ${verb}\`.`);
+        }
+    };
+    if (verb === "templates") {
+        only([]);
+        if (rest.length !== 0)
+            throw new Error("docs templates takes no arguments.");
+        return { ...base, action: "templates" };
+    }
+    if (verb === "create") {
+        only(["--template", "--title", "--parent", "--visibility"]);
+        if (rest.length !== 0)
+            throw new Error("docs create --template takes no body: the template's text is the body. Use --title for the name.");
+        const title = optionalNonEmpty(values.flags.get("--title"));
+        if (!title)
+            throw new Error("docs create needs --title.");
+        const parent = optionalNonEmpty(values.flags.get("--parent"));
+        if (parent && !UUID.test(parent))
+            throw new Error("--parent must be a document id (a UUID).");
+        const visibility = optionalNonEmpty(values.flags.get("--visibility"));
+        if (visibility && visibility !== "org" && visibility !== "private")
+            throw new Error("--visibility must be org or private.");
+        return {
+            ...base,
+            action: "create",
+            title,
+            ...(parent ? { parentId: parent } : {}),
+            ...(visibility ? { visibility: visibility } : {}),
+            docsRefs: { templateId: optionalNonEmpty(values.flags.get("--template")) },
+        };
+    }
+    if (verb === "maintenance") {
+        only(["--mine", "--state"]);
+        if (rest.length !== 0)
+            throw new Error("docs maintenance takes no page, e.g. `cockpit docs maintenance --state review_due`.");
+        const state = optionalNonEmpty(values.flags.get("--state")) ?? "all";
+        if (!STATES.includes(state))
+            throw new Error(`--state must be one of ${STATES.join(", ")}.`);
+        return { ...base, action: "maintenance", docsRefs: { state: state, mine: values.booleans.has("--mine") } };
+    }
+    if (rest.length !== 1)
+        throw new Error(`docs ${verb} needs exactly one page id or slug, e.g. \`cockpit docs ${verb} runbook\`.`);
+    if (verb === "refs") {
+        only([]);
+        return { ...base, action: "refs", docRef: rest[0] };
+    }
+    only(["--owner", "--every", "--no-schedule", "--reviewed"]);
+    const owner = optionalNonEmpty(values.flags.get("--owner"));
+    const everyRaw = optionalNonEmpty(values.flags.get("--every"));
+    const noSchedule = values.booleans.has("--no-schedule");
+    if (everyRaw !== undefined && noSchedule)
+        throw new Error("--every and --no-schedule say opposite things; give one.");
+    let everyDays;
+    if (everyRaw !== undefined) {
+        everyDays = /^\d+$/.test(everyRaw) ? Number(everyRaw) : Number.NaN;
+        if (!Number.isInteger(everyDays) || everyDays < 1 || everyDays > 730)
+            throw new Error("--every is a whole number of days from 1 to 730.");
+    }
+    else if (noSchedule) {
+        everyDays = null;
+    }
+    return {
+        ...base,
+        action: "review",
+        docRef: rest[0],
+        docsRefs: {
+            ...(owner !== undefined ? { owner: owner.toLowerCase() === "none" ? null : owner } : {}),
+            ...(everyDays !== undefined ? { everyDays } : {}),
+            ...(values.booleans.has("--reviewed") ? { reviewed: true } : {}),
+        },
+    };
+}

package/dist/commands/docs-refs.js

@@ -0,0 +1,153 @@
+/**
+ * `cockpit docs templates|create --template|refs|review|maintenance` (BLI-21849): templates, links between pages and
+ * page owners with review dates, over the same doors the browser calls.
+ *
+ *   templates                           GET /api/docs/templates
+ *   create --template <t> --title <x>   POST /api/docs/documents { template_id }
+ *   refs <page>                         GET /api/docs/documents/[id]/references
+ *   review <page> [--owner --every --no-schedule --reviewed]   GET or PUT /api/docs/documents/[id]/stewardship
+ *   maintenance [--mine] [--state]      GET /api/docs/maintenance
+ *
+ * The door accepts an id or a slug, so there is no lookup first. Labels come back verbatim. Titles are shown to the
+ * person and never written to a log line.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[docs refs cli]";
+const DEADLINE_MS = 30_000;
+const KIND = { doc: "page", ticket: "ticket", note: "meeting note" };
+const list = (value) => (Array.isArray(value) ? value : []);
+const str = (value) => (typeof value === "string" ? value : "");
+export async function runDocsRefs(command, door) {
+    switch (command.action) {
+        case "templates": return templates(door);
+        case "create": return createFromTemplate(command, door);
+        case "refs": return refs(command, door);
+        case "review": return review(command, door);
+        case "maintenance": return maintenance(command, door);
+        default: return failAgentDoor(door, TAG, "invalid_body", "Try templates, create --template, refs, review or maintenance.");
+    }
+}
+async function templates(door) {
+    const answer = await askAgentDoor(door, { path: "/api/docs/templates", method: "GET", label: "docs templates", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const found = list(body["templates"]);
+    writeLine(door.io.stderr, `${TAG} templates ${JSON.stringify({ returned: found.length, templates_page: body["templates_page_id"] !== null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    if (found.length === 0)
+        writeLine(door.io.stdout, str(body["hint"]) || "The templates page has no templates yet. Add a child page for each.");
+    for (const template of found)
+        writeLine(door.io.stdout, `${str(template["id"])}  ${str(template["slug"]) || "-"}  rev ${String(template["revision"])}  ${str(template["title"])}`);
+    if (found.length > 0)
+        writeLine(door.io.stdout, `${found.length} template(s). Create one with: cockpit docs create --template <id|slug> --title "<title>".`);
+    return 0;
+}
+async function createFromTemplate(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/docs/documents",
+        method: "POST",
+        label: "docs create from template",
+        timeoutMs: 60_000,
+        body: {
+            title: command.title,
+            template_id: command.docsRefs?.templateId,
+            ...(command.parentId ? { parent_id: command.parentId } : {}),
+            ...(command.visibility ? { visibility: command.visibility } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const document = (body["document"] ?? {});
+    const recorded = body["provenance_recorded"] !== false;
+    writeLine(door.io.stderr, `${TAG} created ${JSON.stringify({ document_id: document["id"] ?? null, provenance_recorded: recorded })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document, template: body["template"] ?? null, provenance_recorded: recorded });
+    writeLine(door.io.stdout, `Created ${str(document["title"])} (${str(document["id"])}) from the template.`);
+    if (!recorded)
+        writeLine(door.io.stdout, "The page was created, but its template link could not be recorded (provenance_recorded: false).");
+    return 0;
+}
+async function refs(command, door) {
+    const answer = await askAgentDoor(door, { path: `/api/docs/documents/${encodeURIComponent(command.docRef ?? "")}/references`, method: "GET", label: "docs refs", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const backlinks = list(body["backlinks"]);
+    const outgoing = list(body["outgoing"]);
+    const coverage = (body["coverage"] ?? {});
+    writeLine(door.io.stderr, `${TAG} refs ${JSON.stringify({ document_id: body["document_id"] ?? null, backlinks: backlinks.length, outgoing: outgoing.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    writeLine(door.io.stdout, "Linked from:");
+    if (backlinks.length === 0)
+        writeLine(door.io.stdout, "  nothing you can read links here");
+    for (const link of backlinks)
+        writeLine(door.io.stdout, `  ${str(link["id"])}  ${str(link["title"])}`);
+    writeLine(door.io.stdout, "Links on this page:");
+    const readable = outgoing.filter((entry) => entry["state"] !== "unavailable");
+    if (readable.length === 0)
+        writeLine(door.io.stdout, "  none");
+    for (const entry of readable)
+        writeLine(door.io.stdout, `  ${KIND[entry["kind"]] ?? str(entry["kind"])}  ${str(entry["key"])}  ${str(entry["title"])}`);
+    const gone = outgoing.filter((entry) => entry["state"] === "unavailable");
+    if (gone.length > 0) {
+        writeLine(door.io.stdout, "Not available to you:");
+        for (const entry of gone)
+            writeLine(door.io.stdout, `  ${KIND[entry["kind"]] ?? str(entry["kind"])}  ${str(entry["key"])}`);
+    }
+    writeLine(door.io.stdout, `Coverage: linked from ${str((coverage["backlinks"] ?? {})["coverage"])}, links on this page ${str((coverage["outgoing"] ?? {})["coverage"])}.`);
+    return 0;
+}
+async function review(command, door) {
+    const given = command.docsRefs ?? {};
+    const write = given.owner !== undefined || given.everyDays !== undefined || given.reviewed === true;
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(command.docRef ?? "")}/stewardship`,
+        method: write ? "PUT" : "GET",
+        label: write ? "docs review set" : "docs review",
+        timeoutMs: 60_000,
+        ...(write
+            ? { body: { ...(given.owner !== undefined ? { owner: given.owner } : {}), ...(given.everyDays !== undefined ? { review_every_days: given.everyDays } : {}), ...(given.reviewed ? { reviewed: true } : {}) } }
+            : {}),
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const steward = (answer.body["stewardship"] ?? {});
+    writeLine(door.io.stderr, `${TAG} review ${JSON.stringify({ document_id: steward["document_id"] ?? null, write, state: steward["state"] ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, stewardship: steward });
+    const owner = steward["owner"];
+    const reviewer = steward["last_reviewed_by"];
+    writeLine(door.io.stdout, `Owner: ${owner ? `${str(owner["name"])} <${str(owner["email"])}>` : "none"}`);
+    writeLine(door.io.stdout, `Review every: ${steward["review_every_days"] ? `${String(steward["review_every_days"])} days` : "no schedule"}`);
+    writeLine(door.io.stdout, `Last reviewed: ${steward["last_reviewed_at"] ? `${str(steward["last_reviewed_at"])} by ${reviewer ? str(reviewer["name"]) : "unknown"}` : "never"}`);
+    writeLine(door.io.stdout, `State: ${str(steward["state"])}${steward["review_due_at"] ? ` (due ${str(steward["review_due_at"])})` : ""}`);
+    return 0;
+}
+async function maintenance(command, door) {
+    const given = command.docsRefs ?? {};
+    const params = new URLSearchParams({ state: given.state ?? "all" });
+    if (given.mine)
+        params.set("owner", "me");
+    const answer = await askAgentDoor(door, { path: `/api/docs/maintenance?${params.toString()}`, method: "GET", label: "docs maintenance", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const items = list(body["items"]);
+    const coverage = (body["coverage"] ?? {});
+    writeLine(door.io.stderr, `${TAG} maintenance ${JSON.stringify({ returned: items.length, coverage: coverage["coverage"] ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    if (items.length === 0)
+        writeLine(door.io.stdout, "No page needs a person right now.");
+    for (const item of items) {
+        const owner = item["owner"];
+        writeLine(door.io.stdout, `${str(item["id"])}  ${list(item["reasons"]).join("+") || str(item["state"])}  ${owner ? str(owner["name"]) : "no owner"}  ${str(item["title"])}`);
+    }
+    writeLine(door.io.stdout, `${items.length} page(s) shown from ${String(coverage["scanned"] ?? 0)} checked, coverage ${str(coverage["coverage"])}.`);
+    return 0;
+}