@aifabrix/builder 2.49.2 → 2.51.0

package/lib/channels/channel-description.js

@@ -0,0 +1,59 @@
+/**
+ * Slack manifest description limits (plan 152).
+ *
+ * @fileoverview Enforce Slack display_information.description max length
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** Slack manifest `display_information.description` max (api.slack.com/reference/manifests). */
+const SLACK_APP_DESCRIPTION_MAX_LENGTH = 140;
+
+/**
+ * @param {string} description
+ * @returns {string}
+ */
+function normalizeSlackAppDescription(description) {
+  const text = String(description ?? '').trim();
+  if (!text || text.length <= SLACK_APP_DESCRIPTION_MAX_LENGTH) {
+    return text;
+  }
+  return `${text.slice(0, SLACK_APP_DESCRIPTION_MAX_LENGTH - 1)}…`;
+}
+
+/**
+ * @param {string} description
+ * @returns {string}
+ * @throws {Error}
+ */
+function assertSlackAppDescription(description) {
+  const text = String(description ?? '').trim();
+  if (text.length > SLACK_APP_DESCRIPTION_MAX_LENGTH) {
+    throw new Error(
+      `Slack app description must be at most ${SLACK_APP_DESCRIPTION_MAX_LENGTH} characters (got ${text.length}). Provide a shorter --description.`
+    );
+  }
+  return text;
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {string} description
+ * @returns {string}
+ */
+function resolveAppDescription(channelTarget, description) {
+  const text = String(description ?? '').trim();
+  if (channelTarget === 'slack') {
+    return assertSlackAppDescription(text);
+  }
+  return text;
+}
+
+module.exports = {
+  SLACK_APP_DESCRIPTION_MAX_LENGTH,
+  normalizeSlackAppDescription,
+  assertSlackAppDescription,
+  resolveAppDescription
+};

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

@@ -1,9 +1,11 @@
 /**
- * Generate integration/<channelTarget>/ for communication external systems (plan 152).
+ * Scaffold integration/<channelTarget>/ from published templates (plan 152).
+ * Manifest SSOT: dataplane integration/ (slack via make sync-json) → templates/channels/{target}/integration/.
+ * Builder generates only *-deploy.json at scaffold time.
  *
- * @fileoverview Builder generator for channel deploy step 1 scaffolds
+ * @fileoverview Channel integration scaffold — template copy + deploy JSON
  * @author AI Fabrix Team
- * @version 1.0.0
+ * @version 2.0.0
  */
 
 'use strict';
@@ -12,201 +14,8 @@ 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');
-}
+const { copyChannelIntegrationTemplate } = require('./channel-integration-template');
+const { generateDeployJson } = require('../generator/index');
 
 /**
  * @param {string} channelTarget
@@ -214,9 +23,9 @@ function buildEnvTemplate(channelTarget) {
  * @param {boolean} [options.force]
  * @param {boolean} [options.allowExperimental]
  * @param {string} [options.projectRoot]
- * @returns {{ integrationDir: string, files: string[] }}
+ * @returns {Promise<{ integrationDir: string, files: string[] }>}
  */
-function scaffoldChannelIntegration(channelTarget, options = {}) {
+async function scaffoldChannelIntegration(channelTarget, options = {}) {
   const target = getChannelTarget(channelTarget);
   if (target.experimental && !options.allowExperimental) {
     throw new Error(
@@ -233,42 +42,16 @@ function scaffoldChannelIntegration(channelTarget, options = {}) {
     );
   }
 
-  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'
-  );
+  const copied = copyChannelIntegrationTemplate(channelTarget, integrationDir);
+  const deployPath = await generateDeployJson(channelTarget, { appPath: integrationDir });
+  const files = [...copied, deployPath];
 
   return {
     integrationDir,
-    files: [systemPath, appPath, envPath, readmePath]
+    files
   };
 }
 
 module.exports = {
-  buildSystemJson,
-  buildApplicationJson,
-  buildEnvTemplate,
   scaffoldChannelIntegration
 };

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

@@ -0,0 +1,94 @@
+/**
+ * Channel integration templates — copied from templates/channels/<target>/integration/.
+ * SSOT for slack: aifabrix-dataplane/integration/slack (make sync-json in dataplane).
+ *
+ * @fileoverview Template resolution and copy for channel scaffold (plan 152)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { nodeFs } = require('../internal/node-fs');
+const fs = nodeFs();
+const path = require('path');
+const { getChannelTarget } = require('./channel-targets');
+
+const BUILDER_ROOT = path.join(__dirname, '..', '..');
+
+/** @type {RegExp[]} */
+const SKIP_TEMPLATE_FILE = [
+  /^\./,
+  /-deploy\.json$/,
+  /^INTEGRATION_CHANGELOG\.md$/i
+];
+
+/**
+ * @param {string} channelTarget
+ * @returns {string}
+ */
+function getChannelIntegrationTemplateDir(channelTarget) {
+  const target = getChannelTarget(channelTarget);
+  return path.join(BUILDER_ROOT, 'templates', 'channels', target.templateDir, 'integration');
+}
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+function shouldCopyTemplateFile(name) {
+  return !SKIP_TEMPLATE_FILE.some((pattern) => pattern.test(name));
+}
+
+/**
+ * @param {string} templateDir
+ * @returns {string[]}
+ */
+function listChannelIntegrationTemplateFiles(templateDir) {
+  if (!fs.existsSync(templateDir)) {
+    return [];
+  }
+  return fs
+    .readdirSync(templateDir)
+    .filter((name) => {
+      const full = path.join(templateDir, name);
+      return fs.statSync(full).isFile() && shouldCopyTemplateFile(name);
+    })
+    .sort();
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {string} integrationDir
+ * @returns {string[]} Copied file paths
+ */
+function copyChannelIntegrationTemplate(channelTarget, integrationDir) {
+  const templateDir = getChannelIntegrationTemplateDir(channelTarget);
+  const names = listChannelIntegrationTemplateFiles(templateDir);
+  if (names.length === 0) {
+    throw new Error(
+      `Channel integration template missing for "${channelTarget}" (${templateDir}). ` +
+        'For slack: edit aifabrix-dataplane/integration/slack and run make sync-json. ' +
+        'For other targets: add templates/channels/<target>/integration/ until dataplane SSOT exists.'
+    );
+  }
+
+  fs.mkdirSync(integrationDir, { recursive: true });
+  const copied = [];
+  for (const name of names) {
+    const src = path.join(templateDir, name);
+    const dest = path.join(integrationDir, name);
+    fs.copyFileSync(src, dest);
+    copied.push(dest);
+  }
+  return copied;
+}
+
+module.exports = {
+  BUILDER_ROOT,
+  SKIP_TEMPLATE_FILE,
+  getChannelIntegrationTemplateDir,
+  shouldCopyTemplateFile,
+  listChannelIntegrationTemplateFiles,
+  copyChannelIntegrationTemplate
+};

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

@@ -9,6 +9,10 @@
 'use strict';
 
 const { getChannelTarget } = require('./channel-targets');
+const { normalizeSlackAppDescription } = require('./channel-description');
+
+/** Default Slack slash prefix — matches dataplane `templates/slack/command_catalog.yaml`. */
+const DEFAULT_SLACK_COMMAND_PREFIX = 'af';
 
 /**
  * Normalize dataplane base URL (no trailing slash).
@@ -50,7 +54,6 @@ function getEndpointPathSuffixes(channelTarget) {
     slack: {
       eventsUrl: '/events',
       interactionUrl: '/interactive',
-      oauthCallbackUrl: '/oauth/callback',
       commandUrl: '/commands'
     },
     'teams-bot': {
@@ -97,6 +100,26 @@ function getLegacyApiPaths(channelTarget) {
   return legacy[channelTarget] || {};
 }
 
+/**
+ * Slack token rotation requires OAuth redirect URLs (api.slack.com app manifest).
+ * @param {string|undefined} oauthCallbackUrl
+ * @returns {{ oauthCallbackUrl?: string, slackRedirectUrlsJson: string, slackTokenRotationEnabled: boolean }}
+ */
+function resolveSlackOAuthManifestFields(oauthCallbackUrl) {
+  const url = typeof oauthCallbackUrl === 'string' ? oauthCallbackUrl.trim() : '';
+  if (!url) {
+    return {
+      slackRedirectUrlsJson: '[]',
+      slackTokenRotationEnabled: false
+    };
+  }
+  return {
+    oauthCallbackUrl: url,
+    slackRedirectUrlsJson: JSON.stringify([url]),
+    slackTokenRotationEnabled: true
+  };
+}
+
 /**
  * @param {Object} params
  * @param {string} params.dataplaneBaseUrl
@@ -106,6 +129,7 @@ function getLegacyApiPaths(channelTarget) {
  * @param {string} [params.environment]
  * @param {string} params.appDescription
  * @param {string} [params.icon]
+ * @param {string} [params.commandPrefix] Slack slash alias prefix (default `af`)
  * @returns {Object}
  */
 function resolveChannelRuntimeValues(params) {
@@ -123,9 +147,13 @@ function resolveChannelRuntimeValues(params) {
     appName: params.appName,
     baseName: params.baseName || params.appName,
     environment: params.environment || 'dev',
-    appDescription: params.appDescription,
+    appDescription:
+      params.channelTarget === 'slack'
+        ? normalizeSlackAppDescription(params.appDescription)
+        : params.appDescription,
     icon: params.icon || '',
     credentialKey: target.credentialKey,
+    credentialPortalUrl: joinUrl(base, `/connected-systems/${params.channelTarget}?tab=authentication`),
     assistantCatalogUrl: joinUrl(base, '/api/v1/workers/available'),
     scopes: []
   };
@@ -140,6 +168,16 @@ function resolveChannelRuntimeValues(params) {
     }
   }
 
+  if (params.channelTarget === 'slack') {
+    const oauthCallbackUrl = params.oauthCallbackUrl || resolved.oauthCallbackUrl;
+    Object.assign(resolved, resolveSlackOAuthManifestFields(oauthCallbackUrl));
+    const prefix =
+      typeof params.commandPrefix === 'string' && params.commandPrefix.trim()
+        ? params.commandPrefix.trim()
+        : DEFAULT_SLACK_COMMAND_PREFIX;
+    resolved.commandPrefix = prefix;
+  }
+
   return resolved;
 }
 
@@ -148,5 +186,7 @@ module.exports = {
   joinUrl,
   externalSystemsPrefix,
   getEndpointPathSuffixes,
-  resolveChannelRuntimeValues
+  resolveSlackOAuthManifestFields,
+  resolveChannelRuntimeValues,
+  DEFAULT_SLACK_COMMAND_PREFIX
 };

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

@@ -1,5 +1,5 @@
 /**
- * TTY output for app add-channel (plan 152).
+ * TTY output for channel add (plan 152).
  *
  * @fileoverview Channel install status display — customer language: Assistant
  * @author AI Fabrix Team
@@ -26,32 +26,79 @@ function separatorLine() {
     : '────────────────────────────────────────';
 }
 
+/**
+ * @param {Object|null} approvalGuide
+ */
+function displayApprovalGuideOptionalLinks(approvalGuide) {
+  if (approvalGuide.artifactPath) {
+    logger.log('');
+    logger.log(metadata('Manifest file:'));
+    logger.log(chalk.white(approvalGuide.artifactPath));
+  }
+  if (approvalGuide.credentialPortalUrl) {
+    logger.log('');
+    logger.log(metadata('AI Fabrix authentication:'));
+    logger.log(chalk.cyan(approvalGuide.credentialPortalUrl));
+  }
+  if (approvalGuide.installGuidePath) {
+    logger.log('');
+    logger.log(metadata(`Full guide: ${approvalGuide.installGuidePath}`));
+  }
+}
+
+/**
+ * @param {Object|null} approvalGuide
+ */
+function displayApprovalGuideSection(approvalGuide) {
+  if (!approvalGuide?.steps?.length) return;
+  logger.log('');
+  const heading =
+    approvalGuide.approvalRequired === false
+      ? 'Go-live steps'
+      : 'Platform admin approval required';
+  logger.log(formatWarningLine(heading));
+  if (approvalGuide.portalUrl) {
+    logger.log(metadata('Admin console:'));
+    logger.log(chalk.cyan(approvalGuide.portalUrl));
+  }
+  logger.log('');
+  logger.log(metadata('Next steps:'));
+  approvalGuide.steps.forEach((step, index) => {
+    logger.log(chalk.white(`  ${index + 1}. ${step}`));
+  });
+  displayApprovalGuideOptionalLinks(approvalGuide);
+}
+
 /**
  * @param {Object} params
  * @param {string} params.channelTarget
  * @param {string} params.name
  * @param {Object|null} params.channelExt
- * @param {string} [params.approvalUrl]
+ * @param {Object|null} [params.approvalGuide]
  */
 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}`);
-    }
+  const status = params.channelExt?.status || 'unknown';
+  displayChannelCoreFields({
+    channelTarget: params.channelTarget,
+    name: params.name,
+    statusLabel: status,
+    baseName: params.channelExt?.baseName,
+    credentialKey: params.channelExt?.credentialKey,
+    capabilities: params.channelExt?.capabilities
+  });
+
+  if (status === 'approvalRequired' && params.approvalGuide) {
+    displayApprovalGuideSection(params.approvalGuide);
+    logger.log(separatorLine());
+    return;
   }
+
   logger.log('');
-  logger.log(formatWarningLine('Channel install already configured. Use --force to regenerate artifacts.'));
-  if (params.approvalUrl) {
-    logger.log(metadata(`Approval URL: ${params.approvalUrl}`));
+  if (status === 'installed' || status === 'validated') {
+    logger.log(formatSuccessLine('Channel install is complete.'));
+    logger.log(metadata('Use --force to regenerate artifacts and patch config.'));
+  } else {
+    logger.log(formatWarningLine('Channel install already configured. Use --force to regenerate artifacts.'));
   }
   logger.log(separatorLine());
 }
@@ -107,14 +154,7 @@ function displayValidationSection(validation) {
  * @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}"`));
+  displayApprovalGuideSection(result.approvalGuide);
 }
 
 /**

package/lib/channels/channel-targets.js

@@ -10,7 +10,7 @@
 
 /** @typedef {'teams-bot'|'slack'|'microsoft-copilot'|'chatgpt'|'web-embed'} ChannelTargetKey */
 
-const DEFAULT_CAPABILITIES = ['chat', 'notify'];
+const DEFAULT_CAPABILITIES = ['chat', 'notify', 'documentApproval'];
 
 const CHANNEL_TARGETS = {
   'teams-bot': {
@@ -101,8 +101,8 @@ function getChannelTarget(channelTarget) {
  */
 function getDefaultChannelDescription() {
   return (
-    'Enterprise AI assistant for employees. Provides access to approved assistants, ' +
-    'enterprise knowledge, business workflows, and governed actions through AI Fabrix.'
+    'Enterprise AI assistant for employees. Approved assistants, enterprise knowledge, ' +
+    'workflows, and governed actions via AI Fabrix.'
   );
 }