@drbaher/draft-cli 0.1.1 → 0.3.2

package/CHANGELOG.md

@@ -4,6 +4,112 @@ 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.3.2 — 2026-05-16
+
+### Fixed
+
+- **Publish auth: restored `NODE_AUTH_TOKEN` env block.** v0.3.1's
+  hotfix bumped `publish.yml` Node from 20 to 22 on the hypothesis
+  that npm CLI 11.5.1+ would auto-detect OIDC and ignore the
+  setup-node placeholder. It didn't: Node 22's npm 11.x still sent
+  the literal `XXXXX-XXXXX-XXXXX-XXXXX` placeholder and got the
+  same 404 from npm. Root cause is *not* Node version; either
+  `setup-node@v6` always writes the placeholder env into the
+  publish step, or npm CLI prefers the `.npmrc` token over OIDC
+  even when both are available. Under investigation.
+- **v0.3.1 tag exists on GitHub but did NOT publish to npm.** Skip
+  it. Registry latest is `0.2.0` until v0.3.2 ships.
+
+Pragmatic call: v0.3.2 ships via the bootstrap `NPM_TOKEN` path.
+Trusted Publisher stays configured on npm so the switch back to
+pure OIDC is a one-line change in `publish.yml` once we understand
+why npm CLI isn't using OIDC. `feedback_oidc_setup_node_v6_placeholder.md`
+in memory tracks the symptom + workarounds tried.
+
+## 0.3.1 — 2026-05-16
+
+### Fixed
+
+- **`publish.yml` now uses Node 22 instead of Node 20.** npm
+  Trusted Publishing requires npm CLI 11.5.1 or later, which ships
+  with Node 22.14+. Node 20 (npm 10.x) silently falls back to
+  `NODE_AUTH_TOKEN` when configured for a registry, and to
+  `setup-node@v6`'s placeholder value (`XXXXX-...`) when the env
+  isn't set — producing a 404 from npm masking the actual 401.
+- **v0.3.0 tag exists on GitHub but did NOT publish to npm.** v0.3.0
+  was the first publish attempt without an `NPM_TOKEN` fallback
+  (PR #10 reverted the bootstrap); the npm-CLI-too-old issue
+  surfaced immediately. No package was uploaded. v0.3.1 is the
+  rebrand of v0.3.0's typed-parameter feature with the workflow
+  fix applied. Skip v0.3.0.
+
+## 0.3.0 — 2026-05-16
+
+### Added
+
+- **Typed parameters (`type: date | money | party`).** Long-form
+  schema entries can declare a `type`, with optional `format` (date)
+  or `currency` (money). Inputs are validated and normalized between
+  value resolution and substitution; bad inputs hard-error with a
+  per-key message (exit 4). See `PARAM_SCHEMA.md` §5 for the accepted
+  shapes per type, the rejected ambiguous forms (Q3.1: US
+  `MM/DD/YYYY` and European `DD/MM/YYYY` are rejected as ambiguous),
+  and the v2 currency scope (Q3.2: USD only).
+- **`--validate` now catches type errors** before draft runs. With
+  `--json`, errors are emitted as a `type_errors` array on the
+  result payload.
+- **New public API:** `parseDateValue(raw)`, `formatDateValue(date, fmt)`,
+  `parseMoneyValue(raw)` → minor units, `formatMoneyValue(minor, currency)`,
+  `normalizeTypedValue(raw, placeholder)`, `normalizeTypedValues(placeholders, resolved)`.
+
+### Schema-contract change
+
+`PARAM_SCHEMA.md` §5 gains a "Typed parameters" section. Long-form
+entries can now include `type`, `format`, and `currency` fields; short
+form is unchanged. v0.3.0 schemas are forward-compatible with v0.2.x
+readers (which will silently ignore the new fields, since they're
+opt-in metadata on the long-form entry).
+
+## 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)
@@ -224,6 +237,39 @@ its own alias list (Q3 locked) — list it explicitly if needed.
 Parser selects long form iff a top-level `_meta` key is present. Short
 and long are not mixable within one file.
 
+### Typed parameters (v0.3.0, opt-in)
+
+Long-form entries can declare `type`, with optional `format` (`date`)
+or `currency` (`money`). Inputs are validated and normalized between
+value resolution and substitution. Bad input → exit 4
+(`EXIT.VALIDATION`) with a per-key error message; all type errors are
+collected before exit so the user sees every issue at once.
+
+```json
+{
+  "_meta": { "schema_version": 1 },
+  "effective_date":  { "aliases": ["Effective Date"],  "type": "date",  "format": "MMMM d, yyyy" },
+  "purchase_amount": { "aliases": ["Purchase Amount"], "type": "money", "currency": "USD" },
+  "party_a":         { "aliases": ["Party A"],         "type": "party" }
+}
+```
+
+| `type`   | Accepts                                                              | Normalizes to                          | Notes |
+| -------- | -------------------------------------------------------------------- | -------------------------------------- | ----- |
+| `date`   | ISO (`2027-01-15`) or spelled (`January 15, 2027`, `Jan 15 2027`)    | `format` field (default `MMMM d, yyyy`) | Q3.1 locked: US (`MM/DD/YYYY`) and European (`DD/MM/YYYY`) numeric forms are **rejected** as ambiguous. |
+| `money`  | `$5,000`, `5000.50`, `$5M`, `2.5K`, `1B`; rejects `$$5`, `5,00`, etc. | `currency`-formatted (e.g. `$5,000,000.00`) | Q3.2 locked: v0.3.0 supports `currency: "USD"` only. |
+| `party`  | Non-empty after trim; no markdown links `[text](url)`; no trailing punctuation `.,;:!?` | Trimmed string | Q3.3 locked: hard error on bad input — typed params are opt-in. |
+
+`format` for `date` supports `yyyy`, `MMMM`, `MM`, `d` tokens (matched
+in a single pass — `MM` doesn't accidentally consume `MMMM`, `d`
+doesn't leak into month names). Other literal characters pass through
+unchanged. Other tokens (e.g. `HH:mm`, `dd`, `EEEE`) are deferred to
+future versions.
+
+Programmatic API for drivers: `parseDateValue`, `formatDateValue`,
+`parseMoneyValue`, `formatMoneyValue`, `normalizeTypedValue`,
+`normalizeTypedValues`.
+
 ### Orphan handling (Q4 locked)
 
 Schema declares a key whose alias list matches no detected phrase →

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.3.2";
 
 // ─── 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 }.
@@ -869,6 +918,12 @@ export function parseSchema(parsed, sourceLabel = "<schema>") {
         aliases: v.aliases.slice(),
         required: v.required !== false,
         default: Object.prototype.hasOwnProperty.call(v, "default") ? v.default : null,
+        // v2 #3: typed parameters. `type` is one of `date|money|party` (or
+        // absent → no validation/normalization). `format` (date) and
+        // `currency` (money) are optional.
+        type: typeof v.type === "string" ? v.type : null,
+        format: typeof v.format === "string" ? v.format : null,
+        currency: typeof v.currency === "string" ? v.currency : null,
       };
     } else {
       if (!Array.isArray(v)) {
@@ -876,7 +931,7 @@ export function parseSchema(parsed, sourceLabel = "<schema>") {
         e.exitCode = EXIT.IO;
         throw e;
       }
-      entries[k] = { aliases: v.slice(), required: true, default: null };
+      entries[k] = { aliases: v.slice(), required: true, default: null, type: null, format: null, currency: null };
     }
   }
   return { form: long ? "long" : "short", entries };
@@ -1017,6 +1072,9 @@ function assemble(tier, hits, schema, warnings, fromLlm = false) {
         required: resolved.required,
         default: resolved.default,
         aliases: resolved.aliases,
+        type: resolved.type,
+        format: resolved.format,
+        currency: resolved.currency,
         hits: [],
       });
     }
@@ -1031,14 +1089,22 @@ function resolveKey(hit, schema, fromLlm) {
   if (schema) {
     for (const [key, entry] of Object.entries(schema.entries)) {
       if (entry.aliases.includes(hit.inner)) {
-        return { key, required: entry.required, default: entry.default, aliases: entry.aliases };
+        return {
+          key,
+          required: entry.required,
+          default: entry.default,
+          aliases: entry.aliases,
+          type: entry.type || null,
+          format: entry.format || null,
+          currency: entry.currency || null,
+        };
       }
     }
     return null;
   }
   const key = fromLlm && hit.suggested_key ? hit.suggested_key : canonicalKey(hit.inner);
   if (!validKey(key)) return null;
-  return { key, required: true, default: null, aliases: [hit.inner] };
+  return { key, required: true, default: null, aliases: [hit.inner], type: null, format: null, currency: null };
 }
 
 // ─── VALUE RESOLUTION (CLI > JSON > prompt > default) ───────────────────────
@@ -1116,6 +1182,218 @@ export async function resolveValues(placeholders, opts, paramsObj, { prompter =
   return { resolved, missing, sources };
 }
 
+// ─── TYPED-PARAMETER NORMALIZATION (v2 #3) ──────────────────────────────────
+// Schema entries can declare `type: date | money | party` with optional
+// `format` (date) or `currency` (money). Inputs are validated and normalized
+// after value resolution and before substitution. Hard error (exit 4) on
+// invalid input — typed params are opt-in; the user asked for validation.
+
+const MONTH_NAMES = ["January", "February", "March", "April", "May", "June",
+                     "July", "August", "September", "October", "November", "December"];
+const MONTH_INDEX = (() => {
+  const m = {};
+  MONTH_NAMES.forEach((name, i) => {
+    m[name.toLowerCase()] = i;
+    m[name.slice(0, 3).toLowerCase()] = i;
+  });
+  // "Sept" is a common 4-letter abbrev.
+  m.sept = 8;
+  return m;
+})();
+
+/**
+ * Parse a date input. Accepts ISO `YYYY-MM-DD` or spelled
+ * `Month D, YYYY` / `Mon D YYYY`. Returns a UTC `Date` on success or `null`
+ * on failure. Q3.1: US (`MM/DD/YYYY`) and European (`DD/MM/YYYY`) numeric
+ * formats are NOT accepted — they're ambiguous and footgun-y. Use ISO for
+ * machine input, spelled for human input.
+ *
+ * @param {string} raw
+ * @returns {Date | null}
+ */
+export function parseDateValue(raw) {
+  const s = String(raw).trim();
+  const iso = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s);
+  if (iso) {
+    const [, y, m, d] = iso;
+    const date = new Date(Date.UTC(+y, +m - 1, +d));
+    // Reject impossible dates (e.g. 2026-02-31 round-trips to 2026-03-03).
+    if (date.getUTCFullYear() !== +y || date.getUTCMonth() !== +m - 1 || date.getUTCDate() !== +d) return null;
+    return date;
+  }
+  const spelled = /^([A-Za-z]+)\s+(\d{1,2}),?\s+(\d{4})$/.exec(s);
+  if (spelled) {
+    const month = MONTH_INDEX[spelled[1].toLowerCase()];
+    if (month === undefined) return null;
+    const date = new Date(Date.UTC(+spelled[3], month, +spelled[2]));
+    if (date.getUTCMonth() !== month || date.getUTCDate() !== +spelled[2]) return null;
+    return date;
+  }
+  return null;
+}
+
+/**
+ * Format a `Date` per a simple format string. Supported tokens:
+ * `yyyy` (year), `MMMM` (full month name), `MM` (2-digit month), `d` (day).
+ * Order doesn't matter; tokens are matched in a single pass so MMMM doesn't
+ * accidentally consume MM, and `d` doesn't leak into month names.
+ *
+ * @param {Date} date
+ * @param {string} format
+ * @returns {string}
+ */
+export function formatDateValue(date, format) {
+  const y = date.getUTCFullYear();
+  const m = date.getUTCMonth();
+  const d = date.getUTCDate();
+  return format.replace(/yyyy|MMMM|MM|d/g, (token) => {
+    if (token === "yyyy") return String(y);
+    if (token === "MMMM") return MONTH_NAMES[m];
+    if (token === "MM") return String(m + 1).padStart(2, "0");
+    if (token === "d") return String(d);
+    return token;
+  });
+}
+
+/**
+ * Parse a money input. Accepts `$5,000`, `5000.50`, `$5M`, `2.5K`, etc.
+ * Handles `K`/`M`/`B` suffixes (case-insensitive). Returns the value in
+ * minor units (cents for USD) as an integer, or `null` on failure.
+ *
+ * @param {string} raw
+ * @returns {number | null}
+ */
+export function parseMoneyValue(raw) {
+  const s = String(raw).trim();
+  if (!s) return null;
+  // Strict shape: optional minus, optional single $, digits (with optional
+  // thousand-comma groups), optional decimal, optional K/M/B. Rejects
+  // doubled `$`, ad-hoc comma placement, multiple decimals, words.
+  if (!/^-?\$?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?[KMB]?$/i.test(s)) return null;
+  let core = s.replace(/[$,\s]/g, "");
+  let mult = 1;
+  if (/[KMB]$/i.test(core)) {
+    mult = { K: 1e3, M: 1e6, B: 1e9 }[core.slice(-1).toUpperCase()];
+    core = core.slice(0, -1);
+  }
+  const n = parseFloat(core);
+  if (!isFinite(n)) return null;
+  return Math.round(n * mult * 100);
+}
+
+/**
+ * Format a money value (in minor units, e.g. cents for USD) per a currency.
+ * Q3.2: v2 supports USD only. Adds thousand separators and always renders
+ * two decimal places.
+ *
+ * @param {number} minor — value in minor units (cents).
+ * @param {string} currency — currency code (only "USD" supported in v2).
+ * @returns {string}
+ * @throws {Error} on unsupported currency.
+ */
+export function formatMoneyValue(minor, currency) {
+  if (currency !== "USD") {
+    throw new Error(`only USD is supported in v0.3.0; got currency="${currency}"`);
+  }
+  const sign = minor < 0 ? "-" : "";
+  const abs = Math.abs(minor);
+  const dollars = Math.floor(abs / 100);
+  const cents = abs % 100;
+  const intPart = String(dollars).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  return `${sign}$${intPart}.${String(cents).padStart(2, "0")}`;
+}
+
+/**
+ * Normalize a raw value per a placeholder's schema-declared type. Returns
+ * the normalized string. Throws on invalid input (Q3.3 → hard error).
+ * If no `type` is declared on the placeholder, returns the raw value
+ * unchanged.
+ *
+ * @param {string} rawValue
+ * @param {{ type?: string|null, format?: string|null, currency?: string|null, key?: string }} placeholder
+ * @returns {string}
+ * @throws {Error} with `.exitCode = EXIT.VALIDATION` on bad input.
+ */
+export function normalizeTypedValue(rawValue, placeholder) {
+  const type = placeholder && placeholder.type;
+  if (!type) return rawValue;
+  if (type === "date") {
+    const date = parseDateValue(rawValue);
+    if (!date) {
+      const e = new Error(
+        `could not parse "${rawValue}" as a date. expected ISO ` +
+        `(2027-01-15) or spelled ("January 15, 2027"). ` +
+        `US ("01/15/2027") and European ("15/01/2027") forms are not ` +
+        `accepted — they're ambiguous.`
+      );
+      e.exitCode = EXIT.VALIDATION;
+      throw e;
+    }
+    return formatDateValue(date, placeholder.format || "MMMM d, yyyy");
+  }
+  if (type === "money") {
+    const minor = parseMoneyValue(rawValue);
+    if (minor === null) {
+      const e = new Error(
+        `could not parse "${rawValue}" as money. expected like ` +
+        `"$5,000", "5000.50", "$5M", "2.5K".`
+      );
+      e.exitCode = EXIT.VALIDATION;
+      throw e;
+    }
+    return formatMoneyValue(minor, placeholder.currency || "USD");
+  }
+  if (type === "party") {
+    const s = String(rawValue).trim();
+    if (!s) {
+      const e = new Error(`party value must be non-empty`);
+      e.exitCode = EXIT.VALIDATION;
+      throw e;
+    }
+    if (/\]\(/.test(s)) {
+      const e = new Error(`party value "${rawValue}" contains a markdown link; pass the bare party name instead.`);
+      e.exitCode = EXIT.VALIDATION;
+      throw e;
+    }
+    if (/[.!?,;:]$/.test(s)) {
+      const e = new Error(`party value "${rawValue}" has trailing punctuation; remove it before passing.`);
+      e.exitCode = EXIT.VALIDATION;
+      throw e;
+    }
+    return s;
+  }
+  const e = new Error(`unknown type "${type}" on placeholder${placeholder.key ? ` "${placeholder.key}"` : ""}. expected one of: date, money, party.`);
+  e.exitCode = EXIT.IO;
+  throw e;
+}
+
+/**
+ * Run {@link normalizeTypedValue} across every resolved placeholder value.
+ * Mutates `resolved` in place with normalized strings. Collects all errors
+ * before returning so the user sees every type failure at once.
+ *
+ * @param {Placeholder[]} placeholders
+ * @param {Object<string,string>} resolved
+ * @returns {{ ok: boolean, errors: Array<{ key: string, message: string }>, normalized: Object<string,{from: string, to: string, type: string}> }}
+ */
+export function normalizeTypedValues(placeholders, resolved) {
+  const errors = [];
+  const normalized = {};
+  for (const p of placeholders) {
+    if (!p.type) continue;
+    if (resolved[p.key] === undefined) continue;
+    const raw = resolved[p.key];
+    try {
+      const norm = normalizeTypedValue(raw, p);
+      if (norm !== raw) normalized[p.key] = { from: raw, to: norm, type: p.type };
+      resolved[p.key] = norm;
+    } catch (e) {
+      errors.push({ key: p.key, message: e.message });
+    }
+  }
+  return { ok: errors.length === 0, errors, normalized };
+}
+
 async function nodePrompter(placeholder) {
   if (!process.stdin.isTTY) return null;
   const rl = createInterface({ input: process.stdin, output: process.stderr });
@@ -1180,6 +1458,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
@@ -1277,6 +1632,21 @@ export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetc
     }
     return EXIT.VALIDATION;
   }
+  // v2 #3: typed-parameter validation. Mirror what cmdDraft does so
+  // `--validate` catches type errors before the user runs draft.
+  const typeCheck = normalizeTypedValues(result.placeholders, resolved);
+  if (!typeCheck.ok) {
+    for (const te of typeCheck.errors) {
+      err.write(paint(`error: type validation failed for "${te.key}": ${te.message}\n`, "red", err));
+    }
+    if (opts.json) {
+      out.write(JSON.stringify({
+        ok: false,
+        type_errors: typeCheck.errors.map(({ key, message }) => ({ key, message })),
+      }, null, 2) + "\n");
+    }
+    return EXIT.VALIDATION;
+  }
   if (opts.json) {
     out.write(JSON.stringify({ ok: true, resolved: Object.keys(resolved), sources }, null, 2) + "\n");
   } else {
@@ -1346,6 +1716,17 @@ export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher
     return EXIT.VALIDATION;
   }
 
+  // v2 #3: typed-parameter normalization. Schema entries can declare
+  // `type: date | money | party`. Inputs are validated and normalized
+  // before substitution. Hard error on bad input (Q3.3 decision).
+  const typeCheck = normalizeTypedValues(result.placeholders, resolved);
+  if (!typeCheck.ok) {
+    for (const te of typeCheck.errors) {
+      err.write(paint(`error: type validation failed for "${te.key}": ${te.message}\n`, "red", err));
+    }
+    return EXIT.VALIDATION;
+  }
+
   // Diff mode: print a substitution table and exit without writing output.
   if (opts.diff) {
     if (opts.json) {
@@ -1367,9 +1748,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 +1783,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 +1802,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.3.2",
   "description": "Fill placeholders in a legal-document template with parameter values. Part of the contract-operations suite.",
   "type": "module",
   "bin": {