@aifabrix/builder 2.49.2 → 2.51.0

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
+};

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

@@ -0,0 +1,155 @@
+/**
+ * Frozen OpenAPI request body schemas for builder-api routes.
+ *
+ * @fileoverview Typed POST/DELETE bodies (additionalProperties: false)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { frozenObject, schemaRef, stringArraySchema } = require('./openapi-schema-helpers');
+
+/** @type {Record<string, Object>} */
+const OPENAPI_REQUEST_SCHEMAS = {
+  SystemKey: {
+    type: 'string',
+    pattern: '^[a-z0-9-_]+$',
+    description: 'External integration system key (lowercase alphanumeric, hyphen, underscore).',
+    example: 'hubspot-demo'
+  },
+  CertifyPillar: {
+    type: 'string',
+    enum: ['operations', 'trust', 'governance', 'lifecycle-run']
+  },
+  TestRunType: {
+    type: 'string',
+    enum: ['unit', 'integration', 'e2e']
+  },
+  RepositorySyncDirection: {
+    type: 'string',
+    enum: ['pull', 'push']
+  },
+  WizardSourceType: {
+    type: 'string',
+    enum: ['openapiFile', 'openapiUrl', 'mcpServer', 'knownPlatform']
+  },
+  WizardSourceConfig: frozenObject(
+    {
+      type: schemaRef('WizardSourceType'),
+      path: { type: 'string' },
+      url: { type: 'string', format: 'uri' },
+      platform: { type: 'string' }
+    },
+    ['type']
+  ),
+  WizardCredentialOptions: frozenObject({
+    method: { type: 'string', description: 'Auth method hint for wizard (e.g. apikey, oauth2).' },
+    credentialKey: { type: 'string', description: 'Existing credential key in Dataplane.' }
+  }),
+  WizardPreferences: frozenObject({
+    expose: { type: 'boolean' },
+    rbac: { type: 'boolean' },
+    sync: { type: 'boolean' }
+  }),
+  CreateSystemRequest: frozenObject({ systemKey: schemaRef('SystemKey') }, ['systemKey']),
+  WizardConfigRequest: frozenObject(
+    {
+      appName: { type: 'string' },
+      mode: { type: 'string' },
+      systemIdOrKey: { type: 'string' },
+      systemDisplayName: { type: 'string' },
+      source: schemaRef('WizardSourceConfig'),
+      credential: schemaRef('WizardCredentialOptions'),
+      preferences: schemaRef('WizardPreferences'),
+      debug: { type: 'boolean' }
+    },
+    ['appName', 'source']
+  ),
+  RepairRequest: frozenObject({
+    dryRun: { type: 'boolean' },
+    auth: { type: 'string' },
+    rbac: { type: 'boolean' },
+    expose: { type: 'boolean' },
+    sync: { type: 'boolean' },
+    test: { type: 'boolean' },
+    api: { type: 'boolean' },
+    operations: {
+      type: 'boolean',
+      description:
+        'When true, sync capabilities[] → openapi.operations → execution.cip.operations for operationId-shaped keys.'
+    },
+    rbacPreset: {
+      type: 'string',
+      enum: ['platform'],
+      description:
+        'When platform, use dataplane platform roles (aifabrix-platform-admin, …) instead of per-system admin/reader.'
+    }
+  }),
+  ValidateRequest: frozenObject({
+    pipelineValidate: { type: 'boolean' }
+  }),
+  PreviewUploadRequest: frozenObject({
+    force: { type: 'boolean' }
+  }),
+  UploadRequest: frozenObject({
+    force: { type: 'boolean' },
+    probe: { type: 'boolean' }
+  }),
+  TestRequest: frozenObject({
+    runType: schemaRef('TestRunType'),
+    noPublish: { type: 'boolean' }
+  }),
+  CertifyRequest: frozenObject({
+    noPublish: { type: 'boolean' },
+    pack: { type: 'string' },
+    lifecycleBody: schemaRef('LifecycleRunRequest')
+  }),
+  LifecycleRunRequest: frozenObject({
+    subjectEmail: { type: 'string', format: 'email' },
+    dryRun: { type: 'boolean' }
+  }),
+  TemplateMaterializeRequest: frozenObject({
+    templateKey: { type: 'string' },
+    params: schemaRef('TemplateMaterializeParams')
+  }),
+  TemplateMaterializeParams: frozenObject({
+    branch: { type: 'string' },
+    paths: stringArraySchema()
+  }),
+  WorkspaceDiffRequest: frozenObject({
+    baseline: { type: 'string' },
+    paths: stringArraySchema()
+  }),
+  WorkspaceResetRequest: frozenObject({
+    templateKey: { type: 'string' },
+    confirm: { type: 'boolean' }
+  }),
+  RepositorySyncRequest: frozenObject({
+    direction: schemaRef('RepositorySyncDirection'),
+    branch: { type: 'string' },
+    paths: stringArraySchema(),
+    commitMessage: { type: 'string' }
+  }),
+  RepositoryCreateReviewRequest: frozenObject({
+    title: { type: 'string' },
+    body: { type: 'string' },
+    sourceBranch: { type: 'string' },
+    targetBranch: { type: 'string' },
+    draft: { type: 'boolean' }
+  }),
+  RepositoryDispatchPipelineRequest: frozenObject({
+    workflow: { type: 'string' },
+    ref: { type: 'string' },
+    inputs: schemaRef('RepositoryPipelineInputs')
+  }),
+  RepositoryPipelineInputs: frozenObject({
+    environment: { type: 'string' },
+    ref: { type: 'string' }
+  }),
+  EmptyRequestBody: frozenObject({})
+};
+
+module.exports = {
+  OPENAPI_REQUEST_SCHEMAS
+};