@bli-cockpit/cli 0.2.62 → 0.2.63

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

@@ -0,0 +1,151 @@
+/**
+ * `cockpit mail` argument parsing (BLI-3708) — the mail surface's half of
+ * `local-args-tower.ts`, a sibling of `local-args-tower-work.ts` for the same
+ * reason that file is one: mail is its own noun with its own vocabulary (a
+ * mailbox, a thread, an attachment, a recipient), and folding it into another
+ * family's parser would stretch that family's doc comment past the truth.
+ *
+ * TWO SECRETS NEVER TRAVEL ON ARGV, and both are refused here rather than at
+ * the door:
+ *
+ * - **The app password.** `cockpit mail add-imap --address <a>` reads it from
+ *   STDIN, always. There is no `--password` flag to forget about: argv is
+ *   world-readable on a shared machine (`ps`), lands in shell history, and is
+ *   captured by this very product's own session harvester. That is the
+ *   sourcing-secrets verdict applied to the one credential this product
+ *   stores.
+ * - **The message body.** `cockpit mail send` takes it from stdin or
+ *   `--file`, the same discipline `cockpit issue comment` and `cockpit docs
+ *   update` keep.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+const MAIL_ACTIONS = new Set([
+    "accounts",
+    "add-imap",
+    "detach",
+    "inbox",
+    "read",
+    "search",
+    "send",
+    "attachment",
+    "sync",
+]);
+/** Every verb that names ONE thing first: a thread, an attachment, a mailbox. */
+const MAIL_ACTIONS_NEEDING_A_SUBJECT = new Set(["read", "attachment", "detach", "sync"]);
+export function parseMailArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--account",
+            "--address",
+            "--name",
+            "--limit",
+            "--before",
+            "--unread",
+            "--label",
+            "--to",
+            "--cc",
+            "--subject",
+            "--reply-to",
+            "--file",
+            "--body-stdin",
+            "--out",
+            "--json",
+        ],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--account",
+            "--address",
+            "--name",
+            "--limit",
+            "--before",
+            "--label",
+            "--to",
+            "--cc",
+            "--subject",
+            "--reply-to",
+            "--file",
+            "--out",
+        ],
+    });
+    const first = values.positionals[0];
+    const action = (first === undefined ? "inbox" : first);
+    if (!MAIL_ACTIONS.has(action)) {
+        throw new Error(`Unknown mail command: ${first}. Try accounts, add-imap, detach, inbox, read, search, send, attachment, or sync.`);
+    }
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    let subject;
+    let query;
+    if (MAIL_ACTIONS_NEEDING_A_SUBJECT.has(action)) {
+        subject = optionalNonEmpty(rest[0]);
+        if (!subject) {
+            throw new Error(action === "read"
+                ? "mail read needs a thread id — take one from `cockpit mail inbox --json`."
+                : `mail ${action} needs an id.`);
+        }
+        if (rest.length > 1)
+            throw new Error(`mail ${action} takes one id, not ${rest.length}.`);
+    }
+    else if (action === "search") {
+        query = optionalNonEmpty(rest.join(" "));
+        if (!query)
+            throw new Error('mail search needs words: cockpit mail search "invoice from stripe".');
+    }
+    else if (rest.length > 0) {
+        throw new Error(`mail ${action} does not take "${rest[0]}".`);
+    }
+    const address = optionalNonEmpty(values.flags.get("--address"));
+    if (action === "add-imap" && !address) {
+        throw new Error("mail add-imap needs --address, and reads the app password from stdin.");
+    }
+    const to = splitAddresses(values.flags.get("--to"));
+    const cc = splitAddresses(values.flags.get("--cc"));
+    if (action === "send" && to.length === 0) {
+        throw new Error('mail send needs --to "someone@example.com" (comma-separated for several).');
+    }
+    if (action === "send" && !optionalNonEmpty(values.flags.get("--account"))) {
+        throw new Error("mail send needs --account <id>: with several mailboxes attached, which address this goes out from is yours to say. `cockpit mail accounts` lists them.");
+    }
+    const outPath = optionalNonEmpty(values.flags.get("--out"));
+    if (action === "attachment" && !outPath) {
+        throw new Error("mail attachment needs --out <path>: the file is written to disk, never to stdout.");
+    }
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    if (limit !== undefined && action !== "inbox" && action !== "search") {
+        throw new Error("--limit belongs to `cockpit mail inbox` or `cockpit mail search`.");
+    }
+    return {
+        kind: "mail",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(subject ? { subjectId: subject } : {}),
+        ...(query ? { query } : {}),
+        accountId: optionalNonEmpty(values.flags.get("--account")),
+        address,
+        displayName: optionalNonEmpty(values.flags.get("--name")),
+        ...(limit === undefined ? {} : { limit }),
+        before: optionalNonEmpty(values.flags.get("--before")),
+        unreadOnly: values.booleans.has("--unread"),
+        label: optionalNonEmpty(values.flags.get("--label")),
+        to,
+        cc,
+        subjectLine: optionalNonEmpty(values.flags.get("--subject")),
+        replyTo: optionalNonEmpty(values.flags.get("--reply-to")),
+        filePath: optionalNonEmpty(values.flags.get("--file")),
+        bodyStdin: values.booleans.has("--body-stdin"),
+        outPath,
+        json: values.booleans.has("--json"),
+    };
+}
+/** `a@x.com, b@y.com` → two recipients. Exact, never fuzzy; empties dropped. */
+function splitAddresses(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter((value) => value !== "");
+}

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

@@ -20,6 +20,7 @@
  *                                                      channels/messages (BLI-3706)
  *   local-args-tower-work.ts    issue, project     — the issue tracker
  *                                                      (BLI-3716)
+ *   local-args-tower-mail.ts    mail               — the mailboxes (BLI-3708)
  *   local-args-tower-search.ts   search            — one bar over all five
  *                                                      corpora (BLI-3728)
  *
@@ -30,4 +31,5 @@ export { parseBriefArgs, WORKBOOK_MIN_WIDTH, parseWorkbookArgs, parseNotesArgs,
 export { SCOUT_MIN_PREFIX_LENGTH, parseScoutArgs, parseOpsArgs, SLACK_WORKSPACE_KEYS, parseSlackArgs, parseSettingsArgs, parseTeamArgs, parseModelArgs, } from "./local-args-tower-admin.js";
 export { parseDocsArgs, parseMsgArgs, } from "./local-args-tower-docs-msg.js";
 export { ISSUE_STATES, parseIssueArgs, parseProjectArgs, } from "./local-args-tower-work.js";
-export { SEARCH_KINDS, parseSearchArgs } from "./local-args-tower-search.js";
+export { SEARCH_KINDS, parseSearchArgs } from "./local-args-tower-search.js";
+export { parseMailArgs } from "./local-args-tower-mail.js";

package/dist/commands/local-args.js

@@ -16,7 +16,7 @@
  * verbatim, no logic change.
  */
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
 // even though it now lives next door. The same goes for the four names the
@@ -103,6 +103,8 @@ export function parseLocalArgs(argv) {
             return parseMsgArgs(argv.slice(1));
         case "issue":
             return parseIssueArgs(argv.slice(1));
+        case "mail":
+            return parseMailArgs(argv.slice(1));
         case "project":
             return parseProjectArgs(argv.slice(1));
         case "search":

package/dist/commands/local-help-commands.js

@@ -596,6 +596,29 @@ export function localSubcommandHelp(command) {
                 "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
             ],
         ],
+        [
+            "mail",
+            [
+                "Usage: cockpit mail [accounts|add-imap|inbox|read <thread>|search \"<words>\"|send|attachment <id>|sync <account>|detach <account>] [flags]",
+                "",
+                "Every mailbox you attached, in one place. One person, several addresses — nothing here has a \"current\" mailbox.",
+                "accounts — every mailbox, its provider (gmail_oauth or imap), its health and when it last synced. The ids other verbs take are on the last line.",
+                "add-imap --address <you@gmail.com> [--name \"<display name>\"] — attaches a personal Google account over IMAP + SMTP. The APP PASSWORD is read from stdin and there is no flag for it:",
+                "      macOS:      printf \"%s\" \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
+                "      PowerShell: \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
+                "      Make one at myaccount.google.com/apppasswords (2-Step Verification has to be on). A work @buildlaunchiterate.ca address connects in the browser instead.",
+                "inbox [--account <id>] [--unread] [--label <l>] [--limit <n>] [--before <iso>] — everything across every mailbox, newest first. * is unread, @ has an attachment.",
+                "read <thread> — one conversation with its bodies. Thread ids come from `cockpit mail inbox --json`.",
+                "search \"<words>\" [--account <id>] [--limit <n>] — full text over subject and body. Quotes and OR work the way they do in a search box.",
+                "send --account <id> --to <a[,b]> [--cc <c>] --subject \"<s>\" [--reply-to <message id>] [--file <path>] — the BODY comes from --file or stdin. --account is required: which address this goes out from is yours to say.",
+                "attachment <id> --out <path> — downloads one attachment to a file. Attachments are pointers until you ask; nothing is stored in Tower.",
+                "sync <account> — reads that mailbox now instead of waiting for the cron. Prints what landed, or the reason it did not.",
+                "detach <account> — removes the mailbox, its stored mail and its credential.",
+                "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+                "A refusal keeps Tower's own reason label — needs_rls_client, account_not_found_or_unreadable, account_not_active, google_oauth_not_configured, credential_unavailable, and so on.",
+                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+            ],
+        ],
         [
             "project",
             [

package/dist/commands/local-help.js

@@ -45,6 +45,7 @@ export const rootCommandNames = new Set([
     "docs",
     "msg",
     "issue",
+    "mail",
     "project",
     "search",
     "release",
@@ -89,6 +90,7 @@ export function localCommandHelp(command) {
         "  cockpit docs [list|tree|read <id|slug>|create --title <t>|update <id>] [--parent <id>|root|--clear-parent] [--query <text>] [--limit <n>] [--visibility org|private] [--file <path>|--body-stdin] [--allow-empty] [--dashboard-url <url>] [--json]",
         "  cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>] [--private] [--members a@x,b@y] [--description <text>] [--thread <id>] [--limit <n>] [--dashboard-url <url>] [--json]",
         "  cockpit issue [list|show <BLI-id>|create --title <t>|update <BLI-id>|move <BLI-id> <state>|comment <BLI-id>|history <BLI-id>] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] [--priority 0-4] [--parent <BLI-id>] [--file <path>|--body-stdin] [--dashboard-url <url>] [--json]",
+        "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--dashboard-url <url>] [--json]",
         "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
         "  cockpit search \"<words>\" [--kind doc,msg,issue,note,memory] [--limit <n>] [--dashboard-url <url>] [--json]",
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",

package/dist/commands/local.js

@@ -35,6 +35,7 @@ import { runClean } from "./clean.js";
 import { runDocs } from "./docs.js";
 import { runMsg } from "./msg.js";
 import { runIssue } from "./issue.js";
+import { runMail } from "./mail.js";
 import { runProject } from "./project.js";
 import { runSearch } from "./search.js";
 import { parseLocalArgs } from "./local-args.js";
@@ -142,6 +143,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runMsg(command, io);
             case "issue":
                 return await runIssue(command, io);
+            case "mail":
+                return await runMail(command, io);
             case "project":
                 return await runProject(command, io);
             case "search":

package/dist/commands/mail.js

@@ -0,0 +1,337 @@
+/**
+ * `cockpit mail` — the mailboxes a person attached, from a terminal
+ * (BLI-3708).
+ *
+ * Nine verbs over `/api/mail/**`, the same doors the browser will use when the
+ * UI lands. Every one of those routes already accepts the collector device
+ * token (`resolveCaller({ allowDeviceToken: true })`), so this command is a
+ * terminal in front of an existing door and adds no authority of its own.
+ *
+ * The CLI is the FIRST surface for this wave, deliberately (AGENTS.md, "CLI is
+ * king"): a mailbox is easier to reason about as `--json` than as a rendered
+ * list, and every bug fixed here is fixed for the browser and MCP halves that
+ * share the same doors.
+ *
+ * TWO SECRETS NEVER TOUCH ARGV. `add-imap` reads the Google app password from
+ * STDIN and there is no flag that would take it; `send` reads the body from
+ * stdin or `--file`. `local-args-tower-mail.ts` says why in full.
+ *
+ * ONE MORE RULE, for the attachment verb: bytes go to a FILE, never to stdout.
+ * `--out` is required. A terminal that prints a PDF is a terminal somebody has
+ * to close, and `--json` output on stdout is a contract other tools parse.
+ */
+import { writeFile } from "node:fs/promises";
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { readNoteFile } from "./notes-file.js";
+import { towerRequest } from "../tower-client.js";
+const TAG = "[mail cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 60_000;
+/** A sync pass reads a bounded page, but a cold mailbox can still take a while. */
+const SYNC_DEADLINE_MS = 120_000;
+const BODY_MAX_CHARS = 200_000;
+const PASSWORD_MAX_CHARS = 200;
+export async function runMail(command, io) {
+    const door = await openAgentDoor("mail", command, io);
+    switch (command.action) {
+        case "accounts":
+            return listAccounts(door);
+        case "add-imap":
+            return addImap(command, door);
+        case "detach":
+            return detach(command, door);
+        case "inbox":
+            return inbox(command, door);
+        case "read":
+            return readThread(command, door);
+        case "search":
+            return search(command, door);
+        case "send":
+            return send(command, door);
+        case "attachment":
+            return attachment(command, door);
+        case "sync":
+            return sync(command, door);
+    }
+}
+async function listAccounts(door) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/mail/accounts",
+        method: "GET",
+        label: "mail accounts",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const accounts = answer.body.accounts ?? [];
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, accounts });
+    if (accounts.length === 0) {
+        writeLine(door.io.stdout, "No mailboxes attached yet.");
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, "A personal address:  cockpit mail add-imap --address you@gmail.com   (app password on stdin)");
+        writeLine(door.io.stdout, "A work address:      open Tower in a browser and connect Google.");
+        return 0;
+    }
+    for (const account of accounts) {
+        const health = account.status === "active" ? account.backfill_state : `${account.status}: ${account.status_reason ?? "no reason recorded"}`;
+        writeLine(door.io.stdout, `${account.address.padEnd(34)}  ${account.provider.padEnd(12)}  ${health.padEnd(18)}  ${account.last_sync_at ?? "never synced"}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${accounts.length} mailbox(es). ids: ${accounts.map((account) => account.id).join(", ")}`);
+    return 0;
+}
+async function addImap(command, door) {
+    // The password comes from stdin and nowhere else. An interactive terminal
+    // with nothing piped in is told how, rather than left waiting on a prompt
+    // that would echo the secret into the scrollback.
+    if (isInteractiveStdin(door.io)) {
+        return failAgentDoor(door, TAG, "password_required_on_stdin", 'The app password is read from stdin, never from a flag. Try: printf "%s" "abcd efgh ijkl mnop" | cockpit mail add-imap --address you@gmail.com');
+    }
+    let appPassword;
+    try {
+        appPassword = (await readPipedText(door.io.stdin, {
+            maxChars: PASSWORD_MAX_CHARS,
+            overflowMessage: "That does not look like a Google app password (they are 16 characters).",
+        })).trim();
+    }
+    catch (error) {
+        return failAgentDoor(door, TAG, "password_unreadable", error instanceof Error ? error.message : String(error));
+    }
+    if (appPassword === "") {
+        return failAgentDoor(door, TAG, "password_required_on_stdin", "Nothing arrived on stdin, so nothing was attached.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/mail/accounts",
+        method: "POST",
+        label: "mail add-imap",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            address: command.address,
+            display_name: command.displayName ?? null,
+            app_password: appPassword,
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const account = answer.body.account;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, account });
+    writeLine(door.io.stdout, `Attached ${account?.address ?? command.address} (${account?.id ?? "no id returned"}).`);
+    writeLine(door.io.stdout, "Nothing is read until a sync runs: `cockpit mail sync <id>`, or wait for the cron.");
+    return 0;
+}
+async function detach(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/mail/accounts?account_id=${encodeURIComponent(command.subjectId ?? "")}`,
+        method: "DELETE",
+        label: "mail detach",
+        timeoutMs: WRITE_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, detached: command.subjectId });
+    writeLine(door.io.stdout, `Detached ${command.subjectId}. Its stored mail and its credential went with it.`);
+    return 0;
+}
+async function inbox(command, door) {
+    const query = new URLSearchParams();
+    if (command.accountId)
+        query.set("account_id", command.accountId);
+    if (command.limit !== undefined)
+        query.set("limit", String(command.limit));
+    if (command.before)
+        query.set("before", command.before);
+    if (command.unreadOnly)
+        query.set("unread", "1");
+    if (command.label)
+        query.set("label", command.label);
+    const suffix = query.toString();
+    const answer = await askAgentDoor(door, {
+        path: `/api/mail/inbox${suffix ? `?${suffix}` : ""}`,
+        method: "GET",
+        label: "mail inbox",
+        timeoutMs: READ_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 });
+    const messages = body.messages ?? [];
+    if (messages.length === 0) {
+        writeLine(door.io.stdout, (body.accounts ?? []).length === 0 ? "No mailboxes attached yet." : "No mail matches that.");
+        return 0;
+    }
+    for (const message of messages) {
+        writeLine(door.io.stdout, messageLine(message));
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${messages.length} message(s) across ${(body.accounts ?? []).length} mailbox(es).`);
+    return 0;
+}
+function messageLine(message) {
+    const flag = message.is_unread ? "*" : " ";
+    const paperclip = message.has_attachments ? "@" : " ";
+    const from = message.from_address?.address ?? "(no sender)";
+    const day = message.internal_date.slice(0, 16).replace("T", " ");
+    return `${flag}${paperclip} ${day}  ${from.padEnd(30).slice(0, 30)}  ${(message.subject ?? "(no subject)").slice(0, 60)}`;
+}
+async function readThread(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/mail/threads/${encodeURIComponent(command.subjectId ?? "")}`,
+        method: "GET",
+        label: "mail read",
+        timeoutMs: READ_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 });
+    writeLine(door.io.stdout, body.thread?.subject ?? "(no subject)");
+    writeLine(door.io.stdout, `${body.thread?.account_address ?? "?"} — ${body.messages?.length ?? 0} message(s)`);
+    for (const message of body.messages ?? []) {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, `--- ${message.internal_date} ${message.from_address?.address ?? "(no sender)"} [${message.id}]`);
+        writeLine(door.io.stdout, (message.body_text ?? message.snippet ?? "(no text body — this message is HTML only)").trim());
+    }
+    return 0;
+}
+async function search(command, door) {
+    const query = new URLSearchParams({ q: command.query ?? "" });
+    if (command.accountId)
+        query.set("account_id", command.accountId);
+    if (command.limit !== undefined)
+        query.set("limit", String(command.limit));
+    const answer = await askAgentDoor(door, {
+        path: `/api/mail/search?${query.toString()}`,
+        method: "GET",
+        label: "mail search",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const matches = answer.body.matches ?? [];
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, query: command.query, matches });
+    if (matches.length === 0) {
+        writeLine(door.io.stdout, `Nothing in your mail matched "${command.query}".`);
+        return 0;
+    }
+    for (const message of matches)
+        writeLine(door.io.stdout, messageLine(message));
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${matches.length} match(es).`);
+    return 0;
+}
+async function send(command, door) {
+    const body = await readBody(command, door);
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    if (body.text.trim() === "") {
+        return failAgentDoor(door, TAG, "body_required", 'A message needs a body: `echo "on my way" | cockpit mail send --account <id> --to someone@example.com --subject "Re: lunch"`.');
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/mail/send",
+        method: "POST",
+        label: "mail send",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            account_id: command.accountId,
+            to: command.to.map((address) => ({ address })),
+            ...(command.cc.length > 0 ? { cc: command.cc.map((address) => ({ address })) } : {}),
+            subject: command.subjectLine ?? "",
+            text: body.text,
+            ...(command.replyTo ? { in_reply_to_message_id: command.replyTo } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const sent = answer.body.sent;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, sent });
+    writeLine(door.io.stdout, `Sent from ${sent?.address ?? "that mailbox"} to ${command.to.join(", ")}${sent?.threaded ? " (as a reply)" : ""}.`);
+    return 0;
+}
+async function attachment(command, door) {
+    const outPath = command.outPath;
+    // The bytes do not go through `askAgentDoor` — it parses JSON, and this
+    // response is a file. Same door, same token, raw response.
+    const result = await towerRequest({
+        dashboardUrl: door.dashboardUrl,
+        path: `/api/mail/attachments/${encodeURIComponent(command.subjectId ?? "")}`,
+        deviceToken: door.deviceToken,
+        fetch: door.io.fetch,
+        method: "GET",
+        label: "mail attachment",
+        timeoutMs: WRITE_DEADLINE_MS,
+        log: (line) => writeLine(door.io.stderr, line),
+    });
+    if (!result.ok) {
+        return failAgentDoor(door, TAG, result.reason, result.detail);
+    }
+    if (!result.response.ok) {
+        return failAgentDoor(door, TAG, `http_${result.response.status}`, `Tower answered ${result.response.status} for that attachment. Nothing was written to ${outPath}.`);
+    }
+    const bytes = Buffer.from(await result.response.arrayBuffer());
+    try {
+        await writeFile(outPath, bytes);
+    }
+    catch (error) {
+        return failAgentDoor(door, TAG, "write_failed", `Downloaded ${bytes.length} bytes and could not write them to ${outPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, path: outPath, bytes: bytes.length });
+    writeLine(door.io.stdout, `Wrote ${bytes.length} bytes to ${outPath}.`);
+    return 0;
+}
+async function sync(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/mail/accounts/${encodeURIComponent(command.subjectId ?? "")}/sync`,
+        method: "POST",
+        label: "mail sync",
+        timeoutMs: SYNC_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const run = answer.body.run;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, run });
+    if (!run) {
+        writeLine(door.io.stdout, "Tower answered without a run. Nothing to report.");
+        return 0;
+    }
+    if (run.reason === "ok") {
+        writeLine(door.io.stdout, `Synced: ${run.messagesAdded} new, ${run.messagesUpdated} updated, ${run.messagesDeleted} gone.`);
+        return 0;
+    }
+    // A failure names itself; the exit code says it failed.
+    writeLine(door.io.stderr, `${TAG} sync ${JSON.stringify({ reason: run.reason, detail: run.detail })}`);
+    writeLine(door.io.stdout, `That mailbox did not sync: ${run.reason}${run.detail ? ` (${run.detail})` : ""}.`);
+    return 1;
+}
+/** Body on stdin, never argv — `--file` is the safest way on Windows. */
+async function readBody(command, door) {
+    if (command.filePath) {
+        const read = await readNoteFile(command.filePath);
+        if (!read.ok) {
+            return { ok: false, reason: read.refusal, detail: `Could not read ${command.filePath}: ${read.detail}` };
+        }
+        return { ok: true, text: read.bytes.toString("utf8") };
+    }
+    if (isInteractiveStdin(door.io))
+        return { ok: true, text: "" };
+    try {
+        const text = await readPipedText(door.io.stdin, {
+            maxChars: BODY_MAX_CHARS,
+            overflowMessage: `A message body is limited to ${BODY_MAX_CHARS} characters here.`,
+        });
+        return { ok: true, text };
+    }
+    catch (error) {
+        return { ok: false, reason: "body_too_long", detail: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.62");
+    writeLine(io?.stdout ?? process.stdout, "0.2.63");
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.62",
+  "version": "0.2.63",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.8",
-    "@bli-cockpit/mcp": "0.1.5",
+    "@bli-cockpit/mcp": "0.1.6",
     "@bli-cockpit/telemetry-core": "0.1.29"
   }
 }