@aifabrix/builder 2.49.1 → 2.50.0

package/lib/programmatic/capability-registry.js

@@ -0,0 +1,77 @@
+/**
+ * Normative builder-api route capability allowlist (plan 154.0 §3.1).
+ *
+ * @fileoverview Single source for HTTP route registration metadata
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** @type {ReadonlyArray<{ method: string, route: string, handlerId: string, operationType: string, mutating: boolean }>} */
+const CAPABILITIES = Object.freeze([
+  { method: 'GET', route: '/workspaces/me/systems', handlerId: 'listSystems', operationType: 'workspace.read', mutating: false },
+  { method: 'POST', route: '/workspaces/me/systems', handlerId: 'createSystem', operationType: 'workspace.write', mutating: true },
+  { method: 'GET', route: '/workspaces/me/systems/:systemKey', handlerId: 'getSystemManifest', operationType: 'workspace.read', mutating: false },
+  { method: 'DELETE', route: '/workspaces/me/systems/:systemKey', handlerId: 'deleteSystem', operationType: 'workspace.write', mutating: true },
+  { method: 'POST', route: '/systems/:systemKey/wizard', handlerId: 'runWizard', operationType: 'plan', mutating: true },
+  { method: 'POST', route: '/systems/:systemKey/repair', handlerId: 'runRepair', operationType: 'plan', mutating: true },
+  { method: 'GET', route: '/systems/:systemKey/manifest/sections', handlerId: 'listManifestSections', operationType: 'workspace.read', mutating: false },
+  { method: 'GET', route: '/systems/:systemKey/manifest/section/:sectionKey', handlerId: 'getManifestSection', operationType: 'workspace.read', mutating: false },
+  { method: 'PATCH', route: '/systems/:systemKey/manifest/section/:sectionKey', handlerId: 'patchManifestSection', operationType: 'workspace.write', mutating: true },
+  { method: 'POST', route: '/systems/:systemKey/manifest/repair', handlerId: 'runManifestRepair', operationType: 'plan', mutating: true },
+  {
+    method: 'GET',
+    route: '/systems/:systemKey/datasources/:datasourceKey/section/:sectionKey',
+    handlerId: 'getDatasourceManifestSection',
+    operationType: 'workspace.read',
+    mutating: false
+  },
+  {
+    method: 'PATCH',
+    route: '/systems/:systemKey/datasources/:datasourceKey/section/:sectionKey',
+    handlerId: 'patchDatasourceManifestSection',
+    operationType: 'workspace.write',
+    mutating: true
+  },
+  { method: 'POST', route: '/systems/:systemKey/validate', handlerId: 'runValidate', operationType: 'validate', mutating: false },
+  { method: 'POST', route: '/systems/:systemKey/preview-upload', handlerId: 'runPreviewUpload', operationType: 'validate', mutating: false },
+  { method: 'POST', route: '/systems/:systemKey/test', handlerId: 'runTest', operationType: 'test', mutating: true },
+  { method: 'POST', route: '/systems/:systemKey/certify/:pillar', handlerId: 'runCertifyPillar', operationType: 'certify', mutating: true },
+  { 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/template/materialize', handlerId: 'materializeTemplate', operationType: 'template', mutating: true },
+  { method: 'GET', route: '/systems/:systemKey/workspace/status', handlerId: 'getWorkspaceStatus', operationType: 'workspace.read', mutating: false },
+  { method: 'POST', route: '/systems/:systemKey/workspace/diff', handlerId: 'runWorkspaceDiff', operationType: 'workspace.read', mutating: false },
+  { method: 'POST', route: '/systems/:systemKey/workspace/reset', handlerId: 'resetWorkspaceFromTemplate', operationType: 'template', mutating: true },
+  { method: 'POST', route: '/systems/:systemKey/repository/sync', handlerId: 'runRepositorySync', operationType: 'repository', mutating: true },
+  { method: 'POST', route: '/systems/:systemKey/repository/create-review', handlerId: 'runRepositoryCreateReview', operationType: 'repository', mutating: true },
+  { method: 'GET', route: '/systems/:systemKey/repository/status', handlerId: 'getRepositoryStatus', operationType: 'repository.read', mutating: false },
+  { method: 'POST', route: '/systems/:systemKey/repository/dispatch-pipeline', handlerId: 'runRepositoryDispatchPipeline', operationType: 'repository', mutating: true },
+  { method: 'GET', route: '/health', handlerId: 'health', operationType: 'infra', mutating: false },
+  { method: 'GET', route: '/health/ready', handlerId: 'ready', operationType: 'infra', mutating: false }
+]);
+
+/**
+ * @param {string} method
+ * @param {string} routePattern
+ * @returns {boolean}
+ */
+function isAllowedCapability(method, routePattern) {
+  const m = String(method || '').toUpperCase();
+  return CAPABILITIES.some((c) => c.method === m && c.route === routePattern);
+}
+
+/**
+ * @param {string} handlerId
+ * @returns {Object|undefined}
+ */
+function getCapabilityByHandlerId(handlerId) {
+  return CAPABILITIES.find((c) => c.handlerId === handlerId);
+}
+
+module.exports = {
+  CAPABILITIES,
+  isAllowedCapability,
+  getCapabilityByHandlerId
+};

package/lib/programmatic/command-options.js

@@ -0,0 +1,32 @@
+/**
+ * Merge WorkspaceContext auth into lib/commands options.
+ *
+ * @fileoverview Programmatic auth injection for CLI wrappers
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { buildProgrammaticAuthContext } = require('./auth-config');
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [options]
+ * @returns {Object}
+ */
+function mergeProgrammaticOptions(ctx, options = {}) {
+  const auth = buildProgrammaticAuthContext(ctx);
+  return {
+    ...options,
+    authConfig: auth.authConfig,
+    dataplaneUrl: auth.dataplaneUrl,
+    environment: auth.environment,
+    silentResolve: true,
+    minimal: options.minimal !== false
+  };
+}
+
+module.exports = {
+  mergeProgrammaticOptions
+};

package/lib/programmatic/enterprise-mcp-client.js

@@ -0,0 +1,98 @@
+/**
+ * Enterprise MCP capability client for builder-api (plan 154.1).
+ *
+ * @fileoverview Provider-neutral invoke via Dataplane MCP execute routes
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('../api/index');
+const { buildProgrammaticAuthContext } = require('./auth-config');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+/**
+ * @returns {string}
+ */
+function resolveEnterpriseMcpSystemKey() {
+  return (process.env.ENTERPRISE_MCP_SYSTEM_KEY || 'enterprise-integration-lifecycle').trim();
+}
+
+/**
+ * @param {string} capabilityKey
+ * @returns {{ resourceType: string, toolName: string }}
+ */
+function parseCapabilityKey(capabilityKey) {
+  const key = String(capabilityKey || '').trim();
+  const dotIndex = key.indexOf('.');
+  if (dotIndex <= 0) {
+    throw new Error('capabilityKey must be resourceType.operation form');
+  }
+  return {
+    resourceType: key.slice(0, dotIndex),
+    toolName: key
+  };
+}
+
+/**
+ * @param {string} systemKey
+ * @param {string} resourceType
+ * @param {string} toolName
+ * @returns {string}
+ */
+function buildMcpExecutePath(systemKey, resourceType, toolName) {
+  return `/api/v1/mcp/${encodeURIComponent(systemKey)}/${encodeURIComponent(resourceType)}/tools/${encodeURIComponent(toolName)}/execute`;
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [userArguments]
+ * @returns {Object}
+ */
+function buildMcpArguments(ctx, userArguments = {}) {
+  return {
+    ...userArguments,
+    integrationSystemKey: ctx.systemKey,
+    ownerUserId: ctx.userId,
+    environment: ctx.environment
+  };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {string} capabilityKey
+ * @param {Object} [userArguments]
+ * @param {Object} [options]
+ * @param {string} [options.mcpSystemKey]
+ * @returns {Promise<Object>}
+ */
+async function invokeEnterpriseMcpCapability(ctx, capabilityKey, userArguments = {}, options = {}) {
+  const { resourceType, toolName } = parseCapabilityKey(capabilityKey);
+  const auth = buildProgrammaticAuthContext(ctx);
+  const mcpSystemKey = options.mcpSystemKey || resolveEnterpriseMcpSystemKey();
+  const client = createDataplaneApiClient(auth.dataplaneUrl, auth.authConfig);
+  const path = buildMcpExecutePath(mcpSystemKey, resourceType, toolName);
+  const res = await client.post(path, {
+    body: {
+      toolName,
+      arguments: buildMcpArguments(ctx, userArguments)
+    }
+  });
+  if (res && res.success === false) {
+    const msg =
+      (res.error && (res.error.formattedError || res.error.error || res.error.message)) ||
+      res.formattedError ||
+      `Enterprise MCP capability failed: ${capabilityKey}`;
+    throw new Error(msg);
+  }
+  return unwrapApiData(res) || res;
+}
+
+module.exports = {
+  invokeEnterpriseMcpCapability,
+  parseCapabilityKey,
+  buildMcpExecutePath,
+  buildMcpArguments,
+  resolveEnterpriseMcpSystemKey
+};

package/lib/programmatic/http-problem-details.js

@@ -0,0 +1,99 @@
+/**
+ * RFC 7807 Problem Details for builder-api HTTP responses.
+ *
+ * @fileoverview Aligns with miso-client express/error-response (miso / dataplane)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getErrorTypeUri, getErrorTitle } = require('@aifabrix/miso-client');
+
+/** @type {Record<number, { type: string, title: string }>} */
+const BUILDER_STATUS_OVERRIDES = Object.freeze({
+  408: { type: '/Errors/GatewayTimeout', title: 'Request Timeout' },
+  413: { type: '/Errors/BadRequest', title: 'Payload Too Large' }
+});
+
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function errorMessageFromUnknown(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  if (error === null || error === undefined) {
+    return 'An error occurred';
+  }
+  return String(error) || 'An error occurred';
+}
+
+/**
+ * @param {import('http').IncomingMessage|Object|null} req
+ * @param {string} [pathname]
+ * @returns {{ originalUrl: string, headers: Object, correlationId?: string }}
+ */
+function buildRequestContext(req, pathname) {
+  const headers = req?.headers || {};
+  const url = pathname || (req?.url ? String(req.url).split('?')[0] : '/');
+  return {
+    originalUrl: url,
+    headers,
+    correlationId: headers['x-correlation-id'] || headers['x-request-id'] || undefined
+  };
+}
+
+/**
+ * @param {unknown} error
+ * @param {number} statusCode
+ * @param {import('http').IncomingMessage|Object|null} req
+ * @param {string} correlationId
+ * @param {string} [pathname]
+ * @returns {Object}
+ */
+function buildProblemDetails(error, statusCode, req, correlationId, pathname) {
+  const requestContext = buildRequestContext(req, pathname);
+  const override = BUILDER_STATUS_OVERRIDES[statusCode];
+  const customType =
+    error && typeof error === 'object' && typeof error.errorType === 'string' ? error.errorType : null;
+  const body = {
+    type: customType || override?.type || getErrorTypeUri(statusCode),
+    title: override?.title || getErrorTitle(statusCode),
+    status: statusCode,
+    detail: errorMessageFromUnknown(error),
+    instance: requestContext.originalUrl
+  };
+  const finalCorrelationId =
+    correlationId ||
+    requestContext.correlationId ||
+    requestContext.headers['x-correlation-id'] ||
+    requestContext.headers['x-request-id'];
+  if (finalCorrelationId) {
+    body.correlationId = String(finalCorrelationId);
+  }
+  if (error && typeof error === 'object' && Array.isArray(error.validationErrors) && error.validationErrors.length) {
+    body.errors = error.validationErrors;
+  }
+  return body;
+}
+
+/**
+ * @param {import('http').ServerResponse} res
+ * @param {number} status
+ * @param {Object} body
+ */
+function writeProblemDetails(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'application/problem+json' });
+  res.end(JSON.stringify(body));
+}
+
+module.exports = {
+  buildProblemDetails,
+  writeProblemDetails,
+  buildRequestContext
+};

package/lib/programmatic/http-route-match.js

@@ -0,0 +1,40 @@
+/**
+ * Match builder-api route patterns to pathnames.
+ *
+ * @fileoverview /systems/:systemKey/upload style matching
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const BASE = '/api/v1/builder';
+
+/**
+ * @param {string} pattern
+ * @param {string} pathname
+ * @returns {Object|null}
+ */
+function matchRoutePattern(pattern, pathname) {
+  const fullPattern = `${BASE}${pattern}`;
+  const names = [];
+  const regexBody = fullPattern.replace(/:[A-Za-z]+/g, (token) => {
+    names.push(token.slice(1));
+    return '([^/]+)';
+  });
+  const re = new RegExp(`^${regexBody}$`);
+  const match = pathname.match(re);
+  if (!match) {
+    return null;
+  }
+  const params = {};
+  names.forEach((name, idx) => {
+    params[name] = match[idx + 1];
+  });
+  return params;
+}
+
+module.exports = {
+  BASE,
+  matchRoutePattern
+};

package/lib/programmatic/idempotency-cache.js

@@ -0,0 +1,69 @@
+/**
+ * In-memory idempotency cache for mutating routes — V1 single replica.
+ *
+ * @fileoverview Key: userId + Idempotency-Key + route + systemKey
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** @type {Map<string, { expiresAt: number, entry: Object }>} */
+const cache = new Map();
+
+/**
+ * @param {Object} params
+ * @param {string} params.userId
+ * @param {string} params.idempotencyKey
+ * @param {string} params.route
+ * @param {string} params.systemKey
+ * @returns {string}
+ */
+function buildIdempotencyCacheKey(params) {
+  return `${params.userId}:${params.route}:${params.systemKey}:${params.idempotencyKey}`;
+}
+
+/**
+ * @param {Object} params
+ * @param {string} params.userId
+ * @param {string} params.idempotencyKey
+ * @param {string} params.route
+ * @param {string} params.systemKey
+ * @returns {Object|null}
+ */
+function getIdempotentResult(params) {
+  const key = buildIdempotencyCacheKey(params);
+  const row = cache.get(key);
+  if (!row) {
+    return null;
+  }
+  if (Date.now() > row.expiresAt) {
+    cache.delete(key);
+    return null;
+  }
+  return row.entry;
+}
+
+/**
+ * @param {Object} params
+ * @param {Object} entry
+ * @param {number} [ttlMs]
+ */
+function setIdempotentResult(params, entry, ttlMs = DEFAULT_TTL_MS) {
+  const key = buildIdempotencyCacheKey(params);
+  cache.set(key, { expiresAt: Date.now() + ttlMs, entry });
+}
+
+function clearIdempotencyCache() {
+  cache.clear();
+}
+
+module.exports = {
+  getIdempotentResult,
+  setIdempotentResult,
+  clearIdempotencyCache,
+  buildIdempotencyCacheKey,
+  DEFAULT_TTL_MS
+};

package/lib/programmatic/index.js

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview builder-api public exports
+ */
+
+'use strict';
+
+const workspaceContext = require('./workspace-context');
+const runUpload = require('./run-upload');
+const runWizard = require('./run-wizard');
+const runRepair = require('./run-repair');
+const runValidate = require('./run-validate');
+const runTest = require('./run-test');
+const runCertify = require('./run-certify');
+const runLifecycle = require('./run-lifecycle');
+const workspaceOps = require('./workspace-ops');
+const capabilityRegistry = require('./capability-registry');
+const bearerAuth = require('./bearer-auth');
+const workspaceMeta = require('./workspace-meta');
+const authConfig = require('./auth-config');
+const commandOptions = require('./command-options');
+const builderApiServer = require('./builder-api-server');
+const routeHandlers = require('./route-handlers');
+const openapiSpec = require('./openapi-spec');
+const workspaceCleanup = require('./workspace-cleanup');
+const nestHttpBridge = require('./nest-http-bridge');
+const requestTimeout = require('./request-timeout');
+const enterpriseMcpClient = require('./enterprise-mcp-client');
+
+module.exports = {
+  ...workspaceContext,
+  ...runUpload,
+  ...runWizard,
+  ...runRepair,
+  ...runValidate,
+  ...runTest,
+  ...runCertify,
+  ...runLifecycle,
+  ...workspaceOps,
+  ...capabilityRegistry,
+  ...bearerAuth,
+  ...workspaceMeta,
+  ...authConfig,
+  ...commandOptions,
+  builderApiServer,
+  routeHandlers,
+  openapiSpec,
+  workspaceCleanup,
+  nestHttpBridge,
+  requestTimeout,
+  enterpriseMcpClient,
+  // Back-compat alias
+  spikeServer: builderApiServer
+};

package/lib/programmatic/integration-path-scope.js

@@ -0,0 +1,39 @@
+/**
+ * AsyncLocalStorage scope for per-request integration path resolution (builder-api).
+ *
+ * @fileoverview Programmatic integration path override for multi-user workspaces
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { AsyncLocalStorage } = require('async_hooks');
+
+const storage = new AsyncLocalStorage();
+
+/**
+ * @typedef {Object} IntegrationPathScope
+ * @property {(systemKey: string) => string} resolveIntegrationPath
+ */
+
+/**
+ * @param {IntegrationPathScope} scope
+ * @param {() => Promise<*> | *} fn
+ * @returns {Promise<*>}
+ */
+function runWithIntegrationPathScope(scope, fn) {
+  return storage.run(scope, fn);
+}
+
+/**
+ * @returns {IntegrationPathScope | undefined}
+ */
+function getIntegrationPathScope() {
+  return storage.getStore();
+}
+
+module.exports = {
+  runWithIntegrationPathScope,
+  getIntegrationPathScope
+};

package/lib/programmatic/log-redaction.js

@@ -0,0 +1,66 @@
+/**
+ * Redact sensitive values from structured logs (plan 154.0 §7).
+ *
+ * @fileoverview Never log Bearer tokens or secret field values
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const SENSITIVE_KEY_RE =
+  /^(authorization|bearer|token|secret|password|apikey|clientsecret|accesstoken|refreshtoken)$/i;
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function redactSecretString(value) {
+  if (!value || typeof value !== 'string') {
+    return '[REDACTED]';
+  }
+  if (value.length <= 8) {
+    return '[REDACTED]';
+  }
+  return `[REDACTED:${value.slice(-4)}]`;
+}
+
+/**
+ * @param {unknown} input
+ * @returns {unknown}
+ */
+function redactForLog(input) {
+  if (input === null || input === undefined) {
+    return input;
+  }
+  if (typeof input === 'string') {
+    if (/^Bearer\s+/i.test(input)) {
+      return 'Bearer [REDACTED]';
+    }
+    if (/^(kv|secure):\/\//i.test(input)) {
+      return '[REDACTED:uri]';
+    }
+    return input;
+  }
+  if (Array.isArray(input)) {
+    return input.map((item) => redactForLog(item));
+  }
+  if (typeof input !== 'object') {
+    return input;
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (SENSITIVE_KEY_RE.test(key)) {
+      out[key] = typeof value === 'string' ? redactSecretString(value) : '[REDACTED]';
+      continue;
+    }
+    out[key] = redactForLog(value);
+  }
+  return out;
+}
+
+module.exports = {
+  redactForLog,
+  redactSecretString,
+  SENSITIVE_KEY_RE
+};