@bli-cockpit/cli 0.2.242 → 0.2.244

package/dist/commands/issue-relations.js

@@ -0,0 +1,151 @@
+import { randomUUID } from "node:crypto";
+/**
+ * `cockpit ticket relations|relate|unrelate` (BLI-21558, P6): what blocks what, over the same doors the
+ * browser uses (`/api/work/issues/<id>/relations`). A child is not a blocker; the parent link is `--parent`.
+ *
+ * `relate <id> --blocks B | --blocked-by B | --related B | --duplicate-of B` takes exactly one kind flag.
+ * `unrelate <id> --relation <relation-id>` or the same kind flag plus the other ticket, found through the read.
+ * Parsing lives here too, so `local-args-tower-work.ts` only lists the flag names.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { askTicketWrite, refuseWrite } from "./issue-write.js";
+import { READ_DEADLINE_MS, TAG, WRITE_DEADLINE_MS } from "./issue-contracts.js";
+export const RELATION_VALUE_FLAGS = ["--blocks", "--blocked-by", "--related", "--duplicate-of", "--relation"];
+const KIND_FLAGS = [
+    ["--blocks", "blocks"], ["--blocked-by", "blocked_by"], ["--related", "related"], ["--duplicate-of", "duplicate"],
+];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Reads the relation flags for one action; refuses a flag on the wrong verb, none, or several. */
+export function readRelationFlags(action, values) {
+    const given = KIND_FLAGS.filter(([flag]) => values.flags.has(flag));
+    const relationId = values.flags.get("--relation");
+    if (action !== "relate" && action !== "unrelate") {
+        if (given.length > 0 || relationId !== undefined)
+            throw new Error("--blocks, --blocked-by, --related, --duplicate-of and --relation belong to `cockpit ticket relate` and `unrelate`.");
+        return {};
+    }
+    if (given.length > 1)
+        throw new Error("Name exactly one of --blocks, --blocked-by, --related or --duplicate-of.");
+    if (relationId !== undefined && (action === "relate" || given.length > 0)) {
+        throw new Error("--relation names the edge to remove on `unrelate`; use it instead of a kind flag.");
+    }
+    if (relationId !== undefined && !UUID.test(relationId))
+        throw new Error("--relation must be a relation id (see `cockpit ticket relations <id> --json`).");
+    const [flag, kind] = given[0] ?? [];
+    if (!flag || !kind) {
+        if (action === "relate")
+            throw new Error("ticket relate needs one of --blocks <id>, --blocked-by <id>, --related <id> or --duplicate-of <id>.");
+        if (relationId === undefined)
+            throw new Error("ticket unrelate needs --relation <relation-id>, or a kind flag with the other ticket.");
+        return { relationId };
+    }
+    return { relation: { kind, target: values.flags.get(flag) ?? "" } };
+}
+const GROUPS = [
+    ["blocks", "Blocks"], ["blocked_by", "Blocked by"], ["related", "Related"], ["duplicate_of", "Duplicate of"], ["duplicates", "Duplicates"],
+];
+export async function showRelations(command, door) {
+    const ref = command.issueRef ?? "";
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/relations`, method: "GET", label: "issue relations", timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const relations = answer.body.relations;
+    if (!relations)
+        return failAgentDoor(door, TAG, "read_failed", "The door answered without relations.");
+    console.error(`${TAG} relations ${JSON.stringify(relations.coverage)}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, relations });
+    let printed = 0;
+    for (const [key, title] of GROUPS) {
+        const items = relations[key];
+        if (items.length === 0)
+            continue;
+        writeLine(door.io.stdout, `${title}:`);
+        for (const item of items)
+            writeLine(door.io.stdout, `  ${item.issue.identifier.padEnd(9)}  ${item.issue.state.padEnd(11)}  ${item.issue.title}  (${item.relation_id})`);
+        printed += items.length;
+    }
+    if (relations.unmapped.length > 0) {
+        writeLine(door.io.stdout, "Not in Tower (from Linear):");
+        for (const item of relations.unmapped)
+            writeLine(door.io.stdout, `  ${item.kind}  ${item.label}  (${item.relation_id})`);
+        printed += relations.unmapped.length;
+    }
+    if (printed === 0)
+        writeLine(door.io.stdout, `${ref} has no relations.`);
+    const { hidden, truncated, limit } = relations.coverage;
+    if (hidden > 0)
+        writeLine(door.io.stdout, `${hidden} relation(s) to tickets you cannot read or that were deleted are not shown.`);
+    if (truncated)
+        writeLine(door.io.stdout, `Showing the first ${limit} relations; there are more.`);
+    return 0;
+}
+export async function relateIssue(command, door) {
+    const ref = command.issueRef ?? "";
+    const relation = command.relation;
+    if (!relation)
+        return failAgentDoor(door, TAG, "invalid_body", "ticket relate needs a kind flag and the other ticket.");
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
+    const answer = await askTicketWrite(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/relations`, method: "POST", label: "issue relate", timeoutMs: WRITE_DEADLINE_MS,
+        body: { request_id: requestId, expected_revision: command.expectedRevision, kind: relation.kind, target: relation.target },
+    });
+    if (!answer.ok)
+        return refuseWrite(door, answer, requestId);
+    return finishWrite(door, answer.body, requestId, `${ref} ${relation.kind.replace("_", " ")} ${relation.target}: recorded.`, "related");
+}
+export async function unrelateIssue(command, door) {
+    const ref = command.issueRef ?? "";
+    let relationId = command.relationId;
+    if (!relationId && command.relation) {
+        const found = await findRelation(command, door);
+        if (typeof found === "number")
+            return found;
+        relationId = found;
+    }
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
+    const query = command.expectedRevision === undefined ? `?request_id=${requestId}` : `?request_id=${requestId}&expected_revision=${command.expectedRevision}`;
+    const answer = await askTicketWrite(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/relations/${encodeURIComponent(relationId ?? "")}${query}`,
+        method: "DELETE", label: "issue unrelate", timeoutMs: WRITE_DEADLINE_MS, body: { request_id: requestId },
+    });
+    if (!answer.ok)
+        return refuseWrite(door, answer, requestId);
+    return finishWrite(door, answer.body, requestId, `${ref}: relation removed.`, "unrelated");
+}
+function finishWrite(door, body, requestId, sentence, tag) {
+    writeLine(door.io.stderr, `${TAG} ${tag} ${JSON.stringify({ relation_id: body.relation_id ?? 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, relation_id: body.relation_id, mutation: body.mutation });
+    writeLine(door.io.stdout, sentence);
+    return 0;
+}
+/** `unrelate <id> --blocks B`: the edge id, found through the same read `relations` prints. */
+async function findRelation(command, door) {
+    const ref = command.issueRef ?? "";
+    const wanted = command.relation;
+    if (!wanted)
+        return failAgentDoor(door, TAG, "invalid_body", "ticket unrelate needs --relation or a kind flag.");
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/relations`, method: "GET", label: "issue relations", timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const relations = answer.body.relations;
+    const group = wanted.kind === "blocks" ? relations?.blocks : wanted.kind === "blocked_by" ? relations?.blocked_by
+        : wanted.kind === "related" ? relations?.related : relations?.duplicate_of;
+    const target = wanted.target.trim().toUpperCase();
+    const hit = (group ?? []).find((item) => item.issue.identifier.toUpperCase() === target || item.issue.id.toLowerCase() === target.toLowerCase())
+        ?? (relations?.unmapped ?? []).find((item) => item.label.toUpperCase() === target && item.kind === (wanted.kind === "blocked_by" ? "" : wanted.kind));
+    if (!hit) {
+        console.error(`${TAG} unrelate refused ${JSON.stringify({ reason: "relation_not_found", kind: wanted.kind })}`);
+        return failAgentDoor(door, TAG, "relation_not_found", `${ref} has no ${wanted.kind.replace("_", " ")} relation with ${wanted.target}.`);
+    }
+    return hit.relation_id;
+}

package/dist/commands/issue-write.js

@@ -35,6 +35,9 @@ export async function createIssue(command, door) {
             ...(command.priority === undefined ? {} : { priority: command.priority }),
             ...(command.estimate === undefined ? {} : { estimate: command.estimate }),
             ...(command.assignee ? { assignee_id: command.assignee } : {}),
+            ...(command.startState ? { state: command.startState } : {}),
+            ...(command.due ? { due_date: command.due } : {}),
+            ...(command.cycle ? { cycle: command.cycle } : {}),
         },
     });
     if (!answer.ok)
@@ -60,7 +63,7 @@ export async function updateIssue(command, door) {
         description = body.text;
     }
     if (!changesAnything(command, description, refs)) {
-        return failAgentDoor(door, TAG, "invalid_body", "issue update needs at least one of --title, --priority, --size, --assignee, --project, --parent, or a description on --body-stdin/--file.");
+        return failAgentDoor(door, TAG, "invalid_body", "issue update needs at least one of --title, --priority, --size, --assignee, --due, --project, --parent, --cycle, or a description on --body-stdin/--file.");
     }
     const requestId = command.requestId ?? randomUUID();
     writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
@@ -74,9 +77,11 @@ export async function updateIssue(command, door) {
             ...(description !== undefined ? { description } : {}),
             ...(command.priority === undefined ? {} : { priority: command.priority }),
             ...(command.estimate === undefined ? {} : { estimate: command.estimate }),
-            ...(command.assignee ? { assignee_id: command.assignee } : {}),
+            ...(command.assignee ? { assignee_id: command.assignee === "none" ? null : command.assignee } : {}),
+            ...(command.due !== undefined ? { due_date: command.due } : {}),
             ...(refs.projectId ? { project_id: refs.projectId } : {}),
             ...(refs.parentId ? { parent_id: refs.parentId } : {}),
+            ...(command.cycle === undefined ? {} : { cycle: command.cycle }),
         },
     });
     if (!answer.ok)
@@ -137,8 +142,34 @@ export async function commentIssue(command, door) {
     writeLine(door.io.stdout, `Commented on ${ref} (${comment?.id ?? ""}).`);
     return 0;
 }
+/** `ticket label <id> --add <name> --remove <name>`: one receipt, one history row (BLI-21422). */
+export async function labelIssue(command, door) {
+    const ref = command.issueRef ?? "";
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
+    const answer = await askTicketWrite(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/labels`,
+        method: "POST",
+        label: "issue label",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { request_id: requestId, expected_revision: command.expectedRevision,
+            ...(command.addLabels?.length ? { add: command.addLabels } : {}),
+            ...(command.removeLabels?.length ? { remove: command.removeLabels } : {}),
+        },
+    });
+    if (!answer.ok)
+        return refuseWrite(door, answer, requestId);
+    const body = answer.body;
+    const names = (body.labels ?? []).map((l) => l.name);
+    writeLine(door.io.stderr, `${TAG} labelled ${JSON.stringify({ issue_id: body.issue?.id ?? null, added: command.addLabels?.length ?? 0, removed: command.removeLabels?.length ?? 0, now: names.length })}`);
+    writeLine(door.io.stderr, `${TAG} local commit receipt ${JSON.stringify(answer.body.mutation ?? { outcome: "unknown_check_again", request_id: requestId })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, issue: maybeWithSizeLabel(body.issue), labels: body.labels ?? [], mutation: answer.body.mutation });
+    writeLine(door.io.stdout, `${body.issue?.identifier ?? ref} labels: ${names.length ? names.join(", ") : "none"}.`);
+    return 0;
+}
 /** A truncated or missing response body cannot be called a successful ticket write. */
-async function askTicketWrite(door, options) {
+export async function askTicketWrite(door, options) {
     try {
         const answer = await askAgentDoor(door, options);
         if (!answer.ok)
@@ -161,11 +192,13 @@ function changesAnything(command, description, refs) {
         || command.priority !== undefined
         || command.estimate !== undefined
         || command.assignee !== undefined
+        || command.due !== undefined
         || refs.projectId !== undefined
-        || refs.parentId !== undefined;
+        || refs.parentId !== undefined
+        || command.cycle !== undefined;
 }
 /** Says where the local commit stands, then fails with the door's own reason. */
-function refuseWrite(door, answer, requestId) {
+export function refuseWrite(door, answer, requestId) {
     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) {

package/dist/commands/issue.js

@@ -33,7 +33,14 @@ 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 { commentIssue, createIssue, labelIssue, moveIssue, updateIssue } from "./issue-write.js";
+import { batchIssues } from "./issue-batch.js";
+import { runInbox } from "./inbox.js";
+import { runWorkNotify } from "./work-notify.js";
+import { runViews } from "./views.js";
+import { runTemplates } from "./templates.js";
+import { runCycles } from "./cycles.js";
+import { relateIssue, showRelations, unrelateIssue } from "./issue-relations.js";
 import { listIssueVersions, restoreIssueVersion } from "./issue-versions.js";
 export async function runIssue(command, io) {
     const door = await openAgentDoor("issue", command, io);
@@ -62,12 +69,36 @@ export async function runIssue(command, io) {
             return moveIssue(command, door);
         case "comment":
             return commentIssue(command, door);
+        case "label":
+            return labelIssue(command, door);
+        case "relations":
+            return showRelations(command, door);
+        case "relate":
+            return relateIssue(command, door);
+        case "unrelate":
+            return unrelateIssue(command, door);
         case "history":
             return issueHistory(command, door);
         case "versions":
             return listIssueVersions(command, door);
         case "restore":
             return restoreIssueVersion(command, door);
+        case "batch":
+            return batchIssues(command, door);
+        case "views":
+            return runViews(command, io, door);
+        case "templates":
+            return runTemplates(command, io, door);
+        case "cycles":
+            return runCycles(command, io, door);
+        case "inbox":
+        case "read":
+        case "unread":
+        case "subscribe":
+        case "unsubscribe":
+            return runInbox(command, io, door);
+        case "notifications":
+            return runWorkNotify(command, io, door);
     }
 }
 function issueLine(issue, directory) {

package/dist/commands/local-args-collector-sources.js

@@ -9,7 +9,7 @@
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
 export function parseSourcesArgs(args) {
     const values = parseNamedArgs(args, {
-        allowedFlags: ["--older-than", "--home", "--dashboard-url", "--json"],
+        allowedFlags: ["--older-than", "--home", "--dashboard-url", "--json", "--reconcile"],
         valueFlags: ["--older-than", "--home", "--dashboard-url"],
     });
     const action = values.positionals[0] ?? "check";
@@ -17,6 +17,7 @@ export function parseSourcesArgs(args) {
         throw new Error("sources has one verb: `cockpit sources check [--older-than <days>] [--json]`.");
     }
     return {
+        reconcile: values.booleans.has("--reconcile"),
         kind: "sources",
         action: "check",
         olderThanDays: optionalPositiveInteger(values.flags.get("--older-than"), "--older-than") ?? null,

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

@@ -4,7 +4,7 @@
  *   cockpit approvals [list] [--status open|done|pending|executing|executed|failed|rejected] [--limit <n>] [--before <cursor>] [--json]
  *   cockpit approvals show <id>
  *   cockpit approvals create                  (the card as JSON on stdin)
- *   cockpit approvals approve <id> [--edit]   (--edit: the edit as JSON on stdin)
+ *   cockpit approvals approve <id> [--edit] [--checked-sent sent|not-sent]   (--edit: the edit as JSON on stdin)
  *   cockpit approvals edit <id> [--approve]   (the edit as JSON on stdin)
  *   cockpit approvals reject <id>
  *   cockpit approvals rules [--active true|false] [--limit <n>]
@@ -25,19 +25,19 @@ const FLAGS_BY_ACTION = {
     list: ["--status", "--limit", "--before"],
     show: [],
     create: [],
-    approve: ["--edit"],
+    approve: ["--edit", "--checked-sent"],
     edit: ["--approve"],
     reject: [],
     rules: ["--active", "--limit"],
     "rules-create": ["--any-audience", "--label"],
     "rules-revoke": ["--reason"],
 };
-const OWN_FLAGS = ["--status", "--limit", "--before", "--edit", "--approve", "--active", "--any-audience", "--label", "--reason"];
+const OWN_FLAGS = ["--status", "--limit", "--before", "--edit", "--checked-sent", "--approve", "--active", "--any-audience", "--label", "--reason"];
 const COMMON_FLAGS = ["--home", "--dashboard-url", "--json"];
 export function parseApprovalsArgs(args) {
     const values = parseNamedArgs(args, {
         allowedFlags: [...OWN_FLAGS, ...COMMON_FLAGS],
-        valueFlags: ["--status", "--limit", "--before", "--active", "--label", "--reason", "--home", "--dashboard-url"],
+        valueFlags: ["--status", "--limit", "--before", "--checked-sent", "--active", "--label", "--reason", "--home", "--dashboard-url"],
     });
     const { action, words } = readAction(values.positionals);
     const given = [...values.flags.keys(), ...values.booleans].filter(flag => OWN_FLAGS.includes(flag));
@@ -60,6 +60,7 @@ export function parseApprovalsArgs(args) {
     if (limit !== undefined && limit > LIST_MAX_LIMIT)
         throw new Error(`--limit is at most ${LIST_MAX_LIMIT}.`);
     const active = readActive(values.flags.get("--active"));
+    const deliveryChecked = readCheckedSent(values.flags.get("--checked-sent"));
     return {
         kind: "approvals",
         action,
@@ -69,6 +70,7 @@ export function parseApprovalsArgs(args) {
         ...(optionalNonEmpty(values.flags.get("--before")) ? { before: optionalNonEmpty(values.flags.get("--before")) } : {}),
         ...(values.booleans.has("--edit") ? { withEdit: true } : {}),
         ...(values.booleans.has("--approve") ? { thenApprove: true } : {}),
+        ...(deliveryChecked ? { deliveryChecked } : {}),
         ...(active !== undefined ? { active } : {}),
         ...(values.booleans.has("--any-audience") ? { anyAudience: true } : {}),
         ...(optionalNonEmpty(values.flags.get("--label")) ? { label: optionalNonEmpty(values.flags.get("--label")) } : {}),
@@ -93,6 +95,16 @@ function readAction(positionals) {
         return { action: first, words: first };
     throw new Error(ONE_VERB);
 }
+/** BLI-21954: what the person found where it was going (Sent, or the channel), on a card whose delivery is unknown. Typed with a hyphen, sent as the door's word. */
+function readCheckedSent(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === "sent")
+        return "sent";
+    if (raw === "not-sent" || raw === "not_sent")
+        return "not_sent";
+    throw new Error("--checked-sent wants sent (it went out: Sent for an email, the channel for a message; mark it done) or not-sent (it did not: send or post it now).");
+}
 function readActive(raw) {
     if (raw === undefined)
         return undefined;

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

@@ -0,0 +1,81 @@
+/**
+ * BLI-21556 `cockpit cal booking-page|booking-slots|book|booking-change|booking-cancel`: the flags, read into a plain
+ * shape. Shape only; the door owns every limit (ranges, duration, buffers, notice, window, the guest cap).
+ */
+import { optionalNonEmpty } from "./local-arg-values.js";
+export const BOOKING_ACTIONS = ["booking-page", "booking-slots", "book", "booking-change", "booking-cancel"];
+/** The guest verbs: they take a page link or token (or a management link or token) and need no device token. */
+export const BOOKING_GUEST_ACTIONS = ["booking-slots", "book", "booking-change", "booking-cancel"];
+export const BOOKING_BOOLEANS = ["--rotate", "--close", "--open"];
+export const BOOKING_VALUE_FLAGS = ["--weekly", "--buffer-before", "--buffer-after", "--notice", "--window", "--start", "--email", "--note"];
+const OWN_FLAGS = [...BOOKING_BOOLEANS, ...BOOKING_VALUE_FLAGS];
+const DAYS = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"];
+/** `mon/09:00-12:00`, `mon,wed/13:00-17:00` or `1/09:00-12:00` -> weekly ranges, or null when it is not that shape. */
+export function parseWeekly(raw) {
+    const match = /^([A-Za-z0-9,]+)\/(\d{2}:\d{2})-(\d{2}:\d{2})$/.exec(raw.trim());
+    if (!match)
+        return null;
+    const days = match[1].split(",").map((day) => {
+        const lower = day.toLowerCase();
+        const named = DAYS.findIndex((name) => lower === name || lower === name + "day" || lower.startsWith(name));
+        return named >= 0 ? named + 1 : Number(day);
+    });
+    if (days.some((day) => !Number.isInteger(day) || day < 1 || day > 7))
+        return null;
+    return days.map((weekday) => ({ weekday, start: match[2], end: match[3] }));
+}
+function wholeNumber(values, flag) {
+    const raw = optionalNonEmpty(values.flags.get(flag));
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        throw new Error(`${flag} takes a whole number.`);
+    return Number(raw);
+}
+export function readBookingFlags(action, values) {
+    if (!BOOKING_ACTIONS.includes(action)) {
+        for (const flag of OWN_FLAGS)
+            if (values.flags.has(flag) || values.booleans.has(flag))
+                throw new Error(`cal ${action} does not take ${flag}; it belongs to the booking verbs.`);
+        return {};
+    }
+    const weekly = (values.flagValues.get("--weekly") ?? []).map((raw) => raw.trim()).filter(Boolean);
+    for (const raw of weekly)
+        if (!parseWeekly(raw))
+            throw new Error("--weekly takes <day>/<HH:MM>-<HH:MM>, like mon/09:00-12:00 or mon,wed/13:00-17:00.");
+    const start = optionalNonEmpty(values.flags.get("--start"));
+    const email = optionalNonEmpty(values.flags.get("--email"));
+    if (action === "book" && (!start || !optionalNonEmpty(values.flags.get("--name")) || !email))
+        throw new Error("cal book needs --start <slot start>, --name \"<you>\" and --email <you@x.com>.");
+    if (action === "booking-change" && !start)
+        throw new Error("cal booking-change needs --start <new slot start>.");
+    if (action !== "booking-page") {
+        for (const flag of ["--weekly", "--buffer-before", "--buffer-after", "--notice", "--window", "--rotate", "--close", "--open"])
+            if (values.flags.has(flag) || values.booleans.has(flag))
+                throw new Error(`cal ${action} does not take ${flag}; it belongs to cal booking-page.`);
+        return { ...(start ? { bookingStart: start } : {}), ...(email ? { guestEmail: email } : {}), ...(optionalNonEmpty(values.flags.get("--note")) ? { guestNote: optionalNonEmpty(values.flags.get("--note")) } : {}) };
+    }
+    if (values.booleans.has("--close") && values.booleans.has("--open"))
+        throw new Error("cal booking-page takes --close or --open, not both.");
+    const id = optionalNonEmpty(values.flags.get("--id"));
+    const list = values.booleans.has("--list");
+    if (list && id)
+        throw new Error("cal booking-page takes --list or --id, not both.");
+    const edits = values.booleans.has("--rotate") || values.booleans.has("--close") || values.booleans.has("--open");
+    if (edits && !id)
+        throw new Error("--rotate, --close and --open change an existing page: add --id <page id> (from --list).");
+    const numbers = {
+        bufferBefore: wholeNumber(values, "--buffer-before"), bufferAfter: wholeNumber(values, "--buffer-after"),
+        minNotice: wholeNumber(values, "--notice"), windowDays: wholeNumber(values, "--window"),
+    };
+    return {
+        bookingMode: list ? "list" : id ? "change" : "create",
+        ...(id ? { bookingId: id } : {}),
+        ...(weekly.length ? { bookingWeekly: weekly } : {}),
+        ...Object.fromEntries(Object.entries(numbers).filter(([, value]) => value !== undefined)),
+        ...(values.booleans.has("--rotate") ? { rotate: true } : {}),
+        ...(values.booleans.has("--close") ? { bookingClosed: true } : values.booleans.has("--open") ? { bookingClosed: false } : {}),
+        ...(values.booleans.has("--single-use") ? { singleUse: true } : {}),
+        ...(optionalNonEmpty(values.flags.get("--duration")) ? { duration: wholeNumber(values, "--duration") } : {}),
+    };
+}

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

@@ -0,0 +1,42 @@
+/**
+ * BLI-21588 `cockpit cal links <event id>` and `cockpit cal agenda`: the flags, read into a plain shape. Shape only;
+ * the doors own the limits (20 links per event, the occurrence rules, who may read the target).
+ */
+import { optionalNonEmpty } from "./local-arg-values.js";
+export const LINKS_ACTIONS = ["links", "agenda"];
+/** `links <event id>` names one event first. */
+export const LINKS_SUBJECT_ACTIONS = ["links"];
+export const LINKS_BOOLEANS = ["--series"];
+export const LINKS_VALUE_FLAGS = ["--add"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** `doc:<uuid>` or `note:<uuid>`; anything else is named, never guessed. */
+export function readLinkTarget(raw) {
+    const [kind, id, ...extra] = raw.split(":");
+    if ((kind !== "doc" && kind !== "note") || !id || extra.length > 0 || !UUID.test(id)) {
+        throw new Error("--add takes doc:<id> or note:<id>, where <id> is the document's or note's uuid.");
+    }
+    return { kind, id: id.toLowerCase() };
+}
+export function readLinksFlags(action, values) {
+    const add = optionalNonEmpty(values.flags.get("--add"));
+    const remove = action === "links" ? optionalNonEmpty(values.flags.get("--remove")) : undefined;
+    const series = values.booleans.has("--series");
+    if (action !== "links") {
+        for (const flag of ["--add", "--series"]) {
+            if (values.flags.has(flag) || values.booleans.has(flag))
+                throw new Error(`cal ${action} does not take ${flag}; it belongs to cal links.`);
+        }
+        return {};
+    }
+    if (add && remove)
+        throw new Error("cal links takes --add or --remove, not both.");
+    if (series && !add)
+        throw new Error("--series goes with --add: it links the whole series instead of one occurrence.");
+    if (add && !series && !optionalNonEmpty(values.flags.get("--occurrence") ?? values.flags.get("--occurrence-start"))) {
+        throw new Error("cal links --add needs --occurrence <the occurrence's ISO start> or --series.");
+    }
+    return {
+        ...(add ? { linkAdd: readLinkTarget(add), ...(series ? { linkSeries: true } : {}) } : {}),
+        ...(remove ? { linkRemove: remove } : {}),
+    };
+}

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

@@ -0,0 +1,74 @@
+/**
+ * BLI-21564 `cockpit cal remind|join|reminders|snooze|dismiss`: the flags, read into a plain shape. Shape only; the
+ * doors own every limit (lead 0 to 60, snooze 5/10/15, the occurrence rules).
+ */
+import { optionalNonEmpty } from "./local-arg-values.js";
+export const REMIND_ACTIONS = ["remind", "join", "reminders", "snooze", "dismiss"];
+/** Verbs that name one event first: `snooze <event id> --occurrence <iso> --minutes 10`. */
+export const REMIND_SUBJECT_ACTIONS = ["snooze", "dismiss"];
+export const REMIND_BOOLEANS = ["--on", "--off", "--print"];
+export const REMIND_VALUE_FLAGS = ["--event", "--lead", "--sound", "--minutes"];
+const OWN_FLAGS = [...REMIND_BOOLEANS, ...REMIND_VALUE_FLAGS];
+function wholeNumber(values, flag) {
+    const raw = optionalNonEmpty(values.flags.get(flag));
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        throw new Error(`${flag} takes a whole number of minutes.`);
+    return Number(raw);
+}
+export function readRemindFlags(action, values) {
+    const owns = (flag) => {
+        if (flag === "--print" || flag === "--event")
+            return action === "join";
+        if (flag === "--minutes")
+            return action === "snooze";
+        return action === "reminders";
+    };
+    for (const flag of OWN_FLAGS) {
+        if ((values.flags.has(flag) || values.booleans.has(flag)) && !owns(flag)) {
+            throw new Error(`cal ${action} does not take ${flag}; it belongs to the cal remind verbs (remind, join, reminders, snooze, dismiss).`);
+        }
+    }
+    const occurrence = optionalNonEmpty(values.flags.get("--occurrence") ?? values.flags.get("--occurrence-start"));
+    if (action === "snooze" || action === "dismiss") {
+        if (!occurrence)
+            throw new Error(`cal ${action} needs --occurrence <the occurrence's ISO start>, as shown by cal next.`);
+        if (action === "dismiss")
+            return {};
+        const minutes = wholeNumber(values, "--minutes");
+        if (minutes === undefined || ![5, 10, 15].includes(minutes))
+            throw new Error("cal snooze needs --minutes 5, 10 or 15.");
+        return { snoozeMinutes: minutes };
+    }
+    if (action === "join") {
+        const event = optionalNonEmpty(values.flags.get("--event"));
+        if (event && !occurrence)
+            throw new Error("cal join --event needs --occurrence <the occurrence's ISO start>.");
+        if (!event && occurrence)
+            throw new Error("cal join --occurrence needs --event <event id>.");
+        return { ...(event ? { remindEvent: event } : {}), ...(values.booleans.has("--print") ? { printOnly: true } : {}) };
+    }
+    if (action !== "reminders")
+        return {};
+    if (values.booleans.has("--on") && values.booleans.has("--off"))
+        throw new Error("cal reminders takes --on or --off, not both.");
+    const patch = {};
+    if (values.booleans.has("--on"))
+        patch.enabled = true;
+    if (values.booleans.has("--off"))
+        patch.enabled = false;
+    const lead = wholeNumber(values, "--lead");
+    if (lead !== undefined) {
+        if (lead > 60)
+            throw new Error("--lead takes 0 to 60 minutes.");
+        patch.lead_minutes = lead;
+    }
+    const sound = optionalNonEmpty(values.flags.get("--sound"));
+    if (sound !== undefined) {
+        if (sound !== "on" && sound !== "off")
+            throw new Error("--sound takes on or off.");
+        patch.sound = sound === "on";
+    }
+    return Object.keys(patch).length ? { reminderPatch: patch } : {};
+}

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

@@ -0,0 +1,41 @@
+/**
+ * BLI-21548 `cockpit cal availability-share|availability-revoke`: the flags, read into a plain shape.
+ * Shape only; the door owns every limit (ranges, duration, expiry).
+ */
+import { optionalNonEmpty } from "./local-arg-values.js";
+export const SHARE_ACTIONS = ["availability-share", "availability-revoke"];
+export const SHARE_BOOLEANS = ["--list", "--text", "--link", "--single-use", "--allow-conflicts"];
+export const SHARE_VALUE_FLAGS = ["--range", "--expires", "--label", "--id"];
+const SHARE_FLAGS = [...SHARE_BOOLEANS, ...SHARE_VALUE_FLAGS];
+export function readShareFlags(action, values) {
+    if (action !== "availability-share") {
+        for (const flag of SHARE_FLAGS) {
+            if (action === "booking-page" && ["--list", "--id", "--single-use"].includes(flag))
+                continue;
+            if (values.flags.has(flag) || values.booleans.has(flag))
+                throw new Error(`cal ${action} does not take ${flag}; it belongs to cal availability-share.`);
+        }
+        return {};
+    }
+    const ranges = (values.flagValues.get("--range") ?? []).map((range) => range.trim()).filter(Boolean);
+    for (const range of ranges)
+        if (range.split("/").length !== 2 || range.split("/").some((end) => !end.trim()))
+            throw new Error("--range takes <start>/<end>, like 2026-10-20T10:00/2026-10-20T17:00 (times without an offset are read in --tz).");
+    const modes = ["--list", "--text", "--link"].filter((flag) => values.booleans.has(flag));
+    if (modes.length > 1)
+        throw new Error(`cal availability-share takes one of --list, --text or --link, not ${modes.join(" and ")}.`);
+    const id = optionalNonEmpty(values.flags.get("--id"));
+    const duration = optionalNonEmpty(values.flags.get("--duration"));
+    if (duration !== undefined && !/^\d+$/.test(duration))
+        throw new Error("--duration takes a whole number of minutes.");
+    return {
+        ...(ranges.length ? { shareRanges: ranges } : {}),
+        shareMode: values.booleans.has("--list") ? "list" : id ? "change" : values.booleans.has("--link") ? "link" : "text",
+        ...(id ? { shareId: id } : {}),
+        ...(duration === undefined ? {} : { duration: Number(duration) }),
+        ...(optionalNonEmpty(values.flags.get("--expires")) ? { shareExpires: optionalNonEmpty(values.flags.get("--expires")) } : {}),
+        ...(optionalNonEmpty(values.flags.get("--label")) ? { shareLabel: optionalNonEmpty(values.flags.get("--label")) } : {}),
+        ...(values.booleans.has("--single-use") ? { singleUse: true } : {}),
+        ...(values.booleans.has("--allow-conflicts") ? { allowConflicts: true } : {}),
+    };
+}