@aifabrix/builder 2.43.0 → 2.44.1

package/lib/utils/yaml-preserve.js

@@ -251,6 +251,35 @@ function collectBlockScalarLines(lines, startIndex, keyIndentLen) {
   return { value: parts.join(' '), endIndex: i };
 }
 
+/**
+ * Processes a single block-scalar key line and its continuation lines.
+ * @param {string} line - Line matching BLOCK_SCALAR_PATTERN
+ * @param {string[]} lines - All lines
+ * @param {number} lineIndex - Index of current line
+ * @param {string} encryptionKey - Encryption key
+ * @param {Object} stats - Mutable stats object
+ * @returns {{ resultLine: string, nextIndex: number }|null} Result or null if not a block scalar
+ */
+function processBlockScalarLine(line, lines, lineIndex, encryptionKey, stats) {
+  const blockMatch = line.match(BLOCK_SCALAR_PATTERN);
+  if (!blockMatch) {
+    return null;
+  }
+  const [, indent, key, blockIndicator, trailingWhitespace, comment] = blockMatch;
+  const keyIndentLen = indent.length;
+  const folded = blockIndicator.startsWith('>');
+  const { value: rawValue, endIndex } = collectBlockScalarLines(lines, lineIndex + 1, keyIndentLen);
+  const value = folded ? rawValue.replace(/\s+/g, ' ').trim() : rawValue;
+  stats.total++;
+  const needEncrypt = shouldEncryptValue(value);
+  const outValue = needEncrypt ? encryptSecret(value, encryptionKey) : value;
+  if (needEncrypt) {
+    stats.encrypted++;
+  }
+  const resultLine = `${indent}${key}: ${outValue}${trailingWhitespace || ''}${comment || ''}`;
+  return { resultLine, nextIndex: endIndex };
+}
+
 function encryptYamlValues(content, encryptionKey) {
   const lines = content.split(/\r?\n/);
   const encryptedLines = [];
@@ -267,20 +296,10 @@ function encryptYamlValues(content, encryptionKey) {
       continue;
     }
 
-    const blockMatch = line.match(BLOCK_SCALAR_PATTERN);
-    if (blockMatch) {
-      const [, indent, key, blockIndicator, trailingWhitespace, comment] = blockMatch;
-      const keyIndentLen = indent.length;
-      const folded = blockIndicator.startsWith('>');
-      const { value: rawValue, endIndex } = collectBlockScalarLines(lines, i + 1, keyIndentLen);
-      const value = folded ? rawValue.replace(/\s+/g, ' ').trim() : rawValue;
-      stats.total++;
-      const outValue = shouldEncryptValue(value) ? encryptSecret(value, encryptionKey) : value;
-      if (shouldEncryptValue(value)) {
-        stats.encrypted++;
-      }
-      encryptedLines.push(`${indent}${key}: ${outValue}${trailingWhitespace || ''}${comment || ''}`);
-      i = endIndex;
+    const blockResult = processBlockScalarLine(line, lines, i, encryptionKey, stats);
+    if (blockResult) {
+      encryptedLines.push(blockResult.resultLine);
+      i = blockResult.nextIndex;
       continue;
     }
 

package/lib/validation/datasource-warnings.js

@@ -0,0 +1,56 @@
+/**
+ * Optional v2.4.x datasource validation warnings (beyond JSON Schema).
+ *
+ * @fileoverview Post-schema warnings for external datasource configs
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const STORAGE_ENTITIES = new Set(['recordStorage', 'documentStorage']);
+
+function warnMissingDimensions(parsed, warnings) {
+  const entityType = parsed.entityType;
+  if (!STORAGE_ENTITIES.has(entityType)) {
+    return;
+  }
+  const dims = parsed.dimensions;
+  if (!dims || typeof dims !== 'object' || Array.isArray(dims) || Object.keys(dims).length === 0) {
+    warnings.push(
+      `Datasource "${parsed.key || '(unknown)'}": dimensions missing or empty for entityType=${entityType} (recommended for ABAC; see schema 2.4.x notes).`
+    );
+  }
+}
+
+function warnFkWithoutActor(parsed, warnings) {
+  const dimensions = parsed.dimensions;
+  if (!dimensions || typeof dimensions !== 'object' || Array.isArray(dimensions)) {
+    return;
+  }
+  for (const [dimKey, binding] of Object.entries(dimensions)) {
+    if (!binding || typeof binding !== 'object' || binding.type !== 'fk') {
+      continue;
+    }
+    if (!Object.prototype.hasOwnProperty.call(binding, 'actor')) {
+      warnings.push(
+        `Datasource "${parsed.key || '(unknown)'}": dimension "${dimKey}" uses type=fk without actor; set actor (displayName, email, userId, groups, roles) for predictable ABAC binding.`
+      );
+    }
+  }
+}
+
+/**
+ * Collects non-fatal warnings for an external datasource document (already parsed).
+ * @param {Object} parsed - Parsed datasource JSON
+ * @returns {string[]} Warning messages (empty if none)
+ */
+function collectExternalDatasourceWarnings(parsed) {
+  const warnings = [];
+  if (!parsed || typeof parsed !== 'object') {
+    return warnings;
+  }
+  warnMissingDimensions(parsed, warnings);
+  warnFkWithoutActor(parsed, warnings);
+  return warnings;
+}
+
+module.exports = { collectExternalDatasourceWarnings };

package/lib/validation/env-template-auth.js

@@ -184,7 +184,7 @@ async function validateAuthSecurityPathConsistency(appPath, errors, _warnings) {
         const canonicalPath = canonicalSegment ? `kv://${systemKey}/${canonicalSegment}` : null;
         if (canonicalPath && value !== canonicalPath) {
           errors.push(
-            `authentication.security.${key} has path ${value}; canonical path is ${canonicalPath}. Run \`aifabrix repair <app>\` to normalize.`
+            `authentication.security.${key} has path ${value}; canonical path is ${canonicalPath}. Run \`aifabrix repair <systemKey>\` to normalize.`
           );
         }
       }

package/lib/validation/external-manifest-validator.js

@@ -10,6 +10,7 @@
  */
 
 const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
 const fs = require('fs');
 const path = require('path');
 const { formatValidationErrors } = require('../utils/error-formatter');
@@ -28,6 +29,7 @@ async function setupAjvWithSchemas() {
     strict: false,
     removeAdditional: false
   });
+  addFormats(ajv);
 
   // Load raw schema objects (not compiled validators)
   const externalSystemSchemaPath = path.join(__dirname, '..', 'schema', 'external-system.schema.json');
@@ -43,11 +45,20 @@ async function setupAjvWithSchemas() {
     externalDatasourceSchema = schemaCopy;
   }
 
-  const externalSystemSchemaId = externalSystemSchema.$id || 'https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/external-system.schema.json';
-  const externalDatasourceSchemaId = externalDatasourceSchema.$id || 'https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/external-datasource.schema.json';
+  if (!externalSystemSchema.$id || typeof externalSystemSchema.$id !== 'string') {
+    throw new Error('External system schema is missing required $id');
+  }
+  if (!externalDatasourceSchema.$id || typeof externalDatasourceSchema.$id !== 'string') {
+    throw new Error('External datasource schema is missing required $id');
+  }
 
-  ajv.addSchema(externalSystemSchema, externalSystemSchemaId);
-  ajv.addSchema(externalDatasourceSchema, externalDatasourceSchemaId);
+  // external-datasource.schema.json references these by $id (aifabrix://schema/type/*)
+  ajv.addSchema(require('../schema/type/document-storage.json'));
+  ajv.addSchema(require('../schema/type/message-service.json'));
+  ajv.addSchema(require('../schema/type/vector-store.json'));
+
+  ajv.addSchema(externalSystemSchema, externalSystemSchema.$id);
+  ajv.addSchema(externalDatasourceSchema, externalDatasourceSchema.$id);
 
   return { ajv, externalSystemSchema, externalDatasourceSchema };
 }
@@ -66,7 +77,10 @@ function validateManifestStructure(manifest, ajv, applicationSchema, errors) {
   const manifestValid = validateManifest(manifest);
 
   if (!manifestValid) {
-    const manifestErrors = formatValidationErrors(validateManifest.errors);
+    const manifestErrors = formatValidationErrors(validateManifest.errors, {
+      rootData: manifest,
+      deploymentManifest: manifest
+    });
     errors.push(...manifestErrors.map(err => `Manifest validation: ${err}`));
   }
 }
@@ -86,7 +100,10 @@ function validateInlineSystem(manifest, ajv, externalSystemSchema, errors) {
     const systemValid = validateSystem(manifest.system);
 
     if (!systemValid) {
-      const systemErrors = formatValidationErrors(validateSystem.errors);
+      const systemErrors = formatValidationErrors(validateSystem.errors, {
+        rootData: manifest.system,
+        deploymentManifest: manifest.system
+      });
       errors.push(...systemErrors.map(err => `System validation: ${err}`));
     }
   } else if (manifest.type === 'external') {
@@ -113,7 +130,10 @@ function validateDatasources(manifest, ajv, externalDatasourceSchema, errors, wa
       manifest.dataSources.forEach((datasource, index) => {
         const datasourceValid = validateDatasource(datasource);
         if (!datasourceValid) {
-          const datasourceErrors = formatValidationErrors(validateDatasource.errors);
+          const datasourceErrors = formatValidationErrors(validateDatasource.errors, {
+            rootData: datasource,
+            deploymentManifest: datasource
+          });
           errors.push(...datasourceErrors.map(err => `Datasource ${index + 1} (${datasource.key || 'unknown'}): ${err}`));
         } else {
           const fieldRefErrors = validateFieldReferences(datasource);

package/lib/validation/validate-display.js

@@ -1,3 +1,4 @@
+const { formatBlockingError, formatSuccessLine, formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
 /**
  * Validation Display Utilities
  *
@@ -25,9 +26,9 @@ function displayApplicationValidation(application) {
 
   logger.log(chalk.blue('\nApplication:'));
   if (application.valid) {
-    logger.log(chalk.green('  ✓ Application configuration is valid'));
+    logger.log(chalk.green('  ✔ Application configuration is valid'));
   } else {
-    logger.log(chalk.red('  ✗ Application configuration has errors:'));
+    logger.log(chalk.red('  ✖ Application configuration has errors:'));
     if (application.errors && application.errors.length > 0) {
       application.errors.forEach(error => {
         logger.log(chalk.red(`    • ${error}`));
@@ -51,12 +52,17 @@ function extractDimensionsFromDatasource(filePath) {
   try {
     const parsed = loadConfigFile(filePath);
 
-    // Check fieldMappings.dimensions (primary location)
-    const dimensions = parsed.fieldMappings?.dimensions || {};
+    const rootFlat = {};
+    const root = parsed.dimensions;
+    if (root && typeof root === 'object' && !Array.isArray(root)) {
+      for (const [dimKey, binding] of Object.entries(root)) {
+        if (binding && typeof binding === 'object' && typeof binding.field === 'string') {
+          rootFlat[dimKey] = `metadata.${binding.field}`;
+        }
+      }
+    }
     const abacDimensions = parsed.abac?.dimensions || {};
-
-    // Merge both sources (abac.dimensions can override fieldMappings.dimensions)
-    const allDimensions = { ...dimensions, ...abacDimensions };
+    const allDimensions = { ...rootFlat, ...abacDimensions };
     const dimensionKeys = Object.keys(allDimensions);
 
     return {
@@ -82,9 +88,9 @@ function displayExternalFilesValidation(externalFiles) {
   logger.log(chalk.blue('\nExternal Integration Files:'));
   externalFiles.forEach(file => {
     if (file.valid) {
-      logger.log(chalk.green(`  ✓ ${file.file} (${file.type})`));
+      logger.log(chalk.green(`  ✔ ${file.file} (${file.type})`));
     } else {
-      logger.log(chalk.red(`  ✗ ${file.file} (${file.type}):`));
+      logger.log(chalk.red(`  ✖ ${file.file} (${file.type}):`));
       file.errors.forEach(error => {
         logger.log(chalk.red(`    • ${error}`));
       });
@@ -126,7 +132,7 @@ function displayDimensionsValidation(externalFiles) {
 
     if (dimensionsInfo.hasDimensions) {
       anyDatasourceHasDimensions = true;
-      logger.log(chalk.green(`  ✓ ${file.file}`));
+      logger.log(chalk.green(`  ✔ ${file.file}`));
       dimensionsInfo.dimensionKeys.forEach(key => {
         const mapping = dimensionsInfo.dimensions[key];
         logger.log(chalk.gray(`      ${key} → ${mapping}`));
@@ -156,9 +162,9 @@ function displayRbacValidation(rbac) {
 
   logger.log(chalk.blue('\nRBAC Configuration:'));
   if (rbac.valid) {
-    logger.log(chalk.green('  ✓ RBAC configuration is valid'));
+    logger.log(chalk.green('  ✔ RBAC configuration is valid'));
   } else {
-    logger.log(chalk.red('  ✗ RBAC configuration has errors:'));
+    logger.log(chalk.red('  ✖ RBAC configuration has errors:'));
     rbac.errors.forEach(error => {
       logger.log(chalk.red(`    • ${error}`));
     });
@@ -183,9 +189,9 @@ function displayFileValidation(result) {
   logger.log(chalk.blue(`\nFile: ${result.file}`));
   logger.log(chalk.blue(`Type: ${result.type}`));
   if (result.valid) {
-    logger.log(chalk.green('  ✓ File is valid'));
+    logger.log(chalk.green('  ✔ File is valid'));
   } else {
-    logger.log(chalk.red('  ✗ File has errors:'));
+    logger.log(chalk.red('  ✖ File has errors:'));
     result.errors.forEach(error => {
       logger.log(chalk.red(`    • ${error}`));
     });
@@ -222,9 +228,9 @@ function displayAggregatedWarnings(warnings) {
 function displayApplicationStep(application) {
   logger.log(chalk.blue('\nApplication:'));
   if (application.valid) {
-    logger.log(chalk.green('  ✓ Application configuration is valid'));
+    logger.log(chalk.green('  ✔ Application configuration is valid'));
   } else {
-    logger.log(chalk.red('  ✗ Application configuration has errors:'));
+    logger.log(chalk.red('  ✖ Application configuration has errors:'));
     application.errors.forEach(error => {
       logger.log(chalk.red(`    • ${error}`));
     });
@@ -253,9 +259,9 @@ function displayComponentsStep(components) {
   if (hasFiles) {
     components.files.forEach(file => {
       if (file.valid) {
-        logger.log(chalk.green(`  ✓ ${file.file} (${file.type})`));
+        logger.log(chalk.green(`  ✔ ${file.file} (${file.type})`));
       } else {
-        logger.log(chalk.red(`  ✗ ${file.file} (${file.type})`));
+        logger.log(chalk.red(`  ✖ ${file.file} (${file.type})`));
       }
     });
   }
@@ -282,7 +288,7 @@ function displayDimensionsStep(datasourceFiles) {
     try {
       const dimensionsInfo = extractDimensionsFromDatasource(file.path || file.file);
       if (dimensionsInfo.hasDimensions) {
-        logger.log(chalk.green(`  ✓ ${file.file}`));
+        logger.log(chalk.green(`  ✔ ${file.file}`));
         dimensionsInfo.dimensionKeys.forEach(key => {
           const mapping = dimensionsInfo.dimensions[key];
           logger.log(chalk.gray(`      ${key} → ${mapping}`));
@@ -308,15 +314,15 @@ function displayManifestStep(manifest, componentFiles) {
   if (manifest.skipped) {
     logger.log(chalk.yellow('  ⊘ Skipped (fix errors above first)'));
   } else if (manifest.valid) {
-    logger.log(chalk.green('  ✓ Full deployment manifest is valid'));
+    logger.log(chalk.green('  ✔ Full deployment manifest is valid'));
     if (componentFiles) {
       const datasourceFiles = componentFiles.filter(f => f.type === 'datasource' || f.type === 'external-datasource');
-      logger.log(chalk.green('    ✓ System configuration valid'));
-      logger.log(chalk.green(`    ✓ ${datasourceFiles.length} datasource(s) valid`));
-      logger.log(chalk.green('    ✓ Schema validation passed'));
+      logger.log(chalk.green('    ✔ System configuration valid'));
+      logger.log(chalk.green(`    ✔ ${datasourceFiles.length} datasource(s) valid`));
+      logger.log(chalk.green('    ✔ Schema validation passed'));
     }
   } else {
-    logger.log(chalk.red('  ✗ Full deployment manifest validation failed:'));
+    logger.log(chalk.red('  ✖ Full deployment manifest validation failed:'));
     const errs = manifest.errors && manifest.errors.length > 0 ? manifest.errors : [];
     if (errs.length > 0) {
       errs.forEach(error => {
@@ -341,9 +347,9 @@ function displayManifestStep(manifest, componentFiles) {
  */
 function displayStepByStepValidation(result) {
   if (result.valid) {
-    logger.log(chalk.green('\n✓ Validation passed!'));
+    logger.log(formatSuccessParagraph('Validation passed!'));
   } else {
-    logger.log(chalk.red('\n✗ Validation failed!'));
+    logger.log(chalk.red('\n✖ Validation failed!'));
   }
 
   displayApplicationStep(result.steps.application);
@@ -388,7 +394,7 @@ function displayBatchValidationResults(batchResult) {
   results.forEach(item => {
     logger.log(chalk.blue(`\n--- ${item.appName} ---`));
     if (item.error) {
-      logger.log(chalk.red(`  ✗ ${item.error}`));
+      logger.log(chalk.red(`  ✖ ${item.error}`));
     } else if (item.result) {
       displayValidationResults(item.result);
     }
@@ -398,10 +404,10 @@ function displayBatchValidationResults(batchResult) {
   const failed = results.length - passed;
   logger.log(chalk.blue('\n--- Summary ---'));
   if (failed === 0) {
-    logger.log(chalk.green(`✓ ${passed} passed, 0 failed`));
+    logger.log(formatSuccessLine(`${passed} passed, 0 failed`));
     logger.log(chalk.green('Overall: Passed'));
   } else {
-    logger.log(chalk.red(`✗ ${passed} passed, ${failed} failed`));
+    logger.log(formatBlockingError(`${passed} passed, ${failed} failed`));
     logger.log(chalk.red('Overall: Failed'));
   }
 }
@@ -445,9 +451,9 @@ function displayValidationResults(result) {
 
   // Legacy format (for regular apps)
   if (result.valid) {
-    logger.log(chalk.green('\n✓ Validation passed!'));
+    logger.log(formatSuccessParagraph('Validation passed!'));
   } else {
-    logger.log(chalk.red('\n✗ Validation failed!'));
+    logger.log(chalk.red('\n✖ Validation failed!'));
   }
 
   displayApplicationValidation(result.application);

package/lib/validation/validate-external-cert-sync.js

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Optional certification sync after external validate (keeps validate.js under max-lines).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {string} appName
+ * @param {Object} options
+ * @param {function(string, Object): Promise<Object>} validateExternalSystemComplete
+ */
+async function runExternalValidateWithOptionalCertSync(appName, options, validateExternalSystemComplete) {
+  const result = await validateExternalSystemComplete(appName, options);
+  if (result.valid && options.certSync === true) {
+    const { trySyncCertificationFromDataplaneForExternalApp } = require('../certification/sync-after-external-command');
+    await trySyncCertificationFromDataplaneForExternalApp(appName, 'validate');
+  }
+  return result;
+}
+
+module.exports = { runExternalValidateWithOptionalCertSync };

package/lib/validation/validate.js

@@ -28,6 +28,7 @@ const {
   validateOAuth2GrantTypeAndAuthorizationUrl,
   validateConfigurationNoStandardAuthVariables
 } = require('./external-system-auth-rules');
+const { runExternalValidateWithOptionalCertSync } = require('./validate-external-cert-sync');
 
 /**
  * Validates a file path (detects type and validates)
@@ -104,15 +105,6 @@ function aggregateValidationResults(appValidation, externalValidations, rbacVali
   };
 }
 
-/**
- * Validates a single external file against its schema
- *
- * @async
- * @function validateExternalFile
- * @param {string} filePath - Path to the file
- * @param {string} type - File type: 'system' | 'datasource'
- * @returns {Promise<Object>} Validation result
- */
 /**
  * Parses external system/datasource file content (JSON or YAML).
  * @function parseJsonFileContent
@@ -179,6 +171,7 @@ function validateRoleReferences(parsed, errors) {
   });
 }
 
+/** @async */
 async function validateExternalFile(filePath, type) {
   if (!fs.existsSync(filePath)) {
     throw new Error(`File not found: ${filePath}`);
@@ -203,9 +196,9 @@ async function validateExternalFile(filePath, type) {
   }
 
   if (normalizedType === 'datasource') {
-    const fieldRefErrors = validateFieldReferences(parseResult.parsed);
-    const abacErrors = validateAbac(parseResult.parsed);
-    errors.push(...fieldRefErrors, ...abacErrors);
+    const { collectExternalDatasourceWarnings } = require('./datasource-warnings');
+    errors.push(...validateFieldReferences(parseResult.parsed), ...validateAbac(parseResult.parsed));
+    warnings.push(...collectExternalDatasourceWarnings(parseResult.parsed));
   }
 
   return {
@@ -470,7 +463,9 @@ async function validateAppOrFile(appOrFile, options = {}) {
   const { appPath, isExternal } = await detectAppType(appName);
   logOfflinePathWhenType(appPath);
 
-  if (isExternal) return await validateExternalSystemComplete(appName, options);
+  if (isExternal) {
+    return await runExternalValidateWithOptionalCertSync(appName, options, validateExternalSystemComplete);
+  }
 
   const appValidation = await validator.validateApplication(appName, options);
   const rbacValidation = await validateRbacForExternalSystem(isExternal, appName);
@@ -497,4 +492,3 @@ module.exports = {
   validateAll: (opts = {}) => batch.validateAll(validateAppOrFile, opts),
   buildBatchResult: batch.buildBatchResult
 };
-

package/lib/validation/validator-unresolved-placeholders.js

@@ -0,0 +1,98 @@
+/**
+ * Scan deployment/config objects for unresolved ${VAR} placeholders (validator helper).
+ *
+ * @fileoverview Extracted from validator.js for ESLint max-lines
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** Pattern matching ${VAR} style unresolved variables in strings */
+const UNRESOLVED_VAR_REGEX = /\$\{[^}]+\}/g;
+
+/** Allowed manifest placeholders in frontDoorRouting.host (expanded at run/resolve time; plan 122). */
+const FRONT_DOOR_HOST_ALLOWED = /\$\{DEV_USERNAME\}|\$\{REMOTE_HOST\}/g;
+
+/**
+ * First ${...} still present after stripping allowed DEV_USERNAME / REMOTE_HOST segments, or null.
+ * @param {string} str
+ * @returns {string|null}
+ */
+function getFrontDoorHostFirstForbiddenPlaceholder(str) {
+  let t = String(str).trim();
+  t = t.replace(FRONT_DOOR_HOST_ALLOWED, '');
+  t = t.replace(/^\.+|\.+$/g, '').trim();
+  const m = t.match(UNRESOLVED_VAR_REGEX);
+  return m ? m[0] : null;
+}
+
+/**
+ * @param {string} obj
+ * @param {string} prefix
+ * @returns {string[]}
+ */
+function collectStringUnresolved(obj, prefix) {
+  if (prefix === 'frontDoorRouting.host') {
+    const bad = getFrontDoorHostFirstForbiddenPlaceholder(obj);
+    return bad ? [`${prefix}: ${bad}`] : [];
+  }
+  const matches = obj.match(UNRESOLVED_VAR_REGEX);
+  if (matches && matches.length > 0) {
+    const pathLabel = prefix || 'value';
+    return [`${pathLabel}: ${matches[0]}`];
+  }
+  return [];
+}
+
+/**
+ * Recursively finds all string values in obj that contain ${...} placeholders.
+ *
+ * @param {Object} obj - Object to scan (e.g. deployment manifest)
+ * @param {string} [prefix=''] - Path prefix for error reporting
+ * @returns {string[]} List of paths with example placeholder (e.g. "port: ${PORT}")
+ */
+function findUnresolvedVariablesInObject(obj, prefix = '') {
+  const found = [];
+  if (obj === null || obj === undefined) {
+    return found;
+  }
+  if (typeof obj === 'string') {
+    return collectStringUnresolved(obj, prefix);
+  }
+  if (Array.isArray(obj)) {
+    obj.forEach((item, i) => {
+      found.push(...findUnresolvedVariablesInObject(item, `${prefix}[${i}]`));
+    });
+    return found;
+  }
+  if (typeof obj === 'object') {
+    for (const [key, value] of Object.entries(obj)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      found.push(...findUnresolvedVariablesInObject(value, path));
+    }
+    return found;
+  }
+  return found;
+}
+
+/**
+ * Validates that deployment manifest contains no unresolved ${...} variables.
+ * @param {Object} deployment - Deployment manifest object
+ * @throws {Error} If any ${...} placeholders are found
+ */
+function validateNoUnresolvedVariablesInDeployment(deployment) {
+  const unresolved = findUnresolvedVariablesInObject(deployment);
+  if (unresolved.length > 0) {
+    const examples = [...new Set(unresolved)].slice(0, 5).join(', ');
+    throw new Error(
+      `Deployment manifest contains unresolved variables (e.g. ${examples}). ` +
+        'Use secret variables (kv://) in env.template for sensitive values, and set the application port as a number in application.yaml.'
+    );
+  }
+}
+
+module.exports = {
+  findUnresolvedVariablesInObject,
+  validateNoUnresolvedVariablesInDeployment
+};