@mettlecast/domain-cli 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## Unreleased
+
+### feat(#2132): Policy-as-data refactor (manifest v2)
+
+**Manifest schema bumped to v2.** Each `ManifestFileEntry` now carries a `policy` field:
+
+- `owned` — scaffold-managed, always overwritten on upgrade, blocked by pre-commit hook
+- `tracked` — scaffold-managed with drift detection; user edits raise a conflict file on upgrade  
+- `seed` — installed once at scaffold init; user owns the file after that, never overwritten
+
+**Automatic migration:** On first run of any `tib` command that reads the manifest, v1 entries (missing `policy`) are automatically upgraded using path-based inference:
+- Paths under `infra/`, `.mc/infra/`, matching `mc-deploy.yml`, or `.github/workflows/` → `owned`
+- Frontend seed page paths (`frontend/src/pages/auth/`, `account/`, `shell/`, `_errors/`, `layouts/`, `styles/brand.css`) → `seed`
+- Everything else → `tracked`
+
+No behavioural change to upgrade or add-module for existing projects.

package/README.md

@@ -0,0 +1,133 @@
+# @mettlecast/domain-cli
+
+Local developer toolchain for TIB Domain Module projects. Provides build, validate, test, and dev subcommands.
+
+## Install
+
+Install as a dev dependency:
+
+```bash
+npm install --save-dev @mettlecast/domain-cli
+```
+
+Then add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "domain:build": "mc-domain-module build ./src/domain",
+    "domain:validate": "mc-domain-module validate ./src/domain",
+    "domain:test": "mc-domain-module test ./src/domain charge-handler --fixture ./fixtures/charge.json",
+    "domain:dev": "mc-domain-module dev ./src/domain"
+  }
+}
+```
+
+## Commands
+
+### Query & Development
+
+| Command | Description | Output |
+|---|---|---|
+| `mc-domain-module build <domain>` | Load domain handlers via tsx, walk registry, emit `.mc/domain-registry.json` | Registry JSON at `--out <path>` or default location |
+| `mc-domain-module validate <domain>` | Build registry and lint (semver ranges, 90-day lifecycle rule, enforcement config) | Exits 1 if validation fails (CI gate) |
+| `mc-domain-module test <domain> <handler-id> --fixture <path>` | Invoke handler with fixture data, hydrate local `DomainContext` stub | Handler result printed to stdout |
+| `mc-domain-module dev <domain>` | Start Fastify HTTP server on port 3000 (or `--port <n>`) simulating API Gateway | All `defineApi()` handlers mounted and callable via HTTP |
+
+### Scaffolding
+
+New domains and handlers:
+
+**Add a new domain:**
+```bash
+npx mc-domain-module add-domain payments [--tenancy required]
+```
+Creates `domains/payments/` with `domain.config.ts`, skeleton API, and event definitions.
+
+**Add an API endpoint to a domain:**
+```bash
+npx mc-domain-module add-api payments charge-api [--method POST] [--tenancy required]
+```
+Creates `domains/payments/api/charge-api.ts` with a `defineApi` v1 stub.
+
+**Add an event subscriber to a domain:**
+```bash
+npx mc-domain-module add-subscriber payments charge-completed-subscriber --event payment.completed
+```
+Creates `domains/payments/subscribers/charge-completed-subscriber.ts` listening to `payment.completed` event.
+
+**Add a flow:**
+```bash
+npx mc-domain-module add-flow onboard-user
+```
+Scaffolds `flows/onboard-user.ts` with a constrained-step skeleton. Flows can ONLY orchestrate domain primitives (`domain-action` / `domain-api` / `domain-event` / flow-control built-ins) — no raw Lambda ARNs or arbitrary Step Functions states allowed.
+
+### Validation & Diagnostics
+
+**Run structural checks:**
+```bash
+npx mc-domain-module doctor              # human-readable table of all checks
+npx mc-domain-module doctor --strict     # exit 1 on any FAIL (CI mode)
+npx mc-domain-module doctor --json       # machine-readable JSON output
+```
+
+**Verify infra/modules/ integrity:**
+```bash
+npx mc-domain-module check-hashes
+```
+Verifies that `infra/modules/` files have not been hand-edited since the last scaffold. Compares current SHA256 against `.mc/modules-hashes.json` manifest. Reports drifted, missing, and unexpected files. Re-scaffold to legitimately update `infra/modules/`.
+
+### Registry Building
+
+**Build domain registries:**
+```bash
+npx mc-domain-module build domains/<id>
+```
+Loads domain handlers, walks registry, and emits `.mc/<id>-registry.json` and `.mc/actions-types.d.ts`. CI runs this before `cdk deploy domain-<id>`.
+
+**Build flow registries:**
+```bash
+npx mc-domain-module build-flows --out .mc/flows-registry.json
+```
+Walks `flows/*.{ts,json}`, validates each flow definition, and emits `.mc/flows-registry.json`. CI runs this before `cdk deploy` of the flows stack.
+
+## Typical Workflow
+
+1. **Develop locally**
+   ```bash
+   npm run domain:dev
+   # Open http://localhost:3000/charge with curl
+   ```
+
+2. **Test a handler**
+   ```bash
+   npm run domain:test charge-handler --fixture ./fixtures/charge.json
+   ```
+
+3. **Validate before commit**
+   ```bash
+   npm run domain:validate
+   ```
+
+4. **Build for deployment**
+   ```bash
+   npm run domain:build
+   # .mc/domain-registry.json is ready for CDK or contracts generation
+   ```
+
+## Options
+
+**`build`:**
+- `--out <path>` — Override output file path (default: `.mc/domain-registry.json`)
+
+**`dev`:**
+- `--port <n>` — Listen port (default: `3000`)
+
+**`test`:**
+- `--fixture <path>` — Required. JSON file with shape `{ event?: unknown, ctx?: Partial<DomainContext> }`
+
+## See Also
+
+- `@mettlecast/domain-runtime` — handler definitions
+- `@mettlecast/domain-cdk-packer` — CDK infrastructure
+- `@mettlecast/eslint-plugin-domain-module` — linting rules

package/dist/builder/build-registry.d.ts

@@ -0,0 +1,20 @@
+import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+/**
+ * Result of a registry build operation.
+ */
+export interface BuildResult {
+    /** The assembled DomainRegistry ready for serialisation. */
+    registry: DomainRegistry;
+    /** Any non-fatal warnings encountered during the build. */
+    warnings: string[];
+}
+/**
+ * Build a DomainRegistry from a domain source directory.
+ * Walks the conventional directory structure, loads each primitive definition
+ * file via the tsx child-process loader, and assembles the registry snapshot.
+ * Zod schema fields are omitted in Phase 1e (schema extraction is v1.x scope).
+ * @param domainRoot - Absolute path to the domain root directory.
+ * @returns BuildResult containing the assembled registry and any warnings.
+ * @throws If domain.config.ts is missing or does not export a 'domain' primitive.
+ */
+export declare function buildRegistry(domainRoot: string): Promise<BuildResult>;

package/dist/builder/build-registry.js

@@ -0,0 +1,178 @@
+import { relative, resolve } from 'node:path';
+import { walkDomainDir } from '../utils/file-helpers.js';
+import { loadModuleExports } from './load-module.js';
+/** Returns true if a value looks like a JSON Schema object (has a 'type' or '$schema' property). */
+function isJsonSchema(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) &&
+        ('type' in v || '$schema' in v || 'properties' in v);
+}
+/**
+ * Build a DomainRegistry from a domain source directory.
+ * Walks the conventional directory structure, loads each primitive definition
+ * file via the tsx child-process loader, and assembles the registry snapshot.
+ * Zod schema fields are omitted in Phase 1e (schema extraction is v1.x scope).
+ * @param domainRoot - Absolute path to the domain root directory.
+ * @returns BuildResult containing the assembled registry and any warnings.
+ * @throws If domain.config.ts is missing or does not export a 'domain' primitive.
+ */
+export async function buildRegistry(domainRoot) {
+    // Resolve to absolute path so downstream fs operations and tsx eval imports
+    // work correctly when the caller passes a relative path.
+    domainRoot = resolve(domainRoot);
+    const warnings = [];
+    const paths = await walkDomainDir(domainRoot);
+    if (!paths.domain) {
+        throw new Error(`buildRegistry: domain.config.ts not found in ${domainRoot}`);
+    }
+    async function load(filePath) {
+        try {
+            return await loadModuleExports(filePath);
+        }
+        catch (err) {
+            warnings.push(`Failed to load ${filePath}: ${String(err)}`);
+            return [];
+        }
+    }
+    function relPath(absPath) {
+        return relative(domainRoot, absPath);
+    }
+    function deployment(raw) {
+        return raw['deployment'];
+    }
+    const domainExports = await load(paths.domain);
+    const domainRaw = domainExports.find(e => e['_kind'] === 'domain');
+    if (!domainRaw) {
+        throw new Error(`buildRegistry: no 'domain' export found in ${paths.domain}`);
+    }
+    const domain = {
+        id: String(domainRaw['id']),
+        kind: 'domain',
+        name: String(domainRaw['name']),
+        tenancy: String(domainRaw['tenancy']),
+        defaultDeployment: deployment(domainRaw),
+    };
+    const [apiExports, webhookExports, subscriberExports, actionExports, scheduleExports, jobExports, integrationExports, eventExports] = await Promise.all([
+        Promise.all(paths.apis.map(load)),
+        Promise.all(paths.webhooks.map(load)),
+        Promise.all(paths.subscribers.map(load)),
+        Promise.all(paths.actions.map(load)),
+        Promise.all(paths.schedules.map(load)),
+        Promise.all(paths.jobs.map(load)),
+        Promise.all(paths.integrations.map(load)),
+        paths.publishes ? load(paths.publishes) : Promise.resolve([]),
+    ]);
+    const apis = paths.apis.flatMap((filePath, i) => (apiExports[i] ?? [])
+        .filter(e => e['_kind'] === 'api')
+        .map(e => {
+        const rawVersions = e['versions'];
+        const versionSnapshots = rawVersions
+            ? Object.entries(rawVersions).map(([ver, v]) => ({
+                version: ver,
+                requestSchema: isJsonSchema(v?.input) ? v.input : undefined,
+                responseSchema: isJsonSchema(v?.output) ? v.output : undefined,
+            }))
+            : [];
+        const latestVersion = versionSnapshots[versionSnapshots.length - 1];
+        return {
+            id: String(e['id']),
+            kind: 'api',
+            handlerFile: relPath(filePath),
+            path: String(e['path']),
+            method: typeof e['method'] === 'string' ? e['method'].toUpperCase() : 'ANY',
+            authType: e['auth']?.type ?? 'jwt',
+            description: typeof e['description'] === 'string' ? e['description'] : undefined,
+            deployment: deployment(e),
+            requestSchema: latestVersion?.requestSchema,
+            responseSchema: latestVersion?.responseSchema,
+            versions: versionSnapshots.length > 0 ? versionSnapshots : undefined,
+        };
+    }));
+    const webhooks = paths.webhooks.flatMap((filePath, i) => (webhookExports[i] ?? [])
+        .filter(e => e['_kind'] === 'webhook')
+        .map(e => ({
+        id: String(e['id']),
+        kind: 'webhook',
+        handlerFile: relPath(filePath),
+        path: String(e['path']),
+        provider: String(e['provider']),
+        hmacAlgorithm: e['verification']?.type,
+        hmacSecretRef: e['verification']?.secretRef,
+        deployment: deployment(e),
+    })));
+    const subscribers = paths.subscribers.flatMap((filePath, i) => (subscriberExports[i] ?? [])
+        .filter(e => e['_kind'] === 'subscriber')
+        .map(e => ({
+        id: String(e['id']),
+        kind: 'subscriber',
+        handlerFile: relPath(filePath),
+        event: String(e['event']),
+        semverRange: String(e['semverRange']),
+        concurrency: e['concurrency'],
+        deployment: deployment(e),
+    })));
+    const schedules = paths.schedules.flatMap((filePath, i) => (scheduleExports[i] ?? [])
+        .filter(e => e['_kind'] === 'schedule')
+        .map(e => ({
+        id: String(e['id']),
+        kind: 'schedule',
+        handlerFile: relPath(filePath),
+        cron: String(e['cron']),
+        enabled: Boolean(e['enabled'] ?? true),
+        deployment: deployment(e),
+    })));
+    const jobs = paths.jobs.flatMap((filePath, i) => (jobExports[i] ?? [])
+        .filter(e => e['_kind'] === 'job')
+        .map(e => ({
+        id: String(e['id']),
+        kind: 'job',
+        handlerFile: relPath(filePath),
+        maxRetries: Number(e['maxRetries'] ?? 3),
+        visibilityTimeoutSeconds: Number(e['visibilityTimeoutSeconds'] ?? 30),
+        deployment: deployment(e),
+    })));
+    const actions = paths.actions.flatMap((filePath, i) => (actionExports[i] ?? [])
+        .filter(e => e['_kind'] === 'action')
+        .map(e => ({
+        id: String(e['id']),
+        kind: 'action',
+        handlerFile: relPath(filePath),
+        visibility: String(e['visibility']),
+        idempotent: Boolean(e['idempotent'] ?? false),
+        description: typeof e['description'] === 'string' ? e['description'] : undefined,
+        deployment: deployment(e),
+        inputSchema: isJsonSchema(e['input']) ? e['input'] : undefined,
+        outputSchema: isJsonSchema(e['output']) ? e['output'] : undefined,
+    })));
+    const integrations = paths.integrations.flatMap((_filePath, i) => (integrationExports[i] ?? [])
+        .filter(e => e['_kind'] === 'integration')
+        .map(e => ({
+        id: String(e['id']),
+        kind: 'integration',
+        baseUrl: String(e['baseUrl']),
+    })));
+    const events = eventExports
+        .filter(e => e['_kind'] === 'event')
+        .map(e => ({
+        id: String(e['id']),
+        kind: 'event',
+        busName: 'default',
+        description: typeof e['description'] === 'string' ? e['description'] : undefined,
+        versions: isJsonSchema(e['schema'])
+            ? [{ version: Number(e['version'] ?? 1), schema: e['schema'] }]
+            : undefined,
+    }));
+    const registry = {
+        schemaVersion: '1',
+        domainRoot,
+        domain,
+        apis,
+        webhooks,
+        subscribers,
+        schedules,
+        jobs,
+        actions,
+        integrations,
+        events,
+    };
+    return { registry, warnings };
+}

package/dist/builder/build-types.d.ts

@@ -0,0 +1,10 @@
+import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+/**
+ * Generate a .d.ts file declaring typed `ctx.actions.call(actionId, input)`
+ * overrides for the union of actions across all registries. The generated
+ * file augments `@mettlecast/domain-runtime`'s ActionsProxy type.
+ *
+ * @param registries - Array of DomainRegistry objects to extract actions from.
+ * @returns A complete .d.ts file as a string, ready to write to disk.
+ */
+export declare function buildActionsTypes(registries: DomainRegistry[]): string;

package/dist/builder/build-types.js

@@ -0,0 +1,32 @@
+/**
+ * Generate a .d.ts file declaring typed `ctx.actions.call(actionId, input)`
+ * overrides for the union of actions across all registries. The generated
+ * file augments `@mettlecast/domain-runtime`'s ActionsProxy type.
+ *
+ * @param registries - Array of DomainRegistry objects to extract actions from.
+ * @returns A complete .d.ts file as a string, ready to write to disk.
+ */
+export function buildActionsTypes(registries) {
+    const overloads = [];
+    for (const reg of registries) {
+        for (const action of reg.actions) {
+            const fqn = `${reg.domain.id}.${action.id}`;
+            // Phase 1: use unknown for input/output
+            // TODO(#1787-Wave3): extract types from action.inputSchema / action.outputSchema via json-schema-to-typescript
+            overloads.push(`  call(actionId: '${fqn}', input?: unknown): Promise<unknown>;`);
+        }
+    }
+    return [
+        '// Generated by `mc-domain-module build` — DO NOT EDIT',
+        '// Source of truth: .mc/{domain-id}-registry.json files',
+        '',
+        `declare module '@mettlecast/domain-runtime' {`,
+        '  interface ActionsProxy {',
+        ...overloads,
+        '  }',
+        '}',
+        '',
+        'export {};',
+        '',
+    ].join('\n');
+}

package/dist/builder/load-domain-module-config.d.ts

@@ -0,0 +1,12 @@
+import type { DomainModuleConfig } from '@mettlecast/domain-runtime/types';
+/**
+ * Load and validate the domain module configuration from `.mc/domain-module.config.ts`.
+ *
+ * Uses the same tsx child-process loader as `loadModuleExports` to handle TypeScript.
+ * Falls back to `{ mode: 'optional' }` when the config file does not exist.
+ * Throws a descriptive error when the file exists but fails schema validation.
+ *
+ * @param projectRoot - Absolute path to the project root (directory containing `.mc/`).
+ * @returns Validated DomainModuleConfig.
+ */
+export declare function loadDomainModuleConfig(projectRoot: string): Promise<DomainModuleConfig>;

package/dist/builder/load-domain-module-config.js

@@ -0,0 +1,34 @@
+import { join } from 'node:path';
+import { access } from 'node:fs/promises';
+import { DomainModuleConfigSchema } from '@mettlecast/domain-runtime/types';
+import { loadModuleExports } from './load-module.js';
+const CONFIG_FILE = '.mc/domain-module.config.ts';
+/**
+ * Load and validate the domain module configuration from `.mc/domain-module.config.ts`.
+ *
+ * Uses the same tsx child-process loader as `loadModuleExports` to handle TypeScript.
+ * Falls back to `{ mode: 'optional' }` when the config file does not exist.
+ * Throws a descriptive error when the file exists but fails schema validation.
+ *
+ * @param projectRoot - Absolute path to the project root (directory containing `.mc/`).
+ * @returns Validated DomainModuleConfig.
+ */
+export async function loadDomainModuleConfig(projectRoot) {
+    const configPath = join(projectRoot, CONFIG_FILE);
+    try {
+        await access(configPath);
+    }
+    catch {
+        return { mode: 'optional' };
+    }
+    const exports = await loadModuleExports(configPath);
+    const raw = exports.find((e) => e._exportName === 'default' || e._exportName === 'config') ?? exports[0];
+    if (!raw) {
+        return { mode: 'optional' };
+    }
+    const parsed = DomainModuleConfigSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`Invalid domain-module.config.ts: ${parsed.error.issues.map((i) => i.message).join(', ')}`);
+    }
+    return parsed.data;
+}

package/dist/builder/load-module.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The set of `_kind` discriminant values that identify a domain primitive export.
+ */
+export declare const PRIMITIVE_KINDS: Set<"api" | "domain" | "webhook" | "subscriber" | "schedule" | "job" | "action" | "integration" | "event">;
+/**
+ * A raw primitive export extracted from a domain source file.
+ * Functions (handler) and Zod schemas (input/output/versions) are stripped
+ * because they cannot cross the child-process JSON boundary.
+ */
+export interface RawPrimitiveExport {
+    /** The `_kind` discriminant identifying the primitive type. */
+    _kind: string;
+    /** The export name within the source module. */
+    _exportName: string;
+    /** All scalar/plain-object fields from the export (functions stripped). */
+    [key: string]: unknown;
+}
+/**
+ * Spawns a tsx child process to import a TypeScript domain source file and
+ * extract all exports whose `_kind` matches a known primitive kind.
+ * Functions and Zod schema objects are stripped before JSON serialisation.
+ * @param absoluteFilePath - Absolute path to the `.ts` source file to load.
+ * @returns Array of raw primitive export objects with scalar fields only.
+ * @throws If tsx exits with a non-zero code or stdout is not valid JSON.
+ */
+export declare function loadModuleExports(absoluteFilePath: string): Promise<RawPrimitiveExport[]>;

package/dist/builder/load-module.js

@@ -0,0 +1,114 @@
+import { spawn } from 'node:child_process';
+import { writeFile, unlink, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+// Resolve tsx's CLI entry point relative to this package, so we never
+// depend on PATH containing node_modules/.bin.
+const _require = createRequire(import.meta.url);
+const tsxRoot = dirname(_require.resolve('tsx/package.json'));
+const tsxCli = join(tsxRoot, 'dist', 'cli.mjs');
+/**
+ * The set of `_kind` discriminant values that identify a domain primitive export.
+ */
+export const PRIMITIVE_KINDS = new Set([
+    'api', 'webhook', 'subscriber', 'schedule', 'job',
+    'action', 'integration', 'event', 'domain',
+]);
+/**
+ * Generates an eval script that imports a TypeScript module and extracts
+ * primitive exports with their functions and schemas stripped.
+ * @param absoluteFilePath - Absolute path to the `.ts` source file.
+ * @returns A string containing the eval script code.
+ */
+function makeEvalScript(absoluteFilePath) {
+    // Convert to file:// URL so ESM loader works on all platforms (especially Windows).
+    const fileUrl = pathToFileURL(absoluteFilePath).href;
+    return `
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import * as mod from ${JSON.stringify(fileUrl)};
+const KINDS = new Set(['api','webhook','subscriber','schedule','job','action','integration','event','domain']);
+function isZod(v) {
+  return v && typeof v === 'object' && typeof v.parse === 'function' && typeof v.safeParse === 'function' && v._def !== undefined;
+}
+function strip(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (typeof v === 'function') continue;
+    if (isZod(v)) {
+      try { out[k] = zodToJsonSchema(v, { target: 'jsonSchema7' }); } catch { /* skip unserializable */ }
+    } else if (Array.isArray(v)) {
+      out[k] = v.map(item => (item && typeof item === 'object' && !isZod(item) ? strip(item) : isZod(item) ? (() => { try { return zodToJsonSchema(item, { target: 'jsonSchema7' }); } catch { return undefined; } })() : item));
+    } else if (v && typeof v === 'object') {
+      out[k] = strip(v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+const seen = new Map();
+for (const [name, val] of Object.entries(mod)) {
+  if (val && typeof val === 'object' && KINDS.has(val._kind)) {
+    const key = val._kind + ':' + name;
+    if (!seen.has(key)) seen.set(key, { ...strip(val), _exportName: name });
+  } else if (val && typeof val === 'object') {
+    // Handle CJS-transpiled exports where named exports are
+    // nested inside default / module.exports.
+    for (const [nestedName, nestedVal] of Object.entries(val)) {
+      if (nestedVal && typeof nestedVal === 'object' && KINDS.has(nestedVal._kind)) {
+        const key = nestedVal._kind + ':' + nestedName;
+        if (!seen.has(key)) seen.set(key, { ...strip(nestedVal), _exportName: nestedName });
+      }
+    }
+  }
+}
+const results = Array.from(seen.values());
+process.stdout.write(JSON.stringify(results));
+`;
+}
+/**
+ * Spawns a tsx child process to import a TypeScript domain source file and
+ * extract all exports whose `_kind` matches a known primitive kind.
+ * Functions and Zod schema objects are stripped before JSON serialisation.
+ * @param absoluteFilePath - Absolute path to the `.ts` source file to load.
+ * @returns Array of raw primitive export objects with scalar fields only.
+ * @throws If tsx exits with a non-zero code or stdout is not valid JSON.
+ */
+export async function loadModuleExports(absoluteFilePath) {
+    // Use a subdir of the project root rather than OS tmpdir so that ESM import
+    // resolution can walk up and find node_modules packages like zod-to-json-schema.
+    const tibTmpDir = join(process.cwd(), '.tib', 'tmp');
+    await mkdir(tibTmpDir, { recursive: true }).catch(() => undefined);
+    const tempPath = join(tibTmpDir, `tib-load-${randomBytes(8).toString('hex')}.mts`);
+    await writeFile(tempPath, makeEvalScript(absoluteFilePath), 'utf8');
+    try {
+        return await new Promise((resolve, reject) => {
+            const tsxChild = spawn(process.execPath, [tsxCli, tempPath], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: { ...process.env },
+            });
+            let stdout = '';
+            let stderr = '';
+            tsxChild.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+            tsxChild.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+            tsxChild.on('close', (code) => {
+                if (code !== 0) {
+                    reject(new Error(`loadModuleExports: tsx exited ${code} for ${absoluteFilePath}\n${stderr}`));
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(stdout));
+                }
+                catch {
+                    reject(new Error(`loadModuleExports: invalid JSON from tsx for ${absoluteFilePath}: ${stdout}`));
+                }
+            });
+            tsxChild.on('error', (err) => reject(err));
+        });
+    }
+    finally {
+        await unlink(tempPath).catch(() => undefined);
+    }
+}

package/dist/builder/zod-to-json.d.ts

@@ -0,0 +1,10 @@
+import type { SchemaSnapshot } from '@mettlecast/domain-cdk-packer';
+/**
+ * Convert a Zod schema to a plain JSON Schema object compatible with SchemaSnapshot.
+ * Uses the `zod-to-json-schema` package under the hood with JSON Schema draft-07 target.
+ * Returns undefined if schema is nullish so callers can safely skip optional schemas.
+ * Input is typed `unknown` to bridge zod v3/v4 generic mismatches with the converter.
+ * @param schema - A Zod schema instance (any version), or undefined/null.
+ * @returns A SchemaSnapshot (plain JSON-serialisable object) or undefined.
+ */
+export declare function toJsonSchema(schema: unknown): SchemaSnapshot | undefined;

package/dist/builder/zod-to-json.js

@@ -0,0 +1,15 @@
+import { zodToJsonSchema } from 'zod-to-json-schema';
+/**
+ * Convert a Zod schema to a plain JSON Schema object compatible with SchemaSnapshot.
+ * Uses the `zod-to-json-schema` package under the hood with JSON Schema draft-07 target.
+ * Returns undefined if schema is nullish so callers can safely skip optional schemas.
+ * Input is typed `unknown` to bridge zod v3/v4 generic mismatches with the converter.
+ * @param schema - A Zod schema instance (any version), or undefined/null.
+ * @returns A SchemaSnapshot (plain JSON-serialisable object) or undefined.
+ */
+export function toJsonSchema(schema) {
+    if (!schema)
+        return undefined;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return zodToJsonSchema(schema, { target: 'jsonSchema7' });
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};