zele 0.3.16 → 0.3.20

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zele",
-  "version": "0.3.16",
-  "description": "Gmail CLI — manage email from your terminal",
+  "version": "0.3.20",
+  "description": "Email & Calendar CLI — Gmail, IMAP/SMTP, Google Calendar from your terminal",
   "type": "module",
   "main": "dist/cli.js",
   "bin": "./dist/cli.js",
@@ -35,11 +35,13 @@
     "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",
     "mimetext": "^3.0.28",
     "mrmime": "^2.0.1",
+    "nodemailer": "^8.0.4",
     "picocolors": "^1.1.1",
     "react": "^19.2.4",
     "remark": "^15.0.1",
@@ -61,6 +63,7 @@
     "@types/email-addresses": "^3.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.2.0",
+    "@types/nodemailer": "^8.0.0",
     "@types/react": "^19.1.2",
     "@types/turndown": "^5.0.5",
     "prisma": "7.3.0",

package/schema.prisma

@@ -13,15 +13,17 @@ enum AccountStatus {
   disabled
 }
 
-// Stores one OAuth credential set per (email, appId) pair.
-// appId is the Google OAuth client ID used during login, enabling
-// multiple OAuth apps per email (different quotas, scopes, etc.).
-// Default is the Thunderbird client ID (the original/only client).
+// Stores one credential set per (email, appId) pair.
+// appId is the Google OAuth client ID for Google accounts, or 'imap_smtp' for IMAP/SMTP accounts.
+// accountType discriminates the credential format stored in tokens.
+// capabilities is a comma-separated list of features: "gmail,calendar,smtp" or "imap,smtp".
 model Account {
   email         String
   appId         String
+  accountType   String    @default("google")  // "google" | "imap_smtp"
+  capabilities  String    @default("")         // comma-separated: "gmail,calendar,smtp" or "imap,smtp" or "imap"
   accountStatus AccountStatus
-  tokens        String // JSON-encoded OAuth2 Credentials
+  tokens        String // JSON: OAuth2 Credentials (google) or ImapSmtpCredentials (imap_smtp)
   createdAt     DateTime
   updatedAt     DateTime @updatedAt
 

package/skills/zele/SKILL.md

@@ -1,112 +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. 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 — Gmail & Google Calendar CLI
+# zele
 
-A multi-account Gmail and Google Calendar client. Output is YAML, pipe-friendly.
-
-## Setup
+Every time you use zele, you MUST fetch the latest README:
 
 ```bash
-# install (requires bun)
-bun install -g zele
-
-# show connected accounts
-zele whoami
-
-# authenticate (opens browser, supports multiple accounts)
-zele login
+curl -s https://raw.githubusercontent.com/remorses/zele/main/README.md # NEVER pipe to head/tail, read the full output
 ```
 
-**Remote/headless 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:
-
-```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
-```
-
-## 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, label, watch for new emails, manage filters
-- **Drafts:** list, create, get, send, delete
-- **Calendar:** list calendars, list/search events, create/update/delete events, RSVP, free/busy
-- **Labels:** list, create, delete, unread counts
-- **Attachments:** list per thread, download
-- **Multi-account:** all commands support `--account <email>` to filter; list/search merge across accounts
-
-## 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.
+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
 ```
 
-## Examples
-
-```bash
-# list inbox
-zele mail list
-
-# list only unread emails
-zele mail list --filter "is:unread"
-
-# list unread emails with attachments in inbox
-zele mail list --filter "is:unread has:attachment"
-
-# combine filter with folder
-zele mail list --filter "from:github" --folder sent
-
-# search mail
-zele mail search "from:github subject:review"
+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.
 
-# read a thread (thread IDs come from list/search output)
-zele mail read <threadId>
+## Rules
 
-# 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
-
-# today's calendar events across all accounts
-zele cal events --today --all
-
-# create a meeting with Google Meet
-zele cal create --summary "Standup" --from tomorrow --to +30m --meet --attendees bob@example.com
-
-# check free/busy
-zele cal freebusy --from today --to +8h
-
-# list Gmail filters
-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

@@ -120,6 +120,26 @@ export class ApiError extends errore.createTaggedError({
   message: 'API call failed: $reason',
 }) {}
 
+/** Returned when a command requires a capability (e.g. gmail labels) that the account doesn't support. */
+export class UnsupportedError extends errore.createTaggedError({
+  name: 'UnsupportedError',
+  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/auth.ts

@@ -16,7 +16,51 @@ import { getPrisma } from './db.js'
 import { GmailClient } from './gmail-client.js'
 import { CalendarClient } from './calendar-client.js'
 import * as errore from 'errore'
-import { AuthError } from './api-utils.js'
+import { AuthError, ApiError, UnsupportedError } from './api-utils.js'
+import { ImapSmtpClient } from './imap-smtp-client.js'
+
+// ---------------------------------------------------------------------------
+// Account types
+// ---------------------------------------------------------------------------
+
+export type AccountType = 'google' | 'imap_smtp'
+
+export const IMAP_SMTP_APP_ID = 'imap_smtp' as const
+
+export interface ImapCredentials {
+  host: string
+  port: number
+  user: string
+  password: string
+  tls: boolean
+}
+
+export interface SmtpCredentials {
+  host: string
+  port: number
+  user: string
+  password: string
+  tls: boolean
+}
+
+/** Stored in the `tokens` column for imap_smtp accounts. */
+export interface ImapSmtpCredentials {
+  imap?: ImapCredentials
+  smtp?: SmtpCredentials
+}
+
+/** Capabilities an account can have. */
+export type AccountCapability = 'gmail' | 'calendar' | 'smtp' | 'imap'
+
+export function parseCapabilities(raw: string): AccountCapability[] {
+  if (!raw) return []
+  return raw.split(',').map((s) => s.trim()).filter(Boolean) as AccountCapability[]
+}
+
+export function hasCapability(capabilities: string | AccountCapability[], cap: AccountCapability): boolean {
+  const list = typeof capabilities === 'string' ? parseCapabilities(capabilities) : capabilities
+  return list.includes(cap)
+}
 
 // ---------------------------------------------------------------------------
 // Known open-source Google OAuth clients (Desktop app type).
@@ -123,6 +167,8 @@ export function createOAuth2Client(appId?: string): OAuth2Client {
 export interface AccountId {
   email: string
   appId: string
+  accountType: AccountType
+  capabilities: AccountCapability[]
 }
 
 // ---------------------------------------------------------------------------
@@ -530,6 +576,7 @@ export async function login(
 
   // Upsert account in DB
   const prisma = await getPrisma()
+  const googleCapabilities = 'gmail,calendar,smtp'
   const upsertResult = await errore.tryAsync({
     try: () =>
       prisma.account.upsert({
@@ -537,12 +584,14 @@ export async function login(
         create: {
           email,
           appId: resolved.clientId,
+          accountType: 'google',
+          capabilities: googleCapabilities,
           accountStatus: 'active',
           tokens: JSON.stringify(tokens),
           createdAt: new Date(),
           updatedAt: new Date(),
         },
-        update: { tokens: JSON.stringify(tokens), updatedAt: new Date() },
+        update: { tokens: JSON.stringify(tokens), capabilities: googleCapabilities, updatedAt: new Date() },
       }),
     catch: (err) => new Error(`Failed to save account ${email}`, { cause: err }),
   })
@@ -551,6 +600,143 @@ export async function login(
   return { email, appId: resolved.clientId, client }
 }
 
+// ---------------------------------------------------------------------------
+// Login: IMAP/SMTP credentials → save to DB
+// ---------------------------------------------------------------------------
+
+export interface LoginImapOptions {
+  email: string
+  imapHost: string
+  imapPort?: number
+  smtpHost?: string
+  smtpPort?: number
+  password?: string
+  imapUser?: string
+  imapPassword?: string
+  smtpUser?: string
+  smtpPassword?: string
+  tls?: boolean
+}
+
+/**
+ * Login with IMAP/SMTP credentials. Tests connections before saving.
+ * Returns an error value if validation or connection test fails.
+ */
+export async function loginImap(
+  options: LoginImapOptions,
+): Promise<{ email: string; appId: string } | Error> {
+  const {
+    email,
+    imapHost,
+    imapPort = 993,
+    smtpHost,
+    smtpPort = 465,
+    password,
+    imapUser,
+    imapPassword,
+    smtpUser,
+    smtpPassword,
+    tls = true,
+  } = options
+
+  const imapPass = imapPassword ?? password
+  if (!imapPass) {
+    return new Error('IMAP password is required (--password or --imap-password)')
+  }
+
+  const credentials: ImapSmtpCredentials = {
+    imap: {
+      host: imapHost,
+      port: imapPort,
+      user: imapUser ?? email,
+      password: imapPass,
+      tls,
+    },
+  }
+
+  // Test IMAP connection
+  const { ImapFlow } = await import('imapflow')
+  const testClient = new ImapFlow({
+    host: imapHost,
+    port: imapPort,
+    secure: tls,
+    auth: { user: imapUser ?? email, pass: imapPass },
+    logger: false,
+  })
+
+  const imapTest = await errore.tryAsync({
+    try: async () => {
+      await testClient.connect()
+      await testClient.logout()
+    },
+    catch: (err) => new AuthError({ email, reason: `IMAP connection failed: ${String(err)}` }),
+  })
+  if (imapTest instanceof Error) return imapTest
+
+  // Configure SMTP if provided
+  const capabilities: AccountCapability[] = ['imap']
+
+  if (smtpHost) {
+    const smtpPass = smtpPassword ?? password
+    if (!smtpPass) {
+      return new Error('SMTP password is required when --smtp-host is provided (--password or --smtp-password)')
+    }
+
+    credentials.smtp = {
+      host: smtpHost,
+      port: smtpPort,
+      user: smtpUser ?? email,
+      password: smtpPass,
+      tls: smtpPort === 465,
+    }
+
+    // Test SMTP connection
+    const nodemailer = await import('nodemailer')
+    const transporter = nodemailer.default.createTransport({
+      host: smtpHost,
+      port: smtpPort,
+      secure: smtpPort === 465,
+      auth: { user: smtpUser ?? email, pass: smtpPass },
+    })
+
+    const smtpTest = await errore.tryAsync({
+      try: () => transporter.verify(),
+      catch: (err) => new AuthError({ email, reason: `SMTP connection failed: ${String(err)}` }),
+    })
+    if (smtpTest instanceof Error) return smtpTest
+
+    capabilities.push('smtp')
+  }
+
+  // Save to DB
+  const prisma = await getPrisma()
+  const upsertResult = await errore.tryAsync({
+    try: () =>
+      prisma.account.upsert({
+        where: { email_appId: { email, appId: IMAP_SMTP_APP_ID } },
+        create: {
+          email,
+          appId: IMAP_SMTP_APP_ID,
+          accountType: 'imap_smtp',
+          capabilities: capabilities.join(','),
+          accountStatus: 'active',
+          tokens: JSON.stringify(credentials),
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        },
+        update: {
+          capabilities: capabilities.join(','),
+          tokens: JSON.stringify(credentials),
+          updatedAt: new Date(),
+        },
+      }),
+    catch: (err) => new Error(`Failed to save account ${email}`, { cause: err }),
+  })
+  if (upsertResult instanceof Error) return upsertResult
+
+  return { email, appId: IMAP_SMTP_APP_ID }
+}
+
 // ---------------------------------------------------------------------------
 // Logout: remove account from DB
 // ---------------------------------------------------------------------------
@@ -571,8 +757,13 @@ export async function logout(email: string): Promise<void | Error> {
 
 export async function listAccounts(): Promise<AccountId[]> {
   const prisma = await getPrisma()
-  const rows = await prisma.account.findMany({ select: { email: true, appId: true } })
-  return rows.map((r) => ({ email: r.email, appId: r.appId }))
+  const rows = await prisma.account.findMany({ select: { email: true, appId: true, accountType: true, capabilities: true } })
+  return rows.map((r) => ({
+    email: r.email,
+    appId: r.appId,
+    accountType: r.accountType as AccountType,
+    capabilities: parseCapabilities(r.capabilities),
+  }))
 }
 
 // ---------------------------------------------------------------------------
@@ -613,13 +804,23 @@ async function authenticateAccount(account: AccountId): Promise<OAuth2Client> {
   return oauth2Client
 }
 
+/** Entry returned by getClients — client is GmailClient for Google accounts, ImapSmtpClient for IMAP/SMTP. */
+export interface ClientEntry {
+  email: string
+  appId: string
+  accountType: AccountType
+  capabilities: AccountCapability[]
+  client: GmailClient | ImapSmtpClient
+}
+
 /**
- * Get authenticated GmailClient instances for all accounts (or filtered by email list).
+ * Get authenticated client instances for all accounts (or filtered by email list).
+ * Returns GmailClient for Google accounts and ImapSmtpClient for IMAP/SMTP accounts.
  * If no accounts are registered, throws with a helpful message.
  */
 export async function getClients(
   accounts?: string[],
-): Promise<Array<{ email: string; appId: string; client: GmailClient }>> {
+): Promise<ClientEntry[]> {
   const allAccounts = await listAccounts()
   if (allAccounts.length === 0) {
     throw new Error('No accounts registered. Run: zele login')
@@ -634,10 +835,33 @@ export async function getClients(
     throw new Error(`No matching accounts. Available: ${available}`)
   }
 
+  const prisma = await getPrisma()
   const results = await Promise.all(
-    filtered.map(async (account) => {
+    filtered.map(async (account): Promise<ClientEntry> => {
+      if (account.accountType === 'imap_smtp') {
+        const row = await prisma.account.findUnique({
+          where: { email_appId: { email: account.email, appId: account.appId } },
+        })
+        if (!row) throw new Error(`No account found for ${account.email}. Run: zele login`)
+        const credentials: ImapSmtpCredentials = JSON.parse(row.tokens)
+        return {
+          email: account.email,
+          appId: account.appId,
+          accountType: 'imap_smtp',
+          capabilities: account.capabilities,
+          client: new ImapSmtpClient({ credentials, account }),
+        }
+      }
+
+      // Google account
       const auth = await authenticateAccount(account)
-      return { email: account.email, appId: account.appId, client: new GmailClient({ auth, account }) }
+      return {
+        email: account.email,
+        appId: account.appId,
+        accountType: 'google',
+        capabilities: account.capabilities,
+        client: new GmailClient({ auth, account }),
+      }
     }),
   )
 
@@ -645,12 +869,12 @@ export async function getClients(
 }
 
 /**
- * Get a single authenticated GmailClient. Errors if multiple accounts exist
+ * Get a single authenticated client. Errors if multiple accounts exist
  * and no --account filter was provided.
  */
 export async function getClient(
   accounts?: string[],
-): Promise<{ email: string; appId: string; client: GmailClient }> {
+): Promise<ClientEntry> {
   const clients = await getClients(accounts)
   if (clients.length === 1) {
     return clients[0]!
@@ -662,12 +886,31 @@ export async function getClient(
   )
 }
 
+/**
+ * Get a single authenticated GmailClient. Errors if account is not a Google account.
+ * Use this for commands that require Gmail-specific features.
+ */
+export async function getGmailClient(
+  accounts?: string[],
+): Promise<{ email: string; appId: string; client: GmailClient }> {
+  const entry = await getClient(accounts)
+  if (entry.accountType !== 'google') {
+    throw new UnsupportedError({
+      feature: 'This command',
+      accountType: 'IMAP/SMTP',
+      hint: 'It requires a Google account.',
+    })
+  }
+  return { email: entry.email, appId: entry.appId, client: entry.client as GmailClient }
+}
+
 // ---------------------------------------------------------------------------
 // Calendar client helpers
 // ---------------------------------------------------------------------------
 
 /**
- * Get authenticated CalendarClient instances for all accounts (or filtered by email list).
+ * Get authenticated CalendarClient instances for Google accounts only.
+ * IMAP/SMTP accounts are silently skipped (calendar requires Google OAuth).
  */
 export async function getCalendarClients(
   accounts?: string[],
@@ -686,8 +929,18 @@ export async function getCalendarClients(
     throw new Error(`No matching accounts. Available: ${available}`)
   }
 
+  // Only Google accounts support calendar
+  const googleAccounts = filtered.filter((a) => a.accountType === 'google')
+  if (googleAccounts.length === 0) {
+    throw new UnsupportedError({
+      feature: 'Calendar',
+      accountType: 'IMAP/SMTP',
+      hint: 'Calendar requires a Google account.',
+    })
+  }
+
   const results = await Promise.all(
-    filtered.map(async (account) => {
+    googleAccounts.map(async (account) => {
       const auth = await authenticateAccount(account)
       const { token } = await auth.getAccessToken()
       if (!token) throw new Error(`Failed to get access token for ${account.email}`)
@@ -723,6 +976,8 @@ export async function getCalendarClient(
 export interface AuthStatus {
   email: string
   appId: string
+  accountType: AccountType
+  capabilities: AccountCapability[]
   expiresAt?: Date
 }
 
@@ -731,11 +986,24 @@ export async function getAuthStatuses(): Promise<AuthStatus[]> {
   const rows = await prisma.account.findMany()
 
   return rows.map((row) => {
-    const tokens: Credentials = JSON.parse(row.tokens)
+    const accountType = row.accountType as AccountType
+    const capabilities = parseCapabilities(row.capabilities)
+    if (accountType === 'google') {
+      const tokens: Credentials = JSON.parse(row.tokens)
+      return {
+        email: row.email,
+        appId: row.appId,
+        accountType,
+        capabilities,
+        expiresAt: tokens.expiry_date ? new Date(tokens.expiry_date) : undefined,
+      }
+    }
+    // IMAP/SMTP — no expiry
     return {
       email: row.email,
       appId: row.appId,
-      expiresAt: tokens.expiry_date ? new Date(tokens.expiry_date) : undefined,
+      accountType,
+      capabilities,
     }
   })
 }

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)'),
 )