@aifabrix/builder 2.45.0 → 2.46.0

package/lib/lifecycle/certification-progress.js

@@ -0,0 +1,231 @@
+/**
+ * @fileoverview UX certification progress for lifecycle CLI (aligned with dataplane overview / app-ui).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { VERDICT } = require('./product-model');
+const { formatOpenApiPublishNextStep } = require('./dataplane-ui-url');
+
+/** @typedef {'governanceCoverage'|'operationalReadiness'|'openApiPublished'|'aiTrust'|'activeWarnings'} CertificationCriterionId */
+
+/**
+ * @typedef {Object} CertificationCriterionRow
+ * @property {CertificationCriterionId} id
+ * @property {string} label
+ * @property {boolean} met
+ */
+
+/**
+ * @typedef {Object} CertificationProgressViewModel
+ * @property {'progress'|'gaps'} mode
+ * @property {string} currentLevel
+ * @property {string} targetLevel
+ * @property {CertificationCriterionRow[]} criteria
+ * @property {number|null} progressPercent
+ * @property {boolean} highestTierAchieved
+ */
+
+const SILVER_TO_GOLD_CRITERIA = [
+  {
+    id: 'governanceCoverage',
+    label: 'Governance Coverage ≥ 95%',
+    evaluate: ctx =>
+      (ctx.report.governance?.policyCoveragePercent ?? 0) >= 95 &&
+      ctx.report.governance?.verdict === VERDICT.VERIFIED
+  },
+  {
+    id: 'operationalReadiness',
+    label: 'Operational Readiness ≥ 90%',
+    evaluate: ctx => (ctx.report.operations?.operationalReadinessPercent ?? 0) >= 90
+  },
+  {
+    id: 'openApiPublished',
+    label: 'OpenAPI Published',
+    evaluate: ctx => ctx.openApiPublished === true
+  },
+  {
+    id: 'aiTrust',
+    label: 'AI Trust ≥ 95%',
+    evaluate: ctx => (ctx.report.trust?.businessContextConfidencePercent ?? 0) >= 95
+  },
+  {
+    id: 'activeWarnings',
+    label: '0 Active Warnings',
+    evaluate: ctx => ctx.activeWarningCount === 0
+  }
+];
+
+/** @type {Record<CertificationCriterionId, string>} */
+const NEXT_COMMAND_BY_CRITERION = {
+  governanceCoverage: 'governance verify',
+  operationalReadiness: 'verify-operations',
+  openApiPublished: '',
+  aiTrust: 'verify-trust',
+  activeWarnings: ''
+};
+
+/**
+ * @param {string} level
+ * @returns {string}
+ */
+function formatCertificationLevel(level) {
+  if (!level || level === 'NONE') return 'Uncertified';
+  return level.charAt(0) + level.slice(1).toLowerCase();
+}
+
+/**
+ * @param {string} current
+ * @returns {string|null}
+ */
+function resolveTargetLevel(current) {
+  if (current === 'NONE' || current === 'BRONZE') return 'SILVER';
+  if (current === 'SILVER') return 'GOLD';
+  if (current === 'GOLD') return 'PLATINUM';
+  return null;
+}
+
+/**
+ * @param {string} current
+ * @param {string} target
+ * @param {{ report: Object, openApiPublished?: boolean, activeWarningCount: number }} ctx
+ * @returns {CertificationCriterionRow[]}
+ */
+function buildCriteriaForTarget(current, target, ctx) {
+  if (current === 'SILVER' && target === 'GOLD') {
+    return SILVER_TO_GOLD_CRITERIA.map(def => ({
+      id: def.id,
+      label: def.label,
+      met: def.evaluate(ctx)
+    }));
+  }
+  return [];
+}
+
+/**
+ * @param {Object|null|undefined} report - SystemLifecycleReport
+ * @param {{ openApiPublished?: boolean }} [options]
+ * @returns {CertificationProgressViewModel|null}
+ */
+function buildCertificationProgress(report, options = {}) {
+  if (!report?.certification?.level) {
+    return null;
+  }
+  const currentLevel = report.certification.level;
+  const targetLevel = resolveTargetLevel(currentLevel);
+  if (!targetLevel) {
+    return {
+      mode: 'gaps',
+      currentLevel,
+      targetLevel: currentLevel,
+      criteria: [],
+      progressPercent: 100,
+      highestTierAchieved: true
+    };
+  }
+
+  const activeWarningCount = Array.isArray(report.warnings) ? report.warnings.length : 0;
+  const ctx = {
+    report,
+    openApiPublished: options.openApiPublished === true,
+    activeWarningCount
+  };
+  const criteria = buildCriteriaForTarget(currentLevel, targetLevel, ctx);
+  if (criteria.length === 0) {
+    return {
+      mode: 'gaps',
+      currentLevel,
+      targetLevel,
+      criteria: [],
+      progressPercent: null,
+      highestTierAchieved: false
+    };
+  }
+
+  const metCount = criteria.filter(c => c.met).length;
+  const progressPercent = Math.round((metCount / criteria.length) * 100);
+  return {
+    mode: 'progress',
+    currentLevel,
+    targetLevel,
+    criteria,
+    progressPercent,
+    highestTierAchieved: false
+  };
+}
+
+/**
+ * @param {CertificationCriterionId} id
+ * @param {Object} report
+ * @param {boolean} openApiPublished
+ * @returns {string|null}
+ */
+function formatCriterionCurrentHint(id, report, openApiPublished) {
+  if (id === 'aiTrust') {
+    const p = report.trust?.businessContextConfidencePercent;
+    return typeof p === 'number' ? `(current: ${p}%)` : null;
+  }
+  if (id === 'operationalReadiness') {
+    const p = report.operations?.operationalReadinessPercent;
+    return typeof p === 'number' ? `(current: ${p}%)` : null;
+  }
+  if (id === 'governanceCoverage') {
+    const p = report.governance?.policyCoveragePercent;
+    return typeof p === 'number' ? `(current: ${p}%)` : null;
+  }
+  if (id === 'openApiPublished' && !openApiPublished) {
+    return '(not published)';
+  }
+  if (id === 'activeWarnings') {
+    const n = Array.isArray(report.warnings) ? report.warnings.length : 0;
+    return n > 0 ? `(current: ${n})` : null;
+  }
+  return null;
+}
+
+/**
+ * @param {string} systemKey
+ * @param {CertificationProgressViewModel} progress
+ * @param {{ dataplaneUrl?: string|null }} [options]
+ * @returns {string|null}
+ */
+function resolveNextStepCommand(systemKey, progress, options = {}) {
+  const firstUnmet = progress.criteria.find(c => !c.met);
+  if (!firstUnmet) return null;
+  const cmd = NEXT_COMMAND_BY_CRITERION[firstUnmet.id];
+  if (firstUnmet.id === 'openApiPublished') {
+    return formatOpenApiPublishNextStep(systemKey, {
+      dataplaneUrl: options.dataplaneUrl,
+      dataplaneUiBaseUrl: options.dataplaneUiBaseUrl
+    });
+  }
+  if (firstUnmet.id === 'activeWarnings') {
+    return 'Resolve lifecycle warnings, then re-run lifecycle';
+  }
+  if (!cmd) return null;
+  return `aifabrix ${cmd} ${systemKey} -v`;
+}
+
+/**
+ * @param {number|null} percent
+ * @param {number} [width]
+ * @returns {string}
+ */
+function formatProgressBar(percent, width = 10) {
+  if (typeof percent !== 'number' || Number.isNaN(percent)) {
+    return '—'.repeat(width);
+  }
+  const filled = Math.round((Math.max(0, Math.min(100, percent)) / 100) * width);
+  return `${'█'.repeat(filled)}${'░'.repeat(width - filled)}`;
+}
+
+module.exports = {
+  buildCertificationProgress,
+  formatCertificationLevel,
+  formatCriterionCurrentHint,
+  resolveNextStepCommand,
+  formatProgressBar,
+  NEXT_COMMAND_BY_CRITERION
+};

package/lib/lifecycle/dataplane-ui-url.js

@@ -0,0 +1,145 @@
+/**
+ * @fileoverview Resolve dataplane app-ui base URL for lifecycle CLI hints.
+ * @author AI Fabrix Team
+ * @version 1.1.0
+ */
+
+'use strict';
+
+const { getConfig } = require('../core/config');
+const {
+  expandDeclarativeUrlsInEnvContent,
+  parseSimpleEnvMap
+} = require('../utils/url-declarative-resolve');
+
+const EXTERNAL_SYSTEMS_UI_PATH = '/external-systems';
+
+/**
+ * @param {string} url
+ * @returns {number|null}
+ */
+function portFromUrl(url) {
+  try {
+    const u = new URL(url);
+    if (u.port) {
+      const port = parseInt(u.port, 10);
+      return Number.isFinite(port) ? port : null;
+    }
+    return u.protocol === 'https:' ? 443 : 80;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+function isLoopbackHost(hostname) {
+  const h = String(hostname || '').toLowerCase();
+  return h === 'localhost' || h === '127.0.0.1' || h === '[::1]';
+}
+
+/**
+ * Browser-reachable origin from the resolved dataplane API base URL (same host/port).
+ * @param {string|null|undefined} dataplaneUrl
+ * @returns {string|null}
+ */
+function resolveDataplaneUiBaseUrlFromApiOrigin(dataplaneUrl) {
+  if (!dataplaneUrl || typeof dataplaneUrl !== 'string') {
+    return null;
+  }
+  try {
+    const u = new URL(dataplaneUrl.replace(/\/$/, ''));
+    return `${u.protocol}//${u.host}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve `url://dataplane-host-public` from builder registry + user config.
+ * @async
+ * @returns {Promise<string|null>}
+ */
+async function resolveDataplaneUiBaseUrlFromRegistry() {
+  try {
+    const userCfg = await getConfig();
+    const content = 'DATAPLANE_UI=url://dataplane-host-public';
+    const expanded = await expandDeclarativeUrlsInEnvContent(content, {
+      profile: 'local',
+      currentAppKey: 'dataplane',
+      useEnvironmentScopedResources: userCfg.useEnvironmentScopedResources === true,
+      appEnvironmentScopedResources: false,
+      remoteServer: userCfg['remote-server'] || userCfg.remoteServer || null,
+      developerIdRaw: userCfg['developer-id'] ?? userCfg.developerId ?? null,
+      traefik: userCfg.traefik === true,
+      userCfg
+    });
+    const map = parseSimpleEnvMap(expanded);
+    const url = map.DATAPLANE_UI;
+    if (url && typeof url === 'string' && !url.startsWith('url://')) {
+      return url.replace(/\/$/, '');
+    }
+  } catch {
+    // Fall back to API origin below.
+  }
+  return null;
+}
+
+/**
+ * @async
+ * @param {string|null|undefined} dataplaneUrl - Resolved dataplane API base URL
+ * @returns {Promise<string|null>}
+ */
+async function resolveDataplaneUiBaseUrl(dataplaneUrl) {
+  const fromRegistry = await resolveDataplaneUiBaseUrlFromRegistry();
+  if (fromRegistry) {
+    return fromRegistry;
+  }
+  return resolveDataplaneUiBaseUrlFromApiOrigin(dataplaneUrl);
+}
+
+/**
+ * @param {string|null|undefined} dataplaneUiBaseUrl
+ * @param {string} systemKey
+ * @returns {string|null}
+ */
+function buildExternalSystemUiUrl(dataplaneUiBaseUrl, systemKey) {
+  if (!dataplaneUiBaseUrl || !systemKey) {
+    return null;
+  }
+  const base = String(dataplaneUiBaseUrl).replace(/\/$/, '');
+  const key = encodeURIComponent(String(systemKey).trim());
+  if (!key) {
+    return null;
+  }
+  return `${base}${EXTERNAL_SYSTEMS_UI_PATH}/${key}`;
+}
+
+/**
+ * @param {string} systemKey
+ * @param {{ dataplaneUrl?: string|null, dataplaneUiBaseUrl?: string|null }} [options]
+ * @returns {string}
+ */
+function formatOpenApiPublishNextStep(systemKey, options = {}) {
+  const uiBase =
+    options.dataplaneUiBaseUrl ||
+    resolveDataplaneUiBaseUrlFromApiOrigin(options.dataplaneUrl);
+  const uiUrl = buildExternalSystemUiUrl(uiBase, systemKey);
+  if (uiUrl) {
+    return `Publish OpenAPI in dataplane UI: ${uiUrl}`;
+  }
+  return `Publish OpenAPI in dataplane UI — open external system "${systemKey}"`;
+}
+
+module.exports = {
+  EXTERNAL_SYSTEMS_UI_PATH,
+  portFromUrl,
+  isLoopbackHost,
+  resolveDataplaneUiBaseUrlFromApiOrigin,
+  resolveDataplaneUiBaseUrlFromRegistry,
+  resolveDataplaneUiBaseUrl,
+  buildExternalSystemUiUrl,
+  formatOpenApiPublishNextStep
+};

package/lib/lifecycle/exit-codes.js

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Exit codes for Enterprise AI Certification verify commands.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { VERDICT } = require('./product-model');
+
+/**
+ * @param {string} verdict
+ * @param {{ partial?: boolean }} [opts]
+ * @returns {number}
+ */
+function exitCodeFromVerdict(verdict, opts = {}) {
+  if (opts.partial === true) return 2;
+  if (verdict === VERDICT.VERIFIED) return 0;
+  return 1;
+}
+
+module.exports = {
+  exitCodeFromVerdict
+};

package/lib/lifecycle/json-envelope.js

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Machine-readable --json envelopes for verify + lifecycle commands.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Object} base
+ * @param {boolean} includeDetails
+ * @returns {Object}
+ */
+function buildJsonEnvelope(base, includeDetails) {
+  const out = { ...base };
+  if (!includeDetails) {
+    delete out.details;
+    delete out.readinessMetrics;
+  }
+  return out;
+}
+
+module.exports = {
+  buildJsonEnvelope
+};

package/lib/lifecycle/lifecycle-governance-options.js

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Map lifecycle CLI flags to governance verify/generate options.
+ */
+
+'use strict';
+
+const { VERDICT } = require('./product-model');
+
+/**
+ * @param {Object} options
+ * @returns {boolean}
+ */
+function lifecycleHasGovernanceSubjects(options) {
+  const emails = options.subjectEmail || options.subjectEmails || [];
+  const ids = options.subjectUserId || options.subjectUserIds || [];
+  return [...emails, ...ids].some(value => String(value || '').trim());
+}
+
+/**
+ * @param {Object} report
+ * @returns {boolean}
+ */
+function lifecycleGovernanceNeedsWork(report) {
+  return report?.governance?.verdict !== VERDICT.VERIFIED;
+}
+
+/**
+ * @param {Object} options
+ * @param {{ authConfig?: Object, dataplaneUrl?: string }} [context]
+ * @returns {Object}
+ */
+function buildGovernanceOptsFromLifecycle(options, context = {}) {
+  return {
+    env: options.env || 'dev',
+    verbose: options.verbose === true,
+    debug: options.debug === true,
+    noSync: true,
+    force: options.force === true,
+    certificationProfile: options.certificationProfile || 'bronze',
+    subjectEmails: options.subjectEmail || options.subjectEmails || [],
+    subjectUserIds: options.subjectUserId || options.subjectUserIds || [],
+    authConfig: context.authConfig,
+    dataplaneUrl: context.dataplaneUrl
+  };
+}
+
+module.exports = {
+  lifecycleHasGovernanceSubjects,
+  lifecycleGovernanceNeedsWork,
+  buildGovernanceOptsFromLifecycle
+};

package/lib/lifecycle/logger-quiet.js

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Suppress CLI logger output during orchestration (verify-operations).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+
+/**
+ * Run async fn with logger.log temporarily disabled.
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+async function withQuietLogs(fn) {
+  const prev = logger.log;
+  logger.log = () => {};
+  try {
+    return await fn();
+  } finally {
+    logger.log = prev;
+  }
+}
+
+module.exports = {
+  withQuietLogs
+};

package/lib/lifecycle/open-api-published.js

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Resolve OpenAPI published flag for lifecycle certification progress.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getExternalSystem } = require('../api/external-systems.api');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+/**
+ * Dataplane ExternalSystemStatus serializes as lowercase (e.g. "published").
+ * @param {string|undefined} status
+ * @returns {boolean}
+ */
+function isExternalSystemPublishedStatus(status) {
+  return String(status || '')
+    .trim()
+    .toLowerCase() === 'published';
+}
+
+/**
+ * Mirrors dataplane SystemOverviewService openApiPublished logic.
+ * @param {Object|null|undefined} system - ExternalSystemResponse body
+ * @returns {boolean}
+ */
+function evaluateOpenApiPublished(system) {
+  if (!system || typeof system !== 'object') {
+    return false;
+  }
+  const published = isExternalSystemPublishedStatus(system.status);
+  const showDocs = system.showOpenApiDocs === true;
+  const hasUrl = !!(system.openApiDocsPageUrl || system.apiDocumentUrl);
+  return published && showDocs && hasUrl;
+}
+
+/**
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} systemKey
+ * @returns {Promise<boolean>}
+ */
+async function resolveOpenApiPublished(dataplaneUrl, authConfig, systemKey) {
+  try {
+    const res = await getExternalSystem(dataplaneUrl, systemKey, authConfig);
+    const system = unwrapApiData(res);
+    return evaluateOpenApiPublished(system);
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  isExternalSystemPublishedStatus,
+  evaluateOpenApiPublished,
+  resolveOpenApiPublished
+};

package/lib/lifecycle/operations-readiness-metrics.js

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview Operational readiness metric rollup for verify-operations (422.0).
+ * Human-facing labels for ICC/PDS/DTS; extraction from lifecycle reliability envelopes.
+ */
+
+'use strict';
+
+/** @type {readonly string[]} */
+const METRIC_KEYS = Object.freeze(['icc', 'pds', 'dts']);
+
+/** @type {Readonly<Record<string, string>>} */
+const OPERATIONS_METRIC_LABELS = Object.freeze({
+  icc: 'Integration contract coverage',
+  pds: 'Pipeline determinism',
+  dts: 'Data trust'
+});
+
+/**
+ * @param {unknown} raw
+ * @returns {number|null}
+ */
+function metricScorePercent(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return null;
+  }
+  const score = raw.score;
+  if (typeof score === 'number' && Number.isFinite(score)) {
+    return Math.max(0, Math.min(100, Math.round(score * 100)));
+  }
+  const pct = raw.percentage;
+  if (typeof pct === 'number' && Number.isFinite(pct)) {
+    return Math.max(0, Math.min(100, Math.round(pct)));
+  }
+  return null;
+}
+
+/**
+ * @param {unknown} envelope
+ * @returns {Record<string, number>|null}
+ */
+function metricsFromEnvelope(envelope) {
+  if (!envelope || typeof envelope !== 'object') {
+    return null;
+  }
+  let metrics = envelope.metricsOutput;
+  if (!metrics && envelope.validation && typeof envelope.validation === 'object') {
+    metrics = envelope.validation.metricsOutput;
+  }
+  if (!metrics || typeof metrics !== 'object') {
+    return null;
+  }
+  const out = {};
+  for (const key of METRIC_KEYS) {
+    const pct = metricScorePercent(metrics[key]);
+    if (pct !== null) {
+      out[key] = pct;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+/**
+ * Conservative rollup: min(ICC,PDS,DTS) per leg across validation + integration envelopes.
+ * E2E legs without metrics are ignored (runtime gate only).
+ * @param {unknown} reliability
+ * @returns {Record<string, number>|null}
+ */
+function rollupReadinessMetrics(reliability) {
+  if (!reliability || typeof reliability !== 'object') {
+    return null;
+  }
+  const legs = [reliability.validation, reliability.integration].filter(Boolean);
+  const rolled = {};
+  for (const key of METRIC_KEYS) {
+    const values = legs
+      .map(leg => metricsFromEnvelope(leg)?.[key])
+      .filter(v => typeof v === 'number');
+    if (values.length > 0) {
+      rolled[key] = Math.min(...values);
+    }
+  }
+  return Object.keys(rolled).length > 0 ? rolled : null;
+}
+
+/**
+ * @param {Object|null} lifecycleReport
+ * @returns {Record<string, number>|null}
+ */
+function extractReadinessMetricsFromLifecycleReport(lifecycleReport) {
+  const reliability = lifecycleReport?.operations?.details?.reliability;
+  return rollupReadinessMetrics(reliability);
+}
+
+module.exports = {
+  METRIC_KEYS,
+  OPERATIONS_METRIC_LABELS,
+  metricScorePercent,
+  metricsFromEnvelope,
+  rollupReadinessMetrics,
+  extractReadinessMetricsFromLifecycleReport
+};