@aifabrix/builder 2.53.1 → 2.55.0

package/lib/channels/add-channel.js

@@ -9,9 +9,15 @@
 'use strict';
 
 const path = require('path');
-const { getChannelTarget, getDefaultChannelDescription } = require('./channel-targets');
+const {
+  assertChannelTargetInstallable,
+  getDefaultChannelDescription
+} = require('./channel-targets');
+const { deriveChannelInstanceKey } = require('./channel-instance-key');
 const { resolveAppDescription } = require('./channel-description');
 const { resolveChannelRuntimeValues } = require('./channel-runtime-resolver');
+const { vendorFacingUrlsFromCtx } = require('./vendor-dataplane-url');
+const { applySlackPackageVersion } = require('./channel-package-version');
 const { generateChannelArtifact } = require('./channel-artifact-generator');
 const { fetchRuntimeLayerBToolNames } = require('./runtime-tool-catalog');
 const { loadChannelPackageContext } = require('./channel-discovery');
@@ -36,21 +42,30 @@ const { runChannelProbe } = require('./channel-probe');
 const { resolveChannelAuthContext } = require('./channel-auth-context');
 const { ensureChannelCredential } = require('./channel-credential');
 const {
-  buildChannelApprovalGuide,
+  buildLiveInstallApprovalGuide,
   resolveApprovalPortalUrl
 } = require('./channel-approval-guide');
 const {
   normalizeBaseChannelName,
   resolveChannelDisplayName
 } = require('./channel-display-name');
-const { displayChannelInstallResult } = require('./channel-status-display');
+const { printLiveChannelCanonicalTty } = require('./channel-add-remaining');
 const { ensureChannelReadyForAdd } = require('./channel-add-ensure');
-const { showExistingChannelStatus } = require('./channel-add-existing');
+const { liveInstallTtyCtx, showExistingChannelStatus, shouldReturnSkippedChannel } = require('./channel-add-existing');
 const {
   assertMicrosoftCopilotOauthReference,
   assertMicrosoftCopilotOauthReferenceBeforeForce,
   loadMicrosoftCopilotEntraContext
 } = require('./microsoft-copilot-channel-add');
+const {
+  maybeAssertMcpClientProfile
+} = require('./mcp-client-channel-add');
+const {
+  runChannelAddPreflights,
+  runChannelAddContinuations
+} = require('./channel-add-continuations');
+const { maybeProvisionSlackChannel, applySlackOnboardToCtx } = require('./slack-channel-add');
+const { maybeProvisionTeamsBotChannel } = require('./teams-bot-channel-add');
 
 /**
  * @param {typeof import('./channel-targets').CHANNEL_TARGETS[string]} target
@@ -66,22 +81,6 @@ function resolveInstallStatus(target, channelExt, dryRun) {
   return 'installed';
 }
 
-/**
- * @param {Object|null} validation
- * @returns {Object|null}
- */
-function toValidationDisplay(validation) {
-  if (!validation) return null;
-  return {
-    callbackReachable: validation.callbackReachable,
-    credentialValid: validation.credentialValid,
-    assistantCatalogReachable: validation.assistantCatalogReachable,
-    inboundVerification: Object.values(validation.inboundVerification).every(Boolean),
-    probeTiers: validation.probeTiers || null,
-    runtimeChecks: validation.runtimeChecks || null
-  };
-}
-
 /**
  * @param {string} channelTarget
  * @param {Object} artifactParams
@@ -102,6 +101,26 @@ function generateArtifactWithAudit(channelTarget, artifactParams) {
   }
 }
 
+/**
+ * @param {string} channelTarget
+ * @param {Object} packageContext
+ * @param {Object} ctx
+ * @returns {Promise<string[]>}
+ */
+async function resolveInstallLayerBToolNames(channelTarget, packageContext, ctx) {
+  const usesLayerB = channelTarget === 'chatgpt'
+    || channelTarget === 'microsoft-copilot'
+    || channelTarget === 'mcp-client'
+    || channelTarget === 'claude';
+  if (!usesLayerB) {
+    return [];
+  }
+  if (packageContext?.governedToolNames?.length > 0) {
+    return packageContext.governedToolNames;
+  }
+  return fetchRuntimeLayerBToolNames(ctx.dataplaneUrl, ctx.authConfig, channelTarget);
+}
+
 /**
  * @param {Object} ctx
  * @param {string} channelTarget
@@ -113,7 +132,7 @@ function generateArtifactWithAudit(channelTarget, artifactParams) {
 async function patchConfigWithAudit(ctx, channelTarget, channelBlock, status, artifactHash) {
   try {
     await patchChannelExtension(
-      { dataplaneUrl: ctx.dataplaneUrl, authConfig: ctx.authConfig, channelTarget },
+      { ...ctx, channelTarget },
       channelBlock
     );
     auditConfigPatched(channelTarget, { status, artifactHash });
@@ -156,18 +175,20 @@ async function maybeRunProbe(ctx, channelBlock, channelTarget, probe) {
  * @returns {Promise<{ target: Object, name: string, baseName: string, description: string, ctx: Object, existing: Object|null }>}
  */
 async function prepareChannelContext(channelTarget, options) {
-  const target = getChannelTarget(channelTarget);
-  if (target.experimental) {
-    throw new Error(
-      `Channel target "${channelTarget}" is experimental. Confirm product requirement before use.`
-    );
-  }
+  const target = assertChannelTargetInstallable(channelTarget, options);
   if (!options.name || typeof options.name !== 'string' || !options.name.trim()) {
     throw new Error('--name is required for channel add');
   }
 
   const baseName = normalizeBaseChannelName(options.name);
-  const ctx = await resolveChannelAuthContext(channelTarget, { silent: options.quiet });
+  const ctx =
+    options.authContext && typeof options.authContext === 'object'
+      ? options.authContext
+      : await resolveChannelAuthContext(channelTarget, {
+        silent: options.verbose !== true
+      });
+  ctx.instanceSystemKey = options.systemKey;
+  ctx.projectRoot = options.projectRoot;
   const name = resolveChannelDisplayName(baseName, ctx.environment);
   const rawDescription =
     options.description && String(options.description).trim()
@@ -176,9 +197,9 @@ async function prepareChannelContext(channelTarget, options) {
   const description = resolveAppDescription(channelTarget, rawDescription);
 
   const system = await fetchCommunicationSystem({
-    dataplaneUrl: ctx.dataplaneUrl,
-    authConfig: ctx.authConfig,
-    channelTarget
+    ...ctx,
+    channelTarget,
+    allowMissing: channelTarget === 'slack'
   });
   const existing = getExistingChannelExtension(system);
   return { target, name, baseName, description, ctx, existing };
@@ -189,58 +210,42 @@ async function prepareChannelContext(channelTarget, options) {
  * @returns {Promise<Object>}
  */
 async function completeLiveInstall(params) {
-  const { ctx, channelTarget, channelBlock, status, artifact, target, name, baseName, options } = params;
-
+  const { ctx, channelTarget, channelBlock, status, artifact, target, options } = params;
   await ensureChannelCredential({
     ctx,
     channelTarget,
     target,
     force: options.force === true
   });
-
   await patchConfigWithAudit(ctx, channelTarget, channelBlock, status, artifact.artifactHash);
-
-  const projectRoot = options.projectRoot || process.cwd();
-  const approvalGuide =
-    status === 'approvalRequired'
-      ? buildChannelApprovalGuide(channelTarget, {
-        projectRoot,
-        name,
-        baseName,
-        artifactPath: artifact.outputPath,
-        dataplaneBaseUrl: ctx.dataplaneUrl,
-        environment: ctx.environment || options.environment || 'dev'
-      })
-      : null;
+  const approvalGuide = buildLiveInstallApprovalGuide(params);
   if (approvalGuide?.portalUrl) {
     auditApprovalRequired(channelTarget, { approvalUrl: approvalGuide.portalUrl });
   }
-
   const validation = await maybeRunProbe(ctx, channelBlock, channelTarget, options.probe);
-
-  displayChannelInstallResult({
-    channelTarget,
-    name,
-    baseName,
-    statusLabel: status === 'approvalRequired' ? 'Approval required' : 'Installed',
-    credentialKey: target.credentialKey,
-    capabilities: target.capabilities,
-    artifactPath: artifact.outputPath,
-    installGuidePath: artifact.installPath,
-    zipPath: artifact.zipPath,
-    installReady: artifact.installReady,
-    blocker: artifact.blocker,
-    packageReady: artifact.packageReady,
-    packageBlocker: artifact.packageBlocker,
-    microsoftPublicationPending:
-      artifact.microsoftPublicationPending !== undefined
-        ? artifact.microsoftPublicationPending
-        : status === 'approvalRequired',
-    validation: toValidationDisplay(validation),
-    approvalGuide
-  });
-
-  return { channelBlock, artifact, validation, approvalGuide };
+  const slack = params.slackProvision || null;
+  const teamsBot = params.teamsBotProvision || null;
+  let ttyCtx = liveInstallTtyCtx(ctx, slack, teamsBot);
+  if (channelTarget === 'slack') {
+    ttyCtx = await applySlackOnboardToCtx(ttyCtx, options);
+  }
+  if (options.quiet !== true) {
+    printLiveChannelCanonicalTty({
+      channelTarget,
+      ctx: ttyCtx,
+      options,
+      runtimeValues: params.runtimeValues
+    });
+  }
+  return {
+    channelBlock,
+    artifact,
+    validation,
+    approvalGuide,
+    slackProvision: slack,
+    teamsBotProvision: teamsBot,
+    runtimeValues: params.runtimeValues
+  };
 }
 
 /**
@@ -248,26 +253,24 @@ async function completeLiveInstall(params) {
  * @returns {{ dryRun: true, channelBlock: Object, artifact: Object }}
  */
 function finishDryRunInstall(params) {
-  displayChannelInstallResult({
-    channelTarget: params.channelTarget,
-    name: params.name,
-    baseName: params.baseName,
-    statusLabel: 'Generated (dry-run)',
-    credentialKey: params.target.credentialKey,
-    capabilities: params.target.capabilities,
-    artifactPath: params.artifact.outputPath,
-    installGuidePath: params.artifact.installPath,
-    zipPath: params.artifact.zipPath,
-    installReady: params.artifact.installReady,
-    blocker: params.artifact.blocker
-  });
-  return { dryRun: true, channelBlock: params.channelBlock, artifact: params.artifact };
+  if (params.options && params.options.quiet !== true) {
+    printLiveChannelCanonicalTty({
+      channelTarget: params.channelTarget,
+      ctx: {
+        dataplaneUrl: params.runtimeValues && params.runtimeValues.dataplaneBaseUrl
+      },
+      options: params.options || { dryRun: true },
+      runtimeValues: params.runtimeValues
+    });
+  }
+  return {
+    dryRun: true,
+    channelBlock: params.channelBlock,
+    artifact: params.artifact,
+    runtimeValues: params.runtimeValues
+  };
 }
 
-/**
- * @param {Object} params
- * @returns {Promise<{ artifact: Object, channelBlock: Object, status: string }>}
- */
 /**
  * @param {Object|null} packageContext
  * @param {Object} options
@@ -286,7 +289,9 @@ function brandingIconOrOption(packageContext, options, key) {
 
 async function resolvePackageContextForInstall(params) {
   const { channelTarget, options, name, description, ctx } = params;
-  const packagingTargets = new Set(['chatgpt', 'microsoft-copilot', 'slack', 'teams-bot']);
+  const packagingTargets = new Set([
+    'chatgpt', 'microsoft-copilot', 'slack', 'teams-bot', 'mcp-client', 'claude'
+  ]);
   if (!packagingTargets.has(channelTarget)) {
     return null;
   }
@@ -325,52 +330,66 @@ async function resolvePackageContextForInstall(params) {
   };
 }
 
-async function buildInstallArtifacts(params) {
-  const { channelTarget, options, target, existing, name, baseName, description, ctx } = params;
-  const packageContext = await resolvePackageContextForInstall(params);
-  let runtimeToolNames = [];
-  if (channelTarget === 'chatgpt' || channelTarget === 'microsoft-copilot') {
-    runtimeToolNames =
-      packageContext?.governedToolNames?.length > 0
-        ? packageContext.governedToolNames
-        : await fetchRuntimeLayerBToolNames(ctx.dataplaneUrl, ctx.authConfig, channelTarget);
-  }
+async function resolveInstallRuntimeValues(params, packageContext, runtimeToolNames) {
+  const { channelTarget, options, existing, name, baseName, description, ctx } = params;
   let entraProvider = null;
   let entraIdentityProvider = null;
   if (channelTarget === 'microsoft-copilot') {
     ({ entraProvider, entraIdentityProvider } = await loadMicrosoftCopilotEntraContext(ctx));
   }
-  const runtimeValues = resolveChannelRuntimeValues({
-    dataplaneBaseUrl: ctx.dataplaneUrl,
+  applySlackPackageVersion(channelTarget, options, existing);
+  const vendor = vendorFacingUrlsFromCtx(ctx);
+  return resolveChannelRuntimeValues({
+    dataplaneBaseUrl: vendor.dataplaneBaseUrl,
+    controllerUrl: vendor.controllerUrl,
     channelTarget,
+    instanceSystemKey: options.systemKey,
     appName: name,
     baseName,
     environment: ctx.environment,
     appDescription: description,
     icon: options.icon,
     commandPrefix: options.commandPrefix,
+    enableMcpServer: options.enableMcpServer,
     layerBToolNames: runtimeToolNames,
     packageContext,
     entraProvider,
     entraIdentityProvider,
     oauthPluginVaultReferenceId: options.oauthPluginVaultReferenceId,
+    packageVersion: options.packageVersion,
     scopes: options.scopes,
     iconColorPath: brandingIconOrOption(packageContext, options, 'iconColorPath'),
-    iconOutlinePath: brandingIconOrOption(packageContext, options, 'iconOutlinePath')
+    iconOutlinePath: brandingIconOrOption(packageContext, options, 'iconOutlinePath'),
+    mcpClientProfile:
+      channelTarget === 'mcp-client' ? maybeAssertMcpClientProfile(channelTarget, options) : undefined
   });
-  const projectRoot = options.projectRoot || process.cwd();
+}
+
+async function buildInstallArtifacts(params) {
+  const { channelTarget, options, target, existing, name, baseName, description } = params;
+  const packageContext = await resolvePackageContextForInstall(params);
+  const runtimeToolNames = await resolveInstallLayerBToolNames(channelTarget, packageContext, params.ctx);
+  const runtimeValues = await resolveInstallRuntimeValues(params, packageContext, runtimeToolNames);
   const artifact = generateArtifactWithAudit(channelTarget, {
-    projectRoot,
+    projectRoot: options.projectRoot || process.cwd(),
     channelTarget,
     runtimeValues,
     dryRun: options.dryRun === true
   });
   const status = resolveInstallStatus(target, existing, options.dryRun === true);
   const channelBlock = buildChannelExtensionBlock(
-    { name, baseName, description, artifactHash: artifact.artifactHash, status },
+    {
+      name,
+      baseName,
+      description,
+      status,
+      artifactHash: artifact.artifactHash,
+      commandPrefix: runtimeValues.commandPrefix,
+      packageVersion: runtimeValues.packageVersion
+    },
     target
   );
-  return { artifact, channelBlock, status };
+  return { artifact, channelBlock, status, runtimeValues };
 }
 
 /**
@@ -379,34 +398,40 @@ async function buildInstallArtifacts(params) {
  * @returns {Object}
  */
 function assertChannelAddOptions(channelTarget, options) {
-  const target = getChannelTarget(channelTarget);
-  if (target.experimental) {
-    throw new Error(
-      `Channel target "${channelTarget}" is experimental. Confirm product requirement before use.`
-    );
-  }
+  const target = assertChannelTargetInstallable(channelTarget, options);
   if (!options.name || typeof options.name !== 'string' || !options.name.trim()) {
     throw new Error('--name is required for channel add');
   }
+  options.systemKey = deriveChannelInstanceKey(channelTarget, options.name, options.systemKey);
   return target;
 }
 
 /**
  * @param {string} channelTarget
  * @param {Object} options
- * @returns {Promise<Object>}
+ * @returns {Promise<void>}
  */
-async function runAddChannel(channelTarget, options = {}) {
-  const target = assertChannelAddOptions(channelTarget, options);
+async function prepareAddChannelGuards(channelTarget, options) {
+  maybeAssertMcpClientProfile(channelTarget, options);
   if (channelTarget === 'microsoft-copilot' && options.force === true) {
     await assertMicrosoftCopilotOauthReferenceBeforeForce(options);
   }
   await ensureChannelReadyForAdd(channelTarget, options);
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runAddChannel(channelTarget, options = {}) {
+  const target = assertChannelAddOptions(channelTarget, options);
+  await prepareAddChannelGuards(channelTarget, options);
   const { name, baseName, description, ctx, existing } = await prepareChannelContext(
     channelTarget,
     options
   );
-  const skipped = showExistingChannelStatus({
+  const skipped = await showExistingChannelStatus({
     existing,
     options,
     channelTarget,
@@ -414,11 +439,13 @@ async function runAddChannel(channelTarget, options = {}) {
     baseName,
     ctx
   });
-  if (skipped) return skipped;
+  if (shouldReturnSkippedChannel(channelTarget, options, skipped)) {
+    return skipped;
+  }
   if (channelTarget === 'microsoft-copilot') {
     await assertMicrosoftCopilotOauthReference({ options, ctx, name, baseName, description });
   }
-  const { artifact, channelBlock, status } = await buildInstallArtifacts({
+  const built = await buildInstallArtifacts({
     channelTarget,
     options,
     target,
@@ -429,21 +456,32 @@ async function runAddChannel(channelTarget, options = {}) {
     ctx
   });
   if (options.dryRun) {
-    return finishDryRunInstall({ channelTarget, name, baseName, target, artifact, channelBlock });
+    return finishDryRunInstall({ channelTarget, name, baseName, target, options, ...built });
   }
-  return completeLiveInstall({
+  return runLiveChannelInstall({
     ctx,
     channelTarget,
-    channelBlock,
-    status,
-    artifact,
+    options,
     target,
     name,
     baseName,
-    options
+    ...built
   });
 }
 
+/**
+ * @param {Object} params
+ * @returns {Promise<Object>}
+ */
+async function runLiveChannelInstall(params) {
+  await runChannelAddPreflights(params);
+  const slackProvision = await maybeProvisionSlackChannel(params);
+  const teamsBotProvision = await maybeProvisionTeamsBotChannel(params);
+  const result = await completeLiveInstall({ ...params, slackProvision, teamsBotProvision });
+  await runChannelAddContinuations(params);
+  return result;
+}
+
 /**
  * @param {string} channelTarget
  * @param {Object} options

package/lib/channels/approval-guides/chatgpt.js

@@ -1,35 +1,31 @@
 /**
- * ChatGPT enterprise channel admin approval steps (plan 152).
+ * ChatGPT remaining workspace steps (customer-facing).
  *
- * @fileoverview OpenAI Platform / workspace connector guide
+ * @fileoverview Short ChatGPT Apps create/publish steps — no protocol dump
  * @author AI Fabrix Team
- * @version 1.0.0
+ * @version 1.3.0
  */
 
 'use strict';
 
-const { formatCredentialPortalStep } = require('./credential-portal');
+const { CHATGPT_APPS_CREATE_URL } = require('../chatgpt-runtime-contract');
 
 /**
  * @param {Object} ctx
- * @returns {{ portalUrl: string, steps: string[] }}
+ * @returns {{ portalUrl: string, heading: string, credentialPortalUrl: null, steps: string[] }}
  */
 function buildChatGptApprovalGuide(ctx) {
+  const name = ctx.appName || ctx.name || '';
+  const serverUrl = ctx.mcpUrl || '';
   return {
-    portalUrl: 'https://chatgpt.com/',
+    portalUrl: CHATGPT_APPS_CREATE_URL,
+    heading: 'Create the ChatGPT app',
+    credentialPortalUrl: null,
     steps: [
-      'Sign in to the ChatGPT web app as a workspace admin or owner.',
-      'Enable Developer mode for custom MCP apps (Business: Workspace settings → Apps, or Settings → Apps → Advanced settings; Enterprise/Edu: grant Developer mode under Permissions & roles → Connected data first).',
-      'Create a custom MCP app with the Remote MCP URL from INSTALL.md (channel-chatgpt.json is a deployment reference, not a plugin archive).',
-      'Select OAuth (authorization-code + PKCE S256). Do not configure a custom API key for a remote custom MCP app.',
-      'Scan tools, complete OAuth if prompted, review discovered governed tools, then save the app as a draft.',
-      formatCredentialPortalStep(
-        ctx,
-        `${ctx.credentialKey || 'channel'} credential references (not secrets to paste into ChatGPT)`
-      ),
-      'Test representative workflows, then publish the app and configure workspace access and action controls.',
-      `After ChatGPT lists the app as active, re-run: ${ctx.resumeCommand}`,
-      'Optional: use --probe for AI Fabrix-side Runtime checks; ChatGPT Scan tools / OAuth / publication remain workspace-admin responsibilities.'
+      `Open ${CHATGPT_APPS_CREATE_URL}`,
+      `Create the app with Name: ${name}; Server URL: ${serverUrl}; Authentication: OAuth. Add the logo now — ChatGPT does not let you change it after create.`,
+      'If ChatGPT shows a callback URL that is not already registered: aifabrix channel configure chatgpt --callback-url "<callback-url>"',
+      'Publish and connect the app.'
     ]
   };
 }

package/lib/channels/approval-guides/claude.js

@@ -0,0 +1,29 @@
+/**
+ * Claude remaining workspace steps (customer-facing).
+ *
+ * @fileoverview Short Claude connector Name, Server URL, and OAuth steps — no protocol dump
+ */
+
+'use strict';
+
+const { CLAUDE_CONNECTORS_URL } = require('../claude-runtime-contract');
+
+/**
+ * @param {Object} ctx
+ * @returns {{ portalUrl: string, heading: string, credentialPortalUrl: null, steps: string[] }}
+ */
+function buildClaudeApprovalGuide(ctx) {
+  const name = ctx.appName || ctx.name || '';
+  const serverUrl = ctx.mcpUrl || '';
+  return {
+    portalUrl: CLAUDE_CONNECTORS_URL,
+    heading: 'Add the Claude custom connector',
+    credentialPortalUrl: null,
+    steps: [
+      `Open ${CLAUDE_CONNECTORS_URL}`,
+      `Add a custom connector with Name: ${name}; Server URL: ${serverUrl}; Authentication: OAuth.`
+    ]
+  };
+}
+
+module.exports = { buildClaudeApprovalGuide };