@mettlecast/domain-cli 0.2.86 → 0.2.87

package/dist/utils/toolchain-manifest.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 declare 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 declare function createToolchainManifest(versions: ToolchainPackages): ToolchainManifest;
+/**
+ * Known @mettlecast dependency names that the domain-cli may reference
+ * with wildcard ranges and should be replaced with exact versions.
+ */
+export declare const METTLECAST_CLI_DEPS: Record<ToolchainPackageId, string>;
+/**
+ * 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 declare function rewriteCliDependencies(pkgJson: {
+    dependencies?: Record<string, string>;
+}, versions: ToolchainPackages): boolean;
+/**
+ * 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 declare function loadToolchainManifest(projectRoot: string): Promise<ToolchainManifest>;

package/dist/utils/toolchain-manifest.js

@@ -0,0 +1,144 @@
+import { join, dirname } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/**
+ * 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';
+/**
+ * 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) {
+    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 = {
+    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, versions) {
+    let changed = false;
+    if (!pkgJson.dependencies)
+        return changed;
+    for (const [id, depName] of Object.entries(METTLECAST_CLI_DEPS)) {
+        const packageId = id;
+        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) {
+    // 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;
+    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;
+    try {
+        manifest = JSON.parse(raw);
+    }
+    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 = [
+        '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() {
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mettlecast/domain-cli",
-  "version": "0.2.86",
+  "version": "0.2.87",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -22,8 +22,8 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.0.0",
     "@aws-sdk/client-sfn": "^3.0.0",
-    "@mettlecast/domain-cdk-packer": "*",
-    "@mettlecast/domain-runtime": "*",
+    "@mettlecast/domain-cdk-packer": "0.2.88",
+    "@mettlecast/domain-runtime": "0.2.87",
     "commander": "^12.0.0",
     "dotenv": "^16.0.0",
     "fastify": "^5.0.0",

package/scripts/generate-toolchain-manifest.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+/**
+ * generate-toolchain-manifest.mjs
+ *
+ * Generates toolchain-manifest.json in the domain-cli package root and,
+ * optionally, rewrites wildcard @mettlecast dependencies in the domain-cli
+ * package.json to exact resolved versions.
+ *
+ * Usage:
+ *   node generate-toolchain-manifest.mjs \
+ *     --cli-version 0.2.53 \
+ *     --runtime-version 0.2.53 \
+ *     --packer-version 0.2.53 \
+ *     --eslint-version 0.2.53 \
+ *     [--rewrite-deps]
+ *
+ * All version flags are required.
+ * The --rewrite-deps flag additionally rewrites the domain-cli's package.json
+ * so that @mettlecast/* dependency ranges are pinned to exact versions.
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI_PKG_DIR = resolve(__dirname, '..');
+const PROJECT_ROOT = resolve(__dirname, '..', '..', '..');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const opts = {
+    cliVersion: '',
+    runtimeVersion: '',
+    packerVersion: '',
+    eslintVersion: '',
+    rewriteDeps: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--cli-version':
+        opts.cliVersion = args[++i];
+        break;
+      case '--runtime-version':
+        opts.runtimeVersion = args[++i];
+        break;
+      case '--packer-version':
+        opts.packerVersion = args[++i];
+        break;
+      case '--eslint-version':
+        opts.eslintVersion = args[++i];
+        break;
+      case '--rewrite-deps':
+        opts.rewriteDeps = true;
+        break;
+      default:
+        console.error(`Unknown flag: ${args[i]}`);
+        process.exit(1);
+    }
+  }
+
+  if (!opts.cliVersion || !opts.runtimeVersion || !opts.packerVersion || !opts.eslintVersion) {
+    console.error(
+      'Missing required flags: --cli-version, --runtime-version, --packer-version, --eslint-version',
+    );
+    process.exit(1);
+  }
+
+  return opts;
+}
+
+/**
+ * Create a ToolchainManifest object.
+ */
+function createToolchainManifest(versions) {
+  return {
+    schemaVersion: 1,
+    registrySchemaVersion: '1',
+    packages: {
+      domainCli: versions.cliVersion,
+      domainCdkPacker: versions.packerVersion,
+      domainRuntime: versions.runtimeVersion,
+      eslintPluginDomainModule: versions.eslintVersion,
+    },
+  };
+}
+
+/**
+ * Rewrite @mettlecast dependencies in the given package.json to exact versions.
+ * Returns true if any dep was modified.
+ */
+function rewriteCliDependencies(pkgJson, versions) {
+  const depMap = {
+    '@mettlecast/domain-cli': versions.cliVersion,
+    '@mettlecast/domain-cdk-packer': versions.packerVersion,
+    '@mettlecast/domain-runtime': versions.runtimeVersion,
+    '@mettlecast/eslint-plugin-domain-module': versions.eslintVersion,
+  };
+
+  let changed = false;
+  if (!pkgJson.dependencies) return changed;
+
+  for (const [depName, exactVersion] of Object.entries(depMap)) {
+    if (depName in pkgJson.dependencies) {
+      pkgJson.dependencies[depName] = exactVersion;
+      changed = true;
+    }
+  }
+
+  return changed;
+}
+
+async function main() {
+  const opts = parseArgs();
+
+  // 1. Generate toolchain-manifest.json
+  const manifest = createToolchainManifest({
+    cliVersion: opts.cliVersion,
+    runtimeVersion: opts.runtimeVersion,
+    packerVersion: opts.packerVersion,
+    eslintVersion: opts.eslintVersion,
+  });
+
+  const manifestPath = resolve(CLI_PKG_DIR, 'toolchain-manifest.json');
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+  console.log(`Generated toolchain-manifest.json → ${manifestPath}`);
+
+  // 2. Optionally rewrite domain-cli package.json deps
+  if (opts.rewriteDeps) {
+    const pkgJsonPath = resolve(CLI_PKG_DIR, 'package.json');
+    const rawPkg = await readFile(pkgJsonPath, 'utf-8');
+    const pkgJson = JSON.parse(rawPkg);
+
+    const changed = rewriteCliDependencies(pkgJson, {
+      cliVersion: opts.cliVersion,
+      runtimeVersion: opts.runtimeVersion,
+      packerVersion: opts.packerVersion,
+      eslintVersion: opts.eslintVersion,
+    });
+
+    if (changed) {
+      await writeFile(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + '\n', 'utf-8');
+      console.log(`Rewrote @mettlecast deps in package.json → ${pkgJsonPath}`);
+    } else {
+      console.log('No @mettlecast deps to rewrite in package.json');
+    }
+  }
+
+  // For CI consumption, print version summary
+  console.log(`\n--- toolchain versions ---`);
+  console.log(`domain-runtime:             ${opts.runtimeVersion}`);
+  console.log(`domain-cdk-packer:          ${opts.packerVersion}`);
+  console.log(`eslint-plugin-domain-module: ${opts.eslintVersion}`);
+  console.log(`domain-cli:                 ${opts.cliVersion}`);
+  console.log(`rewrite-deps:               ${opts.rewriteDeps}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/__tests__/build-registry.test.ts

@@ -53,9 +53,6 @@ describe('buildRegistry', () => {
   });
 
   it('builds a registry with domain + one API-exposed action', async () => {
-    // Issue #4689: defineApi was removed; the canonical HTTP endpoint
-    // surface is `defineAction({ exposure: { type: 'api', ... } })`.
-    // The action is recorded under `registry.actions` with API exposure metadata.
     mockWalkDomainDir.mockResolvedValue({
       domain: '/fake/domains/billing/domain.config.ts',
       webhooks: [],
@@ -162,4 +159,129 @@ describe('buildRegistry', () => {
     expect(warnings[0]).toContain('tsx error');
     expect(registry.actions).toHaveLength(0);
   });
+
+  /**
+   * Strict contract (#5090): missing exposure causes build failure
+   */
+  it('throws when action has no exposure (#5090)', async () => {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      webhooks: [],
+      subscribers: [],
+      actions: ['/fake/domains/billing/actions/no-exposure.ts'],
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+
+    mockLoadModuleExports
+      .mockResolvedValueOnce([
+        { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+      ])
+      .mockResolvedValueOnce([
+        {
+          _kind: 'action',
+          _exportName: 'noExposure',
+          id: 'no-exposure',
+          backendAccess: 'private',
+          // exposure deliberately omitted
+          idempotent: false,
+        },
+      ]);
+
+    await expect(buildRegistry(DOMAIN_ROOT)).rejects.toThrow(/exposure/i);
+  });
+
+  it('throws when action has missing backendAccess (#5090)', async () => {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      webhooks: [],
+      subscribers: [],
+      actions: ['/fake/domains/billing/actions/no-backend.ts'],
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+
+    mockLoadModuleExports
+      .mockResolvedValueOnce([
+        { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+      ])
+      .mockResolvedValueOnce([
+        {
+          _kind: 'action',
+          _exportName: 'noBackend',
+          id: 'no-backend',
+          // backendAccess omitted
+          exposure: { type: 'internal' },
+          idempotent: false,
+        },
+      ]);
+
+    await expect(buildRegistry(DOMAIN_ROOT)).rejects.toThrow(/backendAccess/i);
+  });
+
+  it('throws when action has missing idempotent (#5090)', async () => {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      webhooks: [],
+      subscribers: [],
+      actions: ['/fake/domains/billing/actions/no-idempotent.ts'],
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+
+    mockLoadModuleExports
+      .mockResolvedValueOnce([
+        { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+      ])
+      .mockResolvedValueOnce([
+        {
+          _kind: 'action',
+          _exportName: 'noIdempotent',
+          id: 'no-idempotent',
+          backendAccess: 'private',
+          exposure: { type: 'internal' },
+          // idempotent omitted
+        },
+      ]);
+
+    await expect(buildRegistry(DOMAIN_ROOT)).rejects.toThrow(/idempotent/i);
+  });
+
+  it('accepts a valid internal action with exposure explicitly declared (#5090)', async () => {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      webhooks: [],
+      subscribers: [],
+      actions: ['/fake/domains/billing/actions/internal.ts'],
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+
+    mockLoadModuleExports
+      .mockResolvedValueOnce([
+        { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+      ])
+      .mockResolvedValueOnce([
+        {
+          _kind: 'action',
+          _exportName: 'internalOnly',
+          id: 'internal-only',
+          backendAccess: 'private',
+          exposure: { type: 'internal' },
+          idempotent: false,
+        },
+      ]);
+
+    const { registry } = await buildRegistry(DOMAIN_ROOT);
+    expect(registry.actions).toHaveLength(1);
+    expect(registry.actions[0]!.exposure).toEqual({ type: 'internal' });
+  });
 });