@aifabrix/builder 2.40.0 → 2.41.0

package/lib/core/secrets.js

@@ -8,7 +8,7 @@
  * @author AI Fabrix Team
  * @version 2.0.0
  */
-
+/* eslint-disable max-lines -- Central module; env-only resolve (plan 75) added required options; extract to env-merge would touch multiple callers. */
 const fs = require('fs');
 const path = require('path');
 const logger = require('../utils/logger');
@@ -27,20 +27,27 @@ const {
   ensureNonEmptySecrets,
   validateSecrets
 } = require('../utils/secrets-helpers');
-const { processEnvVariables } = require('../utils/env-copy');
 const { buildEnvVarMap } = require('../utils/env-map');
 const { resolveServicePortsInEnvContent } = require('../utils/secrets-url');
-const { updatePortForDocker } = require('./secrets-docker-env');
+const {
+  updatePortForDocker,
+  getBaseDockerEnv,
+  applyDockerEnvOverride,
+  getContainerPortFromDockerEnv
+} = require('./secrets-docker-env');
+const { getContainerPortFromPath } = require('../utils/port-resolver');
 const {
   generateMissingSecrets,
   createDefaultSecrets
 } = require('../utils/secrets-generator');
+const secretsEnsure = require('./secrets-ensure');
 const {
   resolveSecretsPath,
   getActualSecretsPath
 } = require('../utils/secrets-path');
 const {
   loadUserSecrets,
+  loadPrimaryUserSecrets,
   loadDefaultSecrets
 } = require('../utils/secrets-utils');
 const { decryptSecret, isEncrypted } = require('../utils/secrets-encryption');
@@ -162,12 +169,18 @@ function mergeUserWithConfigFile(userSecrets, resolvedConfigPath) {
 }
 
 /**
- * Loads config secrets path, merges with user secrets (user overrides). Used by loadSecrets cascade.
+ * Loads config secrets path, merges with user secrets (user/master wins, public fills missing).
+ * User/master = primary home (AIFABRIX_HOME or ~/.aifabrix) secrets.local.yaml.
+ * Public = aifabrix-secrets path from config. Used by loadSecrets cascade.
+ * When aifabrix-secrets is an http(s) URL, fetches shared secrets from API (never persisted to disk).
+ *
  * @async
  * @returns {Promise<Object|null>} Merged secrets object or null
  */
 async function loadMergedConfigAndUserSecrets() {
-  const userSecrets = loadUserSecrets();
+  const { loadRemoteSharedSecrets, mergeUserWithRemoteSecrets } = require('../utils/remote-secrets-loader');
+  const { isRemoteSecretsUrl } = require('../utils/remote-dev-auth');
+  const userSecrets = loadPrimaryUserSecrets();
   const hasKeys = (obj) => obj && Object.keys(obj).length > 0;
   const userOrNull = () => (hasKeys(userSecrets) ? userSecrets : null);
   try {
@@ -175,6 +188,11 @@ async function loadMergedConfigAndUserSecrets() {
     if (!configSecretsPath) {
       return userOrNull();
     }
+    if (isRemoteSecretsUrl(configSecretsPath)) {
+      const remoteSecrets = await loadRemoteSharedSecrets();
+      const merged = mergeUserWithRemoteSecrets(userSecrets, remoteSecrets);
+      return hasKeys(merged) ? merged : userOrNull();
+    }
     const resolvedConfigPath = path.isAbsolute(configSecretsPath)
       ? configSecretsPath
       : path.resolve(process.cwd(), configSecretsPath);
@@ -203,7 +221,10 @@ async function loadSecrets(secretsPath, _appName) {
 
   let mergedSecrets = await loadMergedConfigAndUserSecrets();
   if (!mergedSecrets || Object.keys(mergedSecrets).length === 0) {
-    mergedSecrets = loadUserSecrets();
+    mergedSecrets = loadPrimaryUserSecrets();
+    if (Object.keys(mergedSecrets).length === 0) {
+      mergedSecrets = loadUserSecrets();
+    }
     mergedSecrets = await applyCanonicalSecretsOverride(mergedSecrets);
   }
   if (Object.keys(mergedSecrets).length === 0) {
@@ -259,44 +280,57 @@ async function resolveKvReferences(envTemplate, secrets, environment = 'local',
   return replaceKvInContent(resolved, secrets, envVars);
 }
 
-/** Applies environment-specific transformations to resolved content. */
+/** Docker env transformations: ports, infra endpoints, PORT. */
+async function applyDockerTransformations(resolved, variablesPath) {
+  resolved = await resolveServicePortsInEnvContent(resolved, 'docker');
+  resolved = await rewriteInfraEndpoints(resolved, 'docker');
+  const { getEnvHosts, getServiceHost, getServicePort, getLocalhostOverride } = require('../utils/env-endpoints');
+  const hosts = await getEnvHosts('docker');
+  const localhostOverride = getLocalhostOverride('docker');
+  const redisHost = getServiceHost(hosts.REDIS_HOST, 'docker', 'redis', localhostOverride);
+  const redisPort = await getServicePort('REDIS_PORT', 'redis', hosts, 'docker', null);
+  const dbHost = getServiceHost(hosts.DB_HOST, 'docker', 'postgres', localhostOverride);
+  const dbPort = await getServicePort('DB_PORT', 'postgres', hosts, 'docker', null);
+  let dockerEnv = await getBaseDockerEnv();
+  dockerEnv = applyDockerEnvOverride(dockerEnv);
+  const containerPort = getContainerPortFromPath(variablesPath) ?? getContainerPortFromDockerEnv(dockerEnv) ?? 3000;
+  const envVars = await buildEnvVarMap('docker', null, null, { appPort: containerPort });
+  envVars.REDIS_HOST = redisHost;
+  envVars.REDIS_PORT = String(redisPort);
+  envVars.DB_HOST = dbHost;
+  envVars.DB_PORT = String(dbPort);
+  envVars.PORT = String(containerPort);
+  resolved = interpolateEnvVars(resolved, envVars);
+  return updatePortForDocker(resolved, variablesPath);
+}
+/** Environment-specific transformations to resolved content. */
 async function applyEnvironmentTransformations(resolved, environment, variablesPath) {
-  if (environment === 'docker') {
-    resolved = await resolveServicePortsInEnvContent(resolved, environment);
-    resolved = await rewriteInfraEndpoints(resolved, 'docker');
-    const { getEnvHosts, getServiceHost, getServicePort, getLocalhostOverride } = require('../utils/env-endpoints');
-    const hosts = await getEnvHosts('docker');
-    const localhostOverride = getLocalhostOverride('docker');
-    const redisHost = getServiceHost(hosts.REDIS_HOST, 'docker', 'redis', localhostOverride);
-    const redisPort = await getServicePort('REDIS_PORT', 'redis', hosts, 'docker', null);
-    const dbHost = getServiceHost(hosts.DB_HOST, 'docker', 'postgres', localhostOverride);
-    const dbPort = await getServicePort('DB_PORT', 'postgres', hosts, 'docker', null);
-    const envVars = await buildEnvVarMap('docker');
-    envVars.REDIS_HOST = redisHost;
-    envVars.REDIS_PORT = String(redisPort);
-    envVars.DB_HOST = dbHost;
-    envVars.DB_PORT = String(dbPort);
-    resolved = interpolateEnvVars(resolved, envVars);
-    resolved = await updatePortForDocker(resolved, variablesPath);
-  } else if (environment === 'local') {
-    // adjustLocalEnvPortsInContent handles both PORT and infra endpoints
-    resolved = await adjustLocalEnvPortsInContent(resolved, variablesPath);
-  }
+  if (environment === 'docker') return applyDockerTransformations(resolved, variablesPath);
+  if (environment === 'local') return adjustLocalEnvPortsInContent(resolved, variablesPath);
   return resolved;
 }
 
-/** Generates .env file content from template and secrets (without writing to disk). */
-async function generateEnvContent(appName, secretsPath, environment = 'local', force = false) {
-  const builderPath = pathsUtil.getBuilderPath(appName);
-  const templatePath = path.join(builderPath, 'env.template');
-  const variablesPath = resolveApplicationConfigPath(builderPath);
+/**
+ * Generate .env content from template and secrets (no disk write).
+ * When options.envOnly is true, variablesPath is null (no application config).
+ *
+ * @param {string} appName - Application name
+ * @param {string} [secretsPath] - Path to secrets file (optional)
+ * @param {string} [environment='local'] - Environment context
+ * @param {boolean} [force=false] - Generate missing secret keys
+ * @param {Object} [options] - Optional: appPath, envOnly (env-only mode uses only env.template)
+ * @returns {Promise<string>} Resolved env content
+ */
+async function generateEnvContent(appName, secretsPath, environment = 'local', force = false, options = {}) {
+  const appPath = (options && options.appPath) || pathsUtil.getBuilderPath(appName);
+  const templatePath = path.join(appPath, 'env.template');
+  const variablesPath = (options && options.envOnly) ? null : resolveApplicationConfigPath(appPath);
   const template = loadEnvTemplate(templatePath);
   const secretsPaths = await getActualSecretsPath(secretsPath, appName);
   if (force) {
-    const secretsFileForGeneration = secretsPath ? resolveSecretsPath(secretsPath) : secretsPaths.userPath;
-    await generateMissingSecrets(template, secretsFileForGeneration);
+    const preferredPath = secretsPath ? resolveSecretsPath(secretsPath) : secretsPaths.userPath;
+    await secretsEnsure.ensureSecretsFromEnvTemplate(templatePath, { preferredFilePath: preferredPath });
   }
-
   const secrets = await loadSecrets(secretsPath, appName);
   let resolved = await resolveKvReferences(template, secrets, environment, secretsPaths, appName);
   resolved = await applyEnvironmentTransformations(resolved, environment, variablesPath);
@@ -371,73 +405,104 @@ function mergeEnvContentPreservingExisting(newContent, existingMap) {
 }
 
 /**
- * Generates and writes .env file. Newly resolved values (from template + secrets) win over
- * existing .env so that project secrets (e.g. from config aifabrix-secrets) take effect on
- * re-run. Extra variables only in existing .env are kept.
+ * Merges a key-value map into existing .env file content, preserving comments and blank lines.
+ * For each KEY=value line in existing content, replaces value with newMap[KEY] when the key exists
+ * in newMap. Appends any keys from newMap that did not appear in the file.
  *
+ * @function mergeEnvMapIntoContent
+ * @param {string} existingContent - Full existing .env file content
+ * @param {Object.<string, string>} newMap - New key-to-value map (e.g. from resolved or run env)
+ * @returns {string} Merged content with comments preserved
+ */
+function mergeEnvMapIntoContent(existingContent, newMap) {
+  if (!newMap || Object.keys(newMap).length === 0) {
+    return typeof existingContent === 'string' ? existingContent : '';
+  }
+  const lines = (existingContent || '').split(/\r?\n/);
+  const seen = new Set();
+  const out = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      out.push(line);
+      continue;
+    }
+    const eq = trimmed.indexOf('=');
+    if (eq > 0) {
+      const key = trimmed.substring(0, eq).trim();
+      seen.add(key);
+      out.push(Object.prototype.hasOwnProperty.call(newMap, key) ? `${key}=${newMap[key]}` : line);
+      continue;
+    }
+    out.push(line);
+  }
+  for (const key of Object.keys(newMap)) {
+    if (!seen.has(key)) out.push(`${key}=${newMap[key]}`);
+  }
+  return out.join('\n');
+}
+
+/**
+ * Resolves content to write for .env: merges with existing file when present.
+ * @param {string} resolved - Newly generated content
+ * @param {string} pathToPreserve - Path to existing .env to merge from (or null)
+ * @returns {string} Content to write
+ */
+function resolveEnvContentToWrite(resolved, pathToPreserve) {
+  if (!pathToPreserve || !fs.existsSync(pathToPreserve)) return resolved;
+  const existingContent = fs.readFileSync(pathToPreserve, 'utf8');
+  const existingMap = parseEnvContentToMap(existingContent);
+  return mergeEnvContentPreservingExisting(resolved, existingMap);
+}
+
+/**
+ * Generates and writes .env file. Newly resolved values win over existing .env; extra vars in existing .env are kept.
+ * When options.envOnly is true, only env.template is used; .env is written to options.appPath.
  * @async
  * @function generateEnvFile
  * @param {string} appName - Name of the application
  * @param {string} [secretsPath] - Path to secrets file (optional)
  * @param {string} [environment='local'] - Environment context ('local' or 'docker')
  * @param {boolean} [force=false] - Generate missing secret keys in secrets file
- * @param {boolean} [skipOutputPath=false] - Skip copying to envOutputPath
- * @param {string} [preserveFromPath=null] - Path to existing .env to preserve values from (defaults to builder .env)
+ * @param {Object} [options] - Optional: appPath, envOnly, skipOutputPath, preserveFromPath
  * @returns {Promise<string>} Path to generated .env file
- * @throws {Error} If generation fails
- *
- * @example
- * const envPath = await generateEnvFile('myapp', undefined, 'docker');
- * // When builder/myapp/.env already exists, existing values are preserved
  */
-async function generateEnvFile(appName, secretsPath, environment = 'local', force = false, skipOutputPath = false, preserveFromPath = null) {
-  const builderPath = pathsUtil.getBuilderPath(appName);
-  const variablesPath = resolveApplicationConfigPath(builderPath);
-  const envPath = path.join(builderPath, '.env');
-
-  const resolved = await generateEnvContent(appName, secretsPath, environment, force);
-
-  let toWrite = resolved;
-  const pathToPreserve = preserveFromPath || envPath;
-  if (pathToPreserve && fs.existsSync(pathToPreserve)) {
-    const existingContent = fs.readFileSync(pathToPreserve, 'utf8');
-    const existingMap = parseEnvContentToMap(existingContent);
-    toWrite = mergeEnvContentPreservingExisting(resolved, existingMap);
+async function generateEnvFile(appName, secretsPath, environment = 'local', force = false, options = {}) {
+  const opts = options && typeof options === 'object' ? options : {};
+  const appPath = opts.appPath || pathsUtil.getBuilderPath(appName);
+  const envOnly = !!opts.envOnly;
+  const variablesPath = envOnly ? null : resolveApplicationConfigPath(appPath);
+  const envPath = path.join(appPath, '.env');
+
+  if (envOnly) {
+    const templatePath = path.join(appPath, 'env.template');
+    if (!fs.existsSync(templatePath)) {
+      throw new Error(`env.template not found at ${templatePath}. Resolve requires env.template in the app directory.`);
+    }
   }
 
+  const resolved = await generateEnvContent(appName, secretsPath, environment, force, { appPath, envOnly });
+  const preservePath = opts.preserveFromPath !== undefined && opts.preserveFromPath !== null ? opts.preserveFromPath : null;
+  const pathToPreserve = preservePath !== null ? preservePath : envPath;
+  const toWrite = resolveEnvContentToWrite(resolved, pathToPreserve);
   fs.writeFileSync(envPath, toWrite, { mode: 0o600 });
 
-  // Process and copy to envOutputPath if configured (uses localPort for copied file)
-  if (!skipOutputPath) {
+  if (!opts.skipOutputPath) {
+    const { processEnvVariables } = require('../utils/env-copy');
     await processEnvVariables(envPath, variablesPath, appName, secretsPath);
   }
 
   return envPath;
 }
 
-/**
- * Generates admin secrets for infrastructure
- * Creates ~/.aifabrix/admin-secrets.env with Postgres and Redis credentials
- *
- * @async
- * @function generateAdminSecretsEnv
- * @param {string} [secretsPath] - Path to secrets file (optional)
- * @returns {Promise<string>} Path to generated admin-secrets.env file
- * @throws {Error} If generation fails
- *
- * @example
- * const adminEnvPath = await generateAdminSecretsEnv('../../secrets.local.yaml');
- * // Returns: '~/.aifabrix/admin-secrets.env'
- */
+/** Generates admin secrets for infrastructure (~/.aifabrix/admin-secrets.env). Uses admin123 when no postgres password. */
 async function generateAdminSecretsEnv(secretsPath) {
   let secrets;
 
   try {
     secrets = await loadSecrets(secretsPath);
   } catch (error) {
-    // If secrets file doesn't exist, create default secrets
     const defaultSecretsPath = secretsPath || path.join(pathsUtil.getAifabrixHome(), 'secrets.yaml');
-
     if (!fs.existsSync(defaultSecretsPath)) {
       logger.log('Creating default secrets file...');
       await createDefaultSecrets(defaultSecretsPath);
@@ -446,15 +511,14 @@ async function generateAdminSecretsEnv(secretsPath) {
       throw error;
     }
   }
-
   const aifabrixDir = pathsUtil.getAifabrixHome();
   const adminEnvPath = path.join(aifabrixDir, 'admin-secrets.env');
-
   if (!fs.existsSync(aifabrixDir)) {
     fs.mkdirSync(aifabrixDir, { recursive: true, mode: 0o700 });
   }
 
-  const postgresPassword = secrets['postgres-passwordKeyVault'] || '';
+  const raw = secrets['postgres-passwordKeyVault'];
+  const postgresPassword = (raw && String(raw).trim()) || 'admin123';
 
   const adminSecrets = `# Infrastructure Admin Credentials
 POSTGRES_PASSWORD=${postgresPassword}
@@ -477,5 +541,7 @@ module.exports = {
   generateAdminSecretsEnv,
   validateSecrets,
   createDefaultSecrets,
-  getCanonicalSecretName
+  getCanonicalSecretName,
+  parseEnvContentToMap,
+  mergeEnvMapIntoContent
 };

package/lib/datasource/field-reference-validator.js

@@ -0,0 +1,91 @@
+/**
+ * Field Reference Validator for External Datasource
+ *
+ * Validates that field names used in indexing (embedding, uniqueKey),
+ * validation.repeatingValues[].field, and quality.rejectIf[].field exist in
+ * fieldMappings.attributes. Aligns with dataplane invalid_reference semantics.
+ *
+ * @fileoverview Offline field reference validation for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Validates that all field references in indexing, validation, and quality
+ * exist in fieldMappings.attributes. When fieldMappings.attributes is missing
+ * or empty, returns no errors (skip check, matching dataplane behavior).
+ *
+ * @function validateFieldReferences
+ * @param {Object} parsed - Parsed datasource object (after JSON parse)
+ * @returns {string[]} Array of error messages; empty if no invalid references
+ *
+ * @example
+ * const errors = validateFieldReferences(parsed);
+ * if (errors.length > 0) {
+ *   errors.forEach(e => console.error(e));
+ * }
+ */
+function validateFieldReferences(parsed) {
+  const errors = [];
+  const normalizedAttributes = Object.keys(
+    parsed?.fieldMappings?.attributes ?? {}
+  );
+
+  if (normalizedAttributes.length === 0) {
+    return [];
+  }
+
+  // indexing.embedding: array of field names
+  const embedding = parsed?.indexing?.embedding;
+  if (Array.isArray(embedding)) {
+    embedding.forEach((field, i) => {
+      if (typeof field === 'string' && !normalizedAttributes.includes(field)) {
+        errors.push(
+          `indexing.embedding[${i}]: field '${field}' does not exist in fieldMappings.attributes`
+        );
+      }
+    });
+  }
+
+  // indexing.uniqueKey: single field name
+  const uniqueKey = parsed?.indexing?.uniqueKey;
+  if (typeof uniqueKey === 'string' && uniqueKey !== '') {
+    if (!normalizedAttributes.includes(uniqueKey)) {
+      errors.push(
+        `indexing.uniqueKey: field '${uniqueKey}' does not exist in fieldMappings.attributes`
+      );
+    }
+  }
+
+  // validation.repeatingValues[].field
+  const repeatingValues = parsed?.validation?.repeatingValues;
+  if (Array.isArray(repeatingValues)) {
+    repeatingValues.forEach((rule, index) => {
+      const field = rule?.field;
+      if (typeof field === 'string' && !normalizedAttributes.includes(field)) {
+        errors.push(
+          `validation.repeatingValues[${index}].field: field '${field}' does not exist in fieldMappings.attributes`
+        );
+      }
+    });
+  }
+
+  // quality.rejectIf[].field
+  const rejectIf = parsed?.quality?.rejectIf;
+  if (Array.isArray(rejectIf)) {
+    rejectIf.forEach((rule, index) => {
+      const field = rule?.field;
+      if (typeof field === 'string' && !normalizedAttributes.includes(field)) {
+        errors.push(
+          `quality.rejectIf[${index}].field: field '${field}' does not exist in fieldMappings.attributes`
+        );
+      }
+    });
+  }
+
+  return errors;
+}
+
+module.exports = {
+  validateFieldReferences
+};

package/lib/datasource/validate.js

@@ -11,6 +11,7 @@
 const fs = require('fs');
 const { loadExternalDataSourceSchema } = require('../utils/schema-loader');
 const { formatValidationErrors } = require('../utils/error-formatter');
+const { validateFieldReferences } = require('./field-reference-validator');
 
 /**
  * Validates a datasource file against external-datasource schema
@@ -48,11 +49,28 @@ async function validateDatasourceFile(filePath) {
   }
 
   const validate = loadExternalDataSourceSchema();
-  const valid = validate(parsed);
+  const schemaValid = validate(parsed);
+
+  if (!schemaValid) {
+    return {
+      valid: false,
+      errors: formatValidationErrors(validate.errors),
+      warnings: []
+    };
+  }
+
+  const fieldRefErrors = validateFieldReferences(parsed);
+  if (fieldRefErrors.length > 0) {
+    return {
+      valid: false,
+      errors: fieldRefErrors,
+      warnings: []
+    };
+  }
 
   return {
-    valid,
-    errors: valid ? [] : formatValidationErrors(validate.errors),
+    valid: true,
+    errors: [],
     warnings: []
   };
 }

package/lib/deployment/environment-config.js

@@ -0,0 +1,137 @@
+/**
+ * Environment deployment config and preset helpers.
+ * Parses/validates JSON config and builds preset-based config.
+ *
+ * @fileoverview Environment config for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Ajv = require('ajv');
+const { formatValidationErrors } = require('../utils/error-formatter');
+const environmentDeployRequestSchema = require('../schema/environment-deploy-request.schema.json');
+
+/** Allowed preset values for --preset (case-insensitive); API expects lowercase s, m, l, xl */
+const PRESET_VALUES = ['s', 'm', 'l', 'xl'];
+const DEFAULT_PRESET = 's';
+const DEFAULT_SERVICE_NAME = 'aifabrix';
+const DEFAULT_LOCATION = 'swedencentral';
+
+/**
+ * Normalizes and validates preset from CLI (s, m, l, xl; case-insensitive)
+ * @param {string} [preset] - User-provided preset
+ * @returns {string} Normalized preset (lowercase)
+ * @throws {Error} If preset is not one of s, m, l, xl
+ */
+function normalizePreset(preset) {
+  const raw = (preset === null || preset === undefined || preset === '') ? DEFAULT_PRESET : String(preset).trim().toLowerCase();
+  if (!PRESET_VALUES.includes(raw)) {
+    throw new Error(
+      `Invalid preset "${preset}". Use one of: ${PRESET_VALUES.join(', ')}.\n` +
+      'Example: aifabrix env deploy dev --preset s'
+    );
+  }
+  return raw;
+}
+
+/**
+ * Builds environmentConfig from env key and preset (no config file)
+ * @param {string} validatedEnvKey - Validated environment key
+ * @param {string} preset - Normalized preset (s, m, l, xl)
+ * @returns {Object} { environmentConfig, dryRun: false }
+ */
+function buildEnvironmentConfigFromPreset(validatedEnvKey, preset) {
+  return {
+    environmentConfig: {
+      key: validatedEnvKey,
+      environment: validatedEnvKey,
+      preset,
+      serviceName: DEFAULT_SERVICE_NAME,
+      location: DEFAULT_LOCATION
+    },
+    dryRun: false
+  };
+}
+
+/** Reads and parses config file; throws if missing, unreadable, or invalid structure. */
+function parseEnvironmentConfigFile(resolvedPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(resolvedPath, 'utf8');
+  } catch (e) {
+    throw new Error(`Cannot read config file: ${resolvedPath}. ${e.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(
+      `Invalid JSON in config file: ${resolvedPath}\n${e.message}\n` +
+      'Expected format: { "environmentConfig": { "key", "environment", "preset", "serviceName", "location" }, "dryRun": false }'
+    );
+  }
+  if (parsed === null || typeof parsed !== 'object') {
+    throw new Error(
+      `Config file must be a JSON object with "environmentConfig". File: ${resolvedPath}\n` +
+      'Example: { "environmentConfig": { "key": "dev", "environment": "dev", "preset": "s", "serviceName": "aifabrix", "location": "swedencentral" }, "dryRun": false }'
+    );
+  }
+  if (parsed.environmentConfig === undefined) {
+    throw new Error(
+      `Config file must contain "environmentConfig" (object). File: ${resolvedPath}\n` +
+      'Example: { "environmentConfig": { "key": "dev", "environment": "dev", "preset": "s", "serviceName": "aifabrix", "location": "swedencentral" } }'
+    );
+  }
+  if (typeof parsed.environmentConfig !== 'object' || parsed.environmentConfig === null) {
+    throw new Error(`"environmentConfig" must be an object. File: ${resolvedPath}`);
+  }
+  return parsed;
+}
+
+/**
+ * Validates parsed config against schema and returns deploy request.
+ * @param {Object} parsed - Parsed config object
+ * @param {string} resolvedPath - Path for error messages
+ * @returns {Object} { environmentConfig, dryRun? }
+ */
+function validateEnvironmentDeployParsed(parsed, resolvedPath) {
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  const validate = ajv.compile(environmentDeployRequestSchema);
+  if (!validate(parsed)) {
+    const messages = formatValidationErrors(validate.errors);
+    throw new Error(
+      `Environment config validation failed (${resolvedPath}):\n  • ${messages.join('\n  • ')}\n` +
+      'Fix the config file and run the command again. See templates/infra/environment-dev.json for a valid example.'
+    );
+  }
+  return {
+    environmentConfig: parsed.environmentConfig,
+    dryRun: Boolean(parsed.dryRun)
+  };
+}
+
+/**
+ * Loads and validates environment deploy config from a JSON file
+ * @param {string} configPath - Absolute or relative path to config JSON
+ * @returns {Object} Valid deploy request { environmentConfig, dryRun? }
+ * @throws {Error} If file missing, invalid JSON, or validation fails
+ */
+function loadAndValidateEnvironmentDeployConfig(configPath) {
+  const resolvedPath = path.isAbsolute(configPath) ? configPath : path.resolve(process.cwd(), configPath);
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(
+      `Environment config file not found: ${resolvedPath}\n` +
+      'Use --config <file> with a JSON file containing "environmentConfig" (e.g. templates/infra/environment-dev.json).'
+    );
+  }
+  const parsed = parseEnvironmentConfigFile(resolvedPath);
+  return validateEnvironmentDeployParsed(parsed, resolvedPath);
+}
+
+module.exports = {
+  normalizePreset,
+  buildEnvironmentConfigFromPreset,
+  loadAndValidateEnvironmentDeployConfig
+};