@aifabrix/builder 2.49.1 → 2.50.0

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.'
   );
 }
 

package/lib/cli/index.js

@@ -23,15 +23,19 @@ const { setupAppCommands: setupAppManagementCommands } = require('../commands/ap
 const { setupDatasourceCommands } = require('../commands/datasource');
 const { setupDimensionCommands } = require('../commands/dimension');
 const { setupResourceTypeCommands } = require('../commands/resource-type');
+const { setupEnterpriseKnowledgeCommands } = require('../commands/enterprise-knowledge');
 const { setupIdentityCommands } = require('../commands/identity');
 const { setupProtectionCommands } = require('../commands/protection');
+const { setupEvidenceCommands } = require('../commands/evidence');
 const { setupCredentialDeploymentCommands } = require('./setup-credential-deployment');
 const { setupIntegrationClientCommands } = require('./setup-integration-client');
 const { setupPlatformCommands } = require('./setup-platform');
 const { setupCertificationCommands } = require('./setup-certification-commands');
 const { setupGovernanceCommands } = require('../commands/governance');
 const { setupChannelCommands } = require('../commands/channel');
+const { setupManifestCommands } = require('../commands/manifest');
 const { setupNpmCommands } = require('./setup-npm');
+const { setupListCommand } = require('./setup-list');
 
 /**
  * Dev, secrets, parameters, and platform commands (keeps setupCommands under statement limit).
@@ -46,10 +50,10 @@ function setupDevAndPlatformCommands(program) {
 }
 
 /**
- * Sets up all CLI commands on the Commander program instance
- * @param {Command} program - Commander program instance
+ * Core platform and integration CLI command groups.
+ * @param {import('commander').Command} program
  */
-function setupCommands(program) {
+function setupCoreCliCommands(program) {
   setupInfraCommands(program);
   setupAuthCommands(program);
   setupAppCommands(program);
@@ -59,14 +63,34 @@ function setupCommands(program) {
   setupAppManagementCommands(program);
   setupChannelCommands(program);
   setupDatasourceCommands(program);
+  setupManifestCommands(program);
+}
+
+/**
+ * Extended catalog and policy CLI command groups.
+ * @param {import('commander').Command} program
+ */
+function setupExtendedCliCommands(program) {
   setupDimensionCommands(program);
   setupResourceTypeCommands(program);
+  setupEnterpriseKnowledgeCommands(program);
   setupIdentityCommands(program);
   setupProtectionCommands(program);
+  setupEvidenceCommands(program);
   setupUtilityCommands(program);
+  setupListCommand(program);
   setupCredentialDeploymentCommands(program);
   setupIntegrationClientCommands(program);
   setupExternalSystemCommands(program);
+}
+
+/**
+ * Sets up all CLI commands on the Commander program instance
+ * @param {Command} program - Commander program instance
+ */
+function setupCommands(program) {
+  setupCoreCliCommands(program);
+  setupExtendedCliCommands(program);
   setupDevAndPlatformCommands(program);
 }
 

package/lib/cli/infra-guided.js

@@ -15,6 +15,7 @@ const infra = require('../infrastructure');
 const { execWithDockerEnv } = require('../utils/docker-exec');
 const { getLogLevel, passesLevelFilter } = require('../commands/app-logs');
 const { handleLogin } = require('../commands/login');
+const { handleUpBuilderApi } = require('../commands/up-builder-api');
 const {
   resolveGuidedAuthControllerUrl,
   runGuidedAuthStep,
@@ -309,7 +310,10 @@ async function runGuidedUpPlatform(options, handleUpMiso, handleUpDataplane, han
   await runGuidedAuthStep(handleLogin, authOpts, { startSpinner, stopSpinnerSuccess });
   const controllerUrl = await resolveGuidedAuthControllerUrl(authOpts);
   await runGuidedDataplaneInstallPhase(options, handleUpDataplane, handleLogin, controllerUrl);
-  await validateAppErrorLogs(['miso-controller', 'dataplane']);
+  const baSpin = startSpinner('Starting builder-api...');
+  await withMutedLogger(() => handleUpBuilderApi({ ...options, platformInstall: true }));
+  stopSpinnerSuccess(baSpin, 'Builder API ready');
+  await validateAppErrorLogs(['miso-controller', 'dataplane', 'builder-api']);
   await logPlatformReadyFooter();
 }
 

package/lib/cli/setup-app-external-create.js

@@ -0,0 +1,111 @@
+/**
+ * External-system create option normalization for setup-app.js.
+ *
+ * @fileoverview Headless external create CLI helpers
+ */
+
+const VALID_ENTITY_TYPES = ['recordStorage', 'documentStorage', 'vectorStore', 'messageService', 'none'];
+
+/**
+ * Normalize options for external system creation
+ * @param {Object} options - Raw CLI options
+ * @returns {Object} Normalized options
+ */
+function normalizeExternalOptions(options) {
+  const normalized = { ...options };
+  if (options.displayName) normalized.systemDisplayName = options.displayName;
+  if (options.description) normalized.systemDescription = options.description;
+  if (options.systemType) normalized.systemType = options.systemType;
+  if (options.authType) normalized.authType = options.authType;
+  if (options.entityType) {
+    if (!VALID_ENTITY_TYPES.includes(options.entityType)) {
+      throw new Error(`Invalid --entity-type. Must be one of: ${VALID_ENTITY_TYPES.join(', ')}`);
+    }
+    normalized.entityType = options.entityType;
+  }
+  if (options.datasources !== undefined) {
+    const parsedCount = parseInt(options.datasources, 10);
+    if (Number.isNaN(parsedCount) || parsedCount < 1 || parsedCount > 10) {
+      throw new Error('Datasources count must be a number between 1 and 10');
+    }
+    normalized.datasourceCount = parsedCount;
+  }
+  if (options.controller) {
+    normalized.controller = true;
+    normalized.controllerUrl = options.controller;
+  }
+  return normalized;
+}
+
+/**
+ * Whether normalized options include all external CLI fields for headless create.
+ * @param {Object} normalized - Normalized external create options
+ * @returns {boolean}
+ */
+function hasFullExternalCliOptions(normalized) {
+  return Boolean(
+    normalized.systemKey &&
+    normalized.systemDisplayName &&
+    normalized.systemDescription &&
+    normalized.systemType &&
+    normalized.authType &&
+    normalized.entityType &&
+    normalized.datasourceCount
+  );
+}
+
+/**
+ * Map positional systemKey and apply headless defaults for external create.
+ * @param {string} appName - Positional appKey or systemKey from CLI
+ * @param {Object} options - Raw CLI options
+ * @returns {Object} Normalized options ready for createApp
+ */
+function prepareExternalCreateOptions(appName, options) {
+  const normalized = normalizeExternalOptions(options);
+  const isExternalType = options.type === 'external' || !options.type;
+
+  if (isExternalType && appName) {
+    normalized.systemKey = appName;
+  }
+
+  if (isExternalType && hasFullExternalCliOptions(normalized)) {
+    if (!Object.prototype.hasOwnProperty.call(normalized, 'github')) {
+      normalized.github = false;
+    }
+    if (!Object.prototype.hasOwnProperty.call(normalized, 'controller')) {
+      normalized.controller = false;
+    }
+  }
+
+  return normalized;
+}
+
+/**
+ * Validate required options for non-interactive external creation
+ * @param {Object} normalizedOptions - Normalized options
+ * @throws {Error} If required options are missing
+ */
+function validateNonInteractiveExternalOptions(normalizedOptions) {
+  const missing = [];
+  if (!normalizedOptions.systemDisplayName) missing.push('--display-name');
+  if (!normalizedOptions.systemDescription) missing.push('--description');
+  if (!normalizedOptions.systemType) missing.push('--system-type');
+  if (!normalizedOptions.authType) missing.push('--auth-type');
+  if (!normalizedOptions.entityType) missing.push('--entity-type');
+  if (!normalizedOptions.datasourceCount) missing.push('--datasources');
+  if (missing.length > 0) {
+    throw new Error(`Missing required options for non-interactive external create: ${missing.join(', ')}`);
+  }
+  if (!Object.prototype.hasOwnProperty.call(normalizedOptions, 'github')) {
+    normalizedOptions.github = false;
+  }
+  if (!Object.prototype.hasOwnProperty.call(normalizedOptions, 'controller')) {
+    normalizedOptions.controller = false;
+  }
+}
+
+module.exports = {
+  normalizeExternalOptions,
+  prepareExternalCreateOptions,
+  validateNonInteractiveExternalOptions
+};

package/lib/cli/setup-app.help.js

@@ -56,7 +56,7 @@ Examples:
 Notes:
   - To run E2E for one datasource, use:
       aifabrix datasource test-e2e <datasourceKey>
-  - External integration: local system and datasource files are published to the dataplane before E2E (same as upload). Use --no-sync to exercise only config already deployed.
+  - External integration: local system and datasource files are published to the dataplane before E2E (same as upload). Use --no-publish to exercise only config already deployed.
 `;
 
 const IDENTITY_HELP_AFTER = `