@aifabrix/builder 2.46.0 → 2.47.0

package/lib/channels/add-channel.js

@@ -0,0 +1,348 @@
+/**
+ * Orchestrate aifabrix app add-channel (plan 152).
+ *
+ * @fileoverview Channel install after communication external system deploy
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getChannelTarget, getDefaultChannelDescription } = require('./channel-targets');
+const { resolveChannelRuntimeValues } = require('./channel-runtime-resolver');
+const { generateChannelArtifact } = require('./channel-artifact-generator');
+const {
+  getExistingChannelExtension,
+  buildChannelExtensionBlock,
+  fetchCommunicationSystem,
+  patchChannelExtension
+} = require('./channel-external-system');
+const {
+  auditArtifactGenerated,
+  auditConfigPatched,
+  auditApprovalRequired,
+  auditValidated,
+  auditFailed
+} = require('./channel-audit');
+const { runChannelProbe } = require('./channel-probe');
+const { resolveChannelAuthContext } = require('./channel-auth-context');
+const { ensureChannelCredential } = require('./channel-credential');
+const {
+  normalizeBaseChannelName,
+  resolveChannelDisplayName
+} = require('./channel-display-name');
+const {
+  displayExistingChannelStatus,
+  displayChannelInstallResult,
+  displayChannelError
+} = require('./channel-status-display');
+
+/**
+ * @param {typeof import('./channel-targets').CHANNEL_TARGETS[string]} target
+ * @param {Object} channelExt
+ * @param {Object} [context]
+ * @returns {string|null}
+ */
+function resolveApprovalUrl(target, channelExt, context = {}) {
+  if (!target.approvalRequired) return null;
+  if (channelExt?.status === 'installed' || channelExt?.status === 'validated') return null;
+  if (target.key === 'slack' && context.artifactPath) {
+    return `https://api.slack.com/apps/new — upload manifest: ${context.artifactPath}`;
+  }
+  if (target.key === 'teams-bot') {
+    return 'https://admin.teams.microsoft.com/ — configure Bot Channel Registration for this tenant';
+  }
+  return `https://platform-admin.example/configure/${target.key}`;
+}
+
+/**
+ * @param {Object} target
+ * @param {Object} channelExt
+ * @param {boolean} dryRun
+ * @returns {string}
+ */
+function resolveInstallStatus(target, channelExt, dryRun) {
+  if (dryRun) return 'generated';
+  if (channelExt?.status === 'approvalRequired') return 'approvalRequired';
+  if (target.approvalRequired && !channelExt) return 'approvalRequired';
+  if (target.approvalRequired && channelExt?.status !== 'installed') return 'approvalRequired';
+  return 'installed';
+}
+
+/**
+ * @param {Object|null} validation
+ * @returns {Object|null}
+ */
+function toValidationDisplay(validation) {
+  if (!validation) return null;
+  return {
+    callbackReachable: validation.callbackReachable,
+    credentialValid: validation.credentialValid,
+    assistantCatalogReachable: validation.assistantCatalogReachable,
+    inboundVerification: Object.values(validation.inboundVerification).every(Boolean)
+  };
+}
+
+/**
+ * @param {Object} params
+ * @returns {Object|null}
+ */
+function showExistingChannelStatus(params) {
+  const { existing, options, target, channelTarget, name, baseName } = params;
+  if (!existing || options.force || options.dryRun) return null;
+  const sameInstall =
+    (existing.baseName && existing.baseName === baseName) ||
+    (!existing.baseName && existing.name === name);
+  if (!sameInstall) {
+    throw new Error(
+      `Channel already configured as "${existing.name}". ` +
+        `Use --force to replace with "${name}".`
+    );
+  }
+  displayExistingChannelStatus({
+    channelTarget,
+    name: existing.name || name,
+    channelExt: existing,
+    approvalUrl: resolveApprovalUrl(target, existing)
+  });
+  return { skipped: true, channelExt: existing };
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} artifactParams
+ * @returns {Object}
+ */
+function generateArtifactWithAudit(channelTarget, artifactParams) {
+  try {
+    const artifact = generateChannelArtifact(artifactParams);
+    auditArtifactGenerated(channelTarget, {
+      artifactHash: artifact.artifactHash,
+      outputPath: artifact.outputPath,
+      dryRun: artifactParams.dryRun === true
+    });
+    return artifact;
+  } catch (err) {
+    auditFailed(channelTarget, { phase: 'artifact', error: err.message });
+    throw err;
+  }
+}
+
+/**
+ * @param {Object} ctx
+ * @param {string} channelTarget
+ * @param {Object} channelBlock
+ * @param {string} status
+ * @param {string} artifactHash
+ * @returns {Promise<void>}
+ */
+async function patchConfigWithAudit(ctx, channelTarget, channelBlock, status, artifactHash) {
+  try {
+    await patchChannelExtension(
+      { dataplaneUrl: ctx.dataplaneUrl, authConfig: ctx.authConfig, channelTarget },
+      channelBlock
+    );
+    auditConfigPatched(channelTarget, { status, artifactHash });
+  } catch (err) {
+    auditFailed(channelTarget, { phase: 'patch', error: err.message });
+    throw err;
+  }
+}
+
+/**
+ * @param {Object} ctx
+ * @param {Object} channelBlock
+ * @param {string} channelTarget
+ * @param {boolean} probe
+ * @returns {Promise<Object|null>}
+ */
+async function maybeRunProbe(ctx, channelBlock, channelTarget, probe) {
+  if (!probe) return null;
+  const validation = await runChannelProbe(
+    { dataplaneUrl: ctx.dataplaneUrl, authConfig: ctx.authConfig },
+    channelBlock
+  );
+  if (validation.passed) {
+    auditValidated(channelTarget, { probe: true });
+  } else {
+    auditFailed(channelTarget, { phase: 'probe', validation });
+  }
+  return validation;
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} options
+ * @returns {Promise<{ target: Object, name: string, baseName: string, description: string, ctx: Object, existing: Object|null }>}
+ */
+async function prepareChannelContext(channelTarget, options) {
+  const target = getChannelTarget(channelTarget);
+  if (target.experimental) {
+    throw new Error(
+      `Channel target "${channelTarget}" is experimental. Confirm product requirement before use.`
+    );
+  }
+  if (!options.name || typeof options.name !== 'string' || !options.name.trim()) {
+    throw new Error('--name is required for app add-channel');
+  }
+
+  const baseName = normalizeBaseChannelName(options.name);
+  const ctx = await resolveChannelAuthContext(channelTarget, { silent: options.quiet });
+  const name = resolveChannelDisplayName(baseName, ctx.environment);
+  const description =
+    options.description && String(options.description).trim()
+      ? String(options.description).trim()
+      : getDefaultChannelDescription();
+
+  const system = await fetchCommunicationSystem({
+    dataplaneUrl: ctx.dataplaneUrl,
+    authConfig: ctx.authConfig,
+    channelTarget
+  });
+  const existing = getExistingChannelExtension(system);
+  return { target, name, baseName, description, ctx, existing };
+}
+
+/**
+ * @param {Object} params
+ * @returns {Promise<Object>}
+ */
+async function completeLiveInstall(params) {
+  const { ctx, channelTarget, channelBlock, status, artifact, target, name, baseName, options } = params;
+
+  await ensureChannelCredential({
+    ctx,
+    channelTarget,
+    target,
+    force: options.force === true
+  });
+
+  await patchConfigWithAudit(ctx, channelTarget, channelBlock, status, artifact.artifactHash);
+
+  const approvalUrl =
+    status === 'approvalRequired'
+      ? resolveApprovalUrl(target, channelBlock, { artifactPath: artifact.outputPath })
+      : null;
+  if (approvalUrl) {
+    auditApprovalRequired(channelTarget, { approvalUrl });
+  }
+
+  const validation = await maybeRunProbe(ctx, channelBlock, channelTarget, options.probe);
+
+  displayChannelInstallResult({
+    channelTarget,
+    name,
+    baseName,
+    statusLabel: status === 'approvalRequired' ? 'Approval required' : 'Installed',
+    credentialKey: target.credentialKey,
+    capabilities: target.capabilities,
+    artifactPath: artifact.outputPath,
+    installGuidePath: artifact.installPath,
+    validation: toValidationDisplay(validation),
+    approvalUrl
+  });
+
+  return { channelBlock, artifact, validation, approvalUrl };
+}
+
+/**
+ * @param {Object} params
+ * @returns {{ dryRun: true, channelBlock: Object, artifact: Object }}
+ */
+function finishDryRunInstall(params) {
+  displayChannelInstallResult({
+    channelTarget: params.channelTarget,
+    name: params.name,
+    baseName: params.baseName,
+    statusLabel: 'Generated (dry-run)',
+    credentialKey: params.target.credentialKey,
+    capabilities: params.target.capabilities,
+    artifactPath: params.artifact.outputPath,
+    installGuidePath: params.artifact.installPath
+  });
+  return { dryRun: true, channelBlock: params.channelBlock, artifact: params.artifact };
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runAddChannel(channelTarget, options = {}) {
+  const { target, name, baseName, description, ctx, existing } = await prepareChannelContext(
+    channelTarget,
+    options
+  );
+
+  const skipped = showExistingChannelStatus({
+    existing,
+    options,
+    target,
+    channelTarget,
+    name,
+    baseName
+  });
+  if (skipped) return skipped;
+
+  const runtimeValues = resolveChannelRuntimeValues({
+    dataplaneBaseUrl: ctx.dataplaneUrl,
+    channelTarget,
+    appName: name,
+    baseName,
+    environment: ctx.environment,
+    appDescription: description,
+    icon: options.icon
+  });
+
+  const projectRoot = options.projectRoot || process.cwd();
+  const artifact = generateArtifactWithAudit(channelTarget, {
+    projectRoot,
+    channelTarget,
+    runtimeValues,
+    dryRun: options.dryRun === true
+  });
+
+  const status = resolveInstallStatus(target, existing, options.dryRun === true);
+  const channelBlock = buildChannelExtensionBlock(
+    { name, baseName, description, artifactHash: artifact.artifactHash, status },
+    target
+  );
+
+  if (options.dryRun) {
+    return finishDryRunInstall({ channelTarget, name, baseName, target, artifact, channelBlock });
+  }
+
+  return completeLiveInstall({
+    ctx,
+    channelTarget,
+    channelBlock,
+    status,
+    artifact,
+    target,
+    name,
+    baseName,
+    options
+  });
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} options
+ */
+async function addChannelCommand(channelTarget, options = {}) {
+  try {
+    await runAddChannel(channelTarget, options);
+  } catch (err) {
+    displayChannelError(err.message || String(err));
+    throw err;
+  }
+}
+
+module.exports = {
+  runAddChannel,
+  addChannelCommand,
+  resolveApprovalUrl,
+  resolveInstallStatus,
+  normalizeBaseChannelName,
+  resolveChannelDisplayName
+};

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

@@ -0,0 +1,141 @@
+/**
+ * Generate channel artifacts from Handlebars templates (plan 152).
+ *
+ * @fileoverview Channel artifact generation — dist/channels, sha256 hash, no secrets
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const Handlebars = require('handlebars');
+const { getChannelTarget } = require('./channel-targets');
+
+const SECRET_PATTERNS = [/xoxb-/i, /xoxp-/i, /client_secret/i, /signing_secret/i, /Bearer\s+/i];
+
+/**
+ * @param {string} content
+ * @throws {Error}
+ */
+function assertNoSecretsInArtifact(content) {
+  for (const pattern of SECRET_PATTERNS) {
+    if (pattern.test(content)) {
+      throw new Error('Generated artifact must not contain secret-like values');
+    }
+  }
+  if (content.includes('your-domain.com')) {
+    throw new Error('Generated artifact still contains placeholder domain your-domain.com');
+  }
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} channelTarget
+ * @returns {string}
+ */
+function getTemplatesDir(projectRoot, channelTarget) {
+  const target = getChannelTarget(channelTarget);
+  return path.join(projectRoot, 'templates', 'channels', target.templateDir);
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} channelTarget
+ * @returns {string}
+ */
+function getArtifactOutputPath(projectRoot, channelTarget) {
+  const target = getChannelTarget(channelTarget);
+  return path.join(
+    projectRoot,
+    'dist',
+    'channels',
+    channelTarget,
+    target.artifactFileName
+  );
+}
+
+/**
+ * @param {string} templatePath
+ * @param {Object} context
+ * @returns {string}
+ */
+function renderTemplateFile(templatePath, context) {
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`Channel template not found: ${templatePath}`);
+  }
+  const raw = fs.readFileSync(templatePath, 'utf8');
+  const template = Handlebars.compile(raw);
+  return template(context);
+}
+
+/**
+ * @param {string} templatesDir
+ * @param {Object} runtimeValues
+ * @param {string} outputDir
+ * @param {boolean} dryRun
+ * @returns {{ installPath: string, content: string }|null}
+ */
+function renderInstallGuideIfPresent(templatesDir, runtimeValues, outputDir, dryRun) {
+  const installTemplate = path.join(templatesDir, 'install.template.md.hbs');
+  if (!fs.existsSync(installTemplate)) {
+    return null;
+  }
+  const content = renderTemplateFile(installTemplate, runtimeValues);
+  assertNoSecretsInArtifact(content);
+  const installPath = path.join(outputDir, 'INSTALL.md');
+  if (!dryRun) {
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.writeFileSync(installPath, content, 'utf8');
+  }
+  return { installPath, content };
+}
+
+/**
+ * @param {Object} params
+ * @param {string} params.projectRoot
+ * @param {string} params.channelTarget
+ * @param {Object} params.runtimeValues
+ * @param {boolean} [params.dryRun]
+ * @returns {{ outputPath: string, artifactHash: string, content: string, installPath?: string }}
+ */
+function generateChannelArtifact(params) {
+  const templatesDir = getTemplatesDir(params.projectRoot, params.channelTarget);
+  const manifestTemplate = path.join(templatesDir, 'manifest.template.json.hbs');
+  const content = renderTemplateFile(manifestTemplate, params.runtimeValues);
+  assertNoSecretsInArtifact(content);
+
+  const outputPath = getArtifactOutputPath(params.projectRoot, params.channelTarget);
+  const artifactHash = crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+  const outputDir = path.dirname(outputPath);
+
+  if (!params.dryRun) {
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.writeFileSync(outputPath, content, 'utf8');
+  }
+
+  const install = renderInstallGuideIfPresent(
+    templatesDir,
+    params.runtimeValues,
+    outputDir,
+    params.dryRun === true
+  );
+
+  return {
+    outputPath,
+    artifactHash,
+    content,
+    installPath: install?.installPath
+  };
+}
+
+module.exports = {
+  assertNoSecretsInArtifact,
+  getTemplatesDir,
+  getArtifactOutputPath,
+  renderTemplateFile,
+  renderInstallGuideIfPresent,
+  generateChannelArtifact
+};

package/lib/channels/channel-audit.js

@@ -0,0 +1,101 @@
+/**
+ * Structured audit logging for channel install (plan 152).
+ *
+ * @fileoverview Channel install audit events — no secrets in payloads
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+
+/**
+ * @param {string} eventName
+ * @param {Object} payload
+ */
+function emitChannelAuditEvent(eventName, payload) {
+  logger.log(
+    JSON.stringify({
+      event: eventName,
+      ...payload,
+      timestamp: new Date().toISOString()
+    })
+  );
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} details
+ */
+function auditArtifactGenerated(channelTarget, details) {
+  emitChannelAuditEvent('channelArtifactGenerated', { channelTarget, ...details });
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} details
+ */
+function auditConfigPatched(channelTarget, details) {
+  emitChannelAuditEvent('channelConfigPatched', { channelTarget, ...details });
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} details
+ */
+function auditCredentialCreated(channelTarget, details) {
+  emitChannelAuditEvent('channelCredentialCreated', { channelTarget, ...details });
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} details
+ */
+function auditCredentialUpdated(channelTarget, details) {
+  emitChannelAuditEvent('channelCredentialUpdated', { channelTarget, ...details });
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} details
+ */
+function auditApprovalRequired(channelTarget, details) {
+  emitChannelAuditEvent('channelApprovalRequired', { channelTarget, ...details });
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} details
+ */
+function auditApprovalCompleted(channelTarget, details) {
+  emitChannelAuditEvent('channelApprovalCompleted', { channelTarget, ...details });
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} details
+ */
+function auditValidated(channelTarget, details) {
+  emitChannelAuditEvent('channelValidated', { channelTarget, ...details });
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} details
+ */
+function auditFailed(channelTarget, details) {
+  emitChannelAuditEvent('channelFailed', { channelTarget, ...details });
+}
+
+module.exports = {
+  emitChannelAuditEvent,
+  auditArtifactGenerated,
+  auditConfigPatched,
+  auditCredentialCreated,
+  auditCredentialUpdated,
+  auditApprovalRequired,
+  auditApprovalCompleted,
+  auditValidated,
+  auditFailed
+};

package/lib/channels/channel-auth-context.js

@@ -0,0 +1,37 @@
+/**
+ * Resolve controller, dataplane, and auth for channel install.
+ *
+ * @fileoverview Channel install auth context (plan 152)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const config = require('../core/config');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { getDeploymentAuth } = require('../utils/token-manager');
+const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
+
+/**
+ * @async
+ * @param {string} channelTarget
+ * @param {{ silent?: boolean }} [opts]
+ * @returns {Promise<{ controllerUrl: string, environment: string, dataplaneUrl: string, authConfig: Object }>}
+ */
+async function resolveChannelAuthContext(channelTarget, opts = {}) {
+  const controllerUrl = await resolveControllerUrl();
+  const environment = (await config.getEnvironment()) || 'dev';
+  const authConfig = await getDeploymentAuth(controllerUrl, environment, channelTarget);
+  if (!authConfig) {
+    throw new Error('Authentication required. Run "aifabrix login" first.');
+  }
+  const dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig, {
+    silent: opts.silent === true
+  });
+  return { controllerUrl, environment, dataplaneUrl, authConfig };
+}
+
+module.exports = {
+  resolveChannelAuthContext
+};