@aifabrix/builder 2.51.1 → 2.52.1

package/lib/commands/channel.js

@@ -16,29 +16,44 @@ 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');
 
 const CHANNEL_HELP_AFTER = `
 Subcommands:
-  scaffold <target>   Create integration/<target>/ files locally (step 1)
-  add <target>        Channel install guide + manifest/credential patch (step 3)
+  add <target>        One command: scaffold (if needed) → upload (if needed/--force) → install
+  scaffold <target>   Optional: create integration/<target>/ files only (local)
+
+${formatSupportedChannelTargetsHelp()}
 
-Targets:
-  teams-bot, slack, microsoft-copilot, chatgpt
-  web-embed (experimental — scaffold with --allow-experimental)
+Typical flow:
+  aifabrix channel add slack --name "Elsa" --probe
 
-Typical flow (channels are connected systems, not controller apps):
+  # Force re-upload of the communication system, then reinstall channel
+  aifabrix channel add slack --name "Elsa" --force --probe
+
+Optional low-level steps (usually unnecessary):
   aifabrix channel scaffold slack
   aifabrix upload slack --force
-  aifabrix channel add slack --name "Elsa" --probe
 
 Controller pipeline apps only: aifabrix app register · aifabrix app list
 
 Requires: aifabrix login (for add)
 `;
 
+const CHANNEL_SCAFFOLD_HELP_AFTER = `
+${formatSupportedChannelTargetsHelp()}
+
+Prefer one command (scaffold + upload + install):
+  aifabrix channel add slack --name "Your Assistant" --probe
+
+scaffold alone only writes local files under integration/<target>/.
+`;
+
 /**
  * @param {import('commander').Command} program
  */
@@ -46,7 +61,7 @@ function setupChannelCommands(program) {
   const channel = program
     .command('channel')
     .description(
-      'Assistant channels (Slack, Teams, Copilot, ChatGPT) — scaffold integration and install'
+      'Assistant channels — one-command add (scaffold → upload → install), plus optional scaffold'
     )
     .addHelpText('after', CHANNEL_HELP_AFTER);
 
@@ -57,11 +72,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, {
@@ -75,8 +91,7 @@ function setupChannelCommands(program) {
           logger.log(metadata(file));
         }
         logger.log('');
-        logger.log(chalk.white('Next steps:'));
-        logger.log(chalk.gray(`  aifabrix upload ${channelTarget} --force`));
+        logger.log(chalk.white('Next step (recommended):'));
         logger.log(
           chalk.gray(`  aifabrix channel add ${channelTarget} --name "Your Assistant" --probe`)
         );

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/integration-definition.js

@@ -0,0 +1,158 @@
+/**
+ * CLI: integration-definition validate | apply
+ * @fileoverview BT → Builder BID commands (no section PATCH orchestration)
+ */
+
+'use strict';
+
+/* eslint-disable no-console */
+
+const chalk = require('chalk');
+const fs = require('fs');
+const path = require('path');
+const {
+  applyIntegrationDefinition,
+  validateIntegrationDefinition,
+  withDefinitionHash
+} = require('../integration-definition');
+const { handleCommandError } = require('../utils/cli-utils');
+const {
+  formatSuccessLine,
+  formatBlockingError,
+  failureGlyph
+} = require('../utils/cli-layout-chalk');
+
+const PARENT_HELP_AFTER = `
+
+Examples:
+  $ aifabrix integration-definition validate ./bid.json
+  $ aifabrix integration-definition apply ./bid.json --dry-run
+
+BID is the minimal business create language (systemKind, resourceType, propertyKeys).
+Apply materializes integration/<systemKey>/ package files (EDS/system).
+AI catalog: GET /help?topic=resourceTypeCatalog on builder-api.
+`;
+
+const VALIDATE_HELP_AFTER = `
+
+Examples:
+  $ aifabrix integration-definition validate ./bid.json
+  $ aifabrix integration-definition validate ./bid.json --fix-hash
+
+Checks JSON Schema, definitionHash, product rules, and active resourceType catalog keys.
+`;
+
+const APPLY_HELP_AFTER = `
+
+Examples:
+  $ aifabrix integration-definition apply ./bid.json
+  $ aifabrix integration-definition apply ./bid.json --dry-run
+  $ aifabrix integration-definition apply ./bid.json --force
+  $ aifabrix integration-definition apply ./bid.json --output-dir /tmp/out
+`;
+
+/**
+ * @param {string} filePath
+ * @returns {Record<string, unknown>}
+ */
+function loadBidFile(filePath) {
+  const abs = path.resolve(filePath);
+  if (!fs.existsSync(abs)) {
+    throw new Error(`BID file not found: ${abs}`);
+  }
+  return JSON.parse(fs.readFileSync(abs, 'utf8'));
+}
+
+/**
+ * @param {string} file
+ * @param {{ fixHash?: boolean }} options
+ * @returns {Promise<void>}
+ */
+async function runValidateCommand(file, options) {
+  let bid = loadBidFile(file);
+  if (options.fixHash) {
+    bid = withDefinitionHash(bid);
+    fs.writeFileSync(path.resolve(file), `${JSON.stringify(bid, null, 2)}\n`, 'utf8');
+    console.log(formatSuccessLine(`Wrote definitionHash to ${file}`));
+  }
+  const result = validateIntegrationDefinition(bid);
+  if (!result.valid) {
+    console.error(formatBlockingError('BID invalid'));
+    for (const err of result.errors) {
+      console.error(chalk.red(`  ${failureGlyph()} ${err}`));
+    }
+    process.exit(1);
+  }
+  console.log(formatSuccessLine('BID valid'));
+  console.log(`  definitionId: ${result.bid.definitionId}`);
+  console.log(`  definitionHash: ${result.bid.definitionHash}`);
+}
+
+/**
+ * @param {string} file
+ * @param {{ outputDir?: string, dryRun?: boolean, force?: boolean }} options
+ * @returns {Promise<void>}
+ */
+async function runApplyCommand(file, options) {
+  const bid = loadBidFile(file);
+  const out = await applyIntegrationDefinition(bid, {
+    outputDir: options.outputDir,
+    dryRun: Boolean(options.dryRun),
+    force: Boolean(options.force)
+  });
+  console.log(formatSuccessLine(`BID apply ${out.status}`));
+  console.log(`  systemKey: ${out.systemKey}`);
+  console.log(`  outputDir: ${out.outputDir}`);
+  console.log(`  definitionHash: ${out.definitionHash}`);
+  if (out.files) {
+    console.log(`  files: ${out.files.join(', ')}`);
+  }
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupIntegrationDefinitionCommands(program) {
+  const cmd = program
+    .command('integration-definition')
+    .description(
+      'Validate or apply a Builder Integration Definition (BID) — minimal business create language for integration packages'
+    )
+    .addHelpText('after', PARENT_HELP_AFTER);
+
+  cmd
+    .command('validate <file>')
+    .description(
+      'Validate BID JSON (schema, definitionHash, product rules, resourceType catalog)'
+    )
+    .option('--fix-hash', 'Rewrite file with computed definitionHash')
+    .addHelpText('after', VALIDATE_HELP_AFTER)
+    .action(async(file, options) => {
+      try {
+        await runValidateCommand(file, options);
+      } catch (error) {
+        handleCommandError(error, 'integration-definition validate');
+      }
+    });
+
+  cmd
+    .command('apply <file>')
+    .description(
+      'Idempotently apply BID to integration/<systemKey>/ (Builder-owned EDS/system writes)'
+    )
+    .option('--output-dir <dir>', 'Override output directory')
+    .option('--force', 'Rewrite package even when definitionHash matches stamp')
+    .option('--dry-run', 'Show planned files without writing')
+    .addHelpText('after', APPLY_HELP_AFTER)
+    .action(async(file, options) => {
+      try {
+        await runApplyCommand(file, options);
+      } catch (error) {
+        handleCommandError(error, 'integration-definition apply');
+      }
+    });
+}
+
+module.exports = {
+  setupIntegrationDefinitionCommands
+};

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/repair-auth-apply.js

@@ -28,6 +28,7 @@ const ALLOWED_REPAIR_AUTH = [
   'oidc',
   'hmac',
   'none',
+  'system',
   'bearerforward'
 ];
 
@@ -57,8 +58,12 @@ function isAllowedRepairAuth(authOption) {
  */
 function buildAuthenticationForRepair(systemKey, authOption) {
   const normalized = normalizeRepairAuthOption(authOption);
+  if (normalized === 'system') {
+    return buildSystemAuthentication();
+  }
   if (normalized === 'bearerforward') {
-    return buildBearerForwardAuthentication();
+    // Legacy alias: prefer authType system for platform facades.
+    return buildSystemAuthentication();
   }
   const schemaMethod =
     normalized === 'queryparam'
@@ -70,11 +75,19 @@ function buildAuthenticationForRepair(systemKey, authOption) {
 }
 
 /**
- * Facade APIs that forward the caller Bearer token — no workspace kv secret.
- * @returns {{ authType: 'none' }}
+ * Platform-managed downstream authentication (no workspace kv secret).
+ * @returns {{ authType: 'system' }}
+ */
+function buildSystemAuthentication() {
+  return { authType: 'system' };
+}
+
+/**
+ * @deprecated Use buildSystemAuthentication — bearerForward is not a public authType.
+ * @returns {{ authType: 'system' }}
  */
 function buildBearerForwardAuthentication() {
-  return { authType: 'none' };
+  return buildSystemAuthentication();
 }
 
 /**
@@ -99,7 +112,7 @@ function mergePreservedAuthVariables(mergedVariables, existingVars) {
 function repairAuthChangeLabel(authOption) {
   const normalized = normalizeRepairAuthOption(authOption);
   if (normalized === 'bearertoken' || normalized === 'bearerkey') return 'bearerToken';
-  if (normalized === 'bearerforward') return 'bearerForward';
+  if (normalized === 'bearerforward') return 'system';
   return normalized;
 }
 
@@ -157,6 +170,7 @@ module.exports = {
   normalizeRepairAuthOption,
   isAllowedRepairAuth,
   buildAuthenticationForRepair,
+  buildSystemAuthentication,
   buildBearerForwardAuthentication,
   mergePreservedAuthVariables,
   repairAuthChangeLabel,

package/lib/commands/repair-datasource-sync-operations.js

@@ -108,7 +108,10 @@ function ensureSyncOperationScaffold(parsed) {
     parsed.execution = { engine: 'cip' };
   }
   if (!parsed.execution.cip || typeof parsed.execution.cip !== 'object') {
-    parsed.execution.cip = { operations: {} };
+    parsed.execution.cip = { version: '1.0', operations: {} };
+  }
+  if (!parsed.execution.cip.version) {
+    parsed.execution.cip.version = '1.0';
   }
   if (!parsed.execution.cip.operations || typeof parsed.execution.cip.operations !== 'object') {
     parsed.execution.cip.operations = {};

package/lib/commands/role-assistant-test-output.js

@@ -0,0 +1,200 @@
+/**
+ * Role Assistant test CLI envelope + human summary output.
+ * @fileoverview Split from role-assistant.js for max-lines / complexity
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { VERDICT } = require('../lifecycle/product-model');
+const {
+  sectionTitle,
+  headerKeyValue,
+  formatSuccessLine,
+  formatSuccessParagraph,
+  formatWarningLine,
+  formatBlockingError,
+  metadata
+} = require('../utils/cli-test-layout-chalk');
+
+/**
+ * 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 mapCaseEnvelopeRow(row) {
+  return {
+    caseId: row.caseId,
+    sourceFile: row.sourceFile,
+    passed: row.passed,
+    lifecycleState: row.lifecycleState,
+    assertions: row.assertions,
+    failedAssertions: row.failedAssertions,
+    warnings: Array.isArray(row.warnings) ? row.warnings : [],
+    execution: row.execution || null
+  };
+}
+
+function attachEnvelopeCases(envelope, caseResult) {
+  if (Array.isArray(caseResult)) {
+    envelope.cases = caseResult.map(mapCaseEnvelopeRow);
+    const passed = envelope.cases.filter((c) => c.passed).length;
+    envelope.summary = {
+      total: envelope.cases.length,
+      passed,
+      failed: envelope.cases.length - passed
+    };
+    envelope.case = envelope.cases.length === 1 ? envelope.cases[0] : null;
+    return;
+  }
+  if (caseResult) {
+    envelope.case = mapCaseEnvelopeRow(caseResult);
+  }
+}
+
+function buildRoleAssistantTestEnvelope(roleKey, verdict, portalUrl, result, opts, caseResult = null) {
+  const report = result.report || {};
+  const multiCase = Array.isArray(caseResult) && caseResult.length > 1;
+  const envelope = {
+    roleKey,
+    command: 'role-assistant test',
+    mode: opts.suite || multiCase ? 'suite' : 'single',
+    suite: opts.suite || null,
+    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: null,
+    cases: null,
+    summary: null
+  };
+  attachEnvelopeCases(envelope, caseResult);
+  if (opts.verbose || opts.debug) {
+    envelope.report = report;
+  }
+  if (opts.debug) {
+    envelope.debug = {
+      observation: caseResult && !Array.isArray(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 displayPortalAndVerdict(portalUrl, verdict) {
+  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));
+  }
+}
+
+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));
+  displayPortalAndVerdict(portalUrl, verdict);
+  const steps = Array.isArray(result.stepsRun) ? result.stepsRun : [];
+  if (steps.length > 0) {
+    logger.log(metadata(`Steps run: ${formatStepsRunSummary(steps)}`));
+  }
+  if (Array.isArray(caseResult)) {
+    for (const row of caseResult) {
+      displayCaseResultSummary(row);
+    }
+    const passed = caseResult.filter((c) => c.passed).length;
+    logger.log(headerKeyValue('Suite summary:', `${passed}/${caseResult.length} passed`));
+    return;
+  }
+  displayCaseResultSummary(caseResult);
+}
+
+module.exports = {
+  formatStepsRunSummary,
+  buildRoleAssistantTestEnvelope,
+  displayRoleAssistantTestSummary
+};