@mettlecast/domain-cli 0.2.85 → 0.2.87

package/src/builder/build-registry.ts

@@ -15,20 +15,19 @@ import type {
 import { walkDomainDir } from '../utils/file-helpers.js';
 import { loadModuleExports, type RawPrimitiveExport } from './load-module.js';
 
-// Issue #4689: the legacy `defineApi` primitive was removed from
-// `@mettlecast/domain-runtime`. The only HTTP endpoint surface in
-// the new registry is `actions[]` whose `exposure.type === 'api'`.
-
 type ActionBackendAccess = 'private' | 'domain' | 'platform';
 
+type ValidAuth = 'required' | 'none' | 'service';
+type ValidTenancy = 'required' | 'none' | 'system';
+
 type ActionExposure =
   | { type: 'internal' }
   | {
     type: 'api';
     path: string;
     method: string;
-    auth: 'required' | 'none' | 'service';
-    tenancy: 'required' | 'none' | 'system';
+    auth: ValidAuth;
+    tenancy: ValidTenancy;
     roles?: string[];
     securityException?: { reason: string };
     authDeclared?: boolean;
@@ -36,68 +35,94 @@ type ActionExposure =
   };
 
 /**
- * Coerce a raw value into a valid backendAccess scope, defaulting to
- * 'private' when the value is missing or unrecognized. Used by the
- * builder when reading the new-style `backendAccess` field directly.
+ * Validate that a raw value is a valid backendAccess scope.
+ * Throws with diagnostics on invalid/missing values.
  */
-function toBackendAccess(raw: unknown): ActionBackendAccess {
-  return raw === 'domain' || raw === 'platform' ? raw : 'private';
-}
-
-/**
- * Map a legacy `visibility` scope to a `backendAccess` scope for the
- * action-first migration. The legacy `workspace` scope (which previously
- * permitted unauthenticated Function URL exposure) collapses to `domain`
- * so that all cross-domain callers must go through `ctx.actions`.
- */
-function visibilityToBackendAccess(visibility: unknown): ActionBackendAccess {
-  if (visibility === 'workspace') return 'domain';
-  if (visibility === 'domain') return 'domain';
-  return 'private';
+function validateBackendAccess(raw: unknown, actionId: string): ActionBackendAccess {
+  if (raw === 'domain' || raw === 'platform' || raw === 'private') {
+    return raw;
+  }
+  throw new Error(
+    `Action '${actionId}' has invalid or missing \`backendAccess\`. ` +
+    `Must be one of: 'private', 'domain', 'platform'. Got: ${JSON.stringify(raw)}`,
+  );
 }
 
 /**
- * Best-effort reverse mapping from `backendAccess` to the legacy
- * `visibility` field. Used to keep the deprecated field populated so
- * existing CDK constructs that read it continue to behave the same way.
- *
- * - private  -> private
- * - domain   -> domain
- * - platform -> workspace (closest legacy equivalent for platform-level)
+ * Validate and parse an action's `exposure` field.
+ * Throws with actionable diagnostics when exposure is missing, null, or malformed.
  */
-function backendAccessToVisibility(backendAccess: ActionBackendAccess): 'private' | 'domain' | 'workspace' {
-  if (backendAccess === 'platform') return 'workspace';
-  return backendAccess;
-}
+function validateExposure(raw: unknown, actionId: string): { exposure: ActionExposure; authDeclared: boolean; tenancyDeclared: boolean } {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error(
+      `Action '${actionId}' has missing or invalid \`exposure\`. ` +
+      `Every action must declare \`exposure\` explicitly. ` +
+      `Use \`exposure: { type: 'internal' }\` for internal-only actions, or ` +
+      `\`exposure: { type: 'api', path: '...', method: '...', auth: '...', tenancy: '...' }\` for API-exposed actions.`,
+    );
+  }
 
-/**
- * Type guard + sanitizer for an action's `exposure` field. Returns a
- * well-typed `ActionExposure` (extended with `authDeclared` /
- * `tenancyDeclared` tracking flags) or the provided fallback when the
- * raw value does not match a supported exposure shape.
- *
- * The `authDeclared` / `tenancyDeclared` flags record whether the source
- * code explicitly declared each field, or whether the builder fell back
- * to the safe default. They are validation-only and consumed by the
- * domain CLI's validate command (Wave 6 Task 6.1) to enforce the
- * action-first security model (#4619).
- */
-function toExposure(raw: unknown, fallback: ActionExposure): ActionExposure {
-  if (!raw || typeof raw !== 'object') return fallback;
   const candidate = raw as { type?: unknown };
-  if (candidate.type === 'internal') return { type: 'internal' };
-  if (candidate.type !== 'api') return fallback;
-  // Best-effort validation of api exposure fields; any missing required
-  // string field falls back to the supplied default exposure.
+  if (candidate.type === 'internal') {
+    // Internal must be exactly { type: 'internal' } — no extra keys
+    const extraKeys = Object.keys(raw as object).filter(k => k !== 'type');
+    if (extraKeys.length > 0) {
+      throw new Error(
+        `Action '${actionId}' has \`exposure.type: 'internal'\` with unexpected keys: ${extraKeys.join(', ')}. ` +
+        `Internal exposure must be exactly \`{ type: 'internal' }\`.`,
+      );
+    }
+    return { exposure: { type: 'internal' }, authDeclared: false, tenancyDeclared: false };
+  }
+
+  if (candidate.type !== 'api') {
+    throw new Error(
+      `Action '${actionId}' has \`exposure.type\` set to ${JSON.stringify(candidate.type)}. ` +
+      `Must be 'api' or 'internal'.`,
+    );
+  }
+
+  // Validate API exposure
   const api = raw as { path?: unknown; method?: unknown; auth?: unknown; tenancy?: unknown; roles?: unknown; securityException?: unknown };
-  if (typeof api.path !== 'string' || typeof api.method !== 'string') return fallback;
+
+  if (typeof api.path !== 'string' || api.path.trim().length === 0) {
+    throw new Error(
+      `Action '${actionId}' has \`exposure.type: 'api'\` but \`exposure.path\` is missing or empty. ` +
+      `Provide a non-empty path string (e.g. '/v1/tenants/{tenantId}/users').`,
+    );
+  }
+
+  if (typeof api.method !== 'string' || api.method.trim().length === 0) {
+    throw new Error(
+      `Action '${actionId}' has \`exposure.type: 'api'\` but \`exposure.method\` is missing or empty. ` +
+      `Provide an HTTP method (e.g. 'GET', 'POST', 'PUT', 'PATCH', 'DELETE').`,
+    );
+  }
+
   const authRaw = api.auth;
   const tenancyRaw = api.tenancy;
-  const auth: 'required' | 'none' | 'service' =
-    authRaw === 'required' || authRaw === 'none' || authRaw === 'service' ? authRaw : 'required';
-  const tenancy: 'required' | 'none' | 'system' =
-    tenancyRaw === 'required' || tenancyRaw === 'none' || tenancyRaw === 'system' ? tenancyRaw : 'required';
-  const out: ActionExposure & { type: 'api'; authDeclared?: boolean; tenancyDeclared?: boolean } = {
+  
+  let auth: ValidAuth;
+  if (authRaw === 'required' || authRaw === 'none' || authRaw === 'service') {
+    auth = authRaw;
+  } else {
+    throw new Error(
+      `Action '${actionId}' has \`exposure.type: 'api'\` but \`exposure.auth\` is missing or invalid. ` +
+      `Must be 'required', 'none', or 'service'. Got: ${JSON.stringify(authRaw)}`,
+    );
+  }
+  
+  let tenancy: ValidTenancy;
+  if (tenancyRaw === 'required' || tenancyRaw === 'none' || tenancyRaw === 'system') {
+    tenancy = tenancyRaw;
+  } else {
+    throw new Error(
+      `Action '${actionId}' has \`exposure.type: 'api'\` but \`exposure.tenancy\` is missing or invalid. ` +
+      `Must be 'required', 'none', or 'system'. Got: ${JSON.stringify(tenancyRaw)}`,
+    );
+  }
+
+  const out: ActionExposure & { authDeclared?: boolean; tenancyDeclared?: boolean } = {
     type: 'api',
     path: api.path,
     method: api.method,
@@ -106,6 +131,7 @@ function toExposure(raw: unknown, fallback: ActionExposure): ActionExposure {
     authDeclared: authRaw === 'required' || authRaw === 'none' || authRaw === 'service',
     tenancyDeclared: tenancyRaw === 'required' || tenancyRaw === 'none' || tenancyRaw === 'system',
   };
+
   if (Array.isArray(api.roles)) {
     out.roles = api.roles.filter((r): r is string => typeof r === 'string');
   }
@@ -115,7 +141,8 @@ function toExposure(raw: unknown, fallback: ActionExposure): ActionExposure {
       out.securityException = { reason };
     }
   }
-  return out;
+
+  return { exposure: out, authDeclared: out.authDeclared ?? false, tenancyDeclared: out.tenancyDeclared ?? false };
 }
 
 /** Returns true if a value looks like a JSON Schema object (has a 'type' or '$schema' property). */
@@ -138,10 +165,16 @@ export interface BuildResult {
  * 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).
+ *
+ * Strict contract (#5090): every action must have `kind:'action'`, id,
+ * handlerFile, backendAccess, idempotent, and explicit exposure. API requires
+ * path/method/auth/tenancy; internal must be exactly `{type:'internal'}`.
+ * Missing or invalid fields cause a build failure with actionable diagnostics.
+ *
  * @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.
+ * @throws If domain.config.ts is missing or does not export a 'domain' primitive,
+ *         or if any action has missing/invalid required fields.
  */
 export async function buildRegistry(domainRoot: string): Promise<BuildResult> {
   // Resolve to absolute path so downstream fs operations and tsx eval imports
@@ -266,43 +299,34 @@ const [webhookExports, subscriberExports, actionExports,
     (actionExports[i] ?? [])
       .filter(e => e['_kind'] === 'action')
       .map(e => {
-        // Resolve backendAccess. New-style actions carry `backendAccess`
-        // directly. Legacy actions only carry `visibility`; in that case
-        // we collapse workspace -> domain per the migration spec, and we
-        // also remember the legacy flag so we can default exposure to
-        // `{ type: 'internal' }` for actions that have not opted in yet.
-        const hasBackendAccess = 'backendAccess' in e;
-        const rawBackendAccess = e['backendAccess'];
-        const rawVisibility = e['visibility'];
-        const backendAccess: ActionBackendAccess = hasBackendAccess
-          ? toBackendAccess(rawBackendAccess)
-          : visibilityToBackendAccess(rawVisibility);
-        const legacyVisibility = backendAccessToVisibility(backendAccess);
-
-        // Resolve exposure. New-style actions must declare their exposure;
-        // legacy actions that did not opt in default to `{ type: 'internal' }`
-        // so existing internal-only behavior is preserved during migration.
-        const rawExposure = e['exposure'];
-        const exposure: ActionExposure = toExposure(rawExposure, { type: 'internal' });
-        // Record whether the source explicitly declared the `exposure` field.
-        // Validation-only; consumed by the domain CLI's validate command
-        // (Wave 6 Task 6.1) to enforce `ACTION_EXPOSURE_REQUIRED`.
-        const exposureDeclared = rawExposure !== undefined && rawExposure !== null
-          && typeof rawExposure === 'object';
+        const actionId = String(e['id']);
+
+        // Validate required fields — strict contract (#5090)
+        if (!actionId) {
+          throw new Error(`Action in ${relPath(filePath)} has missing or empty \`id\`.`);
+        }
+
+        // Validate backendAccess — required, no legacy default
+        const backendAccess = validateBackendAccess(e['backendAccess'], actionId);
+
+        // Validate exposure — required, no legacy default
+        const { exposure } = validateExposure(e['exposure'], actionId);
+
+        // Validate idempotent — required boolean
+        if (typeof e['idempotent'] !== 'boolean') {
+          throw new Error(
+            `Action '${actionId}' has missing or invalid \`idempotent\`. ` +
+            `Must be a boolean (true or false). Got: ${JSON.stringify(e['idempotent'])}`,
+          );
+        }
 
         return {
-          id: String(e['id']),
+          id: actionId,
           kind: 'action' as const,
           handlerFile: relPath(filePath),
           backendAccess,
           exposure,
-          exposureDeclared,
-          // Keep the legacy field populated so CDK constructs that still
-          // read `visibility` (e.g. action-construct.ts) keep working
-          // through the migration window. New constructs should read
-          // `backendAccess` and `exposure` instead.
-          visibility: legacyVisibility,
-          idempotent: Boolean(e['idempotent'] ?? false),
+          idempotent: Boolean(e['idempotent']),
           description: typeof e['description'] === 'string' ? e['description'] : undefined,
           deployment: deployment(e),
           outboundAccess: outboundAccess(e),

package/src/commands/build-catalog.ts

@@ -213,9 +213,8 @@ export async function runBuildCatalog(registryDir?: string): Promise<DomainCatal
     }
   }
 
-  const mcDir = join(process.cwd(), '.mc');
-  await mkdir(mcDir, { recursive: true });
-  const outPath = join(mcDir, 'domain-registry.json');
+  const outPath = join(dir, 'domain-registry.json');
+  await mkdir(dir, { recursive: true });
   await writeFile(outPath, JSON.stringify(catalog), 'utf8');
 
   cliLogger.info(

package/src/commands/update-all.ts

@@ -1,6 +1,13 @@
 import { join } from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
 import { cliLogger } from '../utils/logger.js';
 import { readScaffoldConfig } from '../utils/scaffold-config.js';
+import {
+  loadToolchainManifest,
+  type ToolchainManifest,
+} from '../utils/toolchain-manifest.js';
 import { runBuild } from './build.js';
 import { runBuildCatalog } from './build-catalog.js';
 import { runBuildFlows } from './build-flows.js';
@@ -8,8 +15,181 @@ import { runBuildUi } from './build-ui.js';
 import { runRegenerateModulesHashes } from './regenerate-modules-hashes.js';
 import { runDoctor } from './doctor.js';
 
+/**
+ * Expected packages in the toolchain manifest.
+ */
+const TOOLCHAIN_PACKAGE_KEYS = [
+  'domainCli',
+  'domainCdkPacker',
+  'domainRuntime',
+  'eslintPluginDomainModule',
+] as const;
+
+/**
+ * Map from toolchain key to npm package name.
+ */
+const TOOLCHAIN_NPM_NAMES: Record<string, string> = {
+  domainCli: '@mettlecast/domain-cli',
+  domainCdkPacker: '@mettlecast/domain-cdk-packer',
+  domainRuntime: '@mettlecast/domain-runtime',
+  eslintPluginDomainModule: '@mettlecast/eslint-plugin-domain-module',
+};
+
+/**
+ * Write exact toolchain versions into infra/modules/package.json.
+ * Replaces the @mettlecast/* dependency versions with the pinned exact versions
+ * from the toolchain manifest. Preserves all other fields unchanged.
+ *
+ * @param projectRoot - Project root directory.
+ * @param manifest - The resolved toolchain manifest.
+ */
+async function pinInfraPackageVersions(
+  projectRoot: string,
+  manifest: ToolchainManifest,
+): Promise<void> {
+  const infraPkgPath = join(projectRoot, 'infra', 'modules', 'package.json');
+
+  if (!existsSync(infraPkgPath)) {
+    cliLogger.warn({ path: infraPkgPath }, 'infra/modules/package.json not found — skipping version pinning');
+    return;
+  }
+
+  const raw = await readFile(infraPkgPath, 'utf-8');
+  const pkg = JSON.parse(raw) as Record<string, unknown>;
+
+  const pkgDeps = (pkg.dependencies ?? {}) as Record<string, string>;
+  const pkgDevDeps = (pkg.devDependencies ?? {}) as Record<string, string>;
+
+  // Pin @mettlecast/domain-cdk-packer
+  if (TOOLCHAIN_NPM_NAMES.domainCdkPacker in pkgDeps) {
+    pkgDeps[TOOLCHAIN_NPM_NAMES.domainCdkPacker] = manifest.packages.domainCdkPacker;
+  }
+
+  // Pin @mettlecast/domain-runtime
+  if (TOOLCHAIN_NPM_NAMES.domainRuntime in pkgDeps) {
+    pkgDeps[TOOLCHAIN_NPM_NAMES.domainRuntime] = manifest.packages.domainRuntime;
+  }
+
+  // Pin @mettlecast/domain-cli
+  if (TOOLCHAIN_NPM_NAMES.domainCli in pkgDevDeps) {
+    pkgDevDeps[TOOLCHAIN_NPM_NAMES.domainCli] = manifest.packages.domainCli;
+  }
+
+  // Pin @mettlecast/eslint-plugin-domain-module
+  if (TOOLCHAIN_NPM_NAMES.eslintPluginDomainModule in pkgDevDeps) {
+    pkgDevDeps[TOOLCHAIN_NPM_NAMES.eslintPluginDomainModule] = manifest.packages.eslintPluginDomainModule;
+  }
+
+  pkg.dependencies = pkgDeps;
+  pkg.devDependencies = pkgDevDeps;
+
+  await writeFile(infraPkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+  cliLogger.info({ path: infraPkgPath }, 'Pinned toolchain versions in infra/modules/package.json');
+}
+
+/**
+ * Write exact toolchain versions into root package.json.
+ * Replaces the @mettlecast/* devDependency versions with the pinned exact versions
+ * from the toolchain manifest. Preserves all other fields unchanged.
+ *
+ * @param projectRoot - Project root directory.
+ * @param manifest - The resolved toolchain manifest.
+ */
+async function pinRootPackageVersions(
+  projectRoot: string,
+  manifest: ToolchainManifest,
+): Promise<void> {
+  const rootPkgPath = join(projectRoot, 'package.json');
+
+  if (!existsSync(rootPkgPath)) {
+    cliLogger.warn({ path: rootPkgPath }, 'root package.json not found — skipping version pinning');
+    return;
+  }
+
+  const raw = await readFile(rootPkgPath, 'utf-8');
+  const pkg = JSON.parse(raw) as Record<string, unknown>;
+
+  const pkgDevDeps = (pkg.devDependencies ?? {}) as Record<string, string>;
+
+  // Pin @mettlecast/domain-cli (root devDependency)
+  if (TOOLCHAIN_NPM_NAMES.domainCli in pkgDevDeps) {
+    pkgDevDeps[TOOLCHAIN_NPM_NAMES.domainCli] = manifest.packages.domainCli;
+  }
+
+  // Pin @mettlecast/domain-runtime (root devDependency)
+  if (TOOLCHAIN_NPM_NAMES.domainRuntime in pkgDevDeps) {
+    pkgDevDeps[TOOLCHAIN_NPM_NAMES.domainRuntime] = manifest.packages.domainRuntime;
+  }
+
+  // Pin @mettlecast/eslint-plugin-domain-module (root devDependency)
+  if (TOOLCHAIN_NPM_NAMES.eslintPluginDomainModule in pkgDevDeps) {
+    pkgDevDeps[TOOLCHAIN_NPM_NAMES.eslintPluginDomainModule] = manifest.packages.eslintPluginDomainModule;
+  }
+
+  pkg.devDependencies = pkgDevDeps;
+
+  await writeFile(rootPkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+  cliLogger.info({ path: rootPkgPath }, 'Pinned toolchain versions in root package.json');
+}
+
+/**
+ * Regenerate lockfiles for root and infra/modules after version pinning.
+ * Runs `npm install --package-lock-only` (without modifying package.json) to
+ * produce deterministic package-lock.json files that match the pinned exact
+ * versions. The `--package-lock` flag overrides any `package-lock=false` in
+ * the project's .npmrc so lockfiles are always generated.
+ *
+ * @param projectRoot - Project root directory.
+ */
+async function regenerateLockfiles(projectRoot: string): Promise<void> {
+  const rootPkgPath = join(projectRoot, 'package.json');
+  const infraPkgPath = join(projectRoot, 'infra', 'modules', 'package.json');
+
+  const npmLockCmd = 'npm install --package-lock-only --package-lock --no-save';
+
+  // Regenerate root lockfile if root package.json exists
+  if (existsSync(rootPkgPath)) {
+    try {
+      cliLogger.info({ projectRoot }, 'Regenerating root package-lock.json');
+      execSync(npmLockCmd, {
+        cwd: projectRoot,
+        stdio: 'pipe',
+        timeout: 120_000,
+      });
+      cliLogger.info({ projectRoot }, 'Root package-lock.json regenerated');
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      cliLogger.warn(
+        { err: message },
+        'Root lockfile regeneration failed (non-fatal — continuing)',
+      );
+    }
+  }
+
+  // Regenerate infra/modules lockfile if infra/modules/package.json exists
+  if (existsSync(infraPkgPath)) {
+    try {
+      const infraDir = join(projectRoot, 'infra', 'modules');
+      cliLogger.info({ path: infraDir }, 'Regenerating infra/modules package-lock.json');
+      execSync(npmLockCmd, {
+        cwd: infraDir,
+        stdio: 'pipe',
+        timeout: 120_000,
+      });
+      cliLogger.info({ path: infraDir }, 'infra/modules package-lock.json regenerated');
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      cliLogger.warn(
+        { err: message },
+        'infra/modules lockfile regeneration failed (non-fatal — continuing)',
+      );
+    }
+  }
+}
+
 /**
  * Run the full scaffold update pipeline:
+ *   0. Resolve toolchain manifest and pin exact versions + regenerate lockfiles
  *   1. Build each domain registry from `.mc/scaffold-config.json`
  *   2. Build the combined domain catalog
  *   3. Build flows registry
@@ -28,6 +208,42 @@ export async function runUpdateAll(opts?: { projectRoot?: string }): Promise<{ s
 
   cliLogger.info({ projectRoot }, 'update-all: starting');
 
+  // 0. Resolve toolchain manifest and pin exact versions
+  cliLogger.info({ projectRoot }, 'update-all: resolving toolchain manifest');
+  let manifest: ToolchainManifest;
+  try {
+    manifest = await loadToolchainManifest(projectRoot);
+    cliLogger.info(
+      {
+        domainCli: manifest.packages.domainCli,
+        domainRuntime: manifest.packages.domainRuntime,
+        domainCdkPacker: manifest.packages.domainCdkPacker,
+        eslintPluginDomainModule: manifest.packages.eslintPluginDomainModule,
+        registrySchemaVersion: manifest.registrySchemaVersion,
+      },
+      'update-all: toolchain manifest resolved',
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    cliLogger.error({ err: message }, 'update-all: toolchain resolution failed — aborting');
+    return { success: false, summary: `Toolchain resolution FAIL: ${message}` };
+  }
+
+  // Pin exact versions from manifest into infra/modules/package.json and root package.json
+  try {
+    await pinInfraPackageVersions(projectRoot, manifest);
+    await pinRootPackageVersions(projectRoot, manifest);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    cliLogger.error({ err: message }, 'update-all: version pinning failed — aborting');
+    return { success: false, summary: `Version pinning FAIL: ${message}` };
+  }
+
+  // Regenerate lockfiles so that root and infra/modules lockfiles exist
+  // and match the pinned exact versions before generated CI uses `npm ci`.
+  cliLogger.info({ projectRoot }, 'update-all: regenerating lockfiles');
+  await regenerateLockfiles(projectRoot);
+
   // 1. Read scaffold-config to discover domains
   const scaffoldConfig = await readScaffoldConfig(projectRoot);
   const domainIds = scaffoldConfig.domainIds ?? [];