@aifabrix/builder 2.53.1 → 2.54.1

package/lib/channels/channel-add-wizard-config.js

@@ -0,0 +1,138 @@
+/**
+ * Wizard prompts from Channel Definition configuration/portalInput.
+ *
+ * @fileoverview Prompt only required missing portal fields
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const inquirer = require('inquirer');
+const { getChannelDefinition } = require('./channel-definition-registry');
+const {
+  envNameToPropertyKey,
+  listDefinitionConfiguration,
+  isSecretShapedValue
+} = require('./channel-configuration-map');
+
+/**
+ * @param {unknown} options
+ * @returns {boolean}
+ */
+function isTrueFalseOptions(options) {
+  if (!Array.isArray(options) || options.length !== 2) {
+    return false;
+  }
+  const values = new Set(options.map((item) => String(item).trim().toLowerCase()));
+  return values.has('true') && values.has('false');
+}
+
+/**
+ * @param {string} field
+ * @param {unknown} [options]
+ * @returns {string}
+ */
+function inquirerTypeForPortalField(field, options) {
+  if (isTrueFalseOptions(options)) {
+    return 'confirm';
+  }
+  if (field === 'select') {
+    return 'list';
+  }
+  if (field === 'password') {
+    return 'password';
+  }
+  return 'input';
+}
+
+/**
+ * @param {Object} options
+ * @param {string} propertyKey
+ * @returns {boolean}
+ */
+function isMissingConfigValue(options, propertyKey) {
+  const value = options[propertyKey];
+  return value === undefined || value === null || value === '';
+}
+
+/**
+ * @param {Object} row
+ * @param {Object} options
+ * @returns {boolean}
+ */
+function shouldPromptConfigurationRow(row, options) {
+  if (!row || !row.portalInput || !row.portalInput.label) {
+    return false;
+  }
+  if (isSecretShapedValue(row.value)) {
+    return false;
+  }
+  const propertyKey = envNameToPropertyKey(row.name);
+  if (!isMissingConfigValue(options, propertyKey)) {
+    return false;
+  }
+  return row.required === true;
+}
+
+/**
+ * @param {Object} row
+ * @returns {Object}
+ */
+function configurationQuestionFromRow(row) {
+  const portal = row.portalInput;
+  const propertyKey = envNameToPropertyKey(row.name);
+  const question = {
+    type: inquirerTypeForPortalField(portal.field, portal.options),
+    name: propertyKey,
+    message: portal.label
+  };
+  if (question.type === 'confirm') {
+    question.default = /^(true|1|yes|on)$/i.test(String(row.value || ''));
+    return question;
+  }
+  if (portal.placeholder) {
+    question.default = portal.placeholder;
+  }
+  if (Array.isArray(portal.options)) {
+    question.choices = portal.options;
+  }
+  return question;
+}
+
+/**
+ * @param {Object} definition
+ * @param {Object} [options]
+ * @returns {Object[]}
+ */
+function missingConfigurationQuestions(definition, options = {}) {
+  return listDefinitionConfiguration(definition)
+    .filter((row) => shouldPromptConfigurationRow(row, options))
+    .map(configurationQuestionFromRow);
+}
+
+/**
+ * @param {string} definitionKey
+ * @param {Object} options
+ * @param {Object} [deps]
+ * @returns {Promise<Object>}
+ */
+async function promptMissingDefinitionConfiguration(definitionKey, options, deps = {}) {
+  const definition = getChannelDefinition(definitionKey);
+  if (!definition) {
+    return {};
+  }
+  const questions = missingConfigurationQuestions(definition, options);
+  if (questions.length === 0) {
+    return {};
+  }
+  const prompt = deps.prompt || ((qs) => inquirer.prompt(qs));
+  return prompt(questions);
+}
+
+module.exports = {
+  inquirerTypeForPortalField,
+  shouldPromptConfigurationRow,
+  missingConfigurationQuestions,
+  promptMissingDefinitionConfiguration
+};

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

@@ -0,0 +1,250 @@
+/**
+ * Interactive prompts when `aifabrix channel add` omits the channel target.
+ *
+ * @fileoverview TTY wizard for name + live channel selection; no mutations until dispatch
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const inquirer = require('inquirer');
+const config = require('../core/config');
+const {
+  formatSupportedChannelTargetsHelp,
+  listWizardChannelChoices
+} = require('./channel-targets');
+const { listMcpClientProfileChoices } = require('./mcp-client/profiles');
+const { promptMissingDefinitionConfiguration } = require('./channel-add-wizard-config');
+
+const CHANNEL_ADD_CANCELLED = 'CHANNEL_ADD_CANCELLED';
+
+/**
+ * Usage text when the wizard cannot run (CI, non-TTY, JSON).
+ * @returns {string}
+ */
+function formatNonInteractiveChannelAddError() {
+  return [
+    'Channel add needs a terminal to choose a channel, or an explicit target:',
+    '  $ aifabrix channel add slack --name "Elsa"',
+    formatSupportedChannelTargetsHelp()
+  ].join('\n');
+}
+
+/**
+ * @param {Error|null|undefined} error
+ * @returns {boolean}
+ */
+function isChannelAddCancelled(error) {
+  return Boolean(error && error.code === CHANNEL_ADD_CANCELLED);
+}
+
+/**
+ * @returns {Error}
+ */
+function createChannelAddCancelledError() {
+  const error = new Error('Channel add cancelled.');
+  error.code = CHANNEL_ADD_CANCELLED;
+  return error;
+}
+
+/**
+ * @param {Error} error
+ * @returns {boolean}
+ */
+function isInquirerCancel(error) {
+  if (!error) {
+    return false;
+  }
+  if (error.name === 'ExitPromptError') {
+    return true;
+  }
+  const message = String(error.message || '');
+  return /force closed|user force closed|prompt was canceled/i.test(message);
+}
+
+/**
+ * TTY wizard only; CI and JSON stay on the explicit command.
+ * @param {Object} [options]
+ * @returns {boolean}
+ */
+function isChannelAddInteractive(options = {}) {
+  if (options.json === true) {
+    return false;
+  }
+  if (process.env.CI === 'true' || process.env.CI === '1') {
+    return false;
+  }
+  return Boolean(process.stdin && process.stdin.isTTY);
+}
+
+/**
+ * @param {string} value
+ * @returns {true|string}
+ */
+function validateChannelName(value) {
+  if (!value || !String(value).trim()) {
+    return 'Channel name is required';
+  }
+  return true;
+}
+
+/**
+ * @returns {{ type: string, name: string, message: string, validate: Function }}
+ */
+function channelNameQuestion() {
+  return {
+    type: 'input',
+    name: 'name',
+    message: 'Channel name:',
+    validate: validateChannelName
+  };
+}
+
+/**
+ * @param {Object} options
+ * @returns {{ type: string, name: string, message: string, choices: Object[] }}
+ */
+function mcpClientProfileQuestion(options = {}) {
+  const already = options.target || options.profile || options.mcpClientProfile;
+  return {
+    type: 'list',
+    name: 'mcpClientProfile',
+    message: 'MCP client:',
+    choices: listMcpClientProfileChoices(),
+    when: (answers) => answers.channelTarget === 'mcp-client' && !already
+  };
+}
+
+/**
+ * @param {Object} options
+ * @returns {{ type: string, name: string, message: string, choices: Object[] }}
+ */
+function channelTargetQuestion(options = {}) {
+  const choices = listWizardChannelChoices({
+    allowExperimental: options.allowExperimental === true
+  });
+  return {
+    type: 'list',
+    name: 'channelTarget',
+    message: 'Select channel:',
+    choices
+  };
+}
+
+/**
+ * @returns {{ type: string, name: string, message: string, default: string }}
+ */
+function channelEnvironmentQuestion() {
+  return {
+    type: 'input',
+    name: 'environment',
+    message: 'Environment:',
+    default: 'dev'
+  };
+}
+
+/**
+ * @param {Object} [deps]
+ * @returns {Promise<string>}
+ */
+async function resolveWizardEnvironment(deps = {}) {
+  const resolveEnvironment = deps.resolveEnvironment || (() => config.resolveEnvironment());
+  const env = await resolveEnvironment();
+  return env && String(env).trim() ? String(env).trim() : '';
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} [deps]
+ * @returns {Promise<Object[]>}
+ */
+async function buildChannelAddWizardQuestions(options = {}, deps = {}) {
+  const questions = [];
+  if (!options.name || !String(options.name).trim()) {
+    questions.push(channelNameQuestion());
+  }
+  questions.push(channelTargetQuestion(options));
+  questions.push(mcpClientProfileQuestion(options));
+  const env = await resolveWizardEnvironment(deps);
+  if (!env) {
+    questions.push(channelEnvironmentQuestion());
+  }
+  return questions;
+}
+
+/**
+ * @param {Object[]} questions
+ * @param {Object} [deps]
+ * @returns {Promise<Object>}
+ */
+async function runChannelAddWizardPrompt(questions, deps = {}) {
+  const prompt = deps.prompt || ((qs) => inquirer.prompt(qs));
+  try {
+    return await prompt(questions);
+  } catch (error) {
+    if (isInquirerCancel(error)) {
+      throw createChannelAddCancelledError();
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} [deps]
+ * @returns {void}
+ */
+function assertChannelAddWizardInteractive(options = {}, deps = {}) {
+  const isInteractive = deps.isInteractive || isChannelAddInteractive;
+  if (!isInteractive(options)) {
+    throw new Error(formatNonInteractiveChannelAddError());
+  }
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} answers
+ * @returns {{ channelTarget: string, name: string, environment?: string, mcpClientProfile?: string }}
+ */
+function selectionFromWizardAnswers(options, answers) {
+  const name = String(answers.name || options.name || '').trim();
+  if (validateChannelName(name) !== true) {
+    throw new Error('Channel name is required');
+  }
+  return {
+    channelTarget: answers.channelTarget,
+    name,
+    environment: answers.environment,
+    mcpClientProfile: answers.mcpClientProfile || options.target || options.profile
+  };
+}
+
+/**
+ * Prompt for missing channel add inputs. Does not write files or credentials.
+ * @param {Object} [options]
+ * @param {Object} [deps] - Inject prompt / resolveEnvironment / isInteractive in tests
+ * @returns {Promise<{ channelTarget: string, name: string, environment?: string }>}
+ */
+async function promptChannelAddWizard(options = {}, deps = {}) {
+  assertChannelAddWizardInteractive(options, deps);
+  const questions = await buildChannelAddWizardQuestions(options, deps);
+  const answers = await runChannelAddWizardPrompt(questions, deps);
+  const selection = selectionFromWizardAnswers(options, answers);
+  const config = await promptMissingDefinitionConfiguration(
+    selection.channelTarget,
+    { ...options, ...selection },
+    deps
+  );
+  return { ...selection, ...config };
+}
+
+module.exports = {
+  CHANNEL_ADD_CANCELLED,
+  formatNonInteractiveChannelAddError,
+  isChannelAddCancelled,
+  isChannelAddInteractive,
+  validateChannelName,
+  buildChannelAddWizardQuestions,
+  promptChannelAddWizard
+};

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

@@ -15,6 +15,7 @@ const Handlebars = require('handlebars');
 const { getChannelTarget } = require('./channel-targets');
 const { BUILDER_ROOT } = require('./channel-integration-template');
 const { generateMicrosoftCopilotPackage } = require('./microsoft-copilot-package');
+const { fillSlackManifestDescriptions } = require('./channel-description');
 
 const SECRET_PATTERNS = [/xoxb-/i, /xoxp-/i, /client_secret/i, /signing_secret/i, /Bearer\s+/i];
 const PLACEHOLDER_DOMAIN_RE = /\byour-domain\.com\b/i;
@@ -106,6 +107,23 @@ function renderInstallGuideIfPresent(templatesDir, runtimeValues, outputDir, dry
   return { installPath, content };
 }
 
+/**
+ * @param {Object} params
+ * @param {string} templatesDir
+ * @param {string} outputPath
+ * @returns {{ outputPath: string, artifactHash: string, content: string, installPath?: string }}
+ */
+function generateCopilotChannelArtifact(params, templatesDir, outputPath) {
+  return generateMicrosoftCopilotPackage({
+    runtimeValues: params.runtimeValues,
+    templatesDir,
+    outputPath,
+    dryRun: params.dryRun === true,
+    assertNoSecretsInArtifact,
+    renderTemplateFile
+  });
+}
+
 /**
  * @param {Object} params
  * @param {string} params.projectRoot
@@ -117,20 +135,16 @@ function renderInstallGuideIfPresent(templatesDir, runtimeValues, outputDir, dry
 function generateChannelArtifact(params) {
   const templatesDir = getChannelTemplatesDir(params.channelTarget);
   const outputPath = getArtifactOutputPath(params.projectRoot, params.channelTarget);
-
   if (params.channelTarget === 'microsoft-copilot') {
-    return generateMicrosoftCopilotPackage({
-      runtimeValues: params.runtimeValues,
-      templatesDir,
-      outputPath,
-      dryRun: params.dryRun === true,
-      assertNoSecretsInArtifact,
-      renderTemplateFile
-    });
+    return generateCopilotChannelArtifact(params, templatesDir, outputPath);
   }
 
+  const runtimeValues = fillSlackManifestDescriptions(
+    params.channelTarget,
+    params.runtimeValues
+  );
   const manifestTemplate = path.join(templatesDir, 'manifest.template.json.hbs');
-  const content = renderTemplateFile(manifestTemplate, params.runtimeValues);
+  const content = renderTemplateFile(manifestTemplate, runtimeValues);
   assertNoSecretsInArtifact(content);
   const artifactHash = crypto.createHash('sha256').update(content, 'utf8').digest('hex');
   const outputDir = path.dirname(outputPath);
@@ -142,13 +156,13 @@ function generateChannelArtifact(params) {
 
   const install = renderInstallGuideIfPresent(
     templatesDir,
-    params.runtimeValues,
+    runtimeValues,
     outputDir,
     params.dryRun === true
   );
 
-  const installReady = params.runtimeValues?.installReady === true;
-  const blocker = params.runtimeValues?.discoveryBlocker || null;
+  const installReady = runtimeValues?.installReady === true;
+  const blocker = runtimeValues?.discoveryBlocker || null;
   return {
     outputPath,
     artifactHash,

package/lib/channels/channel-cardinality.js

@@ -0,0 +1,83 @@
+/**
+ * Channel Definition instance cardinality (projection + install gate).
+ *
+ * @fileoverview maxInstances is schema; canInstall is Builder-only
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getChannelDefinition } = require('./channel-definition-registry');
+const { installationsForDefinition } = require('./channel-install-inventory');
+const { listConnectedSystemsForInventory } = require('./channel-inventory-fetch');
+const { httpError } = require('../programmatic/channel-install-session');
+
+const AT_CAP_REASON = 'Maximum installations reached for this channel.';
+
+/**
+ * @param {Object|null} definition
+ * @returns {number|null}
+ */
+function maxInstancesOf(definition) {
+  const value = definition && definition.channel && definition.channel.maxInstances;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
+    return null;
+  }
+  return Math.floor(value);
+}
+
+/**
+ * Catalog/detail projection. Not an External System schema field except maxInstances.
+ * @param {Object|null} definition
+ * @param {Object[]} [installations]
+ * @returns {Object}
+ */
+function cardinalityProjection(definition, installations = []) {
+  const maxInstances = maxInstancesOf(definition);
+  const installationCount = Array.isArray(installations) ? installations.length : 0;
+  const projection = {
+    installationCount,
+    canInstall: true
+  };
+  if (maxInstances === null) {
+    return projection;
+  }
+  projection.maxInstances = maxInstances;
+  projection.canInstall = installationCount < maxInstances;
+  if (!projection.canInstall) {
+    projection.blockedReason = AT_CAP_REASON;
+  }
+  return projection;
+}
+
+/**
+ * Refuse a new install when the definition is already at maxInstances.
+ * Continue/force of an existing instance skips this gate.
+ * @param {import('../programmatic/workspace-context').WorkspaceContext} ctx
+ * @param {string} definitionKey
+ * @param {Object} [options]
+ * @returns {Promise<void>}
+ */
+async function assertChannelCardinality(ctx, definitionKey, options = {}) {
+  if (options.continueInstall === true || options.force === true) {
+    return;
+  }
+  const definition = getChannelDefinition(definitionKey);
+  if (maxInstancesOf(definition) === null) {
+    return;
+  }
+  const systems = await listConnectedSystemsForInventory(ctx, options.deps || {});
+  const installations = installationsForDefinition(systems, definitionKey);
+  const projection = cardinalityProjection(definition, installations);
+  if (projection.canInstall !== true) {
+    throw httpError(projection.blockedReason || AT_CAP_REASON, 409);
+  }
+}
+
+module.exports = {
+  AT_CAP_REASON,
+  maxInstancesOf,
+  cardinalityProjection,
+  assertChannelCardinality
+};

package/lib/channels/channel-catalog-icon.js

@@ -0,0 +1,45 @@
+/**
+ * Catalog icons live next to Channel Definitions (templates/channels/<key>/icon.svg).
+ *
+ * @fileoverview Safe data-URL icon for published listChannelTargets rows
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const { TEMPLATES_ROOT, channelDiskFs } = require('./channel-definition-registry');
+
+/**
+ * @param {string} raw
+ * @returns {string|undefined}
+ */
+function svgDataUrl(raw) {
+  const svg = String(raw || '').trim();
+  if (!svg.startsWith('<svg') && !svg.startsWith('<?xml')) {
+    return undefined;
+  }
+  return `data:image/svg+xml;base64,${Buffer.from(svg, 'utf8').toString('base64')}`;
+}
+
+/**
+ * @param {string} definitionKey
+ * @returns {string|undefined}
+ */
+function catalogIconHref(definitionKey) {
+  if (!definitionKey || typeof definitionKey !== 'string') {
+    return undefined;
+  }
+  const iconPath = path.join(TEMPLATES_ROOT, definitionKey, 'icon.svg');
+  try {
+    return svgDataUrl(channelDiskFs().readFileSync(iconPath, 'utf8'));
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return undefined;
+    }
+    throw err;
+  }
+}
+
+module.exports = { catalogIconHref };

package/lib/channels/channel-cli-instructions.js

@@ -0,0 +1,75 @@
+/**
+ * Generated CLI install instructions for provisioning.mode=cli.
+ *
+ * @fileoverview Copy-pasteable aifabrix channel add command
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { listDefinitionConfiguration, envNameToPropertyKey } = require('./channel-configuration-map');
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+function quoteCliName(name) {
+  return `"${String(name || '').replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * @param {Object} definition
+ * @returns {string[]}
+ */
+function requiredConfigurationFlags(definition) {
+  const flags = [];
+  for (const row of listDefinitionConfiguration(definition)) {
+    if (row.required !== true) {
+      continue;
+    }
+    const propertyKey = envNameToPropertyKey(row.name);
+    flags.push(`--${propertyKey.replace(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`)} <${propertyKey}>`);
+  }
+  return flags;
+}
+
+/**
+ * @param {Object} definition
+ * @param {{ name?: string }} [opts]
+ * @returns {string}
+ */
+function formatChannelCliInstructions(definition, opts = {}) {
+  const name = opts.name || 'Finance';
+  const required = requiredConfigurationFlags(definition).join(' ');
+  const command = [
+    `aifabrix channel add ${definition.key} --name ${quoteCliName(name)}`,
+    required
+  ]
+    .filter(Boolean)
+    .join(' ');
+  return [
+    'Installation method: AI Fabrix CLI',
+    '',
+    command,
+    '',
+    'Run this from an authenticated AI Fabrix Builder environment.'
+  ].join('\n');
+}
+
+/**
+ * @param {Object} definition
+ * @returns {boolean}
+ */
+function isCliProvisioningMode(definition) {
+  const mode = definition && definition.channel && definition.channel.provisioning
+    ? definition.channel.provisioning.mode
+    : '';
+  return mode === 'cli';
+}
+
+module.exports = {
+  formatChannelCliInstructions,
+  isCliProvisioningMode,
+  requiredConfigurationFlags
+};