@aws/ml-container-creator 0.12.1 → 0.13.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/ml-container-creator",
-  "version": "0.12.1",
+  "version": "0.13.3",
   "description": "Build and deploy custom ML containers on AWS SageMaker with minimal configuration.",
   "main": "src/index.js",
   "bin": {
@@ -102,7 +102,7 @@
     "validate:doc-commands": "node scripts/validate-docs-commands.js",
     "sbom": "sbom --format spdx --output sbom.json",
     "prepublishOnly": "npm run lint && npm run test:all",
-    "prepare": "git config core.hooksPath .githooks || true"
+    "prepare": "husky || true"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.2",
@@ -120,11 +120,19 @@
     "@aws-sdk/client-service-quotas": "^3.700.0",
     "@microsoft/eslint-formatter-sarif": "^3.1.0",
     "eslint": "^8.57.0",
+    "eslint-plugin-property-test-rules": "file:eslint-rules",
     "fast-check": "^4.5.2",
+    "husky": "^9.1.7",
     "license-report": "^6.8.0",
+    "lint-staged": "^17.0.7",
     "mocha": "^10.2.0",
     "npm-force-resolutions": "^0.0.10",
     "nyc": "^15.1.0",
     "sbom": "^0.0.0"
+  },
+  "lint-staged": {
+    "*.js": [
+      "eslint --fix --quiet --max-warnings 0"
+    ]
   }
 }

package/src/app.js

@@ -562,6 +562,20 @@ export async function writeProject(templateDir, destDir, answers, registryConfig
             fs.writeFileSync(gitignorePath, gitignoreContent);
         }
     }
+
+    // Add .mlcc/ to .gitignore (staged-assets tracking — account-specific URIs)
+    {
+        const gitignorePath = path.join(destDir, '.gitignore');
+        const mlccIgnore = '# Staged assets tracking (account-specific, generated by do/stage)\n.mlcc/\n';
+        if (fs.existsSync(gitignorePath)) {
+            const existing = fs.readFileSync(gitignorePath, 'utf8');
+            if (!existing.includes('.mlcc/')) {
+                fs.appendFileSync(gitignorePath, `\n${mlccIgnore}`);
+            }
+        } else {
+            fs.writeFileSync(gitignorePath, mlccIgnore);
+        }
+    }
 }
 
 /**

package/src/lib/prove-pipeline-executor.js

@@ -0,0 +1,294 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Prove Pipeline Executor
+ *
+ * Executes lifecycle stages for validation targets in the `mcc prove` workflow.
+ * Handles stage-specific logic including idempotency checks, status tracking,
+ * and fail-fast behavior.
+ *
+ * Feature: s3-model-loading
+ * Requirements: 5.1, 5.2, 5.3, 5.4, 5.5
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const execFileAsync = promisify(execFile);
+
+// ── Valid Lifecycle Stages ────────────────────────────────────────────────────
+
+/**
+ * All recognized lifecycle stages for the prove pipeline.
+ * The "stage" step pre-stages model weights from HuggingFace to S3.
+ */
+export const VALID_LIFECYCLE_STAGES = [
+    'generate',
+    'stage',
+    'build',
+    'push',
+    'deploy',
+    'test',
+    'tune',
+    'adapter',
+    'test-adapter',
+    'benchmark',
+    'register',
+    'clean'
+];
+
+/**
+ * Possible staging states for status output.
+ */
+export const STAGING_STATES = {
+    STAGED: 'staged',
+    NOT_STAGED: 'not-staged',
+    STAGE_FAILED: 'stage-failed'
+};
+
+// ── Stage Lifecycle Step ─────────────────────────────────────────────────────
+
+/**
+ * Check if a model has already been staged by looking for `.mlcc/staged-assets.json`.
+ *
+ * @param {string} projectDir - Path to the generated project directory
+ * @returns {boolean} True if the model has already been staged
+ */
+export function isAlreadyStaged(projectDir) {
+    const stagedAssetsPath = path.join(projectDir, '.mlcc', 'staged-assets.json');
+    if (!existsSync(stagedAssetsPath)) {
+        return false;
+    }
+
+    try {
+        const content = readFileSync(stagedAssetsPath, 'utf8');
+        const data = JSON.parse(content);
+        // Check that there's a valid staged URI
+        return !!(data?.models?.default?.staged_uri);
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Get the current staging state for a project.
+ *
+ * @param {string} projectDir - Path to the generated project directory
+ * @param {object} [stepResults] - Previous step results (to check for stage-failed)
+ * @returns {string} One of: 'staged', 'not-staged', 'stage-failed'
+ */
+export function getStagingState(projectDir, stepResults = null) {
+    // Check if stage previously failed
+    if (stepResults?.stage?.status === 'fail') {
+        return STAGING_STATES.STAGE_FAILED;
+    }
+
+    if (isAlreadyStaged(projectDir)) {
+        return STAGING_STATES.STAGED;
+    }
+
+    return STAGING_STATES.NOT_STAGED;
+}
+
+/**
+ * Execute the stage lifecycle step with idempotency support.
+ *
+ * If the model is already staged (`.mlcc/staged-assets.json` exists with a valid URI),
+ * the step is skipped and marked as passed.
+ *
+ * If `do/stage` exits non-zero, the model is marked as stage-failed.
+ *
+ * @param {string} projectDir - Path to the generated project directory
+ * @param {object} [options] - Execution options
+ * @param {number} [options.timeout=1800] - Timeout in seconds (default: 30 minutes)
+ * @param {boolean} [options.verbose=false] - Stream stdout/stderr in real time
+ * @returns {Promise<object>} StepResult with name, status, duration, stagingState, and optional error
+ */
+export async function executeStageStep(projectDir, options = {}) {
+    const { timeout = 1800, verbose = false } = options;
+    const startTime = Date.now();
+
+    // Idempotency check: skip if already staged (Requirement 5.4)
+    if (isAlreadyStaged(projectDir)) {
+        return {
+            name: 'stage',
+            status: 'pass',
+            duration: Date.now() - startTime,
+            stagingState: STAGING_STATES.STAGED,
+            skipped: true,
+            message: '✓ Model already staged — skipping'
+        };
+    }
+
+    // Execute do/stage and verify exit code 0 (Requirement 5.2)
+    const command = './do/stage';
+
+    try {
+        if (verbose) {
+            // Verbose: stream output in real time
+            const { spawn } = await import('node:child_process');
+            const result = await new Promise((resolve) => {
+                const child = spawn('bash', ['-c', command], {
+                    cwd: projectDir,
+                    stdio: ['pipe', 'inherit', 'inherit']
+                });
+
+                let killed = false;
+                const timer = setTimeout(() => {
+                    killed = true;
+                    child.kill('SIGTERM');
+                }, timeout * 1000);
+
+                child.on('close', (code) => {
+                    clearTimeout(timer);
+                    if (code === 0) {
+                        resolve({
+                            name: 'stage',
+                            status: 'pass',
+                            duration: Date.now() - startTime,
+                            stagingState: STAGING_STATES.STAGED
+                        });
+                    } else {
+                        const error = killed
+                            ? `Timeout after ${timeout}s`
+                            : `do/stage exited with code ${code}`;
+                        resolve({
+                            name: 'stage',
+                            status: 'fail',
+                            duration: Date.now() - startTime,
+                            stagingState: STAGING_STATES.STAGE_FAILED,
+                            error
+                        });
+                    }
+                });
+
+                child.on('error', (err) => {
+                    clearTimeout(timer);
+                    resolve({
+                        name: 'stage',
+                        status: 'fail',
+                        duration: Date.now() - startTime,
+                        stagingState: STAGING_STATES.STAGE_FAILED,
+                        error: err.message.slice(-500)
+                    });
+                });
+            });
+            return result;
+        }
+
+        // Non-verbose: buffer output
+        await execFileAsync('bash', ['-c', command], {
+            cwd: projectDir,
+            timeout: timeout * 1000,
+            maxBuffer: 10 * 1024 * 1024
+        });
+
+        return {
+            name: 'stage',
+            status: 'pass',
+            duration: Date.now() - startTime,
+            stagingState: STAGING_STATES.STAGED
+        };
+    } catch (err) {
+        // Mark model as failed if staging fails (Requirement 5.3)
+        const error = err.killed
+            ? `Timeout after ${timeout}s`
+            : (err.stderr || err.message).slice(-500);
+
+        return {
+            name: 'stage',
+            status: 'fail',
+            duration: Date.now() - startTime,
+            stagingState: STAGING_STATES.STAGE_FAILED,
+            error
+        };
+    }
+}
+
+// ── Stage Validation ─────────────────────────────────────────────────────────
+
+/**
+ * Validate that a lifecycle stage name is recognized by the prove pipeline.
+ *
+ * @param {string} stageName - The stage name to validate
+ * @returns {boolean} True if the stage is valid
+ */
+export function isValidLifecycleStage(stageName) {
+    return VALID_LIFECYCLE_STAGES.includes(stageName);
+}
+
+/**
+ * Validate a stages array from validation-targets configuration.
+ *
+ * @param {string[]} stages - Array of stage names
+ * @returns {object} Validation result: { valid: boolean, errors: string[] }
+ */
+export function validateStagesArray(stages) {
+    const errors = [];
+
+    if (!Array.isArray(stages)) {
+        return { valid: false, errors: ['stages must be an array'] };
+    }
+
+    if (stages.length === 0) {
+        return { valid: false, errors: ['stages array must not be empty'] };
+    }
+
+    for (const stage of stages) {
+        if (typeof stage !== 'string') {
+            errors.push(`Invalid stage type: expected string, got ${typeof stage}`);
+            continue;
+        }
+        if (!isValidLifecycleStage(stage)) {
+            errors.push(`Unrecognized lifecycle stage: "${stage}"`);
+        }
+    }
+
+    return { valid: errors.length === 0, errors };
+}
+
+// ── Status Output ────────────────────────────────────────────────────────────
+
+/**
+ * Format the staging state for status output display.
+ *
+ * @param {string} state - One of STAGING_STATES values
+ * @returns {string} Formatted status string with emoji
+ */
+export function formatStagingStatus(state) {
+    switch (state) {
+    case STAGING_STATES.STAGED:
+        return '✓ staged';
+    case STAGING_STATES.NOT_STAGED:
+        return '○ not-staged';
+    case STAGING_STATES.STAGE_FAILED:
+        return '✗ stage-failed';
+    default:
+        return '? unknown';
+    }
+}
+
+/**
+ * Build a status summary for a prove target including staging state.
+ *
+ * @param {object} target - The validation target
+ * @param {string} target.model_name - Model name
+ * @param {string} projectDir - Path to the project directory
+ * @param {object} [stepResults] - Results of executed steps
+ * @returns {object} Status summary including stagingState
+ */
+export function buildTargetStatus(target, projectDir, stepResults = null) {
+    const stagingState = getStagingState(projectDir, stepResults);
+    const stages = target.stages || [];
+    const includesStage = stages.includes('stage');
+
+    return {
+        model_name: target.model_name,
+        stagingState,
+        stagingStatus: formatStagingStatus(stagingState),
+        includesStageStep: includesStage
+    };
+}

package/templates/do/README.md

@@ -262,6 +262,43 @@ Clean everything:
 
 ---
 
+### `./do/stage`
+
+Pre-stage model weights from HuggingFace to S3 for faster builds and deploys.
+
+**What it does:**
+- Downloads model weights from HuggingFace using `huggingface-cli`
+- Uses `hf_transfer` for accelerated parallel downloads
+- Syncs downloaded weights to S3 (regional, fast access)
+- Records the staged S3 URI in `.mlcc/staged-assets.json`
+- Idempotent: skips if model is already staged (use `--force` to re-stage)
+
+**Prerequisites:**
+- AWS credentials configured
+- `huggingface-cli` installed (`pip install huggingface_hub[cli] hf_transfer`)
+- Bootstrap profile configured (`ml-container-creator bootstrap`)
+
+**Usage:**
+```bash
+# Stage model to S3
+./do/stage
+
+# Force re-stage even if already present
+./do/stage --force
+
+# Stage and update MODEL_NAME in do/config
+./do/stage --update-config
+
+# Submit as SageMaker Processing Job (for models >500GB)
+./do/stage --submit
+```
+
+**Output:**
+- Staged model S3 URI
+- Updated `.mlcc/staged-assets.json` tracking file
+
+---
+
 <% if (typeof includeBenchmark !== 'undefined' && includeBenchmark) { %>
 ### `./do/benchmark`
 

package/templates/do/adapter

@@ -21,7 +21,10 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 ADAPTER_S3_BUCKET="${ADAPTER_S3_BUCKET:-mlcc-adapters-${_PROFILE[accountId]:-unknown}-${_PROFILE[awsRegion]:-us-east-1}}"
+set -u
 
 source "${SCRIPT_DIR}/lib/wait.sh"
 

package/templates/do/build

@@ -12,8 +12,11 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 ECR_REPOSITORY_NAME="${ECR_REPOSITORY_NAME:-${_PROFILE[ecrRepositoryName]:-ml-container-creator}}"
 export AWS_REGION="${AWS_REGION:-${_PROFILE[awsRegion]:-us-east-1}}"
+set -u
 
 echo "🚀 Building Docker image for ${PROJECT_NAME}"
 echo "   Deployment config: ${DEPLOYMENT_CONFIG}"

package/templates/do/clean.d/async-inference.ejs

@@ -12,8 +12,11 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 ECR_REPOSITORY_NAME="${ECR_REPOSITORY_NAME:-${_PROFILE[ecrRepositoryName]:-ml-container-creator}}"
 export AWS_REGION="${AWS_REGION:-${_PROFILE[awsRegion]:-us-east-1}}"
+set -u
 
 # Parse arguments
 CLEANUP_TARGET=""

package/templates/do/clean.d/batch-transform.ejs

@@ -12,8 +12,11 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 ECR_REPOSITORY_NAME="${ECR_REPOSITORY_NAME:-${_PROFILE[ecrRepositoryName]:-ml-container-creator}}"
 export AWS_REGION="${AWS_REGION:-${_PROFILE[awsRegion]:-us-east-1}}"
+set -u
 
 # Parse arguments
 CLEANUP_TARGET=""

package/templates/do/clean.d/hyperpod-eks.ejs

@@ -12,8 +12,11 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 ECR_REPOSITORY_NAME="${ECR_REPOSITORY_NAME:-${_PROFILE[ecrRepositoryName]:-ml-container-creator}}"
 export AWS_REGION="${AWS_REGION:-${_PROFILE[awsRegion]:-us-east-1}}"
+set -u
 
 # Parse arguments
 CLEANUP_TARGET=""

package/templates/do/clean.d/managed-inference.ejs

@@ -12,8 +12,11 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 ECR_REPOSITORY_NAME="${ECR_REPOSITORY_NAME:-${_PROFILE[ecrRepositoryName]:-ml-container-creator}}"
 export AWS_REGION="${AWS_REGION:-${_PROFILE[awsRegion]:-us-east-1}}"
+set -u
 
 # Parse arguments
 CLEANUP_TARGET=""

package/templates/do/deploy.d/async-inference.ejs

@@ -41,6 +41,8 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 ROLE_ARN="${ROLE_ARN:-${_PROFILE[roleArn]:-}}"
 ECR_REPOSITORY_NAME="${ECR_REPOSITORY_NAME:-${_PROFILE[ecrRepositoryName]:-ml-container-creator}}"
 export AWS_REGION="${AWS_REGION:-${_PROFILE[awsRegion]:-us-east-1}}"
@@ -50,6 +52,7 @@ _ASYNC_BUCKET="${_PROFILE[asyncS3Bucket]:-mlcc-async-${_PROFILE[accountId]:-unkn
 ASYNC_S3_OUTPUT_PATH="${ASYNC_S3_OUTPUT_PATH:-s3://${_ASYNC_BUCKET}/${PROJECT_NAME}/output/}"
 ASYNC_SNS_SUCCESS_TOPIC="${ASYNC_SNS_SUCCESS_TOPIC:-arn:aws:sns:${_PROFILE[awsRegion]:-us-east-1}:${_PROFILE[accountId]:-unknown}:ml-container-creator-${PROJECT_NAME}-async-success}"
 ASYNC_SNS_ERROR_TOPIC="${ASYNC_SNS_ERROR_TOPIC:-arn:aws:sns:${_PROFILE[awsRegion]:-us-east-1}:${_PROFILE[accountId]:-unknown}:ml-container-creator-${PROJECT_NAME}-async-error}"
+set -u
 
 echo "🚀 Deploying to AWS"
 echo "   Project: ${PROJECT_NAME}"

package/templates/do/deploy.d/batch-transform.ejs

@@ -41,6 +41,8 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 ROLE_ARN="${ROLE_ARN:-${_PROFILE[roleArn]:-}}"
 ECR_REPOSITORY_NAME="${ECR_REPOSITORY_NAME:-${_PROFILE[ecrRepositoryName]:-ml-container-creator}}"
 export AWS_REGION="${AWS_REGION:-${_PROFILE[awsRegion]:-us-east-1}}"
@@ -49,6 +51,7 @@ export AWS_REGION="${AWS_REGION:-${_PROFILE[awsRegion]:-us-east-1}}"
 _BATCH_BUCKET="${_PROFILE[batchS3Bucket]:-mlcc-batch-${_PROFILE[accountId]:-unknown}-${_PROFILE[awsRegion]:-us-east-1}}"
 BATCH_INPUT_PATH="${BATCH_INPUT_PATH:-s3://${_BATCH_BUCKET}/${PROJECT_NAME}/input/}"
 BATCH_OUTPUT_PATH="${BATCH_OUTPUT_PATH:-s3://${_BATCH_BUCKET}/${PROJECT_NAME}/output/}"
+set -u
 
 echo "🚀 Deploying to AWS"
 echo "   Project: ${PROJECT_NAME}"

package/templates/do/deploy.d/hyperpod-eks.ejs

@@ -41,7 +41,10 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 export AWS_REGION="${AWS_REGION:-${_PROFILE[awsRegion]:-us-east-1}}"
+set -u
 
 echo "🚀 Deploying to AWS"
 echo "   Project: ${PROJECT_NAME}"

package/templates/do/deploy.d/managed-inference.ejs

@@ -214,9 +214,12 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 ROLE_ARN="${ROLE_ARN:-${_PROFILE[roleArn]:-}}"
 ECR_REPOSITORY_NAME="${ECR_REPOSITORY_NAME:-${_PROFILE[ecrRepositoryName]:-ml-container-creator}}"
 export AWS_REGION="${AWS_REGION:-${_PROFILE[awsRegion]:-us-east-1}}"
+set -u
 
 echo "🚀 Deploying to AWS"
 echo "   Project: ${PROJECT_NAME}"

package/templates/do/lib/staged-assets.sh

@@ -0,0 +1,217 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Shared helper: read/write the .mlcc/staged-assets.json tracking file.
+# Sourced by do/stage, do/submit, and other lifecycle scripts.
+#
+# ─── Schema (.mlcc/staged-assets.json) ───────────────────────────────────────
+#
+# {
+#   "version": "1",
+#   "models": {
+#     "<ic-name>": {
+#       "source":     "<HuggingFace model ID, e.g. google/gemma-4-31B-it>",
+#       "staged_uri": "<S3 URI with trailing slash>",
+#       "staged_at":  "<ISO 8601 timestamp>",
+#       "region":     "<AWS region where the model was staged>",
+#       "size_gb":    <numeric size in GB>
+#     }
+#   },
+#   "adapters": {}
+# }
+#
+# Notes:
+#   - "version" is for forward-compatible schema evolution (start at "1")
+#   - "models" is keyed by IC name; use "default" for single-model projects
+#   - "adapters" is reserved for future LoRA adapter staging (BL-122)
+#   - This file is git-ignored (.mlcc/ contains account-specific URIs)
+#   - The file SHALL NOT be created unless a valid staging operation completes
+# ──────────────────────────────────────────────────────────────────────────────
+
+# Path to the staged-assets file (relative to project root)
+STAGED_ASSETS_DIR=".mlcc"
+STAGED_ASSETS_FILE="${STAGED_ASSETS_DIR}/staged-assets.json"
+
+# _staged_assets_has_jq()
+#   Check if jq is available on the system.
+#   Returns 0 if available, 1 if not.
+_staged_assets_has_jq() {
+    command -v jq &>/dev/null
+}
+
+# _staged_assets_warn_no_jq()
+#   Print a one-time warning when jq is not available.
+_staged_assets_warn_no_jq() {
+    if [ -z "${_STAGED_ASSETS_JQ_WARNED:-}" ]; then
+        echo "⚠️  jq not found — using fallback parser (install jq for full functionality)" >&2
+        _STAGED_ASSETS_JQ_WARNED=1
+    fi
+}
+
+# staged_assets_read_model_uri()
+#   Read the staged S3 URI for the default model from the staged-assets file.
+#   Echoes the S3 URI if found, or an empty string if not available.
+#
+#   Uses jq when available; falls back to grep/sed extraction.
+#
+#   Arguments: none
+#   Output:    S3 URI string (stdout) or empty string
+staged_assets_read_model_uri() {
+    local uri=""
+
+    # No file → empty string
+    if [ ! -f "${STAGED_ASSETS_FILE}" ]; then
+        echo ""
+        return 0
+    fi
+
+    if _staged_assets_has_jq; then
+        uri=$(jq -r '.models.default.staged_uri // empty' "${STAGED_ASSETS_FILE}" 2>/dev/null) || uri=""
+    else
+        _staged_assets_warn_no_jq
+        # Fallback: grep/sed extraction for the staged_uri field within the default model block
+        # This handles the common single-model case reliably
+        uri=$(grep -A 5 '"default"' "${STAGED_ASSETS_FILE}" 2>/dev/null \
+            | grep '"staged_uri"' \
+            | sed 's/.*"staged_uri"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' \
+            | head -1) || uri=""
+    fi
+
+    echo "${uri}"
+}
+
+# staged_assets_write_model()
+#   Create or update the staged-assets file with model staging information.
+#   Creates the .mlcc directory if it does not exist.
+#
+#   Arguments:
+#     $1 - source:   HuggingFace model ID (e.g. "google/gemma-4-31B-it")
+#     $2 - uri:      S3 URI where the model was staged (with trailing slash)
+#     $3 - region:   AWS region where the model was staged
+#     $4 - size_gb:  Total size of the staged model in GB (numeric)
+staged_assets_write_model() {
+    local source="$1"
+    local uri="$2"
+    local region="$3"
+    local size_gb="$4"
+    local timestamp
+    timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+    # Ensure the .mlcc directory exists
+    mkdir -p "${STAGED_ASSETS_DIR}"
+
+    if _staged_assets_has_jq; then
+        if [ -f "${STAGED_ASSETS_FILE}" ]; then
+            # Update existing file — merge the new model entry
+            local tmp_file="${STAGED_ASSETS_FILE}.tmp"
+            jq --arg source "${source}" \
+               --arg uri "${uri}" \
+               --arg ts "${timestamp}" \
+               --arg region "${region}" \
+               --argjson size "${size_gb}" \
+               '.models.default = {
+                   "source": $source,
+                   "staged_uri": $uri,
+                   "staged_at": $ts,
+                   "region": $region,
+                   "size_gb": $size
+               }' "${STAGED_ASSETS_FILE}" > "${tmp_file}" && mv "${tmp_file}" "${STAGED_ASSETS_FILE}"
+        else
+            # Create new file from scratch
+            jq -n --arg source "${source}" \
+                  --arg uri "${uri}" \
+                  --arg ts "${timestamp}" \
+                  --arg region "${region}" \
+                  --argjson size "${size_gb}" \
+                  '{
+                      "version": "1",
+                      "models": {
+                          "default": {
+                              "source": $source,
+                              "staged_uri": $uri,
+                              "staged_at": $ts,
+                              "region": $region,
+                              "size_gb": $size
+                          }
+                      },
+                      "adapters": {}
+                  }' > "${STAGED_ASSETS_FILE}"
+        fi
+    else
+        _staged_assets_warn_no_jq
+        # Fallback: write the JSON directly (create-only, no merge support without jq)
+        cat > "${STAGED_ASSETS_FILE}" << EOF
+{
+  "version": "1",
+  "models": {
+    "default": {
+      "source": "${source}",
+      "staged_uri": "${uri}",
+      "staged_at": "${timestamp}",
+      "region": "${region}",
+      "size_gb": ${size_gb}
+    }
+  },
+  "adapters": {}
+}
+EOF
+    fi
+}
+
+# staged_assets_status()
+#   Print a human-readable table of all staged assets.
+#   Shows models and adapters with their source, URI, region, size, and timestamp.
+#
+#   Arguments: none
+#   Output:    formatted table to stdout
+staged_assets_status() {
+    if [ ! -f "${STAGED_ASSETS_FILE}" ]; then
+        echo "No staged assets found."
+        echo "  Run do/stage to stage model weights to S3."
+        return 0
+    fi
+
+    echo "Staged Assets (.mlcc/staged-assets.json)"
+    echo "─────────────────────────────────────────────────────────────────"
+
+    if _staged_assets_has_jq; then
+        # Print models section
+        local model_count
+        model_count=$(jq -r '.models | length' "${STAGED_ASSETS_FILE}" 2>/dev/null) || model_count=0
+
+        if [ "${model_count}" -gt 0 ]; then
+            echo ""
+            echo "  Models:"
+            echo "  ┌──────────────┬─────────────────────────────────┬──────────────────────────────────────────────────────┬────────────┬─────────┐"
+            printf "  │ %-12s │ %-31s │ %-52s │ %-10s │ %-7s │\n" "IC Name" "Source" "S3 URI" "Region" "Size"
+            echo "  ├──────────────┼─────────────────────────────────┼──────────────────────────────────────────────────────┼────────────┼─────────┤"
+
+            jq -r '.models | to_entries[] | "\(.key)\t\(.value.source)\t\(.value.staged_uri)\t\(.value.region)\t\(.value.size_gb)"' "${STAGED_ASSETS_FILE}" 2>/dev/null | \
+            while IFS=$'\t' read -r ic_name source staged_uri region size_gb; do
+                printf "  │ %-12s │ %-31s │ %-52s │ %-10s │ %5s GB│\n" \
+                    "${ic_name}" "${source}" "${staged_uri}" "${region}" "${size_gb}"
+            done
+
+            echo "  └──────────────┴─────────────────────────────────┴──────────────────────────────────────────────────────┴────────────┴─────────┘"
+        fi
+
+        # Print adapters section (future — show placeholder if empty)
+        local adapter_count
+        adapter_count=$(jq -r '.adapters | length' "${STAGED_ASSETS_FILE}" 2>/dev/null) || adapter_count=0
+
+        if [ "${adapter_count}" -gt 0 ]; then
+            echo ""
+            echo "  Adapters:"
+            jq -r '.adapters | to_entries[] | "    \(.key): \(.value.staged_uri // "not staged")"' "${STAGED_ASSETS_FILE}" 2>/dev/null
+        fi
+    else
+        _staged_assets_warn_no_jq
+        # Fallback: basic display without jq
+        echo ""
+        echo "  Raw contents:"
+        echo ""
+        cat "${STAGED_ASSETS_FILE}"
+    fi
+
+    echo ""
+}

package/templates/do/push

@@ -12,8 +12,11 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 ECR_REPOSITORY_NAME="${ECR_REPOSITORY_NAME:-${_PROFILE[ecrRepositoryName]:-ml-container-creator}}"
 export AWS_REGION="${AWS_REGION:-${_PROFILE[awsRegion]:-us-east-1}}"
+set -u
 
 echo "🚀 Pushing Docker image to Amazon ECR"
 echo "   Project: ${PROJECT_NAME}"

package/templates/do/register

@@ -12,8 +12,11 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 ROLE_ARN="${ROLE_ARN:-${_PROFILE[roleArn]:-}}"
 ECR_REPOSITORY_NAME="${ECR_REPOSITORY_NAME:-${_PROFILE[ecrRepositoryName]:-ml-container-creator}}"
+set -u
 
 # ============================================================
 # Register deployment to the deployment registry

package/templates/do/stage

@@ -23,6 +23,8 @@ set -o pipefail
 # ── Source project configuration ──────────────────────────────────────────────
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/config"
+source "${SCRIPT_DIR}/lib/profile.sh"
+source "${SCRIPT_DIR}/lib/staged-assets.sh"
 
 # ── Parse flags ───────────────────────────────────────────────────────────────
 FORCE=false

package/templates/do/submit

@@ -12,7 +12,10 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 ECR_REPOSITORY_NAME="${ECR_REPOSITORY_NAME:-${_PROFILE[ecrRepositoryName]:-ml-container-creator}}"
+set -u
 
 # ── Derived variables (env var > computed default) ────────────────────────────
 CODEBUILD_PROJECT_NAME="${CODEBUILD_PROJECT_NAME:-${PROJECT_NAME}-build-$(date +%Y%m%d)}"

package/templates/do/tune

@@ -16,7 +16,10 @@ source "${SCRIPT_DIR}/config"
 source "${SCRIPT_DIR}/lib/profile.sh"
 
 # ── Profile-resolved variables (env var > profile > default) ──────────────────
+# Disable unbound-variable checking for associative array access (bash 3.2 compat)
+set +u
 TUNE_S3_BUCKET="${TUNE_S3_BUCKET:-mlcc-tune-${_PROFILE[accountId]:-unknown}-${_PROFILE[awsRegion]:-us-east-1}}"
+set -u
 
 # ── Constants ─────────────────────────────────────────────────────────────────
 CATALOG_FILE="${SCRIPT_DIR}/.tune_catalog.json"