@aifabrix/builder 2.39.3 → 2.40.2

package/lib/app/readme.js

@@ -12,7 +12,8 @@ const fs = require('fs').promises;
 const fsSync = require('fs');
 const path = require('path');
 const handlebars = require('handlebars');
-const yaml = require('js-yaml');
+const { resolveApplicationConfigPath } = require('../utils/paths');
+const { loadConfigFile } = require('../utils/config-format');
 const { generateExternalReadmeContent } = require('../utils/external-readme');
 
 /**
@@ -104,7 +105,7 @@ function buildExternalDatasourcePlaceholders(systemKey, datasourceCount) {
     return {
       entityType,
       displayName: `Datasource ${index + 1}`,
-      fileName: `${systemKey}-datasource-${entityType}.json`
+      fileName: `${systemKey}-datasource-${entityType}.yaml`
     };
   });
 }
@@ -117,7 +118,7 @@ function buildExternalDatasourcePlaceholders(systemKey, datasourceCount) {
  * @returns {Object} Template context
  */
 function buildReadmeContext(appName, config) {
-  const displayName = formatAppDisplayName(appName);
+  const displayName = config.displayName || formatAppDisplayName(appName);
   const port = config.port ?? 3000;
   const localPort = (typeof config.build?.localPort === 'number' && config.build.localPort > 0)
     ? config.build.localPort
@@ -144,7 +145,9 @@ function buildReadmeContext(appName, config) {
 function generateReadmeMd(appName, config) {
   if (config.type === 'external') {
     const systemKey = config.systemKey || appName;
-    const datasources = buildExternalDatasourcePlaceholders(systemKey, config.datasourceCount);
+    const datasources = Array.isArray(config.datasources) && config.datasources.length > 0
+      ? config.datasources
+      : buildExternalDatasourcePlaceholders(systemKey, config.datasourceCount);
     return generateExternalReadmeContent({
       appName,
       systemKey,
@@ -164,7 +167,7 @@ function generateReadmeMd(appName, config) {
  * @function generateReadmeMdFile
  * @param {string} appPath - Path to application directory
  * @param {string} appName - Application name
- * @param {Object} config - Application configuration (e.g. from variables.yaml)
+ * @param {Object} config - Application configuration (e.g. from application.yaml/application.json)
  * @param {Object} [options] - Options
  * @param {boolean} [options.force] - If true, overwrite existing README.md (dynamic generation)
  * @returns {Promise<void>} Resolves when README.md is generated or skipped
@@ -181,21 +184,22 @@ async function generateReadmeMdFile(appPath, appName, config, options = {}) {
 }
 
 /**
- * Loads variables.yaml from app path and generates README.md (overwrites if present).
+ * Loads application config from app path and generates README.md (overwrites if present).
  * Used when copying template apps or running up-miso / up-platform / up-dataplane.
  * @async
  * @function ensureReadmeForAppPath
- * @param {string} appPath - Path to application directory (must contain variables.yaml)
+ * @param {string} appPath - Path to application directory (must contain application config)
  * @param {string} appName - Application name
- * @returns {Promise<void>} Resolves when README.md is written or skipped (no variables.yaml)
+ * @returns {Promise<void>} Resolves when README.md is written or skipped (no application config)
  */
 async function ensureReadmeForAppPath(appPath, appName) {
-  const variablesPath = path.join(appPath, 'variables.yaml');
-  if (!(await fileExists(variablesPath))) {
+  let configPath;
+  try {
+    configPath = resolveApplicationConfigPath(appPath);
+  } catch {
     return;
   }
-  const content = await fs.readFile(variablesPath, 'utf8');
-  const config = yaml.load(content) || {};
+  const config = loadConfigFile(configPath) || {};
   await generateReadmeMdFile(appPath, appName, config, { force: true });
 }
 

package/lib/app/register.js

@@ -152,7 +152,7 @@ async function registerApplication(appKey, options = {}) {
   const { resolveControllerUrl } = require('../utils/controller-url');
   const { resolveEnvironment } = require('../core/config');
 
-  // Load variables.yaml
+  // Load application config
   const { variables, created } = await loadVariablesYaml(appKey);
   const finalVariables = created
     ? await createMinimalAppIfNeeded(appKey, options)

package/lib/app/run-helpers.js

@@ -13,8 +13,8 @@ const fs = require('fs').promises;
 const fsSync = require('fs');
 const path = require('path');
 const chalk = require('chalk');
-const yaml = require('js-yaml');
 const { exec } = require('child_process');
+const { loadConfigFile } = require('../utils/config-format');
 const { promisify } = require('util');
 const validator = require('../validation/validator');
 const infra = require('../infrastructure');
@@ -31,7 +31,7 @@ const { resolveVersionForApp } = require('../utils/image-version');
 
 const execAsync = promisify(exec);
 
-/** Template apps (keycloak, miso-controller, dataplane) - never update variables.yaml when running */
+/** Template apps (keycloak, miso-controller, dataplane) - never update application config when running */
 const TEMPLATE_APP_KEYS = ['keycloak', 'miso-controller', 'dataplane'];
 
 // Re-export container helper functions
@@ -72,19 +72,18 @@ function checkBuilderDirectory(appName) {
 function loadAppConfig(appName) {
   const currentDir = process.cwd();
   const builderPath = pathsUtil.getBuilderPath(appName);
-  const configPath = path.join(builderPath, 'variables.yaml');
-  if (!fsSync.existsSync(configPath)) {
+  let configPath;
+  try {
+    configPath = pathsUtil.resolveApplicationConfigPath(builderPath);
+  } catch {
     throw new Error(
-      `Application configuration not found: ${configPath}\n` +
+      `Application configuration not found in ${builderPath}\n` +
       `Current directory: ${currentDir}\n` +
-      `Expected location: ${builderPath}\n` +
       'Make sure you\'re running from the project root (where \'builder\' directory exists)\n' +
       `Run 'aifabrix create ${appName}' first if configuration doesn't exist`
     );
   }
-
-  const configContent = fsSync.readFileSync(configPath, 'utf8');
-  return yaml.load(configContent);
+  return loadConfigFile(configPath);
 }
 
 /**
@@ -96,7 +95,7 @@ function formatValidationErrors(validation) {
   const allErrors = [];
 
   if (validation.variables && validation.variables.errors && validation.variables.errors.length > 0) {
-    allErrors.push('variables.yaml:');
+    allErrors.push('application config:');
     allErrors.push(...validation.variables.errors.map(err => `  ${err}`));
   }
   if (validation.rbac && validation.rbac.errors && validation.rbac.errors.length > 0) {
@@ -129,8 +128,8 @@ async function validateAppConfiguration(appName) {
   // Load config
   const appConfig = loadAppConfig(appName);
 
-  // Validate configuration
-  const validation = await validator.validateApplication(appName);
+  // Validate configuration (run only uses builder/ apps)
+  const validation = await validator.validateApplication(appName, { type: 'app' });
   if (!validation.valid) {
     const allErrors = formatValidationErrors(validation);
     if (allErrors.length === 0) {
@@ -143,8 +142,8 @@ async function validateAppConfiguration(appName) {
 }
 
 /**
- * Resolves version from image and updates builder/variables.yaml when running.
- * Template apps (keycloak, miso-controller, dataplane) are never updated - variables.yaml stays pristine.
+ * Resolves version from image and updates builder application config when running.
+ * Template apps (keycloak, miso-controller, dataplane) are never updated - config stays pristine.
  * @async
  * @param {string} appName - Application name
  * @param {Object} appConfig - Application configuration
@@ -263,18 +262,21 @@ async function copyEnvToDev(builderEnvPath, devEnvPath) {
  * Handle envOutputPath configuration
  * @async
  * @param {string} appName - Application name
- * @param {string} variablesPath - Path to variables.yaml
+ * @param {string} configPath - Path to application config file
  * @param {string} builderEnvPath - Path to builder .env file
  * @param {string} devEnvPath - Path to dev .env file
  * @param {boolean} [skipOutputPath=false] - When true, skip (e.g. up-miso/up-dataplane, no local code)
  */
-async function handleEnvOutputPath(appName, variablesPath, builderEnvPath, devEnvPath, skipOutputPath = false) {
-  if (skipOutputPath || !fsSync.existsSync(variablesPath)) {
+async function handleEnvOutputPath(appName, configPath, builderEnvPath, devEnvPath, skipOutputPath = false) {
+  if (skipOutputPath) {
+    return;
+  }
+  let variables;
+  try {
+    variables = loadConfigFile(configPath);
+  } catch {
     return;
   }
-
-  const variablesContent = fsSync.readFileSync(variablesPath, 'utf8');
-  const variables = yaml.load(variablesContent);
 
   if (variables?.build?.envOutputPath && variables.build.envOutputPath !== null) {
     logger.log(chalk.blue('Ensuring .env file in apps/ directory is updated for Docker...'));
@@ -338,8 +340,15 @@ async function prepareEnvironment(appName, appConfig, options) {
   await copyEnvToDev(builderEnvPath, devEnvPath);
 
   // Handle envOutputPath if configured (skipped when skipEnvOutputPath e.g. up-miso/up-dataplane)
-  const variablesPath = path.join(devDir, 'variables.yaml');
-  await handleEnvOutputPath(appName, variablesPath, builderEnvPath, devEnvPath, skipEnvOutputPath);
+  let configPath;
+  try {
+    configPath = pathsUtil.resolveApplicationConfigPath(devDir);
+  } catch {
+    configPath = null;
+  }
+  if (configPath) {
+    await handleEnvOutputPath(appName, configPath, builderEnvPath, devEnvPath, skipEnvOutputPath);
+  }
 
   // Generate Docker Compose
   const composeOptions = { ...options };

package/lib/app/run.js

@@ -10,13 +10,18 @@
  */
 
 const chalk = require('chalk');
+const { exec } = require('child_process');
+const { promisify } = require('util');
 const config = require('../core/config');
 const logger = require('../utils/logger');
 const { checkPortAvailable, waitForHealthCheck } = require('../utils/health-check');
 const composeGenerator = require('../utils/compose-generator');
+const containerHelpers = require('../utils/app-run-containers');
 // Helper functions extracted to reduce file size and complexity
 const helpers = require('./run-helpers');
 
+const execAsync = promisify(exec);
+
 /**
  * Validate app for run and check if it's an external system
  * @async
@@ -30,18 +35,20 @@ async function validateAppForRun(appName, _debug) {
     throw new Error('Application name is required');
   }
 
-  // Check if app type is external - skip Docker run
+  // Run only supports regular apps in builder/ (path resolution: integration first, then builder)
   const { detectAppType } = require('../utils/paths');
   try {
-    const { isExternal } = await detectAppType(appName);
-    if (isExternal) {
+    const { isExternal, baseDir } = await detectAppType(appName);
+    if (baseDir !== 'builder' || isExternal) {
       logger.log(chalk.yellow('⚠️  External systems don\'t run as Docker containers.'));
       logger.log(chalk.blue('Use "aifabrix build" to deploy to dataplane, then test via OpenAPI endpoints.'));
       return false;
     }
   } catch (error) {
-    // If detection fails, continue with normal run
-    // (detectAppType throws if app doesn't exist, which is fine for run command)
+    throw new Error(
+      `Application "${appName}" not found in builder/. Only applications in builder/ can be run.\n` +
+      (error.message || '')
+    );
   }
 
   return true;
@@ -202,8 +209,40 @@ async function runApp(appName, options = {}) {
     throw new Error(`Failed to run application: ${error.message}`);
   }
 }
+
+/**
+ * Restart a running application container (Docker restart).
+ * Only applies to apps in builder/ run via aifabrix run.
+ *
+ * @async
+ * @function restartApp
+ * @param {string} appName - Application name (must be running)
+ * @returns {Promise<void>} Resolves when container is restarted
+ * @throws {Error} If app name is invalid, container not found, or restart fails
+ *
+ * @example
+ * await restartApp('myapp');
+ */
+async function restartApp(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('Application name is required and must be a string');
+  }
+  const developerId = await config.getDeveloperId();
+  const containerName = containerHelpers.getContainerName(appName, developerId);
+  try {
+    await execAsync(`docker restart ${containerName}`);
+  } catch (error) {
+    const msg = (error.stderr || error.stdout || error.message || '').toLowerCase();
+    if (msg.includes('no such container') || msg.includes('is not running')) {
+      throw new Error(`Application '${appName}' is not running. Start it with: aifabrix run ${appName}`);
+    }
+    throw new Error(`Failed to restart application: ${error.message}`);
+  }
+}
+
 module.exports = {
   runApp,
+  restartApp,
   checkImageExists: helpers.checkImageExists,
   checkContainerRunning: helpers.checkContainerRunning,
   stopAndRemoveContainer: helpers.stopAndRemoveContainer,

package/lib/app/show-display.js

@@ -15,14 +15,15 @@ const logger = require('../utils/logger');
 function logSourceAndHeader(summary) {
   const isOffline = summary.source === 'offline';
   const sourceLabel = isOffline
-    ? `Source: offline (${summary.path || '—'})`
-    : `Source: online (${summary.controllerUrl || '—'})`;
+    ? `🔴 Source: offline (${summary.path || '—'})`
+    : `🟢 Source: online (${summary.controllerUrl || '—'})`;
   logger.log(sourceLabel);
   logger.log('');
 }
 
 function logApplicationRequired(a) {
-  logger.log('📱 Application');
+  const typeLabel = (a.type && String(a.type).toLowerCase()) || 'webapp';
+  logger.log(`📱 Application - ${typeLabel}`);
   logger.log(`  Key:           ${a.key ?? '—'}`);
   logger.log(`  Display name:  ${a.displayName ?? '—'}`);
   logger.log(`  Description:   ${a.description ?? '—'}`);
@@ -53,19 +54,49 @@ function logApplicationFields(a) {
   logApplicationOptional(a);
 }
 
-function logApplicationExternalIntegration(ei) {
+/** Application section for online + external: Key, Display name, Description, Deployment, Status (no Type; Dataplane block follows). */
+function logApplicationFieldsOnlineExternal(a) {
+  logger.log('🧷 Application - external');
+  logger.log(`  Key:           ${a.key ?? '—'}`);
+  logger.log(`  Display name:  ${a.displayName ?? '—'}`);
+  logger.log(`  Description:   ${a.description ?? '—'}`);
+  logger.log('  Deployment:    —');
+  if (a.status !== undefined && a.status !== '—') logger.log(`  Status:        ${a.status}`);
+}
+
+/** Application section for offline + external: Key, Display name, Description, Deployment, Status, Version when present. */
+function logApplicationFieldsOfflineExternal(a) {
+  logger.log('🧷 Application - external');
+  logger.log(`  Key:           ${a.key ?? '—'}`);
+  logger.log(`  Display name:  ${a.displayName ?? '—'}`);
+  logger.log(`  Description:   ${a.description ?? '—'}`);
+  logger.log('  Deployment:    —');
+  if (a.status !== undefined && a.status !== '—') logger.log(`  Status:        ${a.status}`);
+  if (a.version !== undefined && a.version !== null) logger.log(`  Version:       ${a.version}`);
+}
+
+function logApplicationExternalIntegration(ei, options = {}) {
   logger.log('  External integration:');
   logger.log(`    schemaBasePath: ${ei.schemaBasePath}`);
   logger.log(`    systems: [${(ei.systems || []).join(', ')}]`);
   logger.log(`    dataSources: [${(ei.dataSources || []).join(', ')}]`);
-  logger.log(chalk.gray('\n  For external system data as on dataplane, run: aifabrix show <appKey> --online or aifabrix app show <appKey>.'));
+  if (!options.skipHint) {
+    logger.log(chalk.gray('\n  For external system data as on dataplane, run: aifabrix show <appKey> --online or aifabrix app show <appKey>.'));
+  }
 }
 
-function logApplicationSection(a, isExternal) {
-  logApplicationFields(a);
-  if (isExternal && a.externalIntegration) {
-    logApplicationExternalIntegration(a.externalIntegration);
+function logApplicationSection(a, summary) {
+  const isExternal = summary.isExternal;
+  const onlineExternal = summary.source === 'online' && isExternal;
+  const offlineExternal = summary.source === 'offline' && isExternal;
+  if (onlineExternal) {
+    logApplicationFieldsOnlineExternal(a);
+  } else if (offlineExternal) {
+    logApplicationFieldsOfflineExternal(a);
+  } else {
+    logApplicationFields(a);
   }
+  /* External integration is logged after Dataplane block in display() when external */
 }
 
 function logRolesSection(roles) {
@@ -125,13 +156,13 @@ function logDatabasesSection(dbNames) {
 }
 
 function logExternalSystemMain(ext) {
-  logger.log('🔗 External system (dataplane)');
-  logger.log(`  Dataplane:     ${ext.dataplaneUrl}`);
-  logger.log(`  System key:    ${ext.systemKey}`);
-  logger.log(`  Display name:  ${ext.displayName}`);
-  logger.log(`  Type:          ${ext.type}`);
-  logger.log(`  Status:        ${ext.status}`);
+  logger.log('🧩 Dataplane');
   logger.log(`  Version:       ${ext.version ?? '—'}`);
+  logger.log(`  Credential:    ${ext.credentialId ?? '—'}`);
+  logger.log(`  Status:        ${ext.status ?? '—'}`);
+  logger.log(`  API docs:      ${ext.openApiDocsPageUrl ?? ext.apiDocumentUrl ?? '—'}`);
+  logger.log(`  MCP server:   ${ext.mcpServerUrl ?? '—'}`);
+  logger.log(`  OpenAPI spec:  ${ext.apiDocumentUrl ?? '—'}`);
 }
 
 function logExternalSystemDataSources(dataSources) {
@@ -144,8 +175,8 @@ function logExternalSystemDataSources(dataSources) {
 
 /**
  * Log OpenAPI and MCP documentation links for external system (dataplane endpoints).
- * REST: /api/v1/rest/{systemKey}/docs; MCP: /api/v1/mcp/{systemKey}/{resourceType}/docs per dataSource.
- * @param {Object} ext - External system result (dataplaneUrl, systemKey, dataSources, openapiFiles, openapiEndpoints)
+ * Uses openApiDocsPageUrl from dataplane when available; otherwise REST/MCP constructed URLs.
+ * @param {Object} ext - External system result (dataplaneUrl, systemKey, dataSources, openapiFiles, openapiEndpoints, openApiDocsPageUrl)
  */
 function logExternalSystemServiceLinks(ext) {
   if (!ext || !ext.dataplaneUrl || !ext.systemKey) return;
@@ -155,9 +186,13 @@ function logExternalSystemServiceLinks(ext) {
     (ext.openapiEndpoints && ext.openapiEndpoints.length > 0);
   const dataSources = ext.dataSources || [];
   const hasMcp = dataSources.length > 0;
-  if (!hasOpenApi && !hasMcp) return;
+  const openApiDocsPageUrl = ext.openApiDocsPageUrl;
+  if (!hasOpenApi && !hasMcp && !openApiDocsPageUrl) return;
 
   logger.log('  Service links:');
+  if (openApiDocsPageUrl) {
+    logger.log(`    OpenAPI docs page: ${openApiDocsPageUrl}`);
+  }
   logger.log(`    REST OpenAPI:  ${base}/api/v1/rest/${sk}/docs`);
   if (hasMcp) {
     dataSources.forEach((ds) => {
@@ -175,24 +210,55 @@ function logExternalSystemApplication(ap) {
   if (ap.permissions) logger.log(`    permissions: ${Array.isArray(ap.permissions) ? ap.permissions.join(', ') : ap.permissions}`);
 }
 
-function logExternalSystemSection(ext) {
+function logExternalSystemSection(ext, options = {}) {
   if (!ext) return;
-  logger.log('');
+  if (!options.afterApplication) logger.log('');
   if (ext.error) {
-    logger.log('🔗 External system (dataplane): not available (dataplane unreachable or not found).');
+    logger.log('🧩 Dataplane: not available (dataplane unreachable or not found).');
     return;
   }
   logExternalSystemMain(ext);
-  logExternalSystemDataSources(ext.dataSources);
-  logExternalSystemApplication(ext.application);
-  if (ext.openapiFiles && ext.openapiFiles.length > 0) {
-    logger.log(`  OpenAPI files: ${ext.openapiFiles.length}`);
+  if (!options.compact) {
+    logExternalSystemDataSources(ext.dataSources);
+    logExternalSystemApplication(ext.application);
+    if (ext.openapiFiles && ext.openapiFiles.length > 0) {
+      logger.log(`  OpenAPI files: ${ext.openapiFiles.length}`);
+    }
+    if (ext.openapiEndpoints && ext.openapiEndpoints.length > 0) {
+      const sample = ext.openapiEndpoints.slice(0, 3).map((e) => `${e.method || 'GET'} ${e.path || e.pathPattern || e}`).join(', ');
+      logger.log(`  OpenAPI endpoints: ${ext.openapiEndpoints.length} (e.g. ${sample}${ext.openapiEndpoints.length > 3 ? ' …' : ''})`);
+    }
+    logExternalSystemServiceLinks(ext);
   }
-  if (ext.openapiEndpoints && ext.openapiEndpoints.length > 0) {
-    const sample = ext.openapiEndpoints.slice(0, 3).map((e) => `${e.method || 'GET'} ${e.path || e.pathPattern || e}`).join(', ');
-    logger.log(`  OpenAPI endpoints: ${ext.openapiEndpoints.length} (e.g. ${sample}${ext.openapiEndpoints.length > 3 ? ' …' : ''})`);
+}
+
+function getDisplayContext(summary) {
+  const a = summary.application;
+  const databases = summary.databases ?? a.databases ?? [];
+  const dbNames = Array.isArray(databases) ? databases.map((d) => (d && d.name) || d).filter(Boolean) : [];
+  return {
+    a,
+    roles: summary.roles ?? a.roles ?? [],
+    permissions: summary.permissions ?? a.permissions ?? [],
+    authentication: summary.authentication ?? a.authentication,
+    portalInputConfigurations: summary.portalInputConfigurations ?? a.portalInputConfigurations ?? [],
+    dbNames
+  };
+}
+
+function displayExternalAppBlock(summary) {
+  logger.log('');
+  if (summary.externalSystem && !summary.externalSystem.error) {
+    logExternalSystemSection(summary.externalSystem, { afterApplication: true, compact: true });
+  } else {
+    const reason = summary.externalSystem && summary.externalSystem.error ? ` (${summary.externalSystem.error})` : '';
+    logger.log(`🧩 Dataplane: not available${reason}`);
+  }
+  if (summary.application.externalIntegration) {
+    logger.log('');
+    const skipHint = summary.source === 'online' && summary.externalSystem && !summary.externalSystem.error;
+    logApplicationExternalIntegration(summary.application.externalIntegration, { skipHint });
   }
-  logExternalSystemServiceLinks(ext);
 }
 
 /**
@@ -202,27 +268,21 @@ function logExternalSystemSection(ext) {
  * @param {boolean} [options.permissionsOnly] - When true, output only source and Permissions section
  */
 function display(summary, options = {}) {
-  const a = summary.application;
-  const roles = summary.roles ?? a.roles ?? [];
-  const permissions = summary.permissions ?? a.permissions ?? [];
-  const authentication = summary.authentication ?? a.authentication;
-  const portalInputConfigurations = summary.portalInputConfigurations ?? a.portalInputConfigurations ?? [];
-  const databases = summary.databases ?? a.databases ?? [];
-  const dbNames = Array.isArray(databases) ? databases.map((d) => (d && d.name) || d).filter(Boolean) : [];
+  const ctx = getDisplayContext(summary);
 
   logSourceAndHeader(summary);
   if (options.permissionsOnly) {
-    logPermissionsSection(permissions, { showWhenEmpty: true });
+    logPermissionsSection(ctx.permissions, { showWhenEmpty: true });
     logger.log('');
     return;
   }
-  logApplicationSection(a, summary.isExternal);
-  logRolesSection(roles);
-  /* Permissions section shown only when --permissions is set (permissionsOnly mode) */
-  logAuthSection(authentication);
-  logConfigurationsSection(portalInputConfigurations);
-  logDatabasesSection(dbNames);
-  logExternalSystemSection(summary.externalSystem);
+  logApplicationSection(ctx.a, summary);
+  if (summary.isExternal) displayExternalAppBlock(summary);
+  logRolesSection(ctx.roles);
+  logAuthSection(ctx.authentication);
+  logConfigurationsSection(ctx.portalInputConfigurations);
+  logDatabasesSection(ctx.dbNames);
+  if (!summary.isExternal) logExternalSystemSection(summary.externalSystem);
   logger.log('');
 }