@aifabrix/builder 2.41.0 → 2.42.0

package/lib/schema/application-schema.json

@@ -115,11 +115,6 @@
       "minimum": 1,
       "maximum": 65535
     },
-    "deploymentKey": {
-      "type": "string",
-      "description": "SHA256 hash of deployment manifest (excluding deploymentKey field)",
-      "pattern": "^[a-f0-9]{64}$"
-    },
     "requiresDatabase": {
       "type": "boolean",
       "description": "Whether application requires database"
@@ -137,6 +132,14 @@
             "type": "string",
             "description": "Database name",
             "pattern": "^[a-z0-9_-]+$"
+          },
+          "extensions": {
+            "type": "array",
+            "description": "PostgreSQL extension names to create in this database during db-init (e.g. pgcrypto, uuid-ossp, vector, btree_gin, btree_gist). If the database name ends with 'vector', the vector extension is still added automatically if not listed.",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9_-]+$"
+            }
           }
         },
         "additionalProperties": false

package/lib/schema/external-datasource.schema.json

@@ -3,11 +3,11 @@
   "$id":"https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/external-datasource.schema.json",
   "title":"External Data Source",
   "description":"Configuration for AI Fabrix ExternalDataSource entities. Includes metadata schema, data dimensions, transformation mappings, OpenAPI/MCP exposure, execution logic, and sync behavior.",
-     "metadata":{
+        "metadata":{
         "key":"external-datasource-schema",
         "name":"External Data Source Configuration Schema",
         "description":"JSON schema for validating ExternalDataSource configuration files",
-        "version":"2.1.0",
+        "version":"2.3.0",
         "type":"schema",
         "category":"integration",
         "author":"AI Fabrix Team",
@@ -91,6 +91,22 @@
               "Added contract versioning configuration to datasource root for CI/CD safety and agent stability"
            ],
            "breaking":false
+        },
+        {
+           "version":"2.2.0",
+           "date":"2026-02-26T00:00:00Z",
+           "changes":[
+              "capabilities: preferred format is array [\"list\",\"get\",...]. Schema oneOf accepts both array and legacy object; runtime accepts both for backward compatibility."
+           ],
+           "breaking":false
+        },
+        {
+           "version":"2.3.0",
+           "date":"2026-03-08T00:00:00Z",
+           "changes":[
+              "BREAKING: Added required primaryKey (array of normalized attribute names). Used for get/update/delete and table indexing. Migration: add primaryKey array (e.g. [\"id\"] or [\"externalId\"]) to each datasource config."
+           ],
+           "breaking":true
         }
      ]
   },
@@ -101,7 +117,8 @@
      "systemKey",
      "entityType",
      "resourceType",
-     "fieldMappings"
+     "fieldMappings",
+     "primaryKey"
   ],
   "properties":{
      "key":{
@@ -147,6 +164,16 @@
         "description":"Subset of JSON Schema used to validate raw input metadata.",
         "additionalProperties":true
      },
+     "primaryKey":{
+        "type":"array",
+        "description":"Normalized field names that uniquely identify a record (used for get/update/delete and table indexing). Each element must exist in fieldMappings.dimensions or fieldMappings.attributes.",
+        "minItems":1,
+        "items":{
+           "type":"string",
+           "pattern":"^[a-zA-Z0-9_]+$"
+        },
+        "uniqueItems":true
+     },
      "fieldMappings":{
         "type":"object",
         "description":"Transformation rules and data dimensions. Maps canonical dimensions to system attributes.",
@@ -764,31 +791,27 @@
         "additionalProperties":false
      },
      "capabilities":{
-        "type":"object",
-        "description":"Declares which logical operations are supported by this datasource.",
-        "properties":{
-           "list":{
-              "type":"boolean",
-              "default":true
-           },
-           "get":{
-              "type":"boolean",
-              "default":false
-           },
-           "create":{
-              "type":"boolean",
-              "default":false
-           },
-           "update":{
-              "type":"boolean",
-              "default":false
+        "oneOf":[
+           {
+              "type":"array",
+              "description":"Preferred: list of supported operation names. Values: list, get, create, update, delete.",
+              "items":{"type":"string","enum":["list","get","create","update","delete"]},
+              "uniqueItems":true
            },
-           "delete":{
-              "type":"boolean",
-              "default":false
+           {
+              "type":"object",
+              "description":"Legacy: object with boolean flags per operation. Accepted for backward compatibility.",
+              "properties":{
+                 "list":{"type":"boolean"},
+                 "get":{"type":"boolean"},
+                 "create":{"type":"boolean"},
+                 "update":{"type":"boolean"},
+                 "delete":{"type":"boolean"}
+              },
+              "additionalProperties":false
            }
-        },
-        "additionalProperties":false
+        ],
+        "description":"Supported operations. When omitted, derived from execution.engine (CIP operations or list-only for Python)."
      },
      "execution":{
         "type":"object",

package/lib/schema/external-system.schema.json

@@ -3,18 +3,18 @@
   "$id":"https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/external-system.schema.json",
   "title":"AI Fabrix External System Configuration Schema",
   "description":"Schema for configuring an external system connected to the AI Fabrix Dataplane. This defines authentication, OpenAPI/MCP bindings, field mappings defaults, metadata handling and portal inputs.",
-  "metadata":{
+     "metadata":{
      "key":"external-system-schema",
      "name":"External System Configuration Schema",
      "description":"JSON schema for validating ExternalSystem configuration files",
-     "version":"1.3.0",
+     "version":"1.5.0",
      "type":"schema",
      "category":"integration",
      "author":"AI Fabrix Team",
      "createdAt":"2024-01-01T00:00:00Z",
-     "updatedAt":"2026-02-18T00:00:00Z",
+     "updatedAt":"2026-03-07T00:00:00Z",
      "compatibility":{
-        "minVersion":"1.3.0",
+        "minVersion":"1.4.0",
         "maxVersion":"2.0.0",
         "deprecated":false
      },
@@ -29,6 +29,20 @@
         
      ],
      "changelog":[
+        {
+           "version":"1.5.0",
+           "date":"2026-03-07T00:00:00Z",
+           "changes":[
+              "Optional rateLimit: outbound per-system rate limit (requestsPerWindow/windowSeconds or requestsPerSecond/burstSize); dataplane enforces and handles 429"
+           ]
+        },
+        {
+           "version":"1.4.0",
+           "date":"2026-03-07T00:00:00Z",
+           "changes":[
+              "Optional testEndpoint in authentication.variables for apikey: full URL or path (path resolved against baseUrl); credential test URL for E2E/credential step"
+           ]
+        },
         {
            "version":"1.3.0",
            "date":"2026-02-18T00:00:00Z",
@@ -71,6 +85,18 @@
         }
      ]
   },
+  "$defs":{
+     "authenticationVariablesByMethod":{
+        "oauth2":{"variables":[{"key":"baseUrl","required":true,"description":"API base URL"},{"key":"tokenUrl","required":true,"description":"OAuth token endpoint. Full URL (https://...) or path (e.g. /oauth/v2/token); path is resolved against baseUrl."},{"key":"authorizationUrl","required":false,"description":"OAuth authorization endpoint. Full URL or path; path is resolved against baseUrl. Required when grantType is authorization_code or omitted."},{"key":"grantType","required":false,"description":"OAuth 2.0 grant type. One of: client_credentials, authorization_code. Default: authorization_code."},{"key":"scope","required":false},{"key":"tenantId","required":false},{"key":"testEndpoint","required":false,"description":"Optional URL used when testing the credential (GET). Full URL or path (path resolved against baseUrl). If omitted, baseUrl + /health is used."}],"security":[{"key":"clientId","required":true},{"key":"clientSecret","required":true}]},
+        "aad":{"variables":[{"key":"baseUrl","required":true},{"key":"tokenUrl","required":true,"description":"Token endpoint. Full URL or path (path resolved against baseUrl)."},{"key":"authorizationUrl","required":false,"description":"Authorization endpoint. Full URL or path (path resolved against baseUrl). Required when grantType is authorization_code or omitted."},{"key":"grantType","required":false,"description":"OAuth 2.0 grant type. One of: client_credentials, authorization_code. Default: authorization_code."},{"key":"tenantId","required":false},{"key":"testEndpoint","required":false,"description":"Optional URL used when testing the credential (GET). Full URL or path (path resolved against baseUrl). If omitted, baseUrl + /health is used."}],"security":[{"key":"clientId","required":true},{"key":"clientSecret","required":true}]},
+        "apikey":{"variables":[{"key":"baseUrl","required":true},{"key":"headerName","required":false},{"key":"prefix","required":false},{"key":"testEndpoint","required":false,"description":"Optional URL used when testing the credential (GET). Full URL (https://...) or path (e.g. /crm/v3/objects/contacts?limit=1); path is resolved against baseUrl. If omitted, baseUrl + /health is used."}],"security":[{"key":"apiKey","required":true}]},
+        "basic":{"variables":[{"key":"baseUrl","required":true},{"key":"testEndpoint","required":false,"description":"Optional URL used when testing the credential (GET). Full URL or path (path resolved against baseUrl). If omitted, baseUrl + /health is used."}],"security":[{"key":"username","required":true},{"key":"password","required":true}]},
+        "queryParam":{"variables":[{"key":"baseUrl","required":true},{"key":"paramName","required":true},{"key":"testEndpoint","required":false,"description":"Optional URL used when testing the credential (GET). Full URL or path (path resolved against baseUrl). If omitted, baseUrl + /health is used."}],"security":[{"key":"paramValue","required":true}]},
+        "oidc":{"variables":[{"key":"openIdConfigUrl","required":true},{"key":"clientId","required":true},{"key":"expectedIssuer","required":false},{"key":"algorithms","required":false},{"key":"validateSignature","required":false},{"key":"clockSkewSeconds","required":false},{"key":"testEndpoint","required":false,"description":"Optional URL used when testing the credential (GET). Full URL or path. For OIDC, discovery URL is typically used if testEndpoint omitted."}],"security":[]},
+        "hmac":{"variables":[{"key":"baseUrl","required":false},{"key":"algorithm","required":false},{"key":"signatureHeader","required":false},{"key":"timestampHeader","required":false},{"key":"signaturePrefix","required":false},{"key":"testEndpoint","required":false,"description":"Optional URL used when testing the credential (GET). Full URL or path (path resolved against baseUrl when baseUrl present)."}],"security":[{"key":"signingSecret","required":true}]},
+        "none":{"variables":[],"security":[]}
+     }
+  },
   "type":"object",
   "required":[
      "key",
@@ -153,14 +179,14 @@
            },
            "variables":{
               "type":"object",
-              "description":"Non-secret config. Must include baseUrl for all methods except none. Common keys: baseUrl, tokenUrl, authorizationUrl, tenantId, audience, scope, headerName; queryParam: paramName; oidc: openIdConfigUrl, clientId, expectedIssuer; hmac: algorithm, signatureHeader, timestampHeader, signaturePrefix, timestampMaxAge.",
+              "description":"Non-secret config. See $defs.authenticationVariablesByMethod for per-method keys. oauth2/aad: baseUrl, tokenUrl, authorizationUrl (optional; required when grantType is authorization_code or omitted), grantType (optional, default authorization_code); apikey: baseUrl, headerName (optional), prefix (optional), testEndpoint (optional); basic: baseUrl; queryParam: baseUrl, paramName; oidc: openIdConfigUrl, clientId; hmac: optional; none: empty. URL-valued variables (tokenUrl, authorizationUrl, testEndpoint) accept full URL or path; paths are resolved against baseUrl by the backend.",
               "additionalProperties":{
                  "type":"string"
               }
            },
            "security":{
               "type":"object",
-              "description":"Secret-bearing keys only. Every value must be a Key Vault reference matching ^kv://.+$",
+              "description":"Secret-bearing keys only. Values must be kv:// references. See $defs.authenticationVariablesByMethod. oauth2/aad: clientId, clientSecret; apikey: apiKey; basic: username, password; queryParam: paramValue; oidc: none; hmac: signingSecret.",
               "additionalProperties":{
                  "type":"string",
                  "pattern":"^kv://.+$"
@@ -172,6 +198,17 @@
               "default":true
            }
         },
+        "examples":[
+           {"method":"oauth2","variables":{"baseUrl":"https://api.example.com","tokenUrl":"https://api.example.com/oauth/token","authorizationUrl":"https://api.example.com/oauth/authorize"},"security":{"clientId":"kv://example/clientId","clientSecret":"kv://example/clientSecret"}},
+           {"method":"oauth2","variables":{"baseUrl":"https://api.example.com","tokenUrl":"https://api.example.com/oauth/token","grantType":"client_credentials"},"security":{"clientId":"kv://example/clientId","clientSecret":"kv://example/clientSecret"}},
+           {"method":"apikey","variables":{"baseUrl":"https://api.example.com","headerName":"X-API-Key","testEndpoint":"https://api.example.com/health"},"security":{"apiKey":"kv://example/apiKey"}},
+           {"method":"apikey","variables":{"baseUrl":"https://api.example.com","headerName":"Authorization","prefix":"Bearer","testEndpoint":"/crm/v3/objects/contacts?limit=1"},"security":{"apiKey":"kv://example/apiKey"}},
+           {"method":"basic","variables":{"baseUrl":"https://api.example.com"},"security":{"username":"kv://example/username","password":"kv://example/password"}},
+           {"method":"queryParam","variables":{"baseUrl":"https://api.example.com","paramName":"api_key"},"security":{"paramValue":"kv://example/apiKey"}},
+           {"method":"oidc","variables":{"openIdConfigUrl":"https://example.com/.well-known/openid-configuration","clientId":"app-id"}},
+           {"method":"hmac","variables":{"signatureHeader":"X-Signature"},"security":{"signingSecret":"kv://example/signingSecret"}},
+           {"method":"none","variables":{}}
+        ],
         "additionalProperties":false
      },
      "openapi":{
@@ -446,6 +483,45 @@
         "type":"string",
         "description":"SHA256 hash of triggerPaths payload (64-char hex). Used to detect structural changes. Optional; Dataplane computes when absent.",
         "pattern":"^[a-f0-9]{64}$"
+     },
+     "rateLimit":{
+        "type":"object",
+        "description":"Outbound rate limit for requests from the dataplane to this external system. When set, the dataplane enforces the limit per base URL and handles HTTP 429 (wait and retry). When absent, global env defaults apply (CIP_EXECUTION_RATE_LIMIT_REQUESTS_PER_SECOND, CIP_EXECUTION_RATE_LIMIT_BURST_SIZE). Supports window-based (e.g. HubSpot 100/10s) or token-bucket style (requestsPerSecond + burstSize).",
+        "properties":{
+           "requestsPerWindow":{
+              "type":"integer",
+              "minimum":1,
+              "description":"Maximum requests allowed in the time window (window-based limit). Example: 100 for HubSpot's 100 requests per 10 seconds."
+           },
+           "windowSeconds":{
+              "type":"integer",
+              "minimum":1,
+              "description":"Time window in seconds. Used with requestsPerWindow. Example: 10 for HubSpot (100 requests per 10 seconds)."
+           },
+           "requestsPerSecond":{
+              "type":"number",
+              "minimum":0.1,
+              "description":"Sustained request rate (token-bucket style). When used with burstSize, allows short bursts up to burstSize while refilling at this rate."
+           },
+           "burstSize":{
+              "type":"integer",
+              "minimum":1,
+              "description":"Maximum burst size in tokens (token-bucket style). Used with requestsPerSecond."
+           }
+        },
+        "additionalProperties":false,
+        "oneOf":[
+           {
+              "required":["requestsPerWindow","windowSeconds"]
+           },
+           {
+              "required":["requestsPerSecond","burstSize"]
+           }
+        ],
+        "examples":[
+           {"requestsPerWindow":100,"windowSeconds":10},
+           {"requestsPerSecond":10,"burstSize":100}
+        ]
      }
   },
   "additionalProperties":false

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

@@ -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();
@@ -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/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/compose-generator.js

@@ -224,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 || [] };

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

@@ -38,6 +38,17 @@ function registerComposeHelpers() {
   });
 
   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/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
 };