@aifabrix/builder 2.42.1 → 2.44.0

package/lib/utils/compose-traefik-ingress-base.js

@@ -0,0 +1,158 @@
+/**
+ * Traefik ingress path/host/TLS and StripPrefix derivation helpers for compose generation.
+ *
+ * @fileoverview Traefik PathPrefix + host expansion (shared with health path resolution)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const {
+  buildEnvScopedTraefikPath
+} = require('./environment-scoped-resources');
+const { parseDeveloperIdNum } = require('./declarative-url-ports');
+
+/**
+ * Derives base path from routing pattern by removing trailing wildcards
+ * @param {string} pattern - URL pattern (e.g., '/app/*', '/api/v1/*')
+ * @returns {string} Base path for routing
+ */
+function derivePathFromPattern(pattern) {
+  if (!pattern || typeof pattern !== 'string') {
+    return '/';
+  }
+  const trimmed = pattern.trim();
+  if (trimmed === '/' || trimmed === '') {
+    return '/';
+  }
+  const withoutWildcards = trimmed.replace(/\*+$/g, '');
+  const withoutTrailingSlashes = withoutWildcards.replace(/\/+$/g, '');
+  return withoutTrailingSlashes || '/';
+}
+
+/**
+ * Resolve Traefik TLS from application.yaml `frontDoorRouting.tls` (boolean or string).
+ * String "false" disables TLS; placeholders (e.g. ${TLS_ENABLED}) are treated as enabled.
+ * @param {unknown} tls - Raw tls value
+ * @returns {boolean}
+ */
+function resolveTraefikTlsEnabled(tls) {
+  if (tls === false || tls === 'false') {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Developer label for frontDoorRouting.host only. Id 0 / missing / empty → no subdomain (empty string).
+ * Non-zero → dev01, dev02, … (same padding as buildDevUsername).
+ *
+ * @param {string|number|null|undefined} devId
+ * @returns {string}
+ */
+function buildDevUsernameForFrontDoorHost(devId) {
+  const n = parseDeveloperIdNum(devId);
+  if (n === 0) {
+    return '';
+  }
+  const s = String(n);
+  const padded = s.length === 1 ? s.padStart(2, '0') : s;
+  return `dev${padded}`;
+}
+
+/**
+ * Expand frontDoorRouting.host placeholders (Traefik labels + url:// base). Same rules as declarative URL resolver.
+ * Normalizes ${DEV_USERNAME}${REMOTE_HOST} to insert a dot. Trims stray leading/trailing dots (e.g. id 0 + `.${REMOTE_HOST}` → bare remote hostname).
+ *
+ * @param {string} template
+ * @param {string|number|null|undefined} developerIdRaw
+ * @param {string|null|undefined} remoteServer
+ * @returns {string}
+ */
+function expandFrontDoorHostPlaceholders(template, developerIdRaw, remoteServer) {
+  let t = String(template || '');
+  t = t.replace(/\$\{DEV_USERNAME\}\$\{REMOTE_HOST\}/g, '${DEV_USERNAME}.${REMOTE_HOST}');
+  const devU = buildDevUsernameForFrontDoorHost(developerIdRaw);
+  t = t.replace(/\$\{DEV_USERNAME\}/g, devU);
+  let remoteHost = '';
+  try {
+    if (remoteServer && String(remoteServer).trim()) {
+      remoteHost = new URL(String(remoteServer).trim()).hostname;
+    }
+  } catch {
+    remoteHost = '';
+  }
+  t = t.replace(/\$\{REMOTE_HOST\}/g, remoteHost);
+  t = t.replace(/^\.+/g, '').replace(/\.{2,}/g, '.').replace(/\.+$/g, '').trim();
+  return t;
+}
+
+/**
+ * Traefik PathPrefix / host / TLS from frontDoorRouting (public ingress). Does not include StripPrefix — that follows
+ * the in-container health path: private URL is `http://<service>:<port>` plus the probe path; `/dev`, `/tst`, `/auth`,
+ * etc. are public path segments only.
+ *
+ * @param {Object} config - Application configuration (application.yaml shape)
+ * @param {string|number} devId - Developer id for host expansion
+ * @param {Object|null} scopeOpts - Env-scoped Traefik path (effectiveEnvironmentScopedResources, runEnvKey)
+ * @param {string|null|undefined} remoteServer - For ${REMOTE_HOST}
+ * @returns {{ enabled: false } | { enabled: true, host: string, path: string, tls: boolean, certStore: string|null }}
+ */
+function buildTraefikIngressBase(config, devId, scopeOpts, remoteServer) {
+  const frontDoor = config.frontDoorRouting;
+  if (!frontDoor || frontDoor.enabled !== true) {
+    return { enabled: false };
+  }
+  if (!frontDoor.host || typeof frontDoor.host !== 'string') {
+    throw new Error('frontDoorRouting.host is required when frontDoorRouting.enabled is true');
+  }
+  const host = expandFrontDoorHostPlaceholders(frontDoor.host, devId, remoteServer);
+  const basePath = derivePathFromPattern(frontDoor.pattern);
+  let pathOut = basePath;
+  if (
+    scopeOpts &&
+    scopeOpts.effectiveEnvironmentScopedResources &&
+    scopeOpts.runEnvKey &&
+    (scopeOpts.runEnvKey === 'dev' || scopeOpts.runEnvKey === 'tst')
+  ) {
+    pathOut = buildEnvScopedTraefikPath(basePath, scopeOpts.runEnvKey);
+  }
+  return {
+    enabled: true,
+    host,
+    path: pathOut,
+    tls: resolveTraefikTlsEnabled(frontDoor.tls),
+    certStore: frontDoor.certStore || null
+  };
+}
+
+/**
+ * Whether Traefik should apply StripPrefix so the backend sees the same path as the Docker health probe.
+ * When the resolved compose health path already lies under the public PathPrefix (e.g. /auth/health/ready), forward
+ * the full path. When the probe is root-only (e.g. /health) but PathPrefix is /miso, strip the prefix.
+ *
+ * @param {string} traefikPath - PathPrefix value (slashes normalized, no trailing slash except '/')
+ * @param {string} resolvedHealthPath - Output of resolveHealthCheckPathWithFrontDoorVdir with compose opts
+ * @returns {boolean} true when StripPrefix middleware labels should be emitted
+ */
+function computeTraefikStripPathPrefix(traefikPath, resolvedHealthPath) {
+  const healthRaw = String(resolvedHealthPath || '/').trim();
+  const health = healthRaw.replace(/\/+$/, '') || '/';
+  const prefixRaw = String(traefikPath || '/').trim();
+  const prefix = prefixRaw.replace(/\/+$/, '') || '/';
+  if (prefix === '/' || prefix === '') {
+    return false;
+  }
+  if (health === prefix || health.startsWith(`${prefix}/`)) {
+    return false;
+  }
+  return true;
+}
+
+module.exports = {
+  derivePathFromPattern,
+  resolveTraefikTlsEnabled,
+  buildDevUsernameForFrontDoorHost,
+  expandFrontDoorHostPlaceholders,
+  buildTraefikIngressBase,
+  computeTraefikStripPathPrefix
+};

package/lib/utils/config-paths.js

@@ -8,6 +8,7 @@
  * @version 2.0.0
  */
 
+const fs = require('fs');
 const path = require('path');
 
 /**
@@ -21,6 +22,7 @@ const SETTINGS_RESPONSE_KEYS = [
   'aifabrix-env-config',
   'remote-server',
   'docker-endpoint',
+  'docker-tls-skip-verify',
   'sync-ssh-user',
   'sync-ssh-host'
 ];
@@ -56,38 +58,199 @@ async function setPathConfig(getConfigFn, saveConfigFn, key, value, errorMsg) {
   await saveConfigFn(config);
 }
 
+/**
+ * Clear a path config key (set to undefined so getPathConfig returns null).
+ * @param {Function} getConfigFn - Function to get config
+ * @param {Function} saveConfigFn - Function to save config
+ * @param {string} key - Configuration key
+ * @returns {Promise<void>}
+ */
+async function clearPathConfig(getConfigFn, saveConfigFn, key) {
+  const config = await getConfigFn();
+  config[key] = undefined;
+  await saveConfigFn(config);
+}
+
 function createHomeAndSecretsPathFunctions(getConfigFn, saveConfigFn) {
   return {
     async getAifabrixHomeOverride() {
       return getPathConfig(getConfigFn, 'aifabrix-home');
     },
     async setAifabrixHomeOverride(homePath) {
-      await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-home', homePath, 'Home path is required and must be a string');
+      if (typeof homePath !== 'string') {
+        throw new Error('Home path is required and must be a string');
+      }
+      const trimmed = homePath.trim();
+      if (trimmed === '') {
+        await clearPathConfig(getConfigFn, saveConfigFn, 'aifabrix-home');
+        return;
+      }
+      await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-home', trimmed, 'Home path must be a non-empty string');
+    },
+    async getAifabrixWorkOverride() {
+      return getPathConfig(getConfigFn, 'aifabrix-work');
+    },
+    async setAifabrixWorkOverride(workPath) {
+      if (typeof workPath !== 'string') {
+        throw new Error('Work path is required and must be a string');
+      }
+      const trimmed = workPath.trim();
+      if (trimmed === '') {
+        await clearPathConfig(getConfigFn, saveConfigFn, 'aifabrix-work');
+        return;
+      }
+      const resolved = path.resolve(trimmed);
+      await setPathConfig(
+        getConfigFn,
+        saveConfigFn,
+        'aifabrix-work',
+        resolved,
+        'Work path must be a non-empty string'
+      );
     },
     async getAifabrixSecretsPath() {
       return getPathConfig(getConfigFn, 'aifabrix-secrets');
     },
     async setAifabrixSecretsPath(secretsPath) {
-      await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-secrets', secretsPath, 'Secrets path is required and must be a string');
+      if (typeof secretsPath !== 'string') {
+        throw new Error('Secrets path is required and must be a string');
+      }
+      const trimmed = secretsPath.trim();
+      if (trimmed === '') {
+        await clearPathConfig(getConfigFn, saveConfigFn, 'aifabrix-secrets');
+        return;
+      }
+      await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-secrets', trimmed, 'Secrets path must be a non-empty string');
     }
   };
 }
 
+/**
+ * Resolve configured `aifabrix-env-config` to an absolute path.
+ * Relative paths are resolved against the workspace root first: `aifabrix-work` from the same config,
+ * then {@link module:lib/utils/paths.getAifabrixWork} (env `AIFABRIX_WORK` + on-disk yaml). If neither
+ * is set, falls back to `aifabrix-home` from config, then {@link module:lib/utils/paths.getAifabrixHome}.
+ * Never uses the process current working directory alone as the anchor.
+ *
+ * @async
+ * @param {string} raw - Non-empty path string from config (may be relative)
+ * @param {Function} getConfigFn - Async config loader
+ * @returns {Promise<string>} Normalized absolute path
+ */
+async function resolveEnvConfigPathToAbsolute(raw, getConfigFn) {
+  const trimmed = String(raw || '').trim();
+  if (!trimmed) {
+    throw new Error('Env config path must be a non-empty string');
+  }
+  if (path.isAbsolute(trimmed)) {
+    return path.normalize(path.resolve(trimmed));
+  }
+  const pathsMod = require('./paths');
+
+  const workFromConfig = await getPathConfig(getConfigFn, 'aifabrix-work');
+  let workBase =
+    workFromConfig && String(workFromConfig).trim() !== ''
+      ? path.resolve(String(workFromConfig).trim())
+      : null;
+  if (!workBase) {
+    workBase = pathsMod.getAifabrixWork();
+  }
+  if (workBase && String(workBase).trim() !== '') {
+    return path.normalize(path.resolve(String(workBase).trim(), trimmed));
+  }
+
+  const homeFromConfig = await getPathConfig(getConfigFn, 'aifabrix-home');
+  const base =
+    homeFromConfig && String(homeFromConfig).trim() !== ''
+      ? path.resolve(String(homeFromConfig).trim())
+      : pathsMod.getAifabrixHome();
+  return path.normalize(path.resolve(base, trimmed));
+}
+
 function createEnvConfigPathFunctions(getConfigFn, saveConfigFn) {
   return {
+    /**
+     * Legacy `aifabrix-env-config` path when still set in config (infra defaults are in code).
+     * @returns {Promise<string|null>}
+     */
     async getAifabrixEnvConfigPath() {
-      return getPathConfig(getConfigFn, 'aifabrix-env-config');
+      const value = await getPathConfig(getConfigFn, 'aifabrix-env-config');
+      if (!value || typeof value !== 'string') {
+        return null;
+      }
+      return resolveEnvConfigPathToAbsolute(value, getConfigFn);
     },
     async setAifabrixEnvConfigPath(envConfigPath) {
-      await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-env-config', envConfigPath, 'Env config path is required and must be a string');
+      if (typeof envConfigPath !== 'string') {
+        throw new Error('Env config path is required and must be a string');
+      }
+      const trimmed = envConfigPath.trim();
+      if (trimmed === '') {
+        await clearPathConfig(getConfigFn, saveConfigFn, 'aifabrix-env-config');
+        return;
+      }
+      await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-env-config', trimmed, 'Env config path must be a non-empty string');
     },
     async getAifabrixBuilderDir() {
       const envConfigPath = await getPathConfig(getConfigFn, 'aifabrix-env-config');
-      return envConfigPath && typeof envConfigPath === 'string' ? path.dirname(envConfigPath) : null;
+      if (envConfigPath && typeof envConfigPath === 'string') {
+        const absolute = await resolveEnvConfigPathToAbsolute(envConfigPath.trim(), getConfigFn);
+        return path.dirname(absolute);
+      }
+      const pathsMod = require('./paths');
+      const tryDir = (base) => {
+        if (!base) {
+          return null;
+        }
+        const b = path.join(base, 'builder');
+        try {
+          if (fs.existsSync(b) && fs.statSync(b).isDirectory()) {
+            return b;
+          }
+        } catch {
+          /* ignore */
+        }
+        return null;
+      };
+      const fromProject = tryDir(pathsMod.getProjectRoot());
+      if (fromProject) {
+        return fromProject;
+      }
+      const work = pathsMod.getAifabrixWork();
+      return tryDir(work);
     }
   };
 }
 
+/**
+ * Whether remote Docker TLS should skip server certificate verification (dev / self-signed daemon).
+ * Env AIFABRIX_DOCKER_TLS_SKIP_VERIFY=1|true forces skip when set.
+ * @param {*} raw - Config or settings value
+ * @returns {boolean}
+ */
+function isDockerTlsSkipVerifyTruthy(raw) {
+  if (raw === true || raw === 1) return true;
+  if (typeof raw === 'string') {
+    const s = raw.trim().toLowerCase();
+    return s === 'true' || s === '1' || s === 'yes';
+  }
+  return false;
+}
+
+/**
+ * Explicit opt-out of TLS verify skip in config (docker-tls-skip-verify: false).
+ * @param {*} raw - Config value
+ * @returns {boolean}
+ */
+function isDockerTlsSkipVerifyExplicitlyFalse(raw) {
+  if (raw === false) return true;
+  if (typeof raw === 'string') {
+    const s = raw.trim().toLowerCase();
+    return s === 'false' || s === '0' || s === 'no';
+  }
+  return false;
+}
+
 function createRemoteConfigGetters(getConfigFn) {
   return {
     async getRemoteServer() {
@@ -96,6 +259,25 @@ function createRemoteConfigGetters(getConfigFn) {
     async getDockerEndpoint() {
       return getPathConfig(getConfigFn, 'docker-endpoint');
     },
+    /**
+     * When true, Docker CLI may use DOCKER_TLS_VERIFY=0 only when ca.pem is absent (no trust anchor).
+     * If ca.pem exists (e.g. after issue-cert), the daemon is always verified regardless of this flag.
+     */
+    async getDockerTlsSkipVerify() {
+      const envRaw = process.env.AIFABRIX_DOCKER_TLS_SKIP_VERIFY;
+      if (envRaw !== undefined && String(envRaw).trim() !== '') {
+        return isDockerTlsSkipVerifyTruthy(String(envRaw).trim());
+      }
+      const config = await getConfigFn();
+      const flag = config['docker-tls-skip-verify'];
+      if (isDockerTlsSkipVerifyExplicitlyFalse(flag)) {
+        return false;
+      }
+      if (isDockerTlsSkipVerifyTruthy(flag)) {
+        return true;
+      }
+      return false;
+    },
     async getUserMutagenFolder() {
       return getPathConfig(getConfigFn, 'user-mutagen-folder');
     },
@@ -125,6 +307,24 @@ function createRemoteConfigSetters(getConfigFn, saveConfigFn) {
       const config = await getConfigFn();
       config['docker-endpoint'] = value || undefined;
       await saveConfigFn(config);
+    },
+    async setDockerTlsSkipVerify(value) {
+      const config = await getConfigFn();
+      if (value === null || value === undefined) {
+        config['docker-tls-skip-verify'] = undefined;
+      } else if (typeof value === 'boolean') {
+        config['docker-tls-skip-verify'] = value;
+      } else if (typeof value === 'string') {
+        const s = value.trim().toLowerCase();
+        if (s === '' || s === 'false' || s === '0' || s === 'no') {
+          config['docker-tls-skip-verify'] = false;
+        } else {
+          config['docker-tls-skip-verify'] = isDockerTlsSkipVerifyTruthy(value);
+        }
+      } else {
+        throw new Error('docker-tls-skip-verify must be a boolean or string');
+      }
+      await saveConfigFn(config);
     }
   };
 }
@@ -155,7 +355,8 @@ function applySecretsUrlFromRemote(config) {
   const secretsPath = config['aifabrix-secrets'];
   if (!remoteServer || !secretsPath || isHttpUrl(secretsPath)) return;
   const base = typeof remoteServer === 'string' ? remoteServer.trim().replace(/\/+$/, '') : '';
-  if (base) config['aifabrix-secrets'] = `${base}/api/dev/secrets`;
+  if (!base) return;
+  config['aifabrix-secrets'] = `${base}/api/dev/secrets`;
 }
 
 function applySyncAndDockerFromHost(config) {
@@ -168,6 +369,7 @@ function applySyncAndDockerFromHost(config) {
 async function mergeRemoteSettingsImpl(getConfigFn, saveConfigFn, settings) {
   if (!settings || typeof settings !== 'object') return;
   const config = await getConfigFn();
+  delete config['aifabrix-secrets-path'];
   for (const key of SETTINGS_RESPONSE_KEYS) {
     const raw = settings[key];
     if (raw === undefined || raw === null) continue;
@@ -214,6 +416,7 @@ module.exports = {
   getPathConfig,
   setPathConfig,
   createPathConfigFunctions,
+  resolveEnvConfigPathToAbsolute,
   SETTINGS_RESPONSE_KEYS
 };
 

package/lib/utils/config-scoped-resources-preference.js

@@ -0,0 +1,41 @@
+/**
+ * User preference: useEnvironmentScopedResources in ~/.aifabrix/config.yaml
+ *
+ * @fileoverview Gate for environment-scoped resource resolution (plan 117)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Function} getConfigFn - async () => config object
+ * @param {Function} saveConfigFn - async (config) => void
+ * @returns {{ getUseEnvironmentScopedResources: Function, setUseEnvironmentScopedResources: Function }}
+ */
+function createScopedResourcesPreferenceFunctions(getConfigFn, saveConfigFn) {
+  return {
+    /**
+     * @returns {Promise<boolean>}
+     */
+    async getUseEnvironmentScopedResources() {
+      const cfg = await getConfigFn();
+      return Boolean(cfg.useEnvironmentScopedResources);
+    },
+
+    /**
+     * @param {boolean} value - Activate (true) or passivate (false) user gate
+     * @returns {Promise<void>}
+     */
+    async setUseEnvironmentScopedResources(value) {
+      if (typeof value !== 'boolean') {
+        throw new Error('useEnvironmentScopedResources must be a boolean');
+      }
+      const cfg = await getConfigFn();
+      cfg.useEnvironmentScopedResources = value;
+      await saveConfigFn(cfg);
+    }
+  };
+}
+
+module.exports = { createScopedResourcesPreferenceFunctions };

package/lib/utils/controller-deployment-outcome.js

@@ -0,0 +1,68 @@
+/**
+ * Interprets deployToController / poll result for CLI messaging (status, errors).
+ *
+ * @fileoverview Controller pipeline deployment outcome parsing
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * @typedef {Object} ControllerDeploymentOutcome
+ * @property {boolean} ok - False only for terminal failure-like statuses from controller
+ * @property {string|null} statusLabel - Raw status string when present
+ * @property {string|null} message - Optional deployment message from API
+ * @property {string|null} error - Optional error string from API
+ */
+
+/**
+ * @param {unknown} value - Candidate string field
+ * @returns {string|null} Trimmed non-empty string or null
+ */
+function nonEmptyTrimmed(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const t = String(value).trim();
+  return t ? t : null;
+}
+
+/**
+ * @param {Object} block - status object from API
+ * @returns {string|null}
+ */
+function resolveRawStatusLabel(block) {
+  if (typeof block.status === 'string') {
+    return block.status;
+  }
+  if (typeof block.deploymentStatus === 'string') {
+    return block.deploymentStatus;
+  }
+  return null;
+}
+
+/**
+ * @param {Object|null|undefined} result - deployToController return value
+ * @returns {ControllerDeploymentOutcome}
+ */
+function parseControllerDeploymentOutcome(result) {
+  const block = result && result.status && typeof result.status === 'object' ? result.status : null;
+  if (!block) {
+    return { ok: true, statusLabel: null, message: null, error: null };
+  }
+  const raw = resolveRawStatusLabel(block);
+  const message = nonEmptyTrimmed(block.message);
+  const error = nonEmptyTrimmed(block.error);
+  if (!raw) {
+    return { ok: true, statusLabel: null, message, error };
+  }
+  const s = raw.toLowerCase();
+  const failed = s === 'failed' || s === 'cancelled' || s === 'error';
+  return {
+    ok: !failed,
+    statusLabel: raw,
+    message,
+    error
+  };
+}
+
+module.exports = { parseControllerDeploymentOutcome };

package/lib/utils/credential-display.js

@@ -11,9 +11,9 @@ const chalk = require('chalk');
 
 /** @type {{ verified: string, pending: string, failed: string, expired: string }} */
 const STATUS_ICONS = {
-  verified: ' ✓',
+  verified: ' ✔',
   pending: ' ○',
-  failed: ' ✗',
+  failed: ' ✖',
   expired: ' ⊘'
 };
 

package/lib/utils/credential-secrets-env.js

@@ -92,6 +92,17 @@ function kvPathInferred(segments) {
   return (namespace && pathVar) ? `kv://${namespace}/${pathVar}` : null;
 }
 
+/**
+ * Returns the path segment used in kv://<systemKey>/<segment> for a given security key.
+ * Uses the same derivation as env key → path (securityKeyToVar + varSegmentsToCamelCase).
+ * @param {string} securityKey - Security key (e.g. 'apiKey', 'clientId', 'clientSecret')
+ * @returns {string} Canonical path segment (e.g. 'apiKey', 'clientId')
+ */
+function getKvPathSegmentForSecurityKey(securityKey) {
+  if (!securityKey || typeof securityKey !== 'string') return '';
+  return varSegmentsToCamelCase([securityKeyToVar(securityKey)]);
+}
+
 /**
  * Converts KV_* env key to kv:// path in format kv://<system-key>/<variable>.
  * System-key uses hyphens (e.g. microsoft-teams); variable is camelCase (e.g. clientId).
@@ -220,7 +231,10 @@ function buildItemsFromEnv(envFilePath, secrets, itemsByKey) {
     const fromEnv = collectKvEnvVarsAsSecretItems(envMap);
     for (const { key, value } of fromEnv) {
       const resolved = resolveKvValue(secrets, value);
-      if (resolved !== null && resolved !== undefined && isValidKvPath(key)) itemsByKey.set(key, resolved);
+      // Skip placeholder: value that equals the kv path (e.g. from env.template) must not be pushed as the secret
+      if (resolved !== null && resolved !== undefined && isValidKvPath(key) && resolved.trim() !== key.trim()) {
+        itemsByKey.set(key, resolved);
+      }
     }
   } catch {
     // Best-effort: continue without .env items
@@ -349,6 +363,7 @@ module.exports = {
   collectKvRefsFromPayload,
   pushCredentialSecrets,
   kvEnvKeyToPath,
+  getKvPathSegmentForSecurityKey,
   systemKeyToKvPrefix,
   securityKeyToVar,
   isValidKvPath,

package/lib/utils/dataplane-pipeline-warning.js

@@ -7,19 +7,20 @@
  * @version 2.0.0
  */
 
-const chalk = require('chalk');
 const logger = require('./logger');
+const { metadata } = require('./cli-test-layout-chalk');
 
 /** Message shown when CLI is about to call Dataplane pipeline upload or publish APIs. */
 const DATAPLANE_PIPELINE_WARNING =
   'Configuration will be sent to the Dataplane pipeline API. Ensure you are targeting the correct environment and have the required permissions.';
 
 /**
- * Log the Dataplane pipeline warning (yellow) to the console.
+ * Log the Dataplane pipeline notice (non-warning) to the console.
  * Call before uploadApplicationViaPipeline or publishDatasourceViaPipeline.
  */
 function logDataplanePipelineWarning() {
-  logger.log(chalk.yellow(`⚠ ${DATAPLANE_PIPELINE_WARNING}`));
+  // Informational: this is expected behavior for upload/publish flows.
+  logger.log(metadata(`Dataplane pipeline: ${DATAPLANE_PIPELINE_WARNING}`));
 }
 
 module.exports = {

package/lib/utils/datasource-test-run-capability-scope.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Single-capability CLI contract when --capability is set.
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * @param {Object|null|undefined} envelope - DatasourceTestRun-like
+ * @param {string|undefined|null} requestedCapabilityKey - From CLI --capability
+ * @returns {{ violated: boolean, message?: string, count?: number }}
+ */
+function analyzeCapabilityScope(envelope, requestedCapabilityKey) {
+  const key =
+    requestedCapabilityKey !== undefined &&
+    requestedCapabilityKey !== null &&
+    String(requestedCapabilityKey).trim() !== ''
+      ? String(requestedCapabilityKey).trim()
+      : '';
+  if (!key) {
+    return { violated: false };
+  }
+  const caps =
+    envelope && typeof envelope === 'object' && Array.isArray(envelope.capabilities)
+      ? envelope.capabilities
+      : [];
+  if (caps.length <= 1) {
+    return { violated: false };
+  }
+  const keys = caps.map(c =>
+    c && c.key !== undefined && c.key !== null ? String(c.key) : '?'
+  );
+  const preview = keys.slice(0, 8).join(', ');
+  const suffix = keys.length > 8 ? ', …' : '';
+  return {
+    violated: true,
+    count: caps.length,
+    message: `Capabilities scope: with --capability "${key}", expected a single row in capabilities[]; server returned ${caps.length} (${preview}${suffix}).`
+  };
+}
+
+module.exports = {
+  analyzeCapabilityScope
+};