@aifabrix/builder 2.49.2 → 2.51.0

package/lib/programmatic/manifest-repair.js

@@ -0,0 +1,122 @@
+/**
+ * Section-scoped manifest repair orchestration (plan 154.4).
+ *
+ * @fileoverview Graph-ordered hooks delegating to repair command
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { repairExternalIntegration } = require('../commands/repair');
+const { getRepairTraversalOrder } = require('./manifest-section-dependency-graph');
+const { computeSectionQuality } = require('./manifest-section-quality');
+const { loadSystemDocument, loadDatasourceDocument } = require('./manifest-section-io');
+const { runWithWorkspaceContext } = require('./workspace-context');
+const { touchWorkspaceMeta } = require('./workspace-meta');
+
+const HOOK_FLAG_MAP = Object.freeze({
+  fieldMappings: 'sync',
+  expose: 'expose',
+  rbac: 'rbac',
+  sync: 'sync',
+  test: 'test',
+  api: 'api',
+  operations: 'operations'
+});
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {{ hooks?: string[], sectionKey?: string, datasourceKey?: string, dryRun?: boolean, auth?: string }} body
+ */
+async function runManifestRepair(ctx, body = {}) {
+  return runWithWorkspaceContext(ctx, async() => {
+    const requestedHooks = normalizeHooks(body.hooks, body.sectionKey);
+    const repairOptions = buildRepairOptions(requestedHooks, body);
+    const result = await repairExternalIntegration(ctx.systemKey, repairOptions);
+    if (body.dryRun !== true) {
+      touchWorkspaceMeta(ctx, { lastOperation: 'manifest-repair' });
+    }
+    const qualitySnapshot = buildPostRepairQuality(ctx, body);
+    return {
+      hooksRun: requestedHooks,
+      derivedSectionsUpdated: body.sectionKey ? getRepairTraversalOrder(body.sectionKey).sections : [],
+      repairResult: result,
+      dryRun: body.dryRun === true,
+      quality: qualitySnapshot
+    };
+  });
+}
+
+/**
+ * @param {string[]|undefined} hooks
+ * @param {string|undefined} sectionKey
+ * @returns {string[]}
+ */
+function normalizeHooks(hooks, sectionKey) {
+  if (Array.isArray(hooks) && hooks.length) {
+    return hooks.map(String);
+  }
+  if (sectionKey) {
+    return getRepairTraversalOrder(sectionKey).hooks;
+  }
+  const err = new Error('hooks[] is required when sectionKey is not provided');
+  err.statusCode = 400;
+  throw err;
+}
+
+/**
+ * @param {string[]} hooks
+ * @param {Object} body
+ * @returns {Object}
+ */
+function buildRepairOptions(hooks, body) {
+  /** @type {Object} */
+  const options = {
+    dryRun: body.dryRun === true,
+    auth: body.auth
+  };
+  for (const hook of hooks) {
+    const flag = HOOK_FLAG_MAP[hook];
+    if (flag) {
+      options[flag] = true;
+    }
+  }
+  if (options.rbac === true) {
+    options.operations = true;
+  }
+  return options;
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ * @returns {Object|null}
+ */
+function buildPostRepairQuality(ctx, body) {
+  if (!body.sectionKey) {
+    return null;
+  }
+  try {
+    if (body.sectionKey.startsWith('system.')) {
+      const { systemDoc } = loadSystemDocument(ctx);
+      return computeSectionQuality({ sectionKey: body.sectionKey, currentValue: systemDoc });
+    }
+    if (body.datasourceKey) {
+      const { datasourceDoc } = loadDatasourceDocument(ctx, body.datasourceKey);
+      return computeSectionQuality({
+        sectionKey: body.sectionKey,
+        currentValue: datasourceDoc,
+        datasourceDoc
+      });
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+module.exports = {
+  runManifestRepair,
+  HOOK_FLAG_MAP
+};

package/lib/programmatic/manifest-section-dependency-graph.js

@@ -0,0 +1,160 @@
+/**
+ * Directed dependency graph for governed manifest sections (plan 154.4).
+ *
+ * @fileoverview Repair traversal and nextActions generation
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** @type {ReadonlyArray<[string, string]>} */
+const SECTION_EDGES = Object.freeze([
+  ['datasource.metadata', 'datasource.fieldMappings'],
+  ['datasource.fieldMappings', 'datasource.exposedAttributes'],
+  ['datasource.exposedAttributes', 'datasource.openapiOperations'],
+  ['datasource.openapiOperations', 'datasource.mcpOperations'],
+  ['datasource.mcpOperations', 'system.rolesPermissions'],
+  ['datasource.capabilities', 'datasource.openapiOperations'],
+  ['datasource.identity', 'datasource.fieldMappings'],
+  ['datasource.entityType', 'datasource.metadata']
+]);
+
+/** @type {Readonly<Record<string, string[]>>} */
+const SECTION_REPAIR_HOOKS = Object.freeze({
+  'datasource.metadata': ['fieldMappings', 'expose', 'rbac'],
+  'datasource.fieldMappings': ['fieldMappings', 'expose'],
+  'datasource.exposedAttributes': ['expose'],
+  'datasource.openapiOperations': ['expose', 'rbac'],
+  'datasource.mcpOperations': ['rbac'],
+  'datasource.capabilities': ['expose', 'rbac', 'operations'],
+  'datasource.identity': ['fieldMappings'],
+  'system.rolesPermissions': ['rbac']
+});
+
+/**
+ * @param {string} sectionKey
+ * @returns {string[]}
+ */
+function getDownstream(sectionKey) {
+  const adjacency = buildAdjacency();
+  const visited = new Set();
+  const order = [];
+  const queue = [sectionKey];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const next = adjacency.get(current) || [];
+    for (const dep of next) {
+      if (visited.has(dep)) {
+        continue;
+      }
+      visited.add(dep);
+      order.push(dep);
+      queue.push(dep);
+    }
+  }
+  return order;
+}
+
+/**
+ * @param {string} sectionKey
+ * @returns {{ sections: string[], hooks: string[] }}
+ */
+function getRepairTraversalOrder(sectionKey) {
+  const sections = getDownstream(sectionKey);
+  const hookSet = new Set();
+  const allKeys = [sectionKey, ...sections];
+  for (const key of allKeys) {
+    const hooks = SECTION_REPAIR_HOOKS[key] || [];
+    for (const hook of hooks) {
+      hookSet.add(hook);
+    }
+  }
+  return { sections, hooks: [...hookSet] };
+}
+
+/**
+ * @param {Object} _ctx
+ * @param {{ sectionKey: string, lastOp?: string, quality?: Object }} input
+ * @returns {string[]}
+ */
+function computeNextActions(_ctx, input) {
+  const quality = input.quality || {};
+  const missing = Array.isArray(quality.missingInputs) ? quality.missingInputs : [];
+  const hasRequiredMissing = missing.some((item) => item && item.required === true);
+  if (hasRequiredMissing) {
+    return ['askUser'];
+  }
+  if (input.lastOp === 'getSection') {
+    return ['patchSection', 'repair', 'validate'];
+  }
+  if (input.lastOp === 'patchSection') {
+    const downstream = getDownstream(input.sectionKey);
+    if (downstream.length > 0) {
+      return ['repair', 'validate', 'test'];
+    }
+    return ['validate', 'test'];
+  }
+  if (input.lastOp === 'repair') {
+    return ['validate', 'test'];
+  }
+  return ['patchSection', 'repair', 'validate'];
+}
+
+/**
+ * @returns {Map<string, string[]>}
+ */
+function buildAdjacency() {
+  /** @type {Map<string, string[]>} */
+  const map = new Map();
+  for (const [source, target] of SECTION_EDGES) {
+    const list = map.get(source) || [];
+    list.push(target);
+    map.set(source, list);
+  }
+  return map;
+}
+
+/**
+ * @returns {boolean}
+ */
+function isAcyclicGraph() {
+  const adjacency = buildAdjacency();
+  const visiting = new Set();
+  const visited = new Set();
+
+  /** @param {string} node */
+  function visit(node) {
+    if (visited.has(node)) {
+      return true;
+    }
+    if (visiting.has(node)) {
+      return false;
+    }
+    visiting.add(node);
+    for (const next of adjacency.get(node) || []) {
+      if (!visit(next)) {
+        return false;
+      }
+    }
+    visiting.delete(node);
+    visited.add(node);
+    return true;
+  }
+
+  for (const node of adjacency.keys()) {
+    if (!visit(node)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+module.exports = {
+  SECTION_EDGES,
+  SECTION_REPAIR_HOOKS,
+  getDownstream,
+  getRepairTraversalOrder,
+  computeNextActions,
+  isAcyclicGraph
+};

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