@aifabrix/builder 2.49.1 → 2.50.0

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

@@ -0,0 +1,146 @@
+/**
+ * GET manifest section handler (plan 154.4).
+ *
+ * @fileoverview ManifestSectionView with quality, graph, read token
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const {
+  getDownstream,
+  computeNextActions,
+  getRepairTraversalOrder
+} = require('./manifest-section-dependency-graph');
+const {
+  getSectionDefinition,
+  listSectionKeys,
+  extractSectionValue,
+  buildSchemaFragment
+} = require('./manifest-section-registry');
+const { computeSectionQuality, hasRequiredMissingInputs } = require('./manifest-section-quality');
+const {
+  loadSystemDocument,
+  loadDatasourceDocument,
+  hashValue,
+  redactSecrets,
+  listDatasourceKeys
+} = require('./manifest-section-io');
+const { runWithWorkspaceContext } = require('./workspace-context');
+
+/**
+ * @param {Object} def
+ * @param {{ sectionKey: string, datasourceKey?: string }} options
+ */
+function validateManifestSectionRequest(def, options) {
+  if (def.blocked) {
+    const err = new Error(`Section ${options.sectionKey} is blocked for MCP editing`);
+    err.statusCode = 403;
+    throw err;
+  }
+  if (def.target === 'datasource' && !options.datasourceKey) {
+    const err = new Error('datasourceKey is required for datasource sections');
+    err.statusCode = 400;
+    throw err;
+  }
+  if (def.target === 'system' && options.datasourceKey) {
+    const err = new Error('datasourceKey must not be set for system sections');
+    err.statusCode = 400;
+    throw err;
+  }
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {{ sectionKey: string, datasourceKey?: string }} options
+ * @param {Object} def
+ * @returns {Object}
+ */
+function buildManifestSectionView(ctx, options, def) {
+  const { doc, datasourceDoc } = loadDocuments(ctx, def.target, options.datasourceKey);
+  const rawValue = extractSectionValue(doc, def);
+  const currentValue = redactSecrets(rawValue);
+  const quality = computeSectionQuality({
+    sectionKey: options.sectionKey,
+    currentValue: rawValue,
+    datasourceDoc
+  });
+  const downstreamFromThis = getDownstream(options.sectionKey);
+  const traversal = getRepairTraversalOrder(options.sectionKey);
+  let recommendedNextActions = computeNextActions(ctx, {
+    sectionKey: options.sectionKey,
+    lastOp: 'getSection',
+    quality
+  });
+  if (hasRequiredMissingInputs(quality)) {
+    recommendedNextActions = ['askUser'];
+  }
+
+  return {
+    sectionKey: options.sectionKey,
+    target: def.target,
+    datasourceKey: options.datasourceKey || null,
+    currentValue,
+    schemaFragment: buildSchemaFragment(def.target, def.paths[0]),
+    required: def.required,
+    mutable: def.mutable,
+    sourceOfTruth: def.sourceOfTruth,
+    dependencyGraph: { downstreamFromThis },
+    repairHooks: traversal.hooks,
+    recommendedNextActions,
+    sectionReadToken: hashValue({ sectionKey: options.sectionKey, value: rawValue }),
+    quality
+  };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {{ sectionKey: string, datasourceKey?: string }} options
+ */
+async function getManifestSection(ctx, options) {
+  return runWithWorkspaceContext(ctx, async() => {
+    const def = getSectionDefinition(options.sectionKey);
+    validateManifestSectionRequest(def, options);
+    return buildManifestSectionView(ctx, options, def);
+  });
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {{ target?: string }} [options]
+ */
+async function listManifestSections(ctx, options = {}) {
+  return runWithWorkspaceContext(ctx, async() => {
+    const target = options.target;
+    const systemKeys = listSectionKeys(target === 'datasource' ? 'datasource' : target === 'system' ? 'system' : undefined);
+    const datasourceKeys = listDatasourceKeys(ctx);
+    return {
+      systemKey: ctx.systemKey,
+      sections: systemKeys.map((sectionKey) => ({
+        sectionKey,
+        target: getSectionDefinition(sectionKey).target
+      })),
+      datasourceKeys
+    };
+  });
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {'system' | 'datasource'} target
+ * @param {string} [datasourceKey]
+ */
+function loadDocuments(ctx, target, datasourceKey) {
+  if (target === 'system') {
+    const { systemDoc } = loadSystemDocument(ctx);
+    return { doc: systemDoc, datasourceDoc: undefined };
+  }
+  const { datasourceDoc } = loadDatasourceDocument(ctx, datasourceKey);
+  return { doc: datasourceDoc, datasourceDoc };
+}
+
+module.exports = {
+  getManifestSection,
+  listManifestSections
+};

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

@@ -0,0 +1,252 @@
+/**
+ * PATCH manifest section handler (plan 154.4).
+ *
+ * @fileoverview Intent audit, read token, risk hints
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const {
+  getDownstream,
+  computeNextActions,
+  getRepairTraversalOrder
+} = require('./manifest-section-dependency-graph');
+const {
+  getSectionDefinition,
+  extractSectionValue,
+  injectSectionValue
+} = require('./manifest-section-registry');
+const manifestSectionRegistry = require('./manifest-section-registry');
+const { computeSectionQuality, hasRequiredMissingInputs } = require('./manifest-section-quality');
+const {
+  loadSystemDocument,
+  loadDatasourceDocument,
+  writeJsonDocument,
+  backupFile,
+  hashValue,
+  appendSectionAudit,
+  getIntegrationPath
+} = require('./manifest-section-io');
+const { runWithWorkspaceContext } = require('./workspace-context');
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {{ sectionKey: string, datasourceKey?: string, intent: string, patch: Object, mode: string, sectionReadToken: string, dryRun?: boolean }} body
+ */
+async function patchManifestSection(ctx, body) {
+  return runWithWorkspaceContext(ctx, async() => {
+    assertPatchRequest(body);
+    const def = getSectionDefinition(body.sectionKey);
+    assertPatchAllowed(def, body);
+
+    const loaded = loadTargetDocument(ctx, def.target, body.datasourceKey);
+    const beforeValue = extractSectionValue(loaded.doc, def);
+    verifyReadToken(body, beforeValue);
+
+    const draft = JSON.parse(JSON.stringify(loaded.doc));
+    injectSectionValue(draft, def, body.patch, body.mode === 'replace' ? 'replace' : 'merge');
+    validateDraftDocument(def.target, draft);
+
+    const afterValue = extractSectionValue(draft, def);
+    if (body.dryRun !== true) {
+      persistPatchedDocument(ctx, loaded, draft, body, beforeValue, afterValue);
+    }
+
+    return buildPatchResult(ctx, body, def, beforeValue, afterValue, draft);
+  });
+}
+
+/**
+ * @param {Object} body
+ * @param {*} beforeValue
+ */
+function verifyReadToken(body, beforeValue) {
+  const expectedToken = hashValue({ sectionKey: body.sectionKey, value: beforeValue });
+  if (body.sectionReadToken !== expectedToken) {
+    const err = new Error('Section read token is stale — GET the section again before patching');
+    err.statusCode = 409;
+    throw err;
+  }
+}
+
+/**
+ * @param {'system' | 'datasource'} target
+ * @param {Object} draft
+ */
+function validateDraftDocument(target, draft) {
+  const validation = manifestSectionRegistry.validateManifestDocument(target, draft);
+  if (!validation.valid) {
+    const err = new Error('Patched manifest failed schema validation');
+    err.statusCode = 422;
+    err.errors = validation.errors;
+    throw err;
+  }
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} loaded
+ * @param {Object} draft
+ * @param {Object} body
+ * @param {*} beforeValue
+ * @param {*} afterValue
+ */
+function persistPatchedDocument(ctx, loaded, draft, body, beforeValue, afterValue) {
+  backupFile(getIntegrationPath(ctx), loaded.fileName);
+  writeJsonDocument(loaded.filePath, draft);
+  appendSectionAudit(ctx, {
+    sectionKey: body.sectionKey,
+    datasourceKey: body.datasourceKey || null,
+    intent: body.intent,
+    beforeHash: hashValue(beforeValue),
+    afterHash: hashValue(afterValue),
+    mode: body.mode
+  });
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ * @param {import('./manifest-section-registry-data').SectionDefinition} def
+ * @param {*} beforeValue
+ * @param {*} afterValue
+ * @param {Object} draft
+ */
+function buildPatchResult(ctx, body, def, beforeValue, afterValue, draft) {
+  const quality = computeSectionQuality({
+    sectionKey: body.sectionKey,
+    currentValue: afterValue,
+    datasourceDoc: def.target === 'datasource' ? draft : undefined
+  });
+  const downstream = getDownstream(body.sectionKey);
+  const traversal = getRepairTraversalOrder(body.sectionKey);
+  let nextActions = computeNextActions(ctx, {
+    sectionKey: body.sectionKey,
+    lastOp: 'patchSection',
+    quality
+  });
+  if (hasRequiredMissingInputs(quality)) {
+    nextActions = ['askUser'];
+  }
+  return {
+    sectionKey: body.sectionKey,
+    datasourceKey: body.datasourceKey || null,
+    intent: body.intent,
+    changedPaths: collectChangedPaths(beforeValue, afterValue),
+    beforeHash: hashValue(beforeValue),
+    afterHash: hashValue(afterValue),
+    derivedSectionsAffected: downstream,
+    repairRecommended: downstream.length > 0,
+    repairHooks: traversal.hooks,
+    validationPreview: { valid: true },
+    riskHints: buildRiskHints(body.sectionKey, body.patch, downstream),
+    nextActions,
+    dryRun: body.dryRun === true,
+    quality
+  };
+}
+
+/**
+ * @param {Object} body
+ */
+function assertPatchRequest(body) {
+  if (!body.intent || typeof body.intent !== 'string' || !body.intent.trim()) {
+    const err = new Error('intent is required and must be a non-empty string');
+    err.statusCode = 400;
+    throw err;
+  }
+  if (!body.patch || typeof body.patch !== 'object') {
+    const err = new Error('patch object is required');
+    err.statusCode = 400;
+    throw err;
+  }
+  if (!body.sectionReadToken) {
+    const err = new Error('sectionReadToken is required — GET the section first');
+    err.statusCode = 400;
+    throw err;
+  }
+  if (body.mode !== 'merge' && body.mode !== 'replace') {
+    const err = new Error('mode must be merge or replace');
+    err.statusCode = 400;
+    throw err;
+  }
+}
+
+/**
+ * @param {import('./manifest-section-registry-data').SectionDefinition} def
+ * @param {Object} body
+ */
+function assertPatchAllowed(def, body) {
+  if (def.blocked) {
+    const err = new Error(`Section ${body.sectionKey} is blocked for MCP editing`);
+    err.statusCode = 403;
+    throw err;
+  }
+  if (!def.mutable) {
+    const err = new Error(`Section ${body.sectionKey} is repair-only and cannot be patched directly`);
+    err.statusCode = 403;
+    throw err;
+  }
+  if (def.target === 'datasource' && !body.datasourceKey) {
+    const err = new Error('datasourceKey is required for datasource sections');
+    err.statusCode = 400;
+    throw err;
+  }
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {'system' | 'datasource'} target
+ * @param {string} [datasourceKey]
+ */
+function loadTargetDocument(ctx, target, datasourceKey) {
+  if (target === 'system') {
+    const { systemFile, systemPath, systemDoc } = loadSystemDocument(ctx);
+    return { doc: systemDoc, filePath: systemPath, fileName: systemFile };
+  }
+  const { datasourceFile, datasourcePath, datasourceDoc } = loadDatasourceDocument(ctx, datasourceKey);
+  return { doc: datasourceDoc, filePath: datasourcePath, fileName: datasourceFile };
+}
+
+/**
+ * @param {*} beforeValue
+ * @param {*} afterValue
+ * @returns {string[]}
+ */
+function collectChangedPaths(beforeValue, afterValue) {
+  if (JSON.stringify(beforeValue) === JSON.stringify(afterValue)) {
+    return [];
+  }
+  return ['sectionRoot'];
+}
+
+/**
+ * @param {string} sectionKey
+ * @param {Object} patch
+ * @param {string[]} downstream
+ * @returns {string[]}
+ */
+function buildRiskHints(sectionKey, patch, downstream) {
+  /** @type {string[]} */
+  const hints = [];
+  if (downstream.includes('datasource.fieldMappings')) {
+    hints.push('Derived fieldMappings will change on repair');
+  }
+  if (downstream.includes('system.rolesPermissions')) {
+    hints.push('Cross-system section system.rolesPermissions may change');
+  }
+  if (sectionKey === 'datasource.openapiOperations' || sectionKey === 'datasource.capabilities') {
+    hints.push('New write capability added');
+    hints.push('RBAC repair required before test');
+  }
+  if (JSON.stringify(patch).match(/put|post|patch|delete/i)) {
+    hints.push('Approval may be required before production');
+  }
+  return [...new Set(hints)];
+}
+
+module.exports = {
+  patchManifestSection
+};

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