@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 +503 -2
- package/bin/outlook.js +130 -0
- package/docs/NPM.md +236 -0
- package/package.json +44 -4
- package/scripts/postinstall.mjs +266 -0
package/README.md
CHANGED
|
@@ -1,3 +1,504 @@
|
|
|
1
|
-
#
|
|
1
|
+
# outlook (Pure Microsoft Outlook CLI · TUI · HTTP API · MCP)
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|