/office-transform

name: office-transform
description: 'Extract or edit a selection from xlsx, docx, pdf, or pptx into a new file; the source is never modified.'
version: 1.0.0

Office Transform

Turn a structural selection of an Office/PDF document into a new derived file.

Two invariants hold for every operation:

1. **The source file is read-only.** Every result is a new file; both scripts refuse to write to the source path or overwrite an existing file. Never work around this with ad-hoc shell edits to the original. 2. **Anchors are structural.** Selections address the document's own coordinates — worksheet + A1 range, body-level paragraph ordinal, one-based page number — never screen or DOM positions.

When to use which tool

• Only need to *read* a document to summarize or answer questions → use

`mcp__cherry-tools__to_markdown` instead (see the cherry-tool-guide skill); it is lossy but built for reading.

• The user wants a *file* out — an extracted range, a converted fragment, an edited

copy → this skill.

Input: selection references

Chat surfaces may hand you a fenced `selection-ref` block:

{"path": "/abs/report.xlsx", "anchor": {"format": "xlsx", "sheet": "Sheet1", "range": "A1:C10"}, "excerpt": "…", "fileStamp": {"size": 1024, "mtimeMs": 1700000000000}}

The `anchor` object is exactly what the scripts take via `--anchor`.

**Freshness check.** `fileStamp.mtimeMs` is milliseconds since the Unix epoch, floored to whole milliseconds. Do not compare it to `stat`'s default output: `stat -f %m` (macOS) and `stat -c %Y` (GNU) give whole *seconds*, so multiplying by 1000 loses the sub-second part and never matches. Read whole milliseconds the way the app wrote them:

uv run python -c "import os,sys;st=os.stat(sys.argv[1]);print(st.st_size, st.st_mtime_ns//1_000_000)" '/abs/report.xlsx'

Treat the file as changed when the size differs, or when the mtimes differ by more than 2 ms. The tolerance is small on purpose: both sides floor the same nanosecond timestamp to milliseconds, so they agree exactly, and the couple of milliseconds only covers the rounding of a `double` that can no longer represent current epoch milliseconds exactly. A wider window would hide real edits — a same-size change made within it would read as unchanged, which is why the anchor check below is not optional. On a change, tell the user the file changed since they selected and ask them to re-select — never silently re-anchor.

**Anchor check.** Before a patch-copy edit, also verify the anchor still points where the user thinks: extract the anchored region and compare its text with the reference's `excerpt`, normalizing both sides the same way (NFC, collapse each whitespace run to one space, trim). The two are not equal and are not meant to be — the `excerpt` is what the user selected, while the extract is the whole region an edit would replace. A selection sitting inside one region makes the `excerpt` the shorter side; a selection running past that region anchors to where it *starts*, which makes it the longer one. So the test is containment, whichever way round fits: the `excerpt` appears inside the extract, or the extract's tail is where the `excerpt` begins. Only when neither holds has the anchor stopped pointing at the selection — then stop and tell the user, never edit at a mismatched anchor and never go searching for a "close enough" location. Two cases need care because the two sides are not directly comparable as-is:

• **xlsx**: the `excerpt` is tab-separated cells and newline-separated rows, while extraction

writes csv or md. Compare cell values, not the raw file — read the csv with a csv reader and join the fields with single spaces before normalizing, so `,` and `|` never count as a difference. That join drops the cell boundaries on both sides, so a match proves the text is unchanged, not the grid — the same words re-split across cells still reads as a match. The freshness check above is what catches that; never skip it on a passing anchor check. Number formats are the second asymmetry: the `excerpt` holds what Excel *displays*, because that is what the user pointed at (`1,234.50`, `45.67%`), while extraction writes the stored value (`1234.5`, `0.4567`). Neither side is wrong, so a formatted cell never matches literally. Compare those cells by value, and leave them out of the joined strings so the containment test runs on the text cells alone. Dates, times and durations are the same asymmetry seen from the other side: extraction writes one fixed shape (`2024-01-03`, `2024-01-03 15:04:05`, `26:30:00`) rather than the cell's format, so treat a cell that differs only in date or time presentation as a format difference too. A difference that is only the number format is not a moved anchor, and stopping on one sends the user back to re-select a selection that never moved.

• **docx with `charRange`**: the slice is only part of what patch-copy compares and replaces —

it rewrites the **whole paragraph**. Extract the paragraph *without* `charRange` as well, and read "Edit docx" below before writing.

Users may also describe the region in words ("sheet 2, columns A through C"); build the anchor JSON yourself, confirming the worksheet name or paragraph if ambiguous.

Anchor shapes:

| Format | Anchor | | --- | --- | | xlsx | `{"format":"xlsx","sheet":"Sheet1","range":"A1:C10"}` (range may be one cell) | | docx | `{"format":"docx","paragraph":3,"paraId":"502E8D33","charRange":[0,12]}` (`paraId` optional = the paragraph's `w14:paraId`, resolved first when present; `charRange` optional; ordinal counts body-level paragraphs only, tables excluded) | | pdf | `{"format":"pdf","page":3,"charRange":[0,120]}` (`charRange` optional, applies to extracted text) | | pptx | `{"format":"pptx","slide":2,"nodeId":"4","paragraph":0}` or `{"format":"pptx","slide":2,"nodeId":"7","tableCell":{"row":1,"col":0}}` (`slide` is one-based; `nodeId` is the OOXML