@drbaher/draft-cli 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to this project will be documented in this file. The
 format is loosely based on [Keep a Changelog](https://keepachangelog.com/),
 and the project adheres to semantic versioning once it leaves 0.x.
 
+## 0.2.0 — 2026-05-16
+
+### Added
+
+- **`.docx` output round-trip.** Templates read from `.docx` (tier 3
+  highlight detection) now write back as `.docx`, preserving runs,
+  styles, paragraph breaks, and every non-document part of the package
+  (`[Content_Types].xml`, relationships, images, headers, etc.).
+  Default output filename is `<basename>-filled.docx` next to the
+  input; override with `--output PATH.docx`. Schema-rescue, T1/T2
+  bracket/mustache detection, and T4/T5 substitution all benefit
+  too — any tier that detects a placeholder in a `.docx` template
+  now substitutes back into the same runs.
+- **`--output -` writes plain text to stdout** (Unix `-` convention).
+  Use this on a `.docx` input to get the substituted body as text
+  instead of a `.docx` file: `draft contract.docx --output -`.
+- **`writeDocxBuffer(originalPath, newDocumentXml)`**, **`makeDocxOutputPath(inputPath)`**,
+  **`substituteDocxXml(xml, placeholders, values, tier)`**, **`decideDocxOutput(opts, input)`**,
+  and **`encodeXml(s)`** added to the public API for programmatic
+  drivers. Same import surface as `substitute` and `extractDocxText`.
+
+### Changed
+
+- **Default output for `.docx` input is now `<basename>-filled.docx`,
+  not stdout text.** Previously, `draft contract.docx` (no
+  `--output`) extracted text and wrote substituted plain text to
+  stdout. v0.2.0 writes `contract-filled.docx` next to the input.
+  Pipelines that depended on the stdout-text behavior should pass
+  `--output -` to opt back in.
+
+### Split-run handling
+
+When a placeholder's text spans multiple `<w:t>` runs in the source
+`.docx` (Word sometimes splits runs at punctuation, auto-correct
+boundaries, or comment anchors), v0.2.0 emits a warning and skips
+that substitution rather than merging the runs and losing run-level
+styling. The warning explains how to fix the source: open the
+document, retype the placeholder so it lives in one run, save, and
+retry. This decision is logged in `PARAM_SCHEMA.md` §2.
+
 ## 0.1.1 — 2026-05-16
 
 ### Fixed

package/PARAM_SCHEMA.md

@@ -22,7 +22,20 @@ draft <cat>/<name>[@ver] ...     # pulls via `template-vault get`
 ```
 
 - **Input forms accepted:** `path/to/file.md`, `path/to/file.txt`, `path/to/file.docx`, stdin (`-`), or a `template-vault` ref shaped `<category>/<name>[@version]`. Vault refs shell out to `template-vault get` — no library import.
-- **Output:** stdout by default, `--output PATH` for files. Output is always plain text/markdown in v1 — `.docx` is **input-only** for v1. Writing `.docx` back is deferred to v2.
+- **Output:** depends on input kind and `--output` target.
+
+  | Input        | `--output`          | Output                                |
+  | ------------ | ------------------- | ------------------------------------- |
+  | text (any)   | absent              | plain text on stdout                  |
+  | text (any)   | `-`                 | plain text on stdout                  |
+  | text (any)   | `PATH` (any ext)    | plain text written to `PATH`          |
+  | `.docx`      | absent              | `.docx` to `<basename>-filled.docx`   |
+  | `.docx`      | `PATH.docx`         | `.docx` to `PATH.docx`                |
+  | `.docx`      | `-`                 | plain text (substituted body) on stdout |
+  | `.docx`      | `PATH` (non-`.docx`)| plain text written to `PATH`          |
+
+  `.docx` output is a round-trip: the original `.docx` package is reopened, the substituted text is written back into the same `<w:t>` runs that detection found, and all other parts of the package (relationships, images, headers, `[Content_Types].xml`, etc.) pass through unchanged. Run-level styling is preserved. If a placeholder's text spans multiple `<w:t>` runs in the source (Word sometimes splits runs at punctuation or auto-correct boundaries), that placeholder is **skipped**, not substituted, and a warning is emitted explaining how to fix the source — locked decision Q1.1.
+- `--json`, `--diff`, `--validate`, and `--list-placeholders` all override the `.docx` round-trip and produce text/JSON to stdout (or to `--output PATH`, when provided).
 - **Encoding:** UTF-8 in, UTF-8 out. No BOM written; BOM tolerated on read.
 
 ## 3. Detection cascade (sequential-with-stop)

package/draft-cli.mjs

@@ -70,7 +70,7 @@ import { fileURLToPath } from "node:url";
  */
 
 /** @type {string} */
-export const VERSION = "0.1.1";
+export const VERSION = "0.2.0";
 
 // ─── EXIT CODES ─────────────────────────────────────────────────────────────
 /**
@@ -489,6 +489,43 @@ export async function extractDocxText(path) {
   return { body: docxXmlToText(xml), xml };
 }
 
+/**
+ * Re-read the original `.docx`, swap in a new `word/document.xml`, and
+ * return the resulting `.docx` as a `Buffer`. All other parts of the
+ * package (`[Content_Types].xml`, relationships, images, headers, etc.)
+ * pass through unchanged.
+ *
+ * @param {string} originalPath — filesystem path to the source `.docx`.
+ * @param {string} newDocumentXml — replacement content for `word/document.xml`.
+ * @returns {Promise<Buffer>}
+ * @throws {Error} with `.exitCode = EXIT.IO` on missing jszip or invalid source.
+ */
+export async function writeDocxBuffer(originalPath, newDocumentXml) {
+  const JSZip = await loadJSZip();
+  let zip;
+  try { zip = await JSZip.loadAsync(readFileSync(originalPath)); }
+  catch (err) {
+    const e = new Error(`could not re-open source .docx (${err.message})`);
+    e.exitCode = EXIT.IO;
+    throw e;
+  }
+  zip.file("word/document.xml", newDocumentXml);
+  return await zip.generateAsync({ type: "nodebuffer" });
+}
+
+/**
+ * Derive the default `.docx` output filename from an input path. Appends
+ * `-filled` before the extension: `contract.docx` → `contract-filled.docx`.
+ * If the input has no extension, appends `-filled.docx`.
+ * @param {string} inputPath
+ * @returns {string}
+ */
+export function makeDocxOutputPath(inputPath) {
+  const ext = extname(inputPath);
+  if (!ext) return `${inputPath}-filled.docx`;
+  return `${inputPath.slice(0, -ext.length)}-filled${ext}`;
+}
+
 // Walk the XML in document order. For each <w:p> emit a line; concatenate
 // <w:t> contents within. Decode XML entities. Used for both output body and
 // T1/T2 detection on docx input.
@@ -524,6 +561,18 @@ export function decodeXml(s) {
           .replace(/&quot;/g, '"').replace(/&apos;/g, "'");
 }
 
+/**
+ * Inverse of {@link decodeXml}. Used when writing substituted text back into
+ * a Word document's `<w:t>` runs. Only encodes the three structural
+ * characters; double- and single-quotes don't need encoding inside element
+ * text content.
+ * @param {string} s
+ * @returns {string}
+ */
+export function encodeXml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
 const RECOGNIZED_HIGHLIGHTS = new Set(["yellow", "green", "cyan", "magenta"]);
 
 // Scan the XML for highlighted runs. Returns an array of { text, color }.
@@ -1180,6 +1229,83 @@ function replaceAll(s, find, repl) {
   return s.split(find).join(repl);
 }
 
+/**
+ * Substitute placeholder values *inside the Word XML*, preserving runs
+ * and styling. Returns a new XML string plus warnings for any placeholder
+ * whose text spans multiple `<w:t>` runs in the source — these are
+ * skipped rather than substituted (merging the runs would lose styling
+ * information; leaving them is reversible).
+ *
+ * For T1 (bracket) / T2 (mustache) the search text is the literal match
+ * (e.g. `[Party A]` or `{{party_a}}`). For T3 (docx-highlight), T4
+ * (heuristic), T5 (llm) the search text is the run's inner content with
+ * whole-word boundaries — same semantics as {@link substitute}.
+ *
+ * @param {string} xml — original `word/document.xml`.
+ * @param {Placeholder[]} placeholders
+ * @param {Object<string,string>} values — `{ key: resolvedValue }`.
+ * @param {Tier} tier
+ * @returns {{ xml: string, warnings: string[] }}
+ */
+export function substituteDocxXml(xml, placeholders, values, tier) {
+  let out = xml;
+  const warnings = [];
+  const originalText = docxXmlToText(xml);
+  for (const p of placeholders) {
+    const v = values[p.key];
+    if (v === undefined) continue;
+    for (const h of p.hits) {
+      const find = (tier === "bracket" || tier === "mustache") ? h.match : h.inner;
+      const literal = (tier === "bracket" || tier === "mustache");
+      const buildRe = (global) => literal
+        ? new RegExp(escapeRegex(find), global ? "g" : "")
+        : new RegExp(`(?<![A-Za-z0-9])${escapeRegex(find)}(?![A-Za-z0-9])`, global ? "g" : "");
+      const replaceRe = buildRe(true);
+      let madeSubstitution = false;
+      out = out.replace(/<w:t(\s[^>]*)?>([\s\S]*?)<\/w:t>/g, (match, attrs, content) => {
+        const decoded = decodeXml(content);
+        replaceRe.lastIndex = 0;
+        const replaced = decoded.replace(replaceRe, v);
+        if (replaced === decoded) return match;
+        madeSubstitution = true;
+        return `<w:t${attrs || ""}>${encodeXml(replaced)}</w:t>`;
+      });
+      if (!madeSubstitution && buildRe(false).test(originalText)) {
+        warnings.push(
+          `docx substitution skipped for "${find}" (→ "${v}"): the placeholder spans ` +
+          `multiple text runs in the source, which would lose run-level styling if merged. ` +
+          `Open the document, retype the placeholder so it lives in a single run, and retry.`
+        );
+      }
+    }
+  }
+  return { xml: out, warnings };
+}
+
+/**
+ * Decide whether to write `.docx` output (round-trip) versus plain text.
+ * Returns `{ path }` for `.docx`, or `null` for text. Rules:
+ *   - input must be `.docx`;
+ *   - `--json`, `--diff`, `--validate`, `--list-placeholders` force text;
+ *   - `--output PATH.docx` writes `.docx` to PATH;
+ *   - `--output -` writes plain text to stdout (Unix `-` convention);
+ *   - `--output PATH` with any other extension writes plain text;
+ *   - no `--output` defaults to `<basename>-filled.docx`.
+ *
+ * @param {Object} opts — parsed CLI args.
+ * @param {{kind: "text"|"docx", path: string|null}} input
+ * @returns {{ path: string } | null}
+ */
+export function decideDocxOutput(opts, input) {
+  if (input.kind !== "docx") return null;
+  if (opts.json || opts.diff || opts.listPlaceholders || opts.validate) return null;
+  if (opts.output === "-") return null;
+  if (opts.output) {
+    return extname(opts.output) === ".docx" ? { path: opts.output } : null;
+  }
+  return { path: makeDocxOutputPath(input.path || "out.docx") };
+}
+
 // ─── --why BUILDER ──────────────────────────────────────────────────────────
 /**
  * Format the `--why` stderr block. Stable shape across minor versions; see
@@ -1367,9 +1493,29 @@ export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher
 
   const output = substitute(input.body, result.placeholders, resolved, result.tier);
 
-  // Write output.
-  if (opts.output) {
-    try { writeFileSync(opts.output, output, "utf8"); }
+  // Write output. Three paths:
+  //   (a) docx round-trip: input is .docx and target is .docx (default for .docx
+  //       inputs, unless --output is set to a non-.docx extension or `-`).
+  //   (b) write text to a file (--output PATH, where PATH ≠ "-").
+  //   (c) write text to stdout (no --output, or --output "-").
+  // --json suppresses (c) so it doesn't collide with the JSON payload.
+  const docxOut = decideDocxOutput(opts, input);
+  let writtenPath = null;
+  if (docxOut) {
+    try {
+      const { xml: newXml, warnings: docxWarnings } = substituteDocxXml(
+        input.docxXml, result.placeholders, resolved, result.tier
+      );
+      if (docxWarnings.length) result.warnings.push(...docxWarnings);
+      const buf = await writeDocxBuffer(input.path, newXml);
+      writeFileSync(docxOut.path, buf);
+      writtenPath = docxOut.path;
+    } catch (e) {
+      err.write(paint(`error: could not write ${docxOut.path}: ${e.message}\n`, "red", err));
+      return EXIT.IO;
+    }
+  } else if (opts.output && opts.output !== "-") {
+    try { writeFileSync(opts.output, output, "utf8"); writtenPath = opts.output; }
     catch (e) {
       err.write(paint(`error: could not write ${opts.output}: ${e.message}\n`, "red", err));
       return EXIT.IO;
@@ -1382,8 +1528,8 @@ export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher
     out.write(JSON.stringify({
       ok: true,
       tier: result.tier,
-      output_path: opts.output || null,
-      output: opts.output ? null : output,
+      output_path: writtenPath,
+      output: writtenPath ? null : output,
       placeholders: publicPlaceholders(result.placeholders),
       sources,
       warnings: result.warnings,
@@ -1401,7 +1547,7 @@ export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher
       missing,
       unmapped: result.unmapped,
       warnings: result.warnings,
-      outputPath: opts.output,
+      outputPath: writtenPath,
     }) + "\n");
   }
   for (const w of result.warnings) err.write(paint(`warning: ${w}\n`, "yellow", err));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drbaher/draft-cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Fill placeholders in a legal-document template with parameter values. Part of the contract-operations suite.",
   "type": "module",
   "bin": {