@aifabrix/builder 2.43.0 → 2.44.1

package/lib/generator/helpers.js

@@ -11,6 +11,7 @@
 const fs = require('fs');
 const path = require('path');
 const { loadConfigFile } = require('../utils/config-format');
+const { urlTokenToKeyVaultSecretName } = require('./deploy-manifest-azure-kv');
 
 /**
  * Loads application config file (application.yaml, application.json, or legacy path) via converter.
@@ -218,6 +219,9 @@ function determineVariableLocation(value, key) {
   if (value.startsWith('kv://')) {
     location = 'keyvault';
     required = true;
+  } else if (value.startsWith('url://')) {
+    location = 'keyvault';
+    required = true;
   }
 
   // Check if it's a sensitive variable
@@ -229,6 +233,31 @@ function determineVariableLocation(value, key) {
   return { location, required };
 }
 
+/**
+ * Maps env.template url:// value(s) to Key Vault secret name(s) for deploy JSON.
+ * Comma-separated lists are supported (e.g. CORS ALLOWED_ORIGINS): each segment
+ * starting with url:// is mapped; other segments are left unchanged (e.g. http://localhost:*).
+ *
+ * @param {string} appKey - application.yaml app.key
+ * @param {string} value - Full value after KEY= (must start with url:// for caller)
+ * @returns {string} Comma-joined secret names / literals
+ */
+function mapUrlTemplateValueToKeyVaultNames(appKey, value) {
+  const segments = value
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  return segments
+    .map((seg) => {
+      if (seg.startsWith('url://')) {
+        const token = seg.slice('url://'.length).trim();
+        return urlTokenToKeyVaultSecretName(appKey, token);
+      }
+      return seg;
+    })
+    .join(',');
+}
+
 /**
  * Creates a configuration item from parsed variable
  * @function createConfigItem
@@ -237,12 +266,27 @@ function determineVariableLocation(value, key) {
  * @param {string} location - Variable location
  * @param {boolean} required - Whether variable is required
  * @param {Map} portalInputMap - Map of portalInput configurations
+ * @param {string|null} appKey - application.yaml app.key (required when value uses url://)
  * @returns {Object} Configuration item
  */
-function createConfigItem(key, value, location, required, portalInputMap) {
+function createConfigItem(key, value, location, required, portalInputMap, appKey) {
+  let storedValue = value;
+  if (location === 'keyvault') {
+    if (value.startsWith('kv://')) {
+      storedValue = value.replace('kv://', '');
+    } else if (value.startsWith('url://')) {
+      if (!appKey) {
+        throw new Error(
+          `Cannot resolve ${key}=${value}: application app.key is required to map url:// to a Key Vault secret name`
+        );
+      }
+      storedValue = mapUrlTemplateValueToKeyVaultNames(appKey, value);
+    }
+  }
+
   const configItem = {
     name: key,
-    value: value.replace('kv://', ''), // Remove kv:// prefix for KeyVault
+    value: storedValue,
     location,
     required
   };
@@ -259,6 +303,10 @@ function parseEnvironmentVariables(envTemplate, variablesConfig = null) {
   const configuration = [];
   const lines = envTemplate.split('\n');
   const portalInputMap = createPortalInputMap(variablesConfig);
+  const appKey =
+    variablesConfig && variablesConfig.app && variablesConfig.app.key
+      ? String(variablesConfig.app.key).trim()
+      : null;
 
   for (const line of lines) {
     const parsed = parseEnvironmentVariableLine(line);
@@ -267,7 +315,14 @@ function parseEnvironmentVariables(envTemplate, variablesConfig = null) {
     }
 
     const { location, required } = determineVariableLocation(parsed.value, parsed.key);
-    const configItem = createConfigItem(parsed.key, parsed.value, location, required, portalInputMap);
+    const configItem = createConfigItem(
+      parsed.key,
+      parsed.value,
+      location,
+      required,
+      portalInputMap,
+      appKey
+    );
     configuration.push(configItem);
   }
 

package/lib/generator/index.js

@@ -22,6 +22,7 @@ const { generateControllerManifest } = require('./external-controller-manifest')
 const { resolveVersionForApp } = require('../utils/image-version');
 const { getContainerPort } = require('../utils/port-resolver');
 const { buildEnvVarMap } = require('../utils/env-map');
+const { rewriteFrontDoorHostForAzureDeploy } = require('./deploy-manifest-azure-kv');
 
 /**
  * Generates deployment JSON from application configuration files
@@ -191,6 +192,8 @@ function buildAndValidateDeployment(appName, variables, envTemplate, rbac, optio
     substituteEnvVarsInDeployment(deployment, envVarMap);
   }
 
+  rewriteFrontDoorHostForAzureDeploy(deployment);
+
   // Ensure no other ${...} placeholders remain in manifest
   _validator.validateNoUnresolvedVariablesInDeployment(deployment);
 
@@ -236,6 +239,7 @@ async function buildDeploymentManifestInMemory(appName, options = {}) {
   }
   const envVarMap = await buildEnvVarMap('docker', null, null, { appPort: effectivePort });
   substituteEnvVarsInDeployment(deployment, envVarMap);
+  rewriteFrontDoorHostForAzureDeploy(deployment);
   _validator.validateNoUnresolvedVariablesInDeployment(deployment);
   return { deployment, appPath };
 }

package/lib/generator/split-readme.js

@@ -13,10 +13,15 @@ const { parseImageReference } = require('./parse-image');
  * @param {Object} deployment - Deployment JSON object
  * @returns {{ appName: string, config: Object }}
  */
-function buildReadmeConfigForExternal(deployment) {
+function buildReadmeConfigForExternal(deployment, options = {}) {
   const system = deployment.system;
   const appName = system.key || deployment.key || 'external-system';
   const dataSources = deployment.dataSources || deployment.datasources || [];
+  const rawExt = options.fileExt;
+  const fileExt =
+    rawExt !== undefined && rawExt !== null && String(rawExt).trim() !== ''
+      ? (String(rawExt).startsWith('.') ? String(rawExt) : `.${String(rawExt)}`)
+      : '.json';
   return {
     appName,
     config: {
@@ -25,7 +30,7 @@ function buildReadmeConfigForExternal(deployment) {
       systemType: system.type || 'openapi',
       systemDisplayName: system.displayName || appName,
       systemDescription: system.description || `External system integration for ${appName}`,
-      fileExt: '.yaml',
+      fileExt,
       datasourceCount: dataSources.length,
       datasources: dataSources
     }
@@ -49,7 +54,7 @@ function buildReadmeConfigForApp(deployment) {
     displayName: deployment.displayName,
     description: deployment.description,
     port,
-    build: { localPort: port },
+    build: {},
     image: { name: imageName, registry },
     registry,
     database: deployment.requiresDatabase,
@@ -80,9 +85,9 @@ function buildReadmeConfigForApp(deployment) {
  * @param {Object} deployment - Deployment JSON object
  * @returns {{ appName: string, config: Object }}
  */
-function buildReadmeConfigFromDeployment(deployment) {
+function buildReadmeConfigFromDeployment(deployment, options = {}) {
   if (deployment.system && typeof deployment.system === 'object') {
-    return buildReadmeConfigForExternal(deployment);
+    return buildReadmeConfigForExternal(deployment, options);
   }
   return buildReadmeConfigForApp(deployment);
 }
@@ -92,11 +97,11 @@ function buildReadmeConfigFromDeployment(deployment) {
  * @param {Object} deployment - Deployment JSON object
  * @returns {string} README.md content
  */
-function generateReadmeFromDeployJson(deployment) {
+function generateReadmeFromDeployJson(deployment, options = {}) {
   if (!deployment || typeof deployment !== 'object') {
     throw new Error('Deployment object is required');
   }
-  const { appName, config } = buildReadmeConfigFromDeployment(deployment);
+  const { appName, config } = buildReadmeConfigFromDeployment(deployment, options);
   return generateReadmeMd(appName, config);
 }
 

package/lib/generator/split-variables.js

@@ -56,7 +56,8 @@ function extractOptionalSections(deployment) {
   const optional = {};
   const names = [
     'healthCheck', 'authentication', 'build', 'repository', 'deployment',
-    'startupCommand', 'runtimeVersion', 'scaling', 'frontDoorRouting'
+    'startupCommand', 'runtimeVersion', 'scaling', 'frontDoorRouting',
+    'environmentScopedResources'
   ];
   for (const sectionName of names) {
     extractOptionalSection(deployment, sectionName, optional);

package/lib/generator/split.js

@@ -440,7 +440,7 @@ async function splitDeployJson(deployJsonPath, outputDir = null, splitOptions =
 
   const variables = extractVariablesYaml(deployment);
   const rbac = extractRbacYaml(deployment);
-  const readme = generateReadmeFromDeployJson(deployment);
+  const readme = generateReadmeFromDeployJson(deployment, { fileExt: '.yaml' });
 
   const result = await writeComponentFiles(finalOutputDir, envTemplate, variables, rbac, readme, writeOptions);
   await applyExternalSystemFilesToResult(finalOutputDir, deployment, result);

package/lib/generator/wizard-readme.js

@@ -6,10 +6,10 @@
  */
 
 'use strict';
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 
 const fs = require('fs').promises;
 const path = require('path');
-const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { generateExternalReadmeContent } = require('../utils/external-readme');
 
@@ -48,7 +48,7 @@ async function generateReadme(options) {
 
     if (aiGeneratedContent) {
       await fs.writeFile(readmePath, aiGeneratedContent, 'utf8');
-      logger.log(chalk.green('✓ Generated README.md (AI-generated from dataplane)'));
+      logger.log(formatSuccessLine('Generated README.md (AI-generated from dataplane)'));
       return;
     }
 
@@ -82,7 +82,7 @@ async function generateReadme(options) {
     });
 
     await fs.writeFile(readmePath, readmeContent, 'utf8');
-    logger.log(chalk.green('✓ Generated README.md (template)'));
+    logger.log(formatSuccessLine('Generated README.md (template)'));
   } catch (error) {
     throw new Error(`Failed to generate README.md: ${error.message}`);
   }

package/lib/generator/wizard.js

@@ -8,10 +8,10 @@
  * PASSWORD, BASEURL. See docs/external-systems.md and docs/wizard.md.
  */
 
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 const fs = require('fs').promises;
 const path = require('path');
 const Handlebars = require('handlebars');
-const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
@@ -61,7 +61,7 @@ async function writeSystemYamlFile(appPath, finalSystemKey, systemConfig, format
   const systemFileName = `${finalSystemKey}-system${ext}`;
   const systemFilePath = path.join(appPath, systemFileName);
   writeConfigFile(systemFilePath, systemConfig, format === 'json' ? 'json' : 'yaml');
-  logger.log(chalk.green(`✓ Generated system file: ${systemFileName}`));
+  logger.log(formatSuccessLine(`Generated system file: ${systemFileName}`));
   return systemFilePath;
 }
 
@@ -97,7 +97,7 @@ async function writeDatasourceYamlFiles(appPath, finalSystemKey, datasourceConfi
     const datasourceFilePath = path.join(appPath, datasourceFileName);
     writeConfigFile(datasourceFilePath, datasourceConfig, fmt);
     datasourceFileNames.push(datasourceFileName);
-    logger.log(chalk.green(`✓ Generated datasource file: ${datasourceFileName}`));
+    logger.log(formatSuccessLine(`Generated datasource file: ${datasourceFileName}`));
   }
   return datasourceFileNames;
 }
@@ -135,7 +135,7 @@ async function generateConfigFilesForWizard(params) {
   const envTemplatePath = path.join(appPath, 'env.template');
   const envTemplateContent = generateExternalEnvTemplateContent(systemConfig);
   await fs.writeFile(envTemplatePath, envTemplateContent, 'utf8');
-  logger.log(chalk.green('✓ Generated env.template'));
+  logger.log(formatSuccessLine('Generated env.template'));
 
   try {
     const secretsEnsure = require('../core/secrets-ensure');
@@ -164,7 +164,7 @@ async function generateConfigFilesForWizard(params) {
   const deployJson = toDeployJsonShape(manifest);
   const deployManifestPath = path.join(appPath, `${finalSystemKey}-deploy.json`);
   await fs.writeFile(deployManifestPath, JSON.stringify(deployJson, null, 2), 'utf8');
-  logger.log(chalk.green(`✓ Generated deployment manifest: ${finalSystemKey}-deploy.json`));
+  logger.log(formatSuccessLine(`Generated deployment manifest: ${finalSystemKey}-deploy.json`));
 
   return {
     variablesPath: configPath,
@@ -293,7 +293,7 @@ async function generateOrUpdateVariablesYaml(params) {
       const fsSync = require('fs');
       if (fsSync.existsSync(configPath)) fsSync.unlinkSync(configPath);
     }
-    logger.log(chalk.green(`✓ Generated/updated application${ext}`));
+    logger.log(formatSuccessLine(`Generated/updated application${ext}`));
     return targetPath;
   } catch (error) {
     throw new Error(`Failed to generate application config: ${error.message}`);
@@ -417,7 +417,7 @@ async function _generateEnvTemplate(appPath, systemConfig, finalSystemKey) {
     addBaseUrlLines(lines, systemConfig);
 
     await fs.writeFile(envTemplatePath, lines.join('\n'), 'utf8');
-    logger.log(chalk.green('✓ Generated env.template'));
+    logger.log(formatSuccessLine('Generated env.template'));
   } catch (error) {
     throw new Error(`Failed to generate env.template: ${error.message}`);
   }
@@ -440,7 +440,7 @@ async function writeDeployScriptFromTemplate(templateName, outputPath, context)
   const templatePath = path.join(templatesExternalDir, templateName);
   const content = Handlebars.compile(await fs.readFile(templatePath, 'utf8'))(context);
   await fs.writeFile(outputPath, content, 'utf8');
-  logger.log(chalk.green(`✓ Generated ${path.basename(outputPath)}`));
+  logger.log(formatSuccessLine(`Generated ${path.basename(outputPath)}`));
 }
 
 async function generateDeployScripts(appPath, systemKey, systemFileName, datasourceFileNames) {

package/lib/infrastructure/compose.js

@@ -12,6 +12,32 @@ const fs = require('fs');
 const handlebars = require('handlebars');
 const path = require('path');
 
+/**
+ * Normalize a host path for Docker Compose bind mounts. Docker Desktop sends
+ * mounts to a Linux VM; backslashes in Windows paths yield "invalid volume
+ * specification" from the daemon.
+ *
+ * On Windows, Compose often forwards binds as "SOURCE:TARGET:rw". A SOURCE
+ * like "C:/Users/..." is split at the first colon, so the engine must receive
+ * paths in Linux-VM form (e.g. "/c/Users/...") instead.
+ *
+ * @param {string} fsPath - Host path (absolute or relative)
+ * @returns {string} Path with forward slashes, resolved when relative
+ */
+function toDockerBindMountSource(fsPath) {
+  if (!fsPath || typeof fsPath !== 'string') {
+    return fsPath;
+  }
+  let resolved = path.resolve(fsPath).split(path.sep).join('/');
+  if (process.platform === 'win32') {
+    const drive = /^([a-zA-Z]):(\/.*)$/.exec(resolved);
+    if (drive) {
+      resolved = `/${drive[1].toLowerCase()}${drive[2]}`;
+    }
+  }
+  return resolved;
+}
+
 /**
  * Builds Traefik configuration from environment variables
  * @param {boolean} enabled - Whether Traefik should be included
@@ -22,7 +48,8 @@ function buildTraefikConfig(enabled) {
     enabled: !!enabled,
     certStore: process.env.TRAEFIK_CERT_STORE || null,
     certFile: process.env.TRAEFIK_CERT_FILE || null,
-    keyFile: process.env.TRAEFIK_KEY_FILE || null
+    keyFile: process.env.TRAEFIK_KEY_FILE || null,
+    trustForwardedHeaders: false
   };
 }
 
@@ -40,13 +67,23 @@ function validateTraefikConfig(traefikConfig) {
 
   if (traefikConfig.certStore) {
     if (!traefikConfig.certFile || !traefikConfig.keyFile) {
-      errors.push('TRAEFIK_CERT_FILE and TRAEFIK_KEY_FILE are required when TRAEFIK_CERT_STORE is set');
+      errors.push(
+        'TLS is enabled for Traefik but certificate files are missing or invalid. ' +
+          'Set TRAEFIK_CERT_FILE and TRAEFIK_KEY_FILE (and TRAEFIK_CERT_STORE if used) to your local cert and key, ' +
+          'or disable TLS in application/frontDoorRouting for local development.'
+      );
     } else {
       if (!fs.existsSync(traefikConfig.certFile)) {
-        errors.push(`Certificate file not found: ${traefikConfig.certFile}`);
+        errors.push(
+          'TLS is enabled for Traefik but certificate files are missing or invalid. ' +
+            `Certificate file not found: ${traefikConfig.certFile}`
+        );
       }
       if (!fs.existsSync(traefikConfig.keyFile)) {
-        errors.push(`Private key file not found: ${traefikConfig.keyFile}`);
+        errors.push(
+          'TLS is enabled for Traefik but certificate files are missing or invalid. ' +
+            `Private key file not found: ${traefikConfig.keyFile}`
+        );
       }
     }
   }
@@ -72,16 +109,39 @@ function generateComposeFile(templatePath, devId, idNum, ports, infraDir, option
   const template = handlebars.compile(templateContent);
   const networkName = idNum === 0 ? 'infra-aifabrix-network' : `infra-dev${devId}-aifabrix-network`;
   const serversJsonPath = path.join(infraDir, 'servers.json');
+  const serversJsonBind = toDockerBindMountSource(serversJsonPath);
   const pgpassPath = path.join(infraDir, 'pgpass');
   const traefikConfig = typeof options.traefik === 'object'
     ? options.traefik
     : buildTraefikConfig(!!options.traefik);
-  const pgadminConfig = options.pgadmin && typeof options.pgadmin.enabled === 'boolean'
+  const pgadminConfigRaw = options.pgadmin && typeof options.pgadmin.enabled === 'boolean'
     ? options.pgadmin
     : { enabled: true };
+  const pgadminEnabled = !!pgadminConfigRaw.enabled;
+  const pgpassBootstrapPath = path.join(infraDir, '.pgpass.bootstrap');
+  const pgadminConfig = {
+    ...pgadminConfigRaw,
+    enabled: pgadminEnabled,
+    ...(pgadminEnabled
+      ? { pgpassBootstrapBind: toDockerBindMountSource(pgpassBootstrapPath) }
+      : {})
+  };
   const redisCommanderConfig = options.redisCommander && typeof options.redisCommander.enabled === 'boolean'
     ? options.redisCommander
     : { enabled: true };
+  const traefikForCompose = traefikConfig && typeof traefikConfig === 'object'
+    ? {
+      ...traefikConfig,
+      trustForwardedHeaders: !!traefikConfig.trustForwardedHeaders,
+      ...(traefikConfig.certFile
+        ? { certFile: toDockerBindMountSource(traefikConfig.certFile) }
+        : {}),
+      ...(traefikConfig.keyFile
+        ? { keyFile: toDockerBindMountSource(traefikConfig.keyFile) }
+        : {})
+    }
+    : traefikConfig;
+  const initScriptsBind = toDockerBindMountSource(path.join(infraDir, 'init-scripts'));
   const composeContent = template({
     devId: devId,
     postgresPort: ports.postgres,
@@ -92,9 +152,11 @@ function generateComposeFile(templatePath, devId, idNum, ports, infraDir, option
     traefikHttpsPort: ports.traefikHttps,
     networkName: networkName,
     serversJsonPath: serversJsonPath,
+    serversJsonBind: serversJsonBind,
     pgpassPath: pgpassPath,
     infraDir: infraDir,
-    traefik: traefikConfig,
+    initScriptsBind: initScriptsBind,
+    traefik: traefikForCompose,
     pgadmin: pgadminConfig,
     redisCommander: redisCommanderConfig
   });
@@ -106,5 +168,6 @@ function generateComposeFile(templatePath, devId, idNum, ports, infraDir, option
 module.exports = {
   buildTraefikConfig,
   validateTraefikConfig,
-  generateComposeFile
+  generateComposeFile,
+  toDockerBindMountSource
 };

package/lib/infrastructure/helpers-docker-check.js

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Docker / Compose availability check and user-facing failure text for infra helpers.
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const dockerUtils = require('../utils/docker');
+const { ensureDevCertsIfNeededForRemoteDocker } = require('../utils/ensure-dev-certs-for-remote-docker');
+
+/**
+ * User-facing error when Docker/Compose checks fail (tailored by underlying message).
+ * @param {string} detail - Error message from ensureDockerAndCompose / Docker CLI
+ * @returns {string}
+ */
+function formatDockerInfrastructureFailure(detail) {
+  const cause = (detail || '').trim() || 'unknown error';
+
+  if (/Docker Compose is not available/i.test(cause)) {
+    return (
+      'Cannot use Docker for infrastructure: Docker Compose check failed (see Cause below).\n\n' +
+      `Cause: ${cause}\n\n` +
+      'If Cause mentions TLS, certificate, or handshake, fix client TLS for docker-endpoint (cert.pem, key.pem, ca.pem under ~/.aifabrix/certs/<developer-id>/) or docker-tls-skip-verify when appropriate. ' +
+      'If Cause suggests a missing plugin, install Docker Compose v2 for your user (docker CLI + plugin; no unix socket needed when using tcp:// docker-endpoint). ' +
+      'Or set AIFABRIX_COMPOSE_CMD. Run `aifabrix doctor` for diagnostics.'
+    );
+  }
+
+  if (/AIFABRIX_COMPOSE_CMD/i.test(cause) && /is set but failed/i.test(cause)) {
+    return (
+      'Cannot use Docker for infrastructure: AIFABRIX_COMPOSE_CMD failed.\n\n' +
+      `Cause: ${cause}\n\n` +
+      'Unset or fix AIFABRIX_COMPOSE_CMD, or install a working Compose. Run `aifabrix doctor` for diagnostics.'
+    );
+  }
+
+  return (
+    'Cannot use Docker for infrastructure (Docker CLI missing, Compose missing, or remote Docker misconfigured).\n\n' +
+    `Cause: ${cause}\n\n` +
+    'Install Docker Engine and Compose on this machine (or set AIFABRIX_COMPOSE_CMD). ' +
+    'If you use docker-endpoint in dev config: install cert.pem, key.pem, and ca.pem for full TLS verify; use `aifabrix dev pin` / ' +
+    '`dev init --pin` as needed; or enable TLS skip-verify (config or AIFABRIX_DOCKER_TLS_SKIP_VERIFY) when appropriate. ' +
+    'Run `aifabrix doctor` for diagnostics.'
+  );
+}
+
+/**
+ * Check Docker availability (local daemon or remote via docker-endpoint + TLS).
+ * @async
+ * @returns {Promise<void>}
+ * @throws {Error} If Docker/Compose cannot be used (includes underlying cause)
+ */
+async function checkDockerAvailability() {
+  await ensureDevCertsIfNeededForRemoteDocker();
+  try {
+    await dockerUtils.ensureDockerAndCompose();
+  } catch (error) {
+    const detail = (error && error.message) || String(error);
+    throw new Error(formatDockerInfrastructureFailure(detail));
+  }
+}
+
+module.exports = {
+  formatDockerInfrastructureFailure,
+  checkDockerAvailability
+};