@aifabrix/builder 2.50.0 → 2.51.1

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/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/upload-data-sync-finalize.js

@@ -27,7 +27,7 @@ async function finalizeUploadPublishResult(ctx, payload, options) {
     options,
     label: 'Upload data sync'
   });
-  return { ...ctx, dataSync };
+  return { ...ctx, dataSync, sidecar: ctx.sidecar || null };
 }
 
 /**
@@ -40,15 +40,16 @@ async function finishUnchangedUploadPublication(params) {
   if (!isQuietMinimalSync(options)) {
     logger.log(formatSuccessLine('Config unchanged on dataplane — upload skipped.'));
   }
-  await runUploadSidecarFollowups({
+  const sidecar = await runUploadSidecarFollowups({
     systemKey,
     options,
     payload,
     dataplaneUrl,
-    authConfig
+    authConfig,
+    environment
   });
   return finalizeUploadPublishResult(
-    { dataplaneUrl, authConfig, environment, uploadSkipped: true },
+    { dataplaneUrl, authConfig, environment, uploadSkipped: true, sidecar },
     payload,
     options
   );