@aifabrix/builder 2.52.0 → 2.53.0

package/lib/programmatic/persist-supplied-openapi.js

@@ -0,0 +1,180 @@
+/**
+ * Persist validated OpenAPI documents into workspace openapi/ (517.2).
+ * @fileoverview Runtime-authorized documents only — Builder never browses task store
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { assertValidSystemKey } = require('./system-key');
+const { ensureIntegrationDirectory } = require('./workspace-context');
+
+function sha256Hex(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+function safeOpenApiBasename(filename) {
+  const raw = String(filename || '').trim();
+  const base = path.basename(raw);
+  if (!base || base === '.' || base === '..') {
+    throw new Error('openapi.filename.invalid');
+  }
+  if (raw.includes('..') || raw.includes('/') || raw.includes('\\') || raw.includes('\0')) {
+    throw new Error('openapi.filename.pathTraversal');
+  }
+  return base.endsWith('.json') || base.endsWith('.yaml') || base.endsWith('.yml')
+    ? base
+    : `${base}.json`;
+}
+
+function parseOpenApiDocument(body) {
+  if (body && typeof body === 'object' && !Array.isArray(body)) {
+    return body;
+  }
+  if (typeof body === 'string') {
+    const trimmed = body.trim();
+    if (!trimmed) {
+      throw new Error('openapi.empty');
+    }
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+      return JSON.parse(trimmed);
+    }
+    throw new Error('openapi.yamlUnsupportedInSliceB');
+  }
+  throw new Error('openapi.body.required');
+}
+
+function validateOpenApiDocument(doc) {
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    return { ok: false, reason: 'openapi.invalid', detail: 'Document must be an object' };
+  }
+  const version = typeof doc.openapi === 'string' ? doc.openapi.trim() : '';
+  if (!/^3\./.test(version)) {
+    return {
+      ok: false,
+      reason: 'openapi.invalid',
+      detail: 'Top-level openapi must be a 3.x string'
+    };
+  }
+  if (!doc.paths || typeof doc.paths !== 'object' || Array.isArray(doc.paths)) {
+    return {
+      ok: false,
+      reason: 'openapi.invalid',
+      detail: 'paths object is required'
+    };
+  }
+  if (Object.keys(doc.paths).length === 0) {
+    return {
+      ok: false,
+      reason: 'openapi.invalid',
+      detail: 'paths must not be empty for persist'
+    };
+  }
+  return { ok: true };
+}
+
+function documentBytes(doc) {
+  return Buffer.from(`${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+}
+
+function openapiDirForContext(ctx) {
+  ensureIntegrationDirectory(ctx);
+  return path.join(ctx.getIntegrationRoot(), ctx.systemKey, 'openapi');
+}
+
+function relativeWorkspacePath(ctx, absolutePath) {
+  const root = ctx.getIntegrationRoot();
+  const rel = path.relative(root, absolutePath);
+  // root is .../integration; rel already includes <systemKey>/openapi/<file>
+  return path.join('integration', rel).split(path.sep).join('/');
+}
+
+function persistOneDocument(ctx, row) {
+  let filename = 'unknown.json';
+  try {
+    filename = safeOpenApiBasename(row && (row.filename || row.name));
+  } catch (error) {
+    return {
+      rejected: {
+        filename: String((row && (row.filename || row.name)) || 'unknown'),
+        reason: 'openapi.filename.invalid',
+        detail: error.message || String(error)
+      }
+    };
+  }
+  let doc;
+  try {
+    doc = parseOpenApiDocument(row && row.body);
+  } catch (error) {
+    return {
+      rejected: {
+        filename,
+        reason: 'openapi.invalid',
+        detail: error.message || String(error)
+      }
+    };
+  }
+  const check = validateOpenApiDocument(doc);
+  if (!check.ok) {
+    return { rejected: { filename, reason: check.reason, detail: check.detail } };
+  }
+  const bytes = documentBytes(doc);
+  const digest = `sha256:${sha256Hex(bytes)}`;
+  if (row.digest && String(row.digest).trim() && String(row.digest).trim() !== digest) {
+    return {
+      rejected: {
+        filename,
+        reason: 'openapi.digestMismatch',
+        detail: 'Provided digest does not match serialized body'
+      }
+    };
+  }
+  const dir = openapiDirForContext(ctx);
+  fs.mkdirSync(dir, { recursive: true });
+  const absolutePath = path.join(dir, filename);
+  fs.writeFileSync(absolutePath, bytes);
+  return {
+    accepted: {
+      filename,
+      path: relativeWorkspacePath(ctx, absolutePath),
+      digest
+    }
+  };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ * @returns {{ accepted: Object[], rejected: Object[], workspaceRoot: string }}
+ */
+function persistSuppliedOpenApi(ctx, body) {
+  assertValidSystemKey(ctx.systemKey);
+  const documents = body && Array.isArray(body.documents) ? body.documents : null;
+  if (!documents || documents.length === 0) {
+    throw new Error('documents array is required');
+  }
+  const accepted = [];
+  const rejected = [];
+  for (const row of documents) {
+    const outcome = persistOneDocument(ctx, row);
+    if (outcome.accepted) {
+      accepted.push(outcome.accepted);
+    } else if (outcome.rejected) {
+      rejected.push(outcome.rejected);
+    }
+  }
+  return {
+    accepted,
+    rejected,
+    workspaceRoot: ctx.getIntegrationRoot()
+  };
+}
+
+module.exports = {
+  persistSuppliedOpenApi,
+  validateOpenApiDocument,
+  safeOpenApiBasename,
+  parseOpenApiDocument
+};

package/lib/programmatic/route-handler-map.js

@@ -10,7 +10,11 @@
 
 const { buildContext } = require('./route-handlers-context');
 const { listSystems, createSystem, getSystemManifest, deleteSystem } = require('./workspace-ops');
+const { persistSuppliedOpenApi } = require('./persist-supplied-openapi');
 const { runWizard } = require('./run-wizard');
+const {
+  applyIntegrationDefinitionInWorkspace
+} = require('./run-integration-definition');
 const { runRepair } = require('./run-repair');
 const { runValidate } = require('./run-validate');
 const { runPreviewUpload, runUpload } = require('./run-upload');
@@ -41,6 +45,15 @@ const {
   activateEvidenceCandidates
 } = require('./run-evidence-authoring');
 
+const {
+  buildChannelPackage,
+  getChannelPackageSummary,
+  getChannelPackageZip,
+  patchChannelBranding,
+  getChannelBranding
+} = require('./run-channel-package');
+const { handleGetBuilderHelp } = require('./builder-help');
+
 /** @type {Record<string, Function>} */
 const HANDLER_MAP = {
   listSystems: (_params, auth) => listSystems(buildContext(auth, '_meta')),
@@ -51,12 +64,22 @@ const HANDLER_MAP = {
     }
     return createSystem(buildContext(auth, key), key);
   },
+  persistSuppliedOpenApi: (params, auth, body) =>
+    persistSuppliedOpenApi(
+      buildContext(auth, params.systemKey),
+      body && typeof body === 'object' ? body : {}
+    ),
   getSystemManifest: (params, auth) => getSystemManifest(buildContext(auth, params.systemKey)),
   deleteSystem: (params, auth) => deleteSystem(buildContext(auth, params.systemKey)),
   runWizard: (params, auth, body, query) =>
     runWizard(buildContext(auth, params.systemKey), body, {
       debug: query.debug === 'true' || body.debug === true
     }),
+  applyIntegrationDefinition: (params, auth, body) =>
+    applyIntegrationDefinitionInWorkspace(
+      buildContext(auth, params.systemKey),
+      body && typeof body === 'object' ? body : {}
+    ),
   runRepair: (params, auth, body, query) =>
     runRepair(buildContext(auth, params.systemKey), {
       dryRun: query.dryRun === 'true' || body.dryRun === true,
@@ -179,6 +202,7 @@ const HANDLER_MAP = {
     runRepositoryDispatchPipeline(buildContext(auth, params.systemKey), body),
   health: () => ({ status: 'ok' }),
   ready: () => ({ status: 'ready', dataplaneUrl: process.env.DATAPLANE_URL || null }),
+  getBuilderHelp: (_params, _auth, _body, query) => handleGetBuilderHelp(query || {}),
   getEvidenceMetadata: (params, auth) =>
     getEvidenceMetadata(buildContext(auth, '_evidence'), params.roleKey),
   downloadEvidence: (params, auth, _body, query) =>
@@ -199,7 +223,17 @@ const HANDLER_MAP = {
       roleKey: (body && body.roleKey) || params.roleKey
     }),
   activateEvidenceCandidates: (_params, auth, body) =>
-    activateEvidenceCandidates(buildContext(auth, '_evidence'), body)
+    activateEvidenceCandidates(buildContext(auth, '_evidence'), body),
+  buildChannelPackage: (params, auth, body) =>
+    buildChannelPackage(buildContext(auth, params.systemKey), body || {}),
+  getChannelPackageSummary: (params, auth) =>
+    getChannelPackageSummary(buildContext(auth, params.systemKey)),
+  getChannelPackageZip: (params, auth) =>
+    getChannelPackageZip(buildContext(auth, params.systemKey)),
+  getChannelBranding: (params, auth) =>
+    getChannelBranding(buildContext(auth, params.systemKey)),
+  patchChannelBranding: (params, auth, body) =>
+    patchChannelBranding(buildContext(auth, params.systemKey), body || {})
 };
 
 /**

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,77 @@
+/**
+ * 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 fs = require('../internal/fs-real-sync');
+const {
+  applyIntegrationDefinition,
+  withDefinitionHash
+} = require('../integration-definition');
+const {
+  runWithWorkspaceContext,
+  ensureIntegrationDirectory,
+  WORKSPACE_INTEGRATION_FORMAT
+} = require('./workspace-context');
+const { touchWorkspaceMeta } = require('./workspace-meta');
+
+/**
+ * Workspace openapi/ is the only product resolve root for BID openapiSourceRef
+ * (517.2 persist layout). Do not bind apply to ship-local enrichment fixtures.
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {string}
+ */
+function workspaceOpenApiBaseDir(ctx) {
+  const dir = path.join(ctx.getIntegrationPath(), 'openapi');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * @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: workspaceOpenApiBaseDir(ctx)
+    });
+    touchWorkspaceMeta(ctx, {
+      lastOperation: 'integration-definition-apply',
+      format: WORKSPACE_INTEGRATION_FORMAT,
+      definitionId: out.definitionId,
+      definitionHash: out.definitionHash
+    });
+    return out;
+  });
+}
+
+module.exports = { applyIntegrationDefinitionInWorkspace };