@mettlecast/domain-cli 0.2.0

package/src/commands/build-catalog.ts

@@ -0,0 +1,181 @@
+import { readFile, writeFile, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+
+/** A single API entry in the catalog. */
+export interface CatalogApi {
+  id: string;
+  domainId: string;
+  path: string;
+  method: string;
+  authType: string;
+  description?: string;
+  requestSchema?: Record<string, unknown>;
+  responseSchema?: Record<string, unknown>;
+  versions?: Array<{ version: string; requestSchema?: Record<string, unknown>; responseSchema?: Record<string, unknown> }>;
+}
+
+/** A single action entry in the catalog. */
+export interface CatalogAction {
+  id: string;
+  domainId: string;
+  visibility: string;
+  idempotent: boolean;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+}
+
+/** A single event entry in the catalog. */
+export interface CatalogEvent {
+  id: string;
+  domainId: string;
+  description?: string;
+  versions?: Array<{ version: number; schema: Record<string, unknown> }>;
+}
+
+/** A single subscriber entry in the catalog. */
+export interface CatalogSubscriber {
+  id: string;
+  domainId: string;
+  event: string;
+  semverRange: string;
+  description?: string;
+}
+
+/** A single domain entry in the catalog. */
+export interface CatalogDomain {
+  id: string;
+  name: string;
+  tenancy: string;
+  description?: string;
+}
+
+/** The combined domain catalog written to .mc/domain-registry.json. */
+export interface DomainCatalog {
+  version: 2;
+  generatedAt: string;
+  domains: CatalogDomain[];
+  apis: CatalogApi[];
+  actions: CatalogAction[];
+  events: CatalogEvent[];
+  subscribers: CatalogSubscriber[];
+}
+
+/**
+ * Build the combined domain catalog from all per-domain registry files.
+ * Reads .mc/{domain}-registry.json files and merges them into .mc/domain-registry.json.
+ * @param tibDir - Path to the .tib directory. Defaults to .tib in cwd.
+ * @returns The written catalog.
+ */
+export async function runBuildCatalog(tibDir?: string): Promise<DomainCatalog> {
+  const dir = tibDir ? resolve(tibDir) : join(process.cwd(), '.tib');
+
+  // Find all per-domain registry files
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch {
+    throw new Error(`build-catalog: .tib directory not found at ${dir}. Run tib build first.`);
+  }
+
+  const registryFiles = files.filter(f => f.endsWith('-registry.json') && f !== 'domain-registry.json');
+  if (registryFiles.length === 0) {
+    throw new Error(`build-catalog: no domain registry files found in ${dir}. Run tib build <domain> first.`);
+  }
+
+  const catalog: DomainCatalog = {
+    version: 2,
+    generatedAt: new Date().toISOString(),
+    domains: [],
+    apis: [],
+    actions: [],
+    events: [],
+    subscribers: [],
+  };
+
+  for (const file of registryFiles) {
+    const raw = await readFile(join(dir, file), 'utf8');
+    let registry: Record<string, unknown>;
+    try {
+      registry = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      cliLogger.warn({ file }, 'Skipping invalid JSON registry file');
+      continue;
+    }
+
+    const domainEntry = registry['domain'] as Record<string, unknown> | undefined;
+    if (!domainEntry) {
+      cliLogger.warn({ file }, 'Skipping registry file with no domain entry');
+      continue;
+    }
+
+    const domainId = String(domainEntry['id']);
+
+    catalog.domains.push({
+      id: domainId,
+      name: String(domainEntry['name'] ?? domainId),
+      tenancy: String(domainEntry['tenancy'] ?? 'none'),
+      description: domainEntry['description'] as string | undefined,
+    });
+
+    const apis = (registry['apis'] as Record<string, unknown>[] | undefined) ?? [];
+    for (const api of apis) {
+      catalog.apis.push({
+        id: String(api['id']),
+        domainId,
+        path: String(api['path']),
+        method: String(api['method'] ?? 'ANY'),
+        authType: String(api['authType'] ?? 'jwt'),
+        description: api['description'] as string | undefined,
+        requestSchema: api['requestSchema'] as Record<string, unknown> | undefined,
+        responseSchema: api['responseSchema'] as Record<string, unknown> | undefined,
+        versions: api['versions'] as CatalogApi['versions'],
+      });
+    }
+
+    const actions = (registry['actions'] as Record<string, unknown>[] | undefined) ?? [];
+    for (const action of actions) {
+      catalog.actions.push({
+        id: String(action['id']),
+        domainId,
+        visibility: String(action['visibility'] ?? 'private'),
+        idempotent: Boolean(action['idempotent'] ?? false),
+        description: action['description'] as string | undefined,
+        inputSchema: action['inputSchema'] as Record<string, unknown> | undefined,
+        outputSchema: action['outputSchema'] as Record<string, unknown> | undefined,
+      });
+    }
+
+    const events = (registry['events'] as Record<string, unknown>[] | undefined) ?? [];
+    for (const event of events) {
+      catalog.events.push({
+        id: String(event['id']),
+        domainId,
+        description: event['description'] as string | undefined,
+        versions: event['versions'] as CatalogEvent['versions'],
+      });
+    }
+
+    const subscribers = (registry['subscribers'] as Record<string, unknown>[] | undefined) ?? [];
+    for (const sub of subscribers) {
+      catalog.subscribers.push({
+        id: String(sub['id']),
+        domainId,
+        event: String(sub['event']),
+        semverRange: String(sub['semverRange'] ?? '*'),
+        description: sub['description'] as string | undefined,
+      });
+    }
+  }
+
+  const outPath = join(dir, 'domain-registry.json');
+  await writeFile(outPath, JSON.stringify(catalog, null, 2), 'utf8');
+
+  cliLogger.info(
+    { outPath, domains: catalog.domains.length, apis: catalog.apis.length, actions: catalog.actions.length, events: catalog.events.length },
+    'Domain catalog written'
+  );
+
+  return catalog;
+}

package/src/commands/build-flows.ts

@@ -0,0 +1,198 @@
+/**
+ * Command to build flows into a registry JSON file.
+ */
+
+import { writeFile, mkdir, readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { z } from 'zod';
+import type { FlowRegistry, FlowRegistryEntry } from '@mettlecast/domain-cdk-packer';
+import { loadModuleExports } from '../builder/load-module.js';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * Options for the build-flows command.
+ */
+export interface BuildFlowsOptions {
+  /** Project root directory. Defaults to current working directory. */
+  projectRoot?: string;
+  /** Output path for the flows registry JSON file. Defaults to .mc/flows-registry.json. */
+  outFile?: string;
+}
+
+/**
+ * Zod schema for validating FlowConfig.
+ * Mirrors the schema from domain-runtime's defineFlow.
+ */
+const DomainActionStepSchema = z.object({
+  type: z.literal('domain-action'),
+  name: z.string().min(1),
+  domainId: z.string().regex(/^[a-z][a-z0-9-]*$/),
+  actionId: z.string().min(1),
+  parameters: z.record(z.string(), z.unknown()).optional(),
+  waitForTaskToken: z.boolean().optional(),
+  next: z.string().optional(),
+});
+
+const DomainApiStepSchema = z.object({
+  type: z.literal('domain-api'),
+  name: z.string().min(1),
+  domainId: z.string().regex(/^[a-z][a-z0-9-]*$/),
+  apiId: z.string().min(1),
+  parameters: z.record(z.string(), z.unknown()).optional(),
+  next: z.string().optional(),
+});
+
+const DomainEventStepSchema = z.object({
+  type: z.literal('domain-event'),
+  name: z.string().min(1),
+  eventId: z.string().refine(val => val.includes('.'), { message: 'eventId must be namespaced (e.g. domain.event)' }),
+  payload: z.record(z.string(), z.unknown()),
+  version: z.number().int().positive(),
+  next: z.string().optional(),
+});
+
+const FlowControlStepSchema = z.discriminatedUnion('control', [
+  z.object({ type: z.literal('flow-control'), control: z.literal('choice'), name: z.string(), choices: z.array(z.object({ when: z.string(), next: z.string() })), default: z.string().optional() }),
+  z.object({ type: z.literal('flow-control'), control: z.literal('parallel'), name: z.string(), branches: z.array(z.array(z.unknown())), next: z.string().optional() }),
+  z.object({ type: z.literal('flow-control'), control: z.literal('wait'), name: z.string(), seconds: z.number().int().positive(), next: z.string().optional() }),
+  z.object({ type: z.literal('flow-control'), control: z.literal('succeed'), name: z.string() }),
+  z.object({ type: z.literal('flow-control'), control: z.literal('fail'), name: z.string(), cause: z.string().optional(), error: z.string().optional() }),
+  z.object({ type: z.literal('flow-control'), control: z.literal('pass'), name: z.string(), result: z.unknown().optional(), next: z.string().optional() }),
+]);
+
+const FlowStepSchema = z.union([
+  DomainActionStepSchema,
+  DomainApiStepSchema,
+  DomainEventStepSchema,
+  FlowControlStepSchema,
+]);
+
+const FlowConfigSchema = z.object({
+  id: z.string().regex(/^[a-z][a-z0-9-]*$/),
+  owningDomain: z.string().regex(/^[a-z][a-z0-9-]*$/).optional(),
+  type: z.enum(['express', 'standard']).optional(),
+  name: z.string().min(1),
+  steps: z.array(FlowStepSchema).min(1),
+  trigger: z.object({
+    type: z.literal('event'),
+    eventId: z.string().includes('.'),
+    semverRange: z.string().min(1),
+  }).optional(),
+});
+
+/**
+ * Custom error for flow ID collisions.
+ */
+export class FlowIdCollisionError extends Error {
+  constructor(id: string) {
+    super(`Flow id "${id}" appears in multiple sources`);
+    this.name = 'FlowIdCollisionError';
+  }
+}
+
+async function loadFlowsFromDir(dir: string, owningDomainOverride?: string): Promise<FlowRegistryEntry[]> {
+  const entries: FlowRegistryEntry[] = [];
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return entries;
+    throw err;
+  }
+
+  for (const file of files) {
+    if (file.endsWith('.ts')) {
+      const filePath = join(dir, file);
+      const exports = await loadModuleExports(filePath);
+      for (const exp of exports) {
+        if (exp._kind !== 'flow') continue;
+        const config = FlowConfigSchema.parse(exp);
+        entries.push({
+          id: config.id,
+          owningDomain: owningDomainOverride ?? config.owningDomain,
+          type: config.type,
+          name: config.name,
+          steps: config.steps as any,
+          trigger: config.trigger as any,
+        });
+      }
+    } else if (file.endsWith('.json')) {
+      const filePath = join(dir, file);
+      const raw = await readFile(filePath, 'utf8');
+      const config = FlowConfigSchema.parse(JSON.parse(raw));
+      entries.push({
+        id: config.id,
+        owningDomain: owningDomainOverride ?? config.owningDomain,
+        type: config.type,
+        name: config.name,
+        steps: config.steps as any,
+        trigger: config.trigger as any,
+      });
+    }
+  }
+  return entries;
+}
+
+/**
+ * Execute the build-flows command: scan flows/ and domains/x/flows/ directories for .ts and .json files,
+ * validate and serialize them, and write .mc/flows-registry.json.
+ * @param options - BuildFlowsOptions specifying project root and optional output path.
+ * @returns The absolute path to the written registry file.
+ * @throws If flow validation fails or IDs collide.
+ */
+export async function runBuildFlows(options: BuildFlowsOptions): Promise<string> {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const outFile = options.outFile ?? join(projectRoot, '.tib', 'flows-registry.json');
+
+  cliLogger.info({ projectRoot }, 'Building flows registry');
+
+  const allEntries: FlowRegistryEntry[] = [];
+  const seenIds = new Set<string>();
+
+  // Scan root-level flows/ (deprecated)
+  const rootFlowsDir = join(projectRoot, 'flows');
+  const rootEntries = await loadFlowsFromDir(rootFlowsDir);
+  if (rootEntries.length > 0) {
+    cliLogger.warn(
+      { dir: rootFlowsDir },
+      'Root-level flows/ is deprecated. Move flows to domains/{x}/flows/ and re-run build-flows.'
+    );
+    for (const e of rootEntries) {
+      if (seenIds.has(e.id)) throw new FlowIdCollisionError(e.id);
+      seenIds.add(e.id);
+      allEntries.push(e);
+    }
+  }
+
+  // Scan domains/*/flows/ (preferred)
+  const domainsDir = join(projectRoot, 'domains');
+  let domainEntries: string[];
+  try {
+    domainEntries = (await readdir(domainsDir, { withFileTypes: true }))
+      .filter(e => e.isDirectory())
+      .map(e => e.name);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      domainEntries = [];
+    } else {
+      throw err;
+    }
+  }
+
+  for (const domainId of domainEntries) {
+    const domainFlowsDir = join(domainsDir, domainId, 'flows');
+    const domainFlowEntries = await loadFlowsFromDir(domainFlowsDir, domainId);
+    for (const e of domainFlowEntries) {
+      if (seenIds.has(e.id)) throw new FlowIdCollisionError(e.id);
+      seenIds.add(e.id);
+      allEntries.push(e);
+    }
+  }
+
+  const registry: FlowRegistry = { schemaVersion: '1', flows: allEntries };
+  await mkdir(join(outFile, '..'), { recursive: true });
+  await writeFile(outFile, JSON.stringify(registry, null, 2), 'utf8');
+
+  cliLogger.info({ outFile, flowCount: registry.flows.length }, 'Flows registry written');
+  return outFile;
+}

package/src/commands/build.ts

@@ -0,0 +1,59 @@
+import { writeFile, mkdir, readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+import { buildRegistry } from '../builder/build-registry.js';
+import { buildActionsTypes } from '../builder/build-types.js';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * Options for the build command.
+ */
+export interface BuildOptions {
+  /** Absolute or relative path to the domain root directory. */
+  domainRoot: string;
+  /** Output path for the registry JSON file. Defaults to .mc/domain-registry.json relative to cwd. */
+  outFile?: string;
+}
+
+/**
+ * Execute the build command: load the domain source directory, build the DomainRegistry,
+ * and write the serialised JSON snapshot to disk.
+ * @param options - BuildOptions specifying domain root and optional output path.
+ * @returns The absolute path to the written registry file.
+ * @throws If domain.config.ts is missing or the registry build fails.
+ */
+export async function runBuild(options: BuildOptions): Promise<string> {
+  const domainRoot = resolve(options.domainRoot);
+  const outFile = options.outFile
+    ? resolve(options.outFile)
+    : join(process.cwd(), '.tib', 'domain-registry.json');
+
+  cliLogger.info({ domainRoot }, 'Building domain registry');
+
+  const { registry, warnings } = await buildRegistry(domainRoot);
+
+  for (const w of warnings) {
+    cliLogger.warn(w);
+  }
+
+  await mkdir(join(outFile, '..'), { recursive: true });
+  await writeFile(outFile, JSON.stringify(registry, null, 2), 'utf8');
+
+  cliLogger.info({ outFile, apis: registry.apis.length, events: registry.events.length }, 'Registry written');
+
+  // Discover all sibling registries and emit aggregated types
+  const tibDir = join(process.cwd(), '.tib');
+  const registryFiles = (await readdir(tibDir)).filter(f => f.endsWith('-registry.json'));
+  const allRegistries: DomainRegistry[] = [];
+  for (const f of registryFiles) {
+    const raw = await readFile(join(tibDir, f), 'utf8');
+    allRegistries.push(JSON.parse(raw) as DomainRegistry);
+  }
+  const typesContent = buildActionsTypes(allRegistries);
+  const typesFile = join(tibDir, 'actions-types.d.ts');
+  await writeFile(typesFile, typesContent);
+
+  cliLogger.info({ outFile: typesFile }, 'Types file written');
+
+  return outFile;
+}

package/src/commands/check-hashes.ts

@@ -0,0 +1,150 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { createHash } from 'node:crypto';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * Options for the check-hashes command.
+ */
+export interface CheckHashesOptions {
+  /** Root directory of the project (defaults to cwd). */
+  projectRoot?: string;
+}
+
+/**
+ * A single hash check result.
+ */
+export interface DriftedFile {
+  /** File path relative to project root. */
+  path: string;
+  /** Expected SHA256 hash from manifest. */
+  expectedHash: string;
+  /** Actual SHA256 hash on disk. */
+  actualHash: string;
+}
+
+/**
+ * Result of the check-hashes command.
+ */
+export interface CheckHashesResult {
+  /** Whether all hashes match. */
+  ok: boolean;
+  /** Files that have been modified since scaffold. */
+  drifted: DriftedFile[];
+  /** Files that existed at scaffold time but are now missing. */
+  missing: string[];
+  /** Files on disk that were not in the scaffold manifest. */
+  unexpected: string[];
+}
+
+/**
+ * Manifest of infra/modules/ files with their SHA256 hashes.
+ */
+interface ModulesHashesManifest {
+  /** Schema version. */
+  version: '1';
+  /** ISO timestamp when the manifest was generated. */
+  generatedAt: string;
+  /** Map of relative file path to SHA256 hex digest. */
+  files: Record<string, string>;
+}
+
+/**
+ * Verify that infra/modules/ has not been hand-edited since last scaffold.
+ * Reads .mc/modules-hashes.json manifest and compares each file's SHA256.
+ * @param opts Options including project root directory.
+ * @returns CheckHashesResult with ok, drifted, missing, and unexpected arrays.
+ */
+export async function runCheckHashes(opts: CheckHashesOptions = {}): Promise<CheckHashesResult> {
+  const root = opts.projectRoot ?? process.cwd();
+  const manifestPath = join(root, '.tib', 'modules-hashes.json');
+  const modulesDir = join(root, 'infra', 'modules');
+
+  let manifest: ModulesHashesManifest;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, 'utf8')) as ModulesHashesManifest;
+  } catch (err) {
+    throw new Error(`tib check-hashes: cannot read ${manifestPath} (${(err as Error).message}). Re-scaffold to regenerate the manifest.`);
+  }
+
+  const drifted: DriftedFile[] = [];
+  const missing: string[] = [];
+  const unexpected: string[] = [];
+
+  // Files/directories to skip when walking infra/modules/
+  const SKIP_NAMES = new Set(['node_modules', 'dist', 'cdk.out', 'package-lock.json', '.npmrc']);
+
+  /** Normalize CRLF → LF so hashes match across platforms (Windows vs Linux). */
+  function normalizeLineEndings(buf: Buffer): Buffer {
+    const str = buf.toString('utf8');
+    if (!str.includes('\r\n')) return buf;
+    return Buffer.from(str.replace(/\r\n/g, '\n'), 'utf8');
+  }
+
+  // Walk infra/modules/ to compute current hashes
+  async function walk(dir: string): Promise<string[]> {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const files: string[] = [];
+    for (const entry of entries) {
+      if (SKIP_NAMES.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) files.push(...await walk(full));
+      else if (entry.isFile()) files.push(full);
+    }
+    return files;
+  }
+
+  const onDiskFiles = await walk(modulesDir);
+  const onDiskRel = onDiskFiles.map(f => relative(root, f).replace(/\\/g, '/'));
+  const onDiskSet = new Set(onDiskRel);
+
+  // Check each manifest entry
+  for (const [relPath, expectedHash] of Object.entries(manifest.files)) {
+    if (!onDiskSet.has(relPath)) {
+      missing.push(relPath);
+      continue;
+    }
+    const content = await readFile(join(root, relPath));
+    const normalized = normalizeLineEndings(content);
+    const actualHash = createHash('sha256').update(normalized).digest('hex');
+    if (actualHash !== expectedHash) {
+      drifted.push({ path: relPath, expectedHash, actualHash });
+    }
+  }
+
+  // Files on disk but not in manifest
+  for (const relPath of onDiskRel) {
+    if (!Object.prototype.hasOwnProperty.call(manifest.files, relPath)) {
+      unexpected.push(relPath);
+    }
+  }
+
+  const result: CheckHashesResult = {
+    ok: drifted.length === 0 && missing.length === 0 && unexpected.length === 0,
+    drifted,
+    missing,
+    unexpected,
+  };
+
+  if (!result.ok) {
+    cliLogger.error(
+      { drifted: drifted.length, missing: missing.length, unexpected: unexpected.length },
+      'infra/modules/ has drifted from scaffold'
+    );
+    if (drifted.length > 0) {
+      cliLogger.error('Files modified since last scaffold:');
+      for (const d of drifted) cliLogger.error(`  - ${d.path}`);
+    }
+    if (missing.length > 0) {
+      cliLogger.error('Files deleted since last scaffold:');
+      for (const m of missing) cliLogger.error(`  - ${m}`);
+    }
+    if (unexpected.length > 0) {
+      cliLogger.error('Files added that were not scaffolded (manually-added):');
+      for (const u of unexpected) cliLogger.error(`  - ${u}`);
+    }
+    cliLogger.error('infra/modules/ is TIB-owned. Re-scaffold to update legitimately.');
+  }
+
+  return result;
+}