ask-marcel-office-cli 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -2,6 +2,159 @@
 
 All notable changes to `ask-marcel-office-cli` are documented here.
 
+## 2.5.0
+
+### Fixed: `help` costs the same whoever runs it
+
+The top-level listing is compacted to fit an LLM's token budget, and then
+Commander sized its description column from `process.stdout.columns`, so the
+budget depended on the reader's terminal. Measured on this surface: 35 KB at 80
+columns, 64 KB at 100, 46 KB at 140, 39 KB at 200. Not even monotonic, so no
+width was safe to assume.
+
+The wrap width is now pinned at 80 and the listing is 35 KB everywhere.
+
+This also broke `npm publish`. The byte-count guard in `cli.test.ts` asserts the
+listing stays under 45 KB, and under CI or any piped run stdout is not a TTY, so
+Commander fell back to 80 and the guard passed. Run from an ordinary terminal at
+90 to 150 columns it failed, which is where most terminals sit. A new test
+renders the listing at four widths and asserts one size, so the guard can no
+longer measure a different thing for each reader.
+
+### Fixed: the group conversation collections stop advertising a filter Graph refuses
+
+`list-group-threads` and `list-group-conversations` handed out the full OData
+option set, so both advertised `--filter`. Graph accepts it on neither. Probed
+live on a group the signed-in user belongs to: any predicate on the threads
+collection answers `ConversationFilterOther`, `isLocked eq false` answers
+`ConversationFilterIsLockedEqualsFalse` because the only accepted forms are
+`IsLocked eq true` and `IsLocked ne false`, and a predicate on conversations
+answers `ErrorUnsupportedPathForQuery`.
+
+That broke the promise the usage guide makes, that the CLI advertises only the
+flags the endpoint honours so the manifest never lies. An agent reading the
+manifest spent a round trip to find out. `--filter` is dropped from both; the
+flag is now refused locally with the unknown-flag hint and no network call.
+Filtering a group inbox down to its locked threads is not a use this CLI has,
+so the one working predicate did not earn a caveat in its place.
+
+`--top`, `--skip`, `--orderby`, `--select` and `--expand` are all honoured on
+both collections and are unchanged.
+
+### Added: docx tracked changes cover the table
+
+`extractDocxMetadata` reported formatting revisions on runs and paragraphs only,
+so a reviewer who restyled a table left no trace in the metadata block. Word
+records a table, row and cell property change the same way it records a run's,
+the properties as they were BEFORE the edit nested inside a `*Change` element,
+so the same walker reads all five. `formatChanges[].scope` gains `table`, `row`
+and `cell` alongside `run` and `paragraph`.
+
+One limit worth knowing: a property whose values hang off child elements rather
+than its own attributes, and `w:tblBorders` is the common table case, compares
+as unchanged. The revision is still reported with its author, date and scope; it
+names no property. Structural revisions (`w:cellIns`, `w:cellDel`, `w:cellMerge`)
+carry no before/after pair and are not reported.
+
+### Added: a gate that holds the docs to the registry's numbers
+
+Four numeric claims drifted during the 2.4.0 cycle, and one was wrong on main for
+two releases: `docs/USAGE.md` promised "the 180 READ commands" where the registry
+held 188, three sections after `README.md` said 188 correctly. `mcp.ts` already
+derives its counts and carries a comment saying the prose must be derived too;
+nothing enforced it.
+
+`bun run check:docs` reads the counts off the command registry and the rendered
+manifest, then holds all ten numeric claims in `README.md`, `docs/USAGE.md` and
+`docs/COMMANDS.md` to them, printing `file:line expected N, found M`. A claim
+whose anchor text no longer matches anything fails too, so rewording a sentence
+cannot silently switch its own check off. It runs in CI behind a `--selftest`
+that proves the matcher rejects both a wrong number and a lost anchor.
+
+The stale 188 is corrected in the same change.
+
+### Added: read what is attached to a group post
+
+`get-group-post --expand attachments` was the only route to a post's attachments,
+and it inlines every one of them at once, which is the shape that times out on a
+post carrying a multi-MB file. Three commands make the group inbox readable
+attachment by attachment, all on the `Group.Read.All` scope the token already has:
+
+- `list-group-post-attachments` returns the metadata alone, with the same slim
+  default `--select` the mail and calendar siblings use. Graph silently ignores
+  `$top`, `$skip`, `$orderby` and `$filter` here (probed live: asking for one
+  attachment returned all seven, and `isInline eq false` returned all seven when
+  every one was inline), so only `--select` and `--expand` are exposed.
+- `get-group-post-attachment` fetches one attachment, mirroring `contentBytes`
+  as `base64` so `--output-path` lands it on disk. This is also the route to an
+  image attached to a post.
+- `convert-group-post-attachment-to-markdown` renders one through the shared
+  conversion pipeline, the way the mail and calendar siblings do.
+
+### Fixed: unconvertible attachments name a command that can reach them
+
+The shared conversion pipeline hardcoded the mail remediation wording, so an
+image or scanned PDF attached to a calendar event told the caller to run
+`get-mail-attachment --message-id ...`, which cannot address an event. Each
+caller now supplies its own hints: the calendar converter points at
+`get-calendar-event --expand attachments` and its PDF sibling, and the new post
+converter points at `get-group-post-attachment`.
+
+### Fixed: inline-only mail no longer hides its images
+
+Graph reports `hasAttachments: false` for a message whose only attachments are
+inline images, and both markdown converters fetched the attachment list only on
+that flag. Such a message rendered its images as unnamed placeholders, left them
+out of the attachments list, and embedded nothing under `--inline-images true`.
+The list is now fetched whenever the body references a `cid:` image as well,
+the guard `get-mail-signature` already uses, so
+`convert-mail-to-markdown` and `convert-group-post-to-markdown` name the
+placeholders, list the images with their ids, and embed them on request. No
+extra call for a message without inline images.
+
+### Changed: the shared-mailbox commands say when they will 403
+
+`list-shared-mailbox-messages`, `list-shared-mailbox-folder-messages`,
+`list-shared-mailbox-folders`, `list-shared-mailbox-child-folders` and
+`get-shared-mailbox-message` used to promise a 403 only "if the signed-in user
+does not have shared access". The scope they need, `Mail.Read.Shared`, is on
+neither token this CLI can mint, so their summaries now state that any mailbox
+other than your own is expected to answer `ErrorAccessDenied` whatever delegation
+Exchange holds, that your own UPN works, and that a Microsoft 365 group's mailbox
+is the shared-mail path that does.
+
+### Added: read the posts of a Microsoft 365 group conversation
+
+`list-group-conversations` and `list-group-threads` stopped at Graph's truncated
+`preview`, and a group mailbox cannot be read through the shared-mailbox commands
+(`ErrorGroupIsUsedInNonGroupURI`), so a group's mail was reachable up to its titles
+and no further. Three commands close the gap, all on the `Group.Read.All` scope the
+token already carries:
+
+- `list-group-thread-posts --group-id --thread-id` returns every `post` of a thread
+  with its HTML body, `from`, `sender`, `receivedDateTime` and `hasAttachments`.
+  Graph hands back the whole thread in one call and silently ignores `$top`, `$skip`
+  and `$orderby` while rejecting `$filter` (probed live), so only `--select` and
+  `--expand` are exposed and there is no page cursor.
+- `get-group-post --group-id --thread-id --post-id` is the `get-mail-message` sibling
+  for a group inbox; `--expand attachments` inlines the attachments with their bytes.
+- `convert-group-post-to-markdown` renders one post the way `convert-mail-to-markdown`
+  renders a message, with the same `--inline-images` and `--keep-quoted` flags. A post
+  arrives from the group's own address with the writer in `sender`, so the author line
+  reads `Robin Chen <...> on behalf of Support <...>`; the thread `topic` is the subject
+  and is not repeated.
+
+The mail-to-markdown pipeline now takes the resource path and the header renderer as
+parameters; the mail command's output is unchanged. `list-group-threads` and
+`list-group-conversations` point at the reader, and at `--expand posts`, which already
+inlined the bodies.
+
+### Fixed — deleted text no longer renders in an `.odt` body
+
+The body converter walked `text:tracked-changes` like any other block, so the
+paragraphs a reviewer had deleted printed as if they were still in the
+document. The region is skipped, so the body reads as the document stands.
+
 ## 2.4.0
 
 Two community fixes from [@a-tokyo](https://github.com/a-tokyo). Nothing breaks:

package/README.md

@@ -12,7 +12,7 @@
 
 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 186 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 192 commands](docs/COMMANDS.md)
 
 </div>
 
@@ -61,7 +61,7 @@ Microsoft Graph normally means registering an Azure app, chasing tenant-admin co
 
 ### 🛡️ Safe to hand to an autonomous agent
 
-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.
+The 192 commands break down as 184 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
 
@@ -111,7 +111,7 @@ $ ask-marcel-office download-drive-item-as-markdown --drive-id "b!abc..." --item
 
 | Surface | Commands | In practice |
 |---|---:|---|
-| 📧 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) |
+| 📧 Outlook Mail | 44 | 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 |
@@ -203,7 +203,7 @@ You get **five gateway tools**, not one per command — a schema per command wou
 |:--|:--|
 | `list-commands` | The terse manifest. Start here; `category` narrows it. |
 | `get-command-docs` | Full docs for one command: options, endpoint, example. |
-| `run-command` | The 182 **read** commands. `readOnlyHint: true`, so clients can auto-approve it. |
+| `run-command` | The 188 **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. |
 
@@ -249,7 +249,7 @@ Azure Managed Identity, an on-behalf-of flow, hand-pasted JWTs in tests: the Gra
 
 ## Deep docs
 
-- **[All 186 commands](docs/COMMANDS.md)**: per-category tables with required params + Graph endpoint
+- **[All 192 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