bun-docx 0.20.0 → 0.20.2

package/README.md

@@ -18,7 +18,7 @@ We measured it — a controlled A/B bake-off: **six real document tasks** (fill
 | :------------------------ | ------------------: | --------------------: | --------------: | --------------------: |
 |                           |        **docx-cli** |         default skill |    **docx-cli** |         default skill |
 | Tasks solved (of 6)       |       **4.3** (4–5) |             0.7 (0–1) |   **6.0** (6–6) |             4.0 (4–4) |
-| Rendered correctly (of 6) |                 5.7 |                   3.7 |             6.0 |                   4.7 |
+| Rendered correctly (of 6) |                 6 |                   3.7 |             6.0 |                   4.7 |
 | Outright-broken documents |               **0** |      ~1/run (up to 2) |           **0** |                     0 |
 | Input tokens              |            **2.4M** |           6.1M (2.6×) |        **1.6M** |           3.6M (2.2×) |
 | Wall-clock                |           **924 s** | 1,882 s (2.0× slower) |     **1,175 s** | 2,029 s (1.7× slower) |

package/dist/index.js

@@ -82676,7 +82676,7 @@ async function resolveBlockOrFail(document4, locator) {
     return document4.body.resolveBlock(locator);
   } catch (err) {
     if (err instanceof LocatorResolveError) {
-      return await fail("BLOCK_NOT_FOUND", err.message);
+      return await fail("BLOCK_NOT_FOUND", err.message, STALE_LOCATOR_HINT);
     }
     throw err;
   }
@@ -82726,7 +82726,7 @@ async function resolveBlockRangeOrFail(document4, locator) {
       return await fail("INVALID_LOCATOR", err.message);
     }
     if (err instanceof LocatorResolveError) {
-      return await fail("BLOCK_NOT_FOUND", err.message);
+      return await fail("BLOCK_NOT_FOUND", err.message, STALE_LOCATOR_HINT);
     }
     throw err;
   }
@@ -82735,7 +82735,7 @@ var EXIT2, stdout = async (text6) => {
   await Bun.stdout.write(text6);
 }, stderr = async (text6) => {
   await Bun.stderr.write(text6);
-}, sinks, verboseAck = false, SAVE_FLAGS;
+}, sinks, verboseAck = false, STALE_LOCATOR_HINT = "Locator ids are positional and shift after structural edits (insert/delete/section changes) \u2014 an id from an earlier read may now point elsewhere or be gone. Re-read the file to get current ids, then retry. Applying several changes? Do them from ONE read with --batch (edit/insert/delete/replace/comments) so ids never go stale mid-run.", SAVE_FLAGS;
 var init_respond = __esm(() => {
   init_core2();
   EXIT2 = {
@@ -82768,23 +82768,21 @@ function detectMarkdownInPlainText(text6) {
     return "a link ([text](url))";
   return null;
 }
-async function rejectMarkdownInText(text6, help) {
+async function rejectMarkdownInText(text6) {
   const found = detectMarkdownInPlainText(text6);
   if (!found)
     return null;
-  return await fail("USAGE", `--text writes literal characters, but this value looks like markdown: ${found}. It would be baked in verbatim (e.g. literal ** around the word), not rendered.`, `Use --markdown to parse it (handles ${found}, headings, lists, links), --bold/--italic for a uniformly-emphasized run, or --runs for literal text that really contains these characters. Help:
-${help}`);
+  return await fail("USAGE", `--text writes literal characters, but this value looks like markdown: ${found}. It would be baked in verbatim (e.g. literal ** around the word), not rendered.`, `Use --markdown to parse it (handles ${found}, headings, lists, links), --bold/--italic for a uniformly-emphasized run, or --runs for literal text that really contains these characters.`);
 }
 function detectShellMangledCurrency(text6) {
   const match = text6.match(/(?<![\d$])([.,]\d{2,})/);
   return match?.[1] ?? null;
 }
-async function rejectShellMangledValue(text6, help, label = "this value") {
+async function rejectShellMangledValue(text6, label = "this value") {
   const fragment = detectShellMangledCurrency(text6);
   if (!fragment)
     return null;
-  return await fail("USAGE", `${label} contains "${fragment}" \u2014 a number with no integer part, the signature of a "$" amount gutted by the shell (bash turns double-quoted "$300.00" into ".00" and "$10,000" into ",000"). docx would write the corrupted value verbatim.`, `Wrap any "$"-bearing value in SINGLE quotes ('$300.00') so bash leaves it alone, or supply it via --batch FILE (JSONL never touches the shell). If you really mean "${fragment}", write its integer part (0${fragment}) or use --batch. Help:
-${help}`);
+  return await fail("USAGE", `${label} contains "${fragment}" \u2014 a number with no integer part, the signature of a "$" amount gutted by the shell (bash turns double-quoted "$300.00" into ".00" and "$10,000" into ",000"). docx would write the corrupted value verbatim.`, `Wrap any "$"-bearing value in SINGLE quotes ('$300.00') so bash leaves it alone, or supply it via --batch FILE (JSONL never touches the shell). If you really mean "${fragment}", write its integer part (0${fragment}) or use --batch.`);
 }
 function decodeInlineEscapes(value) {
   if (value === undefined)
@@ -85930,10 +85928,10 @@ async function validateParagraphEdit(values2, paragraphOptions) {
       }
       return { kind: "removeLine" };
     }
-    const rejected = await rejectMarkdownInText(text6, HELP9);
+    const rejected = await rejectMarkdownInText(text6);
     if (typeof rejected === "number")
       return rejected;
-    const mangled = await rejectShellMangledValue(text6, HELP9, "--text");
+    const mangled = await rejectShellMangledValue(text6, "--text");
     if (typeof mangled === "number")
       return mangled;
     return {
@@ -86241,9 +86239,12 @@ General options:
   -h, --help        Show this help
 
 Output:
-  Prints a one-line confirmation on success (exit 0) \u2014 the edited locator is unchanged, so there's
-  nothing to mint. --verbose prints {ok:true, operation, path, locator}.
-  Errors print {code, error, hint?} with a nonzero exit. Discover ids with
+  Prints a one-line confirmation on success (exit 0) \u2014 an in-place edit shifts nothing, so the
+  edited locator is unchanged and there's nothing to mint. --verbose prints {ok:true, operation,
+  path, locator}. Errors print {code, error, hint?} with a nonzero exit.
+  Heads up: a locator you hold from BEFORE a structural edit (an insert/delete elsewhere renumbers
+  ids) is stale \u2014 it lands on the wrong block or errors BLOCK_NOT_FOUND. Re-read after any
+  insert/delete, or apply the whole set from one read with --batch (above). Discover ids with
   \`docx read FILE --ast\` (equation ids appear on EquationRun nodes).
 
 Examples:
@@ -88872,10 +88873,10 @@ async function buildSingleShotOptions(filePath, values2) {
   if (typeof spec === "number")
     return spec;
   if (spec.kind === "text") {
-    const rejected = await rejectMarkdownInText(spec.text, HELP20);
+    const rejected = await rejectMarkdownInText(spec.text);
     if (typeof rejected === "number")
       return rejected;
-    const mangled = await rejectShellMangledValue(spec.text, HELP20, "--text");
+    const mangled = await rejectShellMangledValue(spec.text, "--text");
     if (typeof mangled === "number")
       return mangled;
   }
@@ -94849,7 +94850,7 @@ async function run43(args) {
   }
   const cellTexts = parsed.values.cells ? parsed.values.cells.split(",") : [];
   for (const cell of cellTexts) {
-    const mangled = await rejectShellMangledValue(cell, HELP39, "--cells");
+    const mangled = await rejectShellMangledValue(cell, "--cells");
     if (typeof mangled === "number")
       return mangled;
   }
@@ -98014,7 +98015,7 @@ Examples:
 // package.json
 var package_default = {
   name: "bun-docx",
-  version: "0.20.0",
+  version: "0.20.2",
   description: "Read, edit, redline, and comment on Microsoft Word .docx files from the command line \u2014 built for AI agents.",
   keywords: [
     "docx",
@@ -98137,11 +98138,13 @@ Commands (each one-liner names capabilities you'd otherwise miss; see <command>
 It is highly recommended to run "docx info locators" and "docx info schema" (neither needs a FILE) to understand the addressing model and AST.
 Run "docx <command> --help" for command-specific help.
 
-BATCH MANY CHANGES IN ONE READ: filling a form or applying many edits? Don't go
-one-at-a-time \u2014 edit / insert / replace / delete and comments (add/resolve/delete)
-all take --batch FILE.jsonl (one JSON change per line; "-" reads stdin). Every locator
-addresses the document AS READ, so ids stay valid across the whole batch \u2014 one
-read, one write, no re-reading between changes. See "<command> --help".
+BATCH MANY CHANGES IN ONE READ: locator ids are positional and shift after structural
+edits (insert/delete/section changes), so going one-at-a-time forces a re-read to refresh
+ids after each. Miss the change and the next command lands on the wrong block or errors
+BLOCK_NOT_FOUND. Skip all that: edit / insert / replace / delete and comments
+(add/resolve/delete) all take --batch FILE.jsonl (one JSON change per line; "-" reads
+stdin). Every locator addresses the document AS READ, so ids stay valid across the whole
+batch \u2014 one read, one write, no re-reading between changes. See "<command> --help".
 
 FILL FORMATTED / TABBED LINES WITHOUT REBUILDING RUNS: to fill a template line that
 carries formatting (bold/font) or tab stops \u2014 e.g. "**Org Name**\u21E5Date" \u2014 replace just

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bun-docx",
-	"version": "0.20.0",
+	"version": "0.20.2",
 	"description": "Read, edit, redline, and comment on Microsoft Word .docx files from the command line — built for AI agents.",
 	"keywords": [
 		"docx",