@bli-cockpit/cli 0.2.165 → 0.2.166

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

@@ -14,9 +14,14 @@
  *   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.
+ * - **The message body.** `cockpit mail send` and `cockpit mail draft` take it
+ *   from stdin or `--file`, the same discipline `cockpit issue comment` and
+ *   `cockpit docs update` keep.
+ *
+ * `draft` (BLI-12530) takes `send`'s flags exactly — `--account`, `--to`,
+ * `--cc`, `--subject`, `--reply-to`, `--file` — and is refused the same two
+ * ways when `--account` or `--to` is missing: which mailbox a message is saved
+ * in is as much the caller's to say as which one it goes out from.
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
 const MAIL_ACTIONS = new Set([
@@ -27,10 +32,13 @@ const MAIL_ACTIONS = new Set([
     "read",
     "search",
     "send",
+    "draft",
     "attachment",
     "sync",
     "sync-status",
 ]);
+/** The two verbs that put a message in a mailbox: one sends it, one saves it unsent. */
+const MAIL_ACTIONS_COMPOSING = new Set(["send", "draft"]);
 /** 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"]);
 /** `sync-status [<account id>]` — every mailbox, or one's. Ticket 10730. */
@@ -85,7 +93,7 @@ function readMailAction(values) {
     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, sync, or sync-status.`);
+        throw new Error(`Unknown mail command: ${first}. Try accounts, add-imap, detach, inbox, read, search, send, draft, attachment, sync, or sync-status.`);
     }
     return { action, rest: values.positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -127,11 +135,13 @@ function readImapAddress(action, values) {
 function readMailRecipients(action, values) {
     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 (MAIL_ACTIONS_COMPOSING.has(action) && to.length === 0) {
+        throw new Error(`mail ${action} 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.");
+    if (MAIL_ACTIONS_COMPOSING.has(action) && !optionalNonEmpty(values.flags.get("--account"))) {
+        throw new Error(action === "draft"
+            ? "mail draft needs --account <id>: with several mailboxes attached, which one the draft is saved in is yours to say. `cockpit mail accounts` lists them."
+            : "mail send needs --account <id>: with several mailboxes attached, which address this goes out from is yours to say. `cockpit mail accounts` lists them.");
     }
     return { to, cc };
 }

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

@@ -122,7 +122,7 @@ export const TOWER_COMMAND_HELP = [
     [
         "mail",
         [
-            "Usage: cockpit mail [accounts|add-imap|inbox|read <thread>|search \"<words>\"|send|attachment <id>|sync <account>|sync-status [<account>]|detach <account>] [flags]",
+            "Usage: cockpit mail [accounts|add-imap|inbox|read <thread>|search \"<words>\"|send|draft|attachment <id>|sync <account>|sync-status [<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.",
@@ -134,12 +134,13 @@ export const TOWER_COMMAND_HELP = [
             "read <thread> — one conversation with its bodies. Thread ids come from `cockpit mail inbox` or `cockpit mail search`, in either --json or plain text.",
             "search \"<words>\" [--account <id>] [--limit <n>] — full text over subject and body. Quotes and OR work the way they do in a search box. Every row (text or --json) carries the thread id.",
             "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.",
+            "draft --account <id> --to <a[,b]> [--cc <c>] --subject \"<s>\" [--reply-to <message id>] [--file <path>] — saves the message as a DRAFT in that mailbox for a person to read, edit and send themselves. NOTHING IS SENT and nobody is notified, so there is no confirmation step. Same flags and same body rule as send (--file or stdin). Only the mailbox's owner can draft into it. --reply-to threads the draft into that conversation the way send does; Gmail files it there only when the subject matches the original's, and the answer says whether it did. Gmail mailboxes only: an IMAP mailbox is refused as imap_drafts_unsupported. --json answers { ok, draft: { account_id, address, provider_draft_id, provider_thread_id, threaded } } (BLI-12530).",
             "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.",
             "sync-status [<account>] — every mailbox's health, or one's: last successful sync, the last pass's own reason, how many messages it carried, failures in the last 24h, and the lag between a message's own clock and when Tower stored it (ticket 10730).",
             "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. Shapes differ by verb: inbox/read answer { messages: [...] }, search answers { matches: [...] } — same MessageRow shape either name, always carrying thread_id.",
-            "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.",
+            "A refusal keeps Tower's own reason label — needs_rls_client, account_not_found_or_unreadable, account_not_active, account_not_yours, 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.",
         ],
     ],

package/dist/commands/local-help.js

@@ -124,7 +124,7 @@ export function localCommandHelp(command) {
         "  cockpit docs [list|tree|read <id|slug>|create --title <t>|update <id>|delete <id|slug>] [--parent <id>|root|--clear-parent] [--query <text> [--word]] [--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] [--size S|M|L] [--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 mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|draft --account <id> --to <a> --subject <s> [--reply-to <message id>]|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--dashboard-url <url>] [--json]",
         "  cockpit cal [today|week|next|find \"<words>\"|calendars|add-ical|create --calendar <id> --title <t> --at <iso> --until <iso>|share <id> --org-visible|--private|sync <id> [--full]|detach <id>] [--tz <zone>] [--offset <n>] [--hours <n>] [--from <d> --to <d>] [--calendar <id>] [--limit <n>] [--all] [--dashboard-url <url>] [--json]",
         "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
         "  cockpit github <pr|merge|retitle|rerun> <owner/repo> <n> [--claim <state>] [--method squash|merge|rebase] [--title \"<text>\"] [--run <id>] [--confirm <code>] [--dashboard-url <url>] [--json]",

package/dist/commands/mail-compose.js

@@ -0,0 +1,96 @@
+/**
+ * The compose half of `cockpit mail` (BLI-12530): `draft`, and the two things
+ * it shares with `send` — where a message body comes from, and the JSON both
+ * verbs post.
+ *
+ * `cockpit mail draft` saves a message as a DRAFT in one of your own mailboxes
+ * (`POST /api/mail/drafts`) so a person can read it, edit it and press send
+ * themselves. It is the verb for an agent that prepares mail on somebody's
+ * behalf: nothing is sent, nobody is notified, and so — unlike `send` — there
+ * is nothing to confirm.
+ *
+ * Kept beside `mail.ts` rather than in it because `mail.ts` sits at the edge of
+ * the readability ceiling, and because the two verbs genuinely share one shape:
+ * the request body is built once here, so a field added to `send` cannot be
+ * forgotten by `draft` (both doors accept exactly the same fields).
+ *
+ * THE BODY NEVER TOUCHES ARGV. It comes from `--file` or stdin, the discipline
+ * `send`, `issue comment` and `docs update` already keep — argv is world-
+ * readable on a shared machine and is captured by this product's own session
+ * harvester.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor, } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { readNoteFile } from "./notes-file.js";
+// One spelling per surface: the same tag `mail.ts` uses.
+const TAG = "[mail cli]";
+const WRITE_DEADLINE_MS = 60_000;
+const BODY_MAX_CHARS = 200_000;
+/** Body on stdin, never argv — `--file` is the safest way on Windows. */
+export async function readMailBody(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) };
+    }
+}
+/**
+ * The JSON that `send` and `draft` post. One shape on purpose: the two doors
+ * take the same fields, and a message that can be sent can be saved unsent.
+ */
+export function composedMessageBody(command, text) {
+    return {
+        account_id: command.accountId,
+        to: command.to.map((address) => ({ address })),
+        ...(command.cc.length > 0 ? { cc: command.cc.map((address) => ({ address })) } : {}),
+        subject: command.subjectLine ?? "",
+        text,
+        ...(command.replyTo ? { in_reply_to_message_id: command.replyTo } : {}),
+    };
+}
+/** `draft --account <id> --to <a[,b]> [--cc <c>] --subject "<s>" [--reply-to <message id>] [--file <path>]` */
+export async function runMailDraft(command, door) {
+    const body = await readMailBody(command, door);
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    if (body.text.trim() === "") {
+        return failAgentDoor(door, TAG, "body_required", 'A draft needs a body: `echo "Tuesday works for me." | cockpit mail draft --account <id> --to someone@example.com --subject "Re: lunch"`.');
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/mail/drafts",
+        method: "POST",
+        label: "mail draft",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: composedMessageBody(command, body.text),
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const draft = answer.body.draft;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, draft });
+    writeLine(door.io.stdout, `Saved a draft in ${draft?.address ?? "that mailbox"} for ${command.to.join(", ")}. `
+        + "Nothing was sent: it is in Drafts for a person to read, edit and send.");
+    if (command.replyTo) {
+        // `threaded` is what Gmail answered, not what was asked: a reply is only
+        // filed in its conversation when the subject still matches the original's.
+        writeLine(door.io.stdout, draft?.threaded
+            ? "It sits in the reply's conversation."
+            : "Gmail did not file it in that conversation, so it is a new one. A reply joins its thread only when the subject matches the original's.");
+    }
+    writeLine(door.io.stdout, `draft ${draft?.provider_draft_id ?? "(no id returned)"}  thread ${draft?.provider_thread_id ?? "(none)"}  account ${draft?.account_id ?? command.accountId}`);
+    return 0;
+}

package/dist/commands/mail.js

@@ -2,10 +2,12 @@
  * `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
+ * Ten 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.
+ * `draft` (BLI-12530) lives in `mail-compose.ts` beside the body reader it
+ * shares with `send`.
  *
  * 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
@@ -23,7 +25,7 @@
 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 { composedMessageBody, readMailBody, runMailDraft } from "./mail-compose.js";
 import { cacheAgeLabel, readThroughCache } from "./read-cache.js";
 import { towerRequest } from "../tower-client.js";
 const TAG = "[mail cli]";
@@ -31,7 +33,6 @@ 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);
@@ -50,6 +51,8 @@ export async function runMail(command, io) {
             return search(command, door);
         case "send":
             return send(command, door);
+        case "draft":
+            return runMailDraft(command, door);
         case "attachment":
             return attachment(command, door);
         case "sync":
@@ -250,7 +253,7 @@ async function search(command, door) {
     return 0;
 }
 async function send(command, door) {
-    const body = await readBody(command, door);
+    const body = await readMailBody(command, door);
     if (!body.ok)
         return failAgentDoor(door, TAG, body.reason, body.detail);
     if (body.text.trim() === "") {
@@ -261,14 +264,7 @@ async function send(command, door) {
         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 } : {}),
-        },
+        body: composedMessageBody(command, body.text),
     });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
@@ -361,26 +357,4 @@ async function syncStatus(command, door) {
         writeLine(door.io.stdout, `${account.address}  last_success=${account.last_success_at ?? "never"}  last_run=${lastRun}  failures_24h=${account.failures_24h}  lag=${lag}${account.data_incomplete ? "  (partial read)" : ""}`);
     }
     return 0;
-}
-/** 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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.165",
+  "version": "0.2.166",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.45",
-    "@bli-cockpit/mcp": "0.1.83",
+    "@bli-cockpit/mcp": "0.1.84",
     "@bli-cockpit/telemetry-core": "0.1.57"
   },
   "repository": {