@bli-cockpit/cli 0.2.241 → 0.2.243

package/dist/commands/msg-mark.js

@@ -0,0 +1,148 @@
+/**
+ * The saved, pin and forward verbs of `cockpit msg` (BLI-21774): `save`, `saved`, `pin`, `pins`, `forward`. Same doors the
+ * browser calls (`/api/msg/messages/<id>/save`, `/api/msg/saved`, `.../pin`, `/api/msg/channels/<id>/pins`,
+ * `.../forward`); `--json` prints the door's body unchanged so ids, rows, coverage and reasons match HTTP. A save is private
+ * to you; a pin is shared channel state; a forward posts ONE message holding your comment and the source's exact link,
+ * never its text. A refusal keeps the door's reason: message_not_found_or_unreadable, pin_limit_reached, pin_deleted_message,
+ * channel_archived, forward_source_deleted.
+ */
+import { randomUUID } from "node:crypto";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { runMsgContext } from "./msg-context.js";
+import { runMsgSchedule } from "./msg-schedule.js";
+import { refuseMsgWrite } from "./msg-write.js";
+const TAG = "[msg cli]";
+const DEADLINE_MS = 30_000;
+const COMMENT_MAX_CHARS = 2_000;
+function oneLine(content, deleted) {
+    if (deleted)
+        return "(This message was deleted)";
+    const line = (content ?? "").split("\n")[0] ?? "";
+    return line.length > 140 ? `${line.slice(0, 137)}...` : line;
+}
+async function markVerb(command, door, kind) {
+    const on = command.remove !== true;
+    const answer = await askAgentDoor(door, {
+        path: `/api/msg/messages/${encodeURIComponent(command.targetId ?? "")}/${kind}`,
+        method: on ? "PUT" : "DELETE",
+        label: `msg ${kind}`,
+        timeoutMs: DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} ${kind} ${JSON.stringify({ message_id: command.targetId, on, changed: body.changed === true })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    const past = kind === "save" ? (on ? "Saved" : "Unsaved") : on ? "Pinned" : "Unpinned";
+    writeLine(door.io.stdout, body.changed === false ? `${past} already: ${command.targetId} was already ${past.toLowerCase()}.` : `${past} ${command.targetId}.`);
+    return 0;
+}
+async function savedVerb(command, door) {
+    const query = new URLSearchParams();
+    if (command.before)
+        query.set("before", command.before);
+    if (command.limit)
+        query.set("limit", String(command.limit));
+    const answer = await askAgentDoor(door, {
+        path: `/api/msg/saved${query.size > 0 ? `?${query.toString()}` : ""}`,
+        method: "GET",
+        label: "msg saved",
+        timeoutMs: DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const items = body.items ?? [];
+    writeLine(door.io.stderr, `${TAG} saved ${JSON.stringify({ returned: items.length, dropped: body.coverage?.dropped ?? 0, has_more: body.hasMore === true })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    for (const item of items) {
+        writeLine(door.io.stdout, `${item.message_id}  ${item.saved_at}  ${oneLine(item.message.content, Boolean(item.message.deleted_at))}`);
+    }
+    if (items.length === 0)
+        writeLine(door.io.stdout, "Nothing saved yet.");
+    const dropped = body.coverage?.dropped ?? 0;
+    if (dropped > 0)
+        writeLine(door.io.stdout, `${dropped} saved ${dropped === 1 ? "message is" : "messages are"} not shown: you can no longer read ${dropped === 1 ? "it" : "them"}.`);
+    writeLine(door.io.stdout, body.hasMore && body.nextCursor ? `more: --before ${body.nextCursor}` : "complete");
+    return 0;
+}
+async function pinsVerb(command, door, resolve) {
+    const ref = command.channelRef ?? "";
+    const resolved = await resolve(ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found") {
+        return failAgentDoor(door, TAG, "channel_not_found_or_unreadable", `That channel does not exist, or you cannot read it: ${ref}`);
+    }
+    const answer = await askAgentDoor(door, { path: `/api/msg/channels/${encodeURIComponent(resolved.id)}/pins`, method: "GET", label: "msg pins", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const pins = body.pins ?? [];
+    writeLine(door.io.stderr, `${TAG} pins ${JSON.stringify({ channel_id: resolved.id, returned: pins.length, dropped: body.coverage?.dropped ?? 0 })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    for (const pin of pins) {
+        const who = pin.pinned_by ? body.displayNameById?.[pin.pinned_by] ?? "someone" : "someone";
+        writeLine(door.io.stdout, `${pin.message_id}  pinned ${pin.pinned_at} by ${who}  ${oneLine(pin.message.content, Boolean(pin.message.deleted_at))}`);
+    }
+    if (pins.length === 0)
+        writeLine(door.io.stdout, "Nothing is pinned in this channel.");
+    return 0;
+}
+async function forwardVerb(command, door, resolve) {
+    const ref = command.forwardTo ?? "";
+    const resolved = await resolve(ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found") {
+        return failAgentDoor(door, TAG, "channel_not_found_or_unreadable", `That channel does not exist, or you cannot read it: ${ref}`);
+    }
+    let comment = "";
+    if (!isInteractiveStdin(door.io)) {
+        try {
+            comment = (await readPipedText(door.io.stdin, { maxChars: COMMENT_MAX_CHARS, overflowMessage: `A forward comment is limited to ${COMMENT_MAX_CHARS} characters.` })).trim();
+        }
+        catch (error) {
+            return failAgentDoor(door, TAG, "content_too_long", error instanceof Error ? error.message : String(error));
+        }
+    }
+    const requestId = command.requestId ?? randomUUID();
+    const answer = await askAgentDoor(door, {
+        path: `/api/msg/messages/${encodeURIComponent(command.targetId ?? "")}/forward`,
+        method: "POST",
+        label: "msg forward",
+        timeoutMs: DEADLINE_MS,
+        body: {
+            channel_id: resolved.id,
+            request_id: requestId,
+            ...(comment ? { comment } : {}),
+            ...(command.threadId ? { thread_parent_id: command.threadId } : {}),
+        },
+    });
+    if (!answer.ok)
+        return refuseMsgWrite(door, answer, requestId, "forward");
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} forwarded ${JSON.stringify({ source_id: command.targetId, destination_channel_id: resolved.id, message_id: body.message?.id ?? null, request_id: requestId })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    writeLine(door.io.stdout, `Forwarded ${command.targetId} to ${ref} as ${body.message?.id ?? "a new message"}. It holds your comment and the link only.`);
+    return 0;
+}
+export async function runMsgMark(command, door, resolve) {
+    switch (command.action) {
+        case "save": return markVerb(command, door, "save");
+        case "pin": return markVerb(command, door, "pin");
+        case "saved": return savedVerb(command, door);
+        case "pins": return pinsVerb(command, door, resolve);
+        // BLI-21802: the schedule verbs ride the same entry so `msg.ts` stays under the file-size ratchet.
+        case "schedule":
+        case "remind":
+        case "scheduled": return runMsgSchedule(command, door, resolve);
+        case "context": return runMsgContext(command, door);
+        default: return forwardVerb(command, door, resolve);
+    }
+}

package/dist/commands/msg-notify-args.js

@@ -0,0 +1,100 @@
+/**
+ * Arguments of `cockpit msg notify` (BLI-21605): `notify [--json]`, `notify set --level <all|mentions|none>
+ * [--channel <id|name>] [--mute|--unmute] [--clear]`, `notify quiet <HH:MM-HH:MM> [--timezone <zone>] | --off`,
+ * `notify receipts [--message <id>] [--before <cursor>] [--limit <n>]`. Split out of `local-args-tower-msg.ts`.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl } from "./local-arg-values.js";
+export const MSG_NOTIFY_ONLY_FLAGS = ["--level", "--timezone", "--message", "--mute", "--unmute", "--clear", "--off"];
+const VERBS = new Set(["set", "quiet", "receipts"]);
+const LEVELS = ["all", "mentions", "none"];
+const WINDOW = /^([01]\d|2[0-3]):([0-5]\d)-([01]\d|2[0-3]):([0-5]\d)$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function browserZone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}
+export function parseMsgNotifyArgs(values, rest) {
+    const first = rest[0];
+    if (first !== undefined && !VERBS.has(first)) {
+        throw new Error(`Unknown msg notify command: ${first}. Try set, quiet or receipts, or no verb to show your settings.`);
+    }
+    const verb = first ?? "show";
+    const positional = rest.slice(1);
+    const has = (flag) => values.flags.has(flag) || values.booleans.has(flag);
+    const allowed = {
+        show: [],
+        set: ["--level", "--channel", "--mute", "--unmute", "--clear"],
+        quiet: ["--timezone", "--off"],
+        receipts: ["--message", "--before", "--limit"],
+    };
+    const stray = [...MSG_NOTIFY_ONLY_FLAGS, "--channel", "--before", "--limit"].find((flag) => has(flag) && !allowed[verb].includes(flag));
+    if (stray)
+        throw new Error(`${stray} does not belong to \`cockpit msg notify${verb === "show" ? "" : ` ${verb}`}\`.`);
+    const stray2 = ["--thread", "--members", "--description", "--from", "--request-id", "--expected-revision", "--name", "--out", "--file", "--mark-read", "--mentions", "--threads", "--unread", "--remove", "--private"].find(has);
+    if (stray2)
+        throw new Error(`${stray2} does not belong to \`cockpit msg notify\`.`);
+    const level = optionalNonEmpty(values.flags.get("--level"));
+    const channelRef = optionalNonEmpty(values.flags.get("--channel"));
+    const mute = values.booleans.has("--mute");
+    const unmute = values.booleans.has("--unmute");
+    const clear = values.booleans.has("--clear");
+    const quietOff = values.booleans.has("--off");
+    const timezone = optionalNonEmpty(values.flags.get("--timezone"));
+    const messageId = optionalNonEmpty(values.flags.get("--message"));
+    const before = optionalNonEmpty(values.flags.get("--before"));
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    let quietWindow;
+    if (verb === "set") {
+        if (positional.length > 0)
+            throw new Error(`msg notify set does not take "${positional[0]}".`);
+        if (level && !LEVELS.includes(level))
+            throw new Error("--level must be all, mentions or none.");
+        if (mute && unmute)
+            throw new Error("Pick one of --mute or --unmute.");
+        if (!channelRef && (mute || unmute || clear))
+            throw new Error("--mute, --unmute and --clear need --channel <id|name>.");
+        if (clear && (level || mute || unmute))
+            throw new Error("--clear removes the channel override; do not combine it with --level, --mute or --unmute.");
+        if (!level && !mute && !unmute && !clear)
+            throw new Error("msg notify set needs --level <all|mentions|none>, or with --channel also --mute, --unmute or --clear.");
+    }
+    if (verb === "quiet") {
+        quietWindow = optionalNonEmpty(positional[0]);
+        if (quietOff && quietWindow)
+            throw new Error("Pass a window or --off, not both.");
+        if (!quietOff && (!quietWindow || !WINDOW.test(quietWindow)))
+            throw new Error("msg notify quiet needs a window like 22:00-07:00 (24-hour, may wrap midnight), or --off.");
+        if (positional.length > 1)
+            throw new Error("msg notify quiet takes one window.");
+        if (quietOff && timezone)
+            throw new Error("--timezone belongs with a window, not --off.");
+        if (quietWindow && quietWindow.slice(0, 5) === quietWindow.slice(6))
+            throw new Error("Quiet hours need a start and an end that differ.");
+    }
+    if (verb === "receipts") {
+        if (positional.length > 0)
+            throw new Error(`msg notify receipts does not take "${positional[0]}".`);
+        if (messageId && !UUID.test(messageId))
+            throw new Error("--message takes a message id (a UUID).");
+        if (limit !== undefined && limit > 100)
+            throw new Error("--limit takes 1 to 100.");
+    }
+    return {
+        kind: "msg",
+        action: "notify",
+        notifyVerb: verb,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        isPrivate: false,
+        json: values.booleans.has("--json"),
+        ...(level ? { notifyLevel: level } : {}),
+        ...(channelRef ? { channelRef } : {}),
+        ...(mute ? { mute } : {}),
+        ...(unmute ? { unmute } : {}),
+        ...(clear ? { clear } : {}),
+        ...(quietOff ? { quietOff } : {}),
+        ...(quietWindow ? { quietWindow, timezone: timezone ?? browserZone() } : {}),
+        ...(messageId ? { targetId: messageId } : {}),
+        ...(before ? { before } : {}),
+        ...(limit === undefined ? {} : { limit }),
+    };
+}

package/dist/commands/msg-notify.js

@@ -0,0 +1,122 @@
+/**
+ * `cockpit msg notify` (BLI-21605): your message notification settings, quiet hours, channel overrides and delivery
+ * receipts. Same doors the browser calls (`/api/msg/notifications/settings`, `/api/msg/channels/<id>/notifications`,
+ * `/api/msg/notifications/receipts`); `--json` prints the door's body unchanged so ids, levels and reasons match HTTP.
+ * A phone receipt says `push_accepted` (the push service took it), never that a phone showed it.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[msg cli]";
+const DEADLINE_MS = 30_000;
+function settingsLines(settings) {
+    const quiet = settings.quiet_hours;
+    const lines = [
+        `Default level: ${settings.default_level}`,
+        quiet ? `Quiet hours: ${quiet.start}-${quiet.end} (${quiet.timezone})` : "Quiet hours: off",
+    ];
+    if (settings.channels.length === 0)
+        lines.push("No channel overrides.");
+    for (const channel of settings.channels) {
+        lines.push(`Channel ${channel.channel_id}: ${channel.muted ? "muted" : (channel.level ?? "default level")}${channel.muted && channel.level ? ` (level ${channel.level})` : ""}`);
+    }
+    return lines;
+}
+async function showSettings(door) {
+    const answer = await askAgentDoor(door, { path: "/api/msg/notifications/settings", method: "GET", label: "msg notify", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const settings = answer.body.settings;
+    writeLine(door.io.stderr, `${TAG} notify settings ${JSON.stringify({ channels: settings.channels.length, quiet_hours: settings.quiet_hours !== null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    for (const line of settingsLines(settings))
+        writeLine(door.io.stdout, line);
+    return 0;
+}
+async function putSettings(door, label, body, done) {
+    const answer = await askAgentDoor(door, { path: "/api/msg/notifications/settings", method: "PUT", label, timeoutMs: DEADLINE_MS, body });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const result = answer.body;
+    writeLine(door.io.stderr, `${TAG} ${label} ${JSON.stringify({ changed: result.changed === true, fields: result.changedFields ?? [] })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    writeLine(door.io.stdout, result.changed === false ? `${done} (it was already that way).` : `${done}.`);
+    return 0;
+}
+async function setChannel(command, door, resolve) {
+    const ref = command.channelRef ?? "";
+    const resolved = await resolve(ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found") {
+        return failAgentDoor(door, TAG, "channel_not_found_or_unreadable", `That channel does not exist, or you cannot read it: ${ref}`);
+    }
+    const path = `/api/msg/channels/${encodeURIComponent(resolved.id)}/notifications`;
+    const body = {
+        ...(command.notifyLevel ? { level: command.notifyLevel } : {}),
+        ...(command.mute ? { muted: true } : {}),
+        ...(command.unmute ? { muted: false } : {}),
+    };
+    const answer = command.clear
+        ? await askAgentDoor(door, { path, method: "DELETE", label: "msg notify clear", timeoutMs: DEADLINE_MS })
+        : await askAgentDoor(door, { path, method: "PUT", label: "msg notify set", timeoutMs: DEADLINE_MS, body });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const result = answer.body;
+    writeLine(door.io.stderr, `${TAG} notify channel ${JSON.stringify({ channel_id: resolved.id, changed: result.changed === true, cleared: command.clear === true })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, channel_id: resolved.id, ...answer.body });
+    const now = result.channel ? (result.channel.muted ? "muted" : (result.channel.level ?? "your default level")) : "your default level";
+    writeLine(door.io.stdout, `Channel ${resolved.id}: ${now}${result.changed === false ? " (it was already that way)" : ""}.`);
+    return 0;
+}
+async function showReceipts(command, door) {
+    const query = new URLSearchParams();
+    if (command.targetId)
+        query.set("message_id", command.targetId);
+    if (command.before)
+        query.set("before", command.before);
+    if (command.limit)
+        query.set("limit", String(command.limit));
+    const answer = await askAgentDoor(door, {
+        path: `/api/msg/notifications/receipts${query.size > 0 ? `?${query.toString()}` : ""}`,
+        method: "GET",
+        label: "msg notify receipts",
+        timeoutMs: DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const receipts = body.receipts ?? [];
+    writeLine(door.io.stderr, `${TAG} notify receipts ${JSON.stringify({ returned: receipts.length, has_more: body.hasMore === true })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    if (receipts.length === 0)
+        writeLine(door.io.stdout, "No delivery receipts.");
+    for (const receipt of receipts) {
+        writeLine(door.io.stdout, `${receipt.created_at}  ${receipt.transport}  ${receipt.kind}  ${receipt.outcome}  ${receipt.reason}  message ${receipt.message_id}`);
+    }
+    if (body.nextCursor)
+        writeLine(door.io.stdout, `More: --before ${body.nextCursor}`);
+    return 0;
+}
+export async function runMsgNotify(command, door, resolve) {
+    switch (command.notifyVerb ?? "show") {
+        case "show":
+            return showSettings(door);
+        case "set":
+            if (command.channelRef)
+                return setChannel(command, door, resolve);
+            return putSettings(door, "msg notify set", { default_level: command.notifyLevel }, `Default level is ${command.notifyLevel}`);
+        case "quiet": {
+            if (command.quietOff)
+                return putSettings(door, "msg notify quiet", { quiet_hours: null }, "Quiet hours are off");
+            const [start, end] = (command.quietWindow ?? "").split("-");
+            const zone = command.timezone ?? "UTC";
+            return putSettings(door, "msg notify quiet", { quiet_hours: { start, end, timezone: zone } }, `Quiet hours are ${start}-${end} (${zone})`);
+        }
+        case "receipts":
+            return showReceipts(command, door);
+    }
+}

package/dist/commands/msg-schedule-args.js

@@ -0,0 +1,114 @@
+/**
+ * Arguments of `cockpit msg schedule|remind|scheduled` (BLI-21802):
+ *   schedule <channel> --at <instant|"YYYY-MM-DD HH:MM"> [--timezone <zone>] [--thread <id>] [--request-id <uuid>]   (body on stdin)
+ *   remind <message-id> --at <...> [--timezone <zone>] [--note <text>] [--request-id <uuid>]
+ *   scheduled [--state <state|open|all>] [--before <cursor>] [--limit <n>]
+ *   scheduled change <id> [--at <...>] [--timezone <zone>] [--revision <n>]   (optional new body on stdin)
+ *   scheduled cancel <id> | scheduled done <id>
+ * Split out of `local-args-tower-msg.ts`.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl } from "./local-arg-values.js";
+export const MSG_SCHEDULE_ACTIONS = ["schedule", "remind", "scheduled"];
+export const MSG_SCHEDULE_VALUE_FLAGS = ["--at", "--note", "--state", "--revision"];
+export const SCHEDULE_STATE_NAMES = ["pending", "sent", "failed", "cancelled", "fired", "done", "open", "all"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NOTE_MAX = 500;
+export function isMsgScheduleAction(action) {
+    return MSG_SCHEDULE_ACTIONS.includes(action);
+}
+/** A schedule flag used on another msg verb is named, not ignored. */
+export function rejectMsgScheduleFlags(values) {
+    const flag = MSG_SCHEDULE_VALUE_FLAGS.find((name) => values.flags.has(name));
+    if (flag)
+        throw new Error(`${flag} belongs to \`cockpit msg schedule\`, \`msg remind\` or \`msg scheduled\`.`);
+}
+export function parseMsgScheduleArgs(action, values, rest) {
+    const stray = ["--channel", "--members", "--description", "--from", "--expected-revision", "--name", "--out", "--file", "--level", "--message", "--to"]
+        .find((flag) => values.flags.has(flag));
+    const strayBoolean = ["--private", "--mentions", "--threads", "--unread", "--mark-read", "--remove"].find((flag) => values.booleans.has(flag));
+    if (stray || strayBoolean)
+        throw new Error(`${stray ?? strayBoolean} does not belong to \`cockpit msg ${action}\`.`);
+    const base = {
+        kind: "msg",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        isPrivate: false,
+        json: values.booleans.has("--json"),
+    };
+    const at = optionalNonEmpty(values.flags.get("--at"));
+    const timezone = optionalNonEmpty(values.flags.get("--timezone"));
+    const thread = optionalNonEmpty(values.flags.get("--thread"));
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    const note = values.flags.get("--note");
+    const state = optionalNonEmpty(values.flags.get("--state"));
+    const before = optionalNonEmpty(values.flags.get("--before"));
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    const revisionText = optionalNonEmpty(values.flags.get("--revision"));
+    const revision = revisionText === undefined ? undefined : optionalPositiveInteger(revisionText, "--revision");
+    if (requestId && !UUID.test(requestId))
+        throw new Error("--request-id takes a UUID.");
+    if (thread && (action !== "schedule" || !UUID.test(thread))) {
+        throw new Error(action === "schedule" ? "--thread takes a message id (a UUID)." : "--thread belongs to `cockpit msg schedule`.");
+    }
+    if (note !== undefined && action !== "remind")
+        throw new Error("--note belongs to `cockpit msg remind`.");
+    if (note !== undefined && note.length > NOTE_MAX)
+        throw new Error(`--note is limited to ${NOTE_MAX} characters.`);
+    if (requestId && action === "scheduled")
+        throw new Error("--request-id belongs to `cockpit msg schedule` and `msg remind`.");
+    if (action === "scheduled") {
+        const verb = rest[0];
+        if (verb === "change" || verb === "cancel" || verb === "done") {
+            const targetId = optionalNonEmpty(rest[1]);
+            if (!targetId || !UUID.test(targetId))
+                throw new Error(`msg scheduled ${verb} needs a schedule id (a UUID) from \`cockpit msg scheduled\`.`);
+            if (rest.length > 2)
+                throw new Error(`msg scheduled ${verb} takes one schedule id, not ${rest.length - 1}.`);
+            if (state || before || limit !== undefined)
+                throw new Error("--state, --before and --limit belong to `cockpit msg scheduled` (the list).");
+            if (verb !== "change" && (at || timezone || revision !== undefined))
+                throw new Error(`--at, --timezone and --revision belong to \`cockpit msg scheduled change\`.`);
+            return {
+                ...base, scheduleVerb: verb, targetId,
+                ...(at ? { scheduleAt: at } : {}), ...(timezone ? { timezone } : {}), ...(revision === undefined ? {} : { scheduleRevision: revision }),
+            };
+        }
+        if (rest.length > 0)
+            throw new Error(`msg scheduled does not take "${rest[0]}". Try change, cancel or done, or no word to list.`);
+        if (at || timezone || revision !== undefined)
+            throw new Error("--at, --timezone and --revision belong to `cockpit msg scheduled change`.");
+        if (state && !SCHEDULE_STATE_NAMES.includes(state)) {
+            throw new Error(`--state takes one of ${SCHEDULE_STATE_NAMES.join(", ")}.`);
+        }
+        return {
+            ...base, scheduleVerb: "list",
+            ...(state ? { scheduleState: state } : {}), ...(before ? { before } : {}), ...(limit === undefined ? {} : { limit }),
+        };
+    }
+    if (state || before || limit !== undefined || revision !== undefined) {
+        throw new Error(`--state, --before, --limit and --revision belong to \`cockpit msg scheduled\`, not \`msg ${action}\`.`);
+    }
+    const target = optionalNonEmpty(rest[0]);
+    if (rest.length > 1)
+        throw new Error(`msg ${action} takes one ${action === "schedule" ? "channel" : "message id"}, not ${rest.length}.`);
+    if (!at) {
+        throw new Error(action === "schedule"
+            ? 'msg schedule needs --at, e.g. `echo "standup notes" | cockpit msg schedule ops --at "2026-11-02 09:00" --timezone America/Toronto`.'
+            : 'msg remind needs --at, e.g. `cockpit msg remind <message-id> --at "2026-11-02 09:00" --timezone America/Toronto`.');
+    }
+    if (action === "schedule") {
+        if (!target)
+            throw new Error("msg schedule needs a channel id or name, e.g. `cockpit msg schedule ops --at ...`.");
+        return {
+            ...base, channelRef: target, scheduleAt: at,
+            ...(timezone ? { timezone } : {}), ...(thread ? { threadId: thread } : {}), ...(requestId ? { requestId } : {}),
+        };
+    }
+    if (!target || !UUID.test(target))
+        throw new Error("msg remind needs a message id (a UUID), e.g. `cockpit msg remind <message-id> --at ...`.");
+    return {
+        ...base, targetId: target, scheduleAt: at,
+        ...(timezone ? { timezone } : {}), ...(note !== undefined ? { scheduleNote: note } : {}), ...(requestId ? { requestId } : {}),
+    };
+}