feat: outlook-cli — cross-platform Outlook CLI with multi-account, encrypted auth, and AI agent integration

.env.example

@@ -0,0 +1,19 @@
+# Outlook CLI Configuration
+# Copy this to .env and fill in your values
+
+# Azure App Registration client ID (required)
+OUTLOOK_CLI_CLIENT_ID=your-client-id-here
+
+# Azure AD tenant ID (default: "common" for multi-tenant)
+# Use "consumers" for personal Microsoft accounts only
+# Use "organizations" for work/school accounts only
+# Use a specific tenant GUID for single-tenant apps
+OUTLOOK_CLI_TENANT_ID=common
+
+# Passphrase for encrypting token cache (optional)
+# If not set, a machine-derived passphrase is used automatically
+# Set this if you want to share token caches across machines
+# OUTLOOK_CLI_PASSPHRASE=your-secure-passphrase
+
+# Log level: error, warn, info, debug (default: warn)
+OUTLOOK_CLI_LOG_LEVEL=warn

.github/copilot-instructions.md

@@ -0,0 +1,120 @@
+# Copilot Instructions — outlook-cli
+
+> **For comprehensive agent documentation**, see the `agents/` directory:
+> `agents/ARCHITECTURE.md`, `agents/BUILDING.md`, `agents/MAKING-CHANGES.md`,
+> `agents/TESTING.md`, `agents/REAL-WORLD-VALIDATION.md`, `agents/COMMON-PITFALLS.md`
+
+## Build, Test, Lint
+
+```bash
+npm install                              # Install dependencies
+npm test                                 # Run all tests (vitest)
+npm run test:verbose                     # Detailed test output
+npx vitest run test/node/security/crypto.test.js  # Run a single test file
+npx vitest run -t "should encrypt"       # Run tests matching a name
+npm run test:watch                       # Watch mode (re-runs on save)
+npm run test:coverage                    # Coverage report
+```
+
+The C# implementation builds separately:
+
+```bash
+dotnet build src/dotnet                  # Build C# implementation
+```
+
+CLI integration tests can run against either implementation:
+
+```bash
+OUTLOOK_CLI_BIN="dotnet run --project src/dotnet" npm test
+```
+
+No linter is configured. No build step is needed for Node.js — it runs directly as ES modules.
+
+## Architecture
+
+This is a CLI for Microsoft Outlook (email + calendar) via the Microsoft Graph API. It has two implementations — a **Node.js reference implementation** (`src/node/`) and a **C# optimized implementation** (`src/dotnet/`) — that share the same command structure, file formats, and CLI integration test suite.
+
+### Request flow
+
+```
+bin/outlook-cli.js → src/node/cli/index.js (Commander.js program)
+  → src/node/cli/{mail,calendar,contacts,auth,account,watch}.js (command handlers)
+    → src/node/graph/client.js (GraphClient: auth, retry, rate-limit, pagination)
+      → src/node/auth/msal-client.js → src/node/auth/token-cache.js → src/node/security/crypto.js
+      → src/node/security/token-validator.js (defense-in-depth scope check on EVERY request)
+      → src/node/graph/{mail,calendar,contacts,delta}.js (Graph API endpoints)
+    → src/node/output/render.js → src/node/output/{formatter,markdown,html}.js
+```
+
+### Output dispatch (Strategy pattern)
+
+`render.js` dispatches to format-specific modules (`formatter.js`, `markdown.js`, `html.js`). Each module exports functions named after entity types (`mailList`, `mailDetail`, `eventList`, etc.). The `output()` helper resolves the format, renders, and writes to stdout or file.
+
+### Delegate access
+
+`GraphClient.userPath` returns `/me` for own account or `/users/{email}` for delegate access (`--as` flag). All Graph API modules prepend `userPath` to their endpoint paths.
+
+### Watch mode
+
+Uses Microsoft Graph delta queries (not webhooks). Single-account mode stores delta tokens in `~/.outlook-cli/delta-{alias}.json`. Multi-job mode (`--config watches.json`) runs multiple watches with independent schedules, rule-based condition matching, and action execution (move, mark-read, flag, run commands, channel delivery).
+
+### Configurable permissions
+
+Accounts.json supports a `defaults` block inherited by all accounts, `parent` chains for hierarchical config, and `+`/`-` modifiers on allowed/forbidden scope lists. `send_to` whitelists restrict recipients per-account.
+
+### Operation logging (SQLite)
+
+`src/node/db/database.js` manages `~/.outlook-cli/outlook-cli.db` (WAL mode). `src/node/db/logger.js` provides correlation-ID-based operation logging (start/complete/fail).
+
+### Telemetry
+
+`src/node/telemetry/collector.js` provides an in-memory ring buffer (1000 events), optional SQLite persistence, and process snapshots. Disabled by default; enable via `OUTLOOK_CLI_TELEMETRY=1`.
+
+### Node.js ↔ C# interoperability
+
+Both implementations use identical file formats in `~/.outlook-cli/`:
+- `cache-{alias}.enc` — AES-256-GCM encrypted MSAL token cache (binary: salt(32) + iv(16) + authTag(16) + ciphertext)
+- `accounts.json`, `aliases.json`, `config.json`, `delta-{alias}.json`
+
+The encryption uses PBKDF2-SHA512 with 310,000 iterations. A cache encrypted by Node.js decrypts in C# and vice versa.
+
+## Key Conventions
+
+### Security — CRITICAL
+
+- **`Mail.ReadWrite.All` is a FORBIDDEN scope** — application-level access to all mailboxes is never allowed. `Mail.Send` and `Mail.Send.Shared` are both allowed. The permissions system (configurable via accounts.json) can restrict per-account.
+- `validateTokenScopes()` in `src/node/security/token-validator.js` runs on **every token acquisition** as defense-in-depth. It checks both the MSAL result's scopes array and the decoded JWT `scp` claim.
+- Personal Microsoft accounts return opaque (non-JWT) tokens. Token validators must handle this gracefully (return valid, validate via MSAL scopes array instead).
+
+### Module patterns
+
+- **ESM only** (`"type": "module"`). All imports must use `.js` extensions.
+- **Named exports only** — no default exports. Use `export function` or `export { name }`.
+- **Factory functions** for stateful objects: `createGraphClient()`, `createMsalClient()`, `createCachePlugin()`.
+- **Singleton with reset**: `AccountManager` uses `getAccountManager()` / `resetAccountManager()` (reset is for test isolation).
+
+### Error handling
+
+- Throw immediately for validation errors with actionable context (e.g., "Run `outlook-cli auth login` to authenticate").
+- Network retry: 401 → clear token cache + retry; 429 → wait `Retry-After` seconds + retry; other errors → throw.
+- Decryption failures degrade gracefully (log warning, start with empty cache, user re-authenticates).
+
+### Config resolution (last wins)
+
+1. Hardcoded defaults → 2. Environment variables → 3. `~/.outlook-cli/config.json` → 4. Per-account settings in `accounts.json` → 5. CLI flags.
+
+Config file intentionally overrides env vars (see `Object.assign` in `src/node/config.js`).
+
+### Testing conventions
+
+- **Vitest** with Jest-compatible API (`describe`/`it`/`expect`/`vi.mock()`).
+- Test files organized by category: `test/node/<module>/`, `test/dotnet/`, `test/shared/`, `test/stress/`.
+- Stress tiers: `test/stress/scale/` (@stress), `test/stress/integrity/` (@stress), `test/stress/performance/` (@perf), `test/stress/soak/` (@soak).
+- Tests are fully offline — no network calls, no real Microsoft auth. Mock external dependencies with `vi.mock()`.
+- Crypto tests use **real encryption** (not mocks) — expect ~300ms overhead per test.
+- Tests that write to disk create unique temp directories and clean up in `afterEach`.
+- Test names use `should <expected behavior>` format.
+
+### Input merging
+
+Commands support `--input <file>` for JSON parameter files. **CLI flags always override JSON values.** `bodyFile` takes priority over inline `body`. HTML content type is auto-detected from `.html`/`.htm` file extensions.

.github/workflows/ci.yml

@@ -0,0 +1,130 @@
+# CI — Unit Tests + NativeAOT Build
+#
+# Runs on every push and PR. Fast feedback loop (~2-3 min).
+# - Node.js unit tests on Ubuntu + Windows
+# - C# build + NativeAOT publish on Windows
+# - Test report generation and artifact upload
+#
+# Integration tests (requiring M365 credentials) run separately
+# via integration.yml on manual dispatch or nightly schedule.
+
+name: CI
+
+on:
+  push:
+    branches: [main, 'feature/**']
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ── Node.js Unit Tests ────────────────────────────────────────────────
+  unit-tests:
+    name: Unit Tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        node-version: [22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests
+        run: npm run test:ci
+
+      - name: Generate test report
+        if: always()
+        run: npm run test:report:markdown > test-results/report.md 2>&1 || true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-${{ matrix.os }}
+          path: test-results/
+          retention-days: 30
+
+      - name: Post test summary to PR
+        if: always() && github.event_name == 'pull_request'
+        run: |
+          if [ -f test-results/report.md ]; then
+            echo "## 🧪 Test Results (${{ matrix.os }})" >> $GITHUB_STEP_SUMMARY
+            cat test-results/report.md >> $GITHUB_STEP_SUMMARY
+          fi
+        shell: bash
+
+  # ── C# Build ──────────────────────────────────────────────────────────
+  dotnet-build:
+    name: C# Build
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 8.0.x
+
+      - name: Restore dependencies
+        run: dotnet restore src/dotnet/OutlookCli.csproj
+
+      - name: Build (Debug)
+        run: dotnet build src/dotnet/OutlookCli.csproj --no-restore -warnaserror-
+
+      - name: Verify CLI help
+        run: dotnet run --project src/dotnet -- --help
+
+  # ── NativeAOT Publish ─────────────────────────────────────────────────
+  nativeaot:
+    name: NativeAOT (${{ matrix.rid }})
+    runs-on: ${{ matrix.os }}
+    needs: dotnet-build
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: windows-latest
+            rid: win-x64
+            ext: .exe
+          - os: ubuntu-latest
+            rid: linux-x64
+            ext: ""
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 8.0.x
+
+      - name: Publish NativeAOT
+        run: >
+          dotnet publish src/dotnet/OutlookCli.csproj
+          -r ${{ matrix.rid }}
+          --self-contained
+          /p:PublishAot=true
+          -o publish/${{ matrix.rid }}
+
+      - name: Verify binary runs
+        run: ./publish/${{ matrix.rid }}/outlook-cli${{ matrix.ext }} --help
+        shell: bash
+
+      - name: Upload binary
+        uses: actions/upload-artifact@v4
+        with:
+          name: outlook-cli-${{ matrix.rid }}
+          path: publish/${{ matrix.rid }}/
+          retention-days: 90