@aifabrix/builder 2.32.3 → 2.33.0

package/lib/app/deploy.js

@@ -18,6 +18,8 @@ const logger = require('../utils/logger');
 const config = require('../core/config');
 const { getDeploymentAuth } = require('../utils/token-manager');
 const { detectAppType } = require('../utils/paths');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { checkApplicationExists } = require('../utils/app-existence');
 
 /**
  * Validate application name format
@@ -178,15 +180,26 @@ async function loadVariablesFile(variablesPath) {
 }
 
 /**
- * Extracts deployment configuration from options and variables
- * @param {Object} options - CLI options
- * @param {Object} variables - Variables from variables.yaml
- * @returns {Object} Extracted configuration
+ * Extracts deployment configuration from config.yaml
+ * Resolves controller URL using fallback chain: config.controller → logged-in user → developer ID default
+ * Resolves environment using fallback chain: config.environment → default 'dev'
+ * @async
+ * @param {Object} options - CLI options (for poll settings only)
+ * @param {Object} _variables - Variables from variables.yaml (unused, kept for compatibility)
+ * @returns {Promise<Object>} Extracted configuration with resolved controller URL
  */
-function extractDeploymentConfig(options, variables) {
+async function extractDeploymentConfig(options, _variables) {
+  const { resolveEnvironment } = require('../core/config');
+
+  // Resolve controller URL from config.yaml (no flags, no options)
+  const controllerUrl = await resolveControllerUrl();
+
+  // Resolve environment from config.yaml (no flags, no options)
+  const envKey = await resolveEnvironment();
+
   return {
-    controllerUrl: options.controller || variables.deployment?.controllerUrl,
-    envKey: options.environment || variables.deployment?.environment,
+    controllerUrl,
+    envKey,
     poll: options.poll !== false,
     pollInterval: options.pollInterval || 5000,
     pollMaxAttempts: options.pollMaxAttempts || 60
@@ -200,7 +213,7 @@ function extractDeploymentConfig(options, variables) {
  */
 function validateDeploymentConfig(deploymentConfig) {
   if (!deploymentConfig.controllerUrl) {
-    throw new Error('Controller URL is required. Set it in variables.yaml or use --controller flag');
+    throw new Error('Controller URL is required. Run "aifabrix login" to set the controller URL in config.yaml');
   }
   if (!deploymentConfig.auth) {
     throw new Error('Authentication is required. Run "aifabrix login" first or ensure credentials are in secrets.local.yaml');
@@ -208,19 +221,15 @@ function validateDeploymentConfig(deploymentConfig) {
 }
 
 /**
- * Configure deployment environment settings
+ * Configure deployment environment settings from config.yaml
  * @async
- * @param {Object} options - CLI options
+ * @param {Object} _options - CLI options (unused, kept for compatibility)
  * @param {Object} deploymentConfig - Deployment configuration to update
  * @returns {Promise<void>}
  */
-async function configureDeploymentEnvironment(options, deploymentConfig) {
-  // Update root-level environment if provided
-  if (options.environment) {
-    await config.setCurrentEnvironment(options.environment);
-  }
-
-  // Get current environment from root-level config
+async function configureDeploymentEnvironment(_options, deploymentConfig) {
+  // Get current environment from root-level config (already resolved in extractDeploymentConfig)
+  // This function is kept for compatibility but no longer updates environment from options
   const currentEnvironment = await config.getCurrentEnvironment();
   deploymentConfig.envKey = deploymentConfig.envKey || currentEnvironment;
 }
@@ -234,9 +243,9 @@ async function configureDeploymentEnvironment(options, deploymentConfig) {
  * @throws {Error} If authentication fails
  */
 async function refreshDeploymentToken(appName, deploymentConfig) {
-  // Get controller URL
+  // Get controller URL (should already be resolved by extractDeploymentConfig)
   if (!deploymentConfig.controllerUrl) {
-    throw new Error('Controller URL is required. Set it in variables.yaml or use --controller flag');
+    throw new Error('Controller URL is required. Run "aifabrix login" to set the controller URL in config.yaml');
   }
 
   // Get deployment authentication (device token → client token → credentials)
@@ -275,7 +284,7 @@ async function loadDeploymentConfig(appName, options) {
   const variablesPath = path.join(appPath, 'variables.yaml');
   const variables = await loadVariablesFile(variablesPath);
 
-  const deploymentConfig = extractDeploymentConfig(options, variables);
+  const deploymentConfig = await extractDeploymentConfig(options, variables);
 
   await configureDeploymentEnvironment(options, deploymentConfig);
   await refreshDeploymentToken(appName, deploymentConfig);
@@ -360,6 +369,80 @@ function displayDeploymentResults(result) {
   }
 }
 
+/**
+ * Check if app is external and handle external deployment
+ * @async
+ * @function handleExternalDeployment
+ * @param {string} appName - Application name
+ * @param {Object} options - Deployment options
+ * @returns {Promise<Object|null>} Deployment result if external, null otherwise
+ */
+async function handleExternalDeployment(appName, options) {
+  const { isExternal } = await detectAppType(appName);
+  if (isExternal) {
+    const externalDeploy = require('../external-system/deploy');
+    await externalDeploy.deployExternalSystem(appName, options);
+    return { success: true, type: 'external' };
+  }
+  return null;
+}
+
+/**
+ * Handle deployment errors
+ * @async
+ * @function handleDeploymentError
+ * @param {Error} error - Error that occurred
+ * @param {string} appName - Application name
+ * @param {string} controllerUrl - Controller URL (from config, or null if not yet resolved)
+ * @param {boolean} usedExternalDeploy - Whether external deployment was used
+ */
+async function handleDeploymentError(error, appName, controllerUrl, usedExternalDeploy) {
+  if (usedExternalDeploy) {
+    throw error;
+  }
+  const alreadyLogged = error._logged === true;
+  const url = controllerUrl || 'unknown';
+  const deployer = require('../deployment/deployer');
+  await deployer.handleDeploymentErrors(error, appName, url, alreadyLogged);
+}
+
+/**
+ * Execute standard application deployment flow
+ * @async
+ * @function executeStandardDeployment
+ * @param {string} appName - Application name
+ * @param {Object} options - Deployment options
+ * @returns {Promise<Object>} Deployment result
+ */
+async function executeStandardDeployment(appName, options) {
+  const config = await loadDeploymentConfig(appName, options);
+  const controllerUrl = config.controllerUrl || 'unknown';
+
+  // Check if application exists before deployment
+  const appExists = await checkApplicationExists(appName, controllerUrl, config.envKey, config.auth);
+
+  const { manifest, manifestPath } = await generateAndValidateManifest(appName);
+  displayDeploymentInfo(manifest, manifestPath);
+
+  try {
+    const result = await executeDeployment(manifest, config);
+    displayDeploymentResults(result);
+    return { result, controllerUrl, appExists };
+  } catch (error) {
+    // Enhance error if app exists and credentials are invalid
+    if (appExists && error.status === 401 && !error.message.includes('rotate-secret')) {
+      const enhancedError = new Error(
+        `${error.message}\n\n💡 The application '${appName}' exists in environment '${config.envKey}'. ` +
+        `To fix invalid credentials, rotate the application secret:\n   aifabrix app rotate-secret ${appName}`
+      );
+      enhancedError.status = 401;
+      enhancedError.formatted = error.formatted || enhancedError.message;
+      throw enhancedError;
+    }
+    throw error;
+  }
+}
+
 /**
  * Deploys application to Miso Controller
  * Orchestrates manifest generation, key creation, and deployment
@@ -368,59 +451,38 @@ function displayDeploymentResults(result) {
  * @function deployApp
  * @param {string} appName - Name of the application to deploy
  * @param {Object} options - Deployment options
- * @param {string} options.controller - Controller URL (required)
- * @param {string} [options.environment] - Target environment (miso/dev/tst/pro)
  * @param {boolean} [options.poll] - Poll for deployment status
  * @param {number} [options.pollInterval] - Polling interval in milliseconds
+ * @param {number} [options.pollMaxAttempts] - Max polling attempts
  * @returns {Promise<Object>} Deployment result
  * @throws {Error} If deployment fails
  *
+ * Controller and environment come from config.yaml (set via aifabrix login or aifabrix auth config).
+ *
  * @example
- * await deployApp('myapp', { controller: 'https://controller.aifabrix.ai', environment: 'dev' });
+ * await deployApp('myapp', { poll: true });
  */
 async function deployApp(appName, options = {}) {
   let controllerUrl = null;
-  let config = null;
+  let usedExternalDeploy = false;
 
   try {
-    // 1. Input validation
     if (!appName || typeof appName !== 'string' || appName.trim().length === 0) {
       throw new Error('App name is required');
     }
-
     validateAppName(appName);
 
-    // 2. Check if app type is external - use normal deployment flow with application-schema.json
-    // External systems now deploy via miso controller as normal application (full application file)
-    // The json command generates application-schema.json which is used for deployment
-
-    // 2. Load deployment configuration
-    config = await loadDeploymentConfig(appName, options);
-    controllerUrl = config.controllerUrl || options.controller || 'unknown';
-
-    // 3. Generate and validate manifest
-    const { manifest, manifestPath } = await generateAndValidateManifest(appName);
-
-    // 4. Display deployment info
-    displayDeploymentInfo(manifest, manifestPath);
-
-    // 5. Execute deployment
-    const result = await executeDeployment(manifest, config);
-
-    // 6. Display results
-    displayDeploymentResults(result);
+    const externalResult = await handleExternalDeployment(appName, options);
+    if (externalResult) {
+      return externalResult;
+    }
+    usedExternalDeploy = false;
 
+    const { result, controllerUrl: url } = await executeStandardDeployment(appName, options);
+    controllerUrl = url;
     return result;
-
   } catch (error) {
-    // Use unified error handler from deployer
-    // Check if error was already logged (from deployer.js)
-    const alreadyLogged = error._logged === true;
-    const url = controllerUrl || options.controller || 'unknown';
-
-    const deployer = require('../deployment/deployer');
-    // handleDeploymentErrors will log, format, and throw the error
-    await deployer.handleDeploymentErrors(error, appName, url, alreadyLogged);
+    await handleDeploymentError(error, appName, controllerUrl, usedExternalDeploy);
   }
 }
 

package/lib/app/display.js

@@ -25,9 +25,9 @@ function displayExternalSystemSuccess(appName, config, location) {
   logger.log(chalk.blue(`System Key: ${config.systemKey || appName}`));
   logger.log(chalk.green('\nNext steps:'));
   logger.log(chalk.white('1. Edit external system JSON files in ' + location));
-  logger.log(chalk.white('2. Run: aifabrix app register ' + appName + ' --environment dev'));
-  logger.log(chalk.white('3. Run: aifabrix build ' + appName + ' (deploys to dataplane)'));
-  logger.log(chalk.white('4. Run: aifabrix deploy ' + appName + ' (publishes to dataplane)'));
+  logger.log(chalk.white('2. Run: aifabrix validate ' + appName + ' --type external'));
+  logger.log(chalk.white('3. Run: aifabrix login'));
+  logger.log(chalk.white('4. Run: aifabrix deploy ' + appName));
 }
 
 /**
@@ -50,8 +50,9 @@ function displayWebappSuccess(appName, config, envConversionMessage) {
 
   logger.log(chalk.green('\nNext steps:'));
   logger.log(chalk.white('1. Copy env.template to .env and fill in your values'));
-  logger.log(chalk.white('2. Run: aifabrix build ' + appName));
-  logger.log(chalk.white('3. Run: aifabrix run ' + appName));
+  logger.log(chalk.white('2. Run: aifabrix up'));
+  logger.log(chalk.white('3. Run: aifabrix build ' + appName));
+  logger.log(chalk.white('4. Run: aifabrix run ' + appName));
 }
 
 /**

package/lib/app/dockerfile.js

@@ -15,6 +15,7 @@ const yaml = require('js-yaml');
 const build = require('../build');
 const { validateAppName } = require('./push');
 const logger = require('../utils/logger');
+const { getContainerPort } = require('../utils/port-resolver');
 
 /**
  * Checks if Dockerfile exists and validates overwrite permission
@@ -52,7 +53,7 @@ async function loadAppConfig(configPath, options) {
     const variables = yaml.load(yamlContent);
     return {
       language: options.language || variables.build?.language || 'typescript',
-      port: variables.build?.port || variables.port || 3000,
+      port: getContainerPort(variables, 3000),
       ...variables
     };
   } catch {

package/lib/app/list.js

@@ -286,18 +286,25 @@ 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');
+
+  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;
+  }
 
-  // Get authentication token
-  const controllerUrl = options.controller || null;
+  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)
@@ -308,9 +315,9 @@ async function listApplications(options) {
   // 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, actualControllerUrl);
+    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/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);