@aifabrix/builder 2.50.0 → 2.51.0

package/lib/api/pipeline.api.js

@@ -247,11 +247,15 @@ async function testDatasourceViaPipeline({ dataplaneUrl, systemKey, datasourceKe
  * @returns {Promise<Object>} API envelope `{ success, data }` where `data` is PublicationResult (uploadId, system, datasources, generateMcpContract, …)
  * @throws {Error} If upload fails
  */
+/** Multi-datasource publish often exceeds the default 30s HTTP timeout. */
+const PIPELINE_UPLOAD_TIMEOUT_MS = 300000;
+
 async function uploadApplicationViaPipeline(dataplaneUrl, authConfig, payload) {
   const body = { ...payload, status: payload.status ?? 'draft' };
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/pipeline/upload', {
-    body
+    body,
+    timeoutMs: PIPELINE_UPLOAD_TIMEOUT_MS
   });
 }
 

package/lib/api/resource-types.api.js

@@ -12,7 +12,7 @@ const BASE = '/api/v1/resource-types';
 
 /**
  * List resource types (paginated)
- * @requiresPermission {Controller} resourceTypes:read
+ * @requiresPermission {Controller} resource-types:read
  * @async
  * @function listResourceTypes
  * @param {string} controllerUrl
@@ -34,7 +34,7 @@ async function listResourceTypes(controllerUrl, authConfig, options = {}) {
 
 /**
  * Get a resource type by id or key
- * @requiresPermission {Controller} resourceTypes:read
+ * @requiresPermission {Controller} resource-types:read
  * @async
  * @function getResourceType
  * @param {string} controllerUrl
@@ -49,7 +49,7 @@ async function getResourceType(controllerUrl, authConfig, resourceTypeIdOrKey) {
 
 /**
  * Create a resource type
- * @requiresPermission {Controller} resourceTypes:create
+ * @requiresPermission {Controller} resource-types:create
  * @async
  * @function createResourceType
  * @param {string} controllerUrl
@@ -75,7 +75,7 @@ async function createResourceType(controllerUrl, authConfig, body) {
 
 /**
  * Create-if-missing (idempotent): if a resource type already exists for the key, return success.
- * @requiresPermission {Controller} resourceTypes:read + resourceTypes:create
+ * @requiresPermission {Controller} resource-types:read + resource-types:create
  * @async
  * @function createResourceTypeIdempotent
  * @param {string} controllerUrl

package/lib/api/roles.api.js

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview Business roles API (Controller /api/v1/roles)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const BASE = '/api/v1/roles';
+
+/**
+ * List business roles (paginated)
+ * @requiresPermission {Controller} roles:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+async function listRoles(controllerUrl, authConfig, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(BASE, { params: options });
+}
+
+/**
+ * Get a business role by id or key
+ * @requiresPermission {Controller} roles:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} roleIdOrKey
+ * @returns {Promise<Object>}
+ */
+async function getRole(controllerUrl, authConfig, roleIdOrKey) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(`${BASE}/${encodeURIComponent(roleIdOrKey)}`);
+}
+
+/**
+ * @param {Object} payload
+ * @param {string} key
+ * @param {*} value
+ * @returns {void}
+ */
+function assignOptionalString(payload, key, value) {
+  if (value !== undefined && value !== null && value !== '') {
+    payload[key] = value;
+  }
+}
+
+/**
+ * @param {import('./types/roles.types').CreateBusinessRoleRequest} body
+ * @returns {Object}
+ */
+function buildCreateRoleBody(body) {
+  const payload = {
+    key: body.key,
+    domainKey: body.domainKey,
+    displayName: body.displayName
+  };
+  assignOptionalString(payload, 'description', body.description);
+  assignOptionalString(payload, 'purpose', body.purpose);
+  assignOptionalString(payload, 'businessOutcome', body.businessOutcome);
+  assignOptionalString(payload, 'source', body.source);
+  if (body.isActive !== undefined && body.isActive !== null) {
+    payload.isActive = Boolean(body.isActive);
+  }
+  if (body.metadata && typeof body.metadata === 'object') {
+    payload.metadata = body.metadata;
+  }
+  return payload;
+}
+
+/**
+ * Create a business role
+ * @requiresPermission {Controller} roles:create
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {import('./types/roles.types').CreateBusinessRoleRequest} body
+ * @returns {Promise<Object>}
+ */
+async function createRole(controllerUrl, authConfig, body) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(BASE, { body: buildCreateRoleBody(body) });
+}
+
+/**
+ * Create-if-missing (idempotent): if a role already exists for the key, return success.
+ * @requiresPermission {Controller} roles:read + roles:create
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {import('./types/roles.types').CreateBusinessRoleRequest} body
+ * @returns {Promise<{ created: boolean, response: Object }>}
+ */
+async function createRoleIdempotent(controllerUrl, authConfig, body) {
+  const key = String(body?.key || '').trim();
+  if (!key) {
+    throw new Error('Role key is required');
+  }
+  const getRes = await getRole(controllerUrl, authConfig, key);
+  if (getRes && getRes.success === true) {
+    return { created: false, response: getRes };
+  }
+  const createRes = await createRole(controllerUrl, authConfig, body);
+  if (createRes && createRes.success === true) {
+    return { created: true, response: createRes };
+  }
+  const msg = createRes?.error || createRes?.formattedError || 'Failed to create role';
+  throw new Error(msg);
+}
+
+module.exports = {
+  listRoles,
+  getRole,
+  createRole,
+  createRoleIdempotent
+};

package/lib/api/types/evidence-kinds.types.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Evidence kind API type definitions (Controller /api/v1/evidence-kinds)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * Create evidence kind request body (API shape uses domainKey)
+ * @typedef {Object} CreateEvidenceKindRequest
+ * @property {string} key - Catalog key (lowercase, digits, underscores)
+ * @property {string} domainKey - Enterprise domain key
+ * @property {string} displayName - Human-readable name
+ * @property {string} purpose - Purpose (required by Controller)
+ * @property {string} [description] - Optional description
+ * @property {string} [expectedUse] - Expected use guidance
+ * @property {string} [defaultSeverity] - low | medium | high | critical
+ * @property {boolean} [requiresApproval] - Approval flag
+ * @property {boolean} [isActive] - Active flag
+ * @property {number} [sortOrder] - Sort order
+ * @property {string} [source] - Provenance source
+ * @property {Object} [metadata] - Extensions
+ */
+
+/**
+ * Evidence kind record
+ * @typedef {Object} EvidenceKindRecord
+ * @property {string} id - Controller id
+ * @property {string} key - Catalog key
+ * @property {string} domainKey - Enterprise domain key
+ * @property {string} displayName - Display name
+ * @property {string} purpose - Purpose
+ * @property {string} [description] - Description
+ * @property {string} [expectedUse] - Expected use
+ * @property {string} [defaultSeverity] - Default severity
+ * @property {boolean} requiresApproval - Approval flag
+ * @property {boolean} isActive - Active flag
+ * @property {number} sortOrder - Sort order
+ * @property {string} [source] - Source
+ * @property {Object} [metadata] - Metadata
+ */
+
+module.exports = {};

package/lib/api/types/roles.types.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Business role API type definitions (Controller /api/v1/roles)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * Create business role request body (API shape uses domainKey)
+ * @typedef {Object} CreateBusinessRoleRequest
+ * @property {string} key - Catalog key (lowercase, hyphens)
+ * @property {string} domainKey - Enterprise domain key
+ * @property {string} displayName - Human-readable name
+ * @property {string} [description] - Optional description
+ * @property {string} [purpose] - Role purpose
+ * @property {string} [businessOutcome] - Business outcome
+ * @property {boolean} [isActive] - Active flag
+ * @property {string} [source] - Provenance source
+ * @property {Object} [metadata] - Compiler fields and extensions
+ */
+
+/**
+ * Business role record
+ * @typedef {Object} BusinessRoleRecord
+ * @property {string} id - Controller id
+ * @property {string} key - Catalog key
+ * @property {string} domainKey - Enterprise domain key
+ * @property {string} displayName - Display name
+ * @property {string} [description] - Description
+ * @property {string} [purpose] - Purpose
+ * @property {string} [businessOutcome] - Business outcome
+ * @property {boolean} isActive - Active flag
+ * @property {string} [source] - Source
+ * @property {Object} [metadata] - Metadata
+ */
+
+module.exports = {};

package/lib/app/certification-verify-rows.js

@@ -16,7 +16,7 @@ const { getActiveIntegrationCertificate, verifyIntegrationCertificate } = requir
 function certificateIdString(id) {
   if (id === undefined || id === null) return null;
   if (typeof id === 'string') return id.trim() || null;
-  if (typeof id === 'object' && id !== null && typeof id.id === 'string') return id.id.trim() || null;
+  if (typeof id === 'object' && typeof id.id === 'string') return id.id.trim() || null;
   return null;
 }
 

package/lib/app/show.js

@@ -347,7 +347,7 @@ async function getShowAuthToken(controllerUrl, config) {
   }
 
   const formatted = formatAuthenticationError({
-    controllerUrl: controllerUrl || undefined,
+    controllerUrl: undefined,
     message: 'No valid authentication found'
   });
   logger.error(formatted);
@@ -477,7 +477,7 @@ function resolveExternalSystemMeta(res, config, system, application, appKey) {
 
 function buildBaseExternalResult(configData, appKey, openapiFiles, openapiEndpoints, res) {
   const system = configData.system || configData;
-  const dataSources = configData.dataSources || configData.dataSources || [];
+  const dataSources = configData.dataSources || [];
   const application = configData.application || configData.app || {};
   const config = res && res.config && typeof res.config === 'object' ? res.config : {};
   const meta = resolveExternalSystemMeta(res, config, system, application, appKey);

package/lib/certification/merge-certification-from-artifact.js

@@ -13,7 +13,7 @@
 function certificateIdToString(id) {
   if (id === undefined || id === null) return '';
   if (typeof id === 'string') return id.trim();
-  if (typeof id === 'object' && id !== null && typeof id.id === 'string') return String(id.id).trim();
+  if (typeof id === 'object' && typeof id.id === 'string') return String(id.id).trim();
   return String(id).trim();
 }
 

package/lib/channels/channel-artifact-generator.js

@@ -16,6 +16,7 @@ const { getChannelTarget } = require('./channel-targets');
 const { BUILDER_ROOT } = require('./channel-integration-template');
 
 const SECRET_PATTERNS = [/xoxb-/i, /xoxp-/i, /client_secret/i, /signing_secret/i, /Bearer\s+/i];
+const PLACEHOLDER_DOMAIN_RE = /\byour-domain\.com\b/i;
 
 /**
  * @param {string} content
@@ -27,7 +28,7 @@ function assertNoSecretsInArtifact(content) {
       throw new Error('Generated artifact must not contain secret-like values');
     }
   }
-  if (content.includes('your-domain.com')) {
+  if (PLACEHOLDER_DOMAIN_RE.test(content)) {
     throw new Error('Generated artifact still contains placeholder domain your-domain.com');
   }
 }

package/lib/cli/index.js

@@ -23,6 +23,8 @@ const { setupAppCommands: setupAppManagementCommands } = require('../commands/ap
 const { setupDatasourceCommands } = require('../commands/datasource');
 const { setupDimensionCommands } = require('../commands/dimension');
 const { setupResourceTypeCommands } = require('../commands/resource-type');
+const { setupRoleCommands } = require('../commands/role');
+const { setupEvidenceKindCommands } = require('../commands/evidence-kind');
 const { setupEnterpriseKnowledgeCommands } = require('../commands/enterprise-knowledge');
 const { setupIdentityCommands } = require('../commands/identity');
 const { setupProtectionCommands } = require('../commands/protection');
@@ -73,6 +75,8 @@ function setupCoreCliCommands(program) {
 function setupExtendedCliCommands(program) {
   setupDimensionCommands(program);
   setupResourceTypeCommands(program);
+  setupRoleCommands(program);
+  setupEvidenceKindCommands(program);
   setupEnterpriseKnowledgeCommands(program);
   setupIdentityCommands(program);
   setupProtectionCommands(program);

package/lib/cli/setup-app.js

@@ -62,6 +62,8 @@ Notes:
   - Login or set MISO_CONTROLLER_URL + environment (aifabrix login / aifabrix auth).
   - CI: register once (aifabrix app register <appKey>), store DEV_MISO_CLIENTID and DEV_MISO_CLIENTSECRET in pipeline secrets.
   - upload = dataplane publish for dev iteration; deploy = controller validate + deploy (Azure or local Docker).
+  - Default output is a compact status card; use -v for expanded preflight and readiness detail.
+  - Controller deploy always polls to a terminal status (no --poll / --no-poll on this command).
   - --repository-url overrides repo URL for pipeline validate (default: application.yaml repository.repositoryUrl).
 `;
 
@@ -219,7 +221,7 @@ Examples:
     });
 }
 
-function setupBuildRunLogsDownCommands(program) {
+function registerBuildCommand(program) {
   program.command('build <appKey>')
     .description('Build Docker image for builder appKey (auto-detect runtime)')
     .option('-l, --language <lang>', 'Override language detection')
@@ -243,9 +245,9 @@ function setupBuildRunLogsDownCommands(program) {
         process.exit(1);
       }
     });
+}
 
-  registerRunCommand(program);
-
+function registerLogsCommand(program) {
   program.command('logs <appKey>')
     .description('Tail container logs for appKey (optional env summary; secrets masked)')
     .option('-f', 'Follow log stream')
@@ -256,14 +258,22 @@ function setupBuildRunLogsDownCommands(program) {
       try {
         const { runAppLogs } = require('../commands/app-logs');
         const tailNum = parseInt(options.tail, 10);
-        const level = options.level !== undefined && options.level !== null && options.level !== '' ? String(options.level).trim() : undefined;
-        await runAppLogs(appName, { follow: options.f, tail: Number.isNaN(tailNum) ? 100 : tailNum, level });
+        const level = options.level !== undefined && options.level !== null && options.level !== ''
+          ? String(options.level).trim()
+          : undefined;
+        await runAppLogs(appName, {
+          follow: options.f,
+          tail: Number.isNaN(tailNum) ? 100 : tailNum,
+          level
+        });
       } catch (error) {
         handleCommandError(error, 'logs');
         process.exit(1);
       }
     });
+}
 
+function registerDownAppCommand(program) {
   program.command('down-app <appKey>')
     .description('Stop and remove container for appKey (--volumes removes data volume)')
     .option('--volumes', 'Remove application Docker volume')
@@ -278,6 +288,13 @@ function setupBuildRunLogsDownCommands(program) {
     });
 }
 
+function setupBuildRunLogsDownCommands(program) {
+  registerBuildCommand(program);
+  registerRunCommand(program);
+  registerLogsCommand(program);
+  registerDownAppCommand(program);
+}
+
 function setupShellTestStopCommands(program) {
   program.command('stop <appKey>')
     .description('Alias for down-app: stop and remove container for appKey')

package/lib/cli/setup-dev.js

@@ -12,7 +12,8 @@ const config = require('../core/config');
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
 const { setupDevPathAndFormatCommands } = require('./setup-dev-path-commands');
-const { runDevInit, runDevRefresh } = require('../commands/dev-init');
+const { runDevInit } = require('../commands/dev-init');
+const { runDevRefresh, ensureDevCertFreshIfDue } = require('../commands/dev-refresh');
 const { displayDevConfig } = require('../commands/dev-show-display');
 const {
   handleDevList,
@@ -49,11 +50,21 @@ Examples:
 Requires a configured remote Builder Server and an admin client certificate (same machine setup as dev list / dev pin). After add, run dev pin <id> once to create a PIN for aifabrix dev init.
 `;
 
+/** Appended to `dev list --help` (sort examples). */
+const DEV_LIST_HELP_AFTER = `
+Examples:
+  $ aifabrix dev list
+  $ aifabrix dev list --sort id
+  $ aifabrix dev list --sort -until
+
+Sort fields: id, name, email, until. Prefix - for descending (default: name ascending).
+`;
+
 /** Appended to `aifabrix dev --help` (overview; keep subcommand .description lines short). */
 const DEV_GROUP_HELP_AFTER = `
 Categories:
   Local config   show, set-id, set-scoped-resources, set-env-config, set-home, set-work, set-format, print-home, print-work
-  Onboarding     init (PIN onboarding), refresh (sync settings / renew cert)
+  Onboarding     init (PIN onboarding), refresh (sync settings / renew cert); show auto-renews when due
   Remote admin   list, add, update, pin, delete, platform-install, platform-update, platform-install-cli  (need remote-server + client cert in ~/.aifabrix)
   Sync / stop    down  (Mutagen; optional --apps for containers)
 
@@ -168,9 +179,10 @@ async function handleSetScopedResources(value) {
 function setupDevShowAndSetId(dev) {
   dev
     .command('show')
-    .description('Show dev ports and ~/.aifabrix config')
+    .description('Show dev ports and ~/.aifabrix config (auto-renews cert when due)')
     .action(async() => {
       try {
+        await ensureDevCertFreshIfDue();
         const devId = await config.getDeveloperId();
         await displayDevConfig(devId);
       } catch (error) {
@@ -286,9 +298,14 @@ function setupDevListAddCommands(dev) {
   dev
     .command('list')
     .description('List developers (remote Builder Server)')
-    .action(async() => {
+    .option(
+      '--sort <field>',
+      'Sort field/direction (id|name|email|until; prefix - for descending; default name)'
+    )
+    .addHelpText('after', DEV_LIST_HELP_AFTER)
+    .action(async(options) => {
       try {
-        await handleDevList();
+        await handleDevList(options);
       } catch (error) {
         handleCommandError(error, 'dev list');
         process.exit(1);
@@ -398,8 +415,6 @@ function setupDevUpdatePinDeleteCommands(dev) {
         process.exit(1);
       }
     });
-
-  setupDevDownCommand(dev);
 }
 
 /**
@@ -457,6 +472,7 @@ function setupDevPlatformCommands(dev) {
 function setupDevUserCommands(dev) {
   setupDevListAddCommands(dev);
   setupDevUpdatePinDeleteCommands(dev);
+  setupDevDownCommand(dev);
   setupDevPlatformCommands(dev);
 }
 

package/lib/cli/setup-utility-help-after.js

@@ -18,6 +18,17 @@ Examples:
   $ aifabrix validate --builder
 `;
 
+const VALIDATE_JSON_HELP_AFTER = `
+Examples:
+  $ aifabrix validate-json myapp
+  $ aifabrix validate-json my-system
+  $ aifabrix validate-json --integration
+  $ aifabrix validate-json --builder
+  $ aifabrix validate-json --integration --builder --format json
+
+Runs full local validation first; writes *-deploy.json only when validation succeeds (offline).
+`;
+
 const REPAIR_HELP_AFTER = `
 Examples:
   $ aifabrix repair hubspot-demo
@@ -63,6 +74,7 @@ Examples:
 module.exports = {
   JSON_HELP_AFTER,
   VALIDATE_HELP_AFTER,
+  VALIDATE_JSON_HELP_AFTER,
   REPAIR_HELP_AFTER,
   RESOLVE_HELP_AFTER
 };

package/lib/cli/setup-utility-validate.js

@@ -12,7 +12,7 @@ const fs = require('fs');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
-const { VALIDATE_HELP_AFTER } = require('./setup-utility-help-after');
+const { VALIDATE_HELP_AFTER, VALIDATE_JSON_HELP_AFTER } = require('./setup-utility-help-after');
 
 /**
  * @param {string} appOrFile
@@ -154,7 +154,7 @@ async function runValidateCommand(appOrFile, options) {
 /**
  * @param {import('commander').Command} program
  */
-function setupValidateDiffCommands(program) {
+function setupValidateCommand(program) {
   program.command('validate [appKey|systemKey|file]')
     .description('Validate appKey, systemKey, file path, .protection batch, or all under integration/ and builder/')
     .addHelpText('after', VALIDATE_HELP_AFTER)
@@ -173,7 +173,37 @@ function setupValidateDiffCommands(program) {
         process.exit(1);
       });
     });
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupValidateJsonCommand(program) {
+  program.command('validate-json [appKey|systemKey]')
+    .description(
+      'Validate locally then write *-deploy.json only when validation succeeds (offline; no file-path mode)'
+    )
+    .addHelpText('after', VALIDATE_JSON_HELP_AFTER)
+    .option('--format <format>', 'Output format: json | default (human-readable)')
+    .option('--integration', 'Validate and write deploy JSON for all apps under integration/')
+    .option('--builder', 'Validate and write deploy JSON for all apps under builder/')
+    .action((appKey, options) => {
+      const { runValidateJsonCommand } = require('../commands/validate-json');
+      runValidateJsonCommand(appKey, options)
+        .then(({ exitCode }) => {
+          if (exitCode !== 0) process.exit(exitCode);
+        })
+        .catch((error) => {
+          handleCommandError(error, 'validate-json');
+          process.exit(1);
+        });
+    });
+}
 
+/**
+ * @param {import('commander').Command} program
+ */
+function setupDiffCommand(program) {
   program.command('diff <file1> <file2>')
     .description('Diff two config files (optional schema validate)')
     .option('--no-validate', 'Skip schema validation (type check still applied)')
@@ -191,6 +221,15 @@ function setupValidateDiffCommands(program) {
     });
 }
 
+/**
+ * @param {import('commander').Command} program
+ */
+function setupValidateDiffCommands(program) {
+  setupValidateCommand(program);
+  setupValidateJsonCommand(program);
+  setupDiffCommand(program);
+}
+
 module.exports = {
   setupValidateDiffCommands,
   runValidateCommand

package/lib/commands/deploy-gate-failure-details.js

@@ -124,6 +124,27 @@ function formatIntegrationGateFailure(result) {
   if (result?.message) {
     return String(result.message);
   }
+  const rows = Array.isArray(result?.datasourceResults) ? result.datasourceResults : [];
+  const hints = [];
+  for (const row of rows) {
+    if (!row || row.success !== false) {
+      continue;
+    }
+    const key = row.key || row.datasourceKey || 'datasource';
+    const issues = row.datasourceTestRun?.validation?.issues;
+    if (Array.isArray(issues) && issues.length > 0) {
+      const first = issues[0];
+      const code = first.code ? `${first.code}: ` : '';
+      hints.push(`${key}: ${code}${first.message || 'validation failed'}`);
+      continue;
+    }
+    if (row.error) {
+      hints.push(`${key}: ${row.error}`);
+    }
+  }
+  if (hints.length > 0) {
+    return hints.slice(0, 3).join('; ');
+  }
   return 'integration test did not succeed';
 }