@aifabrix/builder 2.39.2 → 2.40.0

package/lib/validation/validate.js

@@ -10,12 +10,14 @@
  */
 
 const fs = require('fs');
-const path = require('path');
+const yaml = require('js-yaml');
 const validator = require('./validator');
 const { resolveExternalFiles } = require('../utils/schema-resolver');
 const { loadExternalSystemSchema, loadExternalDataSourceSchema, detectSchemaType } = require('../utils/schema-loader');
 const { formatValidationErrors } = require('../utils/error-formatter');
 const { detectAppType } = require('../utils/paths');
+const { logOfflinePathWhenType } = require('../utils/cli-utils');
+const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { displayValidationResults } = require('./validate-display');
 const { generateControllerManifest } = require('../generator/external-controller-manifest');
 const { validateControllerManifest } = require('./external-manifest-validator');
@@ -43,8 +45,8 @@ async function validateFilePath(filePath) {
  * @param {string} appName - Application name
  * @returns {Promise<Array>} Array of validation results
  */
-async function validateExternalFilesForApp(appName) {
-  const files = await resolveExternalFiles(appName);
+async function validateExternalFilesForApp(appName, options = {}) {
+  const files = await resolveExternalFiles(appName, options);
   const validations = [];
 
   for (const file of files) {
@@ -105,21 +107,23 @@ function aggregateValidationResults(appValidation, externalValidations, rbacVali
  * @returns {Promise<Object>} Validation result
  */
 /**
- * Parses JSON file content
+ * Parses external system/datasource file content (JSON or YAML).
  * @function parseJsonFileContent
- * @param {string} filePath - File path
+ * @param {string} filePath - File path (.json, .yaml, or .yml)
  * @returns {Object} Parse result with parsed object or error
  */
 function parseJsonFileContent(filePath) {
   const content = fs.readFileSync(filePath, 'utf8');
+  const isYaml = /\.(yaml|yml)$/i.test(filePath);
   try {
-    return { parsed: JSON.parse(content), error: null };
+    const parsed = isYaml ? yaml.load(content) : JSON.parse(content);
+    return { parsed: parsed || {}, error: null };
   } catch (error) {
     return {
       parsed: null,
       error: {
         valid: false,
-        errors: [`Invalid JSON syntax: ${error.message}`],
+        errors: [isYaml ? `Invalid YAML syntax: ${error.message}` : `Invalid JSON syntax: ${error.message}`],
         warnings: []
       }
     };
@@ -206,7 +210,7 @@ async function validateExternalFile(filePath, type) {
  * @function validateAppOrFile
  * @param {string} appOrFile - Application name or file path
  * @param {Object} [options] - Validation options
- * @param {string} [options.type] - Forced application type (external)
+ *
  * @returns {Promise<Object>} Validation result with aggregated results
  * @throws {Error} If validation fails
  *
@@ -239,9 +243,9 @@ async function validateRbacForExternalSystem(isExternal, appName) {
 }
 
 /**
- * Loads and checks variables.yaml for externalIntegration
+ * Loads and checks application config for externalIntegration
  * @function loadVariablesAndCheckExternalIntegration
- * @param {string} variablesPath - Path to variables.yaml
+ * @param {string} variablesPath - Path to application config
  * @param {Object} appValidation - Application validation result
  * @returns {Object|null} Variables object or null if no externalIntegration
  */
@@ -265,7 +269,7 @@ function loadVariablesAndCheckExternalIntegration(variablesPath, appValidation)
       valid: appValidation.valid,
       application: appValidation,
       externalFiles: [],
-      warnings: [`Could not parse variables.yaml to check externalIntegration: ${error.message}`]
+      warnings: [`Could not parse application config to check externalIntegration: ${error.message}`]
     };
   }
 
@@ -287,9 +291,9 @@ function loadVariablesAndCheckExternalIntegration(variablesPath, appValidation)
  * @param {string} appName - Application name
  * @returns {Promise<Object>} Application validation result
  */
-async function validateApplicationStep(appName) {
+async function validateApplicationStep(appName, options = {}) {
   try {
-    const appValidation = await validator.validateApplication(appName);
+    const appValidation = await validator.validateApplication(appName, options);
     return {
       valid: appValidation.valid,
       errors: appValidation.errors || [],
@@ -311,9 +315,9 @@ async function validateApplicationStep(appName) {
  * @param {string} appName - Application name
  * @returns {Promise<Object>} Components validation result
  */
-async function validateComponentsStep(appName) {
+async function validateComponentsStep(appName, options = {}) {
   try {
-    const externalValidations = await validateExternalFilesForApp(appName);
+    const externalValidations = await validateExternalFilesForApp(appName, options);
     const componentErrors = [];
     const componentWarnings = [];
     const componentFiles = [];
@@ -357,9 +361,9 @@ async function validateComponentsStep(appName) {
  * @param {string} appName - Application name
  * @returns {Promise<Object>} Manifest validation result
  */
-async function validateManifestStep(appName) {
+async function validateManifestStep(appName, options = {}) {
   try {
-    const manifest = await generateControllerManifest(appName);
+    const manifest = await generateControllerManifest(appName, options);
     const manifestValidation = await validateControllerManifest(manifest);
     return {
       valid: manifestValidation.valid,
@@ -389,7 +393,7 @@ async function validateManifestStep(appName) {
  * const result = await validateExternalSystemComplete('my-hubspot');
  * // Returns: { valid: true, errors: [], warnings: [], steps: {...} }
  */
-async function validateExternalSystemComplete(appName) {
+async function validateExternalSystemComplete(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
@@ -400,11 +404,13 @@ async function validateExternalSystemComplete(appName) {
     manifest: { valid: false, errors: [], warnings: [] }
   };
 
+  const externalOptions = { ...options };
+
   // Step 1: Validate Application Config
-  steps.application = await validateApplicationStep(appName);
+  steps.application = await validateApplicationStep(appName, externalOptions);
 
   // Step 2: Validate Individual Components
-  steps.components = await validateComponentsStep(appName);
+  steps.components = await validateComponentsStep(appName, externalOptions);
 
   // If components have errors, return early (don't validate manifest)
   if (!steps.components.valid) {
@@ -417,7 +423,7 @@ async function validateExternalSystemComplete(appName) {
   }
 
   // Step 3 & 4: Generate and Validate Full Manifest (only if Step 2 passes)
-  steps.manifest = await validateManifestStep(appName);
+  steps.manifest = await validateManifestStep(appName, externalOptions);
 
   // Aggregate Results
   const allErrors = [...steps.application.errors, ...steps.components.errors, ...steps.manifest.errors];
@@ -442,23 +448,23 @@ async function validateAppOrFile(appOrFile, options = {}) {
   }
 
   const appName = appOrFile;
-  const { appPath, isExternal } = await detectAppType(appName, options);
+  const { appPath, isExternal } = await detectAppType(appName);
+  logOfflinePathWhenType(appPath);
 
-  // For external systems with --type external flag, use new unified validation
-  if (isExternal && options.type === 'external') {
+  if (isExternal) {
     return await validateExternalSystemComplete(appName);
   }
 
-  const appValidation = await validator.validateApplication(appName);
+  const appValidation = await validator.validateApplication(appName, options);
   const rbacValidation = await validateRbacForExternalSystem(isExternal, appName);
 
-  const variablesPath = path.join(appPath, 'variables.yaml');
+  const variablesPath = resolveApplicationConfigPath(appPath);
   const earlyReturn = loadVariablesAndCheckExternalIntegration(variablesPath, appValidation);
   if (earlyReturn) {
     return earlyReturn;
   }
 
-  const externalValidations = await validateExternalFilesForApp(appName);
+  const externalValidations = await validateExternalFilesForApp(appName, options);
   return aggregateValidationResults(appValidation, externalValidations, rbacValidation);
 }
 

package/lib/validation/validator.js

@@ -2,7 +2,7 @@
  * AI Fabrix Builder Schema Validation
  *
  * This module provides schema validation with developer-friendly error messages.
- * Validates variables.yaml, rbac.yaml, and env.template files.
+ * Validates application.yaml, rbac.yaml, and env.template files.
  *
  * @fileoverview Schema validation with friendly error messages for AI Fabrix Builder
  * @author AI Fabrix Team
@@ -19,10 +19,11 @@ const externalDataSourceSchema = require('../schema/external-datasource.schema.j
 const { transformVariablesForValidation } = require('../utils/variable-transformer');
 const { checkEnvironment } = require('../utils/environment-checker');
 const { formatValidationErrors } = require('../utils/error-formatter');
-const { detectAppType } = require('../utils/paths');
+const { detectAppType, resolveApplicationConfigPath } = require('../utils/paths');
+const { loadConfigFile } = require('../utils/config-format');
 
 /**
- * Validates variables.yaml file against application schema
+ * Validates application config file against application schema
  * Provides detailed error messages for configuration issues
  *
  * @async
@@ -36,27 +37,17 @@ const { detectAppType } = require('../utils/paths');
  * // Returns: { valid: true, errors: [], warnings: [] }
  */
 /**
- * Loads and parses variables.yaml
+ * Loads and parses application config (application.yaml or application.json) via resolver + converter.
  * @async
  * @function loadVariablesYaml
  * @param {string} appName - Application name
  * @returns {Promise<Object>} Variables object
  * @throws {Error} If file not found or invalid
  */
-async function loadVariablesYaml(appName) {
-  const { appPath } = await detectAppType(appName);
-  const variablesPath = path.join(appPath, 'variables.yaml');
-
-  if (!fs.existsSync(variablesPath)) {
-    throw new Error(`variables.yaml not found: ${variablesPath}`);
-  }
-
-  const content = fs.readFileSync(variablesPath, 'utf8');
-  try {
-    return yaml.load(content);
-  } catch (error) {
-    throw new Error(`Invalid YAML syntax in variables.yaml: ${error.message}`);
-  }
+async function loadVariablesYaml(appName, options = {}) {
+  const { appPath } = await detectAppType(appName, options);
+  const configPath = resolveApplicationConfigPath(appPath);
+  return loadConfigFile(configPath);
 }
 
 /**
@@ -119,12 +110,12 @@ function validateFrontDoorRouting(variables, errors) {
   }
 }
 
-async function validateVariables(appName) {
+async function validateVariables(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
 
-  const variables = await loadVariablesYaml(appName);
+  const variables = await loadVariablesYaml(appName, options);
   const transformed = transformVariablesForValidation(variables, appName);
   const validate = setupAjvValidator();
   const valid = validate(transformed);
@@ -203,16 +194,18 @@ function validatePermissions(permissions) {
   return errors;
 }
 
-async function validateRbac(appName) {
+async function validateRbac(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
 
   // Support both builder/ and integration/ directories using detectAppType
-  const { appPath } = await detectAppType(appName);
-  const rbacPath = path.join(appPath, 'rbac.yaml');
+  const { appPath } = await detectAppType(appName, options);
+  const rbacYaml = path.join(appPath, 'rbac.yaml');
+  const rbacYml = path.join(appPath, 'rbac.yml');
+  const rbacPath = fs.existsSync(rbacYaml) ? rbacYaml : (fs.existsSync(rbacYml) ? rbacYml : null);
 
-  if (!fs.existsSync(rbacPath)) {
+  if (!rbacPath) {
     return { valid: true, errors: [], warnings: ['rbac.yaml not found - authentication disabled'] };
   }
 
@@ -251,13 +244,13 @@ async function validateRbac(appName) {
  * const result = await validateEnvTemplate('myapp');
  * // Returns: { valid: true, errors: [], warnings: [] }
  */
-async function validateEnvTemplate(appName) {
+async function validateEnvTemplate(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
 
   // Support both builder/ and integration/ directories using detectAppType
-  const { appPath } = await detectAppType(appName);
+  const { appPath } = await detectAppType(appName, options);
   const templatePath = path.join(appPath, 'env.template');
 
   if (!fs.existsSync(templatePath)) {
@@ -305,6 +298,32 @@ async function validateEnvTemplate(appName) {
   };
 }
 
+/**
+ * Validates a single object against the application schema (no app-name resolution).
+ * Supports both flat root (key, displayName, ...) and nested shape (app: {...}).
+ * Used by diff and other callers that have already parsed the config.
+ *
+ * @function validateObjectAgainstApplicationSchema
+ * @param {Object} obj - Parsed config object (root or { app, deployment })
+ * @returns {{ valid: boolean, errors: string[] }} Validation result
+ *
+ * @example
+ * const result = validateObjectAgainstApplicationSchema(parsed);
+ * if (!result.valid) throw new Error(result.errors.join('; '));
+ */
+function validateObjectAgainstApplicationSchema(obj) {
+  if (!obj || typeof obj !== 'object') {
+    return { valid: false, errors: ['Config must be an object'] };
+  }
+  const toValidate = obj.app && typeof obj.app === 'object' && !obj.key ? obj.app : obj;
+  const validate = setupAjvValidator();
+  const valid = validate(toValidate);
+  return {
+    valid: !!valid,
+    errors: valid ? [] : formatValidationErrors(validate.errors)
+  };
+}
+
 /**
  * Validates deployment JSON against application schema
  * Ensures generated <app-name>-deploy.json matches the schema structure
@@ -360,14 +379,14 @@ function validateDeploymentJson(deployment) {
  * const result = await validateApplication('myapp');
  * // Returns: { valid: true, variables: {...}, rbac: {...}, env: {...} }
  */
-async function validateApplication(appName) {
+async function validateApplication(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
 
-  const variables = await validateVariables(appName);
-  const rbac = await validateRbac(appName);
-  const env = await validateEnvTemplate(appName);
+  const variables = await validateVariables(appName, options);
+  const rbac = await validateRbac(appName, options);
+  const env = await validateEnvTemplate(appName, options);
 
   const valid = variables.valid && rbac.valid && env.valid;
   const errors = [...(variables.errors || []), ...(rbac.errors || []), ...(env.errors || [])];
@@ -392,6 +411,7 @@ module.exports = {
   validateRbac,
   validateEnvTemplate,
   validateDeploymentJson,
+  validateObjectAgainstApplicationSchema,
   checkEnvironment,
   formatValidationErrors,
   validateApplication

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.39.2",
+  "version": "2.40.0",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {
@@ -78,6 +78,7 @@
     "ora": "^5.4.1"
   },
   "devDependencies": {
+    "@babel/preset-env": "^7.29.0",
     "@bcoe/v8-coverage": "^1.0.2",
     "@types/node": "^20.10.0",
     "cross-env": "^10.1.0",

package/templates/README.md

@@ -106,7 +106,7 @@ Create your own step templates in `templates/github/steps/{your-step}.hbs` and r
 
 ### Language and Infrastructure Templates
 
-These templates are processed automatically by the AI Fabrix Builder SDK based on the application schema defined in `variables.yaml`. The generated files will be valid Docker files after template processing.
+These templates are processed automatically by the AI Fabrix Builder SDK based on the application schema defined in `application.yaml`. The generated files will be valid Docker files after template processing.
 
 ## VS Code Configuration
 

package/templates/applications/README.md.hbs

@@ -61,7 +61,7 @@ aifabrix build {{appName}} --tag v1.0.0
 aifabrix push {{appName}} --registry {{registry}} --tag "v1.0.0,latest"
 
 # Deploy (controller and environment from config; set via aifabrix login or aifabrix auth config)
-aifabrix deploy {{appName}} --deployment local
+aifabrix deploy {{appName}} --local
 ```
 
 ---
@@ -132,7 +132,7 @@ aifabrix push {{appName}} --registry {{registry}} --tag "v1.0.0,latest,stable"
 ### Deploy Options
 
 ```bash
-aifabrix deploy {{appName}} --deployment local    # Uses controller and environment from config
+aifabrix deploy {{appName}} --local    # Uses controller and environment from config
 aifabrix deploy {{appName}} --no-poll             # Deploy without polling for status
 ```
 
@@ -166,7 +166,7 @@ Controller URL and environment (for `deploy`, `app register`, etc.) are set via
 
 - **"Docker not running"** → Start Docker Desktop
 - **"Not logged in"** → Run `aifabrix login` first
-- **"Port already in use"** → Use `aifabrix run {{appName}} --port <port>` or set `build.localPort` in `variables.yaml` (default: {{localPort}})
+- **"Port already in use"** → Use `aifabrix run {{appName}} --port <port>` or set `build.localPort` in `application.yaml` (default: {{localPort}})
 - **"Authentication failed"** → Run `aifabrix login` again
 - **"Build fails"** → Check Docker is running and `aifabrix-secrets` in `config.yaml` is configured correctly
 - **"Can't connect"** → Verify infrastructure is running{{#if hasDatabase}} and PostgreSQL is accessible{{/if}}

package/templates/applications/miso-controller/env.template

@@ -105,7 +105,9 @@ REDIS_PERMISSIONS_TTL=900
 # (KeycloakConfiguration + Application url/internalUrl). Sync env->DB at startup via
 # sync-application-urls-from-env.service.
 #
-# NOTE: Do NOT onboard Azure Entra SSO in Keycloak during onboarding (skipAzureEntraSso=true).
+# Azure Entra SSO during onboarding: true = skip (default), false = onboard Azure Entra SSO client in Keycloak
+# (onboarding Azure SSO requires Entra admin consent and Azure app credentials).
+KEYCLOAK_SKIP_AZURE_ENTRA_SSO=false
 
 KEYCLOAK_REALM=aifabrix
 KEYCLOAK_SERVER_URL=kv://keycloak-server-urlKeyVault

package/templates/external-system/README.md.hbs

@@ -10,8 +10,8 @@
 
 ## Files
 
-- `variables.yaml` – Application configuration with `app` and `externalIntegration` blocks
-- `{{systemKey}}-system.json` – External system definition (authentication, OpenAPI/MCP, RBAC)
+- `application.yaml` – Application configuration with `app` and `externalIntegration` blocks
+- `{{systemKey}}-system.yaml` – External system definition (authentication, OpenAPI/MCP, RBAC)
 {{#each datasources}}
 - `{{fileName}}` – Datasource: {{displayName}}
 {{/each}}
@@ -38,8 +38,8 @@ aifabrix wizard --app {{appName}}
 
 Edit files in `integration/{{appName}}/`:
 
-- **Authentication**: `{{systemKey}}-system.json` (auth type, credentials placeholders)
-- **Field mappings**: `{{systemKey}}-datasource-*.json` (dimensions, attributes, operations)
+- **Authentication**: `{{systemKey}}-system.yaml` (auth type, credentials placeholders)
+- **Field mappings**: `{{systemKey}}-datasource-*.yaml` (dimensions, attributes, operations)
 
 ### 3. Validate Configuration
 

package/integration/hubspot/variables.yaml

@@ -1,17 +0,0 @@
-app:
-  key: hubspot
-  displayName: "HubSpot CRM Integration"
-  description: "HubSpot CRM external system integration with companies, contacts, and deals"
-  type: external
-
-externalIntegration:
-  schemaBasePath: ./
-  systems:
-    - hubspot-system.json
-  dataSources:
-    - hubspot-datasource-company.json
-    - hubspot-datasource-contact.json
-    - hubspot-datasource-deal.json
-  autopublish: true
-  version: 1.0.0
-