@bli-cockpit/cli 0.2.239 → 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-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,7 @@ 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";
@@ -67,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);
@@ -304,6 +307,7 @@ 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(),
@@ -356,6 +360,8 @@ async function changeEvent(command, door) {
             // 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 } : {}),
@@ -366,6 +372,7 @@ async function changeEvent(command, door) {
         return emitAgentDoor(door, { ok: true, ...answer.body });
     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)

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

@@ -33,6 +33,7 @@ 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]";
@@ -62,6 +63,10 @@ export async function runDocs(command, io) {
             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). */

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

package/dist/commands/issue.js

@@ -31,6 +31,7 @@ import { assigneeLabel, beginAssigneeDirectoryFetch, finishAssigneeDirectory, wi
 import { cacheAgeLabel, cacheCoverage, readThroughCache } from "./read-cache.js";
 import { readTicketBoard } from "./tickets-board.js";
 import { showIssue } from "./issue-show.js";
+import { addIssuePageQuery, pageFieldsOf, pageFooter, streamAllIssues } from "./issue-list-page.js";
 import { READ_DEADLINE_MS, TAG, resolveProjectId, sizeForEstimate, withSizeLabel, } from "./issue-contracts.js";
 import { commentIssue, createIssue, moveIssue, updateIssue } from "./issue-write.js";
 import { listIssueVersions, restoreIssueVersion } from "./issue-versions.js";
@@ -85,7 +86,7 @@ export function listGapLines(body, requestedLimit) {
     const returned = body.issues?.length ?? 0;
     const completeness = body.completeness;
     if (completeness?.status === "partial") {
-        lines.push(`${TAG} partial list: ${completeness.returned} of ${completeness.total} matching issues; narrow the filter or pass --limit (at most 1000).`);
+        lines.push(`${TAG} partial list: ${completeness.returned} of ${completeness.total} matching issues; narrow the filter, continue with --cursor, or use --all.`);
     }
     else if (completeness?.status === "unknown") {
         lines.push(`${TAG} list may be partial: ${completeness.returned} issues filled the limit and Tower could not count the rest.`);
@@ -110,6 +111,10 @@ async function listIssues(command, door) {
     const built = await buildIssueListQuery(command, door);
     if (!built.ok)
         return built.exitCode;
+    addIssuePageQuery(built.query, command);
+    // BLI-21315: a streamed export never goes through the read cache or buffers.
+    if (command.all)
+        return streamAllIssues(command, door, built.query);
     const suffix = built.query.toString();
     // BLI-10579: the assignee directory (`/api/team/members`) is the whole org
     // roster regardless of which issues come back — it never actually depended
@@ -131,7 +136,7 @@ async function listIssues(command, door) {
     const body = answer.body;
     const issues = body.issues ?? [];
     // BLI-10447: the gaps go to stderr in both modes, so `--json` stdout stays one object.
-    for (const line of listGapLines(body, command.limit ?? 1000))
+    for (const line of listGapLines(body, command.limit ?? 100))
         writeLine(door.io.stderr, line);
     // BLI-10450: one extra call for the whole list, never one per row — the
     // uuid `assignee_id` alone forced a second `cockpit team members` call and
@@ -144,6 +149,7 @@ async function listIssues(command, door) {
             ...cacheCoverage(answer),
             issues: issues.map((issue) => withSizeLabel(withAssigneeIdentity(issue, directory))),
             ...(body.completeness ? { completeness: body.completeness } : {}),
+            ...pageFieldsOf(body),
             ...(body.outside_project ? { outside_project: body.outside_project } : {}),
         });
     }
@@ -157,6 +163,9 @@ async function listIssues(command, door) {
         writeLine(door.io.stdout, issueLine(issue, directory));
     writeLine(door.io.stdout, "");
     writeLine(door.io.stdout, `${issues.length} issue(s).`);
+    const footer = pageFooter(body, "issues");
+    if (footer)
+        writeLine(door.io.stdout, footer);
     return 0;
 }
 /** The list query for the filters given, or the exit code of the project lookup that failed. */
@@ -230,7 +239,12 @@ function historyChange(row) {
 }
 async function issueHistory(command, door) {
     const ref = command.issueRef ?? "";
-    const query = command.limit === undefined ? "" : `?limit=${command.limit}`;
+    const params = new URLSearchParams();
+    if (command.limit !== undefined)
+        params.set("limit", String(command.limit));
+    if (command.cursor)
+        params.set("cursor", command.cursor);
+    const query = params.toString() ? `?${params.toString()}` : "";
     const answer = await askAgentDoor(door, {
         path: `/api/work/issues/${encodeURIComponent(ref)}/history${query}`,
         method: "GET",
@@ -239,9 +253,10 @@ async function issueHistory(command, door) {
     });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const history = answer.body.history ?? [];
+    const historyBody = answer.body;
+    const history = historyBody.history ?? [];
     if (door.json)
-        return emitAgentDoor(door, { ok: true, history });
+        return emitAgentDoor(door, { ok: true, history, ...pageFieldsOf(historyBody) });
     if (history.length === 0) {
         writeLine(door.io.stdout, `No recorded changes for ${ref}.`);
         return 0;
@@ -251,5 +266,8 @@ async function issueHistory(command, door) {
     }
     writeLine(door.io.stdout, "");
     writeLine(door.io.stdout, `${history.length} change(s).`);
+    const footer = pageFooter(historyBody, "changes");
+    if (footer)
+        writeLine(door.io.stdout, footer);
     return 0;
 }

package/dist/commands/local-args-tower-cal.js

@@ -27,7 +27,7 @@ const CAL_ACTIONS = new Set([
     "find",
     "calendars",
     "add-ical",
-    "change", "cancel",
+    "change", "cancel", "rsvp",
     "create",
     "share",
     "detach",
@@ -36,7 +36,7 @@ const CAL_ACTIONS = new Set([
     "delete",
 ]);
 /** Every verb that names ONE thing first — a calendar id, or (delete) an event id. */
-const CAL_ACTIONS_NEEDING_A_SUBJECT = new Set(["event", "export", "duplicate", "calendar-change", "sync", "detach", "share", "delete", "change", "cancel"]);
+const CAL_ACTIONS_NEEDING_A_SUBJECT = new Set(["event", "export", "duplicate", "calendar-change", "sync", "detach", "share", "delete", "change", "cancel", "rsvp"]);
 /** `sync-status [<calendar id>]` — every calendar, or one's. Ticket 10730. */
 const CAL_ACTIONS_WITH_OPTIONAL_SUBJECT = new Set(["sync-status", "undo"]);
 const CAL_ALLOWED_FLAGS = [
@@ -71,6 +71,7 @@ const CAL_ALLOWED_FLAGS = [
     "--idempotency-key",
     "--expected-version",
     "--reason",
+    "--scope", "--occurrence", "--response", "--comment", "--reminder", "--visibility", "--transparency", "--key",
 ];
 const CAL_VALUE_FLAGS = [
     "--home",
@@ -94,6 +95,7 @@ const CAL_VALUE_FLAGS = [
     "--idempotency-key",
     "--expected-version",
     "--reason",
+    "--scope", "--occurrence", "--response", "--comment", "--reminder", "--visibility", "--transparency", "--key",
 ];
 export function parseCalArgs(args) {
     const values = parseNamedArgs(args, { allowedFlags: CAL_ALLOWED_FLAGS, valueFlags: CAL_VALUE_FLAGS });
@@ -106,7 +108,8 @@ export function parseCalArgs(args) {
     // two of them wrong is told about --limit first, as before.
     const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
     const offset = readCalOffset(values);
-    return buildCalCommand(values, action, subject, query, title, startsAt, endsAt, offset, limit);
+    const command = buildCalCommand(values, action, subject, query, title, startsAt, endsAt, offset, limit);
+    return { ...command, ...readCalEventScope(action, values) };
 }
 function readCalAction(values) {
     const first = values.positionals[0];
@@ -122,7 +125,7 @@ function readCalSubjectOrQuery(action, rest) {
     if (CAL_ACTIONS_NEEDING_A_SUBJECT.has(action)) {
         subject = optionalNonEmpty(rest[0]);
         if (!subject) {
-            throw new Error(action === "delete" || action === "duplicate"
+            throw new Error(action === "delete" || action === "duplicate" || action === "change" || action === "cancel" || action === "rsvp"
                 ? `cal ${action} needs an event id — take one from a window verb's output (today/week/next/find).`
                 : `cal ${action} needs a calendar id — take one from \`cockpit cal calendars\`.`);
         }
@@ -182,7 +185,7 @@ function readCalOffset(values) {
 function buildCalCommand(values, action, subject, query, title, startsAt, endsAt, offset, limit) {
     return {
         kind: "cal",
-        occurrenceStart: optionalNonEmpty(values.flags.get("--occurrence-start")),
+        occurrenceStart: optionalNonEmpty(values.flags.get("--occurrence") ?? values.flags.get("--occurrence-start")),
         color: optionalNonEmpty(values.flags.get("--color")),
         action,
         homeDir: optionalNonEmpty(values.flags.get("--home")),
@@ -211,7 +214,7 @@ function buildCalCommand(values, action, subject, query, title, startsAt, endsAt
         allDay: values.booleans.has("--all-day"),
         timed: values.booleans.has("--timed"),
         keepInvitees: values.booleans.has("--keep-invitees"),
-        idempotencyKey: optionalNonEmpty(values.flags.get("--idempotency-key")),
+        idempotencyKey: optionalNonEmpty(values.flags.get("--idempotency-key") ?? values.flags.get("--key")),
         expectedVersion: optionalNonEmpty(values.flags.get("--expected-version")),
         reason: optionalNonEmpty(values.flags.get("--reason")),
         meet: values.booleans.has("--meet"),
@@ -230,4 +233,92 @@ function splitAddresses(raw) {
         .split(",")
         .map((value) => value.trim())
         .filter((value) => value !== "");
+}
+const SCOPES = ["instance", "following", "series"];
+const RSVP_RESPONSES = ["accepted", "declined", "tentative"];
+const VISIBILITIES = ["default", "public", "private", "confidential"];
+const TRANSPARENCIES = ["opaque", "transparent"];
+const WRITE_ACTIONS = new Set(["create", "change"]);
+/**
+ * BLI-21311: the scope, RSVP and event-detail flags. Validated here so a typo
+ * never costs a request; the door still owns every rule that needs the event.
+ */
+function readCalEventScope(action, values) {
+    const out = {};
+    const scope = optionalNonEmpty(values.flags.get("--scope"));
+    if (scope !== undefined) {
+        if (!SCOPES.includes(scope))
+            throw new Error("--scope takes instance, following or series.");
+        if (action !== "change" && action !== "cancel" && action !== "delete" && action !== "rsvp")
+            throw new Error(`cal ${action} does not take --scope.`);
+        if (action === "rsvp" && scope === "following")
+            throw new Error("An RSVP takes --scope instance or series.");
+        out.scope = scope;
+    }
+    if (action === "rsvp") {
+        const response = optionalNonEmpty(values.flags.get("--response"));
+        if (!response || !RSVP_RESPONSES.includes(response)) {
+            throw new Error("cal rsvp needs --response accepted, declined or tentative.");
+        }
+        out.rsvpResponse = response;
+        out.rsvpComment = optionalNonEmpty(values.flags.get("--comment"));
+        return out;
+    }
+    if (values.flags.has("--response") || values.flags.has("--comment"))
+        throw new Error("--response and --comment belong to cal rsvp.");
+    if (!WRITE_ACTIONS.has(action)) {
+        for (const flag of ["--reminder", "--visibility", "--transparency"]) {
+            if (values.flags.has(flag))
+                throw new Error(`cal ${action} does not take ${flag}.`);
+        }
+        return out;
+    }
+    const color = optionalNonEmpty(values.flags.get("--color"));
+    if (color !== undefined) {
+        if (color === "none")
+            out.colorId = null;
+        else if (/^(?:[1-9]|10|11)$/.test(color))
+            out.colorId = Number(color);
+        else
+            throw new Error("--color takes a colour number 1 to 11, or none.");
+    }
+    const reminders = readReminders(values.flagValues.get("--reminder") ?? []);
+    if (reminders !== undefined)
+        out.reminders = reminders;
+    const visibility = optionalNonEmpty(values.flags.get("--visibility"));
+    if (visibility !== undefined) {
+        if (!VISIBILITIES.includes(visibility))
+            throw new Error(`--visibility takes ${VISIBILITIES.join(", ")}.`);
+        out.visibility = visibility;
+    }
+    const transparency = optionalNonEmpty(values.flags.get("--transparency"));
+    if (transparency !== undefined) {
+        if (!TRANSPARENCIES.includes(transparency))
+            throw new Error(`--transparency takes ${TRANSPARENCIES.join(" or ")}.`);
+        out.transparency = transparency;
+    }
+    return out;
+}
+/** `--reminder 10 --reminder 60:email` or `--reminder default`. Max 5, 0..40320 minutes. */
+function readReminders(raw) {
+    if (raw.length === 0)
+        return undefined;
+    if (raw.includes("default")) {
+        if (raw.length > 1)
+            throw new Error("--reminder default stands alone: it means the calendar's own reminders.");
+        return "default";
+    }
+    if (raw.length > 5)
+        throw new Error("An event holds at most 5 reminders.");
+    return raw.map((entry) => {
+        const [minutesText, method, extra] = entry.split(":");
+        if (extra !== undefined || !/^\d+$/.test(minutesText ?? ""))
+            throw new Error("--reminder takes minutes (0 to 40320), optionally minutes:popup or minutes:email, or default.");
+        const minutes = Number(minutesText);
+        if (minutes > 40320)
+            throw new Error("--reminder minutes run from 0 to 40320 (four weeks).");
+        if (method !== undefined && method !== "popup" && method !== "email")
+            throw new Error("A reminder method is popup or email.");
+        return { minutes, ...(method ? { method } : {}) };
+    });
 }