@cosyte/cli 0.0.2 → 0.0.4

package/dist/index.d.cts

@@ -3,23 +3,30 @@ export { r as readFileBytes, a as readStreamBytes } from './io-B2EobRzC.cjs';
 import 'node:stream';
 
 /**
- * The CLI version string, synced with `package.json#version` on release by the Changesets `version`
- * script. Kept in its own module so both the programmatic entry point and the dispatcher share one
- * source of truth.
+ * The CLI version string, synced with `package.json#version` on release by `scripts/sync-version.mjs`,
+ * which the `version` script runs immediately after `changeset version`. Kept in its own module so
+ * both the programmatic entry point and the dispatcher share one source of truth.
+ *
+ * The declaration below is rewritten by that script and is matched at column 0, annotation included.
+ * Renaming it or reflowing it makes the script exit non-zero rather than silently no-op; the shape is
+ * pinned by `test/sanity.test.ts`, and the value is compared against `package.json` there too.
  *
  * @packageDocumentation
  */
 /**
  * The `@cosyte/cli` version. On the uniform `v0.0.x-until-first-alpha` ladder.
  *
+ * Read by `cosyte --version` and by the MCP server's advertised `SERVER_INFO`, so it is a
+ * user-visible surface on both front doors, not merely an export.
+ *
  * @example
  * ```ts
  * import { VERSION } from "@cosyte/cli";
  *
- * typeof VERSION; // => "string"
+ * console.log(`cosyte ${VERSION}`);
  * ```
  */
-declare const VERSION = "0.0.0";
+declare const VERSION: string;
 
 /**
  * The `cosyte` CLI **exit-code contract**: a designed, documented surface that CI pipelines and
@@ -616,6 +623,33 @@ declare function valueFreeLocator(pos: unknown): string;
  * ```
  */
 declare function loadOptional<T>(format: CosyteFormat, load: () => Promise<T>): Promise<T>;
+/**
+ * The same graceful-degradation path as {@link loadOptional}, keyed on a **package name** rather than
+ * a {@link CosyteFormat}, with the diagnostic supplied by the caller.
+ *
+ * Two of the packages the CLI lazy-loads are not wire-format parsers and so cannot go through
+ * {@link loadOptional}: `@cosyte/transform` (a conversion library, not one of the eight formats, so
+ * calling it a "parser" in the diagnostic would be wrong) and `@cosyte/fhir` (a format, but absent for
+ * a reason no reinstall fixes, which the message has to say). Both are reachable from a published
+ * install only if the user already has them, so both must degrade to a value-free
+ * `CLI_PARSER_UNAVAILABLE` (exit `69`) instead of surfacing a raw resolver error and a stack frame.
+ *
+ * @template T - The imported module's type.
+ * @param detail - The value-free diagnostic detail shown when the package is absent.
+ * @param load - A thunk performing the dynamic import.
+ * @returns The imported module.
+ * @throws {CliError} `CLI_PARSER_UNAVAILABLE` (exit `69`) when the package is absent; any other error
+ *   propagates unchanged.
+ * @example
+ * ```ts
+ * import { loadOptionalPackage } from "@cosyte/cli";
+ *
+ * await loadOptionalPackage("the conversion library is not installed", () =>
+ *   import("@cosyte/transform"),
+ * );
+ * ```
+ */
+declare function loadOptionalPackage<T>(detail: string, load: () => Promise<T>): Promise<T>;
 /**
  * Parse one record of `format` into the wrapped library's model + its value-free warnings. The model
  * is emitted verbatim on the data channel; the CLI adds no parsing of its own.
@@ -1357,4 +1391,4 @@ declare function redactCommand(args: string[]): RunResult;
  */
 declare function completionCommand(args: string[]): RunResult;
 
-export { CLI_CODES, type CliCode, CliError, type CosyteFormat, DEID_UNAVAILABLE_REASON, DETECTABLE_FORMATS, type DeidAvailability, type DetectResult, EXIT, type ExitCode, type Finding, type FmtResult, type InputResolution, type InspectSummary, KNOWN_FORMATS, OP_SUPPORT, type Op, type ParseResult, type ParseWarning, type PhiPosture, type ResolvedInput, RunDeps, type RunResult, SHOW_VALUES, UNSAFE_EXCERPT_MAX, UNSAFE_SHOW_VALUES_FLAG, VALUE_FREE, VERSION, type Verdict, asCosyteFormat, classifyCandidates, completionCommand, convertCommand, convertOutcome, deframeMllp, deidStatus, detectFormat, detectionError, errorResult, extractPhiPosture, extractStableCode, fmtCommand, fmtFormat, formatDiagnostic, formatHl7Position, formatsSupporting, inspectCommand, inspectFormat, loadOptional, mapCodesCommand, parseCommand, parseFailureResult, parseFormat, redactCommand, resolveInput, run, supportsOp, toCliError, unsafeInputSuffix, validateCommand, validateFormat, valueFreeLocator };
+export { CLI_CODES, type CliCode, CliError, type CosyteFormat, DEID_UNAVAILABLE_REASON, DETECTABLE_FORMATS, type DeidAvailability, type DetectResult, EXIT, type ExitCode, type Finding, type FmtResult, type InputResolution, type InspectSummary, KNOWN_FORMATS, OP_SUPPORT, type Op, type ParseResult, type ParseWarning, type PhiPosture, type ResolvedInput, RunDeps, type RunResult, SHOW_VALUES, UNSAFE_EXCERPT_MAX, UNSAFE_SHOW_VALUES_FLAG, VALUE_FREE, VERSION, type Verdict, asCosyteFormat, classifyCandidates, completionCommand, convertCommand, convertOutcome, deframeMllp, deidStatus, detectFormat, detectionError, errorResult, extractPhiPosture, extractStableCode, fmtCommand, fmtFormat, formatDiagnostic, formatHl7Position, formatsSupporting, inspectCommand, inspectFormat, loadOptional, loadOptionalPackage, mapCodesCommand, parseCommand, parseFailureResult, parseFormat, redactCommand, resolveInput, run, supportsOp, toCliError, unsafeInputSuffix, validateCommand, validateFormat, valueFreeLocator };

package/dist/index.d.ts

@@ -3,23 +3,30 @@ export { r as readFileBytes, a as readStreamBytes } from './io-B2EobRzC.js';
 import 'node:stream';
 
 /**
- * The CLI version string, synced with `package.json#version` on release by the Changesets `version`
- * script. Kept in its own module so both the programmatic entry point and the dispatcher share one
- * source of truth.
+ * The CLI version string, synced with `package.json#version` on release by `scripts/sync-version.mjs`,
+ * which the `version` script runs immediately after `changeset version`. Kept in its own module so
+ * both the programmatic entry point and the dispatcher share one source of truth.
+ *
+ * The declaration below is rewritten by that script and is matched at column 0, annotation included.
+ * Renaming it or reflowing it makes the script exit non-zero rather than silently no-op; the shape is
+ * pinned by `test/sanity.test.ts`, and the value is compared against `package.json` there too.
  *
  * @packageDocumentation
  */
 /**
  * The `@cosyte/cli` version. On the uniform `v0.0.x-until-first-alpha` ladder.
  *
+ * Read by `cosyte --version` and by the MCP server's advertised `SERVER_INFO`, so it is a
+ * user-visible surface on both front doors, not merely an export.
+ *
  * @example
  * ```ts
  * import { VERSION } from "@cosyte/cli";
  *
- * typeof VERSION; // => "string"
+ * console.log(`cosyte ${VERSION}`);
  * ```
  */
-declare const VERSION = "0.0.0";
+declare const VERSION: string;
 
 /**
  * The `cosyte` CLI **exit-code contract**: a designed, documented surface that CI pipelines and
@@ -616,6 +623,33 @@ declare function valueFreeLocator(pos: unknown): string;
  * ```
  */
 declare function loadOptional<T>(format: CosyteFormat, load: () => Promise<T>): Promise<T>;
+/**
+ * The same graceful-degradation path as {@link loadOptional}, keyed on a **package name** rather than
+ * a {@link CosyteFormat}, with the diagnostic supplied by the caller.
+ *
+ * Two of the packages the CLI lazy-loads are not wire-format parsers and so cannot go through
+ * {@link loadOptional}: `@cosyte/transform` (a conversion library, not one of the eight formats, so
+ * calling it a "parser" in the diagnostic would be wrong) and `@cosyte/fhir` (a format, but absent for
+ * a reason no reinstall fixes, which the message has to say). Both are reachable from a published
+ * install only if the user already has them, so both must degrade to a value-free
+ * `CLI_PARSER_UNAVAILABLE` (exit `69`) instead of surfacing a raw resolver error and a stack frame.
+ *
+ * @template T - The imported module's type.
+ * @param detail - The value-free diagnostic detail shown when the package is absent.
+ * @param load - A thunk performing the dynamic import.
+ * @returns The imported module.
+ * @throws {CliError} `CLI_PARSER_UNAVAILABLE` (exit `69`) when the package is absent; any other error
+ *   propagates unchanged.
+ * @example
+ * ```ts
+ * import { loadOptionalPackage } from "@cosyte/cli";
+ *
+ * await loadOptionalPackage("the conversion library is not installed", () =>
+ *   import("@cosyte/transform"),
+ * );
+ * ```
+ */
+declare function loadOptionalPackage<T>(detail: string, load: () => Promise<T>): Promise<T>;
 /**
  * Parse one record of `format` into the wrapped library's model + its value-free warnings. The model
  * is emitted verbatim on the data channel; the CLI adds no parsing of its own.
@@ -1357,4 +1391,4 @@ declare function redactCommand(args: string[]): RunResult;
  */
 declare function completionCommand(args: string[]): RunResult;
 
-export { CLI_CODES, type CliCode, CliError, type CosyteFormat, DEID_UNAVAILABLE_REASON, DETECTABLE_FORMATS, type DeidAvailability, type DetectResult, EXIT, type ExitCode, type Finding, type FmtResult, type InputResolution, type InspectSummary, KNOWN_FORMATS, OP_SUPPORT, type Op, type ParseResult, type ParseWarning, type PhiPosture, type ResolvedInput, RunDeps, type RunResult, SHOW_VALUES, UNSAFE_EXCERPT_MAX, UNSAFE_SHOW_VALUES_FLAG, VALUE_FREE, VERSION, type Verdict, asCosyteFormat, classifyCandidates, completionCommand, convertCommand, convertOutcome, deframeMllp, deidStatus, detectFormat, detectionError, errorResult, extractPhiPosture, extractStableCode, fmtCommand, fmtFormat, formatDiagnostic, formatHl7Position, formatsSupporting, inspectCommand, inspectFormat, loadOptional, mapCodesCommand, parseCommand, parseFailureResult, parseFormat, redactCommand, resolveInput, run, supportsOp, toCliError, unsafeInputSuffix, validateCommand, validateFormat, valueFreeLocator };
+export { CLI_CODES, type CliCode, CliError, type CosyteFormat, DEID_UNAVAILABLE_REASON, DETECTABLE_FORMATS, type DeidAvailability, type DetectResult, EXIT, type ExitCode, type Finding, type FmtResult, type InputResolution, type InspectSummary, KNOWN_FORMATS, OP_SUPPORT, type Op, type ParseResult, type ParseWarning, type PhiPosture, type ResolvedInput, RunDeps, type RunResult, SHOW_VALUES, UNSAFE_EXCERPT_MAX, UNSAFE_SHOW_VALUES_FLAG, VALUE_FREE, VERSION, type Verdict, asCosyteFormat, classifyCandidates, completionCommand, convertCommand, convertOutcome, deframeMllp, deidStatus, detectFormat, detectionError, errorResult, extractPhiPosture, extractStableCode, fmtCommand, fmtFormat, formatDiagnostic, formatHl7Position, formatsSupporting, inspectCommand, inspectFormat, loadOptional, loadOptionalPackage, mapCodesCommand, parseCommand, parseFailureResult, parseFormat, redactCommand, resolveInput, run, supportsOp, toCliError, unsafeInputSuffix, validateCommand, validateFormat, valueFreeLocator };

package/dist/index.mjs

@@ -2,7 +2,7 @@ import { readFile } from 'fs/promises';
 import { parseArgs } from 'util';
 
 // src/core/version.ts
-var VERSION = "0.0.0";
+var VERSION = "0.0.4";
 
 // src/core/exit-codes.ts
 var EXIT = {
@@ -226,19 +226,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;
@@ -257,7 +263,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));
@@ -318,7 +324,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") {
@@ -428,7 +434,7 @@ async function fmtFormat(format, bytes) {
       return { output: msg.toString(), warningCount: msg.warnings.length };
     }
     case "fhir": {
-      const { parseResource, serializeResource } = await import('@cosyte/fhir');
+      const { parseResource, serializeResource } = await loadFhir();
       const { resource, issues } = parseResource(decode(bytes));
       return { output: serializeResource(resource), warningCount: issues.length };
     }
@@ -466,7 +472,7 @@ async function fmtFormat(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 = [
@@ -836,11 +842,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 {
@@ -1409,6 +1416,6 @@ function resolve(e) {
 `, exit: e.exit };
 }
 
-export { CLI_CODES, CliError, DEID_UNAVAILABLE_REASON, DETECTABLE_FORMATS, EXIT, KNOWN_FORMATS, OP_SUPPORT, SHOW_VALUES, UNSAFE_EXCERPT_MAX, UNSAFE_SHOW_VALUES_FLAG, VALUE_FREE, VERSION, asCosyteFormat, classifyCandidates, completionCommand, convertCommand, convertOutcome, deframeMllp, deidStatus, detectFormat, detectionError, errorResult, extractPhiPosture, extractStableCode, fmtCommand, fmtFormat, formatDiagnostic, formatHl7Position, formatsSupporting, inspectCommand, inspectFormat, loadOptional, mapCodesCommand, parseCommand, parseFailureResult, parseFormat, readFileBytes, readStreamBytes, redactCommand, resolveInput, run, supportsOp, toCliError, unsafeInputSuffix, validateCommand, validateFormat, valueFreeLocator };
+export { CLI_CODES, CliError, DEID_UNAVAILABLE_REASON, DETECTABLE_FORMATS, EXIT, KNOWN_FORMATS, OP_SUPPORT, SHOW_VALUES, UNSAFE_EXCERPT_MAX, UNSAFE_SHOW_VALUES_FLAG, VALUE_FREE, VERSION, asCosyteFormat, classifyCandidates, completionCommand, convertCommand, convertOutcome, deframeMllp, deidStatus, detectFormat, detectionError, errorResult, extractPhiPosture, extractStableCode, fmtCommand, fmtFormat, formatDiagnostic, formatHl7Position, formatsSupporting, inspectCommand, inspectFormat, loadOptional, loadOptionalPackage, mapCodesCommand, parseCommand, parseFailureResult, parseFormat, readFileBytes, readStreamBytes, redactCommand, resolveInput, run, supportsOp, toCliError, unsafeInputSuffix, validateCommand, validateFormat, valueFreeLocator };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map