ask-marcel-office-cli 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,289 @@
 
 All notable changes to `ask-marcel-office-cli` are documented here.
 
+## 2.3.0
+
+> **Read this before upgrading.** This release contains breaking changes to the
+> flag surface despite the minor version number. If you pin `^2.2.0` you will
+> receive it automatically. Anything calling the CLI, the MCP gateway, or the
+> library with an old flag spelling will stop working.
+
+### Removed — every flag alias and every deprecated command name
+
+One name per flag, one name per command. The alias system is gone: 77 flag
+aliases and 4 deprecated command names. Each alias already pointed at a more
+specific canonical, so nothing was renamed to accommodate the removal.
+
+| Gone | Use instead |
+|------|-------------|
+| `--id` (51 commands) | the command's specific id flag (`--message-id`, `--site-id`, …) |
+| `--start` / `--end` (7 date-window commands) | `--start-date-time` / `--end-date-time` |
+| `--body-content` on `create-reply-draft` / `create-forward-draft` | `--comment` |
+| `--task-id` | `--planner-task-id` or `--todo-task-id` |
+| `--folder-id` | `--item-id` |
+| `--item-id` on the SharePoint list commands | `--list-item-id` |
+| `--page-id`, `--section-id` | `--onenote-page-id`, `--onenote-section-id` |
+| `--emails` on `get-schedule` | `--schedules` |
+| `--query` on `search-onenote-pages` | *(now the canonical name, see below)* |
+| `download-onedrive-file-content` | `download-drive-item-content` |
+| `convert-local-file` | `convert-local-file-to-markdown` |
+| `convert-drive-item-zip` | `convert-drive-item-zip-to-markdown` |
+| `convert-mail-attachment-zip` | `convert-mail-attachment-zip-to-markdown` |
+
+Why: the same spelling meant different things on sibling commands. That is how
+`--body-content` came to mean "the text above the quote" on the create-draft
+commands and "replace the ENTIRE body, quote included" on `update-mail-draft`,
+a silent data-loss trap fixed in this same release.
+
+### Changed — `search-onenote-pages --title-substring` is now `--query`
+
+The last flag naming a shared concept differently from its siblings. All eight
+search commands now take `--query`. (`--query` had already been bolted onto this
+command as an alias for exactly this reason; it is now the only name.) The flag
+still matches page TITLES only, which its description states explicitly.
+
+### Changed — a parameter a command does not declare is now refused
+
+Previously the three surfaces disagreed. Commander rejected unknown `--flags` on
+the CLI, but Zod strips unknown keys, so the MCP gateway's `run-command` params
+and direct library `commands[x].execute(...)` calls silently swallowed them and
+returned data that looked like it had obeyed. A live audit found this on 5 of 7
+delta commands. All three surfaces now refuse identically, with
+`errorCode: "unknown_parameter"` and the supported flags named in the message.
+
+### Fixed — `--top` no longer terminates a mail-folder delta sync
+
+`list-mail-folder-messages-delta --top 2` on a 67-message Inbox returned 2
+messages and an `@odata.deltaLink` rather than a `nextLink`. Graph reads a
+*satisfied* `$top` as "this sync is complete", so the other 65 messages were
+never delivered and the caller banked a delta token certifying a sync that never
+happened. `--top` is now sent as `Prefer: odata.maxpagesize`, which pages
+normally. `--skip` and `--orderby` are no longer advertised there (Graph ignores
+the first and rejects the second), and `--filter` / `--orderby` are gone from
+the two drive delta commands for the same reason.
+
+### Fixed — a whole-body draft update can no longer drop quoted history
+
+`update-mail-draft --body-content` on a threaded draft replaced the entire body
+including the quoted thread, with nothing warning at call time. It now reads the
+draft first and refuses when a quote is present, pointing at `--comment`. Pass
+`--replace-quoted-history true` for the deliberate case. The same read refuses
+non-drafts before the write.
+
+### Fixed — the oversized-response banner only names remedies that exist
+
+The `sizeHint` banner called `--output-path` a "universal remedy (works on every
+command)". It is not: plain-JSON commands refuse the flag, and the two commands
+that trip the banner most often (`search-all-files`, `microsoft-search-query`)
+advertise only `--query`, so every remedy it named was a dead end. The banner is
+now derived from the command that produced the payload and the surface asking:
+byte-producing commands keep the `--output-path` wording (`outputPath` on MCP),
+plain-JSON commands on the CLI get a shell redirect, and the same commands on
+MCP get neither, since an MCP client has no shell.
+
+## 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