@aifabrix/builder 2.45.0 → 2.45.5

package/lib/utils/dataplane-cli-version-gate.js

@@ -0,0 +1,202 @@
+/**
+ * Builder CLI ↔ dataplane version gate (plan 142.0).
+ *
+ * Resolves the dataplane-advertised `minBuilderCliVersion` (from cache or a
+ * fresh health probe) and compares it against the installed Builder CLI
+ * version. Used at the top of dataplane API entrypoints so an outdated CLI
+ * cannot mutate dataplane state silently.
+ *
+ * Local-only commands (validate, run, up-infra, file generation) do **not**
+ * call into this module; the gate is intentionally per-call, not global.
+ *
+ * @fileoverview Compatibility gate for dataplane API entrypoints
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { fetchDataplaneGeneralHealth } = require('../api/dataplane-health.api');
+const {
+  getDeviceDataplaneVersions,
+  updateDeviceDataplaneVersions,
+  isCacheStale
+} = require('../core/config-device-dataplane');
+const { compareSemver, isValidSemver } = require('./semver-compare');
+const { formatCliVersionGateError } = require('./dataplane-cli-version-help');
+
+/**
+ * Get the installed Builder CLI version from `package.json`.
+ * Centralized so tests can stub it via Jest module mocks.
+ * @returns {string}
+ */
+function getInstalledCliVersion() {
+  return require('../../package.json').version;
+}
+
+/**
+ * Internal sentinel error code so callers can distinguish gate failures from
+ * generic dataplane errors when needed.
+ * @type {string}
+ */
+const ERROR_CODE = 'CLI_VERSION_INCOMPATIBLE';
+
+/**
+ * True when `err` was thrown by this gate.
+ * @param {*} err
+ * @returns {boolean}
+ */
+function isCliVersionIncompatibleError(err) {
+  return Boolean(err && err.code === ERROR_CODE);
+}
+
+/**
+ * Resolve the dataplane minimum Builder CLI version, preferring cached value
+ * when fresh; otherwise probe health and persist a new snapshot under
+ * `device.<controllerUrl>`.
+ *
+ * @private
+ * @async
+ * @param {string} controllerUrl
+ * @param {string} dataplaneUrl
+ * @param {{ forceRefresh?: boolean }} [options]
+ * @returns {Promise<{ minBuilderCliVersion?: string, dataplaneVersion?: string }>}
+ */
+async function resolveMinBuilderCliVersion(controllerUrl, dataplaneUrl, options = {}) {
+  const forceRefresh = Boolean(options.forceRefresh);
+  if (!forceRefresh) {
+    const cached = await safeReadCache(controllerUrl);
+    if (cached && !isCacheStale(cached)) {
+      return {
+        minBuilderCliVersion: cached.minBuilderCliVersion,
+        dataplaneVersion: cached.version
+      };
+    }
+  }
+
+  const snapshot = await safeFetch(dataplaneUrl);
+  if (!snapshot) {
+    // Cannot reach dataplane → do not gate (offline / pre-rollout). Reuse
+    // any cached value we may have.
+    const cached = await safeReadCache(controllerUrl);
+    return {
+      minBuilderCliVersion: cached ? cached.minBuilderCliVersion : undefined,
+      dataplaneVersion: cached ? cached.version : undefined
+    };
+  }
+
+  await safeWriteCache(controllerUrl, {
+    version: snapshot.version,
+    minBuilderCliVersion: snapshot.minBuilderCliVersion || null
+  });
+  return {
+    minBuilderCliVersion: snapshot.minBuilderCliVersion,
+    dataplaneVersion: snapshot.version
+  };
+}
+
+/**
+ * Read cached versions without throwing — gate failures should not mask real
+ * dataplane errors caused by config corruption.
+ * @private
+ * @async
+ * @param {string} controllerUrl
+ * @returns {Promise<Object|null>}
+ */
+async function safeReadCache(controllerUrl) {
+  if (!controllerUrl) return null;
+  try {
+    return await getDeviceDataplaneVersions(controllerUrl);
+  } catch (_error) {
+    return null;
+  }
+}
+
+/**
+ * Fetch health swallowing transport errors so callers can decide what to do
+ * when the dataplane is unreachable.
+ * @private
+ * @async
+ * @param {string} dataplaneUrl
+ * @returns {Promise<Object|null>}
+ */
+async function safeFetch(dataplaneUrl) {
+  try {
+    return await fetchDataplaneGeneralHealth(dataplaneUrl);
+  } catch (_error) {
+    return null;
+  }
+}
+
+/**
+ * Write the cache without throwing — best-effort persistence.
+ * @private
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} versions
+ * @returns {Promise<void>}
+ */
+async function safeWriteCache(controllerUrl, versions) {
+  if (!controllerUrl) return;
+  try {
+    await updateDeviceDataplaneVersions(controllerUrl, versions);
+  } catch (_error) {
+    // intentionally swallowed — cache write failure must not block the call
+  }
+}
+
+/**
+ * Throw when the installed CLI is older than the dataplane minimum.
+ *
+ * No-op when:
+ *   - `dataplaneUrl` is empty (no dataplane in play)
+ *   - Dataplane omits `minBuilderCliVersion` (no enforcement)
+ *   - Dataplane is unreachable and no cached minimum is known
+ *   - Cached/advertised minimum is not valid semver (warn-only contract per plan)
+ *
+ * @async
+ * @param {string} dataplaneUrl - Dataplane base URL (e.g. `http://localhost:3201`)
+ * @param {Object} [options]
+ * @param {string} [options.controllerUrl] - Controller URL for cache lookup/write
+ * @param {boolean} [options.forceRefresh] - Skip cache and probe health now
+ * @returns {Promise<void>}
+ * @throws {Error & { code: 'CLI_VERSION_INCOMPATIBLE', required: string, installed: string, formatted: string }}
+ */
+async function assertDataplaneCliVersionCompatible(dataplaneUrl, options = {}) {
+  if (!dataplaneUrl || typeof dataplaneUrl !== 'string') {
+    return;
+  }
+  const { minBuilderCliVersion } = await resolveMinBuilderCliVersion(
+    options.controllerUrl || null,
+    dataplaneUrl,
+    { forceRefresh: Boolean(options.forceRefresh) }
+  );
+  if (!minBuilderCliVersion) return;
+  if (!isValidSemver(minBuilderCliVersion)) return;
+
+  // Go through module.exports so tests can stub `getInstalledCliVersion`.
+  const installed = module.exports.getInstalledCliVersion();
+  if (!isValidSemver(installed)) return;
+
+  if (compareSemver(installed, minBuilderCliVersion) >= 0) {
+    return;
+  }
+
+  const formatted = formatCliVersionGateError(minBuilderCliVersion, installed);
+  const error = new Error(
+    `Builder CLI ${installed} is below the dataplane minimum (${minBuilderCliVersion}). ` +
+    'Upgrade with: npm install -g @aifabrix/builder@latest'
+  );
+  error.code = ERROR_CODE;
+  error.required = minBuilderCliVersion;
+  error.installed = installed;
+  error.formatted = formatted;
+  throw error;
+}
+
+module.exports = {
+  assertDataplaneCliVersionCompatible,
+  isCliVersionIncompatibleError,
+  getInstalledCliVersion,
+  ERROR_CODE
+};

package/lib/utils/dataplane-cli-version-help.js

@@ -0,0 +1,74 @@
+/**
+ * Shared "Next actions" + blocking error formatter for the Builder CLI ↔
+ * dataplane version gate (plan 142.0). Used by `auth status` display and by
+ * the gate thrown from dataplane API entrypoints so users see the same bullets
+ * wherever the incompatibility surfaces.
+ *
+ * @fileoverview Shared CLI version-gate UX helpers (next actions + blocking)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const {
+  formatBlockingError,
+  formatNextActions
+} = require('./cli-test-layout-chalk');
+
+/**
+ * Build the canonical Next actions bullets for a CLI ↔ dataplane mismatch.
+ *
+ * @param {string} required - Minimum Builder CLI semver advertised by dataplane
+ * @param {string} installed - Current Builder CLI semver (from package.json)
+ * @returns {string[]} Bullet lines (no prefix)
+ */
+function buildCliVersionUpgradeNextActions(required, installed) {
+  const req = (required || '').trim() || 'the dataplane minimum';
+  const inst = (installed || '').trim() || 'this CLI';
+  return [
+    `Upgrade Builder CLI: npm install -g @aifabrix/builder@${req} (or @latest)`,
+    'Confirm after upgrade: aifabrix auth status',
+    'CI / scripts: aifabrix auth status --validate (exit 3 until upgraded)',
+    `Local work (validate, run, up-infra) still works on ${inst}`
+  ];
+}
+
+/**
+ * Build the blocking line shown before the Next actions block when the CLI is
+ * older than the dataplane minimum.
+ *
+ * @param {string} required - Required minimum semver
+ * @param {string} installed - Currently installed semver
+ * @returns {string}
+ */
+function buildCliVersionBlockingLine(required, installed) {
+  const req = (required || '').trim() || '(unknown)';
+  const inst = (installed || '').trim() || '(unknown)';
+  return formatBlockingError(
+    `Builder CLI ${inst} is below the dataplane minimum (${req}). Upgrade before running dataplane commands.`
+  );
+}
+
+/**
+ * Format the full version-gate error block (blocking line + Next actions).
+ * Suitable for `handleCommandError` output and the `auth status` incompatible
+ * branch.
+ *
+ * @param {string} required - Required minimum semver
+ * @param {string} installed - Currently installed semver
+ * @returns {string} Multi-line, chalk-colored block
+ */
+function formatCliVersionGateError(required, installed) {
+  return [
+    buildCliVersionBlockingLine(required, installed),
+    '',
+    formatNextActions(buildCliVersionUpgradeNextActions(required, installed))
+  ].join('\n');
+}
+
+module.exports = {
+  buildCliVersionUpgradeNextActions,
+  buildCliVersionBlockingLine,
+  formatCliVersionGateError
+};

package/lib/utils/datasource-export-display.js

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview TTY display for `datasource export` (plan 144)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const logger = require('./logger');
+const {
+  sectionTitle,
+  headerKeyValue,
+  metadata: metaGray,
+  formatSuccessLine,
+  formatWarningLine
+} = require('./cli-test-layout-chalk');
+const { emitManifestSourceMetadata } = require('./manifest-source-emit');
+const { integrationManifestLabel } = require('../datasource/datasource-load-export-context');
+const { formatElapsedMs } = require('./datasource-load-export-ui');
+
+const SEP = '────────────────────────────────────────────────────────';
+
+function logExportHeader(ctx, envLabel) {
+  logger.log(SEP);
+  logger.log(sectionTitle(`Export records — ${ctx.datasourceKey}`));
+  logger.log(headerKeyValue('Environment:', envLabel || '—'));
+  logger.log(headerKeyValue('System:', ctx.systemKey));
+  logger.log(SEP);
+  logger.log(metaGray('  Layer: governed records search (ABAC applied)'));
+  logger.log(metaGray('  Not used: direct database access'));
+  logger.log('');
+}
+
+function logExportVerboseStats(result) {
+  const excluded = result.meta?.excluded || {};
+  const abac = excluded.abac !== undefined && excluded.abac !== null ? excluded.abac : 0;
+  const filterEx =
+    excluded.filter !== undefined && excluded.filter !== null ? excluded.filter : 0;
+  logger.log(
+    metaGray(
+      `  Fetched: ${result.recordCount} records · excluded abac ${abac} · filter ${filterEx}`
+    )
+  );
+  const stat = fs.statSync(result.outputFile);
+  const mb = (stat.size / (1024 * 1024)).toFixed(2);
+  logger.log(
+    metaGray(`  Wrote: ${result.recordCount} line(s) (${result.format}) · ${mb} MB`)
+  );
+  logger.log('');
+}
+
+/**
+ * @param {Object} result
+ */
+function displayExportAbacZeroRowsWarning(result) {
+  const excludedAbac = Number(result.excludedAbac ?? result.meta?.excluded?.abac) || 0;
+  if (result.recordCount !== 0 || excludedAbac <= 0) {
+    return;
+  }
+  logger.log(
+    formatWarningLine(
+      `Governed search returned 0 rows; ABAC excluded ${excludedAbac} record(s) for your principal.`
+    )
+  );
+  logger.log(
+    metaGray(
+      '  The physical table may still hold data — export only includes rows your token may read.'
+    )
+  );
+  logger.log(
+    metaGray(
+      '  Fix: upload a protection manifest (aifabrix protection upload <datasourceKey>) with dimension grants for your user, then retry.'
+    )
+  );
+  logger.log('');
+}
+
+/**
+ * @param {Object} result
+ */
+function displayExportLimitCapWarning(result) {
+  if (!result.hitLimitCap) {
+    return;
+  }
+  logger.log(
+    formatWarningLine(`Fetched ${result.recordCount} records (limit cap). More rows may exist.`)
+  );
+  logger.log(metaGray('  Re-run with --filter or wait for dataplane search pagination.'));
+  logger.log('');
+}
+
+/**
+ * @param {Object} result
+ */
+function logExportDurationFooter(result) {
+  if (result.durationMs === undefined || result.durationMs === null) {
+    return;
+  }
+  logger.log(metaGray(`  Completed in ${formatElapsedMs(result.durationMs)}`));
+  logger.log('');
+}
+
+/**
+ * @param {Object} result
+ * @param {Object} opts
+ */
+function displayDatasourceExportTTY(result, opts = {}) {
+  const ctx = result.context || {};
+  logExportHeader(ctx, opts.environment);
+
+  const filterLabel = result.filters ? 'filters (set)' : 'filters (none)';
+  logger.log(
+    metaGray(`  Search: intent ${result.intent} · limit ${result.limit} · ${filterLabel}`)
+  );
+  emitManifestSourceMetadata({
+    tier: 'int',
+    configPath: ctx.manifestPath,
+    labelPrefix: integrationManifestLabel(ctx.appKey)
+  });
+  logger.log(metaGray(`  Output: ${result.outputFile}`));
+  logger.log('');
+
+  if (opts.verbose) {
+    logExportVerboseStats(result);
+  }
+
+  displayExportAbacZeroRowsWarning(result);
+  displayExportLimitCapWarning(result);
+  logger.log(formatSuccessLine('Export complete'));
+  logExportDurationFooter(result);
+  logger.log(SEP);
+}
+
+module.exports = {
+  displayDatasourceExportTTY
+};

package/lib/utils/datasource-load-display.js

@@ -0,0 +1,174 @@
+/**
+ * @fileoverview TTY display for `datasource load` (plan 144)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+const {
+  sectionTitle,
+  headerKeyValue,
+  metadata: metaGray,
+  formatSuccessLine,
+  formatBlockingError,
+  successGlyph,
+  failureGlyph
+} = require('./cli-test-layout-chalk');
+const { emitManifestSourceMetadata } = require('./manifest-source-emit');
+const { integrationManifestLabel } = require('../datasource/datasource-load-export-context');
+const { formatElapsedMs } = require('./datasource-load-export-ui');
+
+const SEP = '────────────────────────────────────────────────────────';
+
+function logLoadHeader(ctx, envLabel) {
+  logger.log(SEP);
+  logger.log(sectionTitle(`Load records — ${ctx.datasourceKey}`));
+  logger.log(headerKeyValue('Environment:', envLabel || '—'));
+  logger.log(headerKeyValue('System:', ctx.systemKey));
+  logger.log(SEP);
+  logger.log(metaGray('  Layer: dataplane bulk sync'));
+  emitManifestSourceMetadata({
+    tier: 'int',
+    configPath: ctx.manifestPath,
+    labelPrefix: integrationManifestLabel(ctx.appKey)
+  });
+}
+
+function displayLoadDryRun(result) {
+  logger.log(chalk.cyan('  Mode: dry-run (no upload)'));
+  logger.log('');
+  const mb = (result.estimatedPayloadBytes / (1024 * 1024)).toFixed(2);
+  const batchCount = Math.ceil(result.recordCount / result.batchSize) || 0;
+  logger.log(
+    metaGray(
+      `  Parsed: ${result.recordCount} records · format ${result.format} · est. payload ~${mb} MB`
+    )
+  );
+  logger.log(
+    metaGray(`  Would upload: ${batchCount} batch(es) · syncType ${result.syncType}`)
+  );
+  logger.log('');
+  logger.log(formatSuccessLine('Dry-run passed'));
+}
+
+function displayLoadBatchesVerbose(batches) {
+  batches.forEach(batch => {
+    if (batch.error) {
+      logger.log(
+        `  Batch ${batch.index}/${batch.total}  ${failureGlyph()} failed (${batch.error})`
+      );
+      return;
+    }
+    const failed = Array.isArray(batch.failed) ? batch.failed.length : 0;
+    if (failed > 0) {
+      logger.log(
+        `  Batch ${batch.index}/${batch.total}  ${failureGlyph()} failed ${failed} of ${batch.recordCount || '?'}`
+      );
+      return;
+    }
+    logger.log(
+      `  Batch ${batch.index}/${batch.total}  ${successGlyph()} inserted ${batch.insertedCount || 0} · updated ${batch.updatedCount || 0} · failed 0`
+    );
+  });
+}
+
+const MAX_FAILURE_LINES = 5;
+
+/**
+ * @param {Object[]} batches
+ */
+function displayLoadFailureSamples(batches) {
+  const samples = [];
+  (batches || []).forEach(batch => {
+    if (!Array.isArray(batch.failed)) return;
+    batch.failed.forEach(item => {
+      if (samples.length >= MAX_FAILURE_LINES) return;
+      const key = item.key ? String(item.key) : '—';
+      const message = item.message || batch.error || 'failed';
+      samples.push({ key, message });
+    });
+  });
+  if (samples.length === 0) return;
+  logger.log('');
+  logger.log(chalk.white(`  Failures (first ${MAX_FAILURE_LINES})`));
+  samples.forEach(({ key, message }) => {
+    logger.log(`  • ${key} — ${message}`);
+  });
+}
+
+function displayLoadVerdict(result) {
+  const failed = result.totals.failedCount || 0;
+  const ok = result.recordCount - failed;
+  if (failed > 0) {
+    if (result.batches && result.batches.length > 0) {
+      displayLoadFailureSamples(result.batches);
+      logger.log('');
+    }
+    logger.log(formatBlockingError(`${ok} ok · ${failed} failed`));
+  } else {
+    logger.log(
+      formatSuccessLine(
+        `${result.recordCount} processed · ${result.totals.insertedCount} inserted · ${result.totals.updatedCount} updated · 0 failed`
+      )
+    );
+  }
+}
+
+/**
+ * @param {Object} result
+ */
+function logLoadDurationFooter(result) {
+  if (result.durationMs === undefined || result.durationMs === null) {
+    return;
+  }
+  logger.log(metaGray(`  Completed in ${formatElapsedMs(result.durationMs)}`));
+  logger.log('');
+}
+
+/**
+ * @param {Object} result
+ * @param {Object} opts
+ */
+function displayLoadUploadSummary(result, opts) {
+  const batchCount = Math.ceil(result.recordCount / result.batchSize) || 0;
+  logger.log(
+    metaGray(
+      `  Parsed: ${result.recordCount} records · format ${result.format} · est. ${batchCount} batch(es) @ ${result.batchSize}`
+    )
+  );
+  logger.log('');
+  if (opts.verbose) {
+    displayLoadBatchesVerbose(result.batches);
+    logger.log('');
+  }
+  displayLoadVerdict(result);
+}
+
+/**
+ * @param {Object} result
+ * @param {Object} opts
+ */
+function displayDatasourceLoadTTY(result, opts = {}) {
+  const ctx = result.context || {};
+  logLoadHeader(ctx, opts.environment);
+  logger.log(metaGray(`  Data file: ${result.file}`));
+  logger.log('');
+
+  if (result.dryRun) {
+    displayLoadDryRun(result);
+    logLoadDurationFooter(result);
+    logger.log(SEP);
+    return;
+  }
+
+  displayLoadUploadSummary(result, opts);
+  logLoadDurationFooter(result);
+  logger.log(SEP);
+}
+
+module.exports = {
+  displayDatasourceLoadTTY
+};

package/lib/utils/datasource-load-export-ui.js

@@ -0,0 +1,120 @@
+/**
+ * @fileoverview Spinner + elapsed time for datasource load/export (plan 144)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+const { formatProgress } = require('./cli-test-layout-chalk');
+
+/**
+ * @param {number} ms
+ * @returns {string}
+ */
+function formatElapsedMs(ms) {
+  const n = Math.max(0, Math.round(Number(ms) || 0));
+  if (n < 1000) {
+    return `${n} ms`;
+  }
+  if (n < 60000) {
+    const sec = n / 1000;
+    return sec >= 10 ? `${Math.round(sec)} s` : `${sec.toFixed(1)} s`;
+  }
+  const min = Math.floor(n / 60000);
+  const sec = Math.round((n % 60000) / 1000);
+  return sec > 0 ? `${min} m ${sec} s` : `${min} m`;
+}
+
+/**
+ * @param {Object} [options]
+ * @param {boolean} [options.json]
+ * @returns {boolean}
+ */
+function shouldShowDatasourceLoadExportProgress(options = {}) {
+  return options.json !== true;
+}
+
+/**
+ * @param {Object} [options]
+ * @returns {boolean}
+ */
+function shouldUseDatasourceLoadExportSpinner(options = {}) {
+  if (!shouldShowDatasourceLoadExportProgress(options)) {
+    return false;
+  }
+  return Boolean(process && process.stdout && process.stdout.isTTY);
+}
+
+/**
+ * @param {string} operation
+ * @param {string} datasourceKey
+ * @returns {string}
+ */
+function buildDatasourceLoadExportSpinnerLabel(operation, datasourceKey) {
+  const key =
+    datasourceKey && String(datasourceKey).trim() ? String(datasourceKey).trim() : 'datasource';
+  if (operation === 'export') {
+    return `Exporting records for ${key}…`;
+  }
+  if (operation === 'load-dry-run') {
+    return `Parsing records for ${key}…`;
+  }
+  return `Loading records for ${key} into dataplane…`;
+}
+
+/**
+ * @param {string} operation
+ * @param {string} datasourceKey
+ * @returns {string}
+ */
+function buildDatasourceLoadExportProgressText(operation, datasourceKey) {
+  return formatProgress(buildDatasourceLoadExportSpinnerLabel(operation, datasourceKey));
+}
+
+/**
+ * @async
+ * @param {Function} work
+ * @param {Object} [opts]
+ * @param {'load'|'load-dry-run'|'export'} [opts.operation]
+ * @param {string} [opts.datasourceKey]
+ * @param {boolean} [opts.json]
+ * @returns {Promise<*>}
+ */
+async function runWithDatasourceLoadExportSpinner(work, opts = {}) {
+  if (!shouldShowDatasourceLoadExportProgress(opts)) {
+    return work();
+  }
+
+  const operation = opts.operation || 'load';
+  const datasourceKey = opts.datasourceKey || '';
+
+  if (!shouldUseDatasourceLoadExportSpinner(opts)) {
+    logger.log(buildDatasourceLoadExportProgressText(operation, datasourceKey));
+    return work();
+  }
+
+  const ora = require('ora');
+  const label = buildDatasourceLoadExportSpinnerLabel(operation, datasourceKey);
+  const spinner = ora({
+    text: chalk.white(label),
+    spinner: 'dots'
+  }).start();
+
+  try {
+    return await work();
+  } finally {
+    spinner.stop();
+  }
+}
+
+module.exports = {
+  formatElapsedMs,
+  shouldShowDatasourceLoadExportProgress,
+  shouldUseDatasourceLoadExportSpinner,
+  buildDatasourceLoadExportSpinnerLabel,
+  buildDatasourceLoadExportProgressText,
+  runWithDatasourceLoadExportSpinner
+};