@aifabrix/builder 2.50.0 → 2.51.1

package/lib/channels/runtime-tool-catalog.js

@@ -0,0 +1,165 @@
+/**
+ * Resolve Runtime Layer B tool names from Dataplane.
+ *
+ * @fileoverview Runtime-orchestration MCP tool discovery for channel artifacts and probes
+ * @author AI Fabrix Team
+ * @version 1.1.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('../api/index');
+const { getChannelTarget } = require('./channel-targets');
+
+/**
+ * Prefer the first-party MCP gateway catalog, then MCP OpenAPI, then legacy paths.
+ */
+const TOOL_CATALOG_BUILDERS = Object.freeze([
+  (systemKey) =>
+    `/api/v1/mcp/servers/tools?filter=${encodeURIComponent(`systemKey:eq:${systemKey}`)}&pageSize=100`,
+  (systemKey) => `/api/v1/mcp/${systemKey}/docs/mcp-openapi.json`,
+  (systemKey) => `/api/v1/external/systems/${systemKey}/mcp/tools`,
+  (systemKey) => `/api/v1/external/systems/${systemKey}/mcp/tools/list`,
+  (systemKey) => `/api/v1/external/systems/${systemKey}/mcp/catalog`,
+  (systemKey) => `/api/v1/external/systems/${systemKey}/tools`
+]);
+
+/**
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+function extractToolNames(value) {
+  if (Array.isArray(value)) {
+    return value
+      .map((item) => {
+        if (typeof item === 'string') return item.trim();
+        if (!item || typeof item !== 'object') return '';
+        return String(item.name || item.toolName || item.key || '').trim();
+      })
+      .filter(Boolean);
+  }
+  if (!value || typeof value !== 'object') {
+    return [];
+  }
+  const body = /** @type {Record<string, unknown>} */ (value);
+  if (body.paths && typeof body.paths === 'object') {
+    return extractToolNamesFromOpenApiPaths(body.paths);
+  }
+  const candidates = [body.tools, body.items, body.data, body.result];
+  for (const candidate of candidates) {
+    const names = extractToolNames(candidate);
+    if (names.length > 0) {
+      return names;
+    }
+  }
+  return [];
+}
+
+/**
+ * @param {Record<string, unknown>} paths
+ * @returns {string[]}
+ */
+function extractToolNamesFromOpenApiPaths(paths) {
+  const names = [];
+  for (const pathKey of Object.keys(paths || {})) {
+    const match = String(pathKey).match(/\/tools\/([^/]+)\/execute$/);
+    if (match && match[1] && match[1] !== 'execute') {
+      names.push(match[1]);
+    }
+  }
+  return [...new Set(names)];
+}
+
+/**
+ * @param {string} routeSystemKey
+ * @returns {string[]}
+ */
+function buildToolCatalogEndpoints(routeSystemKey) {
+  return TOOL_CATALOG_BUILDERS.map((build) => build(routeSystemKey));
+}
+
+/**
+ * @param {Object} response
+ * @returns {string[]}
+ */
+function extractToolNamesFromClientResponse(response) {
+  const direct = extractToolNames(response);
+  if (direct.length > 0) return preferLayerBToolNames(direct);
+  return preferLayerBToolNames(extractToolNames(response?.data ?? response));
+}
+
+/**
+ * Prefer MCP Layer B names (`work.start`) over REST-ish operation ids.
+ *
+ * @param {string[]} names
+ * @returns {string[]}
+ */
+function preferLayerBToolNames(names) {
+  const list = Array.isArray(names) ? names : [];
+  const dotted = list.filter((name) => /^[a-z][a-z0-9]*\.[a-z][a-z0-9.]*$/i.test(name));
+  return dotted.length > 0 ? dotted : list;
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} channelTarget
+ * @returns {Promise<string[]>}
+ */
+async function fetchRuntimeLayerBToolNames(dataplaneUrl, authConfig, channelTarget) {
+  const target = getChannelTarget(channelTarget);
+  const routeSystemKey = target.routeSystemKey || target.key;
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const endpoints = buildToolCatalogEndpoints(routeSystemKey);
+  for (const endpoint of endpoints) {
+    try {
+      const response = await client.get(endpoint, { timeoutMs: 10000 });
+      const names = extractToolNamesFromClientResponse(response);
+      if (Array.isArray(names) && names.length > 0) {
+        return [...new Set(names)].sort();
+      }
+    } catch {
+      // Try the next endpoint candidate.
+    }
+  }
+  return [];
+}
+
+/**
+ * True when Runtime MCP gateway docs or tool catalog is reachable.
+ *
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} routeSystemKey
+ * @returns {Promise<boolean>}
+ */
+async function isRuntimeMcpGatewayReachable(dataplaneUrl, authConfig, routeSystemKey) {
+  if (!dataplaneUrl || !routeSystemKey) return false;
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const candidates = [
+    `/api/v1/mcp/${routeSystemKey}/docs/mcp-openapi.json`,
+    `/api/v1/mcp/servers/tools?filter=${encodeURIComponent(`systemKey:eq:${routeSystemKey}`)}&pageSize=1`
+  ];
+  for (const endpoint of candidates) {
+    try {
+      const response = await client.get(endpoint, { timeoutMs: 8000 });
+      if (response && response.success !== false) {
+        return true;
+      }
+    } catch {
+      // try next
+    }
+  }
+  return false;
+}
+
+module.exports = {
+  TOOL_CATALOG_BUILDERS,
+  extractToolNames,
+  extractToolNamesFromOpenApiPaths,
+  preferLayerBToolNames,
+  buildToolCatalogEndpoints,
+  fetchRuntimeLayerBToolNames,
+  isRuntimeMcpGatewayReachable
+};

package/lib/cli/index.js

@@ -23,6 +23,9 @@ 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 { setupRoleAssistantCommands } = require('../commands/role-assistant');
+const { setupEvidenceKindCommands } = require('../commands/evidence-kind');
 const { setupEnterpriseKnowledgeCommands } = require('../commands/enterprise-knowledge');
 const { setupIdentityCommands } = require('../commands/identity');
 const { setupProtectionCommands } = require('../commands/protection');
@@ -73,6 +76,9 @@ function setupCoreCliCommands(program) {
 function setupExtendedCliCommands(program) {
   setupDimensionCommands(program);
   setupResourceTypeCommands(program);
+  setupRoleCommands(program);
+  setupRoleAssistantCommands(program);
+  setupEvidenceKindCommands(program);
   setupEnterpriseKnowledgeCommands(program);
   setupIdentityCommands(program);
   setupProtectionCommands(program);

package/lib/cli/setup-app.js

@@ -56,12 +56,18 @@ Examples:
   $ aifabrix validate hubspot-demo
   $ aifabrix upload hubspot-demo --probe
   $ aifabrix deploy hubspot-demo --probe -v
+  # Prove pillars in tst/CI, then promote (plain deploy seals cert on published Deploy)
   $ aifabrix deploy ek-sales --gate full --subject-email ops@example.com
+  $ aifabrix deploy ek-sales
 
 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).
+  - Prove (tst/CI): use --gate full (optional --subject-email) before promote; plain deploy promotes without live E2E gates.
+  - After a successful published Deploy, the platform seals the integration certificate (no separate certificates issue step).
+  - 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 +225,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 +249,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 +262,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 +292,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-external-system-help.js

@@ -10,6 +10,7 @@ Examples:
   $ aifabrix upload hubspot-demo
   $ aifabrix upload hubspot-demo -v
   $ aifabrix upload hubspot-demo --probe
+  $ aifabrix upload hubspot-demo --timeout 600000
 
   # Build and validate payload only (no API calls)
   $ aifabrix upload hubspot-demo --dry-run
@@ -18,11 +19,16 @@ Examples:
   $ aifabrix upload .protection
   $ aifabrix upload .protection --warnings-as-errors
 
+  # Role Assistant package (settings section + Evidence sidecars)
+  $ aifabrix upload sales-representative --env dev
+
 Notes:
   - Requires login (aifabrix auth status).
-  - Reads files under integration/<systemKey>/ (system JSON, datasources, credentials).
+  - Reads files under integration/<systemKey>/ or role-assistant/<roleKey>/ for digital workers.
   - Default output is a compact readiness summary; use -v for expanded detail and server-side validate warnings.
-  - --probe runs dataplane runtime checks after publish (slower; common in Session 1).
+  - --probe runs dataplane runtime checks after publish (slower).
+  - --timeout sets publish budget in ms (HTTP client and dataplane); default 300000.
+  - --env selects role-assistant.yaml section (dev|tst|pro) for digital workers; default dev.
   - test-e2e and test-integration publish local files first by default; use --no-publish on those commands to skip.
   - After dimension/FK edits on active datasources, use --force (or test-e2e / test-integration / datasource test-* with --sync --force).
   - For one datasource only: aifabrix datasource upload <datasourceKey>

package/lib/cli/setup-external-system.js

@@ -45,13 +45,16 @@ async function handleUploadCommandAction(systemKey, options) {
     return;
   }
   const upload = require('../commands/upload');
+  const { resolvePipelineUploadTimeoutMs } = require('../api/pipeline.api');
   const probeTimeout =
     options.probeTimeout === undefined || options.probeTimeout === null
       ? 120000
       : Number(options.probeTimeout);
+  const timeoutMs = resolvePipelineUploadTimeoutMs(options.timeout);
   await upload.uploadExternalSystem(systemKey, {
     ...options,
     probeTimeout: Number.isFinite(probeTimeout) ? probeTimeout : 120000,
+    timeoutMs,
     pathOptions: {}
   });
 }
@@ -98,10 +101,19 @@ function setupUploadCommand(program) {
     .option('-v, --verbose', 'Expanded upload summary and server-side pipeline validate warnings before publish')
     .option('--probe', 'After publish, run dataplane runtime checks (validation/run); slower')
     .option('--probe-timeout <ms>', 'Timeout for --probe (default: 120000)', '120000')
+    .option(
+      '--timeout <ms>',
+      'Publish timeout in ms for HTTP and dataplane budget (default: 300000; min 5000, max 2700000)'
+    )
     .option(
       '--force',
       'Bypass schema guards on active datasources during publish (dangerous; shows a warning)'
     )
+    .option(
+      '-e, --env <env>',
+      'Role Assistant settings environment section: dev, tst, or pro (default: dev)',
+      'dev'
+    )
     .action(async(systemKey, options) => {
       try {
         await handleUploadCommandAction(systemKey, options);

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/app-test.js

@@ -166,20 +166,8 @@ async function runDockerExec(containerName, testCmd, envFilePath = null) {
  * @returns {Promise<number>} Exit code
  */
 async function runDockerRunEphemeral(fullImage, testCmd, envFilePath = null) {
-  const { getDockerExecEnv } = require('../utils/remote-docker-env');
-  const dockerEnv = await getDockerExecEnv();
-  return new Promise((resolve) => {
-    const args = ['run', '--rm'];
-    if (envFilePath) args.push('--env-file', envFilePath);
-    args.push(fullImage, 'sh', '-c', testCmd);
-    const proc = spawn('docker', args, {
-      stdio: 'inherit',
-      shell: false,
-      env: dockerEnv
-    });
-    proc.on('close', code => resolve(code !== null ? code : 1));
-    proc.on('error', () => resolve(1));
-  });
+  const { runDockerRunEphemeral: runEphemeral } = require('../utils/docker-run-ephemeral');
+  return runEphemeral(fullImage, testCmd, envFilePath);
 }
 
 /**

package/lib/commands/datasource-load-export-cli.js

@@ -76,7 +76,8 @@ async function datasourceLoadAction(datasourceKey, options) {
       dryRun: options.dryRun,
       batchSize: options.batchSize,
       syncType: options.syncType,
-      format: options.format
+      format: options.format,
+      timeoutMs: options.timeout
     });
 
     if (options.json) {
@@ -141,6 +142,10 @@ function setupDatasourceLoadExportCommands(datasource) {
       'Dataplane syncType',
       'incremental'
     )
+    .option(
+      '--timeout <ms>',
+      'Per-batch HTTP timeout for records/bulk (default 120000)'
+    )
     .option('--dry-run', 'Parse and validate only; no upload')
     .option('-v, --verbose', 'Per-batch progress')
     .option('--json', 'Machine-readable result JSON')

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

@@ -113,6 +113,24 @@ function formatOperationsGateFailure(result) {
   return 'E2E validation did not succeed for one or more datasources';
 }
 
+/**
+ * @param {Object} row
+ * @returns {string|null}
+ */
+function formatFailedDatasourceRowHint(row) {
+  if (!row || row.success !== false) {
+    return null;
+  }
+  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}: ` : '';
+    return `${key}: ${code}${first.message || 'validation failed'}`;
+  }
+  return row.error ? `${key}: ${row.error}` : null;
+}
+
 /**
  * @param {Object} result
  * @returns {string}
@@ -124,6 +142,11 @@ function formatIntegrationGateFailure(result) {
   if (result?.message) {
     return String(result.message);
   }
+  const rows = Array.isArray(result?.datasourceResults) ? result.datasourceResults : [];
+  const hints = rows.map(formatFailedDatasourceRowHint).filter(Boolean);
+  if (hints.length > 0) {
+    return hints.slice(0, 3).join('; ');
+  }
   return 'integration test did not succeed';
 }