@aifabrix/builder 2.53.1 → 2.55.0

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

@@ -0,0 +1,366 @@
+/**
+ * Target-scoped help for `aifabrix channel add`.
+ *
+ * `channel add -h` is the full catalog. `channel add chatgpt -h` lists ChatGPT
+ * flags and examples only (no Slack, Copilot, or MCP-client leftovers).
+ *
+ * @fileoverview Channel add help — catalog vs named-target options
+ */
+
+'use strict';
+
+const { Help } = require('commander');
+const {
+  formatSupportedChannelTargetsHelp,
+  isChannelTargetKey
+} = require('../channels/channel-targets');
+
+const SHARED_OPTION_LONG = new Set([
+  '--name',
+  '--description',
+  '--icon',
+  '--template',
+  '--dry-run',
+  '--force',
+  '--system-key',
+  '--probe',
+  '--verbose',
+  '--json',
+  '--help'
+]);
+
+const TARGET_OPTION_LONG = {
+  slack: new Set(['--command-prefix', '--onboard-users', '--no-onboard-users']),
+  'microsoft-copilot': new Set(['--oauth-plugin-vault-reference-id', '--package-version']),
+  chatgpt: new Set(['--callback-url']),
+  claude: new Set(['--callback-url']),
+  'mcp-client': new Set(['--target', '--profile']),
+  'teams-bot': new Set(),
+  'web-embed': new Set(['--allow-experimental'])
+};
+
+const VALUE_FLAGS = new Set([
+  '-n',
+  '--name',
+  '-d',
+  '--description',
+  '--icon',
+  '--template',
+  '--command-prefix',
+  '--oauth-plugin-vault-reference-id',
+  '--package-version',
+  '--callback-url',
+  '--target',
+  '--profile'
+]);
+
+const CHANNEL_ADD_HELP_AFTER = `
+${formatSupportedChannelTargetsHelp()}
+
+One command covers scaffold → upload → install:
+  $ aifabrix channel add slack --name "Elsa" --probe
+
+Examples:
+  $ aifabrix channel add
+  $ 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 chatgpt --name "Your Assistant" \\
+      --callback-url "https://chatgpt.com/connector/oauth/callback"
+  $ aifabrix channel configure chatgpt --callback-url "https://chatgpt.com/connector/oauth/callback"
+  $ aifabrix channel add claude --name "Onni"
+  $ aifabrix channel configure claude --callback-url "https://claude.ai/api/mcp/auth_callback"
+  $ aifabrix channel add mcp-client --target cursor --name "Onni"
+  $ aifabrix channel add mcp-client --target vscode --name "Onni"
+  $ aifabrix channel add mcp-client --target github-copilot --name "Onni"
+  $ 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
+
+  # Refresh local integration from the channel template, re-upload, regenerate config
+  $ aifabrix channel add slack --name "Elsa" --force
+
+  # Copilot: after MCP URL / Entra change — regenerate ZIP (bumps Teams version 1.0.0 → 1.1.0)
+  $ aifabrix channel add microsoft-copilot --name "Your Assistant" --force \\
+      --oauth-plugin-vault-reference-id "<Teams-Entra-SSO-auth-config-id>"
+
+  # Optional: pin Teams manifest version instead of auto minor bump
+  $ aifabrix channel add microsoft-copilot --name "Your Assistant" --force --package-version 1.2.0 \\
+      --oauth-plugin-vault-reference-id "<Teams-Entra-SSO-auth-config-id>"
+
+  # Validate callbacks and assistant catalog after install
+  $ aifabrix channel add slack --name "Elsa" --probe
+
+  # Slack onboard (email match) without a TTY prompt
+  $ aifabrix channel add slack --name "Elsa" --onboard-users
+  $ aifabrix channel add slack --name "Elsa" --no-onboard-users
+
+Behavior:
+  - Omit the target in a terminal to choose name and channel interactively
+  - --name is required when the target is specified (scripts and CI)
+  - -name is the same as --name; quoted names may contain spaces
+  - Scaffolds integration/<target>/ when missing, empty, or incomplete
+  - With --force, refreshes integration/<target>/ from the channel template, then uploads every time
+  - Uploads when the system is not on the dataplane
+  - Then configures the channel install (artifacts, credentials, admin guide)
+  - slack may ask **Onboard users?** and match Slack profile email to platform user email.
+    Non-interactive: --onboard-users or --no-onboard-users. Default is skip when not asked.
+  - chatgpt registers the ChatGPT callback URL when provided (--callback-url or TTY prompt).
+    It does not rotate the client secret. Remaining ChatGPT steps: Create with logo (cannot change later), Publish, Connect.
+  - claude registers the Claude callback URL (https://claude.ai/api/mcp/auth_callback) and prints
+    Name, Server URL, and Authentication: OAuth. Open https://claude.ai/new#settings/customize-connectors
+    and add a custom connector with those three values (Runtime MCP requires sign-in). Use channel
+    configure claude --callback-url only if Claude shows a callback that is not already registered.
+  - mcp-client writes the Runtime MCP URL into the editor MCP config. Pass --target (or --profile)
+    with cursor, vscode, or github-copilot. It creates or reuses the Integration Client and never
+    rotates the client secret. Remaining step: Reload the editor.
+  - microsoft-copilot uses Entra SSO (trustedIssuer). Agents Toolkit (atk) creates or reuses
+    the Teams Entra SSO auth-config when you are signed in to the matching tenant. Pass
+    --oauth-plugin-vault-reference-id only when you already have the id or toolkit cannot
+    create it. Does not create Fabrix oauth2 channel credentials. Re-run with --force after
+    Runtime MCP URL or SSO changes; Teams manifest version auto-bumps minor (1.0.0 → 1.1.0)
+    unless --package-version is set. --force reuses the existing auth-config id.
+  - teams-bot uses Teams Developer CLI (teams app create --azure) around the existing
+    AI Fabrix messages URL. Azure subscription, resource group, and Entra tenant come
+    from the controller environment (same as Copilot Entra SSO). Remaining Microsoft
+    steps are tenant policy only. --force reuses the Azure-managed bot for this
+    environment and tenant.
+
+Requires: aifabrix login
+`;
+
+const SHARED_TARGET_BEHAVIOR = `Behavior:
+  - --name is required when the target is specified (scripts and CI)
+  - Quoted names may contain spaces
+  - Scaffolds integration/<target>/ when missing, empty, or incomplete
+  - With --force, refreshes integration/<target>/ from the channel template, then uploads every time
+  - Uploads when the system is not on the dataplane
+  - Then configures the channel install (artifacts, credentials, admin guide)`;
+
+const TARGET_HELP_AFTER = {
+  chatgpt: `
+Examples:
+  $ aifabrix channel add chatgpt --name "Your Assistant"
+  $ aifabrix channel add chatgpt --name "Your Assistant" \\
+      --callback-url "https://chatgpt.com/connector/oauth/callback"
+  $ aifabrix channel add chatgpt --name "Your Assistant" --force
+  $ aifabrix channel add chatgpt --name "Your Assistant" --probe
+  $ aifabrix channel configure chatgpt --callback-url "https://chatgpt.com/connector/oauth/callback"
+
+${SHARED_TARGET_BEHAVIOR}
+  - chatgpt registers the ChatGPT callback URL when provided (--callback-url or TTY prompt).
+    It does not rotate the client secret. Remaining ChatGPT steps: Create with logo (cannot change later), Publish, Connect.
+
+Requires: aifabrix login
+
+See all channels:
+  $ aifabrix channel add -h
+`,
+  claude: `
+Examples:
+  $ aifabrix channel add claude --name "Onni"
+  $ aifabrix channel add claude --name "Onni" --force
+  $ aifabrix channel configure claude --callback-url "https://claude.ai/api/mcp/auth_callback"
+
+${SHARED_TARGET_BEHAVIOR}
+  - claude registers the Claude callback URL (https://claude.ai/api/mcp/auth_callback) and prints
+    Name, Server URL, and Authentication: OAuth. Open https://claude.ai/new#settings/customize-connectors
+    and add a custom connector with those three values (Runtime MCP requires sign-in).
+
+Requires: aifabrix login
+
+See all channels:
+  $ aifabrix channel add -h
+`,
+  slack: `
+Examples:
+  $ aifabrix channel add slack --name "Elsa"
+  $ aifabrix channel add slack --name "Elsa" --command-prefix af
+  $ aifabrix channel add slack --name "Elsa" --force --probe
+  $ aifabrix channel add slack --name "Elsa" --onboard-users
+  $ aifabrix channel add slack --name "Elsa" --no-onboard-users
+
+${SHARED_TARGET_BEHAVIOR}
+  - slack may ask **Onboard users?** and match Slack profile email to platform user email.
+    Non-interactive: --onboard-users or --no-onboard-users. Default is skip when not asked.
+
+Requires: aifabrix login
+
+See all channels:
+  $ aifabrix channel add -h
+`,
+  'microsoft-copilot': `
+Examples:
+  $ aifabrix channel add microsoft-copilot --name "Your Assistant" \\
+      --oauth-plugin-vault-reference-id "<Teams-Entra-SSO-auth-config-id>"
+  $ aifabrix channel add microsoft-copilot --name "Your Assistant" --force \\
+      --oauth-plugin-vault-reference-id "<Teams-Entra-SSO-auth-config-id>"
+  $ aifabrix channel add microsoft-copilot --name "Your Assistant" --force --package-version 1.2.0 \\
+      --oauth-plugin-vault-reference-id "<Teams-Entra-SSO-auth-config-id>"
+
+${SHARED_TARGET_BEHAVIOR}
+  - microsoft-copilot uses Entra SSO (trustedIssuer). Pass --oauth-plugin-vault-reference-id
+    only when you already have the Teams Entra SSO auth-config id or toolkit cannot create it.
+    --force reuses the existing auth-config id. Teams manifest version auto-bumps minor
+    unless --package-version is set.
+
+Requires: aifabrix login
+
+See all channels:
+  $ aifabrix channel add -h
+`,
+  'mcp-client': `
+Examples:
+  $ aifabrix channel add mcp-client --target cursor --name "Onni"
+  $ aifabrix channel add mcp-client --target vscode --name "Onni"
+  $ aifabrix channel add mcp-client --target github-copilot --name "Onni"
+
+${SHARED_TARGET_BEHAVIOR}
+  - mcp-client writes the Runtime MCP URL into the editor MCP config. Pass --target (or --profile)
+    with cursor, vscode, or github-copilot. Remaining step: Reload the editor.
+
+Requires: aifabrix login
+
+See all channels:
+  $ aifabrix channel add -h
+`,
+  'teams-bot': `
+Examples:
+  $ aifabrix channel add teams-bot --name "Elsa" --description "Enterprise AI assistant for employees"
+  $ aifabrix channel add teams-bot --name "Elsa" --force
+
+${SHARED_TARGET_BEHAVIOR}
+  - teams-bot uses Teams Developer CLI (teams app create --azure) around the existing
+    AI Fabrix messages URL. Azure subscription, resource group, and Entra tenant come
+    from the controller environment. Remaining Microsoft steps are tenant policy only.
+
+Requires: aifabrix login
+
+See all channels:
+  $ aifabrix channel add -h
+`,
+  'web-embed': `
+Examples:
+  $ aifabrix channel add web-embed --name "Onni" --allow-experimental
+
+${SHARED_TARGET_BEHAVIOR}
+  - web-embed is experimental. Pass --allow-experimental to install.
+
+Requires: aifabrix login
+
+See all channels:
+  $ aifabrix channel add -h
+`
+};
+
+/**
+ * Read the named channel target from `channel add` argv (help runs before parse).
+ * @param {string[]} [argv]
+ * @returns {string|null}
+ */
+function resolveChannelAddHelpTarget(argv = process.argv) {
+  const start = channelAddArgStart(argv);
+  for (let i = start; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--') {
+      break;
+    }
+    if (arg.startsWith('-')) {
+      i += skipOptionValue(arg, argv[i + 1]);
+      continue;
+    }
+    if (isChannelTargetKey(arg)) {
+      return arg;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {number}
+ */
+function channelAddArgStart(argv) {
+  for (let i = 1; i < argv.length; i += 1) {
+    if (argv[i] === 'add' && argv[i - 1] === 'channel') {
+      return i + 1;
+    }
+  }
+  return argv.length;
+}
+
+/**
+ * @param {string} arg
+ * @param {string|undefined} next
+ * @returns {number} extra indexes consumed
+ */
+function skipOptionValue(arg, next) {
+  const eq = arg.indexOf('=');
+  if (eq !== -1) {
+    return 0;
+  }
+  const flag = arg;
+  if (VALUE_FLAGS.has(flag) && next && !next.startsWith('-')) {
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * @param {import('commander').Option} option
+ * @param {string|null} target
+ * @returns {boolean}
+ */
+function isChannelAddOptionVisible(option, target) {
+  if (!target) {
+    return true;
+  }
+  const long = option.long;
+  if (!long || SHARED_OPTION_LONG.has(long)) {
+    return true;
+  }
+  const extra = TARGET_OPTION_LONG[target];
+  return Boolean(extra && extra.has(long));
+}
+
+/**
+ * @param {string|null} [target]
+ * @returns {string}
+ */
+function channelAddHelpAfter(target) {
+  if (target && TARGET_HELP_AFTER[target]) {
+    return TARGET_HELP_AFTER[target];
+  }
+  return CHANNEL_ADD_HELP_AFTER;
+}
+
+/**
+ * @param {import('commander').Command} cmd
+ * @returns {import('commander').Command}
+ */
+function configureChannelAddHelp(cmd) {
+  if (typeof cmd.configureHelp !== 'function') {
+    return cmd;
+  }
+  cmd.configureHelp({
+    visibleOptions(command) {
+      const listed = Help.prototype.visibleOptions.call(this, command);
+      const target = resolveChannelAddHelpTarget();
+      return listed.filter((option) => isChannelAddOptionVisible(option, target));
+    }
+  });
+  return cmd;
+}
+
+module.exports = {
+  CHANNEL_ADD_HELP_AFTER,
+  channelAddHelpAfter,
+  configureChannelAddHelp,
+  isChannelAddOptionVisible,
+  resolveChannelAddHelpTarget
+};

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
 };