@aifabrix/builder 2.49.2 → 2.51.0

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

@@ -0,0 +1,493 @@
+/**
+ * Frozen OpenAPI response data schemas for builder-api routes.
+ *
+ * @fileoverview Typed handler result models (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_RESULT_SCHEMAS = {
+  ProblemDetail: Object.assign(
+    frozenObject(
+      {
+        type: { type: 'string', format: 'uri-reference' },
+        title: { type: 'string' },
+        status: { type: 'integer', minimum: 100, maximum: 599 },
+        detail: { type: 'string' },
+        instance: { type: 'string' },
+        correlationId: { type: 'string' },
+        errors: { type: 'array', items: schemaRef('ProblemValidationError') }
+      },
+      ['type', 'title', 'status', 'detail', 'correlationId', 'instance', 'errors']
+    ),
+    {
+      example: {
+        type: '/Errors/Unauthorized',
+        title: 'Unauthorized',
+        status: 401,
+        detail: 'Missing or invalid Bearer token.',
+        instance: '/api/v1/builder/workspaces/me/systems',
+        correlationId: '00000000-0000-4000-8000-000000000003',
+        errors: []
+      }
+    }
+  ),
+  /** Prefer ProblemDetail; allOf alias for published REST lint (OAPI-148). */
+  ProblemDetails: {
+    allOf: [schemaRef('ProblemDetail')]
+  },
+  ProblemValidationError: frozenObject(
+    {
+      field: { type: 'string' },
+      message: { type: 'string' },
+      value: { type: 'string' }
+    },
+    ['message']
+  ),
+  LifecycleVerdict: {
+    type: 'string',
+    enum: ['VERIFIED', 'FAILED', 'NOT_VERIFIED']
+  },
+  CertificationLevel: {
+    type: 'string',
+    enum: ['BRONZE', 'SILVER', 'GOLD', 'PLATINUM', 'NONE']
+  },
+  CertificationStatus: {
+    type: 'string',
+    enum: [
+      'TECHNICALLY_READY',
+      'AI_READY',
+      'ENTERPRISE_AI_READY',
+      'REGULATED_ENTERPRISE_READY',
+      'NOT_CERTIFIED'
+    ]
+  },
+  WorkspaceMeta: frozenObject(
+    {
+      ownerUserId: { type: 'string' },
+      systemKey: schemaRef('SystemKey'),
+      createdAt: { type: 'string', format: 'date-time' },
+      lastModifiedAt: { type: 'string', format: 'date-time' },
+      lastOperation: { type: 'string' },
+      lastUploadId: { type: ['string', 'null'] }
+    },
+    ['ownerUserId', 'systemKey', 'createdAt', 'lastModifiedAt', 'lastOperation']
+  ),
+  WorkspaceSystemSummary: frozenObject(
+    {
+      systemKey: schemaRef('SystemKey'),
+      meta: {
+        oneOf: [schemaRef('WorkspaceMeta'), { type: 'null' }]
+      }
+    },
+    ['systemKey']
+  ),
+  WorkspaceManifestFileEntry: frozenObject(
+    {
+      path: { type: 'string' },
+      isDirectory: { type: 'boolean' },
+      sizeBytes: { type: 'integer', minimum: 0 },
+      redacted: { type: 'boolean' }
+    },
+    ['path']
+  ),
+  ListSystemsData: frozenObject(
+    {
+      systems: { type: 'array', items: schemaRef('WorkspaceSystemSummary') }
+    },
+    ['systems']
+  ),
+  CreateSystemData: frozenObject(
+    {
+      systemKey: schemaRef('SystemKey'),
+      meta: schemaRef('WorkspaceMeta')
+    },
+    ['systemKey', 'meta']
+  ),
+  SystemManifestData: frozenObject(
+    {
+      systemKey: schemaRef('SystemKey'),
+      meta: { oneOf: [schemaRef('WorkspaceMeta'), { type: 'null' }] },
+      files: { type: 'array', items: schemaRef('WorkspaceManifestFileEntry') }
+    },
+    ['systemKey', 'files']
+  ),
+  DeleteSystemData: frozenObject(
+    {
+      systemKey: schemaRef('SystemKey'),
+      deleted: { type: 'boolean', enum: [true] }
+    },
+    ['systemKey', 'deleted']
+  ),
+  WizardRunData: frozenObject(
+    {
+      systemKey: schemaRef('SystemKey'),
+      status: { type: 'string', enum: ['completed'] }
+    },
+    ['systemKey', 'status']
+  ),
+  RepairResultData: frozenObject(
+    {
+      updated: { type: 'boolean' },
+      actionsPerformed: { type: 'boolean' },
+      changes: stringArraySchema(),
+      warnings: stringArraySchema(),
+      changedFiles: stringArraySchema(),
+      systemFiles: stringArraySchema(),
+      datasourceFiles: stringArraySchema(),
+      backupPaths: stringArraySchema(),
+      appKeyFixed: { type: 'boolean' },
+      datasourceKeysFixed: { type: 'boolean' },
+      rbacFileCreated: { type: 'boolean' },
+      envTemplateRepaired: { type: 'boolean' },
+      manifestRegenerated: { type: 'boolean' },
+      readmeRegenerated: { type: 'boolean' }
+    },
+    ['updated', 'changes', 'warnings', 'changedFiles']
+  ),
+  ValidationStepResult: frozenObject(
+    {
+      valid: { type: 'boolean' },
+      errors: stringArraySchema(),
+      warnings: stringArraySchema(),
+      files: stringArraySchema(),
+      skipped: { type: 'boolean' }
+    },
+    ['valid', 'errors', 'warnings']
+  ),
+  ValidationSteps: frozenObject(
+    {
+      application: schemaRef('ValidationStepResult'),
+      components: schemaRef('ValidationStepResult'),
+      manifest: schemaRef('ValidationStepResult')
+    },
+    ['application', 'components', 'manifest']
+  ),
+  ValidationResultCore: frozenObject(
+    {
+      valid: { type: 'boolean' },
+      errors: stringArraySchema(),
+      warnings: stringArraySchema(),
+      steps: schemaRef('ValidationSteps'),
+      appPath: { type: 'string' }
+    },
+    ['valid', 'errors', 'warnings']
+  ),
+  PipelineValidationResult: frozenObject(
+    {
+      valid: { type: 'boolean' },
+      isValid: { type: 'boolean' },
+      errors: stringArraySchema(),
+      warnings: stringArraySchema()
+    },
+    ['errors', 'warnings']
+  ),
+  ValidateResultData: frozenObject(
+    {
+      validationResult: schemaRef('ValidationResultCore'),
+      pipelineValidation: {
+        oneOf: [schemaRef('PipelineValidationResult'), { type: 'null' }]
+      }
+    },
+    ['validationResult']
+  ),
+  UploadApplicationPreview: frozenObject({
+    key: { type: 'string' },
+    displayName: { type: 'string' },
+    type: { type: 'string' }
+  }),
+  UploadDatasourcePreview: frozenObject({ key: { type: 'string' } }, ['key']),
+  UploadManifestPreview: frozenObject(
+    {
+      key: { type: 'string' },
+      version: { type: 'string' },
+      type: { type: 'string' }
+    },
+    ['key']
+  ),
+  UploadPayloadPreview: frozenObject(
+    {
+      version: { type: 'string' },
+      application: schemaRef('UploadApplicationPreview'),
+      dataSources: { type: 'array', items: schemaRef('UploadDatasourcePreview') }
+    },
+    ['version', 'application', 'dataSources']
+  ),
+  PreviewUploadData: frozenObject(
+    {
+      manifest: schemaRef('UploadManifestPreview'),
+      payload: schemaRef('UploadPayloadPreview')
+    },
+    ['manifest', 'payload']
+  ),
+  UploadResultData: frozenObject(
+    {
+      dataplaneUrl: { type: 'string', format: 'uri' },
+      environment: { type: 'string' },
+      uploadSkipped: { type: 'boolean' }
+    },
+    ['dataplaneUrl', 'environment', 'uploadSkipped']
+  ),
+  TestSystemFileResult: frozenObject(
+    {
+      file: { type: 'string' },
+      valid: { type: 'boolean' },
+      errors: stringArraySchema()
+    },
+    ['file', 'valid', 'errors']
+  ),
+  TestDatasourceResult: frozenObject(
+    {
+      key: { type: 'string' },
+      file: { type: 'string' },
+      valid: { type: 'boolean' },
+      errors: stringArraySchema(),
+      warnings: stringArraySchema(),
+      structuralValid: { type: 'boolean' },
+      payloadTestsRan: { type: 'boolean' },
+      payloadTestsOk: { type: 'boolean' }
+    },
+    ['key', 'valid', 'errors', 'warnings']
+  ),
+  IntegrationDatasourceResult: frozenObject(
+    {
+      key: { type: 'string' },
+      success: { type: 'boolean' },
+      skipped: { type: 'boolean' },
+      error: { type: 'string' }
+    },
+    ['key', 'success']
+  ),
+  E2ETestRunItem: frozenObject(
+    {
+      key: { type: 'string' },
+      success: { type: 'boolean' },
+      error: { type: 'string' },
+      datasourceTestRun: schemaRef('DatasourceTestRunSummary')
+    },
+    ['key', 'success']
+  ),
+  DatasourceTestRunSummary: frozenObject({
+    id: { type: 'string' },
+    status: { type: 'string' },
+    datasourceKey: { type: 'string' }
+  }),
+  UnitTestResultData: frozenObject(
+    {
+      runType: { type: 'string', enum: ['unit'] },
+      valid: { type: 'boolean' },
+      errors: stringArraySchema(),
+      warnings: stringArraySchema(),
+      systemResults: { type: 'array', items: schemaRef('TestSystemFileResult') },
+      datasourceResults: { type: 'array', items: schemaRef('TestDatasourceResult') },
+      systemKey: schemaRef('SystemKey'),
+      appName: { type: 'string' }
+    },
+    ['runType', 'valid', 'errors', 'warnings', 'systemResults', 'datasourceResults']
+  ),
+  IntegrationTestResultData: frozenObject(
+    {
+      runType: { type: 'string', enum: ['integration'] },
+      success: { type: 'boolean' },
+      datasourceResults: { type: 'array', items: schemaRef('IntegrationDatasourceResult') },
+      systemKey: schemaRef('SystemKey'),
+      appName: { type: 'string' }
+    },
+    ['runType', 'success', 'datasourceResults']
+  ),
+  E2ETestResultData: frozenObject(
+    {
+      runType: { type: 'string', enum: ['e2e'] },
+      success: { type: 'boolean' },
+      results: { type: 'array', items: schemaRef('E2ETestRunItem') }
+    },
+    ['runType', 'success', 'results']
+  ),
+  TestResultData: {
+    oneOf: [
+      schemaRef('UnitTestResultData'),
+      schemaRef('IntegrationTestResultData'),
+      schemaRef('E2ETestResultData')
+    ]
+  },
+  CertificationSummary: frozenObject(
+    {
+      level: schemaRef('CertificationLevel'),
+      status: schemaRef('CertificationStatus')
+    },
+    ['level', 'status']
+  ),
+  OperationsCheckDetail: frozenObject({
+    key: { type: 'string' },
+    passed: { type: 'boolean' },
+    message: { type: 'string' }
+  }),
+  OperationsStepResult: frozenObject({
+    step: { type: 'string' },
+    success: { type: 'boolean' },
+    error: { type: 'string' }
+  }),
+  CertifyOperationsResultData: frozenObject(
+    {
+      command: { type: 'string', enum: ['verify-operations'] },
+      systemKey: schemaRef('SystemKey'),
+      verdict: schemaRef('LifecycleVerdict'),
+      operationalReadinessPercent: { type: 'number', minimum: 0, maximum: 100 },
+      certification: schemaRef('CertificationSummary'),
+      warnings: stringArraySchema(),
+      details: { type: 'array', items: schemaRef('OperationsCheckDetail') },
+      stepResults: { type: 'array', items: schemaRef('OperationsStepResult') }
+    },
+    ['command', 'systemKey', 'verdict', 'operationalReadinessPercent', 'certification']
+  ),
+  TrustDatasourceRow: frozenObject(
+    {
+      datasourceKey: { type: 'string' },
+      verdict: schemaRef('LifecycleVerdict'),
+      trustDecision: { type: 'string' },
+      validationStatus: { type: 'string' },
+      error: { type: 'string' }
+    },
+    ['datasourceKey', 'verdict']
+  ),
+  CertifyTrustResultData: frozenObject(
+    {
+      command: { type: 'string', enum: ['verify-trust'] },
+      systemKey: schemaRef('SystemKey'),
+      verdict: schemaRef('LifecycleVerdict'),
+      aiTrustPercent: { type: ['number', 'null'] },
+      accessConfidencePercent: { type: ['number', 'null'] },
+      businessConfidencePercent: { type: ['number', 'null'] },
+      findings: stringArraySchema(),
+      datasourceRows: { type: 'array', items: schemaRef('TrustDatasourceRow') }
+    },
+    ['command', 'systemKey', 'verdict', 'datasourceRows']
+  ),
+  GovernanceScenarioCount: frozenObject(
+    {
+      passed: { type: 'integer', minimum: 0 },
+      total: { type: 'integer', minimum: 0 }
+    },
+    ['passed', 'total']
+  ),
+  GovernanceDatasourceRow: frozenObject(
+    {
+      datasourceKey: { type: 'string' },
+      verdict: schemaRef('LifecycleVerdict'),
+      policyCoveragePercent: { type: ['number', 'null'] },
+      dimensionCoveragePercent: { type: ['number', 'null'] },
+      scenarios: schemaRef('GovernanceScenarioCount')
+    },
+    ['datasourceKey', 'verdict']
+  ),
+  CertifyGovernanceResultData: frozenObject(
+    {
+      command: { type: 'string', enum: ['verify-governance'] },
+      systemKey: schemaRef('SystemKey'),
+      verdict: schemaRef('LifecycleVerdict'),
+      policyCoveragePercent: { type: 'number' },
+      dimensionCoveragePercent: { type: 'number' },
+      enforcementScenarios: schemaRef('GovernanceScenarioCount'),
+      datasourceRows: { type: 'array', items: schemaRef('GovernanceDatasourceRow') }
+    },
+    ['command', 'systemKey', 'verdict', 'enforcementScenarios', 'datasourceRows']
+  ),
+  LifecycleRunStep: frozenObject(
+    {
+      pillar: { type: 'string' },
+      success: { type: 'boolean' },
+      error: { type: 'string' }
+    },
+    ['pillar', 'success']
+  ),
+  LifecycleRunReport: frozenObject(
+    {
+      systemKey: schemaRef('SystemKey'),
+      certification: schemaRef('CertificationSummary')
+    },
+    ['systemKey']
+  ),
+  CertifyLifecycleRunResultData: frozenObject(
+    {
+      report: schemaRef('LifecycleRunReport'),
+      stepsRun: { type: 'array', items: schemaRef('LifecycleRunStep') }
+    },
+    ['report']
+  ),
+  CertifyResultData: {
+    oneOf: [
+      schemaRef('CertifyOperationsResultData'),
+      schemaRef('CertifyTrustResultData'),
+      schemaRef('CertifyGovernanceResultData'),
+      schemaRef('CertifyLifecycleRunResultData')
+    ]
+  },
+  LifecycleReportData: frozenObject(
+    {
+      systemKey: schemaRef('SystemKey'),
+      certification: schemaRef('CertificationSummary'),
+      operationalReadinessPercent: { type: 'number' },
+      summary: { type: 'boolean' },
+      details: { type: 'boolean' }
+    },
+    ['systemKey']
+  ),
+  EnterpriseMcpToolOutput: frozenObject({
+    success: { type: 'boolean' },
+    status: { type: 'string' },
+    message: { type: 'string' },
+    branch: { type: 'string' },
+    pullRequestUrl: { type: 'string', format: 'uri' },
+    syncDirection: schemaRef('RepositorySyncDirection'),
+    commitSha: { type: 'string' },
+    workflowRunId: { type: 'string' }
+  }),
+  WorkspaceRemoteUnavailable: frozenObject(
+    {
+      unavailable: { type: 'boolean', enum: [true] },
+      message: { type: 'string' }
+    },
+    ['unavailable', 'message']
+  ),
+  WorkspaceRemoteStatus: {
+    oneOf: [schemaRef('EnterpriseMcpToolOutput'), schemaRef('WorkspaceRemoteUnavailable'), { type: 'null' }]
+  },
+  EnterpriseMcpInvocationData: frozenObject(
+    {
+      capabilityKey: { type: 'string' },
+      result: schemaRef('EnterpriseMcpToolOutput')
+    },
+    ['capabilityKey', 'result']
+  ),
+  WorkspaceStatusData: frozenObject(
+    {
+      local: schemaRef('SystemManifestData'),
+      remote: schemaRef('WorkspaceRemoteStatus')
+    },
+    ['local', 'remote']
+  ),
+  RepositoryStatusData: frozenObject(
+    {
+      capabilityKey: { type: 'string', enum: ['repository.status'] },
+      result: schemaRef('EnterpriseMcpToolOutput')
+    },
+    ['capabilityKey', 'result']
+  ),
+  HealthData: frozenObject({ status: { type: 'string', enum: ['ok'] } }, ['status']),
+  ReadyData: frozenObject(
+    {
+      status: { type: 'string', enum: ['ready'] },
+      dataplaneUrl: { type: ['string', 'null'], format: 'uri' }
+    },
+    ['status']
+  )
+};
+
+module.exports = {
+  OPENAPI_RESULT_SCHEMAS
+};

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

@@ -0,0 +1,139 @@
+/**
+ * OpenAPI schema descriptions — certify, lifecycle, governance, trust.
+ *
+ * @fileoverview Request/result models for certification routes
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** @type {Record<string, Object>} */
+const CERTIFY_SCHEMA_DESCRIPTIONS = {
+  CertifyRequest: {
+    _schema: 'Optional flags for certification pillar commands.',
+    noPublish: 'When true, skip publishing local files before verify commands.',
+    pack: 'Governance scenario pack key for verify-governance.',
+    lifecycleBody: 'Optional subject and dry-run options when pillar is lifecycle-run.'
+  },
+  LifecycleRunRequest: {
+    _schema: 'Options for lifecycle-run certification pillar.',
+    subjectEmail: 'Email of the subject user for lifecycle scenarios.',
+    dryRun: 'When true, execute lifecycle checks without persisting outcomes.'
+  },
+  CertificationSummary: {
+    _schema: 'Certification level and readiness status from Dataplane lifecycle.',
+    level: 'Certification tier (BRONZE through PLATINUM or NONE).',
+    status: 'Readiness label (e.g. AI_READY, NOT_CERTIFIED).'
+  },
+  OperationsCheckDetail: {
+    _schema: 'Single operational readiness check from verify-operations.',
+    key: 'Check identifier or rule key.',
+    passed: 'True when this check passed.',
+    message: 'Human-readable check outcome message.'
+  },
+  OperationsStepResult: {
+    _schema: 'Result of one step in the verify-operations ladder.',
+    step: 'Step name or command label.',
+    success: 'True when the step completed successfully.',
+    error: 'Error detail when success is false.'
+  },
+  CertifyOperationsResultData: {
+    _schema: 'verify-operations pillar result with readiness percentage.',
+    command: 'Always verify-operations for this variant.',
+    systemKey: 'Integration system key certified.',
+    verdict: 'Lifecycle verdict for operations pillar.',
+    operationalReadinessPercent: 'Operational readiness score 0–100.',
+    certification: 'Certification level and status summary.',
+    warnings: 'Non-blocking operational warnings.',
+    details: 'Per-check operational readiness details.',
+    stepResults: 'Ordered step outcomes for the operations ladder.'
+  },
+  TrustDatasourceRow: {
+    _schema: 'Trust verification row for one datasource from verify-trust.',
+    datasourceKey: 'Datasource key evaluated.',
+    verdict: 'Trust verdict for this datasource.',
+    trustDecision: 'Trust decision label from Dataplane.',
+    validationStatus: 'Validation status string from trust checks.',
+    error: 'Error detail when verdict is not VERIFIED.'
+  },
+  CertifyTrustResultData: {
+    _schema: 'verify-trust pillar result with AI trust percentages.',
+    command: 'Always verify-trust for this variant.',
+    systemKey: 'Integration system key certified.',
+    verdict: 'Aggregate trust verdict.',
+    aiTrustPercent: 'AI trust score 0–100, or null when not computed.',
+    accessConfidencePercent: 'Access confidence score, or null when not computed.',
+    businessConfidencePercent: 'Business confidence score, or null when not computed.',
+    findings: 'Trust findings and recommendations.',
+    datasourceRows: 'Per-datasource trust outcomes.'
+  },
+  GovernanceScenarioCount: {
+    _schema: 'Passed vs total governance enforcement scenarios.',
+    passed: 'Number of scenarios that passed.',
+    total: 'Total scenarios executed.'
+  },
+  GovernanceDatasourceRow: {
+    _schema: 'Governance verification row for one datasource.',
+    datasourceKey: 'Datasource key evaluated.',
+    verdict: 'Governance verdict for this datasource.',
+    policyCoveragePercent: 'Policy coverage percentage, or null when unavailable.',
+    dimensionCoveragePercent: 'Dimension coverage percentage, or null when unavailable.',
+    scenarios: 'Passed and total enforcement scenario counts.'
+  },
+  CertifyGovernanceResultData: {
+    _schema: 'verify-governance pillar result with policy and dimension coverage.',
+    command: 'Always verify-governance for this variant.',
+    systemKey: 'Integration system key certified.',
+    verdict: 'Aggregate governance verdict.',
+    policyCoveragePercent: 'System-level policy coverage percentage.',
+    dimensionCoveragePercent: 'System-level dimension coverage percentage.',
+    enforcementScenarios: 'Aggregate scenario pass counts.',
+    datasourceRows: 'Per-datasource governance outcomes.'
+  },
+  LifecycleRunStep: {
+    _schema: 'One pillar executed during lifecycle-run.',
+    pillar: 'Pillar name (operations, trust, governance, etc.).',
+    success: 'True when this pillar run succeeded.',
+    error: 'Error detail when success is false.'
+  },
+  LifecycleRunReport: {
+    _schema: 'Summary report embedded in lifecycle-run results.',
+    systemKey: 'Integration system key.',
+    certification: 'Certification level and status after lifecycle-run.'
+  },
+  CertifyLifecycleRunResultData: {
+    _schema: 'lifecycle-run pillar result executing multiple certification pillars.',
+    report: 'Lifecycle certification report summary.',
+    stepsRun: 'Ordered list of pillars executed and their outcomes.'
+  },
+  CertifyResultData: {
+    _schema: 'Discriminated union of certification pillar results (see command field).'
+  },
+  LifecycleReportData: {
+    _schema: 'Lifecycle report fetched from Dataplane for a systemKey.',
+    systemKey: 'Integration system key.',
+    certification: 'Current certification level and status.',
+    operationalReadinessPercent: 'Operational readiness when included in report.',
+    summary: 'True when response is summary-only.',
+    details: 'True when detailed sections are included.'
+  },
+  CertifyResultResponse: {
+    _schema: '200 response envelope for runCertifyPillar.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see CertifyResultData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  LifecycleReportResponse: {
+    _schema: '200 response envelope for getLifecycleReport.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see LifecycleReportData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  }
+};
+
+module.exports = {
+  CERTIFY_SCHEMA_DESCRIPTIONS
+};