@aifabrix/builder 2.49.2 → 2.51.0

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

@@ -0,0 +1,269 @@
+/**
+ * Section registry definitions for governed manifest editing (plan 154.4).
+ *
+ * @fileoverview Data-only sectionKey → path mappings
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** @typedef {'system' | 'datasource'} ManifestTarget */
+
+/**
+ * @typedef {Object} SectionDefinition
+ * @property {ManifestTarget} target
+ * @property {string[]} paths
+ * @property {boolean} mutable
+ * @property {boolean} required
+ * @property {boolean} sourceOfTruth
+ * @property {string[]} repairHooks
+ * @property {boolean} [blocked]
+ */
+
+/** @type {Readonly<Record<string, SectionDefinition>>} */
+const SECTION_DEFINITIONS = Object.freeze({
+  'system.basics': {
+    target: 'system',
+    paths: ['key', 'displayName', 'description'],
+    mutable: true,
+    required: true,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'system.kind': {
+    target: 'system',
+    paths: ['type'],
+    mutable: true,
+    required: true,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'system.businessEntities': {
+    target: 'system',
+    paths: ['businessEntities'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'system.authentication': {
+    target: 'system',
+    paths: ['authentication'],
+    mutable: false,
+    required: true,
+    sourceOfTruth: true,
+    repairHooks: [],
+    blocked: true
+  },
+  'system.configuration': {
+    target: 'system',
+    paths: ['configuration'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'system.rolesPermissions': {
+    target: 'system',
+    paths: ['roles', 'permissions'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: false,
+    repairHooks: ['rbac']
+  },
+  'system.subscriptions': {
+    target: 'system',
+    paths: ['subscriptions'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'system.aiInterfaces': {
+    target: 'system',
+    paths: ['aiInterfaces'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'system.lifecycle': {
+    target: 'system',
+    paths: ['lifecycle'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'datasource.basics': {
+    target: 'datasource',
+    paths: ['key', 'displayName', 'description', 'systemKey', 'enabled'],
+    mutable: true,
+    required: true,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'datasource.entityType': {
+    target: 'datasource',
+    paths: ['entityType'],
+    mutable: true,
+    required: true,
+    sourceOfTruth: true,
+    repairHooks: ['fieldMappings']
+  },
+  'datasource.resourceType': {
+    target: 'datasource',
+    paths: ['resourceType'],
+    mutable: true,
+    required: true,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'datasource.metadata': {
+    target: 'datasource',
+    paths: ['metadataSchema'],
+    mutable: true,
+    required: true,
+    sourceOfTruth: true,
+    repairHooks: ['fieldMappings', 'expose', 'rbac']
+  },
+  'datasource.identity': {
+    target: 'datasource',
+    paths: ['primaryKey'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: ['fieldMappings']
+  },
+  'datasource.fieldMappings': {
+    target: 'datasource',
+    paths: ['fieldMappings'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: false,
+    repairHooks: ['fieldMappings', 'expose']
+  },
+  'datasource.capabilities': {
+    target: 'datasource',
+    paths: ['capabilities'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: ['expose', 'rbac']
+  },
+  'datasource.execution': {
+    target: 'datasource',
+    paths: ['execution'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'datasource.openapiOperations': {
+    target: 'datasource',
+    paths: ['openapi'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: ['expose', 'rbac']
+  },
+  'datasource.mcpOperations': {
+    target: 'datasource',
+    paths: ['mcp'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: ['rbac']
+  },
+  'datasource.exposedAttributes': {
+    target: 'datasource',
+    paths: ['exposed'],
+    mutable: false,
+    required: false,
+    sourceOfTruth: false,
+    repairHooks: ['expose']
+  },
+  'datasource.configuration': {
+    target: 'datasource',
+    paths: ['configuration'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'datasource.sync': {
+    target: 'datasource',
+    paths: ['sync'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: ['sync']
+  },
+  'datasource.governance': {
+    target: 'datasource',
+    paths: ['governance'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'datasource.foreignKeys': {
+    target: 'datasource',
+    paths: ['foreignKeys'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'datasource.protection': {
+    target: 'datasource',
+    paths: ['protection'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'datasource.dimensions': {
+    target: 'datasource',
+    paths: ['fieldMappings.dimensions'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: ['fieldMappings']
+  },
+  'datasource.abac': {
+    target: 'datasource',
+    paths: ['abac'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'datasource.dataQuality': {
+    target: 'datasource',
+    paths: ['dataQuality'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'datasource.validation': {
+    target: 'datasource',
+    paths: ['validation'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: []
+  },
+  'datasource.testPayload': {
+    target: 'datasource',
+    paths: ['testPayload'],
+    mutable: true,
+    required: false,
+    sourceOfTruth: true,
+    repairHooks: ['test']
+  }
+});
+
+module.exports = { SECTION_DEFINITIONS };

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

@@ -0,0 +1,222 @@
+/**
+ * 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;
+const PROTOTYPE_POLLUTION_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+
+/**
+ * @param {string} part
+ * @returns {boolean}
+ */
+function isSafePathPart(part) {
+  return typeof part === 'string' && part.length > 0 && !PROTOTYPE_POLLUTION_KEYS.has(part);
+}
+
+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('.');
+  for (const part of parts) {
+    if (!isSafePathPart(part)) {
+      const err = new Error(`Unsafe path segment: ${part}`);
+      err.statusCode = 400;
+      throw err;
+    }
+  }
+  let current = doc;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const part = parts[i];
+    const next = Object.prototype.hasOwnProperty.call(current, part) ? current[part] : undefined;
+    if (next === null || next === undefined || typeof next !== 'object' || Array.isArray(next)) {
+      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
+};