@aifabrix/builder 2.45.0 → 2.45.5

package/lib/utils/agent-trust-run-display.js

@@ -0,0 +1,231 @@
+/**
+ * @fileoverview TTY display for agent metadata trust runs (plan 143).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+const { sectionTitle, headerKeyValue, metadata: metaGray } = require('./cli-test-layout-chalk');
+const { statusGlyph } = require('./datasource-test-run-display');
+const { trustDecisionToRowStatus } = require('../datasource/agent-trust-map');
+
+const SEP = '────────────────────────────────';
+
+/** @type {{ datasource: number, trust: number, conf: number, status: number, cache: number }} */
+const TRUST_TABLE_COLS = {
+  datasource: 30,
+  trust: 24,
+  conf: 6,
+  status: 8,
+  cache: 8
+};
+
+function trustGlyph(trustDecision) {
+  return statusGlyph(trustDecisionToRowStatus(trustDecision));
+}
+
+function publishGateLine(trustDecision, strict) {
+  if (trustDecision === 'notTrusted') return chalk.red('blocked (trustDecision notTrusted)');
+  if (strict) {
+    return trustDecision === 'trusted'
+      ? chalk.green('allowed (strict: trusted)')
+      : chalk.yellow('blocked (strict requires trusted)');
+  }
+  return chalk.green('allowed (warning-only); use --strict to require trusted');
+}
+
+function logTrustHeader(run, env) {
+  logger.log(SEP);
+  logger.log(sectionTitle(`Semantic trust — ${run.datasourceKey}`));
+  logger.log(headerKeyValue('Environment:', env));
+  logger.log(headerKeyValue('System:', run.systemKey || '—'));
+  logger.log(SEP);
+  logger.log(metaGray('  Layer checked: business metadata (404.5 agent validation)'));
+  logger.log(metaGray('  Not checked here: vendor connectivity, sync, record counts (use test-e2e)'));
+  logger.log('');
+}
+
+function logTrustSummaryBlock(run) {
+  const confPct = Math.round((run.confidence || 0) * 100);
+  logger.log(
+    headerKeyValue(
+      'Trust:',
+      `${trustGlyph(run.trustDecision)} ${run.trustDecision} · confidence ${confPct}% · ${run.validationStatus}`
+    )
+  );
+  if (!run.validatedAt) return;
+  const hashShort = run.inputHash ? `${String(run.inputHash).slice(0, 8)}…` : '—';
+  logger.log(
+    metaGray(
+      `  Validated: ${run.validatedAt} · inputHash ${hashShort} · cache: ${run.cacheHit ? 'hit' : 'miss'}`
+    )
+  );
+}
+
+function logTrustWarningsAndFindings(run, opts) {
+  if (run.summary) {
+    logger.log('');
+    logger.log(chalk.white('  Summary'));
+    logger.log(`  ${run.summary}`);
+  }
+  const warnings = Array.isArray(run.highLevelWarnings) ? run.highLevelWarnings : [];
+  const findings = Array.isArray(run.findings) ? run.findings : [];
+  const showVerboseFindings = opts.verbose === true && findings.length > 0;
+  if (warnings.length && !showVerboseFindings) {
+    logger.log('');
+    logger.log(chalk.yellow('  Warnings (high level)'));
+    warnings.forEach(w => logger.log(`  • ${w}`));
+  }
+  if (!showVerboseFindings) return;
+  logger.log('');
+  logger.log(chalk.white('  Findings (verbose, max 10)'));
+  findings.slice(0, 10).forEach(f => {
+    logger.log(`  • [${f.severity || 'info'}] ${f.code || 'FINDING'}: ${f.message || ''}`);
+  });
+}
+
+function logTrustFooter(run, opts) {
+  logger.log('');
+  logger.log(metaGray('  ── Integration reality (informative) ──'));
+  logger.log(metaGray(`  Local manifest:  ${opts.noSync ? 'not uploaded (--no-sync)' : 'uploaded before run'}`));
+  logger.log(metaGray(`  Publish gate:    ${publishGateLine(run.trustDecision, opts.strict === true)}`));
+  logger.log(SEP);
+}
+
+function displayAgentTrustRunTTY(run, opts = {}) {
+  if (!run || opts.json === true) return;
+  const env = opts.environment ? String(opts.environment) : 'dev';
+  logTrustHeader(run, env);
+  logTrustSummaryBlock(run);
+  logTrustWarningsAndFindings(run, opts);
+  logTrustFooter(run, opts);
+}
+
+function trustCacheLabel(trustRun) {
+  if (!trustRun || typeof trustRun !== 'object') return '—';
+  if (trustRun.readLatest === true) return 'latest';
+  if (trustRun.cacheHit === true) return 'hit';
+  if (trustRun.cacheHit === false) return 'miss';
+  return '—';
+}
+
+/**
+ * @param {boolean} showCache
+ * @returns {number}
+ */
+function trustTableLineWidth(showCache) {
+  const { datasource, trust, conf, status, cache } = TRUST_TABLE_COLS;
+  let w = 2 + datasource + 1 + trust + 1 + conf + 1 + status;
+  if (showCache) w += 1 + cache;
+  return w;
+}
+
+/**
+ * @param {string} key
+ * @returns {string}
+ */
+function formatTrustTableDatasourceCol(key) {
+  return String(key || '').padEnd(TRUST_TABLE_COLS.datasource).slice(0, TRUST_TABLE_COLS.datasource);
+}
+
+/**
+ * @param {Object|null|undefined} tr
+ * @returns {string}
+ */
+function formatTrustTableTrustCol(tr) {
+  const w = TRUST_TABLE_COLS.trust;
+  if (!tr || !tr.trustDecision) return '—'.padEnd(w);
+  const decision = String(tr.trustDecision);
+  const cell = `${trustGlyph(decision)} ${decision}`;
+  return cell.length > w ? cell.slice(0, w) : cell.padEnd(w);
+}
+
+/**
+ * @param {Object|null|undefined} tr
+ * @returns {string}
+ */
+function formatTrustTableConfCol(tr) {
+  const w = TRUST_TABLE_COLS.conf;
+  if (!tr || typeof tr.confidence !== 'number') return '—'.padStart(w);
+  return `${Math.round(tr.confidence * 100)}%`.padStart(w);
+}
+
+/**
+ * @param {Object|null|undefined} tr
+ * @param {Object} row
+ * @returns {string}
+ */
+function formatTrustTableStatusCol(tr, row) {
+  const w = TRUST_TABLE_COLS.status;
+  const raw = tr ? String(tr.validationStatus || '—') : row.error || 'fail';
+  return raw.padEnd(w).slice(0, w);
+}
+
+/**
+ * @param {boolean} showCache
+ */
+function logSystemTrustTableHeader(showCache) {
+  const { datasource, trust, conf, status, cache } = TRUST_TABLE_COLS;
+  let header = `  ${'Datasource'.padEnd(datasource)} ${'Trust'.padEnd(trust)} ${'Conf.'.padStart(conf)} ${'Status'.padEnd(status)}`;
+  if (showCache) header += ` ${'Cache'.padEnd(cache)}`;
+  logger.log(chalk.white(header));
+  logger.log(chalk.gray(`  ${'─'.repeat(trustTableLineWidth(showCache))}`));
+}
+
+/**
+ * @param {Object} row
+ * @param {boolean} showCache
+ * @returns {string}
+ */
+function formatTrustTableRow(row, showCache) {
+  const tr = row.trustRun;
+  let line = `  ${formatTrustTableDatasourceCol(row.key)} ${formatTrustTableTrustCol(tr)} ${formatTrustTableConfCol(tr)} ${formatTrustTableStatusCol(tr, row)}`;
+  if (showCache) {
+    line += ` ${trustCacheLabel(tr).padEnd(TRUST_TABLE_COLS.cache).slice(0, TRUST_TABLE_COLS.cache)}`;
+  }
+  return line;
+}
+
+function logSystemTrustTable(list, opts = {}) {
+  const showCache = opts.showCache === true;
+  logSystemTrustTableHeader(showCache);
+  for (const row of list) {
+    logger.log(formatTrustTableRow(row, showCache));
+  }
+}
+
+function displaySystemTrustRollupTTY(systemKey, rows, opts = {}) {
+  if (opts.json === true) return;
+  const list = Array.isArray(rows) ? rows : [];
+  logger.log(SEP);
+  logger.log(sectionTitle(`Semantic trust — system ${systemKey} (${list.length} datasources)`));
+  const { deriveSystemStatus } = require('./external-system-system-test-tty');
+  const worst = deriveSystemStatus(
+    list.map(r => ({
+      success: r.success !== false,
+      datasourceTestRun: {
+        status: r.trustRun ? trustDecisionToRowStatus(r.trustRun.trustDecision) : 'fail'
+      }
+    }))
+  );
+  logger.log(
+    headerKeyValue('System trust:', `${statusGlyph(worst)} ${worst} (worst-of rollup)`)
+  );
+  logger.log('');
+  logSystemTrustTable(list, opts);
+  logger.log('');
+  logger.log(metaGray('  ── What this run proved ──'));
+  logger.log(metaGray(`  ✔ Semantic metadata reviewed for ${list.length} datasource(s) on dataplane`));
+  logger.log(metaGray('  ✖ Did not call external APIs or run CIP (not E2E)'));
+  logger.log(SEP);
+}
+
+module.exports = {
+  displayAgentTrustRunTTY,
+  displaySystemTrustRollupTTY,
+  formatTrustTableRow,
+  TRUST_TABLE_COLS
+};

package/lib/utils/agent-trust-run-exit.js

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Exit codes for agent metadata trust CLI runs (plan 143).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { trustDecisionToRowStatus } = require('../datasource/agent-trust-map');
+const { deriveSystemStatus } = require('./external-system-system-test-tty');
+const { computeExitCodeFromDatasourceTestRun } = require('./datasource-test-run-exit');
+
+/**
+ * @param {Object|null|undefined} run
+ * @param {Object} [opts]
+ * @param {boolean} [opts.warningsAsErrors]
+ * @param {boolean} [opts.strict]
+ * @returns {number}
+ */
+function computeExitCodeFromTrustRun(run, opts = {}) {
+  if (!run || typeof run !== 'object') return 3;
+  const td = run.trustDecision;
+  if (run.validationStatus === 'failed' || td === 'notTrusted') return 1;
+  if (opts.strict === true && td !== 'trusted') return 1;
+  if (opts.warningsAsErrors === true && td === 'usableWithWarnings') return 1;
+  if (td === 'trusted' || td === 'usableWithWarnings' || td === 'pending') return 0;
+  return 3;
+}
+
+/**
+ * @param {Array<{ success?: boolean, trustRun?: Object|null }>} rows
+ * @param {Object} [opts]
+ * @returns {number}
+ */
+function computeSystemExitCodeFromTrustRows(rows, opts = {}) {
+  const list = Array.isArray(rows) ? rows : [];
+  let worst = 0;
+  for (const row of list) {
+    const code = computeExitCodeFromTrustRun(row && row.trustRun, opts);
+    if (code === 3) return 3;
+    if (code > worst) worst = code;
+  }
+  if (worst > 0) return worst;
+  const synthetic = list.map(r => {
+    const tr = r && r.trustRun;
+    const st = tr ? trustDecisionToRowStatus(tr.trustDecision) : 'fail';
+    return { success: st !== 'fail', datasourceTestRun: { status: st } };
+  });
+  const rollup = deriveSystemStatus(synthetic);
+  return computeExitCodeFromDatasourceTestRun(
+    { status: rollup },
+    { warningsAsErrors: opts.warningsAsErrors === true }
+  );
+}
+
+module.exports = {
+  computeExitCodeFromTrustRun,
+  computeSystemExitCodeFromTrustRows
+};

package/lib/utils/agent-trust-wait-ui.js

@@ -0,0 +1,94 @@
+/**
+ * TTY ora spinner for slow agent metadata validation POST (non-cached path).
+ *
+ * @fileoverview Agent trust wait presentation (aligned with validation-poll-ui)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+
+function shouldUseAgentTrustWaitSpinner() {
+  return Boolean(process && process.stdout && process.stdout.isTTY);
+}
+
+/**
+ * @param {string} [datasourceKey]
+ * @param {number} deadlineMs
+ * @returns {string}
+ */
+function buildAgentTrustWaitSpinnerText(datasourceKey, deadlineMs) {
+  const remainingSec = Math.max(0, Math.ceil((deadlineMs - Date.now()) / 1000));
+  const key =
+    datasourceKey && String(datasourceKey).trim() ? String(datasourceKey).trim() : 'datasource';
+  return `Waiting for semantic trust validation… ${key} (~${remainingSec}s left)`;
+}
+
+/**
+ * Run a blocking validate POST behind a TTY spinner (skipped when not a TTY).
+ *
+ * @async
+ * @param {Function} work - Zero-arg async function performing the HTTP call
+ * @param {Object} opts
+ * @param {string} [opts.datasourceKey]
+ * @param {number} opts.timeoutMs
+ * @returns {Promise<*>}
+ */
+async function runWithAgentTrustWaitSpinner(work, opts = {}) {
+  const timeoutMs =
+    Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0 ? opts.timeoutMs : 120000;
+  const deadlineMs = Date.now() + timeoutMs;
+  const datasourceKey = opts.datasourceKey;
+
+  if (!shouldUseAgentTrustWaitSpinner()) {
+    return work();
+  }
+
+  const ora = require('ora');
+  const spinner = ora({
+    text: buildAgentTrustWaitSpinnerText(datasourceKey, deadlineMs),
+    spinner: 'dots'
+  }).start();
+
+  const tick = setInterval(() => {
+    spinner.text = buildAgentTrustWaitSpinnerText(datasourceKey, deadlineMs);
+  }, 1000);
+
+  try {
+    return await work();
+  } finally {
+    clearInterval(tick);
+    spinner.stop();
+  }
+}
+
+const NON_TTY_LOG_MS = 5000;
+
+/**
+ * Optional one-line hint on non-TTY before a slow validate (throttled by caller usage).
+ *
+ * @param {string} [datasourceKey]
+ * @param {number} timeoutMs
+ */
+function logAgentTrustWaitHintOnce(datasourceKey, timeoutMs) {
+  if (shouldUseAgentTrustWaitSpinner()) return;
+  const budgetSec = Math.max(1, Math.ceil(timeoutMs / 1000));
+  const key =
+    datasourceKey && String(datasourceKey).trim() ? String(datasourceKey).trim() : 'datasource';
+  logger.log(
+    chalk.gray(
+      `Waiting for semantic trust validation… ${key} (may take up to ~${budgetSec}s; not cached)`
+    )
+  );
+}
+
+module.exports = {
+  shouldUseAgentTrustWaitSpinner,
+  buildAgentTrustWaitSpinnerText,
+  runWithAgentTrustWaitSpinner,
+  logAgentTrustWaitHintOnce,
+  NON_TTY_LOG_MS
+};

package/lib/utils/cli-exit-codes.js

@@ -0,0 +1,30 @@
+/**
+ * Canonical Builder CLI exit codes for scriptable commands.
+ *
+ * Documented in `docs/commands/authentication.md`. Use in
+ * `aifabrix auth status --validate` and any future `--validate`-style flag.
+ *
+ * @fileoverview Exit-code constants for scriptable Builder CLI commands
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+/** Success. */
+const EXIT_OK = 0;
+
+/** Not authenticated / invalid token. */
+const EXIT_NOT_AUTHENTICATED = 1;
+
+/**
+ * Authenticated but installed Builder CLI version is older than the dataplane
+ * minimum advertised by `GET /api/v1/health → minBuilderCliVersion` (plan 403.0).
+ */
+const EXIT_CLI_VERSION_INCOMPATIBLE = 3;
+
+module.exports = {
+  EXIT_OK,
+  EXIT_NOT_AUTHENTICATED,
+  EXIT_CLI_VERSION_INCOMPATIBLE
+};

package/lib/utils/cli-sync-options.js

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Detect skip-sync from Commander options and raw argv (--no-sync → sync: false).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * True when the user passed `--no-sync` or Commander set `sync: false` / `noSync: true`.
+ * Do not use for `protection upload --no-sync` (post-upload datasource sync only).
+ *
+ * @param {Object|null|undefined} options - Commander-parsed options
+ * @param {import('commander').Command} [cmd] - Commander command (for rawArgs fallback)
+ * @returns {boolean}
+ */
+function cliOptsSkipSync(options, cmd) {
+  if (!options || typeof options !== 'object') {
+    return false;
+  }
+  if (options.noSync === true) {
+    return true;
+  }
+  if (options.sync === false) {
+    return true;
+  }
+  const raw = cmd && Array.isArray(cmd.rawArgs) ? cmd.rawArgs : [];
+  return raw.includes('--no-sync');
+}
+
+module.exports = {
+  cliOptsSkipSync
+};

package/lib/utils/credential-push-ui.js

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview Progress line + optional in-place spinner for credential secret push.
+ * @author AI Fabrix Team
+ * @version 1.2.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+const { formatProgress } = require('./cli-test-layout-chalk');
+
+/**
+ * @param {Object} [options]
+ * @param {boolean} [options.json] - When true, skip progress line and spinner
+ * @returns {boolean}
+ */
+function shouldShowCredentialPushProgress(options = {}) {
+  return options.json !== true;
+}
+
+/**
+ * @param {Object} [options]
+ * @returns {boolean}
+ */
+function shouldUseCredentialPushSpinner(options = {}) {
+  if (!shouldShowCredentialPushProgress(options)) {
+    return false;
+  }
+  return Boolean(process && process.stdout && process.stdout.isTTY);
+}
+
+/**
+ * @param {string} systemKey
+ * @returns {string}
+ */
+function buildCredentialPushSpinnerLabel(systemKey) {
+  const key = systemKey && String(systemKey).trim() ? String(systemKey).trim() : 'integration';
+  return `Pushing credential secrets for ${key}…`;
+}
+
+/**
+ * @param {string} systemKey
+ * @returns {string}
+ */
+function buildCredentialPushSpinnerText(systemKey) {
+  return formatProgress(buildCredentialPushSpinnerLabel(systemKey));
+}
+
+/**
+ * Run credential push work with visible progress (⏳ line or ora with label on TTY).
+ *
+ * @async
+ * @param {Function} work - Zero-arg async function performing the push
+ * @param {Object} [opts]
+ * @param {string} [opts.systemKey]
+ * @param {boolean} [opts.json]
+ * @returns {Promise<*>}
+ */
+async function runWithCredentialPushSpinner(work, opts = {}) {
+  if (!shouldShowCredentialPushProgress(opts)) {
+    return work();
+  }
+
+  if (!shouldUseCredentialPushSpinner(opts)) {
+    logger.log(buildCredentialPushSpinnerText(opts.systemKey));
+    return work();
+  }
+
+  const ora = require('ora');
+  const label = buildCredentialPushSpinnerLabel(opts.systemKey);
+  const spinner = ora({
+    text: chalk.white(label),
+    spinner: 'dots'
+  }).start();
+
+  try {
+    return await work();
+  } finally {
+    spinner.stop();
+  }
+}
+
+module.exports = {
+  shouldShowCredentialPushProgress,
+  shouldUseCredentialPushSpinner,
+  buildCredentialPushSpinnerLabel,
+  buildCredentialPushSpinnerText,
+  runWithCredentialPushSpinner
+};