@aws/ml-container-creator 0.2.0

package/src/lib/huggingface-client.js

@@ -0,0 +1,172 @@
+/**
+ * HuggingFace Hub API Client
+ * 
+ * Fetches model metadata from HuggingFace Hub API with graceful error handling.
+ * Uses Node.js built-in fetch API (available in Node 18+).
+ * 
+ * Requirements: 11.1, 11.2, 11.3, 11.4, 11.8, 11.10, 11.12
+ */
+
+export default class HuggingFaceClient {
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl || 'https://huggingface.co';
+        this.timeout = options.timeout || 5000;
+        this.offline = options.offline || false;
+    }
+
+    /**
+     * Fetch model metadata from HuggingFace Hub API
+     * @param {string} modelId - Model ID (e.g., "meta-llama/Llama-2-7b-chat-hf")
+     * @returns {Promise<Object|null>} Model metadata or null on failure
+     */
+    async fetchModelMetadata(modelId) {
+        if (this.offline) {
+            return null;
+        }
+
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+            const response = await fetch(
+                `${this.baseUrl}/api/models/${modelId}`,
+                { signal: controller.signal }
+            );
+
+            clearTimeout(timeoutId);
+
+            if (!response.ok) {
+                // Handle rate limits
+                if (response.status === 429) {
+                    console.warn('HuggingFace API rate limit reached');
+                    return null;
+                }
+                // Handle not found
+                if (response.status === 404) {
+                    return null;
+                }
+                // Other errors
+                return null;
+            }
+
+            return await response.json();
+        } catch (error) {
+            // Handle timeout
+            if (error.name === 'AbortError') {
+                console.warn(`HuggingFace API timeout after ${this.timeout}ms`);
+                return null;
+            }
+            // Handle network errors
+            if (error.name === 'TypeError' && error.message.includes('fetch')) {
+                console.warn('HuggingFace API network error');
+                return null;
+            }
+            // Other errors - graceful fallback
+            return null;
+        }
+    }
+
+    /**
+     * Fetch tokenizer config for chat template detection
+     * @param {string} modelId - Model ID
+     * @returns {Promise<Object|null>} Tokenizer config or null on failure
+     */
+    async fetchTokenizerConfig(modelId) {
+        if (this.offline) {
+            return null;
+        }
+
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+            const response = await fetch(
+                `${this.baseUrl}/${modelId}/resolve/main/tokenizer_config.json`,
+                { signal: controller.signal }
+            );
+
+            clearTimeout(timeoutId);
+
+            if (!response.ok) {
+                // Handle rate limits
+                if (response.status === 429) {
+                    console.warn('HuggingFace API rate limit reached');
+                    return null;
+                }
+                // Handle not found
+                if (response.status === 404) {
+                    return null;
+                }
+                // Other errors
+                return null;
+            }
+
+            return await response.json();
+        } catch (error) {
+            // Handle timeout
+            if (error.name === 'AbortError') {
+                console.warn(`HuggingFace API timeout after ${this.timeout}ms`);
+                return null;
+            }
+            // Handle network errors
+            if (error.name === 'TypeError' && error.message.includes('fetch')) {
+                console.warn('HuggingFace API network error');
+                return null;
+            }
+            // Other errors - graceful fallback
+            return null;
+        }
+    }
+
+    /**
+     * Fetch model config for model architecture
+     * @param {string} modelId - Model ID
+     * @returns {Promise<Object|null>} Model config or null on failure
+     */
+    async fetchModelConfig(modelId) {
+        if (this.offline) {
+            return null;
+        }
+
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+            const response = await fetch(
+                `${this.baseUrl}/${modelId}/resolve/main/config.json`,
+                { signal: controller.signal }
+            );
+
+            clearTimeout(timeoutId);
+
+            if (!response.ok) {
+                // Handle rate limits
+                if (response.status === 429) {
+                    console.warn('HuggingFace API rate limit reached');
+                    return null;
+                }
+                // Handle not found
+                if (response.status === 404) {
+                    return null;
+                }
+                // Other errors
+                return null;
+            }
+
+            return await response.json();
+        } catch (error) {
+            // Handle timeout
+            if (error.name === 'AbortError') {
+                console.warn(`HuggingFace API timeout after ${this.timeout}ms`);
+                return null;
+            }
+            // Handle network errors
+            if (error.name === 'TypeError' && error.message.includes('fetch')) {
+                console.warn('HuggingFace API network error');
+                return null;
+            }
+            // Other errors - graceful fallback
+            return null;
+        }
+    }
+}

package/src/lib/key-value-parser.js

@@ -0,0 +1,37 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * KEY=VALUE Parser Utility
+ *
+ * Parses KEY=VALUE strings for --model-env and --server-env CLI flags.
+ * Splits only on the first '=' character, allowing values to contain
+ * additional '=' characters.
+ *
+ * Requirements: 3.4, 3.5, 4.4, 4.5
+ */
+
+import { ValidationError } from './config-manager.js'
+
+/**
+ * Parse a KEY=VALUE string, splitting only on the first '=' character.
+ * @param {string} input - Raw CLI value (e.g., "TENSOR_PARALLEL_SIZE=4")
+ * @returns {{ key: string, value: string }}
+ * @throws {ValidationError} if no '=' is present
+ */
+export function parseKeyValue(input) {
+    const idx = input.indexOf('=')
+
+    if (idx === -1) {
+        throw new ValidationError(
+            `Invalid format for env var: expected KEY=VALUE, got '${input}'`,
+            'env',
+            input
+        )
+    }
+
+    const key = input.substring(0, idx)
+    const value = input.substring(idx + 1)
+
+    return { key, value }
+}

package/src/lib/known-flags-validator.js

@@ -0,0 +1,200 @@
+/**
+ * Known Flags Validator Strategy
+ * 
+ * Validates environment variables against a registry of known flags for each framework.
+ * Checks variable names, types, and range constraints.
+ * 
+ * Requirements: 13.9, 13.13, 13.14, 13.15
+ */
+export default class KnownFlagsValidator {
+    /**
+     * Create a new KnownFlagsValidator.
+     * 
+     * @param {Object} frameworkFlags - Framework flags registry
+     */
+    constructor(frameworkFlags = {}) {
+        this.frameworkFlags = frameworkFlags;
+        this.name = 'known-flags-registry';
+    }
+    
+    /**
+     * Validate environment variables against known flags registry.
+     * 
+     * @param {string} framework - Framework name
+     * @param {string} version - Framework version
+     * @param {Object} envVars - Environment variables to validate
+     * @returns {Object} ValidationResult
+     * @returns {Array<Object>} ValidationResult.warnings - Warning messages
+     * @returns {Array<Object>} ValidationResult.errors - Error messages
+     */
+    async validate(framework, version, envVars) {
+        const warnings = [];
+        const errors = [];
+        
+        // Get known flags for this framework version
+        const knownFlags = this.getKnownFlags(framework, version);
+        
+        if (!knownFlags || Object.keys(knownFlags).length === 0) {
+            // No known flags data available
+            return { warnings, errors };
+        }
+        
+        // Validate each environment variable
+        for (const [key, value] of Object.entries(envVars)) {
+            const flagSpec = knownFlags[key];
+            
+            if (!flagSpec) {
+                // Unknown flag - might be valid but not in our registry
+                warnings.push({
+                    key,
+                    message: `Unknown environment variable '${key}' for ${framework} ${version}`
+                });
+                continue;
+            }
+            
+            // Check if flag is deprecated
+            if (flagSpec.deprecated) {
+                warnings.push({
+                    key,
+                    message: `Environment variable '${key}' is deprecated. ${flagSpec.deprecationMessage || ''}`
+                });
+                
+                if (flagSpec.replacement) {
+                    warnings.push({
+                        key,
+                        message: `Consider using '${flagSpec.replacement}' instead of '${key}'`
+                    });
+                }
+            }
+            
+            // Validate type
+            const typeError = this.validateType(key, value, flagSpec.type);
+            if (typeError) {
+                errors.push(typeError);
+                continue; // Skip range validation if type is wrong
+            }
+            
+            // Validate range constraints
+            const rangeError = this.validateRange(key, value, flagSpec);
+            if (rangeError) {
+                errors.push(rangeError);
+            }
+        }
+        
+        return { warnings, errors };
+    }
+    
+    /**
+     * Get known flags for a framework version.
+     * 
+     * @param {string} framework - Framework name
+     * @param {string} version - Framework version
+     * @returns {Object|null} Known flags specification
+     * @private
+     */
+    getKnownFlags(framework, version) {
+        if (!this.frameworkFlags[framework]) {
+            return null;
+        }
+        
+        // Try exact version match first
+        if (this.frameworkFlags[framework][version]) {
+            return this.frameworkFlags[framework][version];
+        }
+        
+        // Try to find closest version (simplified - just use 'default' if available)
+        if (this.frameworkFlags[framework].default) {
+            return this.frameworkFlags[framework].default;
+        }
+        
+        return null;
+    }
+    
+    /**
+     * Validate environment variable type.
+     * 
+     * @param {string} key - Variable name
+     * @param {string} value - Variable value
+     * @param {string} expectedType - Expected type (integer, float, string, boolean)
+     * @returns {Object|null} Error object or null if valid
+     * @private
+     */
+    validateType(key, value, expectedType) {
+        if (!expectedType) {
+            return null; // No type constraint
+        }
+        
+        switch (expectedType) {
+        case 'integer':
+            if (!/^-?\d+$/.test(value)) {
+                return {
+                    key,
+                    message: `Environment variable '${key}' must be an integer, got '${value}'`
+                };
+            }
+            break;
+                
+        case 'float':
+            if (!/^-?\d+(\.\d+)?$/.test(value)) {
+                return {
+                    key,
+                    message: `Environment variable '${key}' must be a float, got '${value}'`
+                };
+            }
+            break;
+                
+        case 'boolean':
+            if (!['true', 'false', '0', '1', 'yes', 'no'].includes(value.toLowerCase())) {
+                return {
+                    key,
+                    message: `Environment variable '${key}' must be a boolean (true/false, 0/1, yes/no), got '${value}'`
+                };
+            }
+            break;
+                
+        case 'string':
+            // String is always valid
+            break;
+                
+        default:
+            // Unknown type - skip validation
+            break;
+        }
+        
+        return null;
+    }
+    
+    /**
+     * Validate environment variable range constraints.
+     * 
+     * @param {string} key - Variable name
+     * @param {string} value - Variable value
+     * @param {Object} flagSpec - Flag specification with min/max constraints
+     * @returns {Object|null} Error object or null if valid
+     * @private
+     */
+    validateRange(key, value, flagSpec) {
+        // Only validate range for numeric types
+        if (flagSpec.type !== 'integer' && flagSpec.type !== 'float') {
+            return null;
+        }
+        
+        const numValue = parseFloat(value);
+        
+        if (flagSpec.min !== undefined && numValue < flagSpec.min) {
+            return {
+                key,
+                message: `Environment variable '${key}' must be >= ${flagSpec.min}, got ${value}`
+            };
+        }
+        
+        if (flagSpec.max !== undefined && numValue > flagSpec.max) {
+            return {
+                key,
+                message: `Environment variable '${key}' must be <= ${flagSpec.max}, got ${value}`
+            };
+        }
+        
+        return null;
+    }
+}

package/src/lib/manifest-cli.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Manifest CLI Wrapper
+ *
+ * A standalone Node.js script invoked by the `do/manifest` shell helper.
+ * Reads the bootstrap config to resolve the active profile, instantiates
+ * AssetManager, and dispatches commands.
+ *
+ * Usage:
+ *   node do/lib/manifest-cli.js add --type <type> --id <id> --project <project> [--meta <json>]
+ *   node do/lib/manifest-cli.js delete --id <id>
+ *   node do/lib/manifest-cli.js list [--project <project>] [--status <status>] [--type <type>]
+ *
+ * Validates: Requirements 9.1–9.7
+ */
+
+import AssetManager, { VALID_RESOURCE_TYPES, VALID_STATUSES } from './asset-manager.js'
+import BootstrapConfig from './bootstrap-config.js'
+
+/**
+ * Parse command-line arguments into a map of flag → value pairs.
+ * Supports --flag value syntax. Positional args are ignored.
+ *
+ * @param {string[]} argv - The raw process.argv array
+ * @returns {{ subcommand: string|null, flags: Object }}
+ */
+function parseArgs(argv) {
+    // argv[0] = node, argv[1] = script path, argv[2] = subcommand, argv[3..] = flags
+    const args = argv.slice(2)
+    const subcommand = args.length > 0 && !args[0].startsWith('--') ? args[0] : null
+    const flags = {}
+
+    for (let i = subcommand ? 1 : 0; i < args.length; i++) {
+        if (args[i].startsWith('--') && i + 1 < args.length) {
+            const key = args[i].slice(2)
+            flags[key] = args[i + 1]
+            i++
+        }
+    }
+
+    return { subcommand, flags }
+}
+
+/**
+ * Print usage information and exit.
+ */
+function printUsage() {
+    console.log('Usage:')
+    console.log('  manifest add --type <resourceType> --id <resourceId> --project <projectName> [--meta <json>]')
+    console.log('  manifest delete --id <resourceId>')
+    console.log('  manifest list [--project <project>] [--status <status>] [--type <type>]')
+    console.log('  manifest prune')
+    console.log('')
+    console.log('Valid resource types:')
+    console.log(`  ${VALID_RESOURCE_TYPES.join(', ')}`)
+    console.log('')
+    console.log('Valid statuses:')
+    console.log(`  ${VALID_STATUSES.join(', ')}`)
+}
+
+/**
+ * Format resources as a table for console output.
+ *
+ * @param {Array<Object>} resources - Array of Asset_Records
+ */
+function printResourceTable(resources) {
+    if (resources.length === 0) {
+        console.log('No resources found.')
+        return
+    }
+
+    // Header
+    const header = ['Type', 'Resource ID', 'Project', 'Status', 'Created At']
+    const widths = header.map(h => h.length)
+
+    // Calculate column widths
+    for (const r of resources) {
+        widths[0] = Math.max(widths[0], (r.resourceType || '').length)
+        widths[1] = Math.max(widths[1], Math.min((r.resourceId || '').length, 60))
+        widths[2] = Math.max(widths[2], (r.project || '').length)
+        widths[3] = Math.max(widths[3], (r.status || '').length)
+        widths[4] = Math.max(widths[4], (r.createdAt || '').length)
+    }
+
+    const pad = (str, width) => String(str).padEnd(width)
+    const separator = widths.map(w => '-'.repeat(w)).join('  ')
+
+    console.log(header.map((h, i) => pad(h, widths[i])).join('  '))
+    console.log(separator)
+
+    for (const r of resources) {
+        const id = (r.resourceId || '').length > 60
+            ? r.resourceId.slice(0, 57) + '...'
+            : r.resourceId || ''
+        console.log([
+            pad(r.resourceType || '', widths[0]),
+            pad(id, widths[1]),
+            pad(r.project || '', widths[2]),
+            pad(r.status || '', widths[3]),
+            pad(r.createdAt || '', widths[4])
+        ].join('  '))
+    }
+}
+
+/**
+ * Handle the `add` subcommand.
+ *
+ * @param {Object} flags - Parsed flags
+ * @param {AssetManager} assetManager - The AssetManager instance
+ */
+function handleAdd(flags, assetManager) {
+    const { type, id, project, meta } = flags
+
+    if (!type || !id || !project) {
+        console.error('Error: --type, --id, and --project are required for the add command.')
+        console.log('')
+        printUsage()
+        process.exitCode = 1
+        return
+    }
+
+    if (!VALID_RESOURCE_TYPES.includes(type)) {
+        console.error(`Error: Invalid resource type "${type}".`)
+        console.error(`Valid types: ${VALID_RESOURCE_TYPES.join(', ')}`)
+        process.exitCode = 1
+        return
+    }
+
+    let metadata = {}
+    if (meta) {
+        try {
+            metadata = JSON.parse(meta)
+        } catch (err) {
+            console.error(`Error: Invalid JSON for --meta: ${err.message}`)
+            process.exitCode = 1
+            return
+        }
+    }
+
+    const now = new Date().toISOString()
+    const record = {
+        resourceId: id,
+        resourceType: type,
+        createdAt: now,
+        lastUpdatedAt: now,
+        project,
+        status: 'active',
+        metadata
+    }
+
+    assetManager.addResource(record)
+    console.log(`Added ${type}: ${id}`)
+}
+
+/**
+ * Handle the `delete` subcommand.
+ *
+ * @param {Object} flags - Parsed flags
+ * @param {AssetManager} assetManager - The AssetManager instance
+ */
+function handleDelete(flags, assetManager) {
+    const { id } = flags
+
+    if (!id) {
+        console.error('Error: --id is required for the delete command.')
+        console.log('')
+        printUsage()
+        process.exitCode = 1
+        return
+    }
+
+    const updated = assetManager.updateStatus(id, 'deleted')
+    if (updated) {
+        console.log(`Marked as deleted: ${id}`)
+    } else {
+        console.log(`Resource not found in manifest: ${id}`)
+    }
+}
+
+/**
+ * Handle the `list` subcommand.
+ *
+ * @param {Object} flags - Parsed flags
+ * @param {AssetManager} assetManager - The AssetManager instance
+ */
+function handleList(flags, assetManager) {
+    const filters = {}
+    if (flags.project) filters.project = flags.project
+    if (flags.status) filters.status = flags.status
+    if (flags.type) filters.resourceType = flags.type
+
+    const resources = assetManager.listResources(filters)
+    printResourceTable(resources)
+}
+
+/**
+ * Handle the `prune` subcommand — remove deleted and unknown records.
+ *
+ * @param {AssetManager} assetManager - The AssetManager instance
+ */
+function handlePrune(assetManager) {
+    const all = assetManager.listResources()
+    const stale = all.filter(r => r.status === 'deleted' || r.status === 'unknown')
+
+    if (stale.length === 0) {
+        console.log('Nothing to prune — no deleted or unknown records found.')
+        return
+    }
+
+    for (const resource of stale) {
+        assetManager.removeResource(resource.resourceId)
+        console.log(`  🗑️  [${resource.status}] ${resource.resourceType}: ${resource.resourceId}`)
+    }
+
+    const remaining = assetManager.listResources()
+    console.log(`\nPruned ${stale.length} record${stale.length === 1 ? '' : 's'}. ${remaining.length} remaining.`)
+}
+
+/**
+ * Main entry point. Resolves the active bootstrap profile,
+ * instantiates AssetManager, and dispatches the subcommand.
+ *
+ * @param {string[]} argv - The raw process.argv array
+ */
+export function main(argv) {
+    const { subcommand, flags } = parseArgs(argv)
+
+    if (!subcommand) {
+        printUsage()
+        process.exitCode = 1
+        return
+    }
+
+    // Resolve active bootstrap profile
+    const bootstrapConfig = new BootstrapConfig()
+    const activeProfile = bootstrapConfig.getActiveProfile()
+
+    if (!activeProfile) {
+        console.warn('Warning: No active bootstrap profile configured. Skipping manifest operation.')
+        console.warn('Run "ml-container-creator bootstrap" to configure a profile.')
+        return
+    }
+
+    const assetManager = new AssetManager(activeProfile.name)
+
+    switch (subcommand) {
+        case 'add':
+            handleAdd(flags, assetManager)
+            break
+        case 'delete':
+            handleDelete(flags, assetManager)
+            break
+        case 'list':
+            handleList(flags, assetManager)
+            break
+        case 'prune':
+            handlePrune(assetManager)
+            break
+        default:
+            console.error(`Unknown subcommand: ${subcommand}`)
+            console.log('')
+            printUsage()
+            process.exitCode = 1
+            break
+    }
+}
+
+// Run when executed directly
+const isDirectExecution = process.argv[1] && (
+    process.argv[1].endsWith('manifest-cli.js') ||
+    process.argv[1].endsWith('do/lib/manifest-cli.js')
+)
+
+if (isDirectExecution) {
+    main(process.argv)
+}