@aifabrix/builder 2.49.2 → 2.51.0

package/lib/programmatic/builder-help.js

@@ -0,0 +1,361 @@
+/**
+ * Builder API LLM help topic dispatch (plan 154.5, 154.6).
+ *
+ * @fileoverview Read-only help envelope from MD, fixtures, and 154.4 registries
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { listSectionKeys, getSectionDefinition, buildSchemaFragment } = require('./manifest-section-registry');
+const { SECTION_EDGES, SECTION_REPAIR_HOOKS, getDownstream } = require('./manifest-section-dependency-graph');
+const { HOOK_FLAG_MAP } = require('./manifest-repair');
+const { buildSchemaCatalogTopicData } = require('./builder-help-schema-catalog');
+const {
+  HELP_CONTENT_VERSION,
+  HELP_SCHEMA_VERSION,
+  buildHelpEnvelope
+} = require('./builder-help-envelope');
+const {
+  buildGoldenExamplesTopic,
+  buildGoldenExampleTopic,
+  buildEvidencePatternsTopic,
+  buildEvidencePatternTopic
+} = require('./builder-help-fixtures');
+const { buildConnectedSystemUiTopic } = require('./builder-help-connected-system-ui');
+const { buildEnterpriseSyncFabrixTopic } = require('./builder-help-enterprise-sync-fabrix');
+const {
+  buildPlatformRolesTopic,
+  buildResourceTypeCatalogTopic,
+  buildDimensionsGuideTopic,
+  buildChannelOnboardingTopic
+} = require('./builder-help-governance');
+
+const HELP_TOPICS = Object.freeze([
+  'overview',
+  'sections',
+  'section',
+  'dependencyGraph',
+  'repairRules',
+  'workflow',
+  'schemaCatalog',
+  'subscriptionGuide',
+  'cipOverview',
+  'goldenExamples',
+  'goldenExample',
+  'evidencePatterns',
+  'evidencePattern',
+  'connectedSystemUi',
+  'enterpriseSyncFabrix',
+  'platformRoles',
+  'resourceTypeCatalog',
+  'dimensionsGuide',
+  'channelOnboarding'
+]);
+
+/** @type {Readonly<Record<string, string>>} */
+const PROSE_TOPIC_FILES = Object.freeze({
+  overview: 'overview.md',
+  workflow: 'workflow.md',
+  subscriptionGuide: 'subscription-guide.md',
+  cipOverview: 'cip-overview.md',
+  enterpriseSyncFabrix: 'enterprise-sync-fabrix.md'
+});
+
+const HELP_MD_DIR = path.join(__dirname, 'help-content');
+
+/**
+ * @param {string} message
+ * @returns {Error}
+ */
+function validationError(message) {
+  const err = new Error(message);
+  err.statusCode = 400;
+  return err;
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function stripLinksFromText(text) {
+  let out = String(text || '');
+  out = out.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+  out = out.replace(/https?:\/\/[^\s)]+/gi, '');
+  return out.replace(/\s{2,}/g, ' ').trim();
+}
+
+/**
+ * @param {string} heading
+ * @param {string[]} bodyLines
+ * @returns {{ heading: string, body: string }}
+ */
+function flushMarkdownSection(heading, bodyLines) {
+  return { heading, body: stripLinksFromText(bodyLines.join('\n')) };
+}
+
+/**
+ * @param {string} fileName
+ * @returns {{ title: string, summary: string, sections: Object[], bodyText: string }}
+ */
+function parseMarkdownHelpFile(fileName) {
+  const raw = fs.readFileSync(path.join(HELP_MD_DIR, fileName), 'utf8');
+  let title = '';
+  let summary = '';
+  /** @type {Object[]} */
+  const sections = [];
+  let currentHeading = '';
+  /** @type {string[]} */
+  let currentBody = [];
+
+  for (const line of raw.split(/\r?\n/)) {
+    if (line.startsWith('# ')) {
+      title = stripLinksFromText(line.slice(2));
+    } else if (line.startsWith('## ')) {
+      if (currentHeading) {
+        sections.push(flushMarkdownSection(currentHeading, currentBody));
+      }
+      currentHeading = stripLinksFromText(line.slice(3));
+      currentBody = [];
+    } else {
+      if (!summary && line.trim()) {
+        summary = stripLinksFromText(line);
+      }
+      if (currentHeading) {
+        currentBody.push(line);
+      }
+    }
+  }
+  if (currentHeading) {
+    sections.push(flushMarkdownSection(currentHeading, currentBody));
+  }
+  return { title, summary, sections, bodyText: stripLinksFromText(raw) };
+}
+
+/**
+ * @param {string} topic
+ * @returns {Object}
+ */
+function buildProseTopic(topic) {
+  const fileName = PROSE_TOPIC_FILES[topic];
+  if (!fileName) {
+    throw validationError(`Unknown prose topic: ${topic}`);
+  }
+  const parsed = parseMarkdownHelpFile(fileName);
+  const recommendedNextByTopic = {
+    overview: ['workflow', 'schemaCatalog'],
+    workflow: ['sections', 'connectedSystemUi', 'enterpriseSyncFabrix'],
+    subscriptionGuide: ['section', 'goldenExamples'],
+    cipOverview: ['schemaCatalog', 'section']
+  };
+  const relatedByTopic = {
+    overview: ['workflow', 'sections', 'schemaCatalog'],
+    workflow: ['overview', 'section', 'connectedSystemUi'],
+    subscriptionGuide: ['section', 'goldenExamples', 'evidencePatterns'],
+    cipOverview: ['schemaCatalog', 'section', 'workflow']
+  };
+  return buildHelpEnvelope({
+    topic,
+    key: topic,
+    title: parsed.title,
+    summary: parsed.summary,
+    data: { sections: parsed.sections, bodyText: parsed.bodyText },
+    related: relatedByTopic[topic] || [],
+    recommendedNext: recommendedNextByTopic[topic] || ['sections']
+  });
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildSchemaCatalogTopic(query) {
+  return buildHelpEnvelope({
+    topic: 'schemaCatalog',
+    key: query.resourceType === 'system' || query.resourceType === 'datasource' ? query.resourceType : 'schemaCatalog',
+    title: 'Manifest schema catalog',
+    summary: 'Top-level schema properties and definition keys — use section topic for fragments and validate for errors.',
+    data: buildSchemaCatalogTopicData(query),
+    related: ['section', 'cipOverview'],
+    recommendedNext: ['section', 'cipOverview']
+  });
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildSectionsTopic(query) {
+  const targetFilter =
+    query.resourceType === 'system' || query.resourceType === 'datasource' ? query.resourceType : undefined;
+  const sectionKeys = listSectionKeys(targetFilter)
+    .sort()
+    .map((sectionKey) => {
+      const def = getSectionDefinition(sectionKey);
+      return {
+        sectionKey,
+        target: def.target,
+        mutable: def.mutable,
+        required: def.required,
+        sourceOfTruth: def.sourceOfTruth,
+        blocked: def.blocked === true,
+        repairHooks: [...(def.repairHooks || [])].sort()
+      };
+    });
+  return buildHelpEnvelope({
+    topic: 'sections',
+    key: 'sections',
+    title: 'Manifest sections',
+    summary: 'Governed section keys for external system and datasource manifests.',
+    data: { sectionKeys },
+    related: ['section', 'dependencyGraph', 'repairRules'],
+    recommendedNext: ['workflow', 'section']
+  });
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildSectionTopic(query) {
+  if (!query.sectionKey) {
+    throw validationError('sectionKey is required when topic=section');
+  }
+  const def = getSectionDefinition(String(query.sectionKey));
+  const downstream = getDownstream(String(query.sectionKey)).sort();
+  return buildHelpEnvelope({
+    topic: 'section',
+    key: String(query.sectionKey),
+    title: `Section ${query.sectionKey}`,
+    summary: `Governed manifest section ${query.sectionKey} (${def.target}).`,
+    data: {
+      definition: {
+        target: def.target,
+        paths: def.paths,
+        mutable: def.mutable,
+        required: def.required,
+        sourceOfTruth: def.sourceOfTruth,
+        blocked: def.blocked === true,
+        repairHooks: [...(def.repairHooks || [])].sort()
+      },
+      schemaFragment: buildSchemaFragment(def.target, def.paths[0]),
+      downstreamSectionKeys: downstream
+    },
+    related: downstream.slice(0, 3),
+    recommendedNext: ['dependencyGraph', 'repairRules', 'workflow']
+  });
+}
+
+/**
+ * @returns {Object}
+ */
+function buildDependencyGraphTopic() {
+  const edges = SECTION_EDGES.map(([from, to]) => ({ from, to })).sort((a, b) =>
+    `${a.from}:${a.to}`.localeCompare(`${b.from}:${b.to}`)
+  );
+  const nodeSet = new Set();
+  for (const edge of edges) {
+    nodeSet.add(edge.from);
+    nodeSet.add(edge.to);
+  }
+  return buildHelpEnvelope({
+    topic: 'dependencyGraph',
+    key: 'dependencyGraph',
+    title: 'Section dependency graph',
+    summary: 'Directed edges from source sections to dependent sections for repair traversal.',
+    data: { edges, nodes: [...nodeSet].sort() },
+    related: ['repairRules', 'sections'],
+    recommendedNext: ['repairRules', 'sections']
+  });
+}
+
+/**
+ * @returns {Object}
+ */
+function buildRepairRulesTopic() {
+  const hooks = Object.keys(HOOK_FLAG_MAP).sort();
+  return buildHelpEnvelope({
+    topic: 'repairRules',
+    key: 'repairRules',
+    title: 'Manifest repair rules',
+    summary: 'Named repair hooks and section-to-hook mappings used after section patches.',
+    data: {
+      hooks,
+      hookFlags: hooks.map((hook) => ({ hook, repairFlag: HOOK_FLAG_MAP[hook] })),
+      sectionHooks: Object.keys(SECTION_REPAIR_HOOKS)
+        .sort()
+        .map((sectionKey) => ({
+          sectionKey,
+          hooks: [...SECTION_REPAIR_HOOKS[sectionKey]].sort()
+        }))
+    },
+    related: ['dependencyGraph', 'section'],
+    recommendedNext: ['workflow', 'dependencyGraph']
+  });
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function getBuilderHelp(query = {}) {
+  const topic = query.topic;
+  if (!topic) {
+    throw validationError('topic query parameter is required');
+  }
+  if (!HELP_TOPICS.includes(topic)) {
+    throw validationError(`Unknown topic: ${topic}`);
+  }
+
+  /** @type {Record<string, (q: Object) => Object>} */
+  const handlers = {
+    overview: () => buildProseTopic('overview'),
+    workflow: () => buildProseTopic('workflow'),
+    subscriptionGuide: () => buildProseTopic('subscriptionGuide'),
+    cipOverview: () => buildProseTopic('cipOverview'),
+    schemaCatalog: buildSchemaCatalogTopic,
+    sections: buildSectionsTopic,
+    section: buildSectionTopic,
+    dependencyGraph: () => buildDependencyGraphTopic(),
+    repairRules: () => buildRepairRulesTopic(),
+    goldenExamples: buildGoldenExamplesTopic,
+    goldenExample: buildGoldenExampleTopic,
+    evidencePatterns: buildEvidencePatternsTopic,
+    evidencePattern: buildEvidencePatternTopic,
+    connectedSystemUi: (q) => {
+      const envelope = buildConnectedSystemUiTopic(q);
+      const parsed = parseMarkdownHelpFile('connected-system-ui.md');
+      envelope.data.bodyText = parsed.bodyText;
+      envelope.data.sections = parsed.sections;
+      return envelope;
+    },
+    enterpriseSyncFabrix: (q) => buildEnterpriseSyncFabrixTopic(q),
+    platformRoles: () => buildPlatformRolesTopic(),
+    resourceTypeCatalog: buildResourceTypeCatalogTopic,
+    dimensionsGuide: () => buildDimensionsGuideTopic(),
+    channelOnboarding: () => buildChannelOnboardingTopic()
+  };
+
+  return handlers[topic](query);
+}
+
+/**
+ * @param {Object} query - Help query parameters (topic, sectionKey, exampleKey, filters).
+ * @returns {Object} Help envelope payload returned inside the builder-api success data field.
+ */
+function handleGetBuilderHelp(query) {
+  return getBuilderHelp(query);
+}
+
+module.exports = {
+  HELP_TOPICS,
+  HELP_CONTENT_VERSION,
+  HELP_SCHEMA_VERSION,
+  stripLinksFromText,
+  buildHelpEnvelope,
+  getBuilderHelp,
+  handleGetBuilderHelp
+};

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,114 @@
+/**
+ * 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();
+}
+
+/**
+ * COM-generated Enterprise MCP tools sometimes use OpenAPI operationId forms
+ * (e.g. repository.getrepositorystatus) instead of canonical capability keys
+ * (repository.status). Map canonical → published name when present.
+ *
+ * @type {Record<string, string>}
+ */
+const ENTERPRISE_MCP_TOOL_ALIASES = {
+  'repository.status': 'repository.getrepositorystatus',
+  'repository.sync': 'repository.runrepositorysync',
+  'repository.createReview': 'repository.runrepositorycreatereview',
+  'repository.dispatchPipeline': 'repository.runrepositorydispatchpipeline',
+  'template.materializeWorkspace': 'template.runwizard'
+};
+
+/**
+ * @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');
+  }
+  const toolName = ENTERPRISE_MCP_TOOL_ALIASES[key] || key;
+  return {
+    resourceType: key.slice(0, dotIndex),
+    toolName
+  };
+}
+
+/**
+ * @param {string} systemKey
+ * @param {string} resourceType
+ * @param {string} toolName
+ * @returns {string}
+ */
+function buildMcpExecutePath(systemKey, resourceType, toolName) {
+  return `/api/v1/mcp/servers/${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
+};