ask-marcel-office-cli 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,207 @@
 
 All notable changes to `ask-marcel-office-cli` are documented here.
 
+## 2.4.0
+
+Two community fixes from [@a-tokyo](https://github.com/a-tokyo). Nothing breaks:
+the new flag is optional, and every existing invocation routes exactly as before.
+
+### Fixed — share links whose filename is not ASCII
+
+`buildShareToken` fed the raw URL string to `btoa`, which only accepts Latin-1.
+A sharing URL with an accented filename minted a token that resolved to nothing,
+and one with a CJK or emoji filename threw `InvalidCharacterError`, which crashed
+the command from inside `Promise.all`. The URL's UTF-8 bytes are now encoded
+before base64url, which is what Graph's `/shares/{token}` resolver expects.
+
+Six commands build that token and all six were affected:
+
+| Command | How it reaches the token |
+|---------|--------------------------|
+| `resolve-drive-share-link` | encodes the sharing URL directly |
+| `convert-mail-attachment-to-markdown` | resolves an attachment's source URL |
+| `convert-mail-attachment-to-pdf` | resolves an attachment's source URL |
+| `extract-mail-attachment-images` | resolves an attachment's source URL |
+| `extract-sharepoint-links-in-mail` | one resolve per link found in the body |
+| `extract-sharepoint-links-in-documents` | one resolve per link found in the text |
+
+The byte-to-base64 step moved into a shared `bytesToBase64` codec under
+`domain/utilities`, replacing the private copy that lived in `fetch-raw-bytes`.
+
+### Added — `next-page --tenant-id`
+
+`next-page` re-signs a cursor to match the identity its originating command used,
+but it knew only two: the home basic token and the elevated chat token. A
+partner-tenant drive listing signs page 1 with a guest token, and the
+`@odata.nextLink` it emits carries no tenant, so page 2 was re-signed with the
+home token and Graph answered `401 invalidAudienceUri`. Anything longer than one
+page in a partner tenant was unreadable past page 1.
+
+Pass the same `--tenant-id` you gave the originating command (ultimately from
+`resolve-drive-share-link`) and the cursor is re-signed with a guest token for
+that tenant. The flag reuses the existing `tenant-option` branding, so a
+malformed GUID is rejected at the boundary before any Graph call.
+
+The footer carries the flag for you. `next:` and `delta:` both render
+`--tenant-id <guid>` whenever the call that produced the cursor used one, so the
+line stays copy-pasteable rather than becoming a 401 one step later. This is the
+line an MCP agent reads to build its next call, not just a terminal convenience.
+
+### Added — docx tracked changes report replacements as one edit
+
+OOXML has no "replace" revision: Word records replacing a span as a deletion
+sitting next to an insertion. Reported as two loose halves, one edit read as an
+unrelated cut plus an unrelated addition somewhere else, with nothing linking
+them. A deletion and an insertion that are adjacent siblings by the same author
+now come back as a single `replacements` entry carrying `before` and `after`,
+and the two halves leave `insertions` / `deletions` so nothing is counted twice.
+The markdown output gains a `### Tracked changes — replacements` section above
+the two existing ones.
+
+Adjacency is real document order, not a guess. The default XML parse groups
+same-named siblings per tag, which cannot distinguish del, ins, del, ins from
+del, del, ins, ins, so revisions are re-read through a second order-preserving
+parser. Pairing is scoped to siblings of one parent, requires the same author on
+both halves, and treats Word's glyph-free markers (`w:proofErr`, bookmark and
+comment anchors) as not separating a pair, while any untouched run of prose does.
+
+Still unreported, unchanged by this: `w:moveFrom` / `w:moveTo`, `w:rPrChange`,
+`w:pPrChange`, and the table-structure revisions. A document whose only tracked
+edit is a formatting change still reports no tracked changes at all.
+
+### Added — docx moves and formatting changes are reported at all
+
+A docx whose only tracked edits were a moved paragraph or a reformat reported
+no tracked changes whatsoever, which reads as a clean document rather than an
+unreviewed one. `w:moveFrom` / `w:moveTo` and `w:rPrChange` / `w:pPrChange` are
+now extracted into two new sections.
+
+`moves` joins the two ends of a move through the `w:name` on the range-start
+markers that bracket them, not by matching their text: Word does guarantee the
+halves carry identical content, so text-matching looks free right up to a
+document that moves the same sentence twice and silently cross-pairs four halves
+into two moves that never happened. A half whose partner is missing still gets a
+row, marked `from-only` or `to-only`.
+
+`formatChanges` names which properties a reviewer altered, comparing attributes
+as well as tag names. `w:color` sits on both sides of a recolour with only its
+`w:val` moving, so a comparison of tag names alone calls that run unchanged.
+Run-level and paragraph-level changes share one list, separated by `scope`.
+
+Table-structure revisions (cell insert / delete / merge, numbering, section and
+table properties) remain unreported, and the `--include-metadata` docs now say
+so rather than leaving it to be discovered.
+
+### Added — `get-mail-signature` empty states carry an `errorCode`
+
+Finding no signature used to come back as a validation error with a good
+message and no code, so an agent routing on `errorCode` saw nothing and the
+live QA sweep logged it as `ERR:err`. Two codes now name the two distinct
+misses: `signature_not_found` when the scanned or pinned message carries no
+OWA signature block, and `no_sent_messages` when there is nothing to scan at
+all. The messages are unchanged.
+
+### Fixed — `scopes-check` never opens a browser
+
+`scopes-check` obtained the basic token through the same acquiring getter as
+every other command, and in a terminal that getter heals an expired session by
+opening a browser; when the persistent profile is already signed in it also
+clears the session so the OAuth grant can re-fire, which drops the 90-day
+"Stay signed in" cookie. A diagnostic did all of that on 2026-09-02. The basic
+tier is now read straight off the cache like the elevated and Teams tiers
+already were: an expired token reports a negative `expiresInSeconds`, an empty
+cache reports not-signed-in, and `login` remains the command that refreshes.
+Bring-your-own-token managers built with `createGraphClient` are unaffected.
+
+### Added — an `invalidAudienceUri` error hint
+
+The one 401 that re-authenticating cannot fix now says so. Graph cannot mint a
+SharePoint token for a tenant you are only a guest in, so an agent told to run
+`login` here loops forever. The hint names `--tenant-id`, points at
+`resolve-drive-share-link` for the GUID, and covers the paginated case where the
+cursor carries no tenant of its own. It sits above the token-expiry rule, which
+would otherwise claim the same 401 and give the wrong advice.
+
+## 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

package/README.md

@@ -4,17 +4,15 @@
 
 ### The Microsoft 365 command line built for AI agents
 
-**One sign-in. 180 read-only commands. Every document as clean markdown.**
+**One sign-in. No Azure app registration. Every document as clean markdown.**
 
 [![npm version](https://img.shields.io/npm/v/ask-marcel-office-cli.svg?logo=npm&color=cb3837)](https://www.npmjs.com/package/ask-marcel-office-cli)
 [![license: MIT](https://img.shields.io/npm/l/ask-marcel-office-cli.svg?color=blue)](LICENSE)
-[![node ≥20](https://img.shields.io/node/v/ask-marcel-office-cli?logo=node.js&color=339933)](https://nodejs.org)
-[![bun ≥1.0](https://img.shields.io/badge/bun-%E2%89%A51.0-14151a?logo=bun)](https://bun.sh)
 [![types included](https://img.shields.io/npm/types/ask-marcel-office-cli?logo=typescript&color=3178c6)](docs/USAGE.md)
 
 Outlook · OneDrive · SharePoint · Calendar · Excel · Teams · Planner · To Do · OneNote · People
 
-[Install](#install-in-60-seconds) · [See it work](#see-it-work) · [What it reaches](#what-your-agent-can-reach) · [Files to markdown](#any-file-becomes-markdown) · [Library](#embed-it-as-a-typescript-library) · [All 184 commands](docs/COMMANDS.md)
+[Install](#install-in-60-seconds) · [See it work](#see-it-work) · [What it reaches](#what-your-agent-can-reach) · [Files to markdown](#any-file-becomes-markdown) · [Library](#embed-it-as-a-typescript-library) · [All 186 commands](docs/COMMANDS.md)
 
 </div>
 
@@ -32,15 +30,38 @@ ask-marcel-office list-mail-messages --top 5
 
 That is the whole setup. **No Azure app registration. No tenant-admin consent. No client secrets.** And nothing for a runaway agent to break: the command surface is read-only by design.
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ask-marcel/ask-marcel-office-cli/main/docs/demo.gif" alt="ask-marcel-office converting an Outlook .msg file into clean markdown in one command, offline" width="880">
+</p>
+
+## The difference in practice
+
+| You need | Raw Microsoft Graph | ask-marcel-office |
+|---|---|---|
+| Access | App registration, admin consent, secret rotation | `login`: one browser sign-in with your own account |
+| An email + attachments | 6+ round trips, HTML-to-text is your problem | `convert-mail-to-markdown`: one call, markdown out |
+| A pptx / pdf / legacy .doc as text | Raw bytes, bring your own converter | `download-drive-item-as-markdown`: one call |
+| A useful error | `BadRequest: Invalid filter clause` | `hint: "string literals MUST use single quotes; embed one by doubling it"` |
+| A 5 MB PDF | Base64 flooding the context window | `--output-path` writes it to disk; the model reads 3 lines |
+| Throttling | HTTP 429, guess the backoff | `retryAfterSeconds` surfaced in the error envelope |
+
+And against the tools you already know:
+
+| | Microsoft Graph SDKs | CLI for Microsoft 365 (PnP) | ask-marcel-office |
+|---|---|---|---|
+| Sign-in | An Entra app registration, always: every auth flow needs a client id | An Entra app registration; its `setup` command creates one, and the permissions it requests can need admin consent | Your own account, in a browser, once. No app registration |
+| Built for | Backend services | Admins and scripts | Tool-calling LLMs: markdown out, lean fields, a repair hint on every error |
+| Can it break things | Whatever your app's permissions allow | Yes: it creates, changes, and deletes across the tenant | No: read-only by design; the four writes only leave unsent drafts |
+
 ## The three walls it removes
 
 ### 🔑 Sign in like a human, not like an app
 
-Microsoft Graph normally means registering an Azure app, chasing tenant-admin consent, and rotating client secrets before the first API call. Here, `login` drives a real browser window through the standard Microsoft sign-in (Playwright under the hood) and captures the same token the Teams web client already uses. Any Microsoft 365 account works, personal or enterprise. Tokens are cached at `~/.ask-marcel/token-cache.json` (0600) and refresh themselves headlessly; `scopes-check` reports per-token scopes and expiry with zero side effects.
+Microsoft Graph normally means registering an Azure app, chasing tenant-admin consent, and rotating client secrets before the first API call. Here, `login` drives a real browser window through the standard Microsoft sign-in (Playwright under the hood) and captures the same token the Teams web client already uses. Any Microsoft 365 account works, personal or enterprise. Tokens are cached at `~/.ask-marcel/token-cache.json` (0600) and refresh themselves headlessly; `scopes-check` reports per-token scopes and expiry without a Graph call and without ever opening a browser: an expired session is reported as expired, not re-captured.
 
 ### 🛡️ Safe to hand to an autonomous agent
 
-The 184 commands break down as 176 GET, 4 read-only POST (three searches and a free/busy lookup), and 4 mail-draft operations. No `send-mail`. No `create-event`. No `upload-file`. No `delete-anything`. The worst a hallucinated tool call can do is leave an unsent draft in your Drafts folder. That is the entire blast radius, which is why you can let an agent explore a mailbox without reviewing every call.
+The 186 commands break down as 178 GET, 4 read-only POST (three searches and a free/busy lookup), and 4 mail-draft operations. No `send-mail`. No `create-event`. No `upload-file`. No `delete-anything`. The worst a hallucinated tool call can do is leave an unsent draft in your Drafts folder. That is the entire blast radius, which is why you can let an agent explore a mailbox without reviewing every call. No analytics, either: the only outbound traffic is Microsoft Graph and a periodic npm version check.
 
 ### 🧠 Responses budgeted for a context window
 
@@ -53,17 +74,26 @@ Reading one email with its attachments in raw Graph: GET the message, GET the at
 ```console
 $ ask-marcel-office convert-mail-to-markdown --message-id "AAMkAD..."
 
-# Q3 budget review: action needed
+**Subject:** Q3 budget review: action needed
 **From:** Robin Chen <robin.chen@contoso.com>
+**To:** Alex Kim <alex.kim@contoso.com>
+**Date:** 2026-09-02T08:14:22Z
 
 Before Friday's review, the forecast tab still shows last quarter's
 headcount. Can you sanity-check the attached numbers?
 
-## Attachments
-- Q3-forecast.xlsx (48 KB) · id AAMkAD...
+Robin
+
+\[inline image: contoso-signature.png\]
+
+_\[Quoted reply chain removed — pass --keep-quoted true to include it\]_
+
+**Attachments:**
+- Q3-forecast.xlsx (49.2 KB, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, id: AAMkAD...)
+_Use `convert-mail-attachment-to-pdf` or `get-mail-attachment` with the attachment id to fetch._
 ```
 
-The quoted chain below the reply is replaced by a one-line marker (restore it with `--keep-quoted true`), inline images become named placeholders, and attachments arrive with the ids ready for the follow-up call:
+Those two bracketed lines are the entire cost of a 40-message thread and a signature logo. Attachments arrive with their ids ready for the follow-up call:
 
 ```console
 $ ask-marcel-office convert-mail-attachment-to-markdown \
@@ -77,22 +107,11 @@ $ ask-marcel-office microsoft-search-query --query "Q3 budget filetype:pptx"
 $ ask-marcel-office download-drive-item-as-markdown --drive-id "b!abc..." --item-id "01BYE..."
 ```
 
-## The difference in practice
-
-| You need | Raw Microsoft Graph | ask-marcel-office |
-|---|---|---|
-| Access | App registration, admin consent, secret rotation | `login`: one browser sign-in with your own account |
-| An email + attachments | 6+ round trips, HTML-to-text is your problem | `convert-mail-to-markdown`: one call, markdown out |
-| A pptx / pdf / legacy .doc as text | Raw bytes, bring your own converter | `download-drive-item-as-markdown`: one call |
-| A useful error | `BadRequest: Invalid filter clause` | `hint: "string literals MUST use single quotes; embed one by doubling it"` |
-| A 5 MB PDF | Base64 flooding the context window | `--output-path` writes it to disk; the model reads 3 lines |
-| Throttling | HTTP 429, guess the backoff | `retryAfterSeconds` surfaced in the error envelope |
-
 ## What your agent can reach
 
 | Surface | Commands | In practice |
 |---|---:|---|
-| 📧 Outlook Mail | 36 | Search and read mail as markdown, convert any attachment (down to nested `.zip` and `.msg`), resolve SharePoint links in bodies, extract your signature, find existing drafts on a thread, prepare reply / forward drafts (the only writes) |
+| 📧 Outlook Mail | 38 | Search and read mail as markdown, convert any attachment (down to nested `.zip` and `.msg`), resolve SharePoint links in bodies, extract your signature, find existing drafts on a thread, prepare reply / forward drafts (the only writes) |
 | 📁 OneDrive + SharePoint | 49 | Discover every drive and site your token can reach, search files, read any document as markdown or PDF, version history, share links resolved even into partner tenants where you're a guest |
 | 📅 Calendar | 24 | "What's on this week" via relative dates (`today`, `start-of-week`, `+7d`), event details, free/busy lookups |
 | 👥 People + directory | 16 | People search, user profiles, the directory around you, your own identity and IDs in one round trip |
@@ -178,13 +197,13 @@ claude mcp add --transport stdio --scope user ask-marcel-office -- npx -y ask-ma
 
 > **Two things to know.** The first launch downloads the package into npx's cache, so allow it one slow start; every start after that is instant. And GUI apps don't inherit your shell's `PATH`: terminal-launched clients resolve `"npx"` fine, but a client launched from the Dock or Start menu (Claude Desktop) may not find it — if the server won't start, replace `"command": "npx"` with the absolute path `which npx` prints. Bun users: `bunx` works in place of `npx -y`.
 
-You get **five gateway tools**, not one per command — 184 tool schemas would bloat every session, the opposite of the point:
+You get **five gateway tools**, not one per command — a schema per command would bloat every session, the opposite of the point:
 
 | Tool | Does |
 |:--|:--|
 | `list-commands` | The terse manifest. Start here; `category` narrows it. |
 | `get-command-docs` | Full docs for one command: options, endpoint, example. |
-| `run-command` | The 180 **read** commands. `readOnlyHint: true`, so clients can auto-approve it. |
+| `run-command` | The 182 **read** commands. `readOnlyHint: true`, so clients can auto-approve it. |
 | `run-write-command` | The 4 mail-draft **write** commands. Separate tool so the read tool's promise stays honest. |
 | `login` | Sign in / refresh. Opens a browser on this machine. |
 
@@ -230,14 +249,14 @@ Azure Managed Identity, an on-behalf-of flow, hand-pasted JWTs in tests: the Gra
 
 ## Deep docs
 
-- **[All 184 commands](docs/COMMANDS.md)**: per-category tables with required params + Graph endpoint
+- **[All 186 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
 - **[Machine-readable manifest](docs/commands.json)**: JSON for programmatic discovery, also importable via `import manifest from 'ask-marcel-office-cli/commands.json'`
 - **[QA playbook](docs/QA-PLAYBOOK.md)**: the repeatable full-surface health check run before each release
 
 ## Roadmap
 
-Read-only stays the default forever. Coverage grows out of real LLM workflows as they come up: suggestions, requests, and pull requests welcome on the [issues page](https://github.com/vdelacou/ask-marcel-office-cli/issues).
+Read-only stays the default forever. Coverage grows out of real LLM workflows as they come up: suggestions, requests, and pull requests welcome on the [issues page](https://github.com/ask-marcel/ask-marcel-office-cli/issues).
 
 ## Built with