@aifabrix/builder 2.43.0 → 2.44.0

package/lib/utils/cli-test-layout-chalk.js

@@ -0,0 +1,267 @@
+/**
+ * @fileoverview Chalk helpers aligned with `.cursor/plans/layout.md` (CLI TTY / validation summaries).
+ * @see `.cursor/plans/layout.md` — Contributor appendix for glyph rules and the implementation map.
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+
+/** Canonical success glyph (green), layout §CORE / §3. */
+function successGlyph() {
+  return chalk.green('✔');
+}
+
+/** Failure glyph only (red), layout §18 — compose with other chalk segments if needed. */
+function failureGlyph() {
+  return chalk.red('✖');
+}
+
+/**
+ * Single-line success message: green ✔ + green rest (layout §CORE).
+ * @param {string} message - text after the ✔ (no leading space)
+ * @returns {string}
+ */
+function formatSuccessLine(message) {
+  return chalk.green(`✔ ${message}`);
+}
+
+/**
+ * Success line with leading newline (common for footers / deploy summaries).
+ * @param {string} message
+ * @returns {string}
+ */
+function formatSuccessParagraph(message) {
+  return chalk.green(`\n✔ ${message}`);
+}
+
+/**
+ * Blocking error line: red ✖ + red message (layout §18).
+ * @param {string} message
+ * @returns {string}
+ */
+function formatBlockingError(message) {
+  return `${chalk.red('✖')} ${chalk.red(message)}`;
+}
+
+/**
+ * Failure with optional hint (layout §7).
+ * @param {string} title - main error text (red)
+ * @param {string} [hint] - optional hint (gray "Hint:" + yellow text)
+ * @returns {string}
+ */
+function formatIssue(title, hint) {
+  const head = `${chalk.red('✖')} ${chalk.red(title)}`;
+  if (!hint) {
+    return head;
+  }
+  return `${head}\n  ${chalk.gray('Hint:')} ${chalk.yellow(hint)}`;
+}
+
+/**
+ * Next actions list (layout §19): bold title, cyan bullets, white lines.
+ * @param {string[]} lines - action text without leading "-"
+ * @returns {string}
+ */
+function formatNextActions(lines) {
+  const body = (lines || [])
+    .map(line => `${chalk.cyan('-')} ${chalk.white(line)}`)
+    .join('\n');
+  return `${sectionTitle('Next actions:')}\n${body}`;
+}
+
+/**
+ * Docs / link line (layout §14): gray label, cyan URL.
+ * @param {string} label - e.g. "Docs:" or "Docs"
+ * @param {string} url
+ * @returns {string}
+ */
+function formatDocsLine(label, url) {
+  const lbl = label.endsWith(':') ? label : `${label}:`;
+  return `${chalk.gray(lbl)} ${chalk.cyan(url)}`;
+}
+
+/**
+ * Progress / async (layout §15): yellow ⏳ + white message.
+ * @param {string} message
+ * @returns {string}
+ */
+function formatProgress(message) {
+  return `${chalk.yellow('⏳')} ${chalk.white(message)}`;
+}
+
+/**
+ * Section title + bullet list (layout §3, §9 impact-style).
+ * @param {string} title
+ * @param {string[]} items - lines without bullet prefix
+ * @param {{ bullet?: 'cyan'|'red' }} [opts]
+ * @returns {string}
+ */
+function formatBulletSection(title, items, opts) {
+  const bulletColor = opts && opts.bullet === 'red' ? chalk.red : chalk.cyan;
+  const body = (items || []).map(line => `${bulletColor('-')} ${chalk.white(line)}`).join('\n');
+  return `${sectionTitle(title)}\n${body}`;
+}
+
+/**
+ * Bold white section title (layout: Section).
+ * @param {string} text
+ * @returns {string}
+ */
+function sectionTitle(text) {
+  return chalk.white.bold(text);
+}
+
+/**
+ * Gray label + bold white value (layout: HEADER BLOCK).
+ * @param {string} label - e.g. "System:"
+ * @param {string} value
+ * @returns {string}
+ */
+function headerKeyValue(label, value) {
+  return `${chalk.gray(label)} ${chalk.white.bold(value)}`;
+}
+
+/**
+ * Info line (cyan ℹ / neutral progress).
+ * @param {string} text
+ * @returns {string}
+ */
+function infoLine(text) {
+  return chalk.cyan(text);
+}
+
+/**
+ * Metadata (URLs, hints).
+ * @param {string} text
+ * @returns {string}
+ */
+function metadata(text) {
+  return chalk.gray(text);
+}
+
+/**
+ * @param {'ok'|'warn'|'fail'|'skipped'} agg
+ * @returns {string} Uppercase status word for header
+ */
+function aggregateStatusWord(agg) {
+  if (agg === 'warn') return 'WARN';
+  if (agg === 'fail') return 'FAIL';
+  if (agg === 'skipped') return 'SKIPPED';
+  return 'OK';
+}
+
+/**
+ * Colored glyph from aggregate status.
+ * @param {'ok'|'warn'|'fail'|'skipped'} agg
+ * @param {string} glyph - unicode ✔ ⚠ ✖ ⏭
+ * @returns {string}
+ */
+function colorAggregateGlyph(agg, glyph) {
+  if (agg === 'ok') return chalk.green(glyph);
+  if (agg === 'warn') return chalk.yellow(glyph);
+  if (agg === 'fail') return chalk.red(glyph);
+  return chalk.gray(glyph);
+}
+
+/**
+ * Full "Status: ✔ OK" line (glyph + word same color family).
+ * @param {'ok'|'warn'|'fail'|'skipped'} agg
+ * @param {string} glyph
+ * @returns {string}
+ */
+function formatStatusKeyValue(agg, glyph) {
+  const g = colorAggregateGlyph(agg, glyph);
+  const w = aggregateStatusWord(agg);
+  const word =
+    agg === 'ok'
+      ? chalk.green(w)
+      : agg === 'warn'
+        ? chalk.yellow(w)
+        : agg === 'fail'
+          ? chalk.red(w)
+          : chalk.gray(w);
+  return `${chalk.gray('Status:')} ${g} ${word}`;
+}
+
+/**
+ * Datasource list row (layout §5): symbol + name (white) + status hint (gray).
+ * @param {'ok'|'warn'|'fail'|'skipped'} rowStatus
+ * @param {string} name
+ * @param {string} [statusHint] - e.g. "Ready", shown in gray parens
+ * @returns {string}
+ */
+function formatDatasourceListRow(rowStatus, name, statusHint) {
+  const sym =
+    rowStatus === 'ok'
+      ? chalk.green('✔')
+      : rowStatus === 'warn'
+        ? chalk.yellow('⚠')
+        : rowStatus === 'fail'
+          ? chalk.red('✖')
+          : chalk.gray('⏭');
+  const hint = statusHint ? ` ${chalk.gray(`(${statusHint})`)}` : '';
+  return `  ${sym} ${chalk.white(name)}${hint}`;
+}
+
+/**
+ * Footer line for all-pass / warn / fail.
+ * @param {boolean} success
+ * @param {'ok'|'warn'|'fail'} [agg]
+ * @param {string} okMsg
+ * @param {string} warnMsg
+ * @param {string} failMsg
+ * @returns {string}
+ */
+function integrationFooterLine(success, agg, okMsg, warnMsg, failMsg) {
+  if (success && agg === 'warn') {
+    return chalk.yellow(`\n⚠ ${warnMsg}`);
+  }
+  if (success) {
+    return formatSuccessParagraph(okMsg);
+  }
+  return chalk.red(`\n✖ ${failMsg}`);
+}
+
+/**
+ * Color a single data-quality / rollup line that starts with ✔, ⚠, or ✖.
+ * @param {string} line
+ * @returns {string}
+ */
+function colorRollupPrefixedLine(line) {
+  const trimmed = line.trimStart();
+  const first = trimmed[0];
+  if (first === '✔') {
+    return chalk.green('✔') + chalk.white(trimmed.slice(1));
+  }
+  if (first === '⚠') {
+    return chalk.yellow('⚠') + chalk.white(trimmed.slice(1));
+  }
+  if (first === '✖') {
+    return chalk.red('✖') + chalk.white(trimmed.slice(1));
+  }
+  return line;
+}
+
+module.exports = {
+  sectionTitle,
+  headerKeyValue,
+  infoLine,
+  metadata,
+  aggregateStatusWord,
+  colorAggregateGlyph,
+  formatStatusKeyValue,
+  formatDatasourceListRow,
+  integrationFooterLine,
+  colorRollupPrefixedLine,
+  successGlyph,
+  failureGlyph,
+  formatSuccessLine,
+  formatSuccessParagraph,
+  formatBlockingError,
+  formatIssue,
+  formatNextActions,
+  formatDocsLine,
+  formatProgress,
+  formatBulletSection
+};

package/lib/utils/cli-utils.js

@@ -10,8 +10,8 @@
 
 const path = require('path');
 const chalk = require('chalk');
-const fs = require('fs').promises;
 const logger = require('./logger');
+const { getDockerDaemonStartHintSentence, getDockerApiOverTcpHintLines } = require('./docker-not-running-hint');
 
 /**
  * Validates a command and its options
@@ -96,7 +96,47 @@ function isPermissionDeniedError(errorMsg) {
 function isDockerPermissionDeniedError(errorMsg) {
   if (!isPermissionDeniedError(errorMsg)) return false;
   const lower = errorMsg.toLowerCase();
-  return lower.includes('docker') || lower.includes('socket') || errorMsg.includes('EACCES');
+  // Do not treat every EACCES as Docker (e.g. mkdir on a bogus server-side secrets path).
+  return lower.includes('docker') || lower.includes('docker.sock') || lower.includes('/var/run/docker');
+}
+
+/**
+ * True for Node fs errno messages (mkdir, open, …), not HTTP 403 from Controller/Dataplane.
+ * Those strings also match {@link isPermissionDeniedError} and must not get API token hints.
+ * @param {string} errorMsg
+ * @returns {boolean}
+ */
+function isLocalFilesystemPermissionDeniedError(errorMsg) {
+  if (!errorMsg || typeof errorMsg !== 'string') return false;
+  const lower = errorMsg.toLowerCase();
+  const looksLikeFsErrno =
+    lower.includes('eacces') ||
+    lower.includes('eperm') ||
+    lower.includes('enoent') ||
+    lower.includes('enospc');
+  if (!looksLikeFsErrno && !lower.includes('permission denied')) return false;
+  return (
+    /\bmkdir\b/i.test(errorMsg) ||
+    /\brmdir\b/i.test(errorMsg) ||
+    /\brename\b/i.test(errorMsg) ||
+    /\bunlink\b/i.test(errorMsg) ||
+    /\bchmod\b/i.test(errorMsg) ||
+    /permission denied,?\s*open\b/i.test(lower) ||
+    /,\s*open\s+['"]/i.test(errorMsg)
+  );
+}
+
+/**
+ * Local fs EACCES (wrong AIFABRIX_HOME path, etc.) — not API/RBAC.
+ * @param {string} errorMsg
+ * @returns {string[]|null}
+ */
+function formatLocalFilesystemPermissionError(errorMsg) {
+  if (!isLocalFilesystemPermissionDeniedError(errorMsg)) return null;
+  return [
+    `   ${errorMsg}`,
+    '   This is a local filesystem path or permissions issue, not an API or RBAC token. Check AIFABRIX_HOME, AIFABRIX_CONFIG, and that the target directory is writable.'
+  ];
 }
 
 /**
@@ -118,7 +158,8 @@ function formatDockerError(errorMsg) {
   if (isDockerNotRunningError(errorMsg)) {
     return [
       '   Docker is not running or not installed.',
-      '   Please start Docker Desktop and try again.'
+      `   ${getDockerDaemonStartHintSentence()}`,
+      ...getDockerApiOverTcpHintLines()
     ];
   }
   if (isPortConflictError(errorMsg)) {
@@ -129,20 +170,37 @@ function formatDockerError(errorMsg) {
   }
   if (isDockerPermissionDeniedError(errorMsg)) {
     return [
-      '   Permission denied.',
-      '   Make sure you have the necessary permissions to run Docker commands.'
+      '   Permission denied when using Docker (e.g. unix socket).',
+      '   On Linux you can add your user to the "docker" group and log in again, or use the Engine API via docker-endpoint:',
+      ...getDockerApiOverTcpHintLines()
     ];
   }
   return null;
 }
 
+/**
+ * True when the message indicates the Azure CLI binary is missing or not logged in.
+ * Do not use a naive "az"+"failed" substring match: "azurecr.io", "Azure", "lazy", "amazon", etc. contain "az".
+ * @param {string} errorMsg - Error message
+ * @returns {boolean}
+ */
+function isAzureCliToolingError(errorMsg) {
+  if (errorMsg.includes('Azure CLI is not installed')) return true;
+  if (errorMsg.includes('az --version failed')) return true;
+  if (errorMsg.includes('Not logged in to Azure')) return true;
+  if (errorMsg.includes('az: command not found')) return true;
+  if (errorMsg.includes('az.cmd: command not found')) return true;
+  if (errorMsg.includes('\'az\' is not recognized') || errorMsg.includes('"az" is not recognized')) return true;
+  return false;
+}
+
 /**
  * Format Azure-related errors
  * @param {string} errorMsg - Error message
  * @returns {string[]|null} Array of error message lines or null if not an Azure error
  */
 function formatAzureError(errorMsg) {
-  if (errorMsg.includes('Azure CLI is not installed') || errorMsg.includes('az --version failed') || (errorMsg.includes('az') && errorMsg.includes('failed'))) {
+  if (isAzureCliToolingError(errorMsg)) {
     return [
       '   Azure CLI is not installed or not working properly.',
       '   Install from: https://docs.microsoft.com/cli/azure/install-azure-cli',
@@ -249,6 +307,7 @@ function formatValidationError(errorMsg) {
 function formatApiPermissionError(errorMsg) {
   if (!isPermissionDeniedError(errorMsg)) return null;
   if (isDockerPermissionDeniedError(errorMsg)) return null;
+  if (isLocalFilesystemPermissionDeniedError(errorMsg)) return null;
   return [
     `   ${errorMsg}`,
     '   Ensure your token has the required permission (e.g. external-system:delete for delete).'
@@ -267,8 +326,25 @@ function formatApiPermissionError(errorMsg) {
  * @param {string} errorMsg - Error message
  * @returns {string[]|null} Formatted error messages or null if no formatter matched
  */
+/**
+ * up-infra / checkDockerAvailability: multi-line "Cannot use Docker for infrastructure" + docker-endpoint hint.
+ * @param {string} errorMsg - Error message
+ * @returns {string[]|null}
+ */
+function formatCannotUseDockerInfrastructureError(errorMsg) {
+  if (!errorMsg.includes('Cannot use Docker for infrastructure')) {
+    return null;
+  }
+  const lines = errorMsg.split('\n').map((l) => l.trim()).filter(Boolean);
+  const out = lines.map((l) => `   ${l}`);
+  out.push(...getDockerApiOverTcpHintLines());
+  return out;
+}
+
 function tryFormatErrorWithFormatters(errorMsg) {
   const formatters = [
+    formatCannotUseDockerInfrastructureError,
+    formatLocalFilesystemPermissionError,
     formatApiPermissionError,
     formatDockerError,
     formatAzureError,
@@ -312,13 +388,13 @@ function formatError(error) {
  * @param {string[]} errorMessages - Error message lines
  */
 function logError(command, errorMessages) {
-  logger.error(`\n❌ Error in ${command} command:`);
+  logger.error(`\n✖ Error in ${command} command:`);
   errorMessages.forEach(msg => logger.error(msg));
   logger.error('\n💡 Run "aifabrix doctor" for environment diagnostics.\n');
 }
 
 /**
- * Logs the resolved app path so the user can see which directory (integration/<app> or builder/<app>) is used.
+ * Logs the resolved app path so the user can see which directory (integration/<systemKey> or builder/<appKey>) is used.
  * Path resolution order is always integration first, then builder; no CLI flag overrides this.
  *
  * @param {string} appPath - Resolved application directory path
@@ -366,7 +442,7 @@ function stripAnsi(str) {
 }
 
 /**
- * Appends a wizard error to integration/<appKey>/error.log (timestamp + message only; no stack or secrets).
+ * Appends a wizard error to integration/<systemKey>/error.log (timestamp + message only; no stack or secrets).
  * Uses full formatted message (with validation details) when error.formatted is set, stripped of ANSI.
  * Does not throw; logs and ignores write failures.
  * @param {string} appKey - Application/integration key (e.g. app name or system key)
@@ -384,8 +460,9 @@ async function appendWizardError(appKey, error) {
   const message = fullPlain && fullPlain.length > rawMessage.length ? fullPlain : rawMessage;
   const line = `${new Date().toISOString()} ${message}\n`;
   try {
-    await fs.mkdir(dir, { recursive: true });
-    await fs.appendFile(logPath, line, 'utf8');
+    const fsp = require('fs').promises;
+    await fsp.mkdir(dir, { recursive: true });
+    await fsp.appendFile(logPath, line, 'utf8');
   } catch (e) {
     logger.warn(`Could not write wizard error.log: ${e.message}`);
   }

package/lib/utils/compose-db-passwords.js

@@ -0,0 +1,138 @@
+/**
+ * Read database passwords from .env for Docker Compose generation.
+ *
+ * @fileoverview Compose DB password helpers
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fsSync = require('fs');
+const fs = require('fs').promises;
+const { formatMissingDbPasswordError } = require('./error-formatter');
+
+/** Reads and parses .env file. @param {string} envPath - Path to .env file. @returns {Promise<Object>} env vars. @throws {Error} If file not found. */
+async function readEnvFile(envPath) {
+  if (!fsSync.existsSync(envPath)) {
+    throw new Error(`.env file not found: ${envPath}`);
+  }
+
+  try {
+    const envContent = await fs.readFile(envPath, 'utf8');
+    if (envContent === undefined || envContent === null) {
+      throw new Error('Failed to read .env file: file content is empty or undefined');
+    }
+    const lines = envContent.split('\n');
+    const envVars = {};
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) {
+        continue;
+      }
+
+      const equalIndex = trimmed.indexOf('=');
+      if (equalIndex > 0) {
+        const key = trimmed.substring(0, equalIndex).trim();
+        const value = trimmed.substring(equalIndex + 1).trim();
+        envVars[key] = value;
+      }
+    }
+
+    return envVars;
+  } catch (error) {
+    throw new Error(`Failed to read .env file: ${error.message}`);
+  }
+}
+
+/**
+ * Validates and extracts password from environment variables
+ * @function extractPassword
+ * @param {Object} envVars - Environment variables
+ * @param {string} passwordKey - Password key to look up
+ * @param {Object} [context] - Optional: { appKey, multi } for clearer error messages
+ * @returns {string} Password value
+ * @throws {Error} If password is missing or empty
+ */
+function extractPassword(envVars, passwordKey, context = {}) {
+  const { appKey, multi } = context;
+  const appSuffix = appKey ? ` for application '${appKey}'` : '';
+
+  if (!(passwordKey in envVars)) {
+    throw new Error(multi && appKey ? formatMissingDbPasswordError(appKey, { multiDb: true, passwordKey }) : 'Missing required password variable ' + passwordKey + ' in .env file' + appSuffix + '. Add ' + passwordKey + '=your_secret to your .env file.');
+  }
+
+  const password = envVars[passwordKey].trim();
+  if (!password || password.length === 0) {
+    throw new Error('Password variable ' + passwordKey + ' is empty in .env file' + appSuffix + '. Set a non-empty value.');
+  }
+
+  return password;
+}
+
+/**
+ * Processes multiple databases
+ * @function processMultipleDatabases
+ * @param {Array} databases - Array of database configurations
+ * @param {Object} envVars - Environment variables
+ * @param {string} appKey - Application key
+ * @returns {Object} Object with passwords map and array
+ */
+function processMultipleDatabases(databases, envVars, appKey) {
+  const passwords = {};
+  const passwordsArray = [];
+  for (let i = 0; i < databases.length; i++) {
+    const db = databases[i];
+    const dbName = db.name || appKey;
+    const passwordKey = `DB_${i}_PASSWORD`;
+    const password = extractPassword(envVars, passwordKey, { appKey, multi: true });
+    passwords[dbName] = password;
+    passwordsArray.push(password);
+  }
+  return { passwords, passwordsArray };
+}
+
+/**
+ * Processes single database case
+ * @function processSingleDatabase
+ * @param {Object} envVars - Environment variables
+ * @param {string} appKey - Application key
+ * @returns {Object} Object with passwords map and array
+ */
+function processSingleDatabase(envVars, appKey) {
+  const passwords = {};
+  const passwordsArray = [];
+  const passwordKey = ('DB_0_PASSWORD' in envVars) ? 'DB_0_PASSWORD' : 'DB_PASSWORD';
+  if (!(passwordKey in envVars)) {
+    throw new Error(formatMissingDbPasswordError(appKey));
+  }
+  const password = extractPassword(envVars, passwordKey, { appKey });
+  passwords[appKey] = password;
+  passwordsArray.push(password);
+  return { passwords, passwordsArray };
+}
+
+/**
+ * Reads database passwords from .env file
+ * @async
+ * @function readDatabasePasswords
+ * @param {string} envPath - Path to .env file
+ * @param {Array<Object>} databases - Array of database configurations
+ * @param {string} appKey - Application key (fallback for single database)
+ * @returns {Promise<Object>} Object with passwords map and array
+ * @throws {Error} If required password variables are missing
+ */
+async function readDatabasePasswords(envPath, databases, appKey) {
+  const envVars = await readEnvFile(envPath);
+  if (databases && databases.length > 0) {
+    const { passwords, passwordsArray } = processMultipleDatabases(databases, envVars, appKey);
+    return { map: passwords, array: passwordsArray };
+  }
+  const { passwords, passwordsArray } = processSingleDatabase(envVars, appKey);
+  return { map: passwords, array: passwordsArray };
+}
+
+module.exports = {
+  readDatabasePasswords,
+  readEnvFile,
+  extractPassword
+};