@aws/ml-container-creator 0.2.0

package/src/lib/bootstrap-config.js

@@ -0,0 +1,238 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Bootstrap Configuration
+ *
+ * Handles reading, writing, and managing the bootstrap configuration file
+ * at ~/.ml-container-creator/config.json. Supports named profiles for
+ * multiple AWS environment configurations.
+ *
+ * Config file format:
+ * {
+ *   "activeProfile": "default",
+ *   "profiles": {
+ *     "default": {
+ *       "awsProfile": "default",
+ *       "awsRegion": "us-east-1",
+ *       "accountId": "111111111111",
+ *       "roleArn": "arn:aws:iam::111111111111:role/mlcc-sagemaker-execution-role",
+ *       "ecrRepositoryName": "ml-container-creator",
+ *       "asyncS3Bucket": "...",
+ *       "batchS3Bucket": "...",
+ *       "ciInfraProvisioned": false,
+ *       "ciTableName": "mlcc-ci-table"
+ *     }
+ *   }
+ * }
+ *
+ * Optional CI fields (added by bootstrap --ci):
+ *   - ciInfraProvisioned (boolean): Whether CI harness infrastructure has been deployed. Defaults to false.
+ *   - ciTableName (string): Name of the DynamoDB CI table. Defaults to "mlcc-ci-table".
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+
+export default class BootstrapConfig {
+    /**
+     * @param {string} [configPath] - Absolute path to the config JSON file.
+     *   Defaults to ~/.ml-container-creator/config.json
+     */
+    constructor(configPath) {
+        this.configPath = configPath || join(homedir(), '.ml-container-creator', 'config.json')
+    }
+
+    /**
+     * Read the config file and return the parsed config object.
+     *
+     * @returns {{ activeProfile: string, profiles: Object }|null} The config object, or null if file doesn't exist
+     */
+    read() {
+        if (!existsSync(this.configPath)) {
+            return null
+        }
+
+        const raw = readFileSync(this.configPath, 'utf8')
+        return JSON.parse(raw)
+    }
+
+    /**
+     * Write a config object to the config file.
+     * Creates the parent directory if it doesn't exist.
+     * Uses 2-space indentation and a trailing newline.
+     *
+     * @param {Object} config - The config object to write
+     */
+    write(config) {
+        const dir = dirname(this.configPath)
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true })
+        }
+
+        writeFileSync(this.configPath, JSON.stringify(config, null, 2) + '\n')
+    }
+
+    /**
+     * Check whether the config file exists.
+     *
+     * @returns {boolean} true if the config file exists
+     */
+    exists() {
+        return existsSync(this.configPath)
+    }
+
+    /**
+     * Get the active profile name and its config.
+     *
+     * @returns {{ name: string, config: Object }|null} The active profile, or null if no active profile
+     */
+    getActiveProfile() {
+        const config = this.read()
+        if (!config || !config.activeProfile || !config.profiles) {
+            return null
+        }
+
+        const profileConfig = config.profiles[config.activeProfile]
+        if (!profileConfig) {
+            return null
+        }
+
+        return { name: config.activeProfile, config: profileConfig }
+    }
+
+    /**
+     * Get a specific profile's config by name.
+     *
+     * @param {string} name - The profile name
+     * @returns {Object|null} The profile config object, or null if not found
+     */
+    getProfile(name) {
+        const config = this.read()
+        if (!config || !config.profiles) {
+            return null
+        }
+
+        return config.profiles[name] || null
+    }
+
+    /**
+     * Get a specific profile's config with CI defaults applied.
+     * Ensures profiles created before CI integration still work by
+     * providing graceful defaults for missing CI fields.
+     *
+     * @param {string} name - The profile name
+     * @returns {Object|null} The profile config with CI defaults, or null if not found
+     */
+    getProfileWithDefaults(name) {
+        const profile = this.getProfile(name)
+        if (!profile) {
+            return null
+        }
+
+        return {
+            ciInfraProvisioned: false,
+            ciTableName: 'mlcc-ci-table',
+            ...profile
+        }
+    }
+
+    /**
+     * Get the active profile with CI defaults applied.
+     * Ensures profiles created before CI integration still work by
+     * providing graceful defaults for missing CI fields.
+     *
+     * @returns {{ name: string, config: Object }|null} The active profile with CI defaults, or null
+     */
+    getActiveProfileWithDefaults() {
+        const active = this.getActiveProfile()
+        if (!active) {
+            return null
+        }
+
+        return {
+            name: active.name,
+            config: {
+                ciInfraProvisioned: false,
+                ciTableName: 'mlcc-ci-table',
+                ...active.config
+            }
+        }
+    }
+
+    /**
+     * Create or update a profile in the config.
+     * Sets the given profile as the active profile and writes the config.
+     *
+     * @param {string} name - The profile name
+     * @param {Object} profileData - The profile configuration data
+     */
+    setProfile(name, profileData) {
+        let config = this.read()
+        if (!config) {
+            config = { activeProfile: null, profiles: {} }
+        }
+        if (!config.profiles) {
+            config.profiles = {}
+        }
+
+        config.profiles[name] = profileData
+        config.activeProfile = name
+        this.write(config)
+    }
+
+    /**
+     * Remove a profile from the config.
+     * If the removed profile was active, sets activeProfile to the first
+     * remaining profile or null if no profiles remain.
+     *
+     * @param {string} name - The profile name to remove
+     * @returns {boolean} true if the profile was removed, false if not found
+     */
+    removeProfile(name) {
+        const config = this.read()
+        if (!config || !config.profiles || !config.profiles[name]) {
+            return false
+        }
+
+        delete config.profiles[name]
+
+        if (config.activeProfile === name) {
+            const remaining = Object.keys(config.profiles)
+            config.activeProfile = remaining.length > 0 ? remaining[0] : null
+        }
+
+        this.write(config)
+        return true
+    }
+
+    /**
+     * List all profile names in the config.
+     *
+     * @returns {string[]} Array of profile name strings
+     */
+    listProfiles() {
+        const config = this.read()
+        if (!config || !config.profiles) {
+            return []
+        }
+
+        return Object.keys(config.profiles)
+    }
+
+    /**
+     * Set the active profile by name and write the config.
+     *
+     * @param {string} name - The profile name to set as active
+     */
+    setActiveProfile(name) {
+        const config = this.read()
+        if (!config) {
+            return
+        }
+
+        config.activeProfile = name
+        this.write(config)
+    }
+}

package/src/lib/ci-register-helpers.js

@@ -0,0 +1,124 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * CI Register Helpers
+ *
+ * Extracted logic from the `do/register` bash template into testable
+ * JavaScript functions. These functions mirror the bash implementations
+ * for configId hashing, CI record building, and record default handling.
+ *
+ * Used by unit and property-based tests to validate CI registration
+ * behavior without executing the bash template directly.
+ */
+
+import { createHash } from 'node:crypto'
+
+/**
+ * Compute a deterministic configId from canonical deployment fields.
+ *
+ * Mirrors the bash logic:
+ *   echo -n "${DEPLOYMENT_CONFIG}:${MODEL_NAME:-none}:${INSTANCE_TYPE}:${AWS_REGION}:${DEPLOYMENT_TARGET}" \
+ *     | sha256sum | cut -c1-16
+ *
+ * @param {string} deploymentConfig - e.g. "transformers-vllm"
+ * @param {string} modelName - e.g. "meta-llama/Llama-2-7b-chat-hf", defaults to "none"
+ * @param {string} instanceType - e.g. "ml.g5.xlarge"
+ * @param {string} region - e.g. "us-east-1"
+ * @param {string} deploymentTarget - e.g. "managed-inference"
+ * @returns {string} 16-character lowercase hex string
+ */
+export function computeConfigId(deploymentConfig, modelName, instanceType, region, deploymentTarget) {
+    const input = `${deploymentConfig}:${modelName || 'none'}:${instanceType}:${region}:${deploymentTarget}`
+    const hash = createHash('sha256').update(input).digest('hex')
+    return hash.slice(0, 16)
+}
+
+/**
+ * Build a CI DynamoDB record structure from registration inputs.
+ *
+ * Mirrors the `write_ci_record` function in the bash template.
+ *
+ * @param {string} configId - The computed configId (16-char hex)
+ * @param {string} configJson - Compact JSON string of the full configuration
+ * @param {object} promotedAttrs - Promoted top-level attributes
+ * @param {string} promotedAttrs.deploymentConfig - e.g. "transformers-vllm"
+ * @param {string} promotedAttrs.baseImage - e.g. "vllm/vllm-openai:v0.8.5"
+ * @param {string} promotedAttrs.baseImageVersion - e.g. "v0.8.5"
+ * @param {string} promotedAttrs.projectName - e.g. "test-vllm"
+ * @returns {object} DynamoDB item structure (plain JS object, not DynamoDB JSON)
+ */
+export function buildCiRecord(configId, configJson, promotedAttrs) {
+    const createdAt = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z')
+    return {
+        configId,
+        schemaVersion: 1,
+        configJson,
+        testStatus: 'untested',
+        lastTestTimestamp: '1970-01-01T00:00:00Z',
+        deploymentConfig: promotedAttrs.deploymentConfig || '',
+        baseImage: promotedAttrs.baseImage || '',
+        baseImageVersion: promotedAttrs.baseImageVersion || '',
+        projectName: promotedAttrs.projectName || '',
+        createdAt
+    }
+}
+
+/**
+ * Apply default values for missing attributes on a CI record.
+ *
+ * Ensures consumers handle records written under older schemaVersions
+ * gracefully (Requirement 2.7).
+ *
+ * @param {object} record - A CI record that may have missing attributes
+ * @returns {object} The record with defaults applied (mutates and returns same object)
+ */
+export function applyRecordDefaults(record) {
+    if (record.schemaVersion === undefined || record.schemaVersion === null) {
+        record.schemaVersion = 1
+    }
+    if (!record.testStatus) {
+        record.testStatus = 'untested'
+    }
+    if (!record.lastTestTimestamp) {
+        record.lastTestTimestamp = '1970-01-01T00:00:00Z'
+    }
+    if (!record.buildStrategy) {
+        record.buildStrategy = 'codebuild-submit'
+    }
+    if (!record.stageResults) {
+        record.stageResults = {}
+    }
+    if (!record.errorMessage && record.errorMessage !== '') {
+        record.errorMessage = ''
+    }
+    if (!record.deploymentConfig) {
+        record.deploymentConfig = ''
+    }
+    if (!record.baseImage) {
+        record.baseImage = ''
+    }
+    if (!record.baseImageVersion) {
+        record.baseImageVersion = ''
+    }
+    if (!record.projectName) {
+        record.projectName = ''
+    }
+    return record
+}
+
+/**
+ * Extract the baseImageVersion from a base image string.
+ *
+ * Mirrors the bash logic:
+ *   case "${promoted_base_image}" in *:*) promoted_base_image_version="${promoted_base_image##*:}" ;; esac
+ *
+ * @param {string} baseImage - e.g. "vllm/vllm-openai:v0.8.5"
+ * @returns {string} The version tag, or empty string if no tag present
+ */
+export function extractBaseImageVersion(baseImage) {
+    if (!baseImage || !baseImage.includes(':')) {
+        return ''
+    }
+    return baseImage.split(':').pop()
+}

package/src/lib/ci-report-helpers.js

@@ -0,0 +1,158 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * CI Report Helpers
+ *
+ * Extracted logic from the `do/ci report` bash template into testable
+ * JavaScript functions. These functions mirror the bash implementations
+ * for coverage report generation, regression detection, and coverage
+ * arithmetic.
+ *
+ * Used by unit and property-based tests to validate CI report behavior
+ * without executing the bash template directly.
+ */
+
+/**
+ * The 15 known deployment configurations across 4 architectures.
+ */
+export const KNOWN_DEPLOYMENT_CONFIGS = [
+    'transformers-vllm',
+    'transformers-sglang',
+    'transformers-lmi',
+    'transformers-djl',
+    'transformers-tensorrt-llm',
+    'http-flask',
+    'http-fastapi',
+    'http-nginx',
+    'triton-fil',
+    'triton-python',
+    'triton-onnx',
+    'triton-tensorrt',
+    'diffusors-vllm',
+    'diffusors-sglang',
+    'diffusors-comfyui'
+]
+
+/**
+ * Group an array of CI records by their deploymentConfig field.
+ *
+ * @param {object[]} records - Array of CI_Record objects
+ * @returns {Map<string, object[]>} Map from deploymentConfig to array of records
+ */
+export function groupByDeploymentConfig(records) {
+    const groups = new Map()
+    for (const record of records) {
+        const key = record.deploymentConfig || ''
+        if (!groups.has(key)) {
+            groups.set(key, [])
+        }
+        groups.get(key).push(record)
+    }
+    return groups
+}
+
+/**
+ * Detect regressions — deployment configs that transitioned from pass to fail-*.
+ *
+ * A regression is defined as a record whose testStatus starts with 'fail-'
+ * AND whose previousTestStatus was 'pass'. Records that were never 'pass'
+ * or that transition from one failure to another are NOT regressions.
+ *
+ * @param {object[]} records - Array of CI_Record objects, each with testStatus and optionally previousTestStatus
+ * @returns {object[]} Array of records that are regressions
+ */
+export function detectRegressions(records) {
+    return records.filter(record => {
+        const current = record.testStatus || ''
+        const previous = record.previousTestStatus || ''
+        return current.startsWith('fail-') && previous === 'pass'
+    })
+}
+
+/**
+ * Compute a full coverage report from CI records and the known config list.
+ *
+ * @param {object[]} records - Array of CI_Record objects from the CI_Table
+ * @param {string[]} knownConfigs - Array of known deployment configuration names
+ * @returns {object} Coverage report with summary statistics
+ * @returns {number} return.total - Total number of known configs
+ * @returns {number} return.tested - Number of configs with at least one CI_Record
+ * @returns {number} return.passing - Number of configs where latest testStatus is 'pass'
+ * @returns {number} return.failing - Number of configs where latest testStatus starts with 'fail-'
+ * @returns {number} return.untested - Number of known configs with no CI_Record
+ * @returns {number} return.coveragePercent - (tested / total) * 100, rounded to 1 decimal
+ * @returns {object[]} return.configurations - Per-config status details
+ * @returns {object[]} return.regressions - Records flagged as regressions
+ * @returns {string[]} return.untestedConfigs - Known configs with no CI_Record
+ */
+export function computeCoverageReport(records, knownConfigs) {
+    const grouped = groupByDeploymentConfig(records)
+
+    // Determine which known configs have been tested
+    const testedConfigSet = new Set()
+    const passingSet = new Set()
+    const failingSet = new Set()
+
+    const configurations = []
+
+    for (const config of knownConfigs) {
+        const configRecords = grouped.get(config) || []
+        if (configRecords.length === 0) {
+            configurations.push({
+                deploymentConfig: config,
+                status: 'untested',
+                recordCount: 0
+            })
+            continue
+        }
+
+        testedConfigSet.add(config)
+
+        // Use the most recent record (by lastTestTimestamp) to determine status
+        const sorted = [...configRecords].sort((a, b) => {
+            const tsA = a.lastTestTimestamp || '1970-01-01T00:00:00Z'
+            const tsB = b.lastTestTimestamp || '1970-01-01T00:00:00Z'
+            return tsB.localeCompare(tsA)
+        })
+        const latest = sorted[0]
+        const status = latest.testStatus || 'untested'
+
+        if (status === 'pass') {
+            passingSet.add(config)
+        } else if (status.startsWith('fail-')) {
+            failingSet.add(config)
+        }
+
+        configurations.push({
+            deploymentConfig: config,
+            status,
+            recordCount: configRecords.length,
+            latestRecord: latest
+        })
+    }
+
+    const total = knownConfigs.length
+    const tested = testedConfigSet.size
+    const untested = total - tested
+    const passing = passingSet.size
+    const failing = failingSet.size
+    const coveragePercent = total > 0
+        ? Math.round((tested / total) * 1000) / 10
+        : 0
+
+    const untestedConfigs = knownConfigs.filter(c => !testedConfigSet.has(c))
+    const regressions = detectRegressions(records)
+
+    return {
+        total,
+        tested,
+        passing,
+        failing,
+        untested,
+        coveragePercent,
+        configurations,
+        regressions,
+        untestedConfigs
+    }
+}