bun-docx 0.17.0 → 0.19.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "bun-docx",
-	"version": "0.17.0",
-	"description": "CLI for AI agents (Claude, Codex) to read, edit, and comment on .docx files with full format fidelity.",
+	"version": "0.19.0",
+	"description": "Read, edit, redline, and comment on Microsoft Word .docx files from the command line — built for AI agents.",
 	"keywords": [
 		"docx",
 		"openxml",
@@ -11,8 +11,15 @@
 		"ai",
 		"claude",
 		"codex",
-		"agentic"
+		"agentic",
+		"agent-skill",
+		"pi-package"
 	],
+	"pi": {
+		"skills": [
+			"./skills"
+		]
+	},
 	"license": "MIT",
 	"author": "Kirill Klimuk",
 	"repository": {
@@ -29,6 +36,7 @@
 	"files": [
 		"dist/index.js",
 		"dist/pdfium-*.wasm",
+		"skills/",
 		"README.md",
 		"LICENSE",
 		"LGPL-3.0.txt",

package/skills/docx-cli/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: docx-cli
+description: "Read, edit, redline, comment on, and create Microsoft Word .docx files. Use to fill out or edit a Word doc, redline a contract with tracked changes, add/resolve comments, replace text keeping its formatting, restyle headings/fonts, edit tables, or read/extract a .docx as Markdown or text. Also BUILD a new .docx — from Markdown or programmatically (code that outputs a Word report with headings, tables, images). Not for PDF, Google Docs, Excel, PowerPoint, or .doc."
+---
+
+# docx-cli
+
+`docx` is a command-line tool for reading, editing, redlining, and commenting on
+Microsoft Word `.docx` files. It edits the underlying OOXML **in place** (it never
+rebuilds the document from a lossy view), addresses everything with **stable
+locators**, and signals success through an **exit code** plus a one-line
+confirmation — so even small, cheap models can drive it reliably.
+
+## 0. Make sure the binary is on PATH
+
+Run `docx --version`. If you get "command not found", install it:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/kklimuk/docx-cli/main/install.sh | sh
+```
+
+Or, from this skill folder, run `bash scripts/bootstrap.sh` — it checks the
+installed version against the latest release and self-updates. Every verb works
+against the `.docx` zip directly; only `docx render` needs Word (macOS/Windows)
+or LibreOffice installed.
+
+## 1. The contract is `--help` / `docx info` — start there
+
+The help text is authoritative and versioned with the binary. This skill is thin
+on purpose and defers to it. Before doing anything, run (none of these need a FILE):
+
+```sh
+docx --help              # every command + a one-line capability hint each
+docx info locators       # the addressing grammar — READ THIS, it is the backbone
+docx info schema         # the JSON-AST shape that "docx read --ast" emits
+```
+
+Then `docx <command> --help` for any verb before you use it.
+
+## 2. Locators — how you address things
+
+- `pN` paragraph, `tN` table, `sN` section; `p3:5-20` = characters 5..19 of `p3`;
+  `pN-pM` a block range; `tN:rRcC` a table cell.
+- Entities: `cN` comment, `imgN` image, `linkN` hyperlink, `fnN`/`enN`
+  foot/endnote, `tcN` tracked change, `eqN` equation.
+- Get them from `docx read FILE` (locators ride the Markdown as `<!-- pN -->`
+  comments) or `docx read FILE --ast` (lossless JSON).
+- **Ids are positional and SHIFT after structural edits.** Re-read between
+  mutations — OR apply many changes from ONE read with `--batch` (below).
+- Pass a locator with `--at` (edit / delete / comments / footnotes / images /
+  hyperlinks / tables / track-changes), `--after`/`--before` (insert), or
+  `--from`/`--to` (read a slice).
+- Don't hand-count character offsets: `docx find FILE "phrase"` returns the exact
+  span locator (e.g. `p3:5-20`) to paste into `--at`.
+
+## 3. Golden workflows
+
+### Fill out a form or contract (keeps formatting)
+`docx replace` swaps only the text and preserves the run's bold/font and any tab
+stops — so it fills bold, tabbed template lines without rebuilding runs.
+```sh
+docx read contract.docx                                  # see content + locators
+docx replace contract.docx "[Client Name]" "Acme, Inc."  # one field
+docx replace contract.docx --batch fills.jsonl           # many fields, one read/write
+```
+
+### Redline with tracked changes
+```sh
+docx track-changes on contract.docx       # turn tracking on (doc-level)
+docx replace contract.docx "Net 90" "Net 30"   # now auto-emits <w:ins>/<w:del>
+docx edit --at p12:0-40 contract.docx --text "…" --track   # or redline one edit
+docx track-changes list contract.docx     # the tcN handles
+docx read contract.docx --current         # view redlines as CriticMarkup
+docx track-changes accept contract.docx --at tc3   # or --all / reject
+```
+
+### Comment on clauses
+```sh
+docx comments add contract.docx --anchor "limitation of liability" --text "Cap is too low."
+docx comments list contract.docx
+docx comments reply contract.docx --at c0 --text "Agreed, raising to \$5M."
+docx comments resolve contract.docx --at c0
+```
+
+### Read / extract
+```sh
+docx read FILE            # Markdown (default; tracked changes shown accepted-clean)
+docx read FILE --ast      # lossless JSON AST
+docx wc FILE              # word count (whole doc or a slice)
+docx outline FILE         # headings as a locator tree
+```
+
+### Build from scratch / verify layout
+```sh
+docx create out.docx --from draft.md      # GFM + math + CriticMarkup + inline HTML
+docx render FILE --out pages/             # PNG per page — only when LAYOUT is the question
+```
+
+## 4. Apply many changes from one read — `--batch`
+
+`edit`, `insert`, `replace`, `delete`, and the `comments` verbs take
+`--batch FILE.jsonl` (one JSON change per line; `-` reads stdin). Every locator
+in the batch addresses the document **as read**, so ids stay valid across the whole
+batch — one read, one write, no re-reading between changes. Keys mirror the
+command's flags. This is the right tool for filling a form or applying a review.
+
+## 5. Output & safety contract
+
+- **Exit code is the success signal:** `0` ok, `1` error, `2` usage, `3`
+  not-found. Every command also prints a one-line text confirmation — you never
+  have to re-read just to learn whether a mutation landed.
+- Mutators overwrite `FILE` **in place** (git is your history). `-o/--output PATH`
+  writes a copy instead; `--dry-run` previews without writing.
+- A command that mints a new handle (`comments add`→`cN`, `insert`→`pN`,
+  `footnotes add`→`fnN`, …) prints the bare locator(s), one per line.
+- Re-read after structural edits (ids shift), or batch from one read.
+- Need exact literal text in (a URL, prose GFM would mangle)? `insert` and
+  `create` take `--text-file PATH` (`-` = stdin): every character lands verbatim,
+  each newline a new paragraph. No escaping burden.
+
+## 6. Going deeper
+
+- `references/commands.md` — the full command surface at a glance.
+- `references/troubleshooting.md` — install, PATH, render runtime, common errors.
+- Or just run `docx <command> --help` — the authoritative, versioned contract.

package/skills/docx-cli/references/commands.md

@@ -0,0 +1,53 @@
+# docx-cli command reference
+
+The **authoritative, versioned** reference is `docx <command> --help` (and
+`docx --help` for the index). This file is a quick map; when a detail matters,
+run the help. None of the `info` commands need a FILE:
+
+```sh
+docx --help            # every command, one capability hint each
+docx info locators     # the addressing grammar (the backbone)
+docx info schema       # the JSON-AST shape that `docx read --ast` emits
+docx info skill        # this skill, regenerated from the binary
+```
+
+## Read & query (never mutate)
+
+| Command             | What it does                                                                                                                                                                |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `read FILE`         | Render as Markdown with `pN` locators. `--from/--to` slice; `--accepted` (default)/`--current`/`--baseline` tracked views; `--comments`; `--ast` for the lossless JSON AST. |
+| `find FILE [QUERY]` | Find spans by text OR by formatting (`--highlight/--color/--bold/--italic/--underline`); returns locators to feed `--at`.                                                   |
+| `wc FILE [LOCATOR]` | Word count for the whole doc or a slice.                                                                                                                                    |
+| `outline FILE`      | Headings as a locator tree.                                                                                                                                                 |
+| `render FILE`       | Render each page to PNG/JPG via Word or LibreOffice — for verifying LAYOUT only.                                                                                            |
+| `styles FILE`       | List/describe styles (`--used`, `--at ID`).                                                                                                                                 |
+| `info <topic>`      | `schema` / `locators` / `skill` — reference material, no FILE.                                                                                                              |
+
+## Mutate (overwrite FILE in place; `-o PATH` writes a copy; `--dry-run` previews)
+
+| Command                              | What it does                                                                                                                      |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `create FILE`                        | Create a new `.docx` (`--from PATH.md` / `--from -`; `--text-file` for literal text).                                             |
+| `edit FILE`                          | Replace/strip text or formatting at a locator (`--clear`, `--track`, `--batch`).                                                  |
+| `insert FILE`                        | Insert a paragraph, image, table, equation, code, markdown, or page break (`--after/--before`, `--track`, `--batch`).             |
+| `delete FILE`                        | Remove a paragraph, range, table, or section break (`--at`, `--track`, `--batch`).                                                |
+| `replace FILE PATTERN REPL`          | Substitute text spans sed-style — KEEPS the run's formatting and tabs (`--regex`, `--track`, `--batch`). The form-fill workhorse. |
+| `sections FILE`                      | Multi-column layout, section breaks, and page setup (margins/orientation/size). The only way to do columns.                       |
+| `styles set/create/set-default-font` | Restyle every heading at once, mint a style, or set the document font.                                                            |
+| `comments`                           | `add` (`--at` / `--anchor PHRASE` / `--batch`), `reply`, `resolve` (`--unset`), `delete`, `list`.                                 |
+| `footnotes` / `endnotes`             | `add` (`--at` / `--anchor`), `edit`, `delete`, `list`.                                                                            |
+| `headers` / `footers`                | `set` / `list` / `clear` — text, page numbers, dates, fields; e.g. `footers set FILE --page-number --of-pages`.                   |
+| `images`                             | `add` (`--caption` for a figure), `extract`, `replace`, `delete`, `list`.                                                         |
+| `hyperlinks`                         | `add` (`--url`), `list`, `replace` (`--with`), `delete`.                                                                          |
+| `tables`                             | Insert/delete rows & columns, merge/unmerge, set widths, borders, formatting.                                                     |
+| `lists`                              | Renumber a numbered list (`set --at pN --start 5` / `--format upper-roman` / `--restart` / `--continue`).                         |
+| `track-changes`                      | `on`/`off`, `list`, `accept`/`reject` (`--at tcN` / `--all`).                                                                     |
+
+## The two gotchas that can trip you up
+
+1. **Ids shift after structural edits.** Re-read between mutations, or apply many
+   changes from ONE read with `--batch FILE.jsonl` — every locator addresses the
+   document as read, so ids stay valid across the whole batch.
+2. **`docx read` is the source of truth for CONTENT.** Only `docx render` (slow —
+   spins up Word) shows LAYOUT: columns, page/section breaks, image placement,
+   table geometry. Render once at the end, not after every edit.

package/skills/docx-cli/references/troubleshooting.md

@@ -0,0 +1,61 @@
+# docx-cli troubleshooting
+
+## `docx: command not found`
+
+The binary isn't on PATH. Install it (or run `scripts/bootstrap.sh`, which also
+self-updates a stale install):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/kklimuk/docx-cli/main/install.sh | sh
+```
+
+It installs to `~/.local/bin/docx` by default. Make sure that directory is on
+your `PATH` (`export PATH="$HOME/.local/bin:$PATH"`). Set `PREFIX=/usr/local/bin`
+before the install to choose another location.
+
+## `docx render` fails or hangs
+
+`render` is the **only** command that needs an external app. Everything else
+operates on the `.docx` zip directly. For `render` you need one of:
+
+- **Word** (macOS or Windows) — highest-fidelity output.
+- **LibreOffice** (`soffice`) — cross-platform; auto-used when Word isn't present.
+
+If neither is installed, every other verb still works — you just can't rasterize
+pages. And you usually don't need to: `docx read` already proves content changes
+through the write→read loop. Render only when the open question is LAYOUT
+(columns, page/section breaks, image sizing, table geometry), and then once.
+
+## "Did my change apply?" — read the exit code
+
+Exit code is the contract: `0` ok, `1` error, `2` usage, `3` not-found. Every
+command also prints a one-line confirmation, so you never have to re-read just to
+learn whether a mutation landed. For the full structured ack, add `--verbose`.
+
+## A locator points at the wrong thing
+
+Block ids (`pN`, `tN`, `sN`, …) are **positional** and shift after structural
+edits (insert/delete that add or remove blocks). Two fixes:
+
+1. **Re-read** (`docx read FILE` or `--ast`) after a structural edit to get fresh ids.
+2. **Batch** instead: `--batch FILE.jsonl` applies many changes from a single
+   read, so every locator stays valid across the whole batch. This is the right
+   tool for filling a form or applying a multi-point review.
+
+To get an exact span locator without counting characters, run
+`docx find FILE "phrase"` and paste the result into `--at`.
+
+## My literal text got mangled (a URL autolinked, prose got reformatted)
+
+The `--markdown`/`--from` channels parse GFM (+ math + CriticMarkup + inline
+HTML), which can transform literal prose. When you need text in **verbatim**, use
+the parser-free channel: `insert` and `create` take `--text-file PATH` (`-` =
+stdin). Every character lands as-is; each newline starts a new paragraph.
+
+## I edited a file and lost some unusual formatting
+
+You shouldn't — docx-cli mutates the underlying XML **in place** and leaves
+constructs it doesn't model untouched. If you rebuilt the document instead
+(`read` → `create`), that round-trips through a view and can drop what the view
+doesn't carry. Prefer in-place `edit`/`replace`/`insert`/`delete` over
+read-then-recreate. `git` is your undo (there's no journal).

package/skills/docx-cli/scripts/bootstrap.sh

@@ -0,0 +1,107 @@
+#!/bin/sh
+# docx-cli skill bootstrap.
+#
+# Ensures the `docx` binary is installed and reasonably current, so an agent that
+# activated this skill can rely on it. Run it once at the start of a session:
+#   bash scripts/bootstrap.sh
+#
+# Behavior:
+#   - not installed  -> install the latest release via the canonical installer
+#   - installed       -> compare against the latest GitHub release tag; if behind,
+#                        self-update (re-running the installer, which fetches latest)
+#   - no network / can't determine latest -> leave the working binary in place and
+#                        exit 0 (every verb except `render` works offline anyway)
+#
+# POSIX sh, no bashisms. The binary is the source of truth — this script only keeps
+# it present and fresh; it never edits the skill.
+
+set -eu
+
+REPO="kklimuk/docx-cli"
+INSTALL_URL="https://raw.githubusercontent.com/${REPO}/main/install.sh"
+
+# ─── Pick a downloader (shared by the version check and the installer fetch) ───
+if command -v curl >/dev/null 2>&1; then
+  fetch() { curl -fsSL "$1"; }
+elif command -v wget >/dev/null 2>&1; then
+  fetch() { wget -qO- "$1"; }
+else
+  echo "docx-cli bootstrap: need curl or wget." >&2
+  exit 1
+fi
+
+# Download install.sh to a temp file FIRST, then run it — so a failed/empty download
+# is caught here instead of being silently swallowed (`fetch | sh` would let `sh` read
+# empty stdin and exit 0, masking the failure). Returns the installer's exit status.
+run_installer() {
+  echo "→ Installing docx-cli (latest) ..."
+  installer="$(mktemp 2>/dev/null || mktemp -t docx-cli-install)"
+  if ! fetch "$INSTALL_URL" > "$installer" || [ ! -s "$installer" ]; then
+    rm -f "$installer"
+    echo "docx-cli bootstrap: could not download the installer from $INSTALL_URL (offline or rate-limited)." >&2
+    return 1
+  fi
+  if sh "$installer"; then rc=0; else rc=$?; fi
+  rm -f "$installer"
+  return "$rc"
+}
+
+# install.sh drops the binary in ${PREFIX:-$HOME/.local/bin} and only PRINTS a PATH hint
+# — it can't edit the caller's PATH. So after installing, confirm `docx` is actually
+# resolvable and fail LOUDLY if not, rather than reporting a false success the agent
+# trips over on its first `docx` call (and re-downloading from scratch every session).
+ensure_reachable() {
+  command -v docx >/dev/null 2>&1 && return 0
+  bindir="${PREFIX:-$HOME/.local/bin}"
+  echo "docx-cli bootstrap: installed to $bindir, but it is NOT on your PATH." >&2
+  echo "  Add it:  export PATH=\"$bindir:\$PATH\"   (then re-run)" >&2
+  echo "  Or invoke the binary directly: $bindir/docx" >&2
+  return 1
+}
+
+# ─── Not installed: install, confirm reachable, finish ───
+if ! command -v docx >/dev/null 2>&1; then
+  echo "docx not found on PATH."
+  run_installer || exit 1
+  ensure_reachable || exit 1
+  exit 0
+fi
+
+installed="$(docx --version 2>/dev/null | awk '{print $NF}')"
+echo "docx-cli present: ${installed:-unknown}"
+
+# Couldn't read a version (broken or changed --version output)? Do NOT enter a reinstall
+# loop — the binary is present and resolvable; leave it and exit clean.
+if [ -z "$installed" ]; then
+  echo "Could not read the installed version — leaving the present binary in place."
+  exit 0
+fi
+
+# ─── Determine the latest released version (best-effort) ───
+latest_json="$(fetch "https://api.github.com/repos/${REPO}/releases/latest" 2>/dev/null || true)"
+latest="$(printf '%s' "$latest_json" | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"v\{0,1\}\([^"]*\)".*/\1/p' | head -n 1)"
+
+if [ -z "$latest" ]; then
+  echo "Could not determine the latest release (offline or rate-limited) — keeping the installed binary."
+  exit 0
+fi
+
+if [ "$installed" = "$latest" ]; then
+  echo "✓ Up to date (${installed})."
+  exit 0
+fi
+
+# Versions differ. Only UPDATE when installed is OLDER than latest — never downgrade a
+# locally-built/pre-release binary that's ahead of the published release. Use version
+# sort when the platform's `sort` supports -V; otherwise fall back to updating.
+if printf '%s\n' "0.0" "0.1" | sort -V >/dev/null 2>&1; then
+  oldest="$(printf '%s\n%s\n' "$installed" "$latest" | sort -V | head -n 1)"
+  if [ "$oldest" != "$installed" ]; then
+    echo "Installed (${installed}) is newer than the latest release (${latest}) — keeping it."
+    exit 0
+  fi
+fi
+
+echo "A newer release is available: ${installed} -> ${latest}."
+run_installer || { echo "docx-cli bootstrap: update failed — keeping ${installed}." >&2; exit 1; }
+ensure_reachable || exit 1