zele 0.3.17 → 0.3.20

package/dist/unsubscribe.js

@@ -0,0 +1,224 @@
+// Unsubscribe header parsing and mechanism planning.
+// Implements RFC 2369 (List-Unsubscribe) + RFC 8058 (List-Unsubscribe-Post
+// One-Click). Pure functions only — no network, no client access.
+//
+// RFC 2369 says List-Unsubscribe contains one or more angle-bracket-enclosed
+// URIs, comma-separated. Each URI is either mailto: (send an email) or
+// http(s): (a landing page).
+//
+// RFC 8058 adds one-click: when both List-Unsubscribe and
+// List-Unsubscribe-Post (with the single value "List-Unsubscribe=One-Click")
+// are present, a client can POST `List-Unsubscribe=One-Click` to the https
+// URL with no cookies, no auth, and no redirects allowed.
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+/**
+ * Split a List-Unsubscribe header into its `<URI>` entries. Commas only
+ * separate entries when they are outside angle brackets; whitespace and
+ * line folding inside the header are tolerated per RFC 2369 §2.
+ */
+export function parseListUnsubscribeEntries(header) {
+    if (!header)
+        return [];
+    const entries = [];
+    let depth = 0;
+    let current = '';
+    for (const ch of header) {
+        if (ch === '<') {
+            depth++;
+            current += ch;
+            continue;
+        }
+        if (ch === '>') {
+            depth = Math.max(0, depth - 1);
+            current += ch;
+            continue;
+        }
+        if (ch === ',' && depth === 0) {
+            entries.push(current);
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    if (current.trim().length > 0)
+        entries.push(current);
+    // Extract the URI inside each angle bracket pair. Anything outside is ignored
+    // (comments, trailing text) per RFC 2369 §2 guideline 2.
+    const result = [];
+    for (const raw of entries) {
+        const match = raw.match(/<([^>]*)>/);
+        if (!match)
+            continue;
+        const uri = match[1].replace(/\s+/g, '').trim();
+        if (uri.length > 0)
+            result.push(uri);
+    }
+    return result;
+}
+/**
+ * Parse a mailto: URI into its target address and optional subject/body/cc.
+ * Returns null if the URI is not a valid mailto.
+ *
+ * Supports percent-encoding per RFC 6068. Note: `mailto:` is NOT
+ * application/x-www-form-urlencoded, so `+` is preserved literally (this
+ * matters for plus-addressing like `foo+tag@example.com`).
+ */
+export function parseMailto(uri) {
+    if (!/^mailto:/i.test(uri))
+        return null;
+    const afterScheme = uri.slice('mailto:'.length);
+    const qIndex = afterScheme.indexOf('?');
+    const rawTo = qIndex === -1 ? afterScheme : afterScheme.slice(0, qIndex);
+    const query = qIndex === -1 ? '' : afterScheme.slice(qIndex + 1);
+    const decode = (s) => {
+        try {
+            // RFC 6068: only percent-decode. Do NOT rewrite `+` → space.
+            return decodeURIComponent(s);
+        }
+        catch {
+            return s;
+        }
+    };
+    // Strip CRLF (defense-in-depth against header injection through mailto
+    // fields that get passed to SMTP/mimetext). Only body is allowed to keep
+    // newlines because it becomes message content.
+    const sanitizeHeader = (s) => s.replace(/[\r\n]/g, '').trim();
+    const to = sanitizeHeader(decode(rawTo));
+    if (!to)
+        return null;
+    const spec = { to };
+    if (!query)
+        return spec;
+    const cc = [];
+    for (const pair of query.split('&')) {
+        if (!pair)
+            continue;
+        const eq = pair.indexOf('=');
+        const key = (eq === -1 ? pair : pair.slice(0, eq)).toLowerCase();
+        const value = eq === -1 ? '' : decode(pair.slice(eq + 1));
+        if (key === 'subject')
+            spec.subject = sanitizeHeader(value);
+        else if (key === 'body')
+            spec.body = value;
+        else if (key === 'cc') {
+            for (const addr of value.split(',')) {
+                const trimmed = sanitizeHeader(addr);
+                if (trimmed)
+                    cc.push(trimmed);
+            }
+        }
+    }
+    if (cc.length > 0)
+        spec.cc = cc;
+    return spec;
+}
+/**
+ * Parse a List-Unsubscribe-Post header value. Per RFC 8058 §5 the only legal
+ * value is exactly `List-Unsubscribe=One-Click`. Whitespace-tolerant.
+ */
+export function parseListUnsubscribePost(header) {
+    if (!header)
+        return false;
+    return header.replace(/\s+/g, '').toLowerCase() === 'list-unsubscribe=one-click';
+}
+/**
+ * Lightweight check for whether a message has any standardized unsubscribe
+ * mechanism advertised. Used by list views that want to surface a
+ * `can_unsubscribe` boolean without building a full plan. Returns true when
+ * List-Unsubscribe contains at least one valid mailto: or http(s): entry.
+ */
+export function hasUnsubscribeMechanism(listUnsubscribe) {
+    if (!listUnsubscribe)
+        return false;
+    const entries = parseListUnsubscribeEntries(listUnsubscribe);
+    return entries.some((e) => /^(mailto|https?):/i.test(e));
+}
+/**
+ * Check whether a message advertises RFC 8058 one-click unsubscribe: both
+ * List-Unsubscribe-Post=One-Click and at least one https: URL in
+ * List-Unsubscribe. Does not check DKIM — the executor is responsible for
+ * that gating at the point of actually POSTing.
+ */
+export function hasOneClickUnsubscribe(listUnsubscribe, listUnsubscribePost) {
+    if (!parseListUnsubscribePost(listUnsubscribePost ?? undefined))
+        return false;
+    if (!listUnsubscribe)
+        return false;
+    return parseListUnsubscribeEntries(listUnsubscribe).some((e) => /^https:/i.test(e));
+}
+// ---------------------------------------------------------------------------
+// Planning
+// ---------------------------------------------------------------------------
+/**
+ * Build an unsubscribe plan from the raw headers + DKIM authenticity flag.
+ *
+ * Preference order:
+ *   1. RFC 8058 one-click (List-Unsubscribe-Post present + https URL).
+ *      Emitted first because it is the spec-preferred programmatic path.
+ *   2. The remaining entries in sender-declared order (RFC 2369 §2 says
+ *      clients should prefer left-to-right order). Each http(s): entry
+ *      becomes a `url` mechanism, each mailto: entry becomes a `mailto`.
+ */
+export function planUnsubscribe({ listUnsubscribe, listUnsubscribePost, dkimAuthentic, }) {
+    const warnings = [];
+    const mechanisms = [];
+    const entries = listUnsubscribe ? parseListUnsubscribeEntries(listUnsubscribe) : [];
+    const postOneClick = parseListUnsubscribePost(listUnsubscribePost);
+    // First pass: RFC 8058 one-click extraction. Any https entries become
+    // one-click candidates if the Post header is present.
+    const oneClickUrls = new Set();
+    let hasOneClick = false;
+    if (postOneClick) {
+        const httpsEntries = entries.filter((e) => /^https:/i.test(e));
+        if (httpsEntries.length > 0) {
+            hasOneClick = true;
+            for (const url of httpsEntries) {
+                mechanisms.push({ kind: 'one-click', url });
+                oneClickUrls.add(url);
+            }
+        }
+        else if (entries.some((e) => /^http:/i.test(e))) {
+            warnings.push('List-Unsubscribe-Post is present but no https URL (only http); RFC 8058 requires https');
+        }
+        else {
+            warnings.push('List-Unsubscribe-Post is present but no http(s) URL to POST to');
+        }
+    }
+    // Second pass: legacy fallbacks in sender-declared order (RFC 2369 §2
+    // left-to-right preference). http(s) URLs already claimed by one-click
+    // are skipped so we don't emit duplicate mechanisms.
+    for (const uri of entries) {
+        if (/^mailto:/i.test(uri)) {
+            const mailto = parseMailto(uri);
+            if (mailto)
+                mechanisms.push({ kind: 'mailto', mailto });
+            continue;
+        }
+        if (/^https?:/i.test(uri)) {
+            if (oneClickUrls.has(uri))
+                continue;
+            mechanisms.push({ kind: 'url', url: uri });
+            continue;
+        }
+    }
+    // DKIM safety notes for one-click. RFC 8058 §4 says the message SHOULD have
+    // a valid DKIM signature covering both headers; we approximate with a
+    // DKIM=pass verdict from the receiving MTA.
+    if (hasOneClick) {
+        if (dkimAuthentic === false) {
+            warnings.push('DKIM did not pass; one-click may be spoofed by an attacker');
+        }
+        else if (dkimAuthentic === null) {
+            warnings.push('DKIM status unknown (no authentication info on this message)');
+        }
+    }
+    return {
+        mechanisms,
+        hasOneClick,
+        dkimAuthentic,
+        warnings,
+    };
+}
+//# sourceMappingURL=unsubscribe.js.map

package/dist/unsubscribe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsubscribe.js","sourceRoot":"","sources":["../src/unsubscribe.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zele",
-  "version": "0.3.17",
+  "version": "0.3.20",
   "description": "Email & Calendar CLI — Gmail, IMAP/SMTP, Google Calendar from your terminal",
   "type": "module",
   "main": "dist/cli.js",
@@ -35,7 +35,7 @@
     "email-reply-parser": "^2.3.5",
     "errore": "^0.11.0",
     "fkill": "^10.0.3",
-    "goke": "^6.1.3",
+    "goke": "^6.6.0",
     "google-auth-library": "^10.5.0",
     "imapflow": "^1.2.18",
     "js-yaml": "^4.1.1",

package/skills/zele/SKILL.md

@@ -1,141 +1,42 @@
 ---
 name: zele
 description: >
-  Control Gmail and Google Calendar via CLI. Read, search, send, reply, and forward
-  emails. Create, update, and delete calendar events. Manage drafts, labels, and attachments.
-  Supports multiple Google accounts and IMAP/SMTP accounts (Fastmail, Outlook, any provider).
-  Use this skill whenever the user asks to check email, send messages, schedule meetings,
-  or manage their calendar.
+  zele is a multi-account email and calendar CLI for Gmail, IMAP/SMTP
+  (Fastmail, Outlook, any provider), and Google Calendar. It reads,
+  searches, sends, replies, forwards, archives, stars, and trashes emails,
+  manages drafts, labels, attachments, and Gmail filters, and creates,
+  updates, and deletes calendar events with RSVP and free/busy support.
+  Output is YAML so commands can be piped through yq and xargs. ALWAYS
+  load this skill when the user asks to check email, read/send messages,
+  reply or forward, archive or trash threads, manage drafts or labels,
+  download attachments, schedule meetings, check their calendar, RSVP
+  to events, or when they run any `zele` command. Load it before writing
+  any code or shell commands that touch zele so you know the correct
+  subcommand structure, the Google vs IMAP feature matrix, the headless
+  login flow, and the agent-specific rules.
 ---
 
-# zele — Email & Calendar CLI
+# zele
 
-A multi-account email and calendar client supporting **Google OAuth** and **IMAP/SMTP** (Fastmail, Outlook, any provider). Output is YAML, pipe-friendly.
-
-## Setup
-
-```bash
-# install (requires bun)
-bun install -g zele
-
-# show connected accounts
-zele whoami
-
-# authenticate with Google (opens browser, supports multiple accounts)
-zele login
-
-# authenticate with IMAP/SMTP (non-interactive, designed for agents)
-zele login imap \
-  --email you@fastmail.com \
-  --imap-host imap.fastmail.com --imap-port 993 \
-  --smtp-host smtp.fastmail.com --smtp-port 465 \
-  --password "your-app-password"
-```
-
-**IMAP/SMTP login options:** `--imap-user` / `--smtp-user` if the login username differs from email. Omit `--smtp-host` for read-only (no sending). Use `--imap-password` / `--smtp-password` for separate credentials.
-
-**Remote/headless Google login:** `zele login` is interactive — it prints an authorization URL and waits for a redirect URL to be pasted back. In agent/headless environments, run it inside tmux so the process persists:
+Every time you use zele, you MUST fetch the latest README:
 
 ```bash
-# start login in a tmux session
-tmux new-session -d -s zele-login 'zele login'
-
-# read the authorization URL from tmux output
-tmux capture-pane -t zele-login -p
-
-# after the user completes consent in their browser, paste the redirect URL
-tmux send-keys -t zele-login 'http://localhost:...?code=...' Enter
-
-# verify login succeeded
-tmux capture-pane -t zele-login -p
-tmux kill-session -t zele-login
+curl -s https://raw.githubusercontent.com/remorses/zele/main/README.md # NEVER pipe to head/tail, read the full output
 ```
 
-## Important
-
-**Always run `zele --help` before using.** The help output is the source of truth for all commands, options, and syntax. Run `zele <command> --help` for subcommand details (e.g. `zele mail send --help`). NEVER use head to truncate the output. read it fully.
-
-Running `zele` with no subcommand launches a human-friendly TUI for browsing email. **Agents should not use the TUI** — always use the CLI subcommands (`zele mail list`, `zele cal events`, etc.) which output structured YAML.
-
-## Capabilities
-
-- **Mail:** list, search, read, send, reply, forward, star, archive, trash, watch for new emails (Google + IMAP)
-- **Drafts:** list, create, get, send, delete (Google + IMAP)
-- **Attachments:** list per thread, download (Google + IMAP)
-- **Labels:** list, create, delete, unread counts (Google only)
-- **Filters:** list server-side filters (Google only)
-- **Calendar:** list calendars, list/search events, create/update/delete events, RSVP, free/busy (Google only)
-- **Multi-account:** all commands support `--account <email>` to filter; list/search merge across all account types
-
-## Account discovery
-
-When the user asks to check emails **for a specific account** (e.g. "check my work email", "what's new on my personal Gmail?"), always run `zele whoami` first to list the connected accounts and find the exact email address to pass to `--account`. Never guess the email — use the output of `zele whoami` to pick the right one. The output also shows account type (`google` or `imap_smtp`) and capabilities.
+Then run the CLI help once — it already includes every subcommand, option, and flag:
 
 ```bash
-# list connected accounts
-zele whoami
-
-# then use the email from the output
-zele mail list --account user@work.com
+zele --help # NEVER pipe to head/tail, read the full output
 ```
 
-## Google-only features
-
-These commands only work with Google accounts. IMAP/SMTP accounts show a helpful error:
+The README and `zele --help` output are the source of truth for commands, options, flags, the Google vs IMAP feature matrix, search operators, and the headless login flow.
 
-- `zele label list/counts/create/delete` — IMAP uses folders, not labels
-- `zele mail label` — adding/removing labels
-- `zele mail filter list` — server-side Gmail filters
-- `zele cal *` — calendar requires Google OAuth
-- `zele profile` — shows limited info for IMAP (email only, no message counts)
+## Rules
 
-## IMAP search support
-
-IMAP accounts support a subset of Gmail query syntax, translated to IMAP SEARCH:
-
-`from:`, `to:`, `subject:`, `is:unread`, `is:starred`, `has:attachment`, `newer_than:Nd`, `older_than:Nm`, `after:YYYY/MM/DD`, `before:YYYY/MM/DD`
-
-Unsupported on IMAP: `cc:`, `-` (negate), `label:`, `in:`, `filename:`, `size:`/`larger:`/`smaller:`, `OR`, `{ }`.
-
-## Examples
-
-```bash
-# list inbox
-zele mail list
-
-# list only unread emails
-zele mail list --filter "is:unread"
-
-# list emails from last 7 days (works for both Google and IMAP)
-zele mail list --filter "newer_than:7d"
-
-# combine filter with folder
-zele mail list --filter "from:github" --folder sent
-
-# search mail
-zele mail search "from:github subject:review"
-
-# read a thread (thread IDs come from list/search output)
-zele mail read <threadId>
-
-# send an email with attachment
-zele mail send --to alice@example.com --subject "Report" --body "See attached" --attach report.pdf
-
-# reply all
-zele mail reply <threadId> --body "Thanks!" --all
-
-# watch inbox for new mail (polls every 15s)
-zele mail watch
-
-# add an IMAP account (non-interactive, for agents)
-zele login imap --email you@fastmail.com --imap-host imap.fastmail.com --smtp-host smtp.fastmail.com --password "app-pass"
-
-# today's calendar events (Google only)
-zele cal events --today --all
-
-# create a meeting with Google Meet (Google only)
-zele cal create --summary "Standup" --from tomorrow --to +30m --meet --attendees bob@example.com
-
-# list Gmail filters (Google only)
-zele mail filter list
-```
+1. **Never use the TUI.** Running `zele` with no subcommand launches a human-facing TUI. Agents must use the CLI subcommands (`zele mail list`, `zele cal events`, etc.) which output structured YAML.
+2. **Always run `zele whoami` first** when the user asks to operate on a specific account. Pick the exact email from the output and pass it with `--account`. Never guess account emails.
+3. **Never truncate `--help` or README output** with `head`, `tail`, `sed`, `awk`, or `less`. Critical rules are spread throughout. Read them in full.
+4. **Parse YAML output with `yq`**, not regex. Pipe IDs through `xargs` for bulk actions: `zele mail list --filter "is:unread" | yq '.[].id' | xargs zele mail archive`.
+5. **Google-only features** (labels, Gmail filters, `zele cal *`, full profile) fail on IMAP accounts with a clear error. Check `zele whoami` output for account type before using them.
+6. **Headless Google login** requires a tmux wrapper because `zele login` is interactive. See the README "Remote / headless login" section for the exact pattern.

package/src/api-utils.ts

@@ -126,6 +126,20 @@ export class UnsupportedError extends errore.createTaggedError({
   message: '$feature is not available for $accountType accounts. $hint',
 }) {}
 
+/** Returned when a thread has no List-Unsubscribe header (RFC 2369) so no
+ *  standardized unsubscribe mechanism is available. */
+export class UnsubscribeUnavailableError extends errore.createTaggedError({
+  name: 'UnsubscribeUnavailableError',
+  message: 'No List-Unsubscribe header on thread $threadId',
+}) {}
+
+/** Returned when the unsubscribe attempt itself failed (HTTP error, SMTP
+ *  send failure, redirect returned when RFC 8058 forbids it, etc.). */
+export class UnsubscribeFailedError extends errore.createTaggedError({
+  name: 'UnsubscribeFailedError',
+  message: 'Unsubscribe via $mechanism failed: $reason',
+}) {}
+
 /** Detect auth-like errors from underlying libraries (tsdav string errors, googleapis structured errors).
  *  Used inside clients to decide whether to return an AuthError.
  *  NOTE: String matching here is intentional — this is the boundary layer that converts

package/src/cli-types.ts

@@ -0,0 +1,8 @@
+// Shared goke type for the zele CLI, including the global options declared
+// on the root `goke('zele')` instance. Living in its own file avoids the
+// circular import that would arise from command modules importing from
+// `./cli.js` (which itself imports every command module).
+
+import type { Goke } from 'goke'
+
+export type ZeleCli = Goke<{ account?: string[] }>

package/src/cli.ts

@@ -9,6 +9,7 @@ import { goke } from 'goke'
 import { z } from 'zod'
 import React from 'react'
 import { listAccounts, login } from './auth.js'
+import type { ZeleCli } from './cli-types.js'
 import { registerAuthCommands } from './commands/auth-cmd.js'
 import { registerMailCommands } from './commands/mail.js'
 import { registerMailActionCommands } from './commands/mail-actions.js'
@@ -21,13 +22,7 @@ import { registerWatchCommands } from './commands/watch.js'
 import { registerFilterCommands } from './commands/filter.js'
 import { handleCommandError } from './output.js'
 
-const cli = goke('zele')
-
-// ---------------------------------------------------------------------------
-// Global options
-// ---------------------------------------------------------------------------
-
-cli.option(
+const cli: ZeleCli = goke('zele').option(
   '--account <account>',
   z.array(z.string()).describe('Filter by email account (repeatable)'),
 )

package/src/commands/attachment.ts

@@ -2,7 +2,7 @@
 // Lists attachments for a thread and downloads them to disk.
 // Skips re-download if file already exists with same size (like gogcli).
 
-import type { Goke } from 'goke'
+import type { ZeleCli } from '../cli-types.js'
 import { z } from 'zod'
 import fs from 'node:fs'
 import path from 'node:path'
@@ -10,7 +10,7 @@ import { getClient } from '../auth.js'
 import * as out from '../output.js'
 import { handleCommandError } from '../output.js'
 
-export function registerAttachmentCommands(cli: Goke) {
+export function registerAttachmentCommands(cli: ZeleCli) {
   // =========================================================================
   // attachment list
   // =========================================================================

package/src/commands/auth-cmd.ts

@@ -2,7 +2,7 @@
 // Manages authentication for zele (Google OAuth and IMAP/SMTP credentials).
 // Supports multiple accounts: login adds accounts, logout removes one.
 
-import type { Goke } from 'goke'
+import type { ZeleCli } from '../cli-types.js'
 import { z } from 'zod'
 import pc from 'picocolors'
 import { login, loginImap, logout, listAccounts, getAuthStatuses } from '../auth.js'
@@ -10,7 +10,7 @@ import { closePrisma } from '../db.js'
 import * as out from '../output.js'
 import { handleCommandError } from '../output.js'
 
-export function registerAuthCommands(cli: Goke) {
+export function registerAuthCommands(cli: ZeleCli) {
   cli
     .command('login', 'Authenticate with Google (opens browser) or show IMAP/SMTP login instructions')
     .action(async () => {

package/src/commands/calendar.ts

@@ -3,7 +3,7 @@
 // Cache is handled by the client — commands just call methods and use data.
 // Multi-account: list/events fetch all accounts concurrently and merge by start time.
 
-import type { Goke } from 'goke'
+import type { ZeleCli } from '../cli-types.js'
 import { z } from 'zod'
 import readline from 'node:readline'
 import { getCalendarClients, getCalendarClient } from '../auth.js'
@@ -17,7 +17,7 @@ import { resolveTimeRange, parseTimeExpression, parseDuration, isDateOnly } from
 // Register commands
 // ---------------------------------------------------------------------------
 
-export function registerCalendarCommands(cli: Goke) {
+export function registerCalendarCommands(cli: ZeleCli) {
   // =========================================================================
   // cal list
   // =========================================================================

package/src/commands/draft.ts

@@ -3,7 +3,7 @@
 // Cache invalidation is handled by the client (sendDraft invalidates threadLists).
 // Multi-account: list fetches all accounts concurrently and merges by date.
 
-import type { Goke } from 'goke'
+import type { ZeleCli } from '../cli-types.js'
 import { z } from 'zod'
 import fs from 'node:fs'
 import { getClients, getClient } from '../auth.js'
@@ -14,7 +14,7 @@ import * as out from '../output.js'
 import { handleCommandError } from '../output.js'
 import pc from 'picocolors'
 
-export function registerDraftCommands(cli: Goke) {
+export function registerDraftCommands(cli: ZeleCli) {
   // =========================================================================
   // draft list
   // =========================================================================
@@ -89,14 +89,17 @@ export function registerDraftCommands(cli: Goke) {
       const draft = await client.getDraft({ draftId })
       if (draft instanceof Error) handleCommandError(draft)
 
+      const fmtRecipients = (list: Array<{ name?: string; email: string }>) =>
+        list.map((r) => r.name && r.name !== r.email ? `${r.name} <${r.email}>` : r.email).join(', ')
+
       console.log(pc.bold(`Draft: ${draft.message.subject}`))
       console.log(pc.dim(`Draft ID: ${draft.id}`))
-      console.log(`To: ${draft.to.join(', ') || '(none)'}`)
+      console.log(`To: ${fmtRecipients(draft.to) || '(none)'}`)
       if (draft.cc.length > 0) {
-        console.log(`Cc: ${draft.cc.join(', ')}`)
+        console.log(`Cc: ${fmtRecipients(draft.cc)}`)
       }
       if (draft.bcc.length > 0) {
-        console.log(`Bcc: ${draft.bcc.join(', ')}`)
+        console.log(`Bcc: ${fmtRecipients(draft.bcc)}`)
       }
       console.log()
 
@@ -161,6 +164,58 @@ export function registerDraftCommands(cli: Goke) {
       out.success('Draft created')
     })
 
+  // =========================================================================
+  // draft update
+  // =========================================================================
+
+  cli
+    .command('draft update <draftId>', 'Update an existing draft')
+    .option('--to <to>', z.string().describe('New recipient email(s), comma-separated'))
+    .option('--subject <subject>', z.string().describe('New subject'))
+    .option('--body <body>', z.string().describe('New body text'))
+    .option('--body-file <bodyFile>', z.string().describe('Read new body from file (use - for stdin)'))
+    .option('--cc <cc>', z.string().describe('New CC recipients (comma-separated)'))
+    .option('--bcc <bcc>', z.string().describe('New BCC recipients (comma-separated)'))
+    .option('--from <from>', z.string().describe('Send-as alias email'))
+    .action(async (draftId, options) => {
+      const { client } = await getClient(options.account)
+
+      // Fetch existing draft to merge unchanged fields
+      const existing = await client.getDraft({ draftId })
+      if (existing instanceof Error) handleCommandError(existing)
+
+      let body = options.body
+      if (options.bodyFile) {
+        if (options.bodyFile === '-') {
+          const chunks: Buffer[] = []
+          for await (const chunk of process.stdin) {
+            chunks.push(chunk)
+          }
+          body = Buffer.concat(chunks).toString('utf-8')
+        } else {
+          body = fs.readFileSync(options.bodyFile, 'utf-8')
+        }
+      }
+
+      const parseEmails = (str: string) =>
+        str.split(',').map((e) => e.trim()).filter(Boolean).map((email) => ({ email }))
+
+      const result = await client.updateDraft({
+        draftId,
+        to: options.to ? parseEmails(options.to) : existing.to,
+        subject: options.subject ?? existing.message.subject,
+        body: body ?? existing.message.body,
+        cc: options.cc ? parseEmails(options.cc) : existing.cc,
+        bcc: options.bcc ? parseEmails(options.bcc) : existing.bcc,
+        threadId: existing.message.threadId || undefined,
+        fromEmail: options.from ?? existing.message.from.email,
+      })
+      if (result instanceof Error) handleCommandError(result)
+
+      out.printYaml(result)
+      out.success('Draft updated')
+    })
+
   // =========================================================================
   // draft send
   // =========================================================================

package/src/commands/filter.ts

@@ -1,14 +1,14 @@
 // Filter commands: list, create, delete Gmail filters.
 // Multi-account support via getClients/getClient like label.ts.
 
-import type { Goke } from 'goke'
+import type { ZeleCli } from '../cli-types.js'
 import { getClients } from '../auth.js'
 import { AuthError, UnsupportedError, isScopeError } from '../api-utils.js'
 import type { GmailClient } from '../gmail-client.js'
 import * as out from '../output.js'
 import { handleCommandError } from '../output.js'
 
-export function registerFilterCommands(cli: Goke) {
+export function registerFilterCommands(cli: ZeleCli) {
   // =========================================================================
   // filter list
   // =========================================================================