@aifabrix/builder 2.42.1 → 2.44.0

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

@@ -0,0 +1,150 @@
+/**
+ * Shared chalk helpers for external system readiness CLI blocks.
+ *
+ * @fileoverview Internals for upload and deploy readiness display
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+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 SEP = chalk.gray('────────────────────────────────');
+
+/**
+ * @param {string} title
+ */
+function logSectionTitle(title) {
+  logger.log('');
+  logger.log(chalk.bold(title));
+}
+
+function logSeparator() {
+  logger.log('');
+  logger.log(SEP);
+}
+
+/**
+ * @param {'ready'|'partial'|'failed'} tier
+ * @returns {string}
+ */
+function tierGlyph(tier) {
+  if (tier === 'ready') return successGlyph();
+  if (tier === 'failed') return failureGlyph();
+  return chalk.yellow('⚠');
+}
+
+/**
+ * @param {'READY'|'PARTIAL'|'FAILED'} v
+ * @returns {string}
+ */
+function verdictLine(v) {
+  const label = chalk.bold('System Readiness: ');
+  if (v === 'READY') return label + chalk.green('READY');
+  if (v === 'FAILED') return label + chalk.red('FAILED');
+  return label + chalk.yellow('PARTIAL');
+}
+
+/**
+ * @param {Array<{ key: string, tier: string }>} rows
+ * @param {{ ready: number, partial: number, failed: number }} counts
+ */
+function logDatasourceTable(rows, counts) {
+  logSectionTitle('Datasources:');
+  for (const r of rows) {
+    const statusLabel = r.tier === 'ready' ? 'Ready' : r.tier === 'failed' ? 'Failed' : 'Partial';
+    logger.log(
+      `${tierGlyph(r.tier)} ${r.key.padEnd(14, ' ')} ${chalk.gray('(' + statusLabel + ')')}`
+    );
+  }
+  logger.log('');
+  logger.log(
+    chalk.gray('Summary:') +
+      ` ${chalk.green('Ready: ' + counts.ready)} · ${chalk.yellow('Partial: ' + counts.partial)} · ${chalk.red('Failed: ' + counts.failed)}`
+  );
+}
+
+/**
+ * @param {Object} system - manifest.system
+ */
+function logIdentityBlock(system) {
+  const { mode, attribution, tokenBroker } = extractIdentitySummary(system || {});
+  logSectionTitle('Identity:');
+  logger.log(`${chalk.gray('Mode:')} ${mode}`);
+  const attrColor = attribution === 'enabled' ? chalk.white : chalk.yellow;
+  logger.log(`${chalk.gray('Attribution:')} ${attrColor(attribution)}`);
+  logger.log(`${chalk.gray('Token broker:')} ${tokenBroker === 'configured' ? chalk.white(tokenBroker) : chalk.gray(tokenBroker)}`);
+}
+
+/**
+ * @param {Object} system - manifest.system
+ * @param {boolean} probed
+ * @param {boolean} [willProbe] - True when caller will run --probe immediately after this block
+ */
+function logCredentialIntentBlock(system, probed, willProbe = false) {
+  const url = resolveCredentialTestEndpointDisplay(system || {});
+  logSectionTitle('Credential (intent):');
+  if (url) {
+    logger.log(chalk.gray('Test endpoint:'));
+    logger.log(chalk.cyan(`GET ${url}`));
+  } else {
+    logger.log(chalk.gray('Test endpoint: (not configured — defaults may apply on server)'));
+  }
+  if (!probed) {
+    if (willProbe) {
+      logger.log(chalk.gray('⏳ Connectivity will be tested next (--probe)'));
+    } else {
+      logger.log(chalk.yellow('⚠ Connectivity not tested (use --probe)'));
+    }
+  }
+}
+
+/**
+ * @param {string[]} actions
+ * @param {string} [extraLine]
+ */
+function logNextActions(actions, extraLine) {
+  logSectionTitle('Next actions:');
+  for (const a of actions) {
+    if (a.startsWith('Run:')) {
+      logger.log(chalk.cyan('- ') + chalk.white(a));
+    } else {
+      logger.log(chalk.cyan('- ') + a);
+    }
+  }
+  if (extraLine) {
+    logger.log(chalk.cyan('- ') + chalk.white(extraLine));
+  }
+}
+
+/**
+ * @param {Object} sys - ExternalSystemResponse
+ */
+function logDocsBlock(sys) {
+  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 });
+  if (sys.mcpServerUrl) urls.push({ label: 'MCP Server', url: sys.mcpServerUrl });
+  if (urls.length === 0) return;
+  logSeparator();
+  logSectionTitle('Docs:');
+  for (const { label, url } of urls) {
+    logger.log(`${chalk.gray(label + ':')} ${chalk.cyan(url)}`);
+  }
+}
+
+module.exports = {
+  SEP,
+  logSeparator,
+  logSectionTitle,
+  tierGlyph,
+  verdictLine,
+  logDatasourceTable,
+  logIdentityBlock,
+  logCredentialIntentBlock,
+  logNextActions,
+  logDocsBlock
+};

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

@@ -0,0 +1,186 @@
+const { formatBlockingError, formatSuccessLine } = require('./cli-test-layout-chalk');
+/**
+ * Chalk-based CLI output for external system upload readiness (+ upload-time probe).
+ * Deploy summary lives in external-system-readiness-deploy-display.js.
+ *
+ * @fileoverview Readiness display for upload and optional probe after upload
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('./logger');
+const {
+  summarizeDatasourceTiersA,
+  summarizeProbeResults,
+  buildNextActionsTierA,
+  coerceProbeRunToResultRows
+} = require('./external-system-readiness-core');
+const {
+  logSeparator,
+  logSectionTitle,
+  logDatasourceTable,
+  logIdentityBlock,
+  logCredentialIntentBlock,
+  logNextActions,
+  logDocsBlock,
+  verdictLine,
+  SEP
+} = require('./external-system-readiness-display-internals');
+
+/**
+ * @param {Object} publication - PublicationResult
+ */
+function logPublishResultBlock(publication) {
+  const genMcp = publication.generateMcpContract === true;
+  logSectionTitle('Publish Result:');
+  logger.log(formatSuccessLine('System registered (controller + dataplane)'));
+  if (publication.uploadId) {
+    logger.log(`${chalk.gray('Upload ID:')} ${chalk.cyan(String(publication.uploadId))}`);
+  }
+  const sys = publication.system || {};
+  if (sys.status) {
+    logger.log(`${chalk.gray('System status:')} ${sys.status}`);
+  }
+  logSeparator();
+  logSectionTitle('MCP Contract:');
+  logger.log(genMcp ? formatSuccessLine('Generated') : chalk.gray('○ Not requested (generateMcpContract false)'));
+}
+
+/**
+ * @param {string} systemKey
+ * @param {{ ready: number, partial: number, failed: number }} summary
+ * @param {boolean} willProbe
+ */
+function logUploadReadinessSummaryMinimal(systemKey, summary, willProbe) {
+  logger.log(chalk.green(`\nUpload complete: ${systemKey}`));
+  logger.log(
+    chalk.gray('Summary:') +
+      ` ${chalk.green('Ready: ' + summary.ready)} · ${chalk.yellow('Partial: ' + summary.partial)} · ${chalk.red('Failed: ' + summary.failed)}`
+  );
+  if (!willProbe) logger.log(chalk.gray('Use --probe for runtime verification'));
+}
+
+/**
+ * @param {string} systemKey
+ * @param {Object} publication
+ * @param {Object} manifest
+ * @param {{ rows: Array<{ key: string, tier: string }>, ready: number, partial: number, failed: number }} summary
+ * @param {boolean} genMcp
+ * @param {boolean} willProbe
+ */
+function logUploadReadinessSummaryExpanded(systemKey, publication, manifest, summary, genMcp, willProbe) {
+  const systemCfg = manifest.system || {};
+  logSeparator();
+  logPublishResultBlock(publication);
+  logSeparator();
+  logDatasourceTable(summary.rows, summary);
+  logSeparator();
+  logIdentityBlock(systemCfg);
+  logSeparator();
+  logCredentialIntentBlock(systemCfg, false, !!willProbe);
+  logSeparator();
+  let hints = buildNextActionsTierA(systemKey, summary, genMcp);
+  if (willProbe) {
+    hints = hints.filter(h => !h.includes(`Run: aifabrix upload ${systemKey} --probe`));
+  }
+  logNextActions(hints);
+}
+
+/**
+ * @param {Object} ctx
+ * @param {string} ctx.systemKey
+ * @param {Object} ctx.publication - PublicationResult
+ * @param {Object} ctx.manifest
+ * @param {boolean} [ctx.minimal] - One-line summary + probe hint only
+ * @param {boolean} [ctx.willProbe] - True when caller will run --probe immediately after this summary
+ */
+function logUploadReadinessSummary(ctx) {
+  const { systemKey, publication, manifest, minimal, willProbe } = ctx;
+  const genMcp = publication.generateMcpContract === true;
+  const summary = summarizeDatasourceTiersA(publication.datasources || [], genMcp);
+  if (minimal) {
+    logUploadReadinessSummaryMinimal(systemKey, summary, willProbe);
+    return;
+  }
+  logUploadReadinessSummaryExpanded(systemKey, publication, manifest, summary, genMcp, willProbe);
+}
+
+/**
+ * @param {Object} validationBody - Unwrapped pipeline/validate response
+ */
+function logServerValidationWarnings(validationBody) {
+  const warnings = validationBody?.warnings;
+  if (!Array.isArray(warnings) || warnings.length === 0) return;
+  logSeparator();
+  logSectionTitle('Server validation:');
+  for (const w of warnings) {
+    logger.log(chalk.yellow(`⚠ Warning: ${typeof w === 'string' ? w : JSON.stringify(w)}`));
+  }
+}
+
+/**
+ * @param {Object} results - Probe result rows
+ * @param {Object} summary - summarizeProbeResults output
+ */
+function logProbeCredentialLine(results, summary) {
+  logSeparator();
+  logSectionTitle('Credential Test:');
+  const anyEndpointFail = results.some(row => row?.endpointTestResults?.success === false);
+  if (anyEndpointFail) {
+    logger.log(formatBlockingError('Failed (see Key Issues / endpoint test)'));
+  } else if (summary.failed > 0) {
+    logger.log(formatBlockingError('Some datasource checks failed'));
+  } else if (summary.partial > 0) {
+    logger.log(chalk.yellow('⚠ Completed with warnings'));
+  } else {
+    logger.log(formatSuccessLine('Passed'));
+  }
+}
+
+/**
+ * @param {Object} probeRaw - Unwrapped POST /validation/run body
+ * @param {string} systemKey
+ */
+function logProbeRuntimeBlock(probeRaw, systemKey) {
+  const results = coerceProbeRunToResultRows(probeRaw);
+  const summary = summarizeProbeResults(results);
+  logSeparator();
+  logger.log(chalk.bold('Runtime Readiness:'));
+  if (results.length === 0) {
+    logger.log(chalk.yellow('⚠ No runtime datasource results were returned by the dataplane probe.'));
+    logger.log(chalk.gray('   Endpoint credential test may still pass even if datasource checks were not reported.'));
+  }
+  logDatasourceTable(summary.rows, summary);
+  if (summary.issues.length > 0) {
+    logSeparator();
+    logSectionTitle('Key Issues:');
+    for (const { key, lines } of summary.issues) {
+      logger.log(chalk.white(key));
+      for (const line of lines) {
+        logger.log(chalk.red(`- ${line}`));
+      }
+    }
+  }
+  logProbeCredentialLine(results, summary);
+  logSeparator();
+  logNextActions(
+    ['Fix API credentials or permissions if endpoint tests failed'],
+    `Run: aifabrix datasource test-e2e <datasourceKey> --app ${systemKey}`
+  );
+}
+
+module.exports = {
+  logUploadReadinessSummary,
+  logServerValidationWarnings,
+  logProbeRuntimeBlock,
+  SEP,
+  logSeparator,
+  logSectionTitle,
+  logDatasourceTable,
+  logIdentityBlock,
+  logCredentialIntentBlock,
+  logNextActions,
+  logDocsBlock,
+  verdictLine
+};

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

@@ -12,9 +12,32 @@
 const fs = require('fs').promises;
 const path = require('path');
 const { testDatasourceViaPipeline } = require('../api/pipeline.api');
+const { integrationResultFromEnvelope, firstIssueMessage } = require('./datasource-test-run-legacy-adapter');
 
 /** Pipeline test endpoints accept client credentials; do not enforce Bearer-only */
 
+/**
+ * Parse successful pipeline test body (envelope or legacy).
+ * @param {Object} body
+ * @param {string} datasourceKey
+ * @returns {Object}
+ * @throws {Error} When body indicates failure
+ */
+function parsePipelineTestResponseBody(body, datasourceKey) {
+  if (body && typeof body === 'object' && typeof body.status === 'string' && body.datasourceKey) {
+    if (body.status === 'fail') {
+      const errMsg = firstIssueMessage(body) || 'Test failed';
+      throw new Error(`Test endpoint failed: ${errMsg}`);
+    }
+    return integrationResultFromEnvelope(body, datasourceKey);
+  }
+  if (body.success === false) {
+    const errMsg = body.error || body.formattedError || 'Test failed';
+    throw new Error(`Test endpoint failed: ${errMsg}`);
+  }
+  return body.data || body;
+}
+
 /**
  * Retry API call with exponential backoff
  * @async
@@ -73,13 +96,8 @@ async function callPipelineTestEndpoint({ systemKey, datasourceKey, payloadTempl
   if (!response.success || !response.data) {
     throw new Error(`Test endpoint failed: ${response.error || response.formattedError || 'Unknown error'}`);
   }
-  // When 200 with success: false in body, pass through; caller interprets via data.success
-  if (response.data?.success === false) {
-    const errMsg = response.data?.error || response.data?.formattedError || 'Test failed';
-    throw new Error(`Test endpoint failed: ${errMsg}`);
-  }
 
-  return response.data.data || response.data;
+  return parsePipelineTestResponseBody(response.data, datasourceKey);
 }
 
 /**

package/lib/utils/external-system-validators.js

@@ -119,31 +119,45 @@ function checkPathExistsInPayload(fieldPath, payloadTemplate) {
 }
 
 /**
- * Validates dimensions object structure and content
- * @param {Object} dimensions - Dimensions object to validate
+ * Root dimensions (dimensionBinding): local bindings as dimKey → metadata path string for validateDimensions.
+ * @param {Object} datasource - Datasource config
+ * @returns {Object} Map suitable for validateDimensions
+ */
+function getDimensionsMapForValidation(datasource) {
+  const root = datasource?.dimensions;
+  if (!root || typeof root !== 'object' || Array.isArray(root)) return {};
+  const out = {};
+  for (const [dimKey, binding] of Object.entries(root)) {
+    if (binding && typeof binding === 'object' && typeof binding.field === 'string') {
+      out[dimKey] = `metadata.${binding.field}`;
+    }
+  }
+  return out;
+}
+
+/**
+ * Validates dimensions object structure and content (path strings).
+ * @param {Object} dimensions - dimKey → path (e.g. metadata.country)
  * @param {Object} results - Results object to update
  */
 function validateDimensions(dimensions, results) {
-  if (!dimensions) {
-    results.errors.push('fieldMappings.dimensions is required (dimensions-first model)');
-    results.valid = false;
+  if (!dimensions || typeof dimensions !== 'object' || Array.isArray(dimensions)) {
+    results.warnings.push('No dimensions configured (schema v2.4: use root dimensions; optional but recommended for ABAC)');
     return;
   }
 
-  if (typeof dimensions !== 'object' || Array.isArray(dimensions)) {
-    results.errors.push('fieldMappings.dimensions must be an object mapping dimension keys to attribute paths');
-    results.valid = false;
+  if (Object.keys(dimensions).length === 0) {
+    results.warnings.push('Dimensions object is empty');
     return;
   }
 
-  // Validate dimension keys and values
   for (const [dimensionKey, attributePath] of Object.entries(dimensions)) {
     if (!/^[a-zA-Z0-9_]+$/.test(dimensionKey)) {
-      results.errors.push(`Invalid dimension key '${dimensionKey}': must match pattern ^[a-zA-Z0-9_]+$`);
+      results.errors.push(`Invalid dimension key '${dimensionKey}': dimension key must contain only letters, numbers, and underscores`);
       results.valid = false;
     }
     if (typeof attributePath !== 'string' || !/^[a-zA-Z0-9_.]+$/.test(attributePath)) {
-      results.errors.push(`Invalid attribute path '${attributePath}' for dimension '${dimensionKey}': must match pattern ^[a-zA-Z0-9_.]+$`);
+      results.errors.push(`Invalid attribute path '${attributePath}' for dimension '${dimensionKey}': attribute path must contain only letters, numbers, underscores, and dots`);
       results.valid = false;
     }
   }
@@ -180,7 +194,7 @@ function validateAttributesStructure(attributes, results) {
  */
 function validateSingleAttribute(attributeName, attributeConfig, payloadTemplate, results) {
   if (!attributeConfig || typeof attributeConfig !== 'object') {
-    results.errors.push(`Attribute '${attributeName}' must be an object with expression and type`);
+    results.errors.push(`Attribute '${attributeName}' must be an object with expression`);
     results.valid = false;
     return;
   }
@@ -224,8 +238,7 @@ function validateFieldMappings(datasource, testPayload) {
     return results;
   }
 
-  // Validate dimensions (required in new schema)
-  validateDimensions(datasource.fieldMappings.dimensions, results);
+  validateDimensions(getDimensionsMapForValidation(datasource), results);
 
   // Validate attributes structure (required in new schema)
   const attributes = validateAttributesStructure(datasource.fieldMappings.attributes, results);
@@ -322,6 +335,11 @@ function validateAgainstSchema(data, schema) {
     validateSchema: false
   });
   addFormats(ajv);
+  // Some schemas (e.g. external-datasource.schema.json) reference these by $id (aifabrix://schema/type/*).
+  // Adding them up-front keeps validation offline-safe and avoids unresolved $ref failures.
+  ajv.addSchema(require('../schema/type/document-storage.json'));
+  ajv.addSchema(require('../schema/type/message-service.json'));
+  ajv.addSchema(require('../schema/type/vector-store.json'));
   // Remove $schema for draft-2020-12 to avoid AJV issues
   const schemaCopy = { ...schema };
   if (schemaCopy.$schema && schemaCopy.$schema.includes('2020-12')) {

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

@@ -0,0 +1,119 @@
+/**
+ * Health check URL resolution helpers.
+ *
+ * @fileoverview Compute health check URL using declarative public URL logic (Traefik/frontDoorRouting)
+ */
+
+'use strict';
+
+const { computePublicUrlBaseString } = require('./url-declarative-public-base');
+const { parseDeveloperIdNum } = require('./declarative-url-ports');
+
+/**
+ * Join URL path segments with exactly one slash between them.
+ * @param {string} a
+ * @param {string} b
+ * @returns {string}
+ */
+function joinUrlPath(a, b) {
+  const left = String(a || '').replace(/\/+$/, '');
+  const right = String(b || '').replace(/^\/+/, '');
+  if (!left) return `/${right}`;
+  if (!right) return left || '/';
+  return `${left}/${right}`;
+}
+
+/**
+ * Convert a frontDoorRouting.pattern (Traefik/Front Door wildcard route) into a concrete mount path.
+ * Example: "/auth/*" -> "/auth"
+ *
+ * @param {string} pattern
+ * @returns {string}
+ */
+function normalizeFrontDoorPatternForHealth(pattern) {
+  let p = String(pattern || '').trim();
+  if (!p) return '/';
+  if (!p.startsWith('/')) p = `/${p}`;
+  // Drop wildcard suffixes used for routing.
+  p = p.replace(/\/\*+$/, '');
+  p = p.replace(/\*+$/, '');
+  // Drop trailing path params like "/foo/{bar}" if present (health is mounted at the base).
+  p = p.replace(/\/\{[^}]+\}$/, '');
+  // Normalize slashes and trailing slash.
+  p = p.replace(/\/{2,}/g, '/');
+  p = p.replace(/\/+$/, '');
+  return p || '/';
+}
+
+/**
+ * @param {Object|null} appConfig
+ * @returns {boolean}
+ */
+function frontDoorEnabled(appConfig) {
+  return Boolean(appConfig && appConfig.frontDoorRouting && appConfig.frontDoorRouting.enabled === true);
+}
+
+/**
+ * @param {Object|null} appConfig
+ * @returns {string|null}
+ */
+function frontDoorPattern(appConfig) {
+  const p = appConfig && appConfig.frontDoorRouting ? appConfig.frontDoorRouting.pattern : null;
+  return (typeof p === 'string' && p.trim()) ? p.trim() : null;
+}
+
+/**
+ * Compute the Traefik front-door health check URL when applicable.
+ *
+ * Returns null when Traefik/frontDoorRouting isn't active or cannot be resolved.
+ *
+ * @async
+ * @param {string} appName
+ * @param {number} healthCheckPort
+ * @param {Object|null} appConfig
+ * @returns {Promise<string|null>}
+ */
+async function computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig) {
+  if (!frontDoorEnabled(appConfig)) return null;
+  const pattern = frontDoorPattern(appConfig);
+  if (!pattern) return null;
+
+  const coreConfig = require('../core/config');
+  const userCfg = await coreConfig.getConfig();
+  if (!(userCfg && userCfg.traefik)) return null;
+
+  const infraTlsEnabled = Boolean(userCfg && userCfg.tlsEnabled);
+  const remoteServer = await coreConfig.getRemoteServer();
+  const developerIdRaw = await coreConfig.getDeveloperId();
+  const developerIdNum = parseDeveloperIdNum(developerIdRaw);
+
+  // Health checks originate from the CLI on the host, not from inside a container.
+  const profile = 'local';
+  const fd = appConfig.frontDoorRouting;
+  const listenPort = Number(appConfig?.port || 3000);
+
+  const publicBase = computePublicUrlBaseString({
+    traefik: true,
+    pathActive: true,
+    hostTemplate: fd.host,
+    tls: fd.tls,
+    developerIdRaw,
+    remoteServer,
+    profile,
+    listenPort,
+    developerIdNum,
+    infraTlsEnabled
+  });
+
+  const healthCheckPath = appConfig?.healthCheck?.path || '/health';
+  const mountPath = normalizeFrontDoorPatternForHealth(pattern);
+  const baseWithFrontDoor = joinUrlPath(publicBase, mountPath);
+  return joinUrlPath(baseWithFrontDoor, healthCheckPath);
+}
+
+module.exports = {
+  joinUrlPath,
+  normalizeFrontDoorPatternForHealth,
+  computeTraefikHealthCheckUrl
+};
+