@aifabrix/builder 2.33.0 → 2.33.3

package/lib/schema/env-config.yaml

@@ -18,6 +18,9 @@ environments:
     MISO_PORT: 3000  # Internal port (container-to-container). MISO_PUBLIC_PORT calculated automatically.
     KEYCLOAK_HOST: keycloak
     KEYCLOAK_PORT: 8082  # Internal port (container-to-container). KEYCLOAK_PUBLIC_PORT calculated automatically.
+    KEYCLOAK_PUBLIC_PORT: 8082
+    DATAPLANE_HOST: dataplane
+    DATAPLANE_PORT: 3001
     NODE_ENV: production
     PYTHONUNBUFFERED: 1
     PYTHONDONTWRITEBYTECODE: 1
@@ -30,8 +33,12 @@ environments:
     REDIS_PORT: 6379
     MISO_HOST: localhost
     MISO_PORT: 3010
+    MISO_PUBLIC_PORT: 3010
     KEYCLOAK_HOST: localhost
     KEYCLOAK_PORT: 8082
+    KEYCLOAK_PUBLIC_PORT: 8082
+    DATAPLANE_HOST: localhost
+    DATAPLANE_PORT: 3011
     NODE_ENV: development
     PYTHONUNBUFFERED: 1
     PYTHONDONTWRITEBYTECODE: 1

package/lib/utils/api.js

@@ -131,6 +131,32 @@ async function handleSuccessResponse(response, url, options, duration) {
   return { success: true, data: text, status: response.status };
 }
 
+/**
+ * Validates that a URL is not empty or missing
+ * @function validateUrl
+ * @param {string} url - URL to validate
+ * @param {string} [urlType='URL'] - Type of URL for error message (e.g., 'Dataplane URL', 'Controller URL')
+ * @returns {void}
+ * @throws {Error} If URL is empty, null, undefined, whitespace-only, or malformed
+ */
+function validateUrl(url, urlType = 'URL') {
+  if (!url || typeof url !== 'string') {
+    throw new Error(`${urlType} is required and must be a string (received: ${JSON.stringify(url)})`);
+  }
+  const trimmedUrl = url.trim();
+  if (!trimmedUrl) {
+    throw new Error(`${urlType} cannot be empty. Please provide a valid URL.`);
+  }
+  // Check for common invalid URL patterns
+  if (trimmedUrl === 'undefined' || trimmedUrl === 'null' || trimmedUrl === 'NaN') {
+    throw new Error(`${urlType} is invalid: "${trimmedUrl}". Please provide a valid URL.`);
+  }
+  // Basic URL format validation - must start with http:// or https://
+  if (!trimmedUrl.match(/^https?:\/\//i)) {
+    throw new Error(`${urlType} must be a valid HTTP/HTTPS URL (received: "${trimmedUrl}")`);
+  }
+}
+
 /**
  * Handles network error from API call
  * @async
@@ -142,7 +168,34 @@ async function handleSuccessResponse(response, url, options, duration) {
  * @returns {Promise<Object>} Error response object
  */
 async function handleNetworkError(error, url, options, duration) {
-  const parsedError = parseErrorResponse(error.message, 0, true);
+  // Enhance error message with URL information if URL is missing or invalid
+  let errorMessage = error.message;
+  if (errorMessage && (errorMessage.includes('cannot be empty') || errorMessage.includes('is required'))) {
+    // Add URL context to validation errors
+    if (!url || !url.trim()) {
+      errorMessage = `${errorMessage} (URL was: ${JSON.stringify(url)})`;
+    } else {
+      errorMessage = `${errorMessage} (URL was: ${url})`;
+    }
+  } else if (!url || !url.trim()) {
+    // If URL is empty but error doesn't mention it, add context
+    errorMessage = `Invalid or missing URL. ${errorMessage} (URL was: ${JSON.stringify(url)})`;
+  }
+
+  const parsedError = parseErrorResponse(errorMessage, 0, true);
+
+  // Extract controller URL from full URL for error data
+  let controllerUrl = null;
+  const endpointUrl = url;
+  if (url && typeof url === 'string' && url.trim()) {
+    try {
+      const urlObj = new URL(url);
+      controllerUrl = `${urlObj.protocol}//${urlObj.host}`;
+    } catch {
+      // If URL parsing fails, use the full URL as endpoint
+      controllerUrl = null;
+    }
+  }
 
   await logApiPerformance({
     url,
@@ -157,10 +210,17 @@ async function handleNetworkError(error, url, options, duration) {
     }
   });
 
+  // Include both controller URL and full endpoint URL in error data
+  const errorData = {
+    ...parsedError.data,
+    controllerUrl: controllerUrl,
+    endpointUrl: endpointUrl
+  };
+
   return {
     success: false,
     error: parsedError.message,
-    errorData: parsedError.data,
+    errorData: errorData,
     errorType: parsedError.type,
     formattedError: parsedError.formatted,
     network: true
@@ -175,6 +235,14 @@ async function handleNetworkError(error, url, options, duration) {
  * @returns {Promise<Object>} Response object with success flag
  */
 async function makeApiCall(url, options = {}) {
+  // Validate URL before attempting request
+  try {
+    validateUrl(url, 'API endpoint URL');
+  } catch (error) {
+    const duration = 0;
+    return await handleNetworkError(error, url || '', options, duration);
+  }
+
   const startTime = Date.now();
   const fetchOptions = { ...options };
   if (!fetchOptions.signal) {

package/lib/utils/compose-generator.js

@@ -17,6 +17,7 @@ const config = require('../core/config');
 const buildCopy = require('./build-copy');
 const { formatMissingDbPasswordError } = require('./error-formatter');
 const { getContainerPort } = require('./port-resolver');
+const { parseImageOverride } = require('./parse-image-ref');
 
 // Register commonly used helpers
 handlebars.registerHelper('eq', (a, b) => a === b);
@@ -129,9 +130,14 @@ function buildAppConfig(appName, config) {
  * Builds image configuration section
  * @param {Object} config - Application configuration
  * @param {string} appName - Application name
+ * @param {string} [imageOverride] - Optional full image reference (registry/name:tag) to use instead of config
  * @returns {Object} Image configuration
  */
-function buildImageConfig(config, appName) {
+function buildImageConfig(config, appName, imageOverride) {
+  const parsed = imageOverride ? parseImageOverride(imageOverride) : null;
+  if (parsed) {
+    return { name: parsed.name, tag: parsed.tag };
+  }
   const imageName = getImageName(config, appName);
   const imageTag = config.image?.tag || 'latest';
   return {
@@ -237,14 +243,15 @@ function buildRequiresConfig(config) {
  * @param {Object} config - Application configuration
  * @param {number} port - Application port
  * @param {string|number} devId - Developer ID
+ * @param {string} [imageOverride] - Optional full image reference for run (e.g. from --image)
  * @returns {Object} Service configuration
  */
-function buildServiceConfig(appName, config, port, devId) {
+function buildServiceConfig(appName, config, port, devId, imageOverride) {
   const containerPortValue = getContainerPort(config, 3000);
   const hostPort = port;
   return {
     app: buildAppConfig(appName, config),
-    image: buildImageConfig(config, appName),
+    image: buildImageConfig(config, appName, 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)
@@ -275,14 +282,7 @@ function buildNetworksConfig(config) {
   return { databases: config.requires?.databases || config.databases || [] };
 }
 
-/**
- * Reads and parses .env file
- * @async
- * @function readEnvFile
- * @param {string} envPath - Path to .env file
- * @returns {Promise<Object>} Object with environment variables
- * @throws {Error} If file not found or read fails
- */
+/** Reads and parses .env file. @param {string} envPath - Path to .env file. @returns {Promise<Object>} env vars. @throws {Error} If file not found. */
 async function readEnvFile(envPath) {
   if (!fsSync.existsSync(envPath)) {
     throw new Error(`.env file not found: ${envPath}`);
@@ -458,9 +458,10 @@ 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;
   const { devId, idNum } = await getDeveloperIdAndNumeric();
   const { networkName, containerName } = buildNetworkAndContainerNames(appName, devId, idNum);
-  const serviceConfig = buildServiceConfig(appName, appConfig, port, devId);
+  const serviceConfig = buildServiceConfig(appName, appConfig, port, devId, imageOverride);
   const volumesConfig = buildVolumesConfig(appName);
   const networksConfig = buildNetworksConfig(appConfig);
 
@@ -495,4 +496,3 @@ module.exports = {
   buildTraefikConfig,
   buildDevUsername
 };
-

package/lib/utils/config-paths.js

@@ -8,6 +8,8 @@
  * @version 2.0.0
  */
 
+const path = require('path');
+
 /**
  * Get path configuration value
  * @async
@@ -102,6 +104,17 @@ function createPathConfigFunctions(getConfigFn, saveConfigFn) {
      */
     async setAifabrixEnvConfigPath(envConfigPath) {
       await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-env-config', envConfigPath, 'Env config path is required and must be a string');
+    },
+
+    /**
+     * Get builder root directory (dirname of aifabrix-env-config when set).
+     * When set, app dirs and generated .env use this instead of cwd/builder.
+     * @async
+     * @returns {Promise<string|null>} Builder root path or null to use cwd/builder
+     */
+    async getAifabrixBuilderDir() {
+      const envConfigPath = await getPathConfig(getConfigFn, 'aifabrix-env-config');
+      return envConfigPath && typeof envConfigPath === 'string' ? path.dirname(envConfigPath) : null;
     }
   };
 }

package/lib/utils/device-code.js

@@ -469,12 +469,13 @@ async function refreshDeviceToken(controllerUrl, refreshToken) {
   }
 
   const url = `${controllerUrl}/api/v1/auth/login/device/refresh`;
+  // Send both refresh_token (OAuth2 RFC 6749 / Keycloak) and refreshToken (camelCase) so controller accepts either
   const response = await getMakeApiCall()(url, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json'
     },
-    body: JSON.stringify({ refreshToken })
+    body: JSON.stringify({ refresh_token: refreshToken, refreshToken })
   });
 
   if (!response.success) {
@@ -490,7 +491,6 @@ async function refreshDeviceToken(controllerUrl, refreshToken) {
 
   return tokenResponse;
 }
-
 module.exports = {
   initiateDeviceCodeFlow,
   pollDeviceCodeToken,

package/lib/utils/env-endpoints.js

@@ -9,7 +9,6 @@
 'use strict';
 
 const fs = require('fs');
-const path = require('path');
 const yaml = require('js-yaml');
 const config = require('../core/config');
 const devConfig = require('../utils/dev-config');
@@ -49,8 +48,7 @@ function splitHost(value) {
 function getLocalhostOverride(context) {
   if (context !== 'local') return null;
   try {
-    const os = require('os');
-    const cfgPath = path.join(os.homedir(), '.aifabrix', 'config.yaml');
+    const cfgPath = config.CONFIG_FILE;
     if (fs.existsSync(cfgPath)) {
       const cfgContent = fs.readFileSync(cfgPath, 'utf8');
       const cfg = yaml.load(cfgContent) || {};
@@ -310,8 +308,7 @@ async function rewriteInfraEndpoints(envContent, context, devPorts, adjustedHost
 
   // Apply config.yaml → environments.{context} override (if exists)
   try {
-    const os = require('os');
-    const cfgPath = path.join(os.homedir(), '.aifabrix', 'config.yaml');
+    const cfgPath = config.CONFIG_FILE;
     if (fs.existsSync(cfgPath)) {
       const cfgContent = fs.readFileSync(cfgPath, 'utf8');
       const cfg = yaml.load(cfgContent) || {};

package/lib/utils/env-map.js

@@ -9,7 +9,6 @@
 'use strict';
 
 const fs = require('fs');
-const path = require('path');
 const yaml = require('js-yaml');
 const { loadEnvConfig } = require('./env-config-loader');
 const config = require('../core/config');
@@ -38,9 +37,9 @@ async function loadBaseVars(context) {
  * @param {Object} os - OS module instance
  * @returns {Object} Override environment variables
  */
-function loadOverrideVars(context, os) {
+function loadOverrideVars(context, _os) {
   try {
-    const cfgPath = path.join(os.homedir(), '.aifabrix', 'config.yaml');
+    const cfgPath = config.CONFIG_FILE;
     if (fs.existsSync(cfgPath)) {
       const cfgContent = fs.readFileSync(cfgPath, 'utf8');
       const cfg = yaml.load(cfgContent) || {};
@@ -60,9 +59,9 @@ function loadOverrideVars(context, os) {
  * @param {Object} os - OS module instance
  * @returns {string|null} Localhost override value or null
  */
-function getLocalhostOverride(os) {
+function getLocalhostOverride(_os) {
   try {
-    const cfgPath = path.join(os.homedir(), '.aifabrix', 'config.yaml');
+    const cfgPath = config.CONFIG_FILE;
     if (fs.existsSync(cfgPath)) {
       const cfgContent = fs.readFileSync(cfgPath, 'utf8');
       const cfg = yaml.load(cfgContent) || {};

package/lib/utils/error-formatters/network-errors.js

@@ -40,7 +40,10 @@ function addControllerUrlHeader(lines, errorData) {
  * @param {Object} errorData - Error response data
  */
 function addControllerUrlToMessage(lines, errorData) {
-  if (errorData && errorData.controllerUrl) {
+  // Prefer showing full endpoint URL if available
+  if (errorData && errorData.endpointUrl) {
+    lines.push(chalk.gray(`Endpoint URL: ${errorData.endpointUrl}`));
+  } else if (errorData && errorData.controllerUrl) {
     lines.push(chalk.gray(`Controller URL: ${errorData.controllerUrl}`));
   }
 }
@@ -77,8 +80,15 @@ function formatHostnameNotFoundError(lines, errorData) {
  */
 function formatTimeoutError(lines, errorData) {
   lines.push(chalk.yellow('Request timed out.'));
-  addControllerUrlToMessage(lines, errorData);
-  lines.push(chalk.gray('The controller may be overloaded.'));
+
+  // Show full endpoint URL if available, otherwise show controller URL
+  if (errorData && errorData.endpointUrl) {
+    lines.push(chalk.gray(`Endpoint URL: ${errorData.endpointUrl}`));
+  } else if (errorData && errorData.controllerUrl) {
+    lines.push(chalk.gray(`Controller URL: ${errorData.controllerUrl}`));
+  }
+
+  lines.push(chalk.gray('The endpoint may not exist, the controller may be overloaded, or there may be a network issue.'));
 }
 
 /**

package/lib/utils/parse-image-ref.js

@@ -0,0 +1,27 @@
+/**
+ * Parse full image reference (registry/name:tag or name:tag) into { name, tag }
+ *
+ * @fileoverview Image reference parsing for compose and run overrides
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Parses full image reference (registry/name:tag or name:tag) into { name, tag }
+ * @param {string} imageRef - Full image reference (e.g. myreg/keycloak:v1 or keycloak:latest)
+ * @returns {{ name: string, tag: string }|null} Parsed name and tag, or null if invalid
+ */
+function parseImageOverride(imageRef) {
+  if (!imageRef || typeof imageRef !== 'string') {
+    return null;
+  }
+  const lastColon = imageRef.lastIndexOf(':');
+  if (lastColon <= 0) {
+    return { name: imageRef.trim(), tag: 'latest' };
+  }
+  const name = imageRef.substring(0, lastColon).trim();
+  const tag = imageRef.substring(lastColon + 1).trim() || 'latest';
+  return { name, tag };
+}
+
+module.exports = { parseImageOverride };

package/lib/utils/paths.js

@@ -30,18 +30,33 @@ function safeHomedir() {
   return process.env.HOME || process.env.USERPROFILE || '/';
 }
 
+/**
+ * Returns the path to the config file (AIFABRIX_HOME env or ~/.aifabrix).
+ * Used so getAifabrixHome can read from the same location as config.js.
+ * @returns {string} Absolute path to config directory
+ */
+function getConfigDirForPaths() {
+  if (process.env.AIFABRIX_HOME && typeof process.env.AIFABRIX_HOME === 'string') {
+    return path.resolve(process.env.AIFABRIX_HOME.trim());
+  }
+  return path.join(safeHomedir(), '.aifabrix');
+}
+
 /**
  * Returns the base AI Fabrix directory.
- * Resolved from config.yaml `aifabrix-home` (stored under OS home).
- * Falls back to ~/.aifabrix when not specified.
+ * Priority: AIFABRIX_HOME env → config.yaml `aifabrix-home` (from AIFABRIX_HOME or ~/.aifabrix) → ~/.aifabrix.
  *
  * @returns {string} Absolute path to the AI Fabrix home directory
  */
 function getAifabrixHome() {
+  if (process.env.AIFABRIX_HOME && typeof process.env.AIFABRIX_HOME === 'string') {
+    return path.resolve(process.env.AIFABRIX_HOME.trim());
+  }
   const isTestEnv = process.env.NODE_ENV === 'test' || process.env.JEST_WORKER_ID !== undefined;
   if (!isTestEnv) {
     try {
-      const configPath = path.join(safeHomedir(), '.aifabrix', 'config.yaml');
+      const configDir = getConfigDirForPaths();
+      const configPath = path.join(configDir, 'config.yaml');
       if (fs.existsSync(configPath)) {
         const content = fs.readFileSync(configPath, 'utf8');
         const config = yaml.load(content) || {};
@@ -278,7 +293,9 @@ function getIntegrationPath(appName) {
 }
 
 /**
- * Gets the builder folder path for regular applications
+ * Gets the builder folder path for regular applications.
+ * When AIFABRIX_BUILDER_DIR is set (e.g. by up-miso/up-dataplane from config aifabrix-env-config),
+ * uses that as builder root instead of cwd/builder.
  * @param {string} appName - Application name
  * @returns {string} Absolute path to builder directory
  */
@@ -286,6 +303,12 @@ function getBuilderPath(appName) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
+  const builderRoot = process.env.AIFABRIX_BUILDER_DIR && typeof process.env.AIFABRIX_BUILDER_DIR === 'string'
+    ? process.env.AIFABRIX_BUILDER_DIR.trim()
+    : null;
+  if (builderRoot) {
+    return path.join(builderRoot, appName);
+  }
   return path.join(process.cwd(), 'builder', appName);
 }
 
@@ -442,6 +465,7 @@ async function detectAppType(appName, options = {}) {
 
 module.exports = {
   getAifabrixHome,
+  getConfigDirForPaths,
   getApplicationsBaseDir,
   getDevDirectory,
   getAppPath,

package/lib/utils/secrets-generator.js

@@ -41,6 +41,36 @@ function findMissingSecretKeys(envTemplate, existingSecrets) {
   return missingKeys;
 }
 
+/**
+ * Generate database password value for a key (databases-*-passwordKeyVault)
+ * @param {string} key - Secret key name
+ * @returns {string|null} Password string or null if key does not match
+ */
+function generateDbPasswordValue(key) {
+  const dbPasswordMatch = key.match(/^databases-([a-z0-9-_]+)-\d+-passwordKeyVault$/i);
+  if (!dbPasswordMatch) return null;
+  const appName = dbPasswordMatch[1];
+  if (appName === 'miso-controller') return 'miso_pass123';
+  const dbName = appName.replace(/-/g, '_');
+  return `${dbName}_pass123`;
+}
+
+/**
+ * Generate database URL value for a key (databases-*-urlKeyVault)
+ * @param {string} key - Secret key name
+ * @returns {string|null} URL string or null if key does not match
+ */
+function generateDbUrlValue(key) {
+  const dbUrlMatch = key.match(/^databases-([a-z0-9-_]+)-\d+-urlKeyVault$/i);
+  if (!dbUrlMatch) return null;
+  const appName = dbUrlMatch[1];
+  if (appName === 'miso-controller') {
+    return 'postgresql://miso_user:miso_pass123@${DB_HOST}:${DB_PORT}/miso';
+  }
+  const dbName = appName.replace(/-/g, '_');
+  return `postgresql://${dbName}_user:${dbName}_pass123@\${DB_HOST}:\${DB_PORT}/${dbName}`;
+}
+
 /**
  * Generates secret value based on key name
  * @function generateSecretValue
@@ -51,22 +81,14 @@ function generateSecretValue(key) {
   const keyLower = key.toLowerCase();
 
   if (keyLower.includes('password')) {
-    const dbPasswordMatch = key.match(/^databases-([a-z0-9-_]+)-\d+-passwordKeyVault$/i);
-    if (dbPasswordMatch) {
-      const appName = dbPasswordMatch[1];
-      const dbName = appName.replace(/-/g, '_');
-      return `${dbName}_pass123`;
-    }
+    const dbPassword = generateDbPasswordValue(key);
+    if (dbPassword !== null) return dbPassword;
     return crypto.randomBytes(32).toString('base64');
   }
 
   if (keyLower.includes('url') || keyLower.includes('uri')) {
-    const dbUrlMatch = key.match(/^databases-([a-z0-9-_]+)-\d+-urlKeyVault$/i);
-    if (dbUrlMatch) {
-      const appName = dbUrlMatch[1];
-      const dbName = appName.replace(/-/g, '_');
-      return `postgresql://${dbName}_user:${dbName}_pass123@\${DB_HOST}:\${DB_PORT}/${dbName}`;
-    }
+    const dbUrl = generateDbUrlValue(key);
+    if (dbUrl !== null) return dbUrl;
     return '';
   }
 

package/lib/utils/secrets-helpers.js

@@ -263,8 +263,7 @@ async function getLocalEnvWithOverrides() {
   let localEnv = await getEnvHosts('local');
 
   try {
-    const os = require('os');
-    const cfgPath = path.join(os.homedir(), '.aifabrix', 'config.yaml');
+    const cfgPath = config.CONFIG_FILE;
     if (fs.existsSync(cfgPath)) {
       const cfgContent = fs.readFileSync(cfgPath, 'utf8');
       const cfg = yaml.load(cfgContent) || {};

package/lib/utils/token-manager-refresh.js

@@ -10,6 +10,7 @@
 
 const config = require('../core/config');
 const { refreshDeviceToken: apiRefreshDeviceToken } = require('./api');
+const { isTokenEncrypted } = require('./token-encryption');
 
 /**
  * Validates refresh token parameters
@@ -138,6 +139,10 @@ async function refreshDeviceToken(controllerUrl, refreshToken) {
   if (!refreshToken || typeof refreshToken !== 'string') {
     throw new Error('Refresh token is required');
   }
+  // Never send encrypted token to the API (causes 401). Decryption should happen in getDeviceToken; this is a safeguard.
+  if (isTokenEncrypted(refreshToken)) {
+    throw new Error('Refresh token is still encrypted; decryption may have failed. Run "aifabrix login" to authenticate again.');
+  }
 
   try {
     // Call API refresh endpoint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.33.0",
+  "version": "2.33.3",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {

package/templates/applications/dataplane/Dockerfile

@@ -0,0 +1,16 @@
+# AI Fabrix Dataplane - Build from base image
+# This repo has no application source; use the published image as baseline.
+# Build: docker build -t aifabrix/dataplane:local .
+# Or use the image directly: docker run aifabrix/dataplane:latest
+
+FROM aifabrix/dataplane:latest
+
+# Expose port (documentation; base image may already set this)
+EXPOSE 3001
+
+# Health check (documentation; base image may already set this)
+HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:3001/health || exit 1
+
+# CMD inherited from base image; override only if needed
+# CMD inherited: uvicorn app.main:app --host 0.0.0.0 --port 3001