@aifabrix/builder 2.51.1 → 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-markdown-frontmatter.js

@@ -0,0 +1,75 @@
+/**
+ * Parse optional YAML frontmatter from Role Assistant knowledge markdown.
+ *
+ * @fileoverview knowledge-markdown-frontmatter
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const yaml = require('js-yaml');
+
+const SEARCH_META_KEYS = [
+  'aspect',
+  'knowledgeType',
+  'knowledgeKey',
+  'title',
+  'resourceType',
+  'roleKey'
+];
+
+/**
+ * Split markdown into optional YAML frontmatter and body.
+ * @param {string} content
+ * @returns {{ frontmatter: Object|null, body: string }}
+ */
+function splitMarkdownFrontmatter(content) {
+  const text = typeof content === 'string' ? content : '';
+  if (!text.startsWith('---')) {
+    return { frontmatter: null, body: text };
+  }
+  const end = text.indexOf('\n---', 3);
+  if (end < 0) {
+    return { frontmatter: null, body: text };
+  }
+  const raw = text.slice(3, end).trim();
+  const body = text.slice(end + 4).replace(/^(?:\r?\n)+/, '');
+  if (!raw) {
+    return { frontmatter: {}, body };
+  }
+  try {
+    const parsed = yaml.load(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { frontmatter: null, body: text };
+    }
+    return { frontmatter: parsed, body };
+  } catch (_error) {
+    return { frontmatter: null, body: text };
+  }
+}
+
+/**
+ * Project searchable metadata fields from frontmatter.
+ * @param {Object|null|undefined} frontmatter
+ * @returns {Object}
+ */
+function knowledgeSearchMetadataFromFrontmatter(frontmatter) {
+  const out = {};
+  if (!frontmatter || typeof frontmatter !== 'object') {
+    return out;
+  }
+  for (const key of SEARCH_META_KEYS) {
+    const value = frontmatter[key];
+    if (typeof value === 'string' && value.trim()) {
+      out[key] = value.trim();
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  SEARCH_META_KEYS,
+  splitMarkdownFrontmatter,
+  knowledgeSearchMetadataFromFrontmatter
+};

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
+};