@aifabrix/builder 2.45.5 → 2.47.0

package/lib/channels/channel-integration-generator.js

@@ -0,0 +1,274 @@
+/**
+ * Generate integration/<channelTarget>/ for communication external systems (plan 152).
+ *
+ * @fileoverview Builder generator for channel deploy step 1 scaffolds
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getChannelTarget } = require('./channel-targets');
+const { getIntegrationPath } = require('../utils/paths');
+
+/** @type {Record<string, Object>} */
+const AUTH_BLOCKS = {
+  slack: {
+    authType: 'credential',
+    credential: {
+      credentialKey: 'slack-app',
+      displayName: 'Slack assistant channel',
+      method: 'hmac',
+      variables: {},
+      security: {
+        signingSecret: 'kv://slack/signingSecret',
+        clientId: 'kv://slack/clientId',
+        clientSecret: 'kv://slack/clientSecret'
+      },
+      writeOnce: true
+    }
+  },
+  'teams-bot': {
+    authType: 'credential',
+    credential: {
+      credentialKey: 'teams-bot',
+      displayName: 'Microsoft Teams assistant bot',
+      method: 'oidc',
+      variables: {
+        openIdConfigUrl: 'https://login.botframework.com/v1/.well-known/openid_configuration',
+        clientId: 'kv://teams-bot/botAppId',
+        expectedIssuer: 'https://api.botframework.com'
+      },
+      security: {},
+      writeOnce: true
+    }
+  },
+  'microsoft-copilot': {
+    authType: 'credential',
+    credential: {
+      credentialKey: 'microsoft-copilot-channel',
+      displayName: 'Microsoft Copilot assistant channel',
+      method: 'oauth2',
+      variables: {
+        tokenUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+        grantType: 'client_credentials'
+      },
+      security: {
+        clientId: 'kv://microsoft-copilot/clientId',
+        clientSecret: 'kv://microsoft-copilot/clientSecret'
+      },
+      writeOnce: true
+    }
+  },
+  chatgpt: {
+    authType: 'credential',
+    credential: {
+      credentialKey: 'chatgpt-channel',
+      displayName: 'ChatGPT assistant channel',
+      method: 'apikey',
+      variables: {},
+      security: {
+        apiKey: 'kv://chatgpt/apiKey'
+      },
+      writeOnce: true
+    }
+  },
+  'web-embed': {
+    authType: 'credential',
+    credential: {
+      credentialKey: 'web-embed-channel',
+      displayName: 'Web embed assistant channel',
+      method: 'apikey',
+      variables: {},
+      security: {
+        apiKey: 'kv://web-embed/apiKey'
+      },
+      writeOnce: true
+    }
+  }
+};
+
+/**
+ * @param {string} channelTarget
+ * @param {typeof import('./channel-targets').CHANNEL_TARGETS[string]} target
+ * @returns {Object}
+ */
+function buildAuthenticationBlock(channelTarget, target) {
+  const block = AUTH_BLOCKS[channelTarget];
+  if (!block) {
+    throw new Error(`No authentication block for channel target "${channelTarget}"`);
+  }
+  const auth = JSON.parse(JSON.stringify(block));
+  auth.credential.credentialKey = target.credentialKey;
+  return auth;
+}
+
+/**
+ * @param {string} channelTarget
+ * @returns {Object}
+ */
+function buildSystemJson(channelTarget) {
+  const target = getChannelTarget(channelTarget);
+  const system = {
+    key: channelTarget,
+    displayName: 'Microsoft Teams assistant bot',
+    description: 'Bot Framework assistant channel (not full Teams / Graph integration)',
+    type: 'custom',
+    systemKind: 'communication',
+    enabled: true,
+    authentication: buildAuthenticationBlock(channelTarget, target),
+    configuration: [],
+    dataSources: []
+  };
+
+  if (channelTarget === 'teams-bot') {
+    system.displayName = 'Microsoft Teams assistant bot';
+    system.endpoints = [
+      {
+        type: 'messages',
+        path: '/messages',
+        router: 'teams_bot_router',
+        description: 'Bot Framework messaging endpoint',
+        active: true
+      },
+      {
+        type: 'notifications',
+        path: '/notifications',
+        router: 'teams_notifications_router',
+        description: 'Proactive notification endpoint',
+        active: true
+      },
+      {
+        type: 'config',
+        path: '/bot-config',
+        router: 'teams_config_router',
+        description: 'Bot configuration endpoint',
+        active: true
+      }
+    ];
+    system.endpointsActive = true;
+  } else {
+    system.displayName = `${target.key} assistant channel`;
+    system.description = 'Communication external system for assistant channel install (plan 152)';
+  }
+
+  return system;
+}
+
+/**
+ * @param {string} channelTarget
+ * @returns {Object}
+ */
+function buildApplicationJson(channelTarget) {
+  const target = getChannelTarget(channelTarget);
+  const systemFile = `${channelTarget}-system.json`;
+  return {
+    app: {
+      key: channelTarget,
+      displayName: `${target.key} assistant channel`,
+      description: 'Assistant communication channel — deploy then app add-channel',
+      type: 'external'
+    },
+    externalIntegration: {
+      schemaBasePath: './',
+      systems: [systemFile],
+      dataSources: [],
+      autopublish: true,
+      version: '1.0.0'
+    }
+  };
+}
+
+/**
+ * @param {string} channelTarget
+ * @returns {string}
+ */
+function buildEnvTemplate(channelTarget) {
+  const kvPrefix = channelTarget === 'web-embed' ? 'web-embed' : channelTarget;
+  const lines = [
+    `# ${channelTarget} assistant channel — resolve secrets before deploy/add-channel`,
+    '# kv:// paths are pushed via aifabrix credential push or add-channel secret sync',
+    ''
+  ];
+  if (channelTarget === 'slack') {
+    lines.push('KV_SLACK_SIGNINGSECRET=kv://slack/signingSecret');
+    lines.push('KV_SLACK_CLIENTID=kv://slack/clientId');
+    lines.push('KV_SLACK_CLIENTSECRET=kv://slack/clientSecret');
+  } else if (channelTarget === 'teams-bot') {
+    lines.push('KV_TEAMS_BOT_BOTAPPID=kv://teams-bot/botAppId');
+  } else if (channelTarget === 'microsoft-copilot') {
+    lines.push('KV_MICROSOFT_COPILOT_CLIENTID=kv://microsoft-copilot/clientId');
+    lines.push('KV_MICROSOFT_COPILOT_CLIENTSECRET=kv://microsoft-copilot/clientSecret');
+  } else {
+    lines.push(`KV_${kvPrefix.toUpperCase().replace(/-/g, '_')}_APIKEY=kv://${kvPrefix}/apiKey`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} [options]
+ * @param {boolean} [options.force]
+ * @param {boolean} [options.allowExperimental]
+ * @param {string} [options.projectRoot]
+ * @returns {{ integrationDir: string, files: string[] }}
+ */
+function scaffoldChannelIntegration(channelTarget, options = {}) {
+  const target = getChannelTarget(channelTarget);
+  if (target.experimental && !options.allowExperimental) {
+    throw new Error(
+      `Channel target "${channelTarget}" is experimental. Pass --allow-experimental to scaffold.`
+    );
+  }
+
+  const integrationDir = options.projectRoot
+    ? path.join(path.resolve(options.projectRoot), 'integration', channelTarget)
+    : getIntegrationPath(channelTarget);
+  if (fs.existsSync(integrationDir) && !options.force) {
+    throw new Error(
+      `Integration folder already exists: ${integrationDir}. Use --force to overwrite generated files.`
+    );
+  }
+
+  fs.mkdirSync(integrationDir, { recursive: true });
+  const systemPath = path.join(integrationDir, `${channelTarget}-system.json`);
+  const appPath = path.join(integrationDir, 'application.json');
+  const envPath = path.join(integrationDir, 'env.template');
+  const readmePath = path.join(integrationDir, 'README.md');
+
+  fs.writeFileSync(systemPath, `${JSON.stringify(buildSystemJson(channelTarget), null, 2)}\n`, 'utf8');
+  fs.writeFileSync(appPath, `${JSON.stringify(buildApplicationJson(channelTarget), null, 2)}\n`, 'utf8');
+  fs.writeFileSync(envPath, buildEnvTemplate(channelTarget), 'utf8');
+  fs.writeFileSync(
+    readmePath,
+    [
+      `# ${channelTarget} assistant channel`,
+      '',
+      '## Two-step install',
+      '',
+      '```bash',
+      `aifabrix deploy ${channelTarget}`,
+      `aifabrix app add-channel ${channelTarget} --name "Your Assistant"`,
+      '```',
+      '',
+      'Generated by `aifabrix channel scaffold`. Secrets belong in kv:// env.template only.',
+      ''
+    ].join('\n'),
+    'utf8'
+  );
+
+  return {
+    integrationDir,
+    files: [systemPath, appPath, envPath, readmePath]
+  };
+}
+
+module.exports = {
+  buildSystemJson,
+  buildApplicationJson,
+  buildEnvTemplate,
+  scaffoldChannelIntegration
+};

package/lib/channels/channel-probe.js

@@ -0,0 +1,89 @@
+/**
+ * Channel install probe checks (plan 152).
+ *
+ * @fileoverview Callback, assistant catalog, and inbound verification probes
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('../api/index');
+const { fetchDataplaneGeneralHealth } = require('../api/dataplane-health.api');
+
+/**
+ * @async
+ * @param {string} url
+ * @returns {Promise<boolean>}
+ */
+async function isUrlReachable(url) {
+  if (!url) return false;
+  const client = new ApiClient(url.split('/api/')[0] || url);
+  try {
+    const pathPart = url.includes('/api/') ? url.substring(url.indexOf('/api/')) : '/health';
+    const res = await client.get(pathPart, { timeoutMs: 8000 });
+    return res && res.success !== false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @returns {Promise<boolean>}
+ */
+async function isAssistantCatalogReachable(dataplaneUrl, authConfig) {
+  const client = require('../api/index').createDataplaneApiClient(dataplaneUrl, authConfig);
+  try {
+    const res = await client.get('/api/v1/workers/available', { timeoutMs: 10000 });
+    return res && res.success !== false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {Object|null} channelExt
+ * @returns {Object}
+ */
+function evaluateInboundVerification(channelExt) {
+  const credentialKey = channelExt?.credentialKey || '';
+  return {
+    slackSigningSecretConfigured: credentialKey.includes('slack'),
+    teamsBotOidcValidationConfigured: credentialKey.includes('teams-bot'),
+    issuerAudienceConfigured: Boolean(channelExt?.type),
+    replayProtectionConfigured: Boolean(channelExt?.status === 'installed' || channelExt?.status === 'validated')
+  };
+}
+
+/**
+ * @async
+ * @param {Object} ctx
+ * @param {Object|null} channelExt
+ * @returns {Promise<Object>}
+ */
+async function runChannelProbe(ctx, channelExt) {
+  const health = await fetchDataplaneGeneralHealth(ctx.dataplaneUrl, { timeoutMs: 8000 });
+  const catalogOk = await isAssistantCatalogReachable(ctx.dataplaneUrl, ctx.authConfig);
+  const callbackOk = health?.status === 'healthy' || health?.status === 'ok';
+
+  const inbound = evaluateInboundVerification(channelExt);
+
+  return {
+    dataplaneHealth: health?.status || 'unknown',
+    callbackReachable: callbackOk,
+    assistantCatalogReachable: catalogOk,
+    credentialValid: Boolean(channelExt?.credentialKey),
+    inboundVerification: inbound,
+    passed: callbackOk && catalogOk && Boolean(channelExt?.credentialKey)
+  };
+}
+
+module.exports = {
+  isUrlReachable,
+  isAssistantCatalogReachable,
+  evaluateInboundVerification,
+  runChannelProbe
+};

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

@@ -0,0 +1,152 @@
+/**
+ * Resolve runtime URLs for channel templates (no hardcoded env URLs).
+ *
+ * @fileoverview Channel runtime value resolution (plan 152)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getChannelTarget } = require('./channel-targets');
+
+/**
+ * Normalize dataplane base URL (no trailing slash).
+ * @param {string} dataplaneBaseUrl
+ * @returns {string}
+ */
+function normalizeBaseUrl(dataplaneBaseUrl) {
+  if (!dataplaneBaseUrl || typeof dataplaneBaseUrl !== 'string') {
+    throw new Error('dataplaneBaseUrl is required');
+  }
+  return dataplaneBaseUrl.trim().replace(/\/+$/, '');
+}
+
+/**
+ * @param {string} base
+ * @param {string} path
+ * @returns {string}
+ */
+function joinUrl(base, path) {
+  return `${normalizeBaseUrl(base)}${path.startsWith('/') ? path : `/${path}`}`;
+}
+
+/**
+ * Dataplane external-system route prefix for webhook URLs.
+ * @param {string} routeSystemKey
+ * @returns {string}
+ */
+function externalSystemsPrefix(routeSystemKey) {
+  return `/api/v1/external/systems/${routeSystemKey}`;
+}
+
+/**
+ * Relative endpoint paths per channel target (under external/systems/{routeSystemKey}).
+ * @param {string} channelTarget
+ * @returns {Record<string, string>}
+ */
+function getEndpointPathSuffixes(channelTarget) {
+  const maps = {
+    slack: {
+      eventsUrl: '/events',
+      interactionUrl: '/interactive',
+      oauthCallbackUrl: '/oauth/callback',
+      commandUrl: '/commands'
+    },
+    'teams-bot': {
+      messagesUrl: '/messages',
+      notificationsUrl: '/notifications',
+      botConfigUrl: '/bot-config'
+    },
+    'microsoft-copilot': {
+      openapiUrl: '/openapi.yaml',
+      actionsBaseUrl: '/actions'
+    },
+    chatgpt: {
+      openapiUrl: '/openapi.yaml',
+      mcpUrl: '/mcp',
+      actionsBaseUrl: '/actions'
+    },
+    'web-embed': {
+      configUrl: '/config'
+    }
+  };
+  return maps[channelTarget] || {};
+}
+
+/**
+ * Legacy / non-external-system paths (Copilot/ChatGPT until dataplane routes exist).
+ * @param {string} channelTarget
+ * @returns {Record<string, string>}
+ */
+function getLegacyApiPaths(channelTarget) {
+  const legacy = {
+    'microsoft-copilot': {
+      openapiUrl: '/api/v1/copilot/openapi.yaml',
+      actionsBaseUrl: '/api/v1/copilot/actions'
+    },
+    chatgpt: {
+      openapiUrl: '/api/v1/chatgpt/openapi.yaml',
+      mcpUrl: '/api/v1/chatgpt/mcp',
+      actionsBaseUrl: '/api/v1/chatgpt/actions'
+    },
+    'web-embed': {
+      configUrl: '/api/v1/web-embed/config'
+    }
+  };
+  return legacy[channelTarget] || {};
+}
+
+/**
+ * @param {Object} params
+ * @param {string} params.dataplaneBaseUrl
+ * @param {string} params.channelTarget
+ * @param {string} params.appName
+ * @param {string} [params.baseName]
+ * @param {string} [params.environment]
+ * @param {string} params.appDescription
+ * @param {string} [params.icon]
+ * @returns {Object}
+ */
+function resolveChannelRuntimeValues(params) {
+  const target = getChannelTarget(params.channelTarget);
+  const base = normalizeBaseUrl(params.dataplaneBaseUrl);
+  const routeKey = target.routeSystemKey || target.key;
+  const systemPrefix = externalSystemsPrefix(routeKey);
+  const suffixes = getEndpointPathSuffixes(params.channelTarget);
+  const legacy = getLegacyApiPaths(params.channelTarget);
+
+  const resolved = {
+    dataplaneBaseUrl: base,
+    channelTarget: params.channelTarget,
+    routeSystemKey: routeKey,
+    appName: params.appName,
+    baseName: params.baseName || params.appName,
+    environment: params.environment || 'dev',
+    appDescription: params.appDescription,
+    icon: params.icon || '',
+    credentialKey: target.credentialKey,
+    assistantCatalogUrl: joinUrl(base, '/api/v1/workers/available'),
+    scopes: []
+  };
+
+  for (const [key, suffix] of Object.entries(suffixes)) {
+    resolved[key] = joinUrl(base, `${systemPrefix}${suffix}`);
+  }
+
+  for (const [key, legacyPath] of Object.entries(legacy)) {
+    if (!resolved[key]) {
+      resolved[key] = joinUrl(base, legacyPath);
+    }
+  }
+
+  return resolved;
+}
+
+module.exports = {
+  normalizeBaseUrl,
+  joinUrl,
+  externalSystemsPrefix,
+  getEndpointPathSuffixes,
+  resolveChannelRuntimeValues
+};

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

@@ -0,0 +1,141 @@
+/**
+ * TTY output for app add-channel (plan 152).
+ *
+ * @fileoverview Channel install status display — customer language: Assistant
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const {
+  formatSuccessLine,
+  formatWarningLine,
+  formatBlockingError,
+  sectionTitle,
+  metadata
+} = require('../utils/cli-test-layout-chalk');
+
+/** @returns {string} */
+function separatorLine() {
+  const gray = chalk.gray;
+  return typeof gray === 'function'
+    ? gray('────────────────────────────────────────')
+    : '────────────────────────────────────────';
+}
+
+/**
+ * @param {Object} params
+ * @param {string} params.channelTarget
+ * @param {string} params.name
+ * @param {Object|null} params.channelExt
+ * @param {string} [params.approvalUrl]
+ */
+function displayExistingChannelStatus(params) {
+  logger.log(sectionTitle(`${params.channelTarget} channel: ${params.name}`));
+  logger.log('');
+  logger.log(metadata(`Status: ${params.channelExt?.status || 'unknown'}`));
+  if (params.channelExt?.baseName && params.channelExt.baseName !== params.name) {
+    logger.log(metadata(`Base name: ${params.channelExt.baseName}`));
+  }
+  logger.log(metadata(`External System: ${params.channelTarget}`));
+  logger.log(metadata(`Credential: ${params.channelExt?.credentialKey || '—'}`));
+  if (params.channelExt?.capabilities?.length) {
+    logger.log(metadata('Capabilities:'));
+    for (const cap of params.channelExt.capabilities) {
+      logger.log(`  - ${cap}`);
+    }
+  }
+  logger.log('');
+  logger.log(formatWarningLine('Channel install already configured. Use --force to regenerate artifacts.'));
+  if (params.approvalUrl) {
+    logger.log(metadata(`Approval URL: ${params.approvalUrl}`));
+  }
+  logger.log(separatorLine());
+}
+
+/**
+ * @param {Object} result
+ */
+function displayChannelCoreFields(result) {
+  logger.log(sectionTitle(`${result.channelTarget} channel: ${result.name}`));
+  logger.log('');
+  logger.log(metadata(`Status: ${result.statusLabel}`));
+  if (result.baseName && result.baseName !== result.name) {
+    logger.log(metadata(`Base name: ${result.baseName}`));
+  }
+  logger.log(metadata(`External System: ${result.channelTarget}`));
+  logger.log(metadata(`Credential: ${result.credentialKey}`));
+  if (result.capabilities?.length) {
+    logger.log(metadata('Capabilities:'));
+    for (const cap of result.capabilities) {
+      logger.log(`  - ${cap}`);
+    }
+  }
+  if (result.artifactPath) {
+    logger.log(metadata(`Artifact: ${result.artifactPath}`));
+  }
+  if (result.installGuidePath) {
+    logger.log(metadata(`Install guide: ${result.installGuidePath}`));
+  }
+}
+
+/**
+ * @param {Object|null} validation
+ */
+function displayValidationSection(validation) {
+  if (!validation) return;
+  logger.log('');
+  logger.log(metadata('Validation:'));
+  if (validation.callbackReachable) {
+    logger.log(formatSuccessLine('Callback reachable'));
+  }
+  if (validation.credentialValid) {
+    logger.log(formatSuccessLine('Credential valid'));
+  }
+  if (validation.assistantCatalogReachable) {
+    logger.log(formatSuccessLine('Assistant catalog reachable'));
+  }
+  if (validation.inboundVerification) {
+    logger.log(formatSuccessLine('Inbound verification configured'));
+  }
+}
+
+/**
+ * @param {Object} result
+ */
+function displayApprovalSection(result) {
+  if (!result.approvalUrl) return;
+  logger.log('');
+  logger.log(formatWarningLine('Approval required'));
+  logger.log(metadata('Open this URL as platform admin:'));
+  logger.log(chalk.cyan(result.approvalUrl));
+  logger.log('');
+  logger.log(metadata('After approval, run:'));
+  logger.log(chalk.white(`  aifabrix app add-channel ${result.channelTarget} --name "${result.name}"`));
+}
+
+/**
+ * @param {Object} result
+ */
+function displayChannelInstallResult(result) {
+  displayChannelCoreFields(result);
+  displayValidationSection(result.validation);
+  displayApprovalSection(result);
+  logger.log(separatorLine());
+}
+
+/**
+ * @param {string} message
+ */
+function displayChannelError(message) {
+  logger.error(formatBlockingError(message));
+}
+
+module.exports = {
+  displayExistingChannelStatus,
+  displayChannelInstallResult,
+  displayChannelError
+};