@aifabrix/builder 2.51.1 → 2.52.1

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

@@ -66,6 +66,20 @@ const OPENAPI_REQUEST_SCHEMAS = {
     },
     ['appName', 'source']
   ),
+  IntegrationDefinitionApplyRequest: frozenObject({
+    integrationDefinition: {
+      type: 'object',
+      additionalProperties: true,
+      description: 'Builder Integration Definition (aifabrix.builder.integrationDefinition).'
+    },
+    bid: {
+      type: 'object',
+      additionalProperties: true,
+      description: 'Alias for integrationDefinition.'
+    },
+    force: { type: 'boolean' },
+    dryRun: { type: 'boolean' }
+  }),
   RepairRequest: frozenObject({
     dryRun: { type: 'boolean' },
     auth: { type: 'string' },

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

@@ -0,0 +1,101 @@
+'use strict';
+
+const { frozenObject, schemaRef } = require('./openapi-schema-helpers');
+
+const OPENAPI_RESULT_SCHEMA_OVERFLOW = {
+  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_SCHEMA_OVERFLOW };

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

@@ -9,6 +9,7 @@
 'use strict';
 
 const { frozenObject, schemaRef, stringArraySchema } = require('./openapi-schema-helpers');
+const { OPENAPI_RESULT_SCHEMA_OVERFLOW } = require('./openapi-result-schemas-overflow');
 
 /** @type {Record<string, Object>} */
 const OPENAPI_RESULT_SCHEMAS = {
@@ -19,9 +20,9 @@ const OPENAPI_RESULT_SCHEMAS = {
         title: { type: 'string' },
         status: { type: 'integer', minimum: 100, maximum: 599 },
         detail: { type: 'string' },
-        instance: { type: 'string' },
+        instance: { type: 'string', format: 'uri' },
         correlationId: { type: 'string' },
-        errors: { type: 'array', items: schemaRef('ProblemValidationError') }
+        errors: { type: 'array', items: schemaRef('ValidationError') }
       },
       ['type', 'title', 'status', 'detail', 'correlationId', 'instance', 'errors']
     ),
@@ -31,9 +32,15 @@ const OPENAPI_RESULT_SCHEMAS = {
         title: 'Unauthorized',
         status: 401,
         detail: 'Missing or invalid Bearer token.',
-        instance: '/api/v1/builder/workspaces/me/systems',
+        instance: 'https://api.example.com/api/v1/builder/workspaces/me/systems',
         correlationId: '00000000-0000-4000-8000-000000000003',
-        errors: []
+        errors: [
+          {
+            field: 'authorization',
+            message: 'Missing or invalid Bearer token.',
+            value: null
+          }
+        ]
       }
     }
   ),
@@ -41,14 +48,27 @@ const OPENAPI_RESULT_SCHEMAS = {
   ProblemDetails: {
     allOf: [schemaRef('ProblemDetail')]
   },
-  ProblemValidationError: frozenObject(
+  ValidationError: Object.assign(
+    frozenObject(
+      {
+        field: { type: 'string' },
+        message: { type: 'string' },
+        value: { type: ['string', 'null'] }
+      },
+      ['field', 'message', 'value']
+    ),
     {
-      field: { type: 'string' },
-      message: { type: 'string' },
-      value: { type: 'string' }
-    },
-    ['message']
+      example: {
+        field: 'authorization',
+        message: 'Missing or invalid Bearer token.',
+        value: null
+      }
+    }
   ),
+  /** Legacy alias — published REST requires ValidationError (OAPI-249/608). */
+  ProblemValidationError: {
+    allOf: [schemaRef('ValidationError')]
+  },
   LifecycleVerdict: {
     type: 'string',
     enum: ['VERIFIED', 'FAILED', 'NOT_VERIFIED', 'NOT_APPLICABLE']
@@ -131,6 +151,21 @@ const OPENAPI_RESULT_SCHEMAS = {
     },
     ['systemKey', 'status']
   ),
+  IntegrationDefinitionApplyData: frozenObject(
+    {
+      status: {
+        type: 'string',
+        enum: ['created', 'updated', 'idempotent', 'dryRun']
+      },
+      systemKey: schemaRef('SystemKey'),
+      outputDir: { type: 'string' },
+      definitionId: { type: 'string' },
+      definitionHash: { type: 'string' },
+      packageVersion: { type: 'string' },
+      files: stringArraySchema()
+    },
+    ['status', 'systemKey']
+  ),
   RepairResultData: frozenObject(
     {
       updated: { type: 'boolean' },
@@ -397,95 +432,7 @@ const OPENAPI_RESULT_SCHEMAS = {
     },
     ['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']
-  )
+  ...OPENAPI_RESULT_SCHEMA_OVERFLOW
 };
 
 module.exports = {

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

@@ -28,18 +28,21 @@ const CORE_SCHEMA_DESCRIPTIONS = {
     title: 'Short human-readable error title.',
     status: 'HTTP status code echoed in the body.',
     detail: 'Actionable error detail safe for operators and agents.',
-    instance: 'Request path or instance identifier.',
+    instance: 'Request URL for this occurrence (URI).',
     correlationId: 'Correlation id for log lookup across services.',
-    errors: 'Field-level validation errors when status is 400.'
+    errors: 'Field-level validation errors (non-empty when status is 400/422).'
   },
   ProblemDetails: {
     _schema: 'Alias of ProblemDetail (allOf) for backward-compatible $refs.'
   },
-  ProblemValidationError: {
+  ValidationError: {
     _schema: 'Single field validation error inside ProblemDetail.errors.',
     field: 'JSON pointer or field name that failed validation.',
     message: 'Validation failure message.',
-    value: 'Rejected value when safe to echo (may be omitted for secrets).'
+    value: 'Rejected value when safe to echo (null when omitted for secrets).'
+  },
+  ProblemValidationError: {
+    _schema: 'Legacy alias of ValidationError (allOf) for older $refs.'
   },
   LifecycleVerdict: {
     _schema: 'Lifecycle verification outcome: VERIFIED, FAILED, NOT_VERIFIED, or NOT_APPLICABLE.'

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

@@ -12,7 +12,7 @@
 const HELP_SCHEMA_DESCRIPTIONS = Object.freeze({
   BuilderHelpTopic: {
     _schema:
-      'Help topic enum: overview, sections, section, dependencyGraph, repairRules, workflow, schemaCatalog, subscriptionGuide, cipOverview, goldenExamples, goldenExample, evidencePatterns, evidencePattern.'
+      'Help topic enum including resourceTypeCatalog (taxonomy keys for BID datasources[].resourceType), overview, sections, schemaCatalog, platformRoles, dimensionsGuide, and related bootstrap topics.'
   },
   BuilderHelpData: {
     _schema: 'Deterministic LLM help payload for one topic (read-only product documentation).',

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

@@ -46,6 +46,30 @@ const OPERATIONS_SCHEMA_DESCRIPTIONS = {
     preferences: 'Optional expose, RBAC, and sync generation flags.',
     debug: 'When true, enable verbose wizard logging (also available as query param).'
   },
+  IntegrationDefinitionApplyRequest: {
+    _schema: 'Apply a Builder Integration Definition (BID) into the workspace package.',
+    integrationDefinition: 'BID document (aifabrix.builder.integrationDefinition).',
+    bid: 'Alias for integrationDefinition.',
+    force: 'When true, rewrite package even if definitionHash matches stamp.',
+    dryRun: 'When true, return planned files without writing.'
+  },
+  IntegrationDefinitionApplyResponse: {
+    _schema: '200 response envelope for applyIntegrationDefinition.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see IntegrationDefinitionApplyData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  IntegrationDefinitionApplyData: {
+    _schema: 'Typed apply result payload.',
+    status: 'created, updated, unchanged, or dryRun.',
+    systemKey: 'Integration system key that was materialized.',
+    outputDir: 'Absolute workspace integration directory.',
+    definitionId: 'BID definitionId.',
+    definitionHash: 'Canonical definitionHash written to stamp.',
+    packageVersion: 'Package version from packageIdentity.',
+    files: 'Relative package file names written or planned.'
+  },
   RepairRequest: {
     _schema: 'Optional flags for workspace repair aligning manifest files with on-disk JSON.',
     dryRun: 'Preview repair actions without writing files.',

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

@@ -41,14 +41,14 @@ function stringArraySchema() {
  * @returns {Object}
  */
 function buildSuccessEnvelopeSchema(dataSchemaName) {
-  const dataExamples = {
-    HealthData: { status: 'ok' },
-    ReadyData: { status: 'ready', dataplaneUrl: 'http://localhost:3601' },
-    ListSystemsData: { systems: [] },
-    EmptyResultData: {},
-    WorkspaceStatusData: { status: 'ready' },
-    RepositoryStatusData: { status: 'ready' }
-  };
+  const { OPENAPI_ENVELOPE_DATA_EXAMPLES } = require('./openapi-envelope-examples');
+  const dataExample = OPENAPI_ENVELOPE_DATA_EXAMPLES[dataSchemaName];
+  if (dataExample === undefined) {
+    throw new Error(
+      `Missing OpenAPI envelope data example for ${dataSchemaName} (OAPI-136). ` +
+        'Add it to lib/programmatic/openapi-envelope-examples.js'
+    );
+  }
   const schema = frozenObject(
     {
       success: { type: 'boolean', enum: [true] },
@@ -60,7 +60,7 @@ function buildSuccessEnvelopeSchema(dataSchemaName) {
   );
   schema.example = {
     success: true,
-    data: dataExamples[dataSchemaName] || {},
+    data: dataExample,
     correlationId: '00000000-0000-4000-8000-000000000001',
     requestId: '00000000-0000-4000-8000-000000000002'
   };

package/lib/programmatic/openapi-spec.js

@@ -73,7 +73,7 @@ function buildStandardErrorResponses() {
  * @returns {boolean}
  */
 function requiresBearerAuth(handlerId) {
-  return handlerId !== 'health' && handlerId !== 'ready';
+  return handlerId !== 'health' && handlerId !== 'ready' && handlerId !== 'getBuilderHelp';
 }
 
 /**
@@ -149,10 +149,20 @@ function buildOpenApiTags() {
     { 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).' },
+    {
+      name: 'help',
+      description:
+        'Deterministic LLM help topics (resourceTypeCatalog, schemaCatalog, …). No authentication.'
+    },
     {
       name: 'evidence',
       description:
         'BTA-facing Evidence authoring: metadata, download, upload (validate+certify), and human-gated activate.'
+    },
+    {
+      name: 'channel',
+      description:
+        'Discovery-driven channel packaging (Copilot, ChatGPT, Slack, Teams): build, summary, ZIP, branding.'
     }
   ];
 }

package/lib/programmatic/orchestration-openapi-meta.js

@@ -71,6 +71,16 @@ const ORCHESTRATION_TAG_CATALOG = Object.freeze({
     resourceType: 'role-evidence',
     permissionClass: 'evidence',
     displayName: 'Evidence'
+  },
+  channel: {
+    resourceType: 'channel',
+    permissionClass: 'channel',
+    displayName: 'Channel'
+  },
+  help: {
+    resourceType: 'document',
+    permissionClass: 'read',
+    displayName: 'Help'
   }
 });
 

package/lib/programmatic/route-handler-map.js

@@ -11,6 +11,9 @@
 const { buildContext } = require('./route-handlers-context');
 const { listSystems, createSystem, getSystemManifest, deleteSystem } = require('./workspace-ops');
 const { runWizard } = require('./run-wizard');
+const {
+  applyIntegrationDefinitionInWorkspace
+} = require('./run-integration-definition');
 const { runRepair } = require('./run-repair');
 const { runValidate } = require('./run-validate');
 const { runPreviewUpload, runUpload } = require('./run-upload');
@@ -41,6 +44,15 @@ const {
   activateEvidenceCandidates
 } = require('./run-evidence-authoring');
 
+const {
+  buildChannelPackage,
+  getChannelPackageSummary,
+  getChannelPackageZip,
+  patchChannelBranding,
+  getChannelBranding
+} = require('./run-channel-package');
+const { handleGetBuilderHelp } = require('./builder-help');
+
 /** @type {Record<string, Function>} */
 const HANDLER_MAP = {
   listSystems: (_params, auth) => listSystems(buildContext(auth, '_meta')),
@@ -57,6 +69,11 @@ const HANDLER_MAP = {
     runWizard(buildContext(auth, params.systemKey), body, {
       debug: query.debug === 'true' || body.debug === true
     }),
+  applyIntegrationDefinition: (params, auth, body) =>
+    applyIntegrationDefinitionInWorkspace(
+      buildContext(auth, params.systemKey),
+      body && typeof body === 'object' ? body : {}
+    ),
   runRepair: (params, auth, body, query) =>
     runRepair(buildContext(auth, params.systemKey), {
       dryRun: query.dryRun === 'true' || body.dryRun === true,
@@ -179,6 +196,7 @@ const HANDLER_MAP = {
     runRepositoryDispatchPipeline(buildContext(auth, params.systemKey), body),
   health: () => ({ status: 'ok' }),
   ready: () => ({ status: 'ready', dataplaneUrl: process.env.DATAPLANE_URL || null }),
+  getBuilderHelp: (_params, _auth, _body, query) => handleGetBuilderHelp(query || {}),
   getEvidenceMetadata: (params, auth) =>
     getEvidenceMetadata(buildContext(auth, '_evidence'), params.roleKey),
   downloadEvidence: (params, auth, _body, query) =>
@@ -199,7 +217,17 @@ const HANDLER_MAP = {
       roleKey: (body && body.roleKey) || params.roleKey
     }),
   activateEvidenceCandidates: (_params, auth, body) =>
-    activateEvidenceCandidates(buildContext(auth, '_evidence'), body)
+    activateEvidenceCandidates(buildContext(auth, '_evidence'), body),
+  buildChannelPackage: (params, auth, body) =>
+    buildChannelPackage(buildContext(auth, params.systemKey), body || {}),
+  getChannelPackageSummary: (params, auth) =>
+    getChannelPackageSummary(buildContext(auth, params.systemKey)),
+  getChannelPackageZip: (params, auth) =>
+    getChannelPackageZip(buildContext(auth, params.systemKey)),
+  getChannelBranding: (params, auth) =>
+    getChannelBranding(buildContext(auth, params.systemKey)),
+  patchChannelBranding: (params, auth, body) =>
+    patchChannelBranding(buildContext(auth, params.systemKey), body || {})
 };
 
 /**