@aifabrix/builder 2.53.1 → 2.55.0

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

@@ -0,0 +1,353 @@
+/**
+ * Copilot waiting install and channel-install envelope persistence.
+ *
+ * @fileoverview Entra SSO wait path plus help payload for generic channel install
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { toChannelInstallEnvelope } = require('../channels/channel-install-envelope');
+const { toChannelInstallHttpPayload } = require('../channels/channel-install-http-payload');
+const { resolveChannelRuntimeValues } = require('../channels/channel-runtime-resolver');
+const { vendorFacingUrlsFromCtx } = require('../channels/vendor-dataplane-url');
+const {
+  startPortalMicrosoftLogin,
+  isLoopbackAuthorizeUrl
+} = require('../channels/microsoft-provisioning');
+const { writeChannelInstallSession, httpError } = require('./channel-install-session');
+const { attachInstallIdentity } = require('./channel-install-help-resolve');
+
+/**
+ * Missing Teams Entra SSO id is a remaining step, not a publish failure.
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function isCopilotEntraWaitingError(err) {
+  if (!err || Number(err.statusCode) !== 409) {
+    return false;
+  }
+  return /Entra SSO registration is stored on this install/i.test(String(err.message || ''));
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} addOptions
+ * @param {string} definitionKey
+ * @returns {Object}
+ */
+function copilotWaitingRuntimeValues(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 : ''
+  });
+}
+
+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 {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} addOptions
+ * @param {string} definitionKey
+ * @param {Object} [deps]
+ * @returns {Promise<Object>}
+ */
+async function retryCopilotCaptureIfAuthenticated(ctx, addOptions, definitionKey, deps, login) {
+  if (!login || login.authenticated !== true || addOptions.copilotCaptureRetry === true) {
+    return null;
+  }
+  try {
+    const result = await deps.executeAddChannel(
+      ctx,
+      { ...addOptions, copilotCaptureRetry: true },
+      deps,
+      definitionKey
+    );
+    if (copilotInstallStillWaiting(definitionKey, result)) {
+      return null;
+    }
+    const envelope = envelopeFromInstall(ctx, addOptions, result, definitionKey);
+    return persistHelpPayload(ctx, addOptions, envelope, definitionKey, result);
+  } catch (err) {
+    if (!isCopilotEntraWaitingError(err)) {
+      throw err;
+    }
+    return null;
+  }
+}
+
+function copilotWaitingWithoutSignInError(login) {
+  if (login && login.authenticated === true) {
+    return httpError(
+      'Microsoft sign-in succeeded, but Copilot setup still needs Entra SSO. ' +
+        'This environment needs an Entra application id and a public MCP URL.',
+      400
+    );
+  }
+  return httpError(
+    'Could not start Microsoft sign-in. Use Get a new code, complete sign-in, then click Continue.',
+    409
+  );
+}
+
+/**
+ * Add-channel can skip/succeed without Entra SSO landing on the install result.
+ * @param {string} definitionKey
+ * @param {Object|null} result
+ * @returns {boolean}
+ */
+function copilotInstallStillWaiting(definitionKey, result) {
+  if (definitionKey !== 'microsoft-copilot') {
+    return false;
+  }
+  const vault =
+    result &&
+    result.runtimeValues &&
+    typeof result.runtimeValues.oauthPluginVaultReferenceId === 'string'
+      ? result.runtimeValues.oauthPluginVaultReferenceId.trim()
+      : '';
+  return !vault;
+}
+
+function persistCopilotWaitingEnvelope(ctx, addOptions, definitionKey, runtimeValues, login) {
+  applyPortalMicrosoftLogin(runtimeValues, login);
+  const loginUrl =
+    typeof runtimeValues.microsoftLoginUrl === 'string' ? runtimeValues.microsoftLoginUrl.trim() : '';
+  if (!loginUrl) {
+    throw copilotWaitingWithoutSignInError(login);
+  }
+  const envelope = toChannelInstallEnvelope({
+    channelTarget: definitionKey,
+    displayName: addOptions.name,
+    ctx: remainingCtxFromResult(ctx, null, addOptions),
+    runtimeValues,
+    verdicts: {
+      runtime: { ok: true, label: 'Deployed' },
+      oauth: { ok: true, label: 'Connected' },
+      vendorSession: { ok: false, label: 'Approval required' }
+    }
+  });
+  return persistHelpPayload(ctx, addOptions, envelope, definitionKey, { runtimeValues });
+}
+
+async function persistWaitingCopilotInstall(ctx, addOptions, definitionKey, deps = {}) {
+  const runtimeValues = copilotWaitingRuntimeValues(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,
+      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 retryCopilotCaptureIfAuthenticated(
+    ctx,
+    addOptions,
+    definitionKey,
+    deps,
+    login
+  );
+  if (captured) {
+    return captured;
+  }
+  return persistCopilotWaitingEnvelope(ctx, addOptions, definitionKey, runtimeValues, login);
+}
+
+/**
+ * @param {Object|null} result
+ * @returns {Object}
+ */
+function teamsBotOauthOk(definitionKey, result, blocker) {
+  if (blocker) {
+    return false;
+  }
+  if (definitionKey !== 'teams-bot') {
+    return true;
+  }
+  const bot = result && result.teamsBotProvision;
+  return Boolean(bot && bot.connected === true && bot.skipped !== true);
+}
+
+/**
+ * @param {Object|null} result
+ * @param {string} [definitionKey]
+ * @returns {Object}
+ */
+function verdictsFromInstallResult(result, definitionKey) {
+  const runtimeValues = (result && result.runtimeValues) || {};
+  const blocker = runtimeValues.discoveryBlocker;
+  const slack = result && result.slackProvision;
+  const connected = Boolean(slack && slack.connected === true);
+  const oauthOk = teamsBotOauthOk(definitionKey, result, blocker);
+  const teamsConnected = teamsBotOauthOk('teams-bot', result, blocker);
+  return {
+    runtime: {
+      ok: !blocker,
+      label: blocker ? 'Unavailable' : 'Deployed'
+    },
+    oauth: { ok: oauthOk, label: oauthOk ? 'Connected' : 'Not connected' },
+    vendorSession: {
+      ok: definitionKey === 'teams-bot' ? teamsConnected : connected,
+      label: (definitionKey === 'teams-bot' ? teamsConnected : connected)
+        ? 'Connected'
+        : 'Approval required'
+    }
+  };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} result
+ * @param {Object} [addOptions]
+ * @returns {Object}
+ */
+function remainingCtxFromResult(ctx, result, addOptions) {
+  const slack = (result && result.slackProvision) || {};
+  const teamsBot = (result && result.teamsBotProvision) || {};
+  const runtime = (result && result.runtimeValues) || {};
+  return {
+    dataplaneUrl: ctx.dataplaneUrl,
+    publicOrigin: ctx.publicOrigin,
+    environment: ctx.environment,
+    projectRoot: ctx.getUserRoot(),
+    instanceSystemKey:
+      (addOptions && addOptions.systemKey) || ctx.instanceSystemKey || runtime.instanceSystemKey,
+    slackConnected: slack.connected === true,
+    slackAppSettingsUrl: slack.slackAppSettingsUrl || slack.appSettingsUrl,
+    slackInstallAppUrl: slack.slackInstallAppUrl || slack.installUrl,
+    slackWorkspaceApproveUrl: slack.slackWorkspaceApproveUrl,
+    slackRemaining: slack.remaining,
+    slackSlashCommand: slack.slashCommand,
+    slackHandshakeFailed: slack.handshakeFailed === true,
+    teamsBotSkipped: teamsBot.skipped === true,
+    teamsBotOpenUrl: teamsBot.openUrl,
+    teamsBotRemaining: teamsBot.remaining,
+    microsoftLoginUrl: runtime.microsoftLoginUrl
+  };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} addOptions
+ * @param {Object|null} result
+ * @returns {Object}
+ */
+function envelopeFromInstall(ctx, addOptions, result, definitionKey) {
+  const runtimeValues = (result && result.runtimeValues) || { appName: addOptions.name };
+  return toChannelInstallEnvelope({
+    channelTarget: definitionKey || ctx.systemKey,
+    displayName: runtimeValues.appName || addOptions.name,
+    ctx: remainingCtxFromResult(ctx, result, addOptions),
+    runtimeValues,
+    verdicts: verdictsFromInstallResult(result, definitionKey || ctx.systemKey)
+  });
+}
+
+/**
+ * @param {Object} addOptions
+ * @param {Object|null} [result]
+ * @returns {string|undefined}
+ */
+function persistableCommandPrefix(addOptions, result) {
+  const fromOptions =
+    typeof addOptions.commandPrefix === 'string' ? addOptions.commandPrefix.trim() : '';
+  if (fromOptions) {
+    return fromOptions;
+  }
+  const runtime = (result && result.runtimeValues) || {};
+  return typeof runtime.commandPrefix === 'string' ? runtime.commandPrefix.trim() : undefined;
+}
+
+/**
+ * @param {Object} addOptions
+ * @param {Object|null} [result]
+ * @returns {string|undefined}
+ */
+function persistablePackageVersion(addOptions, result) {
+  const fromOptions =
+    typeof addOptions.packageVersion === 'string' ? addOptions.packageVersion.trim() : '';
+  if (fromOptions) {
+    return fromOptions;
+  }
+  const runtime = (result && result.runtimeValues) || {};
+  return typeof runtime.packageVersion === 'string' ? runtime.packageVersion.trim() : undefined;
+}
+
+/**
+ * @param {Object|null} [result]
+ * @param {string} key
+ * @returns {*|undefined}
+ */
+function persistableRuntimeValue(result, key) {
+  const runtime = (result && result.runtimeValues) || {};
+  return runtime[key];
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} addOptions
+ * @param {Object} envelope
+ * @param {string} [definitionKey]
+ * @param {Object|null} [result]
+ * @returns {Object}
+ */
+function persistHelpPayload(ctx, addOptions, envelope, definitionKey, result) {
+  const payload = toChannelInstallHttpPayload(envelope);
+  const installationKey = addOptions.systemKey || ctx.instanceSystemKey || ctx.systemKey;
+  const catalogKey = definitionKey || ctx.systemKey;
+  const slack = (result && result.slackProvision) || {};
+  writeChannelInstallSession(ctx, {
+    name: addOptions.name,
+    displayName: envelope.displayName,
+    profile: addOptions.profile || null,
+    allowExperimental: addOptions.allowExperimental === true,
+    phase: envelope.phase,
+    envelope,
+    definitionKey: catalogKey,
+    installationKey,
+    slackAuthTicket: slack.slackAuthTicket,
+    commandPrefix: persistableCommandPrefix(addOptions, result),
+    packageVersion: persistablePackageVersion(addOptions, result),
+    packageAppId: persistableRuntimeValue(result, 'packageAppId'),
+    oauthPluginVaultReferenceId: persistableRuntimeValue(result, 'oauthPluginVaultReferenceId'),
+    microsoftLoginUrl: persistableRuntimeValue(result, 'microsoftLoginUrl'),
+    microsoftLoginUserCode: persistableRuntimeValue(result, 'microsoftLoginUserCode'),
+    microsoftAuthConfigFallback: persistableRuntimeValue(result, 'microsoftAuthConfigFallback') === true
+  });
+  return attachInstallIdentity(payload, catalogKey, installationKey);
+}
+
+module.exports = {
+  isCopilotEntraWaitingError,
+  copilotInstallStillWaiting,
+  persistWaitingCopilotInstall,
+  envelopeFromInstall,
+  persistHelpPayload,
+  remainingCtxFromResult,
+  verdictsFromInstallResult
+};

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

@@ -0,0 +1,236 @@
+/**
+ * Validate and map generic channel install POST body to add-channel options.
+ *
+ * @fileoverview Shared by HTTP install and continue
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const {
+  formatUnknownChannelTargetError,
+  listLiveChannelTargetKeys,
+  assertChannelTargetInstallable
+} = require('../channels/channel-targets');
+const { getChannelDefinition } = require('../channels/channel-definition-registry');
+const {
+  unknownConfigurationKeys,
+  missingRequiredConfigurationKeys,
+  applyConfigurationToAddOptions
+} = require('../channels/channel-configuration-map');
+const { deriveChannelInstanceKey } = require('../channels/channel-instance-key');
+const {
+  installRequiresProfile,
+  isAllowedInstallProfile,
+  profilesForInstall
+} = require('../channels/channel-install-profiles');
+const { httpError } = require('./channel-install-session');
+
+/**
+ * @param {string} systemKey
+ * @param {Object} body
+ * @returns {void}
+ */
+function assertInstallProfile(systemKey, body) {
+  if (!installRequiresProfile(systemKey)) {
+    return;
+  }
+  const profile = typeof body.profile === 'string' ? body.profile.trim() : '';
+  if (!profile) {
+    const keys = profilesForInstall(systemKey).map((row) => row.key).join(', ');
+    throw httpError(`profile is required for ${systemKey} (${keys}).`, 400);
+  }
+  if (!isAllowedInstallProfile(systemKey, profile)) {
+    const keys = profilesForInstall(systemKey).map((row) => row.key).join(', ');
+    throw httpError(`Unknown profile "${profile}" for ${systemKey}. Allowed: ${keys}.`, 400);
+  }
+}
+
+/**
+ * @param {string} systemKey
+ * @param {Object} body
+ * @returns {void}
+ */
+function assertChannelInstallTarget(systemKey, body) {
+  assertInstallProfile(systemKey, body || {});
+  try {
+    assertChannelTargetInstallable(systemKey, {
+      allowExperimental: body && body.allowExperimental === true,
+      continueInstall: body && body.continueInstall === true
+    });
+  } catch (err) {
+    if (err && err.statusCode === 403) {
+      throw httpError(err.message, 403);
+    }
+    const live = listLiveChannelTargetKeys({
+      allowExperimental: body && body.allowExperimental === true
+    }).join(', ');
+    throw httpError(`${err.message}\nLive channels: ${live}`, 400);
+  }
+}
+
+/**
+ * @param {Object} body
+ * @returns {string}
+ */
+function requireInstallName(body) {
+  const name = body && typeof body.name === 'string' ? body.name.trim() : '';
+  if (!name) {
+    throw httpError('name is required.', 400);
+  }
+  return name;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isRetryLoginFlag(value) {
+  return value === true || value === 'true' || value === '1';
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} body
+ * @param {Object|null} def
+ * @returns {Object}
+ */
+function mergeInstallConfiguration(body) {
+  const source = body && typeof body === 'object' ? body : {};
+  const configuration = {
+    ...(source.configuration && typeof source.configuration === 'object' ? source.configuration : {})
+  };
+  for (const key of ['commandPrefix', 'packageVersion', 'oauthPluginVaultReferenceId']) {
+    if (configuration[key] === undefined && typeof source[key] === 'string' && source[key].trim()) {
+      configuration[key] = source[key].trim();
+    }
+  }
+  return configuration;
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} body
+ * @param {Object|null} def
+ * @returns {Object}
+ */
+function applyInstallConfiguration(options, body, def) {
+  const configuration = mergeInstallConfiguration(body);
+  if (def) {
+    const unknown = unknownConfigurationKeys(def, configuration);
+    if (unknown.length > 0) {
+      throw httpError(`Unknown configuration key(s): ${unknown.join(', ')}.`, 400);
+    }
+    const missing = missingRequiredConfigurationKeys(def, configuration);
+    if (missing.length > 0) {
+      throw httpError(`Missing required configuration: ${missing.join(', ')}.`, 400);
+    }
+  } else if (Object.keys(configuration).length > 0) {
+    throw httpError('Unknown configuration keys cannot be validated without a Channel Definition.', 400);
+  }
+  return applyConfigurationToAddOptions(options, configuration);
+}
+
+/**
+ * @param {Object} body
+ * @param {Object|null} def
+ * @returns {Object}
+ */
+function applyVendorSessionToken(options, body) {
+  if (isRetryLoginFlag(body && body.retryLogin)) {
+    options.retryLogin = true;
+    return options;
+  }
+  const token = body && typeof body.token === 'string' ? body.token.trim() : '';
+  if (token) {
+    options.vendorSessionToken = token;
+  }
+  const ticket = body && typeof body.slackAuthTicket === 'string' ? body.slackAuthTicket.trim() : '';
+  if (ticket) {
+    options.slackAuthTicket = ticket;
+  }
+  return options;
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} body
+ * @param {Object|null} def
+ * @returns {Object}
+ */
+function applyInstallBodyOptions(body, def) {
+  const options = applyVendorSessionToken(applyInstallConfiguration({
+    name: requireInstallName(body),
+    force: body.force === true,
+    probe: body.probe === true,
+    dryRun: body.dryRun === true,
+    allowExperimental: body.allowExperimental === true,
+    continueInstall: body.continueInstall === true,
+    quiet: true
+  }, body, def), body);
+  if (body.onboardUsers === true) {
+    options.onboardUsers = true;
+  }
+  if (body.onboardUsers === false) {
+    options.onboardUsers = false;
+  }
+  if (typeof body.profile === 'string' && body.profile.trim()) {
+    const profile = body.profile.trim();
+    options.profile = profile;
+    options.target = profile;
+    options.mcpClientProfile = profile;
+  }
+  return options;
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} body
+ * @param {Object|null} def
+ * @returns {Object}
+ */
+function assignDerivedSystemKey(options, body, def) {
+  const explicitKey = typeof body.systemKey === 'string' ? body.systemKey : '';
+  if (!(def && def.key) && !explicitKey) {
+    return options;
+  }
+  try {
+    options.systemKey = deriveChannelInstanceKey(
+      (def && def.key) || 'channel',
+      options.name,
+      explicitKey
+    );
+  } catch (err) {
+    throw httpError(err.message, 400);
+  }
+  return options;
+}
+
+/**
+ * Map HTTP body to runAddChannel options (same flags as `channel add --name`).
+ * @param {Object} body
+ * @param {Object} [definition]
+ * @returns {Object}
+ */
+function toChannelAddOptionsFromBody(body, definition) {
+  const def = definition || getChannelDefinition(body && body.definitionKey) || null;
+  return assignDerivedSystemKey(applyInstallBodyOptions(body, def), body, def);
+}
+
+/**
+ * @param {string} systemKey
+ * @returns {Error}
+ */
+function unknownChannelError(systemKey) {
+  return httpError(formatUnknownChannelTargetError(systemKey), 400);
+}
+
+module.exports = {
+  assertChannelInstallTarget,
+  assertInstallProfile,
+  requireInstallName,
+  toChannelAddOptionsFromBody,
+  unknownChannelError,
+  isRetryLoginFlag
+};