@aifabrix/builder 2.51.1 → 2.52.0

package/lib/cli/infra-guided.js

@@ -8,8 +8,6 @@ const chalk = require('chalk');
 const logger = require('../utils/logger');
 const config = require('../core/config');
 const devConfig = require('../utils/dev-config');
-const pathsUtil = require('../utils/paths');
-const { loadConfigFile } = require('../utils/config-format');
 const { withMutedLogger } = require('../utils/with-muted-logger');
 const infra = require('../infrastructure');
 const { execWithDockerEnv } = require('../utils/docker-exec');
@@ -41,12 +39,72 @@ const {
   logUpPlatformForceCleanSummary,
   logStoppedServices
 } = require('./infra-guided-footers');
-const healthCheck = require('../utils/health-check');
 const { prepareUrlsLocalRegistryForUpPlatform } = require('../commands/up-common');
 const { assertDevInfraUp } = require('../commands/dev-infra-gate');
 const {
   emitSystemBuilderAppManifestLineIfTTY
 } = require('../utils/manifest-source-emit');
+const { flushDeferredPublicUrlWarnings } = require('./infra-guided-public-url-warn');
+
+/**
+ * Guided Keycloak → Miso Controller start with one spinner per app (no second health wait).
+ * @param {Object} options
+ * @param {Function} handleUpMiso
+ * @returns {Promise<string[]>} Deferred public-URL warning messages
+ */
+async function runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso) {
+  const deferredWarnings = [];
+  const misoSpinnerRef = { current: null };
+  emitSystemBuilderAppManifestLineIfTTY(logger, 'keycloak');
+  const kcSpin = startSpinner('Starting Keycloak...');
+  // Fully mute inner run logs — any newline (✔ / Manifest / blank) splits the ora line.
+  await withMutedLogger(
+    () =>
+      handleUpMiso({
+        ...options,
+        platformInstall: true,
+        onAfterKeycloak: () => {
+          stopSpinnerSuccess(kcSpin, 'Keycloak ready');
+          logger.log('');
+          emitSystemBuilderAppManifestLineIfTTY(logger, 'miso-controller');
+          misoSpinnerRef.current = startSpinner('Starting Miso Controller...');
+        },
+        onMisoPollText: (text) => {
+          const spin = misoSpinnerRef.current;
+          if (spin) {
+            // Keep app name; append health progress so the spinner does not look like a new step.
+            spin.text = `Starting Miso Controller… ${stripHealthPrefix(text)}`;
+            return;
+          }
+          logger.log(text);
+        },
+        onDeferredPublicUrlWarning: (message) => deferredWarnings.push(message)
+      }),
+    { allow: () => false }
+  );
+  if (misoSpinnerRef.current) {
+    stopSpinnerSuccess(misoSpinnerRef.current, 'Miso Controller ready');
+  } else {
+    stopSpinnerSuccess(kcSpin, 'Keycloak ready');
+  }
+  flushDeferredPublicUrlWarnings(deferredWarnings);
+  logger.log('');
+  return deferredWarnings;
+}
+
+/** ESC + CSI SGR — built without a control-char regex literal (no-control-regex). */
+const ANSI_SGR_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+
+/**
+ * Turn "Waiting for health check… (4/45)" into "(4/45)" for nested spinner text.
+ * @param {string} text
+ * @returns {string}
+ */
+function stripHealthPrefix(text) {
+  const raw = String(text || '');
+  const match = raw.match(/\((\d+\/\d+)\)/);
+  return match ? `(${match[1]})` : raw.replace(ANSI_SGR_RE, '').trim();
+}
 
 async function getRunningContainerNameForApp(appName) {
   const apps = await infra.getAppStatus();
@@ -86,31 +144,6 @@ async function validateAppErrorLogs(appNames) {
   logger.log('');
 }
 
-async function waitForAppReady(appName, opts = {}) {
-  const timeoutSeconds = Number.isFinite(opts.timeoutSeconds) ? opts.timeoutSeconds : 90;
-  const builderPath = pathsUtil.getBuilderPath(appName);
-  const configPath = pathsUtil.resolveApplicationConfigPath(builderPath);
-  const appConfig = loadConfigFile(configPath) || {};
-
-  const apps = await infra.getAppStatus();
-  const hit = (apps || []).find(a => a && a.name === appName && typeof a.url === 'string');
-  const portMatch = hit && hit.url ? hit.url.match(/:(\d+)$/) : null;
-  const hostPort = portMatch ? parseInt(portMatch[1], 10) : null;
-  if (!hostPort) {
-    throw new Error(`Could not determine host port for ${appName}`);
-  }
-
-  const userCfg = await config.getConfig();
-  const healthRunOpts = { profile: 'docker' };
-  if (userCfg && userCfg.traefik === true) {
-    healthRunOpts.traefikEnabled = true;
-  }
-  if (typeof opts.onPollText === 'function') {
-    healthRunOpts.onPollText = opts.onPollText;
-  }
-  await healthCheck.waitForHealthCheck(appName, timeoutSeconds, hostPort, appConfig, false, healthRunOpts);
-}
-
 function resolveInfraHost(remoteServer) {
   const raw = String(remoteServer || '').trim().replace(/\/+$/, '');
   if (!raw) return 'localhost';
@@ -179,16 +212,7 @@ async function runGuidedUpMiso(options, handleUpMiso) {
   logger.log('');
   logPlatformSetupDurationHint('platform');
   logger.log('');
-  const kcSpin = startSpinner('Starting Keycloak...');
-  await withMutedLogger(() => handleUpMiso({ ...options, platformInstall: true }));
-  stopSpinnerSuccess(kcSpin, 'Keycloak ready');
-  logger.log('');
-  const mcSpin = startSpinner('Starting Miso Controller...');
-  await waitForAppReady('miso-controller', {
-    timeoutSeconds: 120,
-    onPollText: createSpinnerTextUpdater(mcSpin)
-  });
-  stopSpinnerSuccess(mcSpin, 'Miso Controller ready');
+  await runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso);
   await logMisoReadyFooter();
   await validateAppErrorLogs(['miso-controller']);
 }
@@ -241,22 +265,6 @@ async function refreshDataplaneVersionAfterPlatformInstall() {
   }
 }
 
-async function runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso) {
-  emitSystemBuilderAppManifestLineIfTTY(logger, 'keycloak');
-  const kcSpin = startSpinner('Starting Keycloak...');
-  await withMutedLogger(() => handleUpMiso({ ...options, platformInstall: true }));
-  stopSpinnerSuccess(kcSpin, 'Keycloak ready');
-  logger.log('');
-  emitSystemBuilderAppManifestLineIfTTY(logger, 'miso-controller');
-  const mcSpin = startSpinner('Starting Miso Controller...');
-  await waitForAppReady('miso-controller', {
-    timeoutSeconds: 120,
-    onPollText: createSpinnerTextUpdater(mcSpin)
-  });
-  stopSpinnerSuccess(mcSpin, 'Miso Controller ready');
-  logger.log('');
-}
-
 async function runGuidedDataplaneInstallPhase(options, handleUpDataplane, handleLoginFn, controllerUrl) {
   logger.log('');
   emitSystemBuilderAppManifestLineIfTTY(logger, 'dataplane');
@@ -310,7 +318,7 @@ async function runGuidedUpPlatform(options, handleUpMiso, handleUpDataplane, han
   await runGuidedAuthStep(handleLogin, authOpts, { startSpinner, stopSpinnerSuccess });
   const controllerUrl = await resolveGuidedAuthControllerUrl(authOpts);
   await runGuidedDataplaneInstallPhase(options, handleUpDataplane, handleLogin, controllerUrl);
-  const baSpin = startSpinner('Starting builder-api...');
+  const baSpin = startSpinner('Starting Builder API...');
   await withMutedLogger(() => handleUpBuilderApi({ ...options, platformInstall: true }));
   stopSpinnerSuccess(baSpin, 'Builder API ready');
   await validateAppErrorLogs(['miso-controller', 'dataplane', 'builder-api']);
@@ -353,5 +361,6 @@ module.exports = {
   runGuidedUpMiso,
   runGuidedUpDataplane,
   runGuidedUpPlatform,
-  runGuidedDownInfra
+  runGuidedDownInfra,
+  stripHealthPrefix
 };

package/lib/cli/setup-app.help.js

@@ -11,6 +11,10 @@ Examples:
   $ aifabrix test hubspot -v
   $ aifabrix test hubspot -d
 
+  # Role Assistant (role-assistant/ra-<roleKey>/) — lifecycle checks
+  $ aifabrix test ra-business-transformation
+  $ aifabrix role-assistant test business-transformation
+
   # Builder app (builder/<app>/) — runs in container
   $ aifabrix test myapp -e dev
   $ aifabrix test myapp -e tst

package/lib/cli/setup-app.test-commands.js

@@ -12,9 +12,56 @@ const {
   TEST_E2E_HELP_AFTER
 } = require('./setup-app.help');
 
+/** External packages that use local unit validation (not builder container tests). */
+function isExternalUnitTestWorkspace(baseDir) {
+  return baseDir === 'integration' || baseDir === 'enterprise-knowledge';
+}
+
+/**
+ * Dispatch aifabrix test by detected workspace (builder / integration / role-assistant).
+ * @param {string} appName
+ * @param {Object} options
+ * @param {Object} cmd
+ * @returns {Promise<void>}
+ */
+async function runTestCommandAction(appName, options, cmd) {
+  const rawArgs = Array.isArray(cmd?.rawArgs) ? cmd.rawArgs : [];
+  const envExplicit = rawArgs.includes('-e') || rawArgs.includes('--env');
+  const pathsUtil = require('../utils/paths');
+  const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+  if (options.sync === true) {
+    throw new Error(
+      'Option --sync is not supported for aifabrix test (local or container runs do not publish to the dataplane). ' +
+        'Use: aifabrix upload <systemKey>, then aifabrix test-integration <systemKey> --sync or aifabrix datasource test-integration <datasourceKey> --sync.'
+    );
+  }
+  if (appType && appType.baseDir === 'role-assistant') {
+    const { runRoleAssistantTestAction } = require('../commands/role-assistant');
+    await runRoleAssistantTestAction(appName, options, cmd);
+    return;
+  }
+  if (appType && isExternalUnitTestWorkspace(appType.baseDir)) {
+    const test = require('../external-system/test');
+    const externalOpts = {
+      ...options,
+      // Keep help default but don't override auth/env behavior unless user explicitly set it.
+      env: envExplicit ? options.env : undefined
+    };
+    const results = await test.testExternalSystem(appName, externalOpts);
+    test.displayTestResults(results, options.verbose, appName);
+    if (!results.valid) process.exit(1);
+    return;
+  }
+  const { runAppTest } = require('../commands/app-test');
+  await runAppTest(appName, { env: options.env });
+}
+
 function setupTestCommand(program) {
   program.command('test <appKey|systemKey>')
-    .description('Tests: builder appKey in container; external systemKey = local validation')
+    .description(
+      'Tests: builder appKey in container; integration/EK = local validation; ' +
+        'role-assistant = lifecycle (same as role-assistant test)'
+    )
     .option('-e, --env <env>', 'For builder app: dev (running container) or tst (ephemeral)', 'dev')
     .option('-v, --verbose', 'Verbose output')
     .option('-d, --debug', 'Certification debug + log to integration/<systemKey>/logs/ (external only)')
@@ -25,30 +72,7 @@ function setupTestCommand(program) {
     .addHelpText('after', TEST_HELP_AFTER)
     .action(async(appName, options, cmd) => {
       try {
-        const rawArgs = Array.isArray(cmd?.rawArgs) ? cmd.rawArgs : [];
-        const envExplicit = rawArgs.includes('-e') || rawArgs.includes('--env');
-        const pathsUtil = require('../utils/paths');
-        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-        if (options.sync === true) {
-          throw new Error(
-            'Option --sync is not supported for aifabrix test (local or container runs do not publish to the dataplane). ' +
-              'Use: aifabrix upload <systemKey>, then aifabrix test-integration <systemKey> --sync or aifabrix datasource test-integration <datasourceKey> --sync.'
-          );
-        }
-        if (appType && appType.baseDir === 'integration') {
-          const test = require('../external-system/test');
-          const externalOpts = {
-            ...options,
-            // Keep help default but don't override auth/env behavior unless user explicitly set it.
-            env: envExplicit ? options.env : undefined
-          };
-          const results = await test.testExternalSystem(appName, externalOpts);
-          test.displayTestResults(results, options.verbose, appName);
-          if (!results.valid) process.exit(1);
-          return;
-        }
-        const { runAppTest } = require('../commands/app-test');
-        await runAppTest(appName, { env: options.env });
+        await runTestCommandAction(appName, options, cmd);
       } catch (error) {
         handleCommandError(error, 'test');
         process.exit(1);
@@ -106,7 +130,14 @@ async function runTestE2ECommand(appName, options, cmd) {
         'Remove --no-publish for builder app E2E.'
     );
   }
-  if (appType && appType.baseDir === 'integration') {
+  if (appType && appType.baseDir === 'role-assistant') {
+    throw new Error(
+      `'${appName}' is a Role Assistant under role-assistant/. ` +
+        'Datasource E2E does not apply. Use: aifabrix role-assistant test <roleKey> ' +
+        '(or: aifabrix test <roleKey>).'
+    );
+  }
+  if (appType && isExternalUnitTestWorkspace(appType.baseDir)) {
     await runExternalIntegrationE2EAndExit(appName, options, cmd);
     return;
   }
@@ -122,7 +153,7 @@ function setupInstallCommand(program) {
       try {
         const pathsUtil = require('../utils/paths');
         const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-        if (appType && appType.baseDir === 'integration') {
+        if (appType && (isExternalUnitTestWorkspace(appType.baseDir) || appType.baseDir === 'role-assistant')) {
           logger.log(
             chalk.gray('Install is for builder appKey only. Use aifabrix shell <appKey> for builder apps or External Systems commands for integrations.')
           );
@@ -186,7 +217,7 @@ function setupLintCommand(program) {
       try {
         const pathsUtil = require('../utils/paths');
         const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-        if (appType && appType.baseDir === 'integration') {
+        if (appType && (isExternalUnitTestWorkspace(appType.baseDir) || appType.baseDir === 'role-assistant')) {
           logger.log(chalk.gray('lint is for builder appKey only. Use aifabrix shell <appKey> then make lint or pnpm lint.'));
           return;
         }

package/lib/cli/setup-external-system.js

@@ -159,10 +159,44 @@ function setupDeleteCommand(program) {
  * @param {Object} options - CLI options
  * @returns {Promise<boolean>} True if builder test was run, false otherwise
  */
-async function tryBuilderTestIntegration(appName, options) {
+/**
+ * @param {string} appName
+ * @param {Object} options
+ * @returns {Promise<boolean>} True if a builder-app integration test was started
+ */
+async function tryRunBuilderAppIntegration(appName, options) {
   const fsSync = require('fs');
+  const { getBuilderPath } = require('../utils/paths');
+  const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
+  const builderPath = getBuilderPath(appName);
+  if (!fsSync.existsSync(builderPath)) {
+    return false;
+  }
+  let builderConfigPath;
+  try {
+    builderConfigPath = resolveApplicationConfigPath(builderPath);
+  } catch {
+    return false;
+  }
+  if (!fsSync.existsSync(builderConfigPath)) {
+    return false;
+  }
+  const { runAppTestIntegration } = require('../commands/app-test');
+  await runAppTestIntegration(appName, {
+    env: options.env || options.environment || 'dev'
+  });
+  return true;
+}
+
+/**
+ * Prefer builder-app container tests when no externalIntegration folder exists.
+ * @param {string} appName - App or system key
+ * @param {Object} options - CLI options
+ * @returns {Promise<boolean>} True if builder test was run, false otherwise
+ */
+async function tryBuilderTestIntegration(appName, options) {
   const pathsUtil = require('../utils/paths');
-  const { getIntegrationPath, getBuilderPath } = pathsUtil;
+  const { getIntegrationPath } = pathsUtil;
   const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
   const { loadConfigFile } = require('../utils/config-format');
   const integrationPath = getIntegrationPath(appName);
@@ -173,17 +207,10 @@ async function tryBuilderTestIntegration(appName, options) {
   } catch {
     // integration path or config missing
   }
-  if (!hasExternalIntegration) {
-    const builderPath = getBuilderPath(appName);
-    const builderConfigPath = resolveApplicationConfigPath(builderPath);
-    if (fsSync.existsSync(builderPath) && fsSync.existsSync(builderConfigPath)) {
-      const { runAppTestIntegration } = require('../commands/app-test');
-      const opts = { env: options.env || options.environment || 'dev' };
-      await runAppTestIntegration(appName, opts);
-      return true;
-    }
+  if (hasExternalIntegration) {
+    return false;
   }
-  return false;
+  return tryRunBuilderAppIntegration(appName, options);
 }
 
 /**
@@ -233,6 +260,17 @@ async function runTestIntegrationCommand(appName, options) {
     await runAppTestIntegration(appName, opts);
     return;
   }
+  // Role Assistant / EK / integration packages must use the dataplane path — do not
+  // probe builder/<app> (resolveApplicationConfigPath throws when the folder is absent).
+  if (
+    appType &&
+    (appType.baseDir === 'role-assistant' ||
+      appType.baseDir === 'enterprise-knowledge' ||
+      appType.baseDir === 'integration')
+  ) {
+    await runExternalSystemTestIntegration(appName, options);
+    return;
+  }
   const ranBuilder = await tryBuilderTestIntegration(appName, options);
   if (ranBuilder) {
     if (options.sync === true) {

package/lib/commands/channel-add-setup.js

@@ -9,15 +9,21 @@
 const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
-const { isChannelTargetKey } = require('../channels/channel-targets');
+const {
+  formatSupportedChannelTargetsHelp,
+  isChannelTargetKey
+} = require('../channels/channel-targets');
 const { addChannelCommand } = require('../channels/add-channel');
 
 const CHANNEL_ADD_HELP_AFTER = `
+${formatSupportedChannelTargetsHelp()}
 
 Examples:
   # After upload/deploy of the communication external system
   $ aifabrix channel add slack --name "Elsa"
   $ aifabrix channel add teams-bot --name "Elsa" --description "Enterprise AI assistant for employees"
+  $ aifabrix channel add chatgpt --name "Your Assistant"
+  $ aifabrix channel add microsoft-copilot --name "Your Assistant"
 
   # Slack slash-command prefix (registers /{prefix}-help in manifest)
   $ aifabrix channel add slack --name "Elsa" --command-prefix af
@@ -49,7 +55,7 @@ async function runChannelAddAction(channelTarget, options, meta = {}) {
   }
   if (!isChannelTargetKey(channelTarget)) {
     throw new Error(
-      `Unknown channel target "${channelTarget}". Use teams-bot, slack, microsoft-copilot, or chatgpt.`
+      `Unknown channel target "${channelTarget}". ${formatSupportedChannelTargetsHelp()}`
     );
   }
   await addChannelCommand(channelTarget, {

package/lib/commands/channel.js

@@ -16,7 +16,10 @@ const {
   sectionTitle,
   metadata
 } = require('../utils/cli-test-layout-chalk');
-const { CHANNEL_TARGET_KEYS, isChannelTargetKey } = require('../channels/channel-targets');
+const {
+  formatSupportedChannelTargetsHelp,
+  isChannelTargetKey
+} = require('../channels/channel-targets');
 const { scaffoldChannelIntegration } = require('../channels/channel-integration-generator');
 const { registerChannelAddCommand } = require('./channel-add-setup');
 
@@ -25,9 +28,7 @@ Subcommands:
   scaffold <target>   Create integration/<target>/ files locally (step 1)
   add <target>        Channel install guide + manifest/credential patch (step 3)
 
-Targets:
-  teams-bot, slack, microsoft-copilot, chatgpt
-  web-embed (experimental — scaffold with --allow-experimental)
+${formatSupportedChannelTargetsHelp()}
 
 Typical flow (channels are connected systems, not controller apps):
   aifabrix channel scaffold slack
@@ -39,6 +40,15 @@ Controller pipeline apps only: aifabrix app register · aifabrix app list
 Requires: aifabrix login (for add)
 `;
 
+const CHANNEL_SCAFFOLD_HELP_AFTER = `
+${formatSupportedChannelTargetsHelp()}
+
+Typical flow:
+  aifabrix channel scaffold slack
+  aifabrix upload slack --force
+  aifabrix channel add slack --name "Your Assistant" --probe
+`;
+
 /**
  * @param {import('commander').Command} program
  */
@@ -57,11 +67,12 @@ function setupChannelCommands(program) {
     )
     .option('--force', 'Overwrite generated scaffold files when folder exists')
     .option('--allow-experimental', 'Allow web-embed scaffold')
+    .addHelpText('after', CHANNEL_SCAFFOLD_HELP_AFTER)
     .action(async(channelTarget, options) => {
       try {
         if (!isChannelTargetKey(channelTarget)) {
           throw new Error(
-            `Unknown channel target "${channelTarget}". Expected: ${CHANNEL_TARGET_KEYS.join(', ')}`
+            `Unknown channel target "${channelTarget}". ${formatSupportedChannelTargetsHelp()}`
           );
         }
         const result = await scaffoldChannelIntegration(channelTarget, {

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

@@ -142,7 +142,6 @@ async function runDeployBaselineSteps(systemKey, options) {
       uploadStatus: 'published',
       minimal: true,
       suppressSummary: true,
-      suppressPipelineSpinner: true,
       uploadContext: 'deploy-preflight'
     });
     stepOptions = mergeUploadAuthOptions({ ...options, uploadStatus: 'published' }, uploadCtx);
@@ -322,7 +321,9 @@ function inferGatePillarFromLabel(label) {
  * @returns {Promise<{ baseline: { unitPassed: boolean, integrationPassed: boolean }, gates: Object[] }>}
  */
 async function runDeployGateOrchestrator(systemKey, options = {}) {
-  const quiet = options.quietDeployUi === true || options.verbose !== true;
+  // Default: show unit/integration/publish progress (parity with upload).
+  // Only hush when caller opts in (json / explicit quietDeployUi).
+  const quiet = options.quietDeployUi === true;
   if (!quiet) {
     logger.log('');
     logger.log(sectionTitle('Deploy preflight'));

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

@@ -20,12 +20,9 @@ const { VERDICT, verdictFromPassed } = require('../lifecycle/product-model');
  */
 async function runGovernanceVerifyForExternalSystem(systemKey, options = {}) {
   const pathsUtil = require('../utils/paths');
+  const { assertCertifyExternalWorkspace } = require('../utils/certify-external-workspace');
   const appType = await pathsUtil.detectAppType(systemKey).catch(() => null);
-  if (!appType || appType.baseDir !== 'integration') {
-    throw new Error(
-      'governance verify applies to external integration folders only (integration/<systemKey>/).'
-    );
-  }
+  assertCertifyExternalWorkspace(appType && appType.baseDir, 'governance verify');
 
   if (options.pack) {
     const { runTestGovernanceForExternalSystem } = require('./test-governance-external');

package/lib/commands/lifecycle-external.js

@@ -247,23 +247,30 @@ async function executeLifecycleWork(systemKey, options = {}) {
  */
 async function runLifecycleForExternalSystem(systemKey, options = {}) {
   const pathsUtil = require('../utils/paths');
+  const { assertCertifyExternalWorkspace } = require('../utils/certify-external-workspace');
   const appType = await pathsUtil.detectAppType(systemKey).catch(() => null);
-  const allowedRoots = new Set(['integration', 'role-assistant']);
-  if (!appType || !allowedRoots.has(appType.baseDir)) {
-    throw new Error(
-      'lifecycle applies to external authoring folders only (integration/<systemKey>/ or role-assistant/<roleKey>/).'
-    );
+  assertCertifyExternalWorkspace(appType && appType.baseDir, 'lifecycle');
+
+  let resolvedKey = systemKey;
+  if (appType.baseDir === 'role-assistant') {
+    const { resolveExternalIntegrationContext } = require('./test-e2e-external');
+    const { roleAssistantSystemKey } = require('../utils/role-assistant-paths');
+    try {
+      resolvedKey = resolveExternalIntegrationContext(systemKey).systemKey;
+    } catch {
+      resolvedKey = roleAssistantSystemKey(systemKey);
+    }
   }
 
   if (options.run === true) {
     return runWithVerifyStepProgress(
       'Processing',
-      async(progress) => executeLifecycleWork(systemKey, { ...options, lifecycleProgress: progress }),
+      async(progress) => executeLifecycleWork(resolvedKey, { ...options, lifecycleProgress: progress }),
       { json: options.json === true }
     );
   }
 
-  return executeLifecycleWork(systemKey, options);
+  return executeLifecycleWork(resolvedKey, options);
 }
 
 module.exports = {

package/lib/commands/role-assistant.js

@@ -38,6 +38,61 @@ const {
   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 `
@@ -178,8 +233,7 @@ function displayRoleAssistantTestSummary(roleKey, verdict, portalUrl, result, ca
   }
   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(', ')}`));
+    logger.log(metadata(`Steps run: ${formatStepsRunSummary(steps)}`));
   }
   displayCaseResultSummary(caseResult);
 }
@@ -230,21 +284,24 @@ function computeRoleAssistantExitCode(verdict, caseResult) {
 
 async function runRoleAssistantTestAction(roleKey, options, cmd) {
   const opts = normalizeRoleAssistantTestOptions(options, cmd);
-  const result = await runLifecycleForExternalSystem(roleKey, opts);
+  // 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, roleKey);
-  const caseResult = await resolveRoleAssistantCaseResult(roleKey, opts, result, verdict, portalUrl);
+  const portalUrl = buildExternalSystemUiUrl(result.dataplaneUiBaseUrl, systemKey);
+  const caseResult = await resolveRoleAssistantCaseResult(systemKey, opts, result, verdict, portalUrl);
 
   if (opts.json) {
     logger.log(
       JSON.stringify(
-        buildRoleAssistantTestEnvelope(roleKey, verdict, portalUrl, result, opts, caseResult),
+        buildRoleAssistantTestEnvelope(displayKey, verdict, portalUrl, result, opts, caseResult),
         null,
         2
       )
     );
   } else {
-    displayRoleAssistantTestSummary(roleKey, verdict, portalUrl, result, caseResult);
+    displayRoleAssistantTestSummary(displayKey, verdict, portalUrl, result, caseResult);
   }
 
   const exitCode = computeRoleAssistantExitCode(verdict, caseResult);
@@ -309,5 +366,6 @@ module.exports = {
   normalizeRoleAssistantTestOptions,
   buildRoleAssistantTestEnvelope,
   computeRoleAssistantExitCode,
-  resolveRoleAssistantCaseResult
+  resolveRoleAssistantCaseResult,
+  formatStepsRunSummary
 };