@aifabrix/builder 2.43.0 → 2.44.0

package/lib/utils/dev-ssh-config-helper.js

@@ -0,0 +1,196 @@
+/**
+ * @fileoverview Merge a Builder dev SSH Host alias into ~/.ssh/config (Mutagen / interactive SSH).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const nodeFsLib = require('../internal/node-fs');
+const path = require('path');
+const { ensureSshDir } = require('./ssh-key-helper');
+
+/**
+ * Derive SSH config Host alias: sync user + real hostname (e.g. dev01.builder02.local).
+ * @param {string} sshUser - sync-ssh-user
+ * @param {string} sshHost - sync-ssh-host (HostName)
+ * @returns {string}
+ */
+function getDevSshHostAlias(sshUser, sshHost) {
+  return `${sshUser}.${sshHost}`;
+}
+
+/**
+ * Parse ssh config into Host blocks (lines before the first Host are ignored).
+ * @param {string} content
+ * @returns {{ aliases: string[], body: string[] }[]}
+ */
+function parseSshHostBlocks(content) {
+  const lines = (content || '').split(/\r?\n/);
+  const blocks = [];
+  let i = 0;
+  while (i < lines.length) {
+    const m = lines[i].match(/^Host\s+(.+?)\s*$/i);
+    if (!m) {
+      i++;
+      continue;
+    }
+    const aliases = m[1].trim().split(/\s+/).filter(Boolean);
+    i++;
+    const body = [];
+    while (i < lines.length && !/^Host\s/i.test(lines[i])) {
+      body.push(lines[i]);
+      i++;
+    }
+    blocks.push({ aliases, body });
+  }
+  return blocks;
+}
+
+/**
+ * First value for a directive inside a Host block body (e.g. HostName, User).
+ * @param {string[]} bodyLines
+ * @param {string} directive - e.g. HostName
+ * @returns {string|null}
+ */
+function getHostBlockDirective(bodyLines, directive) {
+  const re = new RegExp(`^\\s+${directive}\\s+(.+)$`, 'i');
+  for (const line of bodyLines) {
+    const m = line.match(re);
+    if (m) return m[1].trim();
+  }
+  return null;
+}
+
+/**
+ * Find a Host block whose HostName and User match (exact trim match).
+ * @param {string} content
+ * @param {string} hostname
+ * @param {string} user
+ * @returns {{ aliases: string[], body: string[] }|null}
+ */
+function findMatchingHostBlockForUserHost(content, hostname, user) {
+  for (const block of parseSshHostBlocks(content)) {
+    const hn = getHostBlockDirective(block.body, 'HostName');
+    const u = getHostBlockDirective(block.body, 'User');
+    if (hn === hostname && u === user) {
+      return block;
+    }
+  }
+  return null;
+}
+
+/**
+ * SSH Host alias to suggest for ssh(1) when a block already exists.
+ * @param {{ aliases: string[] }} matchedBlock
+ * @param {string} canonicalAlias - e.g. dev01.builder02.local
+ * @returns {string}
+ */
+function resolveConnectAlias(matchedBlock, canonicalAlias) {
+  if (matchedBlock.aliases.includes(canonicalAlias)) {
+    return canonicalAlias;
+  }
+  return matchedBlock.aliases[0] || canonicalAlias;
+}
+
+/**
+ * Replace an existing Host block for hostAlias, or append a new block at EOF.
+ * @param {string} content - Existing ssh config (may be empty)
+ * @param {string} hostAlias - Host keyword value (single alias)
+ * @param {string} hostname - HostName directive
+ * @param {string} user - User directive
+ * @returns {string} Updated config
+ */
+function upsertSshHostBlock(content, hostAlias, hostname, user) {
+  const lines = (content || '').split(/\r?\n/);
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const m = line.match(/^Host\s+(.+?)\s*$/i);
+    if (m) {
+      const aliases = m[1].trim().split(/\s+/).filter(Boolean);
+      if (aliases.includes(hostAlias)) {
+        i++;
+        while (i < lines.length && !/^Host\s/i.test(lines[i])) {
+          i++;
+        }
+        continue;
+      }
+    }
+    out.push(line);
+    i++;
+  }
+  const block = [
+    `Host ${hostAlias}`,
+    `    HostName ${hostname}`,
+    `    User ${user}`,
+    '    IdentitiesOnly yes'
+  ].join('\n');
+  const trimmed = out.join('\n').replace(/\s+$/, '');
+  const prefix = trimmed.length ? `${trimmed}\n\n` : '';
+  return `${prefix}${block}\n`;
+}
+
+/**
+ * @param {string} sshUser
+ * @param {string} sshHost
+ * @returns {{ error: string }|{ user: string, host: string, hostAlias: string }}
+ */
+function parseEnsureSshInputs(sshUser, sshHost) {
+  if (!sshUser || typeof sshUser !== 'string' || !sshUser.trim()) {
+    return { error: 'missing ssh user' };
+  }
+  if (!sshHost || typeof sshHost !== 'string' || !sshHost.trim()) {
+    return { error: 'missing ssh host' };
+  }
+  const user = sshUser.trim();
+  const host = sshHost.trim();
+  return { user, host, hostAlias: getDevSshHostAlias(user, host) };
+}
+
+/**
+ * Ensure ~/.ssh/config contains a Host entry for interactive SSH / tooling.
+ * @param {string} sshUser - SSH user (sync-ssh-user)
+ * @param {string} sshHost - Real hostname (sync-ssh-host)
+ * @param {string} [sshDir] - SSH directory (default ~/.ssh)
+ * @returns {Promise<{ ok: boolean, configPath?: string, hostAlias?: string, error?: string, skippedDuplicate?: boolean }>}
+ */
+async function ensureDevSshConfigBlock(sshUser, sshHost, sshDir) {
+  const parsed = parseEnsureSshInputs(sshUser, sshHost);
+  if ('error' in parsed) {
+    return { ok: false, error: parsed.error };
+  }
+  const { user, host, hostAlias } = parsed;
+  const dir = ensureSshDir(sshDir);
+  const configPath = path.join(dir, 'config');
+  let existing = '';
+  try {
+    existing = await nodeFsLib.nodeFs().promises.readFile(configPath, 'utf8');
+  } catch (e) {
+    if (e.code !== 'ENOENT') {
+      return { ok: false, error: e.message || String(e) };
+    }
+  }
+  const matched = findMatchingHostBlockForUserHost(existing, host, user);
+  if (matched) {
+    return {
+      ok: true,
+      configPath,
+      hostAlias: resolveConnectAlias(matched, hostAlias),
+      skippedDuplicate: true
+    };
+  }
+  const next = upsertSshHostBlock(existing, hostAlias, host, user);
+  if (next === existing) {
+    return { ok: true, configPath, hostAlias };
+  }
+  await nodeFsLib.nodeFs().promises.writeFile(configPath, next, { mode: 0o600 });
+  return { ok: true, configPath, hostAlias };
+}
+
+module.exports = {
+  getDevSshHostAlias,
+  findMatchingHostBlockForUserHost,
+  resolveConnectAlias,
+  upsertSshHostBlock,
+  ensureDevSshConfigBlock
+};

package/lib/utils/dev-user-groups.js

@@ -0,0 +1,93 @@
+/**
+ * Allowed dev user groups for Builder Server user APIs (must match server DTOs).
+ * @fileoverview
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const ALLOWED_DEV_GROUPS = Object.freeze([
+  'admin',
+  'secret-manager',
+  'developer',
+  'docker'
+]);
+
+/**
+ * Parse --groups CLI value into normalized lowercase tokens.
+ * Uses commas and/or whitespace so PowerShell (which often turns `a,b,c` into
+ * separate argv tokens later joined as `a b c`) still works.
+ * @param {string|string[]} raw - e.g. "admin, developer,docker" or ["admin","developer"]
+ * @returns {string[]}
+ */
+function parseDevGroupsOption(raw) {
+  if (raw === null || raw === undefined) {
+    return [];
+  }
+  if (Array.isArray(raw)) {
+    return raw
+      .map(s => String(s).trim().toLowerCase())
+      .filter(Boolean);
+  }
+  if (typeof raw !== 'string') {
+    return [];
+  }
+  return raw
+    .split(/[\s,]+/)
+    .map(s => s.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+/**
+ * Ensure every group is allowed; throws with an actionable message if not.
+ * @param {string[]} groups - Normalized group names
+ * @throws {Error} When an unknown group is present
+ * @returns {string[]} Same array reference
+ */
+function validateDevGroups(groups) {
+  if (!Array.isArray(groups)) {
+    throw new Error('groups must be an array');
+  }
+  const invalid = groups.filter(g => !ALLOWED_DEV_GROUPS.includes(g));
+  if (invalid.length > 0) {
+    throw new Error(
+      `Invalid group(s): ${invalid.join(', ')}. Each value must be one of: ${ALLOWED_DEV_GROUPS.join(', ')}`
+    );
+  }
+  return groups;
+}
+
+/**
+ * When the Builder Server rejects `groups` with an enum message that omits `docker`,
+ * but the CLI sent `docker`, append a short hint (the server must be upgraded).
+ * Mutates err.message when applicable.
+ * @param {Error} err - API error
+ * @param {string[]|undefined} requestedGroups - groups sent in the request body
+ * @returns {Error}
+ */
+function augmentDevUserGroupsServerError(err, requestedGroups) {
+  if (!err || typeof err.message !== 'string') {
+    return err;
+  }
+  if (!Array.isArray(requestedGroups) || !requestedGroups.includes('docker')) {
+    return err;
+  }
+  const msg = err.message;
+  const looksLikeGroupEnum =
+    /each value in groups must be one of/i.test(msg) ||
+    (/groups/i.test(msg) && /must be one of the following values/i.test(msg));
+  if (!looksLikeGroupEnum) {
+    return err;
+  }
+  if (msg.toLowerCase().includes('docker')) {
+    return err;
+  }
+  err.message = `${msg} The Builder Server that handled this request does not accept the \`docker\` group yet; update that service (user DTO enum), or omit docker from --groups until it is deployed.`;
+  return err;
+}
+
+module.exports = {
+  ALLOWED_DEV_GROUPS,
+  parseDevGroupsOption,
+  validateDevGroups,
+  augmentDevUserGroupsServerError
+};

package/lib/utils/docker-build.js

@@ -1,3 +1,4 @@
+const { formatSuccessLine } = require('./cli-test-layout-chalk');
 /**
  * Docker Build Utilities
  *
@@ -11,6 +12,7 @@
 
 const { spawn } = require('child_process');
 const ora = require('ora');
+const { getDockerNotRunningErrorMessage } = require('./docker-not-running-hint');
 
 /**
  * Checks if error indicates Docker is not running or not installed
@@ -86,7 +88,7 @@ function handleDockerClose(code, ctx) {
     spinner.fail('Build failed');
     const errorMessage = stderrBuffer || stdoutBuffer || 'Docker build failed';
     if (isDockerNotAvailableError(errorMessage)) {
-      reject(new Error('Docker is not running or not installed. Please start Docker Desktop and try again.'));
+      reject(new Error(getDockerNotRunningErrorMessage()));
     } else {
       const errorLines = errorMessage.split('\n').filter(line => line.trim());
       reject(new Error(`Docker build failed: ${errorLines.slice(-5).join('\n')}`));
@@ -94,17 +96,35 @@ function handleDockerClose(code, ctx) {
   }
 }
 
-function runDockerBuildProcess(buildOpts) {
-  const { imageName, tag, dockerfilePath, contextPath, spinner, resolve, reject, env = {}, buildArgs = {} } = buildOpts;
-  const spawnEnv = { ...process.env, ...env };
+function buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildArgs, noCache) {
   const args = ['build', '-t', `${imageName}:${tag}`, '-f', dockerfilePath];
-  // Pass NPM_TOKEN/PYPI_TOKEN etc. so private registry auth works during RUN npm install / pip install
   for (const [key, value] of Object.entries(buildArgs)) {
     if (value !== null && value !== undefined && String(value).length > 0) {
       args.push('--build-arg', `${key}=${String(value)}`);
     }
   }
+  if (noCache) {
+    args.push('--no-cache');
+  }
   args.push(contextPath);
+  return args;
+}
+
+function runDockerBuildProcess(buildOpts) {
+  const {
+    imageName,
+    tag,
+    dockerfilePath,
+    contextPath,
+    spinner,
+    resolve,
+    reject,
+    env = {},
+    buildArgs = {},
+    noCache = false
+  } = buildOpts;
+  const spawnEnv = { ...process.env, ...env };
+  const args = buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildArgs, noCache);
   const dockerProcess = spawn('docker', args, {
     shell: process.platform === 'win32',
     env: spawnEnv
@@ -135,7 +155,7 @@ function runDockerBuildProcess(buildOpts) {
     spinner.fail('Build failed');
     const msg = error.message || String(error);
     if (isDockerNotAvailableError(msg)) {
-      reject(new Error('Docker is not running or not installed. Please start Docker Desktop and try again.'));
+      reject(new Error(getDockerNotRunningErrorMessage()));
     } else {
       reject(new Error(`Docker build failed: ${msg}`));
     }
@@ -149,10 +169,11 @@ function runDockerBuildProcess(buildOpts) {
  * @param {string} contextPath - Build context path
  * @param {string} tag - Image tag
  * @param {Object} [buildArgs={}] - Optional build args (e.g. NPM_TOKEN, PYPI_TOKEN) for private registries
+ * @param {boolean} [noCache=false] - When true, pass `docker build --no-cache` (full rebuild)
  * @returns {Promise<void>} Resolves when build completes
  * @throws {Error} If build fails
  */
-async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs = {}) {
+async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs = {}, noCache = false) {
   const spinner = ora({ text: 'Starting Docker build...', spinner: 'dots' }).start();
   const fsSync = require('fs');
   const path = require('path');
@@ -187,7 +208,8 @@ async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, b
       resolve,
       reject,
       env: remoteEnv,
-      buildArgs: resolvedBuildArgs
+      buildArgs: resolvedBuildArgs,
+      noCache
     });
   });
 }
@@ -205,16 +227,20 @@ async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, b
  */
 async function executeBuild(imageName, dockerfilePath, contextPath, tag, options) {
   const buildArgs = (options && options.buildArgs) || {};
-  await executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs);
+  // Commander maps `--no-cache` to `cache: false` (boolean negation), not `noCache: true`.
+  const noCache = Boolean(
+    options &&
+      (options.cache === false || options.noCache === true || options['no-cache'] === true)
+  );
+  await executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs, noCache);
 
   // Tag image if additional tag provided
   if (options && options.tag && options.tag !== 'latest') {
     const { promisify } = require('util');
     const { exec } = require('child_process');
     const run = promisify(exec);
-    const { getRemoteDockerEnv } = require('./remote-docker-env');
-    const remoteEnv = await getRemoteDockerEnv();
-    const env = { ...process.env, ...remoteEnv };
+    const { getDockerExecEnv } = require('./remote-docker-env');
+    const env = await getDockerExecEnv();
     await run(`docker tag ${imageName}:${tag} ${imageName}:latest`, { env });
   }
 }
@@ -244,13 +270,12 @@ async function executeDockerBuildWithTag(effectiveImageName, imageName, dockerfi
     const { promisify } = require('util');
     const { exec } = require('child_process');
     const run = promisify(exec);
-    const { getRemoteDockerEnv } = require('./remote-docker-env');
-    const remoteEnv = await getRemoteDockerEnv();
-    const env = { ...process.env, ...remoteEnv };
+    const { getDockerExecEnv } = require('./remote-docker-env');
+    const env = await getDockerExecEnv();
     await run(`docker tag ${effectiveImageName}:${tag} ${imageName}:${tag}`, { env });
-    logger.log(chalk.green(`✓ Tagged image: ${imageName}:${tag}`));
+    logger.log(formatSuccessLine(`Tagged image: ${imageName}:${tag}`));
   } catch (err) {
-    logger.log(chalk.yellow(`⚠️  Warning: Could not create compatibility tag ${imageName}:${tag} - ${err.message}`));
+    logger.log(chalk.yellow(`⚠  Warning: Could not create compatibility tag ${imageName}:${tag} - ${err.message}`));
   }
 }
 

package/lib/utils/docker-exec.js

@@ -0,0 +1,28 @@
+/**
+ * Docker CLI exec with dev-config remote Docker (docker-endpoint + TLS) applied.
+ *
+ * @fileoverview Wraps child_process.exec with getDockerExecEnv for consistent remote daemon use
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { promisify } = require('util');
+const { exec } = require('child_process');
+
+const execAsync = promisify(exec);
+
+/**
+ * Run a shell command with process.env merged with remote Docker client settings when docker-endpoint is set.
+ * @param {string} command
+ * @param {import('child_process').ExecOptions} [options]
+ * @returns {Promise<{ stdout: string, stderr: string }>}
+ */
+async function execWithDockerEnv(command, options = {}) {
+  const { getDockerExecEnv } = require('./remote-docker-env');
+  const env = { ...(await getDockerExecEnv()), ...(options.env || {}) };
+  return execAsync(command, { ...options, env });
+}
+
+module.exports = { execWithDockerEnv };

package/lib/utils/docker-manifest-public-port.js

@@ -0,0 +1,116 @@
+/**
+ * Docker .env generation: manifest `port` is the host-published port; env-config `*_PORT` is
+ * often internal. After resolveKvReferences, ${*_PUBLIC_PORT} may already be interpolated from
+ * schema before manifest port is applied — align *_PUBLIC_PORT with application.yaml `port`.
+ *
+ * Matching rule (no app-specific keys in callers): find env-config `*_HOST` whose value equals
+ * `application.yaml` `app.key` (Docker Compose service name), then update the paired *_PUBLIC_PORT.
+ *
+ * @fileoverview Manifest published port for docker env interpolation
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {string} s
+ * @returns {string}
+ */
+function escapeRegExp(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * @param {Object} envVars
+ * @param {string} appKey - application.yaml app.key (trimmed)
+ * @returns {string|null} e.g. KEYCLOAK_HOST
+ */
+function findDockerHostKeyForAppKey(envVars, appKey) {
+  if (!envVars || !appKey) {
+    return null;
+  }
+  for (const [k, v] of Object.entries(envVars)) {
+    if (!/_HOST$/.test(k)) {
+      continue;
+    }
+    if (String(v) === appKey) {
+      return k;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {Object} envVars
+ * @param {string} appKey
+ * @returns {string|null} e.g. KEYCLOAK_PUBLIC_PORT
+ */
+function publicPortKeyForAppKey(envVars, appKey) {
+  const hostKey = findDockerHostKeyForAppKey(envVars, appKey);
+  if (!hostKey) {
+    return null;
+  }
+  return hostKey.replace(/_HOST$/, '_PUBLIC_PORT');
+}
+
+/**
+ * Set *_PUBLIC_PORT from manifest `port` + developer id when docker service name matches app.key.
+ * @param {Object} envVars - Mutated map from buildEnvVarMap
+ * @param {Object|null|undefined} appDoc - application.yaml root
+ * @returns {Promise<void>}
+ */
+async function mergeDockerManifestPublishedPort(envVars, appDoc) {
+  if (!appDoc || !appDoc.app || typeof appDoc.app.key !== 'string') {
+    return;
+  }
+  const appKey = appDoc.app.key.trim();
+  if (!appKey) {
+    return;
+  }
+  const publicPortKey = publicPortKeyForAppKey(envVars, appKey);
+  if (!publicPortKey) {
+    return;
+  }
+  const rawPub = appDoc.port;
+  const pubBase = rawPub !== undefined && rawPub !== null ? Number(rawPub) : NaN;
+  if (!Number.isFinite(pubBase)) {
+    return;
+  }
+  const devIdNum = await require('./env-map').getDeveloperIdNumber(null);
+  envVars[publicPortKey] = String(devIdNum > 0 ? pubBase + devIdNum * 100 : pubBase);
+}
+
+/**
+ * Rewrite first line for the matched *_PUBLIC_PORT after interpolateEnvVars (early kv pass may have wrong value).
+ * @param {string} resolved
+ * @param {Object} envVars
+ * @param {Object|null|undefined} appDoc
+ * @returns {string}
+ */
+function rewriteDockerManifestPublicPortEnvLine(resolved, envVars, appDoc) {
+  if (!resolved || !appDoc || !appDoc.app || typeof appDoc.app.key !== 'string') {
+    return resolved;
+  }
+  const appKey = appDoc.app.key.trim();
+  if (!appKey) {
+    return resolved;
+  }
+  const publicPortKey = publicPortKeyForAppKey(envVars, appKey);
+  if (!publicPortKey) {
+    return resolved;
+  }
+  const publicPort = envVars[publicPortKey];
+  if (publicPort === undefined || publicPort === null || publicPort === '') {
+    return resolved;
+  }
+  const re = new RegExp(`^${escapeRegExp(publicPortKey)}\\s*=\\s*.*$`, 'm');
+  return resolved.replace(re, `${publicPortKey}=${publicPort}`);
+}
+
+module.exports = {
+  findDockerHostKeyForAppKey,
+  publicPortKeyForAppKey,
+  mergeDockerManifestPublishedPort,
+  rewriteDockerManifestPublicPortEnvLine
+};

package/lib/utils/docker-not-running-hint.js

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Platform-specific hints when the Docker CLI cannot reach the daemon.
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+/**
+ * Short sentence: how to get a working Docker daemon for this OS (no trailing period in fragment use).
+ * @returns {string}
+ */
+function getDockerDaemonStartHintSentence() {
+  if (process.platform === 'linux') {
+    return (
+      'Start the Docker daemon (e.g. sudo systemctl start docker), install Docker Engine if needed, ' +
+      'and ensure your user can use the socket (e.g. sudo usermod -aG docker $USER, then log out and back in). ' +
+      'On Windows or macOS, start Docker Desktop.'
+    );
+  }
+  if (process.platform === 'darwin') {
+    return 'Start Docker Desktop (or Colima / another runtime) and try again.';
+  }
+  return 'Start Docker Desktop and try again.';
+}
+
+/**
+ * Single-line error for thrown Error.message (build spawn failures, etc.).
+ * @returns {string}
+ */
+function getDockerNotRunningErrorMessage() {
+  return `Docker is not running or not installed. ${getDockerDaemonStartHintSentence()}`;
+}
+
+/**
+ * When the user cannot use the local unix socket (no docker group) but Docker runs on the same or another host
+ * exposing the Engine API — the CLI talks to that API via DOCKER_HOST (docker-endpoint in ~/.aifabrix/config.yaml).
+ * @returns {string[]}
+ */
+function getDockerApiOverTcpHintLines() {
+  return [
+    '   Without unix socket access: set docker-endpoint to the Docker Engine API (e.g. tcp://builder02.local:2376). Builder settings often merge this after aifabrix dev init or dev refresh.',
+    '   The CLI still runs docker/docker compose locally as a thin client to that API (not the Builder HTTP API). TLS: cert.pem, key.pem, ca.pem in ~/.aifabrix/certs/<developer-id>/ (match daemon client-auth).',
+    '   Run: aifabrix dev show'
+  ];
+}
+
+module.exports = {
+  getDockerDaemonStartHintSentence,
+  getDockerNotRunningErrorMessage,
+  getDockerApiOverTcpHintLines
+};