@aifabrix/builder 2.59.0 → 2.61.2

package/lib/utils/env-copy.js

@@ -56,16 +56,17 @@ function readDeveloperIdFromConfig(config) {
  * Creates the mount folder on the local filesystem (next to the .env file) when it does not exist.
  * @param {string} content - Env file content
  * @param {string} outputPath - Resolved path of the .env file being written
+ * @param {string} [appName] - System key (defaults to output directory name)
  * @returns {string} Content with /mnt/data replaced by path to mount directory
  */
-function substituteMntDataForLocal(content, outputPath) {
+function substituteMntDataForLocal(content, outputPath, appName) {
   const outputDir = path.dirname(outputPath);
   // Avoid introducing a drive letter for root-relative paths (e.g. "\tmp\out"),
   // which are common in unit tests and some Windows path constructions.
   const isWinRootRelative = process.platform === 'win32' && /^\\(?!\\)/.test(outputDir);
   const localMountPath = isWinRootRelative
-    ? path.win32.normalize(path.win32.join(outputDir, 'mount'))
-    : path.resolve(outputDir, 'mount');
+    ? path.win32.normalize(path.win32.join(outputDir, 'mount', 'data', appName || path.basename(outputDir)))
+    : path.resolve(outputDir, 'mount', 'data', appName || path.basename(outputDir));
   if (!fs.existsSync(localMountPath)) {
     fs.mkdirSync(localMountPath, { recursive: true });
   }
@@ -140,12 +141,12 @@ async function writeEnvOutputForReload(outputPath, runEnvPath, appName) {
     baseContent = await fsp.readFile(outputPath, 'utf8');
   } else if (appName) {
     baseContent = await generateEnvContent(appName, null, 'local', false);
-    baseContent = substituteMntDataForLocal(baseContent, outputPath);
+    baseContent = substituteMntDataForLocal(baseContent, outputPath, appName);
   } else {
     baseContent = runContent;
   }
   let toWrite = mergeEnvMapIntoContent(baseContent, runMap, { appendMissingFromNewMap: false });
-  toWrite = substituteMntDataForLocal(toWrite, outputPath);
+  toWrite = substituteMntDataForLocal(toWrite, outputPath, appName);
   await fsp.writeFile(outputPath, toWrite, { mode: 0o600 });
   logger.log(
     formatSuccessLine(
@@ -163,7 +164,7 @@ async function writeEnvOutputForReload(outputPath, runEnvPath, appName) {
 async function writeEnvOutputForLocal(appName, outputPath) {
   const { generateEnvContent, parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
   let localContent = await generateEnvContent(appName, null, 'local', false);
-  localContent = substituteMntDataForLocal(localContent, outputPath);
+  localContent = substituteMntDataForLocal(localContent, outputPath, appName);
   let toWrite = localContent;
   if (fs.existsSync(outputPath)) {
     const existingContent = await fsp.readFile(outputPath, 'utf8');
@@ -319,7 +320,7 @@ async function patchEnvContentForLocal(envContent, variables) {
 async function syncWrittenBuilderEnvToOutputPath(envPath, outputPath, envOutputPathLabel, copyOptions = {}) {
   const { parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
   const raw = fs.readFileSync(envPath, 'utf8');
-  const synced = substituteMntDataForLocal(raw, outputPath);
+  const synced = substituteMntDataForLocal(raw, outputPath, copyOptions.appName || path.basename(path.dirname(envPath)));
   let toWrite = synced;
   if (!copyOptions.freshEnv && fs.existsSync(outputPath)) {
     const existingContent = fs.readFileSync(outputPath, 'utf8');
@@ -344,7 +345,7 @@ async function writeLocalEnvToOutputPath(outputPath, appName, secretsPath, envOu
   const { generateEnvContent, parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
   const genOpts = extraOpts.appPath ? { appPath: extraOpts.appPath } : {};
   let localEnvContent = await generateEnvContent(appName, secretsPath, 'local', false, genOpts);
-  localEnvContent = substituteMntDataForLocal(localEnvContent, outputPath);
+  localEnvContent = substituteMntDataForLocal(localEnvContent, outputPath, appName);
   let toWrite = localEnvContent;
   if (!extraOpts.freshEnv && fs.existsSync(outputPath)) {
     const existingContent = fs.readFileSync(outputPath, 'utf8');
@@ -366,7 +367,7 @@ async function writeLocalEnvToOutputPath(outputPath, appName, secretsPath, envOu
 async function writePatchedEnvToOutputPath(envPath, outputPath, variables, envOutputPathLabel) {
   const envContent = fs.readFileSync(envPath, 'utf8');
   let patchedContent = await patchEnvContentForLocal(envContent, variables);
-  patchedContent = substituteMntDataForLocal(patchedContent, outputPath);
+  patchedContent = substituteMntDataForLocal(patchedContent, outputPath, variables.app?.key || path.basename(path.dirname(envPath)));
   fs.writeFileSync(outputPath, patchedContent, { mode: 0o600 });
   logger.log(formatSuccessLine(`Copied .env to: ${envOutputPathLabel}`));
 }
@@ -405,7 +406,7 @@ async function copyOrRegenerateEnvForNamedApp(opts) {
     return;
   }
   if (fs.existsSync(envPath)) {
-    await syncWrittenBuilderEnvToOutputPath(envPath, outputPath, label, { freshEnv: freshEnv === true });
+    await syncWrittenBuilderEnvToOutputPath(envPath, outputPath, label, { freshEnv: freshEnv === true, appName });
     return;
   }
   await writeLocalEnvToOutputPath(outputPath, appName, secretsPath, label, localOpts);

package/lib/utils/external-system-system-test-tty.js

@@ -182,7 +182,9 @@ function pickBlockingDatasourceKey(rows) {
 }
 
 function issueKey(issue) {
-  const code = issue && issue.code ? String(issue.code) : '';
+  const code = issue && (issue.stableCode || issue.code)
+    ? String(issue.stableCode || issue.code)
+    : '';
   const msg = issue && issue.message ? String(issue.message) : '';
   return `${code}::${msg}`.toLowerCase();
 }
@@ -402,4 +404,3 @@ module.exports = {
   systemCertStatus,
   drillDownCommand
 };
-

package/lib/utils/image-tags.js

@@ -48,7 +48,7 @@ function expandTag(entry, version) {
  * @throws {Error} On blank entries, unsupported placeholders, missing version or invalid tags
  */
 function resolveImageTags(tagInput, appVersion) {
-  if (tagInput === undefined || tagInput === null || String(tagInput).trim() === '') {
+  if (tagInput === undefined || tagInput === null) {
     return [DEFAULT_TAG];
   }
   const entries = String(tagInput).split(',').map((entry) => entry.trim());
@@ -72,7 +72,7 @@ function resolveImageTags(tagInput, appVersion) {
  */
 function resolveBuildTagPlan(tagInput, appVersion) {
   const tags = resolveImageTags(tagInput, appVersion);
-  const explicitSingle = tags.length === 1 && tagInput !== undefined && tagInput !== null && String(tagInput).trim() !== '';
+  const explicitSingle = tagInput !== undefined && tagInput !== null && !String(tagInput).includes(',');
   if (explicitSingle && !FLOATING_TAGS.includes(tags[0])) {
     tags.push(DEFAULT_TAG);
   }

package/lib/utils/platform-kv-ref.js

@@ -42,7 +42,7 @@ function isPlatformCatalogKvRef(val) {
 
 /**
  * True when repair should normalize a kv value to path-style kv://systemKey/variable.
- * Platform catalog refs (e.g. kv://secrets-openaiApiKeyVault) are never legacy.
+ * Platform catalog refs (e.g. kv://redis-passwordKeyVault) are never legacy.
  *
  * @param {string} val - Value from authentication.security or configuration
  * @returns {boolean}

package/lib/utils/platform-resolution.js

@@ -0,0 +1,226 @@
+/**
+ * Platform and environment configuration resolution (plan 200.0).
+ *
+ * The deployment's Azure resource group is matched against the manifest `platforms` list, yielding
+ * `{platform}` and `{platform.name}`. Platform values expand from those, then the matching
+ * `environments` entry overrides by name. The result is one flat set of names that `env.template`
+ * references as `{NAME}`.
+ *
+ * Pure by contract: manifest + resource group + environment key in, resolved set out. No
+ * filesystem, no Azure, no network — the same function must be implementable in Miso and produce
+ * identical output for the shared test vectors.
+ *
+ * @fileoverview Resource-group driven configuration resolution
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** Local Docker has no resource group; every local run resolves as this platform. */
+const LOCAL_PLATFORM = 'dev';
+/** Capture for `*` in a resource pattern: one group-name segment. */
+const NAME_CAPTURE = '[A-Za-z0-9][A-Za-z0-9-]*';
+const NAME_WILDCARD = '*';
+
+function escapeLiteral(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Compiles a `resource` pattern into a matcher.
+ * `{platform}` matches one of `options`; `*` captures a name segment.
+ * @param {Object} entry - Platform entry
+ * @returns {{ regex: RegExp, order: string[] }} Matcher and the capture order
+ */
+function compileResourcePattern(entry) {
+  const order = [];
+  let source = '';
+  const pattern = String(entry.resource || '');
+  const tokens = pattern.split(/(\{platform\}|\*)/);
+  for (const token of tokens) {
+    if (token === '{platform}') {
+      const options = Array.isArray(entry.options) ? entry.options : [];
+      source += `(${options.map(escapeLiteral).join('|')})`;
+      order.push('platform');
+    } else if (token === NAME_WILDCARD) {
+      source += `(${NAME_CAPTURE})`;
+      order.push('name');
+    } else if (token) {
+      source += escapeLiteral(token);
+    }
+  }
+  return { regex: new RegExp(`^${source}$`), order };
+}
+
+/**
+ * @param {Object} entry - Platform entry
+ * @throws {Error} When the entry cannot yield a platform
+ */
+function assertPlatformDeclaration(entry) {
+  const hasToken = String(entry.resource || '').includes('{platform}');
+  const hasOptions = Array.isArray(entry.options) && entry.options.length > 0;
+  if (hasToken && !hasOptions) {
+    throw new Error(`Platform "${entry.resource}" uses {platform} but declares no options`);
+  }
+  if (!hasToken && !entry.platform) {
+    throw new Error(`Platform "${entry.resource}" has no {platform} token, so it must declare platform:`);
+  }
+  if (hasToken && entry.platform) {
+    throw new Error(`Platform "${entry.resource}" declares both {platform} and platform:; use one`);
+  }
+}
+
+function matchEntry(entry, resourceGroup) {
+  assertPlatformDeclaration(entry);
+  const { regex, order } = compileResourcePattern(entry);
+  const found = regex.exec(resourceGroup);
+  if (!found) return null;
+  const captured = {};
+  order.forEach((key, index) => {
+    captured[key] = found[index + 1];
+  });
+  const platform = captured.platform || entry.platform;
+  const name = entry.name === NAME_WILDCARD ? captured.name : entry.name;
+  if (!name) {
+    throw new Error(`Platform "${entry.resource}" uses name: * but the pattern captures no name segment`);
+  }
+  return { entry, platform, name };
+}
+
+/**
+ * Matches a resource group against the manifest platforms.
+ * @param {Array} platforms - Manifest `platforms`
+ * @param {string} resourceGroup - Target Azure resource group
+ * @returns {{ entry: Object, platform: string, name: string }} The single match
+ * @throws {Error} On no match or more than one match
+ */
+function matchPlatform(platforms, resourceGroup) {
+  const entries = Array.isArray(platforms) ? platforms : [];
+  const group = String(resourceGroup || '').trim();
+  if (!group) {
+    throw new Error('A resource group is required to resolve a platform');
+  }
+  const matches = entries.map(entry => matchEntry(entry, group)).filter(Boolean);
+  if (matches.length === 0) {
+    const tried = entries.map(entry => `"${entry.resource}"`).join(', ') || '(none declared)';
+    throw new Error(`Resource group "${group}" matches no platform. Patterns tried: ${tried}`);
+  }
+  if (matches.length > 1) {
+    const ambiguous = matches.map(match => `"${match.entry.resource}"`).join(', ');
+    throw new Error(`Resource group "${group}" matches more than one platform: ${ambiguous}. Make the patterns exclusive.`);
+  }
+  return matches[0];
+}
+
+/**
+ * Expands `{platform}`, `{platform.name}` and `{resourceGroup}` in a value.
+ * @param {string} value - Raw value
+ * @param {Object} context - `platform`, `name`, `resourceGroup`
+ * @returns {string}
+ * @throws {Error} On an unknown token
+ */
+function expandPlatformTokens(value, context) {
+  const text = value === undefined || value === null ? '' : String(value);
+  return text.replace(/\{([a-zA-Z][a-zA-Z.]*)\}/g, (match, token) => {
+    if (token === 'platform') return context.platform;
+    if (token === 'platform.name') return context.name;
+    if (token === 'resourceGroup') return context.resourceGroup;
+    throw new Error(`Unsupported token ${match}; use {platform}, {platform.name} or {resourceGroup}`);
+  });
+}
+
+function applyItems(target, items, context) {
+  for (const item of Array.isArray(items) ? items : []) {
+    target.set(item.name, expandPlatformTokens(item.value, context));
+  }
+}
+
+/**
+ * Local runs have no resource group, but still need platform values. The first entry that can
+ * produce the local platform supplies them; an `environments` entry still overrides by name.
+ * A `*` name cannot be captured without a group, so it resolves to ''.
+ * @param {Array} platforms - Manifest platforms
+ * @returns {{ entry: Object, platform: string, name: string }|null}
+ */
+function matchLocalPlatform(platforms) {
+  const entry = platforms.find(item =>
+    item.platform === LOCAL_PLATFORM ||
+    (Array.isArray(item.options) && item.options.includes(LOCAL_PLATFORM)));
+  if (!entry) return null;
+  return { entry, platform: LOCAL_PLATFORM, name: entry.name === NAME_WILDCARD ? '' : entry.name };
+}
+
+/**
+ * @param {Object} manifest - Application manifest
+ * @param {string} resourceGroup - Target resource group ('' for local Docker)
+ * @returns {{ entry: Object, platform: string, name: string }|null}
+ */
+function matchIfDeclared(manifest, resourceGroup, allowLocalPlatform) {
+  const platforms = manifest && Array.isArray(manifest.platforms) ? manifest.platforms : [];
+  if (platforms.length === 0) return null;
+  if (!resourceGroup) return allowLocalPlatform ? matchLocalPlatform(platforms) : null;
+  return matchPlatform(platforms, resourceGroup);
+}
+
+function environmentEntry(manifest, environment) {
+  const entries = manifest && Array.isArray(manifest.environments) ? manifest.environments : [];
+  return entries.find(item => item.environment === environment) || null;
+}
+
+function applyBuiltIns(values, context, environment) {
+  const builtIns = [
+    // PLATFORM is omitted when nothing determined it, so a consumer fails closed on {PLATFORM}
+    // rather than receiving a guess.
+    ...(context.platform ? [['PLATFORM', context.platform]] : []),
+    ['PLATFORM_NAME', context.name],
+    ['RESOURCE_GROUP', context.resourceGroup],
+    ['ENVIRONMENT', environment]
+  ];
+  // Built-ins never overwrite an authored name of the same spelling.
+  for (const [key, value] of builtIns) {
+    if (!values.has(key)) values.set(key, value);
+  }
+}
+
+/**
+ * Resolves the configuration set for one deployment.
+ * @param {Object} manifest - Application manifest with optional `platforms` / `environments`
+ * @param {Object} target - `resourceGroup` (omitted for local Docker), `environment`, and
+ *   `allowLocalPlatform` (default true). A caller that is not a local run — the Controller, which
+ *   knows the environment but may not know the group — passes false so a missing group resolves no
+ *   platform at all instead of silently claiming `dev`.
+ * @returns {{ platform: string|null, name: string|null, resourceGroup: string|null, values: Object }}
+ */
+function resolveConfiguration(manifest, target = {}) {
+  const resourceGroup = target.resourceGroup ? String(target.resourceGroup).trim() : '';
+  const environment = target.environment ? String(target.environment).trim() : '';
+  const allowLocalPlatform = target.allowLocalPlatform !== false;
+  const matched = matchIfDeclared(manifest, resourceGroup, allowLocalPlatform);
+  const localPlatform = allowLocalPlatform ? LOCAL_PLATFORM : '';
+  const context = {
+    platform: matched ? matched.platform : localPlatform,
+    name: matched ? matched.name : '',
+    resourceGroup
+  };
+
+  const values = new Map();
+  if (matched) applyItems(values, matched.entry.configuration, context);
+  const envEntry = environmentEntry(manifest, environment);
+  if (envEntry) applyItems(values, envEntry.configuration, context);
+  applyBuiltIns(values, context, environment);
+
+  return {
+    platform: context.platform || null,
+    name: matched && matched.name ? matched.name : null,
+    resourceGroup: resourceGroup || null,
+    values: Object.fromEntries(values)
+  };
+}
+
+module.exports = {
+  LOCAL_PLATFORM,
+  matchPlatform,
+  expandPlatformTokens,
+  resolveConfiguration
+};

package/lib/utils/prepare-local-data-mount.js

@@ -0,0 +1,58 @@
+/**
+ * Prepare persistent storage before starting a local application container.
+ * @fileoverview Local storage mount and configured DATA_DIR initialization
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const dotenv = require('dotenv');
+
+/**
+ * Read only a DATA_DIR beneath the container's storage mount.
+ * @param {string|undefined} envFile - Resolved application env file
+ * @returns {string[]} Relative directory components
+ */
+function dataDirectoryParts(envFile) {
+  if (!envFile || !fs.existsSync(envFile)) return [];
+  const { DATA_DIR: dataDir } = dotenv.parse(fs.readFileSync(envFile, 'utf8'));
+  if (!dataDir || !dataDir.startsWith('/mnt/data/')) return [];
+  const parts = dataDir.slice('/mnt/data/'.length).split('/').filter(part => part && part !== '.');
+  if (parts.some(part => part === '..' || part.includes('\\') || part.includes('\0'))) {
+    throw new Error('DATA_DIR must remain inside the /mnt/data storage mount');
+  }
+  return parts;
+}
+
+/**
+ * Create the mount root and any configured DATA_DIR inside it, preserving state.
+ * Refuse child symlinks so initialization cannot write outside the storage root.
+ * @param {string} localPath - Host directory mounted at /mnt/data
+ * @param {string|undefined} envFile - Resolved application env file
+ * @returns {void}
+ */
+function prepareLocalDataMount(localPath, envFile) {
+  try {
+    const parts = dataDirectoryParts(envFile);
+    fs.mkdirSync(localPath, { recursive: true });
+    let directory = localPath;
+    for (const part of parts) {
+      directory = path.join(directory, part);
+      try {
+        const stat = fs.lstatSync(directory);
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+          throw new Error('DATA_DIR components must be directories, not symlinks or files');
+        }
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+        fs.mkdirSync(directory);
+      }
+    }
+  } catch (error) {
+    // Filesystem errors can include env content or paths; report only their code.
+    const reason = error.code || error.message;
+    throw new Error(`Unable to prepare local storage before container startup: ${reason}`);
+  }
+}
+
+module.exports = { prepareLocalDataMount };

package/lib/utils/resolve-docker-image-ref.js

@@ -148,16 +148,21 @@ function qualifyRepository(registry, repository) {
 }
 
 /**
- * Deployment/registration image reference (`registry/name:tag`) using the shared precedence.
+ * Deployment/registration image reference (`registry/name:tag`).
+ *
+ * Deliberately ignores the installation registry (`dev set-registry`): a generated manifest is a
+ * committed artifact shared by the team, so it must carry the application's own `image.registry`,
+ * not one developer's local default. `push` applies the installation registry when it publishes,
+ * and an explicit `options.registry` still wins here for CI that targets another registry.
  * @param {Object} variables - Application manifest
  * @param {string} fallbackName - Name when the manifest has no image name or app key
- * @param {Object} [options] - Same options as {@link resolveEffectiveRegistry}
+ * @param {Object} [options] - `registry` (explicit override only)
  * @returns {string}
  */
 function buildManifestImageReference(variables, fallbackName, options = {}) {
   const imageName = variables?.image?.name || variables?.app?.key || fallbackName;
   const tag = variables?.image?.tag || 'latest';
-  const { registry } = resolveEffectiveRegistry(variables, options);
+  const { registry } = resolveEffectiveRegistry(variables, { ...options, installationRegistry: '' });
   return `${qualifyRepository(registry, imageName)}:${tag}`;
 }
 

package/lib/utils/secrets-helpers.js

@@ -55,7 +55,6 @@ const { resolveBashKvFromProcessEnv } = require('./secrets-bash-kv');
 const EMPTY_ALLOWED_KV_FALLBACK = new Set([
   'redis-passwordKeyVault',
   'azure-openaiapi-urlKeyVault',
-  'secrets-azureOpenaiApiKeyVault',
   'miso-controller-secrets-apiKeyVault'
 ]);
 

package/lib/utils/system-secret-mapping.js

@@ -0,0 +1,125 @@
+/**
+ * Map an application's `.env` variables onto Miso catalog keys.
+ *
+ * The `.env` is keyed by environment variable (`MORI_POLICY_PRIVATE_KEY`) while the system
+ * secrets API is keyed by catalog key (`secrets-policyPrivateKeyVault`). The mapping is not
+ * invented here: it is read from the application's own `env.template`, because the
+ * `NAME=kv://<catalogKey>` line is already the declaration that decides where the value is
+ * read from at runtime. A second table in the CLI would be free to drift from it.
+ *
+ * A variable whose template line is not a `kv://` reference is ordinary configuration, not a
+ * secret, and is skipped rather than pushed.
+ *
+ * Note this is the flat `kv://<catalogKey>` form used by the Controller's system secrets.
+ * The Dataplane's credential store uses `kv://<systemKey>/<path>`; see
+ * `credential-secrets-env-kv.js` for that one. They are not interchangeable.
+ *
+ * @fileoverview env.template kv:// declarations → catalog keys
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** `NAME=value`, ignoring blank lines, comments and `export ` prefixes. */
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/;
+
+/**
+ * Strip surrounding quotes and trailing whitespace from an env value.
+ * @param {string} raw - Raw right-hand side
+ * @returns {string} Cleaned value
+ */
+function cleanValue(raw) {
+  const trimmed = String(raw === undefined || raw === null ? '' : raw).trim();
+  if (trimmed.length >= 2) {
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if ((first === '"' && last === '"') || (first === '\'' && last === '\'')) {
+      return trimmed.slice(1, -1);
+    }
+  }
+  return trimmed;
+}
+
+/**
+ * Parse `NAME=value` lines into a Map, last assignment winning.
+ * @param {string} content - File content
+ * @returns {Map<string, string>} Variable name → value
+ */
+function parseEnvAssignments(content) {
+  const out = new Map();
+  for (const line of String(content || '').split(/\r?\n/)) {
+    if (!line || /^\s*#/.test(line)) {
+      continue;
+    }
+    const match = line.match(ASSIGNMENT);
+    if (match) {
+      out.set(match[1], cleanValue(match[2]));
+    }
+  }
+  return out;
+}
+
+/**
+ * Catalog keys declared by an `env.template`, keyed by environment variable name.
+ * Only `kv://` lines are secrets; everything else is skipped.
+ * @param {string} templateContent - env.template content
+ * @returns {Map<string, string>} Variable name → catalog key
+ */
+function catalogKeysFromTemplate(templateContent) {
+  const out = new Map();
+  for (const [name, value] of parseEnvAssignments(templateContent)) {
+    if (!value.startsWith('kv://')) {
+      continue;
+    }
+    const catalogKey = value.slice('kv://'.length).trim();
+    if (catalogKey && !catalogKey.includes('/')) {
+      out.set(name, catalogKey);
+    }
+  }
+  return out;
+}
+
+/**
+ * Pair the values in a `.env` with the catalog keys its `env.template` declares.
+ *
+ * Skipped rows are returned rather than dropped, so the command can say why a variable was
+ * not pushed instead of silently ignoring it.
+ *
+ * @param {string} envContent - Operator's .env content
+ * @param {string} templateContent - The application's env.template content
+ * @param {Object} [options] - `only` restricts to one variable name
+ * @returns {{ pushable: Array<Object>, skipped: Array<Object> }} Rows carrying value and catalog key
+ */
+function mapEnvToCatalogKeys(envContent, templateContent, options = {}) {
+  const declared = catalogKeysFromTemplate(templateContent);
+  const values = parseEnvAssignments(envContent);
+  const only = options.only ? String(options.only).trim() : '';
+  const pushable = [];
+  const skipped = [];
+  for (const [name, value] of values) {
+    if (only && name !== only) {
+      continue;
+    }
+    const catalogKey = declared.get(name);
+    if (!catalogKey) {
+      skipped.push({ name, reason: 'not a kv:// reference in env.template' });
+      continue;
+    }
+    if (!value) {
+      skipped.push({ name, catalogKey, reason: 'no value in the env file' });
+      continue;
+    }
+    pushable.push({ name, catalogKey, value });
+  }
+  if (only && pushable.length === 0 && skipped.length === 0) {
+    skipped.push({ name: only, reason: 'not present in the env file' });
+  }
+  return { pushable, skipped };
+}
+
+module.exports = {
+  parseEnvAssignments,
+  catalogKeysFromTemplate,
+  mapEnvToCatalogKeys
+};

package/lib/utils/test-log-writer.js

@@ -9,6 +9,7 @@
 
 const fs = require('fs').promises;
 const path = require('path');
+const { sanitizeBinaryEvidence } = require('./datasource-binary-evidence');
 
 /**
  * Prepare object for JSON serialization (handles circular refs)
@@ -45,7 +46,7 @@ async function writeTestLog(appKey, data, logType = 'test-integration', integrat
   const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
   const filename = `${logType}-${timestamp}.json`;
   const filePath = path.join(logsDir, filename);
-  const sanitized = sanitizeForLog(data);
+  const sanitized = sanitizeForLog(sanitizeBinaryEvidence(data));
   await fs.writeFile(filePath, JSON.stringify(sanitized, null, 2), 'utf8');
   return filePath;
 }

package/lib/validation/external-manifest-validator.js

@@ -16,6 +16,7 @@ const path = require('path');
 const { formatValidationErrors } = require('../utils/error-formatter');
 const { validateFieldReferences } = require('../datasource/field-reference-validator');
 const { validateAbac } = require('../datasource/abac-validator');
+const { validateBinaryDocumentsContract } = require('../datasource/binary-documents-validator');
 const { validateManifestRuntimeConfiguration } = require('./runtime-configuration-rules');
 const { validateAppContractSurface } = require('./openapi-contract-surface-validator');
 
@@ -147,9 +148,13 @@ function validateDatasources(manifest, ajv, externalDatasourceSchema, errors, wa
         } else {
           const fieldRefErrors = validateFieldReferences(datasource);
           const abacErrors = validateAbac(datasource);
+          const binaryDocuments = validateBinaryDocumentsContract(datasource);
           const prefix = `Datasource ${index + 1} (${datasource.key || 'unknown'}): `;
           fieldRefErrors.forEach(e => errors.push(prefix + e));
           abacErrors.forEach(e => errors.push(prefix + e));
+          // Codes are the dataplane's, so the offline answer matches the upload answer.
+          binaryDocuments.errors.forEach(e => errors.push(`${prefix}${e.code}: ${e.message}`));
+          binaryDocuments.warnings.forEach(w => warnings.push(`${prefix}${w.code}: ${w.message}`));
         }
       });
     }

package/lib/validation/openapi-contract-surface-validator.js

@@ -426,5 +426,7 @@ module.exports = {
   validateDatasourceFileContractSurface,
   validateVendorOperationContract,
   validateServiceContractDatasourceContracts,
-  findVendorOperation
+  findVendorOperation,
+  resolveVendorOpenApiSpec,
+  inferIntegrationContextFromPath
 };

package/lib/validation/validate-external-file.js

@@ -111,11 +111,15 @@ function validateDatasourceFileExtras(parsed, filePath) {
   const { collectExternalDatasourceWarnings } = require('./datasource-warnings');
   const { validateDatasourceFileContractSurface } = require('./openapi-contract-surface-validator');
   const errors = [...validateFieldReferences(parsed), ...validateAbac(parsed)];
+  const { validateBinaryDocumentsContract } = require('../datasource/binary-documents-validator');
+  const binary = validateBinaryDocumentsContract(parsed);
+  errors.push(...binary.errors.map(issue => `${issue.code}: ${issue.message}`));
   const contractSurface = validateDatasourceFileContractSurface(parsed, filePath);
   errors.push(...contractSurface.errors);
   const warnings = [
     ...collectExternalDatasourceWarnings(parsed),
-    ...contractSurface.warnings
+    ...contractSurface.warnings,
+    ...binary.warnings.map(issue => `${issue.code}: ${issue.message}`)
   ];
   return { errors, warnings };
 }