@aifabrix/builder 2.50.0 → 2.51.1

package/lib/commands/role-assistant.js

@@ -0,0 +1,313 @@
+/**
+ * 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');
+
+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) {
+    const labels = steps.map((row) => (row && row.pillar ? row.pillar : String(row)));
+    logger.log(metadata(`Steps run: ${labels.join(', ')}`));
+  }
+  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);
+  const result = await runLifecycleForExternalSystem(roleKey, opts);
+  const verdict = lifecycleVerdictFromReport(result.report || {});
+  const portalUrl = buildExternalSystemUiUrl(result.dataplaneUiBaseUrl, roleKey);
+  const caseResult = await resolveRoleAssistantCaseResult(roleKey, opts, result, verdict, portalUrl);
+
+  if (opts.json) {
+    logger.log(
+      JSON.stringify(
+        buildRoleAssistantTestEnvelope(roleKey, verdict, portalUrl, result, opts, caseResult),
+        null,
+        2
+      )
+    );
+  } else {
+    displayRoleAssistantTestSummary(roleKey, 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
+};