@aifabrix/builder 2.41.0 → 2.42.0

package/lib/utils/configuration-env-resolver.js

@@ -0,0 +1,179 @@
+/**
+ * Resolves configuration section values for upload (variable → .env, keyvault → secrets)
+ * and re-templates configuration on download from env.template.
+ *
+ * @fileoverview Configuration env resolution for external system upload/download
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { getIntegrationPath } = require('./paths');
+const { parseEnvToMap, resolveKvValue } = require('./credential-secrets-env');
+const { loadSecrets, resolveKvReferences } = require('../core/secrets');
+const { loadEnvTemplate } = require('./secrets-helpers');
+const { getActualSecretsPath } = require('./secrets-path');
+
+const VAR_PLACEHOLDER_REGEX = /\{\{([^}]+)\}\}/g;
+
+/**
+ * Builds resolved env map and secrets for an integration app (for configuration resolution).
+ * If .env exists, parses it; otherwise resolves env.template with secrets and parses the result.
+ *
+ * @param {string} systemKey - External system key (e.g. 'my-sharepoint')
+ * @returns {Promise<{ envMap: Object.<string, string>, secrets: Object }>} envMap for {{VAR}} substitution, secrets for kv://
+ * @throws {Error} If env.template is missing when .env is missing (only when building from template)
+ */
+async function buildResolvedEnvMapForIntegration(systemKey) {
+  if (!systemKey || typeof systemKey !== 'string') {
+    throw new Error('systemKey is required and must be a string');
+  }
+  const integrationPath = getIntegrationPath(systemKey);
+  const envPath = path.join(integrationPath, '.env');
+  const envTemplatePath = path.join(integrationPath, 'env.template');
+
+  let secrets = {};
+  try {
+    secrets = await loadSecrets(undefined, systemKey);
+  } catch {
+    secrets = {};
+  }
+
+  let envMap = {};
+  if (fs.existsSync(envPath)) {
+    const content = fs.readFileSync(envPath, 'utf8');
+    envMap = parseEnvToMap(content);
+  } else if (fs.existsSync(envTemplatePath)) {
+    const templateContent = loadEnvTemplate(envTemplatePath);
+    const secretsPaths = await getActualSecretsPath(undefined, systemKey);
+    const resolvedContent = await resolveKvReferences(
+      templateContent,
+      secrets,
+      'local',
+      secretsPaths,
+      systemKey
+    );
+    envMap = parseEnvToMap(resolvedContent);
+  }
+  return { envMap, secrets };
+}
+
+/**
+ * Resolves {{VAR}} in a string using envMap. Throws if any variable is missing.
+ *
+ * @param {string} value - Value that may contain {{VAR}}
+ * @param {Object.<string, string>} envMap - Resolved env key-value map
+ * @param {string} [systemKey] - System key for error message
+ * @returns {string} Value with {{VAR}} replaced
+ * @throws {Error} If a {{VAR}} is missing from envMap
+ */
+function substituteVarPlaceholders(value, envMap, systemKey) {
+  const hint = systemKey ? ` Run 'aifabrix resolve ${systemKey}' or set the variable in .env.` : '';
+  return value.replace(VAR_PLACEHOLDER_REGEX, (match, varName) => {
+    const key = varName.trim();
+    if (envMap[key] === undefined || envMap[key] === null) {
+      throw new Error(`Missing configuration env var: ${key}.${hint}`);
+    }
+    return String(envMap[key]);
+  });
+}
+
+/**
+ * Resolves configuration array values in place by location: variable → {{VAR}} from envMap;
+ * keyvault → kv:// from secrets. Does not log or expose secret values.
+ *
+ * @param {Array<{ name?: string, value?: string, location?: string }>} configArray - Configuration array (mutated)
+ * @param {Object.<string, string>} envMap - Resolved env map from buildResolvedEnvMapForIntegration
+ * @param {Object} secrets - Loaded secrets for kv:// resolution
+ * @param {string} [systemKey] - System key for error messages
+ * @throws {Error} If variable env is missing or keyvault secret unresolved (message never contains secret values)
+ */
+function resolveConfigurationValues(configArray, envMap, secrets, systemKey) {
+  if (!Array.isArray(configArray)) return;
+  const hint = systemKey ? ` Run 'aifabrix resolve ${systemKey}' and ensure the key exists in the secrets file.` : '';
+  for (const item of configArray) {
+    if (!item || typeof item.value !== 'string') continue;
+    const location = (item.location || '').toLowerCase();
+    if (location === 'variable') {
+      if (item.value.trim().startsWith('kv://')) {
+        throw new Error(`Configuration entry '${item.name || 'unknown'}' has location 'variable' but value is kv://. Use location 'keyvault' for secrets.`);
+      }
+      item.value = substituteVarPlaceholders(item.value, envMap, systemKey);
+    } else if (location === 'keyvault') {
+      const resolved = resolveKvValue(secrets, item.value);
+      if (resolved === null || resolved === undefined) {
+        throw new Error(`Unresolved keyvault reference for configuration '${item.name || 'unknown'}'.${hint}`);
+      }
+      item.value = resolved;
+    }
+  }
+}
+
+/**
+ * Returns the set of variable names (keys) defined in env.template content.
+ *
+ * @param {string} envTemplateContent - Raw env.template content
+ * @returns {Set<string>} Set of variable names
+ */
+function getEnvTemplateVariableNames(envTemplateContent) {
+  const names = new Set();
+  if (!envTemplateContent || typeof envTemplateContent !== 'string') return names;
+  const lines = envTemplateContent.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq > 0) {
+      const key = trimmed.substring(0, eq).trim();
+      if (key) names.add(key);
+    }
+  }
+  return names;
+}
+
+/**
+ * Re-templates configuration from env.template: for each entry with location === 'variable'
+ * whose name matches a key in env.template, sets value to {{name}}. Mutates configArray in place.
+ *
+ * @param {Array<{ name?: string, value?: string, location?: string }>} configArray - Configuration array (mutated)
+ * @param {Set<string>} envTemplateVariableNames - Variable names present in env.template
+ */
+function retemplateConfigurationFromEnvTemplate(configArray, envTemplateVariableNames) {
+  if (!Array.isArray(configArray) || !envTemplateVariableNames || !envTemplateVariableNames.size) return;
+  for (const item of configArray) {
+    if (!item || (item.location || '').toLowerCase() !== 'variable') continue;
+    const name = item.name && String(item.name).trim();
+    if (name && envTemplateVariableNames.has(name)) {
+      item.value = `{{${name}}}`;
+    }
+  }
+}
+
+/**
+ * Reads env.template at integration path, re-templates the given configuration array,
+ * and returns the updated array (mutates in place). If env.template is missing, does nothing.
+ *
+ * @param {string} systemKey - External system key
+ * @param {Array<{ name?: string, value?: string, location?: string }>} configArray - Configuration array (mutated)
+ * @returns {Promise<boolean>} True if re-templating was applied (env.template existed)
+ */
+async function retemplateConfigurationForDownload(systemKey, configArray) {
+  if (!systemKey || typeof systemKey !== 'string' || !Array.isArray(configArray)) return false;
+  const integrationPath = getIntegrationPath(systemKey);
+  const envTemplatePath = path.join(integrationPath, 'env.template');
+  if (!fs.existsSync(envTemplatePath)) return false;
+  const content = fs.readFileSync(envTemplatePath, 'utf8');
+  const names = getEnvTemplateVariableNames(content);
+  retemplateConfigurationFromEnvTemplate(configArray, names);
+  return true;
+}
+
+module.exports = {
+  buildResolvedEnvMapForIntegration,
+  resolveConfigurationValues,
+  getEnvTemplateVariableNames,
+  retemplateConfigurationFromEnvTemplate,
+  retemplateConfigurationForDownload,
+  substituteVarPlaceholders
+};

package/lib/utils/credential-display.js

@@ -0,0 +1,83 @@
+/**
+ * Credential display utilities – status icons and formatting for CLI output
+ * Aligns with dataplane credential status lifecycle (pending, verified, failed, expired).
+ *
+ * @fileoverview Credential status formatter with icons and chalk colors
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+
+/** @type {{ verified: string, pending: string, failed: string, expired: string }} */
+const STATUS_ICONS = {
+  verified: ' ✓',
+  pending: ' ○',
+  failed: ' ✗',
+  expired: ' ⊘'
+};
+
+/** @type {{ verified: string, pending: string, failed: string, expired: string }} */
+const STATUS_LABELS = {
+  verified: 'Valid',
+  pending: 'Not tested',
+  failed: 'Connection failed',
+  expired: 'Token expired'
+};
+
+/**
+ * Chalk color functions per status
+ * @type {{ verified: Function, pending: Function, failed: Function, expired: Function }}
+ */
+const STATUS_CHALK = {
+  verified: chalk.green,
+  pending: chalk.gray,
+  failed: chalk.red,
+  expired: chalk.yellow
+};
+
+const VALID_STATUSES = ['verified', 'pending', 'failed', 'expired'];
+
+/**
+ * Format credential status for display (icon + optional label)
+ * @param {string} [status] - Credential status (pending | verified | failed | expired)
+ * @returns {{ icon: string, color: Function, label: string } | null} Status info or null when missing/invalid
+ */
+function formatCredentialStatus(status) {
+  if (!status || typeof status !== 'string') return null;
+  const s = status.toLowerCase();
+  if (!VALID_STATUSES.includes(s)) return null;
+  return {
+    icon: STATUS_ICONS[s],
+    color: STATUS_CHALK[s],
+    label: STATUS_LABELS[s]
+  };
+}
+
+/**
+ * Format credential with status for CLI display
+ * @param {Object} credential - Credential object from API
+ * @param {string} [credential.key]
+ * @param {string} [credential.id]
+ * @param {string} [credential.credentialKey]
+ * @param {string} [credential.displayName]
+ * @param {string} [credential.name]
+ * @param {string} [credential.status]
+ * @returns {{ key: string, name: string, statusFormatted: string, statusLabel: string }}
+ */
+function formatCredentialWithStatus(credential) {
+  const key = credential?.key ?? credential?.id ?? credential?.credentialKey ?? '-';
+  const name = credential?.displayName ?? credential?.name ?? key;
+  const statusInfo = formatCredentialStatus(credential?.status);
+  const statusFormatted = statusInfo ? statusInfo.color(statusInfo.icon) : '';
+  const statusLabel = statusInfo ? ` (${statusInfo.label})` : '';
+  return { key, name, statusFormatted, statusLabel };
+}
+
+module.exports = {
+  STATUS_ICONS,
+  STATUS_LABELS,
+  STATUS_CHALK,
+  formatCredentialStatus,
+  formatCredentialWithStatus
+};

package/lib/utils/credential-secrets-env.js

@@ -16,24 +16,107 @@ const KV_PREFIX = 'KV_';
 const KV_REF_PATTERN = /kv:\/\/([a-zA-Z0-9_\-/]+)/g;
 
 /**
- * Converts KV_* env key to kv:// path (e.g. KV_SECRETS_FOO → kv://secrets/foo).
- * @param {string} envKey - Env var name (e.g. KV_SECRETS_CLIENT_SECRET)
- * @returns {string|null} kv:// path or null if invalid
+ * Converts systemKey to KV_* prefix (e.g. hubspot -> HUBSPOT, my-hubspot -> MY_HUBSPOT).
+ * @param {string} systemKey - System key
+ * @returns {string}
+ */
+function systemKeyToKvPrefix(systemKey) {
+  if (!systemKey || typeof systemKey !== 'string') return '';
+  return systemKey.replace(/-/g, '_').toUpperCase();
+}
+
+/**
+ * Maps authentication security key (camelCase) to env VAR (UPPERCASE, no underscores).
+ * Used for canonical KV_<APPKEY>_<VAR> names (e.g. clientId → CLIENTID).
+ * @param {string} securityKey - Security key (e.g. 'clientId', 'clientSecret')
+ * @returns {string}
  */
-function kvEnvKeyToPath(envKey) {
-  if (!envKey || typeof envKey !== 'string' || !envKey.toUpperCase().startsWith(KV_PREFIX)) {
-    return null;
+function securityKeyToVar(securityKey) {
+  if (!securityKey || typeof securityKey !== 'string') return '';
+  return securityKey.replace(/_/g, '').toUpperCase();
+}
+
+/** Known single-segment variable suffixes (uppercase) for inferring var vs namespace in env keys */
+const VAR_SUFFIXES = new Set(['ID', 'SECRET', 'KEY', 'TOKEN', 'URL', 'USERNAME', 'PASSWORD']);
+
+/**
+ * Converts var segment(s) from env key to path-style camelCase (e.g. CLIENT_ID → clientId, CLIENTID → clientId).
+ * @param {string[]} varSegments - One or two segments (e.g. ['CLIENT', 'ID'], ['CLIENTID'])
+ * @returns {string}
+ */
+function varSegmentsToCamelCase(varSegments) {
+  if (!varSegments || varSegments.length === 0) return '';
+  if (varSegments.length === 1) {
+    const s = varSegments[0].toLowerCase();
+    if (s.endsWith('id') && s.length > 2) return s.slice(0, -2) + 'Id';
+    if (s.endsWith('secret') && s.length > 6) return s.slice(0, -6) + 'Secret';
+    if (s.endsWith('key') && s.length > 3) return s.slice(0, -3) + 'Key';
+    if (s.endsWith('token') && s.length > 5) return s.slice(0, -5) + 'Token';
+    if (s.endsWith('url') && s.length > 3) return s.slice(0, -3) + 'Url';
+    return s;
   }
-  const rest = envKey.slice(KV_PREFIX.length);
+  return varSegments.map((seg, i) => {
+    const lower = seg.toLowerCase();
+    return i === 0 ? lower : lower.charAt(0).toUpperCase() + lower.slice(1);
+  }).join('');
+}
+
+/**
+ * Builds kv path from segments when systemKey is provided (path = kv://systemKey/variable).
+ * @param {string[]} segments - Parsed segments after KV_ prefix
+ * @param {string} systemKey - System key (e.g. 'microsoft-teams')
+ * @returns {string|null}
+ */
+function kvPathWithSystemKey(segments, systemKey) {
+  const prefixInKey = systemKey.replace(/-/g, '_').toUpperCase();
+  const prefixSegs = prefixInKey.split('_').filter(Boolean);
+  if (segments.length <= prefixSegs.length) return null;
+  const prefixMatch = prefixSegs.every((p, i) => segments[i] === p);
+  if (!prefixMatch) return null;
+  const varSegments = segments.slice(prefixSegs.length);
+  const pathVar = varSegmentsToCamelCase(varSegments);
+  return pathVar ? `kv://${systemKey}/${pathVar}` : null;
+}
+
+/**
+ * Builds kv path from segments when systemKey is not provided (infers namespace and variable).
+ * @param {string[]} segments - Parsed segments after KV_ prefix
+ * @returns {string|null}
+ */
+function kvPathInferred(segments) {
+  if (segments.length === 1) return `kv://${segments[0].toLowerCase()}`;
+  const varSegmentCount = (segments.length >= 2 && VAR_SUFFIXES.has(segments[segments.length - 1])) ? 2 : 1;
+  const namespace = segments.slice(0, -varSegmentCount).map(s => s.toLowerCase()).join('-');
+  const varSegments = segments.slice(-varSegmentCount);
+  const pathVar = varSegmentsToCamelCase(varSegments);
+  return (namespace && pathVar) ? `kv://${namespace}/${pathVar}` : null;
+}
+
+/**
+ * Converts KV_* env key to kv:// path in format kv://&lt;system-key&gt;/&lt;variable&gt;.
+ * System-key uses hyphens (e.g. microsoft-teams); variable is camelCase (e.g. clientId).
+ * When systemKey is provided, uses it as the path namespace; otherwise infers from segments.
+ *
+ * @param {string} envKey - Env var name (e.g. KV_MICROSOFT_TEAMS_CLIENT_ID)
+ * @param {string} [systemKey] - Optional system key (e.g. 'microsoft-teams'); when provided, path is kv://systemKey/variable
+ * @returns {string|null} kv:// path or null if invalid
+ */
+function kvEnvKeyToPath(envKey, systemKey) {
+  if (!envKey || typeof envKey !== 'string' || !envKey.toUpperCase().startsWith(KV_PREFIX)) return null;
+  const rest = envKey.slice(KV_PREFIX.length).trim();
   if (!rest) return null;
   const segments = rest.split('_').filter(Boolean);
-  const pathPart = segments.map(s => s.toLowerCase()).join('/');
-  return pathPart ? `kv://${pathPart}` : null;
+  if (segments.length === 0) return null;
+
+  const hasSystemKey = typeof systemKey === 'string' && systemKey.length > 0;
+  if (hasSystemKey) return kvPathWithSystemKey(segments, systemKey);
+  return kvPathInferred(segments);
 }
 
 /**
  * Collects KV_* entries from env map as secret items (key = kv path, value = raw).
- * Does not resolve values; empty values are skipped.
+ * When value is a kv:// path, uses it as the key so it matches payload paths (e.g. kv://microsoft-teams/clientId).
+ * Otherwise derives path from env key via kvEnvKeyToPath(envKey).
  *
  * @param {Object.<string, string>} envMap - Key-value map from .env
  * @returns {Array<{ key: string, value: string }>} Items (key = kv://..., value = raw)
@@ -46,7 +129,11 @@ function collectKvEnvVarsAsSecretItems(envMap) {
   for (const [envKey, rawValue] of Object.entries(envMap)) {
     const value = typeof rawValue === 'string' ? rawValue.trim() : '';
     if (value === '') continue;
-    const kvPath = kvEnvKeyToPath(envKey);
+    let kvPath = null;
+    if (value.startsWith('kv://') && isValidKvPath(value)) {
+      kvPath = value;
+    }
+    if (!kvPath) kvPath = kvEnvKeyToPath(envKey);
     if (!kvPath) continue;
     items.push({ key: kvPath, value });
   }
@@ -70,10 +157,7 @@ function resolveKvValue(secrets, value) {
   const pathMatch = trimmed.match(/^kv:\/\/([a-zA-Z0-9_\-/]+)$/);
   if (!pathMatch) return null;
   const pathKey = pathMatch[1];
-  let resolved = secrets[pathKey];
-  if (resolved === undefined && pathKey.includes('/')) {
-    resolved = secrets[pathKey.replace(/\//g, '-')];
-  }
+  const resolved = secrets[pathKey];
   if (resolved === undefined) return null;
   return typeof resolved === 'string' ? resolved : String(resolved);
 }
@@ -156,10 +240,7 @@ function buildItemsFromPayload(payload, secrets, itemsByKey) {
   for (const ref of refs) {
     if (existingKeys.has(ref)) continue;
     const pathKey = ref.replace(/^kv:\/\//, '');
-    let resolved = secrets[pathKey];
-    if (resolved === undefined && pathKey.includes('/')) {
-      resolved = secrets[pathKey.replace(/\//g, '-')];
-    }
+    const resolved = secrets[pathKey];
     if (resolved !== null && resolved !== undefined && isValidKvPath(ref)) {
       itemsByKey.set(ref, typeof resolved === 'string' ? resolved : String(resolved));
     }
@@ -188,12 +269,14 @@ function storedCountFromResponse(res, fallback) {
 async function sendCredentialSecrets(dataplaneUrl, authConfig, items) {
   try {
     const res = await storeCredentialSecrets(dataplaneUrl, authConfig, items);
-    if (res && res.success === false) {
+    const failed = res && (res.success === false || res.data?.success === false);
+    if (failed) {
       const status = res.status ?? res.statusCode;
       if (status === 403 || status === 401) {
         return { pushed: 0, warning: 'Could not push credential secrets (permission denied or unauthenticated). Ensure dataplane role has credential:create if you use KV_* in .env.' };
       }
-      return { pushed: 0, warning: res.formattedError || res.error || 'Failed to push credential secrets to dataplane.' };
+      const errMsg = res.formattedError || res.data?.formattedError || res.error || res.data?.error || 'Failed to push credential secrets to dataplane.';
+      return { pushed: 0, warning: errMsg };
     }
     return { pushed: storedCountFromResponse(res, items.length) };
   } catch (err) {
@@ -212,7 +295,7 @@ async function sendCredentialSecrets(dataplaneUrl, authConfig, items) {
  * @param {string} [options.envFilePath] - Path to .env (integration/<systemKey>/.env)
  * @param {string} [options.appName] - App/system name for loadSecrets context
  * @param {Object} [options.payload] - Upload payload { application, dataSources } for kv scan
- * @returns {Promise<{ pushed: number, warning?: string }>} Count pushed and optional warning
+ * @returns {Promise<{ pushed: number, keys?: string[], skipped?: boolean, warning?: string }>} Count pushed, keys (on success), skipped (when nothing to push), optional warning
  */
 async function pushCredentialSecrets(dataplaneUrl, authConfig, options = {}) {
   const { envFilePath, appName, payload } = options;
@@ -230,8 +313,12 @@ async function pushCredentialSecrets(dataplaneUrl, authConfig, options = {}) {
     .filter(([k]) => isValidKvPath(k))
     .map(([key, value]) => ({ key, value }));
 
-  if (items.length === 0) return { pushed: 0 };
-  return sendCredentialSecrets(dataplaneUrl, authConfig, items);
+  if (items.length === 0) return { pushed: 0, skipped: true };
+  const sendResult = await sendCredentialSecrets(dataplaneUrl, authConfig, items);
+  if (sendResult.pushed > 0) {
+    sendResult.keys = items.map(i => i.key.replace(/^kv:\/\//, ''));
+  }
+  return sendResult;
 }
 
 /**
@@ -262,6 +349,9 @@ module.exports = {
   collectKvRefsFromPayload,
   pushCredentialSecrets,
   kvEnvKeyToPath,
+  systemKeyToKvPrefix,
+  securityKeyToVar,
   isValidKvPath,
-  resolveKvValue
+  resolveKvValue,
+  parseEnvToMap
 };

package/lib/utils/dataplane-pipeline-warning.js

@@ -0,0 +1,28 @@
+/**
+ * Shared warning message for Dataplane pipeline API usage (upload / validate / publish).
+ * Used by upload command and datasource upload so users know configuration is sent to Dataplane.
+ *
+ * @fileoverview Dataplane pipeline usage warning
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('./logger');
+
+/** Message shown when CLI is about to call Dataplane pipeline upload or publish APIs. */
+const DATAPLANE_PIPELINE_WARNING =
+  'Configuration will be sent to the Dataplane pipeline API. Ensure you are targeting the correct environment and have the required permissions.';
+
+/**
+ * Log the Dataplane pipeline warning (yellow) to the console.
+ * Call before uploadApplicationViaPipeline or publishDatasourceViaPipeline.
+ */
+function logDataplanePipelineWarning() {
+  logger.log(chalk.yellow(`⚠ ${DATAPLANE_PIPELINE_WARNING}`));
+}
+
+module.exports = {
+  DATAPLANE_PIPELINE_WARNING,
+  logDataplanePipelineWarning
+};

package/lib/utils/deployment-validation-helpers.js

@@ -34,7 +34,7 @@ function processSuccessfulValidation(responseData) {
 function processValidationFailure(responseData) {
   const errorMessage = responseData.errors && responseData.errors.length > 0
     ? `Validation failed: ${responseData.errors.join(', ')}`
-    : 'Validation failed: Invalid configuration';
+    : (responseData.error || responseData.formattedError || 'Validation failed: Invalid configuration');
   const error = new Error(errorMessage);
   error.status = 400;
   error.data = responseData;
@@ -78,13 +78,13 @@ function handleValidationResponse(response) {
     if (responseData.valid === true) {
       return processSuccessfulValidation(responseData);
     }
-    // Handle validation failure (valid: false)
-    if (responseData.valid === false) {
+    // Handle validation failure (valid: false or success: false in body)
+    if (responseData.valid === false || responseData.success === false) {
       processValidationFailure(responseData);
     }
   }
 
-  // Handle validation errors (non-success responses)
+  // Handle validation errors (non-success HTTP responses)
   if (!response.success) {
     processValidationError(response);
   }

package/lib/utils/dev-ca-install.js

@@ -0,0 +1,139 @@
+/**
+ * Dev CA Install – SSL untrusted detection, fetch CA from Builder Server, install into OS trust store.
+ * Used by `aifabrix dev init` when the server certificate is self-signed. Only /install-ca uses
+ * rejectUnauthorized: false; all other requests use default TLS verification.
+ *
+ * @fileoverview CA install utilities for development Builder Server
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const https = require('https');
+const os = require('os');
+const { execFileSync } = require('child_process');
+const readline = require('readline');
+const chalk = require('chalk');
+
+const SSL_UNTRUSTED_CODES = [
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'DEPTH_ZERO_SELF_SIGNED_CERT',
+  'CERT_UNTRUSTED',
+  'SELF_SIGNED_CERT_IN_CHAIN',
+  'UNABLE_TO_GET_ISSUER_CERT',
+  'UNABLE_TO_GET_ISSUER_CERT_LOCALLY'
+];
+
+/**
+ * Returns true if the error indicates an untrusted/self-signed server certificate.
+ * @param {Error} err - Thrown error (e.g. from devApi.getHealth)
+ * @returns {boolean}
+ */
+function isSslUntrustedError(err) {
+  const code = err?.code || err?.cause?.code;
+  const msg = (err?.message || '').toUpperCase();
+  return SSL_UNTRUSTED_CODES.some(c => code === c || msg.includes(c));
+}
+
+/**
+ * Fetch CA PEM from Builder Server via GET {baseUrl}/install-ca.
+ * Uses rejectUnauthorized: false only for this endpoint (dev setup).
+ * @param {string} baseUrl - Builder Server base URL (no trailing slash)
+ * @returns {Promise<Buffer>} CA certificate PEM
+ */
+function fetchInstallCa(baseUrl) {
+  return new Promise((resolve, reject) => {
+    const url = `${baseUrl.replace(/\/+$/, '')}/install-ca`;
+    const urlObj = new URL(url);
+    if (urlObj.protocol !== 'https:') {
+      reject(new Error('install-ca requires https URL'));
+      return;
+    }
+    const agent = new https.Agent({ rejectUnauthorized: false });
+    const req = https.get(
+      url,
+      { agent },
+      (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          req.destroy();
+          fetchInstallCa(res.headers.location).then(resolve).catch(reject);
+          return;
+        }
+        const chunks = [];
+        res.on('data', c => chunks.push(c));
+        res.on('end', () => {
+          const body = Buffer.concat(chunks).toString('utf8');
+          if (!body || !body.includes('-----BEGIN CERTIFICATE-----')) {
+            reject(new Error('Invalid CA response: expected PEM certificate'));
+            return;
+          }
+          resolve(Buffer.from(body, 'utf8'));
+        });
+      }
+    );
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Install CA PEM into OS trust store (platform-specific).
+ * @param {Buffer|string} caPem - CA certificate PEM
+ * @param {string} baseUrl - Builder Server base URL (for help link)
+ * @returns {Promise<void>}
+ */
+async function installCaPlatform(caPem, baseUrl) {
+  const pem = Buffer.isBuffer(caPem) ? caPem.toString('utf8') : String(caPem);
+  const tmpDir = os.tmpdir();
+  const tmpPath = path.join(tmpDir, 'aifabrix-root-ca.crt');
+  await fs.writeFile(tmpPath, pem, { mode: 0o644 });
+
+  try {
+    if (process.platform === 'win32') {
+      execFileSync('certutil', ['-addstore', '-user', 'ROOT', tmpPath], { stdio: 'inherit' });
+    } else if (process.platform === 'darwin') {
+      const keychain = path.join(os.homedir(), 'Library', 'Keychains', 'login.keychain-db');
+      execFileSync('security', ['add-trusted-cert', '-d', '-r', 'trustRoot', '-k', keychain, tmpPath], { stdio: 'inherit' });
+    } else if (process.platform === 'linux') {
+      const certPath = '/usr/local/share/ca-certificates/aifabrix-root-ca.crt';
+      try {
+        await fs.writeFile(certPath, pem, { mode: 0o644 });
+        execFileSync('update-ca-certificates', [], { stdio: 'inherit' });
+      } catch (e) {
+        if (e.code === 'EACCES' || (e.status !== undefined && e.status !== null && e.status !== 0)) {
+          const helpUrl = `${baseUrl.replace(/\/+$/, '')}/install-ca-help`;
+          throw new Error(
+            `Linux CA install requires sudo. Save CA manually from ${helpUrl} to ${certPath} and run: sudo update-ca-certificates`
+          );
+        }
+        throw e;
+      }
+    } else {
+      throw new Error(`Unsupported platform: ${process.platform}`);
+    }
+  } finally {
+    await fs.unlink(tmpPath).catch(() => {});
+  }
+}
+
+/**
+ * Prompt user: "Download and install the development CA? (y/n)"
+ * @returns {Promise<boolean>}
+ */
+function promptInstallCa() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(chalk.yellow('Server certificate not trusted. Download and install the development CA? (y/n) '), answer => {
+      rl.close();
+      const normalized = (answer || '').trim().toLowerCase();
+      resolve(normalized === 'y' || normalized === 'yes');
+    });
+  });
+}
+
+module.exports = {
+  isSslUntrustedError,
+  fetchInstallCa,
+  installCaPlatform,
+  promptInstallCa
+};