@aifabrix/builder 2.49.2 → 2.51.0

package/lib/programmatic/http-route-match.js

@@ -0,0 +1,40 @@
+/**
+ * Match builder-api route patterns to pathnames.
+ *
+ * @fileoverview /systems/:systemKey/upload style matching
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const BASE = '/api/v1/builder';
+
+/**
+ * @param {string} pattern
+ * @param {string} pathname
+ * @returns {Object|null}
+ */
+function matchRoutePattern(pattern, pathname) {
+  const fullPattern = `${BASE}${pattern}`;
+  const names = [];
+  const regexBody = fullPattern.replace(/:[A-Za-z]+/g, (token) => {
+    names.push(token.slice(1));
+    return '([^/]+)';
+  });
+  const re = new RegExp(`^${regexBody}$`);
+  const match = pathname.match(re);
+  if (!match) {
+    return null;
+  }
+  const params = {};
+  names.forEach((name, idx) => {
+    params[name] = match[idx + 1];
+  });
+  return params;
+}
+
+module.exports = {
+  BASE,
+  matchRoutePattern
+};

package/lib/programmatic/idempotency-cache.js

@@ -0,0 +1,69 @@
+/**
+ * In-memory idempotency cache for mutating routes — V1 single replica.
+ *
+ * @fileoverview Key: userId + Idempotency-Key + route + systemKey
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** @type {Map<string, { expiresAt: number, entry: Object }>} */
+const cache = new Map();
+
+/**
+ * @param {Object} params
+ * @param {string} params.userId
+ * @param {string} params.idempotencyKey
+ * @param {string} params.route
+ * @param {string} params.systemKey
+ * @returns {string}
+ */
+function buildIdempotencyCacheKey(params) {
+  return `${params.userId}:${params.route}:${params.systemKey}:${params.idempotencyKey}`;
+}
+
+/**
+ * @param {Object} params
+ * @param {string} params.userId
+ * @param {string} params.idempotencyKey
+ * @param {string} params.route
+ * @param {string} params.systemKey
+ * @returns {Object|null}
+ */
+function getIdempotentResult(params) {
+  const key = buildIdempotencyCacheKey(params);
+  const row = cache.get(key);
+  if (!row) {
+    return null;
+  }
+  if (Date.now() > row.expiresAt) {
+    cache.delete(key);
+    return null;
+  }
+  return row.entry;
+}
+
+/**
+ * @param {Object} params
+ * @param {Object} entry
+ * @param {number} [ttlMs]
+ */
+function setIdempotentResult(params, entry, ttlMs = DEFAULT_TTL_MS) {
+  const key = buildIdempotencyCacheKey(params);
+  cache.set(key, { expiresAt: Date.now() + ttlMs, entry });
+}
+
+function clearIdempotencyCache() {
+  cache.clear();
+}
+
+module.exports = {
+  getIdempotentResult,
+  setIdempotentResult,
+  clearIdempotencyCache,
+  buildIdempotencyCacheKey,
+  DEFAULT_TTL_MS
+};

package/lib/programmatic/index.js

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview builder-api public exports
+ */
+
+'use strict';
+
+const workspaceContext = require('./workspace-context');
+const runUpload = require('./run-upload');
+const runWizard = require('./run-wizard');
+const runRepair = require('./run-repair');
+const runValidate = require('./run-validate');
+const runTest = require('./run-test');
+const runCertify = require('./run-certify');
+const runLifecycle = require('./run-lifecycle');
+const workspaceOps = require('./workspace-ops');
+const capabilityRegistry = require('./capability-registry');
+const bearerAuth = require('./bearer-auth');
+const workspaceMeta = require('./workspace-meta');
+const authConfig = require('./auth-config');
+const commandOptions = require('./command-options');
+const builderApiServer = require('./builder-api-server');
+const routeHandlers = require('./route-handlers');
+const openapiSpec = require('./openapi-spec');
+const workspaceCleanup = require('./workspace-cleanup');
+const nestHttpBridge = require('./nest-http-bridge');
+const requestTimeout = require('./request-timeout');
+const enterpriseMcpClient = require('./enterprise-mcp-client');
+
+module.exports = {
+  ...workspaceContext,
+  ...runUpload,
+  ...runWizard,
+  ...runRepair,
+  ...runValidate,
+  ...runTest,
+  ...runCertify,
+  ...runLifecycle,
+  ...workspaceOps,
+  ...capabilityRegistry,
+  ...bearerAuth,
+  ...workspaceMeta,
+  ...authConfig,
+  ...commandOptions,
+  builderApiServer,
+  routeHandlers,
+  openapiSpec,
+  workspaceCleanup,
+  nestHttpBridge,
+  requestTimeout,
+  enterpriseMcpClient,
+  // Back-compat alias
+  spikeServer: builderApiServer
+};

package/lib/programmatic/integration-path-scope.js

@@ -0,0 +1,39 @@
+/**
+ * AsyncLocalStorage scope for per-request integration path resolution (builder-api).
+ *
+ * @fileoverview Programmatic integration path override for multi-user workspaces
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { AsyncLocalStorage } = require('async_hooks');
+
+const storage = new AsyncLocalStorage();
+
+/**
+ * @typedef {Object} IntegrationPathScope
+ * @property {(systemKey: string) => string} resolveIntegrationPath
+ */
+
+/**
+ * @param {IntegrationPathScope} scope
+ * @param {() => Promise<*> | *} fn
+ * @returns {Promise<*>}
+ */
+function runWithIntegrationPathScope(scope, fn) {
+  return storage.run(scope, fn);
+}
+
+/**
+ * @returns {IntegrationPathScope | undefined}
+ */
+function getIntegrationPathScope() {
+  return storage.getStore();
+}
+
+module.exports = {
+  runWithIntegrationPathScope,
+  getIntegrationPathScope
+};

package/lib/programmatic/log-redaction.js

@@ -0,0 +1,66 @@
+/**
+ * Redact sensitive values from structured logs (plan 154.0 §7).
+ *
+ * @fileoverview Never log Bearer tokens or secret field values
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const SENSITIVE_KEY_RE =
+  /^(authorization|bearer|token|secret|password|apikey|clientsecret|accesstoken|refreshtoken)$/i;
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function redactSecretString(value) {
+  if (!value || typeof value !== 'string') {
+    return '[REDACTED]';
+  }
+  if (value.length <= 8) {
+    return '[REDACTED]';
+  }
+  return `[REDACTED:${value.slice(-4)}]`;
+}
+
+/**
+ * @param {unknown} input
+ * @returns {unknown}
+ */
+function redactForLog(input) {
+  if (input === null || input === undefined) {
+    return input;
+  }
+  if (typeof input === 'string') {
+    if (/^Bearer\s+/i.test(input)) {
+      return 'Bearer [REDACTED]';
+    }
+    if (/^(kv|secure):\/\//i.test(input)) {
+      return '[REDACTED:uri]';
+    }
+    return input;
+  }
+  if (Array.isArray(input)) {
+    return input.map((item) => redactForLog(item));
+  }
+  if (typeof input !== 'object') {
+    return input;
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (SENSITIVE_KEY_RE.test(key)) {
+      out[key] = typeof value === 'string' ? redactSecretString(value) : '[REDACTED]';
+      continue;
+    }
+    out[key] = redactForLog(value);
+  }
+  return out;
+}
+
+module.exports = {
+  redactForLog,
+  redactSecretString,
+  SENSITIVE_KEY_RE
+};

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