@aifabrix/builder 2.49.2 → 2.51.0

package/lib/commands/role.js

@@ -0,0 +1,452 @@
+/**
+ * Business role commands (Controller).
+ *
+ * Commands:
+ * - aifabrix role create|import|export|get|list
+ *
+ * Distinct from `aifabrix identity role` (environment RBAC mappings).
+ *
+ * @fileoverview Business role CLI commands
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { normalizeControllerUrl, resolveEnvironment } = require('../core/config');
+const { getOrRefreshDeviceToken } = require('../utils/token-manager');
+const {
+  readRoleCreateFile,
+  readRoleCatalogFile,
+  writeRoleCatalogFile,
+  mapRoleFileToApiPayload,
+  mapRoleApiToFileRow
+} = require('../resolvers/role-file');
+const {
+  formatBlockingError,
+  formatSuccessLine,
+  infoLine,
+  headerKeyValue
+} = require('../utils/cli-layout-chalk');
+const { listRoles, getRole, createRoleIdempotent } = require('../api/roles.api');
+
+const ROLE_KEY_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+const ROLE_HELP_AFTER = `
+
+Examples:
+  $ aifabrix role create --key sales-manager --display-name "Sales Manager" --domain sales
+  $ aifabrix role get sales-manager
+  $ aifabrix role list --search sales
+
+Per-command help:  aifabrix role <command> --help
+`;
+
+const ROLE_IMPORT_HELP_AFTER = `
+
+Examples:
+  $ aifabrix role import --file ./baseline-roles.json
+`;
+
+const ROLE_EXPORT_HELP_AFTER = `
+
+Examples:
+  $ aifabrix role export --file ./roles-export.json
+`;
+
+const ROLE_CREATE_HELP_AFTER = `
+
+Examples:
+  $ aifabrix role create --key sales-manager --display-name "Sales Manager" --domain sales
+  $ aifabrix role create --key cfo --display-name "CFO" --domain finance --purpose "..." --business-outcome "..."
+  $ aifabrix role create --file ./sales-manager.json
+`;
+
+const ROLE_GET_HELP_AFTER = `
+
+Examples:
+  $ aifabrix role get sales-manager
+  $ aifabrix role get clx1234567890abcdef
+`;
+
+const ROLE_LIST_HELP_AFTER = `
+
+Examples:
+  $ aifabrix role list
+  $ aifabrix role list --page 1 --page-size 50
+  $ aifabrix role list --search sales
+`;
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+function requireRoleKey(raw) {
+  const key = String(raw || '').trim();
+  if (!key) {
+    throw new Error('Role key is required (--key <key> or --file <path>).');
+  }
+  if (!ROLE_KEY_PATTERN.test(key)) {
+    throw new Error(
+      'Role key must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.'
+    );
+  }
+  return key;
+}
+
+/**
+ * @param {Object} _options
+ * @returns {Promise<{ controllerUrl: string, authConfig: Object }>}
+ */
+async function resolveControllerAndAuth(_options) {
+  const controllerUrl = await resolveControllerUrl();
+  if (!controllerUrl) {
+    throw new Error('Controller URL is required. Run "aifabrix login" first.');
+  }
+  const normalized = normalizeControllerUrl(controllerUrl);
+  const deviceToken = await getOrRefreshDeviceToken(normalized);
+  if (!deviceToken || !deviceToken.token) {
+    throw new Error(
+      `Not authenticated for controller: ${controllerUrl}. ` +
+        'Run "aifabrix login" and try again.'
+    );
+  }
+  return {
+    controllerUrl: deviceToken.controller || normalized,
+    authConfig: { type: 'bearer', token: deviceToken.token }
+  };
+}
+
+async function resolveHeaderContext() {
+  const env = await resolveEnvironment();
+  const controllerUrl = await resolveControllerUrl();
+  const normalized = normalizeControllerUrl(controllerUrl);
+  return { environment: env || 'dev', controllerUrl: normalized };
+}
+
+/**
+ * @param {Object} response
+ * @returns {any}
+ */
+function unwrapControllerData(response) {
+  return response?.data?.data ?? response?.data ?? response;
+}
+
+/**
+ * @param {Object|null|undefined} response
+ * @param {string} label
+ * @returns {void}
+ */
+function assertControllerListSuccess(response, label) {
+  if (response && response.success !== false) {
+    return;
+  }
+  const message =
+    response?.formattedError || response?.error || `Failed to list ${label}`;
+  throw new Error(message);
+}
+
+/**
+ * Extract items from a Controller paginated list response.
+ * @param {Object} response
+ * @returns {Object[]}
+ */
+function extractControllerListItems(response) {
+  if (response?.data && Array.isArray(response.data.data)) {
+    return response.data.data;
+  }
+  const unwrapped = unwrapControllerData(response);
+  if (Array.isArray(unwrapped)) {
+    return unwrapped;
+  }
+  if (unwrapped && Array.isArray(unwrapped.data)) {
+    return unwrapped.data;
+  }
+  throw new Error('Unexpected list response from controller');
+}
+
+/**
+ * Build create payload from flags and optional --file (maps domain → domainKey).
+ * @param {Object} options
+ * @returns {Object}
+ */
+function buildCreatePayload(options) {
+  let base = {};
+  if (options.file) {
+    base = readRoleCreateFile(options.file);
+  }
+  const merged = { ...base };
+  if (options.key) merged.key = options.key;
+  if (options.displayName) merged.displayName = options.displayName;
+  if (options.description !== undefined) merged.description = options.description;
+  if (options.purpose !== undefined) merged.purpose = options.purpose;
+  if (options.businessOutcome !== undefined) merged.businessOutcome = options.businessOutcome;
+  if (options.domain) {
+    merged.domain = options.domain;
+    delete merged.domainKey;
+  }
+  if (options.file && !options.domain && base.domainKey) {
+    return { ...base, key: requireRoleKey(merged.key || base.key) };
+  }
+  const payload = mapRoleFileToApiPayload(
+    {
+      ...merged,
+      domain: merged.domain || merged.domainKey
+    },
+    0
+  );
+  payload.key = requireRoleKey(payload.key);
+  return payload;
+}
+
+/**
+ * @param {Object[]} rows
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @returns {Promise<{ created: number, existed: number, total: number }>}
+ */
+async function importRoleRows(rows, controllerUrl, authConfig) {
+  let created = 0;
+  let existed = 0;
+  for (const payload of rows) {
+    payload.key = requireRoleKey(payload.key);
+    const out = await createRoleIdempotent(controllerUrl, authConfig, payload);
+    if (out.created) {
+      created += 1;
+      continue;
+    }
+    existed += 1;
+  }
+  return { created, existed, total: rows.length };
+}
+
+/**
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @returns {Promise<Object[]>}
+ */
+async function fetchAllRoles(controllerUrl, authConfig) {
+  const all = [];
+  let page = 1;
+  const pageSize = 100;
+  for (;;) {
+    const res = await listRoles(controllerUrl, authConfig, { page, pageSize });
+    assertControllerListSuccess(res, 'roles');
+    const items = extractControllerListItems(res);
+    if (items.length === 0) {
+      break;
+    }
+    all.push(...items);
+    if (items.length < pageSize) {
+      break;
+    }
+    page += 1;
+  }
+  return all;
+}
+
+function setupRoleImportCommand(role) {
+  role
+    .command('import')
+    .description('Import business roles from baseline JSON (idempotent)')
+    .addHelpText('after', ROLE_IMPORT_HELP_AFTER)
+    .requiredOption('--file <path>', 'Baseline catalog (roles[]) or JSON array')
+    .action(async(options) => {
+      try {
+        const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+        const rows = readRoleCatalogFile(options.file);
+        const summary = await importRoleRows(rows, controllerUrl, authConfig);
+        logger.log(
+          formatSuccessLine(
+            `Roles imported: ${summary.total} total ` +
+              `(${summary.created} created, ${summary.existed} already existed)`
+          )
+        );
+      } catch (e) {
+        logger.error(formatBlockingError(e.message));
+        process.exit(1);
+      }
+    });
+}
+
+function setupRoleExportCommand(role) {
+  role
+    .command('export')
+    .description('Export business roles to baseline-shaped JSON')
+    .addHelpText('after', ROLE_EXPORT_HELP_AFTER)
+    .requiredOption('--file <path>', 'Output path for baseline catalog JSON')
+    .action(async(options) => {
+      try {
+        const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+        const records = await fetchAllRoles(controllerUrl, authConfig);
+        const rows = records.map(mapRoleApiToFileRow);
+        writeRoleCatalogFile(options.file, rows);
+        if (rows.length === 0) {
+          logger.log(
+            infoLine(
+              'No business roles on the controller. Create or import roles, then re-run export.'
+            )
+          );
+        }
+        logger.log(formatSuccessLine(`Roles exported: ${rows.length} written to ${options.file}`));
+      } catch (e) {
+        logger.error(formatBlockingError(e.message));
+        process.exit(1);
+      }
+    });
+}
+
+function setupRoleCreateCommand(role) {
+  role
+    .command('create')
+    .description('Create business role (idempotent; success if it already exists)')
+    .addHelpText('after', ROLE_CREATE_HELP_AFTER)
+    .option('--file <path>', 'Read role create payload from JSON file')
+    .option('--key <key>', 'Catalog key (lowercase letters, digits, hyphens)')
+    .option('--display-name <name>', 'Display name')
+    .option('--domain <domain>', 'Enterprise domain key (e.g. sales, finance, platform)')
+    .option('--purpose <text>', 'Role purpose')
+    .option('--business-outcome <text>', 'Business outcome')
+    .option('--description <text>', 'Description')
+    .action(async(options) => {
+      try {
+        const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+        const payload = buildCreatePayload(options);
+        const out = await createRoleIdempotent(controllerUrl, authConfig, payload);
+        const row = unwrapControllerData(out.response);
+        const domain = row.domainKey || payload.domainKey || '—';
+        if (out.created) {
+          logger.log(formatSuccessLine(`Role created: ${row.key} (domain: ${domain})`));
+          return;
+        }
+        logger.log(formatSuccessLine(`Role exists: ${row.key} (domain: ${domain})`));
+        logger.log(infoLine('No changes were needed.'));
+      } catch (e) {
+        logger.error(formatBlockingError(e.message));
+        process.exit(1);
+      }
+    });
+}
+
+function setupRoleGetCommand(role) {
+  role
+    .command('get <roleIdOrKey>')
+    .description('Get business role by id or key')
+    .addHelpText('after', ROLE_GET_HELP_AFTER)
+    .action(async(roleIdOrKey, options) => {
+      try {
+        const { environment, controllerUrl: headerControllerUrl } = await resolveHeaderContext();
+        const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+        const res = await getRole(controllerUrl, authConfig, String(roleIdOrKey).trim());
+        const row = unwrapControllerData(res);
+        logger.log(
+          chalk.bold(`\n👤  Business role 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('Active:', row.isActive === false ? 'false' : 'true'));
+        if (row.purpose) logger.log(headerKeyValue('Purpose:', row.purpose));
+        if (row.businessOutcome) logger.log(headerKeyValue('Business outcome:', row.businessOutcome));
+        if (row.description) logger.log(headerKeyValue('Description:', row.description));
+        logger.log('');
+      } catch (e) {
+        logger.error(formatBlockingError(e.message));
+        process.exit(1);
+      }
+    });
+}
+
+const ROLE_LIST_COLUMNS = { key: 28, display: 28, domain: 14, active: 8 };
+
+function logRoleListHeader(columns) {
+  const keyCol = 'Key'.padEnd(columns.key);
+  const displayCol = 'Display'.padEnd(columns.display);
+  const domainCol = 'Domain'.padEnd(columns.domain);
+  const activeCol = 'Active'.padEnd(columns.active);
+  logger.log(chalk.gray(`${keyCol}${displayCol}${domainCol}${activeCol}`));
+  logger.log(
+    chalk.gray('-'.repeat(columns.key + columns.display + columns.domain + columns.active))
+  );
+}
+
+function logRoleListRows(items, columns) {
+  items.forEach((d) => {
+    const key = (d?.key ?? '—').toString().padEnd(columns.key);
+    const displayName = (d?.displayName ?? '—').toString().padEnd(columns.display);
+    const domain = (d?.domainKey ?? '—').toString().padEnd(columns.domain);
+    const active = (d?.isActive === false ? 'false' : 'true').padEnd(columns.active);
+    logger.log(`${key}${displayName}${domain}${active}`);
+  });
+}
+
+function displayRoleList(items, environment, controllerUrl) {
+  logger.log(chalk.bold(`\n👤  Business roles in ${environment} environment (${controllerUrl}):\n`));
+  if (!Array.isArray(items) || items.length === 0) {
+    logger.log(chalk.gray('  No business roles found.\n'));
+    return;
+  }
+  logRoleListHeader(ROLE_LIST_COLUMNS);
+  logRoleListRows(items, ROLE_LIST_COLUMNS);
+  logger.log('');
+}
+
+function setupRoleListCommand(role) {
+  role
+    .command('list')
+    .description('List business roles')
+    .addHelpText('after', ROLE_LIST_HELP_AFTER)
+    .option('--page <n>', 'Page', (v) => parseInt(v, 10))
+    .option('--page-size <n>', 'Page size', (v) => parseInt(v, 10))
+    .option('--search <text>', 'Search by key/displayName/description')
+    .option('--domain-key <domain>', 'Filter by domain key')
+    .action(async(options) => {
+      try {
+        const { environment, controllerUrl: headerControllerUrl } = await resolveHeaderContext();
+        const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+        const res = await listRoles(controllerUrl, authConfig, {
+          page: options.page,
+          pageSize: options.pageSize,
+          search: options.search,
+          domainKey: options.domainKey
+        });
+        assertControllerListSuccess(res, 'roles');
+        const items = extractControllerListItems(res);
+        displayRoleList(items, environment, headerControllerUrl);
+      } catch (e) {
+        logger.error(formatBlockingError(e.message));
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupRoleCommands(program) {
+  const role = program
+    .command('role')
+    .description('Manage the Controller Role Catalog (COM)')
+    .addHelpText('after', ROLE_HELP_AFTER);
+  setupRoleCreateCommand(role);
+  setupRoleImportCommand(role);
+  setupRoleExportCommand(role);
+  setupRoleGetCommand(role);
+  setupRoleListCommand(role);
+}
+
+module.exports = {
+  setupRoleCommands,
+  requireRoleKey,
+  buildCreatePayload,
+  unwrapControllerData,
+  assertControllerListSuccess,
+  extractControllerListItems,
+  importRoleRows,
+  fetchAllRoles,
+  mapRoleFileToApiPayload,
+  mapRoleApiToFileRow
+};

package/lib/commands/run-post-publish-data-sync.js

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Post-publish/deploy datasource data sync hook.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { resolveSyncPlan, executeSyncPlan } = require('./datasource-sync-policy');
+const { logDatasourceSyncSummary } = require('./datasource-sync-display');
+
+/**
+ * @param {string[]} datasourceKeys
+ * @param {Object|null|undefined} payload
+ * @returns {string[]}
+ */
+function extractDatasourceKeysFromPayload(payload, datasourceKeys) {
+  if (Array.isArray(datasourceKeys) && datasourceKeys.length > 0) {
+    return datasourceKeys;
+  }
+  const fromPayload = Array.isArray(payload?.dataSources)
+    ? payload.dataSources.map((row) => row && row.key).filter(Boolean)
+    : [];
+  return fromPayload;
+}
+
+/**
+ * @async
+ * @param {Object} params
+ * @param {string[]} [params.datasourceKeys]
+ * @param {Object} [params.payload]
+ * @param {string} params.dataplaneUrl
+ * @param {Object} params.authConfig
+ * @param {Object} [params.options]
+ * @param {string} [params.label]
+ * @returns {Promise<Object|null>}
+ */
+async function runPostPublishDataSync(params) {
+  const { dataplaneUrl, authConfig, payload, options = {}, label } = params;
+  if (!dataplaneUrl || !authConfig || options.dryRun === true || options.skipDataSync === true) {
+    return null;
+  }
+
+  const keys = extractDatasourceKeysFromPayload(payload, params.datasourceKeys);
+  if (keys.length === 0) {
+    return null;
+  }
+
+  const plan = await resolveSyncPlan({
+    syncExplicit: options.sync === true,
+    skipSync: options.skipDataSync === true,
+    datasourceKeys: keys,
+    dataplaneUrl,
+    authConfig
+  });
+  const result = await executeSyncPlan(plan, dataplaneUrl, authConfig);
+  logDatasourceSyncSummary(result, {
+    json: options.json === true,
+    label,
+    syncExplicit: options.sync === true
+  });
+  return result;
+}
+
+module.exports = {
+  runPostPublishDataSync,
+  extractDatasourceKeysFromPayload
+};

package/lib/commands/setup-modes.js

@@ -58,7 +58,7 @@ const {
 } = require('../utils/infra-optional-service-flags');
 
 /** Builder app keys touched by `up-platform --force`. */
-const PLATFORM_APPS = ['keycloak', 'miso-controller', 'dataplane'];
+const PLATFORM_APPS = ['keycloak', 'miso-controller', 'dataplane', 'builder-api'];
 
 function formatBackupSuffix() {
   const d = new Date();

package/lib/commands/setup.js

@@ -291,7 +291,7 @@ async function appendSetupInstallationRecord(payload) {
 async function handleSetup(options = {}) {
   const assumeYes = options.yes === true || options.assumeYes === true;
   const startedAt = new Date();
-  let outcome = 'success';
+  let outcome;
   let setupMode = null;
   let err = null;
 

package/lib/commands/test-e2e-external.js

@@ -13,12 +13,12 @@ const path = require('path');
 const fs = require('fs');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
-const { getIntegrationPath } = require('../utils/paths');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadConfigFile } = require('../utils/config-format');
 const { discoverIntegrationFiles, buildEffectiveDatasourceFiles } = require('./repair-internal');
 const { runDatasourceTestE2E } = require('../datasource/test-e2e');
-const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
 const { buildMinimalUploadSyncOptions, isQuietMinimalSync } = require('../utils/upload-sync-options');
 const { getConfig } = require('../core/config');
 const { setupIntegrationTestAuth } = require('../external-system/test-auth');
@@ -90,15 +90,26 @@ function getDatasourceKeys(appPath, configPath, variables, systemKey, systemPars
 
 /**
  * Publish local integration files to the dataplane before E2E (same path as `aifabrix upload <systemKey>`),
- * unless ``options.noSync`` is true.
+ * unless ``options.noPublish`` is true.
  * @param {string} systemKey
  * @param {Object} options
  * @returns {Promise<{ authConfig: Object, dataplaneUrl: string, environment?: string }|null>}
  */
 async function syncLocalIfRequested(systemKey, options) {
-  if (cliOptsSkipSync(options)) return null;
+  if (cliOptsSkipPublish(options)) return null;
   const { uploadExternalSystem } = require('./upload');
-  const uploadOpts = buildMinimalUploadSyncOptions(options);
+  const uploadOpts = {
+    ...buildMinimalUploadSyncOptions(options),
+    uploadStatus: options.uploadStatus === 'published' ? 'published' : 'draft',
+    pathOptions: {},
+    ...(options.authConfig && options.dataplaneUrl
+      ? {
+        authConfig: options.authConfig,
+        dataplaneUrl: options.dataplaneUrl,
+        environment: options.environment
+      }
+      : {})
+  };
   const uploadCtx = await uploadExternalSystem(systemKey, uploadOpts);
   if (uploadCtx?.uploadSkipped !== true && !isQuietMinimalSync(uploadOpts)) {
     logger.log(formatSuccessLine('Sync complete'));
@@ -117,7 +128,7 @@ async function syncLocalIfRequested(systemKey, options) {
  * @param {boolean} [options.debug] - Include debug, write log
  * @param {boolean} [options.verbose] - Verbose output
  * @param {boolean} [options.async] - If false, sync mode (default true)
- * @param {boolean} [options.noSync] - When true, skip upload (E2E uses dataplane config already deployed)
+ * @param {boolean} [options.noPublish] - When true, skip upload (E2E uses dataplane config already deployed)
  * @returns {Promise<{ success: boolean, results: Array<{ key: string, success: boolean, error?: string }> }>}
  */
 /**
@@ -125,11 +136,11 @@ async function syncLocalIfRequested(systemKey, options) {
  * @param {string} externalSystem
  * @returns {{ systemKey: string, keys: string[] }}
  */
-function resolveExternalIntegrationContext(externalSystem) {
+function resolveExternalIntegrationContext(externalSystem, pathOptions = {}) {
   if (!externalSystem || typeof externalSystem !== 'string') {
     throw new Error('External system name is required');
   }
-  const appPath = getIntegrationPath(externalSystem);
+  const appPath = resolveExternalSystemPath(externalSystem, pathOptions);
   if (!fs.existsSync(appPath)) {
     throw new Error(`Integration path not found: ${appPath}`);
   }
@@ -199,6 +210,8 @@ async function runTestE2EForExternalSystem(externalSystem, options = {}) {
     debug: options.debug,
     verbose: options.verbose,
     async: options.async !== false,
+    version: options.version,
+    syncMode: options.syncMode,
     authConfig,
     dataplaneUrl,
     quietPollUi: options.quietPollUi === true,

package/lib/commands/test-governance-cli-options.js

@@ -6,7 +6,7 @@
 
 'use strict';
 
-const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
 
 /**
  * @param {string[]} [raw]
@@ -34,7 +34,7 @@ function normalizeTestGovernanceCliOptions(options, cmd) {
     env: options.env || 'dev',
     verbose: options.verbose === true || has('-v') || has('--verbose'),
     json: options.json === true || has('--json'),
-    noSync: cliOptsSkipSync(options, cmd),
+    noPublish: cliOptsSkipPublish(options, cmd),
     pack: options.pack,
     app: options.app,
     scenarioIds: collectScenarioIds(options.scenario)

package/lib/commands/test-trust-cli-options.js

@@ -4,7 +4,7 @@
 
 'use strict';
 
-const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
 
 /**
  * @param {Object} options - Commander-parsed options
@@ -19,7 +19,7 @@ function normalizeTestTrustCliOptions(options, cmd) {
     debug: options.debug === true || has('-d') || has('--debug'),
     verbose: options.verbose === true || has('-v') || has('--verbose'),
     revalidate: options.revalidate === true || has('--revalidate'),
-    noSync: cliOptsSkipSync(options, cmd),
+    noPublish: cliOptsSkipPublish(options, cmd),
     strict: options.strict === true || has('--strict'),
     summary: options.summary === true || has('--summary'),
     json: options.json === true || has('--json'),