@aws/ml-container-creator 0.2.0

package/src/copy-tpl.js

@@ -0,0 +1,77 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import ejs from 'ejs'
+import { globSync } from 'tinyglobby'
+import fs from 'fs'
+import path from 'path'
+
+/**
+ * Binary file extensions that should be copied without EJS rendering.
+ */
+const BINARY_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.ico', '.bmp', '.tiff', '.webp',
+    '.woff', '.woff2', '.ttf', '.eot', '.otf',
+    '.zip', '.tar', '.gz', '.bz2', '.7z',
+    '.pdf',
+    '.exe', '.dll', '.so', '.dylib',
+    '.pyc', '.pyo', '.class', '.jar', '.war', '.ear'
+])
+
+/**
+ * Determines whether a file is binary based on its extension.
+ *
+ * @param {string} filePath - Path to the file
+ * @returns {boolean} True if the file has a known binary extension
+ */
+function isBinaryFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase()
+    return BINARY_EXTENSIONS.has(ext)
+}
+
+/**
+ * Copies template files from a source directory to a destination directory,
+ * rendering EJS templates with the provided variables.
+ *
+ * Binary files (identified by extension) are copied without EJS rendering.
+ * Directories are created as needed.
+ *
+ * @param {string} templateDir - Source directory containing template files
+ * @param {string} destDir - Destination directory for rendered output
+ * @param {object} vars - Variables to pass to EJS templates
+ * @param {string[]} [ignorePatterns=[]] - Glob patterns for files to exclude
+ */
+export function copyTpl(templateDir, destDir, vars, ignorePatterns = []) {
+    const files = globSync('**/*', {
+        cwd: templateDir,
+        ignore: ignorePatterns,
+        dot: true,
+        onlyFiles: true
+    })
+
+    for (const file of files) {
+        const src = path.join(templateDir, file)
+        const dest = path.join(destDir, file)
+
+        fs.mkdirSync(path.dirname(dest), { recursive: true })
+
+        if (isBinaryFile(file)) {
+            fs.copyFileSync(src, dest)
+            continue
+        }
+
+        const content = fs.readFileSync(src, 'utf8')
+
+        let rendered
+        try {
+            rendered = ejs.render(content, vars, { filename: src })
+        } catch (err) {
+            const line = err.line ? ` (line ${err.line})` : ''
+            throw new Error(
+                `EJS rendering failed for "${file}"${line}: ${err.message}`
+            )
+        }
+
+        fs.writeFileSync(dest, rendered)
+    }
+}

package/src/lib/accelerator-validator.js

@@ -0,0 +1,39 @@
+/**
+ * Base class for accelerator-specific validators.
+ * Implements the plugin architecture for extensible accelerator validation.
+ * 
+ * Requirements: 4.10, 4.21
+ */
+export default class AcceleratorValidator {
+    /**
+     * Validate framework config against instance config.
+     * 
+     * @param {Object} frameworkConfig - Framework accelerator requirements
+     * @param {Object} frameworkConfig.accelerator - Accelerator configuration
+     * @param {string} frameworkConfig.accelerator.type - Accelerator type (cuda, neuron, cpu, rocm)
+     * @param {string} frameworkConfig.accelerator.version - Required accelerator version
+     * @param {Object} instanceConfig - Instance accelerator capabilities
+     * @param {Object} instanceConfig.accelerator - Accelerator configuration
+     * @param {string} instanceConfig.accelerator.type - Accelerator type
+     * @param {Array<string>} instanceConfig.accelerator.versions - Supported versions
+     * @returns {Object} ValidationResult
+     * @returns {boolean} ValidationResult.compatible - Whether configuration is compatible
+     * @returns {string} [ValidationResult.error] - Error message if incompatible
+     * @returns {string} [ValidationResult.warning] - Warning message if issues detected
+     * @returns {string} [ValidationResult.info] - Informational message
+     */
+    validate(_frameworkConfig, _instanceConfig) {
+        throw new Error('AcceleratorValidator.validate() must be implemented by subclass');
+    }
+    
+    /**
+     * Get user-friendly error message for version mismatch.
+     * 
+     * @param {string} required - Required version
+     * @param {Array<string>|string} provided - Provided version(s)
+     * @returns {string} User-friendly error message
+     */
+    getVersionMismatchMessage(_required, _provided) {
+        throw new Error('AcceleratorValidator.getVersionMismatchMessage() must be implemented by subclass');
+    }
+}

package/src/lib/asset-manager.js

@@ -0,0 +1,385 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Asset Manager
+ *
+ * Core data-access module for the deployment registry asset manifest.
+ * Handles reading, writing, querying, and validating the per-profile
+ * asset manifest stored at ~/.ml-container-creator/manifests/{profileName}.json.
+ *
+ * Manifest file format:
+ * {
+ *   "schemaVersion": "2026-05-04",
+ *   "resources": [
+ *     {
+ *       "resourceId": "arn:aws:sagemaker:us-east-1:111111111111:endpoint/my-endpoint",
+ *       "resourceType": "sagemaker-endpoint",
+ *       "createdAt": "2026-05-04T10:30:00Z",
+ *       "lastUpdatedAt": "2026-05-04T10:30:00Z",
+ *       "project": "my-llm-project",
+ *       "status": "active",
+ *       "metadata": {
+ *         "endpointName": "my-endpoint",
+ *         "instanceType": "ml.g5.xlarge",
+ *         "region": "us-east-1"
+ *       }
+ *     }
+ *   ]
+ * }
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { homedir } from 'node:os'
+
+const SCHEMA_VERSION = '2026-05-04'
+
+const VALID_RESOURCE_TYPES = [
+    'sagemaker-endpoint',
+    'sagemaker-endpoint-config',
+    'sagemaker-model',
+    'sagemaker-inference-component',
+    'sagemaker-transform-job',
+    'ecr-image',
+    'codebuild-project',
+    'iam-role',
+    's3-object',
+    'sns-topic',
+    'k8s-deployment',
+    'k8s-service'
+]
+
+const VALID_STATUSES = ['active', 'deleted', 'unknown']
+
+export { SCHEMA_VERSION, VALID_RESOURCE_TYPES, VALID_STATUSES }
+
+export default class AssetManager {
+    /**
+     * @param {string} profileName - The bootstrap profile name
+     * @param {Object} [options] - Optional configuration
+     * @param {string} [options.configDir] - Override the default config directory
+     *   Defaults to ~/.ml-container-creator
+     */
+    constructor(profileName, options = {}) {
+        this.profileName = profileName
+        this.configDir = options.configDir || join(homedir(), '.ml-container-creator')
+    }
+
+    /**
+     * Derive the manifest file path from the profile name.
+     *
+     * @returns {string} Absolute path to the manifest JSON file
+     */
+    get manifestPath() {
+        return join(this.configDir, 'manifests', `${this.profileName}.json`)
+    }
+
+    /**
+     * Read the manifest file and return the parsed manifest object.
+     *
+     * Handles:
+     * - Missing file → return { schemaVersion, resources: [] }
+     * - Invalid JSON → throw descriptive error
+     * - Missing/unrecognized schemaVersion → log warning, attempt best-effort read
+     *
+     * @returns {{ schemaVersion: string, resources: Array<Object> }}
+     */
+    _readManifest() {
+        if (!existsSync(this.manifestPath)) {
+            return { schemaVersion: SCHEMA_VERSION, resources: [] }
+        }
+
+        const raw = readFileSync(this.manifestPath, 'utf8')
+
+        let data
+        try {
+            data = JSON.parse(raw)
+        } catch (err) {
+            throw new Error(
+                `Invalid JSON in manifest file ${this.manifestPath}: ${err.message}`
+            )
+        }
+
+        if (!data.schemaVersion) {
+            console.warn(
+                `Warning: Manifest file ${this.manifestPath} has no schemaVersion. Attempting best-effort read.`
+            )
+        } else if (data.schemaVersion !== SCHEMA_VERSION) {
+            console.warn(
+                `Warning: Manifest file ${this.manifestPath} has unrecognized schemaVersion "${data.schemaVersion}". Attempting best-effort read.`
+            )
+        }
+
+        return {
+            schemaVersion: data.schemaVersion || SCHEMA_VERSION,
+            resources: Array.isArray(data.resources) ? data.resources : []
+        }
+    }
+
+    /**
+     * Write a manifest object to the manifest file.
+     * Creates parent directories if they don't exist.
+     * Uses 2-space indentation and a trailing newline.
+     *
+     * @param {{ schemaVersion: string, resources: Array<Object> }} manifest
+     */
+    _writeManifest(manifest) {
+        const dir = dirname(this.manifestPath)
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true })
+        }
+
+        writeFileSync(
+            this.manifestPath,
+            `${JSON.stringify(manifest, null, 2)}\n`
+        )
+    }
+
+    /**
+     * Validate an Asset_Record against the required schema.
+     *
+     * Checks:
+     * - Required fields: resourceId, resourceType, createdAt, lastUpdatedAt, project, status, metadata
+     * - resourceType is one of VALID_RESOURCE_TYPES
+     * - status is one of VALID_STATUSES
+     * - createdAt and lastUpdatedAt are valid ISO 8601 strings
+     * - metadata is a non-null object
+     *
+     * @param {Object} record - The record to validate
+     * @returns {{ valid: boolean, errors: string[] }}
+     */
+    _validateRecord(record) {
+        const errors = []
+
+        const requiredFields = [
+            'resourceId',
+            'resourceType',
+            'createdAt',
+            'lastUpdatedAt',
+            'project',
+            'status',
+            'metadata'
+        ]
+
+        for (const field of requiredFields) {
+            if (record[field] === undefined || record[field] === null) {
+                errors.push(`Missing required field: ${field}`)
+            }
+        }
+
+        if (record.resourceType !== undefined && record.resourceType !== null) {
+            if (!VALID_RESOURCE_TYPES.includes(record.resourceType)) {
+                errors.push(
+                    `Invalid resourceType: "${record.resourceType}". Must be one of: ${VALID_RESOURCE_TYPES.join(', ')}`
+                )
+            }
+        }
+
+        if (record.status !== undefined && record.status !== null) {
+            if (!VALID_STATUSES.includes(record.status)) {
+                errors.push(
+                    `Invalid status: "${record.status}". Must be one of: ${VALID_STATUSES.join(', ')}`
+                )
+            }
+        }
+
+        if (record.createdAt !== undefined && record.createdAt !== null) {
+            if (!_isValidISO8601(record.createdAt)) {
+                errors.push(
+                    `Invalid createdAt: "${record.createdAt}". Must be a valid ISO 8601 timestamp.`
+                )
+            }
+        }
+
+        if (record.lastUpdatedAt !== undefined && record.lastUpdatedAt !== null) {
+            if (!_isValidISO8601(record.lastUpdatedAt)) {
+                errors.push(
+                    `Invalid lastUpdatedAt: "${record.lastUpdatedAt}". Must be a valid ISO 8601 timestamp.`
+                )
+            }
+        }
+
+        if (record.metadata !== undefined && record.metadata !== null) {
+            if (typeof record.metadata !== 'object' || Array.isArray(record.metadata)) {
+                errors.push('Invalid metadata: must be a non-null object.')
+            }
+        }
+
+        return { valid: errors.length === 0, errors }
+    }
+
+    /**
+     * Add or update a resource record in the manifest (upsert semantics).
+     *
+     * Validates the record, reads the manifest, and either updates an
+     * existing record (matching resourceId) or appends a new one.
+     *
+     * @param {Object} record - The Asset_Record to add or update
+     * @throws {Error} If the record fails validation
+     */
+    addResource(record) {
+        const { valid, errors } = this._validateRecord(record)
+        if (!valid) {
+            throw new Error(`Invalid asset record: ${errors.join('; ')}`)
+        }
+
+        const manifest = this._readManifest()
+        const existingIndex = manifest.resources.findIndex(
+            r => r.resourceId === record.resourceId
+        )
+
+        if (existingIndex !== -1) {
+            manifest.resources[existingIndex].lastUpdatedAt = record.lastUpdatedAt
+            manifest.resources[existingIndex].status = record.status
+        } else {
+            manifest.resources.push(record)
+        }
+
+        this._writeManifest(manifest)
+    }
+
+    /**
+     * Update the status of a resource by its resourceId.
+     *
+     * @param {string} resourceId - The resource identifier to find
+     * @param {string} newStatus - The new status value
+     * @returns {boolean} true if the resource was found and updated, false otherwise
+     */
+    updateStatus(resourceId, newStatus) {
+        const manifest = this._readManifest()
+        const resource = manifest.resources.find(r => r.resourceId === resourceId)
+
+        if (!resource) {
+            return false
+        }
+
+        resource.status = newStatus
+        resource.lastUpdatedAt = new Date().toISOString()
+        this._writeManifest(manifest)
+        return true
+    }
+
+    /**
+     * Get a single resource record by its resourceId.
+     *
+     * @param {string} resourceId - The resource identifier to find
+     * @returns {Object|null} The matching Asset_Record, or null if not found
+     */
+    getResource(resourceId) {
+        const manifest = this._readManifest()
+        return manifest.resources.find(r => r.resourceId === resourceId) || null
+    }
+
+    /**
+     * Remove a resource record from the manifest by its resourceId.
+     *
+     * @param {string} resourceId - The resource identifier to remove
+     * @returns {boolean} true if the resource was found and removed, false otherwise
+     */
+    removeResource(resourceId) {
+        const manifest = this._readManifest()
+        const originalLength = manifest.resources.length
+        manifest.resources = manifest.resources.filter(
+            r => r.resourceId !== resourceId
+        )
+
+        if (manifest.resources.length === originalLength) {
+            return false
+        }
+
+        this._writeManifest(manifest)
+        return true
+    }
+
+    /**
+     * List resources matching optional filters (AND logic).
+     *
+     * Supported filter keys: resourceType, project, status.
+     * With no filters, returns all resources.
+     *
+     * @param {Object} [filters] - Optional filter criteria
+     * @returns {Array<Object>} Matching Asset_Records
+     */
+    listResources(filters = {}) {
+        const manifest = this._readManifest()
+
+        if (!filters || Object.keys(filters).length === 0) {
+            return manifest.resources
+        }
+
+        return manifest.resources.filter(resource => {
+            if (filters.resourceType && resource.resourceType !== filters.resourceType) {
+                return false
+            }
+            if (filters.project && resource.project !== filters.project) {
+                return false
+            }
+            if (filters.status && resource.status !== filters.status) {
+                return false
+            }
+            return true
+        })
+    }
+
+    /**
+     * Group all resources by their project name.
+     *
+     * @returns {Map<string, Array<Object>>} Map of project name → Asset_Record array
+     */
+    getResourcesByProject() {
+        const manifest = this._readManifest()
+        const grouped = new Map()
+
+        for (const resource of manifest.resources) {
+            const project = resource.project
+            if (!grouped.has(project)) {
+                grouped.set(project, [])
+            }
+            grouped.get(project).push(resource)
+        }
+
+        return grouped
+    }
+
+    /**
+     * Count resources by status.
+     *
+     * @returns {{ active: number, deleted: number, unknown: number }}
+     */
+    getStatusCounts() {
+        const manifest = this._readManifest()
+        const counts = { active: 0, deleted: 0, unknown: 0 }
+
+        for (const resource of manifest.resources) {
+            if (resource.status in counts) {
+                counts[resource.status]++
+            }
+        }
+
+        return counts
+    }
+}
+
+/**
+ * Check whether a string is a valid ISO 8601 timestamp.
+ *
+ * Accepts any string that the Date constructor can parse into a valid date
+ * and that matches the ISO 8601 pattern (must contain date separators and
+ * a time designator). This allows both `2026-05-04T10:30:00Z` and
+ * `2026-05-04T10:30:00.000Z` forms.
+ *
+ * @param {string} str - The string to check
+ * @returns {boolean} true if the string is a valid ISO 8601 timestamp
+ */
+function _isValidISO8601(str) {
+    if (typeof str !== 'string' || str.length === 0) {
+        return false
+    }
+    const date = new Date(str)
+    if (isNaN(date.getTime())) {
+        return false
+    }
+    // Ensure the string looks like an ISO 8601 timestamp (not just any parseable date string)
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(str)
+}

package/src/lib/aws-profile-parser.js

@@ -0,0 +1,181 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * AWS Profile Parser
+ *
+ * Parses INI-format AWS configuration files (~/.aws/config and
+ * ~/.aws/credentials) to extract available profile names. Used by
+ * the bootstrap command to present a selectable list of AWS profiles.
+ *
+ * Parsing rules:
+ * - ~/.aws/config uses [profile name] sections (except [default])
+ * - ~/.aws/credentials uses [name] sections directly
+ * - Profiles from both files are merged and deduplicated
+ * - 'default' is always sorted first if present
+ */
+
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+export default class AwsProfileParser {
+    /**
+     * @param {Object} [options] - Optional overrides for testing
+     * @param {string} [options.configPath] - Override path to ~/.aws/config
+     * @param {string} [options.credentialsPath] - Override path to ~/.aws/credentials
+     */
+    constructor(options = {}) {
+        this._configPath = options.configPath || null
+        this._credentialsPath = options.credentialsPath || null
+    }
+
+    /**
+     * Get all AWS profile names from config and credentials files.
+     * Returns a deduplicated array with 'default' sorted first if present.
+     *
+     * @returns {string[]} Profile names, with 'default' first if it exists
+     */
+    getProfiles() {
+        const configProfiles = this._getProfilesFromConfig()
+        const credentialsProfiles = this._getProfilesFromCredentials()
+
+        const allNames = new Set([...configProfiles, ...credentialsProfiles])
+
+        const sorted = [...allNames].sort((a, b) => {
+            if (a === 'default') return -1
+            if (b === 'default') return 1
+            return a.localeCompare(b)
+        })
+
+        return sorted
+    }
+
+    /**
+     * Parse an INI-format file into a Map of section names to key-value objects.
+     *
+     * @param {string} filePath - Absolute path to the INI file
+     * @returns {Map<string, Object>} Map of section names to parsed key-value pairs
+     */
+    _parseIniFile(filePath) {
+        const sections = new Map()
+
+        if (!existsSync(filePath)) {
+            return sections
+        }
+
+        let content
+        try {
+            content = readFileSync(filePath, 'utf8')
+        } catch {
+            return sections
+        }
+
+        let currentSection = null
+        const lines = content.split(/\r?\n/)
+
+        for (const rawLine of lines) {
+            const line = rawLine.trim()
+
+            // Skip empty lines and comments
+            if (!line || line.startsWith('#') || line.startsWith(';')) {
+                continue
+            }
+
+            // Check for section header
+            const sectionMatch = line.match(/^\[([^\]]+)\]$/)
+            if (sectionMatch) {
+                currentSection = sectionMatch[1].trim()
+                if (!sections.has(currentSection)) {
+                    sections.set(currentSection, {})
+                }
+                continue
+            }
+
+            // Parse key = value pairs
+            if (currentSection) {
+                const kvMatch = line.match(/^([^=]+?)=(.*)$/)
+                if (kvMatch) {
+                    const key = kvMatch[1].trim()
+                    const value = kvMatch[2].trim()
+                    sections.get(currentSection)[key] = value
+                }
+            }
+        }
+
+        return sections
+    }
+
+    /**
+     * Extract profile names from a parsed INI Map.
+     * Handles both config-style ([profile X]) and credentials-style ([X]) sections.
+     *
+     * @param {Map<string, Object>} parsed - Parsed INI sections
+     * @param {boolean} [isConfig=false] - Whether this is a config file (uses [profile X] format)
+     * @returns {string[]} Array of profile names
+     */
+    _extractProfileNames(parsed, isConfig = false) {
+        const names = []
+
+        for (const sectionName of parsed.keys()) {
+            if (isConfig) {
+                // ~/.aws/config uses [profile name] except for [default]
+                if (sectionName === 'default') {
+                    names.push('default')
+                } else if (sectionName.startsWith('profile ')) {
+                    const name = sectionName.slice('profile '.length).trim()
+                    if (name) {
+                        names.push(name)
+                    }
+                }
+            } else {
+                // ~/.aws/credentials uses [name] directly
+                names.push(sectionName)
+            }
+        }
+
+        return names
+    }
+
+    /**
+     * Get the path to the AWS config file.
+     *
+     * @returns {string} Absolute path to ~/.aws/config
+     */
+    _getConfigPath() {
+        return this._configPath || join(homedir(), '.aws', 'config')
+    }
+
+    /**
+     * Get the path to the AWS credentials file.
+     *
+     * @returns {string} Absolute path to ~/.aws/credentials
+     */
+    _getCredentialsPath() {
+        return this._credentialsPath || join(homedir(), '.aws', 'credentials')
+    }
+
+    /**
+     * Get profile names from the AWS config file.
+     *
+     * @returns {string[]} Profile names from ~/.aws/config
+     * @private
+     */
+    _getProfilesFromConfig() {
+        const configPath = this._getConfigPath()
+        const parsed = this._parseIniFile(configPath)
+        return this._extractProfileNames(parsed, true)
+    }
+
+    /**
+     * Get profile names from the AWS credentials file.
+     *
+     * @returns {string[]} Profile names from ~/.aws/credentials
+     * @private
+     */
+    _getProfilesFromCredentials() {
+        const credentialsPath = this._getCredentialsPath()
+        const parsed = this._parseIniFile(credentialsPath)
+        return this._extractProfileNames(parsed, false)
+    }
+}