@aifabrix/builder 2.49.1 → 2.50.0

package/lib/utils/external-system-system-test-tty.js

@@ -27,6 +27,10 @@ const {
   logCapabilitiesOverview: logCapabilitiesOverviewSection,
   logIntegrationHealthSection: logIntegrationHealthSectionBlock
 } = require('./external-system-system-test-tty-overview');
+const {
+  systemCertStatus,
+  logCertificationSection
+} = require('./external-system-system-test-tty-certification');
 
 /**
   * @param {'ok'|'warn'|'fail'|'skipped'|null} st
@@ -220,24 +224,6 @@ function collectKeyIssues(rows, cap) {
   return out.slice(0, Math.max(0, cap));
 }
 
-function certificateBucket(env) {
-  const cert = env && env.certificate;
-  if (!cert || typeof cert !== 'object') return { status: null, level: null };
-  return {
-    status: cert.status ? String(cert.status) : null,
-    level: cert.level ? String(cert.level) : null
-  };
-}
-
-function systemCertStatus(rows) {
-  const certs = rows
-    .map(r => (r && r.datasourceTestRun ? certificateBucket(r.datasourceTestRun) : { status: null, level: null }))
-    .filter(c => c.status !== null);
-  if (certs.length === 0) return null;
-  if (certs.some(c => c.status === 'not_passed')) return 'not_passed';
-  return 'passed';
-}
-
 function drillDownCommand(runType, datasourceKey) {
   if (!datasourceKey) return null;
   if (runType === 'e2e') return `aifabrix datasource test-e2e ${datasourceKey}`;
@@ -359,28 +345,6 @@ function logKeyIssuesSection(rows) {
   return true;
 }
 
-function logCertificationSection(rows) {
-  const certSt = systemCertStatus(rows);
-  if (!certSt) return;
-  logger.log('');
-  logger.log(metaGray(SEP));
-  logger.log('');
-  logger.log(sectionTitle('Certification:'));
-  logger.log('');
-  logger.log(chalk.white(`System level: ${certSt === 'passed' ? '✔ Achieved' : '✖ Not achieved'}`));
-  logger.log('');
-  logger.log(chalk.white('Breakdown:'));
-  for (const r of rows) {
-    const env = r && r.datasourceTestRun;
-    if (!env) continue;
-    const cert = certificateBucket(env);
-    if (!cert.status) continue;
-    const g = cert.status === 'passed' ? '✔' : '✖';
-    const tier = cert.level ? cert.level : '(no level)';
-    logger.log(chalk.white(`- ${env.datasourceKey}: ${g} ${tier}`));
-  }
-}
-
 function logUseAndFooter(results, runType, systemStatus, blocking) {
   logger.log('');
   logger.log(metaGray(SEP));
@@ -422,7 +386,7 @@ function displaySystemAggregateDatasourceTestRuns(results, opts) {
   const ttyIo = { log: logger.log.bind(logger), chalk, metaGray, sectionTitle, statusGlyph, SEP };
   logCapabilitiesOverviewSection(rows, ttyIo);
   logIntegrationHealthSectionBlock(rows, runType, ttyIo);
-  logCertificationSection(rows);
+  logCertificationSection(rows, { debug: opts.debug, verbose: opts.verbose });
   logUseAndFooter(results, runType, systemStatus, drillDownKey);
 }
 

package/lib/utils/help-builder.js

@@ -26,6 +26,7 @@ const CATEGORIES = [
       { name: 'up-platform' },
       { name: 'up-miso' },
       { name: 'up-dataplane' },
+      { name: 'up-builder-api' },
       { name: 'down-infra', term: 'down-infra [service|appKey]' },
       { name: 'doctor' },
       { name: 'status' },
@@ -77,8 +78,10 @@ const CATEGORIES = [
       { name: 'dimension' },
       { name: 'dimension value', term: 'dimension value <command>' },
       { name: 'resource-type' },
+      { name: 'enterprise-knowledge' },
       { name: 'identity' },
-      { name: 'protection' }
+      { name: 'protection' },
+      { name: 'evidence' }
     ]
   },
   {
@@ -97,11 +100,13 @@ const CATEGORIES = [
   {
     name: 'External Systems',
     commands: [
+      { name: 'list', term: 'list' },
       { name: 'wizard', term: 'wizard [systemKey]' },
       { name: 'download', term: 'download <systemKey>' },
       { name: 'upload', term: 'upload <systemKey>' },
       { name: 'delete', term: 'delete <systemKey>' },
       { name: 'repair', term: 'repair <systemKey>' },
+      { name: 'manifest', term: 'manifest get-section <systemKey> <sectionKey>' },
       { name: 'channel', term: 'channel scaffold <channelTarget>' },
       { name: 'datasource' },
       { name: 'datasource load', term: 'datasource load <datasourceKey>' },

package/lib/utils/host-ops-job-labels.js

@@ -0,0 +1,236 @@
+/**
+ * Human-readable labels for host-ops job polling output.
+ *
+ * @fileoverview Host-ops job type → user-facing action text
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** @type {Record<string, { action: string, durationHint: string, pendingDetail?: string, runningDetail?: string }>} */
+const HOST_OPS_JOB_LABELS = {
+  'remove-dev-user': {
+    action: 'Removing developer',
+    durationHint: 'usually 1–2 min',
+    pendingDetail: 'waiting for host job',
+    runningDetail: 'stopping platform, removing OS user and database'
+  },
+  'provision-dev-user': {
+    action: 'Provisioning developer',
+    durationHint: 'usually 2–3 min',
+    pendingDetail: 'waiting for host job',
+    runningDetail: 'creating OS user, installing CLI and platform'
+  },
+  'install-dev-platform': {
+    action: 'Installing platform for',
+    durationHint: 'usually 3–5 min',
+    pendingDetail: 'waiting for host job',
+    runningDetail: 'pulling images and starting containers'
+  },
+  'reinstall-dev-platform': {
+    action: 'Re-installing platform for',
+    durationHint: 'usually 3–5 min',
+    pendingDetail: 'waiting for host job',
+    runningDetail: 'replacing platform containers'
+  },
+  'update-dev-platform': {
+    action: 'Updating platform for',
+    durationHint: 'usually 2–4 min',
+    pendingDetail: 'waiting for host job',
+    runningDetail: 'refreshing platform images'
+  },
+  'install-builder-cli': {
+    action: 'Installing Builder CLI for',
+    durationHint: 'usually 1–2 min',
+    pendingDetail: 'waiting for host job',
+    runningDetail: 'installing CLI on dev host'
+  },
+  'remove-dev-platform': {
+    action: 'Removing platform for',
+    durationHint: 'usually 1–2 min',
+    pendingDetail: 'waiting for host job',
+    runningDetail: 'stopping platform containers'
+  }
+};
+
+/**
+ * @param {string|number|undefined} developerId
+ * @returns {string}
+ */
+function formatDevLinuxUserLabel(developerId) {
+  const trimmed = String(developerId ?? '').trim();
+  if (!trimmed) {
+    return 'developer';
+  }
+  if (/^\d+$/.test(trimmed)) {
+    return `dev${String(parseInt(trimmed, 10)).padStart(2, '0')}`;
+  }
+  return trimmed.startsWith('dev') ? trimmed : `dev${trimmed}`;
+}
+
+/**
+ * @param {string|undefined} include
+ * @returns {string[]}
+ */
+function parseHostOpsIncludeList(include) {
+  return String(include ?? '')
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Resolve human-readable target(s) from host-ops job params.
+ *
+ * @param {Object} [params]
+ * @param {string|number} [params.developerId]
+ * @param {string} [params.include]
+ * @param {string} [params.exclude]
+ * @returns {string}
+ */
+function resolveHostOpsTargetLabel(params = {}) {
+  if (params.developerId) {
+    return formatDevLinuxUserLabel(params.developerId);
+  }
+  const included = parseHostOpsIncludeList(params.include);
+  if (included.length === 1) {
+    return formatDevLinuxUserLabel(included[0]);
+  }
+  if (included.length > 1) {
+    return included.map(formatDevLinuxUserLabel).join(', ');
+  }
+  if (params.exclude) {
+    return 'selected developers';
+  }
+  return 'all developers';
+}
+
+/**
+ * @param {Object} [params]
+ * @returns {number}
+ */
+function countHostOpsTargets(params = {}) {
+  if (params.developerId) {
+    return 1;
+  }
+  const included = parseHostOpsIncludeList(params.include);
+  if (included.length > 0) {
+    return included.length;
+  }
+  return 0;
+}
+
+/**
+ * @param {number} ms
+ * @returns {string}
+ */
+function formatHostOpsElapsed(ms) {
+  const totalSec = Math.max(0, Math.floor(ms / 1000));
+  if (totalSec < 60) {
+    return `${totalSec}s`;
+  }
+  const min = Math.floor(totalSec / 60);
+  const sec = totalSec % 60;
+  return sec > 0 ? `${min}m ${sec}s` : `${min}m`;
+}
+
+/**
+ * @param {string} jobType
+ * @param {string|number|undefined} targetLabel
+ * @returns {string}
+ */
+function buildHostOpsActionLabel(jobType, targetLabel) {
+  const meta = HOST_OPS_JOB_LABELS[jobType];
+  const userLabel = targetLabel ? String(targetLabel) : 'developer';
+  if (!meta) {
+    return `Host job for ${userLabel}`;
+  }
+  return `${meta.action} ${userLabel}`;
+}
+
+/**
+ * @param {string} jobType
+ * @param {string} status
+ * @returns {string}
+ */
+function buildHostOpsStatusDetail(jobType, status) {
+  const meta = HOST_OPS_JOB_LABELS[jobType];
+  if (!meta) {
+    return status || 'pending';
+  }
+  if (status === 'running') {
+    return meta.runningDetail || 'running on server';
+  }
+  return meta.pendingDetail || 'queued on server';
+}
+
+/**
+ * @param {string} jobType
+ * @param {Object} [params]
+ * @returns {string}
+ */
+function getHostOpsDurationHint(jobType, params) {
+  const meta = HOST_OPS_JOB_LABELS[jobType];
+  const base = (meta && meta.durationHint) || 'may take several minutes';
+  const count = countHostOpsTargets(params);
+  if (count > 1) {
+    return `${base} per developer (${count} selected)`;
+  }
+  return base;
+}
+
+/**
+ * Single-line poll text (spinner or throttled log).
+ *
+ * @param {Object} ctx
+ * @param {string} ctx.jobType
+ * @param {string} [ctx.targetLabel]
+ * @param {Object} [ctx.params]
+ * @param {string} ctx.status
+ * @param {number} ctx.elapsedMs
+ * @param {string} [ctx.transientNote]
+ * @returns {string}
+ */
+function buildHostOpsPollLine(ctx) {
+  const targetLabel = ctx.targetLabel || resolveHostOpsTargetLabel(ctx.params);
+  const action = buildHostOpsActionLabel(ctx.jobType, targetLabel);
+  const durationHint = getHostOpsDurationHint(ctx.jobType, ctx.params);
+  const elapsed = formatHostOpsElapsed(ctx.elapsedMs);
+  if (ctx.transientNote) {
+    return `${action}: ${ctx.transientNote} (${elapsed}, ${durationHint})`;
+  }
+  const detail = buildHostOpsStatusDetail(ctx.jobType, ctx.status);
+  return `${action}: ${detail} (${elapsed}, ${durationHint})`;
+}
+
+/**
+ * Gray intro line printed once when polling starts.
+ *
+ * @param {string} jobType
+ * @param {string|Object} [targetLabelOrParams]
+ * @returns {string}
+ */
+function buildHostOpsPollIntroLine(jobType, targetLabelOrParams) {
+  const targetLabel =
+    typeof targetLabelOrParams === 'string'
+      ? targetLabelOrParams
+      : resolveHostOpsTargetLabel(targetLabelOrParams);
+  const params = typeof targetLabelOrParams === 'object' ? targetLabelOrParams : undefined;
+  const action = buildHostOpsActionLabel(jobType, targetLabel);
+  const durationHint = getHostOpsDurationHint(jobType, params);
+  return `⏳ ${action} — ${durationHint} on the builder host`;
+}
+
+module.exports = {
+  HOST_OPS_JOB_LABELS,
+  formatDevLinuxUserLabel,
+  parseHostOpsIncludeList,
+  resolveHostOpsTargetLabel,
+  countHostOpsTargets,
+  formatHostOpsElapsed,
+  buildHostOpsActionLabel,
+  buildHostOpsPollLine,
+  buildHostOpsPollIntroLine,
+  getHostOpsDurationHint
+};

package/lib/utils/host-ops-job-result.js

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Host-ops job success/failure interpretation for CLI polling
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * @param {Object|null|undefined} job
+ * @returns {boolean}
+ */
+function isHostOpsJobFailed(job) {
+  if (!job) return true;
+  if (job.status === 'failed') return true;
+  if (job.error) return true;
+  if (!Array.isArray(job.outcomes)) return false;
+  return job.outcomes.some((row) => {
+    if (!row || typeof row !== 'object') return false;
+    const overall = row.overall || row.status;
+    return overall === 'FAIL' || overall === 'BLOCKED';
+  });
+}
+
+/**
+ * @param {Object} job
+ * @returns {string}
+ */
+function formatHostOpsJobFailure(job) {
+  const parts = [];
+  if (job.error) {
+    parts.push(String(job.error));
+  }
+  if (Array.isArray(job.outcomes)) {
+    for (const row of job.outcomes) {
+      if (!row || typeof row !== 'object') continue;
+      const overall = row.overall || row.status;
+      if (overall !== 'FAIL' && overall !== 'BLOCKED') continue;
+      const label = row.linuxUser || row.developerId || 'target';
+      const detail = row.detail ? ` — ${row.detail}` : '';
+      parts.push(`${label}: ${overall}${detail}`);
+    }
+  }
+  if (parts.length > 0) {
+    return parts.join('\n');
+  }
+  return `Host-ops job ${job.jobId || '(unknown)'} failed`;
+}
+
+/**
+ * @param {Object} job
+ * @throws {Error}
+ */
+function assertHostOpsJobSucceeded(job) {
+  if (!isHostOpsJobFailed(job)) return;
+  throw new Error(formatHostOpsJobFailure(job));
+}
+
+module.exports = {
+  isHostOpsJobFailed,
+  formatHostOpsJobFailure,
+  assertHostOpsJobSucceeded
+};

package/lib/utils/host-ops-poll-ui.js

@@ -0,0 +1,163 @@
+/**
+ * TTY ora spinner + throttled non-TTY lines for host-ops job polling.
+ *
+ * @fileoverview Host-ops job poll presentation helpers
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+const {
+  buildHostOpsPollLine,
+  buildHostOpsPollIntroLine
+} = require('./host-ops-job-labels');
+
+const SILENT_POLL_HANDLERS = {
+  onPollProgress: () => {},
+  onTransientError: () => {},
+  finish: () => {}
+};
+
+function shouldUseHostOpsPollSpinner() {
+  return Boolean(process && process.stdout && process.stdout.isTTY);
+}
+
+/**
+ * @deprecated Use buildHostOpsPollLine via createHostOpsPollHandlers context.
+ * @param {string} jobId
+ * @param {string} status
+ * @param {number} attemptIndex
+ * @param {number} maxAttempts
+ * @returns {string}
+ */
+function buildHostOpsPollSpinnerText(jobId, status, attemptIndex, maxAttempts) {
+  const safeStatus = status || 'pending';
+  return `host-ops job ${jobId}: ${safeStatus} (${attemptIndex + 1}/${maxAttempts})`;
+}
+
+const NON_TTY_THROTTLE_MS = 5000;
+
+/**
+ * @param {Object} pollContext
+ * @returns {Function}
+ */
+function createPollLineBuilder(pollContext) {
+  const jobType = pollContext.jobType || 'host-ops';
+  const params = pollContext.params;
+  const targetLabel = pollContext.targetLabel;
+  return (status, elapsedMs, transientNote) =>
+    buildHostOpsPollLine({
+      jobType,
+      targetLabel,
+      params,
+      status,
+      elapsedMs,
+      transientNote
+    });
+}
+
+/**
+ * @param {Object} pollContext
+ * @returns {Function}
+ */
+function createPollIntroLogger(pollContext) {
+  const jobType = pollContext.jobType || 'host-ops';
+  const params = pollContext.params;
+  const targetLabel = pollContext.targetLabel;
+  let introLogged = false;
+  return () => {
+    if (introLogged) {
+      return;
+    }
+    introLogged = true;
+    logger.log(
+      chalk.gray(`  ${buildHostOpsPollIntroLine(jobType, targetLabel || params || undefined)}`)
+    );
+  };
+}
+
+/**
+ * @param {Object} pollContext
+ * @returns {{ onPollProgress: Function, onTransientError: Function, finish: () => void }}
+ */
+function createSpinnerHostOpsPollHandlers(pollContext) {
+  const startedAt = pollContext.startedAt || Date.now();
+  const buildLine = createPollLineBuilder(pollContext);
+  const logIntroOnce = createPollIntroLogger(pollContext);
+  const ora = require('ora');
+  logIntroOnce();
+  const spinner = ora({
+    text: buildLine('pending', 0),
+    spinner: 'dots'
+  }).start();
+  return {
+    onPollProgress: (status) => {
+      spinner.text = buildLine(status, Date.now() - startedAt);
+    },
+    onTransientError: (_err, elapsedMs) => {
+      spinner.text = buildLine('pending', elapsedMs, 'server temporarily unavailable, retrying');
+    },
+    finish: () => {
+      spinner.stop();
+    }
+  };
+}
+
+/**
+ * @param {Object} pollContext
+ * @returns {{ onPollProgress: Function, onTransientError: Function, finish: () => void }}
+ */
+function createNonTtyHostOpsPollHandlers(pollContext) {
+  const startedAt = pollContext.startedAt || Date.now();
+  const buildLine = createPollLineBuilder(pollContext);
+  const logIntroOnce = createPollIntroLogger(pollContext);
+  let lastNonTtyLogAt = 0;
+  return {
+    onPollProgress: (status) => {
+      logIntroOnce();
+      const now = Date.now();
+      const elapsedMs = now - startedAt;
+      if (now - lastNonTtyLogAt < NON_TTY_THROTTLE_MS && elapsedMs > 0) {
+        return;
+      }
+      lastNonTtyLogAt = now;
+      logger.log(chalk.gray(`  ${buildLine(status, elapsedMs)}`));
+    },
+    onTransientError: (_err, elapsedMs) => {
+      logIntroOnce();
+      logger.log(
+        chalk.gray(`  ${buildLine('pending', elapsedMs, 'server temporarily unavailable, retrying')}`)
+      );
+    },
+    finish: () => {}
+  };
+}
+
+/**
+ * @param {string} jobId
+ * @param {Object} [pollContext]
+ * @param {string} [pollContext.jobType]
+ * @param {string} [pollContext.targetLabel]
+ * @param {Object} [pollContext.params]
+ * @param {number} [pollContext.startedAt]
+ * @param {{ silent?: boolean }} [options]
+ * @returns {{ onPollProgress: Function, onTransientError: Function, finish: () => void }}
+ */
+function createHostOpsPollHandlers(jobId, pollContext = {}, options = {}) {
+  if (options && options.silent === true) {
+    return SILENT_POLL_HANDLERS;
+  }
+  if (shouldUseHostOpsPollSpinner()) {
+    return createSpinnerHostOpsPollHandlers(pollContext);
+  }
+  return createNonTtyHostOpsPollHandlers(pollContext);
+}
+
+module.exports = {
+  buildHostOpsPollSpinnerText,
+  createHostOpsPollHandlers,
+  shouldUseHostOpsPollSpinner
+};

package/lib/utils/integration-path-resolve.js

@@ -0,0 +1,112 @@
+/**
+ * Find integration/<systemKey> under aifabrix-work (sibling repos).
+ *
+ * @fileoverview Worktree integration discovery for dev layouts (sibling repos under aifabrix-work)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getAifabrixWork } = require('./paths');
+const { resolveApplicationConfigPath } = require('./app-config-resolver');
+const { discoverIntegrationFiles } = require('../commands/repair-internal');
+
+/**
+ * @param {string} appPath
+ * @returns {boolean}
+ */
+function integrationFolderHasContent(appPath) {
+  if (!fs.existsSync(appPath)) {
+    return false;
+  }
+  try {
+    const st = fs.statSync(appPath);
+    if (!st.isDirectory()) {
+      return false;
+    }
+  } catch {
+    return false;
+  }
+  const { systemFiles, datasourceFiles } = discoverIntegrationFiles(appPath);
+  if (systemFiles.length > 0 || datasourceFiles.length > 0) {
+    return true;
+  }
+  try {
+    resolveApplicationConfigPath(appPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} work
+ * @param {string} systemKey
+ * @returns {{ integrationPath: string, tier: string }[]}
+ */
+function collectWorkRepoIntegrationHits(work, systemKey) {
+  /** @type {{ integrationPath: string, tier: string }[]} */
+  const hits = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(work, { withFileTypes: true });
+  } catch {
+    return hits;
+  }
+  for (const ent of entries) {
+    if (!ent.isDirectory() || ent.name.startsWith('.')) {
+      continue;
+    }
+    const candidate = path.join(work, ent.name, 'integration', systemKey);
+    if (integrationFolderHasContent(candidate)) {
+      hits.push({ integrationPath: path.resolve(candidate), tier: 'work-repo-integration' });
+    }
+  }
+  return hits;
+}
+
+/**
+ * @param {{ integrationPath: string, tier: string }[]} hits
+ * @param {string} systemKey
+ * @returns {{ integrationPath: string, tier: string }|null}
+ */
+function resolveUniqueIntegrationHit(hits, systemKey) {
+  if (hits.length === 1) {
+    return hits[0];
+  }
+  if (hits.length > 1) {
+    const err = new Error(
+      `Integration "${systemKey}" found in multiple repos under aifabrix-work: ${hits.map((h) => h.integrationPath).join(', ')}. ` +
+        'Run from the target repo or narrow with cwd.'
+    );
+    err.statusCode = 409;
+    throw err;
+  }
+  return null;
+}
+
+/**
+ * @param {string} systemKey
+ * @returns {{ integrationPath: string, tier: string }|null}
+ */
+function findIntegrationPathAcrossWorkTree(systemKey) {
+  const work = getAifabrixWork();
+  if (!work) {
+    return null;
+  }
+
+  const direct = path.join(work, 'integration', systemKey);
+  if (integrationFolderHasContent(direct)) {
+    return { integrationPath: path.resolve(direct), tier: 'work-integration' };
+  }
+
+  return resolveUniqueIntegrationHit(collectWorkRepoIntegrationHits(work, systemKey), systemKey);
+}
+
+module.exports = {
+  findIntegrationPathAcrossWorkTree,
+  integrationFolderHasContent
+};