@aifabrix/builder 2.44.5 → 2.44.6

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

package/lib/utils/health-check-db-init.js

@@ -0,0 +1,107 @@
+const chalk = require('chalk');
+const { formatSuccessLine } = require('./cli-test-layout-chalk');
+const logger = require('./logger');
+const { execWithDockerEnv } = require('./docker-exec');
+
+/**
+ * Checks if db-init container exists.
+ * @async
+ * @param {string} dbInitContainer
+ * @returns {Promise<boolean>}
+ */
+async function checkDbInitContainerExists(dbInitContainer) {
+  try {
+    const { stdout } = await execWithDockerEnv(
+      `docker ps -a --filter "name=${dbInitContainer}" --format "{{.Names}}"`
+    );
+    return stdout.trim() === dbInitContainer;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Gets container exit code.
+ * @async
+ * @param {string} dbInitContainer
+ * @returns {Promise<string>}
+ */
+async function getContainerExitCode(dbInitContainer) {
+  const { stdout: exitCode } = await execWithDockerEnv(
+    `docker inspect --format='{{.State.ExitCode}}' ${dbInitContainer}`
+  );
+  return exitCode.trim();
+}
+
+/**
+ * Handles exited container status.
+ * @async
+ * @param {string} dbInitContainer
+ * @returns {Promise<boolean>}
+ */
+async function handleExitedContainer(dbInitContainer) {
+  const { stdout: status } = await execWithDockerEnv(
+    `docker inspect --format='{{.State.Status}}' ${dbInitContainer}`
+  );
+  if (status.trim() === 'exited') {
+    const exitCode = await getContainerExitCode(dbInitContainer);
+    if (exitCode === '0') {
+      logger.log(formatSuccessLine('Database initialization already completed'));
+    } else {
+      logger.log(chalk.yellow(`⚠ Database initialization exited with code ${exitCode}`));
+    }
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Waits for container to exit (best-effort).
+ * @async
+ * @param {string} dbInitContainer
+ * @param {number} maxAttempts
+ * @returns {Promise<void>}
+ */
+async function waitForContainerExit(dbInitContainer, maxAttempts) {
+  for (let attempts = 0; attempts < maxAttempts; attempts++) {
+    const { stdout: currentStatus } = await execWithDockerEnv(
+      `docker inspect --format='{{.State.Status}}' ${dbInitContainer}`
+    );
+    if (currentStatus.trim() === 'exited') {
+      const exitCode = await getContainerExitCode(dbInitContainer);
+      if (exitCode === '0') {
+        logger.log(formatSuccessLine('Database initialization completed'));
+      } else {
+        logger.log(chalk.yellow(`⚠ Database initialization exited with code ${exitCode}`));
+      }
+      return;
+    }
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+}
+
+/**
+ * Checks if db-init container exists and waits for it to complete.
+ * @async
+ * @param {string} appName
+ * @returns {Promise<void>}
+ */
+async function waitForDbInit(appName) {
+  const dbInitContainer = `aifabrix-${appName}-db-init`;
+  try {
+    if (!(await checkDbInitContainerExists(dbInitContainer))) {
+      return;
+    }
+
+    if (await handleExitedContainer(dbInitContainer)) {
+      return;
+    }
+
+    logger.log(chalk.blue('Waiting for database initialization to complete...'));
+    await waitForContainerExit(dbInitContainer, 30);
+  } catch {
+    // db-init container might not exist, which is fine
+  }
+}
+
+module.exports = { waitForDbInit };

package/lib/utils/health-check-public-warn.js

@@ -0,0 +1,69 @@
+/**
+ * Post-success warnings when public/Traefik health URL was skipped or not verified.
+ *
+ * @fileoverview Split from health-check.js for file size limits
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+
+/**
+ * When Traefik URL is set, drop it if the hostname does not resolve; retain full URL for UX.
+ *
+ * @param {string} traefikUrl
+ * @param {boolean} debug
+ * @param {Function} isHostnameResolvableFn - (hostname, debug) => Promise<boolean>
+ * @returns {Promise<{ traefikUrl: string, skippedPublicHealthUrl: string }>}
+ */
+async function filterTraefikUrlByDns(traefikUrl, debug, isHostnameResolvableFn) {
+  if (!traefikUrl) {
+    return { traefikUrl: '', skippedPublicHealthUrl: '' };
+  }
+  try {
+    const hn = new URL(traefikUrl).hostname;
+    const ok = await isHostnameResolvableFn(hn, debug);
+    if (!ok) {
+      return { traefikUrl: '', skippedPublicHealthUrl: traefikUrl };
+    }
+  } catch {
+    return { traefikUrl: '', skippedPublicHealthUrl: '' };
+  }
+  return { traefikUrl, skippedPublicHealthUrl: '' };
+}
+
+/**
+ * @param {Object} p
+ * @param {string} [p.skippedPublicHealthUrl]
+ * @param {string[]} [p.urlsToTry]
+ * @param {number} p.resolvedIndex
+ */
+function logPublicHealthUrlWarningIfNeeded(p) {
+  const { skippedPublicHealthUrl, urlsToTry, resolvedIndex } = p;
+  if (typeof resolvedIndex !== 'number' || resolvedIndex < 0) return;
+
+  if (skippedPublicHealthUrl) {
+    logger.log(
+      chalk.yellow(
+        `⚠ Public URL was not verified (DNS): ${skippedPublicHealthUrl}. ` +
+          'The application reported healthy via localhost only. Validate DNS names and Traefik routing for this host.'
+      )
+    );
+    return;
+  }
+  if (Array.isArray(urlsToTry) && urlsToTry.length > 1 && resolvedIndex > 0) {
+    const pub = urlsToTry[0];
+    logger.log(
+      chalk.yellow(
+        `⚠ Public URL was not verified: ${pub}. ` +
+          'Health checks succeeded via localhost only. Validate Traefik routing, TLS, and DNS.'
+      )
+    );
+  }
+}
+
+module.exports = {
+  filterTraefikUrlByDns,
+  logPublicHealthUrlWarningIfNeeded
+};

package/lib/utils/health-check-url.js

@@ -73,7 +73,16 @@ function frontDoorPattern(appConfig) {
  * @param {Object|null} appConfig
  * @returns {Promise<string|null>}
  */
-async function computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig) {
+/**
+ * Public app URL (Traefik + frontDoor mount path), without the health path — for CLI summaries.
+ *
+ * @async
+ * @param {string} appName
+ * @param {number} healthCheckPort
+ * @param {Object|null} appConfig
+ * @returns {Promise<string|null>}
+ */
+async function computeTraefikPublicAppUrl(_appName, _healthCheckPort, appConfig) {
   if (!frontDoorEnabled(appConfig)) return null;
   const pattern = frontDoorPattern(appConfig);
   if (!pattern) return null;
@@ -87,7 +96,7 @@ async function computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig)
   const developerIdRaw = await coreConfig.getDeveloperId();
   const developerIdNum = parseDeveloperIdNum(developerIdRaw);
 
-  // Health checks originate from the CLI on the host, not from inside a container.
+  // URLs are resolved for the CLI on the host, not from inside a container.
   const profile = 'local';
   const fd = appConfig.frontDoorRouting;
   const listenPort = Number(appConfig?.port || 3000);
@@ -105,15 +114,21 @@ async function computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig)
     infraTlsEnabled
   });
 
-  const healthCheckPath = appConfig?.healthCheck?.path || '/health';
   const mountPath = normalizeFrontDoorPatternForHealth(pattern);
-  const baseWithFrontDoor = joinUrlPath(publicBase, mountPath);
+  return joinUrlPath(publicBase, mountPath);
+}
+
+async function computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig) {
+  const baseWithFrontDoor = await computeTraefikPublicAppUrl(appName, healthCheckPort, appConfig);
+  if (!baseWithFrontDoor) return null;
+  const healthCheckPath = appConfig?.healthCheck?.path || '/health';
   return joinUrlPath(baseWithFrontDoor, healthCheckPath);
 }
 
 module.exports = {
   joinUrlPath,
   normalizeFrontDoorPatternForHealth,
+  computeTraefikPublicAppUrl,
   computeTraefikHealthCheckUrl
 };