ask-marcel-office-cli 1.5.2 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,134 @@
 
 All notable changes to `ask-marcel-office-cli` are documented here.
 
+## 2.1.0
+
+### Added
+
+- **`create-forward-draft`** creates an UNSENT forward draft of an existing
+  message. `POST /me/messages/{id}/createForward` mints the draft (`FW:` subject,
+  quoted original) with your comment placed above the quote and the recipients
+  set, in one call (`Mail.ReadWrite`, already on the basic token).
+  `--to-recipients` is required (a forward with no recipient is not actionable);
+  `--cc-recipients` and a `--subject` override are optional. Like the other
+  mail-draft commands, it produces an UNSENT draft only; the CLI can never send.
+  This is the fourth and last write command, closing the "forward to the right
+  owner" gap that `create-reply-draft` (in-thread) could not.
+- **`convert-local-file --include-images`** (a `.zip` only) also extracts every
+  archive entry's embedded images (docx/xlsx/pptx OOXML media parts, pdf page
+  images), so a screenshot pasted inside a zipped document is reachable in one
+  call.
+- **`login` now reports all four cached tokens** (basic, elevated/M365, and the
+  two Teams-chat substrate tokens chatsvcagg / ic3) with each one's time-left and
+  refresh route, so running `login` while already signed in shows the full token
+  picture instead of a bare `{ status: "authenticated" }`. Each token is
+  `{ available, expiresInSeconds?, refresh: "automatic" | "interactive", reason? }`:
+  basic/chatsvcagg/ic3 refresh automatically from the cached refresh token; the
+  elevated token is `interactive` (re-captured only on a browser login).
+- **`login --force`** ignores the cache and re-captures every token via the
+  browser in one pass — the only way to refresh the elevated token while the
+  basic token is still valid. The persistent browser profile is reused, so you
+  are usually not re-prompted for credentials.
+- **`scopes-check` now reports the elevated (M365ChatClient) token** plus the two
+  Teams-chat substrate tokens (`chatsvcagg` / `ic3`), each in an
+  `{ available, expiresInSeconds? }` block, so a fresh process can pre-flight the
+  historical-version download / convert commands instead of discovering a 403
+  mid-run. The two substrate blocks are additive; the existing top-level fields
+  are unchanged.
+- **Machine-readable `errorCode`s on more error paths** — the elevated /
+  substrate fail-fast (`secondary_token_unavailable`) and the client-side
+  unsupported-input rejections (`unsupported_image` / `unsupported_format` /
+  `unsupported_legacy_office` / `unsupported_document`), so an agent branches on
+  a stable code instead of substring-matching the message.
+
+### Fixed
+
+- **`create-forward-draft` and `create-reply-draft` no longer drop the forwarded
+  / quoted body.** They set the comment via Graph's `comment` parameter on the
+  `createForward` / `createReplyAll` POST, which places it above the preserved
+  quote. The previous implementation PATCHed `body` with only the comment, which
+  **replaced** the whole draft body and dropped the entire forwarded original (a
+  forward went out with just the comment, no message). Caught by a live smoke
+  test; the fix is live-verified.
+
+### Changed
+
+- The `parseRecipients` helper shared by the mail-draft write commands moved to
+  `parse-recipients.ts` (one definition, three call sites), with no behaviour
+  change.
+- `scopes-check` `responseShape` corrected: `elevated.expiresInSeconds` is
+  omitted (the key is absent) when no elevated token is cached, not `null`.
+
+### Removed
+
+- The `--body-content-type` flag on **`create-forward-draft` and
+  `create-reply-draft`** is removed. It never affected the quoted body (Graph
+  embeds the comment / reply as text above the quote), so it was a no-op on those
+  two commands. It remains on `create-mail-draft` and `update-mail-draft`, which
+  set the body directly.
+
+## 2.0.0
+
+Breaking auth simplification, a repo-wide privacy scrub (including a rewrite of
+the full git history), two new commands, and a headless self-heal for the Teams
+chat-substrate tokens.
+
+### BREAKING
+
+- **The CLI binary is renamed `ask-marcel` → `ask-marcel-office`** (matching the
+  package name; the bare `ask-marcel` name is freed for future use and no longer
+  ships as an alias). Update shell scripts, agent prompts, and skills that invoke
+  the old name. npm removes the stale `ask-marcel` bin link on upgrade; if one
+  lingers (e.g. bun global installs), delete it manually.
+- **`ask-marcel login --use-extension` is removed.** The companion browser
+  extension and the system-browser / localhost-callback capture path are gone
+  (`browser-extension/`, the `system-browser-auth` + `token-callback-server`
+  infra, and the `--use-extension` flag). `ask-marcel-office login` — a
+  Playwright-driven Edge/Chrome window that captures all four tokens in one
+  session — is the only login flow. The token cache format is unchanged;
+  existing sessions keep working without re-login.
+
+### Added
+
+- **`get-schedule`** — free/busy availability for a comma-separated list of
+  people and/or meeting rooms over a time window
+  (`POST /me/calendar/getSchedule`, `Calendars.Read` — already on the basic
+  token). Returns each person's `availabilityView` slot string (0 free /
+  1 tentative / 2 busy / 3 OOF / 4 working-elsewhere), the underlying busy
+  blocks, and their working hours. Both bounds accept the relative-date
+  vocabulary (`today`, `+1d`, `start-of-week`, …).
+- **`create-reply-draft`** — create a threaded reply-all draft to an existing
+  message (`createReplyAll` + a body patch), so an agent can prepare a response
+  in-thread. Produces an UNSENT draft only — like `create-mail-draft` /
+  `update-mail-draft`, the CLI can never send. (Third and last write command.)
+- **Teams substrate tokens now self-heal on the command path.** When a
+  chatsvcagg or ic3 token lapses (~hourly), the CLI redeems the shared Teams
+  refresh token for that substrate audience over HTTP — headless, no browser —
+  instead of dead-ending in a "run `ask-marcel-office login`" error. The four
+  Teams chat commands (`list-teams-chats-with-messages`, `list-teams-chat-messages`,
+  `get-teams-chat-message`, `find-chats-with-user`) plus `list-teams-chat-history`
+  now keep working for as long as your Graph token does, rather than dying an hour
+  into a session. Falls back to the interactive-login prompt only when no refresh
+  token is cached or Entra ID rejects the redemption. The elevated token
+  (historical-version downloads) is unaffected — a different app identity with no
+  shared-RT path — and still needs `login` when it lapses.
+
+### Changed
+
+- The npm tarball no longer double-ships the ~500 KB command manifest:
+  `docs/commands.json` was dropped from `files[]` (the importable
+  `ask-marcel-office-cli/commands.json` subpath still resolves to
+  `dist/commands.json`, which remains). Unpacked size ~3.5 → ~3.0 MB.
+
+### Internal
+
+- Privacy scrub: personal/tenant fixture data and internal audit-session
+  labels removed across source, tests, fixtures, and docs — and purged from
+  the entire git history (rewritten and force-pushed).
+- Dead code removed: the single-token browser capture (`acquireToken`), two
+  orphan probe scripts, an unused env module; the four graph-client
+  auth-header closures collapsed into one factory.
+
 ## 1.5.2
 
 ### Fixed
@@ -29,9 +157,11 @@ All notable changes to `ask-marcel-office-cli` are documented here.
   each launched a _visible_ browser that "opens and closes within seconds" to
   silently re-capture — per command, per process, with no cross-process throttle —
   so after the short-lived elevated token (~59 min) expired, every elevated or
-  Teams-chat command popped a window. The command-path auth now **fails fast** with
-  an actionable "run `ask-marcel login`" instead; browser capture is reserved for
-  the explicit `login` command, which re-captures all four tokens in one session.
+  Teams-chat command popped a window. The command-path auth now **self-heals** the
+  chat-substrate tokens with a headless refresh of the shared Teams RT (and, when
+  that can't renew them, fails fast with an actionable "run `ask-marcel-office
+  login`") instead; interactive browser capture is reserved for the explicit
+  `login` command, which re-captures all four tokens in one session.
 
 ## 1.5.0
 

package/README.md

@@ -1,12 +1,12 @@
 # ask-marcel-office-cli
 
-**A Microsoft Graph CLI built for LLMs.** 177 commands across Mail, Calendar, OneDrive, SharePoint, Excel, Teams chats, Planner / To-Do, OneNote, and directory — plus local-file tools (markdown conversion, image extraction) that need no sign-in at all. Sign in once with your Microsoft 365 account — no Azure app registration, no admin consent, no client secrets.
+**A Microsoft Graph CLI built for LLMs.** 180 commands across Mail, Calendar, OneDrive, SharePoint, Excel, Teams chats, Planner / To-Do, OneNote, and directory — plus local-file tools (markdown conversion, image extraction) that need no sign-in at all. Sign in once with your Microsoft 365 account — no Azure app registration, no admin consent, no client secrets.
 
 ```bash
 npm i -g ask-marcel-office-cli
-ask-marcel login                 # browser opens once, token cached
-ask-marcel my-quick-context      # who am I + my IDs, in one round trip
-ask-marcel list-mail-messages --top 5
+ask-marcel-office login                 # browser opens once, token cached
+ask-marcel-office my-quick-context      # who am I + my IDs, in one round trip
+ask-marcel-office list-mail-messages --top 5
 ```
 
 ---
@@ -19,13 +19,13 @@ LLM tool-loops keep hitting the same three walls with Microsoft Graph:
 2. **Default payloads are tuned for backend services, not context windows.** Listing endpoints return every field on every item, used-range Excel calls return four redundant 2D arrays, attachment endpoints inline base64 by default. An agent that reads "what's in my inbox" without trimming burns its budget on metadata it never needed.
 3. **Errors are opaque.** `BadRequest: Invalid filter clause` doesn't tell a model what to fix.
 
-`ask-marcel` fixes all three at the CLI layer, so the model just calls commands and reads back-pressure-friendly responses.
+`ask-marcel-office` fixes all three at the CLI layer, so the model just calls commands and reads back-pressure-friendly responses.
 
 ## What you get
 
 ### Read-only by design
 
-**This is the most important property.** 173 GET endpoints + 2 POST (searches) + 1 POST (create draft) + 1 PATCH (update draft) = 177 commands. No `send-mail`, no `create-event`, no `upload-file`, no `delete-anything`. The only write operations are draft creation and update — a hallucinated command can at most create an unsent draft in your Drafts folder. Safe default for autonomous agents, MCP servers, and "let Claude poke around my mailbox" sessions where you can't fully review every tool call.
+**This is the most important property.** 173 GET endpoints + 3 read-only POST (two searches + free/busy lookup) + 3 POST (create mail draft / threaded reply draft / forward draft) + 1 PATCH (update draft) = 180 commands. No `send-mail`, no `create-event`, no `upload-file`, no `delete-anything`. The only write operations are draft creation (a new mail, a threaded reply-all, or a forward) and update — a hallucinated command can at most create an unsent draft in your Drafts folder. Safe default for autonomous agents, MCP servers, and "let Claude poke around my mailbox" sessions where you can't fully review every tool call.
 
 ### One call gets the full email context
 
@@ -56,7 +56,7 @@ Pass `--include-metadata true` on any `*-as-markdown` (or `convert-mail-attachme
 
 ### Extract embedded images from documents
 
-`extract-drive-item-images` (OneDrive / SharePoint), `extract-mail-attachment-images` (Outlook attachments), and `extract-local-file-images` (a file **on disk** — no Graph, no login) pull the embedded images out of a **docx, xlsx, pptx, or pdf**. For Office files it reads the OOXML media parts (png/jpg/gif/bmp/tiff/webp/svg) — including original full-resolution / un-cropped originals and images on hidden slides that the rendered view never shows. SVG rides back as its XML source (which carries the diagram's own text labels); legacy vector (emf/wmf) and audio/video are skipped. For a PDF it walks every page via [unpdf](https://github.com/unjs/unpdf) (a pure-JS, no-native-deps pdf.js build) and re-encodes each painted image as PNG — page-oriented, so it captures images as drawn on each page (it does not reach layer-hidden/unpainted XObjects or the full uncropped original behind a clipped image). Pair with the global `--output-dir <dir>` to write every image to a folder (the directory is auto-created and each `base64` becomes a `savedTo` path); without it the bytes ride back base64-encoded so a vision model can read them directly.
+`extract-drive-item-images` (OneDrive / SharePoint), `extract-mail-attachment-images` (Outlook attachments), and `extract-local-file-images` (a file **on disk** — no Graph, no login) pull the embedded images out of a **docx, xlsx, pptx, or pdf**. For Office files it reads the OOXML media parts (png/jpg/gif/bmp/tiff/webp/svg) — including original full-resolution / un-cropped originals and images on hidden slides that the rendered view never shows. SVG rides back as its XML source (which carries the diagram's own text labels); legacy vector (emf/wmf) and audio/video are skipped. For a PDF it walks every page via [unpdf](https://github.com/unjs/unpdf) (a pure-JS, no-native-deps pdf.js build) and re-encodes each painted image as PNG — page-oriented, so it captures images as drawn on each page (it does not reach layer-hidden/unpainted XObjects or the full uncropped original behind a clipped image). Pair with the global `--output-dir <dir>` to write every image to a folder (the directory is auto-created and each `base64` becomes a `savedTo` path); without it the bytes ride back base64-encoded so a vision model can read them directly. The same OOXML / PDF image extraction runs over every file **inside a `.zip`** when you pass `convert-local-file --include-images true`: each archive entry gains an `images` array, so a screenshot pasted into a zipped document is still reachable in one call.
 
 The CLI follows any SharePoint media-transform redirect internally, so the LLM never has to fetch an external URL.
 
@@ -68,21 +68,13 @@ The CLI follows any SharePoint media-transform redirect internally, so the LLM n
 
 No Azure app, no tenant admin. The CLI captures the same token the Teams web client uses — works for any Microsoft 365 account, personal or enterprise.
 
-**Login flow:** By default, the CLI uses Playwright to open a browser for authentication. Alternatively, you can use the [Ask Marcel Companion](./browser-extension/) browser extension for faster authentication.
+**Login flow:** the CLI drives a Playwright-launched Edge/Chrome window through the Teams sign-in, captures the tokens, and caches them at `~/.ask-marcel/token-cache.json` (0600). Running `login` again (even when already signed in) reports all four cached tokens — basic, elevated (M365), and the two Teams-chat substrate tokens (chatsvcagg / ic3) — each with its time-left and refresh route: basic/chatsvcagg/ic3 refresh automatically from the cached refresh token, while the elevated token is re-captured only on an interactive login. `login --force` ignores the cache and re-captures every token in one browser pass (the persistent profile is reused, so you are usually not re-prompted for credentials) — the only way to refresh the elevated token while the basic one is still valid. `scopes-check` reports the same four tokens without opening a browser.
 
 ```bash
-ask-marcel login              # default: Playwright browser
-ask-marcel login --use-extension  # use browser extension (requires setup)
+ask-marcel-office login          # sign in, or show all four tokens' status if already signed in
+ask-marcel-office login --force  # re-capture every token, ignoring the cache
 ```
 
-**Browser extension setup (optional, one-time):**
-
-1. Open `chrome://extensions/` (Chrome) or `edge://extensions/` (Edge)
-2. Enable "Developer mode" (top-right toggle)
-3. Click "Load unpacked" → select the `browser-extension/` folder from this repo
-4. **Enable in incognito/inprivate mode:** Click the extension's "Details" button, then enable "Allow in incognito" (Chrome) or "Allow in InPrivate" (Edge). **This is required** — the CLI opens an incognito/inprivate window, and extensions are disabled there by default.
-5. Done — use `ask-marcel login --use-extension` to authenticate via the extension
-
 ### Stable error envelope with actionable hints
 
 Every failure — Graph, CLI parser, Zod validation, substrate — comes back as `{ok: false, error, errorCode?, hint?, source, retryAfterSeconds?}`. The `hint` field tells the model *what to do next* (e.g. "string literals MUST use single quotes; embed one by doubling it") and `source` tells it where the failure came from. Curated rules for 20+ recurring Graph errors plus cross-resolver pointers (passed a Teams URL to `resolve-mail-link`? Hint says "re-run with `resolve-teams-link`"). When Graph throttles (HTTP 429, sometimes 503) the response's `Retry-After` is surfaced as `retryAfterSeconds` — the integer seconds to wait — so a caller running tenant-scale crawls can honor the server's backoff instead of guessing.
@@ -111,14 +103,14 @@ Two flag patterns avoid the round-trip:
 npm i -g ask-marcel-office-cli
 
 # authenticate (cached → refresh → browser fallback)
-ask-marcel login
+ask-marcel-office login
 
 # the rest is read-only (the only writes are mail drafts) and discoverable from --help
-ask-marcel list-drives
-ask-marcel search-onedrive-files --drive-id "b!abc..." --query "Q3 budget"
-ask-marcel convert-mail-to-markdown --message-id "AAMkAD..."
-ask-marcel list-calendar-view --start-date-time today --end-date-time +7d
-ask-marcel convert-mail-attachment-to-pdf \
+ask-marcel-office list-drives
+ask-marcel-office search-onedrive-files --drive-id "b!abc..." --query "Q3 budget"
+ask-marcel-office convert-mail-to-markdown --message-id "AAMkAD..."
+ask-marcel-office list-calendar-view --start-date-time today --end-date-time +7d
+ask-marcel-office convert-mail-attachment-to-pdf \
   --message-id "AAMkAD..." --attachment-id "AAMkAD...attach1" \
   --output-path /tmp/deck.pdf
 ```
@@ -129,11 +121,11 @@ Five discovery surfaces, each tuned for a different audience and token budget:
 
 | When you want | Run | Returns |
 |---|---|---|
-| Help with a single command | `ask-marcel <command> --help` | Required flags, optional flags, an example, pagination notes |
-| A scan of every command | `ask-marcel --help` | One-sentence summary per command, grouped by category |
-| The slim LLM-friendly index | `ask-marcel help-json --terse` | JSON manifest with heavy fields (options, response shape) stripped — best first-call for an agent meeting the CLI for the first time |
-| The slim index for one domain | `ask-marcel help-json --terse --category mail` | Same as above, filtered to one of 12 categories — keeps the response tiny when the agent already knows the domain |
-| Rich docs for one command | `ask-marcel docs <command>` | Full Markdown to stdout (response shape, examples, the underlying Graph endpoint, Microsoft Learn link) |
+| Help with a single command | `ask-marcel-office <command> --help` | Required flags, optional flags, an example, pagination notes |
+| A scan of every command | `ask-marcel-office --help` | One-sentence summary per command, grouped by category |
+| The slim LLM-friendly index | `ask-marcel-office help-json --terse` | JSON manifest with heavy fields (options, response shape) stripped — best first-call for an agent meeting the CLI for the first time |
+| The slim index for one domain | `ask-marcel-office help-json --terse --category mail` | Same as above, filtered to one of 12 categories — keeps the response tiny when the agent already knows the domain |
+| Rich docs for one command | `ask-marcel-office docs <command>` | Full Markdown to stdout (response shape, examples, the underlying Graph endpoint, Microsoft Learn link) |
 
 Pair `help-json --terse --category <name>` with `docs <command>` for the canonical agent loop: scan the category, pick a command, fetch its full docs, then call it.
 
@@ -141,7 +133,7 @@ Pair `help-json --terse --category <name>` with `docs <command>` for the canonic
 
 Most agents already know how to read JSON from stdout. Two patterns work:
 
-**1. Drop in as a shell tool** — the agent learns the manifest, then runs `ask-marcel <command> --output json`. The slim defaults + structured error hints mean it can self-recover from typos.
+**1. Drop in as a shell tool** — the agent learns the manifest, then runs `ask-marcel-office <command> --output json`. The slim defaults + structured error hints mean it can self-recover from typos.
 
 **2. Embed as a library** — every command is exported. Compose it inside your own MCP server, Claude Agent, or LangChain tool:
 
@@ -185,39 +177,11 @@ The `AuthManager` interface is two async methods that return `Result<T, AuthErro
 
 ## Deep docs
 
-- **[All 177 commands](docs/COMMANDS.md)** — per-category tables with required params + Graph endpoint
+- **[All 180 commands](docs/COMMANDS.md)** — per-category tables with required params + Graph endpoint
 - **[Usage guide](docs/USAGE.md)** — output formats, OData passthrough, `--output-path`, pagination, library API, architecture, configuration, quality gates
 - **[Machine-readable manifest](docs/commands.json)** — JSON for programmatic discovery (LLM tool-loops, IDE plugins, MCP servers); also importable via `import manifest from 'ask-marcel-office-cli/commands.json'`
 - **[QA playbook](docs/QA-PLAYBOOK.md)** — the repeatable full-surface health-check procedure (offline gates, parameter matrix, conversion contracts, live Graph drift probes) used to audit each release
 
-
-## Agent skill (progressive disclosure)
-
-A [Codex skill](https://docs.anthropic.com/en/docs/agents-and-tools/codex) lives at `.agents/skills/ask-marcel-office/` and teaches agents how to use the CLI without loading all 177 commands into context at once.
-
-**Structure**
-
-```
-.agents/skills/ask-marcel-office/
-├── SKILL.md                          # core workflow + category index
-└── references/                       # per-domain command details, loaded on demand
-    ├── marcel-mail.md        (32 commands)
-    ├── marcel-drive.md       (30 commands)
-    ├── marcel-calendar.md    (23 commands)
-    ├── marcel-sharepoint.md  (18 commands)
-    ├── marcel-user.md        (15 commands)
-    ├── marcel-tasks.md       (15 commands)
-    ├── marcel-excel.md       (11 commands)
-    ├── marcel-notes.md       (11 commands)
-    ├── marcel-chats.md        (9 commands)
-    ├── marcel-teams.md        (7 commands)
-    └── marcel-meta.md         (6 commands)
-```
-
-**How it works**
-
-`SKILL.md` contains the authentication flow, the discovery loop (`help-json --terse --category` → `docs <cmd>` → execute), key patterns (OData passthrough, relative dates, document conversion, pagination), and a category index. The full command reference for each domain lives in `references/marcel-<category>.md` and is loaded only when the agent needs that domain — keeping the context window lean.
-
 ## Roadmap
 
 Read-only stays the default forever. There's no fixed feature backlog — coverage grows out of real LLM workflows as they come up.