@aifabrix/builder 2.39.0 → 2.39.2

package/lib/app/deploy-status-display.js

@@ -0,0 +1,78 @@
+/**
+ * Deploy status display helpers: build app URL from controller/port and show after deploy.
+ * @fileoverview Status URL display for application deployment
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { getApplicationStatus } = require('../api/applications.api');
+
+/**
+ * Builds app URL from controller base URL and app port (e.g. http://localhost:3600 + 3601 -> http://localhost:3601).
+ * @param {string} controllerUrl - Controller base URL
+ * @param {number} port - Application port
+ * @returns {string|null} App URL or null if parsing fails
+ */
+function buildAppUrlFromControllerAndPort(controllerUrl, port) {
+  if (!controllerUrl || (port === null || port === undefined) || typeof port !== 'number') return null;
+  try {
+    const u = new URL(controllerUrl);
+    u.port = String(port);
+    return u.toString();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parses URL and port from application status response body.
+ * @param {Object} body - Response body (may have data wrapper or top-level url/port)
+ * @returns {{ url: string|null, port: number|null }}
+ */
+function parseUrlAndPortFromStatusBody(body) {
+  const data = body?.data ?? body;
+  const url = (data && typeof data.url === 'string' && data.url.trim() !== '')
+    ? data.url
+    : (body?.url && typeof body.url === 'string' && body.url.trim() !== '')
+      ? body.url
+      : null;
+  const port = (data && typeof data.port === 'number')
+    ? data.port
+    : (body && typeof body.port === 'number')
+      ? body.port
+      : null;
+  return { url, port };
+}
+
+/**
+ * Fetches app URL from controller application status and displays it.
+ * Uses status API url when present; otherwise derives from status port and controller host.
+ * @param {string} controllerUrl - Controller base URL (used only to derive host when status returns port)
+ * @param {string} envKey - Environment key
+ * @param {string} appKey - Application key (manifest.key)
+ * @param {Object} authConfig - Auth used for deployment (same as for status)
+ */
+async function displayAppUrlFromController(controllerUrl, envKey, appKey, authConfig) {
+  let url = null;
+  let port = null;
+  try {
+    const res = await getApplicationStatus(controllerUrl, envKey, appKey, authConfig);
+    const parsed = parseUrlAndPortFromStatusBody(res?.data);
+    url = parsed.url;
+    port = parsed.port;
+  } catch (_) {
+    // Show fallback message below
+  }
+  if (!url && (port !== null && port !== undefined)) {
+    url = buildAppUrlFromControllerAndPort(controllerUrl, port);
+  }
+  if (url) {
+    logger.log(chalk.green(`   ✓ App running at ${url}`));
+  } else {
+    logger.log(chalk.blue('   ✓ App deployed. Get URL from controller dashboard.'));
+  }
+}
+
+module.exports = { displayAppUrlFromController, buildAppUrlFromControllerAndPort, parseUrlAndPortFromStatusBody };

package/lib/app/deploy.js

@@ -17,8 +17,8 @@ const pushUtils = require('../deployment/push');
 const logger = require('../utils/logger');
 const { detectAppType, getBuilderPath, getIntegrationPath } = require('../utils/paths');
 const { checkApplicationExists } = require('../utils/app-existence');
-const { getApplicationStatus } = require('../api/applications.api');
 const { loadDeploymentConfig } = require('./deploy-config');
+const { displayAppUrlFromController } = require('./deploy-status-display');
 
 /**
  * Validate application name format
@@ -219,26 +219,6 @@ function displayDeploymentResults(result) {
   }
 }
 
-/**
- * Fetches app URL from controller application status and displays it.
- * On API failure or missing URL, shows controllerUrl so the user always sees where the app is.
- * @param {string} controllerUrl - Controller base URL (used as fallback)
- * @param {string} envKey - Environment key
- * @param {string} appKey - Application key (manifest.key)
- * @param {Object} authConfig - Auth used for deployment (same as for status)
- */
-async function displayAppUrlFromController(controllerUrl, envKey, appKey, authConfig) {
-  let url = null;
-  try {
-    const res = await getApplicationStatus(controllerUrl, envKey, appKey, authConfig);
-    const body = res?.data;
-    url = (body && (body.url || body.data?.url)) || res?.url || null;
-  } catch (_) {
-    // Use controllerUrl fallback below
-  }
-  logger.log(chalk.green(`   ✓ App running at ${url || controllerUrl}`));
-}
-
 /**
  * Check if app is external and handle external deployment.
  * When options.type === 'external', forces deployment from integration/<app> (no app register needed).

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 yaml = require('js-yaml');
 const { generateExternalReadmeContent } = require('../utils/external-readme');
 
 /**
@@ -158,28 +159,69 @@ function generateReadmeMd(appName, config) {
 }
 
 /**
- * Generates README.md file if it doesn't exist
+ * Generates README.md file (optionally only if missing)
  * @async
  * @function generateReadmeMdFile
  * @param {string} appPath - Path to application directory
  * @param {string} appName - Application name
- * @param {Object} config - Application configuration
+ * @param {Object} config - Application configuration (e.g. from variables.yaml)
+ * @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
  * @throws {Error} If file generation fails
  */
-async function generateReadmeMdFile(appPath, appName, config) {
-  // Ensure directory exists
+async function generateReadmeMdFile(appPath, appName, config, options = {}) {
   await fs.mkdir(appPath, { recursive: true });
   const readmePath = path.join(appPath, 'README.md');
-  if (!(await fileExists(readmePath))) {
-    const readmeContent = generateReadmeMd(appName, config);
-    await fs.writeFile(readmePath, readmeContent, 'utf8');
+  if (!options.force && (await fileExists(readmePath))) {
+    return;
+  }
+  const readmeContent = generateReadmeMd(appName, config);
+  await fs.writeFile(readmePath, readmeContent, 'utf8');
+}
+
+/**
+ * Loads variables.yaml 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} appName - Application name
+ * @returns {Promise<void>} Resolves when README.md is written or skipped (no variables.yaml)
+ */
+async function ensureReadmeForAppPath(appPath, appName) {
+  const variablesPath = path.join(appPath, 'variables.yaml');
+  if (!(await fileExists(variablesPath))) {
+    return;
+  }
+  const content = await fs.readFile(variablesPath, 'utf8');
+  const config = yaml.load(content) || {};
+  await generateReadmeMdFile(appPath, appName, config, { force: true });
+}
+
+/**
+ * Generates README.md for an app at builder path(s): primary and cwd/builder if different.
+ * Use after ensureAppFromTemplate in up-miso / up-dataplane so README reflects current config.
+ * @async
+ * @function ensureReadmeForApp
+ * @param {string} appName - Application name (e.g. keycloak, miso-controller, dataplane)
+ * @returns {Promise<void>}
+ */
+async function ensureReadmeForApp(appName) {
+  const pathsUtil = require('../utils/paths');
+  const primaryPath = pathsUtil.getBuilderPath(appName);
+  await ensureReadmeForAppPath(primaryPath, appName);
+  const cwdBuilderPath = path.join(process.cwd(), 'builder', appName);
+  if (path.resolve(cwdBuilderPath) !== path.resolve(primaryPath)) {
+    await ensureReadmeForAppPath(cwdBuilderPath, appName);
   }
 }
 
 module.exports = {
   generateReadmeMdFile,
   generateReadmeMd,
-  formatAppDisplayName
+  formatAppDisplayName,
+  ensureReadmeForAppPath,
+  ensureReadmeForApp
 };
 

package/lib/cli/setup-service-user.js

@@ -19,17 +19,26 @@ const { runServiceUserCreate } = require('../commands/service-user');
 function setupServiceUserCommands(program) {
   const serviceUser = program
     .command('service-user')
-    .description('Create service users for integrations (one-time secret on create)');
+    .description('Create and manage service users (API clients) for integrations and CI')
+    .addHelpText('after', `
+Service users are dedicated accounts for integrations, CI pipelines, or API clients.
+The controller returns a one-time clientSecret on create—save it immediately; it cannot be retrieved again.
+
+Example:
+  $ aifabrix service-user create -u api-client-001 -e api@example.com \\
+      --redirect-uris "https://app.example.com/callback" --group-names "AI-Fabrix-Developers"
+
+Required: permission service-user:create on the controller. Run "aifabrix login" first.`);
 
   serviceUser
     .command('create')
-    .description('Create a service user (username, email, redirectUris, groupIds); receive one-time clientSecret (save it now)')
-    .option('--controller <url>', 'Controller URL (default: from config)')
+    .description('Create a service user and receive a one-time clientSecret (save it now; it will not be shown again)')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
     .option('-u, --username <username>', 'Service user username (required)')
     .option('-e, --email <email>', 'Email address (required)')
-    .option('--redirect-uris <uris>', 'Comma-separated redirect URIs for OAuth2 (required, e.g. https://app.example.com/callback)')
-    .option('--group-names <names>', 'Comma-separated group names (required, e.g. AI-Fabrix-Developers)')
-    .option('-d, --description <description>', 'Optional description')
+    .option('--redirect-uris <uris>', 'Comma-separated OAuth2 redirect URIs (required)')
+    .option('--group-names <names>', 'Comma-separated group names to assign (required)')
+    .option('-d, --description <description>', 'Description for the service user')
     .action(async(options) => {
       try {
         const opts = {

package/lib/commands/service-user.js

@@ -36,16 +36,22 @@ async function getServiceUserAuth(controllerUrl) {
 }
 
 /**
- * Extract clientId and clientSecret from API response (response may be wrapped in data)
- * @param {Object} response - API response
+ * Extract clientId and clientSecret from API response.
+ * Controller returns { data: { user, clientSecret } }; API client puts body in response.data.
+ * So payload is at response.data.data. clientId may be on user.clientId or user.federatedIdentity.keycloakClientId.
+ * @param {Object} response - API response (success: true, data: body)
  * @returns {{ clientId: string, clientSecret: string }}
  */
 function extractCreateResponse(response) {
-  const data = response?.data ?? response;
-  return {
-    clientId: data?.clientId ?? '',
-    clientSecret: data?.clientSecret ?? ''
-  };
+  const payload = response?.data?.data ?? response?.data ?? response;
+  const user = payload?.user;
+  const clientId =
+    user?.clientId ??
+    user?.federatedIdentity?.keycloakClientId ??
+    payload?.clientId ??
+    '';
+  const clientSecret = payload?.clientSecret ?? '';
+  return { clientId, clientSecret };
 }
 
 /**

package/lib/commands/up-common.js

@@ -15,9 +15,11 @@ const chalk = require('chalk');
 const logger = require('../utils/logger');
 const pathsUtil = require('../utils/paths');
 const { copyTemplateFiles } = require('../validation/template');
+const { ensureReadmeForAppPath, ensureReadmeForApp } = require('../app/readme');
 
 /**
  * Copy template to a target path if variables.yaml is missing there.
+ * After copy, generates README.md from templates/applications/README.md.hbs.
  * @param {string} appName - Application name
  * @param {string} targetAppPath - Target directory (e.g. builder/keycloak)
  * @returns {Promise<boolean>} True if template was copied, false if already present
@@ -28,6 +30,7 @@ async function ensureTemplateAtPath(appName, targetAppPath) {
     return false;
   }
   await copyTemplateFiles(appName, targetAppPath);
+  await ensureReadmeForAppPath(targetAppPath, appName);
   return true;
 }
 
@@ -160,6 +163,7 @@ async function ensureAppFromTemplate(appName) {
     }
   }
 
+  await ensureReadmeForApp(appName);
   return primaryCopied;
 }
 

package/lib/external-system/generator.js

@@ -35,13 +35,19 @@ async function generateExternalSystemTemplate(appPath, systemKey, config) {
     const templateContent = await fs.readFile(templatePath, 'utf8');
     const template = handlebars.compile(templateContent);
 
+    const roles = (config.roles || null) && config.roles.map((role) => ({
+      ...role,
+      groups: role.groups || role.Groups || undefined
+    }));
+
     const context = {
       systemKey: systemKey,
       systemDisplayName: config.systemDisplayName || systemKey.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase()),
       systemDescription: config.systemDescription || `External system integration for ${systemKey}`,
       systemType: config.systemType || 'openapi',
       authType: config.authType || 'apikey',
-      roles: config.roles || null,
+      baseUrl: config.baseUrl || null,
+      roles: roles || null,
       permissions: config.permissions || null
     };
 
@@ -74,6 +80,8 @@ async function generateExternalDataSourceTemplate(appPath, datasourceKey, config
     const templateContent = await fs.readFile(templatePath, 'utf8');
     const template = handlebars.compile(templateContent);
 
+    const dimensions = config.dimensions || {};
+    const attributes = config.attributes || {};
     const context = {
       datasourceKey: datasourceKey,
       datasourceDisplayName: config.datasourceDisplayName || datasourceKey.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase()),
@@ -82,8 +90,11 @@ async function generateExternalDataSourceTemplate(appPath, datasourceKey, config
       entityType: config.entityType || datasourceKey.split('-').pop(),
       resourceType: config.resourceType || 'document',
       systemType: config.systemType || 'openapi',
-      dimensions: config.dimensions || {},
-      attributes: config.attributes || {}
+      // Pass non-empty objects so template uses custom block; empty/null so template uses schema-valid defaults
+      dimensions: Object.keys(dimensions).length > 0 ? dimensions : null,
+      attributes: Object.keys(attributes).length > 0 ? attributes : null,
+      // Literal expression strings for default attribute block (schema: pipe-based DSL {{raw.path}})
+      raw: { id: '{{raw.id}}', name: '{{raw.name}}' }
     };
 
     const rendered = template(context);