@aifabrix/builder 2.52.0 → 2.52.1

package/lib/programmatic/run-channel-package.js

@@ -0,0 +1,236 @@
+/**
+ * Builder API channel packaging handlers (plan 167.0).
+ *
+ * @fileoverview Package build / branding / zip for workspace channel systemKeys
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+const { ensureIntegrationDirectory } = require('./workspace-context');
+const { resolveChannelRuntimeValues } = require('../channels/channel-runtime-resolver');
+const { generateChannelArtifact } = require('../channels/channel-artifact-generator');
+const { loadChannelPackageContext } = require('../channels/channel-discovery');
+const {
+  readChannelBranding,
+  writeChannelBranding,
+  mergeChannelBranding
+} = require('../channels/channel-branding');
+const { isChannelTargetKey } = require('../channels/channel-targets');
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {string}
+ */
+function workspaceSystemDir(ctx) {
+  return ctx.getIntegrationPath();
+}
+
+/**
+ * Channel target equals workspace systemKey for packaging apps.
+ * @param {string} systemKey
+ * @returns {string}
+ */
+function requireChannelTarget(systemKey) {
+  if (!isChannelTargetKey(systemKey)) {
+    throw new Error(
+      `systemKey "${systemKey}" is not a supported channel packaging target`
+    );
+  }
+  return systemKey;
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {{ type: string, token: string }}
+ */
+function authConfigFromContext(ctx) {
+  return { type: 'bearer', token: ctx.bearerToken };
+}
+
+/**
+ * @param {Object} branding
+ * @param {string} channelTarget
+ * @returns {Object}
+ */
+function fallbackPackageContext(branding, channelTarget) {
+  return {
+    displayName: branding.displayName || channelTarget,
+    description: branding.description || '',
+    governedToolNames: [],
+    mcpServerUrl: null,
+    installReady: false,
+    blocker: 'discoveryUnavailable',
+    authentication: null
+  };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ * @param {string} channelTarget
+ * @param {Object} branding
+ * @param {string} dataplaneUrl
+ * @param {Object} packageContext
+ * @returns {Object}
+ */
+function generatePackageArtifact(ctx, body, channelTarget, branding, dataplaneUrl, packageContext) {
+  const appName =
+    branding.displayName || body.name || packageContext.displayName || channelTarget;
+  const description =
+    branding.description || body.description || packageContext.description || '';
+  const runtimeValues = resolveChannelRuntimeValues({
+    dataplaneBaseUrl: dataplaneUrl,
+    channelTarget,
+    appName,
+    baseName: body.baseName || appName,
+    environment: body.environment || ctx.environment || 'dev',
+    appDescription: description,
+    layerBToolNames: packageContext.governedToolNames || [],
+    packageContext,
+    iconColorPath: branding.iconColorPath,
+    iconOutlinePath: branding.iconOutlinePath
+  });
+  return generateChannelArtifact({
+    projectRoot: ctx.getUserRoot(),
+    channelTarget,
+    runtimeValues,
+    dryRun: body.dryRun === true
+  });
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ * @returns {Promise<Object>}
+ */
+async function buildChannelPackage(ctx, body = {}) {
+  const channelTarget = requireChannelTarget(ctx.systemKey);
+  ensureIntegrationDirectory(ctx);
+  const dir = workspaceSystemDir(ctx);
+  const branding = mergeChannelBranding(readChannelBranding(dir), body.branding || {});
+  if (body.branding && typeof body.branding === 'object') {
+    writeChannelBranding(dir, branding);
+  }
+  const dataplaneUrl = ctx.dataplaneUrl || body.dataplaneUrl;
+  if (!dataplaneUrl) {
+    throw new Error('dataplaneUrl is required to build a channel package');
+  }
+  const packageContext = await loadChannelPackageContext({
+    dataplaneBaseUrl: dataplaneUrl,
+    authConfig: authConfigFromContext(ctx),
+    channelTarget,
+    branding
+  }).catch(() => fallbackPackageContext(branding, channelTarget));
+  const artifact = generatePackageArtifact(
+    ctx,
+    body,
+    channelTarget,
+    branding,
+    dataplaneUrl,
+    packageContext
+  );
+  return {
+    channelTarget,
+    installReady: artifact.installReady === true,
+    blocker: artifact.blocker || packageContext.blocker || null,
+    artifactHash: artifact.artifactHash,
+    links: artifact.links || {
+      readme: artifact.installPath,
+      zip: artifact.zipPath || null
+    },
+    summary: artifact.content ? JSON.parse(artifact.content) : null
+  };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {Object}
+ */
+function getChannelPackageSummary(ctx) {
+  const channelTarget = requireChannelTarget(ctx.systemKey);
+  const projectRoot = ctx.getUserRoot();
+  const summaryPath = path.join(
+    projectRoot,
+    'dist',
+    'channels',
+    channelTarget,
+    `channel-${channelTarget}.json`
+  );
+  if (!fs.existsSync(summaryPath)) {
+    throw new Error(`Channel package summary not found: ${summaryPath}`);
+  }
+  const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
+  return {
+    channelTarget,
+    summary,
+    links: summary.links || null,
+    installReady: summary.installReady === true,
+    blocker: summary.blocker || null
+  };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {{ fileName: string, contentType: string, byteLength: number, zipBase64: string }}
+ */
+function getChannelPackageZip(ctx) {
+  const channelTarget = requireChannelTarget(ctx.systemKey);
+  const summary = getChannelPackageSummary(ctx).summary;
+  const zipPath =
+    typeof summary?.links?.zip === 'string' && summary.links.zip
+      ? summary.links.zip
+      : path.join(
+        ctx.getUserRoot(),
+        'dist',
+        'channels',
+        channelTarget,
+        'build',
+        `appPackage.${summary.environment || 'dev'}.zip`
+      );
+  if (!fs.existsSync(zipPath)) {
+    throw new Error(`Channel package ZIP not found: ${zipPath}`);
+  }
+  const buffer = fs.readFileSync(zipPath);
+  return {
+    fileName: path.basename(zipPath),
+    contentType: 'application/zip',
+    byteLength: buffer.length,
+    zipBase64: buffer.toString('base64')
+  };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ * @returns {Object}
+ */
+function patchChannelBranding(ctx, body = {}) {
+  requireChannelTarget(ctx.systemKey);
+  ensureIntegrationDirectory(ctx);
+  const branding = writeChannelBranding(workspaceSystemDir(ctx), body || {});
+  return { systemKey: ctx.systemKey, branding };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {Object}
+ */
+function getChannelBranding(ctx) {
+  requireChannelTarget(ctx.systemKey);
+  return {
+    systemKey: ctx.systemKey,
+    branding: readChannelBranding(workspaceSystemDir(ctx))
+  };
+}
+
+module.exports = {
+  buildChannelPackage,
+  getChannelPackageSummary,
+  getChannelPackageZip,
+  patchChannelBranding,
+  getChannelBranding
+};

package/lib/programmatic/run-integration-definition.js

@@ -0,0 +1,69 @@
+/**
+ * Apply Builder Integration Definition (BID) into a user workspace.
+ *
+ * @fileoverview POST …/integration-definition/apply
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const {
+  applyIntegrationDefinition,
+  withDefinitionHash
+} = require('../integration-definition');
+const {
+  runWithWorkspaceContext,
+  ensureIntegrationDirectory,
+  WORKSPACE_INTEGRATION_FORMAT
+} = require('./workspace-context');
+const { touchWorkspaceMeta } = require('./workspace-meta');
+
+const OPENAPI_ENRICHMENT_DIR = path.join(
+  __dirname,
+  '../integration-definition/openapi-enrichment'
+);
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ * @param {Object} [body.integrationDefinition]
+ * @param {boolean} [body.force]
+ * @param {boolean} [body.dryRun]
+ * @returns {Promise<Object>}
+ */
+async function applyIntegrationDefinitionInWorkspace(ctx, body = {}) {
+  const bidInput = body.integrationDefinition || body.bid || body;
+  if (!bidInput || typeof bidInput !== 'object') {
+    throw new Error('integrationDefinition object is required in request body');
+  }
+  const force = body.force === true;
+  const dryRun = body.dryRun === true;
+  return runWithWorkspaceContext(ctx, async() => {
+    ensureIntegrationDirectory(ctx);
+    const bid = withDefinitionHash(bidInput);
+    const identity = bid.packageIdentity || {};
+    const bidKey = String(identity.systemKey || '').trim();
+    if (bidKey && bidKey !== ctx.systemKey) {
+      throw new Error(
+        `BID packageIdentity.systemKey (${bidKey}) must match path systemKey (${ctx.systemKey})`
+      );
+    }
+    const out = await applyIntegrationDefinition(bid, {
+      outputDir: ctx.getIntegrationPath(),
+      force,
+      dryRun,
+      openapiBaseDir: OPENAPI_ENRICHMENT_DIR
+    });
+    touchWorkspaceMeta(ctx, {
+      lastOperation: 'integration-definition-apply',
+      format: WORKSPACE_INTEGRATION_FORMAT,
+      definitionId: out.definitionId,
+      definitionHash: out.definitionHash
+    });
+    return out;
+  });
+}
+
+module.exports = { applyIntegrationDefinitionInWorkspace };

package/lib/role-assistant/knowledge-sync-logging.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatSuccessLine, formatWarningLine, metadata } = require('../utils/cli-test-layout-chalk');
+
+function logKnowledgeImportSummary(systemKey, result, options = {}) {
+  if (result.skipped) {
+    if (options.verbose === true) {
+      logger.log(metadata(`Knowledge sync skipped (${systemKey}): ${result.reason}`));
+    }
+    return;
+  }
+  if (result.dryRun) {
+    logger.log(formatWarningLine(
+      `Role assistant knowledge dry-run: ${result.fileCount} file(s), ${result.recordCount} record(s), datasource ${result.datasourceKey}`
+    ));
+    return;
+  }
+  logger.log(formatSuccessLine(
+    `Role assistant knowledge synced (${result.datasourceKey}): ${result.recordCount} record(s) from ${result.fileCount} file(s).`
+  ));
+}
+
+function logDocumentStorageSettingsPushSummary(systemKey, result, options = {}) {
+  if (result.skipped) {
+    if (options.verbose === true) {
+      logger.log(metadata(`Knowledge document storage settings skipped (${systemKey}): ${result.reason}`));
+    }
+    return;
+  }
+  if (result.dryRun) {
+    logger.log(formatWarningLine(
+      `Knowledge document storage settings dry-run (${systemKey}): ${result.documentStorageKey || '(clear)'}`
+    ));
+    return;
+  }
+  logger.log(formatSuccessLine(
+    `Knowledge document storage settings updated (${systemKey}): ${result.documentStorageKey || '(cleared)'}`
+  ));
+}
+
+function logKnowledgeExportSummary(systemKey, result, options = {}) {
+  if (result.skipped) {
+    if (options.verbose === true) {
+      logger.log(metadata(`Knowledge export skipped (${systemKey}): ${result.reason}`));
+    }
+    return;
+  }
+  logger.log(formatSuccessLine(
+    `Role assistant knowledge exported (${result.datasourceKey}): ${result.count} document(s) to ${result.knowledgePath}.`
+  ));
+}
+
+module.exports = {
+  logKnowledgeImportSummary,
+  logDocumentStorageSettingsPushSummary,
+  logKnowledgeExportSummary
+};

package/lib/role-assistant/knowledge-sync.js

@@ -12,8 +12,6 @@ const path = require('path');
 const crypto = require('crypto');
 const fs = require('../internal/fs-real-sync');
 const yaml = require('js-yaml');
-const logger = require('../utils/logger');
-const { formatSuccessLine, formatWarningLine, metadata } = require('../utils/cli-test-layout-chalk');
 const { listDocuments, validateDocuments, bulkDocuments } = require('../api/datasources-extended.api');
 const {
   extractDocumentStorageKeyFromAssistantDetails,
@@ -32,6 +30,11 @@ const {
   knowledgeSearchMetadataFromFrontmatter,
   splitMarkdownFrontmatter
 } = require('./knowledge-markdown-frontmatter');
+const {
+  logKnowledgeImportSummary,
+  logDocumentStorageSettingsPushSummary,
+  logKnowledgeExportSummary
+} = require('./knowledge-sync-logging');
 
 function resolveSystemNode(input) {
   if (!input || typeof input !== 'object') {
@@ -80,53 +83,91 @@ async function resolveDocumentStorageKeyFromDataplane(dataplaneUrl, authConfig,
 }
 
 /**
- * Push role-assistant.yaml knowledge.documentStorageKey to dataplane Assistants settings.
+ * Map role-assistant.yaml debug.* → Assistants settings PATCH fields.
+ * includePromptTrace → fullDebugEnabled (LLM prompt capture gate).
+ * enabled → debugEnabled (runtime debug traces).
+ * @param {Object|null|undefined} debugSection
+ * @returns {{ debugEnabled?: boolean, fullDebugEnabled?: boolean }}
+ */
+function mapRoleAssistantDebugToAssistantsSettings(debugSection) {
+  if (!debugSection || typeof debugSection !== 'object') {
+    return {};
+  }
+  const body = {};
+  if (typeof debugSection.enabled === 'boolean') {
+    body.debugEnabled = debugSection.enabled;
+  }
+  if (typeof debugSection.includePromptTrace === 'boolean') {
+    body.fullDebugEnabled = debugSection.includePromptTrace;
+  }
+  return body;
+}
+
+/**
+ * Push role-assistant.yaml knowledge + debug settings to dataplane Assistants.
  * Called on upload/deploy so the operator UI and CLI stay aligned.
  */
-async function pushRoleAssistantDocumentStorageSettings(params) {
+function resolveAssistantSettingsPush(params) {
   const {
     systemKey,
-    dataplaneUrl,
-    authConfig,
     environment = 'dev',
-    pathOptions = {},
-    dryRun = false
+    pathOptions = {}
   } = params;
   const settingsEnv = resolveRoleAssistantSettingsEnvKey(environment);
   const settings = readRoleAssistantSettings(systemKey, { required: false, pathOptions });
   if (!settings) {
-    return { skipped: true, reason: 'missing-role-assistant-settings' };
+    return { result: { skipped: true, reason: 'missing-role-assistant-settings' } };
   }
   const section = resolveRoleAssistantEnvironmentSettings(settings, settingsEnv, {
     required: false
   });
   if (!section) {
-    return { skipped: true, reason: 'missing-env-settings' };
+    return { result: { skipped: true, reason: 'missing-env-settings' } };
   }
   const documentStorageKey =
     resolveDocumentStorageKeyFromRoleAssistantSettings(settings, settingsEnv) || '';
-  if (dryRun) {
-    return {
-      skipped: false,
-      dryRun: true,
-      documentStorageKey: documentStorageKey || null
-    };
+  const debugBody = mapRoleAssistantDebugToAssistantsSettings(section.debug);
+  if (!documentStorageKey && Object.keys(debugBody).length === 0) {
+    return { result: { skipped: true, reason: 'no-document-storage-key', documentStorageKey: null } };
   }
-  if (documentStorageKey === '') {
-    // No Knowledge binding in role-assistant.yaml — skip Assistants settings write.
-    // Draft / not-yet-catalogued digital workers would 404 on PATCH otherwise.
+  const patchBody = { ...debugBody };
+  if (documentStorageKey) {
+    patchBody.documentStorageKey = documentStorageKey;
+  }
+  return { documentStorageKey, debugBody, patchBody };
+}
+
+async function applyAssistantSettingsPush(dataplaneUrl, systemKey, authConfig, settingsPush) {
+  const { documentStorageKey, debugBody, patchBody } = settingsPush;
+  const hasDocumentStorageKey = documentStorageKey !== '';
+  const hasDebugSettings = Object.keys(debugBody).length > 0;
+  let response = await updateAssistantSettings(
+    dataplaneUrl,
+    systemKey,
+    authConfig,
+    patchBody
+  );
+  if (response && response.success === false && hasDocumentStorageKey && hasDebugSettings) {
+    response = await updateAssistantSettings(
+      dataplaneUrl,
+      systemKey,
+      authConfig,
+      debugBody
+    );
+    if (response && response.success === false) {
+      throw new Error(
+        response.formattedError ||
+          response.error ||
+          'Failed to update Assistants debug settings'
+      );
+    }
     return {
-      skipped: true,
-      reason: 'no-document-storage-key',
-      documentStorageKey: null
+      skipped: false,
+      documentStorageKey: null,
+      documentStoragePushFailed: true,
+      ...debugBody
     };
   }
-  if (!dataplaneUrl || !authConfig) {
-    return { skipped: true, reason: 'missing-dataplane-auth' };
-  }
-  const response = await updateAssistantSettings(dataplaneUrl, systemKey, authConfig, {
-    documentStorageKey
-  });
   if (response && response.success === false) {
     throw new Error(
       response.formattedError ||
@@ -136,10 +177,27 @@ async function pushRoleAssistantDocumentStorageSettings(params) {
   }
   return {
     skipped: false,
-    documentStorageKey: documentStorageKey || null
+    documentStorageKey: documentStorageKey || null,
+    ...debugBody
   };
 }
 
+async function pushRoleAssistantDocumentStorageSettings(params) {
+  const { systemKey, dataplaneUrl, authConfig, dryRun = false } = params;
+  const settingsPush = resolveAssistantSettingsPush(params);
+  if (settingsPush.result) {
+    return settingsPush.result;
+  }
+  const { documentStorageKey, debugBody } = settingsPush;
+  if (dryRun) {
+    return { skipped: false, dryRun: true, documentStorageKey: documentStorageKey || null, ...debugBody };
+  }
+  if (!dataplaneUrl || !authConfig) {
+    return { skipped: true, reason: 'missing-dataplane-auth' };
+  }
+  return applyAssistantSettingsPush(dataplaneUrl, systemKey, authConfig, settingsPush);
+}
+
 /**
  * Resolve Knowledge document storage key.
  * Order: role-assistant.yaml → dataplane Assistants settings → package dataSources.
@@ -408,74 +466,11 @@ async function exportRoleAssistantKnowledge(params) {
   return { skipped: false, datasourceKey, count: rows.length, knowledgePath, settingsPath };
 }
 
-function logKnowledgeImportSummary(systemKey, result, options = {}) {
-  if (result.skipped) {
-    if (options.verbose === true) {
-      logger.log(metadata(`Knowledge sync skipped (${systemKey}): ${result.reason}`));
-    }
-    return;
-  }
-  if (result.dryRun) {
-    logger.log(
-      formatWarningLine(
-        `Role assistant knowledge dry-run: ${result.fileCount} file(s), ${result.recordCount} record(s), datasource ${result.datasourceKey}`
-      )
-    );
-    return;
-  }
-  logger.log(
-    formatSuccessLine(
-      `Role assistant knowledge synced (${result.datasourceKey}): ${result.recordCount} record(s) from ${result.fileCount} file(s).`
-    )
-  );
-}
-
-function logDocumentStorageSettingsPushSummary(systemKey, result, options = {}) {
-  if (result.skipped) {
-    if (options.verbose === true) {
-      logger.log(
-        metadata(`Knowledge document storage settings skipped (${systemKey}): ${result.reason}`)
-      );
-    }
-    return;
-  }
-  if (result.dryRun) {
-    logger.log(
-      formatWarningLine(
-        `Knowledge document storage settings dry-run (${systemKey}): ${
-          result.documentStorageKey || '(clear)'
-        }`
-      )
-    );
-    return;
-  }
-  logger.log(
-    formatSuccessLine(
-      `Knowledge document storage settings updated (${systemKey}): ${
-        result.documentStorageKey || '(cleared)'
-      }`
-    )
-  );
-}
-
-function logKnowledgeExportSummary(systemKey, result, options = {}) {
-  if (result.skipped) {
-    if (options.verbose === true) {
-      logger.log(metadata(`Knowledge export skipped (${systemKey}): ${result.reason}`));
-    }
-    return;
-  }
-  logger.log(
-    formatSuccessLine(
-      `Role assistant knowledge exported (${result.datasourceKey}): ${result.count} document(s) to ${result.knowledgePath}.`
-    )
-  );
-}
-
 module.exports = {
   isDigitalWorkerModel,
   resolveRoleAssistantSettingsEnvKey,
   resolveRoleAssistantDocumentStorageKey,
+  mapRoleAssistantDebugToAssistantsSettings,
   pushRoleAssistantDocumentStorageSettings,
   importRoleAssistantKnowledge,
   exportRoleAssistantKnowledge,