himalaya/ROADMAP.md

# Himalaya CLI v2 — roadmap

Living document. Items are grouped by readiness and ordered roughly by
easiest-first within each group. Decisions land inline as `Decided:`
notes; open questions stay in section E until resolved.

## A. Shared API — already adequate

| Command | Status |
|---|---|
| `mailboxes list` | done |
| `envelopes list` | done (pagination: `--page` / `--page-size`, default size 25) |
| `flags add/set/delete` | done |
| `messages get` | done (`--raw` writes original RFC 5322 to stdout; `--json` emits the parsed struct) |
| `messages copy` | done (`<id>… --from <mailbox> --to <mailbox>`) |
| `messages move` | done (`<id>… --from <mailbox> --to <mailbox>`) |
| `messages add` | done (raw RFC 5322 in; `--mailbox <NAME>` + optional `--flag` / `--file`; IMAP APPEND, JMAP Blob/upload + Email/import, Maildir tmp-then-rename) |
| `messages compose` | done (CLI args incl. `--reply` / `--forward` with `--posting-style top\|bottom`, `--quote-headline`, `--signature`/`--signature-file`, `--send`) |
| `messages send` | done (raw RFC 5322 in; SMTP + JMAP) |
| `attachments list` | done (filename / mime / size / inline; `--include-inline` to surface inline parts) |
| `attachments download` | done (`--dir <PATH>`; defaults to account/global `downloads-dir`, then platform downloads dir, then temp) |

**Shared-command rule**: cross-backend commands always treat the IMAP
id as a UID. There is **no** `--seq` flag on the shared API — that
flag is reserved for the protocol-specific `imap` subcommands.

## B. Shared API — follow-ups (none currently)

`messages compose` no longer needs body quoting (shipped via
`--posting-style` + `--quote-headline` + `--signature`). `--save-to`
remains intentionally out of scope: the canonical pipeline is
`messages compose <args> | messages add --mailbox Drafts --flag draft`,
which composes well precisely because both halves are shared
commands. MIME-part extraction stays delegated to `mml`.


## C. Binary surface — to add back later

### C1. Sendmail / command backend

- Generic "exec a command, write the message to its stdin" backend.
  Replaces both v1's `sendmail` variant and any future `mailcmd`
  integrations.
- Config: `command.send = "/usr/sbin/sendmail -t"` (or similar).
- Wires only into `messages send`.

### C2. Notmuch backend

- Local index over Maildir. Adds `notmuch envelopes search` (real
  query support — Notmuch's reason to exist) and reuses the maildir
  arms for everything else.

### C3. `accounts` subcommand + wizard

- **Decided (E6)**: top-level verb is `accounts configure`.
- `accounts list` (read TOML, dump JSON).
- `accounts configure [<name>]` → wizard. Depends on the new
  `pimalaya/inquire` lib (crossterm-based, extracted from old
  `pimalaya-tui`) — himalaya hosts the `accounts configure` entry
  point, the lib provides the prompts.
- Possibly `accounts doctor` later (connectivity check).

### C4. Keyring support (opt-in)

- Cargo feature `keyring`, off by default. When on, secret values in
  TOML can be `{ keyring = "service:account" }`.
- Decoupled from auth itself — works for IMAP password, SMTP password,
  JMAP bearer, etc.

## D. Out of scope (delegated)

| Concern | Lives in |
|---|---|
| OAuth2 token acquisition / refresh | `pimalaya/ortie` (CLI) |
| MML composition, signing, encryption | `pimalaya/mml` (CLI) |
| HTML rendering | downstream tool / TUI |
| Search query DSL across backends | per-protocol commands only |
| Cross-backend sync | future `pimalaya/sirup` (or similar) |

Dropped permanently from v2 binary: `template *`, `attachment download`
(use `mml` for MIME part extraction), `messages delete` (use a flag or
move-to-trash), cross-backend copy, mailto handler.

## E. Resolved design decisions

1. **Pagination default size** — 25, matching v1. (E1)
2. **Compose shape** — single `messages compose` command with
   mutually-exclusive `--reply <id>` / `--forward <id>` flags. (E2)
3. **Compose vs send** — `compose --send` is supported. No interactive
   editor → no reason to force a `compose | send` pipe. (E3)
4. **Copy/move arg shape** — `<id>… --from <mailbox> --to <mailbox>`,
   with `--from` defaulting to `Inbox` and `--to` mandatory. (E4)
5. **`messages get` mode flags** — only `--raw`. JSON output is the
   global `--json` flag's job. No `--attachment-dir`, no `--part`. (E5)
6. **Wizard placement** — `accounts configure`. (E6)
7. **Backend dispatch** — none. The shared command runs unless the
   user explicitly types the protocol verb (`himalaya imap …`,
   `himalaya jmap …`, etc.), in which case the protocol-specific CLI
   takes over. (E7)

## F. Suggested ordering

1. **B1** compose body-quoting + `--save-to` — finish what's missing.
2. **C1** command/sendmail backend — drops in once the SMTP arm is
   stable.
3. **C3 + C4** account wizard + keyring — both gated on the inquire
   lib being extracted.
4. **C2** notmuch — last, depends on having maildir arms solid.