@aifabrix/builder 2.45.5 → 2.47.0

package/lib/governance/governance-cli-errors.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Governance CLI error messages (424.0).
+ */
+
+'use strict';
+
+/**
+ * @param {Error|string} err
+ * @returns {boolean}
+ */
+function isGovernancePackNotFoundError(err) {
+  const raw = (err && err.message) || String(err);
+  return /not found/i.test(raw) || /\b404\b/.test(raw);
+}
+
+/**
+ * @param {Error|string} err
+ * @returns {boolean}
+ */
+function isGovernanceCoverageSchemaError(err) {
+  const raw = (err && err.message) || String(err);
+  return (
+    raw.includes('\'coverage\' is a required property') || /spec\.coverage/i.test(raw)
+  );
+}
+
+/**
+ * Short, non-duplicative CLI message from a dataplane governance API error.
+ * @param {Error|string} err
+ * @returns {string}
+ */
+function shortGovernanceApiError(err) {
+  const raw = ((err && err.message) || String(err)).trim();
+  if (isGovernancePackNotFoundError(err)) {
+    return 'No active pack on dataplane';
+  }
+  if (isGovernanceCoverageSchemaError(err)) {
+    return 'Pack missing spec.coverage (424.0 schema)';
+  }
+  const firstLine = raw.split('\n').find(line => line.trim()) || raw;
+  if (/^Governance scenario pack not found/i.test(firstLine)) {
+    return 'No active pack on dataplane';
+  }
+  return firstLine.length > 100 ? `${firstLine.slice(0, 97)}...` : firstLine;
+}
+
+/**
+ * User-facing hint after a failed governance pack upload (validation).
+ * @param {string} systemKey
+ * @returns {string}
+ */
+function governanceUploadSchemaHint(systemKey) {
+  return (
+    'Scenario pack does not meet the 424.0 schema. Use dataplane-first generation:\n' +
+    `  aifabrix governance generate ${systemKey} --subject-email <email>\n` +
+    'Or: aifabrix verify-governance ' +
+    `${systemKey} --subject-email <email>`
+  );
+}
+
+/**
+ * Clarify subject-resolution 400s (dataplane reachable; User row missing).
+ * @param {Error} err
+ * @param {{ subjectEmails?: string[] }} [context]
+ * @returns {Error}
+ */
+function enrichUnresolvableGovernanceSubjectsError(err, context = {}) {
+  const hay = `${err.message || ''} ${err.formatted || ''}`;
+  if (!hay.includes('No resolvable subjects')) {
+    return err;
+  }
+  const emails = Array.isArray(context.subjectEmails)
+    ? context.subjectEmails.filter(Boolean)
+    : [];
+  const lines = [
+    '',
+    'The dataplane is reachable. This is not a network or controller error.',
+    'Pack generation needs --subject-email values that match existing dataplane User rows.',
+    emails.length > 0 ? `Subject email(s) you passed: ${emails.join(', ')}` : null,
+    'Check:',
+    '  aifabrix identity user list --search <email>',
+    'If the user is missing, apply your identity CSV first:',
+    '  aifabrix identity apply --file integration/<systemKey>/fixtures/<users>.csv --filter-prefix <systemKey>',
+    '  aifabrix identity sync -e dev --purge-cache'
+  ].filter(line => line !== null);
+  err.formatted = `${err.formatted || err.message}${lines.join('\n')}`;
+  return err;
+}
+
+module.exports = {
+  isGovernancePackNotFoundError,
+  isGovernanceCoverageSchemaError,
+  shortGovernanceApiError,
+  governanceUploadSchemaHint,
+  enrichUnresolvableGovernanceSubjectsError
+};

package/lib/governance/governance-download-display.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview TTY summary when governance download finds no active packs.
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const { failureGlyph } = require('../utils/cli-test-layout-chalk');
+const logger = require('../utils/logger');
+
+/**
+ * @param {Array<{ datasourceKey: string, reason: string }>} missing
+ */
+function printGovernanceDownloadMisses(missing) {
+  if (!missing || missing.length === 0) {
+    return;
+  }
+  for (const row of missing) {
+    logger.log(
+      chalk.white(`${row.datasourceKey}: ${failureGlyph()} ${row.reason}`)
+    );
+  }
+  logger.log('');
+  logger.log(chalk.gray('Next steps:'));
+  logger.log(
+    chalk.gray(
+      '  • Run: aifabrix governance generate <systemKey> --subject-email <email>'
+    )
+  );
+  logger.log(
+    chalk.gray('  • Or use: aifabrix verify-governance <systemKey> --subject-email <email>')
+  );
+  logger.log(chalk.gray('  • Ensure protection is published and identity sync has run'));
+}
+
+module.exports = {
+  printGovernanceDownloadMisses
+};

package/lib/governance/governance-run-display.js

@@ -16,7 +16,45 @@ const {
   formatBlockingError
 } = require('../utils/cli-test-layout-chalk');
 
-const SEP = '────────────────────────────────';
+const SEP = '────────────────────────';
+const MAX_SAMPLE_KEYS = 5;
+
+/**
+ * @param {Object|null|undefined} packDocument
+ * @returns {Map<string, { mustIncludeKeys: string[], mustExcludeKeys: string[] }>}
+ */
+function buildScenarioExpectMap(packDocument) {
+  const map = new Map();
+  const scenarios = packDocument?.spec?.scenarios;
+  if (!Array.isArray(scenarios)) {
+    return map;
+  }
+  for (const scenario of scenarios) {
+    if (!scenario || typeof scenario.id !== 'string') {
+      continue;
+    }
+    const expect = scenario.expect || {};
+    map.set(scenario.id, {
+      mustIncludeKeys: Array.isArray(expect.mustIncludeKeys) ? expect.mustIncludeKeys : [],
+      mustExcludeKeys: Array.isArray(expect.mustExcludeKeys) ? expect.mustExcludeKeys : []
+    });
+  }
+  return map;
+}
+
+/**
+ * @param {string[]} keys
+ * @param {number} [maxKeys]
+ * @returns {string}
+ */
+function formatKeySample(keys, maxKeys = MAX_SAMPLE_KEYS) {
+  if (!Array.isArray(keys) || keys.length === 0) {
+    return '—';
+  }
+  const slice = keys.slice(0, maxKeys);
+  const suffix = keys.length > maxKeys ? ` (+${keys.length - maxKeys} more)` : '';
+  return `${slice.join(', ')}${suffix}`;
+}
 
 /**
  * @param {'pass'|'fail'} status
@@ -28,38 +66,162 @@ function scenarioGlyph(status) {
 
 /**
  * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
- * @param {boolean} verbose
  */
-function logScenarioVerdict(scenario, verbose) {
-  logger.log(`  ${scenarioGlyph(scenario.status)} ${scenario.verdict}`);
-  if (!verbose) return;
-  logger.log(
-    metaGray(
-      `      Subject: ${scenario.subjectDisplayName} (${scenario.subjectUserId})`
-    )
-  );
-  if (scenario.subjectGroups && scenario.subjectGroups.length > 0) {
-    logger.log(metaGray(`      Groups: ${scenario.subjectGroups.join(', ')}`));
+function logGovernanceScenarioSubjectLines(scenario) {
+  logger.log(`  ${scenarioGlyph(scenario.status)} ${scenario.id}`);
+  logger.log(metaGray(`      Subject email:  ${scenario.subjectEmail || '—'}`));
+  if (scenario.subjectDisplayName) {
+    logger.log(
+      metaGray(
+        `      Subject:        ${scenario.subjectDisplayName} (${scenario.subjectUserId || '—'})`
+      )
+    );
   }
-  logger.log(
-    metaGray(
-      `      Visible keys: ${scenario.visibleKeyCount} · excluded ABAC: ${scenario.excludedAbac}` +
-        (scenario.auditRef ? ` · audit: ${scenario.auditRef}` : '')
-    )
-  );
-  if (scenario.unexpectedVisibleKeys && scenario.unexpectedVisibleKeys.length > 0) {
+  logger.log(metaGray(`      Verdict:        ${scenario.verdict || '—'}`));
+}
+
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
+ */
+function logGovernanceScenarioCounts(scenario) {
+  const visible = typeof scenario.visibleKeyCount === 'number' ? scenario.visibleKeyCount : 0;
+  const abac = typeof scenario.excludedAbac === 'number' ? scenario.excludedAbac : 0;
+  const filter = typeof scenario.excludedFilter === 'number' ? scenario.excludedFilter : 0;
+  logger.log(metaGray(`      Visible keys:   ${visible} allowed`));
+  logger.log(metaGray(`      Declined:       ${abac} by ABAC · ${filter} by filter`));
+}
+
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
+ * @param {{ mustIncludeKeys: string[], mustExcludeKeys: string[] }} expect
+ */
+function logGovernanceScenarioPassSamples(expect) {
+  const allowed =
+    expect.mustIncludeKeys.length > 0 ? formatKeySample(expect.mustIncludeKeys) : '—';
+  const blocked =
+    expect.mustExcludeKeys.length > 0 ? formatKeySample(expect.mustExcludeKeys) : '—';
+  logger.log(metaGray(`      Sample allowed: ${allowed}`));
+  logger.log(metaGray(`      Sample blocked: ${blocked}`));
+}
+
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
+ */
+function logGovernanceScenarioFailSamples(scenario) {
+  if (scenario.missingRequiredKeys?.length) {
     logger.log(
-      metaGray(`      Unexpected: ${scenario.unexpectedVisibleKeys.join(', ')}`)
+      metaGray(`      Missing keys:   ${formatKeySample(scenario.missingRequiredKeys)}`)
     );
   }
-  if (scenario.missingRequiredKeys && scenario.missingRequiredKeys.length > 0) {
-    logger.log(metaGray(`      Missing: ${scenario.missingRequiredKeys.join(', ')}`));
+  if (scenario.unexpectedVisibleKeys?.length) {
+    logger.log(
+      metaGray(`      Unexpected:     ${formatKeySample(scenario.unexpectedVisibleKeys)}`)
+    );
   }
   if (scenario.fixHint) {
-    logger.log(metaGray(`      Fix: ${scenario.fixHint}`));
+    logger.log(metaGray(`      Fix:            ${scenario.fixHint}`));
   }
 }
 
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
+ * @param {Map<string, { mustIncludeKeys: string[], mustExcludeKeys: string[] }>} expectMap
+ */
+function logGovernanceScenarioDetail(scenario, expectMap) {
+  const expect = expectMap.get(scenario.id) || {
+    mustIncludeKeys: [],
+    mustExcludeKeys: []
+  };
+  logGovernanceScenarioSubjectLines(scenario);
+  logGovernanceScenarioCounts(scenario);
+  if (scenario.status === 'pass') {
+    logGovernanceScenarioPassSamples(expect);
+  } else {
+    logGovernanceScenarioFailSamples(scenario);
+  }
+  if (scenario.subjectGroups?.length) {
+    logger.log(metaGray(`      Groups:         ${scenario.subjectGroups.join(', ')}`));
+  }
+  if (scenario.auditRef) {
+    logger.log(metaGray(`      Audit:          ${scenario.auditRef}`));
+  }
+}
+
+/**
+ * One datasource block for verify-governance -v.
+ * @param {Object} row
+ * @param {string} row.datasourceKey
+ * @param {Object} [row.result]
+ * @param {Object} [row.packDocument]
+ * @param {string} [row.packPath]
+ * @param {string} [row.error]
+ */
+function displayGovernanceDatasourceVerbose(row) {
+  logger.log('');
+  logger.log(chalk.white(`Datasource: ${row.datasourceKey}`));
+  if (row.error) {
+    logger.log(formatBlockingError(row.error));
+    return;
+  }
+  const run = row.result;
+  if (!run || !run.summary) {
+    logger.log(metaGray('  No scenario run result (pack missing or run skipped).'));
+    return;
+  }
+  logger.log(headerKeyValue('Pack:', run.packKey || '—'));
+  if (row.packPath) {
+    logger.log(metaGray(`  File: ${row.packPath}`));
+  }
+  const summary = run.summary;
+  logger.log(
+    headerKeyValue('Scenarios:', `${summary.passed || 0}/${summary.total || 0} passed`)
+  );
+  const expectMap = buildScenarioExpectMap(row.packDocument);
+  for (const scenario of run.scenarios || []) {
+    logGovernanceScenarioDetail(scenario, expectMap);
+  }
+}
+
+/**
+ * Verbose (-v) scenario breakdown for verify-governance / governance verify.
+ * @param {Object} result
+ */
+function displayGovernanceVerboseDetails(result) {
+  if (!result) {
+    return;
+  }
+  logger.log('');
+  logger.log(chalk.white('Scenario results'));
+  logger.log(metaGray(SEP));
+  logger.log(metaGray('Key sets only — no record payloads.'));
+
+  if (result.legacyResult && result.legacyResult.summary) {
+    const dsKey =
+      result.packDatasourceKey ||
+      primaryDatasourceFromPack(result.packDocument) ||
+      'scenario pack';
+    displayGovernanceDatasourceVerbose({
+      datasourceKey: dsKey,
+      result: result.legacyResult,
+      packDocument: result.packDocument,
+      packPath: result.packPath
+    });
+    logger.log('');
+    return;
+  }
+
+  const rows = result.datasourceRows || [];
+  if (rows.length === 0) {
+    logger.log(metaGray('  No datasource scenario packs were run.'));
+    logger.log('');
+    return;
+  }
+  for (const row of rows) {
+    displayGovernanceDatasourceVerbose(row);
+  }
+  logger.log('');
+}
+
 /**
  * @param {string} systemKey
  * @param {import('../api/types/governance-scenarios.types').GovernanceScenariosRunResponse} result
@@ -82,8 +244,13 @@ function displayGovernanceRunTTY(systemKey, result, opts = {}) {
   );
   logger.log(metaGray('  Does not call vendor APIs (use test-e2e for connectivity).'));
   logger.log('');
+  const expectMap = buildScenarioExpectMap(opts.packDocument);
   for (const scenario of result.scenarios || []) {
-    logScenarioVerdict(scenario, opts.verbose === true);
+    if (opts.verbose === true) {
+      logGovernanceScenarioDetail(scenario, expectMap);
+    } else {
+      logger.log(`  ${scenarioGlyph(scenario.status)} ${scenario.verdict}`);
+    }
   }
   logger.log('');
   if (agg === 'ok') {
@@ -112,8 +279,31 @@ function exitCodeFromGovernanceSummary(summary) {
   return 0;
 }
 
+/**
+ * @param {Object|null|undefined} packDocument
+ * @returns {string|null}
+ */
+function primaryDatasourceFromPack(packDocument) {
+  const scenarios = packDocument?.spec?.scenarios;
+  if (!Array.isArray(scenarios)) {
+    return null;
+  }
+  for (const scenario of scenarios) {
+    const keys = scenario?.search?.datasourceKeys;
+    if (Array.isArray(keys) && keys.length > 0 && typeof keys[0] === 'string') {
+      return keys[0];
+    }
+  }
+  return null;
+}
+
 module.exports = {
+  buildScenarioExpectMap,
+  formatKeySample,
+  displayGovernanceDatasourceVerbose,
+  displayGovernanceVerboseDetails,
   displayGovernanceRunTTY,
   printGovernanceRunJson,
-  exitCodeFromGovernanceSummary
+  exitCodeFromGovernanceSummary,
+  primaryDatasourceFromPack
 };

package/lib/identity/fk-reference.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Parse ForeignKeyReference objects from controller identity APIs (plan 194)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {string|Object|null|undefined} ref
+ * @returns {string}
+ */
+function readFkId(ref) {
+  if (typeof ref === 'string') {
+    return ref;
+  }
+  return String(ref?.id || '').trim();
+}
+
+/**
+ * @param {string|Object|null|undefined} ref
+ * @returns {string}
+ */
+function readFkKey(ref) {
+  if (typeof ref === 'string') {
+    return ref;
+  }
+  return String(ref?.key || '').trim();
+}
+
+/**
+ * @param {string|Object|null|undefined} ref
+ * @returns {string}
+ */
+function readFkName(ref) {
+  if (typeof ref === 'string') {
+    return '';
+  }
+  return String(ref?.name || '').trim();
+}
+
+/**
+ * @param {string|Object|null|undefined} ref
+ * @param {string} [fallback]
+ * @returns {string}
+ */
+function formatFkLabel(ref, fallback = '—') {
+  const name = readFkName(ref);
+  if (name) {
+    return name;
+  }
+  const key = readFkKey(ref);
+  if (key) {
+    return key;
+  }
+  const id = readFkId(ref);
+  return id || fallback;
+}
+
+module.exports = {
+  readFkId,
+  readFkKey,
+  readFkName,
+  formatFkLabel
+};

package/lib/identity/identity-apply-core.js

@@ -6,46 +6,13 @@
 
 'use strict';
 
-const { getUser, listUsers } = require('../api/users.api');
-
-/**
- * @param {Object} response
- * @returns {any}
- */
-function unwrapControllerData(response) {
-  if (!response || response.success === false) {
-    return null;
-  }
-  return response?.data?.data ?? response?.data ?? response;
-}
-
-/**
- * @param {Object} response
- * @returns {string}
- */
-function apiErrorMessage(response) {
-  if (!response) {
-    return 'Request failed';
-  }
-  const err = response.error;
-  if (typeof err === 'string') {
-    return err;
-  }
-  if (err && typeof err === 'object') {
-    return err.formattedError || err.message || err.error || 'Request failed';
-  }
-  return response.formattedError || response.message || 'Request failed';
-}
-
-/**
- * @param {Object} response
- * @throws {Error}
- */
-function throwIfApiFailed(response) {
-  if (!response || response.success === false) {
-    throw new Error(apiErrorMessage(response));
-  }
-}
+const { lookupUserByIdOrEmail } = require('./resolve-user-id');
+const { buildSyncStatsFailureMessage } = require('./identity-sync-errors');
+const {
+  unwrapControllerData,
+  apiErrorMessage,
+  throwIfApiFailed
+} = require('./identity-response-helpers');
 
 /**
  * @param {Object|null|undefined} stats
@@ -55,11 +22,7 @@ function throwIfApiFailed(response) {
 function assertSyncStatsOk(stats, opts = {}) {
   const syncErrors = Number(stats?.errors ?? 0);
   if (syncErrors > 0) {
-    throw new Error(
-      `Dataplane full sync reported ${syncErrors} error(s). ` +
-        `usersProcessed=${stats?.usersProcessed ?? 0} groupsProcessed=${stats?.groupsProcessed ?? 0}. ` +
-        'Check miso-controller logs for the sync request.'
-    );
+    throw new Error(buildSyncStatsFailureMessage(stats));
   }
   const processed = Number(stats?.usersProcessed ?? 0);
   if (processed === 0 && !opts.allowEmptySync) {
@@ -79,24 +42,16 @@ function assertSyncStatsOk(stats, opts = {}) {
 async function findExistingUser(controllerUrl, authConfig, userSpec) {
   const csvId = String(userSpec.csvId || '').trim();
   if (csvId) {
-    const byId = await getUser(controllerUrl, authConfig, csvId);
-    const row = unwrapControllerData(byId);
-    if (row && row.id) {
-      return row;
+    const byId = await lookupUserByIdOrEmail(controllerUrl, authConfig, csvId);
+    if (byId?.id) {
+      return byId;
     }
   }
   const email = String(userSpec.email || '').trim();
-  const listed = await listUsers(controllerUrl, authConfig, {
-    search: email,
-    pageSize: 10,
-    page: 1
-  });
-  const items = unwrapControllerData(listed);
-  const list = Array.isArray(items) ? items : items?.data;
-  if (!Array.isArray(list)) {
+  if (!email) {
     return null;
   }
-  return list.find((u) => String(u.email || '').toLowerCase() === email.toLowerCase()) || null;
+  return lookupUserByIdOrEmail(controllerUrl, authConfig, email);
 }
 
 module.exports = {

package/lib/identity/identity-apply-phases.js

@@ -18,6 +18,7 @@ const {
   apiErrorMessage,
   findExistingUser
 } = require('./identity-apply-core');
+const { resolveIdentityUsername } = require('./username-default');
 
 /**
  * @param {string} msg
@@ -75,7 +76,10 @@ async function ensureUser(controllerUrl, authConfig, userSpec, dryRun) {
     firstName: userSpec.firstName,
     lastName: userSpec.lastName,
     displayName: userSpec.displayName,
-    username: userSpec.username,
+    username: resolveIdentityUsername({
+      username: userSpec.username,
+      email: userSpec.email
+    }),
     status: 'active'
   };
   Object.keys(body).forEach((k) => {