@bli-cockpit/cli 0.2.242 → 0.2.243

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-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 } : {}),
+    };
+}

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

@@ -19,8 +19,12 @@
  * would be computed in UTC — "today" would end at 5pm in Vancouver.
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+import { BOOKING_ACTIONS, BOOKING_BOOLEANS, BOOKING_GUEST_ACTIONS, BOOKING_VALUE_FLAGS, readBookingFlags } from "./local-args-tower-cal-booking.js";
+import { LINKS_ACTIONS, LINKS_BOOLEANS, LINKS_SUBJECT_ACTIONS, LINKS_VALUE_FLAGS, readLinksFlags } from "./local-args-tower-cal-links.js";
+import { readRemindFlags, REMIND_ACTIONS, REMIND_BOOLEANS, REMIND_SUBJECT_ACTIONS, REMIND_VALUE_FLAGS } from "./local-args-tower-cal-remind.js";
+import { readShareFlags, SHARE_ACTIONS, SHARE_BOOLEANS, SHARE_VALUE_FLAGS } from "./local-args-tower-cal-share.js";
 const CAL_ACTIONS = new Set([
-    "event", "export", "duplicate", "batch", "undo", "conflicts", "calendar-change", "view-settings", "view-settings-change",
+    "event", "export", "duplicate", "batch", "undo", "conflicts", "calendar-change", "view-settings", "view-settings-change", "people", "availability", "overlays", "suggest", ...SHARE_ACTIONS, ...BOOKING_ACTIONS, ...REMIND_ACTIONS, ...LINKS_ACTIONS,
     "today",
     "week",
     "next",
@@ -36,7 +40,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", "rsvp"]);
+const CAL_ACTIONS_NEEDING_A_SUBJECT = new Set([...BOOKING_GUEST_ACTIONS, ...REMIND_SUBJECT_ACTIONS, ...LINKS_SUBJECT_ACTIONS, "availability-revoke", "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 = [
@@ -73,6 +77,8 @@ const CAL_ALLOWED_FLAGS = [
     "--reason",
     "--scope", "--occurrence", "--response", "--comment", "--reminder", "--visibility", "--transparency", "--key",
     "--view", "--days", "--week-start", "--hide-weekends", "--density", "--zone",
+    "--with", "--pin", "--remove",
+    "--duration", "--weekends", "--recheck", ...SHARE_BOOLEANS, ...SHARE_VALUE_FLAGS, ...BOOKING_BOOLEANS, ...BOOKING_VALUE_FLAGS, ...REMIND_BOOLEANS, ...REMIND_VALUE_FLAGS, ...LINKS_BOOLEANS, ...LINKS_VALUE_FLAGS,
 ];
 const CAL_VALUE_FLAGS = [
     "--home",
@@ -98,6 +104,7 @@ const CAL_VALUE_FLAGS = [
     "--reason",
     "--scope", "--occurrence", "--response", "--comment", "--reminder", "--visibility", "--transparency", "--key",
     "--view", "--days", "--week-start", "--hide-weekends", "--density", "--zone",
+    "--with", "--pin", "--remove", "--duration", ...SHARE_VALUE_FLAGS, ...BOOKING_VALUE_FLAGS, ...REMIND_VALUE_FLAGS, ...LINKS_VALUE_FLAGS,
 ];
 export function parseCalArgs(args) {
     const values = parseNamedArgs(args, { allowedFlags: CAL_ALLOWED_FLAGS, valueFlags: CAL_VALUE_FLAGS });
@@ -111,13 +118,13 @@ export function parseCalArgs(args) {
     const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
     const offset = readCalOffset(values);
     const command = buildCalCommand(values, action, subject, query, title, startsAt, endsAt, offset, limit);
-    return { ...command, ...readCalEventScope(action, values), ...readViewSettingsPatch(action, values) };
+    return { ...command, ...readCalEventScope(action, values), ...readViewSettingsPatch(action, values), ...readPeopleFlags(action, values), ...readShareFlags(action, values), ...readBookingFlags(action, values), ...readRemindFlags(action, values), ...readLinksFlags(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, view-settings, view-settings-change, next, find, calendars, add-ical, create, duplicate, batch, undo, share, detach, sync, sync-status, or delete.`);
+        throw new Error(`Unknown cal command: ${first}. Try today, week, conflicts, calendar-change, view-settings, view-settings-change, people, availability, overlays, suggest, availability-share, availability-revoke, booking-page, booking-slots, book, booking-change, booking-cancel, remind, join, reminders, snooze, dismiss, links, agenda, 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) };
 }
@@ -127,9 +134,17 @@ 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" || 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\`.`);
+            throw new Error(action === "availability-revoke"
+                ? "cal availability-revoke needs a share id — take one from `cockpit cal availability-share --list`."
+                : BOOKING_GUEST_ACTIONS.includes(action)
+                    ? `cal ${action} needs the booking link (or its token) the host or Tower gave you.`
+                    : action === "snooze" || action === "dismiss"
+                        ? `cal ${action} needs an event id and --occurrence — take both from cal next.`
+                        : action === "links"
+                            ? "cal links needs an event id — take one from a window verb's output (today/week/next/find)."
+                            : 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)
             throw new Error(`cal ${action} takes one id, not ${rest.length}.`);
@@ -144,6 +159,11 @@ function readCalSubjectOrQuery(action, rest) {
         if (!query)
             throw new Error('cal find needs words: cockpit cal find "standup".');
     }
+    else if (action === "people") {
+        query = optionalNonEmpty(rest.join(" "));
+        if (!query)
+            throw new Error('cal people needs a name or an email: cockpit cal people "Vee".');
+    }
     else if (rest.length > 0) {
         throw new Error(`cal ${action} does not take "${rest[0]}".`);
     }
@@ -200,7 +220,7 @@ function buildCalCommand(values, action, subject, query, title, startsAt, endsAt
         // `commands/cal.ts` rather than here, so the parser stays pure.
         timeZone: optionalNonEmpty(values.flags.get("--tz")),
         ...(offset === undefined ? {} : { offset }),
-        ...(optionalPositiveInteger(values.flags.get("--hours"), "--hours") === undefined
+        ...(action === "suggest" || optionalPositiveInteger(values.flags.get("--hours"), "--hours") === undefined
             ? {}
             : { hours: optionalPositiveInteger(values.flags.get("--hours"), "--hours") }),
         from: optionalNonEmpty(values.flags.get("--from")),
@@ -370,4 +390,57 @@ function readViewSettingsPatch(action, values) {
             patch.extra_zones = zones;
     }
     return Object.keys(patch).length ? { viewSettings: patch } : {};
+}
+const PEOPLE_FLAG_KEYS = ["--with", "--pin", "--remove"];
+const SUGGEST_FLAG_KEYS = ["--duration", "--weekends"];
+/** BLI-21522: `availability --with` (repeatable), `overlays --pin|--remove`. Each belongs to one verb. */
+function readPeopleFlags(action, values) {
+    const owner = { "--with": "availability", "--pin": "overlays", "--remove": "overlays" };
+    for (const flag of PEOPLE_FLAG_KEYS) {
+        if (values.flags.has(flag) && owner[flag] !== action && !(flag === "--with" && action === "suggest") && !(flag === "--remove" && action === "links"))
+            throw new Error(`cal ${action} does not take ${flag}; it belongs to cal ${owner[flag]}.`);
+    }
+    for (const flag of SUGGEST_FLAG_KEYS) {
+        if ((values.flags.has(flag) || values.booleans.has(flag)) && action !== "suggest" && !(flag === "--duration" && (action === "availability-share" || action === "booking-page")))
+            throw new Error(`cal ${action} does not take ${flag}; it belongs to cal suggest.`);
+    }
+    if (values.booleans.has("--recheck") && action !== "create")
+        throw new Error(`cal ${action} does not take --recheck; it belongs to cal create.`);
+    if (action === "create" && values.booleans.has("--recheck"))
+        return { recheck: true };
+    if (action === "suggest")
+        return readSuggestFlags(values);
+    if (action === "availability") {
+        const labels = (values.flagValues.get("--with") ?? []).map((label) => label.trim()).filter(Boolean);
+        return labels.length ? { peopleWith: labels } : {};
+    }
+    if (action === "overlays") {
+        const pin = optionalNonEmpty(values.flags.get("--pin"));
+        const remove = optionalNonEmpty(values.flags.get("--remove"));
+        if (pin && remove)
+            throw new Error("cal overlays takes --pin or --remove, not both.");
+        return { ...(pin ? { pinLabel: pin } : {}), ...(remove ? { removeEmail: remove } : {}) };
+    }
+    return {};
+}
+/** BLI-21542 `suggest --with ... --duration 30 --hours 09:00-17:00 --weekends`: shape only; the door owns the limits. */
+function readSuggestFlags(values) {
+    const labels = (values.flagValues.get("--with") ?? []).map((label) => label.trim()).filter(Boolean);
+    const out = labels.length ? { peopleWith: labels } : {};
+    const duration = optionalNonEmpty(values.flags.get("--duration"));
+    if (duration !== undefined) {
+        if (!/^\d+$/.test(duration))
+            throw new Error("--duration takes a whole number of minutes.");
+        out.duration = Number(duration);
+    }
+    const hours = optionalNonEmpty(values.flags.get("--hours"));
+    if (hours !== undefined) {
+        const match = /^(\d{1,2}:\d{2})-(\d{1,2}:\d{2})$/.exec(hours);
+        if (!match)
+            throw new Error("--hours takes a range like 09:00-17:00.");
+        out.hoursRange = { start: match[1], end: match[2] };
+    }
+    if (values.booleans.has("--weekends"))
+        out.weekends = true;
+    return out;
 }