@aifabrix/builder 2.43.0 → 2.44.0

package/lib/utils/datasource-test-run-exit.js

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Exit code matrix for DatasourceTestRun after successful HTTP (plan §3.1).
+ * HTTP/transport failures are exit 3 (handled by callers).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Compute CLI exit code from parsed DatasourceTestRun envelope.
+ * Ordering: status / warnings-as-errors → require-cert (§3.1).
+ * @param {import('../api/types/validation-run.types').DatasourceTestRunLike|null|undefined} body
+ * @param {Object} [opts]
+ * @param {boolean} [opts.warningsAsErrors]
+ * @param {boolean} [opts.requireCert]
+ * @returns {number} 0 | 1 | 2 | 3 (3 = treat as parse/body unusable)
+ */
+function computeExitCodeFromDatasourceTestRun(body, opts = {}) {
+  if (!body || typeof body !== 'object') {
+    return 3;
+  }
+  const status = body.status;
+  if (status === 'fail') {
+    return 1;
+  }
+  if (status === 'warn' && opts.warningsAsErrors === true) {
+    return 1;
+  }
+  if (status === 'ok' || status === 'skipped' || status === 'warn') {
+    if (opts.requireCert === true) {
+      const cert = body.certificate;
+      if (!cert) {
+        return 2;
+      }
+      if (cert.status === 'not_passed') {
+        return 2;
+      }
+    }
+    return 0;
+  }
+  return 3;
+}
+
+/**
+ * Exit code for poll timeout with last envelope (plan §3.4).
+ * @param {import('../api/types/validation-run.types').DatasourceTestRunLike|null} lastBody
+ * @returns {number} 1 if root fail, else 3
+ */
+function exitCodeForPollTimeout(lastBody) {
+  if (lastBody && typeof lastBody === 'object' && lastBody.status === 'fail') {
+    return 1;
+  }
+  return 3;
+}
+
+module.exports = {
+  computeExitCodeFromDatasourceTestRun,
+  exitCodeForPollTimeout
+};

package/lib/utils/datasource-test-run-legacy-adapter.js

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Map DatasourceTestRun envelope → legacy CLI display shapes (integration + E2E).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * @param {Object|null} envelope
+ * @returns {string|null}
+ */
+function firstIssueMessage(envelope) {
+  const v = envelope && envelope.validation;
+  const issues = v && Array.isArray(v.issues) ? v.issues : [];
+  const first = issues.find(i => i && (i.message || i.hint));
+  if (first) return String(first.message || first.hint);
+  const integ = envelope && envelope.integration;
+  const steps = integ && Array.isArray(integ.stepResults) ? integ.stepResults : [];
+  const bad = steps.find(s => s && s.success === false && (s.message || s.error));
+  if (bad) return String(bad.message || bad.error || 'Integration step failed');
+  return null;
+}
+
+/**
+ * Legacy integration result for displayIntegrationTestResults / verbose details.
+ * @param {Object|null} envelope
+ * @param {string} datasourceKey
+ * @returns {Object}
+ */
+function integrationResultFromEnvelope(envelope, datasourceKey) {
+  if (!envelope || typeof envelope !== 'object') {
+    return {
+      key: datasourceKey,
+      systemKey: 'unknown',
+      success: false,
+      skipped: false,
+      validationResults: {},
+      fieldMappingResults: {},
+      endpointTestResults: {},
+      error: 'No report envelope',
+      envelope: null
+    };
+  }
+  const success = envelope.status !== 'fail';
+  const err = success ? undefined : firstIssueMessage(envelope) || `status: ${envelope.status}`;
+  return {
+    key: datasourceKey,
+    systemKey: envelope.systemKey || 'unknown',
+    success,
+    skipped: false,
+    error: err,
+    envelope
+  };
+}
+
+/**
+ * Map integration.stepResults → E2E-style steps for displayE2EResults.
+ * @param {Object|null} envelope
+ * @returns {{ steps: Object[], success: boolean, status?: string, error?: string }}
+ */
+function e2eShapeFromEnvelope(envelope) {
+  if (!envelope || typeof envelope !== 'object') {
+    return { steps: [], success: false, error: 'No report envelope' };
+  }
+  const integ = envelope.integration;
+  const raw = integ && Array.isArray(integ.stepResults) ? integ.stepResults : [];
+  const steps = raw.map(s => ({
+    name: s.name || 'step',
+    step: s.name,
+    success: s.success !== false,
+    message: s.message,
+    error: s.success === false ? s.message || 'failed' : undefined
+  }));
+  const success = envelope.status !== 'fail';
+  let status;
+  if (envelope.status === 'fail') status = 'failed';
+  else if (envelope.reportCompleteness && envelope.reportCompleteness !== 'full') {
+    status = 'completed';
+  } else {
+    status = 'completed';
+  }
+  return {
+    steps,
+    success,
+    status,
+    error: success ? undefined : firstIssueMessage(envelope) || undefined
+  };
+}
+
+module.exports = {
+  integrationResultFromEnvelope,
+  e2eShapeFromEnvelope,
+  firstIssueMessage
+};

package/lib/utils/datasource-test-run-report-version.js

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview reportVersion compatibility warnings (plan §3.15).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/** CLI-supported major reportVersion (bump when breaking). */
+const SUPPORTED_MAJOR = 1;
+
+/**
+ * Parse leading major from semver-like string (e.g. 1.1.0 → 1).
+ * @param {string} v
+ * @returns {number|null}
+ */
+function parseMajor(v) {
+  if (!v || typeof v !== 'string') return null;
+  const m = /^v?(\d+)/.exec(v.trim());
+  if (!m) return null;
+  return parseInt(m[1], 10);
+}
+
+/**
+ * stderr messages for reportVersion handling.
+ * @param {string|undefined} reportVersion - From envelope
+ * @returns {{ level: 'none'|'warn'|'info', message: string }|null}
+ */
+function getReportVersionStderrMessage(reportVersion) {
+  const major = parseMajor(reportVersion || '');
+  if (major === null) {
+    return null;
+  }
+  if (major < SUPPORTED_MAJOR - 1) {
+    return {
+      level: 'warn',
+      message: `reportVersion unsupported (got ${reportVersion}, support ${SUPPORTED_MAJOR - 1}–${SUPPORTED_MAJOR} major)`
+    };
+  }
+  if (major > SUPPORTED_MAJOR) {
+    return {
+      level: 'info',
+      message: 'Newer reportVersion; some fields may be ignored'
+    };
+  }
+  return null;
+}
+
+module.exports = {
+  SUPPORTED_MAJOR,
+  parseMajor,
+  getReportVersionStderrMessage
+};

package/lib/utils/datasource-test-run-schema-sync.js

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview SHA-256 compare Builder vs Dataplane DatasourceTestRun JSON Schema (plan §8.1).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const crypto = require('crypto');
+const { nodeFs } = require('../internal/node-fs');
+
+/**
+ * @param {string} filePath - Absolute path to file
+ * @returns {string} Lowercase hex SHA-256 of file bytes
+ */
+function sha256FileSync(filePath) {
+  const buf = nodeFs().readFileSync(filePath);
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * Compare two schema files; throws on mismatch when both exist.
+ * @param {string} builderSchemaPath
+ * @param {string} dataplaneSchemaPath
+ * @returns {{ skipped: boolean, reason?: string, builderSha?: string, dataplaneSha?: string }}
+ */
+function assertDatasourceTestRunSchemasInSync(builderSchemaPath, dataplaneSchemaPath) {
+  if (!nodeFs().existsSync(builderSchemaPath)) {
+    throw new Error(`Builder schema not found: ${builderSchemaPath}`);
+  }
+  if (!nodeFs().existsSync(dataplaneSchemaPath)) {
+    return {
+      skipped: true,
+      reason: `Dataplane schema not found (set AIFABRIX_DATAPLANE_ROOT or checkout sibling repo): ${dataplaneSchemaPath}`
+    };
+  }
+  const builderSha = sha256FileSync(builderSchemaPath);
+  let dataplaneSha;
+  try {
+    dataplaneSha = sha256FileSync(dataplaneSchemaPath);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return {
+        skipped: true,
+        reason: `Dataplane schema not found (set AIFABRIX_DATAPLANE_ROOT or checkout sibling repo): ${dataplaneSchemaPath}`
+      };
+    }
+    throw err;
+  }
+  if (builderSha !== dataplaneSha) {
+    throw new Error(
+      `DatasourceTestRun schema drift: builder ${builderSha} ≠ dataplane ${dataplaneSha}`
+    );
+  }
+  return { skipped: false, builderSha, dataplaneSha };
+}
+
+module.exports = {
+  sha256FileSync,
+  assertDatasourceTestRunSchemasInSync
+};

package/lib/utils/datasource-test-run-tty-log.js

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Log DatasourceTestRun to TTY — shared by datasource commands and external system server tests.
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+const { getReportVersionStderrMessage } = require('./datasource-test-run-report-version');
+const {
+  formatDatasourceTestRunSummary,
+  formatDatasourceTestRunTTY
+} = require('./datasource-test-run-display');
+const {
+  resolveDebugDisplayMode,
+  formatDatasourceTestRunDebugBlock
+} = require('./datasource-test-run-debug-display');
+const { analyzeCapabilityScope } = require('./datasource-test-run-capability-scope');
+
+function emitReportVersionDiagnostics(envelope) {
+  if (!envelope || typeof envelope !== 'object') return;
+  const msg = getReportVersionStderrMessage(envelope.reportVersion);
+  if (!msg) return;
+  if (msg.level === 'warn') logger.warn(chalk.yellow(msg.message));
+  else if (msg.level === 'info') logger.log(chalk.gray(msg.message));
+}
+
+function emitCapabilityScopeDiagnostics(envelope, opts = {}) {
+  const scope = analyzeCapabilityScope(envelope, opts.requestedCapabilityKey);
+  if (scope.violated && scope.message) {
+    logger.warn(chalk.yellow(`⚠ ${scope.message}`));
+  }
+}
+
+/**
+ * Print envelope (JSON, summary, or full TTY + optional debug appendix). Does not emit reportVersion/capability diagnostics.
+ * @param {Object} envelope
+ * @param {Object} options
+ * @param {boolean} [options.json]
+ * @param {boolean} [options.summary]
+ * @param {boolean|string} [options.debug]
+ * @param {string} [options.requestedCapabilityKey]
+ */
+function printDatasourceTestRunForTTY(envelope, options = {}) {
+  const displayOpts = { focusCapabilityKey: options.requestedCapabilityKey };
+  if (options.json) {
+    logger.log(JSON.stringify(envelope));
+    return;
+  }
+  if (options.summary) {
+    logger.log(formatDatasourceTestRunSummary(envelope, displayOpts));
+  } else {
+    logger.log(formatDatasourceTestRunTTY(envelope, displayOpts));
+  }
+  const mode = resolveDebugDisplayMode(options.debug);
+  if (mode) {
+    const appendix = formatDatasourceTestRunDebugBlock(envelope, mode, process.stdout.isTTY);
+    if (appendix) logger.log(appendix);
+  }
+}
+
+/**
+ * Emit diagnostics + human output for one server validation run (integration / test / e2e).
+ * @param {Object|null|undefined} envelope
+ * @param {Object} options - Same flags as unified CLI (json, summary, debug, requestedCapabilityKey)
+ */
+function logEnvelopeForInteractiveCli(envelope, options = {}) {
+  if (!envelope || typeof envelope !== 'object') return;
+  emitReportVersionDiagnostics(envelope);
+  emitCapabilityScopeDiagnostics(envelope, {
+    requestedCapabilityKey: options.requestedCapabilityKey
+  });
+  printDatasourceTestRunForTTY(envelope, options);
+}
+
+module.exports = {
+  emitReportVersionDiagnostics,
+  emitCapabilityScopeDiagnostics,
+  printDatasourceTestRunForTTY,
+  logEnvelopeForInteractiveCli
+};

package/lib/utils/datasource-validation-watch.js

@@ -0,0 +1,266 @@
+/**
+ * @fileoverview File watch + debounce for datasource validation CLI (plan §3.14).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const path = require('path');
+const { nodeFs } = require('../internal/node-fs');
+const chalk = require('chalk');
+const logger = require('./logger');
+
+/**
+ * Resolve integration path at call time so tests' jest.mock('./paths') applies even if this module
+ * was first loaded in a worker before the mock (eager destructuring would keep the real fn).
+ * @param {string} appKey
+ * @returns {string}
+ */
+function getIntegrationPathForWatch(appKey) {
+  return require('./paths').getIntegrationPath(appKey);
+}
+
+const DEFAULT_DEBOUNCE_MS = 500;
+const MAX_DIR_DEPTH = 14;
+
+const SKIP_DIR_NAMES = new Set(['node_modules', '.git', 'dist', 'logs', '.turbo']);
+
+/**
+ * @param {Object|null|undefined} envelope
+ * @returns {string}
+ */
+function fingerprintForWatchDiff(envelope) {
+  if (!envelope || typeof envelope !== 'object') return '';
+  const capList = (Array.isArray(envelope.capabilities) ? envelope.capabilities : [])
+    .map(c =>
+      c && c.key !== undefined && c.key !== null ? `${c.key}:${c.status}` : '?'
+    )
+    .sort()
+    .join('|');
+  const certSt = envelope.certificate && envelope.certificate.status;
+  return `status=${envelope.status}|cert=${certSt || 'none'}|caps=${capList}`;
+}
+
+/**
+ * @param {string|null} prev
+ * @param {string} next
+ * @param {boolean} fullDiff
+ * @returns {string|null}
+ */
+function formatWatchFingerprintDiff(prev, next, fullDiff) {
+  if (prev === null || prev === undefined || prev === next) return null;
+  if (fullDiff) {
+    return `Watch diff:\n  before: ${prev}\n  after:  ${next}`;
+  }
+  return `Watch diff: ${chalk.yellow(prev)} → ${chalk.green(next)}`;
+}
+
+/**
+ * @param {string} root
+ * @param {number} maxDepth
+ * @param {number} depth
+ * @returns {string[]}
+ */
+function listDirectoriesRecursive(root, maxDepth, depth = 0) {
+  const out = [];
+  if (depth > maxDepth || !nodeFs().existsSync(root)) return out;
+  let st;
+  try {
+    st = nodeFs().statSync(root);
+  } catch {
+    return out;
+  }
+  if (!st.isDirectory()) {
+    return [root];
+  }
+  out.push(root);
+  let entries;
+  try {
+    entries = nodeFs().readdirSync(root, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const ent of entries) {
+    if (SKIP_DIR_NAMES.has(ent.name)) continue;
+    if (ent.isDirectory()) {
+      out.push(...listDirectoriesRecursive(path.join(root, ent.name), maxDepth, depth + 1));
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {string} appKey
+ * @param {string[]} [extraPaths]
+ * @param {boolean} [includeApplicationYaml]
+ * @returns {{ kind: 'file'|'dir', path: string }[]}
+ */
+function buildWatchTargetList(appKey, extraPaths = [], includeApplicationYaml = false) {
+  const integrationRoot = getIntegrationPathForWatch(appKey);
+  const seen = new Set();
+  /** @type {{ kind: 'file'|'dir', path: string }[]} */
+  const list = [];
+
+  function addFile(abs) {
+    if (!nodeFs().existsSync(abs) || seen.has(abs)) return;
+    seen.add(abs);
+    list.push({ kind: 'file', path: abs });
+  }
+
+  function addDirTree(absRoot) {
+    if (!nodeFs().existsSync(absRoot)) return;
+    const st = nodeFs().statSync(absRoot);
+    if (st.isFile()) {
+      addFile(absRoot);
+      return;
+    }
+    const dirs = listDirectoriesRecursive(absRoot, MAX_DIR_DEPTH);
+    for (const d of dirs) {
+      if (seen.has(d)) continue;
+      seen.add(d);
+      list.push({ kind: 'dir', path: d });
+    }
+  }
+
+  addDirTree(integrationRoot);
+
+  for (const p of extraPaths) {
+    if (!p || typeof p !== 'string') continue;
+    const abs = path.resolve(p.trim());
+    if (!nodeFs().existsSync(abs)) continue;
+    const pst = nodeFs().statSync(abs);
+    if (pst.isFile()) {
+      addFile(abs);
+    } else {
+      addDirTree(abs);
+    }
+  }
+
+  if (includeApplicationYaml) {
+    const y = path.join(integrationRoot, 'application.yaml');
+    addFile(y);
+  }
+
+  return list;
+}
+
+/**
+ * @param {() => void} fn
+ * @param {number} ms
+ * @returns {() => void}
+ */
+function debounce(fn, ms) {
+  let t = null;
+  return () => {
+    if (t) clearTimeout(t);
+    t = setTimeout(() => {
+      t = null;
+      fn();
+    }, ms);
+  };
+}
+
+/**
+ * @param {{ kind: 'file'|'dir', path: string }[]} targets
+ * @param {() => void} onEvent
+ * @returns {() => void}
+ */
+function startWatchers(targets, onEvent) {
+  const handles = [];
+  for (const t of targets) {
+    try {
+      handles.push(nodeFs().watch(t.path, () => onEvent()));
+    } catch {
+      // ignore unreadable paths
+    }
+  }
+  return () => {
+    for (const h of handles) {
+      try {
+        h.close();
+      } catch {
+        // ignore
+      }
+    }
+  };
+}
+
+/**
+ * @param {Object} opts
+ * @param {string} opts.appKey
+ * @param {string[]} [opts.extraPaths]
+ * @param {boolean} [opts.includeApplicationYaml]
+ * @param {number} [opts.debounceMs]
+ * @param {boolean} [opts.watchCi]
+ * @param {boolean} [opts.watchFullDiff]
+ * @param {() => Promise<{ exitCode: number, envelope: Object|null }>} opts.runOnce
+ * @returns {Promise<void>}
+ */
+async function runDatasourceValidationWatchLoop(opts) {
+  const {
+    appKey,
+    extraPaths = [],
+    includeApplicationYaml = false,
+    debounceMs = DEFAULT_DEBOUNCE_MS,
+    watchCi = false,
+    watchFullDiff = false,
+    runOnce
+  } = opts;
+
+  const targets = buildWatchTargetList(appKey, extraPaths, includeApplicationYaml);
+  if (targets.length === 0) {
+    logger.warn(chalk.yellow('Watch: no directories or files to watch; check integration path.'));
+    process.exit(4);
+    return;
+  }
+
+  let prevFp = null;
+  let running = false;
+
+  const execute = async() => {
+    if (running) return;
+    running = true;
+    try {
+      logger.log(chalk.blue('\n[watch] Running validation…'));
+      const { exitCode, envelope } = await runOnce();
+      const fp = fingerprintForWatchDiff(envelope);
+      const diffMsg = formatWatchFingerprintDiff(prevFp, fp, watchFullDiff);
+      if (diffMsg) logger.log(diffMsg);
+      prevFp = fp;
+      if (watchCi) {
+        process.exit(exitCode);
+        return;
+      }
+      logger.log(chalk.gray(`[watch] exit code ${exitCode} — waiting for file changes (Ctrl+C to stop)`));
+    } finally {
+      running = false;
+    }
+  };
+
+  await execute();
+
+  // In production, watchCi triggers process.exit inside execute; with a mocked exit (tests),
+  // still skip watcher setup so the async function can finish and no duplicate runs occur.
+  if (watchCi) {
+    return;
+  }
+
+  const onFs = debounce(execute, debounceMs);
+  const closeAll = startWatchers(targets, onFs);
+
+  const onSig = () => {
+    closeAll();
+    process.exit(130);
+  };
+  process.on('SIGINT', onSig);
+  process.on('SIGTERM', onSig);
+}
+
+module.exports = {
+  DEFAULT_DEBOUNCE_MS,
+  fingerprintForWatchDiff,
+  formatWatchFingerprintDiff,
+  buildWatchTargetList,
+  debounce,
+  startWatchers,
+  runDatasourceValidationWatchLoop
+};

package/lib/utils/declarative-url-ports.js

@@ -0,0 +1,47 @@
+/**
+ * Host port math for declarative url:// resolution (plan 122).
+ *
+ * @fileoverview publishedHostPort vs localHostPort from manifest port + developer-id
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {string|number|null|undefined} raw - developer-id from config
+ * @returns {number} Numeric id; non-numeric or empty → 0
+ */
+function parseDeveloperIdNum(raw) {
+  if (raw === null || raw === undefined || raw === '') {
+    return 0;
+  }
+  const parsed = parseInt(String(raw).trim(), 10);
+  return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+/**
+ * Docker published host port: port + devId*100 (dev 0 → base port).
+ * @param {number} appPort - Manifest listen port
+ * @param {number} developerIdNum
+ * @returns {number}
+ */
+function publishedHostPort(appPort, developerIdNum) {
+  return appPort + developerIdNum * 100;
+}
+
+/**
+ * Local workstation host port: port + 10 + devId*100 (dev 0 → port+10).
+ * @param {number} appPort
+ * @param {number} developerIdNum
+ * @returns {number}
+ */
+function localHostPort(appPort, developerIdNum) {
+  return appPort + 10 + developerIdNum * 100;
+}
+
+module.exports = {
+  parseDeveloperIdNum,
+  publishedHostPort,
+  localHostPort
+};

package/lib/utils/derive-env-key-from-client-id.js

@@ -0,0 +1,41 @@
+/**
+ * Derive pipeline/env segment (dev|tst|pro|miso) from MISO_CLIENTID convention.
+ *
+ * @fileoverview Plan 122 — optional MISO_PIPELINE_ENV_KEY override
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const ENV_TOKENS = new Set(['dev', 'tst', 'pro', 'miso']);
+
+/**
+ * @param {string|null|undefined} clientId - e.g. miso-controller-dev-dataplane
+ * @param {string|null|undefined} pipelineOverride - MISO_PIPELINE_ENV_KEY when set in resolved env
+ * @returns {string} Lowercase env key (default miso)
+ */
+function deriveEnvKeyFromClientId(clientId, pipelineOverride) {
+  const o = pipelineOverride !== undefined && pipelineOverride !== null
+    ? String(pipelineOverride).trim().toLowerCase()
+    : '';
+  if (o && ENV_TOKENS.has(o)) {
+    return o;
+  }
+  if (!clientId || typeof clientId !== 'string') {
+    return 'miso';
+  }
+  const parts = clientId.split('-').filter(Boolean);
+  for (let i = parts.length - 1; i >= 0; i--) {
+    const p = parts[i].toLowerCase();
+    if (ENV_TOKENS.has(p)) {
+      return p;
+    }
+  }
+  return 'miso';
+}
+
+module.exports = {
+  deriveEnvKeyFromClientId,
+  ENV_TOKENS
+};