# DOCX OOXML tools

The bundled CLI is a self-contained fallback for package diagnostics and safe
DOCX operations. Prefer `word_document` through `office-node`; use this CLI
only when MCP is unavailable, does not expose the requested capability, or a
package-level diagnostic is needed.

```text
node dist/docx-ooxml-cli.mjs inspect input.docx --json
node dist/docx-ooxml-cli.mjs unpack input.docx --output workdir --json
node dist/docx-ooxml-cli.mjs validate workdir --json
node dist/docx-ooxml-cli.mjs pack workdir --output output.docx --json
node dist/docx-ooxml-cli.mjs outline input.docx --json
node dist/docx-ooxml-cli.mjs section input.docx --operation replace_content --section-id chapter-one --content "Nuovo testo" --output output.docx --json
node dist/docx-ooxml-cli.mjs replace-text input.docx --find "old text" --replace "new text" --output result.docx --json
node dist/docx-ooxml-cli.mjs revisions input.docx --intent track_replace --find "old" --replace "new" --author "A. User" --output result.docx --json
node dist/docx-ooxml-cli.mjs comments input.docx --find "text" --text "Check this" --author "A. User" --output result.docx --json
node dist/docx-ooxml-cli.mjs images input.docx --intent replace --relationship-id rIdImage1 --image replacement.png --output result.docx --json
node dist/docx-ooxml-cli.mjs relationships input.docx --json
node dist/docx-ooxml-cli.mjs render input.docx --output-dir rendered --json
```

`unpack` refuses to overwrite its output directory. `pack` reconstructs an
archive only from the manifest produced by `unpack`; it rejects symlinks and
unmanifested or missing parts. The validation report includes untouched-part
hash preservation. Encrypted, macro-enabled, ZIP64, path-traversal and
over-limit archives are rejected with structured error codes.

This tool is intentionally independent of `office-node`, npm dependencies, the
repository path and the current working directory. It requires Node.js 20+.

For section editing, inspect the outline first. IDs are stable within the
current document; title matching is exact and ambiguous titles fail. `read`
does not write. Every other operation requires a separate `--output` path.

`replace_text` is available through `word_document` for visible-text matches
that cross Word runs. It refuses multiple matches unless explicitly enabled and
supports `dry_run`; replacement always writes a separate output file.

`revisions` accepts `track_replace`, `accept`, `reject`, and
`validate_author`. The initial tracked-replace slice supports a single text run
deliberately; cross-run tracking remains blocked rather than emitting a
potentially invalid redline.

Anchored comments are available through `word_document(action="comments")`.
They create a separate DOCX and add the comment part, relationship, content
type override and in-document anchor. Replies use `parent_comment_id`.

Embedded image replacement retains the original relationship and target part.
Use the MCP `images/replace` action with a PNG/JPEG of the same extension, then
run `validate/relationships`. The optional render validation reports when
LibreOffice is unavailable instead of installing or downloading it.

## Build and test boundary

An ephemeral `docx-ooxml-core` source workspace may be used to build and test
this file, but it is not distributed or committed. The bundle is never allowed
to import it at runtime, nor to depend on an MCP server or repository checkout.
The equivalent generated library for future `office-node` actions is
`office-node/lib/generated/docx-ooxml-core.mjs`; it follows the same contract
but is not a runtime dependency of this bundle.

## Licences and dependencies

No third-party runtime dependency is bundled. The implementation uses only
Node.js standard-library modules (`crypto`, `fs`, `path`, `url`, `zlib`).