@amritk/mjst 0.17.0 → 0.19.0

package/AI.md

@@ -41,14 +41,25 @@ mjst compile-api ./routes.ts --out ./dist/handler.ts
    point `--schema` at a JS/TS **module**; `avro` points it at a `.avsc` JSON
    document, which is read as data (no `import()`, so `--export` does not
    apply).
+6. **`--input asyncapi`** reads an AsyncAPI 2.x/3.0 document (JSON or YAML) and
+   generates from every message payload/headers schema, one subtree per message.
+   It rejects `--schema-dir`, `--out-file`, `--root-type`, and `--export`.
+7. **`--message-contracts`** (AsyncAPI only) additionally writes
+   `contracts/<channel>.ts` — a `defineMessages({ ... })` per channel, plus a
+   barrel. Those files import **`@amritk/api`**, which the *consuming* project
+   installs; the CLI does not put it there, and `--build` leaves the contracts
+   as `.ts` for that reason. Incompatible with `--types-only`. Use
+   `--discriminator <prop>` when the document tags frames with something other
+   than `type`; a channel carrying `x-mjst: { discriminator }` keeps its own.
 
 ## Common flags
 
 `--schema` / `--schema-dir`, `--out-dir` / `--out-file`, `--input`,
-`--validators`, `--examples`, `--types-only`, `--build`, `--strict`,
-`--strip-unknown`, `--unknown-keys count-keys|count-enumerable`, `--readonly`,
-`--import-ext ts|js`, `--config <path>`,
-`--resolve-remote` / `--allowed-hosts` (SSRF-guarded remote `$ref`s).
+`--validators`, `--examples`, `--message-contracts`, `--discriminator`,
+`--types-only`, `--build`, `--strict`, `--strip-unknown`,
+`--unknown-keys count-keys|count-enumerable`, `--readonly`,
+`--import-ext ts|js`, `--config <path>`, `--resolve-remote` /
+`--allowed-hosts` (SSRF-guarded remote `$ref`s).
 
 ## Lint gotchas
 

package/README.md

@@ -361,6 +361,24 @@ The exit code is `0` on success, `1` when compilation fails (unloadable module,
 <td colspan="4">Also emit test-data files for every schema into an examples/ subdirectory of the output destination: a fast-check arbitrary (FooArbitrary) that produces schema-valid values and a concrete fooExample value. Under schemaDir the examples mirror the schema layout so they never collide with the parser output. The generated arbitraries import fast-check, which consumers must install as a (dev) dependency; the static example values have no runtime dependencies.</td>
 </tr>
 <tr>
+<td>🔌 <code>messageContracts</code></td>
+<td><code>--message-contracts</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Also emit a @amritk/api channel contract per AsyncAPI channel into a contracts/ subdirectory: one defineMessages({ ... }) module naming every message that channel carries — keyed by the value its discriminator property carries on the wire, with that property stripped out of each payload because the runtime removes it before validating — plus a barrel re-exporting them. Requires input 'asyncapi', which is the only input that has channels and operations to project from. Incompatible with typesOnly: a contract is a runtime value, not a type. The generated modules import @amritk/api, which the consuming project must install; it is not a dependency of the generated parsers.</td>
+</tr>
+<tr>
+<td>🏷️ <code>discriminator</code></td>
+<td><code>--discriminator &lt;prop&gt;</code></td>
+<td><code>string</code></td>
+<td align="center"><code>"type"</code></td>
+</tr>
+<tr>
+<td colspan="4">Property name that says which message a frame is, for the contracts messageContracts emits. Defaults to 'type', matching @amritk/api. A channel that declares its own with 'x-mjst': { 'discriminator': '...' } keeps it — one flag covers a whole run, and a run may span channels that disagree. Only meaningful together with messageContracts.<br><strong>Examples:</strong> <code>"event"</code></td>
+</tr>
+<tr>
 <td>🔨 <code>build</code></td>
 <td><code>--build</code></td>
 <td><code>boolean</code></td>
@@ -376,7 +394,7 @@ The exit code is `0` on success, `1` when compilation fails (unloadable module,
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="4">Allow generated files to overwrite files that already exist in the output destination. By default a collision with a file mjst did not generate (a hand-written index.ts, say) aborts the run before anything is written, because the generator would otherwise replace it — and, under build, delete it along with the other intermediate sources. Regenerating never needs this flag: each run records what it wrote in a .mjst-manifest.json at the root of the output directory, and anything listed there is replaced freely.</td>
+<td colspan="4">Deprecated and ignored. Generated files always replace whatever is at their path, so this flag no longer does anything; it is still accepted so existing scripts and config files keep running. Reverting an unwanted replacement is version control's job. Compilation under build still only removes the intermediate sources the run itself generated.</td>
 </tr>
 <tr>
 <td>⚠️ <code>logWarnings</code></td>

package/dist/cli-config.d.ts

@@ -60,21 +60,36 @@ export type CliConfig = {
      * `fast-check`, which consumers must install as a (dev) dependency.
      */
     readonly examples?: boolean;
+    /**
+     * When true, also emit a `@amritk/api` channel contract per AsyncAPI channel
+     * into a `contracts/` subdirectory: one `defineMessages({ ... })` module
+     * naming every message that channel carries, keyed by its wire discriminator
+     * value, plus a barrel. Requires `input: 'asyncapi'` — the contracts are
+     * projected from the document's channels and operations, which no other input
+     * format has. Incompatible with `typesOnly`: a contract is a runtime value.
+     *
+     * The generated modules import `@amritk/api`, which the *consuming* project
+     * must have installed; it is not a dependency of the generated parsers.
+     */
+    readonly messageContracts?: boolean;
+    /**
+     * Property name that says which message a frame is, for the contracts
+     * `messageContracts` emits. Defaults to `'type'`, matching `@amritk/api`.
+     * A channel that declares its own via `x-mjst: { discriminator }` keeps it —
+     * one flag covers a whole run, and a run may span channels that disagree.
+     */
+    readonly discriminator?: string;
     /**
      * When true, compile the generated TypeScript files to .js and .d.ts output.
      * The .ts source files are removed after compilation.
      */
     readonly build?: boolean;
     /**
-     * When true, generated files may overwrite files that already exist in the
-     * output destination. By default a collision with a file mjst did not generate
-     * (a hand-written `index.ts`, say) aborts the run rather than silently
-     * replacing it — and with `build`, deleting it afterwards. Regeneration does
-     * not need this: each run records what it wrote in a `.mjst-manifest.json` at
-     * the root of the output directory, and reclaims those paths freely. With
-     * `outFile` the "output directory" is the directory holding that file, so the
-     * manifest lands beside it — generated examples and the `build` output already
-     * do.
+     * @deprecated No longer has any effect, and is accepted only so existing
+     * scripts and config files keep running. Generated files always replace
+     * whatever is at their path; version control is where an unwanted replacement
+     * shows up and gets reverted. `build` still only ever deletes the intermediate
+     * sources the run itself committed.
      */
     readonly force?: boolean;
     /**

package/dist/cli.js

@@ -12,8 +12,10 @@ import { combineGeneratedFiles } from "./combine-files.js";
 import { createOutputWriter } from "./create-output-writer.js";
 import { detectHelpersMode } from "./detect-helpers-mode.js";
 import { emitExamples } from "./emit-examples.js";
+import { CONTRACTS_DIR, CONTRACTS_PEER, emitMessageContracts } from "./emit-message-contracts.js";
 import { ensureOutputDir } from "./ensure-output-dir.js";
 import { HELP_TEXT } from "./help-text.js";
+import { isDependencyDeclared } from "./is-dependency-declared.js";
 import { loadAsyncApiDocument } from "./load-asyncapi-document.js";
 import { loadConfig } from "./load-config.js";
 import { loadSchema } from "./load-schema.js";
@@ -22,6 +24,7 @@ import { parseMetaRequest } from "./parse-meta-request.js";
 import { readVersion } from "./read-version.js";
 import { resolveImportExt } from "./resolve-import-ext.js";
 const ROOT_TYPE_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const DISCRIMINATOR_PATTERN = /^[A-Za-z_$][\w$-]*$/;
 const schemaBaseName = (schemaPath) => basename(schemaPath).replace(/\.[^.]+$/, "");
 const resolveHelpersMode = (config, outputDir) => {
   const helpersMode = config.helpers ?? detectHelpersMode(outputDir);
@@ -64,7 +67,7 @@ const commitOrDiscard = async (writer, stageAll) => {
   return writer.commit();
 };
 const runExamples = async (config, outputDir, tasks) => {
-  const writer = await createOutputWriter(outputDir, config.force);
+  const writer = await createOutputWriter(outputDir);
   const written = await commitOrDiscard(writer, async () => {
     for (const task of tasks) {
       await emitExamples({
@@ -153,7 +156,7 @@ const runSingle = async (config, schemaPath, outputDir) => {
   const rootTypeName = config.rootType ?? deriveRootTypeName(schema, schemaBaseName(schemaPath));
   console.log(`Root type: ${rootTypeName}`);
   const files = await buildSchema(schema, rootTypeName, void 0, config.typesOnly, config.logWarnings, config.strict, helpersMode, void 0, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive, void 0, config.unknownKeys);
-  const writer = await createOutputWriter(outputDir, config.force);
+  const writer = await createOutputWriter(outputDir);
   const written = await commitOrDiscard(writer, async () => {
     for (const file of files) {
       const isHelper = file.filename.startsWith("_helpers/");
@@ -183,7 +186,7 @@ const runSingleFile = async (config, schemaPath, outFilePath) => {
   console.log(`Root type: ${rootTypeName}`);
   const files = await buildSchema(schema, rootTypeName, void 0, config.typesOnly, config.logWarnings, config.strict, config.helpers ?? "package", void 0, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive, void 0, config.unknownKeys);
   const combined = combineGeneratedFiles(files);
-  const writer = await createOutputWriter(outputDir, config.force);
+  const writer = await createOutputWriter(outputDir);
   const written = await commitOrDiscard(writer, async () => {
     await writer.stage(basename(outFilePath), config.banner ? resolveBanner(config.banner) + combined : combined);
   });
@@ -211,7 +214,7 @@ const runRecursive = async (config, schemaDir, outputDir) => {
   await ensureOutputDir(outputDir);
   const helpersMode = resolveHelpersMode(config, outputDir);
   const sharedHelpers = /* @__PURE__ */ new Map();
-  const writer = await createOutputWriter(outputDir, config.force);
+  const writer = await createOutputWriter(outputDir);
   const exampleTasks = [];
   const stageAll = async () => {
     for (const schemaFile of schemaFiles) {
@@ -255,6 +258,11 @@ ${relPath} \u2192 ${relNoExt}/ (root type: ${rootTypeName})`);
 Total files generated: ${writtenTsFiles.length}`);
   }
 };
+const reportContractsPeer = (outputDir) => {
+  if (isDependencyDeclared(outputDir, CONTRACTS_PEER))
+    return;
+  console.log(`Tip: the generated contracts import ${CONTRACTS_PEER}, which is not a declared dependency of the project at ${outputDir}. Install it there (it is a peer of the generated code, not of the mjst CLI).`);
+};
 const runAsyncApi = async (config, documentPath, outputDir) => {
   const document = await loadAsyncApiDocument(config, documentPath);
   const model = extractAsyncApi(document);
@@ -262,7 +270,8 @@ const runAsyncApi = async (config, documentPath, outputDir) => {
   for (const issue of model.issues) {
     console.warn(`Warning: ${issue.path}: ${issue.message}`);
   }
-  if (schemas.length === 0) {
+  const contractsPossible = config.messageContracts === true && model.channels.some((c) => c.messages.length > 0);
+  if (schemas.length === 0 && !contractsPossible) {
     console.error(`Error: no generatable message schemas found in ${documentPath}. Every message either declares no payload/headers or uses a non-JSON-Schema schemaFormat (see warnings above).`);
     process.exit(1);
   }
@@ -270,8 +279,11 @@ const runAsyncApi = async (config, documentPath, outputDir) => {
   await ensureOutputDir(outputDir);
   const helpersMode = resolveHelpersMode(config, outputDir);
   const sharedHelpers = /* @__PURE__ */ new Map();
-  const writer = await createOutputWriter(outputDir, config.force);
+  const writer = await createOutputWriter(outputDir);
   const exampleTasks = [];
+  const contractIssues = [];
+  let contractMessageCount = 0;
+  let contractChannelCount = 0;
   const stageAll = async () => {
     for (const extracted of schemas) {
       const { subDir, rootTypeName, schema } = extracted;
@@ -297,15 +309,40 @@ ${subDir}/ (root type: ${rootTypeName})`);
     for (const [filename, content] of sharedHelpers) {
       await writer.stage(filename, content);
     }
+    if (config.messageContracts) {
+      const contracts = await emitMessageContracts({
+        model,
+        writer,
+        bannerPrefix: config.banner ? resolveBanner(config.banner) : "",
+        ...config.discriminator !== void 0 ? { discriminator: config.discriminator } : {}
+      });
+      contractIssues.push(...contracts.issues);
+      contractMessageCount = contracts.messageCount;
+      contractChannelCount = contracts.channelCount;
+    }
   };
   const writtenTsFiles = await commitOrDiscard(writer, stageAll);
   for (const filename of writtenTsFiles)
     console.log(`Generated: ${filename}`);
+  if (config.messageContracts) {
+    for (const issue of contractIssues) {
+      console.warn(`Warning: ${issue.path}: ${issue.message}`);
+    }
+  }
+  if (writtenTsFiles.length === 0) {
+    console.error(`Error: nothing was generated from ${documentPath}. No message declares a payload the generators can use, and no channel projected onto a contract (see the warnings above).`);
+    process.exit(1);
+  }
+  if (config.messageContracts) {
+    console.log(`
+Message contracts: ${contractMessageCount} message(s) across ${contractChannelCount} channel(s)`);
+    reportContractsPeer(outputDir);
+  }
   if (exampleTasks.length > 0) {
     await runExamples(config, outputDir, exampleTasks);
   }
   if (config.build) {
-    await buildOutput(outputDir, writtenTsFiles, config.typesOnly);
+    await buildOutput(outputDir, writtenTsFiles.filter((file) => !file.startsWith(`${CONTRACTS_DIR}/`)), config.typesOnly);
   } else {
     console.log(`
 Total files generated: ${writtenTsFiles.length}`);
@@ -348,6 +385,9 @@ const run = async () => {
     console.error("Error: provide only one of --out-dir or --out-file, not both.");
     process.exit(1);
   }
+  if (config.force) {
+    console.warn("Warning: --force is deprecated and does nothing; generated files always replace what is at their path.");
+  }
   if (config.rootType !== void 0 && !ROOT_TYPE_PATTERN.test(config.rootType)) {
     console.error(`Error: invalid --root-type "${config.rootType}". Expected a TypeScript identifier (letters, digits, _ or $, not starting with a digit).`);
     process.exit(1);
@@ -385,6 +425,23 @@ const run = async () => {
       console.error("Error: --export applies to module inputs (typebox, zod, ...); an AsyncAPI document has no exports.");
       process.exit(1);
     }
+  } else if (config.messageContracts) {
+    console.error("Error: --message-contracts requires --input asyncapi; there are no channels to project otherwise.");
+    process.exit(1);
+  }
+  if (config.messageContracts && config.typesOnly) {
+    console.error("Error: --message-contracts cannot be combined with --types-only, which emits no runtime code.");
+    process.exit(1);
+  }
+  if (config.discriminator !== void 0) {
+    if (!config.messageContracts) {
+      console.error("Error: --discriminator only applies to --message-contracts. Add --message-contracts, or drop it.");
+      process.exit(1);
+    }
+    if (!DISCRIMINATOR_PATTERN.test(config.discriminator)) {
+      console.error(`Error: invalid --discriminator "${config.discriminator}". Expected a property name of letters, digits, _, $ or -, not starting with a digit.`);
+      process.exit(1);
+    }
   }
   if (config.outFile) {
     if (!config.typesOnly) {

package/dist/create-output-writer.d.ts

@@ -3,22 +3,21 @@
  * final location under a temporary name, and only once the whole set is on disk
  * are the temporaries renamed into place.
  *
- * Two failure modes drive the design:
+ * The failure mode it exists for is **partial trees**. Writing straight to the
+ * final paths meant a failure halfway through (a `_helpers` path occupied by a
+ * regular file, a full disk) left some generated files behind and others missing
+ * — a tree that compiles against a schema that no longer exists. Staging first
+ * means the run either lands completely or leaves the destination as it found it.
+ * Renaming is not one atomic operation across the whole set, but every rename
+ * happens after all the risky work (generating, creating directories, writing
+ * bytes) has already succeeded, so it is the cheapest place to get the guarantee.
  *
- * 1. **Partial trees.** Writing straight to the final paths meant a failure
- *    halfway through (a `_helpers` path occupied by a regular file, a full disk)
- *    left some generated files behind and others missing — a tree that compiles
- *    against a schema that no longer exists. Staging first means the run either
- *    lands completely or leaves the destination as it found it. Renaming is not
- *    one atomic operation across the whole set, but every rename happens after
- *    all the risky work (generating, creating directories, writing bytes) has
- *    already succeeded, so it is the cheapest place to get the guarantee.
- * 2. **Clobbering hand-written files.** A generated name can collide with a file
- *    the user wrote (`index.ts` is the common one), which used to be overwritten
- *    without a word — and then, under `--build`, deleted along with the other
- *    intermediate sources. A file is only replaced when a previous run claimed it
- *    (see {@link MANIFEST_FILENAME}) or `--force` says so, and `--build` is only
- *    ever handed the paths this run actually committed.
+ * A generated path that already exists is simply replaced. The writer keeps no
+ * record of what it produced last time: an output directory is generated output,
+ * and version control is where a user sees — and reverts — a replacement they did
+ * not want. What the writer still guarantees is that `--build` only ever deletes
+ * intermediate sources this run committed, so nothing that was already sitting in
+ * the output directory is removed.
  */
 export type OutputWriter = {
     /**
@@ -34,7 +33,10 @@ export type OutputWriter = {
 /**
  * Creates an {@link OutputWriter} rooted at `rootDir`.
  *
+ * Still async with nothing to await: it read the previous run's manifest here
+ * until that was removed, and every call site already awaits it. Keeping the
+ * signature leaves room for setup that does need I/O.
+ *
  * @param rootDir - Output root. Every write must resolve inside it.
- * @param force - Overwrite pre-existing files instead of refusing (`--force`).
  */
-export declare const createOutputWriter: (rootDir: string, force?: boolean) => Promise<OutputWriter>;
+export declare const createOutputWriter: (rootDir: string) => Promise<OutputWriter>;

package/dist/create-output-writer.js

@@ -1,23 +1,8 @@
-import { readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { rename, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve, sep } from "node:path";
 import { ensureOutputDir } from "./ensure-output-dir.js";
-const MANIFEST_FILENAME = ".mjst-manifest.json";
-const pathExists = async (path) => stat(path).then(() => true, () => false);
-const readManifest = async (root) => {
-  const raw = await readFile(join(root, MANIFEST_FILENAME), "utf-8").catch(() => void 0);
-  if (raw === void 0)
-    return /* @__PURE__ */ new Set();
-  try {
-    const parsed = JSON.parse(raw);
-    const files = Array.isArray(parsed.files) ? parsed.files : [];
-    return new Set(files.filter((file) => typeof file === "string").map((file) => resolve(root, file)));
-  } catch {
-    return /* @__PURE__ */ new Set();
-  }
-};
-const createOutputWriter = async (rootDir, force = false) => {
+const createOutputWriter = async (rootDir) => {
   const root = resolve(rootDir);
-  const owned = await readManifest(root);
   const staged = [];
   const stamp = `${process.pid}-${Date.now().toString(36)}`;
   const stage = async (relativePath, content) => {
@@ -25,9 +10,6 @@ const createOutputWriter = async (rootDir, force = false) => {
     if (targetPath !== root && !targetPath.startsWith(root + sep)) {
       throw new Error(`Refusing to write "${relativePath}": it resolves outside the output directory ${root}.`);
     }
-    if (!force && !owned.has(targetPath) && await pathExists(targetPath)) {
-      throw new Error(`Refusing to overwrite ${targetPath}: it already exists and was not generated by mjst. Move it aside, choose another output directory, or pass --force to overwrite it.`);
-    }
     const tempPath = `${targetPath}.mjst-${stamp}-${staged.length}.tmp`;
     await ensureOutputDir(dirname(targetPath));
     await writeFile(tempPath, content, "utf-8");
@@ -36,12 +18,6 @@ const createOutputWriter = async (rootDir, force = false) => {
   const commit = async () => {
     for (const file of staged) {
       await rename(file.tempPath, file.targetPath);
-      owned.add(file.targetPath);
-    }
-    if (staged.length > 0) {
-      const files = [...owned].map((path) => relative(root, path)).sort();
-      await writeFile(join(root, MANIFEST_FILENAME), `${JSON.stringify({ version: 1, files }, null, 2)}
-`, "utf-8");
     }
     return staged.map((file) => file.relativePath);
   };

package/dist/detect-helpers-mode.d.ts

@@ -3,13 +3,8 @@
  * package (`'package'`) or ship the helper sources alongside them (`'embedded'`).
  *
  * We select `'package'` only when `@amritk/helpers` is a *declared* dependency
- * (dependencies / devDependencies / peer / optional) of the target project's
- * nearest `package.json` above `outputDir`. Merely being *resolvable* is not
- * enough: under npm/bun's hoisted layouts `@amritk/helpers` can sit in
- * `node_modules` purely as a transitive dependency of `@amritk/mjst`, which
- * makes `import '@amritk/helpers/...'` work locally but break under
- * pnpm/isolated installs where undeclared packages are not reachable. Requiring
- * a declaration keeps auto-detected `'package'` output portable across install
- * layouts; everything else falls back to the self-contained `'embedded'` mode.
+ * of the target project's nearest `package.json` above `outputDir` — see
+ * {@link isDependencyDeclared} for why merely being resolvable is not enough.
+ * Everything else falls back to the self-contained `'embedded'` mode.
  */
 export declare const detectHelpersMode: (outputDir: string) => 'package' | 'embedded';

package/dist/detect-helpers-mode.js

@@ -1,32 +1,5 @@
-import { readFileSync } from "node:fs";
-import { dirname, join, parse as parsePath, resolve } from "node:path";
-const readDeclaredDeps = (packageJsonPath) => {
-  try {
-    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
-    return /* @__PURE__ */ new Set([
-      ...Object.keys(pkg.dependencies ?? {}),
-      ...Object.keys(pkg.devDependencies ?? {}),
-      ...Object.keys(pkg.peerDependencies ?? {}),
-      ...Object.keys(pkg.optionalDependencies ?? {})
-    ]);
-  } catch {
-    return void 0;
-  }
-};
-const detectHelpersMode = (outputDir) => {
-  let dir = resolve(outputDir);
-  const { root } = parsePath(dir);
-  while (true) {
-    const declared = readDeclaredDeps(join(dir, "package.json"));
-    if (declared) {
-      return declared.has("@amritk/helpers") ? "package" : "embedded";
-    }
-    if (dir === root)
-      break;
-    dir = dirname(dir);
-  }
-  return "embedded";
-};
+import { isDependencyDeclared } from "./is-dependency-declared.js";
+const detectHelpersMode = (outputDir) => isDependencyDeclared(outputDir, "@amritk/helpers") ? "package" : "embedded";
 export {
   detectHelpersMode
 };

package/dist/emit-examples.d.ts

@@ -11,10 +11,9 @@ export type EmitExamplesOptions = {
     /**
      * The run's writer, rooted at the output destination. Examples used to be
      * written straight to disk with `mkdir` + `writeFile`, which meant the one
-     * output tree mjst emits that skipped the ownership check — a hand-written
-     * `examples/index.ts` was overwritten without a word. Taking the writer instead
-     * of a directory makes that impossible to reintroduce: there is no path here
-     * that does not go through staging, the manifest, and `--force`.
+     * output tree mjst emits that skipped staging entirely — a failure part-way
+     * through left a half-written `examples/` tree behind. Taking the writer
+     * instead of a directory makes that impossible to reintroduce.
      */
     readonly writer: OutputWriter;
     /**

package/dist/emit-message-contracts.d.ts

@@ -0,0 +1,47 @@
+import type { AsyncApiModel, ExtractionIssue } from '@amritk/asyncapi';
+import type { OutputWriter } from './create-output-writer.js';
+/** Subdirectory of the output root the contract modules land in. */
+export declare const CONTRACTS_DIR = "contracts";
+/** The package the generated modules import `defineMessages` from. */
+export declare const CONTRACTS_PEER = "@amritk/api";
+export type EmitMessageContractsOptions = {
+    readonly model: AsyncApiModel;
+    readonly writer: OutputWriter;
+    /** Fallback discriminator for channels that do not declare one (`--discriminator`). */
+    readonly discriminator?: string;
+    /** Header comment prepended to each file, when `--banner` asked for one. */
+    readonly bannerPrefix?: string;
+};
+export type EmitMessageContractsResult = {
+    /** Paths staged on the writer, relative to its root, in the order they were staged. */
+    readonly files: readonly string[];
+    /** Everything a channel could not project, for the caller to warn about. */
+    readonly issues: readonly ExtractionIssue[];
+    /** How many messages made it into a contract, across every channel. */
+    readonly messageCount: number;
+    /** How many channels got a contract module (the barrel is not one of them). */
+    readonly channelCount: number;
+};
+/**
+ * Projects every channel of an AsyncAPI document onto a `defineMessages`
+ * contract and stages one module per channel under `contracts/`, plus a barrel.
+ *
+ * These are *runtime values*, not types — which is why the flag that asks for
+ * them refuses `--types-only`, and why the generated files import
+ * `@amritk/api`. That import is the consumer's dependency to satisfy: the CLI
+ * needs the package to have been written, not to be installed where the output
+ * lands, and pinning it as a hard dependency of generated code would drag a
+ * server framework into projects that only wanted the schemas.
+ *
+ * A channel that projects to nothing (every message skipped, or a channel with
+ * no messages at all) is not written: an exported contract with no messages
+ * accepts no frame in either direction, which is a trap rather than a document.
+ * The reasons come back in {@link EmitMessageContractsResult.issues}.
+ *
+ * The barrel's specifiers are always `.ts`, ignoring `--import-ext`: these
+ * modules are the one part of the output `--build` leaves uncompiled (they
+ * import the `@amritk/api` peer, and handing tsc an import the output's project
+ * has not installed would fail the parsers' compilation too). A `.js` specifier
+ * would then name a file this run never wrote.
+ */
+export declare const emitMessageContracts: (options: EmitMessageContractsOptions) => Promise<EmitMessageContractsResult>;

package/dist/emit-message-contracts.js

@@ -0,0 +1,97 @@
+import { buildChannelContract, sanitizeToken } from "@amritk/asyncapi";
+const CONTRACTS_DIR = "contracts";
+const CONTRACTS_PEER = "@amritk/api";
+const renderDirection = (name, direction, indent) => {
+  const entries = Object.entries(direction).map(([messageName, schema]) => {
+    const literal = JSON.stringify(schema, null, 2).replaceAll("\n", `
+${indent}  `);
+    return `${indent}  ${JSON.stringify(messageName)}: ${literal} as const,`;
+  });
+  return `${indent}${name}: {
+${entries.join("\n")}
+${indent}},`;
+};
+const renderChannelModule = (contract, channel) => {
+  const directions = [
+    Object.keys(contract.clientToServer).length > 0 ? renderDirection("clientToServer", contract.clientToServer, "  ") : void 0,
+    Object.keys(contract.serverToClient).length > 0 ? renderDirection("serverToClient", contract.serverToClient, "  ") : void 0
+  ].filter((entry) => entry !== void 0);
+  const address = channel.address !== void 0 && channel.address !== channel.key ? ` (${channel.address})` : "";
+  return [
+    "/**",
+    ` * Message contract for the AsyncAPI channel \`${channel.key}\`${address}.`,
+    " *",
+    ` * Requires \`${CONTRACTS_PEER}\` at runtime \u2014 it is a peer dependency of this`,
+    " * generated code, not of the mjst CLI that wrote it. Install it in the project",
+    " * that imports this file.",
+    " *",
+    " * Message keys are the wire discriminator values: a frame",
+    ` * \`{ "${contract.discriminator}": "<key>", ... }\` selects its schema by that key, and the`,
+    " * tag is removed before the payload below is validated \u2014 which is why no",
+    " * payload here declares it.",
+    " */",
+    `import { defineMessages } from '${CONTRACTS_PEER}'`,
+    "",
+    `export const ${contract.exportName} = defineMessages({`,
+    `  discriminator: '${contract.discriminator}',`,
+    ...directions,
+    "})",
+    ""
+  ].join("\n");
+};
+const emitMessageContracts = async (options) => {
+  const { model, writer, bannerPrefix = "" } = options;
+  const issues = [];
+  const files = [];
+  const barrel = [];
+  const takenTokens = /* @__PURE__ */ new Set();
+  const takenExports = /* @__PURE__ */ new Set();
+  let messageCount = 0;
+  for (const channel of model.channels) {
+    const contract = buildChannelContract(channel, {
+      ...options.discriminator !== void 0 ? { discriminator: options.discriminator } : {}
+    });
+    issues.push(...contract.issues);
+    const count = Object.keys(contract.clientToServer).length + Object.keys(contract.serverToClient).length;
+    if (count === 0) {
+      issues.push({
+        path: `#/channels/${channel.key}`,
+        message: "no message projected onto a contract; no contract module written for this channel"
+      });
+      continue;
+    }
+    messageCount += count;
+    const token = claim(sanitizeToken(channel.key, "channel"), takenTokens, "-");
+    const exportName = claim(contract.exportName, takenExports, "");
+    if (exportName !== contract.exportName) {
+      issues.push({
+        path: `#/channels/${channel.key}`,
+        message: `contract export name "${contract.exportName}" already claimed; using "${exportName}"`
+      });
+    }
+    const filename = `${CONTRACTS_DIR}/${token}.ts`;
+    await writer.stage(filename, bannerPrefix + renderChannelModule({ ...contract, exportName }, channel));
+    files.push(filename);
+    barrel.push(`export { ${exportName} } from './${token}.ts'`);
+  }
+  if (barrel.length > 0) {
+    const filename = `${CONTRACTS_DIR}/index.ts`;
+    await writer.stage(filename, `${bannerPrefix + barrel.join("\n")}
+`);
+    files.push(filename);
+  }
+  return { files, issues, messageCount, channelCount: barrel.length };
+};
+const claim = (base, taken, separator) => {
+  let candidate = base;
+  for (let n = 2; taken.has(candidate); n++) {
+    candidate = `${base}${separator}${n}`;
+  }
+  taken.add(candidate);
+  return candidate;
+};
+export {
+  CONTRACTS_DIR,
+  CONTRACTS_PEER,
+  emitMessageContracts
+};

package/dist/help-text.d.ts

@@ -4,4 +4,4 @@
  * documents these flags (config.schema.json) is not shipped in the published
  * package; the help-text test cross-checks that every flag is listed.
  */
-export declare const HELP_TEXT = "mjst \u2014 generate TypeScript parsers and type definitions from JSON Schemas\n\nUsage:\n  mjst --schema <path> --out-dir <dir> [options]\n  mjst --schema-dir <dir> --out-dir <dir> [options]\n  mjst --schema <path> --out-file <file> --types-only [options]\n\nSubcommands (each with its own flags and --help):\n  mjst lint <files>                       Lint JSON/YAML documents against a ruleset\n  mjst compile-api <module> --out <file>  Compile @amritk/api route contracts into a fetch-handler module\n\nInput:\n  --schema <path>       Schema to process: a JSON Schema file, or a module when --input is set\n  --schema-dir <dir>    Directory of JSON Schemas, processed recursively (instead of --schema)\n  --input <format>      Schema source format: json (default), typebox, zod, valibot, effect, avro,\n                        or asyncapi (an AsyncAPI 2.x/3.0 document, JSON or YAML)\n  --export <name>       Which export of the schema module to use when --input names a module format\n\nOutput:\n  --out-dir <dir>       Output directory for the generated files\n  --out-file <file>     Single-file output instead of a directory (requires --types-only)\n  --types-only          Generate type definitions only, without parser functions\n  --validators          Also emit validateX/isX validators into a validators/ subdir\n  --examples            Also emit fast-check arbitraries + example values under examples/\n  --build               Compile the generated files to .js/.d.ts (implies --import-ext js)\n  --force               Overwrite pre-existing files in the output destination\n  --import-ext <ext>    Extension on generated relative imports: ts (default) or js\n  --helpers <mode>      Runtime helpers: package or embedded (default: auto-detect from package.json)\n  --root-type <name>    Root type name for a single --schema run (default: schema title or filename)\n  --type-suffix <s>     Suffix appended to every $ref-derived type name\n  --banner [text]       Prepend a header comment to every generated file\n  --readonly            Emit deeply readonly type definitions\n\nValidation:\n  --strict              Throw on type/shape mismatches instead of coercing to defaults\n  --strip-unknown       Silently drop undeclared input keys at every nesting level\n  --case-insensitive    Normalize mis-cased enum/const strings to their exact casing\n  --log-warnings        console.warn on input keys not declared in the schema\n  --unknown-keys <s>    How closed objects are proven free of undeclared keys:\n                        count-keys (default, fastest on Bun) or count-enumerable (fastest on Node)\n\nReference resolution:\n  --resolve-remote      Fetch http(s) $refs while resolving cross-file/remote refs (off by default)\n  --allowed-hosts <h>   Restrict remote $ref fetches to these hosts (comma-separated; implies --resolve-remote)\n  --allow-private-hosts Permit remote $refs to private/loopback hosts (SSRF guard, off by default)\n  --allowed-roots <d>   Extra directories a local $ref may resolve into, on top of the schema's own\n                        (comma-separated; relative to the current directory)\n\nMisc:\n  --config <path>       JSON config file with the same keys; CLI flags take precedence\n  --version, -v         Print the CLI version\n  --help, -h            Print this help\n\nDocs: https://github.com/amritk/mjst/tree/main/packages/cli#readme\n";
+export declare const HELP_TEXT = "mjst \u2014 generate TypeScript parsers and type definitions from JSON Schemas\n\nUsage:\n  mjst --schema <path> --out-dir <dir> [options]\n  mjst --schema-dir <dir> --out-dir <dir> [options]\n  mjst --schema <path> --out-file <file> --types-only [options]\n\nSubcommands (each with its own flags and --help):\n  mjst lint <files>                       Lint JSON/YAML documents against a ruleset\n  mjst compile-api <module> --out <file>  Compile @amritk/api route contracts into a fetch-handler module\n\nInput:\n  --schema <path>       Schema to process: a JSON Schema file, or a module when --input is set\n  --schema-dir <dir>    Directory of JSON Schemas, processed recursively (instead of --schema)\n  --input <format>      Schema source format: json (default), typebox, zod, valibot, effect, avro,\n                        or asyncapi (an AsyncAPI 2.x/3.0 document, JSON or YAML)\n  --export <name>       Which export of the schema module to use when --input names a module format\n\nOutput:\n  --out-dir <dir>       Output directory for the generated files\n  --out-file <file>     Single-file output instead of a directory (requires --types-only)\n  --types-only          Generate type definitions only, without parser functions\n  --validators          Also emit validateX/isX validators into a validators/ subdir\n  --examples            Also emit fast-check arbitraries + example values under examples/\n  --message-contracts   Also emit @amritk/api channel contracts under contracts/ (--input asyncapi only)\n  --discriminator <p>   Property naming which message a frame is, for --message-contracts (default: type)\n  --build               Compile the generated files to .js/.d.ts (implies --import-ext js)\n  --force               Deprecated; ignored (generated files always overwrite)\n  --import-ext <ext>    Extension on generated relative imports: ts (default) or js\n  --helpers <mode>      Runtime helpers: package or embedded (default: auto-detect from package.json)\n  --root-type <name>    Root type name for a single --schema run (default: schema title or filename)\n  --type-suffix <s>     Suffix appended to every $ref-derived type name\n  --banner [text]       Prepend a header comment to every generated file\n  --readonly            Emit deeply readonly type definitions\n\nValidation:\n  --strict              Throw on type/shape mismatches instead of coercing to defaults\n  --strip-unknown       Silently drop undeclared input keys at every nesting level\n  --case-insensitive    Normalize mis-cased enum/const strings to their exact casing\n  --log-warnings        console.warn on input keys not declared in the schema\n  --unknown-keys <s>    How closed objects are proven free of undeclared keys:\n                        count-keys (default, fastest on Bun) or count-enumerable (fastest on Node)\n\nReference resolution:\n  --resolve-remote      Fetch http(s) $refs while resolving cross-file/remote refs (off by default)\n  --allowed-hosts <h>   Restrict remote $ref fetches to these hosts (comma-separated; implies --resolve-remote)\n  --allow-private-hosts Permit remote $refs to private/loopback hosts (SSRF guard, off by default)\n  --allowed-roots <d>   Extra directories a local $ref may resolve into, on top of the schema's own\n                        (comma-separated; relative to the current directory)\n\nMisc:\n  --config <path>       JSON config file with the same keys; CLI flags take precedence\n  --version, -v         Print the CLI version\n  --help, -h            Print this help\n\nDocs: https://github.com/amritk/mjst/tree/main/packages/cli#readme\n";

package/dist/help-text.js

@@ -22,8 +22,10 @@ Output:
   --types-only          Generate type definitions only, without parser functions
   --validators          Also emit validateX/isX validators into a validators/ subdir
   --examples            Also emit fast-check arbitraries + example values under examples/
+  --message-contracts   Also emit @amritk/api channel contracts under contracts/ (--input asyncapi only)
+  --discriminator <p>   Property naming which message a frame is, for --message-contracts (default: type)
   --build               Compile the generated files to .js/.d.ts (implies --import-ext js)
-  --force               Overwrite pre-existing files in the output destination
+  --force               Deprecated; ignored (generated files always overwrite)
   --import-ext <ext>    Extension on generated relative imports: ts (default) or js
   --helpers <mode>      Runtime helpers: package or embedded (default: auto-detect from package.json)
   --root-type <name>    Root type name for a single --schema run (default: schema title or filename)

package/dist/is-dependency-declared.d.ts

@@ -0,0 +1,17 @@
+/**
+ * True when `packageName` is a *declared* dependency (dependencies /
+ * devDependencies / peer / optional) of the nearest readable `package.json` at
+ * or above `fromDir`.
+ *
+ * Declared, not merely resolvable: under npm/bun's hoisted layouts a package can
+ * sit in `node_modules` purely as a transitive dependency of `@amritk/mjst`,
+ * which makes importing it work locally but break under pnpm/isolated installs
+ * where undeclared packages are not reachable. Generated code has to survive
+ * both, so the question worth asking is whether the *project* asked for the
+ * package, not whether this machine happens to have it.
+ *
+ * Only the nearest package.json is consulted. A workspace root above it may well
+ * declare the package, but a nested package that does not declare it cannot rely
+ * on the hoist — which is exactly the case this is meant to catch.
+ */
+export declare const isDependencyDeclared: (fromDir: string, packageName: string) => boolean;

package/dist/is-dependency-declared.js

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import { dirname, join, parse as parsePath, resolve } from "node:path";
+const readDeclaredDeps = (packageJsonPath) => {
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    return /* @__PURE__ */ new Set([
+      ...Object.keys(pkg.dependencies ?? {}),
+      ...Object.keys(pkg.devDependencies ?? {}),
+      ...Object.keys(pkg.peerDependencies ?? {}),
+      ...Object.keys(pkg.optionalDependencies ?? {})
+    ]);
+  } catch {
+    return void 0;
+  }
+};
+const isDependencyDeclared = (fromDir, packageName) => {
+  let dir = resolve(fromDir);
+  const { root } = parsePath(dir);
+  while (true) {
+    const declared = readDeclaredDeps(join(dir, "package.json"));
+    if (declared)
+      return declared.has(packageName);
+    if (dir === root)
+      break;
+    dir = dirname(dir);
+  }
+  return false;
+};
+export {
+  isDependencyDeclared
+};

package/dist/load-config.js

@@ -30,6 +30,8 @@ const loadConfig = async (configPath) => {
     ...typeof obj["validators"] === "boolean" && { validators: obj["validators"] },
     ...typeof obj["typesOnly"] === "boolean" && { typesOnly: obj["typesOnly"] },
     ...typeof obj["examples"] === "boolean" && { examples: obj["examples"] },
+    ...typeof obj["messageContracts"] === "boolean" && { messageContracts: obj["messageContracts"] },
+    ...typeof obj["discriminator"] === "string" && { discriminator: obj["discriminator"] },
     ...typeof obj["build"] === "boolean" && { build: obj["build"] },
     ...typeof obj["force"] === "boolean" && { force: obj["force"] },
     ...typeof obj["logWarnings"] === "boolean" && { logWarnings: obj["logWarnings"] },

package/dist/parse-cli-args.js

@@ -5,6 +5,7 @@ const BOOLEAN_KEYS = /* @__PURE__ */ new Set([
   "typesOnly",
   "validators",
   "examples",
+  "messageContracts",
   "build",
   "force",
   "logWarnings",
@@ -22,6 +23,7 @@ const VALUE_KEYS = /* @__PURE__ */ new Set([
   "outFile",
   "input",
   "export",
+  "discriminator",
   "helpers",
   "typeSuffix",
   "importExt",
@@ -74,6 +76,9 @@ const assignValue = (config, key, value) => {
     case "rootType":
       config.rootType = value;
       return true;
+    case "discriminator":
+      config.discriminator = value;
+      return true;
     case "input": {
       const parsed = parseInputValue(value);
       if (!parsed) {
@@ -120,6 +125,9 @@ const assignBoolean = (config, key, value) => {
     case "examples":
       config.examples = value;
       return true;
+    case "messageContracts":
+      config.messageContracts = value;
+      return true;
     case "build":
       config.build = value;
       return true;

package/dist/validate-config.js

@@ -10,6 +10,8 @@ const CONFIG_KEYS = {
   typesOnly: { type: "boolean" },
   validators: { type: "boolean" },
   examples: { type: "boolean" },
+  messageContracts: { type: "boolean" },
+  discriminator: { type: "string" },
   build: { type: "boolean" },
   force: { type: "boolean" },
   logWarnings: { type: "boolean" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "engines": {
@@ -49,13 +49,13 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@amritk/adapters": "^0.6.0",
+    "@amritk/adapters": "^0.6.1",
     "@amritk/api": "^0.16.3",
-    "@amritk/asyncapi": "^0.1.0",
-    "@amritk/generate-examples": "^0.8.2",
-    "@amritk/generate-parsers": "^0.21.0",
-    "@amritk/generate-validators": "^0.16.0",
-    "@amritk/helpers": "^0.19.0",
+    "@amritk/asyncapi": "^0.2.0",
+    "@amritk/generate-examples": "^0.8.3",
+    "@amritk/generate-parsers": "^0.22.0",
+    "@amritk/generate-validators": "^0.16.1",
+    "@amritk/helpers": "^0.20.0",
     "@amritk/lint": "^0.5.3",
     "@amritk/resolve-refs": "^0.7.1",
     "@amritk/yaml": "^0.7.2",