@aifabrix/builder 2.49.2 → 2.51.0

package/lib/commands/deploy-gate-orchestrator.js

@@ -0,0 +1,368 @@
+/**
+ * @fileoverview Deploy pre-promote baseline tests and optional --gate steps (456.9).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const { sectionTitle } = require('../utils/cli-test-layout-chalk');
+const logger = require('../utils/logger');
+const { formatDeployGateFailure } = require('./deploy-gate-failure-details');
+const { testExternalSystem, testExternalSystemIntegration } = require('../external-system/test');
+const { runWithVerifyStepProgress } = require('../lifecycle/verify-step-progress');
+const { runTestE2EForExternalSystem, syncLocalIfRequested, resolveExternalIntegrationContext } = require('./test-e2e-external');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
+const { resolveE2eSyncModeWhenPopulated } = require('./datasource-sync-policy');
+const { runVerifyTrustForExternalSystem } = require('./verify-trust-external');
+const { runVerifyGovernanceForExternalSystem } = require('./verify-governance-external');
+const { runGovernanceGenerateForExternalSystem } = require('./governance-generate-external');
+const { resolveGovernanceFixtureSubjectEmails } = require('./governance-fixture-subjects');
+const { runVerifyGovernanceCombined } = require('./verify-governance-combined-external');
+const { VERDICT } = require('../lifecycle/product-model');
+
+const KNOWN_GATES = ['operations', 'trust', 'governance'];
+
+/**
+ * @param {string|undefined} gateRaw
+ * @returns {string[]}
+ */
+function parseDeployGateTokens(gateRaw) {
+  if (!gateRaw || typeof gateRaw !== 'string') {
+    return [];
+  }
+  const tokens = gateRaw
+    .split(',')
+    .map((part) => part.trim().toLowerCase())
+    .filter(Boolean);
+  if (tokens.includes('full')) {
+    return [...KNOWN_GATES];
+  }
+  return tokens.filter((token) => KNOWN_GATES.includes(token));
+}
+
+/**
+ * Strict promote posture suggests full optional gates when caller requests profile resolution.
+ * @returns {string[]}
+ */
+function resolveStrictPromoteGateProfile() {
+  const level = (process.env.TRUST_CUSTOMER_POLICY_LEVEL || 'standard').trim().toLowerCase();
+  if (level === 'strict') {
+    return [...KNOWN_GATES];
+  }
+  return [];
+}
+
+/**
+ * @param {string|undefined} gateRaw
+ * @param {Object} [options]
+ * @returns {Set<string>}
+ */
+function resolveDeployGateSet(gateRaw, options = {}) {
+  const explicit = parseDeployGateTokens(gateRaw);
+  if (explicit.length > 0) {
+    return new Set(explicit);
+  }
+  if (options.useStrictPromoteProfile === true) {
+    return new Set(resolveStrictPromoteGateProfile());
+  }
+  return new Set();
+}
+
+/**
+ * @param {Object} options
+ * @param {Object|null|undefined} uploadCtx
+ * @returns {Object}
+ */
+function mergeUploadAuthOptions(options, uploadCtx) {
+  if (!uploadCtx?.authConfig || !uploadCtx?.dataplaneUrl) {
+    return { ...options, noPublish: true, verbose: false };
+  }
+  return {
+    ...options,
+    noPublish: true,
+    verbose: false,
+    authConfig: uploadCtx.authConfig,
+    dataplaneUrl: uploadCtx.dataplaneUrl,
+    silentResolve: true
+  };
+}
+
+/**
+ * @async
+ * @param {string} label
+ * @param {Function} runner
+ * @param {Function} isOk
+ * @param {Object} [stepOptions]
+ */
+async function runRequiredDeployStep(label, runner, isOk, stepOptions = {}) {
+  return runWithVerifyStepProgress(
+    label,
+    async() => {
+      const outcome = await runner();
+      if (!isOk(outcome)) {
+        const detail = formatDeployGateFailure(label, outcome);
+        if (stepOptions.quietDeployUi !== true) {
+          logger.log(chalk.red(`✖ ${detail}`));
+        }
+        const err = new Error(`${label} failed: ${detail}`);
+        err.gateFailure = true;
+        err.gateDetail = detail;
+        err.gateLabel = label;
+        if (stepOptions.gatePillar) {
+          err.gatePillar = stepOptions.gatePillar;
+        }
+        throw err;
+      }
+      return outcome;
+    },
+    { json: false, quietProgress: stepOptions.quietDeployUi === true }
+  );
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<{ unitPassed: boolean, integrationPassed: boolean }>}
+ */
+async function runDeployBaselineSteps(systemKey, options) {
+  await runRequiredDeployStep(
+    'Running unit tests',
+    () => testExternalSystem(systemKey, { verbose: false }),
+    (result) => result.valid === true,
+    options
+  );
+
+  let stepOptions = { ...options, noPublish: true, verbose: false, uploadStatus: 'published' };
+  if (!cliOptsSkipPublish(options)) {
+    const uploadCtx = await syncLocalIfRequested(systemKey, {
+      ...options,
+      uploadStatus: 'published',
+      minimal: true,
+      suppressSummary: true,
+      suppressPipelineSpinner: true,
+      uploadContext: 'deploy-preflight'
+    });
+    stepOptions = mergeUploadAuthOptions({ ...options, uploadStatus: 'published' }, uploadCtx);
+  }
+
+  await runRequiredDeployStep(
+    'Running integration tests',
+    () => testExternalSystemIntegration(systemKey, stepOptions),
+    (result) => result.success === true,
+    options
+  );
+
+  return { unitPassed: true, integrationPassed: true };
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runOperationsGate(systemKey, options) {
+  let stepOptions = mergeUploadAuthOptions(options, null);
+  if (!stepOptions.dataplaneUrl || !stepOptions.authConfig) {
+    try {
+      const uploadCtx = await syncLocalIfRequested(systemKey, { ...options, noPublish: true });
+      stepOptions = mergeUploadAuthOptions(options, uploadCtx);
+    } catch {
+      stepOptions = mergeUploadAuthOptions(options, null);
+    }
+  }
+
+  let e2eSyncMode = options.syncMode;
+  if (!e2eSyncMode && stepOptions.dataplaneUrl && stepOptions.authConfig) {
+    try {
+      const { keys } = resolveExternalIntegrationContext(systemKey);
+      e2eSyncMode = await resolveE2eSyncModeWhenPopulated(
+        stepOptions.dataplaneUrl,
+        stepOptions.authConfig,
+        keys
+      );
+    } catch {
+      e2eSyncMode = 'auto';
+    }
+  }
+
+  await runRequiredDeployStep(
+    'Running operations gate (E2E)',
+    () =>
+      runTestE2EForExternalSystem(systemKey, {
+        ...stepOptions,
+        env: options.env,
+        async: options.async !== false,
+        quietPollUi: true,
+        syncMode: e2eSyncMode || stepOptions.syncMode
+      }),
+    (result) => result.success === true,
+    { ...options, gatePillar: 'operations' }
+  );
+
+  return { pillar: 'operations', verdict: VERDICT.VERIFIED };
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runTrustGate(systemKey, options) {
+  const result = await runRequiredDeployStep(
+    'Running trust gate',
+    () => runVerifyTrustForExternalSystem(systemKey, { ...options, noPublish: true }),
+    (outcome) => outcome.verdict === VERDICT.VERIFIED,
+    { ...options, gatePillar: 'trust' }
+  );
+  return {
+    pillar: 'trust',
+    verdict: result.verdict,
+    percent: result.aiTrustPercent ?? undefined
+  };
+}
+
+/**
+ * @param {Object} options
+ * @returns {boolean}
+ */
+function governanceSubjectsProvided(options) {
+  return Boolean(options.subjectEmail);
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runGovernanceGate(systemKey, options) {
+  const gateOptions = { ...options, noPublish: true };
+  let runner;
+  if (governanceSubjectsProvided(gateOptions)) {
+    runner = () => runVerifyGovernanceCombined(systemKey, gateOptions);
+  } else {
+    const fixtureEmails = resolveGovernanceFixtureSubjectEmails(systemKey);
+    if (fixtureEmails.length > 0) {
+      runner = async() => {
+        await runGovernanceGenerateForExternalSystem(systemKey, {
+          ...gateOptions,
+          subjectEmails: fixtureEmails
+        });
+        return runVerifyGovernanceForExternalSystem(systemKey, gateOptions);
+      };
+    } else {
+      runner = () => runVerifyGovernanceForExternalSystem(systemKey, gateOptions);
+    }
+  }
+  const result = await runRequiredDeployStep(
+    'Running governance gate',
+    runner,
+    (outcome) => outcome.verdict === VERDICT.VERIFIED,
+    { ...options, gatePillar: 'governance' }
+  );
+  const scenarios = result.enforcementScenarios || {};
+  return {
+    pillar: 'governance',
+    verdict: result.verdict,
+    scenariosPassed: scenarios.passed,
+    scenariosTotal: scenarios.total
+  };
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Set<string>} gates
+ * @param {Object} options
+ * @returns {Promise<Object[]>}
+ */
+async function runDeployOptionalGates(systemKey, gates, options) {
+  const outcomes = [];
+  try {
+    if (gates.has('operations')) {
+      outcomes.push(await runOperationsGate(systemKey, options));
+    }
+    if (gates.has('trust')) {
+      outcomes.push(await runTrustGate(systemKey, options));
+    }
+    if (gates.has('governance')) {
+      outcomes.push(await runGovernanceGate(systemKey, options));
+    }
+  } catch (err) {
+    if (err && err.gateFailure === true) {
+      err.gatesSoFar = outcomes;
+    }
+    throw err;
+  }
+  return outcomes;
+}
+
+/**
+ * @param {string|undefined} label
+ * @returns {string}
+ */
+function inferGatePillarFromLabel(label) {
+  const text = String(label || '').toLowerCase();
+  if (text.includes('operations')) return 'operations';
+  if (text.includes('trust')) return 'trust';
+  if (text.includes('governance')) return 'governance';
+  return 'operations';
+}
+
+/**
+ * Baseline validate + test + test-integration, then optional --gate steps before controller deploy.
+ * @async
+ * @param {string} systemKey
+ * @param {Object} [options]
+ * @returns {Promise<{ baseline: { unitPassed: boolean, integrationPassed: boolean }, gates: Object[] }>}
+ */
+async function runDeployGateOrchestrator(systemKey, options = {}) {
+  const quiet = options.quietDeployUi === true || options.verbose !== true;
+  if (!quiet) {
+    logger.log('');
+    logger.log(sectionTitle('Deploy preflight'));
+  }
+  const baseline = await runDeployBaselineSteps(systemKey, { ...options, quietDeployUi: quiet });
+  const gates = resolveDeployGateSet(options.gate, options);
+  if (gates.size === 0) {
+    return { baseline, gates: [] };
+  }
+  try {
+    const gateOutcomes = await runDeployOptionalGates(systemKey, gates, {
+      ...options,
+      quietDeployUi: quiet
+    });
+    return { baseline, gates: gateOutcomes };
+  } catch (err) {
+    if (err && err.gateFailure === true && quiet) {
+      const { logDeployGateAbortCompact } = require('../utils/external-system-readiness-compact-blocks');
+      const failedPillar = err.gatePillar || inferGatePillarFromLabel(err.gateLabel);
+      logDeployGateAbortCompact({
+        systemKey,
+        environment: options.environment || options.env || 'dev',
+        dataplaneUrl: options.dataplaneUrl || options.knownDataplaneUrl,
+        baseline,
+        gatesSoFar: err.gatesSoFar || [],
+        failedPillar,
+        failedDetail: err.gateDetail || err.message
+      });
+      err.compactGateAbortLogged = true;
+    }
+    throw err;
+  }
+}
+
+module.exports = {
+  KNOWN_GATES,
+  parseDeployGateTokens,
+  resolveStrictPromoteGateProfile,
+  resolveDeployGateSet,
+  runDeployBaselineSteps,
+  runDeployOptionalGates,
+  runDeployGateOrchestrator
+};

package/lib/commands/dev-cli-handlers.js

@@ -17,6 +17,8 @@ const {
   augmentDevUserGroupsServerError
 } = require('../utils/dev-user-groups');
 const { handleProvisionDevUser, handleRemoveDevUser } = require('./dev-host-ops');
+const { logDevPinShareInstructions } = require('../utils/dev-pin-share-instructions');
+const { sortDevUsers } = require('../utils/dev-list-sort');
 
 const REMOTE_NOT_CONFIGURED_MSG = 'Remote server is not configured. Set remote-server and run "aifabrix dev init" first.';
 
@@ -51,10 +53,12 @@ function formatCertUntil(iso) {
 }
 
 /**
- * Handle dev list – list developer users (remote only). Table format, sorted by name.
+ * Handle dev list – list developer users (remote only). Table format; default sort by name.
+ * @param {Object} [options] - Commander options
+ * @param {string} [options.sort] - Sort field/direction (id|name|email|until; prefix - for descending)
  * @returns {Promise<void>}
  */
-async function handleDevList() {
+async function handleDevList(options = {}) {
   const auth = await getRemoteDevAuth();
   if (!auth) {
     logger.log(chalk.yellow(REMOTE_NOT_CONFIGURED_MSG));
@@ -68,7 +72,7 @@ async function handleDevList() {
   logger.log(chalk.bold('\n📋 Developers:\n'));
   logger.log(chalk.gray('ID'.padEnd(ID_WIDTH) + 'Name'.padEnd(NAME_WIDTH) + 'Email'.padEnd(EMAIL_WIDTH) + 'Cert'.padEnd(CERT_WIDTH) + 'Until'.padEnd(UNTIL_WIDTH) + 'Groups'));
   logger.log(chalk.gray('-'.repeat(TABLE_SEPARATOR_LENGTH)));
-  const sorted = [...users].sort((a, b) => (a.name || '').localeCompare(b.name || '', undefined, { sensitivity: 'base' }));
+  const sorted = sortDevUsers(users, options.sort);
   sorted.forEach(u => {
     const certLabel = u.certificateIssued ? 'yes' : 'no cert';
     const untilRaw = u.certificateIssued && u.certificateValidNotAfter ? u.certificateValidNotAfter : null;
@@ -149,64 +153,6 @@ async function handleDevUpdate(developerId, options) {
   }
 }
 
-function logPinHostsVariantLines(baseInit, id, hostsIp) {
-  logger.log(
-    chalk.cyan('2) Hosts file / administrator')
-    + chalk.gray(
-      ' — use when the hostname does not resolve and your organisation does not publish DNS for it. '
-      + 'Run in an elevated terminal so the hosts file can be updated, or add the entry manually:'
-    )
-  );
-  if (hostsIp) {
-    logger.log(`   ${baseInit} --add-hosts --hosts-ip ${hostsIp}`);
-  } else {
-    logger.log(`   ${baseInit} --add-hosts --hosts-ip <server-LAN-IPv4>`);
-    logger.log(
-      chalk.gray(
-        `   Replace <server-LAN-IPv4> with the Builder Server IPv4, or re-run: aifabrix dev pin ${id} --hosts-ip <ip>`
-      )
-    );
-  }
-}
-
-/**
- * Log copy-paste dev init commands for the developer (standard vs hosts-file).
- * @param {Object} p
- * @param {string} p.id - Developer ID
- * @param {string} p.serverUrl - Builder Server base URL
- * @param {string} p.pin - One-time PIN
- * @param {string} p.expiresAt - PIN expiry (API string)
- * @param {string} [p.hostsIp] - Optional IPv4 for the hosts variant
- * @returns {void}
- */
-function logDevPinShareInstructions(p) {
-  const { id, serverUrl, pin, expiresAt, hostsIp } = p;
-  const baseInit = `aifabrix dev init --developer-id ${id} --server ${serverUrl} --pin ${pin}`;
-  const pinOnly = `aifabrix dev init --pin ${pin}`;
-  logger.log(formatSuccessLine(`PIN created for ${id}, expires ${expiresAt}.`));
-  logger.log('');
-  logger.log(
-    chalk.bold('Share with the developer — they run one command (the PIN is one-time):')
-  );
-  logger.log('');
-  logger.log(
-    chalk.cyan('1) Standard')
-    + chalk.gray(' — use when this machine can resolve the server hostname (DNS or hosts already set):')
-  );
-  logger.log(`   ${baseInit}`);
-  logger.log('');
-  logPinHostsVariantLines(baseInit, id, hostsIp);
-  logger.log('');
-  logger.log(
-    chalk.cyan('3) Config already has remote-server + developer-id')
-    + chalk.gray(
-      ' — e.g. second machine / SSH session after settings were merged; same onboarding, PIN only:'
-    )
-  );
-  logger.log(`   ${pinOnly}`);
-  logger.log('');
-}
-
 /**
  * Handle dev pin – create/regenerate PIN (remote only).
  * @param {string} [developerId] - Developer ID (optional; uses config if omitted)
@@ -294,7 +240,6 @@ async function handleDevDelete(developerId, options = {}) {
     }
   }
   await handleRemoveDevUser(id, { ...options, developerId: id });
-  logger.log(formatSuccessLine(`Developer ${id} removal queued and completed.`));
 }
 
 module.exports = {

package/lib/commands/dev-host-ops-params.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Map Commander options to host-ops job params
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * @param {Object} options
+ * @param {string[]} keys
+ * @returns {string|undefined}
+ */
+function firstOption(options, ...keys) {
+  for (const key of keys) {
+    const value = options[key];
+    if (value !== undefined && value !== null && value !== '') {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * @param {Object} params
+ * @param {Object} options
+ * @param {Array<[string, ...string[]]>} mappings
+ */
+function assignStringParams(params, options, mappings) {
+  for (const [paramKey, ...optionKeys] of mappings) {
+    const value = firstOption(options, ...optionKeys);
+    if (value !== undefined) {
+      params[paramKey] = value;
+    }
+  }
+}
+
+/**
+ * @param {Object} params
+ * @param {Object} options
+ * @param {Array<[string, ...string[]]>} mappings
+ */
+function assignFlagParams(params, options, mappings) {
+  for (const [paramKey, ...optionKeys] of mappings) {
+    if (optionKeys.some((k) => Boolean(options[k]))) {
+      params[paramKey] = true;
+    }
+  }
+}
+
+const STRING_PARAM_MAPPINGS = [
+  ['include', 'include'],
+  ['exclude', 'exclude'],
+  ['builderVersion', 'builderVersion', 'builder-version'],
+  ['adminEmail', 'adminEmail', 'admin-email'],
+  ['adminPassword', 'adminPassword', 'admin-password'],
+  ['platform', 'platform'],
+  ['installation', 'installation']
+];
+
+const FLAG_PARAM_MAPPINGS = [
+  ['skipCert', 'skipCert', 'skip-cert'],
+  ['skipPlatform', 'skipPlatform', 'skip-platform'],
+  ['skipCli', 'skipCli', 'skip-cli'],
+  ['check', 'check'],
+  ['failOnBlocked', 'failOnBlocked']
+];
+
+/**
+ * Build job params from Commander options.
+ * @param {Object} options
+ * @param {string} [developerId]
+ * @returns {Object}
+ */
+function buildJobParams(options, developerId) {
+  const params = {};
+  const id = developerId || firstOption(options, 'developerId', 'developer-id');
+  if (id) {
+    params.developerId = String(id).trim();
+  }
+  assignStringParams(params, options, STRING_PARAM_MAPPINGS);
+  assignFlagParams(params, options, FLAG_PARAM_MAPPINGS);
+  const timeoutMinutes = firstOption(options, 'timeoutMinutes', 'timeout-minutes');
+  if (timeoutMinutes) {
+    params.timeoutMinutes = parseInt(timeoutMinutes, 10);
+  }
+  return params;
+}
+
+module.exports = {
+  buildJobParams,
+  firstOption
+};

package/lib/commands/dev-host-ops-poll.js

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview Host-ops job polling loop
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const hostOpsApi = require('../api/host-ops.api');
+const { assertHostOpsJobSucceeded } = require('../utils/host-ops-job-result');
+
+const POLL_INTERVAL_MS = 3000;
+const POLL_TIMEOUT_MS = 3 * 60 * 60 * 1000;
+const TRANSIENT_HTTP_STATUSES = new Set([502, 503, 504]);
+/** Allow ~3 min of consecutive gateway errors (container restart during remove-dev-user). */
+const MAX_TRANSIENT_POLL_ERRORS = 60;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * @param {Error} err
+ * @returns {boolean}
+ */
+function isTransientHostOpsPollError(err) {
+  return Boolean(err && TRANSIENT_HTTP_STATUSES.has(err.status));
+}
+
+/**
+ * @param {Error} err
+ * @param {string} jobId
+ * @returns {Error}
+ */
+function enhanceTransientHostOpsPollError(err, jobId) {
+  const status = err && err.status;
+  const base =
+    status === 502
+      ? 'Builder server returned Bad Gateway while waiting for the host job.'
+      : `Builder server returned HTTP ${status} while waiting for the host job.`;
+  const hint =
+    'The job may still be running on the host (common during platform teardown or container restart). ' +
+    'Wait 1–2 minutes, then run "aifabrix dev list" to verify. ' +
+    `Job id: ${jobId}`;
+  return new Error(`${base} ${hint}`);
+}
+
+/**
+ * @param {Object} auth
+ * @param {string} jobId
+ * @param {Object} pollUi
+ * @returns {Promise<Object>}
+ */
+async function fetchHostOpsJobWithRetry(auth, jobId, pollUi) {
+  const started = Date.now();
+  for (let attempt = 0; attempt <= MAX_TRANSIENT_POLL_ERRORS; attempt += 1) {
+    try {
+      return await hostOpsApi.getHostOpsJob(
+        auth.serverUrl,
+        auth.clientCertPem,
+        jobId,
+        auth.serverCaPem || undefined
+      );
+    } catch (err) {
+      if (!isTransientHostOpsPollError(err)) {
+        throw err;
+      }
+      if (attempt >= MAX_TRANSIENT_POLL_ERRORS) {
+        throw enhanceTransientHostOpsPollError(err, jobId);
+      }
+      if (pollUi && typeof pollUi.onTransientError === 'function') {
+        pollUi.onTransientError(err, Date.now() - started);
+      }
+      await sleep(POLL_INTERVAL_MS);
+    }
+  }
+  throw new Error(`Failed to fetch host-ops job ${jobId} after transient retries`);
+}
+
+/**
+ * @param {Object} auth
+ * @param {string} jobId
+ * @param {Object} pollUi
+ * @param {boolean} json
+ * @returns {Promise<Object>}
+ */
+async function pollHostOpsJobUntilTerminal(auth, jobId, pollUi, json) {
+  const started = Date.now();
+  while (Date.now() - started < POLL_TIMEOUT_MS) {
+    const job = await fetchHostOpsJobWithRetry(auth, jobId, pollUi);
+    if (!json) {
+      pollUi.onPollProgress(job.status);
+    }
+    if (job.status === 'failed') {
+      throw new Error(job.error || `Host-ops job ${jobId} failed`);
+    }
+    if (job.status === 'completed') {
+      assertHostOpsJobSucceeded(job);
+      return job;
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new Error(`Timed out waiting for host-ops job ${jobId}`);
+}
+
+module.exports = {
+  POLL_INTERVAL_MS,
+  POLL_TIMEOUT_MS,
+  isTransientHostOpsPollError,
+  enhanceTransientHostOpsPollError,
+  fetchHostOpsJobWithRetry,
+  pollHostOpsJobUntilTerminal
+};