@cosyte/cli 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -9,11 +9,81 @@ 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
+
+- **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.
 
 ### 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,37 @@ 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` is published but cannot be installed
+
+**`@cosyte/cli@0.0.1` is on npm and `npm install @cosyte/cli` fails.** It ends 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 @cosyte/cli …` and `npm install -g @cosyte/cli` fail the same way, 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.** The published manifest declares its 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 resolves the paths against a directory that
+does not exist in your `node_modules` and stops at the first one. It is a packaging defect in that
+release, not a fault in any command.
+
+**A published version is immutable, so `0.0.1` will stay broken.** The fix has to arrive as a later
+version, and it is blocked on something outside this package: `@cosyte/fhir` is not on npm yet (its
+name was rejected by the registry as too similar to an existing package, which is a naming problem
+rather than missing work), and `@cosyte/transform` is on npm but currently fails to install for the
+same reason, because it peer-depends on `@cosyte/fhir`. `@cosyte/hl7` and `@cosyte/terminology` are
+published and would swap over today. Until the naming issue is resolved, run the CLI from a source
+checkout (`pnpm install && pnpm build`, then invoke `dist/bin/cosyte.mjs`).
+
+> **Status:** pre-alpha (`0.0.x`), published to npm at `0.0.1`, which **cannot be installed** (see
+> above). 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 +69,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,16 +80,20 @@ 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 is not what is broken. The one release step they do not cover is the dependency swap
+> described above, which is why `0.0.1` published green and still cannot be installed: a dry-run
+> builds the tarball but never resolves it from a registry. **The swap is blocked, not scheduled**,
+> and it stays blocked until `@cosyte/fhir` can be published under a name npm accepts, which also
+> unblocks `@cosyte/transform`. 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`).
+> **None of the commands in this section work today.** `@cosyte/cli` is on npm, but every install
+> route fails with the `ENOENT` described in [the known issue](#known-issue-001-is-published-but-cannot-be-installed)
+> above. They are recorded here as the shape install will take once a fixed version can ship. Until
+> then, run it from a local checkout (`pnpm install && pnpm build`, then invoke `dist/bin/cosyte.mjs`).
 
 ```bash
 npx @cosyte/cli parse message.hl7   # no install; format autodetected → HL7 v2
@@ -207,13 +246,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`
 
@@ -239,6 +279,11 @@ subprocess**, not a hosted endpoint. Register it in an MCP client's config:
 }
 ```
 
+> This registration **does not work yet**: `npx` has to install the package first, and that install
+> fails with the `ENOENT` described in
+> [the known issue](#known-issue-001-is-published-but-cannot-be-installed) above. To run the MCP
+> server today, point `command` at a built local checkout's `dist/bin/cosyte-mcp.mjs` instead.
+
 `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

@@ -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"