@bli-cockpit/cli 0.2.241 → 0.2.243

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

@@ -0,0 +1,67 @@
+/**
+ * Arguments of `cockpit msg context <message-id> [--add <kind:id>] [--remove <link-id>] [--json]` (BLI-21829).
+ * `--add doc:<id>|ticket:<BLI-id or uuid>|event:<id>[@<iso occurrence>]|note:<id>`; `--remove` takes the message id first and the
+ * link id after it. Split out of `local-args-tower-msg.ts`.
+ */
+import { optionalNonEmpty, optionalUrl } from "./local-arg-values.js";
+export const MSG_CONTEXT_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;
+const IDENTIFIER = /^[A-Za-z][A-Za-z0-9]{1,12}-\d+$/;
+const KINDS = ["doc", "ticket", "event", "note"];
+/** `--add` used on another msg verb is named, not ignored. */
+export function rejectMsgContextFlags(values) {
+    if (values.flags.has("--add"))
+        throw new Error("--add belongs to `cockpit msg context`.");
+}
+export function parseContextSpec(spec) {
+    const match = /^(doc|ticket|event|note):(.+)$/i.exec(spec.trim());
+    if (!match)
+        throw new Error("--add takes doc:<id>, ticket:<BLI-id or uuid>, event:<id>[@<iso occurrence>] or note:<id>.");
+    const kind = match[1].toLowerCase();
+    const [id = "", occurrence] = match[2].split("@", 2);
+    const ok = kind === "ticket" ? UUID.test(id) || IDENTIFIER.test(id) : UUID.test(id);
+    if (!ok)
+        throw new Error(`--add ${kind}: needs ${kind === "ticket" ? "a BLI id or a uuid" : "a uuid"}, not "${id}".`);
+    if (occurrence !== undefined) {
+        if (kind !== "event")
+            throw new Error("An @<iso occurrence> belongs to event: only.");
+        const time = Date.parse(occurrence);
+        if (Number.isNaN(time))
+            throw new Error(`--add event: the occurrence "${occurrence}" is not an ISO time.`);
+        return { kind, id, occurrence: new Date(time).toISOString() };
+    }
+    return { kind, id };
+}
+export function parseMsgContextArgs(values, rest) {
+    const stray = ["--channel", "--members", "--description", "--from", "--expected-revision", "--name", "--out", "--file", "--level", "--timezone", "--message", "--to", "--before", "--limit", "--thread", "--request-id"]
+        .find((flag) => values.flags.has(flag));
+    if (stray || values.booleans.has("--private"))
+        throw new Error(`${stray ?? "--private"} does not belong to \`cockpit msg context\`.`);
+    const targetId = optionalNonEmpty(rest[0]);
+    if (!targetId || !UUID.test(targetId)) {
+        throw new Error("msg context needs a message id (a UUID), e.g. `cockpit msg context <message-id> --json`.");
+    }
+    const add = optionalNonEmpty(values.flags.get("--add"));
+    const removing = values.booleans.has("--remove");
+    if (add && removing)
+        throw new Error("msg context takes --add or --remove, not both.");
+    const base = {
+        kind: "msg",
+        action: "context",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        isPrivate: false,
+        json: values.booleans.has("--json"),
+        targetId,
+    };
+    if (removing) {
+        const linkId = optionalNonEmpty(rest[1]);
+        if (!linkId || !UUID.test(linkId) || rest.length > 2) {
+            throw new Error("msg context --remove takes the message id and then the link id, e.g. `cockpit msg context <message-id> --remove <link-id>`.");
+        }
+        return { ...base, contextRemove: linkId };
+    }
+    if (rest.length > 1)
+        throw new Error(`msg context takes one message id, not ${rest.length}.`);
+    return { ...base, ...(add ? { contextAdd: parseContextSpec(add) } : {}) };
+}

package/dist/commands/msg-context.js

@@ -0,0 +1,65 @@
+/**
+ * `cockpit msg context` (BLI-21829): the Tower docs, tickets, calendar events and meeting notes pointed at from one message.
+ * Same doors the browser calls (`/api/msg/messages/<id>/context`, `.../context/<link-id>`); `--json` prints the door's body
+ * unchanged so link ids, kinds and `state: "unavailable"` match HTTP. Every target is read again for YOU: one you cannot open
+ * shows as "Not available to you" with no title. A refusal keeps the door's reason: context_target_unavailable,
+ * context_not_author, context_already_linked, context_limit_reached, context_link_not_found.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[msg cli]";
+const DEADLINE_MS = 30_000;
+function line(link) {
+    if (link.state === "unavailable")
+        return `${link.link_id}  ${link.kind}  Not available to you`;
+    const label = link.kind === "ticket" && link.identifier ? `${link.identifier} ${link.title ?? ""}`.trim() : (link.title ?? link.id);
+    return `${link.link_id}  ${link.kind}  ${label}${link.href ? `  ${link.href}` : ""}`;
+}
+export async function runMsgContext(command, door) {
+    const messageId = encodeURIComponent(command.targetId ?? "");
+    if (command.contextRemove) {
+        const answer = await askAgentDoor(door, {
+            path: `/api/msg/messages/${messageId}/context/${encodeURIComponent(command.contextRemove)}`,
+            method: "DELETE",
+            label: "msg context remove",
+            timeoutMs: DEADLINE_MS,
+        });
+        if (!answer.ok)
+            return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        writeLine(door.io.stderr, `${TAG} context removed ${JSON.stringify({ message_id: command.targetId, link_id: command.contextRemove })}`);
+        if (door.json)
+            return emitAgentDoor(door, { ok: true, ...answer.body });
+        writeLine(door.io.stdout, `Removed context ${command.contextRemove} from ${command.targetId}.`);
+        return 0;
+    }
+    if (command.contextAdd) {
+        const add = command.contextAdd;
+        const answer = await askAgentDoor(door, {
+            path: `/api/msg/messages/${messageId}/context`,
+            method: "POST",
+            body: { target_kind: add.kind, target_id: add.id, ...(add.occurrence ? { occurrence_start: add.occurrence } : {}) },
+            label: "msg context add",
+            timeoutMs: DEADLINE_MS,
+        });
+        if (!answer.ok)
+            return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        const link = answer.body.link;
+        writeLine(door.io.stderr, `${TAG} context added ${JSON.stringify({ message_id: command.targetId, kind: add.kind, link_id: link?.link_id ?? null })}`);
+        if (door.json)
+            return emitAgentDoor(door, { ok: true, ...answer.body });
+        writeLine(door.io.stdout, `Added ${add.kind} context to ${command.targetId}${link ? `:\n${line(link)}` : "."}`);
+        return 0;
+    }
+    const answer = await askAgentDoor(door, { path: `/api/msg/messages/${messageId}/context`, method: "GET", label: "msg context", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const links = answer.body.links ?? [];
+    writeLine(door.io.stderr, `${TAG} context ${JSON.stringify({ message_id: command.targetId, links: links.length, unavailable: links.filter((link) => link.state === "unavailable").length })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    for (const link of links)
+        writeLine(door.io.stdout, line(link));
+    if (links.length === 0)
+        writeLine(door.io.stdout, "No Tower context on this message.");
+    return 0;
+}

package/dist/commands/msg-dm.js

@@ -0,0 +1,28 @@
+/** `cockpit msg dm <email>`: lookup-or-create a direct message (BLI-3749). Split out of `msg.ts` for the file-size ratchet. */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[msg cli]";
+const WRITE_DEADLINE_MS = 30_000;
+export async function openDm(command, door) {
+    const emails = command.dmEmails ?? (command.dmEmail ? [command.dmEmail] : []);
+    const email = emails.join(", ");
+    if (emails.length === 0)
+        return failAgentDoor(door, TAG, "invalid_body", "msg dm needs an email address.");
+    const answer = await askAgentDoor(door, {
+        path: "/api/msg/channels",
+        method: "POST",
+        label: "msg dm",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { dm_participant_emails: emails },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const channel = answer.body.channel ?? null;
+    writeLine(door.io.stderr, `${TAG} dm resolved ${JSON.stringify({ channel_id: channel?.id ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, channel });
+    // Idempotent by contract (`get_or_create_dm`), so the wording says what is
+    // true either way rather than claiming a creation that may not have happened.
+    writeLine(door.io.stdout, `${emails.length > 1 ? "Group message" : "Direct message"} with ${email}: ${channel?.id ?? "?"}`);
+    return 0;
+}

package/dist/commands/msg-draft.js

@@ -0,0 +1,193 @@
+/**
+ * `cockpit msg draft` (BLI-21414): the text you have not sent yet, per channel and thread, the same
+ * drafts the browser autosaves. `list`, `show`, `save` (body piped in), `discard`, `restore` and
+ * `send` (posts the stored draft with a fresh request id, then prints the receipt). Same doors the
+ * browser calls: `/api/msg/drafts`, `/api/msg/drafts/restore` and the channel post door.
+ *
+ * The channel arrives already resolved to an id by `msg.ts`. Draft text is never logged; stderr lines
+ * carry ids, counts and reason labels.
+ */
+import { randomUUID } from "node:crypto";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { readContent, refuseMsgWrite } from "./msg-write.js";
+const TAG = "[msg draft cli]";
+const DEADLINE_MS = 30_000;
+function placeQuery(channelId, command) {
+    const query = new URLSearchParams({ channel_id: channelId });
+    if (command.threadId)
+        query.set("thread_parent_id", command.threadId);
+    return query.toString();
+}
+/** A refusal keeps the door's reason. A conflict names the stored revision; the stored text goes to --json only, never to a log line. */
+function refuseDraft(door, answer) {
+    const stored = answer.body?.draft ?? null;
+    writeLine(door.io.stderr, `${TAG} refused ${JSON.stringify({ reason: answer.reason, stored_revision: stored?.revision ?? null })}`);
+    if (door.json) {
+        writeLine(door.io.stdout, JSON.stringify({ ok: false, error: answer.reason, detail: answer.detail, draft: stored }));
+    }
+    else {
+        writeLine(door.io.stderr, answer.detail);
+        if (answer.reason === "draft_revision_conflict" && stored) {
+            writeLine(door.io.stderr, `The stored draft is at revision ${stored.revision}. Read it with \`cockpit msg draft show\`, then save again with --expected-revision ${stored.revision}.`);
+        }
+    }
+    return 1;
+}
+export async function runMsgDraft(command, door, channelId) {
+    switch (command.draftVerb ?? "list") {
+        case "list":
+            return listDrafts(door);
+        case "show":
+            return showDraft(command, door, channelId ?? "");
+        case "save":
+            return saveDraft(command, door, channelId ?? "");
+        case "discard":
+            return discardDraft(command, door, channelId ?? "");
+        case "restore":
+            return restoreDraft(command, door, channelId ?? "");
+        case "send":
+            return sendDraft(command, door, channelId ?? "");
+    }
+}
+async function listDrafts(door) {
+    const answer = await askAgentDoor(door, { path: "/api/msg/drafts", method: "GET", label: "msg draft list", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return refuseDraft(door, answer);
+    const body = answer.body;
+    const drafts = body.drafts ?? [];
+    writeLine(door.io.stderr, `${TAG} listed ${JSON.stringify({ returned: drafts.length, coverage: body.coverage ?? "unknown" })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, drafts, coverage: body.coverage, limit: body.limit, returned: body.returned ?? drafts.length });
+    if (drafts.length === 0) {
+        writeLine(door.io.stdout, "No unsent drafts.");
+        return 0;
+    }
+    for (const draft of drafts) {
+        writeLine(door.io.stdout, `${draft.channel_id}${draft.thread_parent_id ? ` thread ${draft.thread_parent_id}` : ""}  revision ${draft.revision}  ${draft.content.length} chars  ${draft.updated_at}`);
+    }
+    if (body.coverage === "capped")
+        writeLine(door.io.stdout, `Showing the newest ${body.limit ?? drafts.length}; there are more.`);
+    return 0;
+}
+async function showDraft(command, door, channelId) {
+    const answer = await askAgentDoor(door, { path: `/api/msg/drafts?${placeQuery(channelId, command)}`, method: "GET", label: "msg draft show", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return refuseDraft(door, answer);
+    const draft = answer.body.draft ?? null;
+    writeLine(door.io.stderr, `${TAG} shown ${JSON.stringify({ channel_id: channelId, found: draft !== null, state: draft?.state ?? "none", revision: draft?.revision ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, draft });
+    if (!draft) {
+        writeLine(door.io.stdout, "No draft here.");
+        return 0;
+    }
+    writeLine(door.io.stderr, `revision ${draft.revision}, ${draft.state}`);
+    writeLine(door.io.stdout, draft.content);
+    return 0;
+}
+async function saveDraft(command, door, channelId) {
+    const content = await readContent(door.io);
+    if (!content.ok)
+        return failAgentDoor(door, TAG, content.reason, content.detail);
+    if (content.text === "") {
+        return failAgentDoor(door, TAG, "invalid_body", "There was nothing to save. Use `cockpit msg draft discard` to drop a draft. Nothing was changed.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/msg/drafts",
+        method: "PUT",
+        label: "msg draft save",
+        timeoutMs: DEADLINE_MS,
+        body: {
+            channel_id: channelId,
+            thread_parent_id: command.threadId ?? null,
+            content: content.text,
+            ...(command.expectedRevision === undefined ? {} : { expected_revision: command.expectedRevision }),
+        },
+    });
+    if (!answer.ok)
+        return refuseDraft(door, answer);
+    const result = answer.body;
+    writeLine(door.io.stderr, `${TAG} saved ${JSON.stringify({ channel_id: channelId, outcome: result.outcome ?? null, revision: result.draft?.revision ?? null, chars: content.text.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...result });
+    writeLine(door.io.stdout, `Saved draft, revision ${result.draft?.revision ?? "?"}.`);
+    return 0;
+}
+async function discardDraft(command, door, channelId) {
+    const query = placeQuery(channelId, command) + (command.expectedRevision === undefined ? "" : `&expected_revision=${command.expectedRevision}`);
+    const answer = await askAgentDoor(door, { path: `/api/msg/drafts?${query}`, method: "DELETE", label: "msg draft discard", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return refuseDraft(door, answer);
+    const result = answer.body;
+    writeLine(door.io.stderr, `${TAG} discarded ${JSON.stringify({ channel_id: channelId, changed: result.changed ?? null, revision: result.draft?.revision ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...result });
+    writeLine(door.io.stdout, `Discarded the draft (revision ${result.draft?.revision ?? "?"}). Its text is kept; \`cockpit msg draft restore\` brings it back.`);
+    return 0;
+}
+async function restoreDraft(command, door, channelId) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/msg/drafts/restore",
+        method: "POST",
+        label: "msg draft restore",
+        timeoutMs: DEADLINE_MS,
+        body: {
+            channel_id: channelId,
+            thread_parent_id: command.threadId ?? null,
+            ...(command.expectedRevision === undefined ? {} : { expected_revision: command.expectedRevision }),
+        },
+    });
+    if (!answer.ok)
+        return refuseDraft(door, answer);
+    const result = answer.body;
+    writeLine(door.io.stderr, `${TAG} restored ${JSON.stringify({ channel_id: channelId, changed: result.changed ?? null, revision: result.draft?.revision ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...result });
+    writeLine(door.io.stdout, `Restored the draft, revision ${result.draft?.revision ?? "?"}.`);
+    return 0;
+}
+/** Posts the stored draft with a fresh request id and the draft's revision, then prints the receipt. */
+async function sendDraft(command, door, channelId) {
+    const read = await askAgentDoor(door, { path: `/api/msg/drafts?${placeQuery(channelId, command)}`, method: "GET", label: "msg draft send read", timeoutMs: DEADLINE_MS });
+    if (!read.ok)
+        return refuseDraft(door, read);
+    const draft = read.body.draft ?? null;
+    if (!draft || draft.state !== "active") {
+        return failAgentDoor(door, TAG, "draft_not_found", "There is no unsent draft here to send.", { state: draft?.state ?? "none" });
+    }
+    if (command.expectedRevision !== undefined && command.expectedRevision !== draft.revision) {
+        return refuseDraft(door, {
+            reason: "draft_revision_conflict",
+            detail: "This draft changed since you read it. Nothing was sent.",
+            body: { draft },
+        });
+    }
+    const requestId = command.requestId ?? randomUUID();
+    const answer = await askAgentDoor(door, {
+        path: `/api/msg/channels/${encodeURIComponent(channelId)}/messages`,
+        method: "POST",
+        label: "msg draft send",
+        timeoutMs: DEADLINE_MS,
+        body: {
+            content: draft.content,
+            request_id: requestId,
+            draft_revision: draft.revision,
+            ...(command.threadId ? { thread_parent_id: command.threadId } : {}),
+        },
+    });
+    if (!answer.ok)
+        return refuseMsgWrite(door, answer, requestId, "send");
+    const { message = null, mutation = null, draft: settled = null } = answer.body;
+    writeLine(door.io.stderr, `${TAG} sent ${JSON.stringify({
+        channel_id: channelId, message_id: message?.id ?? null, request_id: requestId, draft_revision: draft.revision,
+        draft_marked: settled?.marked ?? null, draft_reason: settled?.reason ?? null,
+    })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, message, mutation, draft: settled });
+    writeLine(door.io.stdout, `Sent the draft as ${message?.id ?? "?"} (request ${requestId}, ${String(mutation?.["outcome"] ?? "committed")}).`);
+    if (settled && settled.marked === false) {
+        writeLine(door.io.stdout, `The draft was not marked sent (${settled.reason ?? "unknown"}); it is still saved.`);
+    }
+    return 0;
+}

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