ask-marcel-office-cli 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,275 @@
 
 All notable changes to `ask-marcel-office-cli` are documented here.
 
+## 2.2.0
+
+### Added
+
+- **`ask-marcel-office mcp` — serve the whole CLI to any MCP client over stdio.** Hosts
+  without a shell (Claude Desktop, other MCP clients) can now reach every
+  command. Register it with:
+
+  ```bash
+  claude mcp add --transport stdio --scope user ask-marcel-office -- ask-marcel-office mcp
+  ```
+
+  It exposes **five gateway tools**, not one per command — 183 tool schemas
+  would inject hundreds of KB into every session, the exact token bloat this
+  CLI exists to avoid:
+
+  - `list-commands` — the terse manifest (`{name, summary, category}`),
+    optionally filtered to one category. The discovery entry point.
+  - `get-command-docs` — full Markdown docs for a single command: every option,
+    its Graph endpoint, an example, the response shape. Lifecycle commands and
+    deprecated command names both resolve.
+  - `run-command` — runs any of the **179 read** commands. Declared
+    `readOnlyHint: true`, so an MCP client can auto-approve it; a write routed
+    here is refused *before* it executes.
+  - `run-write-command` — runs the **4** mail-draft write commands
+    (`create-mail-draft`, `create-forward-draft`, `create-reply-draft`,
+    `update-mail-draft`). A separate tool precisely so the 179 read commands
+    keep an honest read-only annotation. Marked non-destructive: every write
+    produces an UNSENT draft, and this CLI still cannot send mail.
+  - `login` — sign in or refresh. The elevated (M365) token lapses roughly
+    hourly and only a browser can recapture it, so this saves a terminal
+    round-trip mid-session.
+
+  Both run tools accept `outputPath` / `outputDir`, mirroring the CLI flags, so
+  a multi-MB PDF lands on disk instead of flooding the model's context.
+
+  **Raise your MCP client's tool timeout to ~5 minutes** (`MCP_TOOL_TIMEOUT=300000`
+  or equivalent). Measured against a real tenant: a browser sign-in takes
+  **37–64 s even with no MFA prompt**, while the MCP default request timeout is
+  **60 s** — so `login` times out intermittently at the default. The server keeps
+  running through a client-side timeout, so the sign-in has usually completed
+  anyway; re-run your original command before calling `login` again. Sign in
+  from a terminal the first time (`ask-marcel-office login`), where an MFA prompt adds
+  minutes on top.
+
+  Read/write sets are derived from the registry's `mutates` flag, so a new
+  command lands on the correct tool with no code change here.
+
+- **Files in a partner tenant you are a guest in are now readable.** Previously
+  every such read died at `401 invalidAudienceUri: Invalid audience Uri
+  '00000003-0000-0ff1-ce00-000000000000'` (SharePoint Online's app id): your
+  home-tenant Graph cannot mint a SharePoint token for a foreign tenant, so no
+  home-tier token could reach the file — which is exactly the case when a partner
+  sends you a "Copy link" URL.
+
+  **`resolve-drive-share-link` crosses the boundary by itself.** It tries your
+  home token and, only on that specific error, identifies the owning tenant from
+  the URL host (`contoso.sharepoint.com` → `contoso.onmicrosoft.com` → the
+  tenant's public OIDC discovery document) and retries with a guest token minted
+  by redeeming your existing refresh token against that tenant's authority. No
+  new sign-in, no browser, no Azure app. It returns the tenant as **`tenantId`**;
+  the field's PRESENCE is the signal — absent means the file is in your own
+  tenant and nothing changes.
+
+  **`--tenant-id` carries it to the rest of the family.** `driveId` and `itemId`
+  carry no tenant, so the commands that consume them cannot recover on their own;
+  pass the `tenantId` that `resolve-drive-share-link` returned and they sign with
+  the guest token instead. Available on `get-drive-item`,
+  `download-drive-item-content`, `download-drive-item-as-markdown`,
+  `download-drive-item-as-pdf`, `extract-drive-item-images`,
+  `convert-drive-item-zip`, `get-drive-item-list-item`, `list-folder-files`,
+  `list-drive-item-versions`, `list-drive-item-permissions`, and
+  `list-drive-item-thumbnails`. Optional everywhere; omit it for your own tenant.
+
+  Boundaries worth knowing: a link you simply may not read still fails with
+  `accessDenied` (a guest token would not help, so one is never requested); a
+  tenant that has not consented to this client, or where you are not actually a
+  guest, fails with a message naming that tenant; a SharePoint host whose sign-in
+  domain differs from its name cannot be resolved and says so (`--tenant-id`
+  passed by hand still works there); and `1drv.ms` belongs to no tenant at all,
+  so it is unaffected. Elevated commands do not take the flag — the elevated
+  token is a home-tenant identity, so "elevated in a partner tenant" does not
+  exist. Verified end to end against a real partner tenant.
+
+- **`get-user`** looks up a directory user by id, UPN/email, or name — one
+  command, two routes. An **Azure AD id, UPN, or email** returns that user's FULL
+  profile via `GET /users/{id}` on the elevated M365 token (`User.Read.All`, so
+  `jobTitle` / `department` / `officeLocation` / phones are populated); it honours
+  `--select` / `--expand` and fail-fasts with `secondary_token_unavailable` when
+  the elevated token is cold (run `login --force`). An email that is the user's
+  `mail` but not their sign-in UPN — every **guest / B2B** user, whose UPN is the
+  `alias_homeorg#EXT#@tenant` form — still resolves: when the direct
+  `GET /users/{id}` 404s, the command falls back to
+  `GET /users?$filter=mail eq '<email>'` and returns the single match. A bare **name** instead
+  searches the signed-in user's relevant-people graph
+  (`GET /me/people?$search="name"`) on the basic token — so it works even when the
+  elevated token is cold — and returns candidate matches
+  (`{ id, displayName, mail, jobTitle, department }`) so the caller can
+  disambiguate and re-query by the chosen `id` for the full card. Name search
+  covers your people graph, not the whole tenant; `microsoft-search-query` remains
+  the broad tenant-wide person search. (181st command.)
+
+### Changed
+
+- **Command execution is now shared by both front ends.** The per-command
+  handler (alias normalization, local-filesystem routing, error-source
+  classification, `--output-path` / `--output-dir` persistence) moved out of
+  `cli.ts` into `composition/run-registry-command.ts`, which the CLI and the MCP
+  gateway both call. Behaviour is unchanged — the existing CLI suite passes
+  untouched — but a future fix now reaches both surfaces instead of one.
+- **The output envelope logic is now pure and reusable.** `presenter/output.ts`
+  wrote directly to stdout, which an MCP stdio server cannot do (stdout is its
+  JSON-RPC channel). The envelope layer moved to `presenter/render-to-string.ts`
+  (`renderToString` / `renderErrorToString`); `output.ts` is a thin stdout shim
+  over it. Output is byte-identical. MCP callers therefore get the same
+  `hint:` / `source:` remedies the terminal does.
+
+- **`scopes-check` is now the single detailed token-status view.** Per token
+  (basic / elevated / chatsvcagg / ic3) it reports the `available` flag,
+  seconds-to-expiry, `refresh` route (`automatic` = self-heals from the shared
+  refresh token; `interactive` = the elevated token, needs a browser login), and
+  — new — that token's OWN granted scopes, decoded from its `scp` claim. The four
+  tokens carry distinct scope sets (basic ~31 Graph scopes, elevated ~20,
+  chatsvcagg `user_impersonation`, ic3 `Teams.AccessAsUser.All`), so an agent can
+  intersect each tier against a command's `scopesRequired`. Additive and
+  non-breaking: the flat top-level `scopes`/`audience`/`expiresAt`/`expiresInSeconds`
+  (the basic token) are unchanged. A `hint` field names a forced re-login as the
+  single refresh action.
+- **`login` slimmed to an auth confirmation.** It now prints
+  `{ status: "authenticated", available: [...], hint }` — which token tiers are
+  available, plus a pointer to `scopes-check` (per-token detail) and `login --force`
+  (refresh) — instead of the four-token detail block from 2.1.0, and the confusing
+  refresh-mechanism hint is gone. The detailed per-token status now lives only in
+  `scopes-check`. (Dropping login's `tokens` block is the one breaking-ish change;
+  it shipped a single release earlier and the same detail is fully available via
+  `scopes-check`.)
+- **The mail read commands now include `conversationId` in their default
+  projection.** `list-mail-messages`, `search-mail-messages`, and
+  `get-mail-message` add `conversationId` to their slim default `--select`, so a
+  caller can group results into a thread — or hand the id straight to
+  `list-conversation-messages` — without a second round-trip. The three
+  previously-duplicated default-select strings are now one shared constant
+  (`mail-message-select.ts`) so they cannot drift apart again. Additive
+  (~76 bytes/message); a user-supplied `--select` still overrides entirely.
+- **`resolve-drive-share-link` now resolves a sharing URL to the driveItem in one
+  call.** It previously only encoded the URL into the `u!` share token (offline,
+  no Graph call), forcing a second `/shares/{token}/driveItem` fetch plus
+  hand-parsing `parentReference.driveId`. It now encodes AND fetches, returning
+  `{ driveId, itemId, name, webUrl, size, lastModifiedDateTime, shareToken }` — the
+  two ids every `*-drive-item` command needs, in one shot (basic token,
+  `Files.Read.All`). Shape + behavior change: it now makes a Graph call and no
+  longer returns `graphPath`/`originalUrl`; a cross-tenant or no-access link
+  surfaces the Graph `accessDenied` / `itemNotFound` instead of a share token that
+  would only fail on the follow-up call.
+
+### Fixed
+
+- **`login` no longer sends you round a loop it cannot break.** A command needing
+  the elevated (M365) token failed with "run `ask-marcel-office login`"; `login`
+  answered `authenticated` and changed nothing; the command failed identically.
+  Forever. The elevated token carries no refresh token of its own, so a plain
+  `login` that found a valid cached basic token returned on the cache rung
+  without ever re-capturing it — `--force` was the only escape, and the error
+  message never said so.
+
+  `login` now re-captures the elevated token whenever it is missing, and does
+  nothing when it is already present (no gratuitous browser). The fail-fast
+  message now names the right remedy per tier and explains why: `--force` for
+  elevated, plain `login` for the chatsvcagg / ic3 substrate tokens, which
+  self-heal from the shared refresh token and never needed a browser at all.
+  `scopes-check`'s hint and the README carried the same false "only way" claim and
+  are corrected too. `--force` still works and still re-captures every tier.
+
+- **The library's documented `AuthManager` example did not compile.** The README's
+  "bring your own token" snippet passed `{getAccessToken, logout}` to
+  `createGraphClient` and called `AuthManager` "two async methods"; it has ten.
+  The snippet now compiles, and declines the tiers a custom token source cannot
+  mint rather than omitting them.
+
+- **Guest / external-user (B2B) lookups by UPN now resolve.** A guest UPN is
+  `alice_contoso.com#EXT#@fabrikam.onmicrosoft.com`, and the `#` is the URL
+  fragment delimiter — the seven commands that put a caller-supplied `userId`
+  in a `/users/{id}` path (`get-user-manager`, `get-shared-mailbox-message`,
+  `list-shared-mailbox-messages`, `list-shared-mailbox-folder-messages`,
+  `list-shared-calendar-events`, `list-user-direct-reports`,
+  `list-shared-calendar-view`) interpolated it raw, so `fetch` dropped everything
+  from the `#` onward and queried the wrong user. The `userId` segment is now
+  percent-encoded (`#`→`%23`, `@`→`%40`; GUIDs unchanged), which Microsoft Graph
+  requires for B2B UPNs and which is verified live against the directory. `get-user`
+  (new this release) already encodes its path.
+- **Cached elevated / substrate tokens now survive a basic-token refresh.** The
+  silent basic-token refresh (triggered whenever the Teams token nears expiry)
+  rebuilt the cache from only the three basic fields, wiping the cached `elevated`
+  / `chatsvcagg` / `ic3` tokens on every renewal — so `scopes-check` and `login`
+  then reported them unavailable with empty scopes, and the elevated token (which
+  carries no refresh token of its own) needed a forced re-login to recover. The
+  refresh now merges, preserving all four tokens until they each expire.
+- **`scopes-check` explains an unavailable token.** Every tier block whose
+  `available` is `false` now carries a `reason` — a one-line note on why it is
+  absent and how to restore it (`login --force`; the substrate tiers also self-heal
+  on next use) — so an empty `scopes: []` on a missing token is not misread as "no
+  scopes". Additive and non-breaking; omitted when the token is available.
+
+## 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