@aifabrix/builder 2.39.3 → 2.40.2

package/lib/commands/up-common.js

@@ -10,24 +10,27 @@
 
 const path = require('path');
 const fs = require('fs');
-const yaml = require('js-yaml');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
 const pathsUtil = require('../utils/paths');
+const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
+const { isYamlPath } = require('../utils/config-format');
 const { copyTemplateFiles } = require('../validation/template');
 const { ensureReadmeForAppPath, ensureReadmeForApp } = require('../app/readme');
 
 /**
- * Copy template to a target path if variables.yaml is missing there.
+ * Copy template to a target path if application config is missing there.
  * After copy, generates README.md from templates/applications/README.md.hbs.
  * @param {string} appName - Application name
  * @param {string} targetAppPath - Target directory (e.g. builder/keycloak)
  * @returns {Promise<boolean>} True if template was copied, false if already present
  */
 async function ensureTemplateAtPath(appName, targetAppPath) {
-  const variablesPath = path.join(targetAppPath, 'variables.yaml');
-  if (fs.existsSync(variablesPath)) {
+  try {
+    pathsUtil.resolveApplicationConfigPath(targetAppPath);
     return false;
+  } catch {
+    // No application config; copy template
   }
   await copyTemplateFiles(appName, targetAppPath);
   await ensureReadmeForAppPath(targetAppPath, appName);
@@ -37,18 +40,55 @@ async function ensureTemplateAtPath(appName, targetAppPath) {
 /**
  * Resolve the directory (folder) that would contain the .env file for envOutputPath.
  * @param {string} envOutputPath - Value from build.envOutputPath (e.g. ../../.env)
- * @param {string} variablesPath - Path to variables.yaml
+ * @param {string} configPath - Path to application config file
  * @returns {string} Absolute path to the folder that would contain the output .env file
  */
-function getEnvOutputPathFolder(envOutputPath, variablesPath) {
-  const variablesDir = path.dirname(variablesPath);
-  const resolvedFile = path.resolve(variablesDir, envOutputPath);
+function getEnvOutputPathFolder(envOutputPath, configPath) {
+  const configDir = path.dirname(configPath);
+  const resolvedFile = path.resolve(configDir, envOutputPath);
   return path.dirname(resolvedFile);
 }
 
 /**
- * Validates envOutputPath: if the target folder does not exist, patches variables.yaml to set envOutputPath to null.
+ * Patches envOutputPath to null in raw YAML content so comments and formatting are preserved.
+ * Only touches the line that sets envOutputPath under build.
+ *
+ * @param {string} content - Raw file content (YAML)
+ * @returns {string|null} Patched content, or null if no change
+ */
+function patchEnvOutputPathInYamlContent(content) {
+  const re = /^(\s*)envOutputPath\s*:\s*.+$/m;
+  const match = content.match(re);
+  if (!match) return null;
+  const indent = match[1];
+  return content.replace(re, `${indent}envOutputPath: null`);
+}
+
+/**
+ * Patches config file to set build.envOutputPath to null, preserving comments (YAML only).
+ * For JSON or when in-place patch fails, falls back to full write.
+ *
+ * @param {string} configPath - Path to application config file
+ * @returns {boolean} True if file was modified
+ */
+function patchEnvOutputPathInFile(configPath) {
+  if (!isYamlPath(configPath)) {
+    const variables = loadConfigFile(configPath);
+    const updated = { ...variables, build: { ...(variables.build || {}), envOutputPath: null } };
+    writeConfigFile(configPath, updated);
+    return true;
+  }
+  const content = fs.readFileSync(configPath, 'utf8');
+  const patched = patchEnvOutputPathInYamlContent(content);
+  if (patched === null) return false;
+  fs.writeFileSync(configPath, patched, 'utf8');
+  return true;
+}
+
+/**
+ * Validates envOutputPath: if the target folder does not exist, patches application config to set envOutputPath to null.
  * Used by up-platform, up-miso, up-dataplane so we do not keep a path that points outside an existing tree.
+ * Patches in place for YAML to preserve comments.
  *
  * @param {string} appName - Application name (e.g. keycloak, miso-controller, dataplane)
  */
@@ -59,48 +99,44 @@ function validateEnvOutputPathFolderOrNull(appName) {
   if (path.resolve(cwdBuilderPath) !== path.resolve(pathsToPatch[0])) {
     pathsToPatch.push(cwdBuilderPath);
   }
-  const envOutputPathLine = /^(\s*envOutputPath:)\s*.*$/m;
-  const replacement = '$1 null  # deploy only, no copy';
   for (const appPath of pathsToPatch) {
-    const variablesPath = path.join(appPath, 'variables.yaml');
-    if (!fs.existsSync(variablesPath)) continue;
+    let configPath;
+    try {
+      configPath = pathsUtil.resolveApplicationConfigPath(appPath);
+    } catch {
+      continue;
+    }
     try {
-      const content = fs.readFileSync(variablesPath, 'utf8');
-      const variables = yaml.load(content);
+      const variables = loadConfigFile(configPath);
       const value = variables?.build?.envOutputPath;
       if (value === null || value === undefined || value === '') continue;
-      const folder = getEnvOutputPathFolder(String(value).trim(), variablesPath);
+      const folder = getEnvOutputPathFolder(String(value).trim(), configPath);
       if (fs.existsSync(folder)) continue;
-      const newContent = content.replace(envOutputPathLine, replacement);
-      fs.writeFileSync(variablesPath, newContent, 'utf8');
+      patchEnvOutputPathInFile(configPath);
     } catch (err) {
-      logger.warn(chalk.yellow(`Could not validate envOutputPath in ${variablesPath}: ${err.message}`));
+      logger.warn(chalk.yellow(`Could not validate envOutputPath in ${configPath}: ${err.message}`));
     }
   }
 }
 
 /**
- * Patches a single variables.yaml to set build.envOutputPath to null for deploy-only.
+ * Patches a single application config file to set build.envOutputPath to null for deploy-only.
+ * Only writes when a change is needed (value is set and target folder does not exist).
+ * Uses in-place YAML patch when possible to preserve comments.
  *
- * @param {string} variablesPath - Path to variables.yaml
- * @param {RegExp} envOutputPathLine - Regex for envOutputPath line
- * @param {string} replacement - Replacement string
+ * @param {string} configPath - Path to application config file
  */
-function patchOneVariablesFileForDeployOnly(variablesPath, envOutputPathLine, replacement) {
-  const content = fs.readFileSync(variablesPath, 'utf8');
-  if (!envOutputPathLine.test(content)) return;
-  const variables = yaml.load(content);
+function patchOneVariablesFileForDeployOnly(configPath) {
+  const variables = loadConfigFile(configPath);
   const value = variables?.build?.envOutputPath;
-  if (value !== null && value !== undefined && value !== '') {
-    const folder = getEnvOutputPathFolder(String(value).trim(), variablesPath);
-    if (fs.existsSync(folder)) return;
-  }
-  const newContent = content.replace(envOutputPathLine, replacement);
-  fs.writeFileSync(variablesPath, newContent, 'utf8');
+  if (value === null || value === undefined || value === '') return;
+  const folder = getEnvOutputPathFolder(String(value).trim(), configPath);
+  if (fs.existsSync(folder)) return;
+  patchEnvOutputPathInFile(configPath);
 }
 
 /**
- * Patches variables.yaml to set build.envOutputPath to null for deploy-only (no local code).
+ * Patches application config to set build.envOutputPath to null for deploy-only (no local code).
  * Only patches when the target folder does NOT exist; when folder exists, keeps the value.
  * Use when running up-miso/up-platform so we do not copy .env to repo paths or show that message.
  * Patches both primary builder path and cwd/builder if different.
@@ -114,22 +150,24 @@ function patchEnvOutputPathForDeployOnly(appName) {
   if (path.resolve(cwdBuilderPath) !== path.resolve(pathsToPatch[0])) {
     pathsToPatch.push(cwdBuilderPath);
   }
-  const envOutputPathLine = /^(\s*envOutputPath:)\s*.*$/m;
-  const replacement = '$1 null  # deploy only, no copy';
   for (const appPath of pathsToPatch) {
-    const variablesPath = path.join(appPath, 'variables.yaml');
-    if (!fs.existsSync(variablesPath)) continue;
+    let configPath;
+    try {
+      configPath = pathsUtil.resolveApplicationConfigPath(appPath);
+    } catch {
+      continue;
+    }
     try {
-      patchOneVariablesFileForDeployOnly(variablesPath, envOutputPathLine, replacement);
+      patchOneVariablesFileForDeployOnly(configPath);
     } catch (err) {
-      logger.warn(chalk.yellow(`Could not patch envOutputPath in ${variablesPath}: ${err.message}`));
+      logger.warn(chalk.yellow(`Could not patch envOutputPath in ${configPath}: ${err.message}`));
     }
   }
 }
 
 /**
- * Ensures builder app directory exists from template if variables.yaml is missing.
- * If builder/<appName>/variables.yaml does not exist, copies from templates/applications/<appName>.
+ * Ensures builder app directory exists from template if application config is missing.
+ * If builder/<appName>/application config does not exist, copies from templates/applications/<appName>.
  * Uses AIFABRIX_BUILDER_DIR when set (e.g. by up-miso/up-dataplane from config aifabrix-env-config).
  * When using a custom builder dir, also populates cwd/builder/<appName> so the repo's builder/ is not empty.
  *

package/lib/commands/up-dataplane.js

@@ -3,7 +3,7 @@
  *
  * Always local deployment: registers or rotates dataplane app in dev, sends
  * deployment manifest to Miso Controller, then runs the dataplane app locally
- * (same as aifabrix deploy dataplane --deployment=local). If app is already
+ * (same as aifabrix deploy dataplane --local). If app is already
  * registered, uses rotate-secret; otherwise registers.
  *
  * @fileoverview up-dataplane command implementation
@@ -11,10 +11,9 @@
  * @version 2.0.0
  */
 
-const path = require('path');
-const fs = require('fs');
-const yaml = require('js-yaml');
 const chalk = require('chalk');
+const pathsUtil = require('../utils/paths');
+const { loadConfigFile } = require('../utils/config-format');
 const logger = require('../utils/logger');
 const config = require('../core/config');
 const { checkAuthentication } = require('../utils/app-register-auth');
@@ -47,20 +46,22 @@ async function registerOrRotateDataplane(options, controllerUrl, environmentKey,
 }
 
 /**
- * Build full image ref from registry and dataplane variables (registry/name:tag)
+ * Build full image ref from registry and dataplane config (registry/name:tag)
  * @param {string} registry - Registry URL
  * @returns {string|undefined} Full image reference or undefined
  */
 function buildDataplaneImageRef(registry) {
-  const pathsUtil = require('../utils/paths');
-  const variablesPath = path.join(pathsUtil.getBuilderPath('dataplane'), 'variables.yaml');
-  if (!fs.existsSync(variablesPath)) return undefined;
-  const content = fs.readFileSync(variablesPath, 'utf8');
-  const variables = yaml.load(content);
-  const name = variables?.image?.name || variables?.app?.key || 'dataplane';
-  const tag = variables?.image?.tag || 'latest';
-  const base = (registry || '').replace(/\/+$/, '');
-  return base ? `${base}/${name}:${tag}` : undefined;
+  try {
+    const builderPath = pathsUtil.getBuilderPath('dataplane');
+    const configPath = pathsUtil.resolveApplicationConfigPath(builderPath);
+    const variables = loadConfigFile(configPath);
+    const name = variables?.image?.name || variables?.app?.key || 'dataplane';
+    const tag = variables?.image?.tag || 'latest';
+    const base = (registry || '').replace(/\/+$/, '');
+    return base ? `${base}/${name}:${tag}` : undefined;
+  } catch {
+    return undefined;
+  }
 }
 
 /**

package/lib/commands/up-miso.js

@@ -9,10 +9,9 @@
  * @version 2.0.0
  */
 
-const path = require('path');
-const fs = require('fs');
-const yaml = require('js-yaml');
 const chalk = require('chalk');
+const pathsUtil = require('../utils/paths');
+const { loadConfigFile } = require('../utils/config-format');
 const logger = require('../utils/logger');
 const config = require('../core/config');
 const secrets = require('../core/secrets');
@@ -21,7 +20,7 @@ const app = require('../app');
 const { saveLocalSecret } = require('../utils/local-secrets');
 const { ensureAppFromTemplate, patchEnvOutputPathForDeployOnly, validateEnvOutputPathFolderOrNull } = require('./up-common');
 
-/** Keycloak base port (from templates/applications/keycloak/variables.yaml) */
+/** Keycloak base port (from templates/applications/keycloak application config) */
 const KEYCLOAK_BASE_PORT = 8082;
 /** Miso controller base port (dev-config app base) */
 const MISO_BASE_PORT = 3000;
@@ -46,21 +45,23 @@ function parseImageOptions(imageOpts) {
 }
 
 /**
- * Build full image ref from registry and app variables (registry/name:tag)
+ * Build full image ref from registry and app config (registry/name:tag)
  * @param {string} appName - keycloak or miso-controller
  * @param {string} registry - Registry URL
  * @returns {string} Full image reference
  */
 function buildImageRefFromRegistry(appName, registry) {
-  const pathsUtil = require('../utils/paths');
-  const variablesPath = path.join(pathsUtil.getBuilderPath(appName), 'variables.yaml');
-  if (!fs.existsSync(variablesPath)) return undefined;
-  const content = fs.readFileSync(variablesPath, 'utf8');
-  const variables = yaml.load(content);
-  const name = variables?.image?.name || variables?.app?.key || appName;
-  const tag = variables?.image?.tag || 'latest';
-  const base = (registry || '').replace(/\/+$/, '');
-  return base ? `${base}/${name}:${tag}` : undefined;
+  try {
+    const builderPath = pathsUtil.getBuilderPath(appName);
+    const configPath = pathsUtil.resolveApplicationConfigPath(builderPath);
+    const variables = loadConfigFile(configPath);
+    const name = variables?.image?.name || variables?.app?.key || appName;
+    const tag = variables?.image?.tag || 'latest';
+    const base = (registry || '').replace(/\/+$/, '');
+    return base ? `${base}/${name}:${tag}` : undefined;
+  } catch {
+    return undefined;
+  }
 }
 
 /**

package/lib/commands/upload.js

@@ -0,0 +1,163 @@
+/**
+ * Upload external system to dataplane (upload → validate → publish).
+ *
+ * @fileoverview Upload command handler for aifabrix upload <system-key>
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { getDeploymentAuth, requireBearerForDataplanePipeline } = require('../utils/token-manager');
+const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
+const { validateExternalSystemComplete } = require('../validation/validate');
+const { displayValidationResults } = require('../validation/validate-display');
+const { generateControllerManifest } = require('../generator/external-controller-manifest');
+const {
+  uploadApplicationViaPipeline,
+  validateUploadViaPipeline,
+  publishUploadViaPipeline
+} = require('../api/pipeline.api');
+const { formatApiError } = require('../utils/api-error-handler');
+
+/**
+ * Validates system-key format (same as download).
+ * @param {string} systemKey - System key
+ * @throws {Error} If invalid
+ */
+function validateSystemKeyFormat(systemKey) {
+  if (!systemKey || typeof systemKey !== 'string') {
+    throw new Error('System key is required and must be a string');
+  }
+  if (!/^[a-z0-9-_]+$/.test(systemKey)) {
+    throw new Error('System key must contain only lowercase letters, numbers, hyphens, and underscores');
+  }
+}
+
+/**
+ * Builds pipeline upload payload from controller manifest.
+ * Payload: { version, application, dataSources }; application = system with RBAC.
+ * @param {Object} manifest - Controller manifest from generateControllerManifest
+ * @returns {Object} { version, application, dataSources }
+ */
+function buildUploadPayload(manifest) {
+  return {
+    version: manifest.version || '1.0.0',
+    application: manifest.system,
+    dataSources: manifest.dataSources || []
+  };
+}
+
+/**
+ * Resolves dataplane URL and auth (same pattern as download).
+ * @param {string} systemKey - System key
+ * @param {Object} options - Options with optional dataplane override
+ * @returns {Promise<{ dataplaneUrl: string, authConfig: Object, environment: string }>}
+ */
+async function resolveDataplaneAndAuth(systemKey, options) {
+  const { resolveEnvironment } = require('../core/config');
+  const environment = await resolveEnvironment();
+  const controllerUrl = await resolveControllerUrl();
+  const authConfig = await getDeploymentAuth(controllerUrl, environment, systemKey);
+
+  if (!authConfig.token && !authConfig.clientId) {
+    throw new Error('Authentication required. Run "aifabrix login" or "aifabrix app register <system-key>" first.');
+  }
+
+  let dataplaneUrl;
+  if (options.dataplane) {
+    dataplaneUrl = options.dataplane.replace(/\/$/, '');
+  } else {
+    logger.log(chalk.blue('Resolving dataplane URL...'));
+    dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig);
+  }
+
+  return { dataplaneUrl, authConfig, environment };
+}
+
+/**
+ * Runs upload → validate → publish on the dataplane.
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {Object} authConfig - Auth config
+ * @param {Object} payload - { version, application, dataSources }
+ * @returns {Promise<{ uploadId: string }>}
+ */
+async function runUploadValidatePublish(dataplaneUrl, authConfig, payload) {
+  const uploadRes = await uploadApplicationViaPipeline(dataplaneUrl, authConfig, payload);
+  const uploadId = uploadRes?.data?.uploadId ?? uploadRes?.data?.id ?? uploadRes?.uploadId;
+  if (!uploadId) {
+    const msg = uploadRes?.success === false
+      ? formatApiError(uploadRes, dataplaneUrl)
+      : 'Upload did not return an upload ID';
+    throw new Error(msg);
+  }
+
+  const validateRes = await validateUploadViaPipeline(dataplaneUrl, uploadId, authConfig);
+  if (validateRes?.success === false) {
+    const msg = formatApiError(validateRes, dataplaneUrl);
+    throw new Error(`Upload validation failed: ${msg}`);
+  }
+
+  await publishUploadViaPipeline(dataplaneUrl, uploadId, authConfig);
+  return { uploadId };
+}
+
+/**
+ * Throws if validation result is invalid (displays results first).
+ * @param {Object} validationResult - Result from validateExternalSystemComplete
+ * @throws {Error} If validationResult.valid is false
+ */
+function throwIfValidationFailed(validationResult) {
+  if (!validationResult.valid) {
+    displayValidationResults(validationResult);
+    throw new Error('Validation failed. Fix errors before uploading.');
+  }
+}
+
+/**
+ * Uploads external system to dataplane (upload → validate → publish). No controller deploy.
+ * @param {string} systemKey - External system key (integration/<system-key>/)
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.dryRun] - Validate and build payload only; no API calls
+ * @param {string} [options.dataplane] - Override dataplane URL
+ * @returns {Promise<void>}
+ * @throws {Error} If validation or API calls fail
+ */
+async function uploadExternalSystem(systemKey, options = {}) {
+  validateSystemKeyFormat(systemKey);
+
+  logger.log(chalk.blue(`\nUploading external system to dataplane: ${systemKey}`));
+
+  const validationResult = await validateExternalSystemComplete(systemKey, { type: 'external' });
+  throwIfValidationFailed(validationResult);
+  logger.log(chalk.green('Validation passed.'));
+
+  const manifest = await generateControllerManifest(systemKey, { type: 'external' });
+  const payload = buildUploadPayload(manifest);
+
+  if (options.dryRun) {
+    logger.log(chalk.yellow('Dry run: would upload payload (no API calls).'));
+    logger.log(chalk.gray(`  System: ${manifest.key}, version: ${payload.version}, datasources: ${payload.dataSources.length}`));
+    return;
+  }
+
+  const { dataplaneUrl, authConfig, environment } = await resolveDataplaneAndAuth(systemKey, options);
+  requireBearerForDataplanePipeline(authConfig);
+  logger.log(chalk.blue(`Dataplane: ${dataplaneUrl}`));
+
+  await runUploadValidatePublish(dataplaneUrl, authConfig, payload);
+
+  logger.log(chalk.green('\nUpload validated and published to dataplane.'));
+  logger.log(chalk.blue(`Environment: ${environment}`));
+  logger.log(chalk.blue(`System: ${systemKey}`));
+  logger.log(chalk.blue(`Dataplane: ${dataplaneUrl}`));
+}
+
+module.exports = {
+  uploadExternalSystem,
+  buildUploadPayload,
+  resolveDataplaneAndAuth,
+  runUploadValidatePublish,
+  validateSystemKeyFormat
+};

package/lib/commands/wizard-core.js

@@ -339,7 +339,7 @@ async function validateWizardConfiguration(dataplaneUrl, authConfig, systemConfi
 }
 
 /**
- * Fetches deployment docs and writes README.md when variables.yaml and deploy JSON are available.
+ * Fetches deployment docs and writes README.md when application config and deploy JSON are available.
  * @async
  * @param {string} appPath - Application path
  * @param {string} appName - Application name
@@ -348,12 +348,13 @@ async function validateWizardConfiguration(dataplaneUrl, authConfig, systemConfi
  * @param {string} systemKey - System key
  */
 async function tryUpdateReadmeFromDeploymentDocs(appPath, appName, dataplaneUrl, authConfig, systemKey) {
-  const variablesPath = path.join(appPath, 'variables.yaml');
+  const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
   const deployPath = path.join(appPath, `${appName}-deploy.json`);
   let variablesYaml = null;
   let deployJson = null;
   try {
-    variablesYaml = await fs.readFile(variablesPath, 'utf8');
+    const configPath = resolveApplicationConfigPath(appPath);
+    variablesYaml = await fs.readFile(configPath, 'utf8');
   } catch {
     // optional
   }
@@ -372,7 +373,7 @@ async function tryUpdateReadmeFromDeploymentDocs(appPath, appName, dataplaneUrl,
   if (content && typeof content === 'string') {
     const readmePath = path.join(appPath, 'README.md');
     await fs.writeFile(readmePath, content, 'utf8');
-    logger.log(chalk.gray('  Updated README.md from deployment-docs API (variables.yaml + deploy JSON).'));
+    logger.log(chalk.gray('  Updated README.md from deployment-docs API (application config + deploy JSON).'));
   }
 }
 

package/lib/core/diff.js

@@ -13,6 +13,10 @@ const fs = require('fs');
 const path = require('path');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
+const { loadConfigFile } = require('../utils/config-format');
+const { detectSchemaTypeFromParsed, loadExternalSystemSchema, loadExternalDataSourceSchema } = require('../utils/schema-loader');
+const { validateObjectAgainstApplicationSchema } = require('../validation/validator');
+const { formatValidationErrors } = require('../utils/error-formatter');
 
 /**
  * Handle added field in comparison
@@ -169,19 +173,22 @@ function identifyBreakingChanges(comparison) {
 }
 
 /**
- * Compares two configuration files
- * Loads files, parses JSON, and performs deep comparison
+ * Compares two configuration files.
+ * Both files must be the same config type (app, system, or datasource).
+ * By default validates both against their schema; pass { validate: false } to skip.
  *
  * @async
  * @function compareFiles
  * @param {string} file1 - Path to first file
  * @param {string} file2 - Path to second file
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.validate=true] - If true, validate both files against their schema
  * @returns {Promise<Object>} Comparison result with differences
- * @throws {Error} If files cannot be read or parsed
+ * @throws {Error} If files cannot be read, parsed, types differ, or validation fails
  *
  * @example
  * const result = await compareFiles('./old.json', './new.json');
- * // Returns: { identical: false, added: [...], removed: [...], changed: [...] }
+ * const resultNoValidate = await compareFiles('./a.yaml', './b.yaml', { validate: false });
  */
 /**
  * Validates file paths
@@ -206,21 +213,70 @@ function validateFilePaths(file1, file2) {
 }
 
 /**
- * Reads and parses a JSON file
+ * Reads and parses a config file (JSON or YAML by extension: .json, .yaml, .yml).
  * @function readAndParseFile
  * @param {string} filePath - File path
- * @returns {Object} Parsed JSON object
+ * @returns {Object} Parsed object
  * @throws {Error} If file cannot be read or parsed
  */
 function readAndParseFile(filePath) {
   try {
-    const content = fs.readFileSync(filePath, 'utf8');
-    return JSON.parse(content);
+    return loadConfigFile(filePath);
   } catch (error) {
     throw new Error(`Failed to parse ${filePath}: ${error.message}`);
   }
 }
 
+/**
+ * Maps schema type to user-facing label (app | system | datasource).
+ * @param {string} schemaType - 'application' | 'external-system' | 'external-datasource'
+ * @returns {string} 'app' | 'system' | 'datasource'
+ */
+function toUserFacingType(schemaType) {
+  const map = {
+    application: 'app',
+    'external-system': 'system',
+    'external-datasource': 'datasource'
+  };
+  return map[schemaType] || 'app';
+}
+
+/**
+ * Runs external schema validator and returns error messages or null.
+ * @param {Function} validateFn - AJV validate function
+ * @param {Object} parsed - Parsed config object
+ * @returns {string[]|null} Error messages or null if valid
+ */
+function getValidationErrors(validateFn, parsed) {
+  const valid = validateFn(parsed);
+  if (valid) return null;
+  return formatValidationErrors(validateFn.errors);
+}
+
+/**
+ * Validates parsed object against the schema for the given type.
+ * @param {Object} parsed - Parsed config object
+ * @param {string} schemaType - 'application' | 'external-system' | 'external-datasource'
+ * @param {string} filePath - File path (for error messages)
+ * @throws {Error} If validation fails
+ */
+function validateParsedForType(parsed, schemaType, filePath) {
+  let messages = [];
+  if (schemaType === 'application') {
+    const result = validateObjectAgainstApplicationSchema(parsed);
+    if (!result.valid) messages = result.errors;
+  } else if (schemaType === 'external-system') {
+    messages = getValidationErrors(loadExternalSystemSchema(), parsed) || [];
+  } else if (schemaType === 'external-datasource') {
+    messages = getValidationErrors(loadExternalDataSourceSchema(), parsed) || [];
+  } else {
+    throw new Error(`Unknown schema type: ${schemaType}`);
+  }
+  if (messages.length > 0) {
+    throw new Error(`Validation failed for ${filePath}: ${messages.join('; ')}`);
+  }
+}
+
 /**
  * Extracts version from parsed object
  * @function extractVersion
@@ -267,12 +323,31 @@ function buildComparisonResult(comparison, parsed1, parsed2, file1, file2) {
   };
 }
 
-async function compareFiles(file1, file2) {
+async function compareFiles(file1, file2, options = {}) {
+  const shouldValidate = options.validate !== false;
+
   validateFilePaths(file1, file2);
 
   const parsed1 = readAndParseFile(file1);
   const parsed2 = readAndParseFile(file2);
 
+  const type1 = detectSchemaTypeFromParsed(parsed1, file1);
+  const type2 = detectSchemaTypeFromParsed(parsed2, file2);
+  const userType1 = toUserFacingType(type1);
+  const userType2 = toUserFacingType(type2);
+
+  if (userType1 !== userType2) {
+    throw new Error(
+      `Type mismatch: ${file1} is ${userType1} config and ${file2} is ${userType2} config. ` +
+      'Both files must be the same type (app, system, or datasource).'
+    );
+  }
+
+  if (shouldValidate) {
+    validateParsedForType(parsed1, type1, file1);
+    validateParsedForType(parsed2, type2, file2);
+  }
+
   const comparison = compareObjects(parsed1, parsed2);
   return buildComparisonResult(comparison, parsed1, parsed2, file1, file2);
 }