@aifabrix/builder 2.49.2 → 2.51.0

package/lib/api/evidence.api.js

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview Evidence Fabrix v2 API (dataplane /api/v1/evidence/*).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+const BASE = '/api/v1/evidence';
+
+/**
+ * @param {*} res
+ * @returns {*}
+ */
+function unwrapBody(res) {
+  return unwrapApiData(res) ?? res;
+}
+
+/**
+ * @param {*} res
+ * @param {string} action
+ * @returns {*}
+ */
+function assertApiSuccess(res, action) {
+  if (res && res.success === false) {
+    const message = res.formattedError || res.error || `${action} failed`;
+    const err = new Error(message);
+    err.status = res.status;
+    err.errorData = res.errorData;
+    throw err;
+  }
+  return res;
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {Object} [options]
+ * @param {string} [options.controllerUrl]
+ * @returns {import('./index').ApiClient}
+ */
+function createEvidenceClient(dataplaneUrl, authConfig, options = {}) {
+  return createDataplaneApiClient(dataplaneUrl, authConfig, {
+    controllerUrl: options.controllerUrl || null
+  });
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {import('./types/evidence.types').EvidenceListParams} [params]
+ * @param {Object} [options]
+ * @returns {Promise<import('./types/evidence.types').EvidenceRow[]>}
+ */
+async function listEvidence(dataplaneUrl, authConfig, params = {}, options = {}) {
+  const client = createEvidenceClient(dataplaneUrl, authConfig, options);
+  const query = {};
+  if (params.resourceType) query.resourceType = params.resourceType;
+  if (params.roleKey) query.roleKey = params.roleKey;
+  if (params.genericOnly === true) query.genericOnly = true;
+  if (params.status) query.status = params.status;
+  const res = assertApiSuccess(
+    await client.get(BASE, { params: query }),
+    'List evidence'
+  );
+  const body = unwrapBody(res);
+  return Array.isArray(body?.data) ? body.data : [];
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} evidenceId
+ * @param {Object} [options]
+ * @returns {Promise<import('./types/evidence.types').EvidenceRow>}
+ */
+async function getEvidence(dataplaneUrl, authConfig, evidenceId, options = {}) {
+  const client = createEvidenceClient(dataplaneUrl, authConfig, options);
+  const res = assertApiSuccess(
+    await client.get(`${BASE}/${encodeURIComponent(evidenceId)}`),
+    'Get evidence'
+  );
+  return unwrapBody(res);
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {import('./types/evidence.types').EvidenceCreatePayload} payload
+ * @param {Object} [options]
+ * @returns {Promise<import('./types/evidence.types').EvidenceRow>}
+ */
+async function insertEvidence(dataplaneUrl, authConfig, payload, options = {}) {
+  const client = createEvidenceClient(dataplaneUrl, authConfig, options);
+  const res = assertApiSuccess(
+    await client.post(BASE, { body: payload }),
+    'Insert evidence'
+  );
+  return unwrapBody(res);
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} evidenceId
+ * @param {import('./types/evidence.types').EvidenceUpdatePayload} payload
+ * @param {Object} [options]
+ * @returns {Promise<import('./types/evidence.types').EvidenceRow>}
+ */
+async function updateEvidence(dataplaneUrl, authConfig, evidenceId, payload, options = {}) {
+  const client = createEvidenceClient(dataplaneUrl, authConfig, options);
+  const res = assertApiSuccess(
+    await client.patch(`${BASE}/${encodeURIComponent(evidenceId)}`, { body: payload }),
+    'Update evidence'
+  );
+  return unwrapBody(res);
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} evidenceId
+ * @param {Object} [options]
+ * @returns {Promise<void>}
+ */
+async function deleteEvidence(dataplaneUrl, authConfig, evidenceId, options = {}) {
+  const client = createEvidenceClient(dataplaneUrl, authConfig, options);
+  assertApiSuccess(
+    await client.delete(`${BASE}/${encodeURIComponent(evidenceId)}`),
+    'Delete evidence'
+  );
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {Object[]} rows
+ * @param {Object} [options]
+ * @param {string} [options.controllerUrl]
+ * @param {boolean} [options.dryRun]
+ * @returns {Promise<{ inserted: number, updated: number, dryRun: boolean, data: import('./types/evidence.types').EvidenceRow[] }>}
+ */
+async function loadEvidenceBulk(dataplaneUrl, authConfig, rows, options = {}) {
+  const client = createEvidenceClient(dataplaneUrl, authConfig, options);
+  const params = {};
+  if (options.dryRun === true) {
+    params.dryRun = true;
+  }
+  const res = assertApiSuccess(
+    await client.post(`${BASE}/load`, { body: { data: rows }, params }),
+    'Load evidence'
+  );
+  const body = unwrapBody(res);
+  return {
+    inserted: Number(body?.inserted || 0),
+    updated: Number(body?.updated || 0),
+    dryRun: Boolean(body?.dryRun),
+    data: Array.isArray(body?.data) ? body.data : []
+  };
+}
+
+module.exports = {
+  listEvidence,
+  getEvidence,
+  insertEvidence,
+  updateEvidence,
+  deleteEvidence,
+  loadEvidenceBulk
+};

package/lib/api/external-systems.api.js

@@ -116,12 +116,18 @@ async function deleteExternalSystem(dataplaneUrl, systemIdOrKey, authConfig) {
  * @param {string} dataplaneUrl - Dataplane base URL
  * @param {string} systemIdOrKey - System ID or key
  * @param {Object} authConfig - Authentication configuration
+ * @param {Object} [requestOptions] - Optional query params
+ * @param {string} [requestOptions.versionTarget] - running | latest | explicit version id
  * @returns {Promise<Object>} Config response with application schema and dataSources
  * @throws {Error} If request fails
  */
-async function getExternalSystemConfig(dataplaneUrl, systemIdOrKey, authConfig) {
+async function getExternalSystemConfig(dataplaneUrl, systemIdOrKey, authConfig, requestOptions = {}) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
-  return await client.get(`/api/v1/external/systems/${systemIdOrKey}/config`);
+  const query = {};
+  if (requestOptions.versionTarget) {
+    query.versionTarget = String(requestOptions.versionTarget);
+  }
+  return await client.get(`/api/v1/external/systems/${systemIdOrKey}/config`, { query });
 }
 
 /**

package/lib/api/pipeline.api.js

@@ -247,11 +247,15 @@ async function testDatasourceViaPipeline({ dataplaneUrl, systemKey, datasourceKe
  * @returns {Promise<Object>} API envelope `{ success, data }` where `data` is PublicationResult (uploadId, system, datasources, generateMcpContract, …)
  * @throws {Error} If upload fails
  */
+/** Multi-datasource publish often exceeds the default 30s HTTP timeout. */
+const PIPELINE_UPLOAD_TIMEOUT_MS = 300000;
+
 async function uploadApplicationViaPipeline(dataplaneUrl, authConfig, payload) {
   const body = { ...payload, status: payload.status ?? 'draft' };
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/pipeline/upload', {
-    body
+    body,
+    timeoutMs: PIPELINE_UPLOAD_TIMEOUT_MS
   });
 }
 

package/lib/api/resource-types.api.js

@@ -12,7 +12,7 @@ const BASE = '/api/v1/resource-types';
 
 /**
  * List resource types (paginated)
- * @requiresPermission {Controller} resourceTypes:read
+ * @requiresPermission {Controller} resource-types:read
  * @async
  * @function listResourceTypes
  * @param {string} controllerUrl
@@ -34,7 +34,7 @@ async function listResourceTypes(controllerUrl, authConfig, options = {}) {
 
 /**
  * Get a resource type by id or key
- * @requiresPermission {Controller} resourceTypes:read
+ * @requiresPermission {Controller} resource-types:read
  * @async
  * @function getResourceType
  * @param {string} controllerUrl
@@ -49,7 +49,7 @@ async function getResourceType(controllerUrl, authConfig, resourceTypeIdOrKey) {
 
 /**
  * Create a resource type
- * @requiresPermission {Controller} resourceTypes:create
+ * @requiresPermission {Controller} resource-types:create
  * @async
  * @function createResourceType
  * @param {string} controllerUrl
@@ -69,12 +69,13 @@ async function createResourceType(controllerUrl, authConfig, body) {
   if (body.category) payload.category = body.category;
   if (body.defaultRiskLevel) payload.defaultRiskLevel = body.defaultRiskLevel;
   if (body.status) payload.status = body.status;
+  if (body.domain) payload.domain = body.domain;
   return await client.post(BASE, { body: payload });
 }
 
 /**
  * Create-if-missing (idempotent): if a resource type already exists for the key, return success.
- * @requiresPermission {Controller} resourceTypes:read + resourceTypes:create
+ * @requiresPermission {Controller} resource-types:read + resource-types:create
  * @async
  * @function createResourceTypeIdempotent
  * @param {string} controllerUrl

package/lib/api/roles.api.js

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview Business roles API (Controller /api/v1/roles)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const BASE = '/api/v1/roles';
+
+/**
+ * List business roles (paginated)
+ * @requiresPermission {Controller} roles:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+async function listRoles(controllerUrl, authConfig, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(BASE, { params: options });
+}
+
+/**
+ * Get a business role by id or key
+ * @requiresPermission {Controller} roles:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} roleIdOrKey
+ * @returns {Promise<Object>}
+ */
+async function getRole(controllerUrl, authConfig, roleIdOrKey) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(`${BASE}/${encodeURIComponent(roleIdOrKey)}`);
+}
+
+/**
+ * @param {Object} payload
+ * @param {string} key
+ * @param {*} value
+ * @returns {void}
+ */
+function assignOptionalString(payload, key, value) {
+  if (value !== undefined && value !== null && value !== '') {
+    payload[key] = value;
+  }
+}
+
+/**
+ * @param {import('./types/roles.types').CreateBusinessRoleRequest} body
+ * @returns {Object}
+ */
+function buildCreateRoleBody(body) {
+  const payload = {
+    key: body.key,
+    domainKey: body.domainKey,
+    displayName: body.displayName
+  };
+  assignOptionalString(payload, 'description', body.description);
+  assignOptionalString(payload, 'purpose', body.purpose);
+  assignOptionalString(payload, 'businessOutcome', body.businessOutcome);
+  assignOptionalString(payload, 'source', body.source);
+  if (body.isActive !== undefined && body.isActive !== null) {
+    payload.isActive = Boolean(body.isActive);
+  }
+  if (body.metadata && typeof body.metadata === 'object') {
+    payload.metadata = body.metadata;
+  }
+  return payload;
+}
+
+/**
+ * Create a business role
+ * @requiresPermission {Controller} roles:create
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {import('./types/roles.types').CreateBusinessRoleRequest} body
+ * @returns {Promise<Object>}
+ */
+async function createRole(controllerUrl, authConfig, body) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(BASE, { body: buildCreateRoleBody(body) });
+}
+
+/**
+ * Create-if-missing (idempotent): if a role already exists for the key, return success.
+ * @requiresPermission {Controller} roles:read + roles:create
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {import('./types/roles.types').CreateBusinessRoleRequest} body
+ * @returns {Promise<{ created: boolean, response: Object }>}
+ */
+async function createRoleIdempotent(controllerUrl, authConfig, body) {
+  const key = String(body?.key || '').trim();
+  if (!key) {
+    throw new Error('Role key is required');
+  }
+  const getRes = await getRole(controllerUrl, authConfig, key);
+  if (getRes && getRes.success === true) {
+    return { created: false, response: getRes };
+  }
+  const createRes = await createRole(controllerUrl, authConfig, body);
+  if (createRes && createRes.success === true) {
+    return { created: true, response: createRes };
+  }
+  const msg = createRes?.error || createRes?.formattedError || 'Failed to create role';
+  throw new Error(msg);
+}
+
+module.exports = {
+  listRoles,
+  getRole,
+  createRole,
+  createRoleIdempotent
+};

package/lib/api/types/enterprise-knowledge.types.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Enterprise Knowledge API type definitions
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * @typedef {Object} GenerateManifestSubscription
+ * @property {string} key
+ * @property {string} [event]
+ * @property {Object<string, *>} [filter]
+ * @property {Object<string, *>} [task]
+ */
+
+/**
+ * @typedef {Object} GenerateManifestRequest
+ * @property {string} domain
+ * @property {string} ownerSystemKey
+ * @property {string} [displayName]
+ * @property {string} [description]
+ * @property {GenerateManifestSubscription[]} [subscriptions]
+ * @property {string[]} [sourceSystemKeys]
+ * @property {string} [version]
+ */
+
+/**
+ * @typedef {Object} GenerateManifestFinding
+ * @property {string} code
+ * @property {string} severity
+ * @property {string} message
+ * @property {Object<string, *>} [context]
+ */
+
+/**
+ * @typedef {Object} GenerateManifestResponse
+ * @property {boolean} previewOnly
+ * @property {string} ownerSystemKey
+ * @property {Object<string, *>} externalSystem
+ * @property {Object<string, *>[]} externalDataSources
+ * @property {string} version
+ * @property {GenerateManifestFinding[]} compilerFindings
+ * @property {GenerateManifestFinding[]} trustFindings
+ * @property {string} message
+ */
+
+module.exports = {};

package/lib/api/types/evidence-kinds.types.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Evidence kind API type definitions (Controller /api/v1/evidence-kinds)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * Create evidence kind request body (API shape uses domainKey)
+ * @typedef {Object} CreateEvidenceKindRequest
+ * @property {string} key - Catalog key (lowercase, digits, underscores)
+ * @property {string} domainKey - Enterprise domain key
+ * @property {string} displayName - Human-readable name
+ * @property {string} purpose - Purpose (required by Controller)
+ * @property {string} [description] - Optional description
+ * @property {string} [expectedUse] - Expected use guidance
+ * @property {string} [defaultSeverity] - low | medium | high | critical
+ * @property {boolean} [requiresApproval] - Approval flag
+ * @property {boolean} [isActive] - Active flag
+ * @property {number} [sortOrder] - Sort order
+ * @property {string} [source] - Provenance source
+ * @property {Object} [metadata] - Extensions
+ */
+
+/**
+ * Evidence kind record
+ * @typedef {Object} EvidenceKindRecord
+ * @property {string} id - Controller id
+ * @property {string} key - Catalog key
+ * @property {string} domainKey - Enterprise domain key
+ * @property {string} displayName - Display name
+ * @property {string} purpose - Purpose
+ * @property {string} [description] - Description
+ * @property {string} [expectedUse] - Expected use
+ * @property {string} [defaultSeverity] - Default severity
+ * @property {boolean} requiresApproval - Approval flag
+ * @property {boolean} isActive - Active flag
+ * @property {number} sortOrder - Sort order
+ * @property {string} [source] - Source
+ * @property {Object} [metadata] - Metadata
+ */
+
+module.exports = {};

package/lib/api/types/evidence.types.js

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview JSDoc types for Evidence Fabrix dataplane API.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * @typedef {'active' | 'disabled'} EvidenceStatus
+ */
+
+/**
+ * @typedef {'self' | 'role' | 'roleExceptSelf'} EvidenceApprover
+ */
+
+/**
+ * @typedef {Object} EvidenceApprovalPolicy
+ * @property {boolean} required
+ * @property {EvidenceApprover} approver
+ * @property {string|null} [roleKey]
+ */
+
+/**
+ * @typedef {Object} EvidenceRow
+ * @property {string} id
+ * @property {string} resourceType
+ * @property {string|null} [roleKey]
+ * @property {string} title
+ * @property {string|null} [description]
+ * @property {string} when
+ * @property {string} expectedBehavior
+ * @property {number} order
+ * @property {EvidenceStatus} status
+ * @property {number|null} [generationConfidence]
+ * @property {string|null} [suggestionExplanation]
+ * @property {EvidenceApprovalPolicy} approval
+ * @property {'human' | 'assistant'} createdByType
+ * @property {string} createdById
+ * @property {string} createdAt
+ * @property {string} updatedAt
+ */
+
+/**
+ * @typedef {Object} EvidenceCreatePayload
+ * @property {string} resourceType
+ * @property {string|null} [roleKey]
+ * @property {string} title
+ * @property {string|null} [description]
+ * @property {string} when
+ * @property {string} expectedBehavior
+ * @property {number|null} [order]
+ * @property {EvidenceStatus} [status]
+ * @property {EvidenceApprovalPolicy} [approval]
+ */
+
+/**
+ * @typedef {Partial<EvidenceCreatePayload>} EvidenceUpdatePayload
+ */
+
+/**
+ * @typedef {Object} EvidenceListParams
+ * @property {string} [resourceType]
+ * @property {string} [roleKey]
+ * @property {boolean} [genericOnly]
+ * @property {EvidenceStatus} [status]
+ */
+
+module.exports = {};

package/lib/api/types/resource-types.types.js

@@ -28,6 +28,7 @@
  * @property {ResourceTypeCategory} [category] - Catalog category
  * @property {ResourceTypeRiskLevel} [defaultRiskLevel] - Default risk level
  * @property {ResourceTypeStatus} [status] - Lifecycle status
+ * @property {string} domain - Enterprise domain (static dimension catalog)
  */
 
 /**
@@ -40,6 +41,7 @@
  * @property {ResourceTypeCategory} category - Category
  * @property {ResourceTypeRiskLevel} defaultRiskLevel - Default risk
  * @property {ResourceTypeStatus} status - Status
+ * @property {string} domain - Enterprise domain
  */
 
 module.exports = {};

package/lib/api/types/roles.types.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Business role API type definitions (Controller /api/v1/roles)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * Create business role request body (API shape uses domainKey)
+ * @typedef {Object} CreateBusinessRoleRequest
+ * @property {string} key - Catalog key (lowercase, hyphens)
+ * @property {string} domainKey - Enterprise domain key
+ * @property {string} displayName - Human-readable name
+ * @property {string} [description] - Optional description
+ * @property {string} [purpose] - Role purpose
+ * @property {string} [businessOutcome] - Business outcome
+ * @property {boolean} [isActive] - Active flag
+ * @property {string} [source] - Provenance source
+ * @property {Object} [metadata] - Compiler fields and extensions
+ */
+
+/**
+ * Business role record
+ * @typedef {Object} BusinessRoleRecord
+ * @property {string} id - Controller id
+ * @property {string} key - Catalog key
+ * @property {string} domainKey - Enterprise domain key
+ * @property {string} displayName - Display name
+ * @property {string} [description] - Description
+ * @property {string} [purpose] - Purpose
+ * @property {string} [businessOutcome] - Business outcome
+ * @property {boolean} isActive - Active flag
+ * @property {string} [source] - Source
+ * @property {Object} [metadata] - Metadata
+ */
+
+module.exports = {};

package/lib/app/certification-verify-rows.js

@@ -16,7 +16,7 @@ const { getActiveIntegrationCertificate, verifyIntegrationCertificate } = requir
 function certificateIdString(id) {
   if (id === undefined || id === null) return null;
   if (typeof id === 'string') return id.trim() || null;
-  if (typeof id === 'object' && id !== null && typeof id.id === 'string') return id.id.trim() || null;
+  if (typeof id === 'object' && typeof id.id === 'string') return id.id.trim() || null;
   return null;
 }
 

package/lib/app/controller-application-filter.js

@@ -0,0 +1,36 @@
+/**
+ * Distinguish controller pipeline applications from connected-system (external) registry rows.
+ *
+ * @fileoverview Filter helpers for aifabrix app list vs connected systems list
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * @param {Object} app - Controller application row
+ * @returns {boolean} True when the row represents a connected system, not a runnable app
+ */
+function isControllerExternalApplication(app) {
+  if (!app || typeof app !== 'object') return false;
+  const cfg = app.configuration && typeof app.configuration === 'object' ? app.configuration : {};
+  const appType = app.type ?? cfg.type;
+  return String(appType || '').toLowerCase() === 'external';
+}
+
+/**
+ * @param {Array<Object>} applications - Controller application rows
+ * @returns {{ applications: Array<Object>, excludedCount: number }}
+ */
+function filterControllerApplications(applications) {
+  const list = Array.isArray(applications) ? applications : [];
+  const excludedCount = list.filter(isControllerExternalApplication).length;
+  return {
+    applications: list.filter((app) => !isControllerExternalApplication(app)),
+    excludedCount
+  };
+}
+
+module.exports = {
+  isControllerExternalApplication,
+  filterControllerApplications
+};

package/lib/app/deploy.js

@@ -255,7 +255,7 @@ function displayDeploymentResults(result) {
  * @returns {Promise<Object|null>} Deployment result if external, null otherwise
  */
 async function handleExternalDeployment(appName, options) {
-  const { isExternal } = await detectAppType(appName);
+  const { isExternal } = await detectAppType(appName, options);
   if (isExternal) {
     const externalDeploy = require('../external-system/deploy');
     await externalDeploy.deployExternalSystem(appName, options);