@aifabrix/builder 2.44.4 → 2.44.6

package/lib/commands/parameters-validate.js

@@ -1,11 +1,15 @@
-const { formatBlockingError, formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const {
+  formatBlockingError,
+  formatIssue,
+  formatSuccessLine,
+  sectionTitle
+} = require('../utils/cli-test-layout-chalk');
 /**
  * @fileoverview CLI handler: parameters validate (kv:// vs infra.parameter.yaml)
  * @author AI Fabrix Team
  * @version 2.0.0
  */
 
-const chalk = require('chalk');
 const logger = require('../utils/logger');
 const pathsUtil = require('../utils/paths');
 const {
@@ -17,37 +21,98 @@ const {
   validateCatalogRequiredGenerators
 } = require('../parameters/infra-parameter-validate');
 
+function _loadCatalog(catalogPath) {
+  try {
+    const catalog = catalogPath
+      ? loadInfraParameterCatalog(catalogPath)
+      : getInfraParameterCatalog();
+    return { catalog, catalogPath: catalogPath || 'lib/schema/infra.parameter.yaml' };
+  } catch (e) {
+    logger.log(formatBlockingError(`Could not load infra parameter catalog: ${e.message}`));
+    return null;
+  }
+}
+
+function _printScanSummary(kv) {
+  logger.log(sectionTitle('Scan summary:'));
+  logger.log(
+    `  Apps scanned: ${kv.summary.scannedApps.length} (builder/* only; integration/* is skipped)`
+  );
+  logger.log(`  env.template files: ${kv.summary.scannedEnvTemplates.length}`);
+  logger.log(`  kv:// keys (unique): ${kv.summary.kvKeysCount}`);
+}
+
+function _printCatalogHint(catalogPath) {
+  logger.log(
+    formatIssue(
+      `Catalog: ${catalogPath}`,
+      'Use --catalog to validate against a different infra.parameter.yaml.'
+    )
+  );
+}
+
+function _printKvErrors(kv) {
+  logger.log(sectionTitle('Missing catalog entries:'));
+  kv.errors.forEach((err) => {
+    if (err.key === '__read_error__') {
+      logger.log(
+        formatIssue(
+          `Could not read ${err.envTemplatePath}`,
+          err.message || 'Check file permissions and retry.'
+        )
+      );
+      return;
+    }
+    logger.log(
+      formatIssue(
+        `Unknown kv:// key "${err.key}" in ${err.envTemplatePath}`,
+        'Add a matching entry (or keyPattern) in lib/schema/infra.parameter.yaml.'
+      )
+    );
+  });
+}
+
+function _printSuccess(kv, catalogPath, verbose) {
+  logger.log(formatSuccessLine('parameters validate: catalog OK; workspace kv:// keys covered.'));
+  logger.log(`  Catalog: ${catalogPath}`);
+  _printScanSummary(kv);
+  if (verbose) {
+    logger.log(sectionTitle('Files scanned:'));
+    kv.summary.scannedEnvTemplates.forEach((p) => logger.log(`  - ${p}`));
+  }
+}
+
 /**
  * Run catalog + workspace kv:// validation.
  * @param {Object} [options] - CLI options
  * @returns {Promise<{ valid: boolean }>}
  */
 async function handleParametersValidate(options = {}) {
-  let catalog;
-  try {
-    catalog = options.catalogPath
-      ? loadInfraParameterCatalog(options.catalogPath)
-      : getInfraParameterCatalog();
-  } catch (e) {
-    logger.log(formatBlockingError(`Could not load infra parameter catalog: ${e.message}`));
+  const loaded = _loadCatalog(options.catalogPath);
+  if (!loaded) {
     return { valid: false };
   }
+  const { catalog, catalogPath } = loaded;
 
   const reqGen = validateCatalogRequiredGenerators(catalog.data);
   if (!reqGen.valid) {
     logger.log(formatBlockingError('Catalog requiredForLocal / generator issues:'));
-    reqGen.errors.forEach((err) => logger.log(chalk.yellow(`  • ${err}`)));
+    reqGen.errors.forEach((err) =>
+      logger.log(formatIssue(err, 'Fix infra.parameter.yaml generator for requiredForLocal entry.'))
+    );
     return { valid: false };
   }
 
   const kv = validateWorkspaceKvRefsAgainstCatalog(catalog, pathsUtil);
   if (!kv.valid) {
-    logger.log(formatBlockingError('env.template kv:// keys not covered by infra.parameter.yaml:'));
-    kv.errors.forEach((err) => logger.log(chalk.yellow(`  • ${err}`)));
+    logger.log(formatBlockingError('Missing infra.parameter.yaml coverage for kv:// keys.'));
+    _printCatalogHint(catalogPath);
+    _printScanSummary(kv);
+    _printKvErrors(kv);
     return { valid: false };
   }
 
-  logger.log(formatSuccessLine('parameters validate: catalog OK; workspace kv:// keys covered.'));
+  _printSuccess(kv, catalogPath, Boolean(options.verbose));
   return { valid: true };
 }
 

package/lib/commands/repair-datasource-auto-rbac.js

@@ -0,0 +1,166 @@
+/**
+ * Auto-RBAC operation key normalization for datasource OpenAPI sections.
+ *
+ * @fileoverview Normalize operation keys for RBAC safety and consistency
+ * @author AI Fabrix Team
+ * @version 2.2.0
+ */
+
+'use strict';
+
+function safeString(v) {
+  return typeof v === 'string' && v.trim() ? v.trim() : '';
+}
+
+function toCamelCaseKey(opKey) {
+  const s = safeString(opKey);
+  if (!s) return '';
+  // Split on common separators, keep only alphanumerics
+  const parts = s
+    .split(/[^a-zA-Z0-9]+/g)
+    .map((p) => p.trim())
+    .filter(Boolean);
+  if (parts.length === 0) return '';
+  const first = parts[0].charAt(0).toLowerCase() + parts[0].slice(1);
+  const rest = parts
+    .slice(1)
+    .map((p) => (p.charAt(0).toUpperCase() + p.slice(1)));
+  const out = [first, ...rest].join('');
+  // Must match ^[a-z][a-zA-Z0-9]*$
+  return /^[a-z][a-zA-Z0-9]*$/.test(out) ? out : '';
+}
+
+function buildRenameMap(operationMap) {
+  if (!operationMap || typeof operationMap !== 'object' || Array.isArray(operationMap)) return {};
+  const renameMap = {};
+  for (const k of Object.keys(operationMap)) {
+    // If it's already schema-valid but contains capitals, normalize to lowercase to align
+    // with RBAC permission name restrictions (external-system schema forbids A-Z).
+    if (/^[a-z][a-zA-Z0-9]*$/.test(k)) {
+      if (/[A-Z]/.test(k)) {
+        renameMap[k] = k.toLowerCase();
+      }
+      continue;
+    }
+    const camel = toCamelCaseKey(k);
+    if (!camel || camel === k) continue;
+    // Use lowercase key to keep RBAC permission names schema-valid.
+    renameMap[k] = camel.toLowerCase();
+  }
+  return renameMap;
+}
+
+function toKebabAliasKey(opKey) {
+  const s = safeString(opKey);
+  if (!s) return '';
+  const withHyphens = s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+  const cleaned = withHyphens.replace(/[^a-z0-9-]+/g, '-');
+  return cleaned.replace(/-+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+function buildAliasMapFromCanonicalOps(canonicalOps) {
+  if (!canonicalOps || typeof canonicalOps !== 'object' || Array.isArray(canonicalOps)) return {};
+  const aliasMap = {};
+  for (const k of Object.keys(canonicalOps)) {
+    // If canonical is createBasic, allow alias create-basic to map back to createBasic
+    const alias = toKebabAliasKey(k);
+    if (!alias || alias === k) continue;
+    if (aliasMap[alias]) continue;
+    aliasMap[alias] = k;
+  }
+  return aliasMap;
+}
+
+function renameKeysInObject(obj, renameMap) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return false;
+  let updated = false;
+  for (const [oldKey, newKey] of Object.entries(renameMap)) {
+    if (!oldKey || !newKey || oldKey === newKey) continue;
+    if (obj[oldKey] === undefined) continue;
+    if (obj[newKey] !== undefined) continue; // avoid collisions
+    obj[newKey] = obj[oldKey];
+    delete obj[oldKey];
+    updated = true;
+  }
+  return updated;
+}
+
+function mergeAndDeleteAliasKeys(obj, renameMap) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return false;
+  let updated = false;
+  for (const [oldKey, newKey] of Object.entries(renameMap)) {
+    if (!oldKey || !newKey || oldKey === newKey) continue;
+    if (obj[oldKey] === undefined) continue;
+    if (obj[newKey] === undefined) continue;
+
+    const oldVal = obj[oldKey];
+    const newVal = obj[newKey];
+    if (Array.isArray(oldVal) && Array.isArray(newVal)) {
+      const merged = [...new Set([...newVal, ...oldVal])];
+      obj[newKey] = merged;
+    }
+    delete obj[oldKey];
+    updated = true;
+  }
+  return updated;
+}
+
+function renameScenarioOperations(parsed, renameMap) {
+  const scenarios = parsed?.testPayload?.scenarios;
+  if (!Array.isArray(scenarios)) return false;
+  let updated = false;
+  for (const sc of scenarios) {
+    const op = safeString(sc?.operation);
+    if (!op) continue;
+    const newOp = renameMap[op];
+    if (!newOp) continue;
+    sc.operation = newOp;
+    updated = true;
+  }
+  return updated;
+}
+
+/**
+ * When OpenAPI autoRbac is enabled, ensure operation keys are schema-valid and consistent across:
+ * - openapi.operations
+ * - execution.cip.operations
+ * - testPayload.scenarios[].operation
+ */
+function normalizeAutoRbacOperationKeys(parsed, changes) {
+  const openapi = parsed?.openapi;
+  if (!openapi || typeof openapi !== 'object') return false;
+  if (openapi.autoRbac !== true) return false;
+
+  const renameMap = {
+    ...buildRenameMap(openapi.operations),
+    ...buildAliasMapFromCanonicalOps(openapi.operations)
+  };
+  const keysToRename = Object.keys(renameMap);
+  if (keysToRename.length === 0) return false;
+
+  const cipOps = parsed?.execution?.cip?.operations;
+  let updated = false;
+  updated = renameKeysInObject(openapi.operations, renameMap) || updated;
+  updated = renameKeysInObject(cipOps, renameMap) || updated;
+  updated = renameScenarioOperations(parsed, renameMap) || updated;
+
+  const wsAllowed = parsed?.fieldMappings?.writeSurface?.allowed;
+  updated = renameKeysInObject(wsAllowed, renameMap) || updated;
+  // If both alias + canonical exist, merge and drop alias (schema requires canonical camelCase keys).
+  updated = mergeAndDeleteAliasKeys(wsAllowed, renameMap) || updated;
+
+  if (updated && Array.isArray(changes)) {
+    const pairs = keysToRename.map((k) => `${k}→${renameMap[k]}`).join(', ');
+    changes.push(
+      `Normalized autoRbac operation keys (permission names are lowercase per schema; kebab aliases fold into canonical keys): ${pairs}`
+    );
+  }
+
+  return updated;
+}
+
+module.exports = {
+  normalizeAutoRbacOperationKeys,
+  toCamelCaseKey
+};
+

package/lib/commands/repair-datasource-keys.js

@@ -15,6 +15,7 @@
 const path = require('path');
 const fs = require('fs');
 const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
+const { backupIntegrationFile } = require('../utils/integration-file-backup');
 
 /**
  * Returns suffix from a canonical-format filename: <systemKey>-datasource-<suffix>.<ext>.
@@ -112,13 +113,12 @@ function isFilenameAlreadyCanonical(fileName, systemKey) {
  * @param {string} appPath - Application directory path
  * @param {string[]} datasourceFiles - Current list of datasource filenames
  * @param {string} systemKey - System key
- * @param {Object} variables - Application variables (mutated: externalIntegration.dataSources updated)
- * @param {boolean} dryRun - If true, do not write or rename
- * @param {string[]} changes - Array to append change descriptions to
+ * @param {{ variables: Object, dryRun: boolean, changes: string[], backupCtx?: Object }} writeOpts
  * @returns {{ updated: boolean, datasourceFiles: string[] }} Updated flag and new list of datasource filenames
  */
 /* eslint-disable max-lines-per-function, max-statements, complexity -- Normalization loops and branching per file */
-function normalizeDatasourceKeysAndFilenames(appPath, datasourceFiles, systemKey, variables, dryRun, changes) {
+function normalizeDatasourceKeysAndFilenames(appPath, datasourceFiles, systemKey, writeOpts) {
+  const { variables, dryRun, changes, backupCtx } = writeOpts;
   if (!datasourceFiles || datasourceFiles.length === 0) {
     return { updated: false, datasourceFiles: datasourceFiles || [] };
   }
@@ -174,7 +174,11 @@ function normalizeDatasourceKeysAndFilenames(appPath, datasourceFiles, systemKey
 
     if (parsed.key !== canonicalKey) {
       parsed.key = canonicalKey;
-      if (!dryRun) writeConfigFile(path.join(appPath, fileName), parsed);
+      if (!dryRun) {
+        const fullPath = path.join(appPath, fileName);
+        backupIntegrationFile(fullPath, backupCtx);
+        writeConfigFile(fullPath, parsed);
+      }
       changes.push(`${fileName}: key → ${canonicalKey}`);
       updated = true;
     }
@@ -182,6 +186,7 @@ function normalizeDatasourceKeysAndFilenames(appPath, datasourceFiles, systemKey
       const oldPath = path.join(appPath, fileName);
       const newPath = path.join(appPath, canonicalFileName);
       if (!dryRun && fs.existsSync(oldPath) && !fs.existsSync(newPath)) {
+        backupIntegrationFile(oldPath, backupCtx);
         fs.renameSync(oldPath, newPath);
       }
       changes.push(`Renamed ${fileName} → ${canonicalFileName}`);

package/lib/commands/repair-datasource.js

@@ -10,6 +10,7 @@
 'use strict';
 
 const { repairOpenapiSection } = require('./repair-datasource-openapi');
+const { normalizeAutoRbacOperationKeys } = require('./repair-datasource-auto-rbac');
 
 const DEFAULT_SYNC = {
   mode: 'pull',
@@ -442,13 +443,8 @@ function repairDatasourceFile(parsed, options = {}, changes = []) {
   let updated = false;
   const none = isNoneEntityType(parsed?.entityType);
 
-  if (!none) {
-    updated = repairDimensionBindingShape(parsed, out) || updated;
-    updated = repairRootDimensionsFromAttributes(parsed, out) || updated;
-    updated = repairMetadataSchemaFromAttributes(parsed, out) || updated;
-  }
-
-  updated = repairOpenapiSection(parsed, out) || updated;
+  updated = applyBaseDatasourceRepairs(parsed, none, out) || updated;
+  updated = applyOpenapiDatasourceRepairs(parsed, out) || updated;
 
   if (options.expose) {
     updated = repairExposeFromAttributes(parsed, out) || updated;
@@ -467,6 +463,22 @@ function repairDatasourceFile(parsed, options = {}, changes = []) {
   return { updated, changes: out };
 }
 
+function applyBaseDatasourceRepairs(parsed, none, changes) {
+  if (none) return false;
+  let updated = false;
+  updated = repairDimensionBindingShape(parsed, changes) || updated;
+  updated = repairRootDimensionsFromAttributes(parsed, changes) || updated;
+  updated = repairMetadataSchemaFromAttributes(parsed, changes) || updated;
+  return updated;
+}
+
+function applyOpenapiDatasourceRepairs(parsed, changes) {
+  let updated = false;
+  updated = repairOpenapiSection(parsed, changes) || updated;
+  updated = normalizeAutoRbacOperationKeys(parsed, changes) || updated;
+  return updated;
+}
+
 module.exports = {
   getAttributeKeys,
   parsePathsFromExpressions,

package/lib/commands/repair-env-template.js

@@ -9,6 +9,7 @@
 
 const path = require('path');
 const fs = require('fs');
+const { backupIntegrationFile } = require('../utils/integration-file-backup');
 const { systemKeyToKvPrefix, kvEnvKeyToPath, securityKeyToVar } = require('../utils/credential-secrets-env');
 const { extractEnvTemplate } = require('../generator/split');
 const { generateExternalEnvTemplateContent } = require('../utils/external-env-template');
@@ -235,9 +236,10 @@ function mergeEnvTemplateContent(content, expectedByKey) {
  * @param {string} systemKey - System key
  * @param {boolean} dryRun - If true, do not write
  * @param {string[]} changes - Array to append change descriptions to
+ * @param {Object} [backupCtx] - Optional backup context for backupIntegrationFile
  * @returns {boolean} True if env.template was repaired or created
  */
-function repairEnvTemplate(appPath, systemParsed, systemKey, dryRun, changes) {
+function repairEnvTemplate(appPath, systemParsed, systemKey, dryRun, changes, backupCtx) {
   const effective = buildEffectiveConfiguration(systemParsed, systemKey);
   const expectedByKey = buildExpectedByKey(effective);
   const envPath = path.join(appPath, 'env.template');
@@ -253,6 +255,7 @@ function repairEnvTemplate(appPath, systemParsed, systemKey, dryRun, changes) {
   const { output, changed } = mergeEnvTemplateContent(content, expectedByKey);
 
   if (changed && !dryRun) {
+    backupIntegrationFile(envPath, backupCtx);
     fs.writeFileSync(envPath, output, { mode: 0o644, encoding: 'utf8' });
   }
   if (changed) {

package/lib/commands/repair-openapi-sync.js

@@ -0,0 +1,172 @@
+/**
+ * Upload OpenAPI specs (integration/<systemKey>/openapi/*.json) to dataplane so MCP generation
+ * can resolve `openapi.documentKey` and store mcpContract per datasource.
+ *
+ * This is a *repair* action: upload should remain non-mutating.
+ *
+ * @fileoverview Repair action: sync OpenAPI files for MCP
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { getDeploymentAuth, requireBearerForDataplanePipeline } = require('../utils/token-manager');
+const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
+const { uploadFileAs } = require('../utils/file-upload');
+const { listOpenAPIFiles } = require('../api/external-systems.api');
+
+async function fileExistsAsync(filePath) {
+  try {
+    await fs.promises.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveDataplaneAndAuth(systemKey) {
+  const { resolveEnvironment } = require('../core/config');
+  const environment = await resolveEnvironment();
+  const controllerUrl = await resolveControllerUrl();
+  const authConfig = await getDeploymentAuth(controllerUrl, environment, systemKey);
+  requireBearerForDataplanePipeline(authConfig);
+  const dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig, { silent: true });
+  return { dataplaneUrl, authConfig };
+}
+
+function documentKeyToLocalOpenApiPath(appPath, systemKey, documentKey) {
+  const openapiDir = path.join(appPath, 'openapi');
+  const suffix = documentKey.startsWith(systemKey + '-') ? documentKey.slice(systemKey.length + 1) : documentKey;
+  return path.join(openapiDir, `${suffix}.json`);
+}
+
+async function uploadOneOpenApiFile(dataplaneUrl, authConfig, systemKey, localPath, documentKey) {
+  const url =
+    `${dataplaneUrl.replace(/\/$/, '')}` +
+    `/api/v1/specs/upload?systemIdOrKey=${encodeURIComponent(systemKey)}`;
+  const res = await uploadFileAs(url, localPath, `${documentKey}.json`, 'file', authConfig);
+  if (!res || res.success !== true) {
+    const msg = res && typeof res.formattedError === 'string'
+      ? res.formattedError
+      : (res && typeof res.error === 'string' ? res.error : 'OpenAPI upload failed');
+    throw new Error(msg);
+  }
+}
+
+/**
+ * @param {Object|null|undefined} res
+ * @param {string} fallback
+ * @returns {string}
+ */
+function failureMessageFromApiResult(res, fallback) {
+  if (res && typeof res.formattedError === 'string') return res.formattedError;
+  if (res && typeof res.error === 'string') return res.error;
+  return fallback;
+}
+
+/**
+ * @param {Object} res
+ * @returns {Array<unknown>}
+ */
+function extractOpenApiFileListItems(res) {
+  const data = res && res.data;
+  if (data && Array.isArray(data.data)) return data.data;
+  if (data && Array.isArray(data.items)) return data.items;
+  if (res && Array.isArray(res.items)) return res.items;
+  return [];
+}
+
+async function getExistingOpenApiKeys(dataplaneUrl, systemKey, authConfig) {
+  // Note: this endpoint is system-scoped and does not require guessing externalSystemId.
+  // Dataplane caps pageSize at 100 (OpenAPI route schema); keep within bounds.
+  const res = await listOpenAPIFiles(dataplaneUrl, systemKey, authConfig, { pageSize: 100 });
+  if (!res || res.success !== true) {
+    throw new Error(failureMessageFromApiResult(res, 'Failed to list OpenAPI files'));
+  }
+  const keys = new Set();
+  for (const it of extractOpenApiFileListItems(res)) {
+    if (it && typeof it.key === 'string') keys.add(it.key);
+  }
+  return keys;
+}
+
+function readDatasourceDocumentKey(appPath, datasourceFileName) {
+  const dsPath = path.join(appPath, datasourceFileName);
+  if (!fs.existsSync(dsPath)) return null;
+  const parsed = require('../utils/config-format').loadConfigFile(dsPath);
+  const openapi = parsed && typeof parsed.openapi === 'object' && !Array.isArray(parsed.openapi) ? parsed.openapi : null;
+  return openapi && typeof openapi.documentKey === 'string' ? openapi.documentKey : null;
+}
+
+/**
+ * @param {Object} opts
+ * @param {string} opts.appPath
+ * @param {string} opts.systemKey
+ * @param {string[]} opts.datasourceFiles
+ * @returns {Promise<{ uploaded: number, skipped: number }>}
+ */
+async function syncOpenApiFilesForMcp(opts) {
+  const { appPath, systemKey, datasourceFiles } = opts;
+  const openapiDir = path.join(appPath, 'openapi');
+  if (!(await fileExistsAsync(openapiDir))) return { uploaded: 0, skipped: 0 };
+
+  const { dataplaneUrl, authConfig } = await resolveDataplaneAndAuth(systemKey);
+  const existingKeys = await getExistingOpenApiKeys(dataplaneUrl, systemKey, authConfig);
+  const uploadedKeys = new Set(existingKeys);
+  let uploaded = 0;
+  let skipped = 0;
+
+  for (const fileName of datasourceFiles || []) {
+    const documentKey = readDatasourceDocumentKey(appPath, fileName);
+    if (!documentKey || uploadedKeys.has(documentKey)) continue;
+
+    const localPath = documentKeyToLocalOpenApiPath(appPath, systemKey, documentKey);
+    if (!(await fileExistsAsync(localPath))) {
+      skipped += 1;
+      continue;
+    }
+
+    await uploadOneOpenApiFile(dataplaneUrl, authConfig, systemKey, localPath, documentKey);
+    uploadedKeys.add(documentKey);
+    uploaded += 1;
+  }
+
+  return { uploaded, skipped };
+}
+
+/**
+ * Repair wrapper that returns change-log lines (or []).
+ * @param {Object} opts
+ * @param {boolean} opts.enabled
+ * @param {boolean} opts.dryRun
+ * @param {string} opts.appPath
+ * @param {string} opts.systemKey
+ * @param {string[]} opts.datasourceFiles
+ * @returns {Promise<string[]>}
+ */
+async function maybeSyncOpenApiFilesForMcp(opts) {
+  if (!opts.enabled || opts.dryRun) return [];
+  const r = await syncOpenApiFilesForMcp(opts);
+  const lines = [];
+  if (r.uploaded > 0) {
+    lines.push(`Uploaded ${r.uploaded} OpenAPI file(s) for MCP (keyed by openapi.documentKey)`);
+  }
+  if (r.skipped > 0) {
+    lines.push(
+      `Skipped ${r.skipped} OpenAPI upload(s) (missing local integration/<systemKey>/openapi/<name>.json)`
+    );
+  }
+  return lines;
+}
+
+module.exports = {
+  documentKeyToLocalOpenApiPath,
+  maybeSyncOpenApiFilesForMcp,
+  syncOpenApiFilesForMcp
+};
+

package/lib/commands/repair-persist.js

@@ -0,0 +1,102 @@
+/**
+ * Persistence helpers for repair: write config files, regenerate manifest, regenerate README.
+ *
+ * Extracted from repair.js to keep file size under 500 lines.
+ *
+ * @fileoverview External integration repair helpers (persistence)
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const chalk = require('chalk');
+
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const { getDeployJsonPath } = require('../utils/paths');
+const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
+const { writeConfigFile, writeYamlPreservingComments, isYamlPath } = require('../utils/config-format');
+const { backupIntegrationFile } = require('../utils/integration-file-backup');
+const logger = require('../utils/logger');
+const generator = require('../generator');
+const { generateReadmeFromDeployJson } = require('../generator/split-readme');
+
+/**
+ * README "Files" section should match integration config format on disk (YAML vs JSON).
+ * @param {string} appPath - Integration directory
+ * @returns {string} '.yaml' or '.json'
+ */
+function inferExternalReadmeFileExt(appPath) {
+  try {
+    const configPath = resolveApplicationConfigPath(appPath);
+    const ext = path.extname(configPath).toLowerCase();
+    if (ext === '.yaml' || ext === '.yml') return '.yaml';
+  } catch {
+    /* use default */
+  }
+  return '.json';
+}
+
+async function regenerateManifest(appName, appPath, changes, backupCtx) {
+  try {
+    const deployPath = getDeployJsonPath(appName, 'external', true);
+    backupIntegrationFile(deployPath, backupCtx);
+    const outPath = await generator.generateDeployJson(appName, { appPath });
+    changes.push(`Regenerated ${path.basename(outPath)}`);
+    return true;
+  } catch (err) {
+    logger.log(chalk.yellow(`⚠ Manifest regeneration skipped: ${err.message}`));
+    return false;
+  }
+}
+
+/**
+ * Regenerates README.md from deployment manifest when options.doc is set.
+ * @param {string} appName - Application name
+ * @param {string} appPath - Application path
+ * @param {Object} options - Options (doc, dryRun)
+ * @param {string[]} changes - Array to append change messages to
+ * @returns {Promise<boolean>} True if README was regenerated
+ */
+async function regenerateReadmeIfRequested(appName, appPath, options, changes) {
+  if (!options.doc) return false;
+  const deployJsonPath = getDeployJsonPath(appName, 'external', true);
+  if (!fs.existsSync(deployJsonPath) && !options.dryRun) {
+    await regenerateManifest(appName, appPath, changes, options.backupCtx);
+  }
+  if (!fs.existsSync(deployJsonPath)) return false;
+  try {
+    const deployment = JSON.parse(fs.readFileSync(deployJsonPath, 'utf8'));
+    const fileExt = inferExternalReadmeFileExt(appPath);
+    const readmeContent = generateReadmeFromDeployJson(deployment, { fileExt });
+    const readmePath = path.join(appPath, 'README.md');
+    if (!options.dryRun) {
+      backupIntegrationFile(readmePath, options.backupCtx);
+      fs.writeFileSync(readmePath, readmeContent, { mode: 0o644, encoding: 'utf8' });
+    }
+    changes.push('Regenerated README.md from deployment manifest');
+    return true;
+  } catch (err) {
+    logger.log(chalk.yellow(`⚠ Could not regenerate README: ${err.message}`));
+    return false;
+  }
+}
+
+function persistChangesAndRegenerate(opts) {
+  const { configPath, variables, appName, appPath, changes, originalYamlContent, backupCtx } = opts;
+  backupIntegrationFile(configPath, backupCtx);
+  if (originalYamlContent !== null && originalYamlContent !== undefined && typeof originalYamlContent === 'string' && isYamlPath(configPath)) {
+    writeYamlPreservingComments(configPath, originalYamlContent, variables);
+  } else {
+    writeConfigFile(configPath, variables);
+  }
+  logger.log(formatSuccessLine(`Updated ${path.basename(configPath)}`));
+  changes.forEach(c => logger.log(chalk.gray(`  ${c}`)));
+  return regenerateManifest(appName, appPath, changes, backupCtx);
+}
+
+module.exports = {
+  persistChangesAndRegenerate,
+  regenerateReadmeIfRequested
+};
+