@cosyte/cli 0.0.5 → 0.1.0

package/README.md

@@ -48,19 +48,17 @@ releases, not a fault in any command.
 sibling packages are now declared as real npm ranges, and the resulting tarball has been installed from
 outside this repository and exercised, which is the check a `npm publish --dry-run` cannot perform.
 
-**One dependency could not be made real, and it costs you FHIR support.** `@cosyte/fhir` is not on the
-npm registry, so it cannot be a dependency of this package at all; `@cosyte/transform` is on npm but
-requires it, so npm skips that too. In an installed copy:
-
-- FHIR `parse` / `inspect` / `fmt` / `validate` and the `convert` command report a value-free
-  `CLI_PARSER_UNAVAILABLE` and exit `69`. They never guess, and they never blame your input.
-- HL7 v2, `map-codes`, and the six breadth formats (X12, C-CDA, DICOM, NCPDP, ASTM, MLLP) all work.
-
-To use the FHIR commands today, run the CLI from a source checkout (`pnpm install && pnpm build`, then
-invoke `dist/bin/cosyte.mjs`), where the FHIR library is supplied locally.
-
-> **Status:** pre-alpha (`0.0.x`). `0.0.1` and `0.0.2` are on npm and **cannot be installed** (see
-> above); a later version fixes that. The `cosyte` command wraps **all eight
+**FHIR support arrives through a peer, not a declared dependency.** `@cosyte/fhir` is not in this
+package's manifest. `npm install` brings it in as the peer dependency of `@cosyte/transform`, one of
+this package's optional dependencies, and the FHIR `parse` / `inspect` / `fmt` / `validate` commands
+and `convert` use that copy. If your package manager skips optional dependencies or does not install
+peers, a command whose library is missing reports a value-free `CLI_PARSER_UNAVAILABLE` and exits
+`69`: it never guesses, and it never blames your input. HL7 v2 and `map-codes` run on the two hard
+dependencies, `@cosyte/hl7` and `@cosyte/terminology`, and always work.
+
+> **Status:** `0.1`. While the package is below 1.0, a breaking change ships in a minor version and is
+> called out in the changelog. `0.0.1` and `0.0.2` are on npm and **cannot be installed** (see above);
+> every later version installs. 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:
@@ -77,8 +75,9 @@ invoke `dist/bin/cosyte.mjs`), where the FHIR library is supplied locally.
 >   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 the CLI wires
->   `@cosyte/deid`; it never reads the input and never emits a partial scrub dressed up as de-identified.
+> - **`redact` / `deid`**: a de-identified copy on stdout for `ccda`, `fhir`, `hl7`, `x12`, delegated
+>   whole to `@cosyte/deid`, with that library's value-free manifest on stderr; every other format is a
+>   typed refusal and it 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
@@ -94,20 +93,22 @@ invoke `dist/bin/cosyte.mjs`), where the FHIR library is supplied locally.
 > described above, which is why `0.0.1` and `0.0.2` published green and still cannot be installed: a
 > dry-run builds the tarball but never resolves it from a registry. **That swap has now been made**,
 > and installing the packed tarball from outside the repository is a release step in its own right.
-> `@cosyte/fhir` is the one dependency it could not cover, which is why FHIR support is absent from an
-> installed copy rather than merely deferred. See [RELEASING.md](./RELEASING.md).
+> `@cosyte/fhir` reaches an installed copy as a peer of `@cosyte/transform` (see above). See
+> [RELEASING.md](./RELEASING.md).
 
 ## Run it
 
-> **These commands do not work yet, and the reason is now only that no fixed version has shipped.**
-> The newest version on npm is `0.0.2`, and it is one of the two that cannot be installed. The
-> packaging defect is fixed in this repository and proven by installing the packed tarball outside it,
-> but a published version is immutable, so the fix reaches you only in the next release. Until then,
-> run it from a source checkout: `pnpm install && pnpm build`, then invoke `dist/bin/cosyte.mjs`.
+Requires Node `>=22.0.0 <26.0.0`. This block runs as-is in an empty directory: it installs the CLI,
+writes a short synthetic HL7 v2 message, and reads it back.
 
 ```bash
 npm install -g @cosyte/cli          # put `cosyte` on your PATH
-cosyte parse message.hl7            # format autodetected → HL7 v2
+
+# A synthetic ADT^A01 admit. HL7 v2 ends every segment with a carriage return (\r).
+printf 'MSH|^~\\&|SENDINGAPP|SENDINGFAC|RECEIVINGAPP|RECEIVINGFAC|20240101120000||ADT^A01|MSG00001|P|2.5\rEVN|A01|20240101120000\rPID|1||MRN-000123^^^HOSP^MR||ZZSENTINELLAST^ZZSENTINELFIRST^M||19800101|M\rPV1|1|I|WARD^101^A\r' > message.hl7
+
+cosyte parse message.hl7            # format autodetected → HL7 v2, typed JSON on stdout
+cosyte inspect message.hl7          # a value-free summary: type, version, segment counts
 ```
 
 Or without installing, using `npx`:
@@ -146,7 +147,15 @@ astm | ncpdp | ccda | dicom | mllp`.
 **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.
+continues; the overall exit is a data error (`65`) if any record failed. Each line is written **as
+its record is parsed**, before the rest of the input has been read, so a batch pipes straight into
+the next process.
+
+**Input size.** `parse` reads at most **67108864 bytes (64 MiB)** per invocation, the number
+`cosyte --help` prints. A larger input is a value-free `CLI_INPUT_TOO_LARGE` refusal naming that
+limit, with the data-error exit code (`65`) and never the internal-error code: split the input and
+re-run. Since records are emitted as they are parsed, a refusal can land after some records have
+already reached stdout; the exit code, not the output, says the run did not complete.
 
 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
@@ -230,20 +239,39 @@ 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)                                     |
+Every command is safe to branch on in CI. The exit code carries the outcome. `0` is the conventional
+success status and the codes from `65` up are the values the Unix `sysexits.h` header assigns to the
+conditions they name; `1` and `2` are this CLI's own values, because that header defines no constant
+for either:
+
+| Code | Meaning                                                                                                             |
+| ---- | ------------------------------------------------------------------------------------------------------------------- |
+| `0`  | success / **valid** (`validate`)                                                                                    |
+| `1`  | **invalid**: `validate` found a parseable-but-bad message, or `redact` could not de-identify every locus            |
+| `2`  | usage error (unknown flag, missing argument)                                                                        |
+| `65` | data error (unparseable input, format undetected, or input past the size limit)                                     |
+| `66` | no input (missing/unreadable file)                                                                                  |
+| `69` | unavailable (a capability is not wired for this input, e.g. `redact` on a format `@cosyte/deid` has no adapter for) |
+| `70` | internal error (a bug)                                                                                              |
+| `74` | output error: the output stream closed before the CLI finished writing (a consumer that exited early)               |
 
 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.
+handle, on an invalid message, or on output that never reached its consumer.
+
+### A consumer that goes away
+
+Piping into a reader that stops early is ordinary shell usage (a pager you quit, a `head` that has
+seen enough), and it is not an error in your input:
+
+```bash
+cosyte parse bulk.ndjson --ndjson | head -3   # three lines, then exit 74, and a value-free note
+```
+
+The CLI terminates quietly under `74`: no stack trace, no platform error text, and no byte of the
+input on stderr, just the stable `CLI_OUTPUT_WRITE_FAILED` code. Exit `74` is deliberately not the
+internal-error code: nothing went wrong inside the CLI, the answer simply did not reach you. The
+same holds when the whole result is one write, so a run whose output never arrived is never
+reported as a success.
 
 ## PHI posture
 
@@ -268,15 +296,47 @@ cosyte parse broken.hl7 --format hl7 --unsafe-show-values  # appends a bounded i
 
 ## `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). That package is now
-published, but the CLI does not wire it yet, and the wrapped parsers expose no de-identification API of
-their own. 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 the CLI wires
-`@cosyte/deid` and that integration is vetted.
+De-identification is the one operation whose _job_ is to strip identifiers, and the CLI **owns none of
+the policy**. It belongs to [`@cosyte/deid`](https://github.com/cosyte/deid): the CLI locates nothing,
+transforms nothing, and has no fallback scrub, because 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.
+
+```bash
+cosyte redact adt.hl7 > clean.hl7   # stdout: the de-identified message. stderr: what was touched
+echo $?                             # 0: clean.hl7 is the copy. 1: clean.hl7 is empty, see stderr
+```
+
+**Covered formats: `ccda`, `fhir`, `hl7`, `x12`** (what the library covers and this CLI can serialize
+onto a text stdout). Anything else emits nothing at all:
+
+| Outcome                                                                              | Diagnostic               | Exit |
+| ------------------------------------------------------------------------------------ | ------------------------ | ---- |
+| every locus handled                                                                  | the manifest             | `0`  |
+| a locus the library reports it could not handle                                      | `CLI_DEID_INCOMPLETE`    | `1`  |
+| `astm`, `mllp`, `ncpdp`: no adapter in that library                                  | `CLI_NOT_IMPLEMENTED`    | `69` |
+| `dicom`: covered there, but its de-identified form is binary and this stdout is text | `CLI_FORMAT_UNSUPPORTED` | `65` |
+| `@cosyte/deid` not installed (an optional dependency)                                | `CLI_PARSER_UNAVAILABLE` | `69` |
+
+stderr carries the library's **own value-free manifest** (category, transform, the structural path,
+count, disposition and its stable code) and the library's **own published label and version**: the CLI
+asserts no de-identification standard of its own. An absent library is decided **before your input is
+read**.
+
+What the library's default policy does decides which of the first two rows you get, and the CLI
+passes it no policy of its own:
+
+- **Medical record, account and member numbers are removed**, not replaced by a surrogate: their
+  manifest lines read `removed DEID_CATEGORY_REMOVED`.
+- **A visit number or an order number is blocked, so the whole run is refused.** An HL7 visit number
+  (`PV1-19`), and a placer or filler order number (`ORC-2`/`ORC-3`, `OBR-2`/`OBR-3`), fall to the
+  library's catch-all identifier category, which its default policy blocks rather than removes. Such a
+  message exits with `CLI_DEID_INCOMPLETE` (exit `1`) and nothing on stdout, and stderr names each
+  blocked locus with the library's `DEID_LOCUS_BLOCKED` code. Many real ADT messages carry `PV1-19`,
+  so check the exit code before you use `clean.hl7`.
+
+The CLI still keys every run with a **per-invocation ephemeral key** and says so on stderr: any
+identifier surrogate is consistent within one output and deliberately not stable across runs.
 
 ## `cosyte completion`
 
@@ -315,6 +375,12 @@ and the agent get identical results. The PHI posture is inherited and hardened:
 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.
 
+**Every tool publishes an `outputSchema`**, so a client validates a result against a declared contract
+rather than pattern-matching prose. Each result carries `ok`, a `status` of `success` / `verdict` /
+`failed`, the `exit` code, a stable `code` on a failure, and the tool's own payload under `data`; the
+text content block carries the serialized JSON of that same structured result. See the docs for the
+per-tool payload shapes.
+
 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