@aifabrix/builder 2.40.2 → 2.42.0

package/lib/schema/wizard-config.schema.json

@@ -59,6 +59,17 @@
           "type": "string",
           "description": "Known platform identifier (for known-platform type)",
           "enum": ["hubspot", "salesforce", "zendesk", "slack", "microsoft365"]
+        },
+        "datasourceKeys": {
+          "type": "array",
+          "description": "Datasource keys to include (validated against platform; omit for all)",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1
+        },
+        "entityName": {
+          "type": "string",
+          "description": "Entity for multi-entity OpenAPI (validated against discover-entities; for openapi-file and openapi-url)",
+          "minLength": 1
         }
       },
       "allOf": [
@@ -194,6 +205,11 @@
           "type": "boolean",
           "description": "Enable Role-Based Access Control",
           "default": false
+        },
+        "debug": {
+          "type": "boolean",
+          "description": "When true, capture detailed generation steps and save to debug.log (dataplane returns debugLog)",
+          "default": false
         }
       }
     },

package/lib/utils/api.js

@@ -13,8 +13,8 @@
 const { parseErrorResponse } = require('./api-error-handler');
 const auditLogger = require('../core/audit-logger');
 
-/** Default timeout for HTTP requests (ms). Prevents hanging when the controller is unreachable. */
-const DEFAULT_REQUEST_TIMEOUT_MS = 5000;
+/** Default timeout for HTTP requests (ms). Prevents hanging when the controller is unreachable. 30s allows Azure Web App cold start to complete. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 
 /**
  * Logs API request performance metrics and errors to audit log
@@ -121,10 +121,22 @@ async function handleSuccessResponse(response, url, options, duration) {
     success: true
   });
 
+  // 204 No Content or empty body: nothing to parse (avoids "Unexpected end of JSON input")
+  if (response.status === 204) {
+    return { success: true, data: null, status: response.status };
+  }
+
   const contentType = response.headers.get('content-type');
   if (contentType && contentType.includes('application/json')) {
-    const data = await response.json();
-    return { success: true, data, status: response.status };
+    try {
+      const data = await response.json();
+      return { success: true, data, status: response.status };
+    } catch (e) {
+      if (e instanceof SyntaxError && e.message && e.message.includes('JSON')) {
+        return { success: true, data: null, status: response.status };
+      }
+      throw e;
+    }
   }
 
   const text = await response.text();
@@ -229,7 +241,7 @@ async function handleNetworkError(error, url, options, duration) {
 
 /**
  * Make an API call with proper error handling
- * Uses a 15s timeout to avoid hanging when the controller is unreachable.
+ * Uses a 30s timeout to avoid hanging when the controller is unreachable (Azure cold start can exceed 5s).
  * @param {string} url - API endpoint URL
  * @param {Object} options - Fetch options (signal, method, headers, body, etc.)
  * @returns {Promise<Object>} Response object with success flag
@@ -286,12 +298,28 @@ function extractControllerUrl(url) {
 }
 
 /**
- * Make an authenticated API call with bearer token
- * Automatically refreshes device token on 401 errors if refresh token is available
+ * Set auth header on headers object: Bearer for user token, x-client-token for application token.
+ * @param {Object} headers - Headers object to mutate
+ * @param {string} token - Token value
+ * @param {string} authType - 'bearer' or 'client-token'
+ */
+function setAuthHeader(headers, token, authType) {
+  if (!token) return;
+  if (authType === 'client-token') {
+    headers['x-client-token'] = token;
+  } else {
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+}
+
+/**
+ * Make an authenticated API call with user token (Bearer) or application token (x-client-token).
+ * Automatically refreshes device token on 401 when user Bearer was used.
  * @param {string} url - API endpoint URL
  * @param {Object} options - Fetch options
- * @param {string|Object} tokenOrAuthConfig - Bearer token string or authConfig object
- * @param {string} [tokenOrAuthConfig.token] - Bearer token (if object)
+ * @param {string|Object} tokenOrAuthConfig - User token string (Bearer), or authConfig object with type 'bearer'|'client-token'
+ * @param {string} [tokenOrAuthConfig.type] - 'bearer' (user token) or 'client-token' (application token)
+ * @param {string} [tokenOrAuthConfig.token] - Token (if object)
  * @param {string} [tokenOrAuthConfig.controller] - Controller URL for token refresh (if object)
  * @returns {Promise<Object>} Response object
  */
@@ -299,22 +327,22 @@ function extractControllerUrl(url) {
 async function authenticatedApiCall(url, options = {}, tokenOrAuthConfig) {
   const isStringToken = typeof tokenOrAuthConfig === 'string';
   const token = isStringToken ? tokenOrAuthConfig : tokenOrAuthConfig?.token;
+  const authType = isStringToken ? 'bearer' : tokenOrAuthConfig?.type;
   const authControllerUrl = isStringToken ? null : tokenOrAuthConfig?.controller;
   const isFormData = typeof FormData !== 'undefined' && options.body instanceof FormData;
   const headers = { ...options.headers };
   if (!isFormData && !headers['Content-Type']) {
     headers['Content-Type'] = 'application/json';
   }
-  if (token) {
-    headers['Authorization'] = `Bearer ${token}`;
-  }
+  setAuthHeader(headers, token, authType);
 
   const response = await makeApiCall(url, {
     ...options,
     headers
   });
 
-  if (!response.success && response.status === 401) {
+  // Only attempt device token refresh on 401 when user Bearer token was used (not for client-token)
+  if (!response.success && response.status === 401 && authType !== 'client-token') {
     try {
       const { forceRefreshDeviceToken } = require('./token-manager');
       const refreshedToken = await forceRefreshDeviceToken(authControllerUrl || extractControllerUrl(url));

package/lib/utils/app-register-auth.js

@@ -257,7 +257,22 @@ async function attemptGetAuthenticationToken(normalizedControllerUrl, config, at
   return { token, finalControllerUrl, lastError };
 }
 
-async function checkAuthentication(controllerUrl, _environment) {
+/**
+ * When auth fails and throwOnFailure is true, throws an error with controllerUrl so caller can run login and retry.
+ * @param {string|null} controllerUrl - Controller URL to attach to the thrown error
+ * @param {Error|null} lastError - Last error from token attempt
+ * @param {string[]} attemptedUrls - URLs that were tried
+ * @throws {Error} Error with .controllerUrl and .authFailure set
+ */
+function throwAuthFailureError(controllerUrl, lastError, attemptedUrls) {
+  const message = lastError ? lastError.message : 'No valid authentication found';
+  const err = new Error(message);
+  err.controllerUrl = controllerUrl || (attemptedUrls && attemptedUrls[0]) || null;
+  err.authFailure = true;
+  throw err;
+}
+
+async function checkAuthentication(controllerUrl, _environment, options = {}) {
   try {
     const config = await getConfig();
     const normalizedControllerUrl = normalizeControllerUrlIfProvided(controllerUrl);
@@ -269,8 +284,12 @@ async function checkAuthentication(controllerUrl, _environment) {
       attemptedUrls
     );
 
-    // If no token found, display error with attempted URLs
-    validateAuthenticationResult(token, finalControllerUrl, lastError, controllerUrl, attemptedUrls);
+    if (!token || !finalControllerUrl) {
+      if (options.throwOnFailure) {
+        throwAuthFailureError(controllerUrl || finalControllerUrl, lastError, attemptedUrls);
+      }
+      validateAuthenticationResult(token, finalControllerUrl, lastError, controllerUrl, attemptedUrls);
+    }
 
     return {
       apiUrl: finalControllerUrl,
@@ -278,6 +297,9 @@ async function checkAuthentication(controllerUrl, _environment) {
       controllerUrl: finalControllerUrl
     };
   } catch (error) {
+    if (error.authFailure) {
+      throw error;
+    }
     displayAuthenticationError(error, { controllerUrl: controllerUrl });
   }
 }

package/lib/utils/auth-headers.js

@@ -25,11 +25,12 @@ function createBearerTokenHeaders(token) {
 }
 
 /**
- * Creates authentication headers for Client Credentials flow (legacy support)
+ * Creates authentication headers for the token-issuing endpoint only (e.g. POST /api/v1/auth/token).
+ * Do not use for Controller or Dataplane app endpoints—those require Bearer token (use createBearerTokenHeaders).
  *
  * @param {string} clientId - Application client ID
  * @param {string} clientSecret - Application client secret
- * @returns {Object} Headers object with authentication
+ * @returns {Object} Headers object with x-client-id and x-client-secret
  * @throws {Error} If credentials are missing
  */
 function createClientCredentialsHeaders(clientId, clientSecret) {
@@ -43,14 +44,14 @@ function createClientCredentialsHeaders(clientId, clientSecret) {
 }
 
 /**
- * Creates authentication headers based on auth configuration
- * Supports both Bearer token and client credentials authentication
+ * Creates authentication headers based on auth configuration.
+ * For app endpoints use type 'bearer' only. Use 'client-credentials' only when calling the token-issuing endpoint (e.g. /api/v1/auth/token).
  *
  * @param {Object} authConfig - Authentication configuration
- * @param {string} authConfig.type - Auth type: 'bearer' or 'client-credentials'
+ * @param {string} authConfig.type - Auth type: 'bearer' (for app endpoints) or 'client-credentials' (token endpoint only)
  * @param {string} [authConfig.token] - Bearer token (for type 'bearer')
- * @param {string} [authConfig.clientId] - Client ID (for type 'client-credentials')
- * @param {string} [authConfig.clientSecret] - Client secret (for type 'client-credentials')
+ * @param {string} [authConfig.clientId] - Client ID (for type 'client-credentials', token endpoint only)
+ * @param {string} [authConfig.clientSecret] - Client secret (for type 'client-credentials', token endpoint only)
  * @returns {Object} Headers object with authentication
  * @throws {Error} If auth config is invalid
  */

package/lib/utils/cli-utils.js

@@ -106,6 +106,10 @@ function isDockerPermissionDeniedError(errorMsg) {
  */
 function formatDockerError(errorMsg) {
   if (isDockerImageNotFoundError(errorMsg)) {
+    // Preserve custom hint for template apps (keycloak, miso-controller) from up-miso/up-dataplane
+    if (errorMsg.includes('use --image') || errorMsg.includes('Pull the image')) {
+      return errorMsg.split('\n').map(line => (line.trim() ? `   ${line.trim()}` : ''));
+    }
     return [
       '   Docker image not found.',
       '   Run: aifabrix build <app> first'
@@ -326,6 +330,21 @@ function logOfflinePathWhenType(appPath, options) {
   logger.log(chalk.gray(`Using: ${displayPath}`));
 }
 
+/**
+ * Returns true if the error is likely due to authentication failure (e.g. 401, token expired, login required).
+ * Used to show "Run: aifabrix login" for commands that require Controller auth (e.g. up-dataplane).
+ * @param {Error} error - The error that occurred
+ * @returns {boolean} True if the error appears to be auth-related
+ */
+function isAuthenticationError(error) {
+  if (!error) return false;
+  if (error.authFailure === true) return true;
+  const msg = (error.message || '').toLowerCase();
+  const formatted = (typeof error.formatted === 'string' ? error.formatted : '').toLowerCase();
+  const combined = `${msg} ${formatted}`;
+  return /401|unauthorized|authentication|token expired|login required|aifabrix login|no authentication|device token|refresh token/.test(combined);
+}
+
 /**
  * Handles command errors with user-friendly messages
  * @param {Error} error - The error that occurred
@@ -375,6 +394,7 @@ async function appendWizardError(appKey, error) {
 module.exports = {
   validateCommand,
   handleCommandError,
+  isAuthenticationError,
   appendWizardError,
   logOfflinePathWhenType
 };

package/lib/utils/compose-generator.js

@@ -18,58 +18,12 @@ const buildCopy = require('./build-copy');
 const { formatMissingDbPasswordError } = require('./error-formatter');
 const { getContainerPort } = require('./port-resolver');
 const { parseImageOverride } = require('./parse-image-ref');
+const { registerComposeHelpers } = require('./compose-handlebars-helpers');
+const { isVectorDatabaseName } = require('./compose-vector-helper');
+const paths = require('./paths');
+const { getInfraDirName } = require('../infrastructure/helpers');
 
-// Register commonly used helpers
-handlebars.registerHelper('eq', (a, b) => a === b);
-
-// Register Handlebars helper for quoting PostgreSQL identifiers
-// PostgreSQL requires identifiers with hyphens or special characters to be quoted
-handlebars.registerHelper('pgQuote', (identifier) => {
-  if (!identifier) {
-    return '';
-  }
-  // Always quote identifiers to handle hyphens and special characters
-  // Return SafeString to prevent HTML escaping
-  return new handlebars.SafeString(`"${String(identifier).replace(/"/g, '""')}"`);
-});
-
-// Helper to generate quoted PostgreSQL user name from database name
-// User names must use underscores (not hyphens) for PostgreSQL compatibility
-handlebars.registerHelper('pgUser', (dbName) => {
-  if (!dbName) {
-    return '';
-  }
-  // Replace hyphens with underscores in user name (database names can have hyphens, but user names should not)
-  const userName = `${String(dbName).replace(/-/g, '_')}_user`;
-  // Return SafeString to prevent HTML escaping
-  return new handlebars.SafeString(`"${userName.replace(/"/g, '""')}"`);
-});
-
-// Helper to generate old user name format (for migration - drops old users with hyphens)
-// This is used to drop legacy users that were created with hyphens before the fix
-// Returns unquoted name (quotes should be added in template where needed)
-handlebars.registerHelper('pgUserOld', (dbName) => {
-  if (!dbName) {
-    return '';
-  }
-  // Old format: database name + _user (preserving hyphens)
-  const userName = `${String(dbName)}_user`;
-  // Return unquoted name - template will add quotes where needed
-  return new handlebars.SafeString(userName);
-});
-
-// Helper to generate unquoted PostgreSQL user name (for SQL WHERE clauses)
-// Returns the user name without quotes for use in SQL queries
-handlebars.registerHelper('pgUserName', (dbName) => {
-  if (!dbName) {
-    return '';
-  }
-  // Replace hyphens with underscores in user name
-  const userName = `${String(dbName).replace(/-/g, '_')}_user`;
-  // Return unquoted name for SQL queries
-  return new handlebars.SafeString(userName);
-});
-
+registerComposeHelpers();
 /**
  * Loads and compiles Docker Compose template
  * @param {string} language - Language type
@@ -95,7 +49,6 @@ function loadDockerComposeTemplate(language) {
   const templateContent = fsSync.readFileSync(templatePath, 'utf8');
   return handlebars.compile(templateContent);
 }
-
 /**
  * Extracts image name from configuration (same logic as build.js)
  * @param {Object} config - Application configuration
@@ -112,7 +65,6 @@ function getImageName(config, appName) {
   }
   return appName;
 }
-
 /**
  * Builds app configuration section
  * @param {string} appName - Application name
@@ -125,7 +77,6 @@ function buildAppConfig(appName, config) {
     name: config.displayName || appName
   };
 }
-
 /**
  * Builds image configuration section
  * @param {Object} config - Application configuration
@@ -255,9 +206,6 @@ function buildServiceConfig(appName, config, port, devId, imageOverride) {
     port: containerPortValue, // Container port (for health check and template)
     containerPort: containerPortValue, // Container port (always set, equals containerPort if exists, else port)
     hostPort: hostPort, // Host port (options.port if provided, else config.port)
-    build: {
-      localPort: config.build?.localPort || null // Only used for .env file PORT variable, not for Docker Compose
-    },
     healthCheck: buildHealthCheckConfig(config),
     traefik: buildTraefikConfig(config, devId),
     ...buildRequiresConfig(config)
@@ -276,7 +224,7 @@ function buildVolumesConfig(appName) {
 /**
  * Builds networks configuration for template data
  * @param {Object} config - Application configuration
- * @returns {Object} Networks configuration
+ * @returns {Object} Networks configuration with databases array
  */
 function buildNetworksConfig(config) {
   return { databases: config.requires?.databases || config.databases || [] };
@@ -445,6 +393,52 @@ async function readDatabasePasswordsIfNeeded(requiresDatabase, databases, envFil
   return { map: {}, array: [] };
 }
 
+/**
+ * Resolves image override from options (--image, --tag, or null).
+ * @param {Object} options - Run options
+ * @param {Object} appConfig - Application configuration
+ * @param {string} appName - Application name
+ * @returns {string|null} Full image reference or null
+ */
+function resolveImageOverride(options, appConfig, appName) {
+  if (options.image) return options.image;
+  if (options.imageOverride) return options.imageOverride;
+  if (options.tag) return `${getImageName(appConfig, appName)}:${options.tag}`;
+  return null;
+}
+
+/**
+ * Resolves Miso environment from options (tst, pro, or dev).
+ * @param {Object} options - Run options
+ * @returns {string} 'dev' | 'tst' | 'pro'
+ */
+function resolveMisoEnvironment(options) {
+  const env = (options.env && typeof options.env === 'string') ? options.env.toLowerCase() : 'dev';
+  return (env === 'tst' || env === 'pro') ? env : 'dev';
+}
+
+/**
+ * Resolves dev mount path from options.
+ * @param {Object} options - Run options
+ * @returns {string|null} Trimmed path or null
+ */
+function resolveDevMountPath(options) {
+  return (options.devMountPath && typeof options.devMountPath === 'string') ? options.devMountPath.trim() : null;
+}
+
+/**
+ * Resolves env file path from options or default dev dir (forward slashes).
+ * @param {Object} options - Run options
+ * @param {string} devDir - Default dev directory
+ * @returns {string} Absolute env file path
+ */
+function resolveEnvFilePath(options, devDir) {
+  const envFilePath = (options.envFilePath && typeof options.envFilePath === 'string')
+    ? path.resolve(options.envFilePath)
+    : path.join(devDir, '.env');
+  return envFilePath.replace(/\\/g, '/');
+}
+
 /**
  * Generates Docker Compose configuration from template
  * @async
@@ -458,8 +452,7 @@ async function generateDockerCompose(appName, appConfig, options) {
   const language = appConfig.build?.language || appConfig.language || 'typescript';
   const template = loadDockerComposeTemplate(language);
   const port = options.port || appConfig.port || 3000;
-  const imageOverride = options.image || options.imageOverride ||
-    (options.tag ? `${getImageName(appConfig, appName)}:${options.tag}` : null);
+  const imageOverride = resolveImageOverride(options, appConfig, appName);
   const { devId, idNum } = await getDeveloperIdAndNumeric();
   const { networkName, containerName } = buildNetworkAndContainerNames(appName, devId, idNum);
   const serviceConfig = buildServiceConfig(appName, appConfig, port, devId, imageOverride);
@@ -467,33 +460,41 @@ async function generateDockerCompose(appName, appConfig, options) {
   const networksConfig = buildNetworksConfig(appConfig);
 
   const devDir = buildCopy.getDevDirectory(appName, devId);
-  const envFilePath = path.join(devDir, '.env');
-  const envFileAbsolutePath = envFilePath.replace(/\\/g, '/');
+  const envFileAbsolutePath = resolveEnvFilePath(options, devDir);
+  const dbInitEnvFileAbsolutePath = (options.dbInitEnvFilePath && typeof options.dbInitEnvFilePath === 'string')
+    ? path.resolve(options.dbInitEnvFilePath).replace(/\\/g, '/')
+    : null;
 
   const databasePasswords = await readDatabasePasswordsIfNeeded(
     serviceConfig.requiresDatabase || false,
     networksConfig.databases || [],
-    envFilePath,
+    envFileAbsolutePath,
     appName
   );
-
-  const templateData = {
+  const devMountPath = resolveDevMountPath(options);
+  const reloadStartRaw = appConfig.build?.reloadStart;
+  const reloadStartCommand =
+    devMountPath && typeof reloadStartRaw === 'string' && reloadStartRaw.trim().length > 0
+      ? reloadStartRaw.trim()
+      : null;
+
+  const infraPgpassPath = path.join(paths.getAifabrixHome(), getInfraDirName(devId), 'pgpass');
+  const useInfraPgpass = serviceConfig.requiresDatabase && fsSync.existsSync(infraPgpassPath);
+  return template({
     ...serviceConfig,
     ...volumesConfig,
     ...networksConfig,
     envFile: envFileAbsolutePath,
+    dbInitEnvFile: dbInitEnvFileAbsolutePath,
     databasePasswords,
     devId: idNum,
     networkName,
-    containerName
-  };
-  return template(templateData);
+    containerName,
+    misoEnvironment: resolveMisoEnvironment(options),
+    devMountPath,
+    reloadStartCommand,
+    infraPgpassPath: useInfraPgpass ? infraPgpassPath : null,
+    useInfraPgpass: !!useInfraPgpass
+  });
 }
-
-module.exports = {
-  generateDockerCompose,
-  getImageName,
-  derivePathFromPattern,
-  buildTraefikConfig,
-  buildDevUsername
-};
+module.exports = { generateDockerCompose, getImageName, derivePathFromPattern, buildTraefikConfig, buildDevUsername, isVectorDatabaseName };

package/lib/utils/compose-handlebars-helpers.js

@@ -0,0 +1,54 @@
+/**
+ * Handlebars helpers for Docker Compose templates.
+ * @fileoverview Compose template helpers (pgQuote, pgUser, isVectorDatabase, etc.)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const handlebars = require('handlebars');
+const { isVectorDatabaseName } = require('./compose-vector-helper');
+
+/**
+ * Registers Handlebars helpers used by Docker Compose templates.
+ */
+function registerComposeHelpers() {
+  handlebars.registerHelper('eq', (a, b) => a === b);
+
+  handlebars.registerHelper('pgQuote', (identifier) => {
+    if (!identifier) return '';
+    return new handlebars.SafeString(`"${String(identifier).replace(/"/g, '""')}"`);
+  });
+
+  handlebars.registerHelper('pgUser', (dbName) => {
+    if (!dbName) return '';
+    const userName = `${String(dbName).replace(/-/g, '_')}_user`;
+    return new handlebars.SafeString(`"${userName.replace(/"/g, '""')}"`);
+  });
+
+  handlebars.registerHelper('pgUserOld', (dbName) => {
+    if (!dbName) return '';
+    const userName = `${String(dbName)}_user`;
+    return new handlebars.SafeString(userName);
+  });
+
+  handlebars.registerHelper('pgUserName', (dbName) => {
+    if (!dbName) return '';
+    const userName = `${String(dbName).replace(/-/g, '_')}_user`;
+    return new handlebars.SafeString(userName);
+  });
+
+  handlebars.registerHelper('isVectorDatabase', (name) => isVectorDatabaseName(name));
+
+  /** Returns list of extension names for this database (config extensions + vector if name ends with "vector"). */
+  handlebars.registerHelper('extensionsForDb', (db) => {
+    if (!db) return [];
+    const explicit = Array.isArray(db.extensions) ? db.extensions : [];
+    const list = [...explicit];
+    if (isVectorDatabaseName(db.name) && !list.includes('vector')) {
+      list.push('vector');
+    }
+    return list;
+  });
+}
+
+module.exports = { registerComposeHelpers };

package/lib/utils/compose-vector-helper.js

@@ -0,0 +1,18 @@
+/**
+ * Vector database name predicate for Docker Compose generation.
+ * Used so db-init can run CREATE EXTENSION vector on vector-store databases.
+ * @fileoverview Vector database name helper for compose-generator
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Returns true when the database name ends with "vector" (case-insensitive).
+ * @param {string} name - Database name
+ * @returns {boolean}
+ */
+function isVectorDatabaseName(name) {
+  return name !== null && name !== undefined && String(name).toLowerCase().endsWith('vector');
+}
+
+module.exports = { isVectorDatabaseName };

package/lib/utils/config-format-preference.js

@@ -0,0 +1,51 @@
+/**
+ * Config format preference utilities (json/yaml)
+ *
+ * @fileoverview Format preference get/set for config
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Validate and normalize format (json or yaml)
+ * @param {*} format - Format value
+ * @returns {string} Normalized format ('json' or 'yaml')
+ * @throws {Error} If format is invalid
+ */
+function validateAndNormalizeFormat(format) {
+  if (!format || typeof format !== 'string') {
+    throw new Error('Option --format must be \'json\' or \'yaml\'');
+  }
+  const normalized = format.trim().toLowerCase();
+  if (normalized !== 'json' && normalized !== 'yaml') {
+    throw new Error('Option --format must be \'json\' or \'yaml\'');
+  }
+  return normalized;
+}
+
+/**
+ * Create format preference functions
+ * @param {Function} getConfigFn - Async function to get config
+ * @param {Function} saveConfigFn - Async function to save config
+ * @returns {{ getFormat: Function, setFormat: Function, validateAndNormalizeFormat: Function }}
+ */
+function createFormatFunctions(getConfigFn, saveConfigFn) {
+  return {
+    async getFormat() {
+      const config = await getConfigFn();
+      const raw = config.format;
+      if (!raw || typeof raw !== 'string') return null;
+      const normalized = raw.trim().toLowerCase();
+      return normalized === 'json' || normalized === 'yaml' ? normalized : null;
+    },
+    async setFormat(format) {
+      const normalized = validateAndNormalizeFormat(format);
+      const config = await getConfigFn();
+      config.format = normalized;
+      await saveConfigFn(config);
+    },
+    validateAndNormalizeFormat
+  };
+}
+
+module.exports = { createFormatFunctions, validateAndNormalizeFormat };

package/lib/utils/config-format.js

@@ -14,6 +14,7 @@
 const fs = require('fs');
 const path = require('path');
 const yaml = require('js-yaml');
+const YAML = require('yaml');
 
 const YAML_EXTENSIONS = ['.yaml', '.yml'];
 const JSON_EXTENSIONS = ['.json'];
@@ -144,11 +145,46 @@ function writeConfigFile(filePath, object, format) {
   fs.writeFileSync(filePath, content, 'utf8');
 }
 
+/**
+ * Writes application config YAML by updating only repaired keys in the original content,
+ * so comments and formatting on other keys are preserved. Use for repair flows that
+ * only change externalIntegration and/or app.key.
+ *
+ * @param {string} filePath - Absolute path to the YAML file
+ * @param {string} originalContent - Original file content (with comments)
+ * @param {Object} repairedVariables - Repaired config object; only externalIntegration and app are written
+ * @throws {Error} If parsing or write fails
+ */
+function writeYamlPreservingComments(filePath, originalContent, repairedVariables) {
+  if (!filePath || typeof filePath !== 'string') {
+    throw new Error('writeYamlPreservingComments requires a non-empty file path');
+  }
+  if (typeof originalContent !== 'string') {
+    throw new Error('writeYamlPreservingComments requires original content string');
+  }
+  const doc = YAML.parseDocument(originalContent);
+  if (doc.errors && doc.errors.length > 0) {
+    const first = doc.errors[0];
+    throw new Error(`Invalid YAML: ${first.message}`);
+  }
+  if (!doc.contents) {
+    doc.contents = doc.createNode({});
+  }
+  if (repairedVariables.externalIntegration !== undefined) {
+    doc.set('externalIntegration', doc.createNode(repairedVariables.externalIntegration));
+  }
+  if (repairedVariables.app !== undefined) {
+    doc.set('app', doc.createNode(repairedVariables.app));
+  }
+  fs.writeFileSync(filePath, String(doc), 'utf8');
+}
+
 module.exports = {
   yamlToJson,
   jsonToYaml,
   loadConfigFile,
   writeConfigFile,
+  writeYamlPreservingComments,
   isYamlPath,
   isJsonPath
 };