@aifabrix/builder 2.53.0 → 2.54.1

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

@@ -1,108 +1,153 @@
 /**
  * Register `channel add` (and optional deprecated aliases).
  *
- * @fileoverview Shared Commander wiring for assistant channel install (plan 152)
+ * @fileoverview Shared Commander wiring for assistant channel install
  */
 
 'use strict';
 
 const chalk = require('chalk');
 const logger = require('../utils/logger');
-const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
 const {
-  formatSupportedChannelTargetsHelp,
+  formatUnknownChannelTargetError,
   isChannelTargetKey
 } = require('../channels/channel-targets');
-const { addChannelCommand } = require('../channels/add-channel');
-
-const CHANNEL_ADD_HELP_AFTER = `
-${formatSupportedChannelTargetsHelp()}
-
-One command covers scaffold → upload → install:
-  $ aifabrix channel add slack --name "Elsa" --probe
-
-Examples:
-  $ 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" \\
-      --oauth-plugin-vault-reference-id "<Teams-Entra-SSO-auth-config-id>"
-
-  # Slack slash-command prefix (registers /{prefix}-help in manifest)
-  $ aifabrix channel add slack --name "Elsa" --command-prefix af
-
-  # Generate artifacts only; no dataplane patch / upload
-  $ aifabrix channel add slack --name "Elsa" --dry-run
-
-  # Re-upload communication system + regenerate channel config (does not rotate secrets)
-  $ aifabrix channel add slack --name "Elsa" --force
-
-  # Validate callbacks and assistant catalog after install
-  $ aifabrix channel add slack --name "Elsa" --probe
+const { addChannelCommand, runAddChannel } = require('../channels/add-channel');
+const { toChannelInstallEnvelope } = require('../channels/channel-install-envelope');
+const {
+  isChannelAddCancelled,
+  promptChannelAddWizard
+} = require('../channels/channel-add-wizard');
+const { formatChannelAddFailure } = require('../channels/channel-add-failure');
+const {
+  CHANNEL_ADD_HELP_AFTER,
+  channelAddHelpAfter,
+  configureChannelAddHelp,
+  resolveChannelAddHelpTarget
+} = require('./channel-add-help');
 
-Behavior:
-  - Scaffolds integration/<target>/ when missing (does not overwrite existing files)
-  - Uploads when the system is not on the dataplane; with --force uploads every time
-  - Then configures the channel install (artifacts, credentials, admin guide)
-  - microsoft-copilot uses Entra SSO (trustedIssuer); pass --oauth-plugin-vault-reference-id
-    from Teams Developer Portal. Does not create Fabrix oauth2 channel credentials.
+/**
+ * @param {Object} options
+ * @returns {Object}
+ */
+function toAddChannelCommandOptions(options) {
+  return {
+    name: options.name,
+    description: options.description,
+    icon: options.icon,
+    template: options.template,
+    commandPrefix: options.commandPrefix,
+    systemKey: options.systemKey,
+    oauthPluginVaultReferenceId: options.oauthPluginVaultReferenceId,
+    packageVersion: options.packageVersion,
+    callbackUrl: options.callbackUrl,
+    allowExperimental: options.allowExperimental === true,
+    dryRun: options.dryRun === true,
+    force: options.force === true,
+    probe: options.probe === true,
+    verbose: options.verbose === true,
+    onboardUsers:
+      options.noOnboardUsers === true ? false : options.onboardUsers === true ? true : undefined,
+    target: options.target,
+    profile: options.profile,
+    mcpClientProfile: options.mcpClientProfile
+  };
+}
 
-Requires: aifabrix login
-`;
+/**
+ * Resolve wizard vs explicit target. Explicit path still requires --name.
+ * @param {string|undefined} channelTarget
+ * @param {Object} options
+ * @returns {Promise<{ channelTarget: string, name: string }>}
+ */
+async function resolveChannelAddSelection(channelTarget, options) {
+  if (!channelTarget) {
+    return promptChannelAddWizard(options);
+  }
+  if (!isChannelTargetKey(channelTarget)) {
+    throw new Error(formatUnknownChannelTargetError(channelTarget));
+  }
+  if (!options.name || typeof options.name !== 'string' || !options.name.trim()) {
+    throw new Error('--name is required for channel add');
+  }
+  return {
+    channelTarget,
+    name: options.name,
+    mcpClientProfile: options.target || options.profile
+  };
+}
 
 /**
  * @param {string} channelTarget
  * @param {Object} options
  * @param {{ deprecatedVia?: string }} [meta]
+ * @returns {Promise<void>}
  */
 async function runChannelAddAction(channelTarget, options, meta = {}) {
   if (meta.deprecatedVia) {
     logger.warn(
       chalk.yellow(
-        `Deprecated: use "aifabrix channel add ${channelTarget} ..." instead of "${meta.deprecatedVia}".`
+        `Deprecated: use "aifabrix channel add ${channelTarget || ''} ..." instead of "${meta.deprecatedVia}".`
       )
     );
   }
-  if (!isChannelTargetKey(channelTarget)) {
-    throw new Error(
-      `Unknown channel target "${channelTarget}". ${formatSupportedChannelTargetsHelp()}`
-    );
-  }
-  await addChannelCommand(channelTarget, {
-    name: options.name,
-    description: options.description,
-    icon: options.icon,
-    template: options.template,
-    commandPrefix: options.commandPrefix,
-    oauthPluginVaultReferenceId: options.oauthPluginVaultReferenceId,
-    dryRun: options.dryRun === true,
-    force: options.force === true,
-    probe: options.probe === true
+  const selection = await resolveChannelAddSelection(channelTarget, options);
+  const addOptions = toAddChannelCommandOptions({
+    ...options,
+    ...selection,
+    name: selection.name,
+    mcpClientProfile: selection.mcpClientProfile || options.target || options.profile
   });
+  if (options.json === true) {
+    addOptions.quiet = true;
+    const result = await runAddChannel(selection.channelTarget, addOptions);
+    const envelope = toChannelInstallEnvelope({
+      channelTarget: selection.channelTarget,
+      displayName: addOptions.name,
+      runtimeValues: (result && result.runtimeValues) || { appName: addOptions.name },
+      ctx: { projectRoot: process.cwd() }
+    });
+    process.stdout.write(`${JSON.stringify(envelope)}\n`);
+    return;
+  }
+  await addChannelCommand(selection.channelTarget, addOptions);
 }
 
 /**
- * @param {import('commander').Command} parent
- * @param {{ deprecatedVia?: string, commandName?: string, hidden?: boolean }} [meta]
+ * @param {Error} error
+ * @returns {void}
+ */
+function handleChannelAddError(error) {
+  if (isChannelAddCancelled(error)) {
+    process.exit(0);
+  }
+  if (!error.message?.includes('Authentication required')) {
+    logger.error(formatChannelAddFailure(error));
+  }
+  process.exit(1);
+}
+
+/**
+ * @param {import('commander').Command} cmd
  * @returns {import('commander').Command}
  */
-function registerChannelAddCommand(parent, meta = {}) {
-  const description =
-    'Scaffold (if needed), upload (if needed/--force), then configure channel install';
-  const commandName = meta.commandName || 'add <channelTarget>';
-  const cmd = meta.hidden
-    ? parent.command(commandName, { hidden: true })
-    : parent.command(commandName);
-  cmd
-    .description(meta.deprecatedVia ? `(deprecated) ${description}` : description)
-    .requiredOption('-n, --name <name>', 'Customer-visible channel name (e.g. "Elsa")')
+function attachChannelAddOptions(cmd) {
+  return cmd
+    .option(
+      '-n, --name <name>',
+      'Customer-visible channel name (e.g. "Elsa"); required when the target is specified. Quoted names may contain spaces'
+    )
     .option('-d, --description <text>', 'Channel description (default generated)')
     .option('--icon <path>', 'Path to channel icon asset')
     .option('--template <name>', 'Template override (default from channel target)')
     .option('--dry-run', 'Generate artifacts only; do not upload, patch, or set credentials')
     .option(
       '--force',
-      'Re-upload communication system and regenerate channel config (does not rotate secrets)'
+      'Refresh integration files from the channel template, re-upload, and regenerate channel config (does not rotate secrets)'
+    )
+    .option(
+      '--system-key <key>',
+      'Connected System instance key (default: derived from the channel and --name)'
     )
     .option(
       '--command-prefix <key>',
@@ -110,26 +155,63 @@ function registerChannelAddCommand(parent, meta = {}) {
     )
     .option(
       '--oauth-plugin-vault-reference-id <id>',
-      'Teams Developer Portal Entra SSO OAuth auth-config id (microsoft-copilot)'
+      'Teams Entra SSO auth-config id (microsoft-copilot); optional when Agents Toolkit can create it'
+    )
+    .option(
+      '--package-version <semver>',
+      'Teams manifest version (microsoft-copilot); default auto-bumps minor on regenerate'
     )
     .option('--probe', 'After install, validate callbacks and assistant catalog')
-    .addHelpText('after', CHANNEL_ADD_HELP_AFTER)
-    .action(async(channelTarget, options) => {
-      try {
-        await runChannelAddAction(channelTarget, options, meta);
-      } catch (error) {
-        if (!error.message?.includes('Authentication required')) {
-          const detail = error.message || String(error);
-          logger.error(formatBlockingError(`Channel install failed:\n${detail}`));
-        }
-        process.exit(1);
-      }
-    });
+    .option('--onboard-users', 'Onboard Slack users by matching email after install')
+    .option('--no-onboard-users', 'Skip Slack user onboard')
+    .option('-v, --verbose', 'Print scaffold file list and upload internals')
+    .option('--callback-url <url>', 'ChatGPT or Claude OAuth callback URL to register on the matching profile')
+    .option(
+      '--target <profile>',
+      'MCP client installation profile when the channel is mcp-client (cursor, vscode, github-copilot)'
+    )
+    .option('--profile <profile>', 'Alias for --target (MCP client installation profile)')
+    .option('--allow-experimental', 'Allow experimental targets such as web-embed')
+    .option('--json', 'Machine-readable install envelope (no TTY glyphs)');
+}
+
+/**
+ * @param {{ deprecatedVia?: string }} meta
+ * @returns {Function}
+ */
+function handleChannelAddAction(meta) {
+  return async(channelTarget, options) => {
+    try {
+      await runChannelAddAction(channelTarget, options, meta);
+    } catch (error) {
+      handleChannelAddError(error);
+    }
+  };
+}
+
+/**
+ * @param {import('commander').Command} parent
+ * @param {{ deprecatedVia?: string, commandName?: string, hidden?: boolean }} [meta]
+ * @returns {import('commander').Command}
+ */
+function registerChannelAddCommand(parent, meta = {}) {
+  const description =
+    'Scaffold (if needed), upload (if needed/--force), then configure channel install';
+  const commandName = meta.commandName || 'add [channelTarget]';
+  const cmd = meta.hidden
+    ? parent.command(commandName, { hidden: true })
+    : parent.command(commandName);
+  cmd.description(meta.deprecatedVia ? `(deprecated) ${description}` : description);
+  attachChannelAddOptions(cmd);
+  configureChannelAddHelp(cmd);
+  cmd.addHelpText('after', () => channelAddHelpAfter(resolveChannelAddHelpTarget()));
+  cmd.action(handleChannelAddAction(meta));
   return cmd;
 }
 
 module.exports = {
   CHANNEL_ADD_HELP_AFTER,
   registerChannelAddCommand,
-  runChannelAddAction
+  runChannelAddAction,
+  resolveChannelAddSelection
 };

package/lib/commands/channel-configure.js

@@ -0,0 +1,118 @@
+/**
+ * Register `channel configure` (callback URL on the existing Integration Client).
+ *
+ * @fileoverview Thin wrapper over Integration Client redirect URI update
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const {
+  formatWarningLine,
+  formatBlockingError
+} = require('../utils/cli-layout-chalk');
+const { printCallbackRegistered } = require('../channels/channel-add-tty');
+const { isChannelTargetKey, formatUnknownChannelTargetError } = require('../channels/channel-targets');
+const { resolveChannelAuthContext } = require('../channels/channel-auth-context');
+const { registerChatGptCallbackUrl } = require('../channels/chatgpt-callback');
+const { runChatGptConfigureValidate } = require('../channels/chatgpt-channel-add');
+const { registerClaudeCallbackUrl } = require('../channels/claude-callback');
+const { runClaudeConfigureValidate } = require('../channels/claude-channel-add');
+
+const CONFIGURE_TARGETS = new Set(['chatgpt', 'claude']);
+
+const CHANNEL_CONFIGURE_HELP_AFTER = `
+Examples:
+  $ aifabrix channel configure chatgpt --callback-url "https://chatgpt.com/connector/oauth/callback"
+  $ aifabrix channel configure claude --callback-url "https://claude.ai/api/mcp/auth_callback"
+
+Registers an HTTPS OAuth callback on the existing ChatGPT or Claude Integration Client.
+Does not rotate the client secret. Extra redirect URIs are preserved.
+
+Requires: aifabrix login and integration-client:read plus integration-client:update
+`;
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} ctx
+ * @param {string} callbackUrl
+ * @returns {Promise<Object>}
+ */
+async function registerConfigureCallback(channelTarget, ctx, callbackUrl) {
+  if (channelTarget === 'claude') {
+    return registerClaudeCallbackUrl({ ctx, callbackUrl });
+  }
+  return registerChatGptCallbackUrl({ ctx, callbackUrl });
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} ctx
+ * @returns {Promise<void>}
+ */
+async function validateAfterConfigure(channelTarget, ctx) {
+  if (channelTarget === 'claude') {
+    await runClaudeConfigureValidate(ctx);
+    return;
+  }
+  await runChatGptConfigureValidate(ctx);
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} options
+ * @returns {Promise<void>}
+ */
+async function runChannelConfigure(channelTarget, options = {}) {
+  if (!isChannelTargetKey(channelTarget)) {
+    throw new Error(formatUnknownChannelTargetError(channelTarget));
+  }
+  if (!CONFIGURE_TARGETS.has(channelTarget)) {
+    throw new Error(
+      `channel configure currently supports chatgpt and claude. Received "${channelTarget}".`
+    );
+  }
+  const callbackUrl =
+    typeof options.callbackUrl === 'string' ? options.callbackUrl.trim() : '';
+  if (!callbackUrl) {
+    throw new Error(`--callback-url is required for channel configure ${channelTarget}.`);
+  }
+  const ctx = await resolveChannelAuthContext(channelTarget, { silent: true });
+  const result = await registerConfigureCallback(channelTarget, ctx, callbackUrl);
+  if (result.fallback) {
+    logger.log(
+      formatWarningLine(
+        `Missing integration-client:update. Add the callback on the ${channelTarget} profile: ${result.profileUrl}`
+      )
+    );
+    return;
+  }
+  printCallbackRegistered();
+  await validateAfterConfigure(channelTarget, ctx);
+}
+
+/**
+ * @param {import('commander').Command} parent
+ * @returns {import('commander').Command}
+ */
+function registerChannelConfigureCommand(parent) {
+  return parent
+    .command('configure <channelTarget>')
+    .description('Register a ChatGPT or Claude callback URL on the existing OAuth2 profile')
+    .option('--callback-url <url>', 'HTTPS redirect URI from ChatGPT or Claude OAuth')
+    .addHelpText('after', CHANNEL_CONFIGURE_HELP_AFTER)
+    .action(async(channelTarget, options) => {
+      try {
+        await runChannelConfigure(channelTarget, options);
+      } catch (error) {
+        logger.error(formatBlockingError(error.message || String(error)));
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  CHANNEL_CONFIGURE_HELP_AFTER,
+  registerChannelConfigureCommand,
+  runChannelConfigure
+};

package/lib/commands/channel.js

@@ -22,15 +22,23 @@ const {
 } = require('../channels/channel-targets');
 const { scaffoldChannelIntegration } = require('../channels/channel-integration-generator');
 const { registerChannelAddCommand } = require('./channel-add-setup');
+const { registerChannelConfigureCommand } = require('./channel-configure');
 
 const CHANNEL_HELP_AFTER = `
 Subcommands:
-  add <target>        One command: scaffold (if needed) → upload (if needed/--force) → install
+  add [target]        One command: scaffold (if needed) → upload (if needed/--force) → install
+  configure chatgpt   Register the ChatGPT callback URL on the existing OAuth2 profile
   scaffold <target>   Optional: create integration/<target>/ files only (local)
 
 ${formatSupportedChannelTargetsHelp()}
 
+Examples:
+  $ aifabrix channel add
+  $ aifabrix channel add slack --name "Elsa" --probe
+  $ aifabrix channel configure chatgpt --callback-url "https://chatgpt.com/connector/oauth/callback"
+
 Typical flow:
+  aifabrix channel add
   aifabrix channel add slack --name "Elsa" --probe
 
   # Force re-upload of the communication system, then reinstall channel
@@ -102,6 +110,7 @@ function setupChannelCommands(program) {
     });
 
   registerChannelAddCommand(channel);
+  registerChannelConfigureCommand(channel);
 }
 
 module.exports = { setupChannelCommands };

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

@@ -4,7 +4,10 @@
 
 'use strict';
 
-const { uploadGovernanceScenarioPacks } = require('../lifecycle/scenario-upload');
+const {
+  uploadGovernanceScenarioPacks,
+  normalizeGovernanceUploadResult
+} = require('../lifecycle/scenario-upload');
 const { resolveGovernanceIntegrationContext } = require('./governance-cli-shared');
 
 /**
@@ -18,7 +21,7 @@ async function runGovernanceUploadForExternalSystem(systemKey, options = {}) {
     systemKey,
     options
   );
-  const uploaded = await uploadGovernanceScenarioPacks(
+  const result = await uploadGovernanceScenarioPacks(
     resolvedKey,
     dataplaneUrl,
     authConfig,
@@ -27,7 +30,7 @@ async function runGovernanceUploadForExternalSystem(systemKey, options = {}) {
   return {
     systemKey: resolvedKey,
     command: 'governance upload',
-    uploaded
+    ...normalizeGovernanceUploadResult(result)
   };
 }
 

package/lib/commands/lifecycle-command-action.js

@@ -14,6 +14,7 @@ const { displayLifecycleReportTTY } = require('../lifecycle/report-display');
 const { VERDICT } = require('../lifecycle/product-model');
 const { exitCodeFromVerdict } = require('../lifecycle/exit-codes');
 const { lifecycleHasGovernanceSubjects } = require('../lifecycle/lifecycle-governance-options');
+const { lifecyclePillarSatisfied } = require('../lifecycle/role-assistant-governance');
 
 /**
  * @param {Object} options
@@ -48,11 +49,7 @@ function lifecycleVerdictFromReport(report) {
   if (ops === VERDICT.FAILED || trust === VERDICT.FAILED || gov === VERDICT.FAILED) {
     return VERDICT.FAILED;
   }
-  if (
-    ops === VERDICT.VERIFIED &&
-    trust === VERDICT.VERIFIED &&
-    gov === VERDICT.VERIFIED
-  ) {
+  if (lifecyclePillarSatisfied(ops) && lifecyclePillarSatisfied(trust) && lifecyclePillarSatisfied(gov)) {
     return VERDICT.VERIFIED;
   }
   return VERDICT.NOT_VERIFIED;