@aifabrix/builder 2.53.1 → 2.54.1

package/lib/channels/channel-add-remaining.js

@@ -0,0 +1,486 @@
+/**
+ * Vendor remaining-step payloads for canonical channel add TTY.
+ *
+ * @fileoverview Slack/Copilot/Teams/web-embed remaining steps only
+ */
+
+'use strict';
+
+const path = require('path');
+const { CHANNEL_TARGETS } = require('./channel-targets');
+const { buildCredentialPortalUrl } = require('./approval-guides/credential-portal');
+const { ENTRA_SSO_REGISTRATION_URL } = require('./microsoft-copilot-entra-sso-form');
+const {
+  DEVELOPER_PORTAL_APPS_URL,
+  TEAMS_ADMIN_APPS_URL,
+  copilotPackageAppId,
+  developerPortalPublishOrgUrl
+} = require('./approval-guides/microsoft-copilot');
+const {
+  TEAMS_CLI_MISSING_REMAINING,
+  TEAMS_OPEN_URL,
+  TEAMS_POLICY_REMAINING
+} = require('./microsoft-provisioning/constants');
+const {
+  buildChatGptFormValues,
+  formatChatGptFormValueLines,
+  CHATGPT_APPS_CREATE_URL
+} = require('./chatgpt-setup-values');
+const { printMcpClientDryRunTty } = require('./mcp-client-channel-add');
+const { printClaudeDryRunTty } = require('./claude-channel-add');
+const { CLAUDE_REMAINING_STEPS } = require('./claude-runtime-contract');
+const { vendorFacingUrlsFromCtx } = require('./vendor-dataplane-url');
+const {
+  channelDisplayLabel,
+  printValidating,
+  printRuntimeDeployed,
+  printSlackOnboarded,
+  printOAuthConnected,
+  printSlackConnected,
+  printLabeledUrl,
+  printUseLines,
+  printRemainingSteps
+} = require('./channel-add-tty');
+
+const SLACK_APPS_URL = 'https://api.slack.com/apps';
+
+const SLACK_AUTH_HANDSHAKE_STEPS = [
+  'Paste the slash command in any Slack channel or DM',
+  'Approve the permissions Slack shows',
+  'Paste the challenge code and continue'
+];
+
+const CHATGPT_REMAINING_STEPS = [
+  'Create with logo (cannot change later)',
+  'Publish',
+  'Connect'
+];
+
+/**
+ * @param {Object|null} ctx
+ * @param {string} channelTarget
+ * @returns {string}
+ */
+function credentialUrl(ctx, channelTarget) {
+  const { dataplaneBaseUrl } = vendorFacingUrlsFromCtx(ctx || {});
+  if (!dataplaneBaseUrl) {
+    return '';
+  }
+  const instanceKey =
+    ctx && typeof ctx.instanceSystemKey === 'string' ? ctx.instanceSystemKey.trim() : '';
+  return buildCredentialPortalUrl(dataplaneBaseUrl, instanceKey || channelTarget);
+}
+
+/**
+ * @param {Object|null} ctx
+ * @param {Object|null} runtimeValues
+ * @returns {string}
+ */
+function copilotZipPath(ctx, runtimeValues) {
+  const env =
+    String((runtimeValues && runtimeValues.environment) || (ctx && ctx.environment) || 'dev').trim() ||
+    'dev';
+  const root = (ctx && ctx.projectRoot) || (runtimeValues && runtimeValues.projectRoot) || process.cwd();
+  return path.resolve(root, 'dist', 'channels', 'microsoft-copilot', 'build', `appPackage.${env}.zip`);
+}
+
+/**
+ * Portal download uses the instance key so GET artifacts hits this install.
+ * @param {Object|null} ctx
+ * @returns {string}
+ */
+function copilotArtifactHref(ctx) {
+  const key =
+    ctx && typeof ctx.instanceSystemKey === 'string' && ctx.instanceSystemKey.trim()
+      ? ctx.instanceSystemKey.trim()
+      : 'microsoft-copilot';
+  return `/api/v1/builder/systems/${encodeURIComponent(key)}/channels/artifacts/appPackage`;
+}
+
+/**
+ * @param {Object|null} runtimeValues
+ * @returns {boolean}
+ */
+function hasCopilotOauthVault(runtimeValues) {
+  return Boolean(
+    runtimeValues &&
+    typeof runtimeValues.oauthPluginVaultReferenceId === 'string' &&
+    runtimeValues.oauthPluginVaultReferenceId.trim()
+  );
+}
+
+/**
+ * Toolkit session exists but auth-config capture failed.
+ * @returns {Object}
+ */
+function copilotFallbackRemainingSpec() {
+  return {
+    oauth: true,
+    authHeading: 'Teams Developer Portal (fallback)',
+    authUrl: ENTRA_SSO_REGISTRATION_URL,
+    remainingLabel: 'Microsoft Copilot',
+    steps: ['Paste the auth-config ID if Microsoft 365 Agents Toolkit could not create it']
+  };
+}
+
+/**
+ * Copilot remaining steps while Microsoft login / Toolkit auth-config is missing.
+ * @param {Object|null} runtimeValues
+ * @returns {Object}
+ */
+function copilotWaitingRemainingSpec(runtimeValues) {
+  if (runtimeValues && runtimeValues.microsoftAuthConfigFallback === true) {
+    return copilotFallbackRemainingSpec();
+  }
+  const loginUrl =
+    runtimeValues && typeof runtimeValues.microsoftLoginUrl === 'string'
+      ? runtimeValues.microsoftLoginUrl.trim()
+      : '';
+  const userCode =
+    runtimeValues && typeof runtimeValues.microsoftLoginUserCode === 'string'
+      ? runtimeValues.microsoftLoginUserCode.trim()
+      : '';
+  const steps = loginUrl
+    ? ['Sign in with Microsoft in the browser, then continue after sign-in']
+    : ['Continue to finish Microsoft Copilot setup'];
+  if (loginUrl && userCode) {
+    steps.unshift(`Enter code ${userCode} if the browser asks for it`);
+  }
+  return {
+    oauth: true,
+    authHeading: loginUrl ? 'Sign in with Microsoft' : undefined,
+    authUrl: loginUrl,
+    remainingLabel: 'Microsoft Copilot',
+    steps
+  };
+}
+
+/**
+ * @param {Object|null} ctx
+ * @param {Object|null} runtimeValues
+ * @returns {Object}
+ */
+function copilotRemainingSpec(ctx, runtimeValues) {
+  if (!hasCopilotOauthVault(runtimeValues)) {
+    return copilotWaitingRemainingSpec(runtimeValues);
+  }
+  return {
+    oauth: true,
+    handoffRequired: false,
+    openHeading: 'Import an application',
+    openUrl: DEVELOPER_PORTAL_APPS_URL,
+    activateHeading: 'Publish to your org',
+    activateUrl: developerPortalPublishOrgUrl(copilotPackageAppId(ctx, runtimeValues)),
+    adminHeading: 'Approve in Manage apps',
+    adminUrl: TEAMS_ADMIN_APPS_URL,
+    downloadHeading: 'Download app package',
+    downloadHref: copilotArtifactHref(ctx),
+    remainingLabel: 'Microsoft Copilot',
+    useLines: [`Package: ${copilotZipPath(ctx, runtimeValues)}`],
+    steps: [
+      'Import an application (keep the generated app id)',
+      'Publish to your org',
+      'Approve in Manage apps, then Add from Built for your org'
+    ]
+  };
+}
+
+/**
+ * Slack vendor URLs. Connected (secrets stored) omits Authentication.
+ * @param {Object|null} ctx
+ * @param {{ connected?: boolean }} [options]
+ * @returns {Object}
+ */
+function slackVendorUrls(ctx, options) {
+  const connected = Boolean(options && options.connected);
+  const settingsUrl = ctx && ctx.slackAppSettingsUrl;
+  const installUrl = ctx && ctx.slackInstallAppUrl;
+  const approveUrl = ctx && ctx.slackWorkspaceApproveUrl;
+  return {
+    openHeading: 'Open Slack Apps',
+    openUrl: settingsUrl || (connected ? '' : SLACK_APPS_URL),
+    activateHeading: installUrl ? 'Activate the application' : undefined,
+    activateUrl: installUrl || '',
+    adminHeading: approveUrl ? 'Approve for this workspace' : undefined,
+    adminUrl: approveUrl || '',
+    authUrl: connected ? '' : credentialUrl(ctx, 'slack')
+  };
+}
+
+function slackRecoverySpec(ctx, steps) {
+  return {
+    oauth: false,
+    remainingLabel: 'Slack',
+    steps,
+    ...slackVendorUrls(ctx, { connected: false })
+  };
+}
+
+/**
+ * @param {string[]} steps
+ * @returns {boolean}
+ */
+function isHandshakeRemaining(steps) {
+  const text = (steps || []).join('\n');
+  return /challenge code|token_revoked|token_expired|invalid_auth|not_authed/i.test(text);
+}
+
+/**
+ * @param {string[]} steps
+ * @param {Object} [extra]
+ * @returns {Object}
+ */
+function slackStepsSpec(steps, extra) {
+  return {
+    oauth: false,
+    remainingLabel: 'Slack',
+    steps,
+    ...extra
+  };
+}
+
+function slackCustomSteps(ctx) {
+  if (ctx && Array.isArray(ctx.slackRemaining)) {
+    return ctx.slackRemaining;
+  }
+  return null;
+}
+
+function slackConnectedRemaining(ctx, custom) {
+  return {
+    ...slackStepsSpec(custom || [], { slackConnected: true }),
+    ...slackVendorUrls(ctx, { connected: true })
+  };
+}
+
+function slackSlashRemaining(ctx, custom) {
+  const steps = custom && custom.length > 0 ? custom : [...SLACK_AUTH_HANDSHAKE_STEPS];
+  return slackStepsSpec(steps, { slackSlashCommand: ctx.slackSlashCommand });
+}
+
+function slackFailedRemaining(custom) {
+  const failed = ['Slack authentication could not start on this host.'];
+  return slackStepsSpec(custom && custom.length > 0 ? custom : failed);
+}
+
+function slackRecoveryOrHandshake(ctx, custom) {
+  if (custom && custom.length > 0 && isHandshakeRemaining(custom)) {
+    return slackStepsSpec(custom);
+  }
+  if (custom && custom.length > 0) {
+    return slackRecoverySpec(ctx, custom);
+  }
+  return slackRecoverySpec(ctx, [
+    'Create the Slack app from the generated manifest',
+    'Store the bot token and signing secret'
+  ]);
+}
+
+/**
+ * @param {Object|null} ctx
+ * @returns {Object}
+ */
+function slackRemainingSpec(ctx) {
+  const custom = slackCustomSteps(ctx);
+  if (ctx && ctx.slackConnected === true) {
+    return slackConnectedRemaining(ctx, custom);
+  }
+  if (ctx && ctx.slackSlashCommand) {
+    return slackSlashRemaining(ctx, custom);
+  }
+  if (ctx && ctx.slackHandshakeFailed === true) {
+    return slackFailedRemaining(custom);
+  }
+  return slackRecoveryOrHandshake(ctx, custom);
+}
+
+/**
+ * @param {Object|null} ctx
+ * @returns {Object}
+ */
+function teamsBotLoginUrl(ctx, runtimeValues) {
+  const fromRuntime =
+    runtimeValues && typeof runtimeValues.microsoftLoginUrl === 'string'
+      ? runtimeValues.microsoftLoginUrl.trim()
+      : '';
+  if (fromRuntime) {
+    return fromRuntime;
+  }
+  return ctx && typeof ctx.microsoftLoginUrl === 'string' ? ctx.microsoftLoginUrl.trim() : '';
+}
+
+/**
+ * @param {Object|null} ctx
+ * @param {Object|null} [runtimeValues]
+ * @returns {Object}
+ */
+function teamsBotRemainingSpec(ctx, runtimeValues) {
+  const custom = ctx && Array.isArray(ctx.teamsBotRemaining) ? ctx.teamsBotRemaining : null;
+  if (ctx && ctx.teamsBotSkipped === true) {
+    const loginUrl = teamsBotLoginUrl(ctx, runtimeValues);
+    if (loginUrl) {
+      return {
+        oauth: false,
+        openHeading: 'Sign in with Microsoft',
+        openUrl: loginUrl,
+        remainingLabel: 'Microsoft',
+        steps: ['Sign in with Microsoft in the browser, then continue after sign-in']
+      };
+    }
+    return {
+      oauth: false,
+      remainingLabel: 'Microsoft',
+      steps: custom && custom.length > 0 ? custom : TEAMS_CLI_MISSING_REMAINING
+    };
+  }
+  return {
+    oauth: true,
+    openHeading: 'Open Teams',
+    openUrl: (ctx && ctx.teamsBotOpenUrl) || TEAMS_OPEN_URL,
+    remainingLabel: 'Microsoft',
+    steps: custom && custom.length > 0 ? custom : [TEAMS_POLICY_REMAINING]
+  };
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object|null} ctx
+ * @param {Object|null} [runtimeValues]
+ * @returns {Object}
+ */
+function remainingSpec(channelTarget, ctx, runtimeValues) {
+  if (channelTarget === 'slack') {
+    return slackRemainingSpec(ctx);
+  }
+  if (channelTarget === 'microsoft-copilot') {
+    return copilotRemainingSpec(ctx, runtimeValues);
+  }
+  if (channelTarget === 'teams-bot') {
+    return teamsBotRemainingSpec(ctx, runtimeValues);
+  }
+  if (channelTarget === 'web-embed') {
+    return {
+      oauth: false,
+      remainingLabel: '',
+      steps: ['Embed the generated snippet in your application']
+    };
+  }
+  if (channelTarget === 'mcp-client') {
+    return {
+      oauth: true,
+      remainingLabel: '',
+      steps: ['Reload the editor.']
+    };
+  }
+  if (channelTarget === 'claude') {
+    return {
+      oauth: true,
+      remainingLabel: 'Claude',
+      steps: [...CLAUDE_REMAINING_STEPS]
+    };
+  }
+  const step = CHANNEL_TARGETS[channelTarget] && CHANNEL_TARGETS[channelTarget].remainingManualStep;
+  return {
+    oauth: false,
+    remainingLabel: channelDisplayLabel(channelTarget),
+    steps: step ? [step] : []
+  };
+}
+
+/**
+ * @param {Object} spec
+ * @returns {void}
+ */
+function printVendorUrls(spec) {
+  printLabeledUrl(spec.openHeading, spec.openUrl);
+  printUseLines(spec.useLines);
+  printLabeledUrl(spec.activateHeading, spec.activateUrl);
+  printLabeledUrl(spec.adminHeading, spec.adminUrl);
+  printLabeledUrl(spec.authHeading || 'Authentication', spec.authUrl);
+}
+
+/**
+ * Default TTY after AI Fabrix-owned work for non-ChatGPT targets.
+ * @param {string} channelTarget
+ * @param {Object|null} ctx
+ * @param {Object|null} [runtimeValues]
+ * @returns {void}
+ */
+function printVendorChannelValidated(channelTarget, ctx, runtimeValues) {
+  const spec = remainingSpec(channelTarget, ctx, runtimeValues);
+  printValidating(channelDisplayLabel(channelTarget));
+  printRuntimeDeployed();
+  if (typeof ctx?.slackOnboarded === 'number') {
+    printSlackOnboarded(ctx.slackOnboarded);
+  }
+  if (spec.slackConnected) {
+    printSlackConnected();
+    printVendorUrls(spec);
+    printRemainingSteps(spec.remainingLabel, spec.steps);
+    return;
+  }
+  if (spec.slackSlashCommand) {
+    printLabeledUrl('Run in Slack', spec.slackSlashCommand);
+    printRemainingSteps(spec.remainingLabel, spec.steps);
+    return;
+  }
+  if (spec.oauth === true) {
+    printOAuthConnected();
+  }
+  printVendorUrls(spec);
+  printRemainingSteps(spec.remainingLabel, spec.steps);
+}
+
+/**
+ * Dry-run ChatGPT TTY (no live OAuth).
+ * @param {Object} params
+ * @returns {void}
+ */
+function printChatGptDryRunTty(params) {
+  printValidating('ChatGPT');
+  printRuntimeDeployed();
+  const values = buildChatGptFormValues({ runtimeValues: params.runtimeValues || {} });
+  printLabeledUrl('Open ChatGPT Apps', CHATGPT_APPS_CREATE_URL);
+  printUseLines(formatChatGptFormValueLines(values));
+  printRemainingSteps('ChatGPT', CHATGPT_REMAINING_STEPS);
+}
+
+/**
+ * Live/dry-run install TTY. ChatGPT remaining steps are printed by continuation.
+ * @param {Object} params
+ * @returns {void}
+ */
+function printLiveChannelCanonicalTty(params) {
+  if (params.channelTarget === 'chatgpt') {
+    if (params.options && params.options.dryRun === true) {
+      printChatGptDryRunTty(params);
+    }
+    return;
+  }
+  if (params.channelTarget === 'claude') {
+    if (params.options && params.options.dryRun === true) {
+      printClaudeDryRunTty(params);
+    }
+    return;
+  }
+  if (params.channelTarget === 'mcp-client') {
+    if (params.options && params.options.dryRun === true) {
+      printMcpClientDryRunTty(params);
+    }
+    return;
+  }
+  printVendorChannelValidated(params.channelTarget, {
+    ...(params.ctx || {}),
+    projectRoot: (params.ctx && params.ctx.projectRoot) || (params.options && params.options.projectRoot)
+  }, params.runtimeValues);
+}
+
+module.exports = {
+  SLACK_APPS_URL,
+  SLACK_AUTH_HANDSHAKE_STEPS,
+  CHATGPT_REMAINING_STEPS,
+  CLAUDE_REMAINING_STEPS,
+  remainingSpec,
+  printVendorChannelValidated,
+  printLiveChannelCanonicalTty
+};

package/lib/channels/channel-add-tty.js

@@ -0,0 +1,190 @@
+/**
+ * Canonical default TTY for `aifabrix channel add`.
+ *
+ * @fileoverview Shared scaffold/upload/validate/remaining-step lines
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const {
+  formatSuccessLine,
+  formatBlockingError
+} = require('../utils/cli-layout-chalk');
+const { CHANNEL_TARGETS } = require('./channel-targets');
+
+/**
+ * @param {Object} [options]
+ * @returns {boolean}
+ */
+function isChannelAddVerbose(options) {
+  return Boolean(options && options.verbose === true);
+}
+
+/**
+ * @param {string} channelTarget
+ * @returns {string}
+ */
+function channelDisplayLabel(channelTarget) {
+  const target = CHANNEL_TARGETS[channelTarget];
+  return (target && target.displayLabel) || channelTarget;
+}
+
+/**
+ * @param {string} integrationDir
+ * @returns {void}
+ */
+function printScaffolded(integrationDir) {
+  logger.log(formatSuccessLine(`Scaffolded integration at ${integrationDir}`));
+}
+
+/**
+ * @param {string} systemKey
+ * @returns {void}
+ */
+function printUploaded(systemKey) {
+  logger.log(formatSuccessLine(`Uploaded ${systemKey} in dataplane`));
+}
+
+/**
+ * @param {string} label
+ * @returns {void}
+ */
+function printValidating(label) {
+  logger.log(chalk.white(`Validating ${label}...`));
+}
+
+/**
+ * @returns {void}
+ */
+function printRuntimeDeployed() {
+  logger.log(formatSuccessLine('Runtime: Deployed'));
+}
+
+/**
+ * @param {number} count
+ * @returns {void}
+ */
+function printSlackOnboarded(count) {
+  logger.log(formatSuccessLine(`Onboarded ${Number(count) || 0} Slack users.`));
+}
+
+/**
+ * @returns {void}
+ */
+function printRuntimeUnavailable() {
+  logger.error(formatBlockingError('Runtime: Unavailable'));
+}
+
+/**
+ * @returns {void}
+ */
+function printOAuthConnected() {
+  logger.log(formatSuccessLine('OAuth: Connected.'));
+}
+
+/**
+ * @returns {void}
+ */
+function printSlackConnected() {
+  logger.log(formatSuccessLine('Slack: Connected.'));
+}
+
+/**
+ * @returns {void}
+ */
+function printOAuthNotConnected() {
+  logger.error(formatBlockingError('OAuth: Not connected'));
+}
+
+/**
+ * @param {string} heading
+ * @param {string} url
+ * @returns {void}
+ */
+function printLabeledUrl(heading, url) {
+  if (!url) {
+    return;
+  }
+  logger.log('');
+  logger.log(chalk.white(`${heading}:`));
+  logger.log(chalk.cyan(url));
+}
+
+/**
+ * @param {string[]} lines
+ * @returns {void}
+ */
+function printUseLines(lines) {
+  const usable = (lines || []).filter((line) => {
+    if (typeof line !== 'string' || !line.trim()) {
+      return false;
+    }
+    return !/^Server URL:\s*$/.test(line);
+  });
+  if (usable.length === 0) {
+    return;
+  }
+  logger.log('');
+  logger.log(chalk.white('Use:'));
+  for (const line of usable) {
+    logger.log(chalk.white(line));
+  }
+}
+
+/**
+ * @param {string} vendorLabel
+ * @param {string[]} steps
+ * @returns {void}
+ */
+function printRemainingSteps(vendorLabel, steps) {
+  const list = (steps || []).filter((step) => typeof step === 'string' && step.trim());
+  if (list.length === 0) {
+    return;
+  }
+  const heading = vendorLabel ? `Remaining ${vendorLabel} steps:` : 'Remaining steps:';
+  logger.log('');
+  logger.log(chalk.white(heading));
+  for (const step of list) {
+    logger.log(chalk.white(`- ${step}`));
+  }
+}
+
+/**
+ * @param {string} reason
+ * @param {string} resumeCommand
+ * @returns {void}
+ */
+function printFixThenRerun(reason, resumeCommand) {
+  logger.log('');
+  logger.log(chalk.white(`${reason}, then run:`));
+  logger.log('');
+  logger.log(chalk.white(resumeCommand));
+}
+
+/**
+ * @returns {void}
+ */
+function printCallbackRegistered() {
+  logger.log(formatSuccessLine('Callback registered'));
+}
+
+module.exports = {
+  isChannelAddVerbose,
+  channelDisplayLabel,
+  printScaffolded,
+  printUploaded,
+  printValidating,
+  printRuntimeDeployed,
+  printSlackOnboarded,
+  printRuntimeUnavailable,
+  printOAuthConnected,
+  printSlackConnected,
+  printOAuthNotConnected,
+  printLabeledUrl,
+  printUseLines,
+  printRemainingSteps,
+  printFixThenRerun,
+  printCallbackRegistered
+};