@bli-cockpit/cli 0.2.242 → 0.2.244

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;
+}

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

@@ -0,0 +1,79 @@
+/**
+ * The docs-search flags shared by `cockpit docs search` and `cockpit search --kind doc` (BLI-21697, docs parity
+ * step 6): `--title-only`, `--word`, `--by <me|email|id>`, `--under <id|slug>`, `--since` / `--until`
+ * (`YYYY-MM-DD`, inclusive local days on `updated_at`), `--timezone <IANA>` and `--sort relevance|updated`. One
+ * reader and one query-string writer, so the two commands cannot mean different things. The door checks the
+ * values; this file only checks shape.
+ */
+import { optionalNonEmpty } from "./local-arg-values.js";
+export const DOC_SEARCH_VALUE_FLAGS = ["--by", "--under", "--sort"];
+export const DOC_SEARCH_BOOLEAN_FLAGS = ["--title-only", "--word"];
+/** Flags only a docs search reads (`--since`, `--until` and `--timezone` are shared with the message search). */
+export const DOC_SEARCH_ONLY_FLAGS = [...DOC_SEARCH_VALUE_FLAGS, ...DOC_SEARCH_BOOLEAN_FLAGS];
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+function machineZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    catch {
+        return "UTC";
+    }
+}
+function day(flag, value) {
+    const given = optionalNonEmpty(value);
+    if (given === undefined)
+        return undefined;
+    if (!DAY.test(given))
+        throw new Error(`${flag} takes a day written YYYY-MM-DD, not "${given}".`);
+    return given;
+}
+/** Reads the flags. The machine's IANA zone is sent unless `--timezone` is given. */
+export function readDocSearchFilters(values) {
+    const since = day("--since", values.flags.get("--since"));
+    const until = day("--until", values.flags.get("--until"));
+    if (since && until && since > until)
+        throw new Error(`--since ${since} is after --until ${until}.`);
+    const sort = optionalNonEmpty(values.flags.get("--sort"));
+    if (sort !== undefined && sort !== "relevance" && sort !== "updated") {
+        throw new Error(`--sort takes relevance or updated, not "${sort}".`);
+    }
+    const by = optionalNonEmpty(values.flags.get("--by"));
+    const under = optionalNonEmpty(values.flags.get("--under"));
+    return {
+        ...(values.booleans.has("--title-only") ? { titleOnly: true } : {}),
+        ...(values.booleans.has("--word") ? { wholeWord: true } : {}),
+        ...(by ? { by } : {}),
+        ...(under ? { under } : {}),
+        ...(since ? { since } : {}),
+        ...(until ? { until } : {}),
+        timezone: optionalNonEmpty(values.flags.get("--timezone")) ?? machineZone(),
+        ...(sort ? { sort } : {}),
+    };
+}
+/** True when a flag that narrows by person, subtree or date was given (an empty query is then allowed). */
+export function hasDocScopeFlags(filters) {
+    return Boolean(filters.by || filters.under || filters.since || filters.until);
+}
+/** True when any docs-only flag was given (so `cockpit search` can refuse them without `--kind doc`). */
+export function hasDocSearchFlags(filters) {
+    return Boolean(filters.titleOnly || filters.wholeWord || filters.sort || hasDocScopeFlags(filters));
+}
+/** The query parameters `GET /api/docs/search` and `GET /api/search` read. */
+export function appendDocSearchParams(params, filters) {
+    if (filters.titleOnly)
+        params.set("title_only", "1");
+    if (filters.wholeWord)
+        params.set("word", "1");
+    if (filters.by)
+        params.set("by", filters.by);
+    if (filters.under)
+        params.set("under", filters.under);
+    if (filters.since)
+        params.set("since", filters.since);
+    if (filters.until)
+        params.set("until", filters.until);
+    if (filters.timezone)
+        params.set("tz", filters.timezone);
+    if (filters.sort)
+        params.set("sort", filters.sort);
+}

package/dist/commands/docs-search.js

@@ -0,0 +1,64 @@
+/**
+ * `cockpit docs search` (BLI-21697, docs parity step 6): the library searched by title or text, narrowed by
+ * person, subtree and day, over `GET /api/docs/search` — the SAME door the web box calls, so the ids match the
+ * browser, MCP `docs_search` and JARVIS `searchDocs`. Nothing is matched on this side.
+ *
+ * It prints the hits, `matched/returned` and the coverage line. A walk that stopped early is said out loud
+ * (`capped`, `failed_partial`), never folded into "nothing matched". A door refusal keeps its own `reason` and
+ * sentence (`invalid_filter` names the bad field).
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { appendDocSearchParams } from "./docs-search-args.js";
+const TAG = "[docs search cli]";
+const READ_DEADLINE_MS = 30_000;
+export function docsSearchPath(command) {
+    const params = new URLSearchParams();
+    if (command.query)
+        params.set("q", command.query);
+    appendDocSearchParams(params, command.searchFilters ?? {});
+    if (command.limit !== undefined)
+        params.set("limit", String(command.limit));
+    return `/api/docs/search?${params.toString()}`;
+}
+/** The sentence under the hits: the walk's honesty, in words. */
+export function docsSearchCoverageLine(body) {
+    const counts = `${body.returned ?? 0} of ${body.matched ?? 0} shown`;
+    if (body.coverage === "capped")
+        return `Coverage: capped after ${body.searched ?? 0} pages searched; more exist (${counts}).`;
+    if (body.coverage === "failed_partial") {
+        return `Coverage: partial, some pages could not be searched${body.coverage_reason ? ` (${body.coverage_reason})` : ""} (${counts}).`;
+    }
+    return `Coverage: exhausted (${counts}).`;
+}
+export async function searchDocs(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: docsSearchPath(command),
+        method: "GET",
+        label: "docs search",
+        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, body);
+    const results = body.results ?? [];
+    if (results.length === 0) {
+        writeLine(door.io.stdout, body.coverage === "exhausted" || body.coverage === undefined
+            ? "Nothing you can read matches that."
+            : "Nothing in the pages searched matches that.");
+    }
+    for (const result of results) {
+        writeLine(door.io.stdout, `${result.title}  (${result.slug ?? result.id})`);
+        const where = result.matched_in ? `matched in ${result.matched_in}  ·  ` : "";
+        writeLine(door.io.stdout, `  ${where}${result.id}  ·  updated ${result.updated_at}`);
+        if (result.snippet)
+            writeLine(door.io.stdout, `  ${result.snippet}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${body.returned ?? results.length}/${body.matched ?? results.length} matched/returned.`);
+    writeLine(door.io.stdout, docsSearchCoverageLine(body));
+    console.error(`${TAG} searched`, JSON.stringify({ matched: body.matched ?? 0, returned: results.length, coverage: body.coverage ?? "unknown" }));
+    return 0;
+}

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

@@ -0,0 +1,82 @@
+/**
+ * `cockpit docs sync-resolve|manifest` argument parsing (BLI-21875, docs parity step 12). `sync-status` keeps its parser in
+ * `local-args-tower-docs-msg.ts`; its single-page answer gained detail, not flags.
+ *
+ *   sync-resolve <id|slug> --version <id> --keep-current|--use-kept [--expected-revision N] [--request-id U]
+ *   manifest [--under <id|slug>] [--cursor C] [--all] [--out <file>]
+ *
+ * The door checks authority and the revision; this file only checks shape. It never picks a choice for the person.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const VALUE_FLAGS = ["--home", "--dashboard-url", "--version", "--expected-revision", "--request-id", "--under", "--cursor", "--out"];
+const BOOLEAN_FLAGS = ["--json", "--keep-current", "--use-kept", "--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 isDocsSyncInvocation(args) {
+    return args[0] === "sync-resolve" || args[0] === "manifest";
+}
+export function parseDocsSyncArgs(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 === "manifest") {
+        only(["--under", "--cursor", "--all", "--out"]);
+        if (rest.length !== 0)
+            throw new Error("docs manifest takes no page; use --under <id|slug> for one subtree.");
+        const cursor = optionalNonEmpty(values.flags.get("--cursor"));
+        return {
+            ...base,
+            action: "manifest",
+            ...(cursor ? { cursor } : {}),
+            all: values.booleans.has("--all"),
+            outPath: optionalNonEmpty(values.flags.get("--out")),
+            docsSync: { under: optionalNonEmpty(values.flags.get("--under")) },
+        };
+    }
+    only(["--version", "--keep-current", "--use-kept", "--expected-revision", "--request-id"]);
+    if (rest.length !== 1)
+        throw new Error("docs sync-resolve needs exactly one page id or slug, e.g. `cockpit docs sync-resolve runbook --version <id> --use-kept`.");
+    const keep = values.booleans.has("--keep-current");
+    const useKept = values.booleans.has("--use-kept");
+    if (keep === useKept) {
+        throw new Error("docs sync-resolve needs exactly one choice: --keep-current (keep the page's current text) or --use-kept (make the kept version current). Tower does not choose for you.");
+    }
+    const versionId = optionalNonEmpty(values.flags.get("--version"));
+    if (!versionId || !UUID.test(versionId))
+        throw new Error("docs sync-resolve needs --version <id>, the kept version's id (a UUID from `cockpit docs sync-status <page>`).");
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    if (requestId && !UUID.test(requestId))
+        throw new Error("--request-id must be a UUID.");
+    const revisionRaw = optionalNonEmpty(values.flags.get("--expected-revision"));
+    let expectedRevision;
+    if (revisionRaw !== undefined) {
+        if (keep)
+            throw new Error("--expected-revision belongs with --use-kept: --keep-current writes no text.");
+        expectedRevision = /^\d+$/.test(revisionRaw) ? Number(revisionRaw) : Number.NaN;
+        if (!Number.isInteger(expectedRevision) || expectedRevision < 1)
+            throw new Error("--expected-revision is a positive whole number (the page revision you read).");
+    }
+    return {
+        ...base,
+        action: "sync-resolve",
+        docRef: rest[0],
+        versionId,
+        ...(requestId ? { requestId } : {}),
+        ...(expectedRevision !== undefined ? { expectedRevision } : {}),
+        docsSync: { choice: keep ? "keep_current" : "use_kept_version" },
+    };
+}

package/dist/commands/docs-sync.js

@@ -0,0 +1,197 @@
+/**
+ * `cockpit docs sync-status <page>` detail, `sync-resolve` and `manifest` (BLI-21875): the Notion sync of one page and the
+ * library export manifest, over the same doors the browser calls.
+ *
+ *   sync-status <page>   GET  /api/docs/documents/[id]/notion-sync
+ *   sync-resolve <page>  POST /api/docs/documents/[id]/notion-sync/resolve
+ *   manifest             GET  /api/docs/manifest[?cursor=&under=]
+ *
+ * Every line about a receipt, a loss or a conflict is the door's own `sentence`, printed verbatim, so this terminal says
+ * what the web panel, the MCP tool and JARVIS say. Tower never asks Notion from a request: the answer is what the last
+ * passes recorded, with its age. `manifest` reports readiness; it gives no cutover verdict.
+ */
+import { open } from "node:fs/promises";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[docs sync cli]";
+const READ_DEADLINE_MS = 60_000;
+const WRITE_DEADLINE_MS = 60_000;
+/** 100 calls of 2,000 pages: the most `manifest --all` walks before it says `capped`. */
+const MANIFEST_MAX_CALLS = 100;
+const list = (value) => (Array.isArray(value) ? value : []);
+const str = (value) => (typeof value === "string" ? value : "");
+const num = (value) => (typeof value === "number" ? value : 0);
+const object = (value) => (typeof value === "object" && value !== null ? value : {});
+export async function runDocsSync(command, door) {
+    switch (command.action) {
+        case "sync-resolve": return syncResolve(command, door);
+        case "manifest": return manifest(command, door);
+        default: return failAgentDoor(door, TAG, "invalid_body", "Try sync-status <page>, sync-resolve or manifest.");
+    }
+}
+/** One page's sync status: the list row plus the receipts, losses, conflicts and decisions the door's `detail` carries. */
+export function printSyncDetail(door, ref, body) {
+    const detail = object(body["detail"]);
+    const conflicts = object(detail["conflicts"]);
+    writeLine(door.io.stderr, `${TAG} status ${JSON.stringify({ conflicts: conflicts["total"] ?? null, open: conflicts["open"] ?? null, incomplete: list(detail["incomplete"]).length })}`);
+    const row = list(body["documents"])[0] ?? {};
+    writeLine(door.io.stdout, `${str(row["id"])}  ${str(row["state"])}  ${str(row["slug"]) || "(no slug)"}  ${str(row["title"])}`);
+    writeLine(door.io.stdout, str(detail["state_sentence"]));
+    const receipts = object(detail["last_receipt"]);
+    for (const direction of ["push", "pull"]) {
+        const receipt = object(receipts[direction]);
+        writeLine(door.io.stdout, str(receipt["sentence"]) || `${direction === "push" ? "Push" : "Pull"}: no check recorded for this page yet.`);
+    }
+    const losses = object(detail["losses"]);
+    for (const line of Array.isArray(losses["sentences"]) ? losses["sentences"].map(str) : [])
+        writeLine(door.io.stdout, `Loss: ${line}`);
+    for (const name of Array.isArray(detail["incomplete"]) ? detail["incomplete"].map(str) : []) {
+        writeLine(door.io.stdout, `Could not read just now: ${name}`);
+    }
+    const items = list(conflicts["items"]);
+    for (const item of items) {
+        const resolution = object(item["resolution"]);
+        const status = str(item["status"]) === "open" ? "OPEN    " : "resolved";
+        const decided = str(item["status"]) === "open" ? "" : `  decision: ${str(resolution["choice"])} at ${str(resolution["resolved_at"])}`;
+        writeLine(door.io.stdout, `Conflict ${status}  version ${str(item["version_id"])}  (v${num(item["version_number"])}, kept ${str(item["kept_at"])})  ${str(item["sentence"])}${decided}`);
+    }
+    writeLine(door.io.stdout, `${num(conflicts["total"])} conflict(s) kept, ${num(conflicts["open"])} open; showing the newest ${items.length}. As of ${str(detail["as_of"])}.`);
+    if (num(conflicts["open"]) > 0) {
+        writeLine(door.io.stdout, detail["can_edit"] === true
+            ? `Resolve: cockpit docs sync-resolve ${ref} --version <version id> --keep-current | --use-kept [--expected-revision N]. ${str(detail["resolve_note"])}`
+            : "You can read this page but not edit it, so you cannot resolve its conflicts.");
+    }
+    return 0;
+}
+async function syncResolve(command, door) {
+    const ref = command.docRef ?? "";
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(ref)}/notion-sync/resolve`,
+        method: "POST",
+        label: "docs sync-resolve",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            version_id: command.versionId,
+            choice: command.docsSync?.choice,
+            ...(command.expectedRevision !== undefined ? { expected_revision: command.expectedRevision } : {}),
+            ...(command.requestId ? { request_id: command.requestId } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} resolve ${JSON.stringify({ outcome: body["outcome"] ?? null, choice: object(body["resolution"])["choice"] ?? null, body_written: body["body_written"] ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ...body, ok: true });
+    const resolution = object(body["resolution"]);
+    writeLine(door.io.stdout, str(body["outcome"]) === "already_resolved"
+        ? `Already resolved (${str(resolution["choice"])}, ${str(resolution["resolved_at"])}). Nothing was changed.`
+        : `Recorded ${str(resolution["choice"])} for version ${str(resolution["version_id"])}. Page revision now ${String(body["revision"] ?? "unknown")}${body["body_written"] === true ? "; the kept text is now current" : ""}.`);
+    writeLine(door.io.stdout, str(body["note"]));
+    return 0;
+}
+async function manifest(command, door) {
+    const totals = { entries: [], seen: new Set(), requested: 0, returned: 0, failures: [] };
+    let cursor = command.cursor ?? null;
+    let calls = 0;
+    let status = "exhausted";
+    let reason;
+    let nextCursor = null;
+    let under = null;
+    let generatedAt = null;
+    for (;;) {
+        const query = new URLSearchParams();
+        if (cursor)
+            query.set("cursor", cursor);
+        if (command.docsSync?.under)
+            query.set("under", command.docsSync.under);
+        const answer = await askAgentDoor(door, {
+            path: `/api/docs/manifest${query.size > 0 ? `?${query.toString()}` : ""}`,
+            method: "GET",
+            label: "docs manifest",
+            timeoutMs: READ_DEADLINE_MS,
+        });
+        if (!answer.ok) {
+            if (calls === 0)
+                return failAgentDoor(door, TAG, answer.reason, answer.detail);
+            // A later call failed: the pages already read are kept, and the cursor resumes after them.
+            status = "failed_partial";
+            reason = answer.reason;
+            nextCursor = cursor;
+            writeLine(door.io.stderr, `${TAG} manifest ${JSON.stringify({ call: calls + 1, reason: answer.reason, kept: totals.entries.length })}`);
+            break;
+        }
+        calls += 1;
+        const page = answer.body;
+        const coverage = object(page["coverage"]);
+        totals.requested += num(page["requested"]);
+        totals.returned += num(page["returned"]);
+        for (const entry of list(page["entries"])) {
+            const id = str(entry["id"]);
+            if (!totals.seen.has(id)) {
+                totals.seen.add(id);
+                totals.entries.push(entry);
+            }
+        }
+        totals.failures.push(...list(page["failures"]));
+        under = page["under"] ?? under;
+        generatedAt = page["generated_at"] ?? generatedAt;
+        nextCursor = typeof page["next_cursor"] === "string" ? page["next_cursor"] : null;
+        status = str(coverage["status"]) || "exhausted";
+        reason = str(coverage["reason"]) || undefined;
+        if (status === "failed_partial" || nextCursor === null || !command.all)
+            break;
+        if (calls >= MANIFEST_MAX_CALLS) {
+            status = "capped";
+            reason = "call_ceiling";
+            break;
+        }
+        cursor = nextCursor;
+    }
+    const result = {
+        ok: true,
+        entries: totals.entries,
+        requested: totals.requested,
+        returned: totals.returned,
+        unique: totals.seen.size,
+        coverage: { status, calls, ...(reason ? { reason } : {}) },
+        coverage_text: `${totals.seen.size} unique pages in ${calls} call(s); requested ${totals.requested}, returned ${totals.returned}; read stopped: ${status}${reason ? ` (${reason})` : ""}.`,
+        failures: totals.failures,
+        next_cursor: status === "exhausted" ? null : nextCursor,
+        under,
+        generated_at: generatedAt,
+    };
+    writeLine(door.io.stderr, `${TAG} manifest ${JSON.stringify({ calls, requested: result.requested, returned: result.returned, unique: result.unique, status, failures: result.failures.length })}`);
+    if (command.outPath) {
+        try {
+            // "wx": never overwrite a file someone already has.
+            const handle = await open(command.outPath, "wx");
+            try {
+                await handle.writeFile(`${JSON.stringify(result, null, 2)}\n`);
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            const code = error.code;
+            return failAgentDoor(door, TAG, code === "EEXIST" ? "out_exists" : "out_write_failed", code === "EEXIST" ? `${command.outPath} already exists; choose another path or remove it.` : `Could not write ${command.outPath}.`);
+        }
+        writeLine(door.io.stderr, `${TAG} manifest written ${JSON.stringify({ entries: result.entries.length })}`);
+    }
+    if (door.json)
+        return emitAgentDoor(door, command.outPath ? { ...result, entries: undefined, written_to: command.outPath, entries_written: result.entries.length } : result, status === "failed_partial" ? 1 : 0);
+    for (const entry of totals.entries.slice(0, command.outPath ? 0 : 200)) {
+        const files = Array.isArray(entry["files"]) ? `${entry["files"].length} file(s)` : "files unknown";
+        writeLine(door.io.stdout, `${str(entry["id"])}  r${num(entry["revision"])}  ${str(entry["visibility"])}  ${files}  ${str(entry["slug"]) || "(no slug)"}  ${str(entry["title"])}`);
+    }
+    if (!command.outPath && totals.entries.length > 200)
+        writeLine(door.io.stdout, `… ${totals.entries.length - 200} more; use --out <file> or --json for all of them.`);
+    writeLine(door.io.stdout, result.coverage_text);
+    for (const failure of totals.failures)
+        writeLine(door.io.stdout, `Failure: ${str(failure["stage"])} ${str(failure["reason"])} (${num(failure["count"])})`);
+    if (result.next_cursor)
+        writeLine(door.io.stdout, `More: cockpit docs manifest --cursor ${result.next_cursor}${command.docsSync?.under ? ` --under ${command.docsSync.under}` : ""}`);
+    writeLine(door.io.stdout, "This reports readiness only. It is not a cutover verdict.");
+    return status === "failed_partial" ? 1 : 0;
+}