bun-docx 0.2.0 → 0.3.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/README.md +11 -12
- package/dist/index.js +863 -573
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,13 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
A Bun-built CLI for AI agents (Claude, Codex) to read, edit, and comment on `.docx` files with full format fidelity. Outputs JSON-AST for precise locator-based editing; preserves anything it doesn't model by mutating XML in place.
|
|
4
4
|
|
|
5
|
-
## Stack
|
|
6
|
-
|
|
7
|
-
- **Runtime**: Bun (`node:util` parseArgs, JSX with custom factory, native zlib)
|
|
8
|
-
- **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)
|
|
9
|
-
- **Quality**: Biome + Knip + tsc; LibreOffice headless for round-trip integration tests
|
|
10
|
-
- **Standard**: ECMA-376 Part 1 §17 (WordprocessingML), Transitional profile
|
|
11
|
-
|
|
12
5
|
## Install
|
|
13
6
|
|
|
14
7
|
**Standalone binary** (no Bun required):
|
|
@@ -51,7 +44,6 @@ docx comments add FILE --range p3:5-20 --text "..." [--author NAME]
|
|
|
51
44
|
docx comments reply FILE --to c0 --text "..."
|
|
52
45
|
docx comments resolve FILE --id c0 [--unset]
|
|
53
46
|
docx comments delete FILE --id c0
|
|
54
|
-
docx comments restore FILE --id c0
|
|
55
47
|
docx comments list FILE [--include-resolved] [--thread c0]
|
|
56
48
|
|
|
57
49
|
docx images list FILE
|
|
@@ -63,7 +55,9 @@ docx info schema [--ts]
|
|
|
63
55
|
docx info locators [--json]
|
|
64
56
|
```
|
|
65
57
|
|
|
66
|
-
Every command has `--help`.
|
|
58
|
+
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.
|
|
59
|
+
|
|
60
|
+
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.
|
|
67
61
|
|
|
68
62
|
### Locators
|
|
69
63
|
|
|
@@ -109,7 +103,7 @@ src/
|
|
|
109
103
|
insert/ # insert FILE (uses ./emit Paragraph component)
|
|
110
104
|
edit/ # edit FILE
|
|
111
105
|
delete/ # delete FILE
|
|
112
|
-
comments/ # add | reply | resolve | delete |
|
|
106
|
+
comments/ # add | reply | resolve | delete | list
|
|
113
107
|
images/ # list | extract | replace
|
|
114
108
|
track-changes/ # FILE on|off
|
|
115
109
|
info/ # schema | locators (reference output)
|
|
@@ -124,6 +118,13 @@ tests/
|
|
|
124
118
|
fixtures/
|
|
125
119
|
```
|
|
126
120
|
|
|
121
|
+
## Stack
|
|
122
|
+
|
|
123
|
+
- **Runtime**: Bun (`node:util` parseArgs, JSX with custom factory, native zlib)
|
|
124
|
+
- **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)
|
|
125
|
+
- **Quality**: Biome + Knip + tsc; LibreOffice headless for round-trip integration tests
|
|
126
|
+
- **Standard**: ECMA-376 Part 1 §17 (WordprocessingML), Transitional profile
|
|
127
|
+
|
|
127
128
|
## How It Works
|
|
128
129
|
|
|
129
130
|
**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`, we mutate the underlying XML nodes directly and serialize back. Anything we don't model in the AST (custom styles, theme colors, schema extensions) survives because we never re-emit untouched regions.
|
|
@@ -136,8 +137,6 @@ tests/
|
|
|
136
137
|
|
|
137
138
|
**Cross-format image replacement.** `images replace --at img0 --with new.png` detects the new MIME type via `Bun.file().type`, renames the part (`word/media/image1.jpeg` → `word/media/image1.png`), rewrites the relationship `Target`, and ensures `[Content_Types].xml` has a `<Default>` for the new extension.
|
|
138
139
|
|
|
139
|
-
**Trash for restore.** `comments delete` journals the removed comment XML + anchor info to `<dir>/.docx-cli/trash.json` so `comments restore --id cN` can re-anchor it at its original location.
|
|
140
|
-
|
|
141
140
|
## CI
|
|
142
141
|
|
|
143
142
|
GitHub Actions (`.github/workflows/ci.yml`) runs four jobs on push to `main` and on PRs:
|