@aifabrix/builder 2.39.1 → 2.39.3

package/README.md

@@ -103,7 +103,7 @@ All guides and references are listed in **[docs/README.md](docs/README.md)** (ta
 
 - [CLI Reference](docs/cli-reference.md) – All commands
 - [Infrastructure](docs/infrastructure.md) – What runs and why
-- [Configuration](docs/configuration.md) – Config files
+- [Configuration reference](docs/configuration/README.md) – Config files (deployment key, variables.yaml, env.template, secrets)
 
 ---
 

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/app/register.js

@@ -177,9 +177,9 @@ async function registerApplication(appKey, options = {}) {
     registrationData
   );
 
-  // Save credentials and display results
+  // Save credentials and display results (pass display name we sent so output shows it when API returns key as displayName)
   await saveLocalCredentials(responseData, authConfig.apiUrl);
-  displayRegistrationResults(responseData, authConfig.apiUrl, environment);
+  displayRegistrationResults(responseData, authConfig.apiUrl, environment, registrationData.displayName);
 }
 
 module.exports = { registerApplication, getEnvironmentPrefix };

package/lib/cli/setup-app.js

@@ -187,13 +187,16 @@ See integration/hubspot/wizard-hubspot-e2e.yaml for an example.`)
     .description('Show application container logs (and optional env summary with secrets masked)')
     .option('-f', 'Follow log stream')
     .option('-t, --tail <lines>', 'Number of lines (default: 100); 0 = full list', '100')
+    .option('-l, --level <level>', 'Show only logs at this level or above (debug|info|warn|error)')
     .action(async(appName, options) => {
       try {
         const { runAppLogs } = require('../commands/app-logs');
         const tailNum = parseInt(options.tail, 10);
+        const level = options.level !== undefined && options.level !== null && options.level !== '' ? String(options.level).trim() : undefined;
         await runAppLogs(appName, {
           follow: options.f,
-          tail: Number.isNaN(tailNum) ? 100 : tailNum
+          tail: Number.isNaN(tailNum) ? 100 : tailNum,
+          level
         });
       } catch (error) {
         handleCommandError(error, 'logs');

package/lib/commands/app-logs.js

@@ -8,6 +8,7 @@
 
 const chalk = require('chalk');
 const { exec, spawn } = require('child_process');
+const readline = require('readline');
 const { promisify } = require('util');
 const logger = require('../utils/logger');
 const config = require('../core/config');
@@ -19,6 +20,24 @@ const execAsync = promisify(exec);
 /** Default number of log lines */
 const DEFAULT_TAIL_LINES = 100;
 
+/** Allowed log levels for --level filter (lowest to highest severity) */
+const LOG_LEVELS = ['debug', 'info', 'warn', 'error'];
+
+/** Severity rank: higher = more severe. Used for "show this level and above". */
+const LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+
+/** Prefix pattern: INFO:, ERROR:, WARN:, WARNING:, DEBUG: at start of line */
+const LEVEL_PREFIX_REGEX = /^(DEBUG|INFO|WARN|WARNING|ERROR)\s*[:-\s]/i;
+
+/** Level after timestamp or space (e.g. "2026-02-11 08:51:01 error: msg" or "  error: msg") */
+const LEVEL_AFTER_PREFIX_REGEX = /(?:^|\s)(DEBUG|INFO|WARN|WARNING|ERROR)\s*:/i;
+
+/** Level after word boundary (e.g. "[pino]error: msg" or BOM + "error:") so "error:" is detected anywhere */
+const LEVEL_WORD_BOUNDARY_REGEX = /\b(DEBUG|INFO|WARN|WARNING|ERROR)\s*:/i;
+
+/** JSON "level" field pattern */
+const LEVEL_JSON_REGEX = /"level"\s*:\s*"(\w+)"/i;
+
 /** Env key patterns that indicate a secret (mask value) */
 const SECRET_KEY_PATTERN = /password|secret|token|credential|api[_-]?key/i;
 
@@ -50,6 +69,53 @@ function maskEnvLine(line) {
   return line;
 }
 
+/**
+ * Extract log level from a line (prefix like INFO:/error: or JSON "level":"info").
+ * Supports: INFO:, ERROR:, error:, info: (miso-controller/pino), WARN:, DEBUG:, and "level":"x" in JSON.
+ * @param {string} line - Single log line
+ * @returns {string|null} One of 'debug'|'info'|'warn'|'error', or null if not parseable
+ */
+function getLogLevel(line) {
+  if (!line || typeof line !== 'string') return null;
+  const prefixMatch = line.match(LEVEL_PREFIX_REGEX);
+  if (prefixMatch) {
+    const raw = prefixMatch[1].toLowerCase();
+    return raw === 'warning' ? 'warn' : raw;
+  }
+  const afterPrefixMatch = line.match(LEVEL_AFTER_PREFIX_REGEX);
+  if (afterPrefixMatch) {
+    const raw = afterPrefixMatch[1].toLowerCase();
+    return raw === 'warning' ? 'warn' : raw;
+  }
+  const wordBoundaryMatch = line.match(LEVEL_WORD_BOUNDARY_REGEX);
+  if (wordBoundaryMatch) {
+    const raw = wordBoundaryMatch[1].toLowerCase();
+    return raw === 'warning' ? 'warn' : raw;
+  }
+  const jsonMatch = line.match(LEVEL_JSON_REGEX);
+  if (jsonMatch) {
+    const raw = jsonMatch[1].toLowerCase();
+    return raw === 'warning' ? 'warn' : raw;
+  }
+  return null;
+}
+
+/**
+ * Whether a line's level passes the minimum level filter (show this level and above).
+ * @param {string|null} lineLevel - Level from getLogLevel (null treated as 'info')
+ * @param {string|undefined|null} minLevel - Minimum level (e.g. 'error', 'info')
+ * @returns {boolean} True if line should be shown
+ */
+function passesLevelFilter(lineLevel, minLevel) {
+  if (minLevel === null || minLevel === undefined || minLevel === '') return true;
+  const normalized = (minLevel || '').toString().trim().toLowerCase();
+  if (!LOG_LEVELS.includes(normalized)) return true;
+  const lineRank =
+    lineLevel === null || lineLevel === undefined ? LEVEL_RANK.info : (LEVEL_RANK[lineLevel] ?? LEVEL_RANK.info);
+  const minRank = LEVEL_RANK[normalized];
+  return lineRank >= minRank;
+}
+
 /**
  * Dump container env (masked) and print to logger
  * @async
@@ -75,33 +141,102 @@ async function dumpMaskedEnv(containerName) {
 }
 
 /**
- * Run docker logs (non-follow): tail N lines or full (tail 0)
+ * Run docker logs (non-follow): tail N lines or full (tail 0). If options.level is set, stdout is piped and filtered.
  * @async
  * @param {string} containerName - Docker container name
- * @param {Object} options - { tail: number } (0 = full, no limit)
+ * @param {Object} options - { tail: number, level?: string }
  * @returns {Promise<void>}
  */
 async function runDockerLogs(containerName, options) {
   const args = options.tail === 0 ? ['logs', containerName] : ['logs', '--tail', String(options.tail), containerName];
+  const minLevel =
+    options.level !== undefined && options.level !== null && options.level !== ''
+      ? String(options.level).trim().toLowerCase()
+      : null;
+
+  if (minLevel === null || minLevel === undefined || !LOG_LEVELS.includes(minLevel)) {
+    return new Promise((resolve, reject) => {
+      const proc = spawn('docker', args, { stdio: 'inherit' });
+      proc.on('error', reject);
+      proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`docker logs exited with ${code}`))));
+    });
+  }
+
   return new Promise((resolve, reject) => {
-    const proc = spawn('docker', args, { stdio: 'inherit' });
+    const proc = spawn('docker', args, { stdio: ['inherit', 'pipe', 'pipe'] });
     proc.on('error', reject);
-    proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`docker logs exited with ${code}`))));
+
+    function onLine(line) {
+      if (passesLevelFilter(getLogLevel(line), minLevel)) {
+        process.stdout.write(line + '\n');
+      }
+    }
+
+    const rlOut = readline.createInterface({ input: proc.stdout, crlfDelay: Infinity });
+    rlOut.on('line', onLine);
+    const rlErr = readline.createInterface({ input: proc.stderr, crlfDelay: Infinity });
+    rlErr.on('line', onLine);
+
+    let streamsClosed = 0;
+    let exitCode = null;
+    function tryFinish() {
+      if (streamsClosed < 2 || exitCode === null) return;
+      if (exitCode !== 0) reject(new Error(`docker logs exited with ${exitCode}`));
+      else resolve();
+    }
+    rlOut.on('close', () => {
+      streamsClosed += 1;
+      tryFinish();
+    });
+    rlErr.on('close', () => {
+      streamsClosed += 1;
+      tryFinish();
+    });
+    proc.on('close', (code) => {
+      exitCode = code;
+      tryFinish();
+    });
   });
 }
 
 /**
- * Run docker logs --follow (stream), optionally with tail
+ * Run docker logs --follow (stream), optionally with tail. If minLevel is set, stdout is piped and filtered.
  * @param {string} containerName - Docker container name
  * @param {number} [tail] - Lines to show (0 = full, omit --tail)
+ * @param {string|null} [minLevel] - Minimum log level to show (debug|info|warn|error)
  */
-function runDockerLogsFollow(containerName, tail) {
+function runDockerLogsFollow(containerName, tail, minLevel) {
   const args = tail === 0 ? ['logs', '-f', containerName] : ['logs', '-f', '--tail', String(tail), containerName];
-  const proc = spawn('docker', args, { stdio: 'inherit' });
+  const level =
+    minLevel !== undefined && minLevel !== null && minLevel !== ''
+      ? String(minLevel).trim().toLowerCase()
+      : null;
+  const useFilter = level !== null && level !== undefined && LOG_LEVELS.includes(level);
+
+  if (!useFilter) {
+    const proc = spawn('docker', args, { stdio: 'inherit' });
+    proc.on('error', (err) => {
+      logger.log(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    });
+    proc.on('close', (code) => {
+      if (code !== 0 && code !== null) process.exit(code);
+    });
+    return;
+  }
+
+  const proc = spawn('docker', args, { stdio: ['inherit', 'pipe', 'pipe'] });
   proc.on('error', (err) => {
     logger.log(chalk.red(`Error: ${err.message}`));
     process.exit(1);
   });
+  function onLine(line) {
+    if (passesLevelFilter(getLogLevel(line), level)) process.stdout.write(line + '\n');
+  }
+  const rlOut = readline.createInterface({ input: proc.stdout, crlfDelay: Infinity });
+  rlOut.on('line', onLine);
+  const rlErr = readline.createInterface({ input: proc.stderr, crlfDelay: Infinity });
+  rlErr.on('line', onLine);
   proc.on('close', (code) => {
     if (code !== 0 && code !== null) process.exit(code);
   });
@@ -114,10 +249,22 @@ function runDockerLogsFollow(containerName, tail) {
  * @param {Object} options - CLI options
  * @param {boolean} [options.follow] - Follow log stream (-f)
  * @param {number} [options.tail] - Number of lines (default 100; 0 = full list)
+ * @param {string} [options.level] - Show only logs at this level or above (debug|info|warn|error)
  * @returns {Promise<void>}
  */
 async function runAppLogs(appKey, options = {}) {
   validateAppName(appKey);
+  const rawLevel =
+    options.level !== undefined && options.level !== null && options.level !== ''
+      ? String(options.level).trim()
+      : undefined;
+  const level = rawLevel ? rawLevel.toLowerCase() : undefined;
+  if (level !== undefined && level !== null && !LOG_LEVELS.includes(level)) {
+    throw new Error(
+      `Invalid log level '${rawLevel}'; use one of: ${LOG_LEVELS.join(', ')}`
+    );
+  }
+
   const developerId = await config.getDeveloperId();
   const containerName = containerHelpers.getContainerName(appKey, developerId);
 
@@ -131,16 +278,16 @@ async function runAppLogs(appKey, options = {}) {
   }
 
   if (follow) {
-    runDockerLogsFollow(containerName, tail);
+    runDockerLogsFollow(containerName, tail, level);
     return;
   }
 
   try {
-    await runDockerLogs(containerName, { tail });
+    await runDockerLogs(containerName, { tail, level });
   } catch (err) {
     logger.log(chalk.red(`Error: ${err.message}`));
     throw new Error(`Failed to show logs: ${err.message}`);
   }
 }
 
-module.exports = { runAppLogs, maskEnvLine };
+module.exports = { runAppLogs, maskEnvLine, getLogLevel, passesLevelFilter };

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);

package/lib/schema/deployment-rules.yaml

@@ -49,7 +49,6 @@ application:
   overridablePaths:
     - configuration.items.value
     - authentication.endpoints
-    - deployment.controllerUrl
     - healthCheck.interval
     - healthCheck.probeIntervalInSeconds
 
@@ -60,7 +59,6 @@ externalSystem:
     - description
     - type
     - enabled
-    - environment
     - authentication
     - openapi
     - mcp
@@ -75,8 +73,6 @@ externalSystem:
     - generateMcpContract
     - generateOpenApiContract
   overridablePaths:
-    - environment.baseUrl
-    - environment.region
     - authentication.oauth2
     - authentication.apikey
     - authentication.basic