@aifabrix/builder 2.49.2 → 2.50.0

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

@@ -0,0 +1,225 @@
+/**
+ * Workspace manifest file IO for section editing (plan 154.4).
+ *
+ * @fileoverview Load/save system and datasource JSON with discovery
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+const { discoverIntegrationFiles } = require('../commands/repair-internal');
+const { loadConfigFile } = require('../utils/config-format');
+const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
+
+const AUDIT_FILENAME = '.builder-section-audit.jsonl';
+const SECRET_PATTERN = /kv:\/\/|secure:\/\/|Bearer\s+[A-Za-z0-9._-]+/gi;
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {string}
+ */
+function getIntegrationPath(ctx) {
+  return ctx.getIntegrationPath(ctx.systemKey);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {{ systemFile: string, systemPath: string, systemDoc: Object }}
+ */
+function loadSystemDocument(ctx) {
+  const appPath = getIntegrationPath(ctx);
+  const { systemFiles } = discoverIntegrationFiles(appPath);
+  if (!systemFiles.length) {
+    const err = new Error(`No system file found in workspace for ${ctx.systemKey}`);
+    err.statusCode = 404;
+    throw err;
+  }
+  const systemFile = systemFiles[0];
+  const systemPath = path.join(appPath, systemFile);
+  return { systemFile, systemPath, systemDoc: loadConfigFile(systemPath) };
+}
+
+/**
+ * @param {string} appPath
+ * @param {string} datasourceKey
+ * @returns {string|undefined}
+ */
+function findDatasourceFileName(appPath, datasourceKey) {
+  const { datasourceFiles } = discoverIntegrationFiles(appPath);
+  const key = typeof datasourceKey === 'string' ? datasourceKey.trim() : '';
+  if (!key) return undefined;
+
+  for (const name of datasourceFiles) {
+    try {
+      const doc = loadConfigFile(path.join(appPath, name));
+      if (doc && doc.key === key) return name;
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  const suffixMatch = datasourceFiles.find((name) => {
+    const m = name.match(/-datasource-(.+)\.(json|ya?ml)$/i);
+    if (!m) return false;
+    const suffix = m[1];
+    return key === suffix || key.endsWith(`-${suffix}`);
+  });
+  if (suffixMatch) return suffixMatch;
+
+  return datasourceFiles.find((name) => name.includes(key));
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {string} datasourceKey
+ * @returns {{ datasourceFile: string, datasourcePath: string, datasourceDoc: Object }}
+ */
+function loadDatasourceDocument(ctx, datasourceKey) {
+  const appPath = getIntegrationPath(ctx);
+  const match = findDatasourceFileName(appPath, datasourceKey);
+  if (!match) {
+    const err = new Error(`Datasource file not found for key ${datasourceKey}`);
+    err.statusCode = 404;
+    throw err;
+  }
+  const datasourcePath = path.join(appPath, match);
+  return { datasourceFile: match, datasourcePath, datasourceDoc: loadConfigFile(datasourcePath) };
+}
+
+/**
+ * @param {string} filePath
+ * @param {Object} doc
+ */
+function writeJsonDocument(filePath, doc) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * @param {string} integrationPath
+ * @param {string} relativeName
+ */
+function backupFile(integrationPath, relativeName) {
+  const source = path.join(integrationPath, relativeName);
+  if (!fs.existsSync(source)) {
+    return null;
+  }
+  const backupDir = path.join(integrationPath, 'backup');
+  fs.mkdirSync(backupDir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const dest = path.join(backupDir, `${relativeName}.${stamp}.bak`);
+  fs.copyFileSync(source, dest);
+  return dest;
+}
+
+/**
+ * @param {*} value
+ * @returns {string}
+ */
+function hashValue(value) {
+  const payload = JSON.stringify(value);
+  return `sha256:${crypto.createHash('sha256').update(payload).digest('hex')}`;
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} entry
+ */
+function appendSectionAudit(ctx, entry) {
+  const auditPath = path.join(getIntegrationPath(ctx), AUDIT_FILENAME);
+  const line = `${JSON.stringify({ ...entry, timestamp: new Date().toISOString() })}\n`;
+  fs.appendFileSync(auditPath, line, 'utf8');
+}
+
+/**
+ * @param {*} value
+ * @returns {*}
+ */
+function redactSecrets(value) {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (typeof value === 'string') {
+    return value.replace(SECRET_PATTERN, '[REDACTED]');
+  }
+  if (Array.isArray(value)) {
+    return value.map(redactSecrets);
+  }
+  if (typeof value === 'object') {
+    /** @type {Record<string, *>} */
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      if (/secret|password|token|apikey/i.test(key)) {
+        out[key] = '[REDACTED]';
+      } else {
+        out[key] = redactSecrets(child);
+      }
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {string[]}
+ */
+function listDatasourceKeys(ctx) {
+  const appPath = getIntegrationPath(ctx);
+  let fromConfig = null;
+  try {
+    const configPath = resolveApplicationConfigPath(appPath);
+    if (fs.existsSync(configPath)) {
+      const variables = loadConfigFile(configPath);
+      fromConfig = variables.externalIntegration?.dataSources;
+    }
+  } catch {
+    fromConfig = null;
+  }
+  if (Array.isArray(fromConfig) && fromConfig.length) {
+    return fromConfig.map((name) => {
+      const filePath = path.join(appPath, name);
+      if (fs.existsSync(filePath)) {
+        try {
+          const doc = loadConfigFile(filePath);
+          if (doc && typeof doc.key === 'string' && doc.key.trim()) {
+            return doc.key.trim();
+          }
+        } catch {
+          // fall through to filename heuristic
+        }
+      }
+      return name.replace(/\.(json|ya?ml)$/i, '').replace(/^.*-datasource-/, '');
+    });
+  }
+  const { datasourceFiles } = discoverIntegrationFiles(appPath);
+  return datasourceFiles.map((name) => {
+    try {
+      const doc = loadConfigFile(path.join(appPath, name));
+      if (doc && typeof doc.key === 'string' && doc.key.trim()) {
+        return doc.key.trim();
+      }
+    } catch {
+      // fall through
+    }
+    return name.replace(/\.(json|ya?ml)$/i, '').replace(/^.*-datasource-/, '');
+  });
+}
+
+module.exports = {
+  AUDIT_FILENAME,
+  getIntegrationPath,
+  findDatasourceFileName,
+  loadSystemDocument,
+  loadDatasourceDocument,
+  writeJsonDocument,
+  backupFile,
+  hashValue,
+  appendSectionAudit,
+  redactSecrets,
+  listDatasourceKeys
+};

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

@@ -0,0 +1,171 @@
+/**
+ * Deterministic section quality scoring (plan 154.4).
+ *
+ * @fileoverview SectionQuality, missingInputs, blockingIssues
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const RECORD_STORAGE_TYPES = new Set(['recordStorage', 'documentStorage']);
+
+/**
+ * @param {Object} input
+ * @param {string} input.sectionKey
+ * @param {Object} input.currentValue
+ * @param {Object} [input.datasourceDoc]
+ * @returns {Object}
+ */
+function computeSectionQuality(input) {
+  const blockingIssues = [];
+  const warnings = [];
+  const missingInputs = [];
+  const assumptions = [];
+
+  if (input.sectionKey === 'datasource.entityType') {
+    evaluateEntityType(input.currentValue, missingInputs, blockingIssues);
+  }
+  if (input.sectionKey === 'datasource.identity') {
+    evaluateIdentity(input.datasourceDoc, missingInputs, warnings);
+  }
+  if (input.sectionKey === 'datasource.metadata') {
+    evaluateMetadata(input.currentValue, warnings);
+  }
+  if (input.sectionKey === 'datasource.openapiOperations') {
+    evaluateWriteOps(input.currentValue, warnings);
+  }
+  if (input.sectionKey === 'datasource.capabilities' && input.datasourceDoc) {
+    evaluateCapabilityExecutionParity(input.datasourceDoc, blockingIssues, warnings);
+    evaluateCapabilityOpenApiParity(input.datasourceDoc, warnings);
+  }
+  if (input.sectionKey === 'datasource.openapiOperations' && input.datasourceDoc) {
+    evaluateCapabilityOpenApiParity(input.datasourceDoc, warnings);
+  }
+
+  let score = 100 - blockingIssues.length * 15 - warnings.length * 5 - missingInputs.filter((m) => m.required).length * 10;
+  score = Math.max(0, Math.min(100, score));
+  return { score, blockingIssues, warnings, missingInputs, assumptions };
+}
+
+/**
+ * @param {Object|string} currentValue
+ * @param {Object[]} missingInputs
+ * @param {Object[]} blockingIssues
+ */
+function evaluateEntityType(currentValue, missingInputs, blockingIssues) {
+  const entityType = typeof currentValue === 'string' ? currentValue : currentValue?.entityType;
+  if (!entityType) {
+    missingInputs.push({
+      field: 'entityType',
+      question: 'Which entity type best describes this datasource (recordStorage, documentStorage, serviceContract, none)?',
+      required: true
+    });
+    blockingIssues.push({ severity: 'error', message: 'entityType is required' });
+  }
+}
+
+/**
+ * @param {Object} [datasourceDoc]
+ * @param {Object[]} missingInputs
+ * @param {Object[]} warnings
+ */
+function evaluateIdentity(datasourceDoc, missingInputs, warnings) {
+  const entityType = datasourceDoc?.entityType;
+  if (!entityType || !RECORD_STORAGE_TYPES.has(entityType)) {
+    return;
+  }
+  const primaryKey = datasourceDoc?.primaryKey;
+  if (!primaryKey || (Array.isArray(primaryKey) && primaryKey.length === 0)) {
+    missingInputs.push({
+      field: 'primaryKey',
+      question: 'Which field uniquely identifies this record?',
+      required: true
+    });
+  }
+  if (!datasourceDoc?.metadataSchema?.properties || Object.keys(datasourceDoc.metadataSchema.properties).length === 0) {
+    warnings.push('metadataSchema has no properties defined yet');
+  }
+}
+
+/**
+ * @param {Object} currentValue
+ * @param {Object[]} warnings
+ */
+function evaluateMetadata(currentValue, warnings) {
+  const properties = currentValue?.properties;
+  if (!properties || Object.keys(properties).length === 0) {
+    warnings.push('metadataSchema has no required fields');
+  }
+}
+
+/**
+ * @param {Object} currentValue
+ * @param {Object[]} warnings
+ */
+function evaluateWriteOps(currentValue, warnings) {
+  const ops = currentValue?.operations;
+  if (!ops || typeof ops !== 'object') {
+    return;
+  }
+  const writeOps = Object.entries(ops).filter(([, op]) => op && /put|post|patch|delete/i.test(String(op.method || '')));
+  if (writeOps.length > 0) {
+    warnings.push('Write operations present — RBAC repair may be required before test');
+  }
+}
+
+/**
+ * @param {Object} quality
+ * @returns {boolean}
+ */
+function hasRequiredMissingInputs(quality) {
+  const missing = Array.isArray(quality?.missingInputs) ? quality.missingInputs : [];
+  return missing.some((item) => item && item.required === true);
+}
+
+/**
+ * @param {Object} datasourceDoc
+ * @param {Object[]} blockingIssues
+ * @param {Object[]} warnings
+ */
+function evaluateCapabilityExecutionParity(datasourceDoc, blockingIssues, warnings) {
+  const { listCapabilityKeys } = require('../datasource/capability/capability-manifest');
+  const capKeys = listCapabilityKeys(datasourceDoc?.capabilities);
+  const cipOps = datasourceDoc?.execution?.cip?.operations;
+  const cipCount =
+    cipOps && typeof cipOps === 'object' ? Object.keys(cipOps).length : 0;
+  if (capKeys.length === 0) {
+    return;
+  }
+  if (cipCount !== capKeys.length) {
+    blockingIssues.push({
+      severity: 'error',
+      message: `Capability count (${capKeys.length}) does not match execution.cip.operations count (${cipCount}) — run repair with operations hook`
+    });
+    return;
+  }
+  const missing = capKeys.filter((key) => !cipOps[key]);
+  if (missing.length > 0) {
+    warnings.push(`execution.cip.operations missing keys: ${missing.join(', ')}`);
+  }
+}
+
+/**
+ * @param {Object} datasourceDoc
+ * @param {Object[]} warnings
+ */
+function evaluateCapabilityOpenApiParity(datasourceDoc, warnings) {
+  const { findCapabilityKeysMissingFromOpenApi, formatCapabilityOpenApiDriftWarning } = require('../commands/repair-capability-openapi-warnings');
+  const missingKeys = findCapabilityKeysMissingFromOpenApi(datasourceDoc);
+  if (missingKeys.length === 0) {
+    return;
+  }
+  warnings.push(formatCapabilityOpenApiDriftWarning(datasourceDoc?.key || 'datasource', datasourceDoc, missingKeys));
+}
+
+module.exports = {
+  computeSectionQuality,
+  hasRequiredMissingInputs,
+  evaluateCapabilityExecutionParity,
+  evaluateCapabilityOpenApiParity
+};

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