@aifabrix/builder 2.44.6 → 2.45.5

package/lib/utils/env-copy.js

@@ -11,6 +11,7 @@ const { formatSuccessLine } = require('./cli-test-layout-chalk');
 
 const fs = require('fs');
 const fsp = require('fs').promises;
+const fsRealSync = require('../internal/fs-real-sync');
 const path = require('path');
 const yaml = require('js-yaml');
 const logger = require('./logger');
@@ -98,22 +99,37 @@ function resolveEnvOutputPath(rawOutputPath, variablesPath) {
 }
 
 /**
- * Writes .env to envOutputPath for reload path: merge run .env into existing file.
+ * Writes .env to envOutputPath for `--reload`: merge container `.env.run` into the host file.
+ * Preserves comments when a file already exists (e.g. after `aifabrix resolve`). Keys present only
+ * in `.env.run` (compose-only such as DB_0_NAME) are **not** appended unless they already exist as
+ * `KEY=` lines in the base file. If the output file is missing, seeds from `generateEnvContent`
+ * (`local`) so the host file keeps template comments and localhost-oriented URLs.
+ *
  * @async
  * @param {string} outputPath - Resolved output path
  * @param {string} runEnvPath - Path to .env.run
+ * @param {string} appName - Application name (for template seed when output is absent)
  */
-async function writeEnvOutputForReload(outputPath, runEnvPath) {
-  const { parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
+async function writeEnvOutputForReload(outputPath, runEnvPath, appName) {
+  const { parseEnvContentToMap, mergeEnvMapIntoContent, generateEnvContent } = require('../core/secrets');
   const runContent = await fsp.readFile(runEnvPath, 'utf8');
   const runMap = parseEnvContentToMap(runContent);
-  let toWrite = runContent;
-  if (fs.existsSync(outputPath)) {
-    const existingContent = await fsp.readFile(outputPath, 'utf8');
-    toWrite = mergeEnvMapIntoContent(existingContent, runMap);
+  let baseContent;
+  if (fsRealSync.existsSync(outputPath)) {
+    baseContent = await fsp.readFile(outputPath, 'utf8');
+  } else if (appName) {
+    baseContent = await generateEnvContent(appName, null, 'local', false);
+    baseContent = substituteMntDataForLocal(baseContent, outputPath);
+  } else {
+    baseContent = runContent;
   }
+  const toWrite = mergeEnvMapIntoContent(baseContent, runMap, { appendMissingFromNewMap: false });
   await fsp.writeFile(outputPath, toWrite, { mode: 0o600 });
-  logger.log(formatSuccessLine(`Wrote .env to envOutputPath (same as container, for --reload): ${outputPath}`));
+  logger.log(
+    formatSuccessLine(
+      `Wrote .env to envOutputPath (--reload: merged container env; no extra keys): ${outputPath}`
+    )
+  );
 }
 
 /**
@@ -245,6 +261,30 @@ async function patchEnvContentForLocal(envContent, variables) {
   return envContent;
 }
 
+/**
+ * Copy the just-written builder `<appPath>/.env` to `build.envOutputPath` so both files
+ * share the same resolution pass (no second `generateEnvContent` with a different environment).
+ * Applies {@link substituteMntDataForLocal} for host paths; merges into an existing output file
+ * when present (preserves comments).
+ *
+ * @async
+ * @param {string} envPath - Path to `<appPath>/.env` (already written)
+ * @param {string} outputPath - Resolved `build.envOutputPath`
+ * @param {string} envOutputPathLabel - Label for log (e.g. raw `build.envOutputPath` value)
+ */
+async function syncWrittenBuilderEnvToOutputPath(envPath, outputPath, envOutputPathLabel) {
+  const { parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
+  const raw = fs.readFileSync(envPath, 'utf8');
+  const synced = substituteMntDataForLocal(raw, outputPath);
+  let toWrite = synced;
+  if (fs.existsSync(outputPath)) {
+    const existingContent = fs.readFileSync(outputPath, 'utf8');
+    toWrite = mergeEnvMapIntoContent(existingContent, parseEnvContentToMap(synced));
+  }
+  fs.writeFileSync(outputPath, toWrite, { mode: 0o600 });
+  logger.log(formatSuccessLine(`Copied resolved .env to envOutputPath (${envOutputPathLabel})`));
+}
+
 /**
  * Write regenerated local .env to output path (merge with existing if present).
  * @async
@@ -252,10 +292,12 @@ async function patchEnvContentForLocal(envContent, variables) {
  * @param {string} appName - Application name
  * @param {string} [secretsPath] - Path to secrets file (optional)
  * @param {string} envOutputPathLabel - Label for log message (e.g. variables.build.envOutputPath)
+ * @param {Object} [extraOpts] - Optional: `appPath` for {@link module:lib/core/secrets-env-content.generateEnvContent}
  */
-async function writeLocalEnvToOutputPath(outputPath, appName, secretsPath, envOutputPathLabel) {
+async function writeLocalEnvToOutputPath(outputPath, appName, secretsPath, envOutputPathLabel, extraOpts = {}) {
   const { generateEnvContent, parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
-  let localEnvContent = await generateEnvContent(appName, secretsPath, 'local', false);
+  const genOpts = extraOpts.appPath ? { appPath: extraOpts.appPath } : {};
+  let localEnvContent = await generateEnvContent(appName, secretsPath, 'local', false, genOpts);
   localEnvContent = substituteMntDataForLocal(localEnvContent, outputPath);
   let toWrite = localEnvContent;
   if (fs.existsSync(outputPath)) {
@@ -284,16 +326,45 @@ async function writePatchedEnvToOutputPath(envPath, outputPath, variables, envOu
 }
 
 /**
- * Process and optionally copy env file to envOutputPath if configured
- * Regenerates .env file with env=local for local development (apps/.env)
+ * Process and optionally copy env file to envOutputPath if configured.
+ * When `appName` is set and `preferLocalEnvOutputPath` is true, regenerates **local**-flavored env at
+ * `build.envOutputPath` (IDE/host). **False** only when `remote-server` and `applications.<app>.reload` are both set
+ * (docker flavor at env output). Otherwise, when `appName`
+ * is set and `envPath` exists, copies the same resolved `<appPath>/.env` content to the output path.
+ * Falls back to local regeneration when `envPath` is missing, or patched copy when `appName` is omitted.
+ *
  * @async
  * @function processEnvVariables
  * @param {string} envPath - Path to generated .env file
  * @param {string} variablesPath - Path to application config
  * @param {string} appName - Application name (for regenerating with local env)
  * @param {string} [secretsPath] - Path to secrets file (optional, for regenerating)
+ * @param {Object} [copyOptions] - Optional: `preferLocalEnvOutputPath` (IDE/host file gets **local** flavor
+ *   while `<appPath>/.env` may be docker); `appPath` overrides app root for local regeneration
  */
-async function processEnvVariables(envPath, variablesPath, appName, secretsPath) {
+async function copyOrRegenerateEnvForNamedApp(opts) {
+  const {
+    envPath,
+    outputPath,
+    appName,
+    secretsPath,
+    label,
+    preferLocal,
+    appPathForLocal
+  } = opts;
+  const localOpts = { appPath: appPathForLocal || undefined };
+  if (preferLocal) {
+    await writeLocalEnvToOutputPath(outputPath, appName, secretsPath, label, localOpts);
+    return;
+  }
+  if (fs.existsSync(envPath)) {
+    await syncWrittenBuilderEnvToOutputPath(envPath, outputPath, label);
+    return;
+  }
+  await writeLocalEnvToOutputPath(outputPath, appName, secretsPath, label, localOpts);
+}
+
+async function processEnvVariables(envPath, variablesPath, appName, secretsPath, copyOptions = {}) {
   if (!variablesPath || !fs.existsSync(variablesPath)) {
     return;
   }
@@ -310,8 +381,21 @@ async function processEnvVariables(envPath, variablesPath, appName, secretsPath)
   }
 
   const label = variables.build.envOutputPath;
+  const appPathForLocal =
+    (copyOptions && copyOptions.appPath) ||
+    (variablesPath ? path.dirname(variablesPath) : null);
+  const preferLocal =
+    copyOptions && typeof copyOptions === 'object' && copyOptions.preferLocalEnvOutputPath === true;
   if (appName) {
-    await writeLocalEnvToOutputPath(outputPath, appName, secretsPath, label);
+    await copyOrRegenerateEnvForNamedApp({
+      envPath,
+      outputPath,
+      appName,
+      secretsPath,
+      label,
+      preferLocal,
+      appPathForLocal
+    });
   } else {
     await writePatchedEnvToOutputPath(envPath, outputPath, variables, label);
   }
@@ -321,6 +405,7 @@ module.exports = {
   processEnvVariables,
   resolveEnvOutputPath,
   substituteMntDataForLocal,
+  syncWrittenBuilderEnvToOutputPath,
   writeEnvOutputForReload,
   writeEnvOutputForLocal
 };

package/lib/utils/env-template.js

@@ -13,6 +13,7 @@ const fsSync = require('fs');
 const path = require('path');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
+const pathsUtil = require('./paths');
 
 /**
  * Updates env.template to add MISO_CLIENTID, MISO_CLIENTSECRET, and optionally MISO_CONTROLLER_URL.
@@ -105,7 +106,10 @@ ${missingEntries.join('\n')}
 }
 
 async function updateEnvTemplate(appKey, clientIdKey, clientSecretKey, _controllerUrl) {
-  const envTemplatePath = path.join(process.cwd(), 'builder', appKey, 'env.template');
+  // Use paths.getBuilderPath so the system builder root (e.g. ~/.aifabrix/builder/<app>) and
+  // AIFABRIX_BUILDER_DIR are respected. Falling back to process.cwd() previously made the binary
+  // CLI skip env.template updates whenever cwd was a non-builder repo (e.g. aifabrix-training).
+  const envTemplatePath = path.join(pathsUtil.getBuilderPath(appKey), 'env.template');
 
   if (!fsSync.existsSync(envTemplatePath)) {
     logger.warn(chalk.yellow(`⚠  env.template not found for ${appKey}, skipping update`));

package/lib/utils/health-check-url.js

@@ -62,19 +62,9 @@ function frontDoorPattern(appConfig) {
   return (typeof p === 'string' && p.trim()) ? p.trim() : null;
 }
 
-/**
- * Compute the Traefik front-door health check URL when applicable.
- *
- * Returns null when Traefik/frontDoorRouting isn't active or cannot be resolved.
- *
- * @async
- * @param {string} appName
- * @param {number} healthCheckPort
- * @param {Object|null} appConfig
- * @returns {Promise<string|null>}
- */
 /**
  * Public app URL (Traefik + frontDoor mount path), without the health path — for CLI summaries.
+ * Requires infra Traefik on, `frontDoorRouting.enabled`, host, and pattern.
  *
  * @async
  * @param {string} appName
@@ -83,7 +73,7 @@ function frontDoorPattern(appConfig) {
  * @returns {Promise<string|null>}
  */
 async function computeTraefikPublicAppUrl(_appName, _healthCheckPort, appConfig) {
-  if (!frontDoorEnabled(appConfig)) return null;
+  if (!appConfig || !frontDoorEnabled(appConfig)) return null;
   const pattern = frontDoorPattern(appConfig);
   if (!pattern) return null;
 
@@ -91,6 +81,13 @@ async function computeTraefikPublicAppUrl(_appName, _healthCheckPort, appConfig)
   const userCfg = await coreConfig.getConfig();
   if (!(userCfg && userCfg.traefik)) return null;
 
+  const fd = appConfig.frontDoorRouting;
+  if (!fd || typeof fd !== 'object') return null;
+  const hostTemplate = typeof fd.host === 'string' ? fd.host.trim() : '';
+  if (!hostTemplate) return null;
+
+  const mountPath = normalizeFrontDoorPatternForHealth(pattern);
+
   const infraTlsEnabled = Boolean(userCfg && userCfg.tlsEnabled);
   const remoteServer = await coreConfig.getRemoteServer();
   const developerIdRaw = await coreConfig.getDeveloperId();
@@ -98,7 +95,6 @@ async function computeTraefikPublicAppUrl(_appName, _healthCheckPort, appConfig)
 
   // URLs are resolved for the CLI on the host, not from inside a container.
   const profile = 'local';
-  const fd = appConfig.frontDoorRouting;
   const listenPort = Number(appConfig?.port || 3000);
 
   const publicBase = computePublicUrlBaseString({
@@ -114,10 +110,18 @@ async function computeTraefikPublicAppUrl(_appName, _healthCheckPort, appConfig)
     infraTlsEnabled
   });
 
-  const mountPath = normalizeFrontDoorPatternForHealth(pattern);
   return joinUrlPath(publicBase, mountPath);
 }
 
+/**
+ * Traefik public URL including health path.
+ *
+ * @async
+ * @param {string} appName
+ * @param {number} healthCheckPort
+ * @param {Object|null} appConfig
+ * @returns {Promise<string|null>}
+ */
 async function computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig) {
   const baseWithFrontDoor = await computeTraefikPublicAppUrl(appName, healthCheckPort, appConfig);
   if (!baseWithFrontDoor) return null;
@@ -131,4 +135,3 @@ module.exports = {
   computeTraefikPublicAppUrl,
   computeTraefikHealthCheckUrl
 };
-

package/lib/utils/health-check.js

@@ -16,7 +16,8 @@ const dns = require('dns');
 const chalk = require('chalk');
 const logger = require('./logger');
 const { execWithDockerEnv } = require('./docker-exec');
-const { computeTraefikHealthCheckUrl } = require('./health-check-url');
+/** Namespace require so tests can `jest.spyOn` on `./health-check-url` exports. */
+const healthCheckUrl = require('./health-check-url');
 const { computePathActive } = require('./url-declarative-url-flags');
 const { isFrontDoorRoutingEnabledInDoc } = require('./url-declarative-vdir-inactive-env');
 const { waitForDbInit } = require('./health-check-db-init');
@@ -69,10 +70,11 @@ async function computeHealthCheckUrl(appName, healthCheckPort, appConfig, _opts
     const runOptions = (_opts && typeof _opts === 'object') ? _opts.runOptions : null;
     const wantsTraefik =
       Boolean(runOptions) &&
-      (runOptions.probeViaTraefik === true || runOptions.traefikEnabled === true);
+      (runOptions.probeViaTraefik === true || runOptions.traefikEnabled === true) &&
+      isFrontDoorRoutingEnabledInDoc(appConfig);
     if (!wantsTraefik) return '';
     try {
-      return await computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig);
+      return await healthCheckUrl.computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig);
     } catch {
       return '';
     }
@@ -380,10 +382,10 @@ async function computePreferredHealthCheckUrls(appName, healthCheckPort, config,
   let skippedPublicHealthUrl = '';
   const wantsTraefikFirst = Boolean(
     runOptions && (runOptions.probeViaTraefik === true || runOptions.traefikEnabled === true)
-  );
+  ) && isFrontDoorRoutingEnabledInDoc(config);
   if (wantsTraefikFirst) {
     try {
-      traefikUrl = await computeTraefikHealthCheckUrl(appName, healthCheckPort, config);
+      traefikUrl = await healthCheckUrl.computeTraefikHealthCheckUrl(appName, healthCheckPort, config);
     } catch {
       traefikUrl = '';
     }

package/lib/utils/help-builder.js

@@ -26,10 +26,10 @@ const CATEGORIES = [
       { name: 'up-platform' },
       { name: 'up-miso' },
       { name: 'up-dataplane' },
-      { name: 'down-infra', term: 'down-infra [service|app]' },
+      { name: 'down-infra', term: 'down-infra [service|appKey]' },
       { name: 'doctor' },
       { name: 'status' },
-      { name: 'restart', term: 'restart <service|app>' }
+      { name: 'restart', term: 'restart <service|appKey>' }
     ]
   },
   {
@@ -43,23 +43,22 @@ const CATEGORIES = [
   {
     name: 'Applications (Create & Develop)',
     commands: [
-      { name: 'create', term: 'create <app>' },
-      { name: 'wizard' },
-      { name: 'build', term: 'build <app>' },
-      { name: 'run', term: 'run <app>' },
-      { name: 'shell', term: 'shell <app>' },
-      { name: 'install', term: 'install <app>' },
-      { name: 'lint', term: 'lint <app>' },
-      { name: 'logs', term: 'logs <app>' },
-      { name: 'stop', term: 'stop <app>' },
-      { name: 'dockerfile', term: 'dockerfile <app>' }
+      { name: 'create', term: 'create <appKey|systemKey>' },
+      { name: 'build', term: 'build <appKey>' },
+      { name: 'run', term: 'run <appKey>' },
+      { name: 'shell', term: 'shell <appKey>' },
+      { name: 'install', term: 'install <appKey>' },
+      { name: 'lint', term: 'lint <appKey>' },
+      { name: 'logs', term: 'logs <appKey>' },
+      { name: 'stop', term: 'stop <appKey>' },
+      { name: 'dockerfile', term: 'dockerfile <appKey>' }
     ]
   },
   {
     name: 'Deployment',
     commands: [
-      { name: 'push', term: 'push <app>' },
-      { name: 'deploy', term: 'deploy <app>' }
+      { name: 'push', term: 'push <appKey>' },
+      { name: 'deploy', term: 'deploy <appKey|systemKey>' }
     ]
   },
   {
@@ -80,12 +79,12 @@ const CATEGORIES = [
   {
     name: 'Configuration & Validation',
     commands: [
-      { name: 'resolve', term: 'resolve <app>' },
-      { name: 'json', term: 'json <app>' },
-      { name: 'split-json', term: 'split-json <app>' },
-      { name: 'convert', term: 'convert <app>' },
-      { name: 'show', term: 'show <app>' },
-      { name: 'validate', term: 'validate <appOrFile>' },
+      { name: 'resolve', term: 'resolve <appKey|systemKey>' },
+      { name: 'json', term: 'json <appKey|systemKey>' },
+      { name: 'split-json', term: 'split-json <appKey|systemKey>' },
+      { name: 'convert', term: 'convert <appKey|systemKey>' },
+      { name: 'show', term: 'show <appKey|systemKey>' },
+      { name: 'validate', term: 'validate [appKey|systemKey|file]' },
       { name: 'parameters', term: 'parameters validate' },
       { name: 'diff', term: 'diff <file1> <file2>' }
     ]
@@ -93,16 +92,23 @@ const CATEGORIES = [
   {
     name: 'External Systems',
     commands: [
+      { name: 'wizard', term: 'wizard [systemKey]' },
       { name: 'download', term: 'download <systemKey>' },
       { name: 'upload', term: 'upload <systemKey>' },
       { name: 'delete', term: 'delete <systemKey>' },
       { name: 'repair', term: 'repair <systemKey>' },
       { name: 'datasource' },
+      { name: 'datasource load', term: 'datasource load <datasourceKey>' },
+      { name: 'datasource export', term: 'datasource export <datasourceKey>' },
       { name: 'dimension' },
-      { name: 'dimension-value' },
-      { name: 'test', term: 'test <app>' },
-      { name: 'test-e2e', term: 'test-e2e <app>' },
-      { name: 'test-integration', term: 'test-integration <app>' }
+      { name: 'dimension value', term: 'dimension value <command>' },
+      { name: 'identity' },
+      { name: 'protection' },
+      { name: 'test', term: 'test <appKey|systemKey>' },
+      { name: 'test-e2e', term: 'test-e2e <appKey|systemKey>' },
+      { name: 'test-governance', term: 'test-governance <appKey|systemKey>' },
+      { name: 'test-trust', term: 'test-trust <appKey|systemKey>' },
+      { name: 'test-integration', term: 'test-integration <appKey|systemKey>' }
     ]
   },
   {

package/lib/utils/infra-optional-service-flags.js

@@ -0,0 +1,69 @@
+/**
+ * Optional infra compose flags (Traefik, pgAdmin, Redis Commander) for config.yaml ↔ startInfra.
+ *
+ * @fileoverview Effective flag resolution + backfill missing keys after up-infra / setup
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const config = require('../core/config');
+
+/**
+ * Resolves effective boolean from CLI option vs config.
+ * @param {*} optValue - options.traefik | options.pgAdmin | options.redisAdmin
+ * @param {*} cfgValue - cfg.traefik | cfg.pgadmin | cfg.redisCommander
+ * @param {boolean} defaultWhenUndef - Default when config value is undefined
+ * @returns {boolean}
+ */
+function resolveInfraOptionalFlag(optValue, cfgValue, defaultWhenUndef = true) {
+  if (optValue === true) return true;
+  if (optValue === false) return false;
+  return cfgValue !== false && (cfgValue === true || defaultWhenUndef);
+}
+
+/**
+ * Effective optional infra service flags (same resolution as up-infra → startInfra).
+ *
+ * @param {Object} cfg - Config from {@link config.getConfig}
+ * @param {Object} [options] - Commander options (omit for setup-modes)
+ * @returns {{ traefik: boolean, pgadmin: boolean, redisCommander: boolean }}
+ */
+function computeEffectiveInfraOptionalFlags(cfg, options = {}) {
+  return {
+    traefik: resolveInfraOptionalFlag(options.traefik, cfg.traefik, false),
+    pgadmin: resolveInfraOptionalFlag(options.pgAdmin, cfg.pgadmin, true),
+    redisCommander: resolveInfraOptionalFlag(options.redisAdmin, cfg.redisCommander, true)
+  };
+}
+
+/**
+ * Writes `traefik` / `pgadmin` / `redisCommander` when missing so config matches compose defaults.
+ *
+ * @param {Object} cfg - Mutable config (updated when save runs)
+ * @param {{ traefik: boolean, pgadmin: boolean, redisCommander: boolean }} effective
+ * @returns {Promise<void>}
+ */
+async function persistMissingInfraOptionalServiceFlags(cfg, effective) {
+  const keys = ['traefik', 'pgadmin', 'redisCommander'];
+  const merged = { ...cfg };
+  let dirty = false;
+  for (const k of keys) {
+    if (typeof merged[k] === 'undefined') {
+      merged[k] = effective[k];
+      dirty = true;
+    }
+  }
+  if (!dirty) {
+    return;
+  }
+  await config.saveConfig(merged);
+  Object.assign(cfg, merged);
+}
+
+module.exports = {
+  resolveInfraOptionalFlag,
+  computeEffectiveInfraOptionalFlags,
+  persistMissingInfraOptionalServiceFlags
+};