@aifabrix/builder 2.44.5 → 2.44.6

package/lib/utils/health-check.js

@@ -12,16 +12,24 @@ const { formatSuccessLine } = require('./cli-test-layout-chalk');
 const http = require('http');
 const https = require('https');
 const net = require('net');
+const dns = require('dns');
 const chalk = require('chalk');
 const logger = require('./logger');
 const { execWithDockerEnv } = require('./docker-exec');
 const { computeTraefikHealthCheckUrl } = 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');
+const {
+  filterTraefikUrlByDns,
+  logPublicHealthUrlWarningIfNeeded
+} = require('./health-check-public-warn');
 
 /**
  * Compute the health check URL for an app.
  *
- * - Default (no Traefik front-door): http://localhost:<port><healthPath>
- * - With Traefik + app frontDoorRouting.enabled: <publicBase><frontDoorRouting.pattern><healthPath>
+ * - Default (path inactive): http://localhost:<port><healthPath> (e.g. Keycloak with KC_HTTP_RELATIVE_PATH=/)
+ * - Path active (Traefik on ∧ frontDoorRouting.enabled): localhost probe uses same vdir as the container (e.g. /auth/health/ready)
  *
  * @async
  * @param {string} appName
@@ -29,117 +37,67 @@ const { computeTraefikHealthCheckUrl } = require('./health-check-url');
  * @param {Object|null} appConfig
  * @param {Object} opts
  * @param {Object} [opts.runOptions] - runApp options (may include env + effectiveEnvironmentScopedResources)
+ * @param {boolean} [opts.skipTraefikPublicUrl] - Omit Traefik URL (localhost leg in dual-probe flow only).
  * @returns {Promise<string>}
  */
 async function computeHealthCheckUrl(appName, healthCheckPort, appConfig, _opts = {}) {
-  const healthCheckPath = appConfig?.healthCheck?.path || '/health';
+  const rawHealthPath = appConfig?.healthCheck?.path || '/health';
 
-  // Traefik front-door branch: probe via resolved public host + path (e.g. https://dev02.builder02.local/auth/health/ready)
-  try {
-    const traefikUrl = await computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig);
-    if (traefikUrl) return traefikUrl;
-  } catch {
-    // If any resolver step fails, fall back to localhost probing.
+  function computeLocalhostHealthPath() {
+    // Plan 124 pathActive: prepend front-door pattern when Traefik on; keep bare /health for miso/dataplane style.
+    try {
+      const runOptions = _opts && typeof _opts === 'object' && _opts.runOptions ? _opts.runOptions : null;
+      const traefikOn = Boolean(runOptions && runOptions.traefikEnabled === true);
+      const fd = appConfig && appConfig.frontDoorRouting ? appConfig.frontDoorRouting : null;
+      const pattern = fd && typeof fd.pattern === 'string' ? fd.pattern : null;
+      const pathActive = computePathActive(traefikOn, isFrontDoorRoutingEnabledInDoc(appConfig || null));
+      const shouldMount = pathActive && Boolean(pattern) && rawHealthPath !== '/health';
+      if (!shouldMount) return rawHealthPath;
+      const { joinUrlPath, normalizeFrontDoorPatternForHealth } = require('./health-check-url');
+      const mountPath = normalizeFrontDoorPatternForHealth(pattern);
+      return joinUrlPath(mountPath, rawHealthPath);
+    } catch {
+      return rawHealthPath;
+    }
   }
 
-  // Default: probe local published port.
-  return `http://localhost:${healthCheckPort}${healthCheckPath}`;
-}
+  const localhostHealthPath = computeLocalhostHealthPath();
 
-/**
- * Checks if db-init container exists and waits for it to complete
- * @async
- * @function waitForDbInit
- * @param {string} appName - Application name
- * @throws {Error} If db-init fails
- */
-/**
- * Checks if db-init container exists
- * @async
- * @function checkDbInitContainerExists
- * @param {string} dbInitContainer - Container name
- * @returns {Promise<boolean>} True if container exists
- */
-async function checkDbInitContainerExists(dbInitContainer) {
-  try {
-    const { stdout } = await execWithDockerEnv(`docker ps -a --filter "name=${dbInitContainer}" --format "{{.Names}}"`);
-    return stdout.trim() === dbInitContainer;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Gets container exit code
- * @async
- * @function getContainerExitCode
- * @param {string} dbInitContainer - Container name
- * @returns {Promise<string>} Exit code
- */
-async function getContainerExitCode(dbInitContainer) {
-  const { stdout: exitCode } = await execWithDockerEnv(`docker inspect --format='{{.State.ExitCode}}' ${dbInitContainer}`);
-  return exitCode.trim();
-}
-
-/**
- * Handles exited container status
- * @async
- * @function handleExitedContainer
- * @param {string} dbInitContainer - Container name
- * @returns {Promise<boolean>} True if handled (container already exited)
- */
-async function handleExitedContainer(dbInitContainer) {
-  const { stdout: status } = await execWithDockerEnv(`docker inspect --format='{{.State.Status}}' ${dbInitContainer}`);
-  if (status.trim() === 'exited') {
-    const exitCode = await getContainerExitCode(dbInitContainer);
-    if (exitCode === '0') {
-      logger.log(formatSuccessLine('Database initialization already completed'));
-    } else {
-      logger.log(chalk.yellow(`⚠ Database initialization exited with code ${exitCode}`));
+  // Local readiness probes localhost; optional Traefik URL is for display / dual-probe (see waitForHealthCheck).
+  async function maybeGetTraefikUrl() {
+    if (_opts && _opts.skipTraefikPublicUrl) return '';
+    const runOptions = (_opts && typeof _opts === 'object') ? _opts.runOptions : null;
+    const wantsTraefik =
+      Boolean(runOptions) &&
+      (runOptions.probeViaTraefik === true || runOptions.traefikEnabled === true);
+    if (!wantsTraefik) return '';
+    try {
+      return await computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig);
+    } catch {
+      return '';
     }
-    return true;
   }
-  return false;
-}
 
-/**
- * Waits for container to exit
- * @async
- * @function waitForContainerExit
- * @param {string} dbInitContainer - Container name
- * @param {number} maxAttempts - Maximum attempts
- */
-async function waitForContainerExit(dbInitContainer, maxAttempts) {
-  for (let attempts = 0; attempts < maxAttempts; attempts++) {
-    const { stdout: currentStatus } = await execWithDockerEnv(`docker inspect --format='{{.State.Status}}' ${dbInitContainer}`);
-    if (currentStatus.trim() === 'exited') {
-      const exitCode = await getContainerExitCode(dbInitContainer);
-      if (exitCode === '0') {
-        logger.log(formatSuccessLine('Database initialization completed'));
-      } else {
-        logger.log(chalk.yellow(`⚠ Database initialization exited with code ${exitCode}`));
-      }
-      return;
-    }
-    await new Promise(resolve => setTimeout(resolve, 1000));
-  }
+  const traefikUrl = await maybeGetTraefikUrl();
+  if (traefikUrl) return traefikUrl;
+
+  return `http://localhost:${healthCheckPort}${localhostHealthPath}`;
 }
 
-async function waitForDbInit(appName) {
-  const dbInitContainer = `aifabrix-${appName}-db-init`;
+async function isHostnameResolvable(hostname, debug) {
+  if (!hostname) return false;
+  const hn = String(hostname).trim().toLowerCase();
+  if (!hn) return false;
+  if (hn === 'localhost' || hn === '127.0.0.1' || hn === '::1') return true;
   try {
-    if (!(await checkDbInitContainerExists(dbInitContainer))) {
-      return;
-    }
-
-    if (await handleExitedContainer(dbInitContainer)) {
-      return;
+    await dns.promises.lookup(hn);
+    return true;
+  } catch (err) {
+    // ENOTFOUND: caller may log a single post-success warning with the full public health URL.
+    if (debug && !(err && err.code === 'ENOTFOUND')) {
+      logger.log(chalk.gray(`[DEBUG] DNS lookup failed for ${hostname}: ${err.message}`));
     }
-
-    logger.log(chalk.blue('Waiting for database initialization to complete...'));
-    await waitForContainerExit(dbInitContainer, 30);
-  } catch (error) {
-    // db-init container might not exist, which is fine
+    return false;
   }
 }
 
@@ -411,24 +369,96 @@ async function performHealthCheckAttempt(healthCheckUrl, attempt, maxAttempts, d
   return false;
 }
 
+async function computePreferredHealthCheckUrls(appName, healthCheckPort, config, runOptions, debug) {
+  const localhostUrl = await computeHealthCheckUrl(appName, healthCheckPort, config, {
+    runOptions: runOptions && typeof runOptions === 'object' ? runOptions : {},
+    skipTraefikPublicUrl: true
+  });
+
+  let traefikUrl = '';
+  /** Full Traefik/public health URL when DNS fails — used for one post-success warning. */
+  let skippedPublicHealthUrl = '';
+  const wantsTraefikFirst = Boolean(
+    runOptions && (runOptions.probeViaTraefik === true || runOptions.traefikEnabled === true)
+  );
+  if (wantsTraefikFirst) {
+    try {
+      traefikUrl = await computeTraefikHealthCheckUrl(appName, healthCheckPort, config);
+    } catch {
+      traefikUrl = '';
+    }
+  }
+
+  const filtered = await filterTraefikUrlByDns(traefikUrl, debug, isHostnameResolvable);
+  traefikUrl = filtered.traefikUrl;
+  skippedPublicHealthUrl = filtered.skippedPublicHealthUrl;
+
+  const urlsToTry = traefikUrl ? [traefikUrl, localhostUrl] : [localhostUrl];
+  if (urlsToTry.length > 1) {
+    logger.log(
+      chalk.gray(
+        `ℹ Health check order: Traefik/DNS (${urlsToTry[0]}), then localhost (${urlsToTry[1]}).`
+      )
+    );
+  }
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Health check URLs: ${urlsToTry.join(' | ')}`));
+  }
+  return { urlsToTry, skippedPublicHealthUrl };
+}
+
+async function performHealthCheckAttemptForUrls(urlsToTry, attempt, maxAttempts, debug) {
+  for (let i = 0; i < urlsToTry.length; i++) {
+    const url = urlsToTry[i];
+    const passed = await performHealthCheckAttempt(url, attempt, maxAttempts, debug);
+    if (passed) {
+      return { ok: true, resolvedIndex: i };
+    }
+  }
+  return { ok: false, resolvedIndex: -1 };
+}
+
 async function waitForHealthCheck(appName, timeout = 90, port = null, config = null, debug = false, runOptions = {}) {
   await waitForDbInit(appName);
 
   const healthCheckPort = await determineHealthCheckPort(port, appName, debug);
   const { maxAttempts } = buildHealthCheckConfig(healthCheckPort, config, timeout, debug);
-  const healthCheckUrl = await computeHealthCheckUrl(appName, healthCheckPort, config, { runOptions });
-  if (debug) {
-    logger.log(chalk.gray(`[DEBUG] Health check URL: ${healthCheckUrl}`));
+  const { urlsToTry, skippedPublicHealthUrl } = await computePreferredHealthCheckUrls(
+    appName,
+    healthCheckPort,
+    config,
+    runOptions,
+    debug
+  );
+
+  if (skippedPublicHealthUrl && urlsToTry.length === 1) {
+    logger.log(
+      chalk.gray(
+        `ℹ Health check: public URL not used (DNS): ${skippedPublicHealthUrl}. ` +
+          `Probing ${urlsToTry[0]} only until the app responds.`
+      )
+    );
   }
 
   for (let attempts = 0; attempts < maxAttempts; attempts++) {
-    const passed = await performHealthCheckAttempt(healthCheckUrl, attempts, maxAttempts, debug);
-    if (passed) {
+    const attemptResult = await performHealthCheckAttemptForUrls(urlsToTry, attempts, maxAttempts, debug);
+    if (attemptResult.ok) {
+      logPublicHealthUrlWarningIfNeeded({
+        skippedPublicHealthUrl,
+        urlsToTry,
+        resolvedIndex: attemptResult.resolvedIndex
+      });
       return;
     }
 
     if (attempts < maxAttempts - 1) {
-      logger.log(chalk.yellow(`Waiting for health check... (${attempts + 1}/${maxAttempts}) ${healthCheckUrl}`));
+      const probeHint =
+        urlsToTry.length > 1
+          ? `trying ${urlsToTry[0]}, then ${urlsToTry[1]}`
+          : (urlsToTry[0] || 'health URL');
+      logger.log(
+        chalk.yellow(`Waiting for health check… (${attempts + 1}/${maxAttempts}) (${probeHint})`)
+      );
       await new Promise(resolve => setTimeout(resolve, 2000));
     }
   }

package/lib/utils/help-builder.js

@@ -20,6 +20,8 @@ const CATEGORIES = [
   {
     name: 'Infrastructure (Local Development)',
     commands: [
+      { name: 'setup' },
+      { name: 'teardown' },
       { name: 'up-infra' },
       { name: 'up-platform' },
       { name: 'up-miso' },
@@ -72,7 +74,7 @@ const CATEGORIES = [
       { name: 'app' },
       { name: 'credential' },
       { name: 'deployment' },
-      { name: 'service-user' }
+      { name: 'integration-client' }
     ]
   },
   {
@@ -96,6 +98,8 @@ const CATEGORIES = [
       { name: 'delete', term: 'delete <systemKey>' },
       { name: 'repair', term: 'repair <systemKey>' },
       { name: 'datasource' },
+      { name: 'dimension' },
+      { name: 'dimension-value' },
       { name: 'test', term: 'test <app>' },
       { name: 'test-e2e', term: 'test-e2e <app>' },
       { name: 'test-integration', term: 'test-integration <app>' }

package/lib/utils/image-name.js

@@ -11,18 +11,18 @@
 
 /**
  * Builds a developer-scoped image name for local Docker builds.
- * Format: "<base>-dev<developerId>".
- * If developerId is missing, non-numeric, or 0 → "<base>-extra".
+ * Format: "<base>-dev<developerId>" when developerId is a positive integer.
+ * If developerId is missing, non-numeric, or 0 → returns baseName (manifest image; no dev suffix).
  *
  * @function buildDevImageName
  * @param {string} baseName - Base image name (no registry), e.g., "myapp"
  * @param {(string|number|null|undefined)} developerId - Developer identifier
- * @returns {string} Developer-scoped image name
+ * @returns {string} Developer-scoped image name or base name when id is 0 / absent
  *
  * @example
  * buildDevImageName('myapp', 123) // "myapp-dev123"
- * buildDevImageName('myapp', '0') // "myapp-extra"
- * buildDevImageName('myapp') // "myapp-extra"
+ * buildDevImageName('myapp', '0') // "myapp"
+ * buildDevImageName('myapp') // "myapp"
  */
 function buildDevImageName(baseName, developerId) {
   const id =
@@ -37,13 +37,40 @@ function buildDevImageName(baseName, developerId) {
   }
 
   if (!Number.isFinite(id) || id === 0) {
-    return `${baseName}-extra`;
+    return baseName;
   }
 
   return `${baseName}-dev${id}`;
 }
 
+/**
+ * Developer-scoped repository path for run/build resolution (may include registry prefix).
+ * For qualified paths (slashes), only the last segment gets `-dev<id>`; id 0 returns path unchanged.
+ *
+ * @param {string} repositoryPath - Full repository path (e.g. "reg/ns/app" or "app")
+ * @param {(string|number|null|undefined)} developerId - Developer id from config
+ * @returns {string}
+ */
+function buildDevImageRepositoryPath(repositoryPath, developerId) {
+  if (!repositoryPath || typeof repositoryPath !== 'string') {
+    throw new Error('Repository path is required and must be a string');
+  }
+  const idNum =
+    typeof developerId === 'number' ? developerId : parseInt(String(developerId), 10);
+  if (!Number.isFinite(idNum) || idNum === 0) {
+    return repositoryPath;
+  }
+  const idx = repositoryPath.lastIndexOf('/');
+  const tail = idx === -1 ? repositoryPath : repositoryPath.slice(idx + 1);
+  const scopedTail = buildDevImageName(tail, developerId);
+  if (idx === -1) {
+    return scopedTail;
+  }
+  return `${repositoryPath.slice(0, idx)}/${scopedTail}`;
+}
+
 module.exports = {
-  buildDevImageName
+  buildDevImageName,
+  buildDevImageRepositoryPath
 };
 

package/lib/utils/integration-file-backup.js

@@ -0,0 +1,74 @@
+/**
+ * Timestamped backups under integration/<app>/backup/ (same layout as datasource capability copy).
+ *
+ * @fileoverview Backup before mutating integration JSON/YAML
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * True if path exists and is a regular file (not mocked by typical existsSync spies in unit tests).
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function isRegularFile(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Copies filePath into neighbor backup/ with ISO timestamp suffix.
+ * @param {string} filePath - Absolute path to file to copy
+ * @param {boolean} noBackup - When true, skip and return null
+ * @returns {string|null} Destination path or null
+ */
+function writeBackup(filePath, noBackup) {
+  if (noBackup) {
+    return null;
+  }
+  const dir = path.dirname(filePath);
+  const backupDir = path.join(dir, 'backup');
+  fs.mkdirSync(backupDir, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const base = path.basename(filePath);
+  const dest = path.join(backupDir, `${base}.${ts}.bak`);
+  fs.copyFileSync(filePath, dest);
+  return dest;
+}
+
+/**
+ * Backs up an existing file once per repair run (dedupes by absolute path).
+ * @param {string} filePath - Path to file that will be overwritten
+ * @param {{ dryRun?: boolean, noBackup?: boolean, backupPaths?: string[], backedUpFiles?: Set<string> }} ctx
+ * @returns {string|null}
+ */
+function backupIntegrationFile(filePath, ctx) {
+  const { dryRun, noBackup, backupPaths, backedUpFiles } = ctx || {};
+  if (dryRun || noBackup || !filePath || !isRegularFile(filePath)) {
+    return null;
+  }
+  const abs = path.resolve(filePath);
+  if (backedUpFiles) {
+    if (backedUpFiles.has(abs)) return null;
+    backedUpFiles.add(abs);
+  }
+  const dest = writeBackup(filePath, false);
+  if (dest && Array.isArray(backupPaths)) {
+    backupPaths.push(dest);
+  }
+  return dest;
+}
+
+module.exports = {
+  writeBackup,
+  backupIntegrationFile,
+  isRegularFile
+};

package/lib/utils/mutagen-install.js

@@ -9,6 +9,7 @@
 
 const path = require('path');
 const fs = require('fs');
+const http = require('http');
 const https = require('https');
 const { getAifabrixHome } = require('./paths');
 const { exec } = require('child_process');
@@ -88,10 +89,36 @@ function fetchLatestRelease() {
  * @param {(msg: string) => void} [log] - Optional progress logger
  * @returns {Promise<void>}
  */
-function downloadToFile(url, destPath, log) {
+/**
+ * @param {string} url
+ * @param {string} destPath
+ * @param {(msg: string) => void} [log]
+ * @param {number} [redirectsLeft]
+ * @returns {Promise<void>}
+ */
+function downloadToFile(url, destPath, log, redirectsLeft = 8) {
   return new Promise((resolve, reject) => {
+    if (redirectsLeft <= 0) {
+      reject(new Error('Download redirect loop'));
+      return;
+    }
     const file = fs.createWriteStream(destPath, { flags: 'w' });
-    const req = https.get(url, { headers: { 'User-Agent': 'aifabrix-builder-cli' } }, (res) => {
+    const lib = url.startsWith('http:') ? http : https;
+    const req = lib.get(url, { headers: { 'User-Agent': 'aifabrix-builder-cli' } }, (res) => {
+      const loc = res.headers.location;
+      if ([301, 302, 303, 307, 308].includes(res.statusCode || 0) && loc) {
+        file.close();
+        fs.unlink(destPath, () => {});
+        let nextUrl;
+        try {
+          nextUrl = new URL(loc, url).href;
+        } catch (e) {
+          reject(new Error(`Invalid redirect Location: ${loc}`));
+          return;
+        }
+        downloadToFile(nextUrl, destPath, log, redirectsLeft - 1).then(resolve).catch(reject);
+        return;
+      }
       if (res.statusCode !== 200) {
         file.close();
         fs.unlink(destPath, () => {});
@@ -111,7 +138,7 @@ function downloadToFile(url, destPath, log) {
     req.setTimeout(120000, () => {
       req.destroy(); reject(new Error('Download timeout'));
     });
-    if (typeof log === 'function') log('Downloading Mutagen...');
+    if (typeof log === 'function' && redirectsLeft === 8) log('Downloading Mutagen...');
   });
 }