@aifabrix/builder 2.43.0 → 2.44.1

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'
 ];
@@ -85,6 +87,27 @@ function createHomeAndSecretsPathFunctions(getConfigFn, saveConfigFn) {
       }
       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');
     },
@@ -102,16 +125,60 @@ function createHomeAndSecretsPathFunctions(getConfigFn, saveConfigFn) {
   };
 }
 
-/** Default env-config path when aifabrix-env-config is not set (builder schema). */
-function getDefaultEnvConfigPath() {
-  return path.join(__dirname, '..', 'schema', 'env-config.yaml');
+/**
+ * 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() {
       const value = await getPathConfig(getConfigFn, 'aifabrix-env-config');
-      return value || getDefaultEnvConfigPath();
+      if (!value || typeof value !== 'string') {
+        return null;
+      }
+      return resolveEnvConfigPathToAbsolute(value, getConfigFn);
     },
     async setAifabrixEnvConfigPath(envConfigPath) {
       if (typeof envConfigPath !== 'string') {
@@ -126,11 +193,64 @@ function createEnvConfigPathFunctions(getConfigFn, saveConfigFn) {
     },
     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() {
@@ -139,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');
     },
@@ -168,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);
     }
   };
 }
@@ -198,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) {
@@ -211,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;
@@ -257,7 +416,7 @@ module.exports = {
   getPathConfig,
   setPathConfig,
   createPathConfigFunctions,
-  getDefaultEnvConfigPath,
+  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/configuration-env-resolver.js

@@ -10,7 +10,7 @@
 const path = require('path');
 const fs = require('fs');
 const { getIntegrationPath } = require('./paths');
-const { parseEnvToMap, resolveKvValue } = require('./credential-secrets-env');
+const { parseEnvToMap } = require('./credential-secrets-env');
 const { loadSecrets, resolveKvReferences } = require('../core/secrets');
 const { loadEnvTemplate } = require('./secrets-helpers');
 const { getActualSecretsPath } = require('./secrets-path');
@@ -81,13 +81,13 @@ function substituteVarPlaceholders(value, envMap, systemKey) {
 
 /**
  * Resolves configuration array values in place by location: variable → {{VAR}} from envMap;
- * keyvault → kv:// from secrets. Does not log or expose secret values.
+ * keyvault → leaves kv:// as-is (secret value pushed separately by CLI). Does not log or expose secret values.
  *
  * @param {Array<{ name?: string, value?: string, location?: string }>} configArray - Configuration array (mutated)
  * @param {Object.<string, string>} envMap - Resolved env map from buildResolvedEnvMapForIntegration
- * @param {Object} secrets - Loaded secrets for kv:// resolution
+ * @param {Object} secrets - Loaded secrets (unused for keyvault config values; kept for backward compatibility)
  * @param {string} [systemKey] - System key for error messages
- * @throws {Error} If variable env is missing or keyvault secret unresolved (message never contains secret values)
+ * @throws {Error} If variable env is missing or keyvault value is not a kv:// reference (message never contains secret values)
  */
 function resolveConfigurationValues(configArray, envMap, secrets, systemKey) {
   if (!Array.isArray(configArray)) return;
@@ -101,11 +101,14 @@ function resolveConfigurationValues(configArray, envMap, secrets, systemKey) {
       }
       item.value = substituteVarPlaceholders(item.value, envMap, systemKey);
     } else if (location === 'keyvault') {
-      const resolved = resolveKvValue(secrets, item.value);
-      if (resolved === null || resolved === undefined) {
-        throw new Error(`Unresolved keyvault reference for configuration '${item.name || 'unknown'}'.${hint}`);
+      if (!item.value.trim().startsWith('kv://')) {
+        throw new Error(
+          `Configuration entry '${item.name || 'unknown'}' has location 'keyvault' but value is not kv://. ` +
+            `Set value to a kv:// reference and push the secret with KV_* env vars.${hint}`
+        );
       }
-      item.value = resolved;
+      // Intentionally do not resolve kv:// here. Upload keeps kv:// references in config and
+      // pushes secret values separately via the credential secret API.
     }
   }
 }

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

@@ -132,7 +132,7 @@ function kvEnvKeyToPath(envKey, systemKey) {
  * @param {Object.<string, string>} envMap - Key-value map from .env
  * @returns {Array<{ key: string, value: string }>} Items (key = kv://..., value = raw)
  */
-function collectKvEnvVarsAsSecretItems(envMap) {
+function collectKvEnvVarsAsSecretItems(envMap, systemKey) {
   if (!envMap || typeof envMap !== 'object') {
     return [];
   }
@@ -144,7 +144,7 @@ function collectKvEnvVarsAsSecretItems(envMap) {
     if (value.startsWith('kv://') && isValidKvPath(value)) {
       kvPath = value;
     }
-    if (!kvPath) kvPath = kvEnvKeyToPath(envKey);
+    if (!kvPath) kvPath = kvEnvKeyToPath(envKey, systemKey) || kvEnvKeyToPath(envKey);
     if (!kvPath) continue;
     items.push({ key: kvPath, value });
   }
@@ -223,12 +223,12 @@ function isValidKvPath(key) {
  * @param {Object} secrets - Loaded secrets
  * @param {Map<string, string>} itemsByKey - Mutable map to add items to
  */
-function buildItemsFromEnv(envFilePath, secrets, itemsByKey) {
+function buildItemsFromEnv(envFilePath, secrets, itemsByKey, systemKey) {
   if (!envFilePath || typeof envFilePath !== 'string' || !fs.existsSync(envFilePath)) return;
   try {
     const content = fs.readFileSync(envFilePath, 'utf8');
     const envMap = parseEnvToMap(content);
-    const fromEnv = collectKvEnvVarsAsSecretItems(envMap);
+    const fromEnv = collectKvEnvVarsAsSecretItems(envMap, systemKey);
     for (const { key, value } of fromEnv) {
       const resolved = resolveKvValue(secrets, value);
       // Skip placeholder: value that equals the kv path (e.g. from env.template) must not be pushed as the secret
@@ -320,7 +320,7 @@ async function pushCredentialSecrets(dataplaneUrl, authConfig, options = {}) {
     secrets = {};
   }
   const itemsByKey = new Map();
-  buildItemsFromEnv(envFilePath, secrets, itemsByKey);
+  buildItemsFromEnv(envFilePath, secrets, itemsByKey, appName);
   buildItemsFromPayload(payload, secrets, itemsByKey);
 
   const items = Array.from(itemsByKey.entries())

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
+};