@aifabrix/builder 2.49.2 → 2.50.0

package/lib/programmatic/openapi-docs-serving.js

@@ -0,0 +1,123 @@
+/**
+ * Public OpenAPI / ReDoc serving for builder-api (aligned with dataplane / miso-controller).
+ *
+ * @fileoverview ReDoc HTML shell + request-derived public base URL
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+const { getProjectRoot } = require('../utils/paths');
+const { BASE } = require('./http-route-match');
+
+const REDOC_JS_URL = 'https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js';
+const REDOC_TEMPLATE_REL = path.join('templates', 'openapi', 'redoc_page.html');
+
+/** @type {string|null} */
+let cachedTemplate = null;
+
+/**
+ * Resolve shipped ReDoc HTML template (stable under lib/ layout; not tied to mutable PROJECT_ROOT).
+ * @returns {string}
+ */
+function resolveRedocTemplatePath() {
+  const fromModule = path.resolve(__dirname, '..', '..', REDOC_TEMPLATE_REL);
+  if (fs.existsSync(fromModule)) {
+    return fromModule;
+  }
+  return path.join(getProjectRoot(), REDOC_TEMPLATE_REL);
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @returns {string}
+ */
+function resolvePublicBaseUrl(req) {
+  const rawProto = String(req.headers['x-forwarded-proto'] || '').trim();
+  const proto = rawProto ? rawProto.split(',')[0].trim() : 'http';
+  const rawHost = String(req.headers['x-forwarded-host'] || req.headers.host || '').trim();
+  const host = rawHost ? rawHost.split(',')[0].trim() : '';
+  if (!host) {
+    return '';
+  }
+  return `${proto}://${host}`.replace(/\/$/, '');
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeHtmlAttr(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/</g, '&lt;');
+}
+
+/**
+ * @returns {string}
+ */
+function loadRedocTemplate() {
+  if (cachedTemplate) {
+    return cachedTemplate;
+  }
+  cachedTemplate = fs.readFileSync(resolveRedocTemplatePath(), 'utf8');
+  return cachedTemplate;
+}
+
+/**
+ * @param {Record<string, string>} replacements
+ * @returns {string}
+ */
+function applyTemplateReplacements(replacements) {
+  let html = loadRedocTemplate();
+  for (const [token, value] of Object.entries(replacements)) {
+    html = html.split(token).join(value);
+  }
+  return html;
+}
+
+/**
+ * @returns {string}
+ */
+function openapiJsonPath() {
+  return `${BASE}/api-docs/openapi.json`;
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @returns {string}
+ */
+function absoluteOpenApiJsonUrl(req) {
+  const base = resolvePublicBaseUrl(req);
+  const relative = openapiJsonPath();
+  return base ? `${base}${relative}` : relative;
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @returns {string}
+ */
+function renderBuilderApiRedocHtml(req) {
+  const specUrl = escapeHtmlAttr(absoluteOpenApiJsonUrl(req));
+  const jsonDownloadUrl = `${specUrl}${specUrl.includes('?') ? '&' : '?'}attachment=true`;
+  return applyTemplateReplacements({
+    '@@TITLE@@': 'AI Fabrix Builder API - ReDoc',
+    '@@SPEC_URL@@': specUrl,
+    '@@JSON_DOWNLOAD_URL@@': jsonDownloadUrl,
+    '@@JSON_DOWNLOAD_NAME@@': 'builder-api-openapi.json',
+    '@@REDOC_JS_URL@@': REDOC_JS_URL
+  });
+}
+
+module.exports = {
+  REDOC_JS_URL,
+  resolveRedocTemplatePath,
+  resolvePublicBaseUrl,
+  renderBuilderApiRedocHtml,
+  openapiJsonPath,
+  absoluteOpenApiJsonUrl
+};

package/lib/programmatic/openapi-help-schemas.js

@@ -0,0 +1,63 @@
+/**
+ * OpenAPI component schemas for builder-api help endpoint (plan 154.5).
+ *
+ * @fileoverview BuilderHelpTopic enum and help response data model
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const stringArraySchema = () => ({
+  type: 'array',
+  items: { type: 'string' },
+  additionalProperties: false
+});
+
+/** @type {Record<string, Object>} */
+const OPENAPI_HELP_RESULT_SCHEMAS = Object.freeze({
+  BuilderHelpTopic: {
+    type: 'string',
+    enum: [
+      'overview',
+      'sections',
+      'section',
+      'dependencyGraph',
+      'repairRules',
+      'workflow',
+      'schemaCatalog',
+      'subscriptionGuide',
+      'cipOverview',
+      'goldenExamples',
+      'goldenExample',
+      'evidencePatterns',
+      'evidencePattern',
+      'connectedSystemUi',
+      'enterpriseSyncFabrix',
+      'platformRoles',
+      'resourceTypeCatalog',
+      'dimensionsGuide',
+      'channelOnboarding'
+    ]
+  },
+  BuilderHelpData: {
+    type: 'object',
+    properties: {
+      version: { type: 'string' },
+      schemaVersion: { type: 'string' },
+      topic: { $ref: '#/components/schemas/BuilderHelpTopic' },
+      key: { type: 'string' },
+      title: { type: 'string' },
+      summary: { type: 'string' },
+      data: { type: 'object' },
+      related: stringArraySchema(),
+      recommendedNext: stringArraySchema()
+    },
+    required: ['version', 'schemaVersion', 'topic', 'key', 'title', 'summary', 'data', 'related', 'recommendedNext'],
+    additionalProperties: false
+  }
+});
+
+module.exports = {
+  OPENAPI_HELP_RESULT_SCHEMAS
+};

package/lib/programmatic/openapi-manifest-schemas.js

@@ -0,0 +1,141 @@
+/**
+ * OpenAPI schemas for manifest section routes (plan 154.4).
+ *
+ * @fileoverview Frozen request/result models for section editing
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { frozenObject, schemaRef, stringArraySchema } = require('./openapi-schema-helpers');
+
+const SectionKey = {
+  type: 'string',
+  description: 'Governed manifest section key (e.g. datasource.metadata, system.basics).'
+};
+
+const DatasourceKey = {
+  type: 'string',
+  pattern: '^[a-z0-9-]+$',
+  description: 'Datasource key within the external system workspace.'
+};
+
+const MissingInput = frozenObject(
+  {
+    field: { type: 'string', description: 'Field name requiring user input.' },
+    question: { type: 'string', description: 'Question to ask the user verbatim.' },
+    required: { type: 'boolean', description: 'When true, AI must not guess — ask user first.' }
+  },
+  ['field', 'question', 'required']
+);
+
+const SectionQuality = frozenObject(
+  {
+    score: { type: 'integer', minimum: 0, maximum: 100, description: 'Deterministic quality score.' },
+    blockingIssues: {
+      type: 'array',
+      items: frozenObject({ severity: { type: 'string' }, message: { type: 'string' } }, ['message'])
+    },
+    warnings: stringArraySchema(),
+    missingInputs: { type: 'array', items: schemaRef('MissingInput') },
+    assumptions: stringArraySchema()
+  },
+  ['score', 'blockingIssues', 'warnings', 'missingInputs', 'assumptions']
+);
+
+const OPENAPI_MANIFEST_REQUEST_SCHEMAS = {
+  SectionKey,
+  DatasourceKey,
+  MissingInput,
+  SectionQuality,
+  ManifestPatchSectionRequest: frozenObject(
+    {
+      intent: { type: 'string', minLength: 1, description: 'Why this patch is made — audit and repair hints.' },
+      patch: { type: 'object', description: 'Section-scoped merge/replace payload.' },
+      mode: { type: 'string', enum: ['merge', 'replace'], description: 'Merge into or replace section value.' },
+      sectionReadToken: { type: 'string', description: 'Token from prior GET; stale token returns 409.' },
+      dryRun: { type: 'boolean', description: 'Validate patch without writing files.' }
+    },
+    ['intent', 'patch', 'mode', 'sectionReadToken']
+  ),
+  ManifestRepairRequest: frozenObject(
+    {
+      hooks: stringArraySchema(),
+      sectionKey: schemaRef('SectionKey'),
+      datasourceKey: schemaRef('DatasourceKey'),
+      dryRun: { type: 'boolean' },
+      auth: { type: 'string', description: 'Optional auth repair mode passed to repair command.' }
+    },
+    ['hooks']
+  )
+};
+
+const OPENAPI_MANIFEST_RESULT_SCHEMAS = {
+  ManifestSectionViewData: frozenObject(
+    {
+      sectionKey: schemaRef('SectionKey'),
+      target: { type: 'string', enum: ['system', 'datasource'] },
+      datasourceKey: { type: ['string', 'null'] },
+      currentValue: { type: 'object' },
+      schemaFragment: { type: 'object' },
+      required: { type: 'boolean' },
+      mutable: { type: 'boolean' },
+      sourceOfTruth: { type: 'boolean' },
+      dependencyGraph: frozenObject({ downstreamFromThis: stringArraySchema() }, ['downstreamFromThis']),
+      repairHooks: stringArraySchema(),
+      recommendedNextActions: stringArraySchema(),
+      sectionReadToken: { type: 'string' },
+      quality: schemaRef('SectionQuality')
+    },
+    ['sectionKey', 'target', 'currentValue', 'sectionReadToken', 'quality']
+  ),
+  ManifestPatchResultData: frozenObject(
+    {
+      sectionKey: schemaRef('SectionKey'),
+      datasourceKey: { type: ['string', 'null'] },
+      intent: { type: 'string' },
+      changedPaths: stringArraySchema(),
+      beforeHash: { type: 'string' },
+      afterHash: { type: 'string' },
+      derivedSectionsAffected: stringArraySchema(),
+      repairRecommended: { type: 'boolean' },
+      repairHooks: stringArraySchema(),
+      validationPreview: { type: 'object' },
+      riskHints: stringArraySchema(),
+      nextActions: stringArraySchema(),
+      dryRun: { type: 'boolean' },
+      quality: schemaRef('SectionQuality')
+    },
+    ['sectionKey', 'intent', 'quality']
+  ),
+  ManifestSectionsListData: frozenObject(
+    {
+      systemKey: schemaRef('SystemKey'),
+      sections: {
+        type: 'array',
+        items: frozenObject(
+          { sectionKey: schemaRef('SectionKey'), target: { type: 'string', enum: ['system', 'datasource'] } },
+          ['sectionKey', 'target']
+        )
+      },
+      datasourceKeys: stringArraySchema()
+    },
+    ['systemKey', 'sections', 'datasourceKeys']
+  ),
+  ManifestRepairResultData: frozenObject(
+    {
+      hooksRun: stringArraySchema(),
+      derivedSectionsUpdated: stringArraySchema(),
+      repairResult: { type: 'object' },
+      dryRun: { type: 'boolean' },
+      quality: { oneOf: [schemaRef('SectionQuality'), { type: 'null' }] }
+    },
+    ['hooksRun', 'derivedSectionsUpdated']
+  )
+};
+
+module.exports = {
+  OPENAPI_MANIFEST_REQUEST_SCHEMAS,
+  OPENAPI_MANIFEST_RESULT_SCHEMAS
+};

package/lib/programmatic/openapi-operation-bindings.js

@@ -0,0 +1,274 @@
+/**
+ * Per-operation OpenAPI bindings for builder-api routes.
+ *
+ * @fileoverview Maps handlerId → path/query params, request body, success response schema
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const SYSTEM_KEY_PARAM = {
+  name: 'systemKey',
+  in: 'path',
+  required: true,
+  schema: { $ref: '#/components/schemas/SystemKey' },
+  description: 'External integration system key for the workspace operation.'
+};
+
+const PILLAR_PARAM = {
+  name: 'pillar',
+  in: 'path',
+  required: true,
+  schema: { $ref: '#/components/schemas/CertifyPillar' },
+  description: 'Certification pillar to execute.'
+};
+
+const SECTION_KEY_PARAM = {
+  name: 'sectionKey',
+  in: 'path',
+  required: true,
+  schema: { $ref: '#/components/schemas/SectionKey' },
+  description: 'Governed manifest section key (e.g. datasource.metadata).'
+};
+
+const DATASOURCE_KEY_PARAM = {
+  name: 'datasourceKey',
+  in: 'path',
+  required: true,
+  schema: { $ref: '#/components/schemas/DatasourceKey' },
+  description: 'Datasource key within the integration workspace.'
+};
+
+const IDEMPOTENCY_HEADER = {
+  name: 'Idempotency-Key',
+  in: 'header',
+  required: false,
+  schema: { type: 'string' },
+  description: 'Dedupe mutating retries within 24h (in-memory V1).'
+};
+
+/**
+ * @param {string} schemaName
+ * @param {boolean} [required]
+ * @returns {Object}
+ */
+function jsonRequestBody(schemaName, required = false) {
+  return {
+    required,
+    content: {
+      'application/json': {
+        schema: { $ref: `#/components/schemas/${schemaName}` }
+      }
+    }
+  };
+}
+
+/** @type {Record<string, { parameters?: Object[], requestBody?: Object|null, successResponse: string, queryParameters?: Object[] }>} */
+const OPERATION_BINDINGS = Object.freeze({
+  listSystems: {
+    successResponse: 'ListSystemsResponse'
+  },
+  createSystem: {
+    requestBody: jsonRequestBody('CreateSystemRequest', true),
+    successResponse: 'CreateSystemResponse'
+  },
+  getSystemManifest: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'SystemManifestResponse'
+  },
+  deleteSystem: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'DeleteSystemResponse'
+  },
+  runWizard: {
+    parameters: [SYSTEM_KEY_PARAM],
+    queryParameters: [
+      {
+        name: 'debug',
+        in: 'query',
+        required: false,
+        schema: { type: 'boolean' },
+        description: 'Enable verbose wizard logging.'
+      }
+    ],
+    requestBody: jsonRequestBody('WizardConfigRequest', true),
+    successResponse: 'WizardRunResponse'
+  },
+  runRepair: {
+    parameters: [SYSTEM_KEY_PARAM],
+    queryParameters: [
+      {
+        name: 'dryRun',
+        in: 'query',
+        required: false,
+        schema: { type: 'boolean' },
+        description: 'Preview repair without writing files.'
+      }
+    ],
+    requestBody: jsonRequestBody('RepairRequest'),
+    successResponse: 'RepairResultResponse'
+  },
+  listManifestSections: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'ManifestSectionsListResponse'
+  },
+  getManifestSection: {
+    parameters: [SYSTEM_KEY_PARAM, SECTION_KEY_PARAM],
+    successResponse: 'ManifestSectionViewResponse'
+  },
+  patchManifestSection: {
+    parameters: [SYSTEM_KEY_PARAM, SECTION_KEY_PARAM],
+    requestBody: jsonRequestBody('ManifestPatchSectionRequest', true),
+    successResponse: 'ManifestPatchResultResponse'
+  },
+  getDatasourceManifestSection: {
+    parameters: [SYSTEM_KEY_PARAM, DATASOURCE_KEY_PARAM, SECTION_KEY_PARAM],
+    successResponse: 'ManifestSectionViewResponse'
+  },
+  patchDatasourceManifestSection: {
+    parameters: [SYSTEM_KEY_PARAM, DATASOURCE_KEY_PARAM, SECTION_KEY_PARAM],
+    requestBody: jsonRequestBody('ManifestPatchSectionRequest', true),
+    successResponse: 'ManifestPatchResultResponse'
+  },
+  runManifestRepair: {
+    parameters: [SYSTEM_KEY_PARAM],
+    queryParameters: [
+      {
+        name: 'dryRun',
+        in: 'query',
+        required: false,
+        schema: { type: 'boolean' },
+        description: 'Preview manifest repair without writing files.'
+      }
+    ],
+    requestBody: jsonRequestBody('ManifestRepairRequest', true),
+    successResponse: 'ManifestRepairResultResponse'
+  },
+  runValidate: {
+    parameters: [SYSTEM_KEY_PARAM],
+    queryParameters: [
+      {
+        name: 'pipelineValidate',
+        in: 'query',
+        required: false,
+        schema: { type: 'boolean' },
+        description: 'Run Dataplane pipeline validate-only after local validation passes.'
+      }
+    ],
+    requestBody: jsonRequestBody('ValidateRequest'),
+    successResponse: 'ValidateResultResponse'
+  },
+  runPreviewUpload: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('PreviewUploadRequest'),
+    successResponse: 'PreviewUploadResponse'
+  },
+  runTest: {
+    parameters: [SYSTEM_KEY_PARAM],
+    queryParameters: [
+      {
+        name: 'runType',
+        in: 'query',
+        required: false,
+        schema: { $ref: '#/components/schemas/TestRunType' },
+        description: 'Test stage (defaults to integration).'
+      }
+    ],
+    requestBody: jsonRequestBody('TestRequest'),
+    successResponse: 'TestResultResponse'
+  },
+  runCertifyPillar: {
+    parameters: [SYSTEM_KEY_PARAM, PILLAR_PARAM],
+    requestBody: jsonRequestBody('CertifyRequest'),
+    successResponse: 'CertifyResultResponse'
+  },
+  getLifecycleReport: {
+    parameters: [SYSTEM_KEY_PARAM],
+    queryParameters: [
+      {
+        name: 'details',
+        in: 'query',
+        required: false,
+        schema: { type: 'boolean' },
+        description: 'Include detailed lifecycle report sections.'
+      },
+      {
+        name: 'summary',
+        in: 'query',
+        required: false,
+        schema: { type: 'boolean' },
+        description: 'Return summary-only lifecycle report.'
+      }
+    ],
+    successResponse: 'LifecycleReportResponse'
+  },
+  runUpload: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('UploadRequest'),
+    successResponse: 'UploadResultResponse'
+  },
+  materializeTemplate: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('TemplateMaterializeRequest'),
+    successResponse: 'EnterpriseMcpInvocationResponse'
+  },
+  getWorkspaceStatus: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'WorkspaceStatusResponse'
+  },
+  runWorkspaceDiff: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('WorkspaceDiffRequest'),
+    successResponse: 'EnterpriseMcpInvocationResponse'
+  },
+  resetWorkspaceFromTemplate: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('WorkspaceResetRequest'),
+    successResponse: 'EnterpriseMcpInvocationResponse'
+  },
+  runRepositorySync: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('RepositorySyncRequest'),
+    successResponse: 'EnterpriseMcpInvocationResponse'
+  },
+  runRepositoryCreateReview: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('RepositoryCreateReviewRequest'),
+    successResponse: 'EnterpriseMcpInvocationResponse'
+  },
+  getRepositoryStatus: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'RepositoryStatusResponse'
+  },
+  runRepositoryDispatchPipeline: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('RepositoryDispatchPipelineRequest'),
+    successResponse: 'EnterpriseMcpInvocationResponse'
+  },
+  health: {
+    successResponse: 'HealthResponse'
+  },
+  ready: {
+    successResponse: 'ReadyResponse'
+  }
+});
+
+/**
+ * @param {string} handlerId
+ * @returns {{ parameters?: Object[], requestBody?: Object|null, successResponse: string, queryParameters?: Object[] }}
+ */
+function getOperationBinding(handlerId) {
+  return (
+    OPERATION_BINDINGS[handlerId] || {
+      successResponse: 'EmptyResultResponse',
+      requestBody: jsonRequestBody('EmptyRequestBody')
+    }
+  );
+}
+
+module.exports = {
+  OPERATION_BINDINGS,
+  getOperationBinding,
+  IDEMPOTENCY_HEADER
+};