@aifabrix/builder 2.32.2 → 2.33.0

package/lib/utils/help-builder.js

@@ -0,0 +1,190 @@
+/**
+ * Categorized help builder for AI Fabrix Builder CLI
+ *
+ * Groups commands into logical categories and outputs a user-friendly help.
+ *
+ * @fileoverview Categorized CLI help
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { Help } = require('commander');
+
+/**
+ * Command categories and order. Each command can have an optional `term` override
+ * for the help line (e.g. "down [app]"); otherwise the command name is used.
+ *
+ * @type {Array<{ name: string, commands: Array<{ name: string, term?: string }> }>}
+ */
+const CATEGORIES = [
+  {
+    name: 'Infrastructure (Local Development)',
+    commands: [
+      { name: 'up' },
+      { name: 'down', term: 'down [app]' },
+      { name: 'doctor' },
+      { name: 'status' },
+      { name: 'restart', term: 'restart <service>' }
+    ]
+  },
+  {
+    name: 'Authentication',
+    commands: [
+      { name: 'login' },
+      { name: 'logout' },
+      { name: 'auth' }
+    ]
+  },
+  {
+    name: 'Applications (Create & Develop)',
+    commands: [
+      { name: 'create', term: 'create <app>' },
+      { name: 'wizard' },
+      { name: 'build', term: 'build <app>' },
+      { name: 'run', term: 'run <app>' },
+      { name: 'dockerfile', term: 'dockerfile <app>' }
+    ]
+  },
+  {
+    name: 'Deployment',
+    commands: [
+      { name: 'push', term: 'push <app>' },
+      { name: 'deploy', term: 'deploy <app>' }
+    ]
+  },
+  {
+    name: 'Environments',
+    commands: [
+      { name: 'environment' },
+      { name: 'env' }
+    ]
+  },
+  {
+    name: 'Application & Datasource Management',
+    commands: [
+      { name: 'app' },
+      { name: 'datasource' }
+    ]
+  },
+  {
+    name: 'Configuration & Validation',
+    commands: [
+      { name: 'resolve', term: 'resolve <app>' },
+      { name: 'json', term: 'json <app>' },
+      { name: 'split-json', term: 'split-json <app>' },
+      { name: 'genkey', term: 'genkey <app>' },
+      { name: 'validate', term: 'validate <appOrFile>' },
+      { name: 'diff', term: 'diff <file1> <file2>' }
+    ]
+  },
+  {
+    name: 'External Systems',
+    commands: [
+      { name: 'download', term: 'download <system-key>' },
+      { name: 'delete', term: 'delete <system-key>' },
+      { name: 'test', term: 'test <app>' },
+      { name: 'test-integration', term: 'test-integration <app>' }
+    ]
+  },
+  {
+    name: 'Developer & Secrets',
+    commands: [
+      { name: 'dev' },
+      { name: 'secrets' },
+      { name: 'secure' }
+    ]
+  }
+];
+
+/**
+ * @param {object} helper - Commander Help instance
+ * @param {import('commander').Command} program
+ * @returns {string[]}
+ */
+function formatHeader(helper, program) {
+  const out = [`Usage: ${helper.commandUsage(program)}`, ''];
+  const desc = helper.commandDescription(program);
+  if (desc && String(desc).length > 0) {
+    out.push(helper.wrap(String(desc), helper.helpWidth || 80, 0), '');
+  }
+  return out;
+}
+
+/**
+ * @param {object} helper - Commander Help instance
+ * @param {import('commander').Command} program
+ * @returns {string[]}
+ */
+function formatOptions(helper, program) {
+  const options = helper.visibleOptions(program);
+  if (options.length === 0) return [];
+  const optTermWidth = options.reduce((max, o) => Math.max(max, helper.optionTerm(o).length), 0);
+  const out = ['Options:'];
+  for (const opt of options) {
+    out.push(`  ${helper.optionTerm(opt).padEnd(optTermWidth + 2)}${helper.optionDescription(opt)}`);
+  }
+  out.push('');
+  return out;
+}
+
+/**
+ * @param {object} helper - Commander Help instance
+ * @param {import('commander').Command} program
+ * @returns {{ categorized: Array<{ name: string, lines: Array<{ term: string, desc: string }> }>, pad: number }}
+ */
+function buildCategorizedWithPad(helper, program) {
+  const nameToCmd = new Map(program.commands.map((c) => [c.name(), c]));
+  const categorized = [];
+  let maxTermLen = 'help [command]'.length;
+
+  for (const cat of CATEGORIES) {
+    const lines = [];
+    for (const spec of cat.commands) {
+      const cmd = nameToCmd.get(spec.name);
+      if (!cmd) continue;
+      const term = spec.term || cmd.name();
+      maxTermLen = Math.max(maxTermLen, term.length);
+      const descText = helper.subcommandDescription(cmd) || cmd.description() || '';
+      lines.push({ term, desc: descText });
+    }
+    if (lines.length > 0) categorized.push({ name: cat.name, lines });
+  }
+  return { categorized, pad: maxTermLen + 2 };
+}
+
+/**
+ * @param {object} helper - Commander Help instance
+ * @param {import('commander').Command} program
+ * @returns {string[]}
+ */
+function formatCommandCategories(helper, program) {
+  const { categorized, pad } = buildCategorizedWithPad(helper, program);
+  const out = [];
+  for (const { name, lines } of categorized) {
+    out.push(name + ':');
+    for (const { term, desc: d } of lines) out.push(`  ${term.padEnd(pad)}${d}`);
+    out.push('');
+  }
+  out.push('Help:');
+  out.push(`  ${'help [command]'.padEnd(pad)}display help for command`);
+  out.push('');
+  return out;
+}
+
+/**
+ * Build the full categorized help string for the program.
+ *
+ * @param {import('commander').Command} program - Commander program
+ * @returns {string} Formatted help text
+ */
+function buildCategorizedHelp(program) {
+  const helper = new Help();
+  const output = [
+    ...formatHeader(helper, program),
+    ...formatOptions(helper, program),
+    ...formatCommandCategories(helper, program)
+  ];
+  return output.join('\n');
+}
+
+module.exports = { buildCategorizedHelp, CATEGORIES };

package/lib/utils/infra-status.js

@@ -38,7 +38,11 @@ async function getInfraStatus() {
     postgres: { port: ports.postgres, url: `localhost:${ports.postgres}` },
     redis: { port: ports.redis, url: `localhost:${ports.redis}` },
     pgadmin: { port: ports.pgadmin, url: `http://localhost:${ports.pgadmin}` },
-    'redis-commander': { port: ports.redisCommander, url: `http://localhost:${ports.redisCommander}` }
+    'redis-commander': { port: ports.redisCommander, url: `http://localhost:${ports.redisCommander}` },
+    traefik: {
+      port: `${ports.traefikHttp}/${ports.traefikHttps}`,
+      url: `http://localhost:${ports.traefikHttp}, https://localhost:${ports.traefikHttps}`
+    }
   };
 
   const status = {};
@@ -82,9 +86,15 @@ async function getInfraStatus() {
  */
 function getInfraContainerNames(devIdNum, devId) {
   if (devIdNum === 0) {
-    return ['aifabrix-postgres', 'aifabrix-redis', 'aifabrix-pgadmin', 'aifabrix-redis-commander'];
+    return ['aifabrix-postgres', 'aifabrix-redis', 'aifabrix-pgadmin', 'aifabrix-redis-commander', 'aifabrix-traefik'];
   }
-  return [`aifabrix-dev${devId}-postgres`, `aifabrix-dev${devId}-redis`, `aifabrix-dev${devId}-pgadmin`, `aifabrix-dev${devId}-redis-commander`];
+  return [
+    `aifabrix-dev${devId}-postgres`,
+    `aifabrix-dev${devId}-redis`,
+    `aifabrix-dev${devId}-pgadmin`,
+    `aifabrix-dev${devId}-redis-commander`,
+    `aifabrix-dev${devId}-traefik`
+  ];
 }
 
 /**

package/lib/utils/paths.js

@@ -408,13 +408,28 @@ function checkBuilderFolder(appName) {
  * Checks both integration/ and builder/ folders for backward compatibility
  *
  * @param {string} appName - Application name
- * @returns {Promise<{isExternal: boolean, appPath: string, appType: string}>}
+ * @param {Object} [options] - Detection options
+ * @param {string} [options.type] - Forced application type (external)
+ * @returns {Promise<{isExternal: boolean, appPath: string, appType: string, baseDir?: string}>}
  */
-async function detectAppType(appName) {
+async function detectAppType(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
 
+  if (options.type === 'external') {
+    const integrationPath = getIntegrationPath(appName);
+    if (!fs.existsSync(integrationPath)) {
+      throw new Error(`External system not found in integration/${appName}`);
+    }
+    return {
+      isExternal: true,
+      appPath: integrationPath,
+      appType: 'external',
+      baseDir: 'integration'
+    };
+  }
+
   // Check integration folder first (new structure)
   const integrationResult = checkIntegrationFolder(appName);
   if (integrationResult) {

package/lib/utils/port-resolver.js

@@ -0,0 +1,111 @@
+/**
+ * AI Fabrix Builder - Centralized Port Resolution
+ *
+ * Single source of truth for resolving application port from variables.yaml.
+ * Use getContainerPort for container/Docker/deployment/registration; use getLocalPort
+ * for local .env and dev-id–adjusted host port.
+ *
+ * @fileoverview Port resolution from variables (port, build.containerPort, build.localPort)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const yaml = require('js-yaml');
+
+/**
+ * Resolve container port from variables object.
+ * Precedence: build.containerPort → port → defaultPort.
+ * Used for: Dockerfile, container .env PORT, compose, deployment, app register, variable-transformer, builders, secrets-utils.
+ *
+ * @param {Object} variables - Parsed variables.yaml (or subset with build, port)
+ * @param {number} [defaultPort=3000] - Default when neither build.containerPort nor port is set
+ * @returns {number} Resolved container port
+ */
+function getContainerPort(variables, defaultPort = 3000) {
+  const v = variables || {};
+  return v.build?.containerPort ?? v.port ?? defaultPort;
+}
+
+/**
+ * Resolve local (development) port from variables object.
+ * Precedence: build.localPort (if number and > 0) → port → defaultPort.
+ * Used for: env-copy, env-ports, and as base for getLocalPortFromPath (secrets-helpers).
+ *
+ * @param {Object} variables - Parsed variables.yaml
+ * @param {number} [defaultPort=3000] - Default when neither build.localPort nor port is set
+ * @returns {number} Resolved local port
+ */
+function getLocalPort(variables, defaultPort = 3000) {
+  const v = variables || {};
+  const local = v.build?.localPort;
+  if (typeof local === 'number' && local > 0) {
+    return local;
+  }
+  return v.port ?? defaultPort;
+}
+
+/**
+ * Load variables from path. Returns null if path missing, not found, or parse error.
+ *
+ * @param {string} variablesPath - Path to variables.yaml
+ * @returns {Object|null} Parsed variables or null
+ */
+function loadVariablesFromPath(variablesPath) {
+  if (!variablesPath || !fs.existsSync(variablesPath)) {
+    return null;
+  }
+  try {
+    const content = fs.readFileSync(variablesPath, 'utf8');
+    return yaml.load(content) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve container port from variables.yaml path.
+ * Returns null when file is missing or neither build.containerPort nor port is set (for chaining with other sources).
+ *
+ * @param {string} variablesPath - Path to variables.yaml
+ * @returns {number|null} Container port or null
+ */
+function getContainerPortFromPath(variablesPath) {
+  const v = loadVariablesFromPath(variablesPath);
+  if (!v) {
+    return null;
+  }
+  const p = v.build?.containerPort ?? v.port;
+  return (p !== undefined && p !== null) ? p : null;
+}
+
+/**
+ * Resolve local port from variables.yaml path.
+ * Matches legacy getPortFromVariablesFile: build.localPort (if number and > 0) else variables.port or null.
+ * Returns null when file is missing or neither is set (for calculateAppPort chain).
+ *
+ * @param {string} variablesPath - Path to variables.yaml
+ * @returns {number|null} Local port or null
+ */
+function getLocalPortFromPath(variablesPath) {
+  const v = loadVariablesFromPath(variablesPath);
+  if (!v) {
+    return null;
+  }
+  const local = v.build?.localPort;
+  if (typeof local === 'number' && local > 0) {
+    return local;
+  }
+  const p = v.port;
+  return (p !== undefined && p !== null) ? p : null;
+}
+
+module.exports = {
+  getContainerPort,
+  getLocalPort,
+  getContainerPortFromPath,
+  getLocalPortFromPath,
+  loadVariablesFromPath
+};

package/lib/utils/secrets-helpers.js

@@ -17,6 +17,7 @@ const { rewriteInfraEndpoints, getEnvHosts, getServicePort, getServiceHost, getL
 const { loadEnvConfig } = require('./env-config-loader');
 const { updateContainerPortInEnvFile } = require('./env-ports');
 const { buildEnvVarMap } = require('./env-map');
+const { getLocalPortFromPath } = require('./port-resolver');
 
 /**
  * Interpolate ${VAR} occurrences with values from envVars map
@@ -145,26 +146,13 @@ function getPortFromLocalEnv(localEnv) {
 }
 
 /**
- * Gets port from variables.yaml file
+ * Gets port from variables.yaml file (build.localPort if positive, else port). Uses port-resolver.
  * @function getPortFromVariablesFile
  * @param {string} variablesPath - Path to variables.yaml
  * @returns {number|null} Port value or null
  */
 function getPortFromVariablesFile(variablesPath) {
-  if (!variablesPath || !fs.existsSync(variablesPath)) {
-    return null;
-  }
-  try {
-    const variablesContent = fs.readFileSync(variablesPath, 'utf8');
-    const variables = yaml.load(variablesContent);
-    const localPort = variables?.build?.localPort;
-    if (typeof localPort === 'number' && localPort > 0) {
-      return localPort;
-    }
-    return variables?.port || null;
-  } catch {
-    return null;
-  }
+  return getLocalPortFromPath(variablesPath);
 }
 
 /**

package/lib/utils/secrets-utils.js

@@ -14,6 +14,7 @@ const path = require('path');
 const yaml = require('js-yaml');
 const logger = require('./logger');
 const pathsUtil = require('./paths');
+const { getContainerPort } = require('./port-resolver');
 
 /**
  * Loads secrets from file with cascading lookup support
@@ -145,8 +146,7 @@ function resolveUrlPort(protocol, hostname, port, urlPath, hostnameToService) {
     const variablesContent = fs.readFileSync(serviceVariablesPath, 'utf8');
     const variables = yaml.load(variablesContent);
 
-    // Get containerPort or fall back to port
-    const containerPort = variables?.build?.containerPort || variables?.port || port;
+    const containerPort = getContainerPort(variables, port);
 
     // Replace port in URL
     return `${protocol}${hostname}:${containerPort}${urlPath}`;

package/lib/utils/token-manager.js

@@ -321,7 +321,7 @@ async function getDeploymentAuth(controllerUrl, environment, appName) {
 async function extractClientCredentials(authConfig, appKey, envKey, _options = {}) {
   if (authConfig.type === 'client-credentials') {
     if (!authConfig.clientId || !authConfig.clientSecret) {
-      throw new Error('Client ID and Client Secret are required');
+      throw new Error('Client ID and Client Secret are required for client-credentials authentication');
     }
     return {
       clientId: authConfig.clientId,
@@ -349,14 +349,77 @@ async function extractClientCredentials(authConfig, appKey, envKey, _options = {
       };
     }
 
-    // Construct clientId from controller, environment, and application key
-    // (not used, but shown in error message for reference)
-    throw new Error(`Client ID and Client Secret are required. Add credentials to ~/.aifabrix/secrets.local.yaml as '${appKey}-client-idKeyVault' and '${appKey}-client-secretKeyVault', or use credentials authentication.`);
+    // No credentials found - provide helpful error message
+    throw new Error(
+      'Client ID and Client Secret are required for deployment.\n' +
+      'Add credentials to ~/.aifabrix/secrets.local.yaml as:\n' +
+      `  '${appKey}-client-idKeyVault': <client-id>\n` +
+      `  '${appKey}-client-secretKeyVault': <client-secret>\n\n` +
+      'Or use credentials authentication with --client-id and --client-secret flags.'
+    );
   }
 
   throw new Error('Invalid authentication type');
 }
 
+/**
+ * Force refresh device token for controller (regardless of local expiry time)
+ * Used when server returns 401 even though local token hasn't expired
+ * @param {string} controllerUrl - Controller URL
+ * @returns {Promise<{token: string, controller: string}|null>} Token and controller URL, or null if not available
+ */
+async function forceRefreshDeviceToken(controllerUrl) {
+  // Try to get existing token to get refresh token
+  const tokenInfo = await getDeviceToken(controllerUrl);
+
+  if (!tokenInfo) {
+    return null;
+  }
+
+  // Must have refresh token to force refresh
+  if (!tokenInfo.refreshToken) {
+    logger.warn('Cannot refresh: no refresh token available. Please login again using: aifabrix login');
+    return null;
+  }
+
+  try {
+    const refreshed = await refreshDeviceToken(controllerUrl, tokenInfo.refreshToken);
+    return {
+      token: refreshed.token,
+      controller: controllerUrl
+    };
+  } catch (error) {
+    const errorMessage = error.message || String(error);
+    if (errorMessage.includes('Refresh token has expired')) {
+      logger.warn(`Refresh token expired: ${errorMessage}`);
+    } else {
+      logger.warn(`Failed to refresh device token: ${errorMessage}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Get device-only authentication for services that require user-level authentication.
+ * Used for interactive commands like wizard that don't support client credentials.
+ * @async
+ * @function getDeviceOnlyAuth
+ * @param {string} controllerUrl - Controller URL
+ * @returns {Promise<Object>} Auth config with device token
+ * @throws {Error} If device token is not available
+ */
+async function getDeviceOnlyAuth(controllerUrl) {
+  const deviceToken = await getOrRefreshDeviceToken(controllerUrl);
+  if (deviceToken && deviceToken.token) {
+    return {
+      type: 'bearer',
+      token: deviceToken.token,
+      controller: deviceToken.controller
+    };
+  }
+  throw new Error('Device token authentication required. Run "aifabrix login" to authenticate.');
+}
+
 module.exports = {
   getDeviceToken,
   getClientToken,
@@ -367,7 +430,9 @@ module.exports = {
   loadClientCredentials,
   getOrRefreshClientToken,
   getOrRefreshDeviceToken,
+  forceRefreshDeviceToken,
   getDeploymentAuth,
+  getDeviceOnlyAuth,
   extractClientCredentials
 };
 

package/lib/utils/variable-transformer.js

@@ -9,6 +9,8 @@
  * @version 2.0.0
  */
 
+const { getContainerPort } = require('./port-resolver');
+
 /**
  * Sanitizes authentication type - map keycloak to azure (schema allows: azure, local, none)
  * @function sanitizeAuthType
@@ -40,7 +42,7 @@ function buildBaseResult(variables, appName) {
     type: variables.type || 'webapp',
     image: variables.image,
     registryMode: variables.registryMode || 'external',
-    port: variables.port || 3000,
+    port: getContainerPort(variables, 3000),
     requiresDatabase: variables.requiresDatabase || false,
     requiresRedis: variables.requiresRedis || false,
     requiresStorage: variables.requiresStorage || false,
@@ -304,6 +306,9 @@ function transformSimpleOptionalFields(variables, transformed) {
   if (variables.permissions) {
     transformed.permissions = variables.permissions;
   }
+  if (variables.externalIntegration) {
+    transformed.externalIntegration = variables.externalIntegration;
+  }
 }
 
 /**
@@ -356,7 +361,7 @@ function buildBaseTransformedStructure(variables, appName) {
     type: variables.app?.type || 'webapp',
     image: imageRef,
     registryMode: variables.image?.registryMode || 'external',
-    port: variables.port || 3000,
+    port: getContainerPort(variables, 3000),
     requiresDatabase: requires.database || false,
     requiresRedis: requires.redis || false,
     requiresStorage: requires.storage || false,