@bli-cockpit/cli 0.2.242 → 0.2.244

package/dist/commands/msg-file.js

@@ -0,0 +1,185 @@
+/**
+ * `cockpit msg file` (BLI-21521): first-party message files over the same doors the browser calls.
+ *
+ *   upload <channel> <path|->  reserve (POST /api/msg/files), PUT the bytes to the signed URL, finalize
+ *   show <id>                  the descriptor
+ *   download <id> [--out]      a 60-second signed link, fetched to disk (never overwrites)
+ *   cancel <id>                ends an unattached file
+ *   list <channel>             your own unsent uploads in that channel
+ *
+ * The device token goes to Tower's own routes only; the PUT and the download go to the storage host with
+ * the signed URL and nothing else. File names are shown to the person but never written to a log line.
+ */
+import { randomUUID } from "node:crypto";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { isInteractiveStdin, writeLine } from "./cli-io.js";
+const TAG = "[msg file cli]";
+const DEADLINE_MS = 30_000;
+/** A 25 MB transfer on a slow link; the signed URL itself lives two hours. */
+const TRANSFER_DEADLINE_MS = 10 * 60_000;
+const MAX_BYTES = 26_214_400;
+const MEDIA_TYPES = {
+    ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp",
+    ".pdf": "application/pdf", ".txt": "text/plain", ".md": "text/markdown", ".json": "application/json",
+    ".csv": "text/csv", ".zip": "application/zip", ".svg": "image/svg+xml",
+};
+const describe = (file) => `${file.id}  ${file.state}  ${file.byte_size} bytes  ${file.name}`;
+async function readStdinBytes(door) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of door.io.stdin) {
+        const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        total += buffer.length;
+        if (total > MAX_BYTES)
+            return "too_large";
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks);
+}
+/** `channelId` is already resolved by `msg.ts` for `upload` and `list`. */
+export async function runMsgFile(command, door, channelId) {
+    switch (command.fileVerb) {
+        case "upload": return uploadFile(command, door, channelId ?? "");
+        case "show": return showFile(command, door);
+        case "download": return downloadFile(command, door);
+        case "cancel": return cancelFile(command, door);
+        case "list": return listFiles(door, channelId ?? "");
+        default: return failAgentDoor(door, TAG, "invalid_body", "Try upload, show, download, cancel or list.");
+    }
+}
+async function uploadFile(command, door, channelId) {
+    const source = command.filePath ?? "";
+    let bytes;
+    let name = command.fileName ?? basename(source);
+    if (source === "-") {
+        if (isInteractiveStdin(door.io))
+            return failAgentDoor(door, TAG, "nothing_piped", "Pipe the file in, e.g. `cat report.pdf | cockpit msg file upload general - --name report.pdf`.");
+        const read = await readStdinBytes(door);
+        if (read === "too_large")
+            return failAgentDoor(door, TAG, "file_too_large", `A file can be at most ${MAX_BYTES.toLocaleString("en-US")} bytes (25 MB).`);
+        bytes = read;
+    }
+    else {
+        const path = resolve(source);
+        try {
+            const info = await stat(path);
+            if (!info.isFile())
+                return failAgentDoor(door, TAG, "invalid_body", "That path is not a file.");
+            if (info.size > MAX_BYTES)
+                return failAgentDoor(door, TAG, "file_too_large", `A file can be at most ${MAX_BYTES.toLocaleString("en-US")} bytes (25 MB).`);
+            bytes = await readFile(path);
+        }
+        catch {
+            return failAgentDoor(door, TAG, "invalid_body", "Tower could not read that file. Check the path.");
+        }
+    }
+    if (name === "")
+        name = "file";
+    const mediaType = MEDIA_TYPES[extname(name).toLowerCase()] ?? "application/octet-stream";
+    const reserved = await askAgentDoor(door, {
+        path: "/api/msg/files", method: "POST", label: "msg file reserve", timeoutMs: DEADLINE_MS,
+        body: { channel_id: channelId, name, media_type: mediaType, byte_size: bytes.length },
+    });
+    if (!reserved.ok)
+        return failAgentDoor(door, TAG, reserved.reason, reserved.detail);
+    const { file, upload } = reserved.body;
+    let put;
+    try {
+        put = await door.io.fetch(upload.url, {
+            method: upload.method ?? "PUT", headers: upload.headers ?? {}, body: new Uint8Array(bytes),
+            signal: AbortSignal.timeout(TRANSFER_DEADLINE_MS),
+        });
+    }
+    catch (error) {
+        writeLine(door.io.stderr, `${TAG} put failed ${JSON.stringify({ file_id: file.id, reason: "storage_unreachable", bytes: bytes.length, error_name: error instanceof Error ? error.name : "error" })}`);
+        return failAgentDoor(door, TAG, "storage_unreachable", `Could not reach storage. Nothing was sent. Cancel with \`cockpit msg file cancel ${file.id}\` or upload again.`, { file_id: file.id });
+    }
+    if (!put.ok) {
+        writeLine(door.io.stderr, `${TAG} put refused ${JSON.stringify({ file_id: file.id, reason: `storage_http_${put.status}`, bytes: bytes.length })}`);
+        return failAgentDoor(door, TAG, "storage_unreachable", `Storage refused the upload (HTTP ${put.status}). Cancel with \`cockpit msg file cancel ${file.id}\` or upload again.`, { file_id: file.id });
+    }
+    const done = await askAgentDoor(door, { path: `/api/msg/files/${file.id}/finalize`, method: "POST", label: "msg file finalize", timeoutMs: DEADLINE_MS, body: {} });
+    if (!done.ok) {
+        writeLine(door.io.stderr, `${TAG} finish failed, safe to repeat: POST /api/msg/files/${file.id}/finalize`);
+        return failAgentDoor(door, TAG, done.reason, done.detail, { file_id: file.id });
+    }
+    const ready = done.body.file;
+    writeLine(door.io.stderr, `${TAG} uploaded ${JSON.stringify({ file_id: ready.id, bytes: bytes.length, state: ready.state })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, file: ready });
+    writeLine(door.io.stdout, `Uploaded ${describe(ready)}`);
+    writeLine(door.io.stdout, `Send it with: cockpit msg send ${command.channelRef ?? "<channel>"} --file ${ready.id}`);
+    return 0;
+}
+async function showFile(command, door) {
+    const answer = await askAgentDoor(door, { path: `/api/msg/files/${encodeURIComponent(command.targetId ?? "")}`, method: "GET", label: "msg file show", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const file = answer.body.file;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, file });
+    writeLine(door.io.stdout, describe(file));
+    return 0;
+}
+async function cancelFile(command, door) {
+    const answer = await askAgentDoor(door, { path: `/api/msg/files/${encodeURIComponent(command.targetId ?? "")}`, method: "DELETE", label: "msg file cancel", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const file = answer.body.file;
+    writeLine(door.io.stderr, `${TAG} cancelled ${JSON.stringify({ file_id: file.id, state: file.state })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, file });
+    writeLine(door.io.stdout, `Cancelled ${describe(file)}`);
+    return 0;
+}
+async function listFiles(door, channelId) {
+    const answer = await askAgentDoor(door, { path: `/api/msg/files?channel_id=${encodeURIComponent(channelId)}`, method: "GET", label: "msg file list", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    if (body.files.length === 0)
+        writeLine(door.io.stdout, "No unsent files in that channel.");
+    for (const file of body.files)
+        writeLine(door.io.stdout, describe(file));
+    writeLine(door.io.stdout, `${body.returned} unsent file(s), coverage ${body.coverage}.`);
+    return 0;
+}
+async function downloadFile(command, door) {
+    const id = encodeURIComponent(command.targetId ?? "");
+    const described = await askAgentDoor(door, { path: `/api/msg/files/${id}`, method: "GET", label: "msg file show", timeoutMs: DEADLINE_MS });
+    if (!described.ok)
+        return failAgentDoor(door, TAG, described.reason, described.detail);
+    const file = described.body.file;
+    const link = await askAgentDoor(door, { path: `/api/msg/files/${id}/download?format=json`, method: "GET", label: "msg file link", timeoutMs: DEADLINE_MS });
+    if (!link.ok)
+        return failAgentDoor(door, TAG, link.reason, link.detail);
+    const { url } = link.body;
+    let bytes;
+    try {
+        const response = await door.io.fetch(url, { signal: AbortSignal.timeout(TRANSFER_DEADLINE_MS) });
+        if (!response.ok) {
+            writeLine(door.io.stderr, `${TAG} download refused ${JSON.stringify({ file_id: file.id, reason: `storage_http_${response.status}` })}`);
+            return failAgentDoor(door, TAG, "storage_unreachable", `Storage refused the download (HTTP ${response.status}).`);
+        }
+        bytes = Buffer.from(await response.arrayBuffer());
+    }
+    catch {
+        return failAgentDoor(door, TAG, "storage_unreachable", "Could not reach storage. Try again.");
+    }
+    const target = resolve(command.outPath ?? basename(file.name) ?? randomUUID());
+    try {
+        await writeFile(target, bytes, { flag: "wx" });
+    }
+    catch {
+        return failAgentDoor(door, TAG, "out_exists", "Tower will not overwrite or could not write that path. Pick another with --out.");
+    }
+    writeLine(door.io.stderr, `${TAG} downloaded ${JSON.stringify({ file_id: file.id, bytes: bytes.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, file, path: target, bytes: bytes.length });
+    writeLine(door.io.stdout, `Saved ${bytes.length} bytes to ${target}`);
+    return 0;
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Arguments of `cockpit msg save|saved|pin|pins|forward` (BLI-21774): `save <message-id> [--remove]`, `saved [--before <cursor>]
+ * [--limit <n>]`, `pin <message-id> [--remove]`, `pins <channel>`, `forward <message-id> --to <channel> [--thread <id>]
+ * [--request-id <uuid>]` (the comment is piped in). Split out of `local-args-tower-msg.ts`.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl } from "./local-arg-values.js";
+export const MSG_MARK_ACTIONS = ["save", "saved", "pin", "pins", "forward"];
+export const MSG_MARK_VALUE_FLAGS = ["--to"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isMsgMarkAction(action) {
+    return MSG_MARK_ACTIONS.includes(action);
+}
+/** `--to` used on another msg verb is named, not ignored. */
+export function rejectMsgMarkFlags(values) {
+    if (values.flags.has("--to"))
+        throw new Error("--to belongs to `cockpit msg forward`.");
+}
+export function parseMsgMarkArgs(action, values, rest) {
+    const stray = ["--channel", "--members", "--description", "--from", "--expected-revision", "--name", "--out", "--file", "--level", "--timezone", "--message"]
+        .find((flag) => values.flags.has(flag));
+    if (stray || values.booleans.has("--private"))
+        throw new Error(`${stray ?? "--private"} 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 remove = values.booleans.has("--remove");
+    const before = optionalNonEmpty(values.flags.get("--before"));
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    const thread = optionalNonEmpty(values.flags.get("--thread"));
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    const to = optionalNonEmpty(values.flags.get("--to"));
+    const mentioned = ["--mentions", "--threads", "--unread", "--mark-read"].find((flag) => values.booleans.has(flag));
+    if (mentioned)
+        throw new Error(`${mentioned} does not belong to \`cockpit msg ${action}\`.`);
+    if (remove && action !== "save" && action !== "pin")
+        throw new Error("--remove belongs to `cockpit msg save` and `cockpit msg pin`.");
+    if ((before || limit !== undefined) && action !== "saved")
+        throw new Error("--before and --limit belong to `cockpit msg saved`.");
+    if ((thread || requestId || to) && action !== "forward")
+        throw new Error("--to, --thread and --request-id belong to `cockpit msg forward`.");
+    if (action === "saved") {
+        if (rest.length > 0)
+            throw new Error(`msg saved does not take "${rest[0]}".`);
+        return { ...base, ...(before ? { before } : {}), ...(limit === undefined ? {} : { limit }) };
+    }
+    if (action === "pins") {
+        const channelRef = optionalNonEmpty(rest[0]);
+        if (!channelRef)
+            throw new Error("msg pins needs a channel id or name, e.g. `cockpit msg pins general`.");
+        if (rest.length > 1)
+            throw new Error(`msg pins takes one channel, not ${rest.length}.`);
+        return { ...base, channelRef };
+    }
+    const targetId = optionalNonEmpty(rest[0]);
+    if (!targetId || !UUID.test(targetId)) {
+        throw new Error(`msg ${action} needs a message id (a UUID), e.g. \`cockpit msg ${action} <message-id>\`.`);
+    }
+    if (rest.length > 1)
+        throw new Error(`msg ${action} takes one message id, not ${rest.length}.`);
+    if (action === "forward") {
+        if (!to)
+            throw new Error("msg forward needs --to <channel>, e.g. `echo \"worth a look\" | cockpit msg forward <message-id> --to general`.");
+        if (thread && !UUID.test(thread))
+            throw new Error("--thread takes a message id (a UUID).");
+        if (requestId && !UUID.test(requestId))
+            throw new Error("--request-id takes a UUID.");
+        return {
+            ...base, targetId, forwardTo: to,
+            ...(thread ? { threadId: thread } : {}), ...(requestId ? { requestId } : {}),
+        };
+    }
+    return { ...base, targetId, ...(remove ? { remove } : {}) };
+}

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