@aws/ml-container-creator 0.7.1 → 0.9.0

package/src/lib/config-manager.js

@@ -1089,6 +1089,17 @@ export default class ConfigManager {
                 required: false,
                 default: 64,
                 valueSpace: 'bounded'
+            },
+            modelPackageArn: {
+                cliOption: 'model-package-arn',
+                envVar: null,
+                configFile: true,
+                packageJson: false,
+                mcp: true,
+                promptable: true,
+                required: false,
+                default: null,
+                valueSpace: 'unbounded'
             }
         };
     }
@@ -1860,6 +1871,14 @@ export default class ConfigManager {
             }
         }
 
+        // Validate model package ARN format if provided
+        if (this.config.modelPackageArn) {
+            const modelPackageArnPattern = /^arn:aws:sagemaker:[a-z0-9-]+:\d{12}:model-package\/[a-zA-Z0-9]([a-zA-Z0-9-])*\/\d+$/;
+            if (!modelPackageArnPattern.test(this.config.modelPackageArn)) {
+                errors.push('❌ Invalid model package ARN format. Expected: arn:aws:sagemaker:<region>:<account>:model-package/<name>/<version>');
+            }
+        }
+
         // Only validate required parameters if we're skipping prompts
         // If prompts are available, missing parameters can be collected later
         if (this.skipPrompts) {
@@ -1946,10 +1965,15 @@ export default class ConfigManager {
                 const value = finalConfig[param];
                 const isEmpty = value === null || value === undefined || value === '';
                 
-                // Special case: modelFormat is not required for transformers/triton/diffusors
-                if (param === 'modelFormat' && (finalConfig.architecture === 'transformers' || finalConfig.architecture === 'triton' || finalConfig.architecture === 'diffusors')) {
+                // Special case: modelFormat is not required for transformers/triton/diffusors/marketplace
+                if (param === 'modelFormat' && (finalConfig.architecture === 'transformers' || finalConfig.architecture === 'triton' || finalConfig.architecture === 'diffusors' || finalConfig.architecture === 'marketplace')) {
                     return; // Skip validation
                 }
+
+                // Special case: marketplace projects don't need container-related parameters
+                if (finalConfig.architecture === 'marketplace' && (param === 'includeSampleModel' || param === 'buildTarget')) {
+                    return; // Skip validation — marketplace has no container to build
+                }
                 
                 // Special case: instanceType is not required for hyperpod-eks
                 // when not provided (backward compatibility) — but it IS prompted now
@@ -2368,6 +2392,19 @@ export default class ConfigManager {
                 }
             }
             break;
+
+        case 'modelPackageArn':
+            if (value) {
+                const modelPackageArnPattern = /^arn:aws:sagemaker:[a-z0-9-]+:\d{12}:model-package\/[a-zA-Z0-9]([a-zA-Z0-9-])*\/\d+$/;
+                if (!modelPackageArnPattern.test(value)) {
+                    throw new ValidationError(
+                        '❌ Invalid model package ARN format. Expected: arn:aws:sagemaker:<region>:<account>:model-package/<name>/<version>',
+                        parameter,
+                        value
+                    );
+                }
+            }
+            break;
         }
     }
 

package/src/lib/cross-cutting-checker.js

@@ -23,6 +23,7 @@ export default class CrossCuttingChecker {
         findings.push(...this.checkCudaCompatibility(context, instanceCatalog));
         findings.push(...this.checkModelTypeInstanceAlignment(context, instanceCatalog));
         findings.push(...this.checkKvCacheMemoryFit(context, instanceCatalog));
+        findings.push(...this.checkMarketplaceCompatibility(context));
 
         return findings;
     }
@@ -142,7 +143,7 @@ export default class CrossCuttingChecker {
     }
 
     /**
-     * Verify model source requirements (artifact URI, hub access config).
+     * Verify model source requirements (artifact URI).
      * @param {Object} context - ValidationContext
      * @returns {Array} Findings
      */
@@ -152,38 +153,8 @@ export default class CrossCuttingChecker {
 
         const modelSource = config.modelSource || config.MODEL_SOURCE || '';
 
-        // When modelSource is 'jumpstart-hub', verify HubAccessConfig.HubContentArn is present
-        if (modelSource === 'jumpstart-hub') {
-            const payloads = context.payloads || {};
-            let hubContentArnFound = false;
-
-            for (const payload of Object.values(payloads)) {
-                if (payload?.HubAccessConfig?.HubContentArn) {
-                    hubContentArnFound = true;
-                    break;
-                }
-            }
-
-            if (!hubContentArnFound && !config.HUB_CONTENT_ARN) {
-                findings.push({
-                    service: 'cross-cutting',
-                    operation: 'configuration',
-                    fieldPath: 'HubAccessConfig.HubContentArn',
-                    invalidValue: null,
-                    constraint: {
-                        type: 'conditional-required',
-                        condition: 'modelSource === jumpstart-hub'
-                    },
-                    severity: 'error',
-                    confidence: 'high',
-                    source: 'cross-cutting',
-                    remediationHint: 'When modelSource is "jumpstart-hub", HubAccessConfig.HubContentArn must be present in the payload.'
-                });
-            }
-        }
-
-        // When modelSource in {s3, jumpstart, jumpstart-hub, registry}, verify MODEL_ARTIFACT_URI is non-empty
-        const sourcesRequiringArtifact = ['s3', 'jumpstart', 'jumpstart-hub', 'registry'];
+        // When modelSource in {s3, registry}, verify MODEL_ARTIFACT_URI is non-empty
+        const sourcesRequiringArtifact = ['s3', 'registry'];
         if (sourcesRequiringArtifact.includes(modelSource)) {
             const artifactUri = config.MODEL_ARTIFACT_URI || '';
             if (!artifactUri || artifactUri.trim() === '') {
@@ -457,4 +428,146 @@ export default class CrossCuttingChecker {
 
         return findings;
     }
+
+    /**
+     * Validate marketplace model package compatibility.
+     * Checks ARN format, subscription status, instance type support,
+     * deployment target support, LoRA incompatibility, and adapter operations.
+     *
+     * For live AWS API checks (DescribeModelPackage), gracefully skips
+     * when credentials are unavailable — only format checks are enforced.
+     *
+     * @param {Object} context - ValidationContext
+     * @returns {Array} Findings
+     */
+    checkMarketplaceCompatibility(context) {
+        const findings = [];
+        const config = context.config || {};
+
+        const architecture = config.architecture || config.DEPLOYMENT_CONFIG || '';
+        if (architecture !== 'marketplace') return findings;
+
+        // 1. Validate ARN format
+        const modelPackageArn = config.modelPackageArn || config.MODEL_PACKAGE_ARN || '';
+        if (modelPackageArn) {
+            const arnPattern = /^arn:aws:sagemaker:[a-z0-9-]+:\d{12}:model-package\/[a-zA-Z0-9]([a-zA-Z0-9-])*\/\d+$/;
+            if (!arnPattern.test(modelPackageArn)) {
+                findings.push({
+                    service: 'cross-cutting',
+                    operation: 'configuration',
+                    fieldPath: 'MODEL_PACKAGE_ARN',
+                    invalidValue: modelPackageArn,
+                    constraint: {
+                        type: 'arn-format',
+                        pattern: 'arn:aws:sagemaker:<region>:<account>:model-package/<name>/<version>'
+                    },
+                    severity: 'error',
+                    confidence: 'high',
+                    source: 'cross-cutting',
+                    remediationHint: '❌ Invalid model package ARN format. Expected: arn:aws:sagemaker:<region>:<account>:model-package/<name>/<version>'
+                });
+            }
+        }
+
+        // 2. Verify subscription is active (when package metadata is available)
+        const packageStatus = config._marketplacePackageStatus || config.marketplacePackageStatus || '';
+        if (packageStatus && packageStatus !== 'Active' && packageStatus !== 'Completed') {
+            findings.push({
+                service: 'cross-cutting',
+                operation: 'configuration',
+                fieldPath: 'MODEL_PACKAGE_ARN',
+                invalidValue: modelPackageArn,
+                constraint: {
+                    type: 'subscription-status',
+                    status: packageStatus
+                },
+                severity: 'error',
+                confidence: 'high',
+                source: 'cross-cutting',
+                remediationHint: `❌ Marketplace subscription is not active (status: ${packageStatus}). Renew at AWS Marketplace.`
+            });
+        }
+
+        // 3. Verify instance type is in package's supported list
+        const instanceType = config.INSTANCE_TYPE || config.instanceType || '';
+        const supportedInstanceTypes = config._supportedInstanceTypes || config.supportedInstanceTypes || [];
+        if (instanceType && supportedInstanceTypes.length > 0) {
+            if (!supportedInstanceTypes.includes(instanceType)) {
+                findings.push({
+                    service: 'cross-cutting',
+                    operation: 'configuration',
+                    fieldPath: 'INSTANCE_TYPE',
+                    invalidValue: instanceType,
+                    constraint: {
+                        type: 'marketplace-instance-type',
+                        supportedInstanceTypes
+                    },
+                    severity: 'error',
+                    confidence: 'high',
+                    source: 'cross-cutting',
+                    remediationHint: `❌ Instance type ${instanceType} is not supported by this model package. Supported: ${supportedInstanceTypes.join(', ')}`
+                });
+            }
+        }
+
+        // 4. Verify deployment target is supported by the package
+        const deploymentTarget = context.deploymentTarget || config.deploymentTarget || config.DEPLOYMENT_TARGET || '';
+        const supportedDeploymentTargets = config._supportedDeploymentTargets || config.supportedDeploymentTargets || [];
+        if (deploymentTarget && supportedDeploymentTargets.length > 0) {
+            if (!supportedDeploymentTargets.includes(deploymentTarget)) {
+                findings.push({
+                    service: 'cross-cutting',
+                    operation: 'configuration',
+                    fieldPath: 'DEPLOYMENT_TARGET',
+                    invalidValue: deploymentTarget,
+                    constraint: {
+                        type: 'marketplace-deployment-target',
+                        supportedDeploymentTargets
+                    },
+                    severity: 'error',
+                    confidence: 'high',
+                    source: 'cross-cutting',
+                    remediationHint: `❌ Deployment target ${deploymentTarget} is not supported by this model package.`
+                });
+            }
+        }
+
+        // 5. Reject LoRA with marketplace
+        const enableLora = config.enableLora || config.ENABLE_LORA || false;
+        if (enableLora === true || enableLora === 'true') {
+            findings.push({
+                service: 'cross-cutting',
+                operation: 'configuration',
+                fieldPath: 'enableLora',
+                invalidValue: true,
+                constraint: {
+                    type: 'marketplace-lora-incompatible'
+                },
+                severity: 'error',
+                confidence: 'high',
+                source: 'cross-cutting',
+                remediationHint: '❌ LoRA adapters are not supported for Marketplace model packages (vendor controls the model).'
+            });
+        }
+
+        // 6. Reject adapter operations on marketplace projects
+        const operation = config._operation || config.operation || '';
+        if (operation === 'adapter' || operation === 'do/adapter') {
+            findings.push({
+                service: 'cross-cutting',
+                operation: 'configuration',
+                fieldPath: 'operation',
+                invalidValue: operation,
+                constraint: {
+                    type: 'marketplace-adapter-incompatible'
+                },
+                severity: 'error',
+                confidence: 'high',
+                source: 'cross-cutting',
+                remediationHint: '❌ Adapter operations are not available for Marketplace projects.'
+            });
+        }
+
+        return findings;
+    }
 }

package/src/lib/deployment-config-resolver.js

@@ -12,7 +12,7 @@
 
 /**
  * Canonical mapping from deployment-config strings to structured parts.
- * 2 http + 5 transformers + 7 triton + 1 diffusors = 15 total configs.
+ * 2 http + 5 transformers + 7 triton + 1 diffusors + 1 marketplace = 16 total configs.
  */
 const CANONICAL_CONFIGS = new Map([
     // HTTP architecture (2)
@@ -36,7 +36,10 @@ const CANONICAL_CONFIGS = new Map([
     ['triton-python',           { architecture: 'triton',       backend: 'python',        engine: null }],
 
     // Diffusors architecture (1)
-    ['diffusors-vllm-omni',     { architecture: 'diffusors',    backend: 'vllm-omni',     engine: null }]
+    ['diffusors-vllm-omni',     { architecture: 'diffusors',    backend: 'vllm-omni',     engine: null }],
+
+    // Marketplace architecture (1) — no backend, vendor controls the container
+    ['marketplace',             { architecture: 'marketplace',  backend: null,            engine: null }]
 ]);
 
 export default class DeploymentConfigResolver {
@@ -62,15 +65,18 @@ export default class DeploymentConfigResolver {
      * Compose a deployment-config string from structured parts.
      * Inverse of decompose().
      *
-     * @param {{ architecture: string, backend: string, engine?: string }} parts
+     * @param {{ architecture: string, backend: string|null, engine?: string }} parts
      * @returns {string}
      */
     compose(parts) {
+        if (!parts.backend) {
+            return parts.architecture;
+        }
         return `${parts.architecture}-${parts.backend}`;
     }
 
     /**
-     * Get all 15 valid deployment-config strings.
+     * Get all 16 valid deployment-config strings.
      *
      * @returns {string[]}
      */

package/src/lib/e2e-bootstrap.js

@@ -0,0 +1,227 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * E2E Bootstrap Integration
+ *
+ * Handles the `bootstrap --ci --e2e` flow:
+ * 1. Loads the e2e catalog
+ * 2. Runs quota validation for the CI tier and emits warnings
+ * 3. Deploys the config/bootstrap-e2e-stack.json CloudFormation stack
+ * 4. Stores e2e config (bucket, SNS ARN, CodeBuild project name) in bootstrap config
+ *
+ * Requirements: 3.3, 3.4
+ */
+
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateQuotas } from './e2e-quota-validator.js';
+import { validateCatalog } from './e2e-catalog-validator.js';
+import BootstrapConfig from './bootstrap-config.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const E2E_STACK_NAME = 'mlcc-bootstrap-e2e';
+const E2E_STACK_TEMPLATE_PATH = path.resolve(__dirname, '../../config/bootstrap-e2e-stack.json');
+const DEFAULT_CATALOG_PATH = path.resolve(__dirname, '../../scripts/e2e-catalog.json');
+
+/**
+ * Bootstrap E2E infrastructure.
+ *
+ * Loads the catalog, validates quotas for the CI tier, deploys the
+ * CloudFormation stack, and stores e2e config in the bootstrap profile.
+ *
+ * @param {Object} options
+ * @param {string} options.region - AWS region
+ * @param {string} options.profile - AWS CLI profile name
+ * @param {string} [options.catalogPath] - Path to the e2e catalog JSON file
+ * @param {string} [options.profileName] - Bootstrap profile name (default: 'default')
+ * @param {Object} [options.bootstrapConfig] - Pre-configured BootstrapConfig instance (for testing)
+ * @returns {Promise<Object>} The e2e config object with bucket, SNS ARN, and CodeBuild project name
+ */
+export async function bootstrapE2E(options) {
+    const {
+        region,
+        profile,
+        catalogPath = DEFAULT_CATALOG_PATH,
+        profileName = 'default',
+        bootstrapConfig
+    } = options;
+
+    console.log('\n🧪 E2E Validation Infrastructure Setup\n');
+
+    // Step 1: Load and validate the catalog
+    console.log('  📋 Loading e2e catalog...');
+    const catalog = loadCatalog(catalogPath);
+    console.log(`  ✅ Catalog loaded (${catalog.configs.length} configs)`);
+
+    // Step 2: Run quota validation for CI tier
+    console.log('\n  🔍 Checking service quotas for CI tier...');
+    const quotaResults = await runQuotaValidation('ci', catalog, region);
+
+    if (quotaResults.length === 0) {
+        console.log('  ℹ️  No instance types to validate for CI tier');
+    } else {
+        const insufficient = quotaResults.filter(r => !r.sufficient);
+        if (insufficient.length === 0) {
+            console.log('  ✅ All quotas sufficient for CI tier');
+        } else {
+            for (const result of insufficient) {
+                console.log(`  ⚠️  ${result.instanceType} quota is ${result.available}, need ${result.required} for CI tier`);
+            }
+        }
+    }
+
+    // Step 3: Deploy the E2E CloudFormation stack
+    console.log('\n  ☁️  Deploying E2E infrastructure stack...');
+    const stackOutputs = deployE2EStack(profile, region);
+    console.log('  ✅ E2E stack deployed successfully');
+
+    // Step 4: Store e2e config in bootstrap profile
+    const e2eConfig = {
+        e2eInfraProvisioned: true,
+        e2eCodeBuildProject: stackOutputs.CodeBuildProjectName || 'ml-container-creator-e2e',
+        e2eResultsBucket: stackOutputs.ResultsBucketName || `mlcc-e2e-results-unknown-${region}`,
+        e2eSnsTopicArn: stackOutputs.NotificationsTopicArn || ''
+    };
+
+    console.log('\n  💾 Saving e2e config to bootstrap profile...');
+    const config = bootstrapConfig || new BootstrapConfig();
+    storeE2EConfig(config, profileName, e2eConfig);
+    console.log('  ✅ E2E config saved');
+
+    // Display summary
+    console.log('\n  📋 E2E Infrastructure Summary:');
+    console.log(`     CodeBuild project: ${e2eConfig.e2eCodeBuildProject}`);
+    console.log(`     Results bucket:    ${e2eConfig.e2eResultsBucket}`);
+    console.log(`     SNS topic:         ${e2eConfig.e2eSnsTopicArn}`);
+
+    return e2eConfig;
+}
+
+/**
+ * Load and validate the e2e catalog from a JSON file.
+ *
+ * @param {string} catalogPath - Path to the catalog JSON file
+ * @returns {Object} The validated catalog object
+ * @throws {Error} If the catalog file cannot be read or is invalid
+ */
+export function loadCatalog(catalogPath) {
+    let raw;
+    try {
+        raw = readFileSync(catalogPath, 'utf8');
+    } catch (err) {
+        throw new Error(`Failed to read e2e catalog at ${catalogPath}: ${err.message}`);
+    }
+
+    let catalog;
+    try {
+        catalog = JSON.parse(raw);
+    } catch (err) {
+        throw new Error(`Failed to parse e2e catalog JSON: ${err.message}`);
+    }
+
+    const validation = validateCatalog(catalog);
+    if (!validation.valid) {
+        const errorMessages = validation.errors.map(e => `  ${e.path}: ${e.message}`).join('\n');
+        throw new Error(`E2E catalog validation failed:\n${errorMessages}`);
+    }
+
+    return catalog;
+}
+
+/**
+ * Run quota validation for a given tier and emit warnings.
+ *
+ * @param {string} tier - The tier to validate (e.g., 'ci')
+ * @param {Object} catalog - The validated catalog object
+ * @param {string} region - AWS region
+ * @returns {Promise<Array<{instanceType: string, required: number, available: number, sufficient: boolean}>>}
+ */
+export async function runQuotaValidation(tier, catalog, region) {
+    try {
+        return await validateQuotas(tier, catalog, region);
+    } catch (err) {
+        console.warn(`  ⚠️  Quota validation failed: ${err.message}`);
+        console.warn('     Continuing without quota validation...');
+        return [];
+    }
+}
+
+/**
+ * Deploy the E2E CloudFormation stack.
+ *
+ * Uses `aws cloudformation deploy` which handles both CREATE and UPDATE scenarios.
+ *
+ * @param {string} awsProfile - AWS CLI profile name
+ * @param {string} region - AWS region
+ * @returns {Object} Map of stack output key → output value
+ * @throws {Error} If stack deployment fails
+ */
+export function deployE2EStack(awsProfile, region) {
+    const deployCommand = [
+        'aws cloudformation deploy',
+        `--template-file ${E2E_STACK_TEMPLATE_PATH}`,
+        `--stack-name ${E2E_STACK_NAME}`,
+        '--capabilities CAPABILITY_NAMED_IAM',
+        `--profile ${awsProfile}`,
+        `--region ${region}`
+    ].join(' ');
+
+    try {
+        execSync(deployCommand, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (error) {
+        // "No changes to deploy" is a success case — CloudFormation deploy
+        // exits with code 255 when there's nothing to update
+        const stderr = error.stderr || error.message || '';
+        if (stderr.includes('No changes to deploy')) {
+            console.log('  ℹ️  E2E stack is up to date — no changes needed');
+        } else {
+            throw new Error(`E2E stack deployment failed: ${stderr}`);
+        }
+    }
+
+    // Read stack outputs
+    const describeCommand = `aws cloudformation describe-stacks --stack-name ${E2E_STACK_NAME} --region ${region} --profile ${awsProfile} --output json`;
+    let describeOutput;
+    try {
+        describeOutput = execSync(describeCommand, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (err) {
+        throw new Error(`Failed to read E2E stack outputs: ${err.message}`);
+    }
+
+    const describeResult = JSON.parse(describeOutput.trim());
+    const stack = describeResult.Stacks && describeResult.Stacks[0];
+    if (!stack) {
+        throw new Error(`Stack "${E2E_STACK_NAME}" not found after deployment`);
+    }
+
+    const outputs = {};
+    for (const output of (stack.Outputs || [])) {
+        outputs[output.OutputKey] = output.OutputValue;
+    }
+
+    return outputs;
+}
+
+/**
+ * Store e2e config fields in the bootstrap profile.
+ *
+ * @param {BootstrapConfig} config - BootstrapConfig instance
+ * @param {string} profileName - The profile name to update
+ * @param {Object} e2eConfig - The e2e config fields to store
+ */
+export function storeE2EConfig(config, profileName, e2eConfig) {
+    const fullConfig = config.read();
+    if (!fullConfig || !fullConfig.profiles || !fullConfig.profiles[profileName]) {
+        throw new Error(`Bootstrap profile "${profileName}" not found. Run bootstrap first.`);
+    }
+
+    const profileData = fullConfig.profiles[profileName];
+    Object.assign(profileData, e2eConfig);
+    fullConfig.profiles[profileName] = profileData;
+    config.write(fullConfig);
+}

package/src/lib/e2e-catalog-validator.js

@@ -0,0 +1,103 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * E2E Catalog Validator
+ *
+ * Validates the e2e test catalog against a JSON Schema and enforces
+ * additional constraints (unique IDs) that JSON Schema alone cannot express.
+ * Also provides tier-based filtering of catalog entries.
+ *
+ * Requirements: 1.1, 1.2, 1.3, 1.4
+ */
+
+import Ajv from 'ajv';
+
+const catalogSchema = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'object',
+    required: ['configs'],
+    properties: {
+        configs: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['id', 'tier', 'track', 'args', 'lifecycle', 'timeout'],
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string', pattern: '^[a-z0-9-]+$' },
+                    tier: { type: 'string', enum: ['ci', 'nightly', 'weekly'] },
+                    track: { type: 'string', enum: ['realtime', 'hyperpod', 'async', 'batch'] },
+                    args: { type: 'string' },
+                    lifecycle: {
+                        type: 'array',
+                        items: { type: 'string', pattern: '^[a-z][a-z0-9-]*$' },
+                        minItems: 1
+                    },
+                    timeout: { type: 'integer', minimum: 60 }
+                }
+            }
+        }
+    }
+};
+
+/**
+ * Validate an e2e catalog object against the schema and uniqueness constraints.
+ *
+ * @param {Object} catalog - The catalog object to validate
+ * @returns {{ valid: boolean, errors?: Array<{ path: string, message: string }> }}
+ */
+export function validateCatalog(catalog) {
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    const validate = ajv.compile(catalogSchema);
+
+    const valid = validate(catalog);
+    const errors = [];
+
+    if (!valid) {
+        for (const err of validate.errors) {
+            errors.push({
+                path: err.instancePath || '/',
+                message: err.message
+            });
+        }
+    }
+
+    // Custom check: unique IDs across all entries
+    if (catalog && catalog.configs && Array.isArray(catalog.configs)) {
+        const seen = new Map();
+        for (let i = 0; i < catalog.configs.length; i++) {
+            const entry = catalog.configs[i];
+            if (entry && typeof entry.id === 'string') {
+                if (seen.has(entry.id)) {
+                    errors.push({
+                        path: `/configs/${i}/id`,
+                        message: `duplicate id "${entry.id}" (first seen at index ${seen.get(entry.id)})`
+                    });
+                } else {
+                    seen.set(entry.id, i);
+                }
+            }
+        }
+    }
+
+    if (errors.length > 0) {
+        return { valid: false, errors };
+    }
+
+    return { valid: true };
+}
+
+/**
+ * Filter catalog configs by tier.
+ *
+ * @param {Object} catalog - The catalog object with a `configs` array
+ * @param {string} tier - The tier to filter by (e.g., 'ci', 'nightly', 'weekly')
+ * @returns {Array<Object>} Configs matching the given tier
+ */
+export function filterByTier(catalog, tier) {
+    if (!catalog || !Array.isArray(catalog.configs)) {
+        return [];
+    }
+    return catalog.configs.filter((config) => config.tier === tier);
+}