@aifabrix/builder 2.51.0 → 2.52.0

package/lib/commands/role-assistant.js

@@ -0,0 +1,371 @@
+/**
+ * Role Assistant CLI command group.
+ *
+ * @fileoverview role-assistant test command with portal deep-link output
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const {
+  runLifecycleForExternalSystem,
+  resolveLifecycleAuth
+} = require('./lifecycle-external');
+const { lifecycleVerdictFromReport } = require('./lifecycle-command-action');
+const { buildExternalSystemUiUrl } = require('../lifecycle/dataplane-ui-url');
+const { VERDICT } = require('../lifecycle/product-model');
+const { exitCodeFromVerdict } = require('../lifecycle/exit-codes');
+const {
+  loadRoleAssistantTestCase,
+  evaluateRoleAssistantTestCase
+} = require('../role-assistant/test-cases');
+const {
+  isExecutableRoleAssistantCase,
+  runRoleAssistantCaseLifecycle,
+  mergeCaseExecutionIntoLifecycleResult,
+  lifecycleVerdictFromCaseExecution
+} = require('../role-assistant/test-runner');
+const { collectString } = require('./governance');
+const {
+  sectionTitle,
+  headerKeyValue,
+  formatSuccessLine,
+  formatSuccessParagraph,
+  formatWarningLine,
+  formatBlockingError,
+  metadata
+} = require('../utils/cli-test-layout-chalk');
+const {
+  bareRoleKey,
+  roleAssistantSystemKey
+} = require('../utils/role-assistant-paths');
+
+/**
+ * Bucket a lifecycle step status into ok | failed | skipped | other.
+ * @param {string} status
+ * @returns {'ok'|'failed'|'skipped'|'other'}
+ */
+function bucketStepStatus(status) {
+  const normalized = String(status || 'ok').toLowerCase();
+  if (normalized === 'ok' || normalized === 'verified' || normalized === 'passed') {
+    return 'ok';
+  }
+  if (normalized === 'failed' || normalized === 'error') {
+    return 'failed';
+  }
+  if (normalized === 'skipped' || normalized === 'n/a' || normalized === 'not_applicable') {
+    return 'skipped';
+  }
+  return 'other';
+}
+
+/**
+ * Summarize lifecycle stepsRun rows (API uses step/status/datasourceKey, not pillar).
+ * @param {Array<Object|string>} steps
+ * @returns {string}
+ */
+function formatStepsRunSummary(steps) {
+  const byStep = Object.create(null);
+  for (const row of steps) {
+    if (!row || typeof row !== 'object') {
+      const label = String(row);
+      byStep[label] = byStep[label] || { ok: 0, failed: 0, skipped: 0, other: 0 };
+      byStep[label].other += 1;
+      continue;
+    }
+    const stepName = String(row.step || row.pillar || row.name || 'step').trim() || 'step';
+    const status = row.status || (row.success === false ? 'failed' : 'ok');
+    byStep[stepName] = byStep[stepName] || { ok: 0, failed: 0, skipped: 0, other: 0 };
+    byStep[stepName][bucketStepStatus(status)] += 1;
+  }
+  return Object.keys(byStep)
+    .map((stepName) => {
+      const counts = byStep[stepName];
+      const parts = [];
+      if (counts.ok) parts.push(`${counts.ok} ok`);
+      if (counts.failed) parts.push(`${counts.failed} failed`);
+      if (counts.skipped) parts.push(`${counts.skipped} skipped`);
+      if (counts.other) parts.push(`${counts.other} other`);
+      return parts.length > 0 ? `${stepName} (${parts.join(', ')})` : stepName;
+    })
+    .join('; ');
+}
+
+function roleAssistantHelpAfter() {
+  return `
+Examples:
+  $ aifabrix role-assistant test customer-support-bot
+  $ aifabrix role-assistant test customer-support-bot --case smoke
+  $ aifabrix role-assistant test customer-support-bot --case tests/customer-address-change.yaml
+  $ aifabrix role-assistant test customer-support-bot --subject-email ops@example.com
+  $ aifabrix role-assistant test customer-support-bot --json
+  $ aifabrix role-assistant test customer-support-bot --publish --force
+
+Notes:
+  - Uses the public/running Role Assistant on the dataplane by default (does not publish local datasources).
+  - Use \`aifabrix upload <roleKey> --env …\` (or \`--publish\`) when you intentionally refresh the package.
+  - Runs lifecycle checks, then prints a portal deep link for full step-by-step status.
+  - Case files with input.message/input.content execute Work Hub plan→accept (or work.start when executionPath: intent).
+  - answers[] and approvals[] are matched to runtime wait payloads (questionKey/requestKey/waitReason).
+  - Use the portal URL for detailed human review while automation reads CLI/JSON output.
+`;
+}
+
+function rawArgsInclude(cmd, flag) {
+  const raw = cmd && Array.isArray(cmd.rawArgs) ? cmd.rawArgs : [];
+  return raw.includes(flag);
+}
+
+function optionOrFlag(options, key, cmd, ...flags) {
+  if (options[key] === true) {
+    return true;
+  }
+  return flags.some((flag) => rawArgsInclude(cmd, flag));
+}
+
+function trimOptionalString(value) {
+  return value ? String(value).trim() : '';
+}
+
+function normalizeRoleAssistantTestOptions(options, cmd) {
+  // Role Assistant test uses the public/running digital worker by default.
+  // Opt in to publish with --publish (optional --force).
+  const wantsPublish = optionOrFlag(options, 'publish', cmd, '--publish');
+  return {
+    env: options.env || 'dev',
+    verbose: optionOrFlag(options, 'verbose', cmd, '-v', '--verbose'),
+    debug: optionOrFlag(options, 'debug', cmd, '-d', '--debug'),
+    json: optionOrFlag(options, 'json', cmd, '--json'),
+    noPublish: !wantsPublish,
+    force: optionOrFlag(options, 'force', cmd, '--force'),
+    subjectUserId: options.subjectUserId || [],
+    subjectEmail: options.subjectEmail || [],
+    certificationProfile: options.certificationProfile || 'bronze',
+    case: trimOptionalString(options.case),
+    testsDir: trimOptionalString(options.testsDir),
+    run: true
+  };
+}
+
+function buildRoleAssistantTestEnvelope(roleKey, verdict, portalUrl, result, opts, caseResult = null) {
+  const report = result.report || {};
+  const envelope = {
+    roleKey,
+    command: 'role-assistant test',
+    verdict,
+    portalUrl,
+    openApiPublished: result.openApiPublished === true,
+    certification: report.certification || null,
+    recommendations: Array.isArray(report.recommendations) ? report.recommendations : [],
+    warnings: Array.isArray(report.warnings) ? report.warnings : [],
+    stepsRun: result.stepsRun || [],
+    case: caseResult
+      ? {
+        caseId: caseResult.caseId,
+        sourceFile: caseResult.sourceFile,
+        passed: caseResult.passed,
+        lifecycleState: caseResult.lifecycleState,
+        assertions: caseResult.assertions,
+        failedAssertions: caseResult.failedAssertions,
+        warnings: Array.isArray(caseResult.warnings) ? caseResult.warnings : [],
+        execution: caseResult.execution || null
+      }
+      : null
+  };
+  if (opts.verbose || opts.debug) {
+    envelope.report = report;
+  }
+  if (opts.debug) {
+    envelope.debug = {
+      observation: caseResult ? caseResult.observation : null,
+      lifecycleResult: result
+    };
+  }
+  return envelope;
+}
+
+function displayCaseResultSummary(caseResult) {
+  if (!caseResult) {
+    return;
+  }
+  logger.log(headerKeyValue('Case:', caseResult.caseId));
+  logger.log(headerKeyValue('Case file:', caseResult.sourceFile));
+  logger.log(headerKeyValue('Observed state:', caseResult.lifecycleState));
+  if (caseResult.execution) {
+    logger.log(headerKeyValue('Execution id:', caseResult.execution.processExecutionId || 'n/a'));
+    logger.log(headerKeyValue('Final runtime status:', caseResult.execution.finalStatus || 'n/a'));
+  }
+  if (caseResult.passed) {
+    logger.log(formatSuccessLine('Case assertions passed.'));
+    const warnings = Array.isArray(caseResult.warnings) ? caseResult.warnings : [];
+    for (const row of warnings) {
+      logger.log(formatWarningLine(row.message || String(row)));
+    }
+    return;
+  }
+  logger.log(formatBlockingError('Case assertions failed.'));
+  for (const row of caseResult.failedAssertions) {
+    logger.log(formatWarningLine(row.message));
+  }
+}
+
+function displayRoleAssistantTestSummary(roleKey, verdict, portalUrl, result, caseResult = null) {
+  logger.log('');
+  logger.log(sectionTitle(`${String(roleKey).toUpperCase()} ROLE ASSISTANT TEST`));
+  logger.log('');
+  logger.log(headerKeyValue('Role key:', roleKey));
+  if (portalUrl) {
+    logger.log(headerKeyValue('Portal:', portalUrl));
+  } else {
+    logger.log(formatWarningLine('Portal link unavailable. Configure dataplane public URL and retry.'));
+  }
+  const verdictMessage =
+    verdict === VERDICT.VERIFIED
+      ? 'Lifecycle checks passed. Open portal for full execution steps and logs.'
+      : 'Lifecycle checks are not fully verified. Open portal to inspect blocking steps.';
+  if (verdict === VERDICT.VERIFIED) {
+    logger.log(formatSuccessParagraph(verdictMessage));
+  } else {
+    logger.log(formatWarningLine(verdictMessage));
+  }
+  const steps = Array.isArray(result.stepsRun) ? result.stepsRun : [];
+  if (steps.length > 0) {
+    logger.log(metadata(`Steps run: ${formatStepsRunSummary(steps)}`));
+  }
+  displayCaseResultSummary(caseResult);
+}
+
+async function resolveRoleAssistantCaseResult(roleKey, opts, result, verdict, portalUrl) {
+  if (!opts.case) {
+    return null;
+  }
+  const roleCase = loadRoleAssistantTestCase(roleKey, opts.case, {
+    testsDir: opts.testsDir || null
+  });
+  if (!isExecutableRoleAssistantCase(roleCase)) {
+    return evaluateRoleAssistantTestCase(roleCase, result, verdict, portalUrl);
+  }
+  const authContext = await resolveLifecycleAuth(roleKey, {
+    ...opts,
+    run: false,
+    noPublish: true
+  });
+  const executionResult = await runRoleAssistantCaseLifecycle(roleKey, roleCase, authContext, opts);
+  const executionVerdict = lifecycleVerdictFromCaseExecution(executionResult, verdict);
+  const evaluationInput = mergeCaseExecutionIntoLifecycleResult(result, executionResult);
+  const evaluation = evaluateRoleAssistantTestCase(
+    roleCase,
+    evaluationInput,
+    executionVerdict,
+    portalUrl
+  );
+  evaluation.execution = {
+    processExecutionId: executionResult.processExecutionId || null,
+    finalStatus: executionResult.finalStatus?.status || null,
+    waitReason: executionResult.finalStatus?.wait?.waitReason || null,
+    interactions: executionResult.interactions || [],
+    workResultError: executionResult.workResultError || null
+  };
+  return evaluation;
+}
+
+function computeRoleAssistantExitCode(verdict, caseResult) {
+  if (caseResult) {
+    return caseResult.passed ? 0 : 2;
+  }
+  if (verdict === VERDICT.VERIFIED) {
+    return 0;
+  }
+  return exitCodeFromVerdict(verdict, { partial: verdict === VERDICT.NOT_VERIFIED });
+}
+
+async function runRoleAssistantTestAction(roleKey, options, cmd) {
+  const opts = normalizeRoleAssistantTestOptions(options, cmd);
+  // Dataplane ExternalSystem key is always ra-{roleKey}; bare roleKey is display/settings only.
+  const systemKey = roleAssistantSystemKey(roleKey);
+  const displayKey = bareRoleKey(roleKey);
+  const result = await runLifecycleForExternalSystem(systemKey, opts);
+  const verdict = lifecycleVerdictFromReport(result.report || {});
+  const portalUrl = buildExternalSystemUiUrl(result.dataplaneUiBaseUrl, systemKey);
+  const caseResult = await resolveRoleAssistantCaseResult(systemKey, opts, result, verdict, portalUrl);
+
+  if (opts.json) {
+    logger.log(
+      JSON.stringify(
+        buildRoleAssistantTestEnvelope(displayKey, verdict, portalUrl, result, opts, caseResult),
+        null,
+        2
+      )
+    );
+  } else {
+    displayRoleAssistantTestSummary(displayKey, verdict, portalUrl, result, caseResult);
+  }
+
+  const exitCode = computeRoleAssistantExitCode(verdict, caseResult);
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}
+
+async function roleAssistantTestHandler(roleKey, options, cmd) {
+  try {
+    await runRoleAssistantTestAction(roleKey, options, cmd);
+  } catch (error) {
+    handleCommandError(error, 'role-assistant test');
+    process.exit(3);
+  }
+}
+
+function setupRoleAssistantCommands(program) {
+  const roleAssistant = program
+    .command('role-assistant')
+    .description('Role Assistant lifecycle and portal workflows');
+
+  roleAssistant
+    .command('test <roleKey>')
+    .description('Run role-assistant lifecycle checks and print portal deep link')
+    .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
+    .option('--case <caseIdOrPath>', 'Run and evaluate one role-assistant test case')
+    .option('--tests-dir <dir>', 'Override role-assistant test case directory')
+    .option('-v, --verbose', 'Include full lifecycle report payload in --json output')
+    .option('-d, --debug', 'Write debug logs under role-assistant/<roleKey>/logs/')
+    .option(
+      '--publish',
+      'Publish local Role Assistant package before checks (default: use public/running worker)'
+    )
+    .option('--force', 'Force upload when --publish is set')
+    .option(
+      '--subject-user-id <id>',
+      'Subject user id for governance generate (repeatable)',
+      collectString,
+      []
+    )
+    .option(
+      '--subject-email <email>',
+      'Subject email for governance generate (repeatable)',
+      collectString,
+      []
+    )
+    .option(
+      '--certification-profile <profile>',
+      'Certification profile for governance generate (bronze, silver, gold, ...)',
+      'bronze'
+    )
+    .option('--json', 'Machine-readable output envelope')
+    .addHelpText('after', roleAssistantHelpAfter())
+    .action((roleKey, options, cmd) => roleAssistantTestHandler(roleKey, options, cmd));
+}
+
+module.exports = {
+  setupRoleAssistantCommands,
+  roleAssistantTestHandler,
+  runRoleAssistantTestAction,
+  normalizeRoleAssistantTestOptions,
+  buildRoleAssistantTestEnvelope,
+  computeRoleAssistantExitCode,
+  resolveRoleAssistantCaseResult,
+  formatStepsRunSummary
+};

package/lib/commands/test-governance-external.js

@@ -23,12 +23,9 @@ const { syncLocalIfRequested } = require('./test-e2e-external');
  */
 async function runTestGovernanceForExternalSystem(externalSystem, options = {}) {
   const pathsUtil = require('../utils/paths');
+  const { assertCertifyExternalWorkspace } = require('../utils/certify-external-workspace');
   const appType = await pathsUtil.detectAppType(externalSystem).catch(() => null);
-  if (!appType || appType.baseDir !== 'integration') {
-    throw new Error(
-      'verify-governance applies to external integration folders only (integration/<systemKey>/).'
-    );
-  }
+  assertCertifyExternalWorkspace(appType && appType.baseDir, 'verify-governance');
 
   const systemKey = externalSystem;
   const packPath = resolveGovernancePackPath(systemKey, {

package/lib/commands/up-miso.js

@@ -41,40 +41,73 @@ function parseImageOptions(imageOpts) {
   return map;
 }
 
-/**
- * Build run options and run keycloak, then miso-controller
- * @async
- * @param {Object} options - Commander options (image, registry, registryMode)
- */
-async function runMisoApps(options) {
-  const imageMap = parseImageOptions(options.image);
+function buildPlatformCommonRunOpts(options) {
   const useBaseImage = options.base !== false;
-  const common = {
+  return {
     registry: options.registry,
     registryMode: options.registryMode,
     skipEnvOutputPath: true,
     skipInfraCheck: true,
     base: useBaseImage,
-    skipManifestMetadataLine: true
+    skipManifestMetadataLine: true,
+    ...(options.platformInstall === true ? { silentPoll: true } : {})
   };
-  const platformPollOpts =
-    options.platformInstall === true
-      ? { silentPoll: true }
-      : {};
-  const keycloakRunOpts = { ...common, ...platformPollOpts };
+}
+
+function applyDeferredPublicUrlWarning(runOpts, options) {
+  if (typeof options.onDeferredPublicUrlWarning !== 'function') {
+    return runOpts;
+  }
+  return {
+    ...runOpts,
+    deferPublicUrlWarning: true,
+    onDeferredPublicUrlWarning: options.onDeferredPublicUrlWarning
+  };
+}
+
+function buildKeycloakRunOpts(options, imageMap) {
+  const runOpts = applyDeferredPublicUrlWarning(buildPlatformCommonRunOpts(options), options);
   if (imageMap.keycloak) {
-    keycloakRunOpts.image = imageMap.keycloak;
+    runOpts.image = imageMap.keycloak;
   }
-  const misoRunOpts = { ...common, ...platformPollOpts };
+  return runOpts;
+}
+
+function buildMisoControllerRunOpts(options, imageMap) {
+  const runOpts = applyDeferredPublicUrlWarning(buildPlatformCommonRunOpts(options), options);
   if (imageMap['miso-controller']) {
-    misoRunOpts.image = imageMap['miso-controller'];
+    runOpts.image = imageMap['miso-controller'];
   }
+  if (typeof options.onMisoPollText === 'function') {
+    runOpts.onPollText = options.onMisoPollText;
+    delete runOpts.silentPoll;
+  }
+  return runOpts;
+}
+
+/**
+ * Build run options and run keycloak, then miso-controller
+ * @async
+ * @param {Object} options - Commander options (image, registry, registryMode)
+ */
+async function runMisoApps(options) {
+  const imageMap = parseImageOptions(options.image);
+  const keycloakRunOpts = buildKeycloakRunOpts(options, imageMap);
+  const misoRunOpts = buildMisoControllerRunOpts(options, imageMap);
   const { emitSystemBuilderAppManifestLineIfTTY } = require('../utils/manifest-source-emit');
-  logger.log(chalk.blue('Starting keycloak...'));
-  emitSystemBuilderAppManifestLineIfTTY(logger, 'keycloak');
+  const platformInstall = options.platformInstall === true;
+  if (!platformInstall) {
+    logger.log(chalk.blue('Starting keycloak...'));
+    emitSystemBuilderAppManifestLineIfTTY(logger, 'keycloak');
+  }
   await app.runApp('keycloak', keycloakRunOpts);
-  logger.log(chalk.blue('Starting miso-controller...'));
-  emitSystemBuilderAppManifestLineIfTTY(logger, 'miso-controller');
+  if (typeof options.onAfterKeycloak === 'function') {
+    options.onAfterKeycloak();
+  }
+  if (!platformInstall) {
+    logger.log(chalk.blue('Starting miso-controller...'));
+    emitSystemBuilderAppManifestLineIfTTY(logger, 'miso-controller');
+  }
   await app.runApp('miso-controller', misoRunOpts);
 }
 
@@ -91,7 +124,9 @@ async function runMisoApps(options) {
  * @throws {Error} If infra not up or any step fails
  */
 async function handleUpMiso(options = {}) {
-  logger.log(chalk.blue('Starting up-miso (keycloak + miso-controller from images)...\n'));
+  if (options.platformInstall !== true) {
+    logger.log(chalk.blue('Starting up-miso (keycloak + miso-controller from images)...\n'));
+  }
   await assertDevInfraUp();
   await ensureAppFromTemplate('keycloak');
   await ensureAppFromTemplate('miso-controller');
@@ -103,8 +138,10 @@ async function handleUpMiso(options = {}) {
   patchEnvOutputPathForDeployOnly('miso-controller');
   refreshUrlsLocalRegistryForCurrentProject();
   await runMisoApps(options);
-  logger.log(formatSuccessParagraph('up-miso complete. Keycloak and miso-controller are running.') +
-    chalk.gray('\n  Run onboarding and register Keycloak from the miso-controller repo if needed. Use \'aifabrix up-dataplane\' for dataplane.'));
+  if (options.platformInstall !== true) {
+    logger.log(formatSuccessParagraph('up-miso complete. Keycloak and miso-controller are running.') +
+      chalk.gray('\n  Run onboarding and register Keycloak from the miso-controller repo if needed. Use \'aifabrix up-dataplane\' for dataplane.'));
+  }
 }
 
 module.exports = { handleUpMiso, parseImageOptions };

package/lib/commands/upload-data-sync-finalize.js

@@ -8,9 +8,18 @@
 
 const { runPostPublishDataSync } = require('./run-post-publish-data-sync');
 const { runUploadSidecarFollowups } = require('./upload-sidecar-followups');
-const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const { formatSuccessLine, formatWarningLine, metadata } = require('../utils/cli-test-layout-chalk');
 const logger = require('../utils/logger');
-const { isQuietMinimalSync } = require('../utils/upload-sync-options');
+
+/**
+ * Internal verify/test --sync / deploy-preflight paths suppress upload banners.
+ * Default CLI `aifabrix upload` uses minimal=true but must still announce "unchanged".
+ * @param {Object} [options]
+ * @returns {boolean}
+ */
+function suppressUnchangedUploadBanner(options = {}) {
+  return options.syncMode === true || options.suppressSummary === true;
+}
 
 /**
  * @async
@@ -27,7 +36,7 @@ async function finalizeUploadPublishResult(ctx, payload, options) {
     options,
     label: 'Upload data sync'
   });
-  return { ...ctx, dataSync };
+  return { ...ctx, dataSync, sidecar: ctx.sidecar || null };
 }
 
 /**
@@ -37,18 +46,27 @@ async function finalizeUploadPublishResult(ctx, payload, options) {
  */
 async function finishUnchangedUploadPublication(params) {
   const { systemKey, options, payload, dataplaneUrl, authConfig, environment } = params;
-  if (!isQuietMinimalSync(options)) {
+  if (!suppressUnchangedUploadBanner(options)) {
+    logger.log('');
     logger.log(formatSuccessLine('Config unchanged on dataplane — upload skipped.'));
+    logger.log(metadata(`System: ${systemKey}`));
+    if (options.probe === true) {
+      logger.log(
+        formatWarningLine('Probe skipped (nothing published). Use --force to republish, then --probe.')
+      );
+    }
+    logger.log('');
   }
-  await runUploadSidecarFollowups({
+  const sidecar = await runUploadSidecarFollowups({
     systemKey,
     options,
     payload,
     dataplaneUrl,
-    authConfig
+    authConfig,
+    environment
   });
   return finalizeUploadPublishResult(
-    { dataplaneUrl, authConfig, environment, uploadSkipped: true },
+    { dataplaneUrl, authConfig, environment, uploadSkipped: true, sidecar },
     payload,
     options
   );