npm - @drbaher/draft-cli - Versions diffs - 0.8.0 → 0.8.2 - Mend

@drbaher/draft-cli 0.8.0 → 0.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -4,6 +4,33 @@ 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.8.2 — 2026-05-17
+### Docs
+- **Animated SVG demo embedded in README.** Self-contained
+  (`assets/demo.svg`, ~11 KB) — plays inline on github.com and
+  npmjs.com without an asciinema.org dependency. Shows
+  `--list-placeholders` then a `--diff` substitution against the
+  Common Paper Mutual NDA cover page fixture in `examples/`.
+- Strictly docs + assets; no code or behavior change.
+## 0.8.1 — 2026-05-17
+### Docs
+- **README refreshed for the v2 surface.** New "v2 features" section
+  with one-paragraph showcases for each shipped v2 capability (.docx
+  round-trip, typed parameters, computed placeholders, positional
+  addressing, `parties.json` registry, multi-document bundles,
+  `--from-deal` LLM inference). Command reference updated with new
+  flags + version annotations. Exit-code table updated with code 4
+  (validation / typed / computed / ref / positional) and code 5
+  (LLM). Intro paragraph rewritten to reflect the v2 capability
+  scope instead of just v1.
+- No code or behavior change. v0.8.0's API surface, schema contract,
+  and CLI flags are unchanged. Strictly a docs publish.
 ## 0.8.0 — 2026-05-17
 ### Added

package/README.md CHANGED Viewed

@@ -1,62 +1,68 @@
+<p align="center">
+  <img src="assets/icon.svg" width="120" alt="draft-cli">
+</p>
 # draft-cli
-A **deterministic placeholder-filler** for legal-document templates. Reads
-bracketed (`[Party A]`) or mustache (`{{Party A}}`) markup, `.docx` yellow
-highlights, or generic-name heuristics; substitutes from CLI flags, a JSON
-params file, or an interactive prompt; writes a ready-to-review draft.
+> Part of the contract-operations CLI suite. **draft-cli** (fill placeholders) → [**nda-review-cli**](https://github.com/DrBaher/nda-review-cli) (review, redline, negotiate) → [**docx2pdf-cli**](https://github.com/DrBaher/docx2pdf-cli) (DOCX → PDF) → [**sign-cli**](https://github.com/DrBaher/sign-cli) (signing + audit). [Showcase site](https://cli.drbaher.com/).
-Single-file Node.js. One runtime dependency (`jszip`, for `.docx`). Local-first,
-no telemetry, MIT-licensed. Part of the contract-operations suite (see
-[cli.drbaher.com](https://cli.drbaher.com)).
+[![npm version](https://img.shields.io/npm/v/@drbaher/draft-cli.svg)](https://www.npmjs.com/package/@drbaher/draft-cli)
+[![npm downloads](https://img.shields.io/npm/dw/@drbaher/draft-cli.svg)](https://www.npmjs.com/package/@drbaher/draft-cli)
+[![CI](https://github.com/DrBaher/Draft-CLI/actions/workflows/ci.yml/badge.svg)](https://github.com/DrBaher/Draft-CLI/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
----
+Agent-first placeholder-filler for legal-document templates. Reads bracketed (`[Party A]`) or mustache markup, `.docx` yellow highlights, or generic-name heuristics; substitutes from CLI flags, a JSON params file, a shared `parties.json` registry, or — optionally — values extracted by an LLM from a free-form deal description; writes a ready-to-review draft as text or `.docx` (round-trip, runs and styles preserved). Schema-declared placeholders can be **typed** (`date` / `money` / `party`), **computed** (date arithmetic from another placeholder), **positional** (same text disambiguated by role), and **bundled** (fill multiple templates with one set of values).
-## What it does
+**The asymmetry is the architecture**: every step is deterministic and machine-driven except the values themselves — which can come from a flag, a params file, a parties registry, or an LLM extracting them from a prose deal description that a human wrote.
-You have a template. You have a deal. You want a draft you can review and
-send. The middle step — finding every `[Party A]`, `[Effective Date]`, and
-`[State of California]` and replacing them with real values — is mechanical,
-deterministic work that doesn't need an LLM and shouldn't need to leave your
-machine.
+<p align="center">
+  <img src="assets/demo.svg" alt="draft-cli demo: list placeholders then substitute against the Common Paper NDA cover page" width="900">
+</p>
-```
-template-vault get nda/house-mutual | draft - \
-    --party-a "Acme Corporation" \
-    --party-b "Vendor Inc." \
-    --effective-date 2026-06-01 \
-    --output draft.md
+## Run this
+```bash
+npx @drbaher/draft-cli@latest --demo
 ```
-Or via a params file:
+30 seconds, no file authoring required. Walks through a bracketed-template NDA with three placeholders, demoing the full cascade end-to-end. Or if you want to dive into a real template:
-```
-draft nda/house-mutual --params deal-acme.json --output draft.md
+```bash
+npm i -g @drbaher/draft-cli
+draft --list-placeholders examples/cp-mutual-nda-coverpage.md
 ```
-`draft` does **only** that step. Templates come from `template-vault-cli` or
-any markdown / .docx / stdin source. Review and red-line happens in
-`nda-review-cli`. Conversion to PDF goes through `docx2pdf-cli`. Signing
-goes through `sign-cli`. Each tool stays small and composable.
+## Where to go next
----
+| If you are… | Start here |
+|---|---|
+| **A new user** evaluating the tool | This README's [Quick start](#quick-start) and [What this gives you](#what-this-gives-you) |
+| **A drafter** filling your first template | [GETTING_STARTED.md](GETTING_STARTED.md) — 10-minute walkthrough of the main flows |
+| **An LLM agent** driving the CLI | [AGENTS.md](AGENTS.md) → `draft --list-placeholders --json` → [PARAM_SCHEMA.md](PARAM_SCHEMA.md) for the locked contract |
+| **A schema author** declaring typed / computed / positional placeholders | [PARAM_SCHEMA.md](PARAM_SCHEMA.md) §5 |
+| **A contributor** | [ARCHITECTURE.md](ARCHITECTURE.md), [CONTRIBUTING.md](CONTRIBUTING.md) |
-## Install
+Concept deep-dives live in [PARAM_SCHEMA.md](PARAM_SCHEMA.md) (the v1 + v2 contract); architecture in [ARCHITECTURE.md](ARCHITECTURE.md); FAQ in [FAQ.md](FAQ.md).
-```sh
-npm install -g @drbaher/draft-cli
-```
+## Quick start
-Or run without installing:
+```bash
+# Install
+npm i -g @drbaher/draft-cli
-```sh
+# Or run without installing
 npx @drbaher/draft-cli@latest --demo
+# After install, the binary is named `draft`
+draft --version
+draft --demo
 ```
 Requires Node.js ≥ 18. Tested on Ubuntu and macOS, Node 18 / 20 / 22.
 ### Shell completion
-```sh
+```bash
 # bash
 draft --completion bash >> ~/.bashrc
@@ -65,40 +71,22 @@ draft --completion zsh > ~/.zsh/completions/_draft
 # ensure ~/.zsh/completions is in fpath, then: autoload -U compinit && compinit
 ```
-Completes flags, the `--syntax bracket|mustache` value, `--completion bash|zsh`,
-and file paths for `--params`, `--output`, and `--dictionary`.
----
+Completes flags, the `--syntax bracket|mustache` value, `--completion bash|zsh`, and file paths for `--params`, `--output`, `--dictionary`, `--parties`, `--bundle`, `--from-deal`.
-## 30-second first run
+## What this gives you
-No file authoring required. The bundled demo runs end-to-end:
-```sh
-npx @drbaher/draft-cli@latest --demo
-```
-```
-demo: substituting [Party A], [Party B], [Effective Date]
-# Mutual Non-Disclosure Agreement (demo)
-This Agreement is entered into on 2026-06-01 between Acme Corporation
-and Vendor Inc. (collectively, the "Parties").
-1. Confidentiality. Acme Corporation and Vendor Inc. agree to keep confidential
-   any information disclosed under this Agreement.
-2. Term. This Agreement remains in effect for two years from the
-   2026-06-01.
-```
-What just happened: `draft-cli` detected three bracketed placeholders
-(`[Party A]`, `[Party B]`, `[Effective Date]`), mapped them to the
-canonical keys `party_a`, `party_b`, `effective_date`, and substituted
-in pre-canned demo values. Real runs use your own template and your own
-values.
----
+- **Five-tier detection cascade** — `[Title Case]` brackets / `{{mustache}}` / `.docx` highlights (yellow/green/cyan/magenta) / heuristic dictionary / optional LLM. First tier with hits wins; the rest are skipped. Deterministic through tier 4.
+- **`.docx` round-trip** — read a `.docx` template, fill placeholders, write `<basename>-filled.docx` with runs/styles/paragraph-breaks preserved. T3 highlight detection works against real templates (Common Paper, YC SAFE).
+- **Schema file** for canonical keys, alias phrases, defaults, required-ness, and the v2 fields below (`type`, `format`, `currency`, `computed`, `positions`). Without a schema, every detected bracketed phrase is treated as a required parameter.
+- **Typed parameters** — `type: date | money | party` validates and normalizes inputs before substitution. `"01/15/2027"` → `"January 15, 2027"`; `"$5M"` → `"$5,000,000.00"`. Bad inputs exit 4 with per-key error.
+- **Computed placeholders** — derive one placeholder's value from another via date arithmetic: `{ "from": "effective_date", "op": "+", "value": "2 years" }`. Cycle detection at schema parse time.
+- **Positional addressing** — same placeholder text with different semantic roles, addressed by position. Validated against the YC SAFE `$[_____________] × 2` case.
+- **`parties.json` registry** — declare known parties once; schemas reference `ref:parties.<key>.<field>`. Eliminates duplicating party metadata across templates.
+- **Multi-document bundles** — fill multiple templates with one shared set of values: `draft --bundle deal.bundle.json --params deal.json`. Abort-all on any pre-write error.
+- **LLM-from-deal inference** — `--from-deal PATH` reads a free-form deal description and asks the configured T5 provider (Anthropic / OpenAI / `DRAFT_LLM_*`) to fill the schema's parameters. CLI / `--params` still win over inferred values.
+- **Composable I/O** — stdin (`-`), stdout default, `--output PATH`, `template-vault get` integration for `<category>/<name>[@version]` template refs.
+- **Three modes** — `draft` (substitute and emit), `--list-placeholders` (enumerate), `--validate` (completeness check). All support `--json` and `--why`.
+- **Single file, stdlib + `jszip`**, no telemetry, local-first. Network only when the LLM tier is explicitly configured.
 ## End-to-end transcript
@@ -139,12 +127,9 @@ ok: 3 parameter(s) resolved
 ok
 ```
----
 ## Detection cascade
-`draft-cli` finds placeholders by trying five strategies in order. The
-**first non-empty tier wins** and the others are skipped.
+`draft-cli` finds placeholders by trying five strategies in order. The **first non-empty tier wins** and the others are skipped.
 | Tier | Strategy             | When                                      |
 | ---- | -------------------- | ----------------------------------------- |
@@ -154,45 +139,32 @@ ok
 | 4    | Heuristic dictionary | Bundled list of generic names (`Acme Corporation`, `John Doe`, `example@example.com`, etc.). Warn-only by default. |
 | 5    | LLM                  | Last resort. Runs only when `.env` or process env configures `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `DRAFT_LLM_*`. |
-The cascade is **deterministic through tier 4**. Tier 5 is the only
-non-deterministic step and runs only when you've explicitly configured a
-provider key. Pass `--no-llm` to disable it even when configured. Pass
-`--no-heuristic` to skip tier 4.
+The cascade is **deterministic through tier 4**. Tier 5 is the only non-deterministic step and runs only when you've explicitly configured a provider key. Pass `--no-llm` to disable it even when configured. Pass `--no-heuristic` to skip tier 4.
 See [PARAM_SCHEMA.md](PARAM_SCHEMA.md) for the full contract.
----
 ## Schema file (optional)
-A sibling `<template>.params.json` lets you declare canonical keys, alias
-phrases, defaults, and whether each parameter is required.
-**Short form:**
-```json
-{
-  "party_a": ["Party A", "Disclosing Party"],
-  "party_b": ["Party B", "Receiving Party"],
-  "effective_date": ["Effective Date"]
-}
-```
-**Long form** (gates on `_meta`):
+A sibling `<template>.params.json` lets you declare canonical keys, alias phrases, defaults, and required-ness. The **long form** (gated on `_meta`) unlocks the v2 fields:
 ```json
 {
   "_meta": { "schema_version": 1 },
-  "party_a":        { "aliases": ["Party A"], "required": true },
-  "effective_date": { "aliases": ["Effective Date"], "required": false, "default": "the date first written above" }
+  "party_a":         { "aliases": ["Party A"], "required": true, "type": "party" },
+  "effective_date":  { "aliases": ["Effective Date"], "type": "date", "format": "MMMM d, yyyy" },
+  "term_end":        { "aliases": ["Term End"], "type": "date",
+                       "computed": { "from": "effective_date", "op": "+", "value": "2 years" } },
+  "purchase_amount": { "aliases": ["Purchase Amount"], "type": "money", "currency": "USD" },
+  "blank":           { "aliases": ["_____________"], "type": "money", "currency": "USD",
+                       "positions": [{ "role": "valuation_cap" }, { "role": "purchase_amount" }] }
 }
 ```
-With a schema, `draft-cli` substitutes **only** declared parameters and
-leaves other bracketed text untouched. Without one, every detected
-bracketed phrase is treated as a required parameter.
+With a schema, `draft-cli` substitutes **only** declared parameters and leaves other bracketed text untouched. Without one, every detected bracketed phrase is treated as a required parameter.
+The **short form** is just an aliases map: `{ "party_a": ["Party A"] }`.
----
+See [PARAM_SCHEMA.md](PARAM_SCHEMA.md) §5 for the full schema contract and the locked design decisions per v2 feature.
 ## Command reference
@@ -203,10 +175,15 @@ draft -                       template body on stdin
 draft --demo                  bundled demo, no file needed
 draft --list-placeholders <t> enumerate placeholders and exit
 draft --validate <t> --params completeness check, no output
+draft --bundle <bundle.json>  multi-doc bundle mode (v0.7.0)
 OPTIONS
   --params FILE          JSON file of param values (snake_case keys)
-  -o, --output PATH      write to PATH (default: stdout)
+  --parties PATH         parties.json registry for ref:parties.<key>.<field>  (v0.6.0)
+  --bundle PATH          fill multiple templates in one invocation             (v0.7.0)
+  --from-deal PATH       LLM-extract values from a free-form deal description  (v0.8.0)
+  -o, --output PATH      write to PATH (default: stdout). `-` forces stdout.
+                         For .docx input, default is <basename>-filled.docx   (v0.2.0)
   --syntax bracket|mustache
   -i, --interactive      prompt for missing required parameters
   --why                  structured explanation to stderr
@@ -214,7 +191,7 @@ OPTIONS
   -q, --silent           suppress all stderr (warnings, --why, notes)
   --no-heuristic         disable tier 4
   --yes-heuristic        substitute tier-4 matches without confirmation
-  --no-llm               disable tier 5 even when env is configured
+  --no-llm               disable tier 5 + --from-deal even when env is configured
   --llm                  assert that env is configured (fail-fast if not)
   --check-llm            one-token roundtrip to verify provider config
   --diff                 show substitution table without writing output
@@ -224,81 +201,46 @@ OPTIONS
   -V, --version          show version
 ```
-Exit codes: `0` ok · `1` i/o · `2` validation · `3` template-vault failure
-· `4` llm failure.
----
+Exit codes: `0` ok · `1` i/o · `2` validation · `3` template-vault failure · `4` schema validation / typed parameter / computed / ref / positional · `5` llm failure.
 ## LLM tier (env-gated, opt-in)
-When tiers 1–4 all find nothing, `draft-cli` falls back to a language model
-**only if** a provider key is in the environment. Read order: `.env` in
-the working directory, then `process.env` (process wins).
+When tiers 1–4 all find nothing, `draft-cli` falls back to a language model **only if** a provider key is in the environment. Read order: `.env` in the working directory, then `process.env` (process wins).
 ```sh
 echo 'ANTHROPIC_API_KEY=sk-ant-…' >> .env
 draft some-freeform-draft.md          # tier 5 auto-runs when 1-4 empty
 ```
-Supported providers: Anthropic (`ANTHROPIC_API_KEY`), OpenAI
-(`OPENAI_API_KEY`), or explicit (`DRAFT_LLM_PROVIDER` + `DRAFT_LLM_API_KEY`
-+ optional `DRAFT_LLM_MODEL`). The LLM receives template text only — no
-params file, no `.env` contents, no other data. Pass `--no-llm` to disable
-even when configured.
+Supported providers: Anthropic (`ANTHROPIC_API_KEY`), OpenAI (`OPENAI_API_KEY`), or explicit (`DRAFT_LLM_PROVIDER` + `DRAFT_LLM_API_KEY` + optional `DRAFT_LLM_MODEL`). The LLM receives template text only — no params file, no `.env` contents, no other data. Pass `--no-llm` to disable even when configured.
----
+**v0.8.0 inverse direction — `--from-deal PATH`:** feed prose deal notes and the LLM extracts values for the schema's placeholders (instead of inferring where placeholders are). Uses the same provider config. Errors on provider missing, network failure, or non-JSON response. CLI / `--params` values always win over LLM-inferred ones. See [PARAM_SCHEMA.md](PARAM_SCHEMA.md) §5.
 ## Composability
-`draft-cli` reads from stdin, writes to stdout by default, and exits with
-distinct codes for each failure class. It composes with `template-vault-cli`
-on the read side and `nda-review-cli` / `docx2pdf-cli` / `sign-cli` on
-the write side:
+`draft-cli` reads from stdin, writes to stdout by default, and exits with distinct codes for each failure class. It composes with `template-vault-cli` on the read side and `nda-review-cli` / `docx2pdf-cli` / `sign-cli` on the write side:
-```sh
-template-vault get nda/house-mutual \
-  | draft - --params deal-acme.json \
-  | nda-review review - --playbook house \
+```bash
+# Pull a versioned template, fill it, hand it to review, convert to PDF, sign.
+template-vault get nda/house-mutual@v3 \
+  | draft - --from-deal deal-notes.txt --parties parties.json \
+  | nda-review --redline \
   | docx2pdf - draft.pdf
+sign-cli send draft.pdf --signer counsel@counterparty.com
 ```
-The `--why` and `--json` flags make every step inspectable by agents and
-shell pipelines.
----
-## Part of the contract-operations suite
-`draft-cli` is one of a small set of single-purpose CLIs for contract
-operations. See [cli.drbaher.com](https://cli.drbaher.com) for the suite
-landing page.
-- **[nda-review-cli](https://github.com/DrBaher/nda-review-cli)** —
-  draft, review, and negotiate NDAs against your own house playbook.
-  Deterministic by default; opt-in LLM augmentation.
-- **[docx2pdf-cli](https://github.com/DrBaher/docx2pdf-cli)** —
-  honest DOCX → PDF conversion with batch processing, parallel runs,
-  font validation.
-- **[sign-cli](https://github.com/DrBaher/sign-cli)** —
-  fully-offline PAdES e-signature with hash-chained audit events,
-  RFC 3161 timestamps.
-`template-vault-cli` (a Git-backed, clause-aware package manager for
-legal-document templates) is the natural upstream of `draft-cli` and
-will join the suite when it ships.
----
+Each tool stays small and replaceable. None of them know about each other beyond the standard `stdin / stdout / argv / exit codes` contract.
 ## Documentation
-- [GETTING_STARTED.md](GETTING_STARTED.md) — 10-minute walk-through of every flow.
+- [GETTING_STARTED.md](GETTING_STARTED.md) — 10-minute walkthrough of the main flows.
 - [AGENTS.md](AGENTS.md) — JSON shapes, exit codes, library use; everything an LLM agent driving `draft-cli` needs.
-- [PARAM_SCHEMA.md](PARAM_SCHEMA.md) — locked v1 contract: cascade, schema file, precedence.
-- [ARCHITECTURE.md](ARCHITECTURE.md) — single-file rationale, substitution model, .docx parsing.
-- [FAQ.md](FAQ.md) — design questions and trade-offs.
-- [SECURITY.md](SECURITY.md) — threat model and how to report a vulnerability.
-- [CHANGELOG.md](CHANGELOG.md) — release notes and the v2 "Deferred" list.
-- [CONTRIBUTING.md](CONTRIBUTING.md) — scope rules and release flow.
+- [ARCHITECTURE.md](ARCHITECTURE.md) — how the cascade, schema, and substitution pipeline fit together.
+- [PARAM_SCHEMA.md](PARAM_SCHEMA.md) — v1 + v2 schema contract; locked decisions per feature.
+- [FAQ.md](FAQ.md) — common questions about detection rules, T4 heuristics, and the LLM tier.
+- [V2_BRIEFS_REMAINING.md](V2_BRIEFS_REMAINING.md) — design briefs for the four v2 items shipped after v0.1.x; historical now that all four have landed.
+- [SECURITY.md](SECURITY.md) — reporting vulnerabilities.
+- [CHANGELOG.md](CHANGELOG.md) — every shipped version with locked design decisions.
 ## License

package/draft-cli.mjs CHANGED Viewed

@@ -70,7 +70,7 @@ import { fileURLToPath } from "node:url";
  */
 /** @type {string} */
-export const VERSION = "0.8.0";
+export const VERSION = "0.8.2";
 // ─── EXIT CODES ─────────────────────────────────────────────────────────────
 /**

package/package.json CHANGED Viewed

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