@aifabrix/builder 2.44.6 → 2.45.5

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

package/lib/utils/datasource-test-run-capability-scope.js

@@ -1,12 +1,12 @@
 /**
- * @fileoverview Single-capability CLI contract when --capability is set.
+ * @fileoverview Single-capability CLI contract when positional [capabilityKey] is set.
  * @author AI Fabrix Team
  * @version 2.0.0
  */
 
 /**
  * @param {Object|null|undefined} envelope - DatasourceTestRun-like
- * @param {string|undefined|null} requestedCapabilityKey - From CLI --capability
+ * @param {string|undefined|null} requestedCapabilityKey - From positional [capabilityKey]
  * @returns {{ violated: boolean, message?: string, count?: number }}
  */
 function analyzeCapabilityScope(envelope, requestedCapabilityKey) {
@@ -34,7 +34,7 @@ function analyzeCapabilityScope(envelope, requestedCapabilityKey) {
   return {
     violated: true,
     count: caps.length,
-    message: `Capabilities scope: with --capability "${key}", expected a single row in capabilities[]; server returned ${caps.length} (${preview}${suffix}).`
+    message: `Capabilities scope: with capabilityKey "${key}", expected a single row in capabilities[]; server returned ${caps.length} (${preview}${suffix}).`
   };
 }
 

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

@@ -98,7 +98,7 @@ function colorStepLine(ok, body) {
 }
 
 /**
- * Normalize CLI --capability value for matching envelope.capabilities[].key
+ * Normalize positional [capabilityKey] for matching envelope.capabilities[].key
  * @param {*} focusCapabilityKey
  * @returns {string} trimmed or ''
  */
@@ -354,7 +354,7 @@ function pickExecutiveVerdictLine(envelope) {
 }
 
 /**
- * Plan §3.9: explicit line when E2E has no capability rows (skipped when --capability drill-down is active).
+ * Plan §3.9: explicit line when E2E has no capability rows (skipped when capability drill-down is active).
  * @param {string[]} lines
  * @param {Object} envelope
  * @param {{ focusCapabilityKey?: string }} [options]
@@ -428,7 +428,7 @@ function formatDatasourceTestRunSummary(envelope, options = {}) {
  *   focusCapabilityKey?: string,
  *   includeRefs?: boolean,
  *   includeDebugExecutionSummary?: boolean
- * }} [options] - When focusCapabilityKey set (e.g. --capability), append single-cap block (plan §2.3).
+ * }} [options] - When focusCapabilityKey set (positional [capabilityKey]), append single-cap block (plan §2.3).
  *   includeDebugExecutionSummary: show dataplane `debug.executionSummary` in header (TTY debug appendix uses CLI `--debug`).
  * @returns {string}
  */

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

@@ -49,7 +49,11 @@ function printDatasourceTestRunForTTY(envelope, options = {}) {
     includeDebugExecutionSummary: Boolean(mode)
   };
   if (options.json) {
-    logger.log(JSON.stringify(envelope));
+    const payload =
+      options.auditEvidenceVerification && typeof options.auditEvidenceVerification === 'object'
+        ? { ...envelope, auditEvidenceVerification: options.auditEvidenceVerification }
+        : envelope;
+    logger.log(JSON.stringify(payload));
     return;
   }
   if (options.summary) {