@aifabrix/builder 2.53.1 → 2.55.0

package/lib/programmatic/run-channel-install-teams-bot.js

@@ -0,0 +1,204 @@
+/**
+ * Teams Bot portal install: Microsoft login when Azure-managed provision is skipped.
+ *
+ * @fileoverview Refresh/continue must start sign-in, not reprint Ready
+ */
+
+'use strict';
+
+const { toChannelInstallEnvelope } = require('../channels/channel-install-envelope');
+const {
+  startPortalMicrosoftLogin,
+  isLoopbackAuthorizeUrl
+} = require('../channels/microsoft-provisioning');
+const { resolveChannelRuntimeValues } = require('../channels/channel-runtime-resolver');
+const { vendorFacingUrlsFromCtx } = require('../channels/vendor-dataplane-url');
+const { persistHelpPayload, remainingCtxFromResult, envelopeFromInstall } = require('./run-channel-install-copilot');
+const { httpError } = require('./channel-install-session');
+
+/**
+ * @param {string} definitionKey
+ * @param {Object|null} result
+ * @returns {boolean}
+ */
+function teamsBotInstallStillWaiting(definitionKey, result) {
+  if (definitionKey !== 'teams-bot') {
+    return false;
+  }
+  const bot = result && result.teamsBotProvision;
+  if (bot && bot.connected === true) {
+    return false;
+  }
+  return Boolean(bot && bot.skipped === true);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} addOptions
+ * @param {string} definitionKey
+ * @returns {Object}
+ */
+function teamsBotWaitingRuntimeValues(ctx, addOptions, definitionKey) {
+  const vendor = vendorFacingUrlsFromCtx(ctx);
+  return resolveChannelRuntimeValues({
+    dataplaneBaseUrl: vendor.dataplaneBaseUrl,
+    controllerUrl: vendor.controllerUrl,
+    channelTarget: definitionKey,
+    appName: addOptions.name,
+    instanceSystemKey: addOptions.systemKey || ctx.instanceSystemKey || ctx.systemKey,
+    environment: ctx.environment,
+    appDescription: typeof addOptions.description === 'string' ? addOptions.description : ''
+  });
+}
+
+/**
+ * @param {Object} runtimeValues
+ * @param {Object|null} login
+ * @returns {Object}
+ */
+function applyPortalMicrosoftLogin(runtimeValues, login) {
+  const loginUrl = login && login.loginUrl ? String(login.loginUrl).trim() : '';
+  if (loginUrl && !isLoopbackAuthorizeUrl(loginUrl)) {
+    runtimeValues.microsoftLoginUrl = loginUrl;
+  }
+  if (login && login.userCode) {
+    runtimeValues.microsoftLoginUserCode = login.userCode;
+  }
+  return runtimeValues;
+}
+
+/**
+ * @param {Object|null} login
+ * @returns {Error}
+ */
+function teamsBotWaitingWithoutSignInError() {
+  return httpError(
+    'Could not start Microsoft sign-in. Use Get a new code, complete sign-in, then click Continue.',
+    409
+  );
+}
+
+/**
+ * @param {Object} addOptions
+ * @param {Object} runtimeValues
+ * @returns {Object}
+ */
+function skippedTeamsBotResult(addOptions, runtimeValues, provision) {
+  const remaining = provision && Array.isArray(provision.remaining) ? provision.remaining : [];
+  return {
+    runtimeValues: { ...runtimeValues, appName: runtimeValues.appName || addOptions.name },
+    teamsBotProvision: {
+      skipped: true,
+      connected: false,
+      ...(remaining.length > 0 ? { remaining } : {})
+    }
+  };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} addOptions
+ * @param {string} definitionKey
+ * @param {Object} runtimeValues
+ * @param {Object|null} login
+ * @returns {Object}
+ */
+function persistWaitingTeamsBotEnvelope(ctx, addOptions, definitionKey, runtimeValues, login, provision) {
+  applyPortalMicrosoftLogin(runtimeValues, login);
+  const loginUrl =
+    typeof runtimeValues.microsoftLoginUrl === 'string' ? runtimeValues.microsoftLoginUrl.trim() : '';
+  if (!loginUrl && !(login && (login.authenticated === true || login.waiting === true))) {
+    throw teamsBotWaitingWithoutSignInError();
+  }
+  const result = skippedTeamsBotResult(addOptions, runtimeValues, provision);
+  const envelope = toChannelInstallEnvelope({
+    channelTarget: definitionKey,
+    displayName: addOptions.name,
+    ctx: remainingCtxFromResult(ctx, result, addOptions),
+    runtimeValues: result.runtimeValues,
+    verdicts: {
+      runtime: { ok: true, label: 'Deployed' },
+      oauth: { ok: false, label: 'Not connected' },
+      vendorSession: { ok: false, label: 'Sign in required' }
+    }
+  });
+  return persistHelpPayload(ctx, addOptions, envelope, definitionKey, result);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} addOptions
+ * @param {string} definitionKey
+ * @param {Object} deps
+ * @param {Object|null} login
+ * @returns {Promise<Object|null>}
+ */
+async function retryTeamsBotIfAuthenticated(ctx, addOptions, definitionKey, deps, login) {
+  if (!login || login.authenticated !== true || addOptions.teamsBotProvisionRetry === true) {
+    return null;
+  }
+  if (typeof deps.executeAddChannel !== 'function') {
+    return null;
+  }
+  const result = await deps.executeAddChannel(
+    ctx,
+    { ...addOptions, teamsBotProvisionRetry: true },
+    deps,
+    definitionKey
+  );
+  if (!teamsBotInstallStillWaiting(definitionKey, result)) {
+    const envelope = envelopeFromInstall(ctx, addOptions, result, definitionKey);
+    return persistHelpPayload(ctx, addOptions, envelope, definitionKey, result);
+  }
+  const runtimeValues = teamsBotWaitingRuntimeValues(ctx, addOptions, definitionKey);
+  return persistWaitingTeamsBotEnvelope(
+    ctx,
+    addOptions,
+    definitionKey,
+    runtimeValues,
+    login,
+    result.teamsBotProvision
+  );
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} addOptions
+ * @param {string} definitionKey
+ * @param {Object} [deps]
+ * @returns {Promise<Object>}
+ */
+async function persistWaitingTeamsBotInstall(ctx, addOptions, definitionKey, deps = {}) {
+  const runtimeValues = teamsBotWaitingRuntimeValues(ctx, addOptions, definitionKey);
+  let login = { waiting: true };
+  try {
+    login = await startPortalMicrosoftLogin({
+      installationKey: addOptions.systemKey || ctx.instanceSystemKey || ctx.systemKey,
+      expectedTenantId: runtimeValues.entraTenantId,
+      retryLogin: addOptions.retryLogin === true,
+      loginCli: 'teams',
+      deps: (deps && deps.microsoftProvisioningDeps) || {}
+    });
+  } catch (err) {
+    if (err && (err.statusCode || err.code === 'WRONG_TENANT' || err.code === 'TOOLKIT')) {
+      throw err;
+    }
+    throw httpError((err && err.message) || 'Could not start Microsoft sign-in.', 409);
+  }
+  const captured = await retryTeamsBotIfAuthenticated(
+    ctx,
+    addOptions,
+    definitionKey,
+    deps,
+    login
+  );
+  if (captured) {
+    return captured;
+  }
+  return persistWaitingTeamsBotEnvelope(ctx, addOptions, definitionKey, runtimeValues, login);
+}
+
+module.exports = {
+  teamsBotInstallStillWaiting,
+  persistWaitingTeamsBotInstall
+};

package/lib/programmatic/run-channel-install.js

@@ -0,0 +1,346 @@
+/**
+ * Builder-api generic channel install (help markdown + machine envelope).
+ *
+ * @fileoverview Wraps add-channel; default HTTP is helpMarkdown + phase + userActions
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { runAddChannel } = require('../channels/add-channel');
+const registry = require('../channels/channel-definition-registry');
+const { assertChannelInstanceAvailable, adoptExistingInstanceAsContinue } = require('../channels/channel-instance-collision');
+const { assertChannelCardinality } = require('../channels/channel-cardinality');
+const { assertIntegrationClientPermissions } = require('../channels/channel-oauth-preflight');
+const {
+  formatChannelCliInstructions,
+  isCliProvisioningMode
+} = require('../channels/channel-cli-instructions');
+const { runWithWorkspaceContext } = require('./workspace-context');
+const { createHttpRawResult } = require('./http-raw-response');
+const {
+  requireChannelInstallSession,
+  httpError
+} = require('./channel-install-session');
+const {
+  resolveChannelInstallHelp,
+  resolveInstallDefinitionKey
+} = require('./channel-install-help-resolve');
+const {
+  assertChannelInstallTarget,
+  toChannelAddOptionsFromBody,
+  isRetryLoginFlag
+} = require('./run-channel-install-options');
+const { listChannelTargets } = require('./run-channel-catalog');
+const {
+  peekPortalMicrosoftLogin,
+  awaitPortalMicrosoftLogin
+} = require('../channels/microsoft-provisioning');
+const {
+  isCopilotEntraWaitingError,
+  copilotInstallStillWaiting,
+  persistWaitingCopilotInstall,
+  envelopeFromInstall,
+  persistHelpPayload
+} = require('./run-channel-install-copilot');
+const {
+  persistWaitingTeamsBotInstall,
+  teamsBotInstallStillWaiting
+} = require('./run-channel-install-teams-bot');
+
+const DEFAULT_DEPS = { runAddChannel };
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {Object}
+ */
+function authContextFromWorkspace(ctx) {
+  return {
+    controllerUrl: ctx.controllerUrl,
+    environment: ctx.environment,
+    dataplaneUrl: ctx.dataplaneUrl,
+    authConfig: { type: 'bearer', token: ctx.bearerToken, preserveBearer: true }
+  };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} addOptions
+ * @param {Object} [deps]
+ * @returns {Promise<Object>}
+ */
+function rethrowAsChannelInstallHttpError(err) {
+  if (err && err.statusCode) {
+    throw err;
+  }
+  const status = Number(err && err.status);
+  if (status >= 400 && status < 600) {
+    throw httpError(err.message, status);
+  }
+  const message = err && err.message ? String(err.message) : '';
+  if (/validation failed|does not match expected system key/i.test(message)) {
+    throw httpError(message, 400);
+  }
+  if (/oauth-plugin-vault-reference-id|OAuthPluginVault/i.test(message)) {
+    throw httpError(
+      'Copilot app package is not ready until Teams Entra SSO registration is stored on this install.',
+      409
+    );
+  }
+  throw err;
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} addOptions
+ * @param {Object} [deps]
+ * @param {string} definitionKey
+ * @returns {Promise<Object>}
+ */
+async function executeAddChannel(ctx, addOptions, deps = DEFAULT_DEPS, definitionKey) {
+  const runAdd = deps.runAddChannel || runAddChannel;
+  const options = {
+    ...addOptions,
+    quiet: true,
+    projectRoot: ctx.getUserRoot(),
+    authContext: authContextFromWorkspace(ctx)
+  };
+  const channelTarget = definitionKey || ctx.systemKey;
+  try {
+    return await runWithWorkspaceContext(ctx, () => runAdd(channelTarget, options));
+  } catch (err) {
+    if (err && err.boundary === 'permissions') {
+      throw httpError(err.message, 403);
+    }
+    rethrowAsChannelInstallHttpError(err);
+  }
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ * @param {Object} [deps]
+ * @returns {Promise<Object>}
+ */
+async function runChannelInstall(ctx, body, deps = DEFAULT_DEPS) {
+  const definitionKey = resolveInstallDefinitionKey(ctx);
+  if (definitionKey !== ctx.systemKey && !ctx.instanceSystemKey) {
+    ctx.instanceSystemKey = ctx.systemKey;
+  }
+  assertChannelInstallTarget(definitionKey, body || {});
+  const definition = registry.getChannelDefinition(definitionKey);
+  if (definition && isCliProvisioningMode(definition)) {
+    const name = (body && body.name) || 'Finance';
+    throw httpError(formatChannelCliInstructions(definition, { name }), 409);
+  }
+  const addOptions = toChannelAddOptionsFromBody(body || {}, definition);
+  if (addOptions.systemKey) {
+    ctx.instanceSystemKey = addOptions.systemKey;
+  }
+  await assertIntegrationClientPermissions(ctx, definitionKey, deps);
+  await adoptExistingInstanceAsContinue(ctx, addOptions, body, deps);
+  await assertChannelCardinality(ctx, definitionKey, {
+    continueInstall: addOptions.continueInstall === true,
+    force: body && body.force === true,
+    deps
+  });
+  await assertChannelInstanceAvailable(ctx, addOptions.systemKey, {
+    getExternalSystem: deps.getExternalSystem,
+    continueInstall: addOptions.continueInstall === true,
+    force: body && body.force === true
+  });
+  return addChannelOrCopilotWaiting(ctx, addOptions, deps, definitionKey);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} addOptions
+ * @param {Object} deps
+ * @param {string} definitionKey
+ * @returns {Promise<Object>}
+ */
+function persistCopilotWaiting(ctx, addOptions, definitionKey, deps) {
+  return persistWaitingCopilotInstall(ctx, addOptions, definitionKey, {
+    ...deps,
+    executeAddChannel
+  });
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} addOptions
+ * @param {Object} deps
+ * @param {string} definitionKey
+ * @returns {Promise<Object>}
+ */
+async function addChannelOrCopilotWaiting(ctx, addOptions, deps, definitionKey) {
+  if (definitionKey === 'microsoft-copilot' && addOptions.retryLogin === true) {
+    return persistCopilotWaiting(ctx, addOptions, definitionKey, deps);
+  }
+  if (definitionKey === 'teams-bot' && addOptions.retryLogin === true) {
+    return persistWaitingTeamsBotInstall(ctx, addOptions, definitionKey, {
+      ...deps,
+      executeAddChannel
+    });
+  }
+  try {
+    const result = await executeAddChannel(ctx, addOptions, deps, definitionKey);
+    if (copilotInstallStillWaiting(definitionKey, result)) {
+      return persistCopilotWaiting(ctx, addOptions, definitionKey, deps);
+    }
+    if (teamsBotInstallStillWaiting(definitionKey, result)) {
+      return persistWaitingTeamsBotInstall(ctx, addOptions, definitionKey, {
+        ...deps,
+        executeAddChannel
+      });
+    }
+    const envelope = envelopeFromInstall(ctx, addOptions, result, definitionKey);
+    return persistHelpPayload(ctx, addOptions, envelope, definitionKey, result);
+  } catch (err) {
+    if (definitionKey === 'microsoft-copilot' && isCopilotEntraWaitingError(err)) {
+      return persistCopilotWaiting(ctx, addOptions, definitionKey, deps);
+    }
+    throw err;
+  }
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [query]
+ * @returns {Object}
+ */
+function getChannelInstall(ctx, query = {}) {
+  return resolveChannelInstallHelp(ctx, query);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {Object}
+ */
+function getChannelInstallHelp(ctx) {
+  const payload = resolveChannelInstallHelp(ctx);
+  return createHttpRawResult({
+    contentType: 'text/markdown; charset=utf-8',
+    body: payload.helpMarkdown,
+    fileName: 'help.md'
+  });
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [deps]
+ * @returns {Promise<Object>}
+ */
+function continueInstallArgs(bodyOrDeps, deps) {
+  if (bodyOrDeps && typeof bodyOrDeps.runAddChannel === 'function') {
+    return { body: {}, deps: bodyOrDeps };
+  }
+  return { body: bodyOrDeps || {}, deps: deps || DEFAULT_DEPS };
+}
+
+/**
+ * @param {Object} session
+ * @param {Object} body
+ * @returns {string}
+ */
+function continueVaultReferenceId(session, body) {
+  const fromBody =
+    typeof body.oauthPluginVaultReferenceId === 'string' ? body.oauthPluginVaultReferenceId.trim() : '';
+  if (fromBody) {
+    return fromBody;
+  }
+  return typeof session.oauthPluginVaultReferenceId === 'string'
+    ? session.oauthPluginVaultReferenceId.trim()
+    : '';
+}
+
+/**
+ * Slash prefix is chosen on first POST; continue must not fall back to `af`.
+ * @param {Object} session
+ * @param {Object} body
+ * @returns {Object}
+ */
+function continueCommandPrefix(session, body) {
+  const fromBody =
+    typeof body.commandPrefix === 'string' ? body.commandPrefix.trim() : '';
+  const configuration = body.configuration && typeof body.configuration === 'object'
+    ? body.configuration
+    : {};
+  const fromConfig =
+    typeof configuration.commandPrefix === 'string' ? configuration.commandPrefix.trim() : '';
+  const fromSession =
+    typeof session.commandPrefix === 'string' ? session.commandPrefix.trim() : '';
+  const commandPrefix = fromBody || fromConfig || fromSession;
+  return commandPrefix ? { commandPrefix } : {};
+}
+
+/**
+ * Device-code wait is Copilot and Teams Bot. Slack continue must not sit on that timer.
+ * @param {Object} session
+ * @param {boolean} retryLogin
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {boolean}
+ */
+function shouldAwaitPortalMicrosoftLogin(session, retryLogin, ctx) {
+  if (retryLogin || !session.installationKey) {
+    return false;
+  }
+  const definitionKey = session.definitionKey || resolveInstallDefinitionKey(ctx);
+  return definitionKey === 'microsoft-copilot' || definitionKey === 'teams-bot';
+}
+
+async function prepareCopilotContinueLogin(session, retryLogin, ctx) {
+  if (!shouldAwaitPortalMicrosoftLogin(session, retryLogin, ctx)) {
+    return;
+  }
+  const peeked = peekPortalMicrosoftLogin(session.installationKey);
+  if (peeked && peeked.authenticated === true) {
+    await awaitPortalMicrosoftLogin(session.installationKey, 15000);
+    return;
+  }
+  if (peeked && peeked.loginUrl) {
+    throw httpError(
+      'Finish Microsoft sign-in in the browser, then click Continue.',
+      409
+    );
+  }
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [body]
+ * @param {Object} [deps]
+ * @returns {Promise<Object>}
+ */
+async function continueChannelInstall(ctx, bodyOrDeps = {}, deps = DEFAULT_DEPS) {
+  const parsed = continueInstallArgs(bodyOrDeps, deps);
+  const session = requireChannelInstallSession(ctx);
+  const retryLogin = isRetryLoginFlag(parsed.body.retryLogin);
+  await prepareCopilotContinueLogin(session, retryLogin, ctx);
+  const token = typeof parsed.body.token === 'string' ? parsed.body.token.trim() : '';
+  const vaultId = continueVaultReferenceId(session, parsed.body);
+  return runChannelInstall(ctx, {
+    name: session.name,
+    profile: session.profile || undefined,
+    allowExperimental: session.allowExperimental === true,
+    continueInstall: true,
+    ...(session.installationKey ? { systemKey: session.installationKey } : {}),
+    ...continueCommandPrefix(session, parsed.body),
+    ...(retryLogin ? { retryLogin: true } : {}),
+    ...(!retryLogin && token ? { token } : {}),
+    ...(!retryLogin && session.slackAuthTicket ? { slackAuthTicket: session.slackAuthTicket } : {}),
+    ...(vaultId ? { oauthPluginVaultReferenceId: vaultId } : {})
+  }, parsed.deps);
+}
+
+module.exports = {
+  listChannelTargets,
+  runChannelInstall,
+  getChannelInstall,
+  getChannelInstallHelp,
+  continueChannelInstall,
+  shouldAwaitPortalMicrosoftLogin,
+  toChannelAddOptionsFromBody,
+  envelopeFromInstall
+};