@mettlecast/domain-cli 0.2.86 → 0.2.87

package/src/commands/validate.ts

@@ -21,12 +21,6 @@ type ActionApiExposureWithDeclaration = {
   tenancyDeclared?: boolean;
 };
 
-type ActionRegistryEntryWithDeclaration = ActionRegistryEntry & {
-  backendAccess?: 'private' | 'domain' | 'platform';
-  exposureDeclared?: boolean;
-  exposure: { type: 'internal' } | ActionApiExposureWithDeclaration;
-};
-
 /**
  * A single validation failure.
  */
@@ -138,32 +132,7 @@ async function checkRawPathViolations(
 }
 
 /**
- * Deployment-time security checks (#4662 Task D).
- *
- * Mirrors the invariants enforced at CDK synth time by
- * `SecurityAssertionAspect` in `@mettlecast/domain-cdk-packer`. Running
- * them at the CLI stage means developers get a structured error code in
- * their terminal and CI fails on `mc-domain-module validate` BEFORE a
- * (potentially expensive) `cdk synth` is attempted.
- *
- * Each rule maps 1:1 to an aspect annotation code so downstream tooling
- * can correlate build-time and synth-time failures.
- *
- * Issue #4689: the legacy `defineApi` factory and `registry.apis` field
- * were removed. Deployment-time API invariants are enforced against the
- * `actions[]` API-exposure surface — see `checkActionFirstSecurity`.
- */
-function checkDeploymentSecurity(_actions: ActionRegistryEntry[]): ValidationError[] {
-  // Action API exposures are already covered by `checkActionFirstSecurity`
-  // for `tenancy: 'required'` paths and `auth: 'none'` exceptions. The
-  // codes there (TENANT_API_PATH_REQUIRED, AUTH_NONE_REQUIRES_EXCEPTION)
-  // are kept stable for back-compat — they map to the same aspect codes.
-  //
-  return [];
-}
-
-/**
- * Action-first security validation rules (#4619, Wave 6 Task 6.1).
+ * Check action-first security invariants.
  *
  * These checks enforce the action-first security model on the
  * serialised DomainRegistry produced by `buildRegistry`. The rules
@@ -173,36 +142,42 @@ function checkDeploymentSecurity(_actions: ActionRegistryEntry[]): ValidationErr
  *
  * Each rule emits a structured `ValidationError` whose `code` is the
  * rule ID listed in the spec (e.g. `ACTION_EXPOSURE_REQUIRED`,
- * `TENANT_API_PATH_REQUIRED`). Messages include the offending action
- * or API id and the actionable fix.
+ * `TENANT_API_PATH_REQUIRED`, `API_INPUT_SCHEMA_REQUIRED`).
  */
 function checkActionFirstSecurity(actions: ActionRegistryEntry[]): ValidationError[] {
   const errors: ValidationError[] = [];
 
-  for (const action of actions as ActionRegistryEntryWithDeclaration[]) {
+  for (const action of actions) {
     const id = action.id;
 
     // ACTION_EXPOSURE_REQUIRED — every action registry entry must have
-    // `exposure` declared in source. The builder defaults missing
-    // exposure to `{ type: 'internal' }` for backwards compatibility,
-    // and flags the entry with `exposureDeclared: false` so the validator
-    // can surface it. Legacy actions that use `visibility` only (no
-    // `backendAccess`) are also allowed to default during migration.
-    if (action.exposureDeclared === false && action.backendAccess !== 'private') {
-      // Only fire for non-private actions: a private action with no
-      // exposure is the natural migration state for legacy
-      // visibility:'private' handlers, and forcing exposure would
-      // produce noisy errors during the migration window.
-      // (When Wave 7+ removes the legacy visibility alias this branch
-      // becomes a hard error for every action.)
+    // `exposure` declared and valid. The buildRegistry now rejects
+    // missing/invalid exposure at build time, but we also verify here
+    // for belt-and-suspenders.
+    if (!action.exposure) {
       errors.push({
         code: 'ACTION_EXPOSURE_REQUIRED',
-        message: `Action '${id}' has no explicit \`exposure\`. New-style actions must declare \`exposure\` (e.g. \`{ type: 'api', path: '...', method: 'POST', auth: 'required', tenancy: 'required' }\`) or \`{ type: 'internal' }\` to opt out of API exposure.`,
+        message: `Action '${id}' has no \`exposure\`. Every action must declare \`exposure\` explicitly.`,
       });
+      continue;
     }
 
     if (action.exposure.type === 'api') {
-      errors.push(...checkApiExposureSecurity(action.id, action.exposure));
+      errors.push(...checkApiExposureSecurity(action.id, action.exposure as unknown as ActionApiExposureWithDeclaration));
+
+      // API actions must have input/output schema snapshots
+      if (!action.inputSchema) {
+        errors.push({
+          code: 'API_INPUT_SCHEMA_REQUIRED',
+          message: `Action '${id}' is API-exposed but has no \`inputSchema\`. API-exposed actions must declare input/output Zod schemas.`,
+        });
+      }
+      if (!action.outputSchema) {
+        errors.push({
+          code: 'API_OUTPUT_SCHEMA_REQUIRED',
+          message: `Action '${id}' is API-exposed but has no \`outputSchema\`. API-exposed actions must declare input/output Zod schemas.`,
+        });
+      }
     }
   }
 
@@ -217,9 +192,8 @@ function checkApiExposureSecurity(actionId: string, exposure: ActionApiExposureW
   const errors: ValidationError[] = [];
 
   // API_EXPOSURE_AUTH_REQUIRED — API-exposed actions must declare auth
-  // explicitly. The builder defaults auth to 'required' when the source
-  // omits it; the validator surfaces the omission so developers are not
-  // silently relying on the safe-default.
+  // explicitly. The builder now rejects missing auth, but we validate
+  // here too for completeness.
   if (exposure.authDeclared === false) {
     errors.push({
       code: 'API_EXPOSURE_AUTH_REQUIRED',
@@ -251,10 +225,7 @@ function checkApiExposureSecurity(actionId: string, exposure: ActionApiExposureW
   }
 
   // TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC — `tenancy: 'none'` on a
-  // public API route must justify the missing tenant context. If the
-  // route is already justified as anonymous via `auth: 'none'` the
-  // same `securityException` may be reused; otherwise an exception is
-  // required for tenancy: 'none' on its own.
+  // public API route must justify the missing tenant context.
   if (exposure.tenancy === 'none') {
     const reason = exposure.securityException?.reason;
     if (!reason || reason.trim().length === 0) {
@@ -267,8 +238,7 @@ function checkApiExposureSecurity(actionId: string, exposure: ActionApiExposureW
 
   // SYSTEM_API_REQUIRES_ROLE — `tenancy: 'system'` combined with
   // `auth: 'required'` must declare non-empty `roles` so the JWT
-  // authorizer can scope the call. Routes that use `auth: 'service'`
-  // are service-only and do not require role narrowing.
+  // authorizer can scope the call.
   if (exposure.tenancy === 'system' && exposure.auth === 'required') {
     if (!Array.isArray(exposure.roles) || exposure.roles.length === 0) {
       errors.push({
@@ -336,23 +306,12 @@ export async function runValidate(
 
   errors.push(...checkSubscriberSemverRanges(registry.subscribers));
 
-  // Issue #4689: defineApi and registry.apis were removed. The action-first
-  // validation rules in `checkActionFirstSecurity` cover the action surface
-  // that now owns all HTTP endpoints.
-
   const rawPathErrors = await checkRawPathViolations(registry.domainRoot, config);
   errors.push(...rawPathErrors);
 
-  // Wave 6 Task 6.1: action-first security validation gates (#4619).
-  // Runs against the registry built above so the rules see the same
-  // shape the CDK packer will eventually consume.
+  // Action-first security validation gates (#5090).
   errors.push(...checkActionFirstSecurity(registry.actions));
 
-  // Issue #4662 Task D — deployment-time security gates. These mirror
-  // the CDK synth-time `SecurityAssertionAspect` so violations are
-  // caught before any AWS deployment is attempted.
-  errors.push(...checkDeploymentSecurity(registry.actions));
-
   const totalPrimitives = registry.webhooks.length +
     registry.subscribers.length + registry.schedules.length +
     registry.jobs.length + registry.actions.length;

package/src/utils/toolchain-manifest.ts

@@ -0,0 +1,236 @@
+import { join, dirname } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Toolchain manifest types and factory for the @mettlecast publish workflow.
+ *
+ * The manifest is included in the published domain-cli tarball so that
+ * `mc-domain-module update-all` (or a future standalone updater) can
+ * determine exact package versions to install / pin.
+ *
+ * Manifest schema:
+ * ```json
+ * {
+ *   "schemaVersion": 1,
+ *   "registrySchemaVersion": "1",
+ *   "packages": {
+ *     "domainCli": "0.2.53",
+ *     "domainCdkPacker": "0.2.53",
+ *     "domainRuntime": "0.2.53",
+ *     "eslintPluginDomainModule": "0.2.53"
+ *   }
+ * }
+ * ```
+ *
+ * `registrySchemaVersion` matches the existing `DomainRegistry.schemaVersion`
+ * string literal `'1'` so that consumer validation can compare the manifest
+ * registry schema version to the generated registry schema version directly.
+ */
+
+/**
+ * Shape of the published toolchain-manifest.json at package root.
+ */
+export interface ToolchainManifest {
+  /** Manifest schema version (integer). Must be 1 for this generation. */
+  schemaVersion: number;
+  /**
+   * Registry schema version — a string matching the `DomainRegistry.schemaVersion`
+   * literal (currently `'1'`). Consumer validation compares this against the
+   * generated registry schema version to verify contract compatibility.
+   */
+  registrySchemaVersion: string;
+  packages: ToolchainPackages;
+}
+
+export interface ToolchainPackages {
+  domainCli: string;
+  domainCdkPacker: string;
+  domainRuntime: string;
+  eslintPluginDomainModule: string;
+}
+
+/**
+ * The expected registry schema version that matches `DomainRegistry.schemaVersion`.
+ * Consumer validation compares the manifest's `registrySchemaVersion` against
+ * this constant and the generated registry's `schemaVersion`.
+ */
+export const EXPECTED_REGISTRY_SCHEMA_VERSION = '1';
+
+/**
+ * Package identifiers used in the manifest.
+ * Maps to the `packages` key in ToolchainManifest.
+ */
+export type ToolchainPackageId = keyof ToolchainPackages;
+
+/**
+ * Create a ToolchainManifest from exact resolved versions.
+ * This is a pure factory function (no side-effects).
+ *
+ * @param versions - Exact semver strings for each package
+ * @returns A complete ToolchainManifest
+ */
+export function createToolchainManifest(versions: ToolchainPackages): ToolchainManifest {
+  return {
+    schemaVersion: 1,
+    registrySchemaVersion: EXPECTED_REGISTRY_SCHEMA_VERSION,
+    packages: {
+      domainCli: versions.domainCli,
+      domainCdkPacker: versions.domainCdkPacker,
+      domainRuntime: versions.domainRuntime,
+      eslintPluginDomainModule: versions.eslintPluginDomainModule,
+    },
+  };
+}
+
+/**
+ * Known @mettlecast dependency names that the domain-cli may reference
+ * with wildcard ranges and should be replaced with exact versions.
+ */
+export const METTLECAST_CLI_DEPS: Record<ToolchainPackageId, string> = {
+  domainCli: '@mettlecast/domain-cli',
+  domainCdkPacker: '@mettlecast/domain-cdk-packer',
+  domainRuntime: '@mettlecast/domain-runtime',
+  eslintPluginDomainModule: '@mettlecast/eslint-plugin-domain-module',
+};
+
+/**
+ * Rewrite the domain-cli package.json's @mettlecast dependencies from
+ * wildcard / workspace ranges to exact resolved versions.
+ *
+ * @param pkgJson - Parsed package.json content (mutated in place)
+ * @param versions - Exact semver versions for each toolchain package
+ * @returns True if any dependency was rewritten
+ */
+export function rewriteCliDependencies(
+  pkgJson: { dependencies?: Record<string, string> },
+  versions: ToolchainPackages,
+): boolean {
+  let changed = false;
+
+  if (!pkgJson.dependencies) return changed;
+
+  for (const [id, depName] of Object.entries(METTLECAST_CLI_DEPS)) {
+    const packageId = id as ToolchainPackageId;
+    if (depName in pkgJson.dependencies) {
+      const exact = versions[packageId];
+      pkgJson.dependencies[depName] = exact;
+      changed = true;
+    }
+  }
+
+  return changed;
+}
+
+/**
+ * Resolve the toolchain manifest from the installed @mettlecast/domain-cli package.
+ * Tries the project's `node_modules/@mettlecast/domain-cli/` first, then falls
+ * back to the CLI's own package root (for global/npx installations).
+ *
+ * @param projectRoot - Project root directory.
+ * @returns The parsed toolchain manifest.
+ * @throws If the manifest is missing, malformed, or has an incompatible schema version.
+ */
+export async function loadToolchainManifest(projectRoot: string): Promise<ToolchainManifest> {
+  // Primary path: project's node_modules
+  const projectManifestPath = join(
+    projectRoot,
+    'node_modules',
+    '@mettlecast',
+    'domain-cli',
+    'toolchain-manifest.json',
+  );
+
+  // Fallback path: CLI's own package root (resolved from this module's location)
+  const cliPackageRoot = resolveCliPackageRoot();
+  const cliManifestPath = join(cliPackageRoot, 'toolchain-manifest.json');
+
+  let manifestPath: string;
+
+  if (existsSync(projectManifestPath)) {
+    manifestPath = projectManifestPath;
+  } else if (existsSync(cliManifestPath)) {
+    manifestPath = cliManifestPath;
+  } else {
+    throw new Error(
+      `toolchain-manifest.json not found at ${projectManifestPath} or ${cliManifestPath}. ` +
+        "Run 'npm install' or 'npm ci' in the project root first, then retry.",
+    );
+  }
+
+  const raw = await readFile(manifestPath, 'utf-8');
+  let manifest: ToolchainManifest;
+  try {
+    manifest = JSON.parse(raw) as ToolchainManifest;
+  } catch {
+    throw new Error(
+      `toolchain-manifest.json at ${manifestPath} is not valid JSON.`,
+    );
+  }
+
+  // Validate schema version
+  if (typeof manifest.schemaVersion !== 'number' || manifest.schemaVersion !== 1) {
+    throw new Error(
+      `toolchain manifest schemaVersion is ${String(manifest.schemaVersion)}, expected 1. ` +
+        'The installed @mettlecast/domain-cli version is incompatible with this toolchain resolver.',
+    );
+  }
+
+  // Validate registry schema version equals expected value
+  if (
+    typeof manifest.registrySchemaVersion !== 'string' ||
+    manifest.registrySchemaVersion !== EXPECTED_REGISTRY_SCHEMA_VERSION
+  ) {
+    throw new Error(
+      `toolchain manifest registrySchemaVersion is "${String(manifest.registrySchemaVersion)}", ` +
+        `expected "${EXPECTED_REGISTRY_SCHEMA_VERSION}". ` +
+        'The registry schema contract is incompatible with this toolchain resolver.',
+    );
+  }
+
+  // Validate all package keys are present and non-empty
+  if (!manifest.packages || typeof manifest.packages !== 'object') {
+    throw new Error(
+      'toolchain manifest is missing required field "packages".',
+    );
+  }
+
+  const TOOLCHAIN_PACKAGE_KEYS: Array<keyof ToolchainPackages> = [
+    'domainCli',
+    'domainCdkPacker',
+    'domainRuntime',
+    'eslintPluginDomainModule',
+  ];
+
+  for (const key of TOOLCHAIN_PACKAGE_KEYS) {
+    const version = manifest.packages[key];
+    if (typeof version !== 'string' || version.length === 0) {
+      throw new Error(
+        `toolchain manifest is missing or has empty version for package "${key}".`,
+      );
+    }
+  }
+
+  return manifest;
+}
+
+/**
+ * Resolve the @mettlecast/domain-cli package root directory.
+ * Uses the location of this module file (toolchain-manifest.ts) to find
+ * the CLI package root, supporting both source and dist layouts.
+ */
+function resolveCliPackageRoot(): string {
+  const thisFile = fileURLToPath(import.meta.url);
+  // In source: packages/domain-cli/src/utils/toolchain-manifest.ts -> up 3 levels
+  // In dist: packages/domain-cli/dist/utils/toolchain-manifest.js -> up 2 levels
+  const candidate = dirname(dirname(dirname(thisFile)));
+  // Check if candidate has package.json with @mettlecast/domain-cli name
+  const pkgJsonPath = join(candidate, 'package.json');
+  if (existsSync(pkgJsonPath)) {
+    return candidate;
+  }
+  // Fall back to dirname(dirname(thisFile)) for dist layout
+  const candidate2 = dirname(dirname(thisFile));
+  return candidate2;
+}

package/toolchain-manifest.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "registrySchemaVersion": "1",
+  "packages": {
+    "domainCli": "0.2.87",
+    "domainCdkPacker": "0.2.88",
+    "domainRuntime": "0.2.87",
+    "eslintPluginDomainModule": "0.2.87"
+  }
+}