@aifabrix/builder 2.40.0 → 2.41.0

package/lib/utils/api.js

@@ -13,8 +13,8 @@
 const { parseErrorResponse } = require('./api-error-handler');
 const auditLogger = require('../core/audit-logger');
 
-/** Default timeout for HTTP requests (ms). Prevents hanging when the controller is unreachable. */
-const DEFAULT_REQUEST_TIMEOUT_MS = 5000;
+/** Default timeout for HTTP requests (ms). Prevents hanging when the controller is unreachable. 30s allows Azure Web App cold start to complete. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 
 /**
  * Logs API request performance metrics and errors to audit log
@@ -229,7 +229,7 @@ async function handleNetworkError(error, url, options, duration) {
 
 /**
  * Make an API call with proper error handling
- * Uses a 15s timeout to avoid hanging when the controller is unreachable.
+ * Uses a 30s timeout to avoid hanging when the controller is unreachable (Azure cold start can exceed 5s).
  * @param {string} url - API endpoint URL
  * @param {Object} options - Fetch options (signal, method, headers, body, etc.)
  * @returns {Promise<Object>} Response object with success flag

package/lib/utils/app-register-auth.js

@@ -257,7 +257,22 @@ async function attemptGetAuthenticationToken(normalizedControllerUrl, config, at
   return { token, finalControllerUrl, lastError };
 }
 
-async function checkAuthentication(controllerUrl, _environment) {
+/**
+ * When auth fails and throwOnFailure is true, throws an error with controllerUrl so caller can run login and retry.
+ * @param {string|null} controllerUrl - Controller URL to attach to the thrown error
+ * @param {Error|null} lastError - Last error from token attempt
+ * @param {string[]} attemptedUrls - URLs that were tried
+ * @throws {Error} Error with .controllerUrl and .authFailure set
+ */
+function throwAuthFailureError(controllerUrl, lastError, attemptedUrls) {
+  const message = lastError ? lastError.message : 'No valid authentication found';
+  const err = new Error(message);
+  err.controllerUrl = controllerUrl || (attemptedUrls && attemptedUrls[0]) || null;
+  err.authFailure = true;
+  throw err;
+}
+
+async function checkAuthentication(controllerUrl, _environment, options = {}) {
   try {
     const config = await getConfig();
     const normalizedControllerUrl = normalizeControllerUrlIfProvided(controllerUrl);
@@ -269,8 +284,12 @@ async function checkAuthentication(controllerUrl, _environment) {
       attemptedUrls
     );
 
-    // If no token found, display error with attempted URLs
-    validateAuthenticationResult(token, finalControllerUrl, lastError, controllerUrl, attemptedUrls);
+    if (!token || !finalControllerUrl) {
+      if (options.throwOnFailure) {
+        throwAuthFailureError(controllerUrl || finalControllerUrl, lastError, attemptedUrls);
+      }
+      validateAuthenticationResult(token, finalControllerUrl, lastError, controllerUrl, attemptedUrls);
+    }
 
     return {
       apiUrl: finalControllerUrl,
@@ -278,6 +297,9 @@ async function checkAuthentication(controllerUrl, _environment) {
       controllerUrl: finalControllerUrl
     };
   } catch (error) {
+    if (error.authFailure) {
+      throw error;
+    }
     displayAuthenticationError(error, { controllerUrl: controllerUrl });
   }
 }

package/lib/utils/cli-utils.js

@@ -106,6 +106,10 @@ function isDockerPermissionDeniedError(errorMsg) {
  */
 function formatDockerError(errorMsg) {
   if (isDockerImageNotFoundError(errorMsg)) {
+    // Preserve custom hint for template apps (keycloak, miso-controller) from up-miso/up-dataplane
+    if (errorMsg.includes('use --image') || errorMsg.includes('Pull the image')) {
+      return errorMsg.split('\n').map(line => (line.trim() ? `   ${line.trim()}` : ''));
+    }
     return [
       '   Docker image not found.',
       '   Run: aifabrix build <app> first'
@@ -326,6 +330,21 @@ function logOfflinePathWhenType(appPath, options) {
   logger.log(chalk.gray(`Using: ${displayPath}`));
 }
 
+/**
+ * Returns true if the error is likely due to authentication failure (e.g. 401, token expired, login required).
+ * Used to show "Run: aifabrix login" for commands that require Controller auth (e.g. up-dataplane).
+ * @param {Error} error - The error that occurred
+ * @returns {boolean} True if the error appears to be auth-related
+ */
+function isAuthenticationError(error) {
+  if (!error) return false;
+  if (error.authFailure === true) return true;
+  const msg = (error.message || '').toLowerCase();
+  const formatted = (typeof error.formatted === 'string' ? error.formatted : '').toLowerCase();
+  const combined = `${msg} ${formatted}`;
+  return /401|unauthorized|authentication|token expired|login required|aifabrix login|no authentication|device token|refresh token/.test(combined);
+}
+
 /**
  * Handles command errors with user-friendly messages
  * @param {Error} error - The error that occurred
@@ -375,6 +394,7 @@ async function appendWizardError(appKey, error) {
 module.exports = {
   validateCommand,
   handleCommandError,
+  isAuthenticationError,
   appendWizardError,
   logOfflinePathWhenType
 };

package/lib/utils/compose-generator.js

@@ -18,58 +18,12 @@ const buildCopy = require('./build-copy');
 const { formatMissingDbPasswordError } = require('./error-formatter');
 const { getContainerPort } = require('./port-resolver');
 const { parseImageOverride } = require('./parse-image-ref');
+const { registerComposeHelpers } = require('./compose-handlebars-helpers');
+const { isVectorDatabaseName } = require('./compose-vector-helper');
+const paths = require('./paths');
+const { getInfraDirName } = require('../infrastructure/helpers');
 
-// Register commonly used helpers
-handlebars.registerHelper('eq', (a, b) => a === b);
-
-// Register Handlebars helper for quoting PostgreSQL identifiers
-// PostgreSQL requires identifiers with hyphens or special characters to be quoted
-handlebars.registerHelper('pgQuote', (identifier) => {
-  if (!identifier) {
-    return '';
-  }
-  // Always quote identifiers to handle hyphens and special characters
-  // Return SafeString to prevent HTML escaping
-  return new handlebars.SafeString(`"${String(identifier).replace(/"/g, '""')}"`);
-});
-
-// Helper to generate quoted PostgreSQL user name from database name
-// User names must use underscores (not hyphens) for PostgreSQL compatibility
-handlebars.registerHelper('pgUser', (dbName) => {
-  if (!dbName) {
-    return '';
-  }
-  // Replace hyphens with underscores in user name (database names can have hyphens, but user names should not)
-  const userName = `${String(dbName).replace(/-/g, '_')}_user`;
-  // Return SafeString to prevent HTML escaping
-  return new handlebars.SafeString(`"${userName.replace(/"/g, '""')}"`);
-});
-
-// Helper to generate old user name format (for migration - drops old users with hyphens)
-// This is used to drop legacy users that were created with hyphens before the fix
-// Returns unquoted name (quotes should be added in template where needed)
-handlebars.registerHelper('pgUserOld', (dbName) => {
-  if (!dbName) {
-    return '';
-  }
-  // Old format: database name + _user (preserving hyphens)
-  const userName = `${String(dbName)}_user`;
-  // Return unquoted name - template will add quotes where needed
-  return new handlebars.SafeString(userName);
-});
-
-// Helper to generate unquoted PostgreSQL user name (for SQL WHERE clauses)
-// Returns the user name without quotes for use in SQL queries
-handlebars.registerHelper('pgUserName', (dbName) => {
-  if (!dbName) {
-    return '';
-  }
-  // Replace hyphens with underscores in user name
-  const userName = `${String(dbName).replace(/-/g, '_')}_user`;
-  // Return unquoted name for SQL queries
-  return new handlebars.SafeString(userName);
-});
-
+registerComposeHelpers();
 /**
  * Loads and compiles Docker Compose template
  * @param {string} language - Language type
@@ -95,7 +49,6 @@ function loadDockerComposeTemplate(language) {
   const templateContent = fsSync.readFileSync(templatePath, 'utf8');
   return handlebars.compile(templateContent);
 }
-
 /**
  * Extracts image name from configuration (same logic as build.js)
  * @param {Object} config - Application configuration
@@ -112,7 +65,6 @@ function getImageName(config, appName) {
   }
   return appName;
 }
-
 /**
  * Builds app configuration section
  * @param {string} appName - Application name
@@ -125,7 +77,6 @@ function buildAppConfig(appName, config) {
     name: config.displayName || appName
   };
 }
-
 /**
  * Builds image configuration section
  * @param {Object} config - Application configuration
@@ -255,9 +206,6 @@ function buildServiceConfig(appName, config, port, devId, imageOverride) {
     port: containerPortValue, // Container port (for health check and template)
     containerPort: containerPortValue, // Container port (always set, equals containerPort if exists, else port)
     hostPort: hostPort, // Host port (options.port if provided, else config.port)
-    build: {
-      localPort: config.build?.localPort || null // Only used for .env file PORT variable, not for Docker Compose
-    },
     healthCheck: buildHealthCheckConfig(config),
     traefik: buildTraefikConfig(config, devId),
     ...buildRequiresConfig(config)
@@ -445,6 +393,52 @@ async function readDatabasePasswordsIfNeeded(requiresDatabase, databases, envFil
   return { map: {}, array: [] };
 }
 
+/**
+ * Resolves image override from options (--image, --tag, or null).
+ * @param {Object} options - Run options
+ * @param {Object} appConfig - Application configuration
+ * @param {string} appName - Application name
+ * @returns {string|null} Full image reference or null
+ */
+function resolveImageOverride(options, appConfig, appName) {
+  if (options.image) return options.image;
+  if (options.imageOverride) return options.imageOverride;
+  if (options.tag) return `${getImageName(appConfig, appName)}:${options.tag}`;
+  return null;
+}
+
+/**
+ * Resolves Miso environment from options (tst, pro, or dev).
+ * @param {Object} options - Run options
+ * @returns {string} 'dev' | 'tst' | 'pro'
+ */
+function resolveMisoEnvironment(options) {
+  const env = (options.env && typeof options.env === 'string') ? options.env.toLowerCase() : 'dev';
+  return (env === 'tst' || env === 'pro') ? env : 'dev';
+}
+
+/**
+ * Resolves dev mount path from options.
+ * @param {Object} options - Run options
+ * @returns {string|null} Trimmed path or null
+ */
+function resolveDevMountPath(options) {
+  return (options.devMountPath && typeof options.devMountPath === 'string') ? options.devMountPath.trim() : null;
+}
+
+/**
+ * Resolves env file path from options or default dev dir (forward slashes).
+ * @param {Object} options - Run options
+ * @param {string} devDir - Default dev directory
+ * @returns {string} Absolute env file path
+ */
+function resolveEnvFilePath(options, devDir) {
+  const envFilePath = (options.envFilePath && typeof options.envFilePath === 'string')
+    ? path.resolve(options.envFilePath)
+    : path.join(devDir, '.env');
+  return envFilePath.replace(/\\/g, '/');
+}
+
 /**
  * Generates Docker Compose configuration from template
  * @async
@@ -458,8 +452,7 @@ async function generateDockerCompose(appName, appConfig, options) {
   const language = appConfig.build?.language || appConfig.language || 'typescript';
   const template = loadDockerComposeTemplate(language);
   const port = options.port || appConfig.port || 3000;
-  const imageOverride = options.image || options.imageOverride ||
-    (options.tag ? `${getImageName(appConfig, appName)}:${options.tag}` : null);
+  const imageOverride = resolveImageOverride(options, appConfig, appName);
   const { devId, idNum } = await getDeveloperIdAndNumeric();
   const { networkName, containerName } = buildNetworkAndContainerNames(appName, devId, idNum);
   const serviceConfig = buildServiceConfig(appName, appConfig, port, devId, imageOverride);
@@ -467,33 +460,41 @@ async function generateDockerCompose(appName, appConfig, options) {
   const networksConfig = buildNetworksConfig(appConfig);
 
   const devDir = buildCopy.getDevDirectory(appName, devId);
-  const envFilePath = path.join(devDir, '.env');
-  const envFileAbsolutePath = envFilePath.replace(/\\/g, '/');
+  const envFileAbsolutePath = resolveEnvFilePath(options, devDir);
+  const dbInitEnvFileAbsolutePath = (options.dbInitEnvFilePath && typeof options.dbInitEnvFilePath === 'string')
+    ? path.resolve(options.dbInitEnvFilePath).replace(/\\/g, '/')
+    : null;
 
   const databasePasswords = await readDatabasePasswordsIfNeeded(
     serviceConfig.requiresDatabase || false,
     networksConfig.databases || [],
-    envFilePath,
+    envFileAbsolutePath,
     appName
   );
-
-  const templateData = {
+  const devMountPath = resolveDevMountPath(options);
+  const reloadStartRaw = appConfig.build?.reloadStart;
+  const reloadStartCommand =
+    devMountPath && typeof reloadStartRaw === 'string' && reloadStartRaw.trim().length > 0
+      ? reloadStartRaw.trim()
+      : null;
+
+  const infraPgpassPath = path.join(paths.getAifabrixHome(), getInfraDirName(devId), 'pgpass');
+  const useInfraPgpass = serviceConfig.requiresDatabase && fsSync.existsSync(infraPgpassPath);
+  return template({
     ...serviceConfig,
     ...volumesConfig,
     ...networksConfig,
     envFile: envFileAbsolutePath,
+    dbInitEnvFile: dbInitEnvFileAbsolutePath,
     databasePasswords,
     devId: idNum,
     networkName,
-    containerName
-  };
-  return template(templateData);
+    containerName,
+    misoEnvironment: resolveMisoEnvironment(options),
+    devMountPath,
+    reloadStartCommand,
+    infraPgpassPath: useInfraPgpass ? infraPgpassPath : null,
+    useInfraPgpass: !!useInfraPgpass
+  });
 }
-
-module.exports = {
-  generateDockerCompose,
-  getImageName,
-  derivePathFromPattern,
-  buildTraefikConfig,
-  buildDevUsername
-};
+module.exports = { generateDockerCompose, getImageName, derivePathFromPattern, buildTraefikConfig, buildDevUsername, isVectorDatabaseName };

package/lib/utils/compose-handlebars-helpers.js

@@ -0,0 +1,43 @@
+/**
+ * Handlebars helpers for Docker Compose templates.
+ * @fileoverview Compose template helpers (pgQuote, pgUser, isVectorDatabase, etc.)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const handlebars = require('handlebars');
+const { isVectorDatabaseName } = require('./compose-vector-helper');
+
+/**
+ * Registers Handlebars helpers used by Docker Compose templates.
+ */
+function registerComposeHelpers() {
+  handlebars.registerHelper('eq', (a, b) => a === b);
+
+  handlebars.registerHelper('pgQuote', (identifier) => {
+    if (!identifier) return '';
+    return new handlebars.SafeString(`"${String(identifier).replace(/"/g, '""')}"`);
+  });
+
+  handlebars.registerHelper('pgUser', (dbName) => {
+    if (!dbName) return '';
+    const userName = `${String(dbName).replace(/-/g, '_')}_user`;
+    return new handlebars.SafeString(`"${userName.replace(/"/g, '""')}"`);
+  });
+
+  handlebars.registerHelper('pgUserOld', (dbName) => {
+    if (!dbName) return '';
+    const userName = `${String(dbName)}_user`;
+    return new handlebars.SafeString(userName);
+  });
+
+  handlebars.registerHelper('pgUserName', (dbName) => {
+    if (!dbName) return '';
+    const userName = `${String(dbName).replace(/-/g, '_')}_user`;
+    return new handlebars.SafeString(userName);
+  });
+
+  handlebars.registerHelper('isVectorDatabase', (name) => isVectorDatabaseName(name));
+}
+
+module.exports = { registerComposeHelpers };

package/lib/utils/compose-vector-helper.js

@@ -0,0 +1,18 @@
+/**
+ * Vector database name predicate for Docker Compose generation.
+ * Used so db-init can run CREATE EXTENSION vector on vector-store databases.
+ * @fileoverview Vector database name helper for compose-generator
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Returns true when the database name ends with "vector" (case-insensitive).
+ * @param {string} name - Database name
+ * @returns {boolean}
+ */
+function isVectorDatabaseName(name) {
+  return name !== null && name !== undefined && String(name).toLowerCase().endsWith('vector');
+}
+
+module.exports = { isVectorDatabaseName };

package/lib/utils/config-paths.js

@@ -10,6 +10,21 @@
 
 const path = require('path');
 
+/**
+ * GET /api/dev/settings response parameter names (builder-cli.md §1).
+ * Single source of truth so CLI and config merge stay aligned with the contract.
+ */
+const SETTINGS_RESPONSE_KEYS = [
+  'user-mutagen-folder',
+  'secrets-encryption',
+  'aifabrix-secrets',
+  'aifabrix-env-config',
+  'remote-server',
+  'docker-endpoint',
+  'sync-ssh-user',
+  'sync-ssh-host'
+];
+
 /**
  * Get path configuration value
  * @async
@@ -73,6 +88,114 @@ function createEnvConfigPathFunctions(getConfigFn, saveConfigFn) {
   };
 }
 
+function createRemoteConfigGetters(getConfigFn) {
+  return {
+    async getRemoteServer() {
+      return getPathConfig(getConfigFn, 'remote-server');
+    },
+    async getDockerEndpoint() {
+      return getPathConfig(getConfigFn, 'docker-endpoint');
+    },
+    async getUserMutagenFolder() {
+      return getPathConfig(getConfigFn, 'user-mutagen-folder');
+    },
+    async getSyncSshUser() {
+      return getPathConfig(getConfigFn, 'sync-ssh-user');
+    },
+    async getSyncSshHost() {
+      return getPathConfig(getConfigFn, 'sync-ssh-host');
+    }
+  };
+}
+
+function createRemoteConfigSetters(getConfigFn, saveConfigFn) {
+  return {
+    async setRemoteServer(value) {
+      if (value !== null && value !== undefined && typeof value !== 'string') {
+        throw new Error('remote-server must be a string');
+      }
+      const config = await getConfigFn();
+      config['remote-server'] = value ? value.trim().replace(/\/+$/, '') : undefined;
+      await saveConfigFn(config);
+    },
+    async setDockerEndpoint(value) {
+      if (value !== null && value !== undefined && typeof value !== 'string') {
+        throw new Error('docker-endpoint must be a string');
+      }
+      const config = await getConfigFn();
+      config['docker-endpoint'] = value || undefined;
+      await saveConfigFn(config);
+    }
+  };
+}
+
+function isHttpUrl(value) {
+  return typeof value === 'string' && (value.startsWith('http://') || value.startsWith('https://'));
+}
+
+/**
+ * Derive hostname from a URL (e.g. https://builder.aifabrix.dev -> builder.aifabrix.dev).
+ * @param {string} url - URL string
+ * @returns {string|null} Hostname or null if invalid
+ */
+function hostnameFromUrl(url) {
+  if (!url || typeof url !== 'string') return null;
+  const s = url.trim().replace(/\/+$/, '');
+  if (!s) return null;
+  const withProtocol = s.match(/^https?:\/\//) ? s : `https://${s}`;
+  try {
+    return new URL(withProtocol).hostname || null;
+  } catch {
+    return null;
+  }
+}
+
+function applySecretsUrlFromRemote(config) {
+  const remoteServer = config['remote-server'];
+  const secretsPath = config['aifabrix-secrets'];
+  if (!remoteServer || !secretsPath || isHttpUrl(secretsPath)) return;
+  const base = typeof remoteServer === 'string' ? remoteServer.trim().replace(/\/+$/, '') : '';
+  if (base) config['aifabrix-secrets'] = `${base}/api/dev/secrets`;
+}
+
+function applySyncAndDockerFromHost(config) {
+  const host = hostnameFromUrl(config['remote-server']);
+  if (!host) return;
+  if (!config['sync-ssh-host']) config['sync-ssh-host'] = host;
+  if (!config['docker-endpoint']) config['docker-endpoint'] = `tcp://${host}:2376`;
+}
+
+async function mergeRemoteSettingsImpl(getConfigFn, saveConfigFn, settings) {
+  if (!settings || typeof settings !== 'object') return;
+  const config = await getConfigFn();
+  for (const key of SETTINGS_RESPONSE_KEYS) {
+    const raw = settings[key];
+    if (raw === undefined || raw === null) continue;
+    const value = typeof raw === 'string' ? raw.trim() : raw;
+    if (value === '') continue;
+    config[key] = value;
+  }
+  applySecretsUrlFromRemote(config);
+  applySyncAndDockerFromHost(config);
+  await saveConfigFn(config);
+}
+
+/**
+ * Remote Docker / Builder Server config. Used when remote-server is set.
+ * @param {Function} getConfigFn - Function to get config
+ * @param {Function} saveConfigFn - Function to save config
+ * @returns {Object} Remote config getters, setters, and mergeRemoteSettings
+ */
+function createRemoteConfigFunctions(getConfigFn, saveConfigFn) {
+  return {
+    ...createRemoteConfigGetters(getConfigFn),
+    ...createRemoteConfigSetters(getConfigFn, saveConfigFn),
+    async mergeRemoteSettings(settings) {
+      return mergeRemoteSettingsImpl(getConfigFn, saveConfigFn, settings);
+    }
+  };
+}
+
 /**
  * Create path configuration functions with config access
  * @param {Function} getConfigFn - Function to get config
@@ -82,13 +205,15 @@ function createEnvConfigPathFunctions(getConfigFn, saveConfigFn) {
 function createPathConfigFunctions(getConfigFn, saveConfigFn) {
   return {
     ...createHomeAndSecretsPathFunctions(getConfigFn, saveConfigFn),
-    ...createEnvConfigPathFunctions(getConfigFn, saveConfigFn)
+    ...createEnvConfigPathFunctions(getConfigFn, saveConfigFn),
+    ...createRemoteConfigFunctions(getConfigFn, saveConfigFn)
   };
 }
 
 module.exports = {
   getPathConfig,
   setPathConfig,
-  createPathConfigFunctions
+  createPathConfigFunctions,
+  SETTINGS_RESPONSE_KEYS
 };