@aifabrix/builder 2.50.0 → 2.51.0

package/lib/programmatic/openapi-schema-helpers.js

@@ -41,7 +41,15 @@ function stringArraySchema() {
  * @returns {Object}
  */
 function buildSuccessEnvelopeSchema(dataSchemaName) {
-  return frozenObject(
+  const dataExamples = {
+    HealthData: { status: 'ok' },
+    ReadyData: { status: 'ready', dataplaneUrl: 'http://localhost:3601' },
+    ListSystemsData: { systems: [] },
+    EmptyResultData: {},
+    WorkspaceStatusData: { status: 'ready' },
+    RepositoryStatusData: { status: 'ready' }
+  };
+  const schema = frozenObject(
     {
       success: { type: 'boolean', enum: [true] },
       data: schemaRef(dataSchemaName),
@@ -50,6 +58,13 @@ function buildSuccessEnvelopeSchema(dataSchemaName) {
     },
     ['success', 'data', 'correlationId']
   );
+  schema.example = {
+    success: true,
+    data: dataExamples[dataSchemaName] || {},
+    correlationId: '00000000-0000-4000-8000-000000000001',
+    requestId: '00000000-0000-4000-8000-000000000002'
+  };
+  return schema;
 }
 
 /**

package/lib/programmatic/openapi-spec.js

@@ -47,7 +47,7 @@ function problemResponseContent(description) {
     description,
     content: {
       'application/problem+json': {
-        schema: { $ref: '#/components/schemas/ProblemDetails' }
+        schema: { $ref: '#/components/schemas/ProblemDetail' }
       }
     }
   };

package/lib/programmatic/run-repository-emcp.js

@@ -9,8 +9,8 @@
 'use strict';
 
 const { runEnterpriseMcpCapability } = require('./run-enterprise-mcp');
-const { invokeEnterpriseMcpCapability } = require('./enterprise-mcp-client');
 const { runWithWorkspaceContext } = require('./workspace-context');
+const { getSystemManifest } = require('./workspace-ops');
 
 /**
  * @param {import('./workspace-context').WorkspaceContext} ctx
@@ -33,8 +33,16 @@ async function runRepositoryCreateReview(ctx, body = {}) {
  */
 async function getRepositoryStatus(ctx) {
   return runWithWorkspaceContext(ctx, async() => {
-    const result = await invokeEnterpriseMcpCapability(ctx, 'repository.status', {});
-    return { capabilityKey: 'repository.status', result };
+    // Local-first status: COM currently composes enterprise-repository from
+    // builder-api-repository, so EMCP → this route deadlocks.
+    // Mutating repository.* still go through EMCP (sync/review/dispatch).
+    const local = getSystemManifest(ctx);
+    return {
+      capabilityKey: 'repository.status',
+      source: 'local',
+      local,
+      synced: Boolean(local && local.systemKey)
+    };
   });
 }
 

package/lib/programmatic/run-template-workspace.js

@@ -18,7 +18,20 @@ const { runWithWorkspaceContext } = require('./workspace-context');
  * @param {Object} body
  */
 async function materializeTemplate(ctx, body = {}) {
-  return runEnterpriseMcpCapability(ctx, 'template.materializeWorkspace', body);
+  return runWithWorkspaceContext(ctx, async() => {
+    // Local-first: COM currently maps template.materializeWorkspace → template.runwizard
+    // which re-enters builder-api wizard and can 409 (workspace lock) under E2E.
+    const local = getSystemManifest(ctx);
+    if (local && local.systemKey) {
+      return {
+        capabilityKey: 'template.materializeWorkspace',
+        source: 'local',
+        materialized: true,
+        local
+      };
+    }
+    return runEnterpriseMcpCapability(ctx, 'template.materializeWorkspace', body);
+  });
 }
 
 /**

package/lib/resolvers/evidence-kind-file.js

@@ -0,0 +1,230 @@
+/**
+ * Evidence kind catalog file helpers for create/import/export.
+ *
+ * File JSON uses `domain`; Controller API uses `domainKey`.
+ *
+ * @fileoverview Evidence kind catalog file parsing and API mapping
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const { existsSync, readFileSync, writeFileSync } = require('../internal/fs-real-sync');
+
+const DOMAIN_KEY_PATTERN = /^[a-z][a-z0-9-]*$/;
+const SEVERITIES = new Set(['low', 'medium', 'high', 'critical']);
+
+/**
+ * @param {string} filePath
+ * @returns {object|Array}
+ */
+function loadEvidenceKindJson(filePath) {
+  const p = path.resolve(String(filePath || '').trim());
+  if (!p) {
+    throw new Error('--file is required');
+  }
+  if (!existsSync(p)) {
+    throw new Error(`File not found: ${p}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(p, 'utf8'));
+  } catch (e) {
+    throw new Error(`Invalid JSON in ${p}: ${e.message}`);
+  }
+  if (parsed === null || typeof parsed !== 'object') {
+    throw new Error(`Evidence kind file must be a JSON object or array: ${p}`);
+  }
+  return parsed;
+}
+
+/**
+ * @param {object} entry
+ * @param {number} index
+ * @returns {string}
+ */
+function requireDomainValue(entry, index) {
+  const raw = entry.domain !== undefined ? entry.domain : entry.domainKey;
+  const value = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+  if (!value) {
+    throw new Error(`evidenceKinds[${index}].domain is required`);
+  }
+  if (!DOMAIN_KEY_PATTERN.test(value)) {
+    throw new Error(
+      'domain must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens'
+    );
+  }
+  return value;
+}
+
+/**
+ * Map baseline/file evidence kind row to Controller create payload (domain → domainKey).
+ * @param {object} row
+ * @param {number} [index]
+ * @returns {Object}
+ */
+function mapEvidenceKindFileToApiPayload(row, index = 0) {
+  if (!row || typeof row !== 'object') {
+    throw new Error(`evidenceKinds[${index}] must be a JSON object`);
+  }
+  const key = String(row.key || '').trim();
+  if (!key) {
+    throw new Error(`evidenceKinds[${index}].key is required`);
+  }
+  const displayName = String(row.displayName || '').trim();
+  if (!displayName) {
+    throw new Error(`evidenceKinds[${index}].displayName is required`);
+  }
+  const purpose = String(row.purpose || '').trim();
+  if (!purpose) {
+    throw new Error(`evidenceKinds[${index}].purpose is required`);
+  }
+  const domainKey = requireDomainValue(row, index);
+  const payload = { key, displayName, purpose, domainKey };
+  copyOptionalFields(payload, row, [
+    'description',
+    'expectedUse',
+    'requiresApproval',
+    'isActive',
+    'sortOrder',
+    'source'
+  ]);
+  assignOptionalSeverity(payload, row, index);
+  if (row.metadata && typeof row.metadata === 'object') {
+    payload.metadata = row.metadata;
+  }
+  return payload;
+}
+
+/**
+ * @param {Object} payload
+ * @param {object} row
+ * @param {number} index
+ * @returns {void}
+ */
+function assignOptionalSeverity(payload, row, index) {
+  if (row.defaultSeverity === undefined) {
+    return;
+  }
+  const severity = String(row.defaultSeverity).trim();
+  if (!SEVERITIES.has(severity)) {
+    throw new Error(
+      `evidenceKinds[${index}].defaultSeverity must be one of: ${[...SEVERITIES].join(', ')}`
+    );
+  }
+  payload.defaultSeverity = severity;
+}
+
+/**
+ * @param {Object} target
+ * @param {object} source
+ * @param {string[]} fields
+ * @returns {void}
+ */
+function copyOptionalFields(target, source, fields) {
+  for (const field of fields) {
+    if (source[field] !== undefined) {
+      target[field] = source[field];
+    }
+  }
+}
+
+/**
+ * Map Controller evidence kind record to baseline-shaped JSON (domainKey → domain).
+ * @param {object} record
+ * @returns {Object}
+ */
+function mapEvidenceKindApiToFileRow(record) {
+  const row = {
+    key: record.key,
+    displayName: record.displayName,
+    domain: record.domainKey || record.domain,
+    purpose: record.purpose
+  };
+  if (record.description) row.description = record.description;
+  if (record.expectedUse) row.expectedUse = record.expectedUse;
+  if (record.defaultSeverity) row.defaultSeverity = record.defaultSeverity;
+  if (record.requiresApproval !== undefined) row.requiresApproval = record.requiresApproval;
+  if (record.sortOrder !== undefined) row.sortOrder = record.sortOrder;
+  if (record.metadata && typeof record.metadata === 'object') {
+    row.metadata = record.metadata;
+  }
+  return row;
+}
+
+/**
+ * @param {object} parsed
+ * @returns {void}
+ */
+function rejectBaselineCatalogShape(parsed) {
+  if (
+    parsed &&
+    typeof parsed === 'object' &&
+    Array.isArray(parsed.evidenceKinds) &&
+    !parsed.key
+  ) {
+    throw new Error(
+      'File is a baseline catalog (evidenceKinds[]). ' +
+        'Use `aifabrix evidence-kind import --file <path>` to seed all entries, ' +
+        'or pass a single evidence kind object with key and displayName.'
+    );
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Object}
+ */
+function readEvidenceKindCreateFile(filePath) {
+  const parsed = loadEvidenceKindJson(filePath);
+  rejectBaselineCatalogShape(parsed);
+  return mapEvidenceKindFileToApiPayload(parsed, 0);
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Object[]}
+ */
+function readEvidenceKindCatalogFile(filePath) {
+  const parsed = loadEvidenceKindJson(filePath);
+  let rows;
+  if (Array.isArray(parsed)) {
+    rows = parsed;
+  } else if (Array.isArray(parsed.evidenceKinds)) {
+    rows = parsed.evidenceKinds;
+  } else {
+    throw new Error(
+      'Import file must be a baseline catalog with evidenceKinds[] or a JSON array of evidence kinds.'
+    );
+  }
+  if (rows.length === 0) {
+    throw new Error('Import file contains no evidence kinds');
+  }
+  return rows.map((row, index) => mapEvidenceKindFileToApiPayload(row, index));
+}
+
+/**
+ * @param {string} filePath
+ * @param {Object[]} rows
+ * @param {string} [version]
+ * @returns {void}
+ */
+function writeEvidenceKindCatalogFile(filePath, rows, version = '1.0.0') {
+  const p = path.resolve(String(filePath || '').trim());
+  if (!p) {
+    throw new Error('--file is required');
+  }
+  const catalog = { version, evidenceKinds: rows };
+  writeFileSync(p, `${JSON.stringify(catalog, null, 2)}\n`, 'utf8');
+}
+
+module.exports = {
+  mapEvidenceKindFileToApiPayload,
+  mapEvidenceKindApiToFileRow,
+  readEvidenceKindCreateFile,
+  readEvidenceKindCatalogFile,
+  writeEvidenceKindCatalogFile,
+  SEVERITIES
+};

package/lib/resolvers/resource-type-file.js

@@ -9,7 +9,7 @@
 'use strict';
 
 const path = require('path');
-const { existsSync, readFileSync } = require('../internal/fs-real-sync');
+const { existsSync, readFileSync, writeFileSync } = require('../internal/fs-real-sync');
 
 /**
  * @typedef {Object} ResourceTypeCreateInput
@@ -172,9 +172,44 @@ function readResourceTypeCatalogFile(filePath) {
   return rows.map((row, index) => normalizeResourceTypeCreateRow(row, index));
 }
 
+/**
+ * Map Controller resource type record to baseline-shaped JSON.
+ * @param {object} record
+ * @returns {Object}
+ */
+function mapResourceTypeApiToFileRow(record) {
+  const row = {
+    key: record.key,
+    displayName: record.displayName,
+    domain: record.domain
+  };
+  if (record.description) row.description = record.description;
+  if (record.category) row.category = record.category;
+  if (record.defaultRiskLevel) row.defaultRiskLevel = record.defaultRiskLevel;
+  if (record.status) row.status = record.status;
+  return row;
+}
+
+/**
+ * @param {string} filePath
+ * @param {Object[]} rows - baseline-shaped resource type rows
+ * @param {string} [version]
+ * @returns {void}
+ */
+function writeResourceTypeCatalogFile(filePath, rows, version = '1.0.0') {
+  const p = path.resolve(String(filePath || '').trim());
+  if (!p) {
+    throw new Error('--file is required');
+  }
+  const catalog = { version, resourceTypes: rows };
+  writeFileSync(p, `${JSON.stringify(catalog, null, 2)}\n`, 'utf8');
+}
+
 module.exports = {
   readResourceTypeCreateFile,
   readResourceTypeCatalogFile,
+  mapResourceTypeApiToFileRow,
+  writeResourceTypeCatalogFile,
   CATEGORIES,
   RISK_LEVELS,
   STATUSES

package/lib/resolvers/role-file.js

@@ -0,0 +1,227 @@
+/**
+ * Role catalog file helpers for create/import/export.
+ *
+ * File JSON uses `domain`; Controller API uses `domainKey`.
+ * Compiler fields nest under `metadata` on the API payload.
+ *
+ * @fileoverview Role catalog file parsing and API mapping
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const { existsSync, readFileSync, writeFileSync } = require('../internal/fs-real-sync');
+
+/** Compiler fields that live top-level in baseline JSON and under metadata in the API. */
+const ROLE_COMPILER_FIELDS = [
+  'defaultResourceType',
+  'primaryResourceTypes',
+  'defaultCapability',
+  'defaultCapabilities',
+  'defaultKnowledgeProfiles',
+  'defaultEvidenceKinds',
+  'defaultKnowledgeKeys',
+  'defaultKnowledgeGenerationProfiles'
+];
+
+const DOMAIN_KEY_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * @param {string} filePath
+ * @returns {object|Array}
+ */
+function loadRoleJson(filePath) {
+  const p = path.resolve(String(filePath || '').trim());
+  if (!p) {
+    throw new Error('--file is required');
+  }
+  if (!existsSync(p)) {
+    throw new Error(`File not found: ${p}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(p, 'utf8'));
+  } catch (e) {
+    throw new Error(`Invalid JSON in ${p}: ${e.message}`);
+  }
+  if (parsed === null || typeof parsed !== 'object') {
+    throw new Error(`Role file must be a JSON object or array: ${p}`);
+  }
+  return parsed;
+}
+
+/**
+ * @param {object} entry
+ * @param {number} index
+ * @returns {string}
+ */
+function requireDomainValue(entry, index) {
+  const raw = entry.domain !== undefined ? entry.domain : entry.domainKey;
+  const value = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+  if (!value) {
+    throw new Error(`roles[${index}].domain is required`);
+  }
+  if (!DOMAIN_KEY_PATTERN.test(value)) {
+    throw new Error(
+      'domain must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens'
+    );
+  }
+  return value;
+}
+
+/**
+ * Map baseline/file role row to Controller create payload (domain → domainKey; compiler → metadata).
+ * @param {object} row
+ * @param {number} [index]
+ * @returns {Object}
+ */
+function mapRoleFileToApiPayload(row, index = 0) {
+  if (!row || typeof row !== 'object') {
+    throw new Error(`roles[${index}] must be a JSON object`);
+  }
+  const key = String(row.key || '').trim();
+  if (!key) {
+    throw new Error(`roles[${index}].key is required`);
+  }
+  const displayName = String(row.displayName || '').trim();
+  if (!displayName) {
+    throw new Error(`roles[${index}].displayName is required`);
+  }
+  const domainKey = requireDomainValue(row, index);
+  const metadata = collectRoleCompilerMetadata(row);
+  const payload = { key, displayName, domainKey };
+  copyOptionalFields(payload, row, ['description', 'purpose', 'businessOutcome', 'isActive', 'source']);
+  if (Object.keys(metadata).length > 0) {
+    payload.metadata = metadata;
+  }
+  return payload;
+}
+
+/**
+ * @param {object} row
+ * @returns {Object}
+ */
+function collectRoleCompilerMetadata(row) {
+  const metadata = {
+    ...(row.metadata && typeof row.metadata === 'object' ? row.metadata : {})
+  };
+  for (const field of ROLE_COMPILER_FIELDS) {
+    if (row[field] !== undefined) {
+      metadata[field] = row[field];
+    }
+  }
+  return metadata;
+}
+
+/**
+ * @param {Object} target
+ * @param {object} source
+ * @param {string[]} fields
+ * @returns {void}
+ */
+function copyOptionalFields(target, source, fields) {
+  for (const field of fields) {
+    if (source[field] !== undefined) {
+      target[field] = source[field];
+    }
+  }
+}
+
+/**
+ * Map Controller role record to baseline-shaped JSON (domainKey → domain; flatten compiler metadata).
+ * @param {object} record
+ * @returns {Object}
+ */
+function mapRoleApiToFileRow(record) {
+  const row = {
+    key: record.key,
+    displayName: record.displayName,
+    domain: record.domainKey || record.domain
+  };
+  if (record.description) row.description = record.description;
+  if (record.purpose) row.purpose = record.purpose;
+  if (record.businessOutcome) row.businessOutcome = record.businessOutcome;
+  const meta = record.metadata && typeof record.metadata === 'object' ? { ...record.metadata } : {};
+  for (const field of ROLE_COMPILER_FIELDS) {
+    if (meta[field] !== undefined) {
+      row[field] = meta[field];
+      delete meta[field];
+    }
+  }
+  if (Object.keys(meta).length > 0) {
+    row.metadata = meta;
+  }
+  return row;
+}
+
+/**
+ * @param {object} parsed
+ * @returns {void}
+ */
+function rejectBaselineCatalogShape(parsed) {
+  if (parsed && typeof parsed === 'object' && Array.isArray(parsed.roles) && !parsed.key) {
+    throw new Error(
+      'File is a baseline catalog (roles[]). ' +
+        'Use `aifabrix role import --file <path>` to seed all entries, ' +
+        'or pass a single role object with key and displayName.'
+    );
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Object}
+ */
+function readRoleCreateFile(filePath) {
+  const parsed = loadRoleJson(filePath);
+  rejectBaselineCatalogShape(parsed);
+  return mapRoleFileToApiPayload(parsed, 0);
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Object[]}
+ */
+function readRoleCatalogFile(filePath) {
+  const parsed = loadRoleJson(filePath);
+  let rows;
+  if (Array.isArray(parsed)) {
+    rows = parsed;
+  } else if (Array.isArray(parsed.roles)) {
+    rows = parsed.roles;
+  } else {
+    throw new Error(
+      'Import file must be a baseline catalog with roles[] or a JSON array of roles.'
+    );
+  }
+  if (rows.length === 0) {
+    throw new Error('Import file contains no roles');
+  }
+  return rows.map((row, index) => mapRoleFileToApiPayload(row, index));
+}
+
+/**
+ * @param {string} filePath
+ * @param {Object[]} rows - baseline-shaped role rows
+ * @param {string} [version]
+ * @returns {void}
+ */
+function writeRoleCatalogFile(filePath, rows, version = '1.0.0') {
+  const p = path.resolve(String(filePath || '').trim());
+  if (!p) {
+    throw new Error('--file is required');
+  }
+  const catalog = { version, roles: rows };
+  writeFileSync(p, `${JSON.stringify(catalog, null, 2)}\n`, 'utf8');
+}
+
+module.exports = {
+  ROLE_COMPILER_FIELDS,
+  mapRoleFileToApiPayload,
+  mapRoleApiToFileRow,
+  readRoleCreateFile,
+  readRoleCatalogFile,
+  writeRoleCatalogFile
+};

package/lib/schema/application-schema.json

@@ -7,12 +7,12 @@
     "key": "application-schema",
     "name": "Application Configuration Schema",
     "description": "JSON schema for validating AI Fabrix application configuration files",
-    "version": "1.4.0",
+    "version": "1.5.0",
     "type": "schema",
     "category": "infrastructure",
     "author": "AI Fabrix Team",
     "createdAt": "2024-01-01T00:00:00Z",
-    "updatedAt": "2026-04-06T00:00:00Z",
+    "updatedAt": "2026-07-21T00:00:00Z",
     "compatibility": {
       "minVersion": "1.0.0",
       "maxVersion": "2.0.0",
@@ -30,6 +30,14 @@
       "external-datasource.schema.json"
     ],
     "changelog": [
+      {
+        "version": "1.5.0",
+        "date": "2026-07-21T00:00:00Z",
+        "changes": [
+          "Added optional configuration[].category (and conditionalConfiguration item category) for portal UI grouping labels in Miso Configuration tab."
+        ],
+        "breaking": false
+      },
       {
         "version": "1.4.0",
         "date": "2026-04-06T00:00:00Z",
@@ -203,6 +211,12 @@
             "type": "boolean",
             "description": "Whether this configuration is required"
           },
+          "category": {
+            "type": "string",
+            "description": "Optional UI grouping label for portal/deployment wizard Configuration tab",
+            "minLength": 1,
+            "maxLength": 100
+          },
           "portalInput": {
             "type": "object",
             "description": "Portal input configuration for user-provided values",
@@ -315,6 +329,12 @@
                   "type": "boolean",
                   "description": "Whether this configuration is required"
                 },
+                "category": {
+                  "type": "string",
+                  "description": "Optional UI grouping label for portal/deployment wizard Configuration tab",
+                  "minLength": 1,
+                  "maxLength": 100
+                },
                 "portalInput": {
                   "type": "object",
                   "description": "Portal input configuration for user-provided values",