@aifabrix/builder 2.46.0 → 2.47.1

package/lib/external-system/test.js

@@ -7,7 +7,6 @@
  */
 /* eslint-disable max-lines,max-lines-per-function,max-statements,complexity,max-depth -- Integration test flow with system-level and per-datasource paths */
 
-const fs = require('fs').promises;
 const fsSync = require('fs');
 const path = require('path');
 const chalk = require('chalk');
@@ -69,15 +68,15 @@ async function loadVariablesYamlFile(variablesPath) {
 }
 
 /**
- * Loads a single JSON file
+ * Loads a single integration config file (JSON, YAML, or YML).
  * @async
- * @function loadJsonFile
- * @param {string} filePath - Path to JSON file
+ * @function loadIntegrationConfigFile
+ * @param {string} filePath - Path to config file
  * @param {string} fileName - File name for error messages
- * @returns {Promise<Object>} Parsed JSON data
- * @throws {Error} If file not found or invalid JSON
+ * @returns {Promise<Object>} Parsed config object
+ * @throws {Error} If file not found or invalid format
  */
-async function loadJsonFile(filePath, fileName) {
+async function loadIntegrationConfigFile(filePath, fileName) {
   if (!fsSync.existsSync(filePath)) {
     // Use "System file not found" for system files to match test expectations
     if (fileName.includes('system') || fileName.includes('deploy')) {
@@ -86,12 +85,8 @@ async function loadJsonFile(filePath, fileName) {
     throw new Error(`${fileName} not found: ${filePath}`);
   }
 
-  const content = await fs.readFile(filePath, 'utf8');
-  try {
-    return JSON.parse(content);
-  } catch (error) {
-    throw new Error(`Invalid JSON syntax in ${fileName}: ${error.message}`);
-  }
+  const { loadConfigFile } = require('../utils/config-format');
+  return loadConfigFile(filePath);
 }
 
 /**
@@ -121,7 +116,7 @@ async function loadSystemFiles(systemFiles, schemaBasePath, appPath) {
   const systemJsonFiles = [];
   for (const systemFile of systemFiles) {
     const systemPath = resolveFilePath(schemaBasePath, appPath, systemFile);
-    const systemJson = await loadJsonFile(systemPath, systemFile);
+    const systemJson = await loadIntegrationConfigFile(systemPath, systemFile);
     systemJsonFiles.push({ path: systemPath, data: systemJson });
   }
   return systemJsonFiles;
@@ -140,7 +135,7 @@ async function loadDatasourceFiles(datasourceFiles, schemaBasePath, appPath) {
   const datasourceJsonFiles = [];
   for (const datasourceFile of datasourceFiles) {
     const datasourcePath = resolveFilePath(schemaBasePath, appPath, datasourceFile);
-    const datasourceJson = await loadJsonFile(datasourcePath, datasourceFile);
+    const datasourceJson = await loadIntegrationConfigFile(datasourcePath, datasourceFile);
     datasourceJsonFiles.push({ path: datasourcePath, data: datasourceJson });
   }
   return datasourceJsonFiles;

package/lib/generator/builders.js

@@ -267,6 +267,15 @@ function validateBuildFields(build) {
   if (build.dockerfile && build.dockerfile.trim()) {
     buildConfig.dockerfile = build.dockerfile;
   }
+  if (build.worker === true) {
+    buildConfig.worker = true;
+  }
+  if (typeof build.imageRunWorker === 'string' && build.imageRunWorker.trim()) {
+    buildConfig.imageRunWorker = build.imageRunWorker.trim();
+  }
+  if (typeof build.imageRunBeat === 'string' && build.imageRunBeat.trim()) {
+    buildConfig.imageRunBeat = build.imageRunBeat.trim();
+  }
 
   return Object.keys(buildConfig).length > 0 ? buildConfig : null;
 }
@@ -390,6 +399,7 @@ module.exports = {
   buildOptionalFields,
   buildManifestStructure,
   filterConfigurationByRegistryMode,
-  sanitizeAuthType
+  sanitizeAuthType,
+  validateBuildFields
 };
 

package/lib/generator/external-controller-manifest.js

@@ -27,11 +27,14 @@ const { loadVariables, loadRbac } = require('./helpers');
  * @param {Object} systemJson - System JSON object (mutated in place)
  */
 function normalizeLegacyAuthMethod(systemJson) {
+  const { getAuthCredentialTemplate } = require('../utils/authentication-shape');
   const auth = systemJson && systemJson.authentication;
   if (!auth || typeof auth !== 'object') return;
-  const method = String(auth.method || '').trim().toLowerCase();
+  const credential = getAuthCredentialTemplate(auth);
+  if (!credential) return;
+  const method = String(credential.method || '').trim().toLowerCase();
   if (method === 'bearerkey') {
-    auth.method = 'bearerToken';
+    credential.method = 'bearerToken';
   }
 }
 

package/lib/generator/split.js

@@ -453,6 +453,8 @@ module.exports = {
   extractVariablesYaml,
   extractRbacYaml,
   parseImageReference,
-  generateReadmeFromDeployJson
+  generateReadmeFromDeployJson,
+  mergeEnvTemplateWithExisting,
+  buildEnvTemplateExpectedByKey
 };
 

package/lib/generator/wizard.js

@@ -32,34 +32,7 @@ function toKeySegment(str) {
   return sanitized || 'default';
 }
 
-/**
- * Align authentication.security kv:// namespaces and credentialKey with the final system key.
- * Dataplane normalizes this before respond; when appName overrides a spec-derived key (e.g.
- * OpenAPI title "Companies"), the builder still must rewrite nested auth so it matches env.template.
- *
- * @param {Object|null|undefined} authentication - authentication block from dataplane
- * @param {string} systemKey - Final external system key (integration app name)
- * @param {string} [authDisplayName] - Credential display name (typically title-cased app name)
- */
-function normalizeAuthenticationToSystemKey(authentication, systemKey, authDisplayName) {
-  if (!authentication || typeof authentication !== 'object') return;
-  authentication.credentialKey = `${systemKey}-cred`;
-  const security = authentication.security;
-  if (security && typeof security === 'object') {
-    for (const k of Object.keys(security)) {
-      const v = security[k];
-      if (typeof v === 'string' && v.startsWith('kv://')) {
-        const rest = v.slice(5);
-        const idx = rest.indexOf('/');
-        const suffix = idx >= 0 ? rest.slice(idx + 1) : '';
-        security[k] = suffix ? `kv://${systemKey}/${suffix}` : `kv://${systemKey}`;
-      }
-    }
-  }
-  if (authDisplayName) {
-    authentication.displayName = authDisplayName;
-  }
-}
+const { normalizeAuthenticationToSystemKey } = require('../utils/authentication-shape');
 
 /**
  * Generate files from dataplane-generated wizard configurations

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) => {

package/lib/identity/identity-display.js

@@ -0,0 +1,243 @@
+/**
+ * @fileoverview TTY layout helpers for aifabrix identity commands (plan 151)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const {
+  formatBlockingError,
+  formatNextActions,
+  headerKeyValue,
+  sectionTitle
+} = require('../utils/cli-layout-chalk');
+const { readFkId, readFkKey, readFkName, formatFkLabel } = require('./fk-reference');
+const { unwrapControllerData } = require('./identity-response-helpers');
+
+/**
+ * @param {Object|null|undefined} response
+ * @returns {{ items: Object[], meta: Object|null }}
+ */
+function extractPaginatedList(response) {
+  if (!response || response.success === false) {
+    return { items: [], meta: null };
+  }
+  const body = response.data;
+  if (body && Array.isArray(body.data)) {
+    return { items: body.data, meta: body.meta ?? null };
+  }
+  const unwrapped = unwrapControllerData(response);
+  if (Array.isArray(unwrapped)) {
+    return { items: unwrapped, meta: null };
+  }
+  if (unwrapped && Array.isArray(unwrapped.data)) {
+    return { items: unwrapped.data, meta: unwrapped.meta ?? null };
+  }
+  return { items: [], meta: null };
+}
+
+/**
+ * @param {Object} user
+ * @returns {string}
+ */
+function formatUserDisplayName(user) {
+  const display = String(user?.displayName || '').trim();
+  if (display) {
+    return display;
+  }
+  const parts = [user?.firstName, user?.lastName].filter(Boolean).map(String);
+  const joined = parts.join(' ').trim();
+  return joined || '—';
+}
+
+/**
+ * @param {string} value
+ * @param {number} width
+ * @returns {string}
+ */
+function padCell(value, width) {
+  const text = String(value ?? '—');
+  if (text.length <= width) {
+    return text.padEnd(width);
+  }
+  if (width <= 1) {
+    return text.slice(0, width);
+  }
+  return `${text.slice(0, width - 1)}…`;
+}
+
+/**
+ * @param {{ emoji?: string, title: string, context?: string, shown?: number, total?: number|null }} opts
+ */
+function printIdentityListHeader(opts) {
+  const emoji = opts.emoji ? `${opts.emoji} ` : '';
+  const context = opts.context ? ` (${opts.context})` : '';
+  const shown = Number.isFinite(opts.shown) ? opts.shown : 0;
+  const total = Number.isFinite(opts.total) ? opts.total : null;
+  const count =
+    total !== null && total >= shown ? `${shown} shown of ${total}` : `${shown} shown`;
+  logger.log(chalk.bold(`\n${emoji}${opts.title}${context} — ${count}:\n`));
+}
+
+/**
+ * @param {Array<{ label: string, width: number, value: (row: Object) => string }>} columns
+ * @param {Object[]} rows
+ */
+function printIdentityTable(columns, rows) {
+  const header = columns.map((col) => padCell(col.label, col.width)).join('');
+  logger.log(chalk.gray(header));
+  logger.log(chalk.gray('-'.repeat(columns.reduce((sum, col) => sum + col.width, 0))));
+  rows.forEach((row) => {
+    const line = columns.map((col) => padCell(col.value(row), col.width)).join('');
+    logger.log(line);
+  });
+  logger.log('');
+}
+
+/**
+ * @param {Object|null|undefined} meta
+ */
+function printListPaginationFooter(meta) {
+  if (!meta || !Number.isFinite(meta.totalItems)) {
+    return;
+  }
+  const page = meta.currentPage ?? meta.page ?? 1;
+  const pageSize = meta.pageSize ?? meta.page_size;
+  const totalPages = meta.totalPages ?? meta.total_pages;
+  const parts = [`total ${meta.totalItems}`];
+  if (pageSize) {
+    parts.unshift(`page ${page}`);
+  }
+  if (totalPages) {
+    parts.push(`${totalPages} pages`);
+  }
+  logger.log(chalk.gray(`  ${parts.join(' · ')}\n`));
+}
+
+/**
+ * @param {string} title
+ * @param {Array<{ label: string, value: string }>} fields
+ */
+function printIdentityRecord(title, fields) {
+  logger.log(sectionTitle(title));
+  fields.forEach(({ label, value }) => {
+    logger.log(`  ${headerKeyValue(`${label}:`, value || '—')}`);
+  });
+  logger.log('');
+}
+
+/**
+ * @param {string} message
+ * @param {string[]} [hints]
+ */
+function printIdentityEmpty(message, hints = []) {
+  logger.log(chalk.gray(`  ${message}\n`));
+  if (hints.length > 0) {
+    logger.log(formatNextActions(hints));
+    logger.log('');
+  }
+}
+
+/**
+ * @param {string} entity
+ * @param {string} query
+ * @param {string[]} [hints]
+ */
+function printIdentityNotFound(entity, query, hints = []) {
+  logger.error(formatBlockingError(`${entity} not found: ${query}`));
+  if (hints.length > 0) {
+    logger.log(formatNextActions(hints));
+  }
+}
+
+const USER_LIST_COLUMNS = [
+  { label: 'Id', width: 38, value: (u) => u.id || '—' },
+  { label: 'Username', width: 16, value: (u) => u.username || '—' },
+  { label: 'Name', width: 22, value: (u) => formatUserDisplayName(u) },
+  { label: 'Email', width: 34, value: (u) => u.email || '—' },
+  { label: 'Status', width: 10, value: (u) => u.status || '—' }
+];
+
+const GROUP_LIST_COLUMNS = [
+  { label: 'Id', width: 38, value: (g) => g.id || '—' },
+  { label: 'Name', width: 28, value: (g) => g.name || '—' },
+  { label: 'Display name', width: 28, value: (g) => g.displayName || '—' }
+];
+
+/**
+ * @param {Object[]} memberships
+ */
+function printUserGroupsTable(memberships) {
+  printIdentityTable(
+    [
+      { label: 'Group key', width: 28, value: (m) => readFkKey(m.groupId) || '—' },
+      { label: 'Group name', width: 28, value: (m) => formatFkLabel(m.groupId) },
+      { label: 'Group id', width: 38, value: (m) => readFkId(m.groupId) || '—' },
+      { label: 'Role hint', width: 12, value: (m) => m.roleHint || '—' }
+    ],
+    memberships
+  );
+}
+
+/**
+ * @param {Object[]} memberships
+ */
+function printGroupMembersTable(memberships) {
+  printIdentityTable(
+    [
+      { label: 'User key', width: 22, value: (m) => readFkKey(m.userId) || '—' },
+      { label: 'User name', width: 24, value: (m) => formatFkLabel(m.userId) },
+      { label: 'User id', width: 38, value: (m) => readFkId(m.userId) || '—' },
+      { label: 'Role hint', width: 12, value: (m) => m.roleHint || '—' }
+    ],
+    memberships
+  );
+}
+
+/**
+ * @param {Object} user
+ */
+function printUserRecord(user) {
+  printIdentityRecord('User', [
+    { label: 'Id', value: user.id },
+    { label: 'Email', value: user.email },
+    { label: 'Username', value: user.username },
+    { label: 'Name', value: formatUserDisplayName(user) },
+    { label: 'Display name', value: user.displayName },
+    { label: 'Status', value: user.status },
+    { label: 'Verified', value: user.emailVerified ? 'yes' : 'no' }
+  ]);
+}
+
+/**
+ * @param {Object} group
+ */
+function printGroupRecord(group) {
+  printIdentityRecord('Group', [
+    { label: 'Id', value: group.id },
+    { label: 'Name', value: group.name },
+    { label: 'Display name', value: group.displayName },
+    { label: 'Description', value: group.description }
+  ]);
+}
+
+module.exports = {
+  extractPaginatedList,
+  formatUserDisplayName,
+  printIdentityListHeader,
+  printIdentityTable,
+  printListPaginationFooter,
+  printIdentityRecord,
+  printIdentityEmpty,
+  printIdentityNotFound,
+  USER_LIST_COLUMNS,
+  GROUP_LIST_COLUMNS,
+  printUserGroupsTable,
+  printGroupMembersTable,
+  printUserRecord,
+  printGroupRecord,
+  readFkName
+};

package/lib/identity/identity-response-helpers.js

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Shared controller response helpers for identity modules
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @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));
+  }
+}
+
+module.exports = {
+  unwrapControllerData,
+  apiErrorMessage,
+  throwIfApiFailed
+};

package/lib/identity/identity-sync-errors.js

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview User-facing identity sync failure messages
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Object|null|undefined} stats
+ * @returns {boolean}
+ */
+function isZeroProgressSyncFailure(stats) {
+  const usersProcessed = Number(stats?.usersProcessed ?? 0);
+  const groupsProcessed = Number(stats?.groupsProcessed ?? 0);
+  return usersProcessed === 0 && groupsProcessed === 0;
+}
+
+/**
+ * Build a multi-line CLI message when controller sync stats report errors.
+ *
+ * @param {Object|null|undefined} stats
+ * @returns {string}
+ */
+function buildSyncStatsFailureMessage(stats) {
+  const syncErrors = Number(stats?.errors ?? 0);
+  const usersProcessed = Number(stats?.usersProcessed ?? 0);
+  const groupsProcessed = Number(stats?.groupsProcessed ?? 0);
+
+  const lines = [
+    `Dataplane full sync reported ${syncErrors} error(s).`,
+    `usersProcessed=${usersProcessed} groupsProcessed=${groupsProcessed}.`
+  ];
+
+  if (isZeroProgressSyncFailure(stats)) {
+    lines.push(
+      '',
+      'The controller accepted the sync request, but no identity data reached the dataplane.',
+      'Common causes:',
+      '  • Expired or invalid dataplane client token (controller → dataplane auth)',
+      '  • Dataplane unreachable or unhealthy',
+      '  • Dataplane MISO_CLIENTID / MISO_CLIENTSECRET out of sync with the controller',
+      '',
+      'Try:',
+      '  aifabrix auth status',
+      '  aifabrix run dataplane --reload',
+      'Then retry:',
+      '  aifabrix identity sync -e dev --purge-cache',
+      '',
+      'If it still fails, check miso-controller logs for the sync request.'
+    );
+  } else {
+    lines.push('Check miso-controller logs for the sync request.');
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  isZeroProgressSyncFailure,
+  buildSyncStatsFailureMessage
+};