@bli-cockpit/cli 0.2.238 → 0.2.240

package/dist/commands/cal-delete.js

@@ -1,23 +1,33 @@
 import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
 import { writeLine } from "./cli-io.js";
+import { writeScopeFacts } from "./cal-scope.js";
 const TAG = "[cal cli]";
 const DELETE_DEADLINE_MS = 60_000;
 export async function runCalDelete(command, door) {
+    const query = new URLSearchParams();
+    if (command.accountName)
+        query.set("account", command.accountName);
+    if (command.scope)
+        query.set("scope", command.scope);
+    if (command.occurrenceStart)
+        query.set("occurrence_start", command.occurrenceStart);
     const answer = await askAgentDoor(door, {
-        path: `/api/cal/events/${encodeURIComponent(command.subjectId ?? "")}${command.accountName ? `?account=${encodeURIComponent(command.accountName)}` : ""}`,
+        path: `/api/cal/events/${encodeURIComponent(command.subjectId ?? "")}${query.size > 0 ? `?${query.toString()}` : ""}`,
         method: "DELETE",
         label: "cal delete",
         timeoutMs: DELETE_DEADLINE_MS,
     });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const deleted = answer.body.deleted;
+    const full = answer.body;
+    const deleted = full.deleted;
     if (door.json)
-        return emitAgentDoor(door, { ok: true, deleted });
+        return emitAgentDoor(door, { ok: true, ...full });
     if (!deleted) {
         writeLine(door.io.stdout, "Tower answered without a result. Nothing to report.");
         return 0;
     }
+    writeScopeFacts(door, full);
     if (deleted.account_name)
         writeLine(door.io.stdout, `Account: ${deleted.account_name}.`);
     const alreadyGone = deleted.google === "already_gone_at_google";

package/dist/commands/cal-direct.js

@@ -0,0 +1,119 @@
+/**
+ * `cockpit cal duplicate | batch | undo` (BLI-21296, calendar slice 4): the
+ * terminal in front of the same doors the browser's grid uses. `batch` reads
+ * its changes as JSON on stdin; every verb takes `--idempotency-key` so a retry
+ * writes once, and `--json` prints the door's answer untouched.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+const TAG = "[cal cli]";
+const WRITE_DEADLINE_MS = 300_000;
+export async function runCalDirect(command, door) {
+    if (command.action === "duplicate")
+        return duplicate(command, door);
+    if (command.action === "batch")
+        return batch(command, door);
+    return undo(command, door);
+}
+function keyed(command) {
+    return {
+        ...(command.idempotencyKey ? { idempotency_key: command.idempotencyKey } : {}),
+        ...(command.reason ? { reason: command.reason } : {}),
+    };
+}
+function writeReceiptLines(door, receipt) {
+    if (receipt.event?.account_name)
+        writeLine(door.io.stdout, `Account: ${receipt.event.account_name}.`);
+    if (receipt.event?.event_id)
+        writeLine(door.io.stdout, `Tower event: ${receipt.event.event_id}`);
+    if (receipt.change_id)
+        writeLine(door.io.stdout, `Change: ${receipt.change_id} (undo with: cockpit cal undo ${receipt.change_id})`);
+    else
+        writeLine(door.io.stdout, "Google took the change but Tower could not record it in the ledger, so there is no change id to undo.");
+    if (receipt.event?.version)
+        writeLine(door.io.stdout, `Version: ${receipt.event.version}`);
+    if (receipt.replayed)
+        writeLine(door.io.stdout, "This key was used before: nothing new was written; this is the first receipt.");
+}
+async function duplicate(command, door) {
+    const answer = await askAgentDoor(door, {
+        method: "POST",
+        path: `/api/cal/events/${encodeURIComponent(command.subjectId ?? "")}/duplicate`,
+        label: "cal duplicate",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            ...(command.startsAt ? { starts_at: command.startsAt } : {}),
+            ...(command.endsAt ? { ends_at: command.endsAt } : {}),
+            ...(command.calendarId ? { calendar_id: command.calendarId } : {}),
+            ...(command.accountName ? { account: command.accountName } : {}),
+            ...(command.keepInvitees ? { keep_invitees: true } : {}),
+            ...keyed(command),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    const receipt = answer.body;
+    writeLine(door.io.stdout, `Duplicated "${receipt.event?.title ?? "the event"}". ${receipt.invitees === "kept" ? "The same guests were invited (Google emailed them)." : "No guests were invited."}`);
+    writeReceiptLines(door, receipt);
+    return 0;
+}
+async function readBatchBody(door) {
+    if (isInteractiveStdin(door.io))
+        return null;
+    try {
+        const parsed = JSON.parse(await readPipedText(door.io.stdin, { maxChars: 200_000, overflowMessage: "The batch is too large." }));
+        if (Array.isArray(parsed))
+            return { changes: parsed };
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function batch(command, door) {
+    const body = await readBatchBody(door);
+    if (!body || !Array.isArray(body.changes)) {
+        return failAgentDoor(door, TAG, "invalid_body", 'Pipe JSON: {"changes":[{"event_id":"…","starts_at":"…","ends_at":"…","expected_version":"…"}]} (or a bare array). Up to 25 changes, each event once.');
+    }
+    const answer = await askAgentDoor(door, {
+        method: "POST",
+        path: "/api/cal/events/batch",
+        label: "cal batch",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { ...body, ...keyed(command) },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const result = answer.body;
+    // A script must be able to tell "all of it" from "some of it" without parsing: exit 1 unless every item was written.
+    const code = result.outcome === "all_committed" ? 0 : 1;
+    if (door.json)
+        return emitAgentDoor(door, { ok: code === 0, ...result }, code);
+    for (const item of result.items) {
+        writeLine(door.io.stdout, `#${item.index + 1} ${item.event_id}: ${item.outcome}${item.reason ? ` (${item.reason})` : ""}${item.change_id ? ` change ${item.change_id}` : ""}`);
+    }
+    writeLine(door.io.stdout, `${result.committed} of ${result.items.length} changed (${result.outcome.replaceAll("_", " ")}).`);
+    if (result.unchanged.length > 0) {
+        writeLine(door.io.stdout, `Left as they were: ${result.unchanged.map((item) => `#${item.index + 1} ${item.event_id}`).join(", ")}.`);
+    }
+    return code;
+}
+async function undo(command, door) {
+    const answer = await askAgentDoor(door, {
+        method: "POST",
+        path: "/api/cal/undo",
+        label: "cal undo",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { ...(command.subjectId ? { change_id: command.subjectId } : {}), ...keyed(command) },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    const receipt = answer.body;
+    writeLine(door.io.stdout, `Undid change ${receipt.undoes_change_id}. The earlier values are back (or the created event is gone); guests, if any, were told by Google.`);
+    writeReceiptLines(door, receipt);
+    return 0;
+}

package/dist/commands/cal-scope.js

@@ -0,0 +1,71 @@
+/**
+ * Recurring-event scope, RSVP and event-detail flags for `cockpit cal`
+ * (BLI-21311, slice 5). The scope words ("this event", "this and following
+ * events", "all events") come from the door and are printed as it sent them;
+ * this module only builds the request fields and says what came back.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[cal cli]";
+const WRITE_DEADLINE_MS = 60_000;
+/** `scope` and `occurrence_start`, only when the caller gave them. */
+export function scopeFields(command) {
+    return {
+        ...(command.scope ? { scope: command.scope } : {}),
+        ...(command.occurrenceStart ? { occurrence_start: command.occurrenceStart } : {}),
+    };
+}
+/** `color_id`, `reminders`, `visibility`, `transparency`, only when given. */
+export function detailFields(command) {
+    return {
+        ...(command.colorId !== undefined ? { color_id: command.colorId } : {}),
+        ...(command.reminders !== undefined ? { reminders: command.reminders } : {}),
+        ...(command.visibility ? { visibility: command.visibility } : {}),
+        ...(command.transparency ? { transparency: command.transparency } : {}),
+    };
+}
+/** Prints the scope label, occurrence, split ids and notice the door answered with. */
+export function writeScopeFacts(door, facts) {
+    if (facts.scope_label)
+        writeLine(door.io.stdout, `Applied to: ${facts.scope_label}${facts.occurrence_start ? ` (occurrence ${facts.occurrence_start})` : ""}.`);
+    if (facts.trimmed_until)
+        writeLine(door.io.stdout, `Series now ends: ${facts.trimmed_until}.`);
+    const split = facts.series_split;
+    if (split) {
+        writeLine(door.io.stdout, `New series: ${split.new_series_id ?? "unknown"}. Trimmed series: ${split.trimmed_series_id ?? "unknown"}${split.trimmed_until ? ` (until ${split.trimmed_until})` : ""}.`);
+        if (split.atomic === false)
+            writeLine(door.io.stdout, "The split ran in steps and is not atomic; check both series.");
+    }
+    if (facts.notice)
+        writeLine(door.io.stdout, facts.notice);
+}
+export async function runCalRsvp(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/cal/events/${encodeURIComponent(command.subjectId ?? "")}/rsvp`,
+        method: "POST",
+        label: "cal rsvp",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            response: command.rsvpResponse,
+            ...(command.rsvpComment ? { comment: command.rsvpComment } : {}),
+            ...(command.accountName ? { account: command.accountName } : {}),
+            ...scopeFields(command),
+            ...(command.expectedVersion ? { expected_version: command.expectedVersion } : {}),
+            ...(command.idempotencyKey ? { idempotency_key: command.idempotencyKey } : {}),
+            ...(command.reason ? { reason: command.reason } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    const body = answer.body;
+    const rsvp = body.rsvp;
+    writeLine(door.io.stdout, `RSVP ${rsvp?.response ?? command.rsvpResponse}${rsvp?.previous_response ? ` (was ${rsvp.previous_response})` : ""}${body.replayed ? " - already recorded, nothing sent again" : ""}.`);
+    writeScopeFacts(door, { scope_label: rsvp?.scope_label, occurrence_start: rsvp?.occurrence_start, notice: body.notice });
+    if (body.change_id)
+        writeLine(door.io.stdout, `Change: ${body.change_id}`);
+    if (body.version)
+        writeLine(door.io.stdout, `Version: ${body.version}`);
+    return 0;
+}

package/dist/commands/cal.js

@@ -25,6 +25,8 @@ import { runCalAddIcal, runCalDetach, runCalShare, runCalSync } from "./cal-cale
 import { runCalDetail } from "./cal-detail.js";
 import { runCalOverlay } from "./cal-overlay.js";
 import { runCalDelete } from "./cal-delete.js";
+import { detailFields, runCalRsvp, scopeFields, writeScopeFacts } from "./cal-scope.js";
+import { runCalDirect } from "./cal-direct.js";
 import { runCalSyncStatus } from "./cal-sync-status.js";
 import { writeLine } from "./cli-io.js";
 import { cacheAgeLabel, cacheCoverage, readThroughCache } from "./read-cache.js";
@@ -37,6 +39,10 @@ export async function runCal(command, io) {
         case "event":
         case "export":
             return runCalDetail(command, door);
+        case "duplicate":
+        case "batch":
+        case "undo":
+            return runCalDirect(command, door);
         case "conflicts":
         case "calendar-change":
             return runCalOverlay(command, door);
@@ -62,6 +68,8 @@ export async function runCal(command, io) {
             return runCalSyncStatus(command, door);
         case "change":
             return changeEvent(command, door);
+        case "rsvp":
+            return runCalRsvp(command, door);
         case "cancel":
         case "delete":
             return runCalDelete(command, door);
@@ -299,6 +307,9 @@ async function create(command, door) {
             ...(command.allDay ? { all_day: true } : {}),
             ...(command.attendees.length > 0 ? { attendees: command.attendees } : {}),
             ...(command.meet ? { meet: true } : {}),
+            ...detailFields(command),
+            ...(command.idempotencyKey ? { idempotency_key: command.idempotencyKey } : {}),
+            ...(command.reason ? { reason: command.reason } : {}),
             time_zone: command.timeZone ?? localTimeZone(),
         },
     });
@@ -340,11 +351,31 @@ function meetingLinkText(event) {
 }
 async function changeEvent(command, door) {
     const answer = await askAgentDoor(door, { path: `/api/cal/events/${encodeURIComponent(command.subjectId)}`, method: "PATCH", label: "cal change", timeoutMs: WRITE_DEADLINE_MS,
-        body: { ...(command.accountName ? { account: command.accountName } : {}), ...(command.title ? { title: command.title } : {}), ...(command.startsAt ? { starts_at: command.startsAt } : {}), ...(command.endsAt ? { ends_at: command.endsAt } : {}), ...(command.location ? { location: command.location } : {}) } });
+        body: {
+            ...(command.accountName ? { account: command.accountName } : {}),
+            ...(command.title ? { title: command.title } : {}),
+            ...(command.startsAt ? { starts_at: command.startsAt } : {}),
+            ...(command.endsAt ? { ends_at: command.endsAt } : {}),
+            ...(command.location ? { location: command.location } : {}),
+            // BLI-21296: all-day conversion either way, and the write controls.
+            ...(command.allDay ? { all_day: true } : command.timed ? { all_day: false } : {}),
+            ...(command.timeZone && (command.allDay || command.timed) ? { time_zone: command.timeZone } : {}),
+            ...scopeFields(command),
+            ...detailFields(command),
+            ...(command.expectedVersion ? { expected_version: command.expectedVersion } : {}),
+            ...(command.idempotencyKey ? { idempotency_key: command.idempotencyKey } : {}),
+            ...(command.reason ? { reason: command.reason } : {}),
+        } });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
     if (door.json)
         return emitAgentDoor(door, { ok: true, ...answer.body });
-    writeLine(door.io.stdout, `Changed event in ${answer.body.event?.account_name ?? "its account"}.`);
+    const changed = answer.body;
+    writeLine(door.io.stdout, `Changed event in ${changed.event?.account_name ?? "its account"}.`);
+    writeScopeFacts(door, changed);
+    if (changed.change_id)
+        writeLine(door.io.stdout, `Change: ${changed.change_id} (undo with: cockpit cal undo ${changed.change_id})`);
+    if (changed.version)
+        writeLine(door.io.stdout, `Version: ${changed.version}`);
     return 0;
 }

package/dist/commands/docs-share.js

@@ -0,0 +1,81 @@
+/**
+ * `cockpit docs share` and `cockpit docs access` — named page editors from a terminal (BLI-21313).
+ * A sibling of `docs.ts`, like `docs-notion.ts`.
+ *
+ * `access <id|slug>`                      → `GET    /api/docs/documents/[id]/grants`
+ * `share <id|slug> --add <email>`         → `POST   /api/docs/documents/[id]/grants`
+ * `share <id|slug> --remove <email>`      → `DELETE /api/docs/documents/[id]/grants`
+ *
+ * The door answers with the shared permission explanation, and every refusal keeps its own reason
+ * label verbatim (`private_page_grant_needs_decision`, `not_grant_manager`, `person_not_found`, ...).
+ * A person is an exact email; the server resolves it, so this file never guesses who someone is.
+ */
+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;
+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 };
+}
+function printPermission(door, permission) {
+    for (const line of permission.reasons)
+        writeLine(door.io.stdout, line);
+    for (const editor of permission.editors)
+        writeLine(door.io.stdout, `  editor: ${editor.display_name}${editor.email ? ` <${editor.email}>` : ""}`);
+}
+export async function accessDocs(command, door) {
+    const target = await resolveOrFail(command, door);
+    if ("exit" in target)
+        return target.exit;
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(target.id)}/grants`,
+        method: "GET",
+        label: "docs access",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} access ${JSON.stringify({ document_id: target.id, role: body.permission.role, editors: body.permission.editors.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    printPermission(door, body.permission);
+    for (const event of body.events ?? []) {
+        writeLine(door.io.stdout, `  ${event.created_at}: ${event.actor_name} ${event.action === "granted" ? "added" : "removed"} ${event.grantee_name}`);
+    }
+    return 0;
+}
+export async function shareDocs(command, door) {
+    const target = await resolveOrFail(command, door);
+    if ("exit" in target)
+        return target.exit;
+    const adding = command.addPerson !== undefined;
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(target.id)}/grants`,
+        method: adding ? "POST" : "DELETE",
+        label: adding ? "docs share add" : "docs share remove",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { person: adding ? command.addPerson : command.removePerson, ...(command.reason ? { reason: command.reason } : {}) },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} share ${JSON.stringify({ document_id: target.id, action: adding ? "add" : "remove", outcome: body.outcome, reason: body.reason, request_id: body.request_id })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    const person = adding ? command.addPerson : command.removePerson;
+    writeLine(door.io.stdout, body.outcome === "unchanged"
+        ? `Nothing changed: ${person} ${adding ? "is already an editor" : "was not an editor"}.`
+        : `${adding ? "Added" : "Removed"} ${person} ${adding ? "as an editor of" : "from the editors of"} ${target.id}.`);
+    printPermission(door, body.permission);
+    return 0;
+}

package/dist/commands/docs.js

@@ -27,11 +27,13 @@
  * `document_not_writable`, `title_too_long`, `content_too_long`,
  * `circular_parent`, and so on — never rephrased here.
  */
+import { randomUUID } from "node:crypto";
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
 import { readDoc } from "./docs-read.js";
 import { exportDoc } from "./docs-export.js";
 import { linkDoc, syncStatusDocs } from "./docs-notion.js";
+import { accessDocs, shareDocs } from "./docs-share.js";
 import { readNoteFile } from "./notes-file.js";
 import { cacheAgeLabel, cacheCoverage, readThroughCache } from "./read-cache.js";
 const TAG = "[docs cli]";
@@ -59,6 +61,12 @@ export async function runDocs(command, io) {
             return syncStatusDocs(command, door);
         case "export":
             return exportDoc(command, door);
+        case "mutation-status":
+            return mutationStatusDocs(command, door);
+        case "share":
+            return shareDocs(command, door);
+        case "access":
+            return accessDocs(command, door);
     }
 }
 /** `--parent`, `--query`, `--word`, `--limit`, `--bodies` (BLI-10450) as the door's own query parameters (BLI-3737). */
@@ -248,14 +256,41 @@ async function updateDoc(command, door) {
         && !command.clearParent) {
         return failAgentDoor(door, TAG, "invalid_body", "docs update needs at least one of --title, --visibility, --parent/--clear-parent, or a body on --body-stdin/--file.");
     }
-    const answer = await updateDocument(command, door, resolved.id, bodyMarkdown);
+    // BLI-21298: every save carries a request id, so a lost response can be checked and a retry applies once.
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
+    const answer = await updateDocument(command, door, resolved.id, bodyMarkdown, requestId);
+    if (!answer.ok)
+        return refuseDocsWrite(door, answer, requestId);
+    const { document = {}, mutation } = answer.body;
+    writeLine(door.io.stderr, `${TAG} updated ${JSON.stringify({ document_id: document["id"] ?? resolved.id, request_id: requestId, revision: mutation?.["revision"] ?? document["revision"] })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document, mutation });
+    writeLine(door.io.stdout, `Updated ${String(document["title"] ?? "")} (${String(document["id"] ?? resolved.id)}), revision ${String(mutation?.["revision"] ?? document["revision"] ?? "?")}.`);
+    return 0;
+}
+/** Says where the save stands, then fails with the door's own reason (a conflict names the current revision). */
+function refuseDocsWrite(door, answer, requestId) {
+    const mutation = answer.body?.mutation;
+    writeLine(door.io.stderr, `${TAG} check the save with cockpit docs mutation-status ${requestId}; 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 } : {});
+}
+/** BLI-21298: reads only your own save receipt. A missing receipt is unknown_check_again, never "nothing changed". */
+async function mutationStatusDocs(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/mutations/${encodeURIComponent(command.docRef ?? "")}`,
+        method: "GET",
+        label: "docs mutation status",
+        timeoutMs: READ_DEADLINE_MS,
+    });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const document = answer.body.document ?? {};
-    writeLine(door.io.stderr, `${TAG} updated ${JSON.stringify({ document_id: document["id"] ?? resolved.id })}`);
     if (door.json)
-        return emitAgentDoor(door, { ok: true, document });
-    writeLine(door.io.stdout, `Updated ${String(document["title"] ?? "")} (${String(document["id"] ?? resolved.id)}).`);
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    writeLine(door.io.stdout, JSON.stringify(answer.body));
     return 0;
 }
 /**
@@ -327,13 +362,15 @@ async function deleteOneDocument(door, ref, id) {
         return { ref, ok: false, reason: answer.reason, detail: answer.detail };
     return { ref, ok: true, id };
 }
-async function updateDocument(command, door, documentId, bodyMarkdown) {
+async function updateDocument(command, door, documentId, bodyMarkdown, requestId) {
     return askAgentDoor(door, {
         path: `/api/docs/documents/${encodeURIComponent(documentId)}`,
         method: "PATCH",
         label: "docs update",
         timeoutMs: WRITE_DEADLINE_MS,
         body: {
+            request_id: requestId,
+            ...(command.expectedRevision !== undefined ? { expected_revision: command.expectedRevision } : {}),
             ...(command.title !== undefined ? { title: command.title } : {}),
             ...(bodyMarkdown !== undefined ? { body_markdown: bodyMarkdown } : {}),
             ...(command.visibility !== undefined ? { visibility: command.visibility } : {}),

package/dist/commands/drills-render.js

@@ -21,9 +21,9 @@ export function overviewLines(body) {
         lines.push(`${body.queue.newLeft} new drill${body.queue.newLeft === 1 ? "" : "s"} waiting. Run: cockpit drills start`, "");
     else
         lines.push("You are all caught up. Nothing new is waiting.", "");
-    lines.push(`Theme: ${body.theme.label}${body.theme.chosen ? "" : " (the default; change it with `cockpit drills theme set <theme>`)"}`, "");
+    lines.push(body.theme.plain ? "Theme: Plain (no theme; if you like, pick one with `cockpit drills theme set <theme>`)" : `Theme: ${body.theme.label}`, "");
     if (body.bosses.length > 0) {
-        lines.push("Bosses");
+        lines.push(body.theme.plain ? "Mistakes you are working on" : "Bosses");
         for (const boss of body.bosses)
             lines.push(`  ${boss.bossName}: ${boss.progressLine}`);
         lines.push("");

package/dist/commands/drills.js

@@ -114,11 +114,11 @@ async function themeShow(door) {
     writeLine(door.io.stderr, `${TAG} theme answered ${JSON.stringify({ key: body.theme.key, chosen: body.theme.chosen, ready: body.ready })}`);
     if (door.json)
         return emitAgentDoor(door, response.body);
-    writeLine(door.io.stdout, `Your theme: ${body.theme.label}${body.theme.chosen ? "" : " (the default)"}`);
-    writeLine(door.io.stdout, "Choices:");
+    writeLine(door.io.stdout, `Your theme: ${body.theme.label}${body.theme.chosen ? "" : " (the default: drills are shown straight, with no theme)"}`);
+    writeLine(door.io.stdout, "If you like, pick a theme (plain turns it off):");
     for (const choice of body.themes)
-        writeLine(door.io.stdout, `  ${choice.key}: ${choice.blurb}${choice.key === body.suggestedTheme && !body.theme.chosen ? "  (suggested)" : ""}`);
-    writeLine(door.io.stdout, "Or use your own words. Change it with: cockpit drills theme set <theme> [--play <what you play>] [--watch <what you watch>] [--train <what you train>]");
+        writeLine(door.io.stdout, `  ${choice.key}: ${choice.blurb}${choice.key === body.suggestedTheme && choice.key !== "plain" && !body.theme.chosen ? "  (suggested)" : ""}`);
+    writeLine(door.io.stdout, "Or type anything you're into. Change it with: cockpit drills theme set <theme> [--play <what you play>] [--watch <what you watch>] [--train <what you train>]");
     return 0;
 }
 async function themeSet(command, door) {

package/dist/commands/issue-list-page.js

@@ -0,0 +1,101 @@
+/**
+ * The cursor contract on the CLI (BLI-21315): the page fields a list prints,
+ * the extra query a page carries, and `--all`, which walks every page and
+ * streams one JSON object per line so a large export never buffers.
+ *
+ * The door (`GET /api/work/issues`) owns the filters, the order and the
+ * cursor; this file only carries them over and reports what came back. A
+ * walk that stops early still ends with a final line naming the coverage and
+ * the reason, and the command exits non-zero.
+ */
+import { askAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { READ_DEADLINE_MS, TAG, withSizeLabel } from "./issue-contracts.js";
+const ALL_PAGE_SIZE = 500;
+/** The additive page fields as `--json` output, only the ones the door sent. */
+export function pageFieldsOf(body) {
+    const fields = {};
+    for (const key of ["next_cursor", "has_more", "coverage", "requested", "returned", "unique", "failure_reason"]) {
+        if (body[key] !== undefined)
+            fields[key] = body[key];
+    }
+    return fields;
+}
+/** The sentence under a text page; null when the door sent no page fields or the page was whole. */
+export function pageFooter(body, what) {
+    if (body.coverage === undefined)
+        return null;
+    if (body.coverage === "complete")
+        return null;
+    return body.next_cursor
+        ? `More ${what} available (${body.returned ?? "?"} shown). Continue with --cursor ${body.next_cursor}, or use --all.`
+        : `More ${what} may exist; this Tower gave no cursor to continue from.`;
+}
+/** Filters, sort and cursor beyond the long-standing ones, as door query parameters. */
+export function addIssuePageQuery(query, command) {
+    const pairs = [
+        ["label", command.label],
+        ["q", command.q],
+        ["created_from", command.createdAfter],
+        ["created_to", command.createdBefore],
+        ["updated_from", command.updatedAfter],
+        ["updated_to", command.updatedBefore],
+        ["sort", command.sort],
+        ["dir", command.dir],
+        ["cursor", command.cursor],
+    ];
+    for (const [name, value] of pairs)
+        if (value)
+            query.set(name, value);
+}
+/**
+ * `list --all`: NDJSON on stdout, one issue per line, then ONE final line
+ * `{"type":"coverage",...}`. Exit 0 only when the walk was complete.
+ */
+export async function streamAllIssues(command, door, base) {
+    const query = new URLSearchParams(base);
+    query.set("limit", String(Math.min(command.limit ?? ALL_PAGE_SIZE, ALL_PAGE_SIZE)));
+    query.delete("cursor");
+    const seen = new Set();
+    let returned = 0;
+    let pages = 0;
+    let expected = null;
+    let cursor = null;
+    for (;;) {
+        if (cursor)
+            query.set("cursor", cursor);
+        const answer = await askAgentDoor(door, {
+            path: `/api/work/issues?${query.toString()}`,
+            method: "GET",
+            label: "issue list",
+            timeoutMs: READ_DEADLINE_MS,
+        });
+        if (!answer.ok) {
+            console.error(`${TAG} walk interrupted`, JSON.stringify({ reason: answer.reason, pages, returned }));
+            writeLine(door.io.stdout, JSON.stringify({
+                type: "coverage", coverage: "failed_partial", reason: answer.reason, detail: answer.detail,
+                pages, returned, unique: seen.size, expected, next_cursor: cursor,
+            }));
+            return 1;
+        }
+        const body = answer.body;
+        pages += 1;
+        if (pages === 1 && typeof body.counts?.total === "number")
+            expected = body.counts.total;
+        for (const issue of body.issues ?? []) {
+            returned += 1;
+            seen.add(issue.id);
+            writeLine(door.io.stdout, JSON.stringify(withSizeLabel(issue)));
+        }
+        console.error(`${TAG} page ${JSON.stringify({ page: pages, returned: body.issues?.length ?? 0, coverage: body.coverage ?? null })}`);
+        cursor = body.next_cursor ?? null;
+        if (!cursor)
+            break;
+    }
+    const exact = expected === null || expected === returned;
+    writeLine(door.io.stdout, JSON.stringify({
+        type: "coverage", coverage: "complete", pages, returned, unique: seen.size, expected,
+        ...(returned === seen.size && exact ? {} : { note: "returned, unique and expected do not all agree; rows changed during the walk" }),
+    }));
+    return 0;
+}