@aifabrix/builder 2.49.2 → 2.50.0

package/lib/programmatic/manifest-section-registry.js

@@ -0,0 +1,205 @@
+/**
+ * Section registry extract/inject for governed manifest editing (plan 154.4).
+ *
+ * @fileoverview sectionKey enum, subtree IO, schema fragments
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  loadExternalSystemSchema,
+  loadExternalDataSourceSchema
+} = require('../utils/schema-loader');
+const { SECTION_DEFINITIONS } = require('./manifest-section-registry-data');
+
+const SCHEMA_DIR = path.join(__dirname, '..', 'schema');
+
+/** @type {Object|null} */
+let systemSchemaDoc = null;
+/** @type {Object|null} */
+let datasourceSchemaDoc = null;
+
+function getSystemSchemaDoc() {
+  if (!systemSchemaDoc) {
+    systemSchemaDoc = JSON.parse(fs.readFileSync(path.join(SCHEMA_DIR, 'external-system.schema.json'), 'utf8'));
+  }
+  return systemSchemaDoc;
+}
+
+function getDatasourceSchemaDoc() {
+  if (!datasourceSchemaDoc) {
+    datasourceSchemaDoc = JSON.parse(
+      fs.readFileSync(path.join(SCHEMA_DIR, 'external-datasource.schema.json'), 'utf8')
+    );
+  }
+  return datasourceSchemaDoc;
+}
+
+/**
+ * @param {string} sectionKey
+ * @returns {import('./manifest-section-registry-data').SectionDefinition}
+ */
+function getSectionDefinition(sectionKey) {
+  const def = SECTION_DEFINITIONS[sectionKey];
+  if (!def) {
+    const err = new Error(`Unknown sectionKey: ${sectionKey}`);
+    err.statusCode = 404;
+    throw err;
+  }
+  return def;
+}
+
+/**
+ * @param {string} [targetFilter]
+ * @returns {string[]}
+ */
+function listSectionKeys(targetFilter) {
+  return Object.keys(SECTION_DEFINITIONS).filter((key) => {
+    if (!targetFilter) {
+      return true;
+    }
+    return SECTION_DEFINITIONS[key].target === targetFilter;
+  });
+}
+
+/**
+ * @param {Object} doc
+ * @param {string} dottedPath
+ * @returns {*}
+ */
+function getPathValue(doc, dottedPath) {
+  const parts = dottedPath.split('.');
+  let current = doc;
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return current;
+}
+
+/**
+ * @param {Object} doc
+ * @param {string} dottedPath
+ * @param {*} value
+ */
+function setPathValue(doc, dottedPath, value) {
+  const parts = dottedPath.split('.');
+  let current = doc;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const part = parts[i];
+    if (current[part] === null || current[part] === undefined || typeof current[part] !== 'object') {
+      current[part] = {};
+    }
+    current = current[part];
+  }
+  current[parts[parts.length - 1]] = value;
+}
+
+/**
+ * @param {Object} doc
+ * @param {import('./manifest-section-registry-data').SectionDefinition} def
+ * @returns {Object}
+ */
+function extractSectionValue(doc, def) {
+  if (def.paths.length === 1) {
+    const value = getPathValue(doc, def.paths[0]);
+    return value === undefined ? {} : value;
+  }
+  /** @type {Record<string, *>} */
+  const result = {};
+  for (const pathKey of def.paths) {
+    const leaf = pathKey.includes('.') ? pathKey.split('.').pop() : pathKey;
+    const value = getPathValue(doc, pathKey);
+    if (value !== undefined) {
+      result[leaf] = value;
+    }
+  }
+  return result;
+}
+
+/**
+ * @param {Object} doc
+ * @param {import('./manifest-section-registry-data').SectionDefinition} def
+ * @param {Object} sectionValue
+ * @param {'merge' | 'replace'} mode
+ */
+function injectSectionValue(doc, def, sectionValue, mode) {
+  if (def.paths.length === 1) {
+    const pathKey = def.paths[0];
+    if (mode === 'replace') {
+      setPathValue(doc, pathKey, sectionValue);
+      return;
+    }
+    const existing = getPathValue(doc, pathKey);
+    const merged =
+      existing && typeof existing === 'object' && !Array.isArray(existing)
+        ? { ...existing, ...sectionValue }
+        : sectionValue;
+    setPathValue(doc, pathKey, merged);
+    return;
+  }
+  for (const pathKey of def.paths) {
+    const leaf = pathKey.includes('.') ? pathKey.split('.').pop() : pathKey;
+    if (!(leaf in sectionValue)) {
+      continue;
+    }
+    if (mode === 'replace') {
+      setPathValue(doc, pathKey, sectionValue[leaf]);
+    } else {
+      const existing = getPathValue(doc, pathKey);
+      const incoming = sectionValue[leaf];
+      const merged =
+        existing && typeof existing === 'object' && !Array.isArray(existing) && typeof incoming === 'object'
+          ? { ...existing, ...incoming }
+          : incoming;
+      setPathValue(doc, pathKey, merged);
+    }
+  }
+}
+
+/**
+ * @param {import('./manifest-section-registry-data').ManifestTarget} target
+ * @param {string} pathKey
+ * @returns {Object}
+ */
+function buildSchemaFragment(target, pathKey) {
+  const root = target === 'system' ? getSystemSchemaDoc() : getDatasourceSchemaDoc();
+  const topKey = pathKey.split('.')[0];
+  const prop = root.properties && root.properties[topKey];
+  if (!prop) {
+    return { type: 'object' };
+  }
+  if (pathKey.includes('.')) {
+    return { type: 'object' };
+  }
+  return JSON.parse(JSON.stringify(prop));
+}
+
+/**
+ * @param {import('./manifest-section-registry-data').ManifestTarget} target
+ * @param {Object} doc
+ * @returns {{ valid: boolean, errors: Object[] }}
+ */
+function validateManifestDocument(target, doc) {
+  const validate = target === 'system' ? loadExternalSystemSchema() : loadExternalDataSourceSchema();
+  const valid = validate(doc);
+  return { valid: !!valid, errors: validate.errors || [] };
+}
+
+module.exports = {
+  SECTION_DEFINITIONS,
+  getSectionDefinition,
+  listSectionKeys,
+  extractSectionValue,
+  injectSectionValue,
+  buildSchemaFragment,
+  validateManifestDocument,
+  getPathValue,
+  setPathValue
+};

package/lib/programmatic/nest-http-bridge.js

@@ -0,0 +1,34 @@
+/**
+ * Mount builder-api Node router on an Express instance (Nest adapter).
+ *
+ * @fileoverview Shared HTTP bridge for spike server and Nest bootstrap
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { handleRequest, BASE } = require('./builder-api-server');
+
+/**
+ * @param {import('express').Express} expressApp
+ */
+function wireBuilderApiHttpBridge(expressApp) {
+  expressApp.use((req, res, next) => {
+    const pathname = (req.url || '/').split('?')[0];
+    if (pathname !== BASE && !pathname.startsWith(`${BASE}/`)) {
+      next();
+      return;
+    }
+    handleRequest(req, res).catch((err) => {
+      res.statusCode = 500;
+      res.setHeader('Content-Type', 'application/json');
+      res.end(JSON.stringify({ error: err.message || 'Internal error' }));
+    });
+  });
+}
+
+module.exports = {
+  wireBuilderApiHttpBridge,
+  BASE
+};

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

@@ -0,0 +1,68 @@
+/**
+ * OpenAPI component schemas for builder-api (frozen models + response envelopes).
+ *
+ * @fileoverview Merges request/result schemas; no additionalProperties: true
+ * @author AI Fabrix Team
+ * @version 1.1.0
+ */
+
+'use strict';
+
+const { enrichOpenApiComponentSchemas } = require('./openapi-description-enricher');
+const { buildSuccessEnvelopeSchema } = require('./openapi-schema-helpers');
+const { OPENAPI_REQUEST_SCHEMAS } = require('./openapi-request-schemas');
+const { OPENAPI_RESULT_SCHEMAS } = require('./openapi-result-schemas');
+const {
+  OPENAPI_MANIFEST_REQUEST_SCHEMAS,
+  OPENAPI_MANIFEST_RESULT_SCHEMAS
+} = require('./openapi-manifest-schemas');
+
+const RESPONSE_ENVELOPES = [
+  ['ListSystemsResponse', 'ListSystemsData'],
+  ['CreateSystemResponse', 'CreateSystemData'],
+  ['SystemManifestResponse', 'SystemManifestData'],
+  ['DeleteSystemResponse', 'DeleteSystemData'],
+  ['WizardRunResponse', 'WizardRunData'],
+  ['RepairResultResponse', 'RepairResultData'],
+  ['ValidateResultResponse', 'ValidateResultData'],
+  ['PreviewUploadResponse', 'PreviewUploadData'],
+  ['UploadResultResponse', 'UploadResultData'],
+  ['TestResultResponse', 'TestResultData'],
+  ['CertifyResultResponse', 'CertifyResultData'],
+  ['LifecycleReportResponse', 'LifecycleReportData'],
+  ['EnterpriseMcpInvocationResponse', 'EnterpriseMcpInvocationData'],
+  ['WorkspaceStatusResponse', 'WorkspaceStatusData'],
+  ['RepositoryStatusResponse', 'RepositoryStatusData'],
+  ['HealthResponse', 'HealthData'],
+  ['ReadyResponse', 'ReadyData'],
+  ['EmptyResultResponse', 'EmptyResultData'],
+  ['ManifestSectionViewResponse', 'ManifestSectionViewData'],
+  ['ManifestPatchResultResponse', 'ManifestPatchResultData'],
+  ['ManifestSectionsListResponse', 'ManifestSectionsListData'],
+  ['ManifestRepairResultResponse', 'ManifestRepairResultData']
+];
+
+/**
+ * @returns {Record<string, Object>}
+ */
+function buildOpenApiComponentSchemas() {
+  const envelopes = {};
+  for (const [responseName, dataName] of RESPONSE_ENVELOPES) {
+    envelopes[responseName] = buildSuccessEnvelopeSchema(dataName);
+  }
+  return enrichOpenApiComponentSchemas({
+    ...OPENAPI_REQUEST_SCHEMAS,
+    ...OPENAPI_MANIFEST_REQUEST_SCHEMAS,
+    ...OPENAPI_RESULT_SCHEMAS,
+    ...OPENAPI_MANIFEST_RESULT_SCHEMAS,
+    EmptyResultData: { type: 'object', properties: {}, additionalProperties: false },
+    ...envelopes
+  });
+}
+
+module.exports = {
+  buildOpenApiComponentSchemas,
+  buildSuccessEnvelopeSchema,
+  OPENAPI_REQUEST_SCHEMAS,
+  OPENAPI_RESULT_SCHEMAS
+};

package/lib/programmatic/openapi-description-enricher.js

@@ -0,0 +1,117 @@
+/**
+ * Apply MCP-friendly descriptions to frozen OpenAPI component schemas.
+ *
+ * @fileoverview Merges description catalogs and wraps $ref props for OAS 3.0
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { CORE_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-core');
+const { OPERATIONS_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-operations');
+const { CERTIFY_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-certify');
+const { MANIFEST_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-manifest');
+const { MCP_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-mcp');
+const { HELP_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-help');
+
+/** @type {Record<string, Object>} */
+const MERGED_SCHEMA_DESCRIPTIONS = {
+  ...CORE_SCHEMA_DESCRIPTIONS,
+  ...OPERATIONS_SCHEMA_DESCRIPTIONS,
+  ...CERTIFY_SCHEMA_DESCRIPTIONS,
+  ...MANIFEST_SCHEMA_DESCRIPTIONS,
+  ...MCP_SCHEMA_DESCRIPTIONS,
+  ...HELP_SCHEMA_DESCRIPTIONS
+};
+
+/**
+ * @param {Object} propSchema
+ * @param {string} description
+ * @returns {Object}
+ */
+function withPropertyDescription(propSchema, description) {
+  if (!description) {
+    return propSchema;
+  }
+  if (propSchema.$ref) {
+    return { description, allOf: [propSchema] };
+  }
+  return { ...propSchema, description };
+}
+
+/**
+ * @param {Object} propSchema
+ * @param {Object} propDesc
+ */
+function enrichArrayProperty(propSchema, propDesc) {
+  if (typeof propDesc._schema === 'string') {
+    propSchema.description = propDesc._schema;
+  }
+  enrichSchemaNode(propSchema.items, propDesc._arrayItems);
+}
+
+/**
+ * @param {Object} schema
+ * @param {string} prop
+ * @param {string|Object} propDesc
+ */
+function enrichSchemaProperty(schema, prop, propDesc) {
+  const propSchema = schema.properties[prop];
+  if (!propSchema) {
+    return;
+  }
+  if (typeof propDesc === 'string') {
+    schema.properties[prop] = withPropertyDescription(propSchema, propDesc);
+    return;
+  }
+  if (typeof propDesc !== 'object') {
+    return;
+  }
+  if (propDesc._arrayItems && propSchema.type === 'array' && propSchema.items) {
+    enrichArrayProperty(propSchema, propDesc);
+    return;
+  }
+  enrichSchemaNode(propSchema, propDesc);
+}
+
+/**
+ * @param {Object} schema
+ * @param {Object} descNode
+ */
+function enrichSchemaNode(schema, descNode) {
+  if (!schema || !descNode || typeof descNode !== 'object') {
+    return;
+  }
+  if (typeof descNode._schema === 'string') {
+    schema.description = descNode._schema;
+  }
+  if (!schema.properties) {
+    return;
+  }
+  for (const [prop, propDesc] of Object.entries(descNode)) {
+    if (prop === '_schema') {
+      continue;
+    }
+    enrichSchemaProperty(schema, prop, propDesc);
+  }
+}
+
+/**
+ * @param {Record<string, Object>} schemas
+ * @returns {Record<string, Object>}
+ */
+function enrichOpenApiComponentSchemas(schemas) {
+  for (const [name, descNode] of Object.entries(MERGED_SCHEMA_DESCRIPTIONS)) {
+    if (schemas[name]) {
+      enrichSchemaNode(schemas[name], descNode);
+    }
+  }
+  return schemas;
+}
+
+module.exports = {
+  enrichOpenApiComponentSchemas,
+  MERGED_SCHEMA_DESCRIPTIONS,
+  withPropertyDescription
+};

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