@aifabrix/builder 2.49.2 → 2.51.0

package/lib/programmatic/openapi-descriptions.js

@@ -0,0 +1,190 @@
+/**
+ * MCP-friendly OpenAPI operation text for builder-api routes (plan 154.0 §6).
+ *
+ * @fileoverview One capability per route; imperative descriptions
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** @type {Record<string, { summary: string, description: string, tags: string[] }>} */
+const OPERATION_DESCRIPTIONS = Object.freeze({
+  listSystems: {
+    summary: 'List workspace external systems',
+    description:
+      'List integration system keys under the authenticated user workspace. Read-only; does not call Dataplane.',
+    tags: ['workspace']
+  },
+  createSystem: {
+    summary: 'Create workspace system folder',
+    description:
+      'Create an empty integration workspace for a systemKey. Mutating; requires Idempotency-Key on retries.',
+    tags: ['workspace']
+  },
+  getSystemManifest: {
+    summary: 'Read workspace manifest summary',
+    description: 'Return local workspace metadata and file manifest for one systemKey. Read-only.',
+    tags: ['workspace']
+  },
+  deleteSystem: {
+    summary: 'Delete workspace system folder',
+    description:
+      'Remove the local integration workspace for a systemKey. Mutating; does not delete Dataplane config.',
+    tags: ['workspace']
+  },
+  runWizard: {
+    summary: 'Generate integration files from OpenAPI or wizard config',
+    description:
+      'Run headless wizard to materialize system and datasource JSON under the workspace. Mutating; may take up to MAX_REQUEST_TIMEOUT_MS. Retry with the same Idempotency-Key.',
+    tags: ['build']
+  },
+  runRepair: {
+    summary: 'Repair workspace manifest drift',
+    description:
+      'Align application manifest, env.template, and datasource metadata with on-disk JSON. Mutating.',
+    tags: ['build']
+  },
+  listManifestSections: {
+    summary: 'List governed manifest sections',
+    description: 'Return sectionKey catalog and datasource keys for MCP section editing. Read-only.',
+    tags: ['manifest']
+  },
+  getManifestSection: {
+    summary: 'Read one system manifest section',
+    description:
+      'Return section value, schema fragment, quality, dependency graph, and sectionReadToken. MUST call before patchSection.',
+    tags: ['manifest']
+  },
+  patchManifestSection: {
+    summary: 'Patch one system manifest section',
+    description:
+      'Apply governed merge/replace to a system section. Requires intent and sectionReadToken from GET. Mutating.',
+    tags: ['manifest']
+  },
+  getDatasourceManifestSection: {
+    summary: 'Read one datasource manifest section',
+    description:
+      'Return datasource section value, quality, missingInputs, and sectionReadToken. MUST call before patchSection.',
+    tags: ['manifest']
+  },
+  patchDatasourceManifestSection: {
+    summary: 'Patch one datasource manifest section',
+    description:
+      'Apply governed merge/replace to a datasource section. Requires intent and sectionReadToken. Mutating.',
+    tags: ['manifest']
+  },
+  runManifestRepair: {
+    summary: 'Repair manifest sections with explicit hooks',
+    description:
+      'Run named repair hooks in dependency-graph order after section patches. Mutating; does not auto-upload.',
+    tags: ['manifest']
+  },
+  runValidate: {
+    summary: 'Validate local integration manifests',
+    description:
+      'Run AJV validation on workspace files. Optionally include pipeline validate-only against Dataplane (read-only).',
+    tags: ['validate']
+  },
+  runPreviewUpload: {
+    summary: 'Preview dev upload payload without publishing',
+    description:
+      'Build and validate the deploy payload locally. MUST NOT push credentials or mutate Dataplane. Use before POST /upload.',
+    tags: ['validate']
+  },
+  runTest: {
+    summary: 'Run unit, integration, or e2e tests',
+    description:
+      'Execute test ladder for the workspace. Mutating when syncing to Dataplane. e2e may take up to MAX_TEST_E2E_TIMEOUT_MS.',
+    tags: ['test']
+  },
+  runCertifyPillar: {
+    summary: 'Run certification pillar checks',
+    description:
+      'Run verify-operations, verify-trust, verify-governance, or lifecycle-run against Dataplane. Mutating when sync is enabled.',
+    tags: ['certify']
+  },
+  getLifecycleReport: {
+    summary: 'Read lifecycle certification report',
+    description: 'Fetch lifecycle report from Dataplane for the workspace system. Read-only proxy.',
+    tags: ['certify']
+  },
+  runUpload: {
+    summary: 'Upload integration to dev Dataplane',
+    description:
+      'Full dev publish: validate, sync deploy JSON, push credentials, pipeline upload. Requires external-system:publish in dev. Mutating; use Idempotency-Key; may take up to MAX_UPLOAD_TIMEOUT_MS.',
+    tags: ['apply']
+  },
+  materializeTemplate: {
+    summary: 'Materialize workspace from template',
+    description:
+      'Invoke Enterprise MCP template.materializeWorkspace for the integration systemKey. Provider-neutral; mutating.',
+    tags: ['template']
+  },
+  getWorkspaceStatus: {
+    summary: 'Read workspace status',
+    description: 'Combine local workspace manifest with Enterprise MCP workspace.status when available.',
+    tags: ['workspace']
+  },
+  runWorkspaceDiff: {
+    summary: 'Diff workspace draft',
+    description: 'Invoke Enterprise MCP workspace.diff for local draft vs remote/template baseline.',
+    tags: ['workspace']
+  },
+  resetWorkspaceFromTemplate: {
+    summary: 'Reset workspace from template',
+    description:
+      'Invoke Enterprise MCP workspace.resetFromTemplate. Use Dataplane lifecycle / verify-trust before mutating when required.',
+    tags: ['template']
+  },
+  runRepositorySync: {
+    summary: 'Sync workspace with remote repository',
+    description:
+      'Invoke Enterprise MCP repository.sync (pull or push via body params). Provider-neutral; mutating.',
+    tags: ['repository']
+  },
+  runRepositoryCreateReview: {
+    summary: 'Create or update repository review',
+    description: 'Invoke Enterprise MCP repository.createReview (PR or provider-equivalent). Mutating.',
+    tags: ['repository']
+  },
+  getRepositoryStatus: {
+    summary: 'Read repository sync status',
+    description: 'Invoke Enterprise MCP repository.status. Read-only proxy.',
+    tags: ['repository']
+  },
+  runRepositoryDispatchPipeline: {
+    summary: 'Dispatch repository pipeline',
+    description: 'Invoke Enterprise MCP repository.dispatchPipeline for CI/CD dispatch. Mutating.',
+    tags: ['repository']
+  },
+  health: {
+    summary: 'Liveness probe',
+    description: 'Returns ok when the builder-api process is running. No authentication.',
+    tags: ['infra']
+  },
+  ready: {
+    summary: 'Readiness probe',
+    description: 'Returns ready with configured dataplaneUrl. Does not verify Dataplane connectivity in V1.',
+    tags: ['infra']
+  }
+});
+
+/**
+ * @param {string} handlerId
+ * @returns {{ summary: string, description: string, tags: string[] }}
+ */
+function getOperationDescription(handlerId) {
+  return (
+    OPERATION_DESCRIPTIONS[handlerId] || {
+      summary: handlerId,
+      description: handlerId,
+      tags: ['builder']
+    }
+  );
+}
+
+module.exports = {
+  OPERATION_DESCRIPTIONS,
+  getOperationDescription
+};

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