@aifabrix/builder 2.51.0 → 2.51.1

package/lib/commands/evidence-kind.js

@@ -299,6 +299,67 @@ function setupEvidenceKindCreateCommand(cmd) {
     });
 }
 
+/**
+ * @param {object} contribution
+ * @returns {string}
+ */
+function formatEvidenceKindContributionLine(contribution) {
+  const parts = [
+    contribution.key || '—',
+    contribution.typeRef || null,
+    contribution.referenceValue !== null
+    && contribution.referenceValue !== undefined
+    && contribution.unit
+      ? `${contribution.referenceValue} ${contribution.unit}`
+      : contribution.unit || null,
+    contribution.primary ? 'primary' : null,
+    contribution.attributionKey || null,
+    contribution.attributionBoundary || null
+  ].filter(Boolean);
+  return `  - ${parts.join(' · ')}`;
+}
+
+/**
+ * @param {object} row
+ * @returns {void}
+ */
+function logEvidenceKindContributions(row) {
+  const contributions = row?.metadata?.contributions;
+  if (!Array.isArray(contributions) || contributions.length === 0) {
+    return;
+  }
+  logger.log(headerKeyValue('Contributions:', `${contributions.length}`));
+  contributions.forEach((item) => {
+    logger.log(formatEvidenceKindContributionLine(item));
+  });
+}
+
+/**
+ * @param {object} row
+ * @param {string} environment
+ * @param {string} controllerUrl
+ * @returns {void}
+ */
+function displayEvidenceKindDetail(row, environment, controllerUrl) {
+  logger.log(
+    chalk.bold(`\n📎  Evidence kind in ${environment} environment (${controllerUrl}):\n`)
+  );
+  logger.log(headerKeyValue('Key:', row.key || '—'));
+  logger.log(headerKeyValue('Display:', row.displayName || '—'));
+  logger.log(headerKeyValue('Domain:', row.domainKey || '—'));
+  logger.log(headerKeyValue('Purpose:', row.purpose || '—'));
+  logger.log(headerKeyValue('Severity:', row.defaultSeverity || '—'));
+  logger.log(headerKeyValue('Active:', row.isActive === false ? 'false' : 'true'));
+  if (row.source) logger.log(headerKeyValue('Source:', row.source));
+  if (row.requiresApproval !== undefined) {
+    logger.log(headerKeyValue('Requires approval:', row.requiresApproval ? 'true' : 'false'));
+  }
+  if (row.expectedUse) logger.log(headerKeyValue('Expected use:', row.expectedUse));
+  if (row.description) logger.log(headerKeyValue('Description:', row.description));
+  logEvidenceKindContributions(row);
+  logger.log('');
+}
+
 function setupEvidenceKindGetCommand(cmd) {
   cmd
     .command('get <evidenceKindIdOrKey>')
@@ -310,20 +371,7 @@ function setupEvidenceKindGetCommand(cmd) {
         const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
         const res = await getEvidenceKind(controllerUrl, authConfig, String(evidenceKindIdOrKey).trim());
         const row = unwrapControllerData(res);
-        logger.log(
-          chalk.bold(
-            `\n📎  Evidence kind in ${environment} environment (${headerControllerUrl}):\n`
-          )
-        );
-        logger.log(headerKeyValue('Key:', row.key || '—'));
-        logger.log(headerKeyValue('Display:', row.displayName || '—'));
-        logger.log(headerKeyValue('Domain:', row.domainKey || '—'));
-        logger.log(headerKeyValue('Purpose:', row.purpose || '—'));
-        logger.log(headerKeyValue('Severity:', row.defaultSeverity || '—'));
-        logger.log(headerKeyValue('Active:', row.isActive === false ? 'false' : 'true'));
-        if (row.expectedUse) logger.log(headerKeyValue('Expected use:', row.expectedUse));
-        if (row.description) logger.log(headerKeyValue('Description:', row.description));
-        logger.log('');
+        displayEvidenceKindDetail(row, environment, headerControllerUrl);
       } catch (e) {
         logger.error(formatBlockingError(e.message));
         process.exit(1);
@@ -424,5 +472,7 @@ module.exports = {
   unwrapControllerData,
   importEvidenceKindRows,
   mapEvidenceKindFileToApiPayload,
-  mapEvidenceKindApiToFileRow
+  mapEvidenceKindApiToFileRow,
+  displayEvidenceKindDetail,
+  formatEvidenceKindContributionLine
 };

package/lib/commands/governance-generate-external.js

@@ -12,33 +12,21 @@ const {
 const { runWithVerifyStepProgress } = require('../lifecycle/verify-step-progress');
 
 /**
- * @async
- * @param {string} systemKey
+ * @param {string[]} targetKeys
+ * @param {Object} ctx
  * @param {Object} options
- * @returns {Promise<Object>}
+ * @returns {Promise<Array>}
  */
-async function runGovernanceGenerateForExternalSystem(systemKey, options = {}) {
-  const subjects = buildSubjectsFromOptions(options);
-  if (subjects.length === 0) {
-    throw new Error(
-      'At least one --subject-user-id or --subject-email is required for governance generate'
-    );
-  }
-
-  const { resolvedKey, keys, authConfig, dataplaneUrl } =
-    await resolveGovernanceIntegrationContext(systemKey, options);
-
-  const profile = (options.certificationProfile || 'bronze').trim().toLowerCase();
-  const maxSamples = Number(options.maxSamplesPerPartition) || 25;
-
-  const results = await runWithVerifyStepProgress(
+async function generatePacksForDatasourceKeys(targetKeys, ctx, options) {
+  const { dataplaneUrl, authConfig, resolvedKey, subjects, profile, maxSamples } = ctx;
+  return runWithVerifyStepProgress(
     'Generating governance scenario packs',
     async progress => {
       const rows = [];
-      for (let index = 0; index < keys.length; index += 1) {
-        const dsKey = keys[index];
+      for (let index = 0; index < targetKeys.length; index += 1) {
+        const dsKey = targetKeys[index];
         if (typeof progress.setLabel === 'function') {
-          progress.setLabel(`Generating pack: ${dsKey} (${index + 1}/${keys.length})`);
+          progress.setLabel(`Generating pack: ${dsKey} (${index + 1}/${targetKeys.length})`);
         }
         const row = await generateDatasourceGovernancePack(
           dataplaneUrl,
@@ -57,6 +45,53 @@ async function runGovernanceGenerateForExternalSystem(systemKey, options = {}) {
     },
     options
   );
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runGovernanceGenerateForExternalSystem(systemKey, options = {}) {
+  const subjects = buildSubjectsFromOptions(options);
+  if (subjects.length === 0) {
+    throw new Error(
+      'At least one --subject-user-id or --subject-email is required for governance generate'
+    );
+  }
+
+  const { resolvedKey, keys, authConfig, dataplaneUrl } =
+    await resolveGovernanceIntegrationContext(systemKey, options);
+
+  const {
+    filterAbacRequiredDatasourceKeys
+  } = require('../lifecycle/access-control-abac');
+  const targetKeys = Array.isArray(options.datasourceKeys) && options.datasourceKeys.length
+    ? options.datasourceKeys
+    : filterAbacRequiredDatasourceKeys(resolvedKey, keys);
+
+  if (targetKeys.length === 0) {
+    return {
+      systemKey: resolvedKey,
+      command: 'governance generate',
+      generated: 0,
+      results: []
+    };
+  }
+
+  const results = await generatePacksForDatasourceKeys(
+    targetKeys,
+    {
+      dataplaneUrl,
+      authConfig,
+      resolvedKey,
+      subjects,
+      profile: (options.certificationProfile || 'bronze').trim().toLowerCase(),
+      maxSamples: Number(options.maxSamplesPerPartition) || 25
+    },
+    options
+  );
 
   return {
     systemKey: resolvedKey,

package/lib/commands/lifecycle-external.js

@@ -98,13 +98,18 @@ async function runLifecycleGovernanceCombinedIfNeeded(
  */
 async function runMissingVerifyStepsLocally(systemKey, report, options) {
   const runOpts = { ...options, noPublish: true };
-  if (report.operations?.verdict !== VERDICT.VERIFIED) {
+  const pathsUtil = require('../utils/paths');
+  const appType = await pathsUtil.detectAppType(systemKey).catch(() => null);
+  const isRoleAssistantPackage = appType?.baseDir === 'role-assistant';
+  // verify-operations is integration/-only; Role Assistant packages use dataplane lifecycle report.
+  if (report.operations?.verdict !== VERDICT.VERIFIED && !isRoleAssistantPackage) {
     await runVerifyOperationsForExternalSystem(systemKey, runOpts);
   }
   if (report.trust?.verdict !== VERDICT.VERIFIED) {
     await runVerifyTrustForExternalSystem(systemKey, runOpts);
   }
-  if (report.governance?.verdict !== VERDICT.VERIFIED) {
+  if (report.governance?.verdict !== VERDICT.VERIFIED
+    && report.governance?.verdict !== VERDICT.NOT_APPLICABLE) {
     if (lifecycleHasGovernanceSubjects(options)) {
       const { runVerifyGovernanceCombined } = require('./verify-governance-combined-external');
       await runVerifyGovernanceCombined(
@@ -243,9 +248,10 @@ async function executeLifecycleWork(systemKey, options = {}) {
 async function runLifecycleForExternalSystem(systemKey, options = {}) {
   const pathsUtil = require('../utils/paths');
   const appType = await pathsUtil.detectAppType(systemKey).catch(() => null);
-  if (!appType || appType.baseDir !== 'integration') {
+  const allowedRoots = new Set(['integration', 'role-assistant']);
+  if (!appType || !allowedRoots.has(appType.baseDir)) {
     throw new Error(
-      'lifecycle applies to external integration folders only (integration/<systemKey>/).'
+      'lifecycle applies to external authoring folders only (integration/<systemKey>/ or role-assistant/<roleKey>/).'
     );
   }
 

package/lib/commands/repair-datasource-apply.js

@@ -84,7 +84,16 @@ function applyBaseDatasourceRepairs(parsed, none, changes, options, helpers) {
   updated = helpers.repairMetadataSchemaFromAttributes(parsed, changes) || updated;
   const warnings = Array.isArray(options.warnings) ? options.warnings : [];
   updated = repairWebhookSection(parsed, changes, warnings) || updated;
-  updated = repairSyncBridgeSection(parsed, changes, warnings) || updated;
+  updated = repairSyncBridgeSection(parsed, changes, warnings, options) || updated;
+  if (
+    Number.isInteger(options.businessOrder) &&
+    options.businessOrder >= 1 &&
+    (parsed.businessOrder === undefined || parsed.businessOrder === null)
+  ) {
+    parsed.businessOrder = options.businessOrder;
+    changes.push(`Set businessOrder ${options.businessOrder} (absent; datasource repair order)`);
+    updated = true;
+  }
   collectWebhookSyncBridgeSystemWarnings(parsed, options.systemParsed, warnings);
   return updated;
 }

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

@@ -30,7 +30,8 @@ function runDatasourceRepairs(appPath, datasourceFiles, options, dryRun, changes
   if (!datasourceFiles || datasourceFiles.length === 0) return false;
   let updated = false;
   const warnings = Array.isArray(context.warnings) ? context.warnings : [];
-  for (const fileName of datasourceFiles) {
+  for (let i = 0; i < datasourceFiles.length; i += 1) {
+    const fileName = datasourceFiles[i];
     const filePath = path.join(appPath, fileName);
     if (!fs.existsSync(filePath)) continue;
     try {
@@ -41,7 +42,8 @@ function runDatasourceRepairs(appPath, datasourceFiles, options, dryRun, changes
         test: options.test,
         operations: options.operations,
         systemParsed: context.systemParsed,
-        warnings
+        warnings,
+        businessOrder: i + 1
       });
       if (fileUpdated) {
         updated = true;

package/lib/commands/repair-datasource-test-payload.js

@@ -57,30 +57,51 @@ function getSchemaNodeAtPath(rootSchema, pathParts) {
   return node;
 }
 
+/**
+ * Format / pattern samples for string-like schema nodes.
+ * @param {Object} node - JSON Schema node
+ * @returns {*|undefined}
+ */
+function placeholderFromFormatOrPattern(node) {
+  const samples = {
+    'date-time': '2025-01-15T10:30:00Z',
+    date: '2025-01-15',
+    uuid: '00000000-0000-4000-8000-000000000001',
+    uri: 'https://example.com/objects/1',
+    'uri-reference': 'https://example.com/objects/1',
+    email: 'sample@example.com'
+  };
+  if (node.format && Object.prototype.hasOwnProperty.call(samples, node.format)) {
+    return samples[node.format];
+  }
+  if (typeof node.pattern === 'string' && /\\d/.test(node.pattern)) {
+    return '+1 555 0100';
+  }
+  return undefined;
+}
+
 /**
  * @param {Object|null|undefined} node - JSON Schema node
  * @returns {*}
  */
 function placeholderFromSchemaNode(node) {
-  if (!node || typeof node !== 'object') return '';
+  if (!node || typeof node !== 'object') return 'sample';
+  const fromFormat = placeholderFromFormatOrPattern(node);
+  if (fromFormat !== undefined) return fromFormat;
   const type = primarySchemaType(node.type);
-  if (node.format === 'date-time') return '2025-01-15T10:30:00Z';
-  if (node.format === 'date') return '2025-01-15';
-  if (node.format === 'uuid') return '00000000-0000-4000-8000-000000000001';
   if (type === 'boolean') return false;
   if (type === 'integer' || type === 'number') return 0;
   if (type === 'array') return [];
   if (type === 'object') {
-    if (node.properties && typeof node.properties === 'object') {
-      const out = {};
-      for (const [k, sub] of Object.entries(node.properties)) {
-        out[k] = placeholderFromSchemaNode(sub);
-      }
-      return out;
+    const props = node.properties;
+    if (!props || typeof props !== 'object') return {};
+    const out = {};
+    for (const [k, sub] of Object.entries(props)) {
+      out[k] = placeholderFromSchemaNode(sub);
     }
-    return {};
+    return out;
   }
-  return '';
+  return 'sample';
 }
 
 /**
@@ -92,18 +113,35 @@ function placeholderForType(type) {
   if (type === 'boolean') return false;
   if (type === 'array') return [];
   if (type === 'object') return {};
-  return '';
+  return 'sample';
 }
 
 /**
- * @param {Object} parsed - Datasource config
- * @param {string[]} pathParts - Path under raw payload
- * @param {Object} [attrConfig] - Attribute config (optional type fallback)
- * @returns {*}
+ * Prefer schema nodes that carry format/pattern over bare type-only nodes.
+ * @param {Object|null|undefined} a
+ * @param {Object|null|undefined} b
+ * @returns {Object|null}
  */
+function pickRicherSchemaNode(a, b) {
+  const score = node => {
+    if (!node || typeof node !== 'object') return -1;
+    let s = 0;
+    if (node.format) s += 2;
+    if (node.pattern) s += 2;
+    if (node.type) s += 1;
+    return s;
+  };
+  if (score(a) < 0 && score(b) < 0) return null;
+  return score(a) >= score(b) ? a : b;
+}
+
 function resolvePlaceholderForPath(parsed, pathParts, attrConfig) {
   const node = getSchemaNodeAtPath(parsed?.metadataSchema, pathParts);
-  if (node) return placeholderFromSchemaNode(node);
+  // HubSpot-style: materialized root prop (phone/email/url) may be richer than nested.
+  const leaf = pathParts[pathParts.length - 1];
+  const rootNode = parsed?.metadataSchema?.properties?.[leaf];
+  const picked = pickRicherSchemaNode(node, rootNode);
+  if (picked) return placeholderFromSchemaNode(picked);
   return placeholderForType(attrConfig?.type || 'string');
 }
 
@@ -154,7 +192,10 @@ function enrichObjectLeavesFromNestedPaths(parsed, pathEntries, payloadTemplate)
       payloadTemplate.properties = placeholderFromSchemaNode(propertiesNode);
     }
     if (payloadTemplate.properties[leaf] === undefined || payloadTemplate.properties[leaf] === '') {
-      const leafNode = getSchemaNodeAtPath(parsed?.metadataSchema, ['properties', leaf]);
+      const leafNode = pickRicherSchemaNode(
+        getSchemaNodeAtPath(parsed?.metadataSchema, ['properties', leaf]),
+        parsed?.metadataSchema?.properties?.[leaf]
+      );
       payloadTemplate.properties[leaf] = leafNode
         ? placeholderFromSchemaNode(leafNode)
         : 'sample';
@@ -209,6 +250,24 @@ function buildPathEntriesFromAttributes(parsed, attrs) {
  * @param {Array} pathEntries - From buildPathEntriesFromAttributes
  * @returns {{ payloadTemplate: Object, expectedResult: Object }}
  */
+/**
+ * Ensure metadataSchema.required root keys exist on payloadTemplate.
+ * @param {Object} parsed
+ * @param {Object} payloadTemplate
+ */
+function ensureRequiredRootPlaceholders(parsed, payloadTemplate) {
+  const required = parsed?.metadataSchema?.required;
+  const props = parsed?.metadataSchema?.properties;
+  if (!Array.isArray(required) || !props || typeof props !== 'object') return;
+  for (const key of required) {
+    if (!key || typeof key !== 'string') continue;
+    const existing = payloadTemplate[key];
+    if (existing !== undefined && existing !== '') continue;
+    const node = props[key];
+    payloadTemplate[key] = node ? placeholderFromSchemaNode(node) : 'sample';
+  }
+}
+
 function buildTemplatesFromPathEntries(parsed, pathEntries) {
   const payloadTemplate = {};
   const expectedResult = {};
@@ -223,6 +282,7 @@ function buildTemplatesFromPathEntries(parsed, pathEntries) {
     setNestedValue(payloadTemplate, parts, resolvePlaceholderForPath(parsed, parts, config));
   }
   enrichObjectLeavesFromNestedPaths(parsed, pathEntries, payloadTemplate);
+  ensureRequiredRootPlaceholders(parsed, payloadTemplate);
   return { payloadTemplate, expectedResult };
 }
 
@@ -255,5 +315,6 @@ module.exports = {
   placeholderFromSchemaNode,
   placeholderForType,
   resolvePlaceholderForPath,
+  ensureRequiredRootPlaceholders,
   repairTestPayload
 };

package/lib/commands/repair-datasource-webhooks-sync-bridge.js

@@ -88,21 +88,59 @@ function ensureSyncBridgeExternalIdMetadata(parsed, changes) {
   return true;
 }
 
+/**
+ * Default syncBridge when --sync repair runs and the field is absent.
+ * Explicit values (including disabled) are never overwritten.
+ *
+ * @param {object} parsed
+ * @param {Object} [options]
+ * @returns {'master' | 'disabled' | null}
+ */
+function defaultSyncBridgeForSyncRepair(parsed, options = {}) {
+  if (options.sync !== true) {
+    return null;
+  }
+  if (Object.prototype.hasOwnProperty.call(parsed || {}, 'syncBridge')) {
+    return null;
+  }
+  const entityType = String(parsed?.entityType || '').trim();
+  if (entityType === 'none') {
+    return null;
+  }
+  const resourceType = String(parsed?.resourceType || '').trim();
+  // Owner/employee catalogs typically do not own sync propagation.
+  if (resourceType === 'employee') {
+    return 'disabled';
+  }
+  if (entityType === 'recordStorage' || entityType === '') {
+    return 'master';
+  }
+  return null;
+}
+
 /**
  * @param {object} parsed
  * @param {string[]} changes
  * @param {string[]} warnings
+ * @param {Object} [options]
  * @returns {boolean}
  */
-function repairSyncBridgeSection(parsed, changes, warnings) {
+function repairSyncBridgeSection(parsed, changes, warnings, options = {}) {
+  let updated = false;
+  const seeded = defaultSyncBridgeForSyncRepair(parsed, options);
+  if (seeded) {
+    parsed.syncBridge = seeded;
+    changes.push(`Set syncBridge default ${seeded} (--sync repair; field was absent)`);
+    updated = true;
+  }
   const mode = parsed?.syncBridge || 'disabled';
   if (mode === 'disabled') {
-    return false;
+    return updated;
   }
   if (mode === 'master' && !parsed.resourceType) {
     warnings.push('syncBridge=master requires resourceType for propagation grouping.');
   }
-  return ensureSyncBridgeExternalIdMetadata(parsed, changes);
+  return ensureSyncBridgeExternalIdMetadata(parsed, changes) || updated;
 }
 
 /**
@@ -128,6 +166,7 @@ function collectWebhookSyncBridgeSystemWarnings(parsed, systemParsed, warnings)
 module.exports = {
   repairWebhookSection,
   repairSyncBridgeSection,
+  defaultSyncBridgeForSyncRepair,
   collectWebhookSyncBridgeSystemWarnings,
   systemHasWebhookInboundAuth
 };

package/lib/commands/repair-internal.js

@@ -28,7 +28,15 @@ function discoverIntegrationFiles(appPath) {
   if (!fs.existsSync(appPath)) {
     return { systemFiles: [], datasourceFiles: [] };
   }
-  const entries = fs.readdirSync(appPath);
+  let entries = [];
+  try {
+    entries = fs.readdirSync(appPath);
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return { systemFiles: [], datasourceFiles: [] };
+    }
+    throw error;
+  }
   const systemFiles = [];
   const datasourceFiles = [];
   for (const name of entries) {

package/lib/commands/repair-openapi-sync.js

@@ -123,6 +123,28 @@ function readDatasourceDocumentKey(appPath, datasourceFileName) {
   return openapi && typeof openapi.documentKey === 'string' ? openapi.documentKey : null;
 }
 
+/**
+ * @returns {Promise<'uploaded'|'skipped'|'skip'>}
+ */
+async function syncOneDatasourceOpenApiFile(ctx, fileName) {
+  const documentKey = readDatasourceDocumentKey(ctx.appPath, fileName);
+  if (!documentKey || ctx.uploadedThisRun.has(documentKey)) return 'skip';
+  if (!ctx.forceUpload && ctx.existingKeys.has(documentKey)) return 'skip';
+
+  const localPath = documentKeyToLocalOpenApiPath(ctx.appPath, ctx.systemKey, documentKey);
+  if (!(await fileExistsAsync(localPath))) return 'skipped';
+
+  await uploadOneOpenApiFile(
+    ctx.dataplaneUrl,
+    ctx.authConfig,
+    ctx.systemKey,
+    localPath,
+    documentKey
+  );
+  ctx.uploadedThisRun.add(documentKey);
+  return 'uploaded';
+}
+
 /**
  * @param {Object} opts
  * @param {string} opts.appPath
@@ -139,26 +161,21 @@ async function syncOpenApiFilesForMcp(opts) {
     dataplaneUrl: opts.dataplaneUrl,
     authConfig: opts.authConfig
   });
-  const existingKeys = await getExistingOpenApiKeys(dataplaneUrl, systemKey, authConfig);
-  const uploadedThisRun = new Set();
+  const ctx = {
+    appPath,
+    systemKey,
+    dataplaneUrl,
+    authConfig,
+    existingKeys: await getExistingOpenApiKeys(dataplaneUrl, systemKey, authConfig),
+    uploadedThisRun: new Set(),
+    forceUpload: opts.force === true
+  };
   let uploaded = 0;
   let skipped = 0;
-  const forceUpload = opts.force === true;
-
   for (const fileName of datasourceFiles || []) {
-    const documentKey = readDatasourceDocumentKey(appPath, fileName);
-    if (!documentKey || uploadedThisRun.has(documentKey)) continue;
-    if (!forceUpload && existingKeys.has(documentKey)) continue;
-
-    const localPath = documentKeyToLocalOpenApiPath(appPath, systemKey, documentKey);
-    if (!(await fileExistsAsync(localPath))) {
-      skipped += 1;
-      continue;
-    }
-
-    await uploadOneOpenApiFile(dataplaneUrl, authConfig, systemKey, localPath, documentKey);
-    uploadedThisRun.add(documentKey);
-    uploaded += 1;
+    const outcome = await syncOneDatasourceOpenApiFile(ctx, fileName);
+    if (outcome === 'uploaded') uploaded += 1;
+    if (outcome === 'skipped') skipped += 1;
   }
 
   return { uploaded, skipped };