@aifabrix/builder 2.49.2 → 2.51.0

package/lib/programmatic/orchestration-openapi-meta.js

@@ -0,0 +1,159 @@
+/**
+ * Orchestration OpenAPI governance metadata (plan 154.7).
+ *
+ * Maps builder-api OpenAPI tags → catalog resourceType, permission class, and
+ * per-operation x-aifabrix extensions for dataplane wizard / CIP manifest generation.
+ *
+ * @fileoverview Tag catalog and x-aifabrix operation extensions
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getOperationDescription } = require('./openapi-descriptions');
+const { CAPABILITIES } = require('./capability-registry');
+
+/** @type {Readonly<Record<string, { resourceType: string, permissionClass: string, displayName: string }>>} */
+/** Catalog keys only — must exist in baseline-resourcetypes.json (active on dataplane). */
+const ORCHESTRATION_TAG_CATALOG = Object.freeze({
+  workspace: {
+    resourceType: 'workspace',
+    permissionClass: 'workspace',
+    displayName: 'Workspace'
+  },
+  build: {
+    resourceType: 'template',
+    permissionClass: 'plan',
+    displayName: 'Build'
+  },
+  manifest: {
+    resourceType: 'policy',
+    permissionClass: 'workspace',
+    displayName: 'Manifest'
+  },
+  validate: {
+    resourceType: 'document',
+    permissionClass: 'validate',
+    displayName: 'Validate'
+  },
+  test: {
+    resourceType: 'task',
+    permissionClass: 'test',
+    displayName: 'Test'
+  },
+  certify: {
+    resourceType: 'approval',
+    permissionClass: 'certify',
+    displayName: 'Certify'
+  },
+  apply: {
+    resourceType: 'project',
+    permissionClass: 'apply',
+    displayName: 'Apply'
+  },
+  template: {
+    resourceType: 'product',
+    permissionClass: 'template',
+    displayName: 'Template'
+  },
+  repository: {
+    resourceType: 'repository',
+    permissionClass: 'repository',
+    displayName: 'Repository'
+  },
+  infra: {
+    resourceType: 'channel',
+    permissionClass: 'infra',
+    displayName: 'Infrastructure'
+  }
+});
+
+/**
+ * @param {string} tag
+ * @returns {{ resourceType: string, permissionClass: string, displayName: string }}
+ */
+function resolveTagCatalogEntry(tag) {
+  const key = String(tag || '').trim().toLowerCase();
+  return (
+    ORCHESTRATION_TAG_CATALOG[key] || {
+      resourceType: 'document',
+      permissionClass: 'read',
+      displayName: key || 'operations'
+    }
+  );
+}
+
+/**
+ * @param {{ handlerId: string, operationType: string, mutating: boolean }} capability
+ * @returns {{ datasourceTag: string, resourceType: string, operationType: string, permissionClass: string, mutating: boolean }}
+ */
+function buildOperationXAfabrix(capability) {
+  const meta = getOperationDescription(capability.handlerId);
+  const primaryTag = Array.isArray(meta.tags) && meta.tags.length > 0 ? meta.tags[0] : 'builder';
+  const catalog = resolveTagCatalogEntry(primaryTag);
+  return {
+    datasourceTag: primaryTag,
+    resourceType: catalog.resourceType,
+    operationType: capability.operationType,
+    permissionClass: catalog.permissionClass,
+    mutating: capability.mutating === true
+  };
+}
+
+/**
+ * @param {string} handlerId
+ * @returns {string}
+ */
+function handlerDatasourceTag(handlerId) {
+  const meta = getOperationDescription(handlerId);
+  if (Array.isArray(meta.tags) && meta.tags.length > 0) {
+    return meta.tags[0];
+  }
+  return 'builder';
+}
+
+/**
+ * Group capability handlerIds by OpenAPI datasource tag.
+ *
+ * @returns {ReadonlyMap<string, string[]>}
+ */
+function groupHandlerIdsByDatasourceTag() {
+  /** @type {Map<string, string[]>} */
+  const grouped = new Map();
+  for (const cap of CAPABILITIES) {
+    const tag = handlerDatasourceTag(cap.handlerId);
+    const list = grouped.get(tag) || [];
+    list.push(cap.handlerId);
+    grouped.set(tag, list);
+  }
+  return grouped;
+}
+
+/**
+ * @returns {ReadonlyArray<{ tag: string, resourceType: string, permissionClass: string, displayName: string, operationCount: number }>}
+ */
+function listOrchestrationDatasourceTags() {
+  const grouped = groupHandlerIdsByDatasourceTag();
+  return [...grouped.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([tag, handlerIds]) => {
+      const catalog = resolveTagCatalogEntry(tag);
+      return {
+        tag,
+        resourceType: catalog.resourceType,
+        permissionClass: catalog.permissionClass,
+        displayName: catalog.displayName,
+        operationCount: handlerIds.length
+      };
+    });
+}
+
+module.exports = {
+  ORCHESTRATION_TAG_CATALOG,
+  resolveTagCatalogEntry,
+  buildOperationXAfabrix,
+  handlerDatasourceTag,
+  groupHandlerIdsByDatasourceTag,
+  listOrchestrationDatasourceTags
+};

package/lib/programmatic/platform-rbac-catalog.js

@@ -0,0 +1,90 @@
+/**
+ * Platform RBAC role catalog — mirrors dataplane builder/dataplane/rbac.yaml roles block.
+ *
+ * @fileoverview SSOT for facade/orchestration integrations using platform roles (plan 154.7)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** @type {ReadonlyArray<{ name: string, value: string, description: string, groups: string[] }>} */
+const PLATFORM_ROLES = Object.freeze([
+  {
+    name: 'AI Fabrix Platform Admin',
+    value: 'aifabrix-platform-admin',
+    description: 'Full platform infrastructure management and enterprise controller access',
+    groups: ['AI-Fabrix-Platform-Admins']
+  },
+  {
+    name: 'AI Fabrix Security Admin',
+    value: 'aifabrix-security-admin',
+    description: 'Security and compliance management for enterprise controller',
+    groups: ['AI-Fabrix-Security-Admins']
+  },
+  {
+    name: 'AI Fabrix Deployment Admin',
+    value: 'aifabrix-deployment-admin',
+    description: 'Application deployment orchestration and environment management',
+    groups: ['AI-Fabrix-Deployment-Admins']
+  },
+  {
+    name: 'AI Fabrix Compliance Admin',
+    value: 'aifabrix-compliance-admin',
+    description: 'ISO 27001 compliance monitoring and audit management',
+    groups: ['AI-Fabrix-Compliance-Admins']
+  },
+  {
+    name: 'AI Fabrix Developer',
+    value: 'aifabrix-developer',
+    description: 'Developer access to deploy applications via CI pipelines',
+    groups: ['AI-Fabrix-Developers']
+  },
+  {
+    name: 'AI Fabrix Observer',
+    value: 'aifabrix-observer',
+    description: 'Read-only access to monitoring, logs, and compliance reports',
+    groups: ['AI-Fabrix-Observers']
+  },
+  {
+    name: 'AI Fabrix AI Trust Operator',
+    value: 'aifabrix-ai-trust-operator',
+    description: 'Run AI Trust access evaluation and explain visibility for governed users',
+    groups: ['AI-Fabrix-AI-Trust-Operators']
+  },
+  {
+    name: 'AI Fabrix External System Discoverer',
+    value: 'aifabrix-external-system-discoverer',
+    description: 'Discover business context for external systems via REST and MCP',
+    groups: ['AI-Fabrix-External-System-Discoverers']
+  }
+]);
+
+const PLATFORM_ROLE_VALUES = Object.freeze(PLATFORM_ROLES.map((r) => r.value));
+
+/**
+ * @returns {Array<{ name: string, value: string, description: string, groups: string[] }>}
+ */
+function listPlatformRoles() {
+  return PLATFORM_ROLES.map((r) => ({
+    name: r.name,
+    value: r.value,
+    description: r.description,
+    groups: [...r.groups]
+  }));
+}
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isPlatformRoleValue(value) {
+  return PLATFORM_ROLE_VALUES.includes(value);
+}
+
+module.exports = {
+  PLATFORM_ROLES,
+  PLATFORM_ROLE_VALUES,
+  listPlatformRoles,
+  isPlatformRoleValue
+};

package/lib/programmatic/request-timeout.js

@@ -0,0 +1,53 @@
+/**
+ * Per-route request timeouts (plan 154.0 §3.2).
+ *
+ * @fileoverview Returns 408 when handler exceeds MAX_*_TIMEOUT_MS
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {string} handlerId
+ * @returns {number}
+ */
+function getTimeoutMsForHandler(handlerId) {
+  if (handlerId === 'runUpload') {
+    return Number(process.env.MAX_UPLOAD_TIMEOUT_MS || 300000);
+  }
+  if (handlerId === 'runTest') {
+    return Number(process.env.MAX_TEST_E2E_TIMEOUT_MS || 120000);
+  }
+  if (handlerId === 'runCertifyPillar') {
+    return Number(process.env.MAX_CERTIFY_TIMEOUT_MS || 120000);
+  }
+  return Number(process.env.MAX_REQUEST_TIMEOUT_MS || 120000);
+}
+
+/**
+ * @param {string} handlerId
+ * @param {() => Promise<*>} fn
+ * @returns {Promise<*>}
+ */
+async function withRequestTimeout(handlerId, fn) {
+  const ms = getTimeoutMsForHandler(handlerId);
+  let timeoutId;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      const err = new Error(`Request exceeded ${ms}ms timeout`);
+      err.statusCode = 408;
+      reject(err);
+    }, ms);
+  });
+  try {
+    return await Promise.race([fn(), timeoutPromise]);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+module.exports = {
+  getTimeoutMsForHandler,
+  withRequestTimeout
+};

package/lib/programmatic/route-handler-map.js

@@ -0,0 +1,143 @@
+/**
+ * Individual route handler implementations for builder-api dispatch map.
+ *
+ * @fileoverview Keeps dispatchHandler under max-lines-per-function
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { buildContext } = require('./route-handlers-context');
+const { listSystems, createSystem, getSystemManifest, deleteSystem } = require('./workspace-ops');
+const { runWizard } = require('./run-wizard');
+const { runRepair } = require('./run-repair');
+const { runValidate } = require('./run-validate');
+const { runPreviewUpload, runUpload } = require('./run-upload');
+const { runTest } = require('./run-test');
+const { runCertifyPillar } = require('./run-certify');
+const { getLifecycleReport } = require('./run-lifecycle');
+const {
+  materializeTemplate,
+  getWorkspaceStatus,
+  runWorkspaceDiff,
+  resetWorkspaceFromTemplate
+} = require('./run-template-workspace');
+const {
+  runRepositorySync,
+  runRepositoryCreateReview,
+  getRepositoryStatus,
+  runRepositoryDispatchPipeline
+} = require('./run-repository-emcp');
+const { getManifestSection, listManifestSections } = require('./manifest-get-section');
+const { patchManifestSection } = require('./manifest-patch-section');
+const { runManifestRepair } = require('./manifest-repair');
+
+/** @type {Record<string, Function>} */
+const HANDLER_MAP = {
+  listSystems: (_params, auth) => listSystems(buildContext(auth, '_meta')),
+  createSystem: (_params, auth, body) => {
+    const key = body.systemKey;
+    if (!key || typeof key !== 'string') {
+      throw new Error('systemKey is required in request body');
+    }
+    return createSystem(buildContext(auth, key), key);
+  },
+  getSystemManifest: (params, auth) => getSystemManifest(buildContext(auth, params.systemKey)),
+  deleteSystem: (params, auth) => deleteSystem(buildContext(auth, params.systemKey)),
+  runWizard: (params, auth, body, query) =>
+    runWizard(buildContext(auth, params.systemKey), body, {
+      debug: query.debug === 'true' || body.debug === true
+    }),
+  runRepair: (params, auth, body, query) =>
+    runRepair(buildContext(auth, params.systemKey), {
+      dryRun: query.dryRun === 'true' || body.dryRun === true,
+      auth: body.auth,
+      rbac: body.rbac === true,
+      rbacPreset: body.rbacPreset,
+      expose: body.expose === true,
+      sync: body.sync === true,
+      test: body.test === true,
+      api: body.api === true,
+      operations: body.operations === true || body.rbac === true
+    }),
+  listManifestSections: (params, auth) => listManifestSections(buildContext(auth, params.systemKey)),
+  getManifestSection: (params, auth) =>
+    getManifestSection(buildContext(auth, params.systemKey), { sectionKey: params.sectionKey }),
+  patchManifestSection: (params, auth, body) =>
+    patchManifestSection(buildContext(auth, params.systemKey), {
+      sectionKey: params.sectionKey,
+      intent: body.intent,
+      patch: body.patch,
+      mode: body.mode,
+      sectionReadToken: body.sectionReadToken,
+      dryRun: body.dryRun === true
+    }),
+  getDatasourceManifestSection: (params, auth) =>
+    getManifestSection(buildContext(auth, params.systemKey), {
+      sectionKey: params.sectionKey,
+      datasourceKey: params.datasourceKey
+    }),
+  patchDatasourceManifestSection: (params, auth, body) =>
+    patchManifestSection(buildContext(auth, params.systemKey), {
+      sectionKey: params.sectionKey,
+      datasourceKey: params.datasourceKey,
+      intent: body.intent,
+      patch: body.patch,
+      mode: body.mode,
+      sectionReadToken: body.sectionReadToken,
+      dryRun: body.dryRun === true
+    }),
+  runManifestRepair: (params, auth, body, query) =>
+    runManifestRepair(buildContext(auth, params.systemKey), {
+      hooks: body.hooks,
+      sectionKey: body.sectionKey,
+      datasourceKey: body.datasourceKey,
+      dryRun: query.dryRun === 'true' || body.dryRun === true,
+      auth: body.auth
+    }),
+  runValidate: (params, auth, body, query) =>
+    runValidate(buildContext(auth, params.systemKey), {
+      pipelineValidate: query.pipelineValidate === 'true' || body.pipelineValidate === true
+    }),
+  runPreviewUpload: (params, auth, body) =>
+    runPreviewUpload(buildContext(auth, params.systemKey), { force: body.force === true }),
+  runUpload: (params, auth, body) =>
+    runUpload(buildContext(auth, params.systemKey), {
+      force: body.force === true,
+      probe: body.probe === true,
+      minimal: true
+    }),
+  runTest: (params, auth, body, query) =>
+    runTest(buildContext(auth, params.systemKey), {
+      runType: body.runType || query.runType || 'integration',
+      noPublish: body.noPublish === true
+    }),
+  runCertifyPillar: (params, auth, body) =>
+    runCertifyPillar(buildContext(auth, params.systemKey), params.pillar, {
+      noPublish: body.noPublish === true,
+      pack: body.pack,
+      body: body.lifecycleBody
+    }),
+  getLifecycleReport: (params, auth, _body, query) =>
+    getLifecycleReport(buildContext(auth, params.systemKey), {
+      details: query.details === 'true',
+      summary: query.summary === 'true'
+    }),
+  materializeTemplate: (params, auth, body) =>
+    materializeTemplate(buildContext(auth, params.systemKey), body),
+  getWorkspaceStatus: (params, auth) => getWorkspaceStatus(buildContext(auth, params.systemKey)),
+  runWorkspaceDiff: (params, auth, body) => runWorkspaceDiff(buildContext(auth, params.systemKey), body),
+  resetWorkspaceFromTemplate: (params, auth, body) =>
+    resetWorkspaceFromTemplate(buildContext(auth, params.systemKey), body),
+  runRepositorySync: (params, auth, body) => runRepositorySync(buildContext(auth, params.systemKey), body),
+  runRepositoryCreateReview: (params, auth, body) =>
+    runRepositoryCreateReview(buildContext(auth, params.systemKey), body),
+  getRepositoryStatus: (params, auth) => getRepositoryStatus(buildContext(auth, params.systemKey)),
+  runRepositoryDispatchPipeline: (params, auth, body) =>
+    runRepositoryDispatchPipeline(buildContext(auth, params.systemKey), body),
+  health: () => ({ status: 'ok' }),
+  ready: () => ({ status: 'ready', dataplaneUrl: process.env.DATAPLANE_URL || null })
+};
+
+module.exports = { HANDLER_MAP };

package/lib/programmatic/route-handlers-context.js

@@ -0,0 +1,29 @@
+/**
+ * WorkspaceContext factory for route handlers.
+ *
+ * @fileoverview Shared buildContext helper
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createWorkspaceContext } = require('./workspace-context');
+
+/**
+ * @param {Object} auth
+ * @param {string} systemKey
+ * @returns {import('./workspace-context').WorkspaceContext}
+ */
+function buildContext(auth, systemKey) {
+  return createWorkspaceContext({
+    userId: auth.userId,
+    systemKey,
+    bearerToken: auth.bearerToken,
+    dataplaneUrl: process.env.DATAPLANE_URL,
+    controllerUrl: process.env.MISO_CONTROLLER_URL || process.env.CONTROLLER_URL,
+    environment: process.env.DEFAULT_ENVIRONMENT
+  });
+}
+
+module.exports = { buildContext };

package/lib/programmatic/route-handlers.js

@@ -0,0 +1,33 @@
+/**
+ * Builder-api route handler dispatch by capability handlerId.
+ *
+ * @fileoverview Maps registry handlers to lib/programmatic operations
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { HANDLER_MAP } = require('./route-handler-map');
+
+/**
+ * @param {string} handlerId
+ * @param {Object} params
+ * @param {Object} auth
+ * @param {Object} body
+ * @param {Object} query
+ * @returns {Promise<Object>}
+ */
+async function dispatchHandler(handlerId, params, auth, body, query) {
+  const handler = HANDLER_MAP[handlerId];
+  if (!handler) {
+    const err = new Error('Handler not implemented');
+    err.statusCode = 404;
+    throw err;
+  }
+  return handler(params, auth, body, query);
+}
+
+module.exports = {
+  dispatchHandler
+};

package/lib/programmatic/run-certify.js

@@ -0,0 +1,57 @@
+/**
+ * Programmatic certify pillar wrappers.
+ *
+ * @fileoverview POST /certify/*
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { runVerifyOperationsForExternalSystem } = require('../commands/verify-operations-external');
+const { runVerifyTrustForExternalSystem } = require('../commands/verify-trust-external');
+const { runVerifyGovernanceForExternalSystem } = require('../commands/verify-governance-external');
+const { runSystemLifecycle } = require('../api/lifecycle.api');
+const { runWithWorkspaceContext } = require('./workspace-context');
+const { mergeProgrammaticOptions } = require('./command-options');
+const { touchWorkspaceMeta } = require('./workspace-meta');
+
+const PILLARS = new Set(['operations', 'trust', 'governance', 'lifecycle-run']);
+
+/**
+ * @param {string} pillar
+ */
+function assertPillar(pillar) {
+  if (!PILLARS.has(pillar)) {
+    throw new Error(`Unknown certify pillar: ${pillar}`);
+  }
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {string} pillar
+ * @param {Object} [options]
+ */
+async function runCertifyPillar(ctx, pillar, options = {}) {
+  assertPillar(pillar);
+  const merged = mergeProgrammaticOptions(ctx, {
+    ...options,
+    noPublish: options.noPublish === true
+  });
+  return runWithWorkspaceContext(ctx, async() => {
+    let result;
+    if (pillar === 'operations') {
+      result = await runVerifyOperationsForExternalSystem(ctx.systemKey, merged);
+    } else if (pillar === 'trust') {
+      result = await runVerifyTrustForExternalSystem(ctx.systemKey, merged);
+    } else if (pillar === 'governance') {
+      result = await runVerifyGovernanceForExternalSystem(ctx.systemKey, merged);
+    } else {
+      result = await runSystemLifecycle(merged.dataplaneUrl, merged.authConfig, ctx.systemKey, options.body || {});
+    }
+    touchWorkspaceMeta(ctx, { lastOperation: `certify:${pillar}` });
+    return result;
+  });
+}
+
+module.exports = { runCertifyPillar, PILLARS };

package/lib/programmatic/run-enterprise-mcp.js

@@ -0,0 +1,32 @@
+/**
+ * Shared Enterprise MCP route runners for builder-api (154.1).
+ *
+ * @fileoverview Workspace context + metadata touch wrapper
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { runWithWorkspaceContext } = require('./workspace-context');
+const { touchWorkspaceMeta } = require('./workspace-meta');
+const { invokeEnterpriseMcpCapability } = require('./enterprise-mcp-client');
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {string} capabilityKey
+ * @param {Object} [args]
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+async function runEnterpriseMcpCapability(ctx, capabilityKey, args = {}, options = {}) {
+  return runWithWorkspaceContext(ctx, async() => {
+    const result = await invokeEnterpriseMcpCapability(ctx, capabilityKey, args, options);
+    touchWorkspaceMeta(ctx, { lastOperation: capabilityKey });
+    return { capabilityKey, result };
+  });
+}
+
+module.exports = {
+  runEnterpriseMcpCapability
+};

package/lib/programmatic/run-lifecycle.js

@@ -0,0 +1,29 @@
+/**
+ * Programmatic lifecycle report wrapper.
+ *
+ * @fileoverview GET /lifecycle
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getSystemLifecycleReport } = require('../api/lifecycle.api');
+const { runWithWorkspaceContext } = require('./workspace-context');
+const { mergeProgrammaticOptions } = require('./command-options');
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [options]
+ */
+async function getLifecycleReport(ctx, options = {}) {
+  const merged = mergeProgrammaticOptions(ctx, options);
+  return runWithWorkspaceContext(ctx, async() =>
+    getSystemLifecycleReport(merged.dataplaneUrl, merged.authConfig, ctx.systemKey, {
+      details: options.details === true,
+      summary: options.summary === true
+    })
+  );
+}
+
+module.exports = { getLifecycleReport };

package/lib/programmatic/run-repair.js

@@ -0,0 +1,41 @@
+/**
+ * Programmatic repair wrapper.
+ *
+ * @fileoverview POST /repair → repairExternalIntegration
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { repairExternalIntegration } = require('../commands/repair');
+const { runWithWorkspaceContext, WORKSPACE_INTEGRATION_FORMAT } = require('./workspace-context');
+const { touchWorkspaceMeta } = require('./workspace-meta');
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [options]
+ */
+async function runRepair(ctx, options = {}) {
+  return runWithWorkspaceContext(ctx, async() => {
+    const result = await repairExternalIntegration(ctx.systemKey, {
+      dryRun: options.dryRun === true,
+      auth: options.auth,
+      rbac: options.rbac === true,
+      expose: options.expose === true,
+      sync: options.sync === true,
+      test: options.test === true,
+      api: options.api === true,
+      operations: options.operations === true || options.rbac === true,
+      splitDatasources: options.splitDatasources === true,
+      format: WORKSPACE_INTEGRATION_FORMAT,
+      rbacPreset: options.rbacPreset
+    });
+    if (options.dryRun !== true) {
+      touchWorkspaceMeta(ctx, { lastOperation: 'repair' });
+    }
+    return result;
+  });
+}
+
+module.exports = { runRepair };