@aifabrix/builder 2.52.0 → 2.53.0

package/lib/channels/channel-discovery.js

@@ -0,0 +1,330 @@
+/**
+ * External AI Discovery mapping for channel packaging (plan 167.0).
+ *
+ * @fileoverview Pure discovery → package context; optional Dataplane fetch
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('../api');
+const { RUNTIME_ORCHESTRATION_SYSTEM_KEY } = require('./chatgpt-runtime-contract');
+const { normalizeBaseUrl, joinUrl } = require('./channel-runtime-resolver');
+
+const GATEWAY_TOOLS_CATALOG_MARKER = '/api/v1/mcp/servers/tools';
+
+/**
+ * @param {string} pathOrUrl
+ * @returns {boolean}
+ */
+function isGatewayToolsCatalogUrl(pathOrUrl) {
+  const value = String(pathOrUrl || '');
+  return value.includes(GATEWAY_TOOLS_CATALOG_MARKER);
+}
+
+/**
+ * Normalize discovery paths that include a public `/data` prefix.
+ * @param {string} dataplaneBaseUrl
+ * @param {string|null|undefined} pathOrUrl
+ * @returns {string|null}
+ */
+function resolveDiscoveryUrl(dataplaneBaseUrl, pathOrUrl) {
+  if (!pathOrUrl || typeof pathOrUrl !== 'string') {
+    return null;
+  }
+  const trimmed = pathOrUrl.trim();
+  if (!trimmed) {
+    return null;
+  }
+  if (isGatewayToolsCatalogUrl(trimmed)) {
+    throw new Error(
+      'Gateway tools catalog must not be used as MCP server URL for channel packages'
+    );
+  }
+  if (/^https?:\/\//i.test(trimmed)) {
+    return trimmed;
+  }
+  let relative = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  if (relative.startsWith('/data/api/')) {
+    relative = relative.slice('/data'.length);
+  }
+  return joinUrl(normalizeBaseUrl(dataplaneBaseUrl), relative);
+}
+
+/**
+ * @param {Object} discovery
+ * @param {string} key
+ * @returns {Object|null}
+ */
+function findEntryPoint(discovery, key) {
+  const entries = Array.isArray(discovery?.entryPoints) ? discovery.entryPoints : [];
+  return entries.find((ep) => ep && ep.key === key) || null;
+}
+
+/**
+ * @param {Object} discovery
+ * @returns {string[]}
+ */
+function extractGovernedToolNames(discovery) {
+  const fromRuntime = discovery?.runtimeDiscovery?.governedToolNames;
+  if (Array.isArray(fromRuntime) && fromRuntime.length > 0) {
+    return fromRuntime.map((name) => String(name)).filter(Boolean);
+  }
+  const tools = Array.isArray(discovery?.tools) ? discovery.tools : [];
+  return tools.map((tool) => (tool && tool.name ? String(tool.name) : '')).filter(Boolean);
+}
+
+/**
+ * @param {Object} discovery
+ * @param {Object|null} adapter
+ * @param {string} dataplaneBaseUrl
+ * @returns {{ mcpServerUrl: string|null, installReady: boolean, blocker: string|null }}
+ */
+function resolveMcpConnection(discovery, adapter, dataplaneBaseUrl) {
+  const adapterUrl = adapter?.connection?.mcpServerUrl || null;
+  const remote = findEntryPoint(discovery, 'remoteMcp');
+  const fromEntry =
+    resolveDiscoveryUrl(dataplaneBaseUrl, remote?.absoluteUrl) ||
+    resolveDiscoveryUrl(dataplaneBaseUrl, remote?.path);
+  const mcpServerUrl = resolveDiscoveryUrl(dataplaneBaseUrl, adapterUrl) || fromEntry;
+  if (mcpServerUrl && isGatewayToolsCatalogUrl(mcpServerUrl)) {
+    throw new Error(
+      'Gateway tools catalog must not be used as MCP server URL for channel packages'
+    );
+  }
+  const mcpReady = discovery?.publication?.mcpReady === true;
+  const connectable = adapter ? adapter.connectable === true : mcpReady;
+  const remoteAvailable = discovery?.transport?.remoteMcp?.status === 'available';
+  const installReady = Boolean(mcpReady && connectable && remoteAvailable && mcpServerUrl);
+  const blocker =
+    adapter?.blocker ||
+    (!installReady ? 'remoteMcpUnavailable' : null);
+  return { mcpServerUrl, installReady, blocker };
+}
+
+/**
+ * @param {Object} branding
+ * @param {Object} identity
+ * @param {Object|null} adapter
+ * @returns {string}
+ */
+function resolvePackageDisplayName(branding, identity, adapter) {
+  if (typeof branding.displayName === 'string' && branding.displayName.trim()) {
+    return branding.displayName.trim();
+  }
+  return (
+    identity.displayName ||
+    adapter?.nameForHuman ||
+    adapter?.displayName ||
+    identity.systemKey ||
+    RUNTIME_ORCHESTRATION_SYSTEM_KEY
+  );
+}
+
+/**
+ * @param {Object} branding
+ * @param {Object} identity
+ * @param {Object|null} adapter
+ * @param {Object} discovery
+ * @returns {string}
+ */
+function resolvePackageDescription(branding, identity, adapter, discovery) {
+  if (typeof branding.description === 'string' && branding.description.trim()) {
+    return branding.description.trim();
+  }
+  return (
+    identity.description ||
+    adapter?.descriptionForHuman ||
+    adapter?.description ||
+    discovery.operatingModel?.summary ||
+    ''
+  );
+}
+
+/**
+ * @param {Object|null} auth
+ * @returns {Object|null}
+ */
+function mapAdapterAuthentication(auth) {
+  if (!auth) return null;
+  return {
+    recommendedCapability: auth.recommendedCapability || null,
+    issuer: auth.issuer || null,
+    openidConfigurationUrl: auth.openidConfigurationUrl || null,
+    authorizationServerMetadataUrl: auth.authorizationServerMetadataUrl || null,
+    protectedResourceMetadataUrl: auth.protectedResourceMetadataUrl || null,
+    resource: auth.resource || auth.apiResource || null,
+    audience: auth.audience !== undefined && auth.audience !== null ? auth.audience : null,
+    scopes: Array.isArray(auth.scopes)
+      ? [...auth.scopes]
+      : Array.isArray(auth.allowedScopes)
+        ? [...auth.allowedScopes]
+        : [],
+    operatorNote: auth.operatorNote || null,
+    pkceRequired: auth.pkceRequired === true,
+    clientRegistrationModes: Array.isArray(auth.clientRegistrationModes)
+      ? [...auth.clientRegistrationModes]
+      : []
+  };
+}
+
+/**
+ * @param {Object} branding
+ * @returns {boolean}
+ */
+function isBrandingApplied(branding) {
+  return Boolean(
+    (branding.displayName && String(branding.displayName).trim()) ||
+      (branding.description && String(branding.description).trim())
+  );
+}
+
+/**
+ * Map discovery (+ optional adapter) into packaging fields.
+ *
+ * @param {Object} params
+ * @param {Object} params.discovery
+ * @param {Object} [params.adapter]
+ * @param {string} params.dataplaneBaseUrl
+ * @param {Object} [params.branding]
+ * @returns {Object}
+ */
+function mapDiscoveryToPackageContext(params) {
+  const discovery = params.discovery;
+  if (!discovery || typeof discovery !== 'object') {
+    throw new Error('discovery document is required');
+  }
+  const identity = discovery.identity || {};
+  const branding = params.branding && typeof params.branding === 'object' ? params.branding : {};
+  const adapter = params.adapter || null;
+  const connection = resolveMcpConnection(discovery, adapter, params.dataplaneBaseUrl);
+  const authCaps = Array.isArray(discovery.authenticationCapabilities)
+    ? discovery.authenticationCapabilities.map((c) => c.capability || c).filter(Boolean)
+    : [];
+  return {
+    systemKey: identity.systemKey || RUNTIME_ORCHESTRATION_SYSTEM_KEY,
+    displayName: resolvePackageDisplayName(branding, identity, adapter),
+    description: resolvePackageDescription(branding, identity, adapter, discovery),
+    governedToolNames: extractGovernedToolNames(discovery),
+    mcpServerUrl: connection.mcpServerUrl,
+    installReady: connection.installReady,
+    blocker: connection.blocker,
+    authentication: mapAdapterAuthentication(adapter?.authentication || null),
+    authenticationCapabilities: authCaps,
+    publication: {
+      mcpReady: discovery.publication?.mcpReady === true,
+      environment: discovery.publication?.environment || null
+    },
+    brandingApplied: isBrandingApplied(branding)
+  };
+}
+
+/**
+ * @param {Object} response
+ * @returns {Object}
+ */
+function unwrapApiData(response) {
+  if (response && typeof response === 'object' && response.data && typeof response.data === 'object') {
+    if (response.data.kind || response.data.identity || response.data.adapter) {
+      return response.data;
+    }
+  }
+  return response;
+}
+
+/**
+ * @param {string} dataplaneBaseUrl
+ * @param {Object} authConfig
+ * @param {string} [systemKey]
+ * @returns {Promise<Object>}
+ */
+async function fetchExternalAiDiscovery(
+  dataplaneBaseUrl,
+  authConfig,
+  systemKey = RUNTIME_ORCHESTRATION_SYSTEM_KEY
+) {
+  const client = new ApiClient(normalizeBaseUrl(dataplaneBaseUrl), authConfig || {});
+  const response = await client.get(`/api/v1/external/systems/${systemKey}/discovery`);
+  const discovery = unwrapApiData(response);
+  if (!discovery || !discovery.kind) {
+    throw new Error(`Discovery document missing for systemKey=${systemKey}`);
+  }
+  return discovery;
+}
+
+/**
+ * @param {string} dataplaneBaseUrl
+ * @param {Object} authConfig
+ * @param {string} adapterKey microsoft-plugin | chatgpt-setup
+ * @param {string} [systemKey]
+ * @returns {Promise<Object>}
+ */
+async function fetchExternalAiDiscoveryAdapter(
+  dataplaneBaseUrl,
+  authConfig,
+  adapterKey,
+  systemKey = RUNTIME_ORCHESTRATION_SYSTEM_KEY
+) {
+  const client = new ApiClient(normalizeBaseUrl(dataplaneBaseUrl), authConfig || {});
+  const response = await client.get(
+    `/api/v1/external/systems/${systemKey}/discovery/adapters/${adapterKey}`
+  );
+  return unwrapApiData(response);
+}
+
+/**
+ * @param {string} channelTarget
+ * @returns {string|null}
+ */
+function adapterKeyForChannel(channelTarget) {
+  if (channelTarget === 'microsoft-copilot') return 'microsoft-plugin';
+  if (channelTarget === 'chatgpt') return 'chatgpt-setup';
+  return null;
+}
+
+/**
+ * Fetch discovery (+ adapter when known) and map package context.
+ *
+ * @param {Object} params
+ * @returns {Promise<Object>}
+ */
+async function loadChannelPackageContext(params) {
+  const systemKey = params.runtimeSystemKey || RUNTIME_ORCHESTRATION_SYSTEM_KEY;
+  const discovery = await fetchExternalAiDiscovery(
+    params.dataplaneBaseUrl,
+    params.authConfig,
+    systemKey
+  );
+  const adapterKey = adapterKeyForChannel(params.channelTarget);
+  let adapter = null;
+  if (adapterKey) {
+    try {
+      adapter = await fetchExternalAiDiscoveryAdapter(
+        params.dataplaneBaseUrl,
+        params.authConfig,
+        adapterKey,
+        systemKey
+      );
+    } catch {
+      adapter = null;
+    }
+  }
+  return mapDiscoveryToPackageContext({
+    discovery,
+    adapter,
+    dataplaneBaseUrl: params.dataplaneBaseUrl,
+    branding: params.branding
+  });
+}
+
+module.exports = {
+  GATEWAY_TOOLS_CATALOG_MARKER,
+  isGatewayToolsCatalogUrl,
+  resolveDiscoveryUrl,
+  mapDiscoveryToPackageContext,
+  fetchExternalAiDiscovery,
+  fetchExternalAiDiscoveryAdapter,
+  adapterKeyForChannel,
+  loadChannelPackageContext
+};

package/lib/channels/channel-external-system.js

@@ -72,7 +72,7 @@ async function fetchCommunicationSystem(ctx) {
   if (!system || typeof system !== 'object') {
     throw new Error(
       `Communication external system "${ctx.channelTarget}" was not found. ` +
-        `Run: aifabrix deploy ${ctx.channelTarget}`
+        `Run: aifabrix channel add ${ctx.channelTarget} --name "…" --force`
     );
   }
   const kind = system.systemKind || system.systemKindKey;

package/lib/channels/channel-runtime-resolver.js

@@ -19,6 +19,12 @@ const {
   COPILOT_RUNTIME_TRANSPORT,
   COPILOT_RUNTIME_AUTH_MODE
 } = require('./chatgpt-runtime-contract');
+const { applyMicrosoftCopilotDisplayLimits } = require('./microsoft-copilot-limits');
+const {
+  resolveCopilotEntraScopes,
+  evaluateCopilotEntraSsoReadiness
+} = require('./microsoft-copilot-entra-sso');
+const { applyCopilotEntraSsoFormFields } = require('./microsoft-copilot-entra-sso-form');
 
 /** Default Slack slash prefix — matches dataplane `templates/slack/command_catalog.yaml`. */
 const DEFAULT_SLACK_COMMAND_PREFIX = 'af';
@@ -152,15 +158,62 @@ function buildDeterministicGuid(seed) {
  * @param {Object} resolved
  * @param {Object} params
  */
-function applyMicrosoftCopilotRuntimeValues(resolved, params) {
+/**
+ * Apply discovery-driven package context (plan 167.0).
+ * @param {Object} resolved
+ * @param {Object} [packageContext]
+ */
+function applyDiscoveryPackageContext(resolved, packageContext) {
+  if (!packageContext || typeof packageContext !== 'object') {
+    resolved.installReady = false;
+    resolved.discoveryBlocker = resolved.discoveryBlocker || 'discoveryUnavailable';
+    return;
+  }
+  if (Array.isArray(packageContext.governedToolNames) && packageContext.governedToolNames.length > 0) {
+    resolved.layerBToolNames = [...packageContext.governedToolNames];
+  }
+  if (packageContext.mcpServerUrl) {
+    resolved.mcpUrl = packageContext.mcpServerUrl;
+  }
+  if (packageContext.displayName && !resolved.brandingNameOverride) {
+    // Keep CLI --name as appName; discovery fills defaults only when requested upstream.
+  }
+  if (packageContext.description && !resolved.appDescription) {
+    resolved.appDescription = packageContext.description;
+  }
+  resolved.installReady = packageContext.installReady === true;
+  resolved.discoveryBlocker = packageContext.blocker || null;
+  resolved.discoveryAuthentication = packageContext.authentication || null;
+  resolved.discoveryAuthenticationCapabilities = packageContext.authenticationCapabilities || [];
+}
+
+/**
+ * @param {Object} resolved
+ * @returns {void}
+ */
+function applyCopilotRuntimeDomain(resolved) {
+  resolved.runtimeDomain = '';
+  try {
+    resolved.runtimeDomain = new URL(resolved.mcpUrl).hostname;
+  } catch {
+    try {
+      resolved.runtimeDomain = new URL(resolved.dataplaneBaseUrl).hostname;
+    } catch {
+      resolved.runtimeDomain = '';
+    }
+  }
+}
+
+/**
+ * @param {Object} resolved
+ * @param {Object} params
+ * @returns {void}
+ */
+function applyCopilotPackageIdentity(resolved, params) {
   resolved.runtimeSystemKey = COPILOT_RUNTIME_SYSTEM_KEY;
   resolved.runtimeTransport = COPILOT_RUNTIME_TRANSPORT;
   resolved.runtimeAuthMode = COPILOT_RUNTIME_AUTH_MODE;
   resolved.layerBToolNames = Array.isArray(params.layerBToolNames) ? [...params.layerBToolNames] : [];
-  resolved.scopes = Array.isArray(params.scopes)
-    ? [...params.scopes]
-    : ['openid', 'profile', 'offline_access'];
-  resolved.scopesJson = JSON.stringify(resolved.scopes);
   resolved.packageVersion = typeof params.packageVersion === 'string' ? params.packageVersion : '1.0.0';
   resolved.packageAppId = buildDeterministicGuid(
     `${resolved.channelTarget}:${resolved.baseName}:${resolved.environment}:app`
@@ -168,16 +221,49 @@ function applyMicrosoftCopilotRuntimeValues(resolved, params) {
   resolved.pluginId = buildDeterministicGuid(
     `${resolved.channelTarget}:${resolved.baseName}:${resolved.environment}:plugin`
   );
-  resolved.runtimeDomain = '';
-  try {
-    resolved.runtimeDomain = new URL(resolved.mcpUrl).hostname;
-  } catch {
-    try {
-      resolved.runtimeDomain = new URL(resolved.dataplaneBaseUrl).hostname;
-    } catch {
-      resolved.runtimeDomain = '';
-    }
+  const referenceId =
+    typeof params.oauthPluginVaultReferenceId === 'string' &&
+    params.oauthPluginVaultReferenceId.trim()
+      ? params.oauthPluginVaultReferenceId.trim()
+      : '';
+  resolved.oauthPluginVaultReferenceId = referenceId || null;
+}
+
+/**
+ * @param {Object} resolved
+ * @param {Object} params
+ * @returns {void}
+ */
+function applyMicrosoftCopilotRuntimeValues(resolved, params) {
+  applyCopilotPackageIdentity(resolved, params);
+  applyDiscoveryPackageContext(resolved, params.packageContext);
+  resolved.scopes = resolveCopilotEntraScopes({
+    explicitScopes: params.scopes,
+    packageContext: params.packageContext,
+    entraProvider: params.entraProvider
+  });
+  resolved.scopesJson = JSON.stringify(resolved.scopes);
+  const readiness = evaluateCopilotEntraSsoReadiness({
+    packageContext: params.packageContext,
+    oauthPluginVaultReferenceId: resolved.oauthPluginVaultReferenceId,
+    scopes: resolved.scopes,
+    entraProvider: params.entraProvider || null,
+    mcpServerUrl: resolved.mcpUrl || null
+  });
+  resolved.installReady = readiness.installReady;
+  resolved.discoveryBlocker = readiness.blocker;
+  resolved.packageReady = readiness.packageReady;
+  resolved.packageBlocker = readiness.packageBlocker;
+  resolved.microsoftPublicationPending = readiness.microsoftPublicationPending !== false;
+  resolved.discoveryAuthentication = readiness.packageAuthentication;
+  if (params.entraProvider?.issuer) {
+    resolved.entraIssuer = params.entraProvider.issuer;
   }
+  if (params.iconColorPath) resolved.iconColorPath = params.iconColorPath;
+  if (params.iconOutlinePath) resolved.iconOutlinePath = params.iconOutlinePath;
+  applyCopilotRuntimeDomain(resolved);
+  applyCopilotEntraSsoFormFields(resolved, params);
+  applyMicrosoftCopilotDisplayLimits(resolved);
 }
 
 /**
@@ -254,6 +340,7 @@ function resolveChannelRuntimeValues(params) {
 
   if (params.channelTarget === 'slack') {
     applySlackRuntimeValues(resolved, params);
+    applyDiscoveryPackageContext(resolved, params.packageContext);
   }
 
   if (params.channelTarget === 'microsoft-copilot') {
@@ -262,6 +349,11 @@ function resolveChannelRuntimeValues(params) {
 
   if (params.channelTarget === 'chatgpt') {
     applyChatGptRuntimeValues(resolved, params);
+    applyDiscoveryPackageContext(resolved, params.packageContext);
+  }
+
+  if (params.channelTarget === 'teams-bot') {
+    applyDiscoveryPackageContext(resolved, params.packageContext);
   }
 
   return resolved;
@@ -277,6 +369,7 @@ module.exports = {
   applySlackRuntimeValues,
   applyMicrosoftCopilotRuntimeValues,
   applyChatGptRuntimeValues,
+  applyDiscoveryPackageContext,
   resolveSlackOAuthManifestFields,
   resolveChannelRuntimeValues,
   DEFAULT_SLACK_COMMAND_PREFIX

package/lib/channels/channel-status-display.js

@@ -55,10 +55,10 @@ function displayApprovalGuideSection(approvalGuide) {
   const heading =
     approvalGuide.approvalRequired === false
       ? 'Go-live steps'
-      : 'Platform admin approval required';
+      : 'Organisation publish / Teams admin approval required';
   logger.log(formatWarningLine(heading));
   if (approvalGuide.portalUrl) {
-    logger.log(metadata('Admin console:'));
+    logger.log(metadata('Developer Portal:'));
     logger.log(chalk.cyan(approvalGuide.portalUrl));
   }
   logger.log('');
@@ -125,7 +125,40 @@ function displayChannelCoreFields(result) {
     logger.log(metadata(`Artifact: ${result.artifactPath}`));
   }
   if (result.installGuidePath) {
-    logger.log(metadata(`Install guide: ${result.installGuidePath}`));
+    logger.log(metadata(`Install guide (README): ${result.installGuidePath}`));
+  }
+  if (result.zipPath) {
+    logger.log(metadata(`Package ZIP: ${result.zipPath}`));
+  }
+  displayReadinessLines(result);
+}
+
+/**
+ * Split package/Runtime readiness from Microsoft organisation publication.
+ * @param {Object} result
+ */
+function displayReadinessLines(result) {
+  const packageReady =
+    result.packageReady === true ||
+    (result.packageReady === undefined && result.installReady === true);
+  const packageBlocker = result.packageBlocker || result.blocker || null;
+  if (packageReady) {
+    logger.log(metadata('Package / Runtime ready: yes'));
+  } else if (packageBlocker) {
+    logger.log(metadata(`Package / Runtime ready: no (${packageBlocker})`));
+  } else if (result.installReady === false) {
+    logger.log(metadata('Package / Runtime ready: no'));
+  }
+  if (result.microsoftPublicationPending === true) {
+    logger.log(
+      metadata(
+        'Microsoft publication: pending (Developer Portal import → Publish to your org → Teams admin approval)'
+      )
+    );
+  } else if (result.microsoftPublicationPending === false) {
+    logger.log(metadata('Microsoft publication: cleared'));
+  } else if (result.installReady === false && result.blocker && !packageBlocker) {
+    logger.log(metadata(`Install ready: no (${result.blocker})`));
   }
 }
 

package/lib/channels/microsoft-copilot-channel-add.js

@@ -0,0 +1,138 @@
+/**
+ * microsoft-copilot channel-add helpers (Entra SSO form context for operator errors).
+ *
+ * @fileoverview Keep add-channel.js under size limits
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { resolveChannelAuthContext } = require('./channel-auth-context');
+const {
+  normalizeBaseChannelName,
+  resolveChannelDisplayName
+} = require('./channel-display-name');
+const { getDefaultChannelDescription } = require('./channel-targets');
+const { resolveAppDescription } = require('./channel-description');
+const { loadChannelPackageContext } = require('./channel-discovery');
+const { getInboundMicrosoftEntraIdProvider } = require('../api/token-providers.api');
+const { getKeycloakEntraIdentityProvider } = require('../api/keycloak.api');
+const { resolveChannelRuntimeValues } = require('./channel-runtime-resolver');
+const { assertOauthPluginVaultReferenceId } = require('./microsoft-copilot-entra-sso');
+
+/**
+ * @param {Object} options
+ * @returns {boolean}
+ */
+function hasOauthPluginVaultReference(options) {
+  return (
+    typeof options.oauthPluginVaultReferenceId === 'string' &&
+    Boolean(options.oauthPluginVaultReferenceId.trim())
+  );
+}
+
+/**
+ * Load Trust source + Keycloak Entra IdP for Copilot packaging (null on miss/error).
+ * @param {Object} ctx
+ * @returns {Promise<{ entraProvider: Object|null, entraIdentityProvider: Object|null }>}
+ */
+async function loadMicrosoftCopilotEntraContext(ctx) {
+  let entraProvider = null;
+  let entraIdentityProvider = null;
+  if (!ctx?.controllerUrl) {
+    return { entraProvider, entraIdentityProvider };
+  }
+  try {
+    entraProvider = await getInboundMicrosoftEntraIdProvider(ctx.controllerUrl, ctx.authConfig);
+  } catch {
+    entraProvider = null;
+  }
+  try {
+    entraIdentityProvider = await getKeycloakEntraIdentityProvider(
+      ctx.controllerUrl,
+      ctx.authConfig
+    );
+  } catch {
+    entraIdentityProvider = null;
+  }
+  return { entraProvider, entraIdentityProvider };
+}
+
+/**
+ * @param {Object} params
+ * @returns {Promise<Object>}
+ */
+async function resolveCopilotFormContextForError(params) {
+  const { options, ctx, name, baseName, description } = params;
+  let packageContext = null;
+  try {
+    packageContext = await loadChannelPackageContext({
+      dataplaneBaseUrl: ctx.dataplaneUrl,
+      authConfig: ctx.authConfig,
+      channelTarget: 'microsoft-copilot',
+      branding: { displayName: name, description }
+    });
+  } catch {
+    packageContext = null;
+  }
+  const { entraProvider, entraIdentityProvider } = await loadMicrosoftCopilotEntraContext(ctx);
+  return resolveChannelRuntimeValues({
+    dataplaneBaseUrl: ctx.dataplaneUrl,
+    channelTarget: 'microsoft-copilot',
+    appName: name,
+    baseName,
+    environment: ctx.environment,
+    appDescription: description,
+    packageContext,
+    entraProvider,
+    entraIdentityProvider,
+    oauthPluginVaultReferenceId: options.oauthPluginVaultReferenceId
+  });
+}
+
+/**
+ * @param {Object} params
+ * @throws {Error}
+ */
+async function assertMicrosoftCopilotOauthReference(params) {
+  const { options } = params;
+  if (hasOauthPluginVaultReference(options)) {
+    return;
+  }
+  const formContext = await resolveCopilotFormContextForError(params);
+  assertOauthPluginVaultReferenceId({ ...options, formContext });
+}
+
+/**
+ * Fail before force upload when Teams Entra SSO auth-config id is missing.
+ * @param {Object} options
+ * @throws {Error}
+ */
+async function assertMicrosoftCopilotOauthReferenceBeforeForce(options) {
+  if (hasOauthPluginVaultReference(options)) {
+    return;
+  }
+  const ctx = await resolveChannelAuthContext('microsoft-copilot', { silent: options.quiet });
+  const baseName = normalizeBaseChannelName(options.name);
+  const name = resolveChannelDisplayName(baseName, ctx.environment);
+  const rawDescription =
+    options.description && String(options.description).trim()
+      ? String(options.description).trim()
+      : getDefaultChannelDescription();
+  await assertMicrosoftCopilotOauthReference({
+    options,
+    ctx,
+    name,
+    baseName,
+    description: resolveAppDescription('microsoft-copilot', rawDescription)
+  });
+}
+
+module.exports = {
+  hasOauthPluginVaultReference,
+  loadMicrosoftCopilotEntraContext,
+  resolveCopilotFormContextForError,
+  assertMicrosoftCopilotOauthReference,
+  assertMicrosoftCopilotOauthReferenceBeforeForce
+};