bun-docx 0.10.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LGPL-3.0.txt +165 -0
- package/NOTICES +181 -0
- package/README.md +170 -106
- package/dist/index.js +71850 -33767
- package/dist/pdfium-jj0zq23w.wasm +0 -0
- package/package.json +20 -4
package/README.md
CHANGED
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.loom.com/share/da70269a970f42caa138fb3389b4b9cc)
|
|
4
4
|
|
|
5
|
-
**
|
|
5
|
+
**A `.docx` CLI built for AI agents.** Leave comments, suggest redlines, and edit Word documents without breaking the formatting or losing content — a human accepts or rejects in Word afterward.
|
|
6
6
|
|
|
7
7
|
- Hand a `.docx` to Claude or Codex and get back a redlined copy with comments — open it in Word, accept or reject as usual.
|
|
8
|
-
- Agents
|
|
9
|
-
- Custom styles, theme colors, embedded objects — all of it survives.
|
|
8
|
+
- Agents address text by **stable locators** with character offsets (`p3:5-20`); humans see normal Word formatting on disk.
|
|
9
|
+
- Custom styles, theme colors, embedded objects — all of it survives. The CLI mutates XML in place rather than re-emitting from a lossy model.
|
|
10
10
|
|
|
11
11
|
## Install
|
|
12
12
|
|
|
@@ -38,19 +38,19 @@ bunx bun-docx read doc.docx
|
|
|
38
38
|
The repo includes a Common Paper Mutual NDA template at `tests/fixtures/mnda.docx`. Below are the primitives an agent would compose to fill in the cover page and leave redline edits — the same flow shown in the video above. Every command was verified end-to-end against the fixture:
|
|
39
39
|
|
|
40
40
|
```sh
|
|
41
|
-
# Make a copy first — there's no undo
|
|
41
|
+
# Make a copy first — there's no undo (git is the history; the CLI overwrites in place)
|
|
42
42
|
cp tests/fixtures/mnda.docx mnda-filled.docx
|
|
43
43
|
|
|
44
44
|
# Read the cover-page table so the agent knows what placeholders exist
|
|
45
|
-
docx read mnda-filled.docx --to t1
|
|
45
|
+
docx read mnda-filled.docx --from t1 --to t1
|
|
46
46
|
|
|
47
47
|
# Fill the yellow-highlighted bracketed placeholders
|
|
48
|
-
docx replace mnda-filled.docx "Fill in: today
|
|
48
|
+
docx replace mnda-filled.docx "Fill in: today's date" "May 6, 2026"
|
|
49
49
|
docx replace mnda-filled.docx "fill in state and/or county" "California"
|
|
50
50
|
docx replace mnda-filled.docx "fill in state" "California"
|
|
51
51
|
docx replace mnda-filled.docx "Fill in, if any." "None."
|
|
52
52
|
|
|
53
|
-
# Verify nothing's left to fill
|
|
53
|
+
# Verify nothing's left to fill (bare locator lines, one per match; nothing → exit 0)
|
|
54
54
|
docx find mnda-filled.docx '\[(Fill|fill)[^]]*\]' --regex --all
|
|
55
55
|
|
|
56
56
|
# Flip on tracked changes for the redline pass
|
|
@@ -61,71 +61,84 @@ docx replace mnda-filled.docx \
|
|
|
61
61
|
"having a reasonable need to know" \
|
|
62
62
|
"with a documented need to know"
|
|
63
63
|
|
|
64
|
-
# Leave a comment for the human reviewer
|
|
65
|
-
docx comments add mnda-filled.docx --
|
|
64
|
+
# Leave a comment for the human reviewer — addresses an existing span with --at
|
|
65
|
+
docx comments add mnda-filled.docx --at p7:0-30 \
|
|
66
66
|
--text "Should we narrow 'representatives' to a named list?"
|
|
67
67
|
```
|
|
68
68
|
|
|
69
|
-
Open `mnda-filled.docx` in Word: tracked changes and comments appear in the review pane, ready to accept, reject, or reply. Or run `docx track-changes accept
|
|
69
|
+
Open `mnda-filled.docx` in Word: tracked changes and comments appear in the review pane, ready to accept, reject, or reply. Or run `docx track-changes accept mnda-filled.docx --all` to bake them in from the CLI.
|
|
70
70
|
|
|
71
|
-
##
|
|
71
|
+
## `docx <command> --help` is the authoritative contract
|
|
72
|
+
|
|
73
|
+
> **Agents: run `docx <command> --help` before composing a call.** Every command's `--help` is the source of truth for its flags, locator forms, and exact output shape — this README is a map, not the territory. Two more must-reads:
|
|
74
|
+
>
|
|
75
|
+
> - **`docx info locators`** — the canonical locator grammar (`--json` for a machine-readable form). The top-level `docx --help` says it outright: *"It is highly recommended to agents to run `docx info locators` to understand their capabilities."*
|
|
76
|
+
> - **`docx info schema`** — the AST type definitions (`--ts` for TypeScript source) that `read --ast` emits.
|
|
77
|
+
|
|
78
|
+
## Command reference
|
|
79
|
+
|
|
80
|
+
`docx <verb>` and `docx <noun> <verb>`. Every command has `--help`. Two groups: **read/query** commands print data to stdout; **mutate** commands change the file (and accept `--dry-run`, `-o/--output PATH`, `-v/--verbose`).
|
|
81
|
+
|
|
82
|
+
### Read & query (print to stdout, never write the file)
|
|
72
83
|
|
|
73
84
|
```sh
|
|
74
|
-
docx
|
|
75
|
-
docx read
|
|
76
|
-
docx
|
|
77
|
-
docx
|
|
78
|
-
docx
|
|
79
|
-
docx
|
|
80
|
-
|
|
81
|
-
docx
|
|
82
|
-
docx
|
|
83
|
-
docx
|
|
84
|
-
docx
|
|
85
|
-
docx
|
|
86
|
-
docx
|
|
87
|
-
|
|
88
|
-
docx
|
|
89
|
-
docx
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
docx
|
|
97
|
-
docx
|
|
98
|
-
|
|
99
|
-
docx
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
85
|
+
docx read FILE [--from LOC] [--to LOC] [--accepted | --baseline | --current] [--comments]
|
|
86
|
+
docx read FILE --ast # JSON-AST instead of Markdown (disables the markdown-only flags)
|
|
87
|
+
docx find FILE QUERY [--regex] [--ignore-case] [--all] [--nth N] [--current | --baseline] [--exact] [--json]
|
|
88
|
+
docx wc FILE [LOCATOR] [--accepted | --baseline | --current] [--json]
|
|
89
|
+
docx outline FILE [--style-prefix S] [--json]
|
|
90
|
+
docx render FILE [--out DIR] [--engine word|libreoffice|auto] [--dpi N] [--pages 1-N] [--format png|jpg]
|
|
91
|
+
|
|
92
|
+
docx comments list FILE [--include-resolved] [--thread cN]
|
|
93
|
+
docx footnotes list FILE
|
|
94
|
+
docx endnotes list FILE
|
|
95
|
+
docx images list FILE
|
|
96
|
+
docx hyperlinks list FILE
|
|
97
|
+
docx track-changes list FILE
|
|
98
|
+
|
|
99
|
+
docx info schema [--ts]
|
|
100
|
+
docx info locators [--json]
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Mutate (change FILE in place; `--dry-run`, `-o PATH`, `-v` everywhere)
|
|
104
|
+
|
|
105
|
+
```sh
|
|
106
|
+
docx create FILE [--title T] [--author A] [--text "..." | --from PATH.md]
|
|
107
|
+
docx insert FILE (--after | --before) LOCATOR <content> # LOCATOR = pN | tN | sN | tN:rRcC:pK
|
|
108
|
+
docx edit FILE --at LOCATOR <content> # LOCATOR = pN | pN-pM | sN | eqN
|
|
109
|
+
docx delete FILE --at LOCATOR # LOCATOR = pN | pN-pM | tN | sN
|
|
110
|
+
docx replace FILE PATTERN REPLACEMENT [--regex] [--ignore-case] [--all] [--limit N] [--current | --baseline] [--exact]
|
|
111
|
+
|
|
112
|
+
# insert/edit content selectors (run "docx insert --help" / "docx edit --help" for the full list):
|
|
113
|
+
# --text "..." [--style NAME] [--alignment A] [--color HEX] [--bold] [--italic] [--url URL]
|
|
114
|
+
# --runs '[{"type":"text","text":"X","bold":true}]'
|
|
115
|
+
# --markdown "..." | --markdown-file PATH # GFM + math + CriticMarkup → one or more blocks
|
|
116
|
+
# --code "..." | --code-file PATH [--language LANG]
|
|
117
|
+
# --equation "x^2 + y^2" [--display|--inline]
|
|
118
|
+
# --task checked|unchecked | --list bullet|ordered [--list-level N] (insert)
|
|
119
|
+
# --task checked|unchecked (edit, flip in place)
|
|
120
|
+
# --table --rows N --cols N [--widths "A,B,C"] [--table-width V] [--borders S] [--layout L] (insert)
|
|
121
|
+
# --image SRC [--alt T] [--width IN] [--height IN] (insert; SRC = path, data: URI, or http(s) URL)
|
|
122
|
+
# --page-break | --column-break | --section [--columns N] [--type T] (insert)
|
|
123
|
+
|
|
124
|
+
docx comments add FILE --at LOCATOR --text "..." [--author NAME] [--current | --baseline]
|
|
103
125
|
docx comments add FILE --anchor "phrase" --text "..." [--occurrence N]
|
|
104
|
-
docx comments add FILE --batch reviews.jsonl
|
|
105
|
-
docx comments reply FILE --
|
|
106
|
-
docx comments resolve FILE --
|
|
107
|
-
docx comments
|
|
108
|
-
|
|
109
|
-
docx
|
|
110
|
-
docx
|
|
111
|
-
docx
|
|
112
|
-
docx
|
|
113
|
-
|
|
114
|
-
docx
|
|
115
|
-
|
|
116
|
-
docx
|
|
117
|
-
docx footnotes list FILE
|
|
118
|
-
docx endnotes add FILE --at pN[:offset] --text "..."
|
|
119
|
-
docx endnotes edit FILE --id enN --text "..."
|
|
120
|
-
docx endnotes delete FILE --id enN
|
|
121
|
-
docx endnotes list FILE
|
|
122
|
-
|
|
123
|
-
docx images list FILE
|
|
124
|
-
docx images extract FILE --to ./media [--id imgN]
|
|
126
|
+
docx comments add FILE --batch reviews.jsonl # JSONL: { at | anchor (+occurrence), text, author? }
|
|
127
|
+
docx comments reply FILE --at cN --text "..."
|
|
128
|
+
docx comments resolve FILE --at cN [--at cM ...] [--unset] | --batch resolutions.jsonl
|
|
129
|
+
docx comments delete FILE --at cN [--at cM ...] | --batch removals.jsonl
|
|
130
|
+
|
|
131
|
+
docx footnotes add FILE --at pN[:offset] (--text "..." | --runs JSON | --markdown TEXT)
|
|
132
|
+
docx footnotes edit FILE --at fnN (--text "..." | --runs JSON | --markdown TEXT)
|
|
133
|
+
docx footnotes delete FILE --at fnN
|
|
134
|
+
docx endnotes add FILE --at pN[:offset] (--text "..." | --runs JSON | --markdown TEXT)
|
|
135
|
+
docx endnotes edit FILE --at enN (--text "..." | --runs JSON | --markdown TEXT)
|
|
136
|
+
docx endnotes delete FILE --at enN
|
|
137
|
+
|
|
138
|
+
docx images extract FILE --to DIR [--at imgN] # --to = output directory; --at picks one image
|
|
125
139
|
docx images replace FILE --at imgN --with ./new.png
|
|
126
140
|
docx images delete FILE --at imgN
|
|
127
141
|
|
|
128
|
-
docx hyperlinks list FILE
|
|
129
142
|
docx hyperlinks add FILE --at pN:S-E --url URL
|
|
130
143
|
docx hyperlinks replace FILE --at linkN --with URL
|
|
131
144
|
docx hyperlinks delete FILE --at linkN
|
|
@@ -140,92 +153,143 @@ docx tables unmerge FILE --at tN:rRcC
|
|
|
140
153
|
docx tables borders FILE --at tN [--style single|double|none] [--size N] [--color HEX]
|
|
141
154
|
|
|
142
155
|
docx track-changes FILE on|off
|
|
143
|
-
docx track-changes list FILE
|
|
144
156
|
docx track-changes accept FILE (--at tcN [--at tcM ...] | --all)
|
|
145
157
|
docx track-changes reject FILE (--at tcN [--at tcM ...] | --all)
|
|
146
|
-
docx info schema [--ts]
|
|
147
|
-
docx info locators [--json]
|
|
148
158
|
```
|
|
149
159
|
|
|
150
|
-
|
|
160
|
+
> **One rule to memorize: addressing an existing thing is always `--at`.**
|
|
161
|
+
> `comments reply/resolve/delete`, `footnotes/endnotes edit/delete`, `images extract/replace/delete`, `hyperlinks replace/delete`, `tables *`, `track-changes accept/reject`, `edit`, and `delete` all take `--at LOCATOR`. The exceptions are positional or directional by nature: `insert` uses `--after`/`--before LOCATOR`; `read` slices with `--from`/`--to LOCATOR`; `wc` takes a positional `[LOCATOR]`; `find`/`replace` take a positional `QUERY`/`PATTERN`. `images extract --to DIR` is an *output directory*, not a locator.
|
|
162
|
+
|
|
163
|
+
## Output contract
|
|
151
164
|
|
|
152
|
-
|
|
165
|
+
The CLI is built for non-interactive agents. **Exit code is the success signal**, output is data:
|
|
153
166
|
|
|
154
|
-
|
|
167
|
+
| Exit | Meaning | Error codes |
|
|
168
|
+
| ---- | ------- | ----------- |
|
|
169
|
+
| `0` | success | — |
|
|
170
|
+
| `2` | usage / bad locator | `USAGE`, `INVALID_LOCATOR` |
|
|
171
|
+
| `3` | addressed thing not found | `FILE_NOT_FOUND`, `PART_NOT_FOUND`, `BLOCK_NOT_FOUND`, `COMMENT_NOT_FOUND`, `IMAGE_NOT_FOUND`, `HYPERLINK_NOT_FOUND`, `TRACKED_CHANGE_NOT_FOUND`, `MATCH_NOT_FOUND` |
|
|
172
|
+
| `1` | general failure | `NOT_A_ZIP`, `TRACKED_CHANGE_CONFLICT`, `TABLE_STRUCTURE`, `IMAGE_SOURCE`, `RENDER_ENGINE`, `RENDER_FAILED`, `UNHANDLED` |
|
|
155
173
|
|
|
156
|
-
|
|
174
|
+
**Errors** print `{code, error, hint?}` JSON to stdout with a nonzero exit — note there is **no `ok` field**; the exit code plus `code` are the unambiguous signal.
|
|
157
175
|
|
|
158
|
-
|
|
176
|
+
**The `ok` field appears in exactly one place: the `--verbose` success ack** (`{ok:true, operation, path, …}`). Without `-v`, success output is shaped for the next command:
|
|
159
177
|
|
|
160
|
-
|
|
178
|
+
| Command class | Default stdout on success | `--verbose` |
|
|
179
|
+
| ------------- | ------------------------- | ----------- |
|
|
180
|
+
| **Mutator that mints a new handle** — `comments add`→`cN`, `comments reply`→`cN`, `footnotes/endnotes add`→`fnN`/`enN`, `hyperlinks add`→`linkN`, `insert`→the new `pN` | the bare locator(s), **one per line** (a multi-block `--markdown` insert prints several) | full `{ok:true,…}` ack |
|
|
181
|
+
| **Mutator with no new handle** — `edit`, `delete`, `replace`, `create`, `comments resolve/delete`, `images replace/delete`, `hyperlinks replace/delete`, `footnotes/endnotes edit/delete`, `tables *`, `track-changes accept/reject` & toggle | **silent** (exit `0`) | full `{ok:true,…}` ack |
|
|
182
|
+
| `find` | matched span locators, one per line (no matches → nothing, exit `0`) | `--json` → `{ totalMatches, query, view, matches:[…], normalizedQuery? }` |
|
|
183
|
+
| `wc` | the bare count (whole-doc adds a tab-separated `sections` column, like `wc`) | `--json` → `{ words, scope, view, sections? }` |
|
|
184
|
+
| `outline` | indented `LOCATOR⇥TEXT` tree (two spaces per level) | `--json` → nested `[{ id, locator, level, style, text, children }]` |
|
|
185
|
+
| `read` | GFM Markdown, each paragraph trailed by `<!-- pN -->` | `--ast` → the JSON AST body (`docx info schema`) |
|
|
186
|
+
| `render` | image paths, one per line | `--verbose` → `{ok, operation, path, engine, output, pages}` |
|
|
187
|
+
| `* list` (all six `list` verbs) | a **bare JSON array**; each item's `id` is its `--at` handle | — |
|
|
161
188
|
|
|
162
|
-
-
|
|
163
|
-
- `--baseline` — pre-change view: drops `<w:ins>` and `<w:moveTo>`, renders `<w:del>` and `<w:moveFrom>` as plain text.
|
|
164
|
-
- `--current` — raw concatenation, with diff markup. Additive wrappers render as CriticMarkup `{++text++}[^tcN]` and subtractive as `{--text--}[^tcN]`, with `[^tcN]: …` definitions appended at end.
|
|
189
|
+
`--dry-run` always prints a preview object (no `ok`) and writes nothing; it wins over `-o/--output`.
|
|
165
190
|
|
|
166
|
-
|
|
191
|
+
## Discovering ids
|
|
167
192
|
|
|
168
|
-
|
|
193
|
+
Locators come in two flavors. **Positional block ids** (`pN`, `tN`, `sN`) are derived from document order and **shift after structural edits** — re-read between non-trivial mutations. **Entity ids** (`cN`, `imgN`, `linkN`, `fnN`, `enN`, `tcN`, `eqN`) are surfaced by a `list` verb (or `read --ast`) and are what you pass to `--at`:
|
|
169
194
|
|
|
170
|
-
|
|
195
|
+
| Id | Discover with | Used by |
|
|
196
|
+
| -- | ------------- | ------- |
|
|
197
|
+
| `pN` / `tN` / `sN` (block ids) | `docx read FILE` (the `<!-- pN -->` trailers), `docx read FILE --ast`, `docx outline FILE` (heading `pN`s), or `docx render` page images | `read`, `edit`, `insert`, `delete`, `wc`, `find` results |
|
|
198
|
+
| `cN` (comment) | `docx comments list FILE` | `comments reply/resolve/delete --at` |
|
|
199
|
+
| `fnN` / `enN` (foot/endnote) | `docx footnotes list FILE` / `docx endnotes list FILE` | `footnotes/endnotes edit/delete --at` |
|
|
200
|
+
| `imgN` (image) | `docx images list FILE` | `images extract/replace/delete --at` |
|
|
201
|
+
| `linkN` (hyperlink) | `docx hyperlinks list FILE` | `hyperlinks replace/delete --at` |
|
|
202
|
+
| `tcN` (tracked change) | `docx track-changes list FILE` | `track-changes accept/reject --at` |
|
|
203
|
+
| `eqN` (equation) | `docx read FILE --ast` (run `latex` field) | `edit --at eqN --equation` |
|
|
171
204
|
|
|
172
|
-
|
|
205
|
+
Each `list` verb prints a bare JSON array where every item's `id` is exactly the handle you feed back to `--at` — pipe through `jq` to filter (`docx comments list doc.docx | jq '.[] | select(.author=="Jane")'`).
|
|
173
206
|
|
|
174
|
-
|
|
207
|
+
## Locators
|
|
175
208
|
|
|
176
|
-
`
|
|
209
|
+
`docx info locators` (`--json` for machine-readable) is the canonical reference. The grammar in brief:
|
|
177
210
|
|
|
178
|
-
|
|
211
|
+
```
|
|
212
|
+
pN paragraph N pN:S-E chars S..E within paragraph N
|
|
213
|
+
pN-pM whole-paragraph range pN:S-pM:E cross-paragraph character range
|
|
214
|
+
sN section break N tN table N
|
|
215
|
+
tN:rRcC cell at row R, col C tN:rRcC:pK paragraph K of that cell (chainable)
|
|
216
|
+
tN:rR / tN:cC table row R / column C tN:rR1cC1-rR2cC2 rectangular cell region (merge)
|
|
217
|
+
cN imgN linkN fnN enN tcN eqN entity ids (comment / image / hyperlink /
|
|
218
|
+
footnote / endnote / tracked-change / equation)
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
**Offset semantics: character offsets are 0-based, start-inclusive, end-exclusive** — `p3:5-20` is the 15 characters at indices 5..19 of paragraph 3. Offsets count the *visible* text of the paragraph in the selected view (accepted by default).
|
|
179
222
|
|
|
180
|
-
|
|
223
|
+
**Nested tables chain the same syntax** arbitrarily deep — `t0:r2c1:t0:r0c0:p0` is the first paragraph of the (0,0) cell of the first table nested inside the (2,1) cell of the document's first table.
|
|
181
224
|
|
|
182
|
-
|
|
225
|
+
**Not every command accepts every form** — each command's `--at`/`--from`/positional help lists exactly what it takes. The shapes:
|
|
183
226
|
|
|
184
|
-
|
|
227
|
+
| Form | Accepted by |
|
|
228
|
+
| ---- | ----------- |
|
|
229
|
+
| `pN`, `tN`, `sN`, `tN:rRcC:pK` (blocks) | `read --from/--to`, `insert --after/--before`, `wc`, `comments add` |
|
|
230
|
+
| `pN`, `pN-pM`, `sN`, `eqN` | `edit --at` |
|
|
231
|
+
| `pN`, `pN-pM`, `tN`, `sN` | `delete --at` |
|
|
232
|
+
| `pN:S-E`, `pN:S-pM:E`, `tN:rRcC:pK:S-E` (spans) | `comments add --at`, `hyperlinks add --at` (single paragraph), `find`/`wc` results |
|
|
233
|
+
| `pN[:offset]` (point) | `footnotes/endnotes add --at` |
|
|
234
|
+
| `cN` / `fnN` / `enN` / `imgN` / `linkN` / `tcN` (entities) | the matching noun's `--at` (the `c`/`fn`/`en`/`img`/`link`/`tc` prefix is optional) |
|
|
235
|
+
| `tN`, `tN:rR`, `tN:cC`, `tN:rRcC`, `tN:rR1cC1-rR2cC2` | the `tables` verbs |
|
|
185
236
|
|
|
186
|
-
|
|
237
|
+
## Common workflows
|
|
187
238
|
|
|
188
|
-
|
|
239
|
+
**find → comment.** `find` emits bare locators that drop straight into `comments add --at` (same default view, so offsets line up — no coordinate translation):
|
|
189
240
|
|
|
241
|
+
```sh
|
|
242
|
+
docx comments add doc.docx --at "$(docx find doc.docx 'fatally flawed' | head -1)" \
|
|
243
|
+
--text "Cite a source here?"
|
|
244
|
+
# or anchor by phrase directly:
|
|
245
|
+
docx comments add doc.docx --anchor "fatally flawed" --text "Cite a source here?"
|
|
190
246
|
```
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
cN, imgN, linkN, tcN comment / image / hyperlink / tracked-change ids
|
|
247
|
+
|
|
248
|
+
**read → edit markdown round-trip.** `read` emits a markdown dialect that `edit --markdown` re-parses, so render → LLM-rewrite → splice-back is lossless for paragraphs/lists/quotes:
|
|
249
|
+
|
|
250
|
+
```sh
|
|
251
|
+
docx read doc.docx --from p3 --to p3 # → markdown (with <!-- p3 --> trailer)
|
|
252
|
+
# … hand to an LLM, get a revised block back …
|
|
253
|
+
docx edit doc.docx --at p3 --markdown-file revised.md # multi-block source expands naturally
|
|
199
254
|
```
|
|
200
255
|
|
|
201
|
-
|
|
256
|
+
Use `--markdown-file` (not `--markdown TEXT`) when the source starts with `-` — Node's `parseArgs` rejects leading-dash flag values.
|
|
202
257
|
|
|
203
|
-
|
|
258
|
+
**track-changes review loop.** Toggle tracking on, make edits (they auto-emit `<w:ins>`/`<w:del>`), then inventory and resolve:
|
|
204
259
|
|
|
205
|
-
|
|
260
|
+
```sh
|
|
261
|
+
docx track-changes doc.docx on
|
|
262
|
+
docx replace doc.docx "old phrasing" "new phrasing" --all
|
|
263
|
+
docx track-changes list doc.docx # → JSON array of { id:tcN, kind, author, text, … }
|
|
264
|
+
docx read doc.docx --current # → CriticMarkup {++ins++}[^tcN] / {--del--}[^tcN]
|
|
265
|
+
docx track-changes accept doc.docx --at tc0 --at tc2 # or --all
|
|
266
|
+
```
|
|
206
267
|
|
|
207
|
-
|
|
268
|
+
`read` has three tracked-change views: default **`current`** shows CriticMarkup with `[^tcN]` footnotes; **`--accepted`** drops subtractive edits and inlines additive ones (the post-accept document); **`--baseline`** does the reverse (the pre-change document). `find`, `replace`, `wc`, and `comments add` honor the same `--accepted`/`--baseline`/`--current` flags so offsets stay consistent across commands. Add `--comments` to `read` to append `[^cN]` footnotes for comment spans.
|
|
208
269
|
|
|
209
|
-
|
|
270
|
+
## How It Works
|
|
210
271
|
|
|
211
|
-
**
|
|
272
|
+
**In-place XML mutation.** The AST returned by `read` is a _view_ over the parsed XML tree, not a separate model. When you `edit` or `comments add`, the CLI mutates the underlying XML nodes directly and serializes back. Anything not modeled in the AST (custom styles, theme colors, schema extensions) survives because untouched regions are never re-emitted. Never delete a relationship something still references — that corrupts the file — so part/relationship pruning is gated on a reference scan; unreferenced orphans are left in place.
|
|
212
273
|
|
|
213
|
-
**
|
|
274
|
+
**JSX for emitters.** Constructing OOXML fragments imperatively (`<w:rPr>` → `<w:b/>` → `<w:color w:val="800080"/>`) is verbose, so fresh XML is authored in JSX with a custom factory: `<w.rPr><w.b/><w.color w-val="800080"/></w.rPr>` becomes the right `XmlNode` tree.
|
|
214
275
|
|
|
215
|
-
**
|
|
276
|
+
**Span-aware comments & hyperlinks.** `comments add --at p3:5-20` (and `hyperlinks add`) find the runs containing offsets 5 and 20, split them at the boundaries (preserving `<w:rPr>` on both halves), and insert markers between the slices. Comments authored by older tools that lack `w14:paraId` (required by `commentsExtended.xml`) get a fresh paraId injected automatically on resolve/reply.
|
|
216
277
|
|
|
217
|
-
**
|
|
278
|
+
**Tracked changes.** With `<w:trackChanges/>` set, `insert`/`edit`/`delete`/`replace` emit native `<w:ins>`/`<w:del>` (attributed via `--author`, `$DOCX_AUTHOR`, or `docx-cli`). `edit --at pN --text` runs a word-level diff so unchanged words keep their formatting and only changed words are wrapped — the same shape Word produces mid-tracking. `accept`/`reject` handle run-level ins/del/moveFrom/moveTo, `sectPrChange`, paragraph-mark ins/del, and the table-structural revisions (rowIns/rowDel, cellIns/cellDel, tblGridChange, tcPrChange). OOXML has no tracked-change construct for hyperlink edits or image swaps, so under tracking those emit a `[docx-cli]` audit comment instead of a fake revision (image *deletion* is honest removal — it wraps a real `<w:del>`).
|
|
218
279
|
|
|
219
|
-
**
|
|
280
|
+
**Rich content.** Images insert from a path, `data:` URI, or `http(s)` URL (bounded fetch; HEIC→JPEG transcode; SVG sanitized; non-public/metadata addresses refused at every redirect hop). Equations round-trip OOXML `<m:oMath>` ↔ LaTeX (reconstructed, not legacy plaintext) — authored via temml (LaTeX→MathML) plus an in-house MathML→OMML adapter, no LGPL deps. Code blocks emit one `CodeBlock`-styled paragraph per line with optional lowlight syntax highlighting (37 bundled languages); they collapse back to a GFM fenced block on read. GFM task lists round-trip Word's checkbox content control (and the Word-for-Web Wingdings-glyph variant), surfacing as `taskState` in the AST. Tables operate on a merge-aware logical grid so `gridSpan`/`vMerge` cells map onto physical `<w:tc>`, and structural edits refuse to bisect an existing merge.
|
|
220
281
|
|
|
221
|
-
**
|
|
282
|
+
**Markdown dialect.** `create --from`, `insert/edit --markdown`, and the note bodies all parse the same GFM + math + CriticMarkup dialect (remark + remark-gfm + remark-math), composing the existing OOXML emitters. `read` emits a compatible dialect, so the read → edit → write loop round-trips (lossless for paragraphs, lists, and nested blockquotes; code/tables/math/headings inside a blockquote intentionally escape to top level on import).
|
|
222
283
|
|
|
223
|
-
**
|
|
284
|
+
**Visual verification.** `docx render` is the only command that needs an external runtime: it drives Microsoft Word (macOS via `osascript`, Windows via PowerShell COM — the ground-truth renderer) or LibreOffice (`soffice`, cross-platform) to produce a PDF, then rasterizes in-process via the bundled `@hyzyla/pdfium` WASM package — no poppler/pdftoppm/ImageMagick needed. Agents that consume PNGs use this to verify edits, diff accept/reject before-vs-after, or generate screenshots.
|
|
224
285
|
|
|
225
286
|
## Stack
|
|
226
287
|
|
|
227
288
|
- **Runtime**: Bun (`node:util` parseArgs, JSX with custom factory, native zlib)
|
|
228
289
|
- **Parser**: [`jszip`](https://www.npmjs.com/package/jszip) + [`fast-xml-parser`](https://www.npmjs.com/package/fast-xml-parser) + [`fast-xml-builder`](https://www.npmjs.com/package/fast-xml-builder)
|
|
290
|
+
- **Markdown**: [`unified`](https://www.npmjs.com/package/unified) + [`remark-parse`](https://www.npmjs.com/package/remark-parse) + [`remark-gfm`](https://www.npmjs.com/package/remark-gfm) + [`remark-math`](https://www.npmjs.com/package/remark-math)
|
|
291
|
+
- **Math**: [`temml`](https://www.npmjs.com/package/temml) (MIT) compiles LaTeX → MathML; an in-house MathML → OMML adapter handles the OOXML side bidirectionally
|
|
292
|
+
- **Render**: [`@hyzyla/pdfium`](https://www.npmjs.com/package/@hyzyla/pdfium) (MIT wrapper + Apache-2.0 PDFium-as-WASM) for the PDF → PNG/JPG step, plus [`pngjs`](https://www.npmjs.com/package/pngjs) / [`jpeg-js`](https://www.npmjs.com/package/jpeg-js) for image encoding
|
|
229
293
|
- **Images**: [`heic-convert`](https://www.npmjs.com/package/heic-convert) (wasm libheif) transcodes HEIC/HEIF input to JPEG on insert
|
|
230
294
|
- **Quality**: Biome + Knip + tsc; LibreOffice headless for round-trip integration tests
|
|
231
295
|
- **Standard**: ECMA-376 Part 1 §17 (WordprocessingML), Transitional profile
|