bun-docx 0.6.0 → 0.7.0

package/README.md

@@ -31,7 +31,7 @@ bunx bun-docx read doc.docx
 
 ```sh
 docx create FILE [--title T] [--author A] [--text "..."]
-docx read FILE [--markdown [--from pN] [--to pN] [--changes] [--comments]]
+docx read FILE [--markdown [--from pN] [--to pN] [--accepted | --baseline] [--comments]]
 docx insert FILE --after p3 --text "..." [--style HeadingN] [--color HEX] [--bold] [--italic] [--url URL]
 docx insert FILE --after p3 --runs '[{"type":"text","text":"X","bold":true}]'
 docx edit   FILE --at p3 --text "..." | --runs '[...]'
@@ -40,6 +40,9 @@ docx delete FILE --at p3
 docx find FILE QUERY [--regex] [--ignore-case] [--all] [--nth N]
 docx replace FILE PATTERN REPLACEMENT [--regex] [--ignore-case] [--all] [--limit N] [--dry-run]
 
+docx wc      FILE [LOCATOR] [--accepted | --baseline]
+docx outline FILE
+
 docx comments add     FILE --range p3:5-20 --text "..." [--author NAME]
 docx comments reply   FILE --to c0 --text "..."
 docx comments resolve FILE --id c0 [--unset]
@@ -56,13 +59,18 @@ docx hyperlinks replace FILE --at linkN --with URL
 docx hyperlinks delete  FILE --at linkN
 
 docx track-changes FILE on|off
+docx track-changes list   FILE
+docx track-changes accept FILE (--at tcN | --all)
+docx track-changes reject FILE (--at tcN | --all)
 docx info schema [--ts]
 docx info locators [--json]
 ```
 
 Every command has `--help`. Mutating commands accept `--dry-run` and `-o/--output PATH` (write to a parallel file instead of overwriting `FILE`). JSON output by default for `read` and `*.list`; structured `{ok, code, error, hint}` on failure.
 
-When `<w:trackChanges/>` is set in the doc (toggle via `docx track-changes FILE on`), `insert`/`edit`/`delete`/`replace` automatically emit `<w:ins>`/`<w:del>` markers attributed to `$DOCX_AUTHOR` (default `docx-cli`). To make a one-off untracked edit, flip the flag off, edit, then flip it back on. `find` results inside tracked-change wrappers carry a `trackedChanges` array so agents can decide what to do with hits in pending insertions/deletions.
+When `<w:trackChanges/>` is set in the doc (toggle via `docx track-changes FILE on`), `insert`/`edit`/`delete`/`replace` automatically emit `<w:ins>`/`<w:del>` markers. Author resolution: per-call `--author NAME` overrides `$DOCX_AUTHOR`, which falls back to `docx-cli`. To make a one-off untracked edit, flip the flag off, edit, then flip it back on. `find` results inside tracked-change wrappers carry a `trackedChanges` array so agents can decide what to do with hits in pending insertions/deletions. `docx track-changes list FILE` returns a JSON inventory of every revision wrapper (`<w:ins>` / `<w:del>` / `<w:moveFrom>` / `<w:moveTo>`) with stable `tcN` ids, author, date, paragraph location, and the affected text. `docx track-changes accept FILE --at tcN | --all` incorporates changes — additive wrappers (`<w:ins>` / `<w:moveTo>`) get unwrapped, subtractive wrappers (`<w:del>` / `<w:moveFrom>`) get deleted; `reject` is the inverse (additive deleted, subtractive unwrapped after `<w:delText>` → `<w:t>`). moveFrom/moveTo halves are processed independently, so `--all` handles a complete move; targeting one half by `tcN` leaves the other in place. Accept/reject themselves bypass tracking — they're doc surgery, not edits.
+
+OOXML has no native tracked-change form for hyperlink edits or image swaps, so when track-changes is on, `hyperlinks add/replace/delete` and `images replace` auto-emit a `[docx-cli] …` comment anchored to the affected span/run instead. The comment carries the same `--author` attribution as the other tracked operations. Word itself silently bypasses tracking for these — we trade silence for an explicit audit trail.
 
 ### Markdown rendering
 
@@ -80,9 +88,14 @@ When `<w:trackChanges/>` is set in the doc (toggle via `docx track-changes FILE
 - Footnotes / endnotes → inline `[^fnN]` / `[^enN]` refs with GFM footnote definitions at end of output
 - Charts / SmartArt / shapes / other non-picture drawings → `` `[chart]` `` / `` `[smartart]` `` / `` `[shape]` `` / `` `[drawing]` `` placeholders
 
-`--from LOC` and `--to LOC` slice by top-level block (both inclusive). Accepts paragraph, table, cell, span, and range locators; cell/span/range collapse to their enclosing top-level block. Comment/image/hyperlink locators are rejected.
+`--from LOC` and `--to LOC` slice by top-level block (both inclusive). Accepts paragraph, table, cell, span, and range locators; cell/span/range collapse to their enclosing top-level block. Comment/image/hyperlink/tracked-change locators are rejected.
+
+**Tracked changes — three views.** By default, additive wrappers (`<w:ins>`, `<w:moveTo>`) render as CriticMarkup `{++text++}[^tcN]` and subtractive wrappers (`<w:del>`, `<w:moveFrom>`) as `{--text--}[^tcN]`, with `[^tcN]: insertion|deletion|moveTo|moveFrom by author (date)` definitions appended after any comment/footnote/endnote definitions. The `[^tcN]` reference is a stable positional id (`tc0`, `tc1`, …) that's also addressable as a locator and reported by `docx track-changes list`. Two flags switch view; they're mutually exclusive:
+
+- `--accepted` — post-accept view: `<w:del>` and `<w:moveFrom>` runs are dropped, `<w:ins>` and `<w:moveTo>` runs render as plain text. No CriticMarkup, no `[^tcN]` refs, no appendix.
+- `--baseline` — pre-change view: `<w:ins>` and `<w:moveTo>` runs are dropped, `<w:del>` and `<w:moveFrom>` runs render as plain text. No CriticMarkup, no `[^tcN]` refs, no appendix.
 
-`--changes` renders tracked insertions and deletions as `<ins>`/`<del>` instead of producing the accepted view (which silently drops deletions and inlines insertions).
+`docx wc` accepts the same `--accepted` / `--baseline` flags with parallel semantics: default counts everything currently on disk (plain + ins + del), `--accepted` skips deletions, `--baseline` skips insertions. The response includes a `view` field so agents know which mode the count was taken from.
 
 `--comments` appends a GFM footnote reference (`[^cN]`) at the end of each commented span and emits one footnote definition per comment at the end of the output:
 
@@ -98,11 +111,11 @@ Footnotes/endnotes (the document's own `<w:footnoteReference>` / `<w:endnoteRefe
 ### Locators
 
 ```
-pN              paragraph N (e.g., p3)
-pN:S-E          characters S..E within paragraph N
-pN:S-pM:E       cross-paragraph range
-tN              table N; tN:rRcC for cell at row R, col C
-cN, imgN, linkN comment / image / hyperlink ids
+pN                   paragraph N (e.g., p3)
+pN:S-E               characters S..E within paragraph N
+pN:S-pM:E            cross-paragraph range
+tN                   table N; tN:rRcC for cell at row R, col C
+cN, imgN, linkN, tcN comment / image / hyperlink / tracked-change ids
 ```
 
 Run `docx info locators` for the full reference.
@@ -139,10 +152,14 @@ src/
     insert/              # insert FILE  (uses ./emit Paragraph component)
     edit/                # edit FILE
     delete/              # delete FILE
+    find/                # find FILE QUERY
+    replace/             # replace FILE PATTERN REPLACEMENT
+    wc/                  # wc FILE [LOCATOR]
+    outline/             # outline FILE
     comments/            # add | reply | resolve | delete | list
     images/              # list | extract | replace
     hyperlinks/          # add | list | replace | delete
-    track-changes/       # FILE on|off
+    track-changes/       # on|off | list | accept | reject (apply.ts holds the unwrap/delete logic)
     info/                # schema | locators (reference output)
   core/
     package/             # JSZip open/close, named-part read/write