@aifabrix/builder 2.45.5 → 2.47.0

package/lib/utils/api.js

@@ -10,7 +10,8 @@
  * @version 2.0.0
  */
 
-const { parseErrorResponse } = require('./api-error-handler');
+const { parseErrorResponse, formatNetworkError } = require('./api-error-handler');
+const { inferServiceLabelFromUrl } = require('./service-url-label');
 const auditLogger = require('../core/audit-logger');
 
 /** Default timeout for HTTP requests (ms). Prevents hanging when the controller is unreachable. 30s allows Azure Web App cold start to complete. */
@@ -172,7 +173,7 @@ async function handleSuccessResponse(response, url, options, duration) {
  * @throws {Error} If URL is empty, null, undefined, whitespace-only, or malformed
  */
 function validateUrl(url, urlType = 'URL') {
-  if (!url || typeof url !== 'string') {
+  if (url === null || url === undefined || typeof url !== 'string') {
     throw new Error(`${urlType} is required and must be a string (received: ${JSON.stringify(url)})`);
   }
   const trimmedUrl = url.trim();
@@ -248,20 +249,18 @@ async function handleNetworkError(error, url, options, duration) {
   const flat = flattenNetworkErrorDetail(error);
   const errorMessage = withUrlContextForNetworkError(flat || error.message, url);
 
-  const parsedError = parseErrorResponse(errorMessage, 0, true);
-
-  // Extract controller URL from full URL for error data
-  let controllerUrl = null;
+  let serviceBaseUrl = null;
   const endpointUrl = url;
   if (url && typeof url === 'string' && url.trim()) {
     try {
       const urlObj = new URL(url);
-      controllerUrl = `${urlObj.protocol}//${urlObj.host}`;
+      serviceBaseUrl = `${urlObj.protocol}//${urlObj.host}`;
     } catch {
-      // If URL parsing fails, use the full URL as endpoint
-      controllerUrl = null;
+      serviceBaseUrl = null;
     }
   }
+  const serviceLabel = inferServiceLabelFromUrl(endpointUrl);
+  const parsedError = parseErrorResponse(errorMessage, 0, true);
 
   await logApiPerformance({
     url,
@@ -276,24 +275,61 @@ 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
+    controllerUrl: serviceBaseUrl,
+    endpointUrl: endpointUrl,
+    serviceLabel
   };
+  const formattedError = formatNetworkError(errorMessage, errorData);
 
   return {
     success: false,
-    error: parsedError.message,
+    error: errorMessage,
     errorData: errorData,
-    errorType: parsedError.type,
-    formattedError: parsedError.formatted,
+    errorType: 'network',
+    formattedError,
     network: true,
     originalError: error
   };
 }
 
+/**
+ * @param {Object} options - Fetch options passed to makeApiCall
+ * @returns {{ fetchOptions: Object, singleRequestTimeoutMs: number }}
+ */
+function prepareFetchOptionsForRequest(options) {
+  const fetchOptions = { ...options };
+  const singleRequestTimeoutMs = resolveSingleRequestTimeoutMs(fetchOptions);
+  if (!fetchOptions.signal) {
+    fetchOptions.signal = AbortSignal.timeout(singleRequestTimeoutMs);
+  }
+  delete fetchOptions.timeoutMs;
+  delete fetchOptions.requestTimeoutMs;
+  return { fetchOptions, singleRequestTimeoutMs };
+}
+
+/**
+ * @param {Error} err
+ * @param {string} url
+ * @param {number} singleRequestTimeoutMs
+ * @returns {Error}
+ */
+function normalizeFetchNetworkError(err, url, singleRequestTimeoutMs) {
+  if (err?.name !== 'AbortError') {
+    return err;
+  }
+  const serviceLabel = inferServiceLabelFromUrl(url);
+  const serviceName =
+    serviceLabel === 'dataplane'
+      ? 'dataplane'
+      : serviceLabel === 'controller'
+        ? 'controller'
+        : 'service';
+  return new Error(
+    `Request timed out after ${Math.round(singleRequestTimeoutMs / 1000)} seconds. The ${serviceName} may be unreachable. Check the URL and network.`
+  );
+}
+
 /**
  * Make an API call with proper error handling
  * Uses a 30s timeout by default. Pass ``options.timeoutMs`` or ``options.requestTimeoutMs`` for
@@ -304,22 +340,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);
+    return await handleNetworkError(error, url || '', options, 0);
   }
 
   const startTime = Date.now();
-  const fetchOptions = { ...options };
-  const singleRequestTimeoutMs = resolveSingleRequestTimeoutMs(fetchOptions);
-  if (!fetchOptions.signal) {
-    fetchOptions.signal = AbortSignal.timeout(singleRequestTimeoutMs);
-  }
-  delete fetchOptions.timeoutMs;
-  delete fetchOptions.requestTimeoutMs;
+  const { fetchOptions, singleRequestTimeoutMs } = prepareFetchOptionsForRequest(options);
 
   try {
     const response = await fetch(url, fetchOptions);
@@ -332,11 +360,7 @@ async function makeApiCall(url, options = {}) {
     return await handleSuccessResponse(response, url, options, duration);
   } catch (err) {
     const duration = Date.now() - startTime;
-    const error = err?.name === 'AbortError'
-      ? new Error(
-        `Request timed out after ${Math.round(singleRequestTimeoutMs / 1000)} seconds. The controller may be unreachable. Check the URL and network.`
-      )
-      : err;
+    const error = normalizeFetchNetworkError(err, url, singleRequestTimeoutMs);
     return await handleNetworkError(error, url, options, duration);
   }
 }

package/lib/utils/app-relative-path-env.js

@@ -0,0 +1,112 @@
+/**
+ * Per-app virtual-directory env var names ({@code <NAME>_RELATIVE_PATH}) for Builder CLI.
+ *
+ * @fileoverview {@code app.key} → {@code DATAPLANE_RELATIVE_PATH}, {@code MYAPP_RELATIVE_PATH}, etc.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** Must match {@link module:lib/utils/url-declarative-vdir-inactive-env} token (avoid circular require). */
+const URL_DECLARATIVE_VDIR_PUBLIC_TOKEN = 'url://vdir-public';
+
+/** Suffix for runtime mount vars derived from {@code application.yaml} {@code app.key}. */
+const APP_RELATIVE_PATH_ENV_SUFFIX = '_RELATIVE_PATH';
+
+/**
+ * Apps whose runtime vdir env name is not {@code UPPER(appKey)_RELATIVE_PATH}.
+ * @type {Readonly<Record<string, string>>}
+ */
+const APP_RELATIVE_PATH_ENV_KEY_OVERRIDES = Object.freeze({
+  keycloak: 'KC_HTTP_RELATIVE_PATH',
+  'miso-controller': 'MISO_RELATIVE_PATH'
+});
+
+/** Always rewritten to "/" when front-door path is inactive (shared infra apps). */
+const INACTIVE_VDIR_PUBLIC_STATIC_ENV_KEYS = Object.freeze([
+  'KC_HTTP_RELATIVE_PATH',
+  'MISO_RELATIVE_PATH'
+]);
+
+/**
+ * @param {string} appKey - {@code application.yaml} {@code app.key}
+ * @returns {string} e.g. {@code dataplane} → {@code DATAPLANE_RELATIVE_PATH}, {@code myapp} → {@code MYAPP_RELATIVE_PATH}
+ */
+function appKeyToRelativePathEnvKey(appKey) {
+  const key = String(appKey || '').trim();
+  if (!key) {
+    return '';
+  }
+  const override = APP_RELATIVE_PATH_ENV_KEY_OVERRIDES[key];
+  if (override) {
+    return override;
+  }
+  const upper = key.replace(/-/g, '_').toUpperCase();
+  return `${upper}${APP_RELATIVE_PATH_ENV_SUFFIX}`;
+}
+
+/**
+ * Whether {@code key} is a runtime vdir env name (static Keycloak/Miso or {@code NAME_RELATIVE_PATH}).
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isAppRelativePathEnvKey(key) {
+  const name = String(key || '').trim();
+  if (!name) {
+    return false;
+  }
+  if (INACTIVE_VDIR_PUBLIC_STATIC_ENV_KEYS.includes(name)) {
+    return true;
+  }
+  return name.endsWith(APP_RELATIVE_PATH_ENV_SUFFIX);
+}
+
+/**
+ * Env keys to rewrite when path is inactive: static Keycloak/Miso + current app vdir key.
+ * @param {string|null|undefined} appKey - {@code application.yaml} {@code app.key}
+ * @returns {ReadonlySet<string>}
+ */
+function resolveInactiveVdirRewriteEnvKeys(appKey) {
+  const keys = new Set(INACTIVE_VDIR_PUBLIC_STATIC_ENV_KEYS);
+  const envKey = appKeyToRelativePathEnvKey(appKey);
+  if (envKey) {
+    keys.add(envKey);
+  }
+  return keys;
+}
+
+/**
+ * When an app is created from a product template, rename the template's {@code *_RELATIVE_PATH}
+ * line to match {@code app.key} (e.g. {@code DATAPLANE_RELATIVE_PATH} → {@code MYAPP_RELATIVE_PATH}).
+ * @param {string} content - {@code env.template} body
+ * @param {string} appKey
+ * @returns {string}
+ */
+function renameAppRelativePathEnvKeyInTemplate(content, appKey) {
+  const targetKey = appKeyToRelativePathEnvKey(appKey);
+  if (!targetKey || !content || !content.includes(URL_DECLARATIVE_VDIR_PUBLIC_TOKEN)) {
+    return content;
+  }
+  const escapedToken = URL_DECLARATIVE_VDIR_PUBLIC_TOKEN.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const lineRe = new RegExp(
+    `^([ \\t]*)([A-Z][A-Z0-9_]*${APP_RELATIVE_PATH_ENV_SUFFIX})([ \\t]*=\\s*)${escapedToken}[ \\t]*$`,
+    'gm'
+  );
+  return content.replace(lineRe, (match, indent, currentKey, eq) => {
+    if (currentKey === targetKey) {
+      return match;
+    }
+    return `${indent}${targetKey}${eq}${URL_DECLARATIVE_VDIR_PUBLIC_TOKEN}`;
+  });
+}
+
+module.exports = {
+  APP_RELATIVE_PATH_ENV_SUFFIX,
+  APP_RELATIVE_PATH_ENV_KEY_OVERRIDES,
+  INACTIVE_VDIR_PUBLIC_STATIC_ENV_KEYS,
+  appKeyToRelativePathEnvKey,
+  isAppRelativePathEnvKey,
+  resolveInactiveVdirRewriteEnvKeys,
+  renameAppRelativePathEnvKeyInTemplate
+};

package/lib/utils/app-run-containers.js

@@ -85,6 +85,27 @@ async function logContainerDebugInfo(containerName) {
   logger.log(chalk.gray(`[DEBUG] Container ports: ${ports.trim()}`));
 }
 
+/**
+ * @param {string} stdout - `docker ps --format "{{.Names}}"` output
+ * @returns {string[]}
+ */
+function parseDockerPsNameLines(stdout) {
+  return String(stdout || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+/**
+ * True when an exact container name appears in docker ps output (not a substring sibling).
+ * @param {string} containerName
+ * @param {string} stdout
+ * @returns {boolean}
+ */
+function isExactContainerNameInPsOutput(containerName, stdout) {
+  return parseDockerPsNameLines(stdout).includes(containerName);
+}
+
 async function checkContainerRunning(appName, developerId, debug = false, scopeOpts = null) {
   try {
     const containerName = getContainerName(appName, developerId, scopeOpts);
@@ -93,7 +114,7 @@ async function checkContainerRunning(appName, developerId, debug = false, scopeO
       logger.log(chalk.gray(`[DEBUG] Executing: ${cmd}`));
     }
     const { stdout } = await execWithDockerEnv(cmd);
-    const isRunning = stdout.trim() === containerName;
+    const isRunning = isExactContainerNameInPsOutput(containerName, stdout);
     if (debug) {
       logger.log(chalk.gray(`[DEBUG] Container ${containerName} running: ${isRunning}`));
       if (isRunning) {
@@ -161,6 +182,8 @@ module.exports = {
   checkContainerRunning,
   stopAndRemoveContainer,
   logContainerStatus,
-  getContainerName
+  getContainerName,
+  parseDockerPsNameLines,
+  isExactContainerNameInPsOutput
 };
 

package/lib/utils/authentication-shape.js

@@ -0,0 +1,224 @@
+/**
+ * External system authentication shape helpers (schema 2.4.x nested credential).
+ *
+ * @fileoverview Normalize flat legacy auth blocks to authType + credential template
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getKvPathSegmentForSecurityKey } = require('./credential-secrets-env');
+
+/**
+ * @param {Object|null|undefined} authentication
+ * @returns {Object|null} Credential template (method, variables, security) or null
+ */
+function getAuthCredentialTemplate(authentication) {
+  if (!authentication || typeof authentication !== 'object') {
+    return null;
+  }
+  if (authentication.authType === 'credential' && authentication.credential) {
+    return authentication.credential;
+  }
+  if (authentication.method) {
+    return authentication;
+  }
+  return null;
+}
+
+/**
+ * @param {Object|null|undefined} authentication
+ * @returns {string}
+ */
+function getAuthMethodFromAuthentication(authentication) {
+  const credential = getAuthCredentialTemplate(authentication);
+  return String(credential?.method || authentication?.method || '').trim();
+}
+
+/**
+ * Builds flat credential template fields (method, variables, security) for a method.
+ * @param {string} systemKey
+ * @param {string} authType
+ * @returns {{ method: string, variables: Object, security: Object }}
+ */
+function buildFlatCredentialTemplate(systemKey, authType) {
+  const kvPath = (securityKey) => {
+    const segment = getKvPathSegmentForSecurityKey(securityKey);
+    return segment ? `kv://${systemKey}/${segment}` : null;
+  };
+  const method = authType || 'apikey';
+  const base = 'https://api.example.com';
+
+  const authMap = {
+    oauth2: {
+      variables: { baseUrl: base, tokenUrl: `${base}/oauth/token`, authorizationUrl: `${base}/oauth/authorize` },
+      security: { clientId: kvPath('clientId'), clientSecret: kvPath('clientSecret') }
+    },
+    aad: {
+      variables: {
+        baseUrl: base,
+        tokenUrl: 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token',
+        tenantId: '{tenant-id}'
+      },
+      security: { clientId: kvPath('clientId'), clientSecret: kvPath('clientSecret') }
+    },
+    apikey: {
+      variables: { baseUrl: base, headerName: 'X-API-Key' },
+      security: { apiKey: kvPath('apiKey') }
+    },
+    bearerToken: {
+      variables: { baseUrl: base, headerName: 'Authorization', prefix: 'Bearer' },
+      security: { token: kvPath('token') }
+    },
+    basic: {
+      variables: { baseUrl: base },
+      security: { username: kvPath('username'), password: kvPath('password') }
+    },
+    queryParam: {
+      variables: { baseUrl: base, paramName: 'api_key' },
+      security: { paramValue: kvPath('paramValue') }
+    },
+    oidc: {
+      variables: { openIdConfigUrl: 'https://example.com/.well-known/openid-configuration', clientId: 'app-id' },
+      security: {}
+    },
+    hmac: {
+      variables: { baseUrl: base, algorithm: 'sha256', signatureHeader: 'X-Signature' },
+      security: { signingSecret: kvPath('signingSecret') }
+    },
+    none: {
+      variables: {},
+      security: {}
+    }
+  };
+
+  const auth = authMap[method] || authMap.apikey;
+  return { method, variables: auth.variables, security: auth.security };
+}
+
+/**
+ * Builds schema-compliant authentication block for external-system.schema.json.
+ * @param {string} systemKey
+ * @param {string} authType - oauth2, apikey, bearerToken, none, …
+ * @returns {Object}
+ */
+function buildAuthenticationFromMethod(systemKey, authType) {
+  const method = authType || 'apikey';
+  if (method === 'none') {
+    return { authType: 'none' };
+  }
+  const flat = buildFlatCredentialTemplate(systemKey, method);
+  return {
+    authType: 'credential',
+    credential: {
+      credentialKey: `${systemKey}-cred`,
+      method: flat.method,
+      variables: flat.variables,
+      security: flat.security,
+      writeOnce: true
+    }
+  };
+}
+
+/**
+ * @param {Object} authentication
+ * @param {string} systemKey
+ * @returns {{ authentication: Object, changed: boolean }}
+ */
+function normalizeNestedCredentialBlock(authentication, systemKey) {
+  const credential = { ...authentication.credential };
+  let changed = Object.keys(authentication).some((k) => !['authType', 'credential'].includes(k));
+  if (!credential.credentialKey) {
+    credential.credentialKey = `${systemKey}-cred`;
+    changed = true;
+  }
+  if (credential.writeOnce === undefined) {
+    credential.writeOnce = true;
+    changed = true;
+  }
+  return { authentication: { authType: 'credential', credential }, changed };
+}
+
+/**
+ * @param {Object} flatAuth
+ * @param {string} systemKey
+ * @returns {{ authentication: Object, changed: boolean }}
+ */
+function wrapFlatAuthAsNested(flatAuth, systemKey) {
+  const credential = {
+    credentialKey: flatAuth.credentialKey || `${systemKey}-cred`,
+    method: flatAuth.method,
+    variables: flatAuth.variables && typeof flatAuth.variables === 'object' ? flatAuth.variables : {},
+    security: flatAuth.security && typeof flatAuth.security === 'object' ? flatAuth.security : {},
+    writeOnce: flatAuth.writeOnce !== false
+  };
+  if (flatAuth.displayName) {
+    credential.displayName = flatAuth.displayName;
+  }
+  return { authentication: { authType: 'credential', credential }, changed: true };
+}
+
+/**
+ * Migrates legacy flat authentication to nested authType + credential.
+ * @param {Object|null|undefined} authentication
+ * @param {string} systemKey
+ * @returns {{ authentication: Object, changed: boolean }}
+ */
+function migrateAuthenticationToNestedSchema(authentication, systemKey) {
+  if (!authentication || typeof authentication !== 'object') {
+    return { authentication: authentication || { authType: 'none' }, changed: false };
+  }
+  if (authentication.authType === 'none') {
+    return { authentication: { authType: 'none' }, changed: false };
+  }
+  if (authentication.authType === 'apiProvider' && authentication.apiProvider) {
+    return { authentication, changed: false };
+  }
+  if (authentication.authType === 'credential' && authentication.credential) {
+    return normalizeNestedCredentialBlock(authentication, systemKey);
+  }
+  if (authentication.method) {
+    return wrapFlatAuthAsNested(authentication, systemKey);
+  }
+  return { authentication, changed: false };
+}
+
+/**
+ * Align credential kv:// paths and credentialKey with the integration system key (wizard output).
+ * @param {Object|null|undefined} authentication
+ * @param {string} systemKey
+ * @param {string} [authDisplayName]
+ */
+function normalizeAuthenticationToSystemKey(authentication, systemKey, authDisplayName) {
+  if (!authentication || typeof authentication !== 'object') return;
+  const migrated = migrateAuthenticationToNestedSchema(authentication, systemKey);
+  Object.assign(authentication, migrated.authentication);
+  const credential = authentication.authType === 'credential' ? authentication.credential : null;
+  if (!credential) return;
+  credential.credentialKey = `${systemKey}-cred`;
+  const security = credential.security;
+  if (security && typeof security === 'object') {
+    for (const k of Object.keys(security)) {
+      const v = security[k];
+      if (typeof v === 'string' && v.startsWith('kv://')) {
+        const rest = v.slice(5);
+        const idx = rest.indexOf('/');
+        const suffix = idx >= 0 ? rest.slice(idx + 1) : '';
+        security[k] = suffix ? `kv://${systemKey}/${suffix}` : `kv://${systemKey}`;
+      }
+    }
+  }
+  if (authDisplayName) {
+    credential.displayName = authDisplayName;
+  }
+}
+
+module.exports = {
+  getAuthCredentialTemplate,
+  getAuthMethodFromAuthentication,
+  buildFlatCredentialTemplate,
+  buildAuthenticationFromMethod,
+  migrateAuthenticationToNestedSchema,
+  normalizeAuthenticationToSystemKey
+};

package/lib/utils/build-copy.js

@@ -14,6 +14,11 @@ const fs = require('fs').promises;
 const fsSync = require('fs');
 const path = require('path');
 const paths = require('./paths');
+const { formatWarningLine } = require('./cli-test-layout-chalk');
+const logger = require('./logger');
+
+/** Builder `.env` is not copied into the dev workspace (plan 139: resolve in-memory; run uses `.env.run`). */
+const BUILD_WORKSPACE_SKIP_FILES = new Set(['.env']);
 
 /**
  * Copies all files from builder directory to developer-specific directory
@@ -81,8 +86,11 @@ async function copyDirectory(sourceDir, targetDir) {
   const entries = await fs.readdir(sourceDir);
 
   for (const entry of entries) {
-    // Skip hidden files and directories (but allow .env, .gitignore, etc.)
-    if (entry.startsWith('.') && entry !== '.env' && entry !== '.gitignore') {
+    if (BUILD_WORKSPACE_SKIP_FILES.has(entry)) {
+      continue;
+    }
+    // Skip hidden files and directories (allow .gitignore)
+    if (entry.startsWith('.') && entry !== '.gitignore') {
       continue;
     }
 
@@ -92,12 +100,35 @@ async function copyDirectory(sourceDir, targetDir) {
     const stats = await fs.stat(sourcePath);
 
     if (stats.isDirectory()) {
-      // Recursively copy subdirectories
       await copyDirectory(sourcePath, targetPath);
     } else if (stats.isFile()) {
-      // Copy file
-      await fs.copyFile(sourcePath, targetPath);
+      await copyFileToWorkspace(sourcePath, targetPath, entry);
+    }
+  }
+}
+
+/**
+ * Copy a single file into the dev workspace; skip unreadable files instead of failing the build.
+ * @async
+ * @param {string} sourcePath
+ * @param {string} targetPath
+ * @param {string} entryName
+ */
+async function copyFileToWorkspace(sourcePath, targetPath, entryName) {
+  try {
+    await fs.copyFile(sourcePath, targetPath);
+  } catch (err) {
+    const code = err && err.code ? String(err.code) : '';
+    if (code === 'EACCES' || code === 'EPERM') {
+      logger.log(
+        formatWarningLine(
+          `Skipped ${entryName} during workspace copy (permission denied). ` +
+            'Use "aifabrix resolve <app>" for a persistent .env when needed.'
+        )
+      );
+      return;
     }
+    throw err;
   }
 }