@aifabrix/builder 2.53.1 → 2.55.0

package/lib/programmatic/builder-api-route-dispatch.js

@@ -16,6 +16,7 @@ const { executeCapabilityRequest } = require('./builder-api-request');
  * @property {import('http').ServerResponse} res
  * @property {Function} sendJson
  * @property {Function} sendProblem
+ * @property {Function} [sendRaw]
  * @property {Function} readJsonBody
  * @property {Object} resolved
  * @property {Object} query
@@ -26,54 +27,67 @@ const { executeCapabilityRequest } = require('./builder-api-request');
 
 /**
  * @param {DispatchCapabilityRouteOptions} options
+ * @param {Object} outcome
+ * @returns {void}
  */
-async function dispatchCapabilityRoute(options) {
-  const {
-    req,
-    res,
-    sendJson,
-    sendProblem,
-    readJsonBody,
-    resolved,
-    query,
+function deliverCapabilityOutcome(options, outcome) {
+  const { req, res, sendJson, sendRaw, resolved, logRequestOutcome } = options;
+  if (outcome.raw && typeof sendRaw === 'function') {
+    sendRaw(res, outcome.raw, outcome.requestId);
+  } else {
+    sendJson(res, outcome.httpStatus, outcome.body, outcome.requestId);
+  }
+  logRequestOutcome({
+    requestId: outcome.requestId,
+    correlationId: (outcome.body && outcome.body.correlationId) || outcome.requestId,
+    route: resolved.routeKey,
+    method: req.method,
+    status: outcome.httpStatus,
+    systemKey: resolved.params.systemKey,
+    userId: outcome.userId
+  });
+}
+
+/**
+ * @param {DispatchCapabilityRouteOptions} options
+ * @param {Error & { statusCode?: number, retryAfter?: number }} err
+ * @returns {void}
+ */
+function handleDispatchError(options, err) {
+  const { req, res, sendProblem, resolved, requestId, pathname, logRequestOutcome } = options;
+  const status = err.statusCode || 500;
+  if (status === 409 && err.retryAfter) {
+    res.setHeader('Retry-After', String(err.retryAfter));
+  }
+  sendProblem(req, res, err, status, requestId, pathname);
+  logRequestOutcome({
     requestId,
-    pathname,
-    logRequestOutcome
-  } = options;
+    route: resolved.routeKey,
+    method: req.method,
+    status,
+    systemKey: resolved.params.systemKey,
+    error: err.message
+  });
+}
+
+/**
+ * @param {DispatchCapabilityRouteOptions} options
+ * @returns {Promise<void>}
+ */
+async function dispatchCapabilityRoute(options) {
   try {
     const outcome = await executeCapabilityRequest({
-      req,
-      capability: resolved.capability,
-      params: resolved.params,
-      routeKey: resolved.routeKey,
-      requestId,
-      readJsonBody,
-      query
-    });
-    sendJson(res, outcome.httpStatus, outcome.body, outcome.requestId);
-    logRequestOutcome({
-      requestId: outcome.requestId,
-      correlationId: outcome.body.correlationId,
-      route: resolved.routeKey,
-      method: req.method,
-      status: outcome.httpStatus,
-      systemKey: resolved.params.systemKey,
-      userId: outcome.userId
+      req: options.req,
+      capability: options.resolved.capability,
+      params: options.resolved.params,
+      routeKey: options.resolved.routeKey,
+      requestId: options.requestId,
+      readJsonBody: options.readJsonBody,
+      query: options.query
     });
+    deliverCapabilityOutcome(options, outcome);
   } catch (err) {
-    const status = err.statusCode || 500;
-    if (status === 409 && err.retryAfter) {
-      res.setHeader('Retry-After', String(err.retryAfter));
-    }
-    sendProblem(req, res, err, status, requestId, pathname);
-    logRequestOutcome({
-      requestId,
-      route: resolved.routeKey,
-      method: req.method,
-      status,
-      systemKey: resolved.params.systemKey,
-      error: err.message
-    });
+    handleDispatchError(options, err);
   }
 }
 

package/lib/programmatic/builder-api-server.js

@@ -1,5 +1,5 @@
 /**
- * Builder API HTTP server (plan 154.0 — pre-Nest unified router).
+ * Builder API HTTP server (pre-Nest unified router).
  *
  * @fileoverview Full V1 route set via capability registry
  * @author AI Fabrix Team
@@ -18,6 +18,8 @@ const { writeAccessLog } = require('./access-log');
 const { dispatchCapabilityRoute } = require('./builder-api-route-dispatch');
 const { renderBuilderApiRedocHtml, resolvePublicBaseUrl } = require('./openapi-docs-serving');
 const { buildProblemDetails, writeProblemDetails } = require('./http-problem-details');
+const { sendRaw } = require('./http-raw-response');
+const { handleCorsPreflight } = require('./builder-api-cors');
 
 /**
  * @param {import('http').ServerResponse} res
@@ -171,6 +173,10 @@ async function handleRequest(req, res) {
   const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
   const pathname = url.pathname;
 
+  if (handleCorsPreflight(req, res, requestId, pathname, logRequestOutcome)) {
+    return;
+  }
+
   if (isRedocHtmlPath(pathname) || isOpenApiJsonPath(pathname)) {
     handleOpenApiDocs(req, res, pathname, requestId);
     logRequestOutcome({
@@ -196,6 +202,7 @@ async function handleRequest(req, res) {
     res,
     sendJson,
     sendProblem,
+    sendRaw,
     readJsonBody,
     resolved,
     query,

package/lib/programmatic/capability-registry.js

@@ -49,6 +49,7 @@ const CAPABILITIES = Object.freeze([
   { method: 'GET', route: '/systems/:systemKey/lifecycle', handlerId: 'getLifecycleReport', operationType: 'certify.read', mutating: false },
   { method: 'POST', route: '/systems/:systemKey/upload', handlerId: 'runUpload', operationType: 'apply.dev', mutating: true },
   { method: 'POST', route: '/systems/:systemKey/deploy', handlerId: 'runDeploySystem', operationType: 'apply.prod', mutating: true },
+  { method: 'POST', route: '/systems/:systemKey/download', handlerId: 'runDownload', operationType: 'workspace.write', mutating: true },
   {
     method: 'POST',
     route: '/systems/:systemKey/datasources/:datasourceKey/protection/upload',
@@ -76,8 +77,62 @@ const CAPABILITIES = Object.freeze([
   { method: 'GET', route: '/systems/:systemKey/channels/package/zip', handlerId: 'getChannelPackageZip', operationType: 'channel.read', mutating: false },
   { method: 'GET', route: '/systems/:systemKey/channels/branding', handlerId: 'getChannelBranding', operationType: 'channel.read', mutating: false },
   { method: 'PATCH', route: '/systems/:systemKey/channels/branding', handlerId: 'patchChannelBranding', operationType: 'channel', mutating: true },
+  { method: 'GET', route: '/channels', handlerId: 'listChannelTargets', operationType: 'channel.read', mutating: false },
+  { method: 'GET', route: '/channels/:definitionKey', handlerId: 'getChannelDefinitionDetail', operationType: 'channel.read', mutating: false },
+  {
+    method: 'GET',
+    route: '/channels/:definitionKey/installations/:systemKey',
+    handlerId: 'getChannelInstallation',
+    operationType: 'channel.read',
+    mutating: false
+  },
+  { method: 'POST', route: '/systems/:systemKey/channels/install', handlerId: 'runChannelInstall', operationType: 'channel', mutating: true },
+  { method: 'GET', route: '/systems/:systemKey/channels/install', handlerId: 'getChannelInstall', operationType: 'channel.read', mutating: false },
+  {
+    method: 'GET',
+    route: '/systems/:systemKey/channels/install/help.md',
+    handlerId: 'getChannelInstallHelp',
+    operationType: 'channel.read',
+    mutating: false
+  },
+  {
+    method: 'POST',
+    route: '/systems/:systemKey/channels/install/continue',
+    handlerId: 'continueChannelInstall',
+    operationType: 'channel',
+    mutating: true
+  },
+  { method: 'GET', route: '/systems/:systemKey/channels/artifacts', handlerId: 'listChannelArtifacts', operationType: 'channel.read', mutating: false },
+  {
+    method: 'GET',
+    route: '/systems/:systemKey/channels/artifacts/:artifactId',
+    handlerId: 'getChannelArtifact',
+    operationType: 'channel.read',
+    mutating: false
+  },
+  {
+    method: 'GET',
+    route: '/systems/:systemKey/channels/callbacks/:provider',
+    handlerId: 'getChannelCallback',
+    operationType: 'channel',
+    mutating: true
+  },
+  {
+    method: 'POST',
+    route: '/systems/:systemKey/channels/callbacks/:provider',
+    handlerId: 'postChannelCallback',
+    operationType: 'channel',
+    mutating: true
+  },
   { method: 'GET', route: '/health', handlerId: 'health', operationType: 'infra', mutating: false },
   { method: 'GET', route: '/health/ready', handlerId: 'ready', operationType: 'infra', mutating: false },
+  {
+    method: 'GET',
+    route: '/auth/permissions',
+    handlerId: 'getAuthPermissions',
+    operationType: 'infra',
+    mutating: false
+  },
   {
     method: 'GET',
     route: '/help',

package/lib/programmatic/channel-install-help-resolve.js

@@ -0,0 +1,359 @@
+/**
+ * Resolve channel install help for a definition or instance key.
+ *
+ * @fileoverview POST identity + per-instance GET (session or synthesized)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { toChannelInstallEnvelope } = require('../channels/channel-install-envelope');
+const { toChannelInstallHttpPayload } = require('../channels/channel-install-http-payload');
+const { resolveChannelRuntimeValues } = require('../channels/channel-runtime-resolver');
+const { vendorFacingUrlsFromCtx } = require('../channels/vendor-dataplane-url');
+const {
+  getChannelDefinition,
+  listChannelDefinitionKeys
+} = require('../channels/channel-definition-registry');
+const {
+  readChannelInstallSession,
+  writeChannelInstallSession,
+  httpError
+} = require('./channel-install-session');
+const { peekPortalMicrosoftLogin } = require('../channels/microsoft-provisioning/login-portal');
+
+/**
+ * @param {Object} payload
+ * @param {string} definitionKey
+ * @param {string} installationKey
+ * @returns {Object}
+ */
+function attachInstallIdentity(payload, definitionKey, installationKey) {
+  return {
+    ...payload,
+    definitionKey,
+    installationKey,
+    systemKey: installationKey
+  };
+}
+
+/**
+ * @param {Object[]} [actions]
+ * @param {string} id
+ * @returns {string}
+ */
+function copyActionValue(actions, id) {
+  const row = (actions || []).find((action) => action && action.id === id);
+  return row && typeof row.value === 'string' ? row.value.trim() : '';
+}
+
+/**
+ * @param {Object} session
+ * @returns {Object}
+ */
+function runtimeValuesFromStoredEnvelope(session) {
+  const envelope = session.envelope || {};
+  const use = envelope.useValues || {};
+  const actions = envelope.userActions || [];
+  return {
+    appName:
+      use.Name ||
+      copyActionValue(actions, 'copy-name') ||
+      session.displayName ||
+      session.name ||
+      '',
+    appDescription: use.Description || copyActionValue(actions, 'copy-description') || '',
+    mcpUrl: use['Server URL'] || copyActionValue(actions, 'copy-server-url') || ''
+  };
+}
+
+/**
+ * @param {Object} session
+ * @returns {Object}
+ */
+function copilotRuntimeFromSession(session) {
+  const peek = peekPortalMicrosoftLogin(session.installationKey) || {};
+  return {
+    appName: session.displayName || session.name,
+    oauthPluginVaultReferenceId: session.oauthPluginVaultReferenceId,
+    packageAppId: session.packageAppId,
+    microsoftLoginUrl: peek.loginUrl || session.microsoftLoginUrl,
+    microsoftLoginUserCode: peek.userCode || session.microsoftLoginUserCode,
+    microsoftAuthConfigFallback: session.microsoftAuthConfigFallback === true
+  };
+}
+
+/**
+ * @param {Object} session
+ * @returns {Object}
+ */
+function refreshCopilotEnvelope(session, ctx) {
+  const definitionKey = session.definitionKey || session.channelTarget;
+  if (definitionKey !== 'microsoft-copilot') {
+    return session.envelope;
+  }
+  return toChannelInstallEnvelope({
+    channelTarget: definitionKey,
+    displayName: session.displayName || session.name || 'Microsoft Copilot',
+    ctx: {
+      instanceSystemKey: session.installationKey,
+      projectRoot: ctx && typeof ctx.getUserRoot === 'function' ? ctx.getUserRoot() : undefined
+    },
+    runtimeValues: copilotRuntimeFromSession(session),
+    verdicts: (session.envelope && session.envelope.verdicts) || {
+      runtime: { ok: true, label: 'Deployed' }
+    }
+  });
+}
+
+/**
+ * Rebuild ChatGPT help so Open ChatGPT Apps uses the current drafts URL.
+ * @param {Object} session
+ * @returns {Object}
+ */
+function refreshChatGptEnvelope(session) {
+  const definitionKey = session.definitionKey || session.channelTarget;
+  if (definitionKey !== 'chatgpt') {
+    return session.envelope;
+  }
+  return toChannelInstallEnvelope({
+    channelTarget: definitionKey,
+    displayName: session.displayName || session.name || 'ChatGPT',
+    ctx: {},
+    runtimeValues: runtimeValuesFromStoredEnvelope(session),
+    verdicts: (session.envelope && session.envelope.verdicts) || {
+      runtime: { ok: true, label: 'Deployed' }
+    }
+  });
+}
+
+/**
+ * Rebuild Claude help so connectors URL and Name/Server URL stay current.
+ * @param {Object} session
+ * @returns {Object}
+ */
+function refreshClaudeEnvelope(session) {
+  const definitionKey = session.definitionKey || session.channelTarget;
+  if (definitionKey !== 'claude') {
+    return session.envelope;
+  }
+  return toChannelInstallEnvelope({
+    channelTarget: definitionKey,
+    displayName: session.displayName || session.name || 'Claude',
+    ctx: {},
+    runtimeValues: runtimeValuesFromStoredEnvelope(session),
+    verdicts: (session.envelope && session.envelope.verdicts) || {
+      runtime: { ok: true, label: 'Deployed' }
+    }
+  });
+}
+
+/**
+ * @param {Object} session
+ * @returns {Object}
+ */
+function refreshStoredEnvelope(session, ctx) {
+  const definitionKey = session.definitionKey || session.channelTarget;
+  if (definitionKey === 'microsoft-copilot') {
+    return refreshCopilotEnvelope(session, ctx);
+  }
+  if (definitionKey === 'chatgpt') {
+    return refreshChatGptEnvelope(session);
+  }
+  if (definitionKey === 'claude') {
+    return refreshClaudeEnvelope(session);
+  }
+  return session.envelope;
+}
+
+function helpPayloadFromSession(session, ctx) {
+  const envelope = refreshStoredEnvelope(session, ctx) || session.envelope;
+  if (envelope && typeof envelope === 'object') {
+    const payload = toChannelInstallHttpPayload(envelope);
+    const definitionKey = session.definitionKey || session.channelTarget;
+    const installationKey = session.installationKey;
+    if (!definitionKey || !installationKey) {
+      return payload;
+    }
+    return attachInstallIdentity(payload, definitionKey, installationKey);
+  }
+  const payload = {
+    helpMarkdown: session.helpMarkdown,
+    helpMarkdownContentType: 'text/markdown'
+  };
+  if (session.phase === 'waitingForUser') {
+    payload.refreshHintSeconds = 15;
+  }
+  const definitionKey = session.definitionKey || session.channelTarget;
+  const installationKey = session.installationKey;
+  if (!definitionKey || !installationKey) {
+    return payload;
+  }
+  return attachInstallIdentity(payload, definitionKey, installationKey);
+}
+
+/**
+ * @param {string} instanceKey
+ * @returns {string|null}
+ */
+function definitionKeyFromInstanceKey(instanceKey) {
+  const keys = listChannelDefinitionKeys().sort((left, right) => right.length - left.length);
+  for (const key of keys) {
+    if (instanceKey === key || instanceKey.startsWith(`${key}-`)) {
+      return key;
+    }
+  }
+  return null;
+}
+
+/**
+ * Catalog key for install/continue. Path may be the definition or the instance.
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {string}
+ */
+function resolveInstallDefinitionKey(ctx) {
+  if (getChannelDefinition(ctx.systemKey)) {
+    return ctx.systemKey;
+  }
+  const session = readChannelInstallSession(ctx);
+  const fromSession = session && (session.definitionKey || session.channelTarget);
+  if (typeof fromSession === 'string' && getChannelDefinition(fromSession)) {
+    return fromSession;
+  }
+  const fromInstance = definitionKeyFromInstanceKey(ctx.systemKey);
+  if (fromInstance && getChannelDefinition(fromInstance)) {
+    return fromInstance;
+  }
+  return ctx.systemKey;
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {Object|null}
+ */
+function readInstanceSystemDoc(ctx) {
+  const filePath = path.join(ctx.getIntegrationPath(), `${ctx.systemKey}-system.json`);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {Object} doc
+ * @param {string} instanceKey
+ * @returns {string|null}
+ */
+function definitionKeyFromDoc(doc, instanceKey) {
+  const stamped = doc && doc.channel && doc.channel.definitionKey;
+  if (typeof stamped === 'string' && stamped.trim()) {
+    return stamped.trim();
+  }
+  return definitionKeyFromInstanceKey(instanceKey);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {string} definitionKey
+ * @param {string} displayName
+ * @param {string} [description]
+ * @returns {Object}
+ */
+function runtimeValuesForHelp(ctx, definitionKey, displayName, description) {
+  const vendor = vendorFacingUrlsFromCtx(ctx);
+  return resolveChannelRuntimeValues({
+    dataplaneBaseUrl: vendor.dataplaneBaseUrl,
+    controllerUrl: vendor.controllerUrl,
+    channelTarget: definitionKey,
+    appName: displayName,
+    instanceSystemKey: ctx.systemKey,
+    environment: ctx.environment,
+    appDescription: description || ''
+  });
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} doc
+ * @returns {{ payload: Object, envelope: Object }|null}
+ */
+function synthesizeInstallHelp(ctx, doc) {
+  const installationKey = ctx.systemKey;
+  const definitionKey = definitionKeyFromDoc(doc, installationKey);
+  if (!definitionKey || !getChannelDefinition(definitionKey)) {
+    return null;
+  }
+  const displayName =
+    (typeof doc.displayName === 'string' && doc.displayName.trim()) || installationKey;
+  const envelope = toChannelInstallEnvelope({
+    channelTarget: definitionKey,
+    displayName,
+    ctx: {
+      dataplaneUrl: ctx.dataplaneUrl,
+      environment: ctx.environment,
+      projectRoot: ctx.getUserRoot()
+    },
+    runtimeValues: runtimeValuesForHelp(ctx, definitionKey, displayName, doc.description),
+    verdicts: { runtime: { ok: true, label: 'Deployed' } }
+  });
+  const payload = attachInstallIdentity(
+    toChannelInstallHttpPayload(envelope),
+    definitionKey,
+    installationKey
+  );
+  writeChannelInstallSession(ctx, {
+    name: displayName,
+    displayName,
+    phase: envelope.phase,
+    envelope,
+    definitionKey,
+    installationKey
+  });
+  return { payload, envelope };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [query]
+ * @returns {Object}
+ */
+function resolveChannelInstallHelp(ctx, query = {}) {
+  const session = readChannelInstallSession(ctx);
+  if (session) {
+    if (query.verbose === 'true' || query.verbose === true) {
+      return refreshStoredEnvelope(session, ctx) || session.envelope;
+    }
+    return helpPayloadFromSession(session, ctx);
+  }
+  if (getChannelDefinition(ctx.systemKey)) {
+    throw httpError('Channel install session not found. POST install first.', 404);
+  }
+  const doc = readInstanceSystemDoc(ctx);
+  if (!doc) {
+    throw httpError('Channel install session not found. POST install first.', 404);
+  }
+  const synthesized = synthesizeInstallHelp(ctx, doc);
+  if (!synthesized) {
+    throw httpError('Channel install session not found. POST install first.', 404);
+  }
+  if (query.verbose === 'true' || query.verbose === true) {
+    return synthesized.envelope;
+  }
+  return synthesized.payload;
+}
+
+module.exports = {
+  attachInstallIdentity,
+  helpPayloadFromSession,
+  definitionKeyFromInstanceKey,
+  resolveInstallDefinitionKey,
+  resolveChannelInstallHelp
+};