@aifabrix/builder 2.53.1 → 2.55.0

package/lib/commands/repair-external-run.js

@@ -18,6 +18,7 @@ const { persistChangesAndRegenerate, regenerateReadmeIfRequested, regenerateDepl
 const { runRepairSteps } = require('./repair-steps');
 const { runDatasourceRepairs } = require('./repair-datasource-run');
 const { repairSplitOrchestrationDatasources } = require('./repair-orchestration-datasource-split');
+const { mergeOrchestrationTagOperations } = require('./repair-orchestration-tag-merge');
 const { maybeRepairRbac } = require('./repair-rbac');
 const { collectCapabilityOpenApiDriftWarnings } = require('./repair-capability-openapi-warnings');
 const { maybeRunOpenApiSyncForMcp } = require('./repair-openapi-sync');
@@ -169,7 +170,62 @@ async function runDatasourceOpenApiRepairs(ws) {
     changes: ws.changes,
     backupCtx: ws.backupCtx
   });
-  return { datasourceRepairUpdated: datasourceRepairUpdated || splitResult.updated, openapiActionsPerformed };
+  const tagMerge = mergeOrchestrationTagOperations({
+    appPath: ws.appPath,
+    systemKey: ws.systemKey,
+    dryRun: ws.dryRun,
+    changes: ws.changes,
+    backupCtx: ws.backupCtx,
+    options: ws.options
+  });
+  return {
+    datasourceRepairUpdated: datasourceRepairUpdated || splitResult.updated || tagMerge.length > 0,
+    openapiActionsPerformed
+  };
+}
+
+/**
+ * @param {Object} ws
+ * @returns {Promise<Object>}
+ */
+/**
+ * @param {Object} ws
+ * @returns {Object}
+ */
+function runRepairRbacStep(ws) {
+  return maybeRepairRbac(
+    ws.appPath,
+    ws.systemFilePath,
+    ws.systemParsed,
+    ws.datasourceFiles,
+    {
+      rbac: Boolean(ws.options.rbac),
+      rbacFmt: ws.rbacFmt,
+      rbacPreset: ws.options.rbacPreset,
+      dryRun: ws.dryRun,
+      changes: ws.changes,
+      backupCtx: ws.backupCtx
+    }
+  );
+}
+
+/**
+ * @param {Object} ws
+ * @param {Object} steps
+ * @param {boolean} datasourceRepairUpdated
+ * @param {Object} rbac
+ * @returns {boolean}
+ */
+function anyRepairLocalUpdated(ws, steps, datasourceRepairUpdated, rbac) {
+  return Boolean(
+    ws.keysNormalized ||
+      steps.updated ||
+      datasourceRepairUpdated ||
+      rbac.rbacMigratedFromSystem ||
+      rbac.rbacMergeUpdated ||
+      rbac.rbacSyncedIntoSystem ||
+      rbac.rbacSecurityBound
+  );
 }
 
 /**
@@ -198,32 +254,10 @@ async function runRepairIntegrationFileSteps(ws) {
     collectCapabilityOpenApiDriftWarnings(ws.appPath, ws.datasourceFiles, ws.warnings);
   }
   const { datasourceRepairUpdated, openapiActionsPerformed } = await runDatasourceOpenApiRepairs(ws);
-  const { rbacMigratedFromSystem, rbacMergeUpdated, rbacSyncedIntoSystem, rbacSecurityBound } =
-    maybeRepairRbac(
-      ws.appPath,
-      ws.systemFilePath,
-      ws.systemParsed,
-      ws.datasourceFiles,
-      {
-        rbac: Boolean(ws.options.rbac),
-        rbacFmt: ws.rbacFmt,
-        rbacPreset: ws.options.rbacPreset,
-        dryRun: ws.dryRun,
-        changes: ws.changes,
-        backupCtx: ws.backupCtx
-      }
-    );
-  const anyLocalUpdated =
-    ws.keysNormalized ||
-    steps.updated ||
-    datasourceRepairUpdated ||
-    rbacMigratedFromSystem ||
-    rbacMergeUpdated ||
-    rbacSyncedIntoSystem ||
-    rbacSecurityBound;
+  const rbac = runRepairRbacStep(ws);
   return {
     steps,
-    anyLocalUpdated,
+    anyLocalUpdated: anyRepairLocalUpdated(ws, steps, datasourceRepairUpdated, rbac),
     changes: ws.changes,
     warnings: ws.warnings,
     openapiActionsPerformed,

package/lib/commands/repair-openapi-rest-runtime.js

@@ -0,0 +1,127 @@
+/**
+ * Infer published REST restRuntime from a Builder OpenAPI path.
+ *
+ * @fileoverview CIP item routes bind one `{systemKey}` path param as recordIdentifier
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const APP_PACKAGE_ARTIFACT_ID = 'appPackage';
+const BUILDER_API_PREFIX = /^\/api\/v1\/builder/;
+
+/**
+ * Published REST cannot carry extra `{param}` segments except as restRuntime
+ * templates bound from the catch-all item subpath (only recordIdentifier is
+ * canonical). Channel ZIP downloads use the envelope artifact id `appPackage`.
+ * @param {string} segment
+ * @returns {string}
+ */
+function normalizeRestRuntimeSegment(segment) {
+  if (segment === '{artifactId}') {
+    return APP_PACKAGE_ARTIFACT_ID;
+  }
+  if (segment === '{systemKey}') {
+    return '{installationKey}';
+  }
+  return segment;
+}
+
+/**
+ * @param {string} tail
+ * @returns {string[]}
+ */
+function splitNormalizedSegments(tail) {
+  return tail.split('/').filter(Boolean).map(normalizeRestRuntimeSegment);
+}
+
+/**
+ * @param {string} stripped
+ * @returns {{ pathKind: string, subpathSegments: string[] }|undefined}
+ */
+function restRuntimeFromSystemsPath(stripped) {
+  const match = stripped.match(/^\/systems\/\{[^}]+\}\/(.+)$/);
+  if (!match) {
+    return undefined;
+  }
+  const segs = splitNormalizedSegments(match[1]);
+  if (segs.length === 0) {
+    return undefined;
+  }
+  return { pathKind: 'itemSubresource', subpathSegments: segs };
+}
+
+/**
+ * @param {string} stripped
+ * @returns {{ pathKind: string, subpathSegments?: string[] }|undefined}
+ */
+function restRuntimeFromChannelsPath(stripped) {
+  if (/^\/channels\/\{[^}]+\}$/.test(stripped)) {
+    return { pathKind: 'item' };
+  }
+  const match = stripped.match(/^\/channels\/\{[^}]+\}\/(.+)$/);
+  if (!match) {
+    return undefined;
+  }
+  const segs = splitNormalizedSegments(match[1]);
+  if (segs.length === 0) {
+    return undefined;
+  }
+  return { pathKind: 'itemSubresource', subpathSegments: segs };
+}
+
+/**
+ * @param {string} stripped
+ * @returns {{ pathKind: string, subpathSegments: string[] }|undefined}
+ */
+function restRuntimeFromCollectionPath(stripped) {
+  if (stripped.includes('{')) {
+    return undefined;
+  }
+  const match = stripped.match(/^\/[^/]+\/(.+)$/);
+  if (!match) {
+    return undefined;
+  }
+  const segs = match[1].split('/').filter(Boolean);
+  if (segs.length === 0) {
+    return undefined;
+  }
+  return { pathKind: 'collectionSubresource', subpathSegments: segs };
+}
+
+/**
+ * @param {string} vendorPath
+ * @returns {{ pathKind: string, subpathSegments?: string[] }|undefined}
+ */
+function restRuntimeFromVendorPath(vendorPath) {
+  if (typeof vendorPath !== 'string' || !vendorPath.trim()) {
+    return undefined;
+  }
+  const stripped = vendorPath.replace(BUILDER_API_PREFIX, '');
+  return (
+    restRuntimeFromSystemsPath(stripped) ||
+    restRuntimeFromChannelsPath(stripped) ||
+    restRuntimeFromCollectionPath(stripped)
+  );
+}
+
+/**
+ * @param {Object} openapiOp
+ * @returns {Object}
+ */
+function withInferredRestRuntime(openapiOp) {
+  if (!openapiOp || typeof openapiOp !== 'object' || openapiOp.restRuntime) {
+    return openapiOp;
+  }
+  const restRuntime = restRuntimeFromVendorPath(openapiOp.path);
+  if (!restRuntime) {
+    return openapiOp;
+  }
+  return { ...openapiOp, restRuntime };
+}
+
+module.exports = {
+  restRuntimeFromVendorPath,
+  withInferredRestRuntime
+};

package/lib/commands/repair-orchestration-tag-merge.js

@@ -0,0 +1,339 @@
+/**
+ * Merge new tagged OpenAPI operations onto existing split orchestration datasources.
+ *
+ * @fileoverview --api follow-up for builder-api after OpenAPI export
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { CAPABILITIES } = require('../programmatic/capability-registry');
+const { buildOpenApiSpec } = require('../programmatic/openapi-spec');
+const { buildOperationXAfabrix } = require('../programmatic/orchestration-openapi-meta');
+const { getOperationDescription } = require('../programmatic/openapi-descriptions');
+const { isProgrammaticOrchestrationSystem } = require('./repair-openapi-export');
+const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
+const { backupIntegrationFile } = require('../utils/integration-file-backup');
+const { trackRepairWrite } = require('./repair-changed-files');
+const { withInferredRestRuntime } = require('./repair-openapi-rest-runtime');
+
+const DEFAULT_SECURITY = Object.freeze([
+  { oauth2: ['business-transformation'] },
+  { oauth2: ['aifabrix-developer'] },
+  { oauth2: ['aifabrix-platform-admin'] }
+]);
+
+/**
+ * @param {string} handlerId
+ * @returns {string}
+ */
+function manifestKeyForHandler(handlerId) {
+  return String(handlerId || '').trim().toLowerCase();
+}
+
+/**
+ * @param {Object} parsed
+ * @returns {Set<string>}
+ */
+function existingOperationIds(parsed) {
+  const ids = new Set();
+  const ops = parsed && parsed.openapi && parsed.openapi.operations;
+  if (!ops || typeof ops !== 'object') {
+    return ids;
+  }
+  for (const entry of Object.values(ops)) {
+    if (entry && typeof entry.operationId === 'string' && entry.operationId.trim()) {
+      ids.add(entry.operationId.trim());
+    }
+  }
+  return ids;
+}
+
+/**
+ * Copy oauth2 security from a sibling operation on the same datasource.
+ * @param {Object} parsed
+ * @returns {Array<{ oauth2: string[] }>}
+ */
+function securityFromParsed(parsed) {
+  const ops = parsed && parsed.openapi && parsed.openapi.operations;
+  if (ops && typeof ops === 'object') {
+    for (const entry of Object.values(ops)) {
+      if (entry && Array.isArray(entry.security) && entry.security.length > 0) {
+        return entry.security.map((row) => ({
+          oauth2: Array.isArray(row.oauth2) ? [...row.oauth2] : []
+        }));
+      }
+    }
+  }
+  return DEFAULT_SECURITY.map((row) => ({ oauth2: [...row.oauth2] }));
+}
+
+/**
+ * @param {Object} spec
+ * @param {string} handlerId
+ * @returns {{ path: string, method: string, summary: string }|null}
+ */
+function findSpecOperation(spec, handlerId) {
+  const paths = spec && spec.paths && typeof spec.paths === 'object' ? spec.paths : {};
+  for (const [route, methods] of Object.entries(paths)) {
+    if (!methods || typeof methods !== 'object') {
+      continue;
+    }
+    for (const [method, operation] of Object.entries(methods)) {
+      if (operation && operation.operationId === handlerId) {
+        return {
+          path: route,
+          method: String(method).toUpperCase(),
+          summary:
+            (typeof operation.summary === 'string' && operation.summary.trim()) ||
+            getOperationDescription(handlerId).summary
+        };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {Object} specOp
+ * @param {string} handlerId
+ * @param {Object} parsed
+ * @returns {Object}
+ */
+function buildOpenapiOperation(specOp, handlerId, parsed) {
+  return withInferredRestRuntime({
+    operationId: handlerId,
+    path: specOp.path,
+    method: specOp.method,
+    security: securityFromParsed(parsed)
+  });
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string} key
+ * @param {Object} openapiOp
+ * @returns {boolean}
+ */
+function fillMissingRestRuntime(parsed, key, openapiOp) {
+  const existing = parsed.openapi && parsed.openapi.operations && parsed.openapi.operations[key];
+  if (!existing || existing.restRuntime || !openapiOp || !openapiOp.restRuntime) {
+    return false;
+  }
+  existing.restRuntime = openapiOp.restRuntime;
+  return true;
+}
+
+/**
+ * @param {string} key
+ * @param {string} description
+ * @returns {Object}
+ */
+function buildCipPassthrough(key, description) {
+  return {
+    enabled: true,
+    description,
+    steps: [
+      { fetch: { source: 'openapi', openapiRef: key, query: {} } },
+      { map: { useFieldMappings: true, inputPath: '$' } },
+      { output: { mode: 'records' } }
+    ]
+  };
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string} key
+ * @param {string} description
+ * @returns {boolean}
+ */
+function ensureCapability(parsed, key, description) {
+  if (!Array.isArray(parsed.capabilities)) {
+    parsed.capabilities = [];
+  }
+  if (parsed.capabilities.some((row) => row && row.key === key)) {
+    return false;
+  }
+  parsed.capabilities.push({
+    key,
+    description,
+    riskLevel: 'medium',
+    approvalRequired: false
+  });
+  return true;
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string} key
+ * @param {Object} openapiOp
+ * @param {string} description
+ * @returns {string[]}
+ */
+function ensureCipScaffold(parsed) {
+  if (!parsed.openapi || typeof parsed.openapi !== 'object') {
+    parsed.openapi = {};
+  }
+  if (!parsed.openapi.operations || typeof parsed.openapi.operations !== 'object') {
+    parsed.openapi.operations = {};
+  }
+  if (!parsed.execution) {
+    parsed.execution = { engine: 'cip', cip: { version: '1.0', operations: {} } };
+  }
+  if (!parsed.execution.cip) {
+    parsed.execution.cip = { version: '1.0', operations: {} };
+  }
+  if (!parsed.execution.cip.operations) {
+    parsed.execution.cip.operations = {};
+  }
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string} key
+ * @param {Object} openapiOp
+ * @param {string} description
+ * @returns {string[]}
+ */
+function mergeOneOperation(parsed, key, openapiOp, description) {
+  const added = [];
+  ensureCipScaffold(parsed);
+  if (ensureCapability(parsed, key, description)) {
+    added.push(`capabilities.${key}`);
+  }
+  if (!parsed.openapi.operations[key]) {
+    parsed.openapi.operations[key] = withInferredRestRuntime(openapiOp);
+    added.push(`openapi.operations.${key}`);
+  } else if (fillMissingRestRuntime(parsed, key, withInferredRestRuntime(openapiOp))) {
+    added.push(`openapi.operations.${key}.restRuntime`);
+  }
+  if (!parsed.execution.cip.operations[key]) {
+    parsed.execution.cip.operations[key] = buildCipPassthrough(key, description);
+    added.push(`execution.cip.operations.${key}`);
+  }
+  return added;
+}
+
+/**
+ * @param {string} appPath
+ * @param {string} systemKey
+ * @param {string} tag
+ * @returns {string}
+ */
+function tagDatasourcePath(appPath, systemKey, tag) {
+  return path.join(appPath, `${systemKey}-datasource-${tag}.json`);
+}
+
+/**
+ * @param {Map<string, Object|null>} cache
+ * @param {string} appPath
+ * @param {string} systemKey
+ * @param {string} tag
+ * @returns {{ filePath: string, parsed: Object, dirty: boolean }|null}
+ */
+function loadTagEntry(cache, appPath, systemKey, tag) {
+  const filePath = tagDatasourcePath(appPath, systemKey, tag);
+  if (cache.has(filePath)) {
+    return cache.get(filePath);
+  }
+  if (!fs.existsSync(filePath)) {
+    cache.set(filePath, null);
+    return null;
+  }
+  const entry = { filePath, parsed: loadConfigFile(filePath), dirty: false };
+  cache.set(filePath, entry);
+  return entry;
+}
+
+/**
+ * @param {Map<string, Object|null>} cache
+ * @param {boolean} dryRun
+ * @param {Object} backupCtx
+ * @returns {void}
+ */
+function persistDirtyEntries(cache, dryRun, backupCtx) {
+  for (const entry of cache.values()) {
+    if (!entry || !entry.dirty) {
+      continue;
+    }
+    if (!dryRun) {
+      backupIntegrationFile(entry.filePath, backupCtx);
+      writeConfigFile(entry.filePath, entry.parsed);
+    }
+    trackRepairWrite(entry.filePath, { ...(backupCtx || {}), dryRun: Boolean(dryRun) });
+  }
+}
+
+/**
+ * @param {Map<string, Object|null>} cache
+ * @param {Object} spec
+ * @param {Object} capability
+ * @param {string} appPath
+ * @param {string} systemKey
+ * @returns {string[]}
+ */
+function mergeCapabilityIntoCache(cache, spec, capability, appPath, systemKey) {
+  const tag = buildOperationXAfabrix(capability).datasourceTag;
+  if (tag !== 'infra') {
+    return [];
+  }
+  const entry = loadTagEntry(cache, appPath, systemKey, tag);
+  if (!entry) {
+    return [];
+  }
+  const specOp = findSpecOperation(spec, capability.handlerId);
+  if (!specOp) {
+    return [];
+  }
+  const key = manifestKeyForHandler(capability.handlerId);
+  const openapiOp = buildOpenapiOperation(specOp, capability.handlerId, entry.parsed);
+  if (existingOperationIds(entry.parsed).has(capability.handlerId)) {
+    if (!fillMissingRestRuntime(entry.parsed, key, openapiOp)) {
+      return [];
+    }
+    entry.dirty = true;
+    return [`${path.basename(entry.filePath)}: openapi.operations.${key}.restRuntime`];
+  }
+  const added = mergeOneOperation(entry.parsed, key, openapiOp, specOp.summary);
+  if (added.length > 0) {
+    entry.dirty = true;
+  }
+  return added.map((part) => `${path.basename(entry.filePath)}: ${part}`);
+}
+
+/**
+ * Merge missing infra-tagged OpenAPI operations onto the existing infra datasource.
+ * Does not create new split files (package/branding stay on the channel tag).
+ * @param {Object} params
+ * @returns {string[]}
+ */
+function mergeOrchestrationTagOperations(params) {
+  const { appPath, systemKey, dryRun, changes, backupCtx, options } = params;
+  if (!isProgrammaticOrchestrationSystem(systemKey)) {
+    return [];
+  }
+  if (!options || !options.api) {
+    return [];
+  }
+  const spec = buildOpenApiSpec();
+  const cache = new Map();
+  const added = [];
+  for (const capability of CAPABILITIES) {
+    added.push(...mergeCapabilityIntoCache(cache, spec, capability, appPath, systemKey));
+  }
+  persistDirtyEntries(cache, dryRun, backupCtx);
+  if (Array.isArray(changes)) {
+    added.forEach((line) => changes.push(line));
+  }
+  return added;
+}
+
+module.exports = {
+  manifestKeyForHandler,
+  existingOperationIds,
+  mergeOneOperation,
+  mergeOrchestrationTagOperations
+};

package/lib/commands/repair-rbac-catalog-defaults.js

@@ -0,0 +1,96 @@
+/**
+ * Catalog Admin/Observer defaults for Connected System RBAC.
+ *
+ * @fileoverview Upload requires COM catalog keys — never invent {systemKey}-admin
+ */
+
+'use strict';
+
+const {
+  listPlatformRoles,
+  ROLE_PLATFORM_ADMIN,
+  ROLE_OBSERVER
+} = require('../programmatic/platform-rbac-catalog');
+
+const CATALOG_ADMIN_ROLE = ROLE_PLATFORM_ADMIN;
+const CATALOG_READER_ROLE = ROLE_OBSERVER;
+
+/**
+ * @returns {Array<{ name: string, value: string, description: string, groups: string[] }>}
+ */
+function catalogAdminReaderRoles() {
+  const all = listPlatformRoles();
+  const admin = all.find((r) => r.value === CATALOG_ADMIN_ROLE);
+  const reader = all.find((r) => r.value === CATALOG_READER_ROLE);
+  return [admin, reader].filter(Boolean);
+}
+
+/**
+ * @param {string[]} roleValuesList
+ * @param {string} [systemKey]
+ * @param {string|null} [fallback]
+ * @returns {string|null}
+ */
+function pickCatalogAdminRoleValue(roleValuesList, systemKey, fallback) {
+  const values = Array.isArray(roleValuesList) ? roleValuesList : [];
+  return (
+    values.find((v) => v === CATALOG_ADMIN_ROLE) ||
+    (systemKey ? values.find((v) => v === `${systemKey}-admin`) : undefined) ||
+    values.find((v) => typeof v === 'string' && v.endsWith('-admin')) ||
+    fallback ||
+    values[0] ||
+    null
+  );
+}
+
+/**
+ * @param {string[]} roleValuesList
+ * @param {string} [systemKey]
+ * @param {string|null} [fallback]
+ * @returns {string|null}
+ */
+function pickCatalogReaderRoleValue(roleValuesList, systemKey, fallback) {
+  const values = Array.isArray(roleValuesList) ? roleValuesList : [];
+  return (
+    values.find((v) => v === CATALOG_READER_ROLE) ||
+    (systemKey ? values.find((v) => v === `${systemKey}-reader`) : undefined) ||
+    values.find((v) => typeof v === 'string' && v.endsWith('-reader')) ||
+    fallback ||
+    null
+  );
+}
+
+/**
+ * Ensures catalog Admin/Reader roles if rbac.roles is empty. Mutates rbac.
+ * @param {Object} rbac
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function ensureDefaultRoles(rbac, changes) {
+  const hasRoles = Array.isArray(rbac.roles) && rbac.roles.length > 0;
+  if (hasRoles) return false;
+  const seeded = catalogAdminReaderRoles();
+  if (seeded.length < 2) return false;
+  rbac.roles = seeded;
+  const listGetPerms = (rbac.permissions || [])
+    .filter((p) => p?.name && (p.name.split(':')[1] === 'list' || p.name.split(':')[1] === 'get'))
+    .map((p) => p.name);
+  for (const p of rbac.permissions || []) {
+    if (!p.roles) p.roles = [];
+    if (p.name && listGetPerms.includes(p.name) && !p.roles.includes(CATALOG_READER_ROLE)) {
+      p.roles.push(CATALOG_READER_ROLE);
+    }
+    if (!p.roles.includes(CATALOG_ADMIN_ROLE)) p.roles.push(CATALOG_ADMIN_ROLE);
+  }
+  changes.push('Added catalog Admin and Reader roles to rbac file');
+  return true;
+}
+
+module.exports = {
+  CATALOG_ADMIN_ROLE,
+  CATALOG_READER_ROLE,
+  catalogAdminReaderRoles,
+  pickCatalogAdminRoleValue,
+  pickCatalogReaderRoleValue,
+  ensureDefaultRoles
+};