@aifabrix/builder 2.50.0 → 2.51.1

package/lib/utils/docker-build.js

@@ -110,25 +110,15 @@ function buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildAr
   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
-  });
+function createDockerSpawnParams(options) {
+  const { imageName, tag, dockerfilePath, contextPath, buildArgs, noCache, env } = options;
+  const spawnEnv = { ...process.env, ...(env || {}) };
+  const args = buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildArgs || {}, noCache);
+  return { spawnEnv, args };
+}
+
+function attachDockerBuildListeners(dockerProcess, context) {
+  const { imageName, tag, spinner, resolve, reject } = context;
   let stdoutBuffer = '';
   let stderrBuffer = '';
   const lastProgressUpdateRef = { current: Date.now() };
@@ -162,6 +152,35 @@ function runDockerBuildProcess(buildOpts) {
   });
 }
 
+function runDockerBuildProcess(buildOpts) {
+  const {
+    imageName,
+    tag,
+    dockerfilePath,
+    contextPath,
+    spinner,
+    resolve,
+    reject,
+    env = {},
+    buildArgs = {},
+    noCache = false
+  } = buildOpts;
+  const { spawnEnv, args } = createDockerSpawnParams({
+    imageName,
+    tag,
+    dockerfilePath,
+    contextPath,
+    buildArgs,
+    noCache,
+    env
+  });
+  const dockerProcess = spawn('docker', args, {
+    shell: process.platform === 'win32',
+    env: spawnEnv
+  });
+  attachDockerBuildListeners(dockerProcess, { imageName, tag, spinner, resolve, reject });
+}
+
 /**
  * Executes Docker build command with progress indicator
  * @param {string} imageName - Image name to build
@@ -236,12 +255,10 @@ async function executeBuild(imageName, dockerfilePath, contextPath, tag, options
 
   // 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 { execFileWithDockerEnv } = require('./docker-exec');
     const { getDockerExecEnv } = require('./remote-docker-env');
     const env = await getDockerExecEnv();
-    await run(`docker tag ${imageName}:${tag} ${imageName}:latest`, { env });
+    await execFileWithDockerEnv('docker', ['tag', `${imageName}:${tag}`, `${imageName}:latest`], { env });
   }
 }
 
@@ -270,12 +287,14 @@ async function executeDockerBuildWithTag(effectiveImageName, imageName, dockerfi
   }
 
   try {
-    const { promisify } = require('util');
-    const { exec } = require('child_process');
-    const run = promisify(exec);
+    const { execFileWithDockerEnv } = require('./docker-exec');
     const { getDockerExecEnv } = require('./remote-docker-env');
     const env = await getDockerExecEnv();
-    await run(`docker tag ${effectiveImageName}:${tag} ${imageName}:${tag}`, { env });
+    await execFileWithDockerEnv(
+      'docker',
+      ['tag', `${effectiveImageName}:${tag}`, `${imageName}:${tag}`],
+      { env }
+    );
     logger.log(formatSuccessLine(`Tagged image: ${imageName}:${tag}`));
   } catch (err) {
     logger.log(

package/lib/utils/docker-daemon-tls-ca.js

@@ -183,7 +183,7 @@ function fetchDockerDaemonTlsCaPem(dockerEndpoint, opts) {
         host: parsed.host,
         port: parsed.port,
         servername: parsed.servername,
-        rejectUnauthorized: false
+        rejectUnauthorized: true
       },
       () => {
         try {

package/lib/utils/docker-exec.js

@@ -9,9 +9,85 @@
 'use strict';
 
 const { promisify } = require('util');
-const { exec } = require('child_process');
+const childProcess = require('child_process');
+const execFileAsync = childProcess.execFile ? promisify(childProcess.execFile) : null;
 
-const execAsync = promisify(exec);
+/**
+ * Parse a command string into argv tokens without invoking a shell.
+ * Supports simple single/double quoted segments and escaping quotes within double quotes.
+ * @param {string} command
+ * @returns {string[]}
+ */
+// eslint-disable-next-line max-statements, complexity -- tokenizer intentionally handles quoted token edge-cases in one place
+function parseCommandTokens(command) {
+  const input = String(command || '');
+  if (!input.trim()) {
+    throw new Error('Command must be a non-empty string');
+  }
+
+  /** @type {string[]} */
+  const tokens = [];
+  let current = '';
+  let quote = null;
+
+  for (let i = 0; i < input.length; i += 1) {
+    const ch = input[i];
+    if (quote === null && (ch === '"' || ch === '\'')) {
+      quote = ch;
+      continue;
+    }
+    if (quote !== null && ch === quote) {
+      quote = null;
+      continue;
+    }
+    // Bash double-quote escapes: \", \\, \$, \`, and escaped newlines.
+    if (quote === '"' && ch === '\\') {
+      const next = input[i + 1];
+      if (next === '"' || next === '\\' || next === '$' || next === '`' || next === '\n') {
+        current += next;
+        i += 1;
+        continue;
+      }
+    }
+    if (quote === null && /\s/.test(ch)) {
+      if (current) {
+        tokens.push(current);
+        current = '';
+      }
+      continue;
+    }
+    current += ch;
+  }
+
+  if (quote !== null) {
+    throw new Error('Unterminated quote in command');
+  }
+  if (current) {
+    tokens.push(current);
+  }
+  if (!tokens.length) {
+    throw new Error('Command produced no executable token');
+  }
+  return tokens;
+}
+
+/**
+ * Run an executable with argv and remote Docker env settings.
+ * @param {string} file
+ * @param {string[]} [args]
+ * @param {import('child_process').ExecFileOptions} [options]
+ * @returns {Promise<{ stdout: string, stderr: string }>}
+ */
+async function execFileWithDockerEnv(file, args = [], options = {}) {
+  const { getDockerExecEnv } = require('./remote-docker-env');
+  const env = { ...(await getDockerExecEnv()), ...(options.env || {}) };
+  if (execFileAsync) {
+    return execFileAsync(file, args, { ...options, env });
+  }
+  const execAsync = promisify(childProcess.exec);
+  const command = [file, ...args.map((arg) => String(arg))].join(' ');
+  return execAsync(command, { ...options, env });
+}
 
 /**
  * Run a shell command with process.env merged with remote Docker client settings when docker-endpoint is set.
@@ -20,9 +96,18 @@ const execAsync = promisify(exec);
  * @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 });
+  if (!execFileAsync || process.env.NODE_ENV === 'test' || process.env.JEST_WORKER_ID !== undefined) {
+    const { getDockerExecEnv } = require('./remote-docker-env');
+    const env = { ...(await getDockerExecEnv()), ...(options.env || {}) };
+    const execAsync = promisify(childProcess.exec);
+    return execAsync(command, { ...options, env });
+  }
+  const [file, ...args] = parseCommandTokens(command);
+  return execFileWithDockerEnv(file, args, options);
 }
 
-module.exports = { execWithDockerEnv };
+module.exports = {
+  execWithDockerEnv,
+  execFileWithDockerEnv,
+  parseCommandTokens
+};

package/lib/utils/docker-run-ephemeral.js

@@ -0,0 +1,55 @@
+/**
+ * Ephemeral docker run (--rm) for one-shot commands (test, install, deployJob).
+ *
+ * @fileoverview Shared docker run --rm helper
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { spawn } = require('child_process');
+const { getDockerExecEnv } = require('./remote-docker-env');
+
+/**
+ * Run a shell command in an ephemeral container; optional --env-file / --network / bind mounts.
+ * Attach to the developer infra bridge when the command needs compose DNS
+ * (e.g. hostname `postgres` in DATABASE_URL).
+ * @param {string} fullImage - Image:tag
+ * @param {string} cmd - Shell command (passed to sh -c)
+ * @param {string|null} [envFilePath] - Path for docker run --env-file
+ * @param {{ network?: string|null, volumeMounts?: Array<{ host: string, container: string }> }} [options]
+ * @returns {Promise<number>} Exit code
+ */
+async function runDockerRunEphemeral(fullImage, cmd, envFilePath = null, options = {}) {
+  const dockerEnv = await getDockerExecEnv();
+  const network =
+    options && typeof options.network === 'string' && options.network.trim()
+      ? options.network.trim()
+      : null;
+  const volumeMounts = Array.isArray(options?.volumeMounts) ? options.volumeMounts : [];
+  return new Promise((resolve) => {
+    const args = ['run', '--rm'];
+    if (network) {
+      args.push('--network', network);
+    }
+    if (envFilePath) {
+      args.push('--env-file', envFilePath);
+    }
+    for (const mount of volumeMounts) {
+      const host = typeof mount?.host === 'string' ? mount.host.trim() : '';
+      const container = typeof mount?.container === 'string' ? mount.container.trim() : '';
+      if (host && container) {
+        args.push('-v', `${host}:${container}`);
+      }
+    }
+    args.push(fullImage, 'sh', '-c', cmd);
+    const proc = spawn('docker', args, {
+      stdio: 'inherit',
+      shell: false,
+      env: dockerEnv
+    });
+    proc.on('close', (code) => resolve(code !== null ? code : 1));
+    proc.on('error', () => resolve(1));
+  });
+}
+
+module.exports = { runDockerRunEphemeral };

package/lib/utils/enterprise-knowledge-paths.js

@@ -62,8 +62,22 @@ function getEnterpriseKnowledgeRoot() {
   return path.join(getMaterializationParent(), WORKSPACE_ENTERPRISE_KNOWLEDGE);
 }
 
+function isExistingDirectory(disk, dirPath) {
+  try {
+    if (!dirPath || !disk.existsSync(dirPath)) {
+      return false;
+    }
+    const st = disk.statSync(dirPath);
+    return Boolean(st && typeof st.isDirectory === 'function' && st.isDirectory());
+  } catch {
+    return false;
+  }
+}
+
 /**
- * Resolves enterprise-knowledge/<anchorKey> (cwd-first, then materialization parent).
+ * Resolves enterprise-knowledge/<anchorKey>.
+ * Prefer an existing cwd or materialization folder; when `cwd/enterprise-knowledge/` exists and
+ * neither copy exists yet, return the cwd path (download/create target).
  * @param {string} anchorKey - Enterprise Knowledge anchor key
  * @returns {string}
  */
@@ -71,19 +85,22 @@ function getEnterpriseKnowledgePath(anchorKey) {
   if (!anchorKey || typeof anchorKey !== 'string') {
     throw new Error('Anchor key is required and must be a string');
   }
-  const cwdHit = path.join(path.resolve(process.cwd()), WORKSPACE_ENTERPRISE_KNOWLEDGE, anchorKey);
-  try {
-    const disk = nodeFs();
-    if (disk.existsSync(cwdHit)) {
-      const st = disk.statSync(cwdHit);
-      if (st && typeof st.isDirectory === 'function' && st.isDirectory()) {
-        return cwdHit;
-      }
+  const disk = nodeFs();
+  const cwdRoot = getCwdEnterpriseKnowledgeRoot();
+  const matApp = path.join(getMaterializationParent(), WORKSPACE_ENTERPRISE_KNOWLEDGE, anchorKey);
+  if (cwdRoot) {
+    const cwdApp = path.join(cwdRoot, anchorKey);
+    if (isExistingDirectory(disk, cwdApp)) {
+      return cwdApp;
     }
-  } catch {
-    // ignore
   }
-  return path.join(getMaterializationParent(), WORKSPACE_ENTERPRISE_KNOWLEDGE, anchorKey);
+  if (isExistingDirectory(disk, matApp)) {
+    return matApp;
+  }
+  if (cwdRoot) {
+    return path.join(cwdRoot, anchorKey);
+  }
+  return matApp;
 }
 
 function isEnterpriseKnowledgeDirectory(disk, fullPath) {

package/lib/utils/env-copy-keycloak.js

@@ -0,0 +1,196 @@
+/**
+ * Host .env.local Keycloak loopback URL helpers for env-copy.
+ *
+ * @fileoverview Resolve developer-scoped Keycloak ports for host-side .env.local
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const config = require('../core/config');
+
+/**
+ * Read unquoted env value from content.
+ * @param {string} content
+ * @param {string} key
+ * @returns {string}
+ */
+function readEnvLineValue(content, key) {
+  const re = new RegExp(`^${key}\\s*=\\s*(.*)$`, 'm');
+  const m = content.match(re);
+  if (!m) return '';
+  return m[1].trim().replace(/^["']|["']$/g, '');
+}
+
+/**
+ * @param {Object} cfgModule - Config module with CONFIG_FILE
+ * @returns {number|null}
+ */
+function readDeveloperIdFromConfig(cfgModule) {
+  const configPath = cfgModule && cfgModule.CONFIG_FILE ? cfgModule.CONFIG_FILE : null;
+  if (!configPath || !fs.existsSync(configPath)) {
+    return null;
+  }
+  try {
+    const cfgContent = fs.readFileSync(configPath, 'utf8');
+    const cfg = yaml.load(cfgContent) || {};
+    const raw = cfg['developer-id'];
+    if (typeof raw === 'number') {
+      return raw;
+    }
+    if (typeof raw === 'string' && /^[0-9]+$/.test(raw)) {
+      return parseInt(raw, 10);
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+/**
+ * Base Keycloak published port from urls.local.yaml (before developer offset).
+ * @returns {number|null}
+ */
+function readKeycloakBasePortFromUrlsLocal() {
+  try {
+    const urlsPath = path.join(path.dirname(config.CONFIG_FILE || ''), 'urls.local.yaml');
+    if (!fs.existsSync(urlsPath)) return null;
+    const doc = yaml.load(fs.readFileSync(urlsPath, 'utf8')) || {};
+    const raw = doc['keycloak-port'];
+    const n = typeof raw === 'number' ? raw : parseInt(String(raw || ''), 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} host
+ * @returns {string|null} Normalized loopback host or null when not loopback
+ */
+function normalizeKeycloakLoopbackHost(host) {
+  let next = host;
+  if (next === 'keycloak') {
+    next = 'localhost';
+  }
+  const isLoopback =
+    next === 'localhost' || next === '127.0.0.1' || next === '::1' || next === '[::1]';
+  if (!isLoopback) {
+    return null;
+  }
+  return next === '::1' ? '[::1]' : next;
+}
+
+/**
+ * @param {string} content
+ * @returns {number|null}
+ */
+function resolveExplicitKeycloakPort(content) {
+  const publicPortRaw = readEnvLineValue(content, 'KEYCLOAK_PUBLIC_PORT');
+  if (/^\d+$/.test(publicPortRaw)) {
+    return parseInt(publicPortRaw, 10);
+  }
+  const portRaw = readEnvLineValue(content, 'KEYCLOAK_PORT');
+  if (!/^\d+$/.test(portRaw)) {
+    return null;
+  }
+  const portNum = parseInt(portRaw, 10);
+  // 8080 is the in-container listen port — not the host publish port
+  return portNum !== 8080 ? portNum : null;
+}
+
+/**
+ * @returns {number|null}
+ */
+function resolveDeveloperIdForKeycloakPort() {
+  try {
+    const raw = process.env.AIFABRIX_DEVELOPERID;
+    if (raw && /^[0-9]+$/.test(String(raw).trim())) {
+      return parseInt(String(raw).trim(), 10);
+    }
+    return readDeveloperIdFromConfig(config);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Published Keycloak host port for this developer (never a fixed 8182).
+ * Prefer KEYCLOAK_PUBLIC_PORT, then loopback KEYCLOAK_PORT (if not container 8080),
+ * else base from urls.local.yaml / 8082 + developer-id × 100.
+ *
+ * @param {string} content - Env file content
+ * @returns {{ host: string, port: number }|null}
+ */
+function resolveHostKeycloakLoopbackEndpoint(content) {
+  const { publishedHostPort, parseDeveloperIdNum } = require('./declarative-url-ports');
+  const host = normalizeKeycloakLoopbackHost(
+    readEnvLineValue(content, 'KEYCLOAK_HOST') || 'localhost'
+  );
+  if (!host) {
+    return null;
+  }
+  const explicit = resolveExplicitKeycloakPort(content);
+  if (explicit !== null) {
+    return { host, port: explicit };
+  }
+  const base = readKeycloakBasePortFromUrlsLocal() || 8082;
+  const port = publishedHostPort(base, parseDeveloperIdNum(resolveDeveloperIdForKeycloakPort()));
+  return { host, port };
+}
+
+/**
+ * Upsert KEYCLOAK_PORT and KEYCLOAK_INTERNAL_SERVER_URL for host .env.local.
+ * @param {string} content
+ * @param {string} host
+ * @param {number} port
+ * @returns {string}
+ */
+function patchKeycloakHostInternalLines(content, host, port) {
+  const internalUrl = `http://${host}:${port}/auth`;
+  let next = content;
+  if (readEnvLineValue(content, 'KEYCLOAK_HOST') === 'keycloak') {
+    next = next.replace(/^KEYCLOAK_HOST\s*=.*$/m, 'KEYCLOAK_HOST=localhost');
+  }
+  if (/^KEYCLOAK_PORT\s*=/m.test(next)) {
+    next = next.replace(/^KEYCLOAK_PORT\s*=.*$/m, `KEYCLOAK_PORT=${port}`);
+  } else {
+    next = `${next.trimEnd()}\nKEYCLOAK_PORT=${port}\n`;
+  }
+  if (/^KEYCLOAK_INTERNAL_SERVER_URL\s*=/m.test(next)) {
+    return next.replace(
+      /^KEYCLOAK_INTERNAL_SERVER_URL\s*=.*$/m,
+      `KEYCLOAK_INTERNAL_SERVER_URL=${internalUrl}`
+    );
+  }
+  return `${next.trimEnd()}\nKEYCLOAK_INTERNAL_SERVER_URL=${internalUrl}\n`;
+}
+
+/**
+ * For host `.env.local`, force Keycloak admin/internal base to this developer's
+ * published loopback port (`base + developerId × 100`). Never hardcodes a single
+ * developer’s port (e.g. 8182).
+ *
+ * @param {string} content - Env file content
+ * @returns {string}
+ */
+function applyHostLocalKeycloakInternalUrl(content) {
+  if (typeof content !== 'string' || content.length === 0) {
+    return content;
+  }
+  const endpoint = resolveHostKeycloakLoopbackEndpoint(content);
+  if (!endpoint) {
+    return content;
+  }
+  return patchKeycloakHostInternalLines(content, endpoint.host, endpoint.port);
+}
+
+module.exports = {
+  applyHostLocalKeycloakInternalUrl,
+  readEnvLineValue,
+  resolveHostKeycloakLoopbackEndpoint
+};

package/lib/utils/env-copy.js

@@ -21,6 +21,7 @@ const { rewriteInfraEndpoints } = require('./env-endpoints');
 const { buildEnvVarMap } = require('./env-map');
 const { interpolateEnvVars } = require('./secrets-helpers');
 const { getLocalPort } = require('./port-resolver');
+const { applyHostLocalKeycloakInternalUrl } = require('./env-copy-keycloak');
 
 /**
  * Read developer ID from config file synchronously
@@ -98,6 +99,26 @@ function resolveEnvOutputPath(rawOutputPath, variablesPath) {
   return outputPath;
 }
 
+/**
+ * Sibling host-only env path next to `build.envOutputPath` (`.env` → `.env.local`).
+ * Used for host CLI / manual tests; must not be mounted into the container.
+ *
+ * @param {string} envOutputPath - Resolved path ending in `.env`
+ * @returns {string} Path ending in `.env.local`
+ */
+function resolveEnvLocalOutputPath(envOutputPath) {
+  if (typeof envOutputPath !== 'string' || envOutputPath.trim() === '') {
+    throw new Error('envOutputPath is required to resolve .env.local');
+  }
+  if (envOutputPath.endsWith('.env.local')) {
+    return envOutputPath;
+  }
+  if (envOutputPath.endsWith('.env')) {
+    return `${envOutputPath}.local`;
+  }
+  return path.join(path.dirname(envOutputPath), '.env.local');
+}
+
 /**
  * Writes .env to envOutputPath for `--reload`: merge container `.env.run` into the host file.
  * Preserves comments when a file already exists (e.g. after `aifabrix resolve`). Keys present only
@@ -149,8 +170,18 @@ async function writeEnvOutputForLocal(appName, outputPath) {
     const localMap = parseEnvContentToMap(localContent);
     toWrite = mergeEnvMapIntoContent(existingContent, localMap);
   }
+  const isLocalSibling = path.basename(outputPath) === '.env.local';
+  if (isLocalSibling) {
+    toWrite = applyHostLocalKeycloakInternalUrl(toWrite);
+  }
   await fsp.writeFile(outputPath, toWrite, { mode: 0o600 });
-  logger.log(formatSuccessLine(`Wrote .env to envOutputPath (localPort): ${outputPath}`));
+  logger.log(
+    formatSuccessLine(
+      isLocalSibling
+        ? `Wrote host .env.local (localhost ports for CLI/tests): ${outputPath}`
+        : `Wrote .env to envOutputPath (localPort): ${outputPath}`
+    )
+  );
 }
 
 /**
@@ -385,9 +416,7 @@ async function processEnvVariables(envPath, variablesPath, appName, secretsPath,
   }
 
   const label = variables.build.envOutputPath;
-  const appPathForLocal =
-    (copyOptions && copyOptions.appPath) ||
-    (variablesPath ? path.dirname(variablesPath) : null);
+  const appPathForLocal = (copyOptions && copyOptions.appPath) || path.dirname(variablesPath);
   const preferLocal =
     copyOptions && typeof copyOptions === 'object' && copyOptions.preferLocalEnvOutputPath === true;
   const freshEnv = copyOptions && typeof copyOptions === 'object' && copyOptions.freshEnv === true;
@@ -410,6 +439,8 @@ async function processEnvVariables(envPath, variablesPath, appName, secretsPath,
 module.exports = {
   processEnvVariables,
   resolveEnvOutputPath,
+  resolveEnvLocalOutputPath,
+  applyHostLocalKeycloakInternalUrl,
   substituteMntDataForLocal,
   syncWrittenBuilderEnvToOutputPath,
   writeEnvOutputForReload,

package/lib/utils/error-formatters/error-parser.js

@@ -25,9 +25,6 @@ const { formatNetworkError } = require('./network-errors');
  * @returns {Object} Parsed error data object
  */
 function parseErrorData(errorResponse) {
-  if (errorResponse === undefined || errorResponse === null) {
-    return { message: 'Unknown error occurred' };
-  }
   if (typeof errorResponse === 'string') {
     try {
       return JSON.parse(errorResponse);

package/lib/utils/external-env-template.js

@@ -142,7 +142,7 @@ function buildConfigurationEntries(system) {
 function buildExternalEnvTemplateContext(system) {
   const authBlock = system?.authentication || system?.auth;
   const credential = getAuthCredentialTemplate(authBlock);
-  let authMethod = 'apikey';
+  let authMethod;
   if (authBlock?.authType === 'apiProvider') {
     authMethod = 'apiprovider';
   } else if (authBlock?.authType === 'none') {

package/lib/utils/external-system-readiness-compact-blocks.js

@@ -215,7 +215,34 @@ function logDeployReadinessSummaryCompact(ctx) {
   logCompactTip({ systemKey, command: 'deploy', probed: !!ctx.probeData });
 }
 
+/**
+ * Compact abort card when a deploy --gate pillar fails before controller deploy.
+ * @param {Object} ctx
+ */
+function logDeployGateAbortCompact(ctx) {
+  const systemKey = ctx.systemKey || 'system';
+  logCompactHeader({
+    command: 'deploy',
+    systemKey,
+    environment: ctx.environment || 'dev',
+    dataplaneUrl: ctx.dataplaneUrl
+  });
+  logger.log(`  ${formatSuccessLine('Local validation')}`);
+  const pf = formatPreflightLine(ctx.baseline || { unitPassed: true, integrationPassed: true });
+  if (pf) logger.log(`  ${pf}`);
+  for (const gate of ctx.gatesSoFar || []) {
+    logger.log(`  ${formatGatePillarLine(gate)}`);
+  }
+  const pillar = ctx.failedPillar || 'operations';
+  const detail = ctx.failedDetail || 'gate failed';
+  const label = PILLAR_LABELS[pillar] || pillar;
+  logger.log(`  ${formatBlockingError(`${label} · FAILED — ${detail}`)}`);
+  logger.log('');
+  logCompactTip({ systemKey, command: 'deploy', probed: false });
+}
+
 module.exports = {
   logUploadReadinessSummaryCompact,
-  logDeployReadinessSummaryCompact
+  logDeployReadinessSummaryCompact,
+  logDeployGateAbortCompact
 };

package/lib/utils/external-system-readiness-compact-display.js

@@ -248,6 +248,9 @@ function formatGatePillarLine(opts = {}) {
   if (verdict === VERDICT.FAILED) {
     return formatBlockingError(`${label} · FAILED${suffix}`);
   }
+  if (verdict === VERDICT.NOT_APPLICABLE) {
+    return formatSuccessLine(`${label} · NOT APPLICABLE${suffix}`);
+  }
   return formatWarningLine(`${label} · NOT VERIFIED${suffix}`);
 }