@aifabrix/builder 2.32.2 → 2.33.0

package/lib/app/list.js

@@ -126,14 +126,35 @@ async function findDeviceTokenFromConfig(deviceConfig) {
   return null;
 }
 
+/**
+ * Format URL and port for display
+ * @param {Object} app - Application object
+ * @returns {string} Formatted URL and port string
+ */
+function formatUrlAndPort(app) {
+  const url = app.url || app.dataplaneUrl || app.dataplane?.url || app.configuration?.dataplaneUrl || null;
+  const port = app.port || app.configuration?.port || null;
+
+  const parts = [];
+  if (url) {
+    parts.push(`URL: ${chalk.blue(url)}`);
+  }
+  if (port) {
+    parts.push(`Port: ${chalk.blue(port)}`);
+  }
+
+  return parts.length > 0 ? ` (${parts.join(', ')})` : '';
+}
+
 /**
  * Display applications list
  * @param {Array} applications - Array of application objects
  * @param {string} environment - Environment name or key
+ * @param {string} controllerUrl - Controller URL
  */
-function displayApplications(applications, environment) {
+function displayApplications(applications, environment, controllerUrl) {
   const environmentName = environment || 'miso';
-  const header = `Applications in ${environmentName} environment`;
+  const header = `Applications in ${environmentName} environment (${controllerUrl})`;
 
   if (applications.length === 0) {
     logger.log(chalk.bold(`\n📱 ${header}:\n`));
@@ -144,7 +165,8 @@ function displayApplications(applications, environment) {
   logger.log(chalk.bold(`\n📱 ${header}:\n`));
   applications.forEach((app) => {
     const hasPipeline = app.configuration?.pipeline?.isActive ? '✓' : '✗';
-    logger.log(`${hasPipeline} ${chalk.cyan(app.key)} - ${app.displayName} (${app.status || 'unknown'})`);
+    const urlAndPort = formatUrlAndPort(app);
+    logger.log(`${hasPipeline} ${chalk.cyan(app.key)} - ${app.displayName} (${app.status || 'unknown'})${urlAndPort}`);
   });
   logger.log('');
 }
@@ -152,23 +174,19 @@ function displayApplications(applications, environment) {
 /**
  * Try to get device token from controller URL
  * @async
- * @param {string} controllerUrl - Controller URL
- * @returns {Promise<Object|null>} Object with token and controllerUrl, or null
+ * @param {string} controllerUrl - Controller URL (explicitly provided by user)
+ * @returns {Promise<Object|null>} Object with token and controllerUrl, or null if token not found
+ * @throws {Error} If authentication/refresh fails
  */
 async function tryGetTokenFromController(controllerUrl) {
-  try {
-    const normalizedUrl = normalizeControllerUrl(controllerUrl);
-    const deviceToken = await getOrRefreshDeviceToken(normalizedUrl);
-    if (deviceToken && deviceToken.token) {
-      return {
-        token: deviceToken.token,
-        actualControllerUrl: deviceToken.controller || normalizedUrl
-      };
-    }
-  } catch (error) {
-    logger.error(chalk.red(`❌ Failed to authenticate with controller: ${controllerUrl}`));
-    logger.error(chalk.gray(`Error: ${error.message}`));
-    process.exit(1);
+  const normalizedUrl = normalizeControllerUrl(controllerUrl);
+  const deviceToken = await getOrRefreshDeviceToken(normalizedUrl);
+  if (deviceToken && deviceToken.token) {
+    // Always use the provided controller URL (normalized) to ensure we use the exact URL the user specified
+    return {
+      token: deviceToken.token,
+      actualControllerUrl: normalizedUrl
+    };
   }
   return null;
 }
@@ -215,25 +233,36 @@ function validateAuthToken(token, actualControllerUrl, controllerUrl) {
 /**
  * Get authentication token for listing applications
  * @async
- * @param {string} [controllerUrl] - Optional controller URL
+ * @param {string} [controllerUrl] - Optional controller URL (if provided, must use this specific URL)
  * @param {Object} config - Configuration object
  * @returns {Promise<Object>} Object with token and actualControllerUrl
  * @throws {Error} If authentication fails
  */
 async function getListAuthToken(controllerUrl, config) {
-  // Try to get token from controller URL first
-  let authResult = null;
+  // If controller URL is explicitly provided, use only that URL (no fallback)
   if (controllerUrl) {
-    authResult = await tryGetTokenFromController(controllerUrl);
+    const authResult = await tryGetTokenFromController(controllerUrl);
+    if (!authResult || !authResult.token) {
+      // No token found for explicitly provided controller URL
+      logger.error(chalk.red(`❌ No authentication token found for controller: ${controllerUrl}`));
+      logger.error(chalk.gray('Please login to this controller using: aifabrix login'));
+      process.exit(1);
+      // Return to prevent further execution in tests where process.exit is mocked
+      return { token: null, actualControllerUrl: null };
+    }
+    return validateAuthToken(authResult.token, authResult.actualControllerUrl, controllerUrl);
   }
 
-  // If no token yet, try to find device token from config
-  if (!authResult && config.device) {
-    authResult = await tryGetTokenFromConfig(config.device);
+  // If no controller URL provided, try to find device token from config
+  if (config.device) {
+    const authResult = await tryGetTokenFromConfig(config.device);
+    if (authResult && authResult.token) {
+      return validateAuthToken(authResult.token, authResult.actualControllerUrl, null);
+    }
   }
 
-  // Validate and return token or exit
-  return validateAuthToken(authResult?.token || null, authResult?.actualControllerUrl || null, controllerUrl);
+  // No token found anywhere
+  return validateAuthToken(null, null, null);
 }
 
 /**
@@ -257,26 +286,38 @@ function handleListResponse(response, actualControllerUrl) {
 }
 
 /**
- * List applications in an environment
+ * List applications in an environment.
+ * Controller and environment come from config.yaml (set via aifabrix login or aifabrix auth config).
  * @async
- * @param {Object} options - Command options
- * @param {string} options.environment - Environment ID or key
- * @param {string} [options.controller] - Controller URL (optional, uses configured controller if not provided)
+ * @param {Object} [_options] - Command options (reserved)
  * @throws {Error} If listing fails
  */
-async function listApplications(options) {
-  const config = await getConfig();
+async function listApplications(options = {}) {
+  const { resolveControllerUrl } = require('../utils/controller-url');
+  const { resolveEnvironment } = require('../core/config');
 
-  // Get authentication token
-  const controllerUrl = options.controller || null;
+  const controllerUrl = options.controller || (await resolveControllerUrl());
+  if (!controllerUrl) {
+    logger.error(chalk.red('❌ Controller URL is required. Run "aifabrix login" to set the controller URL in config.yaml'));
+    process.exit(1);
+    return;
+  }
+
+  const environment = options.environment || (await resolveEnvironment());
+  const config = await getConfig();
   const { token, actualControllerUrl } = await getListAuthToken(controllerUrl, config);
 
+  // Check if authentication succeeded (may be null after process.exit in tests)
+  if (!token || !actualControllerUrl) {
+    return;
+  }
+
   // Use centralized API client
   const authConfig = { type: 'bearer', token: token };
   try {
-    const response = await listEnvironmentApplications(actualControllerUrl, options.environment, authConfig);
+    const response = await listEnvironmentApplications(actualControllerUrl, environment, authConfig);
     const applications = handleListResponse(response, actualControllerUrl);
-    displayApplications(applications, options.environment);
+    displayApplications(applications, environment, actualControllerUrl);
   } catch (error) {
     logger.error(chalk.red(`❌ Failed to list applications from controller: ${actualControllerUrl}`));
     logger.error(chalk.gray(`Error: ${error.message}`));

package/lib/app/prompts.js

@@ -9,6 +9,7 @@
  */
 
 const inquirer = require('inquirer');
+const { getDefaultControllerUrl } = require('../utils/controller-url');
 
 /**
  * Builds basic questions (port, language)
@@ -223,10 +224,11 @@ function buildExternalSystemQuestions(options, appName) {
 
 /**
  * Builds workflow questions (GitHub, Controller)
+ * @async
  * @param {Object} options - Provided options
- * @returns {Array} Array of question objects
+ * @returns {Promise<Array>} Array of question objects
  */
-function buildWorkflowQuestions(options) {
+async function buildWorkflowQuestions(options) {
   const questions = [];
 
   // GitHub workflows
@@ -255,11 +257,13 @@ function buildWorkflowQuestions(options) {
   if (!options.controllerUrl && options.controller &&
       !Object.prototype.hasOwnProperty.call(options, 'controllerUrl')) {
     const misoHost = process.env.MISO_HOST || 'localhost';
+    const defaultControllerUrl = await getDefaultControllerUrl();
+    const defaultUrl = defaultControllerUrl.replace('http://localhost:', `http://${misoHost}:`);
     questions.push({
       type: 'input',
       name: 'controllerUrl',
       message: 'Enter Controller URL:',
-      default: `http://${misoHost}:3000`,
+      default: defaultUrl,
       when: (answers) => answers.controller === true
     });
   }
@@ -424,14 +428,14 @@ async function promptForOptions(appName, options) {
     // For external type, prompt for external system configuration
     questions = [
       ...buildExternalSystemQuestions(options, appName),
-      ...buildWorkflowQuestions(options)
+      ...(await buildWorkflowQuestions(options))
     ];
   } else {
     // For regular apps, use standard prompts
     questions = [
       ...buildBasicQuestions(options, appType),
       ...buildServiceQuestions(options, appType),
-      ...buildWorkflowQuestions(options)
+      ...(await buildWorkflowQuestions(options))
     ];
   }
 

package/lib/app/readme.js

@@ -12,6 +12,7 @@ const fs = require('fs').promises;
 const fsSync = require('fs');
 const path = require('path');
 const handlebars = require('handlebars');
+const { generateExternalReadmeContent } = require('../utils/external-readme');
 
 /**
  * Checks if a file exists
@@ -86,6 +87,27 @@ function extractServiceFlags(config) {
   };
 }
 
+/**
+ * Builds placeholder datasources for external README generation
+ * @function buildExternalDatasourcePlaceholders
+ * @param {number} datasourceCount - Datasource count
+ * @returns {Array<Object>} Datasource placeholders
+ */
+function buildExternalDatasourcePlaceholders(systemKey, datasourceCount) {
+  const normalizedCount = Number.isInteger(datasourceCount)
+    ? datasourceCount
+    : parseInt(datasourceCount, 10);
+  const total = Number.isFinite(normalizedCount) && normalizedCount > 0 ? normalizedCount : 0;
+  return Array.from({ length: total }, (_value, index) => {
+    const entityType = `entity${index + 1}`;
+    return {
+      entityType,
+      displayName: `Datasource ${index + 1}`,
+      fileName: `${systemKey}-datasource-${entityType}.json`
+    };
+  });
+}
+
 /**
  * Builds template context for README generation
  * @function buildReadmeContext
@@ -95,8 +117,11 @@ function extractServiceFlags(config) {
  */
 function buildReadmeContext(appName, config) {
   const displayName = formatAppDisplayName(appName);
-  const imageName = `aifabrix/${appName}`;
-  const port = config.port || 3000;
+  const port = config.port ?? 3000;
+  const localPort = (typeof config.build?.localPort === 'number' && config.build.localPort > 0)
+    ? config.build.localPort
+    : port;
+  const imageName = config.image?.name || `aifabrix/${appName}`;
   // Extract registry from nested structure (config.image.registry) or flattened (config.registry)
   const registry = config.image?.registry || config.registry || 'myacr.azurecr.io';
 
@@ -108,6 +133,7 @@ function buildReadmeContext(appName, config) {
     displayName,
     imageName,
     port,
+    localPort,
     registry,
     ...serviceFlags,
     hasAnyService
@@ -115,117 +141,20 @@ function buildReadmeContext(appName, config) {
 }
 
 function generateReadmeMd(appName, config) {
-  const context = buildReadmeContext(appName, config);
-  // Always generate comprehensive README programmatically to ensure consistency
-  // regardless of template file content
-  return generateComprehensiveReadme(context);
-}
-
-/**
- * Generates comprehensive README.md content programmatically
- * @param {Object} context - Template context
- * @returns {string} Comprehensive README.md content
- */
-function generateComprehensiveReadme(context) {
-  const { appName, displayName, imageName, port, registry, hasDatabase, hasRedis, hasStorage, hasAuthentication, hasAnyService } = context;
-
-  let prerequisites = 'Before running this application, ensure the following prerequisites are met:\n';
-  prerequisites += '- `@aifabrix/builder` installed globally\n';
-  prerequisites += '- Docker Desktop running\n';
-
-  if (hasAnyService) {
-    if (hasDatabase) {
-      prerequisites += '- PostgreSQL database\n';
-    }
-    if (hasRedis) {
-      prerequisites += '- Redis\n';
-    }
-    if (hasStorage) {
-      prerequisites += '- File storage configured\n';
-    }
-    if (hasAuthentication) {
-      prerequisites += '- Authentication/RBAC configured\n';
-    }
-  } else {
-    prerequisites += '- Infrastructure running\n';
+  if (config.type === 'external') {
+    const systemKey = config.systemKey || appName;
+    const datasources = buildExternalDatasourcePlaceholders(systemKey, config.datasourceCount);
+    return generateExternalReadmeContent({
+      appName,
+      systemKey,
+      systemType: config.systemType,
+      displayName: config.systemDisplayName,
+      description: config.systemDescription,
+      datasources
+    });
   }
-
-  let troubleshooting = '';
-  if (hasDatabase) {
-    troubleshooting = `### Database Connection Issues
-
-If you encounter database connection errors, ensure:
-- PostgreSQL is running and accessible
-- Database credentials are correctly configured in your \`.env\` file
-- The database name matches your configuration
-- Verify infrastructure is running and PostgreSQL is accessible`;
-  } else {
-    troubleshooting = 'Verify infrastructure is running.';
-  }
-
-  return `# ${displayName} Builder
-
-Build, run, and deploy ${displayName}.
-
-## Prerequisites
-
-${prerequisites}
-
-## Quick Start
-
-### 1. Install
-
-Install the AI Fabrix Builder CLI if you haven't already.
-
-### 2. Configure
-
-Configure your application settings in \`variables.yaml\`.
-
-### 3. Build & Run Locally
-
-Build the application:
-\`\`\`bash
-aifabrix build ${appName}
-\`\`\`
-
-Run the application:
-\`\`\`bash
-aifabrix run ${appName}
-\`\`\`
-
-The application will be available at http://localhost:${port} (default: ${port}).
-
-### 4. Deploy to Azure
-
-Push to registry:
-\`\`\`bash
-aifabrix push ${appName} --registry ${registry} --tag "v1.0.0,latest"
-\`\`\`
-
-## Configuration
-
-- **Port**: ${port} (default: 3000)
-- **Image**: ${imageName}:latest
-- **Registry**: ${registry}
-
-## Docker Commands
-
-View logs:
-\`\`\`bash
-docker logs aifabrix-${appName} -f
-\`\`\`
-
-Stop the application:
-\`\`\`bash
-aifabrix down ${appName}
-\`\`\`
-
-## Troubleshooting
-
-${troubleshooting}
-
-For more information, see the [AI Fabrix Builder documentation](https://docs.aifabrix.com).
-`;
+  const context = buildReadmeContext(appName, config);
+  return _loadReadmeTemplate()(context);
 }
 
 /**

package/lib/app/register.js

@@ -43,7 +43,7 @@ function buildRegistrationData(appConfig, options) {
 
   // Handle external type vs non-external types differently
   if (appConfig.appType === 'external') {
-    // For external type: include externalIntegration, exclude registryMode/port/image
+    // For external type: include externalIntegration, exclude registryMode/port/image/url
     if (appConfig.externalIntegration) {
       registrationData.externalIntegration = appConfig.externalIntegration;
     }
@@ -60,6 +60,12 @@ function buildRegistrationData(appConfig, options) {
     if (appConfig.image) {
       registrationData.image = appConfig.image;
     }
+
+    // URL: always set when we have port so controller DB has it. Precedence: --url, variables (app.url, deployment.dataplaneUrl, deployment.appUrl), else http://localhost:{localPort|port}
+    const portForUrl = appConfig.localPort ?? appConfig.port;
+    if (portForUrl) {
+      registrationData.url = options.url || appConfig.url || `http://localhost:${portForUrl}`;
+    }
   }
 
   return registrationData;
@@ -103,20 +109,48 @@ async function saveLocalCredentials(responseData, apiUrl) {
 }
 
 /**
- * Register an application
+ * For localhost controller: apply developer-id offset to port and URL fallback so the
+ * controller can reach the app on the correct Docker/exposed host port.
+ * @async
+ * @param {Object} appConfig - App config (mutated: port, url)
+ * @param {string} apiUrl - Controller API URL
+ * @param {Object} options - CLI options (url override)
+ */
+async function applyLocalhostPortAdjustment(appConfig, apiUrl, options) {
+  if (!isLocalhost(apiUrl) || appConfig.port === null || appConfig.port === undefined) {
+    return;
+  }
+  const { getDeveloperId } = require('../core/config');
+  const devId = await getDeveloperId();
+  const devIdNum = (devId !== null && devId !== undefined && devId !== '') ? parseInt(devId, 10) : 0;
+  if (Number.isNaN(devIdNum) || devIdNum <= 0) {
+    return;
+  }
+  const adjusted = appConfig.port + devIdNum * 100;
+  appConfig.port = adjusted;
+  if (!options.url && !appConfig.url) {
+    appConfig.url = `http://localhost:${adjusted}`;
+  }
+}
+
+/**
+ * Register an application.
+ * Controller and environment come from config.yaml (set via aifabrix login or aifabrix auth config).
  * @async
  * @param {string} appKey - Application key
  * @param {Object} options - Registration options
- * @param {string} options.environment - Environment ID or key
- * @param {string} [options.controller] - Controller URL (overrides variables.yaml)
  * @param {number} [options.port] - Application port
+ * @param {string} [options.url] - Application URL (overrides variables; see app register --help for fallback when omitted)
  * @param {string} [options.name] - Override display name
  * @param {string} [options.description] - Override description
  * @throws {Error} If registration fails
  */
-async function registerApplication(appKey, options) {
+async function registerApplication(appKey, options = {}) {
   logger.log(chalk.blue('📋 Registering application...\n'));
 
+  const { resolveControllerUrl } = require('../utils/controller-url');
+  const { resolveEnvironment } = require('../core/config');
+
   // Load variables.yaml
   const { variables, created } = await loadVariablesYaml(appKey);
   const finalVariables = created
@@ -127,10 +161,11 @@ async function registerApplication(appKey, options) {
   const appConfig = await extractAppConfiguration(finalVariables, appKey, options);
   await validateAppRegistrationData(appConfig, appKey);
 
-  // Get controller URL with priority: options.controller > variables.yaml > device tokens
-  const controllerUrl = options.controller || finalVariables?.deployment?.controllerUrl;
-  const authConfig = await checkAuthentication(controllerUrl, options.environment);
-  const environment = registerApplicationSchema.environmentId(options.environment);
+  const [controllerUrl, environmentKey] = await Promise.all([resolveControllerUrl(), resolveEnvironment()]);
+  const authConfig = await checkAuthentication(controllerUrl, environmentKey);
+  const environment = registerApplicationSchema.environmentId(environmentKey);
+
+  await applyLocalhostPortAdjustment(appConfig, authConfig.apiUrl, options);
 
   // Register application
   const registrationData = buildRegistrationData(appConfig, options);

package/lib/app/rotate-secret.js

@@ -9,7 +9,8 @@
  */
 
 const chalk = require('chalk');
-const { getConfig, normalizeControllerUrl } = require('../core/config');
+const { getConfig, normalizeControllerUrl, resolveEnvironment } = require('../core/config');
+const { resolveControllerUrl } = require('../utils/controller-url');
 const { getOrRefreshDeviceToken } = require('../utils/token-manager');
 const { rotateApplicationSecret } = require('../api/applications.api');
 const { formatApiError } = require('../utils/api-error-handler');
@@ -61,6 +62,22 @@ function validateEnvironment(environment) {
   }
 }
 
+/**
+ * Resolve controller URL and environment from config; exit if controller is missing.
+ * @async
+ * @returns {Promise<{controllerUrl: string, environment: string}>}
+ */
+async function resolveControllerAndEnvironment() {
+  const controllerUrl = await resolveControllerUrl();
+  if (!controllerUrl) {
+    logger.error(chalk.red('❌ Controller URL is required. Run "aifabrix login" to set the controller URL in config.yaml'));
+    process.exit(1);
+  }
+  const environment = await resolveEnvironment();
+  validateEnvironment(environment);
+  return { controllerUrl, environment };
+}
+
 /**
  * Validate credentials object structure
  * @param {Object} credentials - Credentials object to validate
@@ -152,7 +169,8 @@ function displayRotationResults(appKey, environment, credentials, apiUrl, messag
   logger.log(chalk.green('✅ Secret rotated successfully!\n'));
   logger.log(chalk.bold('📋 Application Details:'));
   logger.log(`   Key:         ${appKey}`);
-  logger.log(`   Environment: ${environment}\n`);
+  logger.log(`   Environment: ${environment}`);
+  logger.log(`   Controller:  ${apiUrl}\n`);
 
   logger.log(chalk.bold.yellow('🔑 NEW CREDENTIALS:'));
   logger.log(chalk.yellow(`   Client ID:     ${credentials.clientId}`));
@@ -285,46 +303,46 @@ async function saveCredentialsLocally(appKey, credentials, actualControllerUrl)
 }
 
 /**
- * Rotate secret for an application
+ * Call rotate API, validate response, save locally, and display results.
+ * @async
+ * @param {string} appKey - Application key
+ * @param {string} actualControllerUrl - Resolved controller URL
+ * @param {string} environment - Environment ID or key
+ * @param {string} token - Bearer token
+ */
+async function executeRotation(appKey, actualControllerUrl, environment, token) {
+  const authConfig = { type: 'bearer', token };
+  const response = await rotateApplicationSecret(actualControllerUrl, environment, appKey, authConfig);
+
+  if (!response.success) {
+    const formattedError = response.formattedError || formatApiError(response, actualControllerUrl);
+    logger.error(formattedError);
+    logger.error(chalk.gray(`\nController URL: ${actualControllerUrl}`));
+    process.exit(1);
+  }
+
+  const { credentials, message } = validateResponse(response);
+  await saveCredentialsLocally(appKey, credentials, actualControllerUrl);
+  displayRotationResults(appKey, environment, credentials, actualControllerUrl, message);
+}
+
+/**
+ * Rotate secret for an application.
+ * Controller and environment come from config.yaml (set via aifabrix login or aifabrix auth config).
  * @async
  * @param {string} appKey - Application key
- * @param {Object} options - Command options
- * @param {string} options.environment - Environment ID or key
- * @param {string} [options.controller] - Controller URL (optional, uses configured controller if not provided)
+ * @param {Object} [_options] - Command options (reserved)
  * @throws {Error} If rotation fails
  */
-async function rotateSecret(appKey, options) {
+async function rotateSecret(appKey, _options = {}) {
   logger.log(chalk.yellow('⚠️  This will invalidate the old ClientSecret!\n'));
 
+  const { controllerUrl, environment } = await resolveControllerAndEnvironment();
   const config = await getConfig();
-
-  // Get authentication token
-  const controllerUrl = options.controller || null;
   const { token, actualControllerUrl } = await getRotationAuthToken(controllerUrl, config);
 
-  // Validate environment
-  validateEnvironment(options.environment);
-
-  // Use centralized API client
-  const authConfig = { type: 'bearer', token: token };
   try {
-    const response = await rotateApplicationSecret(actualControllerUrl, options.environment, appKey, authConfig);
-
-    if (!response.success) {
-      const formattedError = response.formattedError || formatApiError(response, actualControllerUrl);
-      logger.error(formattedError);
-      logger.error(chalk.gray(`\nController URL: ${actualControllerUrl}`));
-      process.exit(1);
-    }
-
-    // Validate response structure and extract credentials
-    const { credentials, message } = validateResponse(response);
-
-    // Save credentials locally
-    await saveCredentialsLocally(appKey, credentials, actualControllerUrl);
-
-    // Display results
-    displayRotationResults(appKey, options.environment, credentials, actualControllerUrl, message);
+    await executeRotation(appKey, actualControllerUrl, environment, token);
   } catch (error) {
     logger.error(chalk.red(`❌ Failed to rotate secret via controller: ${actualControllerUrl}`));
     logger.error(chalk.gray(`Error: ${error.message}`));