@cosyte/cli 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -9,11 +9,198 @@ this file is maintained by hand (Changesets handles the version bump and publish
 
 ## [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).
+### Fixed
+
+- **`@cosyte/cli` can be installed from npm again (CLI-UNINSTALLABLE-MANIFEST).** `0.0.1` and `0.0.2`
+  both published with all ten `@cosyte/*` sibling packages declared as `file:vendor/*.tgz` local
+  paths. `vendor/` is not in `files` and there is no `bundledDependencies`, so the tarball shipped
+  none of them and every install route died on the first: `ENOENT ...
+node_modules/@cosyte/cli/vendor/cosyte-fhir-0.0.0.tgz`. The siblings are now real registry ranges:
+  `@cosyte/hl7` (`^0.0.7`) and `@cosyte/terminology` (`^0.0.9`) as hard `dependencies`, and the six
+  breadth parsers plus `@cosyte/transform` (`^0.0.4`) as `optionalDependencies`. Verified the way a
+  dry-run cannot: the packed tarball was installed in a clean directory outside the repo (exit `0`),
+  then both bins were run and the `.` subpath imported under ESM and CJS.
+
+- **`VERSION` and `cosyte --version` now report the release you are running (CLI-VERSION-DRIFT).**
+  `src/core/version.ts` exported `"0.0.0"` while `package.json` said `0.0.2`, and the constant's own
+  doc comment claimed it was "synced with `package.json#version` on release by the Changesets
+  `version` script" when no such step existed. Confirmed in the published tarball: `@cosyte/cli@0.0.2`
+  ships `VERSION = "0.0.0"` in `dist/index.mjs` and `dist/index.cjs`. It reached two user-visible
+  surfaces, `cosyte --version` and the MCP server's advertised `serverInfo.version`. `scripts/sync-version.mjs`
+  (ported from `@cosyte/transform`) now runs inside the `version` script, and `test/sanity.test.ts`
+  compares the export against `package.json` so a skipped sync goes red rather than shipping.
+  **The two assertions that let five bad releases through the sibling packages are fixed here, not
+  just the value:** `docs-content/installation.md` asserted `typeof VERSION` (true of every wrong
+  value) and now asserts the exact version, which the sync script keeps in step; and the declaration's
+  `: string` annotation, which the sync script's pattern keys on, is pinned by its own test, so
+  dropping it fails at `pnpm test` instead of silently at release time.
+
+- **The `attw` publish gate no longer exits 0 on an untyped pack (ATTW-FALSE-GREEN-PORT).** The
+  `attw` script was the bare CLI (`attw --pack . --profile node16`), and
+  `@arethetypeswrong/cli@0.18.4`'s `getExitCode.js` opens with `if (!analysis.types) return 0`,
+  returning before the problem list is read. So a tarball carrying no declarations at all printed
+  "This package does not contain types." and **exited 0**, and `verify.sh` propagated that 0 as a
+  pass. Reproduced on this package with zero concurrency and the real `--profile node16`
+  invocation, twice: with `dist/` removed, and with all ten of the build's declaration files
+  deleted and its JS left in place. The second is the realistic window, because `tsup` writes JS in
+  one pass and declarations in a later one; instrumented on one build here at a 10ms poll, all
+  eight `.mjs`/`.cjs` files appeared on a single poll at 4.92s and all ten declarations on a single
+  later poll at 11.82s, a 6.90s interval. That interval moves with load (7.85s on a busier box);
+  the ordering, and the ten declarations landing together, do not. Not answered with a lock or a
+  build queue: the gate is now able to report that its own inputs were missing, whatever removed
+  them.
+  - `scripts/attw.mjs` (ported from the fix shipped in `@cosyte/terminology`) runs two nets around
+    the real binary. A **preflight** that every relative path `package.json` promises exists and is
+    non-empty, naming the missing file; and a **post-check** that promotes the untyped sentence to a
+    failure, which catches declarations that are on disk but excluded from the tarball. Every
+    argument this repo passes is forwarded, so `--profile node16` keeps its exact meaning: measured
+    here, without it `@cosyte/cli/mcp` fails `node10` resolution and `attw` exits 1.
+  - **The preflight also walks `bin`, which the ported original did not**, because this is a `bin`
+    package and the sibling it came from ships no executable. Measured: with `dist/bin/cosyte.mjs`
+    deleted and everything else built, `attw --pack . --profile node16` printed every subpath green
+    and exited 0 over a tarball with no `cosyte` command in it.
+  - **`--quiet`, `-q`, `--format`, `-f` and `--config-path` are refused by option name and not by
+    value**, as is a `.attw.json` setting `quiet` or `format` (`readConfig()` applies it after
+    argv). Each was measured here to remove the untyped sentence from the output while still
+    exiting 0. `--config-path` is refused on a measurement rather than the inference the original
+    recorded. **Two limits are disclosed rather than closed**, both measured: the match is on an
+    exact argv token, so commander's attached and clustered short forms `-fjson` and `-Pf json` get
+    through (`-qP` does not; the wrapper treats an empty transcript as a failure), and a declared
+    path not starting with `.` is skipped by the preflight. The invocation this replaced exited 0
+    on the same pack with no arguments at all.
+  - **A correction to the ported message.** `files: ["dist"]` packs all ten declarations `tsup`
+    emits while `package.json` names only four; the shared `dist/io-<hash>.d.*` **and the four
+    `dist/bin/*.d.*`** ride along unnamed, and `analysis.types` is true if the tarball carries any
+    declaration. Measured on this tree: losing the four declared declarations gives "No types"
+    problems and **exit 1** while any of the other six survives, and only losing all ten gives the
+    untyped sentence and **exit 0**. So a partial declaration loss is caught by `attw` itself and
+    only a total one is the false green. The preflight reports both outcomes instead of asserting
+    the exit 0, which the inherited wording would have done falsely.
+  - `test/scripts/attw-gate.test.ts` pins all of it against the real binary, including attw's own
+    exit 0, a negative control on a well-formed package, that a genuine attw failure still fails
+    with attw's own status, and that the profile flag survives the wrapper in both directions.
+  - `scripts/verify.sh` in the meta-repo is unchanged; its propagation was never at fault.
+
+- **The public surface now states that `0.0.1` is published and uninstallable (ASSETS-P8).** `0.0.1`
+  published on 2026-07-29 with all ten `file:vendor/*.tgz` dependency specifiers intact. `vendor/` is
+  not in `files` and there is no `bundledDependencies`, so every install route (`npm i`, `npm i -g`,
+  `npx`) fails with `ENOENT` on `node_modules/@cosyte/cli/vendor/cosyte-fhir-0.0.0.tgz`. Reproduced
+  in a clean directory. A published version is immutable (ADR 0001), so `0.0.1` stays broken and the
+  fix must ship as a later version.
+  - `README.md` gains a **"Known issue"** section stating what fails, the exact error, why, and that
+    a source checkout is the only workaround. `docs-content/installation.md` gains the same under
+    **"Installing fails today"**. Both copies of the broken `npx`-based MCP registration snippet are
+    annotated (`README.md` and `docs-content/mcp.md`).
+  - **Four false claims corrected.** (1) `README.md` said "not yet published to npm"; it is
+    published. (2) It described swapping the vendored sibling deps for real `@cosyte/*` npm ranges as
+    a step still to come "at that flip"; the flip already happened without the swap, which is the
+    defect. (3) The same "not yet published" claim appeared in **three** `docs-content/` pages. (4)
+    The `redact`/`deid` terminal diagnostic, the `--help` text, three JSDoc blocks that compile into
+    `dist/*.d.ts`, and **five** docs pages said `@cosyte/deid` was unpublished, unshipped, or unbuilt;
+    it is published at `0.0.2`, and the accurate statement is that the CLI does not wire it yet. Every
+    count here was re-derived by census of the base tree, not estimated.
+  - **The "all eight formats" claim was checked and is correct**: `CosyteFormat` and `OP_SUPPORT` both
+    enumerate exactly eight.
+  - `RELEASING.md` records that the documented dependency-swap step was skipped, that a green
+    `npm publish --dry-run` cannot catch this (it packs a tarball but never resolves its deps from a
+    registry), and adds a checklist step to install the published version from outside the repo.
+- **The route to an installable release, recorded in `RELEASING.md` and verified against the
+  registry.** `@cosyte/hl7` (`0.0.3`), `@cosyte/terminology` (`0.0.4`) and all six breadth parsers
+  would swap to real ranges today. `@cosyte/fhir` is unpublished (`FHIR-NPM-NAME`, an npm E403
+  name-similarity rejection) and `@cosyte/transform@0.0.2` fails `E404` on its `@cosyte/fhir` peer,
+  so neither can. An installable release is nonetheless reachable before that unblocks, because npm
+  tolerates an `optionalDependency` that fails to resolve (measured). It needs a code change first:
+  `@cosyte/fhir` and `@cosyte/transform` are imported with a raw `await import()`, so they must be
+  routed through a guarded loader to degrade to `CLI_PARSER_UNAVAILABLE` (exit `69`) rather than
+  crash. `loadOptional()` cannot be reused unchanged: it takes a `CosyteFormat`, and `"transform"` is
+  not one, and its diagnostic hardcodes the word "parser". Not undertaken here.
+  - **Superseded within this same unreleased set**, by the two entries at the top of this section:
+    the swap and the loader change were both carried out. Two claims that entry made did not survive
+    contact: the "name similarity" reading of the `@cosyte/fhir` `E403` was **retracted across the
+    ecosystem on 2026-08-03** (the cause is unexplained; do not assert one), and "npm tolerates an
+    `optionalDependency` that fails to resolve" is true only in isolation. Declaring **both**
+    `@cosyte/fhir` and `@cosyte/transform` optional fails the install outright with `ERESOLVE`, which
+    is why `@cosyte/fhir` ended up not declared at all rather than declared optional.
+
+### Changed
+
+- **FHIR support is unavailable in an npm-installed copy, and now says so instead of crashing.**
+  `@cosyte/fhir` is not on the npm registry, so it cannot be declared as a dependency at all;
+  measured, declaring it alongside `@cosyte/transform` (which requires it) fails the whole install
+  with `ERESOLVE`. `@cosyte/transform` is therefore skipped by npm as an unresolvable optional
+  dependency. Both were previously loaded with a bare `await import()`, which in an installed copy
+  would have surfaced a raw resolver error and a stack frame, so FHIR `parse`/`inspect`/`fmt`/`validate`
+  and `convert` now degrade to a value-free `CLI_PARSER_UNAVAILABLE` (exit `69`) with a diagnostic that
+  says the package is not on the registry rather than "install it". **Neither diagnostic says "install
+  it", and that is deliberate**: `npm install @cosyte/transform` fails `E404` on its own
+  `@cosyte/fhir` peer, so `loadOptional()`'s stock wording ("install it to use this format, it is an
+  optional dependency") would point a user at a command that cannot succeed. New
+  `loadOptionalPackage(detail, load)` under `loadOptional`, exported on the `.` subpath.
+  `@cosyte/fhir` is retained as a `devDependency` on the vendored tarball so this repo's own FHIR and
+  `convert` tests still run; note that `devDependencies` **are** published, so that one
+  `file:vendor/*.tgz` specifier does remain in the manifest, harmlessly, because a consumer never
+  installs a dependency's `devDependencies` (verified: the install exits `0`). HL7 v2, `map-codes` and
+  the six breadth formats are unaffected and work from a plain install.
+
+- **Documented a pre-existing defect that this release makes reachable for the first time:
+  `--omit=optional` produces an install in which the `cosyte` command does not run at all.** The
+  install exits `0`, then every invocation, `--version` included, fails with `ERR_MODULE_NOT_FOUND` on
+  `@modelcontextprotocol/sdk` and a raw stack trace, because the built `dist/bin/cosyte.mjs` imports
+  the SDK statically at the top level rather than only on the `mcp` path. Verified identical on the
+  base commit, so it is not introduced here; it simply could not be hit before, because the package
+  could not be installed at all. `docs-content/` now says not to use that flag instead of implying it
+  is a supported way to slim the install. **The code defect is not fixed here** and needs its own
+  change: it also falsifies the "a plain `cosyte parse` never pulls it" claim in `src/bin/cosyte.ts`.
+
+- **The docs no longer tell you to run `npx @cosyte/cli …`, which never worked.** Separate from the
+  packaging defect and not fixed by it: `npx` runs the executable whose name matches the package
+  name's last segment, which would be `cli`, and this package ships `cosyte` and `cosyte-mcp`, so the
+  short form fails with `could not determine executable to run`. Reproduced on the published `0.0.2`
+  and on the fixed tarball, whose `bin` block is byte-identical. `README.md`, `docs-content/installation.md`
+  and both MCP registration snippets now use `npx --package @cosyte/cli cosyte …` /
+  `npx -y --package @cosyte/cli cosyte-mcp`, each measured working. A `cli` bin alias would fix the
+  short form and is deliberately not added, because `npm install -g` would then claim a command named
+  `cli` on the user's `PATH`.
 
 ### Added
 
+- **`README.md` now opens with the shared Cosyte lockup in a `<picture>` block, above the H1.** The
+  dark-ground tile (`cosyte-lockup-tile-on-dark-1200x300.png`) sits behind a
+  `prefers-color-scheme: dark` media query and the light-ground tile
+  (`cosyte-lockup-tile-on-light-1200x300.png`) is the inner `<img>` fallback, so the mark is read on
+  a ground that matches the page it is read on. The `# @cosyte/cli` heading and the blockquote under
+  it are unchanged: the artwork reads "Cosyte" and the heading names the package, so nothing on the
+  page is duplicated. Both URLs were re-checked immediately before the push and returned
+  `200 image/png` (10513 bytes dark, 10455 light). The block was copied byte for byte out of
+  `@cosyte/hl7`'s `README.md` rather than retyped and diffed against it, because a transcription
+  error in one of these URLs is a broken image on a public package page.
+
+  **This replaces the per-package banner added earlier in the same unreleased window, and the reason
+  it replaces it is recorded rather than dropped.** That banner was a plain markdown image, chosen
+  over `<img>` or `<picture>` on the stated ground that whether npm's markdown sanitizer preserves a
+  `<picture>` element was unverified. That was an accurate account of what was known when it was
+  written, and it has since been measured: **GitHub honours the `prefers-color-scheme` switch**
+  (observed on `@cosyte/astm` in dark mode, where the rendered image's `currentSrc` resolves to the
+  on-dark tile and its parent element is `PICTURE`), and **on the npm package page the `<img>` is
+  hoisted out of its `<picture>` by the anchor wrapper** rather than the element being stripped, so
+  the light cut renders, which is the correct one there because npmjs.com has no dark mode. Those two
+  measurements were taken on `astm` and reported into this repo rather than re-taken here; what was
+  re-checked directly for `cli` is that both tile URLs return `200 image/png`. The failure mode is
+  safe either way: a renderer that strips `<source>` renders the inner `<img>`, so the worst case is
+  a light-ground mark on a dark page, never a missing or broken image.
+
+  **Why this is corrected rather than annotated in place.** `0.0.1` published on 2026-07-29, a day
+  before the banner landed, so no `@cosyte/cli` tarball has ever carried the banner or the sentence
+  announcing it. Annotating an entry no consumer received would publish an addition and its
+  replacement as two changes when only one was ever visible, so the banner entry is removed from this
+  release and its reasoning is carried here instead of being silently reversed.
+
+  The alt text describes the artwork, a plus mark set in two overlapping rounded squares beside the
+  Cosyte wordmark, rather than the package. It is what a screen reader on the npm page reads out and
+  what a reader gets when the image fails to load, so repeating the `@cosyte/cli` heading below it
+  would be a wasted line. The wording is the one eight sibling packages already carry, confirmed
+  against both rendered PNGs here rather than copied on trust.
+
 - **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

package/README.md

@@ -1,3 +1,8 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://cosyte.com/tile/cosyte-lockup-tile-on-dark-1200x300.png">
+  <img alt="Cosyte: a plus mark set in two overlapping rounded squares, one solid and one outlined, beside the Cosyte wordmark" src="https://cosyte.com/tile/cosyte-lockup-tile-on-light-1200x300.png">
+</picture>
+
 # @cosyte/cli
 
 > The **cosyte CLI**: a PHI-safe developer front door over the `@cosyte/*` healthcare parsers.
@@ -17,7 +22,43 @@ It is a thin, honest skin over libraries that already own correctness ([`@cosyte
 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
+## Known issue: `0.0.1` and `0.0.2` are published but cannot be installed
+
+**`npm install @cosyte/cli@0.0.1` and `@0.0.2` both fail.** They end in an `ENOENT`, like this:
+
+```
+npm error code ENOENT
+npm error path node_modules/@cosyte/cli/vendor/cosyte-fhir-0.0.0.tgz
+npm error enoent ENOENT: no such file or directory
+```
+
+`npx` and `npm install -g` fail the same way on those two versions, and so does the `npx`-based MCP
+server registration below. There is no workaround from the consumer side. **Nothing is wrong with your
+setup, and re-running it will not help.**
+
+**Why.** Those manifests declared the ten `@cosyte/*` sibling packages as local file paths
+(`file:vendor/*.tgz`) rather than as npm version ranges. Those tarballs live in the git repository and
+are deliberately not part of the published package, so npm resolved the paths against a directory that
+does not exist in your `node_modules` and stopped at the first one. It was a packaging defect in those
+releases, not a fault in any command.
+
+**A published version is immutable, so `0.0.1` and `0.0.2` stay broken: install a later version.** The
+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
 > 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:
@@ -34,8 +75,8 @@ diagnostic** posture.
 >   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.
+> - **`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.
 > - **`completion <bash|zsh|fish>`**: print a static shell completion script.
 >
 > **Support is honest per (format, operation)**: not every parser faithfully supports every command, so
@@ -45,23 +86,42 @@ diagnostic** posture.
 > 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).
+> The CLI is **feature-complete**: 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. Those gates cover the code, and
+> the code was never what was broken. The one release step they do not cover is the dependency swap
+> 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).
 
 ## 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`).
+> **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`.
 
 ```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
+npm install -g @cosyte/cli          # put `cosyte` on your PATH
+cosyte parse message.hl7            # format autodetected → HL7 v2
 ```
 
+Or without installing, using `npx`:
+
+```bash
+npx --package @cosyte/cli cosyte parse message.hl7
+```
+
+> **`npx @cosyte/cli …` (the short form) does not work, and this is not the packaging defect above.**
+> It fails with `could not determine executable to run`. When a package ships more than one
+> executable, `npx` runs the one whose name matches the package name's last segment; that would be
+> `cli`, and this package ships `cosyte` and `cosyte-mcp`. Naming the executable explicitly with
+> `--package` is the supported form, and it works. A `cli` executable is deliberately **not** added as
+> an alias: `npm install -g` would then put a command called `cli` on every user's `PATH`, which is far
+> too generic a name to claim.
+
 ## `cosyte parse`
 
 Read a file (or stdin via `-`), autodetect the format by content, and print the parsed model as typed
@@ -207,13 +267,14 @@ 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), which is not published, and
-the wrapped parsers expose no de-identification API. A built-in "minimal Safe-Harbor" pass over only
+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 `@cosyte/deid`
-ships and is vetted.
+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.
 
 ## `cosyte completion`
 
@@ -234,11 +295,17 @@ subprocess**, not a hosted endpoint. Register it in an MCP client's config:
 ```json
 {
   "mcpServers": {
-    "cosyte": { "command": "npx", "args": ["-y", "@cosyte/cli", "mcp"] }
+    "cosyte": { "command": "npx", "args": ["-y", "--package", "@cosyte/cli", "cosyte-mcp"] }
   }
 }
 ```
 
+> **`--package` is required, and the shorter `["-y", "@cosyte/cli", "mcp"]` does not work**: it fails
+> with `could not determine executable to run`, for the `npx` executable-selection reason described
+> under [Run it](#run-it) above. This also needs a version that can be installed at all, so not
+> `0.0.1` or `0.0.2`. The `convert` tool reports `CLI_PARSER_UNAVAILABLE` from an npm install, because
+> the FHIR library is not on the registry.
+
 `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

package/dist/bin/cosyte-mcp.cjs

@@ -7,7 +7,7 @@ var types_js = require('@modelcontextprotocol/sdk/types.js');
 var util = require('util');
 
 // src/core/version.ts
-var VERSION = "0.0.0";
+var VERSION = "0.0.3";
 
 // src/core/exit-codes.ts
 var EXIT = {
@@ -23,7 +23,7 @@ var EXIT = {
   DATAERR: 65,
   /** No input: the named file does not exist or is unreadable (`EX_NOINPUT`). */
   NOINPUT: 66,
-  /** Unavailable: a required capability is not yet built (e.g. `redact` before `@cosyte/deid`), a
+  /** Unavailable: a required capability is not yet wired (e.g. `redact` before `@cosyte/deid`), a
    * distinct non-zero signal that is never a fake success (`EX_UNAVAILABLE`). */
   UNAVAILABLE: 69,
   /** Internal error: an unexpected exception (a bug), distinct from a handled bad input (`EX_SOFTWARE`). */
@@ -51,8 +51,8 @@ var CLI_CODES = {
   CLI_PARSER_UNAVAILABLE: "CLI_PARSER_UNAVAILABLE",
   /** The wrapped parser rejected the input. Positional context only, never the offending bytes. Exit `65`. */
   CLI_PARSE_FAILED: "CLI_PARSE_FAILED",
-  /** A command whose ground-layer library is not yet built (e.g. `redact` before `@cosyte/deid`
-   * ships). Never a fake success: a distinct, value-free "unavailable" signal. Exit `69`. */
+  /** A command whose ground-layer library is not yet wired (e.g. `redact` before `@cosyte/deid` is
+   * wired). Never a fake success: a distinct, value-free "unavailable" signal. Exit `69`. */
   CLI_NOT_IMPLEMENTED: "CLI_NOT_IMPLEMENTED",
   /** An unexpected internal error (a bug). Exit `70`. */
   CLI_INTERNAL: "CLI_INTERNAL"
@@ -228,19 +228,25 @@ function anyError(findings) {
   return findings.some((f) => ERROR_SEVERITIES.has(f.severity));
 }
 async function loadOptional(format, load) {
+  return loadOptionalPackage(
+    `the @cosyte/${format} parser is not installed; install it to use this format (it is an optional dependency)`,
+    load
+  );
+}
+async function loadOptionalPackage(detail, load) {
   try {
     return await load();
   } catch (e) {
     if (isModuleNotFound(e)) {
-      throw new CliError(
-        CLI_CODES.CLI_PARSER_UNAVAILABLE,
-        EXIT.UNAVAILABLE,
-        `the @cosyte/${format} parser is not installed; install it to use this format (it is an optional dependency)`
-      );
+      throw new CliError(CLI_CODES.CLI_PARSER_UNAVAILABLE, EXIT.UNAVAILABLE, detail);
     }
     throw e;
   }
 }
+var FHIR_UNAVAILABLE = "the @cosyte/fhir parser is not installed, and it is not currently on the npm registry, so it cannot be installed from there; FHIR support is unavailable in this install";
+async function loadFhir() {
+  return loadOptionalPackage(FHIR_UNAVAILABLE, () => import('@cosyte/fhir'));
+}
 function isModuleNotFound(e) {
   if (typeof e !== "object" || e === null) return false;
   const code = "code" in e ? e.code : void 0;
@@ -259,7 +265,7 @@ async function parseFormat(format, bytes) {
       };
     }
     case "fhir": {
-      const { parseResource, serializeResource } = await import('@cosyte/fhir');
+      const { parseResource, serializeResource } = await loadFhir();
       const text = decode(bytes);
       const { resource, issues } = parseResource(text);
       const model = JSON.parse(serializeResource(resource));
@@ -320,7 +326,7 @@ async function inspectFormat(format, bytes) {
       };
     }
     case "fhir": {
-      const { parseResource, resourceType, readBundle } = await import('@cosyte/fhir');
+      const { parseResource, resourceType, readBundle } = await loadFhir();
       const { resource, issues } = parseResource(decode(bytes));
       const rt = resourceType(resource) ?? null;
       if (rt === "Bundle") {
@@ -425,7 +431,7 @@ async function inspectFormat(format, bytes) {
 async function validateFormat(format, bytes) {
   switch (format) {
     case "fhir": {
-      const { parseResource, validateResource } = await import('@cosyte/fhir');
+      const { parseResource, validateResource } = await loadFhir();
       const { resource, issues } = parseResource(decode(bytes));
       const validation = validateResource(resource);
       const findings = [
@@ -673,11 +679,12 @@ async function convertCommand(args, deps, posture = VALUE_FREE) {
   return { stdout: `${conversion.bundleText}
 `, stderr, exit };
 }
+var TRANSFORM_UNAVAILABLE = "the @cosyte/transform conversion library is not installed, so convert is unavailable; it requires @cosyte/fhir, which is not currently on the npm registry, so npm skips transform as an unresolvable optional dependency and installing it directly fails for the same reason";
 async function runConvert(bytes, posture) {
   const [{ parseHL7 }, { toFhir }, { serializeResource }] = await Promise.all([
     import('@cosyte/hl7'),
-    import('@cosyte/transform'),
-    import('@cosyte/fhir')
+    loadOptionalPackage(TRANSFORM_UNAVAILABLE, () => import('@cosyte/transform')),
+    loadFhir()
   ]);
   let msg;
   try {