@aifabrix/builder 2.49.2 → 2.50.0

package/lib/programmatic/openapi-schema-descriptions-operations.js

@@ -0,0 +1,281 @@
+/**
+ * OpenAPI schema descriptions — wizard, repair, validate, upload, test.
+ *
+ * @fileoverview Request/result models for build and validate routes
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** @type {Record<string, Object>} */
+const OPERATIONS_SCHEMA_DESCRIPTIONS = {
+  WizardSourceType: {
+    _schema: 'Wizard input source: OpenAPI file/URL, MCP server, or known platform template.'
+  },
+  WizardSourceConfig: {
+    _schema: 'Wizard source descriptor; set path, url, or platform based on type.',
+    type: 'Source kind that determines which other fields are required.',
+    path: 'Local filesystem path to an OpenAPI or wizard config file.',
+    url: 'Remote URL to fetch an OpenAPI document.',
+    platform: 'Known platform key when type is knownPlatform.'
+  },
+  WizardCredentialOptions: {
+    _schema: 'Optional credential hints for wizard credential selection step.',
+    method: 'Auth method hint for wizard (e.g. apikey, oauth2).',
+    credentialKey: 'Existing credential key in Dataplane to reuse.'
+  },
+  WizardPreferences: {
+    _schema: 'Optional wizard generation preferences for expose, RBAC, and sync defaults.',
+    expose: 'When true, generate exposed datasource API surfaces.',
+    rbac: 'When true, generate rbac.yaml with default roles.',
+    sync: 'When true, include sync configuration on datasources.'
+  },
+  CreateSystemRequest: {
+    _schema: 'Request body to create an empty integration workspace folder.',
+    systemKey: 'Unique integration system key for the new workspace.'
+  },
+  WizardConfigRequest: {
+    _schema: 'Headless wizard configuration to generate system and datasource JSON.',
+    appName: 'Integration app folder name under the user workspace.',
+    mode: 'Optional wizard mode override (defaults to headless generation).',
+    systemIdOrKey: 'Existing system id or key when extending an integration.',
+    systemDisplayName: 'Human-readable display name for the external system.',
+    source: 'OpenAPI, MCP, or platform source descriptor.',
+    credential: 'Optional credential selection hints.',
+    preferences: 'Optional expose, RBAC, and sync generation flags.',
+    debug: 'When true, enable verbose wizard logging (also available as query param).'
+  },
+  RepairRequest: {
+    _schema: 'Optional flags for workspace repair aligning manifest files with on-disk JSON.',
+    dryRun: 'Preview repair actions without writing files.',
+    auth: 'Repair authentication blocks (e.g. switch to apikey).',
+    rbac: 'Regenerate or repair rbac.yaml.',
+    expose: 'Align expose flags on datasources.',
+    sync: 'Align sync configuration on datasources.',
+    test: 'Align test payload sections on datasources.',
+    api: 'Repair OpenAPI exposure metadata on the system.',
+    operations:
+      'When true, sync capabilities[] → openapi.operations → execution.cip.operations for operationId-shaped keys.',
+    rbacPreset:
+      'When platform, apply dataplane platform roles from rbac.yaml SSOT instead of per-system admin/reader.'
+  },
+  ValidateRequest: {
+    _schema: 'Optional validate flags; pipeline validate may also be passed as query param.',
+    pipelineValidate: 'When true, run Dataplane pipeline validate-only after local AJV passes.'
+  },
+  PreviewUploadRequest: {
+    _schema: 'Optional flags for preview-upload (no Dataplane mutation).',
+    force: 'When true, build preview even when local validation reports warnings.'
+  },
+  UploadRequest: {
+    _schema: 'Optional flags for dev Dataplane upload (requires external-system:publish).',
+    force: 'When true, upload even when validation reports non-blocking issues.',
+    probe: 'When true, perform connectivity probe before upload.'
+  },
+  TestRequest: {
+    _schema: 'Optional test ladder options; runType may also be passed as query param.',
+    runType: 'Test stage: unit, integration (default), or e2e.',
+    noPublish: 'When true, skip publishing local files before integration or e2e tests.'
+  },
+  WizardRunData: {
+    _schema: 'Result after headless wizard completes file generation.',
+    systemKey: 'Integration system key that was materialized.',
+    status: 'Wizard completion status (completed when successful).'
+  },
+  RepairResultData: {
+    _schema: 'Detailed repair outcome listing files changed and flags updated.',
+    updated: 'True when any file or manifest field was modified.',
+    actionsPerformed: 'True when repair executed at least one action (dry-run may be false).',
+    changes: 'Human-readable list of repair actions taken.',
+    warnings: 'Non-blocking repair warnings.',
+    changedFiles: 'Workspace-relative paths that were written.',
+    systemFiles: 'System JSON paths touched by repair.',
+    datasourceFiles: 'Datasource JSON paths touched by repair.',
+    backupPaths: 'Backup copies created before mutating files.',
+    appKeyFixed: 'True when application.yaml app key was corrected.',
+    datasourceKeysFixed: 'True when datasource systemKey references were corrected.',
+    rbacFileCreated: 'True when rbac.yaml was created.',
+    envTemplateRepaired: 'True when env.template auth vars were aligned.',
+    manifestRegenerated: 'True when deploy manifest JSON was regenerated.',
+    readmeRegenerated: 'True when README.md was regenerated.'
+  },
+  ValidationStepResult: {
+    _schema: 'Result of one validation step (application, components, or manifest).',
+    valid: 'True when this step passed with no errors.',
+    errors: 'Blocking validation error messages.',
+    warnings: 'Non-blocking validation warnings.',
+    files: 'Files validated in this step.',
+    skipped: 'True when the step was skipped (e.g. missing optional inputs).'
+  },
+  ValidationSteps: {
+    _schema: 'Per-layer validation breakdown for local AJV validate.',
+    application: 'application.yaml / variables validation result.',
+    components: 'External system and datasource JSON validation result.',
+    manifest: 'Deploy manifest and integration file list validation result.'
+  },
+  ValidationResultCore: {
+    _schema: 'Aggregate local validation result for the integration workspace.',
+    valid: 'True when all executed steps passed.',
+    errors: 'Combined blocking errors across steps.',
+    warnings: 'Combined warnings across steps.',
+    steps: 'Per-step validation results.',
+    appPath: 'Absolute or workspace-relative app path validated.'
+  },
+  PipelineValidationResult: {
+    _schema: 'Dataplane pipeline validate-only result (read-only toward Dataplane).',
+    valid: 'True when pipeline validation succeeded.',
+    isValid: 'Alias flag mirroring valid from Dataplane response.',
+    errors: 'Pipeline validation errors from Dataplane.',
+    warnings: 'Pipeline validation warnings from Dataplane.'
+  },
+  ValidateResultData: {
+    _schema: 'Combined local and optional pipeline validation payload.',
+    validationResult: 'Local AJV validation aggregate.',
+    pipelineValidation: 'Pipeline validate-only result when requested; null otherwise.'
+  },
+  UploadApplicationPreview: {
+    _schema: 'Application summary inside an upload payload preview.',
+    key: 'Application key in the deploy payload.',
+    displayName: 'Human-readable application name.',
+    type: 'Application type (external for integrations).'
+  },
+  UploadDatasourcePreview: {
+    _schema: 'Datasource key entry inside upload payload preview.',
+    key: 'Datasource key included in the deploy payload.'
+  },
+  UploadManifestPreview: {
+    _schema: 'Top-level manifest metadata in preview-upload response.',
+    key: 'External system key in the manifest.',
+    version: 'Manifest or integration version string.',
+    type: 'Manifest type discriminator.'
+  },
+  UploadPayloadPreview: {
+    _schema: 'Deploy payload body preview without credentials or Dataplane mutation.',
+    version: 'Payload schema version.',
+    application: 'Application object summary.',
+    dataSources: 'Datasource keys that would be uploaded.'
+  },
+  PreviewUploadData: {
+    _schema: 'Preview-upload result: manifest summary plus redacted payload preview.',
+    manifest: 'Manifest metadata that would be sent to Dataplane.',
+    payload: 'Structured deploy payload preview (no secrets).'
+  },
+  UploadResultData: {
+    _schema: 'Dev upload result after publish to Dataplane.',
+    dataplaneUrl: 'Dataplane base URL used for upload.',
+    environment: 'Target environment name (typically dev).',
+    uploadSkipped: 'True when upload was skipped (e.g. validate-only or no changes).'
+  },
+  TestSystemFileResult: {
+    _schema: 'Unit test result for one system-level JSON file.',
+    file: 'Validated file path.',
+    valid: 'True when structural validation passed.',
+    errors: 'Structural validation errors for this file.'
+  },
+  TestDatasourceResult: {
+    _schema: 'Unit or structural test result for one datasource file.',
+    key: 'Datasource key.',
+    file: 'Datasource JSON file path.',
+    valid: 'True when all checks for this datasource passed.',
+    errors: 'Validation or test errors.',
+    warnings: 'Non-blocking warnings.',
+    structuralValid: 'True when JSON schema validation passed.',
+    payloadTestsRan: 'True when test payload execution ran.',
+    payloadTestsOk: 'True when test payload execution succeeded.'
+  },
+  IntegrationDatasourceResult: {
+    _schema: 'Integration test result for one datasource via Dataplane pipeline.',
+    key: 'Datasource key tested.',
+    success: 'True when integration test passed.',
+    skipped: 'True when the datasource test was skipped.',
+    error: 'Error message when success is false.'
+  },
+  E2ETestRunItem: {
+    _schema: 'End-to-end test result for one datasource against live APIs.',
+    key: 'Datasource key tested.',
+    success: 'True when e2e test passed.',
+    error: 'Error message when success is false.',
+    datasourceTestRun: 'Dataplane datasource test run summary when available.'
+  },
+  DatasourceTestRunSummary: {
+    _schema: 'Summary of a Dataplane datasource test run record.',
+    id: 'Test run id in Dataplane.',
+    status: 'Test run status string from Dataplane.',
+    datasourceKey: 'Datasource key associated with the run.'
+  },
+  UnitTestResultData: {
+    _schema: 'Aggregate unit test result for local integration files.',
+    runType: 'Always unit for this variant.',
+    valid: 'True when all system and datasource unit checks passed.',
+    errors: 'Aggregate error messages.',
+    warnings: 'Aggregate warnings.',
+    systemResults: 'Per system-file validation results.',
+    datasourceResults: 'Per datasource validation results.',
+    systemKey: 'Integration system key tested.',
+    appName: 'Integration app folder name.'
+  },
+  IntegrationTestResultData: {
+    _schema: 'Aggregate integration test result via Dataplane pipeline.',
+    runType: 'Always integration for this variant.',
+    success: 'True when all datasource integration tests passed.',
+    datasourceResults: 'Per-datasource integration outcomes.',
+    systemKey: 'Integration system key tested.',
+    appName: 'Integration app folder name.'
+  },
+  E2ETestResultData: {
+    _schema: 'Aggregate e2e test result against live external APIs.',
+    runType: 'Always e2e for this variant.',
+    success: 'True when all datasource e2e tests passed.',
+    results: 'Per-datasource e2e outcomes.'
+  },
+  TestResultData: {
+    _schema: 'Discriminated union of unit, integration, or e2e test results (see runType).'
+  },
+  WizardRunResponse: {
+    _schema: '200 response envelope for runWizard.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see WizardRunData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  RepairResultResponse: {
+    _schema: '200 response envelope for runRepair.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see RepairResultData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  ValidateResultResponse: {
+    _schema: '200 response envelope for runValidate.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see ValidateResultData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  PreviewUploadResponse: {
+    _schema: '200 response envelope for runPreviewUpload.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see PreviewUploadData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  UploadResultResponse: {
+    _schema: '200 response envelope for runUpload.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see UploadResultData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  TestResultResponse: {
+    _schema: '200 response envelope for runTest.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see TestResultData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  }
+};
+
+module.exports = {
+  OPERATIONS_SCHEMA_DESCRIPTIONS
+};

package/lib/programmatic/openapi-schema-helpers.js

@@ -0,0 +1,93 @@
+/**
+ * Helpers for frozen OpenAPI component schemas (additionalProperties: false).
+ *
+ * @fileoverview Shared builders for builder-api OpenAPI models
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Record<string, Object>} properties
+ * @param {string[]} [required]
+ * @returns {Object}
+ */
+function frozenObject(properties, required) {
+  const schema = { type: 'object', properties, additionalProperties: false };
+  if (required && required.length > 0) {
+    schema.required = required;
+  }
+  return schema;
+}
+
+/**
+ * @param {string} name
+ * @returns {{ $ref: string }}
+ */
+function schemaRef(name) {
+  return { $ref: `#/components/schemas/${name}` };
+}
+
+/**
+ * @returns {Object}
+ */
+function stringArraySchema() {
+  return { type: 'array', items: { type: 'string' } };
+}
+
+/**
+ * @param {string} dataSchemaName
+ * @returns {Object}
+ */
+function buildSuccessEnvelopeSchema(dataSchemaName) {
+  return frozenObject(
+    {
+      success: { type: 'boolean', enum: [true] },
+      data: schemaRef(dataSchemaName),
+      correlationId: { type: 'string', format: 'uuid' },
+      requestId: { type: 'string', format: 'uuid' }
+    },
+    ['success', 'data', 'correlationId']
+  );
+}
+
+/**
+ * @param {Object} schema
+ * @param {string} [path]
+ * @returns {string[]}
+ */
+function collectAdditionalPropertiesViolations(schema, path = '') {
+  if (!schema || typeof schema !== 'object') {
+    return [];
+  }
+  const violations = [];
+  const here = path || 'root';
+  if (schema.additionalProperties === true) {
+    violations.push(here);
+  }
+  if (schema.properties && typeof schema.properties === 'object') {
+    for (const [key, child] of Object.entries(schema.properties)) {
+      violations.push(...collectAdditionalPropertiesViolations(child, `${here}.properties.${key}`));
+    }
+  }
+  if (schema.items) {
+    violations.push(...collectAdditionalPropertiesViolations(schema.items, `${here}.items`));
+  }
+  for (const key of ['oneOf', 'anyOf', 'allOf']) {
+    if (Array.isArray(schema[key])) {
+      schema[key].forEach((child, index) => {
+        violations.push(...collectAdditionalPropertiesViolations(child, `${here}.${key}[${index}]`));
+      });
+    }
+  }
+  return violations;
+}
+
+module.exports = {
+  frozenObject,
+  schemaRef,
+  stringArraySchema,
+  buildSuccessEnvelopeSchema,
+  collectAdditionalPropertiesViolations
+};

package/lib/programmatic/openapi-spec.js

@@ -0,0 +1,203 @@
+/**
+ * OpenAPI 3.0 document for builder-api workspace orchestration routes.
+ *
+ * @fileoverview Generated from capability-registry + typed component schemas
+ * @author AI Fabrix Team
+ * @version 1.1.0
+ */
+
+'use strict';
+
+const { CAPABILITIES } = require('./capability-registry');
+const { BASE } = require('./http-route-match');
+const { getOperationDescription } = require('./openapi-descriptions');
+const { buildOpenApiComponentSchemas } = require('./openapi-component-schemas');
+const { getOperationBinding, IDEMPOTENCY_HEADER } = require('./openapi-operation-bindings');
+const { buildOperationXAfabrix, listOrchestrationDatasourceTags } = require('./orchestration-openapi-meta');
+
+/**
+ * @param {string} routePattern
+ * @returns {string}
+ */
+function toOpenApiPath(routePattern) {
+  return `${BASE}${routePattern}`.replace(/:([A-Za-z]+)/g, '{$1}');
+}
+
+/**
+ * @param {string} responseSchemaName
+ * @returns {Object}
+ */
+function successResponseContent(responseSchemaName) {
+  return {
+    description: 'Successful builder-api envelope (success, data, correlationId, requestId).',
+    content: {
+      'application/json': {
+        schema: { $ref: `#/components/schemas/${responseSchemaName}` }
+      }
+    }
+  };
+}
+
+/**
+ * @param {string} description
+ * @returns {Object}
+ */
+function problemResponseContent(description) {
+  return {
+    description,
+    content: {
+      'application/problem+json': {
+        schema: { $ref: '#/components/schemas/ProblemDetails' }
+      }
+    }
+  };
+}
+
+/**
+ * @returns {Record<string, Object>}
+ */
+function buildStandardErrorResponses() {
+  return {
+    400: problemResponseContent('Invalid request (validation, JSON parse, or missing required body field).'),
+    401: problemResponseContent('Missing or invalid Bearer token.'),
+    404: problemResponseContent('Workspace system not found or route handler not registered.'),
+    408: problemResponseContent('Request exceeded capability timeout.'),
+    409: problemResponseContent('Workspace lock held by another in-flight operation.'),
+    413: problemResponseContent('Request body exceeds MAX_BODY_BYTES.'),
+    500: problemResponseContent('Unexpected server error.')
+  };
+}
+
+/**
+ * @param {string} handlerId
+ * @returns {boolean}
+ */
+function requiresBearerAuth(handlerId) {
+  return handlerId !== 'health' && handlerId !== 'ready';
+}
+
+/**
+ * @param {Object} capability
+ * @param {Object} operation
+ */
+function applyOperationDurationHints(capability, operation) {
+  const durationByHandler = {
+    runUpload: Number(process.env.MAX_UPLOAD_TIMEOUT_MS || 300000),
+    runTest: Number(process.env.MAX_TEST_E2E_TIMEOUT_MS || 120000),
+    runCertifyPillar: Number(process.env.MAX_CERTIFY_TIMEOUT_MS || 120000)
+  };
+  const durationMs = durationByHandler[capability.handlerId];
+  if (durationMs !== undefined) {
+    operation['x-max-duration-ms'] = durationMs;
+  }
+}
+
+/**
+ * @param {Object} capability
+ * @returns {Object}
+ */
+function buildOperationObject(capability) {
+  const meta = getOperationDescription(capability.handlerId);
+  const binding = getOperationBinding(capability.handlerId);
+  const operation = {
+    operationId: capability.handlerId,
+    summary: meta.summary,
+    description: meta.description,
+    tags: meta.tags,
+    responses: {
+      200: successResponseContent(binding.successResponse),
+      ...buildStandardErrorResponses()
+    }
+  };
+
+  const parameters = [...(binding.parameters || []), ...(binding.queryParameters || [])];
+  if (capability.mutating) {
+    operation.description = `${meta.description} Requires Idempotency-Key header on mutating retries.`;
+    parameters.push(IDEMPOTENCY_HEADER);
+  }
+  if (parameters.length > 0) {
+    operation.parameters = parameters;
+  }
+
+  if (binding.requestBody) {
+    operation.requestBody = binding.requestBody;
+  }
+
+  if (requiresBearerAuth(capability.handlerId)) {
+    operation.security = [{ bearerAuth: [] }];
+  }
+
+  applyOperationDurationHints(capability, operation);
+  operation['x-aifabrix'] = buildOperationXAfabrix(capability);
+
+  return operation;
+}
+
+/**
+ * @param {Object} [options]
+ * @param {string} [options.publicBaseUrl]
+ * @returns {Object}
+ */
+function buildOpenApiSpec(options = {}) {
+  const publicBaseUrl = (options.publicBaseUrl || '').replace(/\/$/, '');
+  const serverUrl = publicBaseUrl || '/';
+  /** @type {Record<string, Object>} */
+  const paths = {};
+  for (const capability of CAPABILITIES) {
+    const pathKey = toOpenApiPath(capability.route);
+    if (!paths[pathKey]) {
+      paths[pathKey] = {};
+    }
+    const method = capability.method.toLowerCase();
+    paths[pathKey][method] = buildOperationObject(capability);
+  }
+
+  return {
+    openapi: '3.0.3',
+    info: {
+      title: 'AI Fabrix Builder API',
+      version: '1.0.0',
+      description:
+        'Workspace orchestration for external-system dev publish. Repository and template operations delegate to Enterprise MCP (154.1). Successful JSON responses use `{ success, data, correlationId, requestId? }` with `application/json`. Errors use RFC 7807 Problem Details (`application/problem+json`) aligned with miso-controller and dataplane.',
+      'x-aifabrix': {
+        redocUrl: '/api/docs',
+        contractTier: 'public',
+        mcpGenerationReady: true,
+        rbacPreset: 'platform',
+        datasourceSplitMode: 'per-tag',
+        orchestrationDatasourceTags: listOrchestrationDatasourceTags()
+      }
+    },
+    servers: [{ url: serverUrl, description: 'Builder API public base URL' }],
+    tags: [
+      { name: 'workspace', description: 'Per-user integration workspaces (list, create, manifest, status, diff).' },
+      { name: 'build', description: 'Wizard generation and manifest repair.' },
+      { name: 'manifest', description: 'Governed section get/patch/repair for LLM and MCP workflows.' },
+      { name: 'validate', description: 'Local AJV validation and preview-upload (no Dataplane mutation).' },
+      { name: 'test', description: 'Unit, integration, and e2e test ladder.' },
+      { name: 'certify', description: 'Verify operations/trust/governance and lifecycle certification.' },
+      { name: 'apply', description: 'Dev Dataplane upload (requires external-system:publish).' },
+      { name: 'template', description: 'Enterprise MCP template.materializeWorkspace and workspace reset.' },
+      { name: 'repository', description: 'Enterprise MCP repository.sync, createReview, status, dispatchPipeline.' },
+      { name: 'infra', description: 'Liveness and readiness probes (no authentication).' }
+    ],
+    components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT',
+          description:
+            'User access token from aifabrix login. Forwarded to Dataplane; requires external-system:publish for dev upload.'
+        }
+      },
+      schemas: buildOpenApiComponentSchemas()
+    },
+    paths
+  };
+}
+
+module.exports = {
+  buildOpenApiSpec,
+  toOpenApiPath
+};