bun-docx 0.8.0 → 0.9.0

package/README.md

@@ -42,7 +42,7 @@ The repo includes a Common Paper Mutual NDA template at `tests/fixtures/mnda.doc
 cp tests/fixtures/mnda.docx mnda-filled.docx
 
 # Read the cover-page table so the agent knows what placeholders exist
-docx read mnda-filled.docx --markdown --to t1
+docx read mnda-filled.docx --to t1
 
 # Fill the yellow-highlighted bracketed placeholders
 docx replace mnda-filled.docx "Fill in: today’s date" "May 6, 2026"
@@ -72,7 +72,8 @@ Open `mnda-filled.docx` in Word: tracked changes and comments appear in the revi
 
 ```sh
 docx create FILE [--title T] [--author A] [--text "..."]
-docx read FILE [--markdown [--from pN] [--to pN] [--accepted | --baseline | --current] [--comments]]
+docx read FILE [--from pN] [--to pN] [--accepted | --baseline | --current] [--comments]
+docx read FILE --ast    # JSON-AST opt-in (every other read flag is markdown-only)
 docx insert FILE --after p3 --text "..." [--style HeadingN] [--color HEX] [--bold] [--italic] [--url URL]
 docx insert FILE --after p3 --runs '[{"type":"text","text":"X","bold":true}]'
 docx insert FILE --after p3 --page-break | --column-break
@@ -124,7 +125,7 @@ Every command has `--help`. Mutating commands accept `--dry-run`, `-o/--output P
 
 ### Markdown rendering
 
-`docx read FILE --markdown` renders the document body as GitHub-flavored Markdown instead of JSON. Useful when an LLM wants to skim a doc without parsing the AST. Each rendered paragraph is followed by an HTML comment with its locator (`<!-- p3 -->`) so the markdown is invisible-pinned: humans see clean prose in a renderer, agents parse the locators from raw text.
+`docx read FILE` renders the document body as GitHub-flavored Markdown — the default since v0.9. Useful when an LLM wants to skim a doc without parsing the AST. Each rendered paragraph is followed by an HTML comment with its locator (`<!-- p3 -->`) so the markdown is invisible-pinned: humans see clean prose in a renderer, agents parse the locators from raw text. Pass `--ast` for the structured JSON when programmatic walks need the typed tree (`docx read FILE --ast | jq '.blocks[] | select(.type == "paragraph")'`).
 
 `--from LOC` and `--to LOC` slice by top-level block (both inclusive). Accepts paragraph, table, cell, span, and range locators; cell/span/range collapse to their enclosing top-level block.
 

package/dist/index.js

@@ -8953,7 +8953,7 @@ var require_zipEntries = __commonJS((exports, module) => {
       if (this.centralDirRecords !== this.files.length) {
         if (this.centralDirRecords !== 0 && this.files.length === 0) {
           throw new Error("Corrupted zip or bug: expected " + this.centralDirRecords + " records in central dir, got " + this.files.length);
-        } else {}
+        }
       }
     },
     readEndOfCentral: function() {
@@ -18680,7 +18680,7 @@ Options:
   --current         search the raw concatenation (both ins and del text)
   --baseline        search the pre-change text (skip ins/moveTo)
                     default: accepted view (skip del/moveFrom) \u2014 matches
-                    "docx read --markdown" / "docx wc" / "docx comments add"
+                    "docx read" / "docx wc" / "docx comments add"
   --exact           disable query normalization (no markdown-emphasis stripping,
                     no smart/straight quote or em/en-dash equivalence)
   -h, --help        show this help
@@ -21445,7 +21445,7 @@ async function run25(args) {
       args,
       allowPositionals: true,
       options: {
-        markdown: { type: "boolean" },
+        ast: { type: "boolean" },
         from: { type: "string" },
         to: { type: "string" },
         accepted: { type: "boolean" },
@@ -21465,15 +21465,15 @@ async function run25(args) {
   const path = parsed.positionals[0];
   if (!path)
     return fail("USAGE", "Missing FILE argument", HELP25);
-  const markdown = Boolean(parsed.values.markdown);
+  const ast = Boolean(parsed.values.ast);
   const from = parsed.values.from;
   const to = parsed.values.to;
   const accepted = Boolean(parsed.values.accepted);
   const baseline = Boolean(parsed.values.baseline);
   const current = Boolean(parsed.values.current);
   const showComments = Boolean(parsed.values.comments);
-  if (!markdown && (from || to || accepted || baseline || current || showComments)) {
-    return fail("USAGE", "--from, --to, --accepted, --baseline, --current, and --comments require --markdown", HELP25);
+  if (ast && (from || to || accepted || baseline || current || showComments)) {
+    return fail("USAGE", "--from, --to, --accepted, --baseline, --current, and --comments are Markdown-only and cannot be combined with --ast", HELP25);
   }
   const viewFlagCount = (accepted ? 1 : 0) + (baseline ? 1 : 0) + (current ? 1 : 0);
   if (viewFlagCount > 1) {
@@ -21483,68 +21483,63 @@ async function run25(args) {
   const docView = await openOrFail(path);
   if (typeof docView === "number")
     return docView;
-  if (markdown) {
-    try {
-      const rendered = renderMarkdown(docView.doc, {
-        from,
-        to,
-        view,
-        showComments
-      });
-      await writeStdout(rendered);
-      return EXIT.OK;
-    } catch (err) {
-      if (err instanceof MarkdownLocatorError) {
-        return fail("INVALID_LOCATOR", err.message);
-      }
-      throw err;
+  if (ast) {
+    await enrichImageHashes(docView);
+    await respond(docView.doc);
+    return EXIT.OK;
+  }
+  try {
+    const rendered = renderMarkdown(docView.doc, {
+      from,
+      to,
+      view,
+      showComments
+    });
+    await writeStdout(rendered);
+    return EXIT.OK;
+  } catch (err) {
+    if (err instanceof MarkdownLocatorError) {
+      return fail("INVALID_LOCATOR", err.message);
     }
+    throw err;
   }
-  await enrichImageHashes(docView);
-  await respond(docView.doc);
-  return EXIT.OK;
 }
-var HELP25 = `docx read \u2014 print AST as JSON, or render document body as Markdown
+var HELP25 = `docx read \u2014 render document body as Markdown, or print AST as JSON
 
 Usage:
   docx read FILE [options]
 
 Options:
-  --markdown        Render the body as GitHub-flavored Markdown
-                    (instead of JSON). Locators are emitted as
-                    <!-- pN --> HTML comments after each paragraph and
-                    inside cell content (invisible in rendered view,
-                    but parseable from raw markdown).
-  --from LOC        Start markdown rendering at top-level block LOC (inclusive)
-  --to LOC          End markdown rendering at top-level block LOC (inclusive)
+  --ast             Print the typed AST as JSON instead of rendering Markdown.
+                    Disables all the Markdown-only flags below.
+  --from LOC        Start rendering at top-level block LOC (inclusive)
+  --to LOC          End rendering at top-level block LOC (inclusive)
                     Accepts pN, tN, tN:rRcC[:pK[:S-E]], pN:S-E, pN:S-pM:E.
                     Cell/span/range locators collapse to their enclosing
                     top-level block (the table or paragraph).
-  --accepted        Default with --markdown: render the post-accept view \u2014
-                    drop subtractive wrappers (<w:del>, <w:moveFrom>), inline
+  --accepted        Default view: render the post-accept document \u2014 drop
+                    subtractive wrappers (<w:del>, <w:moveFrom>), inline
                     additive wrappers (<w:ins>, <w:moveTo>) as plain text,
                     no markers/refs. Kept as an explicit alias for clarity.
-  --baseline        With --markdown, render the pre-change view: drop
-                    additive wrappers (<w:ins>, <w:moveTo>), inline
-                    subtractive wrappers (<w:del>, <w:moveFrom>) as plain
-                    text, no markers/refs.
-  --current         With --markdown, render the raw concatenation: additive
-                    wrappers as {++text++}[^tcN] and subtractive as
-                    {--text--}[^tcN] (CriticMarkup); the [^tcN] footnote
-                    spells out the kind (insertion / deletion / moveTo /
-                    moveFrom). Mutually exclusive with --accepted/--baseline.
-  --comments        With --markdown, append [^cN] after each commented span
-                    and emit a footnote definition for each comment at the
-                    end of the output (author, date, body).
+  --baseline        Render the pre-change view: drop additive wrappers
+                    (<w:ins>, <w:moveTo>), inline subtractive wrappers
+                    (<w:del>, <w:moveFrom>) as plain text, no markers/refs.
+  --current         Render the raw concatenation: additive wrappers as
+                    {++text++}[^tcN] and subtractive as {--text--}[^tcN]
+                    (CriticMarkup); the [^tcN] footnote spells out the kind
+                    (insertion / deletion / moveTo / moveFrom). Mutually
+                    exclusive with --accepted/--baseline.
+  --comments        Append [^cN] after each commented span and emit a
+                    footnote definition for each comment at the end of the
+                    output (author, date, body).
   -h, --help        Show this help
 
 Examples:
   docx read input.docx
-  docx read input.docx --markdown
-  docx read input.docx --markdown --from p3 --to p20
-  docx read input.docx --markdown --accepted --comments
-  docx read input.docx --markdown --baseline
-  docx read input.docx | jq '.blocks[] | select(.type == "paragraph")'
+  docx read input.docx --from p3 --to p20
+  docx read input.docx --accepted --comments
+  docx read input.docx --baseline
+  docx read input.docx --ast | jq '.blocks[] | select(.type == "paragraph")'
 `;
 var init_read2 = __esm(() => {
   init_core();
@@ -22159,7 +22154,7 @@ Options:
   --current         operate on the raw concatenation (both ins and del text)
   --baseline        operate on the pre-change text (skip ins/moveTo)
                     default: accepted view (skip del/moveFrom) \u2014 matches
-                    "docx find" / "docx read --markdown"
+                    "docx find" / "docx read"
   --exact           disable pattern normalization (no markdown-emphasis stripping,
                     no smart/straight quote or em/en-dash equivalence)
   -o, --output PATH write to PATH instead of overwriting FILE
@@ -23256,7 +23251,7 @@ Options:
   --accepted        Default. Count the accepted view: skip subtractive
                     wrappers (<w:del>, <w:moveFrom>); keep additive
                     wrappers (<w:ins>, <w:moveTo>) as plain text. Mirrors
-                    "docx read --markdown" / "docx find" defaults.
+                    "docx read" / "docx find" defaults.
   --baseline        Count the baseline view: skip additive wrappers
                     (<w:ins>, <w:moveTo>); keep subtractive wrappers
                     (<w:del>, <w:moveFrom>) as plain text \u2014 i.e., the doc as
@@ -23286,7 +23281,7 @@ var init_wc = __esm(() => {
 // package.json
 var package_default = {
   name: "bun-docx",
-  version: "0.8.0",
+  version: "0.9.0",
   description: "CLI for AI agents (Claude, Codex) to read, edit, and comment on .docx files with full format fidelity.",
   keywords: [
     "docx",
@@ -23355,7 +23350,7 @@ Usage:
 
 Commands:
   create    FILE  Create a new minimal .docx
-  read      FILE  Print AST as JSON
+  read      FILE  Render body as Markdown (--ast for JSON)
   edit      FILE  Replace text/properties at a locator
   insert    FILE  Insert a block or run
   delete    FILE  Remove a block or run range
@@ -23394,7 +23389,7 @@ Tracked changes:
   with the next paragraph; reject-ins removes the entire owning paragraph).
   Out of scope: rPrChange / pPrChange formatting revisions.
 
-  "docx read --markdown" surfaces them as CriticMarkup:
+  "docx read" surfaces them as CriticMarkup:
     {++inserted++}[^tcN]   {--deleted--}[^tcN]
   with a [^tcN]: definition appendix. Switch view with --accepted (post-accept:
   drop del, ins as plain) or --baseline (pre-change: drop ins, del as plain).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bun-docx",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"description": "CLI for AI agents (Claude, Codex) to read, edit, and comment on .docx files with full format fidelity.",
 	"keywords": [
 		"docx",