@mettlecast/domain-cli 0.2.0

package/src/builder/build-registry.ts

@@ -0,0 +1,237 @@
+import { relative, resolve } from 'node:path';
+import type {
+  DomainRegistry,
+  ApiRegistryEntry,
+  ApiVersionSnapshot,
+  SchemaSnapshot,
+  WebhookRegistryEntry,
+  SubscriberRegistryEntry,
+  ScheduleRegistryEntry,
+  JobRegistryEntry,
+  ActionRegistryEntry,
+  IntegrationRegistryEntry,
+  EventRegistryEntry,
+  DomainRegistryEntry,
+  SerialDeploymentConfig,
+} from '@mettlecast/domain-cdk-packer';
+import { walkDomainDir } from '../utils/file-helpers.js';
+import { loadModuleExports, type RawPrimitiveExport } from './load-module.js';
+
+/** Returns true if a value looks like a JSON Schema object (has a 'type' or '$schema' property). */
+function isJsonSchema(v: unknown): boolean {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) &&
+    ('type' in (v as object) || '$schema' in (v as object) || 'properties' in (v as object));
+}
+
+/**
+ * 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 async function buildRegistry(domainRoot: string): Promise<BuildResult> {
+  // 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: string[] = [];
+  const paths = await walkDomainDir(domainRoot);
+
+  if (!paths.domain) {
+    throw new Error(`buildRegistry: domain.config.ts not found in ${domainRoot}`);
+  }
+
+  async function load(filePath: string): Promise<RawPrimitiveExport[]> {
+    try {
+      return await loadModuleExports(filePath);
+    } catch (err) {
+      warnings.push(`Failed to load ${filePath}: ${String(err)}`);
+      return [];
+    }
+  }
+
+  function relPath(absPath: string): string {
+    return relative(domainRoot, absPath);
+  }
+
+  function deployment(raw: RawPrimitiveExport): SerialDeploymentConfig | undefined {
+    return raw['deployment'] as SerialDeploymentConfig | undefined;
+  }
+
+  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: DomainRegistryEntry = {
+    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: ApiRegistryEntry[] = paths.apis.flatMap((filePath, i) =>
+    (apiExports[i] ?? [])
+      .filter(e => e['_kind'] === 'api')
+      .map(e => {
+        const rawVersions = e['versions'] as Record<string, { input?: unknown; output?: unknown }> | undefined;
+        const versionSnapshots: ApiVersionSnapshot[] = rawVersions
+          ? Object.entries(rawVersions).map(([ver, v]) => ({
+              version: ver,
+              requestSchema: isJsonSchema(v?.input) ? (v.input as SchemaSnapshot) : undefined,
+              responseSchema: isJsonSchema(v?.output) ? (v.output as SchemaSnapshot) : undefined,
+            }))
+          : [];
+        const latestVersion = versionSnapshots[versionSnapshots.length - 1];
+        return {
+          id: String(e['id']),
+          kind: 'api' as const,
+          handlerFile: relPath(filePath),
+          path: String(e['path']),
+          method: typeof e['method'] === 'string' ? e['method'].toUpperCase() : 'ANY',
+          authType: ((e['auth'] as { type?: string } | undefined)?.type as 'jwt' | 'api-key' | 'none' | undefined) ?? '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: WebhookRegistryEntry[] = paths.webhooks.flatMap((filePath, i) =>
+    (webhookExports[i] ?? [])
+      .filter(e => e['_kind'] === 'webhook')
+      .map(e => ({
+        id: String(e['id']),
+        kind: 'webhook' as const,
+        handlerFile: relPath(filePath),
+        path: String(e['path']),
+        provider: String(e['provider']),
+        hmacAlgorithm: (e['verification'] as { type?: string } | undefined)?.type,
+        hmacSecretRef: (e['verification'] as { secretRef?: string } | undefined)?.secretRef,
+        deployment: deployment(e),
+      }))
+  );
+
+  const subscribers: SubscriberRegistryEntry[] = paths.subscribers.flatMap((filePath, i) =>
+    (subscriberExports[i] ?? [])
+      .filter(e => e['_kind'] === 'subscriber')
+      .map(e => ({
+        id: String(e['id']),
+        kind: 'subscriber' as const,
+        handlerFile: relPath(filePath),
+        event: String(e['event']),
+        semverRange: String(e['semverRange']),
+        concurrency: e['concurrency'] as number | undefined,
+        deployment: deployment(e),
+      }))
+  );
+
+  const schedules: ScheduleRegistryEntry[] = paths.schedules.flatMap((filePath, i) =>
+    (scheduleExports[i] ?? [])
+      .filter(e => e['_kind'] === 'schedule')
+      .map(e => ({
+        id: String(e['id']),
+        kind: 'schedule' as const,
+        handlerFile: relPath(filePath),
+        cron: String(e['cron']),
+        enabled: Boolean(e['enabled'] ?? true),
+        deployment: deployment(e),
+      }))
+  );
+
+  const jobs: JobRegistryEntry[] = paths.jobs.flatMap((filePath, i) =>
+    (jobExports[i] ?? [])
+      .filter(e => e['_kind'] === 'job')
+      .map(e => ({
+        id: String(e['id']),
+        kind: 'job' as const,
+        handlerFile: relPath(filePath),
+        maxRetries: Number(e['maxRetries'] ?? 3),
+        visibilityTimeoutSeconds: Number(e['visibilityTimeoutSeconds'] ?? 30),
+        deployment: deployment(e),
+      }))
+  );
+
+  const actions: ActionRegistryEntry[] = paths.actions.flatMap((filePath, i) =>
+    (actionExports[i] ?? [])
+      .filter(e => e['_kind'] === 'action')
+      .map(e => ({
+        id: String(e['id']),
+        kind: 'action' as const,
+        handlerFile: relPath(filePath),
+        visibility: String(e['visibility']) as 'private' | 'domain' | 'workspace',
+        idempotent: Boolean(e['idempotent'] ?? false),
+        description: typeof e['description'] === 'string' ? e['description'] : undefined,
+        deployment: deployment(e),
+        inputSchema: isJsonSchema(e['input']) ? (e['input'] as SchemaSnapshot) : undefined,
+        outputSchema: isJsonSchema(e['output']) ? (e['output'] as SchemaSnapshot) : undefined,
+      }))
+  );
+
+  const integrations: IntegrationRegistryEntry[] = paths.integrations.flatMap((_filePath, i) =>
+    (integrationExports[i] ?? [])
+      .filter(e => e['_kind'] === 'integration')
+      .map(e => ({
+        id: String(e['id']),
+        kind: 'integration' as const,
+        baseUrl: String(e['baseUrl']),
+      }))
+  );
+
+  const events: EventRegistryEntry[] = eventExports
+    .filter(e => e['_kind'] === 'event')
+    .map(e => ({
+      id: String(e['id']),
+      kind: 'event' as const,
+      busName: 'default',
+      description: typeof e['description'] === 'string' ? e['description'] : undefined,
+      versions: isJsonSchema(e['schema'])
+        ? [{ version: Number(e['version'] ?? 1), schema: e['schema'] as SchemaSnapshot }]
+        : undefined,
+    }));
+
+  const registry: DomainRegistry = {
+    schemaVersion: '1',
+    domainRoot,
+    domain,
+    apis,
+    webhooks,
+    subscribers,
+    schedules,
+    jobs,
+    actions,
+    integrations,
+    events,
+  };
+
+  return { registry, warnings };
+}

package/src/builder/build-types.ts

@@ -0,0 +1,36 @@
+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 function buildActionsTypes(registries: DomainRegistry[]): string {
+  const overloads: string[] = [];
+
+  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/src/builder/load-domain-module-config.ts

@@ -0,0 +1,43 @@
+import { join } from 'node:path';
+import { access } from 'node:fs/promises';
+import { DomainModuleConfigSchema } from '@mettlecast/domain-runtime/types';
+import type { DomainModuleConfig } 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: string): Promise<DomainModuleConfig> {
+  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/src/builder/load-module.ts

@@ -0,0 +1,133 @@
+import { spawn } from 'node:child_process';
+import { writeFile, unlink, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+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',
+] as const);
+
+/**
+ * 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;
+}
+
+/**
+ * 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: string): string {
+  // 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: string): Promise<RawPrimitiveExport[]> {
+  // 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<RawPrimitiveExport[]>((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: Buffer) => { stdout += chunk.toString(); });
+      tsxChild.stderr.on('data', (chunk: Buffer) => { 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) as RawPrimitiveExport[]);
+        } 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/src/builder/zod-to-json.ts

@@ -0,0 +1,16 @@
+import { zodToJsonSchema } from 'zod-to-json-schema';
+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 function toJsonSchema(schema: unknown): SchemaSnapshot | undefined {
+  if (!schema) return undefined;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return zodToJsonSchema(schema as any, { target: 'jsonSchema7' }) as SchemaSnapshot;
+}