@shinick/outlook 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,504 @@
1
- # Temporary Holding Version
1
+ # outlook (Pure Microsoft Outlook CLI · TUI · HTTP API · MCP)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **`outlook`** (`@shinick/outlook`) is a pure **Microsoft Outlook** terminal client and AI agent toolkit built in Rust. Triage Mail, inspect Calendar agendas, manage Microsoft To Do tasks, and search Contacts & Entra Directory at local-cache speed—all from a single native binary.
4
+
5
+ > One standalone executable (`outlook` / `outlook.exe`) bundles OAuth 2.0 keyring credentials (plus automatic M365 shared-session bootstrap with `teams`), a **SQLite WAL + FTS5 local cache (`cache.db`)**, a Minimal-Chrome **`ratatui` TUI**, a background sync daemon (`outlook daemon`), an **Axum HTTP REST API (`outlook serve` on `:3939`)**, and a **stdio JSON-RPC 2.0 MCP server (`outlook mcp`)**. Prebuilt binaries ship for Windows, macOS, and Linux (`x86_64` / `aarch64`, compatible with **AlmaLinux 8 / GLIBC 2.28+**).
6
+
7
+ ---
8
+
9
+ ## Table of Contents
10
+
11
+ - [Overview & Key Highlights](#overview--key-highlights)
12
+ - [Installation](#installation)
13
+ - [npm Global Install](#npm-global-install)
14
+ - [Prebuilt Binaries & PowerShell Launcher](#prebuilt-binaries--powershell-launcher)
15
+ - [Build from Source](#build-from-source)
16
+ - [One-Click Self-Update](#one-click-self-update)
17
+ - [Authentication & External Token Brokers](#authentication--external-token-brokers)
18
+ - [Interactive & Headless Login](#interactive--headless-login)
19
+ - [Automatic M365 Shared-Session Bootstrap (`teams-cli`)](#automatic-m365-shared-session-bootstrap-teams-cli)
20
+ - [Microsoft Graph Delegated Scopes](#microsoft-graph-delegated-scopes)
21
+ - [External Token Brokers (`OUTLOOK_TOKEN_FILE`)](#external-token-brokers-outlook_token_file)
22
+ - [Custom Entra ID App Registration](#custom-entra-id-app-registration)
23
+ - [Minimal-Chrome TUI Guide](#minimal-chrome-tui-guide)
24
+ - [Layout, Density & Themes](#layout-density--themes)
25
+ - [Key Shortcuts](#key-shortcuts)
26
+ - [Quoted-Reply Folding & Inline Image Preview](#quoted-reply-folding--inline-image-preview)
27
+ - [CLI Reference](#cli-reference)
28
+ - [Subcommands](#subcommands)
29
+ - [Common CLI Workflows](#common-cli-workflows)
30
+ - [HTTP Server (`outlook serve`)](#http-server-outlook-serve)
31
+ - [MCP Server (`outlook mcp`)](#mcp-server-outlook-mcp)
32
+ - [Environment Variables & Configuration](#environment-variables--configuration)
33
+ - [Storage & Config Locations](#storage--config-locations)
34
+ - [Environment Variables](#environment-variables)
35
+ - [Example `config.toml`](#example-configtoml)
36
+ - [License](#license)
37
+
38
+ ---
39
+
40
+ ## Overview & Key Highlights
41
+
42
+ - **100% Pure Microsoft Outlook (Mail · Calendar · Tasks · Contacts)**:
43
+ - **Mail**: Header-first folder listing and incremental delta sync, on-demand HTML body hydration with `$batch` neighbor prefetch, conversation thread grouping (`t`), Focused/Other Inbox toggle (`F`), Markdown-to-HTML compose/reply/reply-all/forward, file & inline `cid:` attachments, and 0ms optimistic triage (`archive`, `mark-read`, `flag`, `move`, `delete`).
44
+ - **Calendar**: `calendarView` agenda queries, event creation with Teams online meetings, RSVP (`accept` / `tentative` / `decline`), and event deletion.
45
+ - **Tasks (Microsoft To Do)**: Task lists, due dates, importance, and instant completion toggling.
46
+ - **Contacts & Directory**: Unified search across personal Outlook contacts (`/me/contacts`) and Entra ID organization directory (`/users`).
47
+ - **Minimal-Chrome Responsive TUI (`ratatui`)**: 3-tier responsive layout (`Wide >= 120`, `Medium 80..119`, `Narrow < 80`) across tabs `1` Mail, `2` Calendar, and `3` Tasks, unified `Ctrl+K` Omni-Switcher, Cozy/Compact density (`Ctrl+D`), quoted-reply folding (`z`), and colorblind-safe themes (`NO_COLOR`, `Ansi16`, `Ansi256`, Midnight Dark, Daylight Light).
48
+ - **Local SQLite WAL + FTS5 Cache & Daemon**: Stores folders, messages, events, tasks, and contacts in `cache.db` for instant hybrid FTS5 + `LIKE` offline search (`outlook search`) and sub-5ms CLI reads when `outlook daemon` is running.
49
+ - **Inline Terminal Image Preview (`v` / `Alt+v` / click / `outlook preview`)**: Multi-protocol high-resolution rendering for PNG, JPEG, GIF, WebP, and inline `cid:` / `https://` images with automatic terminal detection across **Windows, Linux, and macOS** (**Kitty Graphics Protocol**, **iTerm2 `OSC 1337`**, **Sixel `DCS q`**, and **24-bit Unicode Half-Blocks (`▀`)** fallback).
50
+ - **Automatic JWT Scope Diagnostics**: `outlook whoami`, `outlook doctor`, and `403 Forbidden` handlers inspect JWT `scp`/`roles` claims to flag missing Outlook permissions (such as `Mail.ReadBasic`-only tokens).
51
+ - **AI Agent Automation (`outlook serve` & `outlook mcp`)**: Local Axum HTTP JSON API (`127.0.0.1:3939`, optional `--api-key` / `--token` auth, `/openapi.json`) and newline-delimited stdio JSON-RPC 2.0 MCP server exposing **20 Microsoft Outlook tools**.
52
+ - **Cross-Platform & AlmaLinux 8 Ready**: Single static binary (bundled SQLite + `rustls`, zero OpenSSL dev dependencies). Prebuilt Linux binaries target **GLIBC 2.28** (`AlmaLinux 8`, `RHEL 8+`, `Rocky Linux 8+`, `Ubuntu 20.04+`, `Debian 10+`).
53
+
54
+ ---
55
+
56
+ ## Installation
57
+
58
+ ### npm Global Install
59
+
60
+ Install `@shinick/outlook` globally to link the native binary for Windows, macOS, or Linux (`x64` / `arm64`):
61
+
62
+ ```bash
63
+ npm install -g @shinick/outlook
64
+ outlook --version
65
+
66
+ # Or run one-off without installing globally
67
+ npx @shinick/outlook --version
68
+ ```
69
+
70
+ See [docs/NPM.md](docs/NPM.md) for optional per-platform package details and zero-Node `postinstall` linking.
71
+
72
+ ### Prebuilt Binaries & PowerShell Launcher
73
+
74
+ Download a prebuilt archive or binary directly from [GitHub Releases](https://github.com/shinick-dev/outlook/releases):
75
+
76
+ ```powershell
77
+ # Windows: download outlook.exe directly
78
+ gh release download v0.1.0 -R shinick-dev/outlook --pattern "outlook.exe" --dir "$HOME\.local\bin" --clobber
79
+ ```
80
+
81
+ If you clone the repository, you can register the PowerShell `$PROFILE` shim (`outlook`) or use the bundled wrapper scripts (`outlook.cmd` on Windows, `./outlook` on macOS/Linux):
82
+
83
+ ```powershell
84
+ gh repo clone shinick-dev/outlook
85
+ cd outlook
86
+ pwsh -File .\scripts\install-profile.ps1
87
+ . $PROFILE
88
+ outlook --version
89
+ ```
90
+
91
+ ### Build from Source
92
+
93
+ Requires **Rust 1.80+**. SQLite (`rusqlite` `bundled`) and TLS (`rustls`) are compiled in statically—no external OpenSSL or SQLite libraries required:
94
+
95
+ ```bash
96
+ cargo build --release
97
+ ./target/release/outlook --help
98
+ ```
99
+
100
+ CI Linux releases (`x86_64-unknown-linux-gnu` and `aarch64-unknown-linux-gnu`) are cross-compiled with `cargo-zigbuild` targeting **GLIBC 2.28** and verified with `node scripts/verify-glibc.mjs --max 2.28` on `almalinux:8`. For older systems (e.g., CentOS 7) or Alpine/musl, build from source with `cargo build --release`.
101
+
102
+ ### One-Click Self-Update
103
+
104
+ `outlook update` checks GitHub Releases (`shinick-dev/outlook`), verifies `SHA256SUMS.txt`, and safely swaps the running binary (including locked executables on Windows NTFS):
105
+
106
+ ```bash
107
+ outlook update --check # Check for a newer release without installing
108
+ outlook update # Download, verify SHA-256, and update in place
109
+ outlook update --force # Reinstall the current release
110
+ ```
111
+
112
+ ---
113
+
114
+ ## Authentication & External Token Brokers
115
+
116
+ ### Interactive & Headless Login
117
+
118
+ ```bash
119
+ # 1. Interactive browser login (OAuth 2.0 Authorization Code + PKCE)
120
+ outlook login
121
+
122
+ # 2. Headless / SSH / remote terminal login (Device Code flow)
123
+ outlook login --device-code
124
+
125
+ # 3. Supply an existing Microsoft Graph access token or token file
126
+ outlook login --access-token "$GRAPH_TOKEN"
127
+ outlook login --token-file ~/.cursor/tc-auth/access_token
128
+ # Or via environment variable:
129
+ export OUTLOOK_ACCESS_TOKEN="$GRAPH_TOKEN"
130
+
131
+ # 4. Inspect active identity, JWT scopes, auth source, and Graph connectivity
132
+ outlook whoami
133
+ outlook doctor --online
134
+
135
+ # 5. Clear stored credentials (OS keyring + fallback file)
136
+ outlook logout
137
+ ```
138
+
139
+ On headless Linux without D-Bus Secret Service, `outlook` automatically falls back to a `0600` `credentials.json` file in the config directory.
140
+
141
+ ### Automatic M365 Shared-Session Bootstrap (`teams-cli`)
142
+
143
+ When `share_m365_auth = true` (default, controlled by `OUTLOOK_SHARE_M365_AUTH`), `outlook` automatically checks for an existing `teams-cli` stored session (`teams-cli` OS keyring or `credentials.json`) or `TEAMS_TOKEN_FILE` whenever no dedicated `outlook-cli` token is configured:
144
+
145
+ - If the `teams-cli` session already holds Outlook scopes (`Mail.*`, `Calendars.*`, `Tasks.*`), `outlook` reuses it seamlessly (`auth_mode = "shared_teams_session"` or `"shared_teams_token_file"`).
146
+ - If the `teams-cli` session has a refresh token without Outlook scopes yet, `outlook` silently upgrades the refresh token for Outlook scopes without requiring a second browser login.
147
+ - Set `OUTLOOK_SHARE_M365_AUTH=false` (or `share_m365_auth = false` in `config.toml`) to disable cross-app session reuse.
148
+
149
+ ### Microsoft Graph Delegated Scopes
150
+
151
+ `outlook` requests Microsoft Outlook delegated scopes across Mail, Calendar, Contacts, and To Do:
152
+
153
+ | Area | Scope | Purpose |
154
+ | --- | --- | --- |
155
+ | **Auth & Profile** | `offline_access` | Issue refresh tokens for silent renewal |
156
+ | | `User.Read` | Read signed-in user profile (`/me`) |
157
+ | | `User.ReadBasic.All` | Search Entra organization directory (`/users`) |
158
+ | **Mail** | `Mail.ReadWrite` | Read folders/messages, mark read/flag, move, delete, download attachments |
159
+ | | `Mail.Send` | Send, reply, reply-all, and forward emails |
160
+ | **Calendar** | `Calendars.ReadWrite` | List calendar events, create events, RSVP, cancel/delete |
161
+ | **Contacts** | `Contacts.Read` / `Contacts.ReadWrite` | List and search personal Outlook contacts |
162
+ | **Tasks** | `Tasks.ReadWrite` | List To Do task lists, create, complete, and delete tasks |
163
+
164
+ ### External Token Brokers (`OUTLOOK_TOKEN_FILE`)
165
+
166
+ When an external tool (e.g., F12 browser token capture, `tc-auth`, `az account get-access-token`, HashiCorp Vault) manages your Graph token, configure `OUTLOOK_TOKEN_FILE` / `OUTLOOK_TOKEN_REFRESH_CMD` (or `config.toml`). Whenever `OUTLOOK_TOKEN_FILE` or `OUTLOOK_ACCESS_TOKEN` is active, `outlook` automatically skips OS keyring and `credentials.json` access.
167
+
168
+ **Option 1 — `config.toml` (recommended persistent setup):**
169
+
170
+ ```toml
171
+ # Windows: %APPDATA%\outlook-cli\config.toml
172
+ # Linux/macOS: ~/.config/outlook-cli/config.toml
173
+ token_file = "~/.cursor/tc-auth/access_token"
174
+ token_refresh_cmd = "python ~/.cursor/tc-auth/graph-auth.py refresh"
175
+ token_refresh_mins = 5
176
+ ```
177
+
178
+ **Option 2 — Environment variables (`bash` / `PowerShell`):**
179
+
180
+ ```bash
181
+ export OUTLOOK_TOKEN_FILE="$HOME/.cursor/tc-auth/access_token"
182
+ export OUTLOOK_TOKEN_REFRESH_CMD="python $HOME/.cursor/tc-auth/graph-auth.py refresh"
183
+ export OUTLOOK_TOKEN_REFRESH_MINS=5
184
+ ```
185
+
186
+ ```powershell
187
+ $env:OUTLOOK_TOKEN_FILE = "$HOME\.cursor\tc-auth\access_token"
188
+ $env:OUTLOOK_TOKEN_REFRESH_CMD = "python `"$HOME\.cursor\tc-auth\graph-auth.py`" refresh"
189
+ $env:OUTLOOK_TOKEN_REFRESH_MINS = "5"
190
+ ```
191
+
192
+ **Option 3 — Direct stdout from Azure CLI (`az account get-access-token`):**
193
+
194
+ If `token_refresh_cmd` is set without `token_file`, `outlook` parses either a raw JWT or Azure CLI camelCase JSON (`accessToken` / `expiresOn`) from `stdout`:
195
+
196
+ ```toml
197
+ token_refresh_cmd = "az account get-access-token --resource https://graph.microsoft.com --output json"
198
+ token_refresh_mins = 5
199
+ ```
200
+
201
+ ```bash
202
+ OUTLOOK_TOKEN_REFRESH_CMD="az account get-access-token --resource https://graph.microsoft.com --output json" outlook whoami
203
+ ```
204
+
205
+ ### Custom Entra ID App Registration
206
+
207
+ By default `outlook` uses its built-in multi-tenant public client ID (`14d82eec-204b-4c2f-b7e8-296a70dab67e`). If your organization requires an internal Entra ID app registration, add the delegated scopes above, enable **Public client flows** with redirect URI `http://localhost` under **Mobile and desktop applications**, and pass your IDs:
208
+
209
+ ```bash
210
+ outlook login --client-id "<AZURE_APP_CLIENT_ID>" --tenant-id "<TENANT_ID>"
211
+
212
+ # Or via environment variables (override config.toml):
213
+ export OUTLOOK_CLIENT_ID="<AZURE_APP_CLIENT_ID>"
214
+ export OUTLOOK_TENANT_ID="<TENANT_ID>" # default: common
215
+ ```
216
+
217
+ You can also override default scopes via `scopes = [...]` in `config.toml`.
218
+
219
+ ---
220
+
221
+ ## Minimal-Chrome TUI Guide
222
+
223
+ Launch the interactive TUI by running `outlook` (or `outlook tui`):
224
+
225
+ ```bash
226
+ outlook
227
+ ```
228
+
229
+ ### Layout, Density & Themes
230
+
231
+ - **Minimal-Chrome 3-Tier Responsive Layout**:
232
+ - **Wide (`>= 120` cols)**: Left navigation rail (Mail folders / Calendar / To Do lists) + middle message/agenda/task list + right reader & detail pane.
233
+ - **Medium (`80..119` cols)**: Compact list + reader workspace (`Ctrl+B` toggles sidebar).
234
+ - **Narrow (`< 80` cols)**: Single-pane focus view with a compact top bar.
235
+ - **Cozy & Compact Density (`Ctrl+D`)**: Toggle between spacious multi-line message rows (**Cozy**) and high-density single-line rows (**Compact**).
236
+ - **Colorblind-Safe Multi-Depth Themes**: Automatically detects `NO_COLOR`, `Ansi16`, `Ansi256`, and Truecolor terminals (`Midnight Dark` & `Daylight Light`), or select a preset in Settings (`Ctrl+,`) or `config.toml`.
237
+
238
+ ### Key Shortcuts
239
+
240
+ | Key | Context | Action |
241
+ | --- | --- | --- |
242
+ | `1` / `2` / `3` (`Alt+1..3`) | Global | Switch to **Mail** / **Calendar** / **Tasks & Contacts** tab |
243
+ | `Ctrl+K` | Global | **Unified Omni-Switcher** (`>` commands, `#` folders, `@` contacts, `/` search) |
244
+ | `j` / `k` / `↑` / `↓` | Global | Navigate folders, message list, agenda, or scroll reading pane |
245
+ | `Tab` / `Enter` / `Esc` | Global | Cycle focus (`Folders <-> List <-> Reader`) or close modal |
246
+ | `Space` / `PgDn` / `PgUp` | List / Reader | Page-scroll reading pane directly from the list |
247
+ | `c` | Mail | **Compose** new email (`To`/`Cc`/`Bcc` contact autocomplete, Markdown body, `Ctrl+V` inline image) |
248
+ | `r` / `R` / `f` | Mail | **Reply** / **Reply-All** / **Forward** selected email |
249
+ | `e` | Mail | **Archive** selected email (optimistic 0ms UI update) |
250
+ | `u` / `g` | Mail | Toggle **Read/Unread** (`u`) or **Flag/Unflag** (`g`) |
251
+ | `m` | Mail | **Move** email to folder (fuzzy folder picker) |
252
+ | `Del` / `#` | Mail | Delete email (with confirmation) |
253
+ | `t` / `F` / `U` | Mail | Toggle **Thread grouping** (`t`), **Focused Inbox** (`F`), or **Unread filter** (`U`) |
254
+ | `z` | Mail Reader | **Fold / unfold** quoted email reply history |
255
+ | `v` / `Alt+v` | Mail Reader | Open high-resolution **inline terminal image preview** (`+`/`-`/`0`, `p` protocol, `[`/`]`, `d` save) |
256
+ | `d` / `A` / `o` | Mail Reader | Download attachment (`d`), open attachment picker (`A`), or open link (`o`) |
257
+ | `n` | Calendar / Tasks | Create **New Event** (Calendar) or **New Task / To Do List** (Tasks) |
258
+ | `a` / `y` / `x` | Calendar | RSVP **Accept** (`a`), **Tentative** (`y`), or **Decline** (`x`) |
259
+ | `Space` / `Enter` | Tasks | Toggle task completion (0ms optimistic UI) |
260
+ | `/` / `Ctrl+F` | Global | Search mail (SQLite FTS5 local + Graph KQL remote) |
261
+ | `Ctrl+B` / `Ctrl+D` | Global | Toggle left sidebar (`Ctrl+B`) / Cozy-Compact density (`Ctrl+D`) |
262
+ | `Ctrl+R` / `F5` | Global | Manual sync / refresh all domains |
263
+ | `Ctrl+,` / `?` / `Ctrl+Q` | Global | Settings / Help overlay / Safe quit |
264
+
265
+ Compose modal shortcuts (`c`, `r`, `R`, `f`): `Ctrl+Enter` or `Alt+Enter` to send, `Tab`/`Enter` on `To`/`Cc`/`Bcc` to insert autocomplete contact chip, `Ctrl+V` to paste text or clipboard screenshot (`cid:`), `Ctrl+A` to attach a file, `Ctrl+E` to edit in `$EDITOR`, `Ctrl+S` to save draft (`Esc` auto-stashes locally).
266
+
267
+ ### Quoted-Reply Folding & Inline Image Preview
268
+
269
+ - Pressing `z` in the Mail reader collapses or expands nested quoted email threads (`QuotedHistory`) so long reply chains stay readable.
270
+ - Pressing `v` / `Alt+v` (or clicking an `[IMG ...]` chip or inline thumbnail) renders attached or inline `cid:`/`https://` images with automatic terminal protocol detection across **Windows, Linux, and macOS**:
271
+ - **Kitty Graphics Protocol** (Kitty, Ghostty)
272
+ - **iTerm2 Inline Images (`OSC 1337`)** (WezTerm on Windows/Linux/macOS, iTerm2 on macOS, Rio, Mintty)
273
+ - **Sixel (`DCS q`)** (Windows Terminal v1.22+, foot, Contour, mlterm)
274
+ - **24-bit Unicode Half-Blocks (`▀`)** universal fallback (tmux/SSH/legacy consoles)
275
+ - Configure the default globally via `image_protocol = "auto"` in `config.toml`, `OUTLOOK_IMAGE_PROTOCOL`, or `outlook preview --protocol <PROTOCOL>`.
276
+
277
+ ---
278
+
279
+ ## CLI Reference
280
+
281
+ ### Subcommands
282
+
283
+ | Command | Alias | Description | Key Options |
284
+ | --- | --- | --- | --- |
285
+ | `outlook` | - | Launch the TUI (default when no subcommand is given) | - |
286
+ | `outlook tui` | - | Launch the interactive TUI | - |
287
+ | `outlook login` | `in` | Sign in with Microsoft Entra ID (PKCE, Device Code, or token) | `--client-id`, `--tenant-id`, `--device-code`, `--client-secret`, `--access-token` (`--token`), `--token-file`, `--port`, `--json` |
288
+ | `outlook logout` | `out` | Remove stored credentials from keyring & fallback file | `--json` |
289
+ | `outlook whoami` | - | Show current profile, token expiry, scopes, and auth source | `--json` |
290
+ | `outlook doctor` | - | Show config/DB/keyring paths, image protocol, and diagnostics | `--online` (`--probe`), `--json` |
291
+ | `outlook update` | - | Check GitHub Releases and self-update binary | `--check`, `--force`, `--repo`, `--json` |
292
+ | `outlook folders` | - | List Outlook mail folders with unread/total counts | `--refresh`, `--offline`, `--cached`/`--fast`, `--json` |
293
+ | `outlook mail` | `ls`, `inbox` | List messages in Inbox or a specified folder | `--folder <F>`, `--limit <N>`, `--unread`, `--flagged`, `--focused`, `--refresh`, `--offline`, `--cached`/`--fast`, `--json` |
294
+ | `outlook read <id>` | `cat` | Read a mail message with full headers, body, and attachments | `--raw-html`, `--mark-read`, `--preview-images`, `--offline`, `--cached`/`--fast`, `--json` |
295
+ | `outlook send` | `compose` | Compose and send a new email (Markdown + attachments) | `--to <ADDR>`, `--cc`, `--bcc`, `--subject <S>`, `--body <MD>`, `--attach <PATH>`, `--inline <IMG>`, `--importance <low\|normal\|high>`, `--json` |
296
+ | `outlook reply <id> <md>` | - | Reply (or reply-all) to a mail message | `--all`, `--json` |
297
+ | `outlook forward <id> [md]` | - | Forward a mail message | `--to <ADDR>`, `--json` |
298
+ | `outlook mark <id>` | - | Update read/unread or flag status | `--read` / `--unread`, `--flag` / `--unflag`, `--json` |
299
+ | `outlook move <id> <folder>` | - | Move a mail message to another folder | `--json` |
300
+ | `outlook archive <id>` | - | Archive a mail message (`move <id> archive`) | `--json` |
301
+ | `outlook delete <id>` | `rm` | Delete a mail message (`--yes` required with `--json`) | `--yes`, `--json` |
302
+ | `outlook search <query>` | - | Search local SQLite FTS5 or Graph KQL `$search` | `--folder <F>`, `--remote`, `--limit <N>`, `--json` |
303
+ | `outlook download <id>` | `dl` | Download a mail attachment to disk | `--attachment <IDX_OR_NAME>`, `--dir`/`--out <DIR>`, `--json` |
304
+ | `outlook preview <id>` | - | Render a mail image attachment in the terminal | `--attachment <IDX_OR_NAME>`, `--offline`, `--protocol`, `--cols`, `--rows` |
305
+ | `outlook preview-file <path>` | - | Render a local image file in the terminal | `--protocol`, `--cols`, `--rows` |
306
+ | `outlook calendar` | `cal`, `events` | List upcoming calendar events | `--days <N>`, `--from`/`--start`, `--to`/`--end`, `--limit <N>`, `--offline`, `--cached`/`--fast`, `--json` |
307
+ | `outlook event <id>` | - | Read full details and attendees of a calendar event | `--offline`, `--cached`/`--fast`, `--json` |
308
+ | `outlook create-event` | - | Create a new calendar event | `--subject`, `--start`, `--end`, `--location`, `--attendee`/`--to`, `--body`, `--online`, `--all-day`, `--time-zone`, `--json` |
309
+ | `outlook rsvp <id> <resp>` | - | Respond to a calendar invite (`accept`, `tentative`, `decline`) | `--comment <TEXT>`, `--json` |
310
+ | `outlook delete-event <id>` | - | Delete a calendar event (`--yes` required with `--json`) | `--yes`, `--json` |
311
+ | `outlook tasks` | `todo` | List Microsoft To Do tasks | `--list <NAME_OR_ID>`, `--all`, `--limit <N>`, `--refresh`, `--offline`, `--cached`/`--fast`, `--json` |
312
+ | `outlook task-lists` | - | List Microsoft To Do task lists | `--refresh`, `--offline`, `--cached`/`--fast`, `--json` |
313
+ | `outlook add-task <title>` | - | Add a new Microsoft To Do task | `--list`, `--due <YYYY-MM-DD>`, `--importance <low\|normal\|high>`, `--notes`/`--body`, `--json` |
314
+ | `outlook done <task_id>` | - | Mark a Microsoft To Do task completed (or reopen with `--undo`) | `--list`, `--undo`, `--json` |
315
+ | `outlook delete-task <task_id>` | - | Delete a Microsoft To Do task (`--yes` required with `--json`) | `--list`, `--yes`, `--json` |
316
+ | `outlook contacts` | - | List or search personal Outlook contacts and org directory | `--query`/`--q`, `--limit <N>`, `--refresh`, `--offline`, `--cached`/`--fast`, `--json` |
317
+ | `outlook sync` | - | Full sync of folders, inbox, calendar, tasks, and contacts | `--days <N>`, `--limit <N>`, `--json` |
318
+ | `outlook daemon <cmd>` | - | Control the background sync daemon (`start`, `status`, `stop`, `restart`, `run`) | `--json` (on `start`/`status`/`stop`/`restart`) |
319
+ | `outlook serve` | `api` | Start the local HTTP JSON API server | `--bind <IP>`, `--port <3939>`, `--api-key`/`--token <KEY>` |
320
+ | `outlook mcp` | `mcp-server` | Start the stdio MCP (JSON-RPC 2.0) server | - |
321
+
322
+ ### Common CLI Workflows
323
+
324
+ ```bash
325
+ # 1. Inspect folders, read unread inbox mail, and reply
326
+ outlook folders
327
+ outlook mail --folder inbox --unread --limit 20
328
+ outlook read AAMkAGI2... --mark-read
329
+ outlook reply AAMkAGI2... "Thanks, **approved** for release." --all
330
+
331
+ # 2. Send an email with Markdown, attachment, and inline image
332
+ outlook send --to alice@contoso.com --cc bob@contoso.com \
333
+ --subject "v0.1.0 Release Summary" \
334
+ --body "See attached report and latency chart." \
335
+ --attach ./report.pdf \
336
+ --inline ./latency.png \
337
+ --importance high
338
+
339
+ # 3. Triage, search, and archive
340
+ outlook mark AAMkAGI2... --flag --read
341
+ outlook move AAMkAGI2... archive
342
+ outlook search "quarterly review" --remote --json
343
+
344
+ # 4. Calendar agenda, event creation, and RSVP
345
+ outlook calendar --days 7
346
+ outlook create-event --subject "Sprint Review" \
347
+ --start "2026-11-20T14:00:00Z" --end "2026-11-20T15:00:00Z" \
348
+ --attendee alice@contoso.com --online
349
+ outlook rsvp EVENT_ID accept --comment "Joining remotely"
350
+
351
+ # 5. Microsoft To Do tasks, contacts, and background daemon
352
+ outlook add-task "Verify GLIBC 2.28 build" --due 2026-11-20 --importance high
353
+ outlook done TASK_ID
354
+ outlook contacts --query alice --json
355
+ outlook daemon start
356
+ outlook mail --cached --json
357
+ ```
358
+
359
+ ---
360
+
361
+ ## HTTP Server (`outlook serve`)
362
+
363
+ Run a local Axum HTTP JSON API server for scripts, webhooks, and AI agents (defaults to `127.0.0.1:3939`):
364
+
365
+ ```bash
366
+ outlook serve # http://127.0.0.1:3939
367
+ outlook serve --port 9000 --api-key secret123 # Require Bearer/x-api-key (except /health)
368
+ ```
369
+
370
+ ```bash
371
+ curl http://127.0.0.1:3939/health
372
+ curl http://127.0.0.1:3939/v1/mail/messages?folder=inbox&unread=true
373
+ curl -X POST http://127.0.0.1:3939/v1/mail/send \
374
+ -H "Content-Type: application/json" \
375
+ -d '{"to":["alice@contoso.com"],"subject":"Build green","markdown":"All checks passed!"}'
376
+ ```
377
+
378
+ Key endpoints:
379
+ - `GET /health`, `GET /openapi.json`, `GET /v1/whoami`
380
+ - `GET /v1/mail/folders`, `GET /v1/mail/messages`, `GET / PATCH / DELETE /v1/mail/messages/{id}`
381
+ - `POST /v1/mail/send`, `POST /v1/mail/messages/{id}/reply`, `POST /v1/mail/messages/{id}/forward`
382
+ - `POST /v1/mail/messages/{id}/attachments/{att_id}/download`, `GET /v1/mail/search`
383
+ - `GET / POST /v1/calendar/events`, `GET / DELETE /v1/calendar/events/{id}`, `POST /v1/calendar/events/{id}/rsvp`
384
+ - `GET /v1/todo/lists`, `GET / POST /v1/todo/tasks`, `PATCH / DELETE /v1/todo/tasks/{id}`
385
+ - `GET /v1/contacts`
386
+
387
+ See [docs/API.md](docs/API.md) and [docs/openapi.yaml](docs/openapi.yaml) for the complete HTTP API reference.
388
+
389
+ ---
390
+
391
+ ## MCP Server (`outlook mcp`)
392
+
393
+ `outlook mcp` (alias `outlook mcp-server`) runs a **newline-delimited JSON-RPC 2.0** Model Context Protocol server over **stdio** (`stdout` is strictly reserved for JSON-RPC frames; logs go to `stderr`). Authenticate first with `outlook login` or configure `OUTLOOK_ACCESS_TOKEN` / `OUTLOOK_TOKEN_FILE` (or automatic `teams-cli` shared M365 session bootstrap).
394
+
395
+ ### Claude Desktop (`claude_desktop_config.json`)
396
+
397
+ ```json
398
+ {
399
+ "mcpServers": {
400
+ "outlook": {
401
+ "command": "outlook",
402
+ "args": ["mcp"]
403
+ }
404
+ }
405
+ }
406
+ ```
407
+
408
+ Or point directly to a repository launcher / binary without installing globally:
409
+
410
+ ```json
411
+ {
412
+ "mcpServers": {
413
+ "outlook": {
414
+ "command": "C:\\path\\to\\outlook\\outlook.cmd",
415
+ "args": ["mcp"]
416
+ }
417
+ }
418
+ }
419
+ ```
420
+
421
+ ### Claude Code
422
+
423
+ ```bash
424
+ claude mcp add outlook -- outlook mcp
425
+ ```
426
+
427
+ ### OpenAI Codex CLI (`~/.codex/config.toml`)
428
+
429
+ ```toml
430
+ [mcp_servers.outlook]
431
+ command = "outlook"
432
+ args = ["mcp"]
433
+ ```
434
+
435
+ **20 exposed MCP tools:** `whoami`, `list_mail_folders`, `list_messages`, `get_message`, `send_mail`, `reply_mail`, `forward_mail`, `update_message`, `delete_message` (`confirm: true`), `download_attachment`, `search_mail`, `list_events`, `create_event`, `respond_event`, `delete_event` (`confirm: true`), `list_todo_lists`, `list_tasks`, `create_task`, `complete_task`, and `search_contacts`. See [docs/MCP.md](docs/MCP.md) for request/response schemas.
436
+
437
+ ---
438
+
439
+ ## Environment Variables & Configuration
440
+
441
+ ### Storage & Config Locations
442
+
443
+ | Item | Default Path (Windows / Linux & macOS) | Override |
444
+ | --- | --- | --- |
445
+ | Configuration (`config.toml`) | `%APPDATA%\outlook-cli\config.toml` / `~/.config/outlook-cli/config.toml` | `OUTLOOK_CONFIG_DIR` |
446
+ | Unsent drafts (`drafts.json`) | `<config_dir>\drafts.json` | `OUTLOOK_CONFIG_DIR` |
447
+ | Credentials | OS Keyring (`outlook-cli` / `default`) + fallback `<config_dir>\credentials.json` | `OUTLOOK_DISABLE_KEYRING=1` |
448
+ | SQLite cache (`cache.db`) | `%LOCALAPPDATA%\outlook-cli\<user_id>\cache.db` / `~/.local/share/outlook-cli/<user_id>/cache.db` | `OUTLOOK_DATA_DIR` |
449
+ | Downloads folder | `~/Downloads/outlook` (or `download_dir` in `config.toml`) | - |
450
+ | Graph / Auth base URLs | `https://graph.microsoft.com/v1.0` / `https://login.microsoftonline.com` | `OUTLOOK_GRAPH_BASE_URL`, `OUTLOOK_AUTH_BASE_URL` |
451
+ | Self-update repository | `shinick-dev/outlook` | `OUTLOOK_GITHUB_REPO` |
452
+
453
+ ### Environment Variables
454
+
455
+ | Variable | Description |
456
+ | --- | --- |
457
+ | `OUTLOOK_CLIENT_ID` | Override custom Entra ID application (client) ID (falls back to `TEAMS_CLIENT_ID`, `AZURE_CLIENT_ID`) |
458
+ | `OUTLOOK_TENANT_ID` | Override Entra ID tenant ID (default: `common`; falls back to `TEAMS_TENANT_ID`, `AZURE_TENANT_ID`) |
459
+ | `OUTLOOK_ACCESS_TOKEN` | Inject a Bearer access token directly (skips OS keyring lookup) |
460
+ | `OUTLOOK_TOKEN_FILE` | Path to external token file (raw JWT or JSON; skips OS keyring lookup) |
461
+ | `OUTLOOK_TOKEN_REFRESH_CMD` | External command hook to refresh tokens before expiry or on `401` |
462
+ | `OUTLOOK_TOKEN_REFRESH_MINS` | Minutes before `exp` to proactively run `OUTLOOK_TOKEN_REFRESH_CMD` (default: `5`) |
463
+ | `OUTLOOK_SHARE_M365_AUTH` | Reuse `TEAMS_TOKEN_FILE` or `teams-cli` stored session when no `outlook-cli` token exists (default: `true`) |
464
+ | `OUTLOOK_DISABLE_KEYRING` | Set to `1` to disable OS keyring and store credentials in `credentials.json` |
465
+ | `OUTLOOK_CLI_CACHE_SECS` | Local SQLite cache TTL in seconds for CLI reads (default: `0`; `--cached`/`--fast` prefers cache) |
466
+ | `OUTLOOK_AUTO_DAEMON` | Set to `1`/`true` to auto-start and attach to `outlook daemon` for sub-5ms CLI reads (default: `false`) |
467
+ | `OUTLOOK_IMAGE_PROTOCOL` | Override terminal image rendering protocol (`auto`, `kitty`, `iterm2`, `sixel`, `halfblock`) |
468
+ | `OUTLOOK_CONFIG_DIR` | Override directory for `config.toml`, `credentials.json`, and `drafts.json` |
469
+ | `OUTLOOK_DATA_DIR` | Override directory for the SQLite cache (`cache.db`) |
470
+ | `OUTLOOK_NO_BROWSER` | Set to `1`/`true` to disable automatic browser launch during `outlook login` |
471
+ | `OUTLOOK_GRAPH_BASE_URL` | Override Microsoft Graph v1.0 base URL |
472
+ | `OUTLOOK_AUTH_BASE_URL` | Override Entra ID OAuth 2.0 base URL |
473
+ | `OUTLOOK_GITHUB_REPO` | Override GitHub `owner/repo` used by `outlook update` |
474
+ | `OUTLOOK_GITHUB_TOKEN` | GitHub token for private release checks in `outlook update` |
475
+ | `OUTLOOK_ALLOW_INSECURE_SERVE` | Set to `1` to permit non-loopback `outlook serve` binds without `--api-key` |
476
+ | `NO_COLOR` | Set to any non-empty value to force monochrome `NoColor` TUI rendering |
477
+
478
+ ### Example `config.toml`
479
+
480
+ ```toml
481
+ client_id = "14d82eec-204b-4c2f-b7e8-296a70dab67e"
482
+ tenant_id = "common"
483
+ density = "cozy" # "cozy" | "compact"
484
+ theme = "auto" # "auto" | "dark" | "light" | "ansi256" | "ansi16" | "nocolor"
485
+ notify = true
486
+ show_nav_rail = true
487
+ group_threads = true
488
+ focused_only = false
489
+ inline_images = true
490
+ image_protocol = "auto" # "auto" | "kitty" | "iterm2" | "sixel" | "halfblock"
491
+ download_dir = ""
492
+ share_m365_auth = true
493
+ cli_cache_ttl_secs = 0
494
+ auto_daemon = false
495
+ token_file = ""
496
+ token_refresh_cmd = ""
497
+ token_refresh_mins = 5
498
+ ```
499
+
500
+ ---
501
+
502
+ ## License
503
+
504
+ MIT
package/bin/outlook.js ADDED
@@ -0,0 +1,130 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ const fs = require('node:fs');
5
+ const os = require('node:os');
6
+ const path = require('node:path');
7
+ const { spawn } = require('node:child_process');
8
+
9
+ const SUPPORTED = [
10
+ 'win32-x64',
11
+ 'win32-arm64',
12
+ 'darwin-x64',
13
+ 'darwin-arm64',
14
+ 'linux-x64',
15
+ 'linux-arm64',
16
+ ];
17
+
18
+ function fail(message) {
19
+ process.stderr.write(`outlook: ${message}\n`);
20
+ process.exit(1);
21
+ }
22
+
23
+ function formatLinuxGlibcHint() {
24
+ return [
25
+ 'Prebuilt Linux binaries target GLIBC >= 2.28 (AlmaLinux 8 / RHEL 8 / Rocky Linux 8 / Ubuntu 20.04+ / Debian 10+).',
26
+ 'If you are on an older glibc distribution (such as CentOS 7 with GLIBC < 2.28) or Alpine/musl,',
27
+ 'build from source with Cargo instead:',
28
+ ' cargo install --git https://github.com/shinick-dev/outlook --locked',
29
+ 'or clone the repository and run:',
30
+ ' cargo build --release',
31
+ ].join('\n');
32
+ }
33
+
34
+ const platform = process.platform;
35
+ const arch = process.arch;
36
+ const platformKey = `${platform}-${arch}`;
37
+ const packageName = `@shinick/outlook-${platformKey}`;
38
+ const binaryName = platform === 'win32' ? 'outlook.exe' : 'outlook';
39
+
40
+ let packageDir = null;
41
+ try {
42
+ packageDir = path.dirname(require.resolve(`${packageName}/package.json`));
43
+ } catch {
44
+ packageDir = null;
45
+ }
46
+
47
+ const binaryPath = packageDir ? path.join(packageDir, 'bin', binaryName) : null;
48
+
49
+ if (!binaryPath || !fs.existsSync(binaryPath)) {
50
+ const lines = [
51
+ `no prebuilt binary found for ${platformKey}.`,
52
+ '',
53
+ `Expected the optional dependency "${packageName}" to provide:`,
54
+ ` ${binaryPath || `node_modules/${packageName}/bin/${binaryName}`}`,
55
+ '',
56
+ `Supported platforms: ${SUPPORTED.join(', ')}`,
57
+ '',
58
+ 'Try one of:',
59
+ ' npm install -g @shinick/outlook --include=optional',
60
+ ' npm install @shinick/outlook --include=optional',
61
+ ' npx --yes @shinick/outlook',
62
+ '',
63
+ 'If you are on an unsupported platform (for example Alpine/musl Linux),',
64
+ 'build from source with Cargo:',
65
+ ' cargo build --release',
66
+ ];
67
+ fail(lines.join('\n'));
68
+ }
69
+
70
+ // npm does not guarantee the executable bit survives packaging, so make sure
71
+ // the binary is runnable before spawning it (only chmod when X_OK is missing).
72
+ if (platform !== 'win32') {
73
+ try {
74
+ fs.accessSync(binaryPath, fs.constants.X_OK);
75
+ } catch {
76
+ try {
77
+ fs.chmodSync(binaryPath, 0o755);
78
+ } catch {
79
+ // Read-only install; spawn will report EACCES if the bit is missing.
80
+ }
81
+ }
82
+ }
83
+
84
+ const child = spawn(binaryPath, process.argv.slice(2), {
85
+ stdio: 'inherit',
86
+ windowsHide: false,
87
+ });
88
+
89
+ child.on('error', (err) => {
90
+ if (
91
+ platform === 'linux' &&
92
+ (err.code === 'ENOENT' || /GLIBC_/i.test(String(err.message || '')))
93
+ ) {
94
+ fail(
95
+ `failed to launch ${binaryPath}: ${err.message}\n\n${formatLinuxGlibcHint()}`,
96
+ );
97
+ }
98
+ fail(`failed to launch ${binaryPath}: ${err.message}`);
99
+ });
100
+
101
+ // Forward termination signals to the child process.
102
+ for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
103
+ const handler = () => {
104
+ if (!child.killed) {
105
+ try {
106
+ child.kill(signal);
107
+ } catch {
108
+ // Child already exited.
109
+ }
110
+ }
111
+ };
112
+ try {
113
+ process.on(signal, handler);
114
+ } catch {
115
+ // Signal not supported on this platform.
116
+ }
117
+ }
118
+
119
+ child.on('exit', (code, signal) => {
120
+ if (signal) {
121
+ const number = os.constants.signals[signal] || 1;
122
+ process.exit(128 + number);
123
+ }
124
+ if (platform === 'linux' && code === 127) {
125
+ process.stderr.write(
126
+ `outlook: binary exited with code 127 (missing shared library, dynamic linker, or GLIBC symbol version).\n${formatLinuxGlibcHint()}\n`,
127
+ );
128
+ }
129
+ process.exit(code === null ? 1 : code);
130
+ });
package/docs/NPM.md ADDED
@@ -0,0 +1,236 @@
1
+ # npm distribution
2
+
3
+ `@shinick/outlook` is distributed on npm as a small JavaScript launcher plus one
4
+ optional dependency per platform. The launcher resolves the prebuilt Rust binary
5
+ and execs it directly (with `scripts/postinstall.mjs` linking the native binary
6
+ into `bin/` and Windows shims for zero-Node-startup execution), so there is no
7
+ compiler, Node native addon, or network download during install.
8
+
9
+ The Rust crate is named `outlook-cli` and produces the pure **Microsoft Outlook**
10
+ binary (`outlook` / `outlook.exe`). The npm package is scoped as `@shinick/outlook`
11
+ and installs the **`outlook`** command.
12
+
13
+ ## Install and run
14
+
15
+ ```sh
16
+ # one-off
17
+ npx @shinick/outlook --version
18
+
19
+ # global install (installs `outlook`)
20
+ npm install -g @shinick/outlook
21
+ outlook --version
22
+
23
+ # project-local
24
+ npm install @shinick/outlook
25
+ npx outlook mail list
26
+ ```
27
+
28
+ All workflows share the same Microsoft Entra ID login (or automatic M365 shared-session
29
+ bootstrap with `teams-cli`), SQLite WAL + FTS5 cache (`cache.db`), background sync
30
+ daemon (`outlook daemon start | status | stop | restart`), HTTP API (`outlook serve`,
31
+ default `127.0.0.1:3939`), MCP server (`outlook mcp`), and multi-protocol terminal image
32
+ preview (`Kitty` / `iTerm2` / `Sixel` / `Halfblock` via `outlook preview` and the TUI).
33
+ Read commands also support `--cached` / `--fast` for instant local cache reads, or run
34
+ with zero Graph round-trips while the daemon is warm:
35
+
36
+ - `outlook login`, `outlook whoami`, `outlook doctor --online`
37
+ - `outlook folders`, `outlook mail --folder inbox --limit 30`, `outlook read <message_id>`
38
+ - `outlook send`, `outlook reply`, `outlook forward`, `outlook mark`, `outlook move`, `outlook archive`, `outlook delete`
39
+ - `outlook calendar --days 7`, `outlook event <id>`, `outlook create-event`, `outlook rsvp`, `outlook delete-event`
40
+ - `outlook contacts --query <q>`, `outlook task-lists`, `outlook tasks`, `outlook add-task`, `outlook done`, `outlook delete-task`
41
+ - `outlook search`, `outlook download`, `outlook preview`, `outlook sync`, `outlook daemon <start|status|stop|restart>`, `outlook tui`, `outlook serve`, `outlook mcp`, `outlook update`
42
+
43
+ ## Supported platforms
44
+
45
+ | npm package | OS | CPU | Rust target |
46
+ | ------------------------------- | ------- | ----- | ----------------------------------- |
47
+ | `@shinick/outlook-win32-x64` | Windows | x64 | `x86_64-pc-windows-msvc` |
48
+ | `@shinick/outlook-win32-arm64` | Windows | arm64 | `aarch64-pc-windows-msvc` |
49
+ | `@shinick/outlook-darwin-x64` | macOS | x64 | `x86_64-apple-darwin` |
50
+ | `@shinick/outlook-darwin-arm64` | macOS | arm64 | `aarch64-apple-darwin` |
51
+ | `@shinick/outlook-linux-x64` | Linux | x64 | `x86_64-unknown-linux-gnu` (2.28) |
52
+ | `@shinick/outlook-linux-arm64` | Linux | arm64 | `aarch64-unknown-linux-gnu` (2.28) |
53
+
54
+ Linux packages are cross-compiled in CI with `cargo-zigbuild` against **GLIBC 2.28** (`*.2.28`) and verified with `scripts/verify-glibc.mjs` plus an `almalinux:8` container smoke test, so prebuilt binaries run out of the box on **AlmaLinux 8 / RHEL 8+ / Rocky Linux 8+ / Ubuntu 20.04+ / Debian 10+**. Older glibc distributions (e.g., CentOS 7 with `GLIBC < 2.28`) and Alpine/musl Linux should build from source with Cargo (`cargo build --release`).
55
+
56
+ ## How resolution works
57
+
58
+ `bin/outlook.js` looks up `@shinick/outlook-<platform>-<arch>` through
59
+ `require.resolve`, then executes
60
+ `node_modules/@shinick/outlook-<platform>-<arch>/bin/outlook` (or `outlook.exe` on
61
+ Windows) with `stdio: 'inherit'`. On `npm install`, `scripts/postinstall.mjs`
62
+ additionally replaces `bin/outlook.js` (Unix) or rewrites `.bin/outlook[.cmd|.ps1]`
63
+ (Windows) to invoke the native Rust executable directly without spawning Node.
64
+ Signals (`SIGINT`, `SIGTERM`, `SIGHUP`) are forwarded and the launcher exits
65
+ with the child's exit code. If the platform package is missing (for example
66
+ because optional dependencies were skipped), the launcher prints the supported
67
+ platforms and the `--include=optional` hint instead of a stack trace.
68
+
69
+ ## Layout
70
+
71
+ ```
72
+ package.json # @shinick/outlook launcher package (bin: outlook)
73
+ bin/outlook.js # outlook launcher
74
+ scripts/postinstall.mjs # zero-Node native binary linker on npm install
75
+ outlook / outlook.cmd # repo-local Outlook launchers
76
+ npm/outlook-<platform>/ # one package per platform
77
+ package.json # os/cpu/files, same version as root
78
+ bin/outlook[.exe] # added by scripts/build-npm.mjs, never committed
79
+ scripts/build-npm.mjs # copy target/<triple>/release/outlook[.exe]
80
+ scripts/sync-version.mjs # Cargo.toml version -> all package.json files
81
+ scripts/verify-glibc.mjs # verify Linux ELF GLIBC <= 2.28 symbol ceiling
82
+ .github/workflows/release.yml # tag-triggered build, publish, GitHub Release
83
+ ```
84
+
85
+ Binaries are gitignored (`npm/*/bin/outlook*`). A clean checkout has empty
86
+ platform `bin/` directories until a build or `npm run build:npm` runs.
87
+
88
+ ## Versioning
89
+
90
+ `Cargo.toml` (`[package].version`) is the single source of truth. To bump:
91
+
92
+ ```sh
93
+ # edit Cargo.toml [package].version
94
+ node scripts/sync-version.mjs
95
+ ```
96
+
97
+ The script updates the root `package.json`, every `npm/outlook-*/package.json`,
98
+ and the root `optionalDependencies` pins. It is idempotent; `--check` exits
99
+ non-zero if anything is stale. All packages must be published at the same
100
+ version because the root package pins its platform packages exactly.
101
+
102
+ Tag the release with a matching `v` prefix:
103
+
104
+ ```sh
105
+ git tag v0.1.0
106
+ git push origin v0.1.0
107
+ ```
108
+
109
+ ## Publishing
110
+
111
+ Publishing is automated by `.github/workflows/release.yml`, which is triggered
112
+ by pushing a `v*` tag (or manually via `workflow_dispatch`).
113
+
114
+ 1. Add a repository secret `NPM_TOKEN` (an npm automation token with publish
115
+ rights for the `@shinick/outlook` packages).
116
+ 2. Bump the version in `Cargo.toml`, run `node scripts/sync-version.mjs`,
117
+ commit, and push `v<version>`.
118
+ 3. The workflow builds six targets, stages binaries into the platform
119
+ packages, uploads artifacts, publishes each platform package, publishes the
120
+ root package, and creates a GitHub Release with the archives, `outlook.exe`,
121
+ and `SHA256SUMS.txt`.
122
+
123
+ The publish job verifies that the tag matches the package version and that all
124
+ six platform packages contain a binary before publishing anything. Platform
125
+ packages are published first so the root package's `optionalDependencies` can
126
+ resolve immediately.
127
+
128
+ Manual publish (matching order):
129
+
130
+ ```sh
131
+ node scripts/sync-version.mjs --check
132
+ for dir in npm/outlook-*; do npm publish "$dir" --access public; done
133
+ npm publish --access public
134
+ ```
135
+
136
+ ## Local validation
137
+
138
+ ```sh
139
+ # stage the current host binary (Windows example)
140
+ node scripts/build-npm.mjs --target x86_64-pc-windows-msvc
141
+ node bin/outlook.js --version
142
+
143
+ npm pack --dry-run
144
+ npm pack --dry-run ./npm/outlook-win32-x64
145
+ ```
146
+
147
+ `node scripts/build-npm.mjs` with no arguments uses the host target and falls
148
+ back to `target/release/` when a plain `cargo build --release` was used.
149
+ `--all` attempts every supported target and warns about the ones not built on
150
+ the current host.
151
+
152
+ ## External token brokers, M365 bootstrap & token scopes
153
+
154
+ When using an external Microsoft Graph token broker (`tc-auth`, `az account get-access-token`, Vault CLI, etc.), configure `token_file` / `token_refresh_cmd` instead of shell wrappers (avoids `cmd.exe` 1023-char `set /p` truncation and `.ps1`/`.cmd` shim issues). Setting `OUTLOOK_TOKEN_FILE` (`token_file`) or `OUTLOOK_ACCESS_TOKEN` automatically skips OS keyring reads.
155
+
156
+ When `share_m365_auth = true` (default; `OUTLOOK_SHARE_M365_AUTH=true`), `outlook` can also bootstrap from an existing `TEAMS_TOKEN_FILE` or `teams-cli` stored session if no `outlook-cli` token is configured yet.
157
+
158
+ ### Required Microsoft Graph delegated scopes
159
+
160
+ Pure Outlook requests only Microsoft Outlook & Graph core scopes:
161
+
162
+ `offline_access`, `User.Read`, `User.ReadBasic.All`, `Mail.ReadWrite`, `Mail.Send`, `Calendars.ReadWrite`, `Contacts.ReadWrite`, `Tasks.ReadWrite`
163
+
164
+ Run `outlook whoami` or `outlook doctor` to inspect JWT `scp`/`roles` claims automatically.
165
+
166
+ ### 1. `config.toml` (recommended persistent setup)
167
+
168
+ ```toml
169
+ # Windows: %APPDATA%\outlook-cli\config.toml
170
+ # Linux/macOS: ~/.config/outlook-cli/config.toml
171
+ token_file = "~/.cursor/tc-auth/access_token"
172
+ token_refresh_cmd = "python ~/.cursor/tc-auth/graph-auth.py refresh"
173
+ token_refresh_mins = 5
174
+ ```
175
+
176
+ ### 2. Environment variables
177
+
178
+ ```sh
179
+ export OUTLOOK_TOKEN_FILE="$HOME/.cursor/tc-auth/access_token"
180
+ export OUTLOOK_TOKEN_REFRESH_CMD="python $HOME/.cursor/tc-auth/graph-auth.py refresh"
181
+ export OUTLOOK_TOKEN_REFRESH_MINS=5
182
+ ```
183
+
184
+ ### 3. Azure CLI (`az account get-access-token`) JSON/stdout integration
185
+
186
+ If `token_file` is omitted, `token_refresh_cmd` stdout (raw JWT or Azure CLI camelCase JSON `accessToken` / `expiresOn`) is parsed and cached in memory:
187
+
188
+ ```toml
189
+ token_refresh_cmd = "az account get-access-token --resource https://graph.microsoft.com --output json"
190
+ token_refresh_mins = 5
191
+ ```
192
+
193
+ ### Key environment variables
194
+
195
+ | Variable | Summary |
196
+ | --- | --- |
197
+ | `OUTLOOK_ACCESS_TOKEN` | Static Bearer token override (automatically skips OS keyring) |
198
+ | `OUTLOOK_TOKEN_FILE` | External token file path (raw JWT or JSON; skips OS keyring) |
199
+ | `OUTLOOK_TOKEN_REFRESH_CMD` | Shell command run to refresh expiring/`401` tokens |
200
+ | `OUTLOOK_TOKEN_REFRESH_MINS` | Refresh lead window in minutes before expiry (default `5`) |
201
+ | `OUTLOOK_SHARE_M365_AUTH` | Share/bootstrap M365 token session from `TEAMS_TOKEN_FILE` or `teams-cli` (default `true`) |
202
+ | `OUTLOOK_DISABLE_KEYRING=1` | Disable OS keyring and use `credentials.json` only |
203
+ | `OUTLOOK_CLIENT_ID` | Override Entra ID application client ID (falls back to `TEAMS_CLIENT_ID`, `AZURE_CLIENT_ID`) |
204
+ | `OUTLOOK_TENANT_ID` | Override Entra ID tenant ID (default `common`; falls back to `TEAMS_TENANT_ID`, `AZURE_TENANT_ID`) |
205
+ | `OUTLOOK_CONFIG_DIR` | Override config/credentials directory |
206
+ | `OUTLOOK_DATA_DIR` | Override SQLite cache (`cache.db`) directory |
207
+ | `OUTLOOK_NO_BROWSER` | Disable automatic browser launch during login (`1` / `true`) |
208
+ | `OUTLOOK_CLI_CACHE_SECS` | CLI read cache TTL in seconds (default `0`; `--cached` / `--fast` forces cache-first reads) |
209
+ | `OUTLOOK_AUTO_DAEMON` | Auto-start/attach to the background sync daemon (`1` / `true`, or `config.toml`: `auto_daemon = true`, default `false`) |
210
+ | `OUTLOOK_IMAGE_PROTOCOL` | Terminal image protocol override (`auto`, `kitty`, `iterm2`, `sixel`, `halfblock`) |
211
+ | `OUTLOOK_GITHUB_REPO` | Override GitHub `owner/repo` used by `outlook update` (default `shinick-dev/outlook`) |
212
+ | `OUTLOOK_GITHUB_TOKEN` | GitHub token for private release checks in `outlook update` |
213
+
214
+ ## Troubleshooting
215
+
216
+ - **`no prebuilt binary found for <platform>-<arch>`** — the optional
217
+ dependency was skipped. Reinstall with
218
+ `npm install -g @shinick/outlook --include=optional` or
219
+ `npm install @shinick/outlook --include=optional`. Check that your npm config
220
+ does not set `omit=optional`.
221
+ - **`EBADPLATFORM` / package skipped** — npm installs only the matching
222
+ `os`/`cpu` package. Cross-installing (for example x64 Node on ARM Windows via
223
+ emulation) still reports the Node architecture, so install under the native
224
+ Node build.
225
+ - **Older Linux (`GLIBC < 2.28`, e.g. CentOS 7) or Alpine/musl Linux** — prebuilt Linux binaries require **GLIBC >= 2.28** (AlmaLinux 8 / RHEL 8+ / Rocky Linux 8+ / Ubuntu 20.04+ / Debian 10+). On older glibc or musl systems, build from source with Cargo (`cargo build --release`).
226
+ - **macOS Gatekeeper** — npm-installed binaries are not notarized. If macOS
227
+ blocks execution, allow the binary in System Settings → Privacy & Security, or
228
+ build from source.
229
+ - **Corporate proxy/firewall** — `npx @shinick/outlook` performs a registry
230
+ download each time unless cached; use a global install for offline-friendly
231
+ use.
232
+ - **Verify the binary** —
233
+ `node -p "require.resolve('@shinick/outlook-win32-x64/package.json')"`
234
+ (adjust for your platform) shows which platform package npm selected.
235
+ - **Tag push did not publish** — check the publish job log; a tag/version
236
+ mismatch or a missing `NPM_TOKEN` fails the job before any publish.
package/package.json CHANGED
@@ -1,6 +1,46 @@
1
1
  {
2
2
  "name": "@shinick/outlook",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Microsoft Outlook terminal client & AI agent toolkit — Mail, Calendar, Tasks & Contacts (CLI, TUI, HTTP API, MCP)",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/shinick-dev/outlook.git"
8
+ },
9
+ "license": "MIT",
10
+ "bin": {
11
+ "outlook": "bin/outlook.js"
12
+ },
13
+ "files": [
14
+ "bin/outlook.js",
15
+ "scripts/postinstall.mjs",
16
+ "docs/NPM.md",
17
+ "README.md"
18
+ ],
19
+ "engines": {
20
+ "node": ">=18"
21
+ },
22
+ "keywords": [
23
+ "microsoft-outlook",
24
+ "outlook",
25
+ "microsoft-365",
26
+ "microsoft-graph",
27
+ "mail",
28
+ "calendar",
29
+ "cli",
30
+ "tui",
31
+ "mcp"
32
+ ],
33
+ "scripts": {
34
+ "postinstall": "node scripts/postinstall.mjs",
35
+ "sync-version": "node scripts/sync-version.mjs",
36
+ "build:npm": "node scripts/build-npm.mjs"
37
+ },
38
+ "optionalDependencies": {
39
+ "@shinick/outlook-win32-x64": "0.1.0",
40
+ "@shinick/outlook-win32-arm64": "0.1.0",
41
+ "@shinick/outlook-darwin-x64": "0.1.0",
42
+ "@shinick/outlook-darwin-arm64": "0.1.0",
43
+ "@shinick/outlook-linux-x64": "0.1.0",
44
+ "@shinick/outlook-linux-arm64": "0.1.0"
45
+ }
46
+ }
@@ -0,0 +1,266 @@
1
+ #!/usr/bin/env node
2
+ // Zero-Node-Process npm native binary linker.
3
+ //
4
+ // On Unix (linux/darwin): replaces installed `bin/outlook.js` with
5
+ // hardlinks/symlinks directly to `@shinick/outlook-<platform>-<arch>/bin/outlook` so npm's
6
+ // bin symlink execve's the native Rust binary directly (0ms Node startup, 0MB Node RSS).
7
+ //
8
+ // On Windows (win32): creates an NTFS hardlink (fallback copy) `bin/outlook.exe`
9
+ // and rewrites npm's `.bin/outlook[.cmd|.ps1]` shims when present to invoke
10
+ // `outlook.exe` directly without spawning `node.exe`.
11
+
12
+ import fs from 'node:fs';
13
+ import path from 'node:path';
14
+ import { createRequire } from 'node:module';
15
+ import { fileURLToPath } from 'node:url';
16
+
17
+ const BIN_NAMES = ['outlook'];
18
+ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
19
+
20
+ function linkOrCopyFile(source, destination) {
21
+ const tmp = `${destination}.tmp-${process.pid}`;
22
+ try {
23
+ fs.rmSync(tmp, { force: true });
24
+ } catch {
25
+ // Ignore cleanup errors on nonexistent temp paths.
26
+ }
27
+ try {
28
+ fs.linkSync(source, tmp);
29
+ } catch {
30
+ fs.copyFileSync(source, tmp);
31
+ }
32
+ try {
33
+ fs.renameSync(tmp, destination);
34
+ } catch {
35
+ try {
36
+ fs.rmSync(destination, { force: true });
37
+ } catch {
38
+ // Ignore; renameSync below will surface or fail safely.
39
+ }
40
+ fs.renameSync(tmp, destination);
41
+ }
42
+ }
43
+
44
+ function replaceJsWithNativeLinkUnix(binaryPath, destinationJs) {
45
+ const tmp = `${destinationJs}.tmp-${process.pid}`;
46
+ try {
47
+ fs.rmSync(tmp, { force: true });
48
+ } catch {
49
+ // Ignore cleanup errors.
50
+ }
51
+ try {
52
+ fs.linkSync(binaryPath, tmp);
53
+ } catch {
54
+ try {
55
+ fs.rmSync(tmp, { force: true });
56
+ } catch {
57
+ // Ignore cleanup errors.
58
+ }
59
+ fs.symlinkSync(binaryPath, tmp);
60
+ }
61
+ try {
62
+ fs.renameSync(tmp, destinationJs);
63
+ } catch (err) {
64
+ try {
65
+ fs.rmSync(tmp, { force: true });
66
+ } catch {
67
+ // Ignore cleanup errors.
68
+ }
69
+ throw err;
70
+ }
71
+ }
72
+
73
+ function collectWindowsShimDirs(pkgRoot, env = process.env) {
74
+ const dirs = [];
75
+ const parentScope = path.dirname(pkgRoot);
76
+ const nodeModulesDir = path.dirname(parentScope);
77
+ if (
78
+ path.basename(parentScope) === '@shinick' &&
79
+ path.basename(nodeModulesDir) === 'node_modules'
80
+ ) {
81
+ dirs.push(path.join(nodeModulesDir, '.bin'));
82
+ // On global Windows npm installs (`%APPDATA%\npm\node_modules\@shinick\outlook`),
83
+ // shims sit directly in the parent of `node_modules` even when `npm_config_prefix` is unset in npm v9+.
84
+ dirs.push(path.dirname(nodeModulesDir));
85
+ }
86
+
87
+ if (env.npm_config_global === 'true' && env.npm_config_prefix) {
88
+ const prefix = path.resolve(env.npm_config_prefix);
89
+ dirs.push(prefix);
90
+ dirs.push(path.join(prefix, 'bin'));
91
+ }
92
+
93
+ return [...new Set(dirs)];
94
+ }
95
+
96
+ function shimReferencesLauncher(content, name) {
97
+ const normalized = content.replace(/\\/g, '/').toLowerCase();
98
+ return (
99
+ normalized.includes('@shinick/outlook') &&
100
+ normalized.includes(`bin/${name}.js`)
101
+ );
102
+ }
103
+
104
+ function rewriteWindowsShims(shimDir, pkgRoot) {
105
+ if (!fs.existsSync(shimDir)) return 0;
106
+ let rewritten = 0;
107
+
108
+ for (const name of BIN_NAMES) {
109
+ const exePath = path.join(pkgRoot, 'bin', `${name}.exe`);
110
+ if (!fs.existsSync(exePath)) continue;
111
+
112
+ const relWin = path.relative(shimDir, exePath).replace(/\//g, '\\');
113
+ const relPosix = path.relative(shimDir, exePath).replace(/\\/g, '/');
114
+
115
+ // 1. `<name>.cmd`
116
+ const cmdPath = path.join(shimDir, `${name}.cmd`);
117
+ try {
118
+ if (fs.existsSync(cmdPath)) {
119
+ const content = fs.readFileSync(cmdPath, 'utf8');
120
+ if (shimReferencesLauncher(content, name)) {
121
+ fs.writeFileSync(cmdPath, `@ECHO off\r\n"%~dp0${relWin}" %*\r\n`, 'utf8');
122
+ rewritten += 1;
123
+ }
124
+ }
125
+ } catch {
126
+ // Fall back cleanly to bin/<name>.js if shim is read-only or locked.
127
+ }
128
+
129
+ // 2. `<name>.ps1`
130
+ const ps1Path = path.join(shimDir, `${name}.ps1`);
131
+ try {
132
+ if (fs.existsSync(ps1Path)) {
133
+ const content = fs.readFileSync(ps1Path, 'utf8');
134
+ if (shimReferencesLauncher(content, name)) {
135
+ const ps1Body = [
136
+ '#!/usr/bin/env pwsh',
137
+ '$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent',
138
+ `$exePath = Join-Path $basedir '${relWin.replace(/'/g, "''")}'`,
139
+ 'if ($MyInvocation.ExpectingInput) {',
140
+ ' $input | & $exePath @args',
141
+ '} else {',
142
+ ' & $exePath @args',
143
+ '}',
144
+ 'exit $LASTEXITCODE',
145
+ '',
146
+ ].join('\n');
147
+ fs.writeFileSync(ps1Path, ps1Body, 'utf8');
148
+ rewritten += 1;
149
+ }
150
+ }
151
+ } catch {
152
+ // Fall back cleanly.
153
+ }
154
+
155
+ // 3. `<name>` (Git Bash / MSYS2 POSIX shell shim)
156
+ const shPath = path.join(shimDir, name);
157
+ try {
158
+ if (fs.existsSync(shPath)) {
159
+ const content = fs.readFileSync(shPath, 'utf8');
160
+ if (shimReferencesLauncher(content, name)) {
161
+ const shBody = [
162
+ '#!/bin/sh',
163
+ 'basedir=$(dirname "$(echo "$0" | sed -e \'s,\\\\,/,g\')")',
164
+ `exec "$basedir/${relPosix}" "$@"`,
165
+ '',
166
+ ].join('\n');
167
+ fs.writeFileSync(shPath, shBody, 'utf8');
168
+ rewritten += 1;
169
+ }
170
+ }
171
+ } catch {
172
+ // Fall back cleanly.
173
+ }
174
+ }
175
+
176
+ return rewritten;
177
+ }
178
+
179
+ export function runPostinstall(options = {}) {
180
+ const pkgRoot = path.resolve(options.pkgRoot || PKG_ROOT);
181
+ const platform = options.platform || process.platform;
182
+ const arch = options.arch || process.arch;
183
+ const env = options.env || process.env;
184
+
185
+ // CRITICAL SAFETY GUARD: Never mutate files inside the git development repository.
186
+ if (
187
+ fs.existsSync(path.join(pkgRoot, 'Cargo.toml')) ||
188
+ fs.existsSync(path.join(pkgRoot, '.git'))
189
+ ) {
190
+ return { skipped: true, reason: 'dev_repo' };
191
+ }
192
+
193
+ const platformKey = `${platform}-${arch}`;
194
+ const packageName = `@shinick/outlook-${platformKey}`;
195
+ const binaryName = platform === 'win32' ? 'outlook.exe' : 'outlook';
196
+
197
+ let packageDir = null;
198
+ try {
199
+ const requireFromPkg = createRequire(path.join(pkgRoot, 'package.json'));
200
+ packageDir = path.dirname(requireFromPkg.resolve(`${packageName}/package.json`));
201
+ } catch {
202
+ packageDir = null;
203
+ }
204
+
205
+ const binaryPath = packageDir ? path.join(packageDir, 'bin', binaryName) : null;
206
+ if (!binaryPath || !fs.existsSync(binaryPath)) {
207
+ return { skipped: true, reason: 'missing_platform_binary' };
208
+ }
209
+
210
+ const binDir = path.join(pkgRoot, 'bin');
211
+ if (!fs.existsSync(binDir)) {
212
+ return { skipped: true, reason: 'missing_bin_dir' };
213
+ }
214
+
215
+ if (platform === 'win32') {
216
+ let linked = 0;
217
+ for (const name of BIN_NAMES) {
218
+ const destExe = path.join(binDir, `${name}.exe`);
219
+ try {
220
+ linkOrCopyFile(binaryPath, destExe);
221
+ linked += 1;
222
+ } catch {
223
+ // Leave fallback JS launcher untouched.
224
+ }
225
+ }
226
+
227
+ let shimsRewritten = 0;
228
+ for (const shimDir of collectWindowsShimDirs(pkgRoot, env)) {
229
+ try {
230
+ shimsRewritten += rewriteWindowsShims(shimDir, pkgRoot);
231
+ } catch {
232
+ // Never fail npm install on read-only or custom shims.
233
+ }
234
+ }
235
+ return { skipped: false, platform, linked, shimsRewritten };
236
+ }
237
+
238
+ // Unix (linux, darwin): chmod once and replace bin/*.js with hardlink/symlink to native binary.
239
+ try {
240
+ fs.chmodSync(binaryPath, 0o755);
241
+ } catch {
242
+ // Ignore on read-only stores.
243
+ }
244
+
245
+ let linked = 0;
246
+ for (const name of BIN_NAMES) {
247
+ const destJs = path.join(binDir, `${name}.js`);
248
+ try {
249
+ replaceJsWithNativeLinkUnix(binaryPath, destJs);
250
+ linked += 1;
251
+ } catch {
252
+ // Leave fallback JS launcher intact.
253
+ }
254
+ }
255
+
256
+ return { skipped: false, platform, linked };
257
+ }
258
+
259
+ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
260
+ try {
261
+ runPostinstall();
262
+ } catch {
263
+ // Postinstall optimization must never fail npm install.
264
+ }
265
+ process.exit(0);
266
+ }