@cosyte/cli 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,326 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Versions and publishing are managed with [Changesets](https://github.com/changesets/changesets);
+this file is maintained by hand (Changesets handles the version bump and publish only).
+
+## [Unreleased]
+
+The first pre-alpha release (`0.0.1`) will ship the initial public API surface. The package begins
+its public history at `0.0.x`, per the cosyte version ladder (`0.0.x` until first alpha).
+
+### Added
+
+- **Phase 7: release hardening (the final roadmap phase; the CLI is feature-complete).** No new
+  runtime command surface: this phase is publish-readiness.
+  - **Fuzz gate over the two input boundaries.** `test/fuzz.property.test.ts` fuzzes the terminal
+    (`run`, over arbitrary argv vectors + stdin bytes) and the agent surface (`dispatchTool`, over an
+    arbitrary tool name + arguments), asserting neither ever throws an unhandled exception, always
+    resolves to a documented exit code, and never leaks a raw stack frame onto a secondary channel. The
+    case count scales via `CLI_FUZZ_RUNS`; a scheduled **Fuzz** workflow (`.github/workflows/fuzz.yml`)
+    runs it nightly at a high count, and `pnpm test:fuzz` runs it on demand.
+  - **Exit-code golden matrix.** `test/exit-code-matrix.test.ts` locks one representative invocation for
+    every code in the `0/1/2/65/66/69/70` contract, driven end-to-end through `run`, so a regression that
+    turns an invalid-input exit `1` into a `0` (or renumbers a code) fails CI. The exit-code map and the
+    stable `CLI_*` diagnostic codes are a stability surface: renaming one is a breaking change.
+  - **Publish dry-run proven.** A new `smoke` gate (`scripts/smoke.mjs`, wired into `verify.sh`)
+    exercises the **built** package (the dual ESM/CJS `.` and `./mcp` subpath exports, and **both**
+    `cosyte` / `cosyte-mcp` bins under `node`) and `npm publish --dry-run` assembles a clean tarball
+    (`dist` + `README`/`LICENSE`/`CHANGELOG`). `attw` remains a publish gate.
+  - **Honesty + release docs.** `docs-content/limitations.md` (wraps-not-implements, the non-goals, the
+    honest per-(format, operation) support matrix, the PHI-default posture), a man-page-style
+    `docs-content/reference-commands.md`, and `RELEASING.md` (the one-package-two-bins publish,
+    provenance/OIDC, the vendored-`file:`→npm dep swap, and the two standing founder stops).
+- **Phase 6: six more formats + streaming + shell completion (ADR 0025).** The `cosyte` CLI now wraps
+  **all eight cosyte formats**, routed through a single lazy **per-format adapter registry**
+  (`src/core/parsers.ts`) that replaces the old per-command `hl7 ? : fhir` branches and makes support
+  **per (format, operation)**. An unsupported (format, op) is a value-free `CLI_FORMAT_UNSUPPORTED`,
+  never a fake (ADR 0018).
+  - **New formats and their honest capabilities.** `x12`, `astm`, `ncpdp` (SCRIPT) → **parse · inspect ·
+    fmt · validate**; `ccda` → **inspect · fmt** (XML re-serialize) **· validate** (`parse` deferred, no
+    library-blessed JSON model; XML is the canonical form); `dicom` → **inspect · validate** (`parse`/`fmt`
+    deferred. The model is binary); `mllp` → **parse · inspect** (a transport container the CLI de-frames
+    to its enclosed HL7 message(s)). Content autodetection now covers all eight (conservative + disjoint:
+    a leading `0x0B` VT byte routes to `mllp`, `ISA`→`x12`, an `H`-record→`astm`, `<ClinicalDocument>`→`ccda`,
+    a `<Message>` in the NCPDP namespace→`ncpdp`, `DICM`@128→`dicom`); `--format` accepts `mllp`.
+  - **Streaming / multi-message.** `parse` emits **NDJSON** with per-record isolation for inherently
+    multi-record inputs: an **MLLP** stream (one record per frame) and any input under the new
+    **`--ndjson`** flag (one record per non-empty line: the FHIR bulk-data convention). A record that
+    fails to parse becomes a value-free `{ record, error }` line and the stream continues; the overall
+    exit is a data error (`65`) if any record failed. A single message is unchanged (one pretty, or
+    `--json` compact, envelope + a value-free warning-count note).
+  - **Shell completion.** `cosyte completion <bash|zsh|fish>` prints a static, value-free completion
+    script generated from the command tree.
+  - **Dependencies. The cap stays 4 (no umbrella edit).** The six breadth parsers are vendored
+    **`optionalDependencies`**, lazy-loaded per format and **outside** the hard-runtime-dep closure
+    (ADR 0025, mirroring the MCP SDK isolation of ADR 0024). An absent optional parser degrades to a
+    value-free **`CLI_PARSER_UNAVAILABLE`** (exit `69`), never a crash. Pinned sibling commits: dicom
+    `d1ed590`, x12 `0c60606`, ccda `3753216`, ncpdp `184eecc`, astm `92ac210`, mllp `aecff75` (all
+    v0.0.1 except astm records-layer). Third-party CLI-core runtime deps stay **zero**.
+  - New diagnostic **`CLI_PARSER_UNAVAILABLE`** (exit `69`); the exit-code contract is otherwise
+    unchanged (`0/1/2/65/66/69/70`). New value-free inspect summaries per format; new programmatic
+    exports (`OP_SUPPORT`, `supportsOp`, `formatsSupporting`, `parseFormat`, `inspectFormat`, `fmtFormat`,
+    `validateFormat`, `deframeMllp`, `loadOptional`, `valueFreeLocator`, `DETECTABLE_FORMATS`,
+    `completionCommand`, and the result/summary types). The public `WIRED_FORMATS` set is **removed** in
+    favour of the per-op `OP_SUPPORT` matrix (pre-alpha `0.0.x` surface change).
+
+- **Phase 5: the `cosyte-mcp` MCP server (the agent front door).** A **stdio Model Context Protocol
+  server** that exposes the shared command core to an LLM/agent as callable tools: the second adapter
+  over one core (ADR 0022, 0024). Reachable three ways: the new **`cosyte-mcp`** bin, the **`cosyte mcp`**
+  subcommand, and the **`@cosyte/cli/mcp`** subpath export. Tools: **`parse`**, **`validate`**,
+  **`inspect`**, and **`convert`**, each a thin wrapper that calls the same command handler the terminal
+  uses (with `--json`), so `cosyte parse` and the MCP `parse` tool agree by construction; the CLI
+  re-implements nothing.
+  - **PHI posture, inherited and hardened.** Every tool runs under the value-free posture. There is
+    **no** `--unsafe-show-values` door on the agent surface. A tool _result_ carries the requested data
+    (the parsed model / converted Bundle: the explicit request); a tool _error_ carries only the value-
+    free diagnostic (a stable code + positional context), never an input value. A parsed-but-invalid
+    `validate` verdict is a **successful** call reporting the verdict, not a tool error; only a hard
+    failure (unparseable / no input / usage) sets `isError`.
+  - **The MCP SDK is isolated and runtime-optional (ADR 0024).** `@modelcontextprotocol/sdk` (the CLI's
+    first and only third-party runtime dependency) is declared in **`optionalDependencies`** (pinned
+    `1.29.0`) and imported **only** in `src/mcp/server.ts`, reachable solely via the `./mcp` boundary
+    (the subpath, the `cosyte-mcp` bin, and a dynamic `import()` on the `cosyte mcp` branch). A `cosyte
+parse` invocation never loads it; the core works with the SDK absent (`--omit=optional`). Because it
+    is not part of the hard runtime closure, the umbrella `verify-policy.json` cap on `cli` runtime
+    `dependencies` stays **4**: unchanged. A static isolation test proves no `core`/`commands` module
+    imports the SDK.
+  - New subpath export **`@cosyte/cli/mcp`** and new **`cosyte-mcp`** bin; new programmatic exports
+    (`createMcpServer`, `startStdioServer`, `dispatchTool`, `TOOL_DEFS`, and the MCP result types) on the
+    `./mcp` subpath. `redact`/`deid` (gated on `@cosyte/deid`) and `map-codes` are deliberately not
+    exposed as tools yet.
+- **Phase 4: `convert` / `map-codes` (the consumer-of-consumers commands).** Two commands that wrap
+  the higher-layer libraries; the CLI adds **no** mapping or terminology logic of its own.
+  - **`convert <file|-> --to fhir [--json] [--quiet]`**: **HL7 v2 → FHIR R4** via
+    **`@cosyte/transform`**. Parses the input with `@cosyte/hl7`, hands the parsed message to
+    `transform.toFhir`, and emits the serialized FHIR **message `Bundle`** (the library's canonical
+    serialization) on **stdout**: `cosyte convert` equals `transform`'s programmatic output. The
+    conversion's value-free issues (a stable code + a v2-index → FHIRPath locator, never a field value)
+    render on stderr (or as a JSON envelope under `--json`); `--quiet` suppresses them. The
+    load-bearing rule mirrors `validate`: an **error-severity** transform issue drives exit **`1`**,
+    never `0`. `--to fhir` is required (the only target); a **non-HL7 source** (e.g. a FHIR document) is
+    a value-free `CLI_FORMAT_UNSUPPORTED` data error (`65`), never a fake conversion; an unparseable
+    HL7 input is `CLI_PARSE_FAILED` (`65`).
+  - **`map-codes <conceptmap|-> --code <code> [--system <uri>] [--version] [--display] [--json]
+[--quiet]`**: translate a single source coding through a **BYO FHIR R4 ConceptMap** via
+    **`@cosyte/terminology`** (`$translate`). The positional is the ConceptMap document; the source
+    coding is named by flags. A ConceptMap and a code are **reference data, not PHI**, so the
+    translation result goes to **stdout**: a **match** → the target coding(s) + exit **`0`**; an
+    **unmapped** code → the never-fabricate `TERM_TRANSLATE_UNMAPPED` signal + exit **`1`**. A map that
+    is not valid JSON or not a loadable ConceptMap is the new value-free **`CLI_MAP_INVALID`** data
+    error (`65`), surfacing the stable terminology-loader code (e.g. `TERM_CONCEPTMAP_MALFORMED`),
+    never the map's bytes.
+  - New **`CLI_MAP_INVALID`** diagnostic code. New programmatic exports: `convertCommand`,
+    `convertOutcome`, `mapCodesCommand`. New runtime dependencies (ADR 0023): **`@cosyte/transform`**
+    (`e6c4531`, v0.0.0) and **`@cosyte/terminology`** (`e5ed368`, v0.0.1) as **hard, first-party,
+    lazy-loaded** deps: vendored as `pnpm pack` tarballs under `vendor/` until PUB-FLIP
+    (`pnpm vendor:refresh`; umbrella ADR 0008). The umbrella `verify-policy.json` cap on `cli` runtime
+    deps was raised **2 → 4**; third-party CLI-core runtime deps stay **zero** (both siblings are
+    lazy-loaded per command, so the `parse` fast path never loads them).
+  - **ADR `0023`**: wire `@cosyte/transform` + `@cosyte/terminology`; the deliberate 2 → 4 cap raise
+    (amends ADR 0021).
+- **Phase 3: `validate` / `inspect` / `fmt`.** Three commands over the two wired parsers
+  (HL7 v2 + FHIR R4), each a thin wrapper that re-implements no library logic.
+  - **`validate <file|-> [--profile] [--json] [--quiet]`**: parse + run the wrapped parser's own
+    validation surface, with the **verdict in the exit code**: `0` valid, **`1` invalid** (parseable
+    but non-conformant), `65` unparseable, `66` no input, `2` usage. The load-bearing rule: a
+    validation failure is **never** exit `0`; "unparseable" (`65`) is a distinct signal from "parsed
+    but invalid" (`1`). Findings are **value-free**: a stable code, a severity, and a positional
+    locator (a FHIRPath, or an HL7 segment/field index), on stderr by default, or as value-free JSON
+    on stdout under `--json`; `--quiet` makes the exit code the whole signal. The CLI invents **no**
+    verdict: FHIR validity is `@cosyte/fhir`'s `validateResource().valid` (plus any error-severity
+    read issue); HL7 validity is "parseable" (its warnings are non-fatal by the library's design:
+    surfaced, never failing). **`--profile` is gated** to an honest `CLI_NOT_IMPLEMENTED` (exit `69`):
+    the CLI bundles no profiles yet, so it never fakes or silently drops a profile verdict.
+  - **`inspect <file|-> [--json]`**: a **value-free structural summary**: HL7 message type, version,
+    per-segment-type counts, and a warning count; FHIR `resourceType`, Bundle entry counts by type, and
+    a read-issue count. Counts and structural type codes only, never a field value.
+  - **`fmt <file|->`**: **canonical re-serialization** via the wrapped library's spec-clean
+    serializer (`Hl7Message.toString()` / `serializeResource`); its stdout **is** the data channel. An
+    unparseable input is a data error (`65`) with **no partial emit**.
+  - New `EXIT.INVALID` (`1`): the `validate` verdict code (the exit-code contract is now
+    `0/1/2/65/66/69/70`). All four commands share one input + format front door (`core/resolveInput`)
+    and one value-free parser-failure boundary (`core/wrap`), so the value-free-by-default posture and
+    the `--unsafe-show-values` chokepoint apply uniformly; `parse` was refactored onto the shared
+    helpers (behavior-preserving). New programmatic exports: `validateCommand`, `inspectCommand`,
+    `fmtCommand`, `resolveInput`, `parseFailureResult`, `formatHl7Position`, `errorResult`. No new
+    runtime dependencies: stays within the cap of 2.
+- **Phase 2: PHI posture hardened + `redact`/`deid` + `--unsafe-show-values`.**
+  - **`--unsafe-show-values`**: a global, opt-in, PHI-exposing flag, resolved once and order-
+    independently and funnelled through a **single chokepoint** (`core/phi.ts`), so the "a value
+    reaches a secondary surface **iff** the flag is set" property holds in one place. Off by default;
+    with it set, a `CLI_PARSE_FAILED` diagnostic appends a bounded, single-line excerpt of the
+    offending input. Every other surface stays value-free, and a successful parse still puts values
+    only on the stdout data channel.
+  - **`redact` / `deid` (`<file|->`, `--format`)**: the de-identification command, shipped as an
+    **honest, typed `CLI_NOT_IMPLEMENTED`** (new exit code `69`, `EX_UNAVAILABLE`). It is **gated on
+    `@cosyte/deid`** (unpublished, `DEID-1` in flight), **never reads the input**, and never emits a
+    partial Safe-Harbor scrub presented as de-identified. A built-in redactor is **deliberately
+    withheld**: a partial scrub over only the obvious PHI loci would leave PHI behind and present a
+    false-safety impression (the cardinal hazard). It delegates to `@cosyte/deid` via a documented
+    seam (`core/deid.ts`) when that library ships and is vetted.
+  - **Never a PHI temp file / never a file log**: proven by test (no command creates a file in the
+    working directory) and by design (commands return a `RunResult`; only the thin `bin` writes to
+    process streams).
+  - New `CLI_NOT_IMPLEMENTED` diagnostic code and `EXIT.UNAVAILABLE` (`69`); new programmatic exports
+    (`PhiPosture`, `VALUE_FREE`/`SHOW_VALUES`, `extractPhiPosture`, `unsafeInputSuffix`, `deidStatus`,
+    `redactCommand`).
+- **Phase 1: the `cosyte parse` foundation.** Reshaped the scaffold from a library skeleton into a
+  **`bin` package**: `package.json#bin` maps `cosyte` → `dist/bin/cosyte.mjs` (a shebang entry over a
+  testable `core`), argument-parsed with Node's built-in `util.parseArgs` + a hand-rolled subcommand
+  dispatcher (**no third-party CLI framework**).
+- **`cosyte parse <file|->`**: reads a file argument or stdin (`-`); **autodetects the format by
+  content** (HL7 v2 `MSH` framing, FHIR JSON `resourceType`): conservative and fail-safe (a confident
+  single match parses; ambiguity/no-match is a data error asking for `--format`, never a guess); routes
+  to the wrapped parser (**lazy-loaded** per format); emits the parsed model as **typed JSON on
+  stdout**. Flags: `--format`, `--json`, `--quiet`, `--no-color`.
+- **The exit-code contract** (`sysexits.h`-grounded, documented, tested): `0` success · `2` usage ·
+  `65` data/parse error (`EX_DATAERR`) · `66` no input (`EX_NOINPUT`) · `70` internal (`EX_SOFTWARE`).
+  The CLI never exits `0` on input it could not handle.
+- **Value-free diagnostic channel** with stable `CLI_*` codes (`CLI_FORMAT_UNDETECTED`,
+  `CLI_FORMAT_AMBIGUOUS`, `CLI_FORMAT_UNSUPPORTED`, `CLI_NO_INPUT`, `CLI_EMPTY_INPUT`,
+  `CLI_PARSE_FAILED`, `CLI_USAGE`, `CLI_INTERNAL`). **stdout is the data channel; every stderr line is
+  value-free**: code + position only, never a field value. No temp files, no file logging.
+- **Programmatic `core` API** (the `.` subpath): `detectFormat` / `classifyCandidates` /
+  `detectionError`, `EXIT`, `CLI_CODES` / `CliError`, `run`, `parseCommand`, `VERSION`.
+- **Runtime dependencies (ADR 0021):** `@cosyte/hl7` (`46d50eb`, v0.0.1) and `@cosyte/fhir` (`7a099b2`,
+  v0.0.0) as **hard, first-party** deps (an `npx` bin cannot peer-depend) vendored as `pnpm pack`
+  tarballs under `vendor/` until PUB-FLIP (`pnpm vendor:refresh`; umbrella ADR 0008). Capped at **2**
+  by the umbrella `verify-policy.json`; third-party CLI-core runtime deps stay **zero**.
+- **ADRs:** `0021` (developer-tooling tier is a `bin` that hard-depends on first-party siblings;
+  third-party runtime deps minimized) and `0022` (one repo, two bins: the CLI and the future
+  `cosyte-mcp` MCP server over one core; the web playground is out of scope).
+
+### Changed
+
+- **The documented per-(format, operation) support matrix now states its negatives in words.** In
+  `docs-content/limitations.md` the table used a bare `U+2014` **as a cell value meaning "not
+  supported"**. The em-dash sweep below rewrote it as punctuation, so `dicom` `fmt`, `mllp` `fmt` and
+  `mllp` `validate` rendered as a stray colon: **"support absent" silently became "support unstated"**,
+  on the page whose whole job is honest capability disclosure, in a form a reader would read as a
+  rendering artifact rather than as a claim. Caught by the conformance refuter, not by CI, and nothing
+  in this repo's CI could have caught it (`test/docs-content.test.ts` only executes runnable `ts`
+  blocks, and Prettier's glob does not cover `docs-content/`). Those three cells now read
+  `not supported`. **The support facts are unchanged; the page now says them.** Before sweeping any
+  repo for this character, find the places it is a value rather than punctuation and convert those by
+  hand, to a word, first.
+
+- **No cosyte surface in this repo uses an em dash any more, and a CI gate keeps it that way.** The
+  brand rule (`knowledgebase/06-brand/voice-and-tone.md`, "No em dashes. Ever.") bans `U+2014`
+  outright and names commit messages explicitly. Measured byte-level over **all 124 tracked files**,
+  not over markdown alone: **659 occurrences across 87 files**, all as the literal character and none
+  in an encoded form. **61 of the 87 are not markdown** (26 are), and one is `package.json`, whose
+  `description` is published to npm and rendered on the package page. Every occurrence was rewritten
+  in place with a period, a colon, a comma, or parentheses, never re-encoded. Consumer-visible text
+  that changed wording: the npm description, `README.md`, `docs-content/`, `cosyte --help`, the
+  generated `bash`/`zsh`/`fish` completion scripts, and the `redact`/`deid` and reserved `--profile`
+  unavailability messages. **No stable code, exit code, flag name, or JSON field changed**, so nothing
+  branching on an exit code or parsing `--json` is affected. Commit subjects already on `main` are
+  left alone: the message half runs on `pull_request` only, and history is not rewritten.
+  - **The gate.** `scripts/check-no-emdash.sh` (`pnpm check:no-emdash`) plus
+    `.github/workflows/no-emdash.yml` scan both halves the rule covers: every tracked file, and the
+    pull request title, body, and commit messages, on the non-default `edited` trigger so retitling a
+    pull request re-checks it. The new `no-emdash` check-run context is required by the
+    `ci-required-checks` ruleset.
+  - **Binary handling, which is why this repo does not run the text-only variant its siblings run.**
+    `cli` tracks eleven binaries (the ten `vendor/cosyte-*.tgz` packed sibling dependencies and
+    `test/__fixtures__/sample.dcm`), so the script partitions on an explicit NUL-byte rule rather than
+    on `grep -I`'s heuristic, which would silently skip a genuine text file with a broken encoding.
+    The reason is measured rather than precautionary: `vendor/cosyte-hl7-0.0.0.tgz` **already
+    contains the byte sequence `E2 80 94`** by compression coincidence, so a text-only scan reds on it
+    today, naming a compressed byte stream nobody wrote and offering no way to fix it.
+  - **Disclosed limits, in the script header rather than left implicit.** A tracked _text_ file
+    holding a NUL byte is exempt and its em dash would be missed (there is none today; the excluded
+    count on the OK line is the tell). Encoded-form matching is literal, so lowercase `%e2%80%94`, a
+    capital-X `&#X2014;`, and a semicolon-less `&#x2014` pass. The scan reads file contents, never
+    file names.
+
+- **The published type declarations no longer carry internal project bookkeeping.** `dist/index.d.ts`
+  and `dist/mcp.d.ts` (and their `.d.cts` twins) are compiled from the JSDoc on every exported symbol,
+  and that JSDoc was citing item identifiers (`CLI-6`), ADR numbers (`ADR 0018`, `0021`, `0022`,
+  `0025`), the meta-repo roadmap in prose and by path (`cli roadmap §7`,
+  `operations/roadmaps/cli.md`), and phase language (`§Phase 4`, `Phase-5`, "in a later phase"). All
+  of it rendered on hover for anyone who installed the package. **Measured on `62fba77` with the rule
+  set that ships alongside: 61 occurrences across 23 tracked `src/` files, producing 56 across the
+  three declaration files a consumer receives (43 in `dist/index.d.ts`, 12 in `dist/mcp.d.ts` and 1
+  in the shared `dist/io-*.d.ts` chunk both entries import), each mirrored in its `.d.cts` twin. Now
+  0 on every one of them.** (The shared chunk is easy to miss and was missed once here: a count that
+  scans only the named entry points under-reports.) Every removal is a cut, not a rewrite: the
+  surrounding guarantees (value-free stderr, the never-a-fake `CLI_FORMAT_UNSUPPORTED`, the gated
+  `redact`, the exit-code contract) are worded exactly as strongly as before. Internal traceability
+  stays where the convention puts it: this file, the changesets, the commits and the roadmap.
+- **A dependency-budget figure left `src/core/deid.ts` too.** The module said wiring `@cosyte/deid`
+  "would breach the CLI's runtime-dep cap (2)". Only the number was stale: the cap has been 4 since
+  `convert`/`map-codes` landed, and the constraint itself still holds, because the package declares
+  exactly 4 hard runtime dependencies and a fifth would indeed breach it. The clause went because a
+  dependency-budget figure is internal bookkeeping a consumer cannot act on, not because the
+  constraint lapsed. The reasons that actually ground the refusal to ship a built-in redactor are
+  untouched: `@cosyte/deid` is unpublished, the wrapped parsers expose no de-identification API, and
+  a partial scrub would present a false-safety impression.
+- **`CosyteFormat`'s documentation no longer understates autodetection.** It read as though content
+  detection recognised only HL7 v2 and FHIR, with the other six accepted by `--format` but "not yet
+  wired", which has not been true since all eight formats gained signatures. The stale sentence is
+  removed rather than restated.
+- **A gate now enforces the public-surface rule, which is why the class stops regrowing.**
+  `scripts/check-no-internal-refs.sh` (`pnpm check:no-internal-refs`, on the `verify.sh cli` ladder)
+  plus `.github/workflows/no-internal-refs.yml` port the shape of `hl7`'s gate
+  ([hl7#62](https://github.com/cosyte/hl7/pull/62), [hl7#64](https://github.com/cosyte/hl7/pull/64))
+  and `ncpdp`'s ([ncpdp#36](https://github.com/cosyte/ncpdp/pull/36)) rather than the file. Four
+  passes: the public markdown surface line by line and paragraph-joined, the npm metadata, `src/`
+  doc comments, and `src/` string literals (the pass that would have caught the two identifiers this
+  package printed to a user's terminal). Seven rules. Re-derived for this repo: the scan surface, a
+  standards-designation exclusion list covering **all eight** formats (this is the package where
+  `HL7-V2`, `FHIR-R4`, `DICOM-SR`, `NCPDP-SCRIPT`, `X12-837P`, `CCDA-R2.1`, `MSH-2`, `NM1-03`,
+  `439-E4` and `ICD-10-CM` are live at once, so the `WORD-N` trap is at its widest), and a seventh
+  rule no sibling has, a **prose roadmap citation**, which was 30 of the 61 and which `hl7`'s
+  path-keyed rule cannot see. Both self-test halves run on every invocation: positive samples prove
+  each rule still matches, negative samples prove none has been widened into the `WORD-N` shape that
+  would delete the reference material the CLI's docs exist to provide. `CHANGELOG.md` is excluded on
+  purpose, as it is in `hl7` and `ncpdp`: it ships inside the npm tarball, yet the convention names it
+  as one of the places identifiers belong. That contradiction is ecosystem-wide, and it is recorded
+  here rather than settled by one repo.
+- **`redact`/`deid` no longer names an internal tracking identifier on any consumer surface.** The
+  `CLI_NOT_IMPLEMENTED` text printed when de-identification is unavailable carried an internal work
+  item that means nothing to anyone running the command, and the same identifier reached the
+  published type declarations (`dist/index.d.ts` / `dist/index.d.cts`), where it surfaces in editor
+  tooltips. Both now state only the consumer-observable fact: the command delegates to
+  `@cosyte/deid`, which is unpublished, and the CLI ships no built-in redactor because a partial
+  scrub would present a false-safety impression. The stable `CLI_NOT_IMPLEMENTED` code and the exit
+  `69` are unchanged.
+- **`CLI_PARSER_UNAVAILABLE`'s message no longer cites an internal decision record.** The error
+  raised when an optional per-format parser is not installed pointed at an ADR number, which is
+  meaningless to a caller; it now just names the package to install. The stable
+  `CLI_PARSER_UNAVAILABLE` code and the exit `69` are unchanged. The same sweep removed the
+  remaining roadmap-phase language from `README.md` and `docs-content/troubleshooting.md`.
+- **The CI checks are now binding on `main`.** `ci / verify (22, ubuntu-latest)`,
+  `ci / verify (24, ubuntu-latest)`, `ci / actionlint` and `codeql / analyze (javascript-typescript)`
+  are required status checks, each pinned to the `github-actions` app, alongside branch deletion and
+  force-push protection. They were advisory before: a red check could not stop a merge. Dependabot
+  now watches the npm and GitHub Actions dependency surfaces weekly, which nothing did previously.
+- **Reshaped the package from the parser-library scaffold to a `bin` package.** Removed the archetype
+  stubs (`parseCli`, `WARNING_CODES`, `FATAL_CODES`); replaced the library `src/index.ts` and the
+  round-trip property test with the command tree, the programmatic `core` API, and command-contract /
+  autodetection / PHI-leak / equivalence tests. Rewrote `docs-content/` and `README.md` for the CLI.
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+- **README + guides now describe the shipped Phase-3 command surface.** The `README.md` and
+  `docs-content/guides-overview.md` "Status" blurbs read as a Phase-1-forward roadmap ("Phase 1 ships
+  `parse`…"); they now state the current surface directly (`parse` / `validate` / `inspect` / `fmt`
+  and the gated `redact`/`deid`) over the two wired parsers (HL7 v2 + FHIR R4). The pre-alpha,
+  not-yet-published-to-npm status is unchanged (accurate), and the `npx`/`npm install -g` examples now
+  carry a "not on npm yet" caveat (docs-only; README-ORG-SWEEP).
+- **`phi-scan` now scans the real fixture directory.** The scanner's fixture root pointed at a
+  nonexistent `test/fixtures/`; it now walks `test/__fixtures__/` (and the same path in the staged
+  filter), so the PHI commit-gate actually covers the CLI's synthetic fixtures.
+
+### Security
+
+[Unreleased]: https://github.com/cosyte/cli/commits/main

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cosyte
+
+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.

package/README.md

@@ -0,0 +1,265 @@
+# @cosyte/cli
+
+> The **cosyte CLI**: a PHI-safe developer front door over the `@cosyte/*` healthcare parsers.
+
+`@cosyte/cli` is a **`bin` package**: its primary artifact is the `cosyte` command on your `PATH`. Pipe
+a raw message from a hospital feed into the terminal and get typed, structured JSON back in one line,
+without writing code, without reading the spec, and **without ever being handed a confident wrong value
+or a silent success on a malformed message**.
+
+```bash
+cat adt.hl7 | cosyte parse -
+```
+
+It is a thin, honest skin over libraries that already own correctness ([`@cosyte/hl7`](https://github.com/cosyte/hl7),
+[`@cosyte/fhir`](https://github.com/cosyte/fhir), [`@cosyte/transform`](https://github.com/cosyte/transform),
+[`@cosyte/terminology`](https://github.com/cosyte/terminology)): it routes, reads, and shapes output,
+and owns two disciplines of its own: a documented **exit-code contract** and a **value-free
+diagnostic** posture.
+
+> **Status:** pre-alpha (`0.0.x`), **not yet published to npm**. The `cosyte` command wraps **all eight
+> cosyte formats** (**HL7 v2**, **FHIR R4**, **X12**, **ASTM**, **NCPDP SCRIPT**, **C-CDA**, **DICOM**,
+> and **MLLP**) plus the `@cosyte/transform` and `@cosyte/terminology` higher-layer libraries, with
+> conservative content-format autodetection and a documented exit-code contract:
+>
+> - **`parse`**: autodetect the format and print the parsed model as typed JSON on stdout. Multi-record
+>   inputs (an **MLLP** stream, or any input under **`--ndjson`**) stream as **NDJSON** with per-record
+>   isolation.
+> - **`validate`**: parse, then run the wrapped parser's own validation surface, with the **verdict in
+>   the exit code** (`0` valid · `1` invalid · `65` unparseable); findings are value-free.
+> - **`inspect`**: a value-free structural summary (type/classification codes + structural counts).
+> - **`fmt`**: canonical re-serialization through the library's spec-clean serializer; no partial emit
+>   on unparseable input.
+> - **`convert`**: HL7 v2 → FHIR R4 via `@cosyte/transform`; the converted `Bundle` on stdout, value-
+>   free issues on stderr, and a non-zero exit on an error-severity conversion issue.
+> - **`map-codes`**: translate a code through a BYO FHIR ConceptMap via `@cosyte/terminology`; the
+>   target coding(s) on stdout, or a value-free unmapped signal + exit `1`.
+> - **`redact` / `deid`**: gated to an honest `CLI_NOT_IMPLEMENTED` (exit `69`) until `@cosyte/deid`
+>   ships; it never reads the input and never emits a partial scrub dressed up as de-identified.
+> - **`completion <bash|zsh|fish>`**: print a static shell completion script.
+>
+> **Support is honest per (format, operation)**: not every parser faithfully supports every command, so
+> the deferred cells (DICOM `parse`/`fmt`: binary model; C-CDA `parse`: XML is the canonical `fmt`
+> surface; MLLP `fmt`/`validate`) are a value-free `CLI_FORMAT_UNSUPPORTED`, never a fake. PHI discipline
+> runs throughout: value-free by default across every diagnostic, the loud opt-in `--unsafe-show-values`
+> as the single door to a value on a secondary surface, and never a temp file with PHI. An **MCP server**
+> (`cosyte-mcp`) exposes the same core to an LLM/agent as callable tools.
+>
+> The CLI is **feature-complete and release-hardened**: an argv+stdin+MCP fuzz
+> gate, an exit-code golden matrix, a built-package smoke of both bins, and a clean `npm publish`
+> dry-run. What remains is the two standing founder stops (flipping the repo public and the real
+> `npm publish`) plus swapping the vendored sibling deps for real `@cosyte/*` npm ranges at that flip.
+> See [RELEASING.md](./RELEASING.md).
+
+## Run it
+
+> Not on npm yet. The commands below are how you'll install and run it **once it's published**.
+> Until then, run it from a local checkout (`pnpm build`, then invoke `dist/bin/cosyte.mjs`).
+
+```bash
+npx @cosyte/cli parse message.hl7   # no install; format autodetected → HL7 v2
+npm install -g @cosyte/cli          # or put `cosyte` on your PATH
+cosyte --help
+```
+
+## `cosyte parse`
+
+Read a file (or stdin via `-`), autodetect the format by content, and print the parsed model as typed
+JSON on stdout:
+
+```bash
+cosyte parse message.hl7            # → { "format": "hl7", "model": …, "warnings": [] }
+cat patient.json | cosyte parse -   # from a pipeline
+cosyte parse --json message.hl7 | jq '.model'   # compact machine output
+cosyte parse --format hl7 msg.txt   # override autodetection
+cosyte parse stream.mllp             # MLLP frames → one NDJSON record per frame
+cosyte parse bulk.ndjson --ndjson    # one FHIR resource per line → NDJSON records
+```
+
+Autodetection is **conservative**: a confident single match parses; ambiguity or no match is a typed
+data error asking for `--format`, **never a guessed parser**. `--format` accepts `hl7 | fhir | x12 |
+astm | ncpdp | ccda | dicom | mllp`.
+
+**Streaming / multi-message.** A single message prints one JSON envelope. A multi-record input (an
+**MLLP** stream, one record per frame, or any input under **`--ndjson`**, one record per non-empty
+line) streams as **NDJSON**, one `{ record, format, model, warnings }` line each, with per-record
+isolation: a record that fails to parse becomes a value-free `{ record, error }` line and the stream
+continues; the overall exit is a data error (`65`) if any record failed.
+
+Support is honest **per (format, operation)**: `x12`/`astm`/`ncpdp` support all of parse/inspect/fmt/
+validate; `ccda` supports inspect/fmt/validate (parse deferred); `dicom` supports inspect/validate
+(parse/fmt deferred); `mllp` supports parse/inspect. A deferred cell is a value-free
+`CLI_FORMAT_UNSUPPORTED`, never a fake result.
+
+## `cosyte validate`
+
+Parse the input and run the wrapped parser's own validation surface, with the **verdict in the exit
+code**, so it drops straight into a CI gate:
+
+```bash
+cosyte validate message.hl7            # exit 0 valid · 1 invalid · 65 unparseable
+cosyte validate patient.json --json    # value-free { format, valid, findings } on stdout
+cosyte validate patient.json --quiet   # no output: the exit code is the whole signal
+```
+
+Findings are **value-free**: a stable code, a severity, and a positional locator (a FHIRPath, or an
+HL7 segment/field index), never a field value. The verdict is the wrapped library's, never invented:
+FHIR validity is `@cosyte/fhir`'s `validateResource()`; an HL7 message is valid when it parses (its
+warnings are non-fatal deviations, surfaced but never failing). `--profile` is reserved: the CLI
+bundles no profiles yet, so it reports an honest "unavailable" (exit `69`) rather than fake a verdict.
+
+The load-bearing rule: a validation failure is **never exit 0**, and "unparseable" (`65`) is a distinct
+signal from "parsed, but invalid" (`1`).
+
+## `cosyte inspect`
+
+A value-free structural summary, the "what shape is this?" answer, with no field value:
+
+```bash
+cosyte inspect message.hl7    # message type, version, per-segment counts, warning count
+cosyte inspect bundle.json --json
+```
+
+## `cosyte fmt`
+
+Canonically re-serialize through the wrapped library's spec-clean serializer (HL7 CR-separated;
+FHIR canonical JSON, decimals byte-exact). Its stdout **is** the data channel; an unparseable input is
+a data error with **no partial emit**:
+
+```bash
+cat messy.json | cosyte fmt -   # → canonical FHIR JSON on stdout
+cosyte fmt message.hl7          # → spec-clean HL7
+```
+
+## `cosyte convert`
+
+Convert an **HL7 v2** message to **FHIR R4** via [`@cosyte/transform`](https://github.com/cosyte/transform).
+The converted FHIR message `Bundle` is your explicit request, so it goes to **stdout**; the
+conversion's value-free issues (a v2 index → FHIRPath locator + a stable code, never a field value) go
+to stderr:
+
+```bash
+cosyte convert adt.hl7 --to fhir            # → a FHIR message Bundle on stdout
+cat oru.hl7 | cosyte convert - --to fhir | jq '.entry[].resource.resourceType'
+cosyte convert adt.hl7 --to fhir --json     # { format, bundle, findings } on stdout
+cosyte convert adt.hl7 --to fhir --quiet    # bundle only; the exit code carries the outcome
+```
+
+`--to fhir` is required (the only target today). The CLI adds no mapping of its own. The FHIR is
+`@cosyte/transform`'s, faithfully surfaced. The load-bearing rule mirrors `validate`: an
+**error-severity** conversion issue exits **`1`**, never `0`. A non-HL7 input (e.g. a FHIR document) is
+a data error (`65`), never a fake conversion.
+
+## `cosyte map-codes`
+
+Translate a single code through a **bring-your-own FHIR ConceptMap** via
+[`@cosyte/terminology`](https://github.com/cosyte/terminology) (`$translate`). A ConceptMap and a code
+are reference data, not PHI, so the translation result is your explicit request on **stdout**:
+
+```bash
+cosyte map-codes gender.conceptmap.json \
+  --system http://hl7.org/fhir/administrative-gender --code male   # → the target coding(s), exit 0
+cat cm.json | cosyte map-codes - --code female --json              # compact { source, result }
+```
+
+The CLI ships no terminology content and never fabricates a target: a **match** is exit `0`; an
+**unmapped** code is the value-free `TERM_TRANSLATE_UNMAPPED` signal + exit `1`; a map that is not
+valid JSON or not a loadable ConceptMap is a `CLI_MAP_INVALID` data error (`65`).
+
+## The exit-code contract
+
+Every command is safe to branch on in CI. The exit code carries the outcome (`sysexits.h`):
+
+| Code | Meaning                                                    |
+| ---- | ---------------------------------------------------------- |
+| `0`  | success / **valid** (`validate`)                           |
+| `1`  | **invalid**: `validate` found a parseable-but-bad message  |
+| `2`  | usage error (unknown flag, missing argument)               |
+| `65` | data error (unparseable input, or format undetected)       |
+| `66` | no input (missing/unreadable file)                         |
+| `69` | unavailable (a capability is not yet built, e.g. `redact`) |
+| `70` | internal error (a bug)                                     |
+
+The load-bearing rule: the CLI **never prints a reassuring line and exits `0`** on input it could not
+handle, or on an invalid message.
+
+## PHI posture
+
+A CLI operates on real files a developer points at. So the channels are split: **stdout is the data
+channel** (`parse` prints the parsed model there because that is your explicit request) while **every
+diagnostic on stderr is value-free** (a stable code, a position, a file path, never a name, DOB, MRN,
+or field value). The CLI writes no temp files and logs to no file.
+
+### `--unsafe-show-values`
+
+Value-free-by-default is the whole point, but when you are debugging a rejected message locally, you
+sometimes need to see the bytes. `--unsafe-show-values` is the **single, loud, opt-in door**: with it
+set, a `CLI_PARSE_FAILED` diagnostic appends a bounded excerpt of the offending input. It is off by
+default, it is **PHI-exposing** (the name carries the warning), and it is the _only_ configuration
+under which a value can reach a secondary surface. A successful parse still puts values only on
+stdout, never on stderr.
+
+```bash
+cosyte parse broken.hl7 --format hl7                       # value-free: a code + position only
+cosyte parse broken.hl7 --format hl7 --unsafe-show-values  # appends a bounded input excerpt (PHI!)
+```
+
+## `cosyte redact` / `cosyte deid`
+
+De-identification is the one operation whose _job_ is to strip PHI. It is **not implemented yet, on
+purpose.** It belongs to [`@cosyte/deid`](https://github.com/cosyte/deid), which is not published, and
+the wrapped parsers expose no de-identification API. A built-in "minimal Safe-Harbor" pass over only
+the obvious fields would leave PHI behind and _look_ de-identified while silently under-redacting: the
+exact false-safety hazard `redact` exists to avoid. So `cosyte redact <file>` is an honest, typed
+`CLI_NOT_IMPLEMENTED` (exit `69`, `EX_UNAVAILABLE`) that **never reads your input** and **never emits a
+partial scrub dressed up as safe**. It will produce a real de-identified copy once `@cosyte/deid`
+ships and is vetted.
+
+## `cosyte completion`
+
+Print a shell completion script generated from the command tree, and source it:
+
+```bash
+source <(cosyte completion bash)     # bash
+source <(cosyte completion zsh)      # zsh
+cosyte completion fish | source      # fish
+```
+
+## The MCP server (agent front door)
+
+The same `core` is exposed to an **LLM/agent** as a [Model Context Protocol](https://modelcontextprotocol.io)
+server: the second adapter over one codebase (the terminal is the first). It is a **local stdio
+subprocess**, not a hosted endpoint. Register it in an MCP client's config:
+
+```json
+{
+  "mcpServers": {
+    "cosyte": { "command": "npx", "args": ["-y", "@cosyte/cli", "mcp"] }
+  }
+}
+```
+
+`cosyte mcp` and the standalone `cosyte-mcp` bin both start the stdio server. It exposes four tools
+(`parse`, `validate`, `inspect`, `convert`), each calling the same command the terminal runs, so the CLI
+and the agent get identical results. The PHI posture is inherited and hardened: there is **no
+`--unsafe-show-values` door on the agent surface**, a tool _result_ carries the requested data, and a
+tool _error_ carries only value-free diagnostics (a stable code + position, never an input value). A
+parsed-but-invalid `validate` is a **successful** call reporting the verdict, not a tool error.
+
+The MCP SDK (`@modelcontextprotocol/sdk`) is the CLI's only third-party runtime dependency; it is
+declared **optional** and loaded only on the MCP path, so a `cosyte parse` invocation never pulls it and
+the core works with the SDK absent. The server surface is importable via the `@cosyte/cli/mcp` subpath
+(`createMcpServer`, `startStdioServer`, `dispatchTool`, `TOOL_DEFS`).
+
+## Programmatic API
+
+The same `core` is importable (the `.` subpath): `detectFormat`, the `EXIT` map (now including
+`EXIT.INVALID`), the `CLI_CODES` diagnostic registry, `resolveInput`, `run`, and each command
+(`parseCommand`, `validateCommand`, `inspectCommand`, `fmtCommand`, `convertCommand`, `mapCodesCommand`,
+`redactCommand`, plus `convertOutcome` for the conversion verdict). The **`./mcp` subpath** exports the
+agent adapter (`createMcpServer`, `startStdioServer`, `dispatchTool`, `TOOL_DEFS`). See the docs for the
+full surface.
+
+## License
+
+MIT © Cosyte