@bli-cockpit/cli 0.2.238 → 0.2.240

package/dist/commands/issue-versions.js

@@ -0,0 +1,93 @@
+import { randomUUID } from "node:crypto";
+/**
+ * `cockpit ticket versions <id>` and `cockpit ticket restore <id> --version <n>`
+ * (BLI-21300): the saved descriptions of one ticket, and the write that puts an
+ * older one back as a NEW version. Same doors the browser uses
+ * (`GET .../versions`, `POST .../versions/restore`).
+ *
+ * `restore` takes the version NUMBER the person read in `versions`, looks up
+ * that version's id in the same list, and sends the id: the door never guesses
+ * "the previous one". A number the list does not carry is refused here with
+ * the numbers that do exist, before anything is written.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { READ_DEADLINE_MS, TAG, WRITE_DEADLINE_MS } from "./issue-contracts.js";
+export async function listIssueVersions(command, door) {
+    const ref = command.issueRef ?? "";
+    const query = command.limit === undefined ? "" : `?limit=${command.limit}`;
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/versions${query}`,
+        method: "GET",
+        label: "issue versions",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const versions = answer.body.versions ?? [];
+    console.error(`${TAG} versions ${JSON.stringify({ count: versions.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, versions });
+    if (versions.length === 0) {
+        writeLine(door.io.stdout, `No saved description versions for ${ref}.`);
+        return 0;
+    }
+    for (const row of versions) {
+        const from = row.restored_from_version ? ` (restored from ${row.restored_from_version})` : "";
+        writeLine(door.io.stdout, `v${row.version}  ${row.id}  ${row.created_at}  ${row.source}${from}  ${row.markdown.length} chars`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${versions.length} version(s), newest first. Restore one with: cockpit ticket restore ${ref} --version <n>`);
+    return 0;
+}
+export async function restoreIssueVersion(command, door) {
+    const ref = command.issueRef ?? "";
+    const wanted = command.versionNumber;
+    const listed = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/versions?limit=500`,
+        method: "GET",
+        label: "issue versions",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!listed.ok)
+        return failAgentDoor(door, TAG, listed.reason, listed.detail);
+    const versions = listed.body.versions ?? [];
+    const chosen = versions.find(row => row.version === wanted);
+    if (!chosen) {
+        const have = versions.map(row => row.version).join(", ") || "none";
+        console.error(`${TAG} restore refused ${JSON.stringify({ reason: "version_not_found", requested: wanted ?? null, available: versions.length })}`);
+        return failAgentDoor(door, TAG, "version_not_found", `${ref} has no version ${wanted}. Versions: ${have}.`);
+    }
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision, version: chosen.version })}`);
+    let answer;
+    try {
+        answer = await askAgentDoor(door, {
+            path: `/api/work/issues/${encodeURIComponent(ref)}/versions/restore`,
+            method: "POST",
+            label: "issue restore",
+            timeoutMs: WRITE_DEADLINE_MS,
+            body: { request_id: requestId, expected_revision: command.expectedRevision, version_id: chosen.id },
+        });
+    }
+    catch {
+        console.error(`${TAG} response lost`, JSON.stringify({ reason: "mutation_unknown" }));
+        writeLine(door.io.stderr, `${TAG} check local commit with cockpit ticket mutation-status ${requestId}; retry unchanged input with --request-id ${requestId}.`);
+        return failAgentDoor(door, TAG, "mutation_unknown", "Result unknown. Check this request ID before retrying with identical input.");
+    }
+    if (!answer.ok) {
+        writeLine(door.io.stderr, `${TAG} check local commit with cockpit ticket mutation-status ${requestId}; retry unchanged input with --request-id ${requestId}.`);
+        const mutation = answer.body?.mutation ?? { request_id: requestId, outcome: "unknown_check_again" };
+        if (door.json)
+            return emitAgentDoor(door, { ok: false, error: answer.reason, detail: answer.detail, mutation }, 1);
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    }
+    const body = answer.body;
+    const newVersion = body.mutation?.description_version;
+    writeLine(door.io.stderr, `${TAG} restored ${JSON.stringify({ restored_version: chosen.version, new_version: newVersion ?? null })}`);
+    writeLine(door.io.stderr, `${TAG} local commit receipt ${JSON.stringify(body.mutation ?? { outcome: "unknown_check_again", request_id: requestId })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, issue: body.issue, mutation: body.mutation });
+    writeLine(door.io.stdout, `Restored version ${chosen.version} of ${ref} as new version ${newVersion ?? "?"}.`);
+    return 0;
+}

package/dist/commands/issue.js

@@ -31,8 +31,10 @@ 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";
 export async function runIssue(command, io) {
     const door = await openAgentDoor("issue", command, io);
     switch (command.action) {
@@ -62,6 +64,10 @@ export async function runIssue(command, io) {
             return commentIssue(command, door);
         case "history":
             return issueHistory(command, door);
+        case "versions":
+            return listIssueVersions(command, door);
+        case "restore":
+            return restoreIssueVersion(command, door);
     }
 }
 function issueLine(issue, directory) {
@@ -80,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.`);
@@ -105,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
@@ -126,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
@@ -139,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 } : {}),
         });
     }
@@ -152,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. */
@@ -225,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",
@@ -234,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;
@@ -246,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

@@ -20,14 +20,14 @@
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
 const CAL_ACTIONS = new Set([
-    "event", "export", "conflicts", "calendar-change",
+    "event", "export", "duplicate", "batch", "undo", "conflicts", "calendar-change",
     "today",
     "week",
     "next",
     "find",
     "calendars",
     "add-ical",
-    "change", "cancel",
+    "change", "cancel", "rsvp",
     "create",
     "share",
     "detach",
@@ -36,9 +36,9 @@ 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", "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"]);
+const CAL_ACTIONS_WITH_OPTIONAL_SUBJECT = new Set(["sync-status", "undo"]);
 const CAL_ALLOWED_FLAGS = [
     "--home",
     "--dashboard-url",
@@ -60,12 +60,18 @@ const CAL_ALLOWED_FLAGS = [
     "--location",
     "--attendee",
     "--all-day",
+    "--timed",
+    "--keep-invitees",
     "--meet",
     "--org-visible",
     "--private",
     "--full",
     "--yes",
     "--json",
+    "--idempotency-key",
+    "--expected-version",
+    "--reason",
+    "--scope", "--occurrence", "--response", "--comment", "--reminder", "--visibility", "--transparency", "--key",
 ];
 const CAL_VALUE_FLAGS = [
     "--home",
@@ -86,6 +92,10 @@ const CAL_VALUE_FLAGS = [
     "--until",
     "--location",
     "--attendee",
+    "--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 });
@@ -98,13 +108,14 @@ 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];
     const action = (first === undefined ? "today" : first);
     if (!CAL_ACTIONS.has(action)) {
-        throw new Error(`Unknown cal command: ${first}. Try today, week, conflicts, calendar-change, next, find, calendars, add-ical, create, share, detach, sync, sync-status, or delete.`);
+        throw new Error(`Unknown cal command: ${first}. Try today, week, conflicts, calendar-change, next, find, calendars, add-ical, create, duplicate, batch, undo, share, detach, sync, sync-status, or delete.`);
     }
     return { action, rest: values.positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -114,8 +125,8 @@ function readCalSubjectOrQuery(action, rest) {
     if (CAL_ACTIONS_NEEDING_A_SUBJECT.has(action)) {
         subject = optionalNonEmpty(rest[0]);
         if (!subject) {
-            throw new Error(action === "delete"
-                ? "cal delete needs an event id — take one from a window verb's output (today/week/next/find)."
+            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\`.`);
         }
         if (rest.length > 1)
@@ -174,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")),
@@ -201,6 +212,11 @@ function buildCalCommand(values, action, subject, query, title, startsAt, endsAt
         location: optionalNonEmpty(values.flags.get("--location")),
         attendees: splitAddresses(values.flags.get("--attendee")),
         allDay: values.booleans.has("--all-day"),
+        timed: values.booleans.has("--timed"),
+        keepInvitees: values.booleans.has("--keep-invitees"),
+        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"),
         orgVisible: values.booleans.has("--org-visible"),
         makePrivate: values.booleans.has("--private"),
@@ -217,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 } : {}) };
+    });
 }

package/dist/commands/local-args-tower-docs-msg.js

@@ -8,13 +8,14 @@
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
 import { parseDocsExportFlags } from "./local-args-docs-export.js";
-const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update", "delete", "link", "sync-status", "export"]);
+const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update", "delete", "link", "sync-status", "export", "mutation-status", "share", "access"]);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 // BLI-10450: `read` moved to its own branch in `parseDocsDocumentReference` —
 // it takes SEVERAL references now, so it no longer shares the "exactly one"
 // rule `update`/`link` still enforce. BLI‑10555: `delete` takes several too
 // (the same door, called once per ref), so it joined `read`'s branch rather
 // than this set.
-const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["update", "link", "export"]);
+const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["update", "link", "export", "mutation-status", "share", "access"]);
 const DOCS_ALLOWED_FLAGS = [
     "--home",
     "--dashboard-url",
@@ -22,6 +23,8 @@ const DOCS_ALLOWED_FLAGS = [
     "--parent",
     "--clear-parent",
     "--allow-empty",
+    "--expected-revision",
+    "--request-id",
     "--visibility",
     "--file",
     "--body-stdin",
@@ -34,6 +37,9 @@ const DOCS_ALLOWED_FLAGS = [
     "--offset",
     "--format",
     "--out",
+    "--add",
+    "--remove",
+    "--reason",
     "--json",
 ];
 const DOCS_VALUE_FLAGS = [
@@ -41,6 +47,8 @@ const DOCS_VALUE_FLAGS = [
     "--dashboard-url",
     "--title",
     "--parent",
+    "--expected-revision",
+    "--request-id",
     "--visibility",
     "--file",
     "--query",
@@ -49,21 +57,27 @@ const DOCS_VALUE_FLAGS = [
     "--offset",
     "--format",
     "--out",
+    "--add",
+    "--remove",
+    "--reason",
 ];
 export function parseDocsArgs(args) {
     const values = parseNamedArgs(args, { allowedFlags: DOCS_ALLOWED_FLAGS, valueFlags: DOCS_VALUE_FLAGS });
     const { action, rest } = parseDocsAction(values.positionals);
     const link = parseDocsLink(action, rest, values.booleans.has("--clear"));
     const { docRef, docRefs } = parseDocsDocumentReference(action, link.rest);
-    const { visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset } = parseDocsFlags(action, values);
+    const { visibility, clearParent, parentId, allowEmpty, title, requestId, expectedRevision, query, wholeWord, limit, bodies, section, offset } = parseDocsFlags(action, values);
     if (action === "read")
         validateDocsReadTargets(docRefs, parentId, bodies);
+    if (action === "mutation-status" && !UUID_PATTERN.test(docRef ?? "")) {
+        throw new Error("docs mutation-status needs a request UUID (the --request-id you sent, or the one `docs update` printed).");
+    }
     // BLI‑10555: `delete` needs no `--parent`/`--bodies` shape, only at least
     // one reference — `read`'s emptier validation does not apply.
     if (action === "delete" && (!docRefs || docRefs.length === 0)) {
         throw new Error("docs delete needs one or more document ids/slugs.");
     }
-    return buildDocsCommand(values, action, docRef, docRefs, visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset, link);
+    return buildDocsCommand(values, action, docRef, docRefs, visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset, link, { requestId, expectedRevision });
 }
 /**
  * BLI-10450: `read` takes either several document references OR
@@ -115,7 +129,7 @@ function parseDocsAction(positionals) {
     const first = positionals[0];
     const action = (first === undefined ? "list" : first);
     if (!DOCS_ACTIONS.has(action)) {
-        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, update, delete, link, sync-status, or export.`);
+        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, update, delete, link, sync-status, export, mutation-status, share, or access.`);
     }
     return { action, rest: positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -173,11 +187,19 @@ function parseDocsWriteFlags(action, values) {
     if (allowEmpty && action !== "update") {
         throw new Error("--allow-empty belongs to `cockpit docs update`.");
     }
+    // BLI-21298: the write-safety pair belongs to `update`, like the other save-shaping flags.
+    if ((values.flags.has("--request-id") || values.flags.has("--expected-revision")) && action !== "update") {
+        throw new Error("--request-id and --expected-revision belong to `cockpit docs update`.");
+    }
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    if (requestId && !UUID_PATTERN.test(requestId))
+        throw new Error("--request-id must be a UUID.");
+    const expectedRevision = optionalPositiveInteger(values.flags.get("--expected-revision"), "--expected-revision");
     const title = optionalNonEmpty(values.flags.get("--title"));
     if (action === "create" && !title) {
         throw new Error("docs create needs --title.");
     }
-    return { visibility, clearParent, parentId, allowEmpty, title };
+    return { visibility, clearParent, parentId, allowEmpty, title, requestId, expectedRevision };
 }
 /** The flags that narrow or slice what a list or read returns. */
 function parseDocsReadFlags(action, values) {
@@ -217,6 +239,26 @@ function parseDocsReadFlags(action, values) {
         throw new Error("--offset belongs to `cockpit docs read`.");
     return { query, wholeWord, limit, bodies, section, offset };
 }
+/**
+ * BLI-21313: `docs share <doc> --add <email> | --remove <email> [--reason <text>]` names or removes a page editor;
+ * `docs access <doc>` reads who may edit and why. A person is an exact email address, never a fuzzy name.
+ */
+function parseDocsShareFlags(action, values) {
+    const addPerson = optionalNonEmpty(values.flags.get("--add"));
+    const removePerson = optionalNonEmpty(values.flags.get("--remove"));
+    const reason = optionalNonEmpty(values.flags.get("--reason"));
+    if ((addPerson || removePerson || reason) && action !== "share") {
+        throw new Error("--add, --remove and --reason belong to `cockpit docs share`.");
+    }
+    if (action === "share") {
+        if (Boolean(addPerson) === Boolean(removePerson)) {
+            throw new Error("docs share needs exactly one of --add <email> or --remove <email>.");
+        }
+        if (reason && reason.length > 200)
+            throw new Error("--reason can be at most 200 characters.");
+    }
+    return { ...(addPerson ? { addPerson } : {}), ...(removePerson ? { removePerson } : {}), ...(reason ? { reason } : {}) };
+}
 function parseDocsOffset(raw) {
     const offsetRaw = optionalNonEmpty(raw);
     if (offsetRaw === undefined)
@@ -226,7 +268,7 @@ function parseDocsOffset(raw) {
         throw new Error("--offset must be a whole number 0 or greater.");
     return offset;
 }
-function buildDocsCommand(values, action, docRef, docRefs, visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset, link) {
+function buildDocsCommand(values, action, docRef, docRefs, visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset, link, safety) {
     return {
         kind: "docs",
         action,
@@ -238,6 +280,8 @@ function buildDocsCommand(values, action, docRef, docRefs, visibility, clearPare
         ...(parentId ? { parentId } : {}),
         clearParent,
         ...(allowEmpty ? { allowEmpty } : {}),
+        ...(safety.requestId ? { requestId: safety.requestId } : {}),
+        ...(safety.expectedRevision === undefined ? {} : { expectedRevision: safety.expectedRevision }),
         visibility: visibility,
         filePath: optionalNonEmpty(values.flags.get("--file")),
         bodyStdin: values.booleans.has("--body-stdin"),
@@ -250,6 +294,7 @@ function buildDocsCommand(values, action, docRef, docRefs, visibility, clearPare
         ...(link.notionPage ? { notionPage: link.notionPage } : {}),
         ...(link.clearLink ? { clearLink: true } : {}),
         ...parseDocsExportFlags(action, values),
+        ...parseDocsShareFlags(action, values),
         json: values.booleans.has("--json"),
     };
 }

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

@@ -54,7 +54,7 @@ export function parseDrillsArgs(args) {
     if (action === "theme-set") {
         theme = rest.join(" ").trim();
         if (!theme)
-            throw new Error("`cockpit drills theme set` takes a theme: video-game, boxing, muay-thai, crime-drama, anime, sports, or your own words.");
+            throw new Error("`cockpit drills theme set` takes a theme: plain (no theme, the default), video-game, sports, movies-tv, music, anime, cooking, or anything you're into in your own words.");
     }
     else if (rest.length > 0)
         throw new Error(`\`cockpit drills ${action}\` takes no positional arguments.`);