@drbaher/draft-cli 0.1.0

package/FAQ.md

@@ -0,0 +1,190 @@
+# FAQ
+
+## Why `[Bracketed Title Case]` as the primary syntax instead of mustache?
+
+The legal templates `draft-cli` targets — Common Paper, YC SAFE,
+Bonterms, most house templates — use square-bracket placeholders. That's
+the de-facto convention in the legal-tech corner of the world. Mustache
+(`{{...}}`) is the engineering-template convention; it's supported via
+`--syntax mustache` for cases where you've already written a template
+in that flavor.
+
+We deliberately don't auto-detect mixed conventions, only warn about
+them. Auto-detection would surprise users whose template includes a
+`{{quote}}` inside a code block.
+
+## Why no computed placeholders like `[Effective Date + 2 years]`?
+
+Deferred to v2. The hard part isn't the arithmetic — it's the date
+parsing (handling `2026-06-01`, `June 1, 2026`, `the first business
+day of Q3`, etc.) and the locale/timezone surface. v1 keeps the
+substitution model trivially auditable: each placeholder is replaced
+with the literal string the user supplied. No transformations, no
+locale, no surprises.
+
+The schema's long form reserves a future `"computed"` field for this.
+
+## How is this different from a real templating engine like Handlebars or Jinja?
+
+Three differences that matter for legal-doc workflows:
+
+1. **Detection cascade.** A templating engine assumes the template
+   already has explicit markup (`{{name}}`). `draft-cli` also handles
+   `.docx` yellow highlights, generic-name heuristics, and an LLM
+   fallback. You can hand it a contract that has *no* markup and get
+   a list of likely placeholders.
+2. **Alias-aware schema.** `[Party A]` and `[Disclosing Party]` and
+   `[Originating Party]` are the same role with three names. The schema
+   file maps multiple bracketed phrase forms to one canonical key.
+   Most templating engines don't have this.
+3. **Agent-friendly surface.** Every command emits a structured `--why`
+   block and supports `--json`. The CLI is built for both humans and
+   LLM agents to call.
+
+If you're filling in `{{name}}` in an email template, Handlebars is
+fine. If you're filling in `[Party A]` in an NDA and want to know
+which of seven bracketed phrases got substituted from where, this is
+the tool.
+
+## Why is the LLM tier env-gated instead of a CLI flag?
+
+Two reasons:
+
+1. **Configuration vs invocation.** Whether you have an LLM provider
+   available is a property of your environment, not of any individual
+   `draft` invocation. Env is the right surface.
+2. **Friction-as-consent.** Setting `ANTHROPIC_API_KEY=...` in `.env`
+   takes a few seconds and is a deliberate act. Passing `--llm` on the
+   command line is easy to muscle-memory into a one-liner without
+   thinking about the network call. The env gate forces you to opt in
+   once and re-affirm by leaving the key configured.
+
+`--no-llm` exists so a script can disable T5 even when env happens to
+be set. `--llm` exists so a script can fail-fast if env is not set
+(instead of silently falling through to T4).
+
+## Why does `--yes-heuristic` even exist? Can't draft-cli just substitute?
+
+The heuristic dictionary contains generic-sounding values like
+`Acme Corporation`, `John Doe`, `example@example.com`. If your real
+counterparty happens to be named "Acme Corporation," substituting
+silently would replace their actual name with whatever value you
+supplied for `acme_corporation` — possibly the new party's name, but
+possibly something worse.
+
+The default behavior in non-interactive mode is **warn and do
+nothing** — list the matches but leave them untouched. You either
+add the matches to your template's `.params.json` (promoting them to
+declared parameters) or pass `--yes-heuristic` to accept the risk
+non-interactively.
+
+In interactive mode, you get a `y/N` prompt per run.
+
+## Why is `draft-cli` Node.js and not Python? The other Python CLI uses pipx.
+
+The contract-operations suite has two Python CLIs (`template-vault-cli`,
+`nda-review-cli` — both `pipx`-installed) and two JS CLIs (`docx2pdf-cli`,
+`sign-cli` — both `npm`/`npx`-installed). `draft-cli` joined the JS lane
+during the v1 design conversation, mirroring `docx2pdf-cli`'s posture
+(single-file Node, npm-installed, stdlib + one carefully-chosen dep).
+The decision lives in [CHANGELOG.md](CHANGELOG.md) v0.1.0.
+
+The CLI is provider-and-runtime-agnostic from a user perspective: it
+reads stdin, writes stdout, has clear exit codes, and integrates with
+the Python siblings via subprocess (`template-vault get | draft -`).
+
+## Why don't you ship `.docx` output?
+
+Round-tripping back to `.docx` (preserving styles, numbered lists, run
+formatting, and the original run boundaries) is its own problem domain.
+The substituted text might be longer or shorter than the original;
+Word's run-and-paragraph model means the substituted text either has
+to inherit the entire surrounding run's formatting, or split itself
+across runs in a way that respects the document's style table. None of
+this is hard, but it's a different feature from "find and replace."
+
+For now, `.docx` is **input-only** in v1 — you get text out. If you
+need `.docx` out, run the text through `docx2pdf-cli` first, or open
+the markdown output in Word.
+
+## Why does the canonical key for `[1 year(s)]` look like `_1_year_s`?
+
+Because the v1 bracket rule had to handle real Common Paper templates
+(see the v0.1.0 CHANGELOG entry), it admits sentence-shaped placeholders
+with full punctuation. The canonical-key derivation is a permissive slug
+to make sure inferred keys are always valid snake_case identifiers:
+non-alphanumeric runs collapse to `_`, leading digits get a `_` prefix,
+and the result is capped at 60 chars.
+
+Real templates with sentence-shaped placeholders should ship a
+`<template>.params.json` schema that maps to clean keys. That's what
+the Common Paper fixture in `tests/fixtures/cp-mutual-nda-coverpage.params.json`
+does — `[1 year(s)]` maps to the clean key `term`.
+
+## Can I extend the heuristic dictionary?
+
+Yes. Pass `--dictionary path/to/your.json` — the file must be a JSON
+array of strings. Your file **replaces** the bundled list (not extends
+it). Copy `DEFAULT_HEURISTIC_DICT` out of `draft-cli.mjs` and edit if
+you want a superset.
+
+## What if a template has two `[_____________]` placeholders that should hold different values?
+
+The YC SAFE has this exact problem: one `$[_____________]` is the
+purchase amount, another `$[_____________]` is the post-money valuation
+cap. Same bracketed text, different roles.
+
+v1's alias-based matching treats them as one parameter. Substituting
+`100000` for `purchase_amount` will replace **both** occurrences.
+
+Workarounds for v1:
+
+1. Edit the template before running draft-cli to make the placeholders
+   distinguishable: `[Purchase Amount]` and `[Valuation Cap]`. Then
+   the schema can map them independently.
+2. Substitute the first, then run draft-cli again with a different
+   value to substitute the second. Awkward but works for two-occurrence
+   cases.
+3. Run draft-cli, then manually fix the second occurrence in the output.
+
+Positional-aware placeholder addressing (`[___1]`, `[___2]`) is a v2
+candidate.
+
+## My template has `[COMPANY]` in the signature block. draft-cli ignores it. Why?
+
+`draft-cli`'s default detection rule rejects all-caps bracketed runs to
+avoid false positives on section headings like `[CONFIDENTIALITY]`. But
+all-caps signature-block placeholders are real, especially in older
+templates and ones converted from `.docx`.
+
+The fix: declare it in the schema file with the all-caps phrase as an
+alias.
+
+```json
+{ "company": ["Company Name", "COMPANY"] }
+```
+
+`draft-cli` consults the schema's alias union during detection and
+**rescues** otherwise-rejected runs that are explicitly declared. This
+is documented in [PARAM_SCHEMA.md §5](PARAM_SCHEMA.md). Without the
+schema, the run is silently skipped — which is intentional, but visible
+when you run `--list-placeholders` and don't see the placeholder you
+expected.
+
+## How do I integrate with `template-vault-cli`?
+
+`template-vault-cli` ships templates by category and name. `draft-cli`
+recognizes `<category>/<name>[@version]` as a vault ref and shells out
+to `template-vault get`:
+
+```sh
+draft nda/house-mutual --params deal.json
+```
+
+If `template-vault` isn't on `$PATH` or returns non-zero, `draft-cli`
+exits with code `3` and surfaces the vault's error message. You can
+also pipe explicitly:
+
+```sh
+template-vault get nda/house-mutual | draft - --params deal.json
+```

package/GETTING_STARTED.md

@@ -0,0 +1,263 @@
+# Getting started
+
+A 10-minute walkthrough of the main flows. Assumes you have Node 18+.
+
+## 1. Install (or try without installing)
+
+```sh
+npm install -g @drbaher/draft-cli
+draft --version    # → draft-cli 0.1.0
+```
+
+To try without installing globally:
+
+```sh
+npx @drbaher/draft-cli@latest --demo
+```
+
+## 2. The 30-second demo
+
+```sh
+draft --demo
+```
+
+This substitutes three placeholders in a bundled NDA template and
+prints the result. No file authoring required.
+
+```
+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").
+...
+```
+
+## 3. Your first real template
+
+Save this as `simple-nda.md`:
+
+```markdown
+This Agreement is between [Party A] and [Party B], effective [Effective Date].
+[Party A] and [Party B] agree to keep confidential information confidential.
+```
+
+List the placeholders draft-cli finds:
+
+```sh
+draft --list-placeholders simple-nda.md
+```
+
+Output:
+
+```
+party_a  (Party A)  ×2  [tier=bracket]
+party_b  (Party B)  ×2  [tier=bracket]
+effective_date  (Effective Date)  ×1  [tier=bracket]
+```
+
+Substitute via CLI flags:
+
+```sh
+draft simple-nda.md \
+  --party-a "Acme Corporation" \
+  --party-b "Vendor Inc." \
+  --effective-date 2026-06-01
+```
+
+Substitute via a JSON file:
+
+```sh
+cat > deal.json <<'EOF'
+{"party_a": "Acme Corporation", "party_b": "Vendor Inc.", "effective_date": "2026-06-01"}
+EOF
+
+draft simple-nda.md --params deal.json --output draft.md
+cat draft.md
+```
+
+## 4. The `--why` block
+
+```sh
+draft simple-nda.md --params deal.json --why
+```
+
+`--why` emits a structured stderr block describing what happened:
+
+```
+draft: substituted 3 of 3 placeholders
+why:
+  input         = simple-nda.md
+  tier          = bracket
+  schema        = (none, inferred)
+  placeholders  = 3 distinct, 5 occurrences
+  resolved      = 3 (0 from CLI, 3 from --params, 0 interactive, 0 default)
+  defaulted     = 0
+  unresolved    = 0
+  unmapped      = 0
+  warnings      = 0
+```
+
+The block is parseable but also human-readable. It tells you which
+tier matched, where each value came from, and whether anything got
+defaulted, prompted, or left unresolved.
+
+## 5. The `--json` mode
+
+```sh
+draft simple-nda.md --params deal.json --json
+```
+
+Stdout is a single JSON object that any downstream tool can parse:
+
+```json
+{
+  "ok": true,
+  "tier": "bracket",
+  "output_path": null,
+  "output": "This Agreement is between Acme Corporation and Vendor Inc.…",
+  "placeholders": [ {…}, {…}, {…} ],
+  "sources": { "party_a": "params", "party_b": "params", "effective_date": "params" },
+  "warnings": [],
+  "unmapped": []
+}
+```
+
+Combine with `--output` to write the substituted text to disk AND get
+the JSON report:
+
+```sh
+draft simple-nda.md --params deal.json --output draft.md --json | jq '.placeholders[].key'
+```
+
+## 6. Validate before drafting
+
+`--validate` runs the same lookup but never writes output. Useful in
+CI / pre-commit hooks:
+
+```sh
+draft --validate simple-nda.md --params deal.json && echo "ok"
+```
+
+Exit code `0` if every required placeholder resolves, `2` otherwise.
+With `--json`, you get a structured `{ok: bool, missing: [...]}` report.
+
+## 7. Alias-aware schema
+
+Real legal templates use multiple bracketed phrase forms for the same
+role: `[Party A]` and `[Disclosing Party]` are usually the same person.
+Declare aliases in a sibling `<template>.params.json`:
+
+```sh
+cat > simple-nda.params.json <<'EOF'
+{
+  "party_a": ["Party A", "Disclosing Party"],
+  "party_b": ["Party B", "Receiving Party"],
+  "effective_date": ["Effective Date"]
+}
+EOF
+```
+
+Now `draft simple-nda.md --party-a "Acme"` substitutes **both**
+`[Party A]` and `[Disclosing Party]` everywhere in the template with
+`Acme`.
+
+Long form supports defaults:
+
+```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" }
+}
+```
+
+The presence of a top-level `_meta` key tells the parser to expect long
+form. With `required: false` and a `default`, a missing CLI value falls
+through to the default and validation still passes.
+
+## 8. Real-world Common Paper template
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/CommonPaper/Mutual-NDA/main/Mutual-NDA-coverpage.md \
+  -o coverpage.md
+
+draft --list-placeholders coverpage.md
+```
+
+You'll see sentence-shaped placeholders like `[Today's date]`,
+`[1 year(s)]`, and the full
+`[Evaluating whether to enter into a business relationship with the other party.]`.
+The keys are ugly because they're auto-derived. Add a schema file to
+give them clean names:
+
+```sh
+cat > coverpage.params.json <<'EOF'
+{
+  "purpose":         ["Evaluating whether to enter into a business relationship with the other party."],
+  "effective_date":  ["Today’s date"],
+  "term":            ["1 year(s)"],
+  "governing_state": ["Fill in state"],
+  "jurisdiction":    ["Fill in city or county and state, i.e. “courts located in New Castle, DE”"]
+}
+EOF
+
+draft coverpage.md \
+  --purpose "Evaluating whether to acquire Vendor Inc." \
+  --effective-date 2026-06-01 \
+  --term "2 years" \
+  --governing-state "Delaware" \
+  --jurisdiction "New Castle County, Delaware" \
+  --output draft.md
+```
+
+The substituted draft preserves Markdown structure (the
+`### Effective Date` heading, the checkbox markers `- [x]`, the
+signature table) byte-for-byte except for the substituted placeholders.
+
+## 9. `.docx` input
+
+Pass a `.docx` directly:
+
+```sh
+draft your-template.docx --party-a "Acme" --output draft.md
+```
+
+Tier 1 (bracket) tries first against the extracted text. If the
+`.docx` has no bracketed markup, tier 3 (highlight) catches
+yellow / green / cyan / magenta highlighted runs as placeholders.
+Output is plain markdown; `.docx` output round-trip is a v2 feature.
+
+## 10. Tab completion (optional)
+
+```sh
+# bash
+draft --completion bash >> ~/.bashrc
+
+# zsh
+draft --completion zsh > ~/.zsh/completions/_draft
+```
+
+After reloading your shell, tab-completion fills in flags, the
+`--syntax bracket|mustache` argument, and file paths for `--params`,
+`--output`, and `--dictionary`. The dynamic `--<param-name>` flags
+aren't completed (they depend on the template), but every static flag
+is.
+
+## 11. Compose with the rest of the suite
+
+```sh
+template-vault get nda/house-mutual \
+  | draft - --params deal.json \
+  | nda-review review - --playbook house \
+  | docx2pdf - draft.pdf
+```
+
+Each tool reads from stdin, writes to stdout, and exits with distinct
+codes. Add `--why` or `--json` at any step to inspect what happened.
+
+---
+
+For the full command reference, see [README.md](README.md#command-reference).
+For the parameter contract details, see [PARAM_SCHEMA.md](PARAM_SCHEMA.md).
+For architectural rationale, see [ARCHITECTURE.md](ARCHITECTURE.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DrBaher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.