@aifabrix/builder 2.40.2 → 2.42.0

package/lib/commands/dev-init.js

@@ -0,0 +1,347 @@
+/**
+ * @fileoverview aifabrix dev init – onboard with Builder Server (issue-cert, save cert, get settings, add SSH key).
+ * Auth: first call (issue-cert) uses no client cert; all other calls (getSettings, addSshKey, and every other dev API) send the client certificate.
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const chalk = require('chalk');
+const config = require('../core/config');
+const { getConfigDirForPaths } = require('../utils/paths');
+const { generateCSR, getCertDir, readClientCertPem, readClientKeyPem, getCertValidNotAfter } = require('../utils/dev-cert-helper');
+const { getOrCreatePublicKeyContent } = require('../utils/ssh-key-helper');
+const devApi = require('../api/dev.api');
+const logger = require('../utils/logger');
+const {
+  isSslUntrustedError,
+  fetchInstallCa,
+  installCaPlatform,
+  promptInstallCa
+} = require('../utils/dev-ca-install');
+
+/**
+ * Ensure the Builder Server is trusted: run health check; on SSL untrusted error,
+ * optionally fetch and install CA, then retry.
+ * @param {string} baseUrl - Builder Server base URL
+ * @param {Object} options - Commander options (yes, y, no-install-ca)
+ * @returns {Promise<void>}
+ */
+async function ensureServerTrusted(baseUrl, options) {
+  const skipInstall = options['no-install-ca'];
+  const autoInstall = options.yes || options.y;
+  try {
+    await devApi.getHealth(baseUrl);
+  } catch (err) {
+    if (!isSslUntrustedError(err)) throw err;
+    const manualUrl = `${baseUrl.replace(/\/+$/, '')}/install-ca`;
+    if (skipInstall) {
+      throw new Error(`Server certificate not trusted. Install CA manually: ${manualUrl}`);
+    }
+    if (!autoInstall) {
+      const install = await promptInstallCa();
+      if (!install) {
+        throw new Error(`Server certificate not trusted. Install CA manually: ${manualUrl}`);
+      }
+    }
+    logger.log(chalk.gray('  Downloading and installing CA...'));
+    const caPem = await fetchInstallCa(baseUrl);
+    await installCaPlatform(caPem, baseUrl);
+    logger.log(chalk.gray('  CA installed. Retrying...'));
+    await devApi.getHealth(baseUrl);
+  }
+}
+
+/**
+ * Validate init options and return normalized baseUrl and devId.
+ * @param {Object} options - Commander options
+ * @returns {{ baseUrl: string, devId: string }}
+ */
+function validateInitOptions(options) {
+  const devId = options.developerId || options['developer-id'];
+  const server = options.server;
+  const pin = options.pin;
+
+  if (!devId || typeof devId !== 'string' || !/^[0-9]+$/.test(devId)) {
+    throw new Error('--developer-id is required and must be a non-empty digit string (e.g. 01)');
+  }
+  if (!server || typeof server !== 'string' || !server.trim()) {
+    throw new Error('--server is required and must be the Builder Server base URL (e.g. https://dev.aifabrix.dev)');
+  }
+  if (!pin || typeof pin !== 'string' || !pin.trim()) {
+    throw new Error('--pin is required (one-time PIN from your admin)');
+  }
+  return { baseUrl: server.trim().replace(/\/+$/, ''), devId };
+}
+
+/**
+ * Request certificate from Builder Server; map API errors to user messages.
+ * @param {string} baseUrl - Builder Server base URL
+ * @param {string} devId - Developer ID
+ * @param {string} pin - One-time PIN
+ * @param {string} csrPem - PEM CSR
+ * @returns {Promise<Object>} IssueCertResponseDto
+ */
+async function requestCertificate(baseUrl, devId, pin, csrPem) {
+  try {
+    return await devApi.issueCert(baseUrl, {
+      developerId: devId,
+      pin: pin.trim(),
+      csr: csrPem
+    });
+  } catch (err) {
+    if (err.status === 401) {
+      throw new Error('Invalid or expired PIN. Ask your admin for a new PIN (aifabrix dev pin <developerId>).');
+    }
+    if (err.status === 404) {
+      throw new Error(`Developer ${devId} not found on the server.`);
+    }
+    if (err.status === 503) {
+      throw new Error('Certificate signing is temporarily unavailable. Try again later.');
+    }
+    throw err;
+  }
+}
+
+/**
+ * Normalize PEM string: turn literal \n (backslash-n) into real newlines so Docker/OpenSSL accept it.
+ * Some servers return JSON with escaped newlines in the PEM string.
+ * @param {string} pem - PEM string (certificate or CA)
+ * @returns {string} PEM with real newlines
+ */
+function normalizePemNewlines(pem) {
+  if (typeof pem !== 'string') return pem;
+  return pem.replace(/\\n/g, '\n');
+}
+
+/**
+ * Save certificate, key, and optional CA to cert dir; set developer-id in config.
+ * Remote Docker requires ca.pem in the cert dir; if the server provides it (e.g. issue-cert
+ * response caCertificate or ca), it is saved so DOCKER_CERT_PATH works.
+ * @param {string} configDir - Config directory
+ * @param {string} devId - Developer ID
+ * @param {string} certificatePem - Issued certificate PEM
+ * @param {string} keyPem - Private key PEM
+ * @param {string} [caPem] - Optional CA certificate PEM (for remote Docker TLS)
+ */
+async function saveCertAndConfig(configDir, devId, certificatePem, keyPem, caPem) {
+  const certDir = getCertDir(configDir, devId);
+  await fs.mkdir(certDir, { recursive: true });
+  const certNormalized = normalizePemNewlines(certificatePem);
+  const keyNormalized = normalizePemNewlines(keyPem);
+  await fs.writeFile(path.join(certDir, 'cert.pem'), certNormalized, { mode: 0o600 });
+  await fs.writeFile(path.join(certDir, 'key.pem'), keyNormalized, { mode: 0o600 });
+  if (caPem && typeof caPem === 'string' && caPem.trim()) {
+    const caNormalized = normalizePemNewlines(caPem.trim());
+    await fs.writeFile(path.join(certDir, 'ca.pem'), caNormalized, { mode: 0o600 });
+    logger.log(chalk.green('  ✓ Certificate and CA saved to ') + chalk.cyan(path.join(certDir, 'cert.pem')));
+  } else {
+    logger.log(chalk.green('  ✓ Certificate saved to ') + chalk.cyan(path.join(certDir, 'cert.pem')));
+  }
+  await config.setDeveloperId(devId);
+  logger.log(chalk.green('  ✓ Developer ID set to ') + chalk.cyan(devId));
+}
+
+/**
+ * Message for 400 Bad Request: nginx often forwards X-Client-Cert with literal newlines.
+ * @returns {string} Hint for server-side nginx fix
+ */
+function getBadRequestHint() {
+  return 'Bad Request (400) often means the server\'s nginx is forwarding the client certificate with literal newlines in X-Client-Cert. On the server, use nginx njs to escape newlines (see .cursor/plans/builder-cli.md §5).';
+}
+
+/**
+ * Log a one-line hint for cert troubleshooting (curl test and docs).
+ * @param {string} configDir - Config directory
+ * @param {string} devId - Developer ID
+ * @param {string} baseUrl - Builder Server base URL
+ */
+function logCertTroubleshootingHint(configDir, devId, baseUrl) {
+  const certDir = getCertDir(configDir, devId);
+  const certPath = path.join(certDir, 'cert.pem');
+  const keyPath = path.join(certDir, 'key.pem');
+  logger.log(chalk.gray(`  Test with: curl -v --cert ${certPath} --key ${keyPath} ${baseUrl}/api/dev/settings`));
+  logger.log(chalk.gray('  See .cursor/plans/builder-cli.md §5 for 200 vs 401 vs 400 and nginx/server fix.'));
+}
+
+/**
+ * Register SSH public key with Builder Server for Mutagen sync.
+ * @param {string} baseUrl - Builder Server base URL
+ * @param {string} clientCertPem - Client certificate PEM
+ * @param {string} clientKeyPem - Client private key PEM (for mTLS)
+ * @param {string} devId - Developer ID
+ */
+async function registerSshKey(baseUrl, clientCertPem, clientKeyPem, devId) {
+  const publicKey = getOrCreatePublicKeyContent();
+  try {
+    await devApi.addSshKey(baseUrl, clientCertPem, devId, {
+      publicKey,
+      label: 'aifabrix-init'
+    }, clientKeyPem);
+    logger.log(chalk.green('  ✓ SSH key registered'));
+  } catch (err) {
+    if (err.status === 409) {
+      logger.log(chalk.yellow('  ⚠ SSH key already registered'));
+    } else {
+      throw err;
+    }
+  }
+}
+
+/**
+ * Run SSH key registration step (log, register, handle 400 hint).
+ * @param {string} baseUrl - Builder Server base URL
+ * @param {Object} issueResponse - IssueCert response (certificate)
+ * @param {string} keyPem - Client key PEM
+ * @param {string} configDir - Config directory
+ * @param {string} devId - Developer ID
+ * @private
+ */
+async function _runSshKeyRegistrationStep(baseUrl, issueResponse, keyPem, configDir, devId) {
+  logger.log(chalk.gray('  Registering SSH key for Mutagen sync...'));
+  try {
+    if (keyPem && typeof keyPem === 'string') {
+      logger.log(chalk.gray('  Using client certificate for TLS'));
+    }
+    await registerSshKey(baseUrl, issueResponse.certificate, keyPem, devId);
+  } catch (err) {
+    const msg = err.status === 400 ? getBadRequestHint() : (err.message || String(err));
+    logger.log(chalk.yellow('  ⚠ Could not register SSH key: ' + msg));
+    logCertTroubleshootingHint(configDir, devId, baseUrl);
+  }
+}
+
+/**
+ * Apply settings from issue-cert response or fetch via getSettings; merge into config.
+ * @param {string} baseUrl - Builder Server base URL
+ * @param {string} devId - Developer ID
+ * @param {Object} issueResponse - IssueCert response (certificate, settings)
+ * @param {string} keyPem - Client key PEM
+ */
+async function applySettingsFromServer(baseUrl, devId, issueResponse, keyPem) {
+  const configDir = getConfigDirForPaths();
+  if (issueResponse.settings && typeof issueResponse.settings === 'object') {
+    await config.mergeRemoteSettings(issueResponse.settings);
+    logger.log(chalk.green('  ✓ Config updated from server (issue-cert response)'));
+    return;
+  }
+  logger.log(chalk.gray('  Fetching settings...'));
+  try {
+    if (keyPem && typeof keyPem === 'string') {
+      logger.log(chalk.gray('  Using client certificate for TLS'));
+    }
+    const settings = await devApi.getSettings(baseUrl, issueResponse.certificate, keyPem);
+    await config.mergeRemoteSettings(settings);
+    logger.log(chalk.green('  ✓ Config updated from server'));
+  } catch (err) {
+    const msg = err.status === 400 ? getBadRequestHint() : (err.message || String(err));
+    logger.log(chalk.yellow('  ⚠ Could not fetch settings (server may not support cert yet): ' + msg));
+    logCertTroubleshootingHint(configDir, devId, baseUrl);
+  }
+}
+
+/**
+ * Run dev init: validate PIN via issue-cert, save certificate, fetch settings, add SSH key.
+ * @param {Object} options - Commander options (devId, server, pin)
+ * @returns {Promise<void>}
+ */
+async function runDevInit(options) {
+  const { baseUrl, devId } = validateInitOptions(options);
+  logger.log(chalk.blue('\n🔐 Onboarding with Builder Server...\n'));
+
+  try {
+    await ensureServerTrusted(baseUrl, options);
+  } catch (err) {
+    throw new Error(`Cannot reach Builder Server at ${baseUrl}. Check URL and network. ${err.message}`);
+  }
+
+  logger.log(chalk.gray('  Generating certificate request...'));
+  const { csrPem, keyPem } = generateCSR(devId);
+
+  logger.log(chalk.gray('  Requesting certificate (issue-cert)...'));
+  const issueResponse = await requestCertificate(baseUrl, devId, options.pin, csrPem);
+
+  const configDir = getConfigDirForPaths();
+  const caPem = issueResponse.caCertificate || issueResponse.ca;
+  await saveCertAndConfig(configDir, devId, issueResponse.certificate, keyPem, caPem);
+
+  await config.setRemoteServer(baseUrl);
+
+  await applySettingsFromServer(baseUrl, devId, issueResponse, keyPem);
+  await _runSshKeyRegistrationStep(baseUrl, issueResponse, keyPem, configDir, devId);
+  logger.log(chalk.green('\n✓ Onboarding complete. You can use remote Docker and Mutagen sync.\n'));
+}
+
+/** Days before cert expiry at which we auto-refresh on dev refresh. */
+const CERT_REFRESH_DAYS = 14;
+
+/**
+ * True if the cert in certDir expires within CERT_REFRESH_DAYS (or we cannot read expiry).
+ * @param {string} certDir - Certificate directory
+ * @returns {boolean}
+ */
+function shouldRefreshDevCert(certDir) {
+  const validNotAfter = getCertValidNotAfter(certDir);
+  if (!validNotAfter) return true;
+  const now = Date.now();
+  const threshold = now + CERT_REFRESH_DAYS * 24 * 60 * 60 * 1000;
+  return validNotAfter.getTime() < threshold;
+}
+
+/**
+ * Refresh developer certificate: create PIN (with current cert), issue new cert, save and apply settings.
+ * @param {{ serverUrl: string, clientCertPem: string }} auth - Current auth from getRemoteDevAuth
+ * @returns {Promise<void>}
+ */
+async function runCertificateRefresh(auth) {
+  const devId = await config.getDeveloperId();
+  if (!devId) throw new Error('developer-id not set in config.');
+  const configDir = getConfigDirForPaths();
+  logger.log(chalk.blue('\n🔄 Refreshing certificate (create PIN + issue-cert)...\n'));
+  const pinRes = await devApi.createPin(auth.serverUrl, auth.clientCertPem, devId);
+  const pin = pinRes.pin;
+  if (!pin || typeof pin !== 'string') throw new Error('Server did not return a PIN.');
+  logger.log(chalk.gray('  Generating new certificate request...'));
+  const { csrPem, keyPem } = generateCSR(devId);
+  logger.log(chalk.gray('  Requesting new certificate (issue-cert)...'));
+  const issueResponse = await requestCertificate(auth.serverUrl, devId, pin, csrPem);
+  const caPem = issueResponse.caCertificate || issueResponse.ca;
+  await saveCertAndConfig(configDir, devId, issueResponse.certificate, keyPem, caPem);
+  await applySettingsFromServer(auth.serverUrl, devId, issueResponse, keyPem);
+  logger.log(chalk.green('✓ Certificate refreshed and config updated from server.\n'));
+}
+
+/**
+ * Fetch settings from Builder Server and merge into config (GET /api/dev/settings).
+ * If certificate expires within CERT_REFRESH_DAYS (or --cert), refresh cert first (create PIN + issue-cert).
+ * @param {Object} [options] - Commander options; options.cert = true forces cert refresh
+ * @returns {Promise<void>}
+ * @throws {Error} If remote server or certificate not configured, or getSettings fails
+ */
+async function runDevRefresh(options = {}) {
+  const { getRemoteDevAuth } = require('../utils/remote-dev-auth');
+  const auth = await getRemoteDevAuth();
+  if (!auth) {
+    throw new Error('Remote server is not configured. Set remote-server and run "aifabrix dev init" first.');
+  }
+  const devId = await config.getDeveloperId();
+  const configDir = getConfigDirForPaths();
+  const certDir = getCertDir(configDir, devId);
+  const clientCertPem = readClientCertPem(certDir);
+  const clientKeyPem = readClientKeyPem(certDir);
+  if (!clientCertPem) {
+    throw new Error('Client certificate not found. Run "aifabrix dev init" first.');
+  }
+  const forceCertRefresh = Boolean(options.cert);
+  if (forceCertRefresh || shouldRefreshDevCert(certDir)) {
+    await runCertificateRefresh(auth);
+    return;
+  }
+  logger.log(chalk.blue('\n🔄 Fetching settings from Builder Server...\n'));
+  const settings = await devApi.getSettings(auth.serverUrl, clientCertPem, clientKeyPem || undefined);
+  await config.mergeRemoteSettings(settings);
+  logger.log(chalk.green('✓ Config updated from server. Run "aifabrix dev config" to verify.\n'));
+}
+
+module.exports = { runDevInit, runDevRefresh };

package/lib/commands/repair-auth-config.js

@@ -0,0 +1,99 @@
+/**
+ * Normalizes system file authentication.security and configuration keyvault entries.
+ * @fileoverview Repair auth/config KV_* names and path-style kv:// values
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { systemKeyToKvPrefix, securityKeyToVar, kvEnvKeyToPath } = require('../utils/credential-secrets-env');
+
+/**
+ * Returns true if a kv value looks like legacy format (KeyVault suffix or no path segments).
+ * @param {string} val - Value from authentication.security or configuration
+ * @returns {boolean}
+ */
+function isLegacyKvValue(val) {
+  if (typeof val !== 'string' || !val.trim().toLowerCase().startsWith('kv://')) return false;
+  const after = val.trim().slice(5); // after 'kv://'
+  return after.includes('KeyVault') || !after.includes('/');
+}
+
+/**
+ * Normalizes authentication.security keyvault entries to path-style kv:// values (kv://systemKey/variable).
+ * @param {Object} security - authentication.security object (mutated)
+ * @param {string} prefix - KV prefix (e.g. 'HUBSPOT')
+ * @param {string} systemKey - System key for path namespace
+ * @param {string[]} changes - Array to append change descriptions to
+ * @returns {boolean} True if any change was made
+ */
+function normalizeSecuritySection(security, prefix, systemKey, changes) {
+  let updated = false;
+  for (const key of Object.keys(security)) {
+    const val = security[key];
+    if (typeof val !== 'string' || !isLegacyKvValue(val)) continue;
+    const envName = `KV_${prefix}_${securityKeyToVar(key)}`;
+    const pathVal = kvEnvKeyToPath(envName, systemKey);
+    if (pathVal) {
+      security[key] = pathVal;
+      changes.push(`authentication.security.${key}: normalized to path-style ${pathVal}`);
+      updated = true;
+    }
+  }
+  return updated;
+}
+
+/**
+ * Normalizes configuration array keyvault entries to canonical KV_* names and path-style values.
+ * @param {Object[]} config - configuration array (mutated)
+ * @param {string} prefix - KV prefix (e.g. 'HUBSPOT')
+ * @param {string} systemKey - System key for path namespace
+ * @param {string[]} changes - Array to append change descriptions to
+ * @returns {boolean} True if any change was made
+ */
+function normalizeConfigurationSection(config, prefix, systemKey, changes) {
+  let updated = false;
+  for (let i = 0; i < config.length; i++) {
+    const entry = config[i];
+    if (!entry || !entry.name || (entry.location !== 'keyvault' && !String(entry.name).startsWith('KV_'))) continue;
+    const afterPrefix = entry.name.startsWith(`KV_${prefix}_`)
+      ? entry.name.slice(`KV_${prefix}_`.length)
+      : entry.name.replace(/^KV_[A-Z0-9]+_/, '');
+    const normalizedVar = afterPrefix.replace(/_/g, '').toUpperCase();
+    const canonicalName = `KV_${prefix}_${normalizedVar}`;
+    const pathVal = kvEnvKeyToPath(canonicalName, systemKey);
+    if (!pathVal) continue;
+    const pathValWithoutPrefix = pathVal.replace(/^kv:\/\//, '');
+    const valueLegacy = typeof entry.value === 'string' && (entry.value.includes('KeyVault') || !entry.value.includes('/'));
+    if (entry.name !== canonicalName || (valueLegacy && entry.value !== pathValWithoutPrefix)) {
+      config[i] = { ...entry, name: canonicalName, value: pathValWithoutPrefix, location: 'keyvault' };
+      changes.push(`configuration: normalized ${entry.name} → ${canonicalName}, value → path-style`);
+      updated = true;
+    }
+  }
+  return updated;
+}
+
+/**
+ * Normalizes system file authentication.security and configuration keyvault entries to canonical
+ * KV_* names and path-style kv:// values so upload validation and env.template align.
+ *
+ * @param {Object} systemParsed - Parsed system config (mutated)
+ * @param {string} systemKey - System key (e.g. 'hubspot')
+ * @param {string[]} changes - Array to append change descriptions to
+ * @returns {boolean} True if any change was made
+ */
+function normalizeSystemFileAuthAndConfig(systemParsed, systemKey, changes) {
+  const prefix = systemKeyToKvPrefix(systemKey);
+  if (!prefix) return false;
+  const security = systemParsed.authentication?.security;
+  let updated = (security && typeof security === 'object' && normalizeSecuritySection(security, prefix, systemKey, changes));
+  const config = systemParsed.configuration;
+  if (Array.isArray(config)) {
+    updated = normalizeConfigurationSection(config, prefix, systemKey, changes) || updated;
+  }
+  return updated;
+}
+
+module.exports = { normalizeSystemFileAuthAndConfig, isLegacyKvValue };

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

@@ -0,0 +1,208 @@
+/**
+ * Normalize datasource keys and filenames to canonical form during repair.
+ *
+ * Key: <systemKey>-<resourceType> or <systemKey>-<resourceType>-2, -3 for duplicates.
+ * Filename: <systemKey>-datasource-<suffix>.<ext> where suffix = key without leading systemKey-.
+ * Skips keys/filenames that already match the valid pattern (e.g. customer-extra, customer-1).
+ *
+ * @fileoverview Datasource key and filename normalization for repair
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
+
+/**
+ * Returns suffix from a canonical-format filename: <systemKey>-datasource-<suffix>.<ext>.
+ *
+ * @param {string} fileName - Filename
+ * @param {string} systemKey - System key
+ * @returns {string|null} Suffix or null if not in canonical format
+ */
+function suffixFromCanonicalFilename(fileName, systemKey) {
+  const base = path.basename(fileName);
+  const ext = path.extname(fileName);
+  const withoutExt = base.slice(0, -ext.length);
+  const prefix = `${systemKey}-datasource-`;
+  if (!withoutExt.startsWith(prefix)) return null;
+  return withoutExt.slice(prefix.length) || null;
+}
+
+/**
+ * Returns true if the key already matches canonical form and should not be changed.
+ * Valid: <systemKey>-<resourceType> or <systemKey>-<resourceType>-<extra> (e.g. customer-extra, customer-1).
+ * When fileName is provided and is canonical, key may be just the suffix (e.g. record-storage).
+ * Invalid (will normalize): key ending with redundant -datasource (e.g. hubspot-demo-companies-datasource).
+ *
+ * @param {string} key - Datasource key
+ * @param {string} systemKey - System key
+ * @param {string} [fileName] - Optional filename; if canonical, key can be suffix-only
+ * @returns {boolean}
+ */
+function isKeyAlreadyCanonical(key, systemKey, fileName) {
+  if (!key || !systemKey) return false;
+  if (fileName && isFilenameAlreadyCanonical(fileName, systemKey)) {
+    const suffixFromFile = suffixFromCanonicalFilename(fileName, systemKey);
+    if (suffixFromFile && (key === suffixFromFile || key === `${systemKey}-${suffixFromFile}`)) {
+      return true;
+    }
+  }
+  if (!key.startsWith(systemKey + '-')) return false;
+  const suffix = key.slice(systemKey.length + 1);
+  if (!suffix) return false;
+  if (suffix.endsWith('-datasource')) return false;
+  return true;
+}
+
+/**
+ * Derives resourceType slug from key: strip systemKey prefix, then strip trailing -datasource if present.
+ *
+ * @param {string} key - Current datasource key
+ * @param {string} systemKey - System key
+ * @returns {string}
+ */
+function slugFromKey(key, systemKey) {
+  if (!key || !systemKey || !key.startsWith(systemKey + '-')) return key || '';
+  let suffix = key.slice(systemKey.length + 1);
+  if (suffix.endsWith('-datasource')) suffix = suffix.slice(0, -'-datasource'.length);
+  return suffix || key;
+}
+
+/**
+ * Returns canonical filename for a datasource: <systemKey>-datasource-<suffix>.<ext>.
+ *
+ * @param {string} canonicalKey - Canonical datasource key
+ * @param {string} systemKey - System key
+ * @param {string} ext - File extension including dot (e.g. .json)
+ * @returns {string}
+ */
+function canonicalDatasourceFilename(canonicalKey, systemKey, ext) {
+  const suffix = canonicalKey.startsWith(systemKey + '-')
+    ? canonicalKey.slice(systemKey.length + 1)
+    : canonicalKey;
+  return `${systemKey}-datasource-${suffix}${ext}`;
+}
+
+/**
+ * Returns true if filename already matches canonical pattern <systemKey>-datasource-<suffix>.<ext>.
+ *
+ * @param {string} fileName - Current filename
+ * @param {string} systemKey - System key
+ * @returns {boolean}
+ */
+function isFilenameAlreadyCanonical(fileName, systemKey) {
+  const base = path.basename(fileName);
+  const ext = path.extname(fileName);
+  const withoutExt = base.slice(0, -ext.length);
+  const prefix = `${systemKey}-datasource-`;
+  if (!withoutExt.startsWith(prefix)) return false;
+  const suffix = withoutExt.slice(prefix.length);
+  if (!suffix || suffix.endsWith('-datasource')) return false;
+  return true;
+}
+
+/**
+ * Normalizes datasource keys and filenames to canonical form. Runs early in repair.
+ * Updates file contents (key property), renames files when needed, and updates variables.externalIntegration.dataSources.
+ *
+ * @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
+ * @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) {
+  if (!datasourceFiles || datasourceFiles.length === 0) {
+    return { updated: false, datasourceFiles: datasourceFiles || [] };
+  }
+
+  const slugCounts = new Map();
+  const fileInfos = [];
+
+  for (const fileName of datasourceFiles) {
+    const filePath = path.join(appPath, fileName);
+    if (!fs.existsSync(filePath)) continue;
+    let parsed;
+    try {
+      parsed = loadConfigFile(filePath);
+    } catch (err) {
+      fileInfos.push({ fileName, key: null, skip: true });
+      continue;
+    }
+    const key = (parsed && typeof parsed.key === 'string' && parsed.key.trim()) ? parsed.key.trim() : null;
+    if (isKeyAlreadyCanonical(key, systemKey, fileName) && isFilenameAlreadyCanonical(fileName, systemKey)) {
+      fileInfos.push({ fileName, key, skip: true });
+      continue;
+    }
+    const slug = slugFromKey(key || fileName, systemKey);
+    fileInfos.push({
+      fileName,
+      parsed,
+      key,
+      slug,
+      canonicalKey: null,
+      skip: false
+    });
+  }
+
+  for (const info of fileInfos) {
+    if (info.skip) continue;
+    const slug = info.slug;
+    const n = (slugCounts.get(slug) || 0) + 1;
+    slugCounts.set(slug, n);
+    info.canonicalKey = n === 1 ? `${systemKey}-${slug}` : `${systemKey}-${slug}-${n}`;
+  }
+
+  let updated = false;
+  const newDatasourceFiles = [];
+
+  for (const info of fileInfos) {
+    if (info.skip) {
+      newDatasourceFiles.push(info.fileName);
+      continue;
+    }
+    const { fileName, parsed, canonicalKey } = info;
+    const ext = path.extname(fileName);
+    const canonicalFileName = canonicalDatasourceFilename(canonicalKey, systemKey, ext);
+
+    if (parsed.key !== canonicalKey) {
+      parsed.key = canonicalKey;
+      if (!dryRun) writeConfigFile(path.join(appPath, fileName), parsed);
+      changes.push(`${fileName}: key → ${canonicalKey}`);
+      updated = true;
+    }
+    if (fileName !== canonicalFileName) {
+      const oldPath = path.join(appPath, fileName);
+      const newPath = path.join(appPath, canonicalFileName);
+      if (!dryRun && fs.existsSync(oldPath) && !fs.existsSync(newPath)) {
+        fs.renameSync(oldPath, newPath);
+      }
+      changes.push(`Renamed ${fileName} → ${canonicalFileName}`);
+      updated = true;
+      newDatasourceFiles.push(canonicalFileName);
+    } else {
+      newDatasourceFiles.push(fileName);
+    }
+  }
+
+  if (updated && variables.externalIntegration && Array.isArray(variables.externalIntegration.dataSources)) {
+    variables.externalIntegration.dataSources = [...newDatasourceFiles].sort();
+  }
+
+  return { updated, datasourceFiles: newDatasourceFiles };
+}
+
+module.exports = {
+  normalizeDatasourceKeysAndFilenames,
+  isKeyAlreadyCanonical,
+  slugFromKey,
+  canonicalDatasourceFilename,
+  isFilenameAlreadyCanonical
+};