@aifabrix/builder 2.44.5 → 2.45.0

package/lib/utils/env-copy.js

@@ -11,6 +11,7 @@ const { formatSuccessLine } = require('./cli-test-layout-chalk');
 
 const fs = require('fs');
 const fsp = require('fs').promises;
+const fsRealSync = require('../internal/fs-real-sync');
 const path = require('path');
 const yaml = require('js-yaml');
 const logger = require('./logger');
@@ -98,22 +99,37 @@ function resolveEnvOutputPath(rawOutputPath, variablesPath) {
 }
 
 /**
- * Writes .env to envOutputPath for reload path: merge run .env into existing file.
+ * 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
+ * in `.env.run` (compose-only such as DB_0_NAME) are **not** appended unless they already exist as
+ * `KEY=` lines in the base file. If the output file is missing, seeds from `generateEnvContent`
+ * (`local`) so the host file keeps template comments and localhost-oriented URLs.
+ *
  * @async
  * @param {string} outputPath - Resolved output path
  * @param {string} runEnvPath - Path to .env.run
+ * @param {string} appName - Application name (for template seed when output is absent)
  */
-async function writeEnvOutputForReload(outputPath, runEnvPath) {
-  const { parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
+async function writeEnvOutputForReload(outputPath, runEnvPath, appName) {
+  const { parseEnvContentToMap, mergeEnvMapIntoContent, generateEnvContent } = require('../core/secrets');
   const runContent = await fsp.readFile(runEnvPath, 'utf8');
   const runMap = parseEnvContentToMap(runContent);
-  let toWrite = runContent;
-  if (fs.existsSync(outputPath)) {
-    const existingContent = await fsp.readFile(outputPath, 'utf8');
-    toWrite = mergeEnvMapIntoContent(existingContent, runMap);
+  let baseContent;
+  if (fsRealSync.existsSync(outputPath)) {
+    baseContent = await fsp.readFile(outputPath, 'utf8');
+  } else if (appName) {
+    baseContent = await generateEnvContent(appName, null, 'local', false);
+    baseContent = substituteMntDataForLocal(baseContent, outputPath);
+  } else {
+    baseContent = runContent;
   }
+  const toWrite = mergeEnvMapIntoContent(baseContent, runMap, { appendMissingFromNewMap: false });
   await fsp.writeFile(outputPath, toWrite, { mode: 0o600 });
-  logger.log(formatSuccessLine(`Wrote .env to envOutputPath (same as container, for --reload): ${outputPath}`));
+  logger.log(
+    formatSuccessLine(
+      `Wrote .env to envOutputPath (--reload: merged container env; no extra keys): ${outputPath}`
+    )
+  );
 }
 
 /**
@@ -245,6 +261,30 @@ async function patchEnvContentForLocal(envContent, variables) {
   return envContent;
 }
 
+/**
+ * Copy the just-written builder `<appPath>/.env` to `build.envOutputPath` so both files
+ * share the same resolution pass (no second `generateEnvContent` with a different environment).
+ * Applies {@link substituteMntDataForLocal} for host paths; merges into an existing output file
+ * when present (preserves comments).
+ *
+ * @async
+ * @param {string} envPath - Path to `<appPath>/.env` (already written)
+ * @param {string} outputPath - Resolved `build.envOutputPath`
+ * @param {string} envOutputPathLabel - Label for log (e.g. raw `build.envOutputPath` value)
+ */
+async function syncWrittenBuilderEnvToOutputPath(envPath, outputPath, envOutputPathLabel) {
+  const { parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
+  const raw = fs.readFileSync(envPath, 'utf8');
+  const synced = substituteMntDataForLocal(raw, outputPath);
+  let toWrite = synced;
+  if (fs.existsSync(outputPath)) {
+    const existingContent = fs.readFileSync(outputPath, 'utf8');
+    toWrite = mergeEnvMapIntoContent(existingContent, parseEnvContentToMap(synced));
+  }
+  fs.writeFileSync(outputPath, toWrite, { mode: 0o600 });
+  logger.log(formatSuccessLine(`Copied resolved .env to envOutputPath (${envOutputPathLabel})`));
+}
+
 /**
  * Write regenerated local .env to output path (merge with existing if present).
  * @async
@@ -252,10 +292,12 @@ async function patchEnvContentForLocal(envContent, variables) {
  * @param {string} appName - Application name
  * @param {string} [secretsPath] - Path to secrets file (optional)
  * @param {string} envOutputPathLabel - Label for log message (e.g. variables.build.envOutputPath)
+ * @param {Object} [extraOpts] - Optional: `appPath` for {@link module:lib/core/secrets-env-content.generateEnvContent}
  */
-async function writeLocalEnvToOutputPath(outputPath, appName, secretsPath, envOutputPathLabel) {
+async function writeLocalEnvToOutputPath(outputPath, appName, secretsPath, envOutputPathLabel, extraOpts = {}) {
   const { generateEnvContent, parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
-  let localEnvContent = await generateEnvContent(appName, secretsPath, 'local', false);
+  const genOpts = extraOpts.appPath ? { appPath: extraOpts.appPath } : {};
+  let localEnvContent = await generateEnvContent(appName, secretsPath, 'local', false, genOpts);
   localEnvContent = substituteMntDataForLocal(localEnvContent, outputPath);
   let toWrite = localEnvContent;
   if (fs.existsSync(outputPath)) {
@@ -284,16 +326,45 @@ async function writePatchedEnvToOutputPath(envPath, outputPath, variables, envOu
 }
 
 /**
- * Process and optionally copy env file to envOutputPath if configured
- * Regenerates .env file with env=local for local development (apps/.env)
+ * Process and optionally copy env file to envOutputPath if configured.
+ * When `appName` is set and `preferLocalEnvOutputPath` is true, regenerates **local**-flavored env at
+ * `build.envOutputPath` (IDE/host). **False** only when `remote-server` and `applications.<app>.reload` are both set
+ * (docker flavor at env output). Otherwise, when `appName`
+ * is set and `envPath` exists, copies the same resolved `<appPath>/.env` content to the output path.
+ * Falls back to local regeneration when `envPath` is missing, or patched copy when `appName` is omitted.
+ *
  * @async
  * @function processEnvVariables
  * @param {string} envPath - Path to generated .env file
  * @param {string} variablesPath - Path to application config
  * @param {string} appName - Application name (for regenerating with local env)
  * @param {string} [secretsPath] - Path to secrets file (optional, for regenerating)
+ * @param {Object} [copyOptions] - Optional: `preferLocalEnvOutputPath` (IDE/host file gets **local** flavor
+ *   while `<appPath>/.env` may be docker); `appPath` overrides app root for local regeneration
  */
-async function processEnvVariables(envPath, variablesPath, appName, secretsPath) {
+async function copyOrRegenerateEnvForNamedApp(opts) {
+  const {
+    envPath,
+    outputPath,
+    appName,
+    secretsPath,
+    label,
+    preferLocal,
+    appPathForLocal
+  } = opts;
+  const localOpts = { appPath: appPathForLocal || undefined };
+  if (preferLocal) {
+    await writeLocalEnvToOutputPath(outputPath, appName, secretsPath, label, localOpts);
+    return;
+  }
+  if (fs.existsSync(envPath)) {
+    await syncWrittenBuilderEnvToOutputPath(envPath, outputPath, label);
+    return;
+  }
+  await writeLocalEnvToOutputPath(outputPath, appName, secretsPath, label, localOpts);
+}
+
+async function processEnvVariables(envPath, variablesPath, appName, secretsPath, copyOptions = {}) {
   if (!variablesPath || !fs.existsSync(variablesPath)) {
     return;
   }
@@ -310,8 +381,21 @@ async function processEnvVariables(envPath, variablesPath, appName, secretsPath)
   }
 
   const label = variables.build.envOutputPath;
+  const appPathForLocal =
+    (copyOptions && copyOptions.appPath) ||
+    (variablesPath ? path.dirname(variablesPath) : null);
+  const preferLocal =
+    copyOptions && typeof copyOptions === 'object' && copyOptions.preferLocalEnvOutputPath === true;
   if (appName) {
-    await writeLocalEnvToOutputPath(outputPath, appName, secretsPath, label);
+    await copyOrRegenerateEnvForNamedApp({
+      envPath,
+      outputPath,
+      appName,
+      secretsPath,
+      label,
+      preferLocal,
+      appPathForLocal
+    });
   } else {
     await writePatchedEnvToOutputPath(envPath, outputPath, variables, label);
   }
@@ -321,6 +405,7 @@ module.exports = {
   processEnvVariables,
   resolveEnvOutputPath,
   substituteMntDataForLocal,
+  syncWrittenBuilderEnvToOutputPath,
   writeEnvOutputForReload,
   writeEnvOutputForLocal
 };

package/lib/utils/env-template.js

@@ -13,6 +13,7 @@ const fsSync = require('fs');
 const path = require('path');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
+const pathsUtil = require('./paths');
 
 /**
  * Updates env.template to add MISO_CLIENTID, MISO_CLIENTSECRET, and optionally MISO_CONTROLLER_URL.
@@ -105,7 +106,10 @@ ${missingEntries.join('\n')}
 }
 
 async function updateEnvTemplate(appKey, clientIdKey, clientSecretKey, _controllerUrl) {
-  const envTemplatePath = path.join(process.cwd(), 'builder', appKey, 'env.template');
+  // Use paths.getBuilderPath so the system builder root (e.g. ~/.aifabrix/builder/<app>) and
+  // AIFABRIX_BUILDER_DIR are respected. Falling back to process.cwd() previously made the binary
+  // CLI skip env.template updates whenever cwd was a non-builder repo (e.g. aifabrix-training).
+  const envTemplatePath = path.join(pathsUtil.getBuilderPath(appKey), 'env.template');
 
   if (!fsSync.existsSync(envTemplatePath)) {
     logger.warn(chalk.yellow(`⚠  env.template not found for ${appKey}, skipping update`));

package/lib/utils/external-readme.js

@@ -15,6 +15,72 @@ const path = require('path');
 const handlebars = require('handlebars');
 const { getProjectRoot } = require('./paths');
 
+/**
+ * Extracts secret keys from integration/<appName>/env.template when present.
+ * Looks for values like `kv://systemKey/apiKey` and returns that key for
+ * `aifabrix secret set <key> <value>`.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.appName
+ * @returns {Array<{path: string, description: string}>}
+ */
+function extractSecretPathsFromEnvTemplate({ projectRoot, appName }) {
+  if (!projectRoot || !appName) return [];
+
+  const envTemplatePath = path.join(projectRoot, 'integration', appName, 'env.template');
+  if (!fs.existsSync(envTemplatePath)) return [];
+
+  const raw = _tryReadTextOrNull(envTemplatePath);
+  if (raw === null) return [];
+  if (typeof raw !== 'string') return [];
+
+  function parseSecretKey(value) {
+    if (!value || typeof value !== 'string') return null;
+    const kvIdx = value.indexOf('kv://');
+    if (kvIdx === -1) return null;
+    const after = value.slice(kvIdx + 'kv://'.length);
+    const key = after.split(/[ \t#]/)[0]?.trim();
+    return key || null;
+  }
+
+  function parseLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) return null;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx <= 0) return null;
+    const varName = trimmed.slice(0, eqIdx).trim();
+    const value = trimmed.slice(eqIdx + 1).trim();
+    const key = parseSecretKey(value);
+    if (!key) return null;
+    return { varName: varName || 'Secret', key };
+  }
+
+  const out = [];
+  const seen = new Set();
+
+  for (const line of raw.split('\n')) {
+    const parsed = parseLine(line);
+    if (!parsed) continue;
+    const dedupeKey = `${parsed.varName}::${parsed.key}`;
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    out.push({ path: parsed.key, description: parsed.varName });
+  }
+
+  return out;
+}
+
+function _tryReadTextOrNull(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch (e) {
+    // Some Jest suites partially mock fs.existsSync; treat missing files as absent templates.
+    if (e && e.code === 'ENOENT') return null;
+    throw e;
+  }
+}
+
 /**
  * Formats a display name from a key
  * @param {string} key - System or app key
@@ -179,7 +245,9 @@ function buildExternalReadmeContext(params = {}) {
   const normalizedExt = fileExt && fileExt.startsWith('.') ? fileExt : `.${fileExt || 'json'}`;
   const datasources = normalizeDatasources(params.datasources, systemKey, fileExt);
   const authType = params.authType || params.authentication?.type || params.authentication?.method || params.authentication?.authType;
-  const secretPaths = buildSecretPaths(systemKey, authType);
+  const projectRoot = getProjectRoot();
+  const secretPathsFromEnv = extractSecretPathsFromEnvTemplate({ projectRoot, appName });
+  const secretPaths = secretPathsFromEnv.length > 0 ? secretPathsFromEnv : buildSecretPaths(systemKey, authType);
   const rbacOptionalFile = rbacOptionalFilename(normalizedExt);
 
   return {
@@ -238,5 +306,6 @@ module.exports = {
   buildExternalReadmeContext,
   generateExternalReadmeContent,
   wrapPlainTextForMarkdown,
-  collapseConsecutiveBlankLines
+  collapseConsecutiveBlankLines,
+  extractSecretPathsFromEnvTemplate
 };

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

@@ -19,6 +19,7 @@ const {
   headerKeyValue,
   formatStatusKeyValue,
   colorRollupPrefixedLine,
+  formatSuccessLine,
   metadata: metaGray
 } = require('./cli-test-layout-chalk');
 
@@ -338,7 +339,7 @@ function displayLocalExternalTestPlanLayout(results, verbose, appName) {
 function logVerboseSystemRows(systemResults) {
   for (const s of systemResults || []) {
     const ok = s.valid;
-    logger.log(ok ? chalk.green(`  ✔ ${s.file}`) : chalk.red(`  ✖ ${s.file}`));
+    logger.log(ok ? (chalk.green('  ') + formatSuccessLine(s.file)) : chalk.red(`  ✖ ${s.file}`));
     (s.errors || []).forEach(e => logger.log(chalk.red(`    - ${e}`)));
   }
 }
@@ -346,7 +347,7 @@ function logVerboseSystemRows(systemResults) {
 function logVerboseDatasourceRows(datasourceResults) {
   for (const d of datasourceResults || []) {
     const ok = d.valid;
-    logger.log(ok ? chalk.green(`  ✔ ${d.key} (${d.file})`) : chalk.red(`  ✖ ${d.key} (${d.file})`));
+    logger.log(ok ? (chalk.green('  ') + formatSuccessLine(`${d.key} (${d.file})`)) : chalk.red(`  ✖ ${d.key} (${d.file})`));
     (d.errors || []).forEach(e => logger.log(chalk.red(`    - ${e}`)));
     (d.warnings || []).forEach(w => logger.log(chalk.yellow(`    ⚠ ${w}`)));
     if (d.fieldMappingResults && d.fieldMappingResults.mappedFields) {

package/lib/utils/external-system-readiness-core.js

@@ -43,30 +43,57 @@ function unwrapPublicationResult(res) {
  * Rules: inactive/archived → Failed; MCP expected but missing → Partial; draft → Partial; published/deployed + active → Ready.
  * @param {Object} ds - ExternalDataSourceResponse-like
  * @param {boolean} generateMcpContract - From application config
- * @returns {'ready'|'partial'|'failed'}
+ * @returns {{ tier: 'ready'|'partial'|'failed', partialReason: string|null }}
  */
-function classifyDatasourceTierA(ds, generateMcpContract) {
+function classifyDatasourceTierADetail(ds, generateMcpContract) {
   const active = ds.isActive !== false;
   const status = String(ds.status || '').toLowerCase();
   if (!active || status === 'archived') {
-    return 'failed';
+    return { tier: 'failed', partialReason: null };
   }
   if (generateMcpContract === true && !ds.mcpContract) {
-    return 'partial';
+    return { tier: 'partial', partialReason: 'mcp_missing' };
   }
   if (status === 'draft') {
-    return 'partial';
+    return { tier: 'partial', partialReason: 'draft' };
   }
   if (status === 'published' || status === 'deployed') {
-    return 'ready';
+    return { tier: 'ready', partialReason: null };
+  }
+  return { tier: 'partial', partialReason: 'unknown_status' };
+}
+
+/**
+ * @param {Object} ds - ExternalDataSourceResponse-like
+ * @param {boolean} generateMcpContract - From application config
+ * @returns {'ready'|'partial'|'failed'}
+ */
+function classifyDatasourceTierA(ds, generateMcpContract) {
+  return classifyDatasourceTierADetail(ds, generateMcpContract).tier;
+}
+
+/**
+ * Short hint for CLI when Tier A is partial (machine codes from classifyDatasourceTierADetail).
+ * @param {string|null} partialReason
+ * @returns {string}
+ */
+function formatTierAPartialHint(partialReason) {
+  if (partialReason === 'mcp_missing') {
+    return 'no MCP contract stored (OpenAPI link or generation)';
+  }
+  if (partialReason === 'draft') {
+    return 'status draft (trigger paths / certification gate)';
   }
-  return 'partial';
+  if (partialReason === 'unknown_status') {
+    return 'unexpected lifecycle status';
+  }
+  return '';
 }
 
 /**
  * @param {Array<Object>} datasources - Datasource list
  * @param {boolean} generateMcpContract
- * @returns {{ rows: Array<{ key: string, tier: string }>, ready: number, partial: number, failed: number }}
+ * @returns {{ rows: Array<{ key: string, tier: string, partialReason?: string|null }>, ready: number, partial: number, failed: number }}
  */
 function summarizeDatasourceTiersA(datasources, generateMcpContract) {
   const rows = [];
@@ -75,10 +102,14 @@ function summarizeDatasourceTiersA(datasources, generateMcpContract) {
   let failed = 0;
   for (const ds of datasources || []) {
     const key = ds.key || ds.sourceKey || 'unknown';
-    const tier = classifyDatasourceTierA(ds, generateMcpContract);
-    rows.push({ key, tier });
-    if (tier === 'ready') ready += 1;
-    else if (tier === 'partial') partial += 1;
+    const detail = classifyDatasourceTierADetail(ds, generateMcpContract);
+    const row = { key, tier: detail.tier };
+    if (detail.tier === 'partial' && detail.partialReason) {
+      row.partialReason = detail.partialReason;
+    }
+    rows.push(row);
+    if (detail.tier === 'ready') ready += 1;
+    else if (detail.tier === 'partial') partial += 1;
     else failed += 1;
   }
   return { rows, ready, partial, failed };
@@ -401,7 +432,9 @@ module.exports = {
   unwrapApiData,
   unwrapPublicationResult,
   isPublicationResultShape,
+  classifyDatasourceTierADetail,
   classifyDatasourceTierA,
+  formatTierAPartialHint,
   summarizeDatasourceTiersA,
   aggregateVerdictFromCounts,
   classifyDatasourceTierB,

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

@@ -83,7 +83,7 @@ function logDeployProbeDatasourceSection(probeData) {
  * @param {Object|null} systemFromDataplane
  * @param {boolean} genMcp
  */
-function logDeployContractsSection(systemFromDataplane, genMcp) {
+function logDeployContractsSection(systemFromDataplane, genMcp, dataplaneUrl, systemKey) {
   if (!systemFromDataplane) return;
   logSeparator();
   logSectionTitle('Contracts:');
@@ -94,7 +94,7 @@ function logDeployContractsSection(systemFromDataplane, genMcp) {
   } else {
     logger.log(chalk.gray('○ OpenAPI docs URL not available'));
   }
-  logDocsBlock(systemFromDataplane);
+  logDocsBlock(systemFromDataplane, { dataplaneUrl, systemKey, genMcp: mcpOk });
 }
 
 /**
@@ -260,7 +260,7 @@ function logDeployReadinessSummary(ctx) {
 
   logDeployIdentityAndCredentialBlocks(systemCfg, !!probeData);
 
-  logDeployContractsSection(systemFromDataplane, genMcp);
+  logDeployContractsSection(systemFromDataplane, genMcp, dataplaneUrl, systemKey);
   logDeployNextActionsSection(systemKey, probeData, summary, genMcp);
 }
 

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

@@ -9,7 +9,11 @@
 const chalk = require('chalk');
 const { failureGlyph, successGlyph } = require('./cli-test-layout-chalk');
 const logger = require('./logger');
-const { extractIdentitySummary, resolveCredentialTestEndpointDisplay } = require('./external-system-readiness-core');
+const {
+  extractIdentitySummary,
+  resolveCredentialTestEndpointDisplay,
+  formatTierAPartialHint
+} = require('./external-system-readiness-core');
 
 const SEP = chalk.gray('────────────────────────────────');
 
@@ -56,8 +60,12 @@ function logDatasourceTable(rows, counts, title) {
   logSectionTitle(title && String(title).trim() ? String(title).trim() : 'Datasources:');
   for (const r of rows) {
     const statusLabel = r.tier === 'ready' ? 'Ready' : r.tier === 'failed' ? 'Failed' : 'Partial';
+    const hint =
+      r.tier === 'partial' && r.partialReason
+        ? chalk.gray(` — ${formatTierAPartialHint(r.partialReason)}`)
+        : '';
     logger.log(
-      `${tierGlyph(r.tier)} ${r.key.padEnd(14, ' ')} ${chalk.gray('(' + statusLabel + ')')}`
+      `${tierGlyph(r.tier)} ${r.key.padEnd(14, ' ')} ${chalk.gray('(' + statusLabel + ')')}${hint}`
     );
   }
   logger.log('');
@@ -120,14 +128,35 @@ function logNextActions(actions, extraLine) {
   }
 }
 
+/**
+ * Dataplane serves MCP OpenAPI docs at /api/v1/mcp/{systemKey}/docs.
+ *
+ * @param {Object} sys - ExternalSystemResponse
+ * @param {{ dataplaneUrl?: string, systemKey?: string, genMcp?: boolean }} [opts]
+ * @returns {string|null}
+ */
+function deriveMcpDocsPageUrl(sys, opts) {
+  if (!sys || !opts) return null;
+  if (sys.mcpDocsPageUrl) return String(sys.mcpDocsPageUrl);
+  const { dataplaneUrl, systemKey, genMcp } = opts;
+  if (!genMcp || !dataplaneUrl || !systemKey) return null;
+  if (!sys.mcpServerUrl) return null;
+  if (!sys.openApiDocsPageUrl && !sys.apiDocumentUrl) return null;
+  const base = String(dataplaneUrl).replace(/\/+$/, '');
+  return `${base}/api/v1/mcp/${encodeURIComponent(systemKey)}/docs`;
+}
+
 /**
  * @param {Object} sys - ExternalSystemResponse
+ * @param {{ dataplaneUrl?: string, systemKey?: string, genMcp?: boolean }} [opts]
  */
-function logDocsBlock(sys) {
+function logDocsBlock(sys, opts) {
   if (!sys) return;
   const urls = [];
   if (sys.openApiDocsPageUrl) urls.push({ label: 'OpenAPI Docs Page', url: sys.openApiDocsPageUrl });
   if (sys.apiDocumentUrl) urls.push({ label: 'API Docs', url: sys.apiDocumentUrl });
+  const mcpDocs = deriveMcpDocsPageUrl(sys, opts);
+  if (mcpDocs) urls.push({ label: 'MCP Docs Page', url: mcpDocs });
   if (sys.mcpServerUrl) urls.push({ label: 'MCP Server', url: sys.mcpServerUrl });
   if (urls.length === 0) return;
   logSeparator();
@@ -147,5 +176,6 @@ module.exports = {
   logIdentityBlock,
   logCredentialIntentBlock,
   logNextActions,
+  deriveMcpDocsPageUrl,
   logDocsBlock
 };

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

@@ -44,7 +44,16 @@ function logPublishResultBlock(publication) {
   }
   logSeparator();
   logSectionTitle('MCP Contract:');
-  logger.log(genMcp ? formatSuccessLine('Generated') : chalk.gray('○ Not requested (generateMcpContract false)'));
+  if (genMcp) {
+    logger.log(formatSuccessLine('Generation requested (manifest generateMcpContract)'));
+    logger.log(
+      chalk.gray(
+        '  Per-datasource MCP appears when dataplane stores mcpContract (OpenAPI resolves + generation succeeds).'
+      )
+    );
+  } else {
+    logger.log(chalk.gray('○ Not requested (generateMcpContract false)'));
+  }
 }
 
 /**

package/lib/utils/file-upload.js

@@ -33,10 +33,10 @@ async function validateFileExists(filePath) {
  * @param {Object} additionalFields - Additional fields
  * @returns {Promise<FormData>} FormData object
  */
-async function buildFormData(filePath, fieldName, additionalFields) {
+async function buildFormData(filePath, fieldName, additionalFields, opts = {}) {
   const formData = new FormData();
   const fileContent = await fs.readFile(filePath);
-  const fileName = path.basename(filePath);
+  const fileName = opts.filenameOverride ? String(opts.filenameOverride) : path.basename(filePath);
   const fileBlob = new Blob([fileContent], { type: 'application/octet-stream' });
   formData.append(fieldName, fileBlob, fileName);
 
@@ -74,6 +74,43 @@ async function uploadFile(url, filePath, fieldName = 'file', authConfig = {}, ad
   return await client.postFormData(endpointPath, formData);
 }
 
+/**
+ * Upload a file using multipart/form-data but override the filename sent to the server.
+ * Useful when the server derives a key from the upload filename.
+ *
+ * @async
+ * @function uploadFileAs
+ * @param {string} url - Full API endpoint URL
+ * @param {string} filePath - Path to file to upload
+ * @param {string} filenameOverride - Filename to present to server (e.g. 'my-key.json')
+ * @param {string} fieldName - Form field name for the file (default: 'file')
+ * @param {Object} [authConfig] - Authentication configuration
+ * @param {Object} [additionalFields] - Additional form fields to include
+ * @returns {Promise<Object>} API response
+ */
+async function uploadFileAs(
+  url,
+  filePath,
+  filenameOverride,
+  fieldName = 'file',
+  authConfig = {},
+  additionalFields = {}
+) {
+  await validateFileExists(filePath);
+  if (!filenameOverride || typeof filenameOverride !== 'string') {
+    throw new Error('filenameOverride is required and must be a string');
+  }
+
+  const parsed = new URL(url);
+  const baseUrl = parsed.origin;
+  const endpointPath = parsed.pathname + parsed.search;
+
+  const formData = await buildFormData(filePath, fieldName, additionalFields, { filenameOverride });
+  const client = new ApiClient(baseUrl, authConfig);
+  return await client.postFormData(endpointPath, formData);
+}
+
 module.exports = {
-  uploadFile
+  uploadFile,
+  uploadFileAs
 };