@aifabrix/builder 2.51.0 → 2.52.0

package/lib/utils/role-assistant-paths.js

@@ -0,0 +1,160 @@
+/**
+ * Role Assistant workspace path helpers.
+ *
+ * @fileoverview Paths under role-assistant/ for Role Assistant packages
+ * @author AI Fabrix Team
+ * @version 1.1.0
+ */
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const { nodeFs } = require('../internal/node-fs');
+
+const WORKSPACE_ROLE_ASSISTANT = 'role-assistant';
+const SYSTEM_KIND_DIGITAL_WORKER = 'digitalWorker';
+const ROLE_ASSISTANT_SYSTEM_PREFIX = 'ra-';
+
+function getMaterializationParent() {
+  const work = process.env.AIFABRIX_WORK;
+  if (work && typeof work === 'string' && work.trim()) {
+    return path.resolve(work.trim());
+  }
+  if (process.env.AIFABRIX_HOME && typeof process.env.AIFABRIX_HOME === 'string') {
+    return path.resolve(process.env.AIFABRIX_HOME.trim());
+  }
+  return path.join(os.homedir(), '.aifabrix');
+}
+
+function getCwdRoleAssistantRoot() {
+  const p = path.join(path.resolve(process.cwd()), WORKSPACE_ROLE_ASSISTANT);
+  try {
+    const disk = nodeFs();
+    if (disk.existsSync(p)) {
+      const st = disk.statSync(p);
+      if (st && typeof st.isDirectory === 'function' && st.isDirectory()) {
+        return p;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+function getRoleAssistantRoot() {
+  const cwdRoot = getCwdRoleAssistantRoot();
+  if (cwdRoot) {
+    return cwdRoot;
+  }
+  return path.join(getMaterializationParent(), WORKSPACE_ROLE_ASSISTANT);
+}
+
+function isExistingDirectory(disk, dirPath) {
+  try {
+    if (!dirPath || !disk.existsSync(dirPath)) {
+      return false;
+    }
+    const st = disk.statSync(dirPath);
+    return Boolean(st && typeof st.isDirectory === 'function' && st.isDirectory());
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Bare business roleKey (strips leading ra- if present).
+ * @param {string} roleKeyOrSystemKey
+ * @returns {string}
+ */
+function bareRoleKey(roleKeyOrSystemKey) {
+  const raw = String(roleKeyOrSystemKey || '').trim();
+  if (raw.toLowerCase().startsWith(ROLE_ASSISTANT_SYSTEM_PREFIX)) {
+    return raw.slice(ROLE_ASSISTANT_SYSTEM_PREFIX.length);
+  }
+  return raw;
+}
+
+/**
+ * Folder / ExternalSystem key for a Role Assistant: ra-{roleKey}.
+ * @param {string} roleKeyOrSystemKey
+ * @returns {string}
+ */
+function roleAssistantSystemKey(roleKeyOrSystemKey) {
+  const bare = bareRoleKey(roleKeyOrSystemKey);
+  if (!bare) {
+    return '';
+  }
+  return `${ROLE_ASSISTANT_SYSTEM_PREFIX}${bare}`;
+}
+
+/**
+ * Candidate folder names under role-assistant/ (prefer ra-, then legacy bare).
+ * @param {string} roleKeyOrSystemKey
+ * @returns {string[]}
+ */
+function roleAssistantFolderCandidates(roleKeyOrSystemKey) {
+  const withRa = roleAssistantSystemKey(roleKeyOrSystemKey);
+  const bare = bareRoleKey(roleKeyOrSystemKey);
+  const out = [];
+  if (withRa) {
+    out.push(withRa);
+  }
+  if (bare && bare !== withRa) {
+    out.push(bare);
+  }
+  return out;
+}
+
+function firstExistingUnderRoot(disk, root, folderNames) {
+  if (!root) {
+    return null;
+  }
+  for (const name of folderNames) {
+    const candidate = path.join(root, name);
+    if (isExistingDirectory(disk, candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolves role-assistant/ra-{roleKey} (preferred) or legacy bare folder.
+ * @param {string} roleKey
+ * @returns {string}
+ */
+function getRoleAssistantPath(roleKey) {
+  if (!roleKey || typeof roleKey !== 'string') {
+    throw new Error('Role key is required and must be a string');
+  }
+  const disk = nodeFs();
+  const folders = roleAssistantFolderCandidates(roleKey);
+  const preferred = roleAssistantSystemKey(roleKey);
+  const cwdRoot = getCwdRoleAssistantRoot();
+  const matRoot = path.join(getMaterializationParent(), WORKSPACE_ROLE_ASSISTANT);
+
+  const existing =
+    firstExistingUnderRoot(disk, cwdRoot, folders) ||
+    firstExistingUnderRoot(disk, matRoot, folders);
+  if (existing) {
+    return existing;
+  }
+  if (cwdRoot) {
+    return path.join(cwdRoot, preferred);
+  }
+  return path.join(matRoot, preferred);
+}
+
+module.exports = {
+  WORKSPACE_ROLE_ASSISTANT,
+  SYSTEM_KIND_DIGITAL_WORKER,
+  ROLE_ASSISTANT_SYSTEM_PREFIX,
+  getCwdRoleAssistantRoot,
+  getRoleAssistantRoot,
+  getRoleAssistantPath,
+  bareRoleKey,
+  roleAssistantSystemKey,
+  roleAssistantFolderCandidates
+};

package/lib/utils/schema-loader.js

@@ -18,6 +18,7 @@ const addFormats = require('ajv-formats');
 // These are reset when module is reloaded (for testing)
 let externalSystemValidator = null;
 let externalDataSourceValidator = null;
+let roleAssistantSettingsValidator = null;
 
 /**
  * Reset validators cache (for testing)
@@ -26,6 +27,7 @@ let externalDataSourceValidator = null;
 function resetValidators() {
   externalSystemValidator = null;
   externalDataSourceValidator = null;
+  roleAssistantSettingsValidator = null;
 }
 
 /**
@@ -138,6 +140,38 @@ function loadExternalDataSourceSchema() {
   return externalDataSourceValidator;
 }
 
+/**
+ * Loads and compiles role-assistant settings schema.
+ * @function loadRoleAssistantSettingsSchema
+ * @returns {Function}
+ */
+function loadRoleAssistantSettingsSchema() {
+  if (roleAssistantSettingsValidator) {
+    return roleAssistantSettingsValidator;
+  }
+
+  const schemaPath = path.join(__dirname, '..', 'schema', 'role-assistant-settings.schema.json');
+  let schema;
+  try {
+    const schemaContent = fsRealSync.readFileSync(schemaPath, 'utf8');
+    schema = JSON.parse(schemaContent);
+  } catch (error) {
+    try {
+      schema = require('../schema/role-assistant-settings.schema.json');
+    } catch {
+      if (error && error.code === 'ENOENT') {
+        throw new Error(`Role assistant settings schema not found: ${schemaPath}`);
+      }
+      throw new Error(`Invalid JSON in role-assistant-settings.schema.json: ${error.message}`);
+    }
+  }
+
+  const ajv = new Ajv({ allErrors: true, strict: false, strictSchema: false });
+  addFormats(ajv);
+  roleAssistantSettingsValidator = ajv.compile(schema);
+  return roleAssistantSettingsValidator;
+}
+
 /**
  * Detect schema type from $id field
  * @param {Object} parsed - Parsed JSON object
@@ -157,6 +191,9 @@ function detectFromId(parsed) {
   if (parsed.$id.includes('application-schema')) {
     return 'application';
   }
+  if (parsed.$id.includes('role-assistant-settings')) {
+    return 'role-assistant-settings';
+  }
 
   return null;
 }
@@ -239,6 +276,9 @@ function detectFromApplicationFields(parsed) {
  */
 function detectFromFilename(filePath) {
   const fileName = path.basename(filePath).toLowerCase();
+  if (fileName === 'role-assistant.yaml' || fileName === 'role-assistant.yml') {
+    return 'role-assistant-settings';
+  }
   if (fileName.includes('external-system') || fileName.includes('external_system')) {
     return 'external-system';
   }
@@ -347,6 +387,7 @@ function detectSchemaType(filePath, content) {
 module.exports = {
   loadExternalSystemSchema,
   loadExternalDataSourceSchema,
+  loadRoleAssistantSettingsSchema,
   registerExternalDatasourceAjvDependencies,
   detectSchemaType,
   detectSchemaTypeFromParsed,

package/lib/utils/schema-resolver.js

@@ -175,6 +175,18 @@ function resolveDatasourceFiles(schemaBasePath, datasourceFiles) {
   return datasourceFiles.map(fileName => resolveSingleExternalFile(schemaBasePath, fileName, 'datasource'));
 }
 
+function resolveRoleAssistantSettingsFile(appPath) {
+  const yamlPath = path.join(appPath, 'role-assistant.yaml');
+  if (fs.existsSync(yamlPath)) {
+    return resolveSingleExternalFile(appPath, 'role-assistant.yaml', 'role-assistant-settings');
+  }
+  const ymlPath = path.join(appPath, 'role-assistant.yml');
+  if (fs.existsSync(ymlPath)) {
+    return resolveSingleExternalFile(appPath, 'role-assistant.yml', 'role-assistant-settings');
+  }
+  return resolveSingleExternalFile(appPath, 'role-assistant.yaml', 'role-assistant-settings');
+}
+
 /**
  * @param {string} schemaBasePath
  * @param {string[]} systemFileNames
@@ -282,6 +294,21 @@ async function loadAndValidateVariables(appPath) {
   }
 }
 
+function readSystemKindFromFirstSystemFile(schemaBasePath, systemFileNames) {
+  if (!systemFileNames.length) {
+    return '';
+  }
+  try {
+    const firstSystemPath = path.join(schemaBasePath, systemFileNames[0]);
+    const parsedSystem = loadConfigFile(firstSystemPath);
+    return parsedSystem && typeof parsedSystem.systemKind === 'string'
+      ? parsedSystem.systemKind
+      : '';
+  } catch {
+    return '';
+  }
+}
+
 async function resolveExternalFiles(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
@@ -295,15 +322,20 @@ async function resolveExternalFiles(appName, options = {}) {
   }
 
   const schemaBasePath = await resolveSchemaBasePath(appName, options);
-  const systemFiles = resolveSystemFiles(schemaBasePath, variables.externalIntegration.systems);
+  const systemFileNames = variables.externalIntegration.systems || [];
+  const systemFiles = resolveSystemFiles(schemaBasePath, systemFileNames);
+  const systemKind = readSystemKindFromFirstSystemFile(schemaBasePath, systemFileNames);
   const orderedNames = orderDatasourceFileNamesBySystemKeys(
     schemaBasePath,
-    variables.externalIntegration.systems,
+    systemFileNames,
     variables.externalIntegration.dataSources || []
   );
   const datasourceFiles = resolveDatasourceFiles(schemaBasePath, orderedNames);
-
-  return [...systemFiles, ...datasourceFiles];
+  const extraFiles = [];
+  if (String(systemKind).trim() === 'digitalWorker') {
+    extraFiles.push(resolveRoleAssistantSettingsFile(appPath));
+  }
+  return [...systemFiles, ...datasourceFiles, ...extraFiles];
 }
 
 module.exports = {

package/lib/utils/token-manager.js

@@ -408,53 +408,62 @@ function applyLabDataplaneApiKeyBearer(authConfig) {
   return authConfig;
 }
 
+function looksLikeJwtBearer(token) {
+  const existing = token ? String(token) : '';
+  return existing.split('.').length === 3 && existing.length > 80;
+}
+
+function preferClientCredentialsDeploymentAuth() {
+  return String(process.env.AIFABRIX_DEPLOYMENT_AUTH || '').toLowerCase() === 'client-credentials';
+}
+
+/**
+ * @param {Object} authConfig
+ * @returns {boolean} true when a substitution was applied
+ */
+function trySubstituteEnvApiKeyBearer(authConfig) {
+  if (!process.env.API_KEY) {
+    return false;
+  }
+  const apiKey = String(process.env.API_KEY);
+  if (authConfig.type === 'bearer' && authConfig.token !== apiKey) {
+    authConfig.token = apiKey;
+    return true;
+  }
+  if (authConfig.type === 'client-token') {
+    authConfig.type = 'bearer';
+    authConfig.token = apiKey;
+    return true;
+  }
+  if (!authConfig.token) {
+    authConfig.type = 'bearer';
+    authConfig.token = apiKey;
+    return true;
+  }
+  return false;
+}
+
 function requireBearerForDataplanePipeline(authConfig) {
   if (!authConfig || typeof authConfig !== 'object') {
     return;
   }
-
   if (authConfig.type === 'client-token' && authConfig.token) {
     return;
   }
-
   // Token-forward (builder-api / bearerForward): never substitute lab API_KEY for the caller JWT.
   if (authConfig.preserveBearer && authConfig.token) {
     return;
   }
-
-  const preferAppClientToken =
-    String(process.env.AIFABRIX_DEPLOYMENT_AUTH || '').toLowerCase() === 'client-credentials';
-
-  const existing = authConfig.token ? String(authConfig.token) : '';
-  const looksLikeJwt = existing.split('.').length === 3 && existing.length > 80;
   // Enterprise path: keep a real OAuth JWT; do not overwrite with process.env.API_KEY.
-  if (looksLikeJwt) {
+  if (looksLikeJwtBearer(authConfig.token)) {
     return;
   }
-
-  if (!preferAppClientToken && process.env.API_KEY) {
-    const apiKey = String(process.env.API_KEY);
-    if (authConfig.type === 'bearer' && authConfig.token !== apiKey) {
-      authConfig.token = apiKey;
-      return;
-    }
-    if (authConfig.type === 'client-token') {
-      authConfig.type = 'bearer';
-      authConfig.token = apiKey;
-      return;
-    }
-  }
-
-  if (authConfig.token) {
+  if (!preferClientCredentialsDeploymentAuth() && trySubstituteEnvApiKeyBearer(authConfig)) {
     return;
   }
-
-  if (!preferAppClientToken && process.env.API_KEY) {
-    authConfig.type = 'bearer';
-    authConfig.token = String(process.env.API_KEY);
+  if (authConfig.token) {
     return;
   }
-
   if (authConfig.clientId || authConfig.clientSecret) {
     throw new Error(
       'Dataplane pipeline endpoints require OAuth2 (Bearer token) or x-client-token. ' +

package/lib/utils/upload-sync-options.js

@@ -10,7 +10,7 @@
 
 /**
  * @param {Object} [options] - CLI options from test / sync callers
- * @returns {{ minimal: true, verbose: boolean, silentResolve: true, syncMode: true, force?: true, authConfig?: Object, dataplaneUrl?: string, environment?: string }}
+ * @returns {{ minimal: true, verbose: boolean, silentResolve: boolean, syncMode: boolean, force?: true, authConfig?: Object, dataplaneUrl?: string, environment?: string }}
  */
 function buildMinimalUploadSyncOptions(options = {}) {
   const deployPreflight = options.uploadContext === 'deploy-preflight';
@@ -18,11 +18,14 @@ function buildMinimalUploadSyncOptions(options = {}) {
     minimal: true,
     // CLI -v on verify-* / test-* is for run output, not preflight upload banners.
     verbose: false,
-    silentResolve: true,
-    syncMode: true,
+    // Deploy preflight should match `af upload` progress (URL + Publishing spinner).
+    // Verify/test --sync stays silent so parent command owns the progress line.
+    silentResolve: !deployPreflight,
+    syncMode: !deployPreflight,
     skipDataSync: true,
+    // Explicit suppress wins; deploy-preflight never suppresses the Publishing spinner.
     suppressPipelineSpinner:
-      options.suppressPipelineSpinner === true || deployPreflight === true
+      options.suppressPipelineSpinner === true && !deployPreflight
   };
   if (options.force === true) {
     out.force = true;

package/lib/utils/url-declarative-resolve-load-doc.js

@@ -25,6 +25,42 @@ function tryReadApplicationYamlAt(cfgPath) {
   }
 }
 
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPositivePortValue(value) {
+  if (typeof value === 'number' && value > 0) {
+    return true;
+  }
+  return typeof value === 'string' && /^\d+$/.test(String(value).trim());
+}
+
+/**
+ * True when a manifest can authoritatively supply listen/port for url:// expansion.
+ * External-system `application.json` (upload payload) has no HTTP listen port — using it
+ * for `url://builder-api-internal` falls through to {@link DECLARATIVE_URL_INFRA_DEFAULTS}
+ * (3000) and breaks Docker CIP against the real builder-api container (3005).
+ *
+ * @param {object|null|undefined} doc
+ * @returns {boolean}
+ */
+function isDeclarativeUrlPortAuthorityDoc(doc) {
+  if (!doc || typeof doc !== 'object') {
+    return false;
+  }
+  if ((doc.app && doc.app.type) === 'external') {
+    return false;
+  }
+  if (doc.externalIntegration && typeof doc.externalIntegration === 'object') {
+    return false;
+  }
+  return (
+    isPositivePortValue(doc.port) ||
+    isPositivePortValue(doc.build && doc.build.containerPort)
+  );
+}
+
 /**
  * Candidate paths for cross-app url:// resolution (low → high priority).
  * Platform system apps prefer materialized `~/.aifabrix-work|home/builder` over CLI package `builder/` stubs.
@@ -83,7 +119,7 @@ function loadApplicationYamlDocForUrlResolve(appKey, ctx, pathsUtil) {
     if (appKey === current && ctx.variablesPath) {
       const vp = path.resolve(String(ctx.variablesPath));
       const fromVars = tryReadApplicationYamlAt(vp);
-      if (fromVars) {
+      if (isDeclarativeUrlPortAuthorityDoc(fromVars)) {
         return fromVars;
       }
     }
@@ -105,5 +141,6 @@ function loadApplicationYamlDocForUrlResolve(appKey, ctx, pathsUtil) {
 
 module.exports = {
   collectApplicationYamlPathsForUrlResolve,
+  isDeclarativeUrlPortAuthorityDoc,
   loadApplicationYamlDocForUrlResolve
 };

package/lib/validation/external-manifest-validator.js

@@ -217,6 +217,36 @@ function validateDatasourceSystemKeyAlignment(manifest, errors) {
   });
 }
 
+/**
+ * Vendor OpenAPI contract surface is for Connected Systems. Role Assistants
+ * (digitalWorker) promote settings + Evidence — skip blocking OpenAPI vendor checks.
+ * @param {Object} manifest
+ * @param {Object} options
+ * @param {string[]} errors
+ * @param {string[]} warnings
+ */
+function applyExternalContractSurfaceChecks(manifest, options, errors, warnings) {
+  if (manifest.type !== 'external' || !Array.isArray(manifest.dataSources) || !manifest.system?.key) {
+    return;
+  }
+  const appPath = options.appPath;
+  if (typeof appPath !== 'string' || !appPath) {
+    return;
+  }
+  const systemKind =
+    typeof manifest.system.systemKind === 'string' ? manifest.system.systemKind.trim() : '';
+  if (systemKind === 'digitalWorker') {
+    warnings.push(
+      'Role Assistant (digitalWorker): vendor OpenAPI contract checks skipped ' +
+        '(settings + evidence path; run repair --api only when binding vendor OpenAPI).'
+    );
+    return;
+  }
+  const contract = validateAppContractSurface(appPath, manifest.system.key, manifest.dataSources);
+  errors.push(...contract.errors);
+  warnings.push(...contract.warnings);
+}
+
 /**
  * Validates controller deployment manifest for external systems
  * Validates manifest structure and inline system/dataSources against their schemas
@@ -251,14 +281,7 @@ async function validateControllerManifest(manifest, options = {}) {
   validateDatasources(manifest, ajv, externalDatasourceSchema, errors, warnings);
   validateDatasourceSystemKeyAlignment(manifest, errors);
   errors.push(...validateManifestRuntimeConfiguration(manifest));
-  if (manifest.type === 'external' && Array.isArray(manifest.dataSources) && manifest.system?.key) {
-    const appPath = options.appPath;
-    if (typeof appPath === 'string' && appPath) {
-      const contract = validateAppContractSurface(appPath, manifest.system.key, manifest.dataSources);
-      errors.push(...contract.errors);
-      warnings.push(...contract.warnings);
-    }
-  }
+  applyExternalContractSurfaceChecks(manifest, options, errors, warnings);
   validateConditionalRequirements(manifest, errors, warnings);
   validateRequiredFields(manifest, errors);
 

package/lib/validation/reserved-system-key-prefixes.js

@@ -0,0 +1,56 @@
+/**
+ * Frozen ExternalSystem key prefixes (Role Assistant / Enterprise Knowledge).
+ *
+ * @fileoverview Reject hand-authored ra-/ek- keys under integration/
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const RESERVED_SYSTEM_KEY_PREFIXES = ['ra-', 'ek-'];
+
+/**
+ * @param {string|null|undefined} systemKey
+ * @returns {boolean}
+ */
+function hasReservedPlatformSystemKeyPrefix(systemKey) {
+  const normalized = String(systemKey || '')
+    .trim()
+    .toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+  return RESERVED_SYSTEM_KEY_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+
+/**
+ * Connected Systems under integration/ must not use reserved prefixes.
+ * Role Assistant packages live under role-assistant/ra-*.
+ *
+ * @param {string|null|undefined} systemKey
+ * @param {string|null|undefined} workspaceBaseDir - integration | role-assistant | …
+ * @returns {string|null} Error message or null when allowed
+ */
+function reservedSystemKeyError(systemKey, workspaceBaseDir) {
+  if (!hasReservedPlatformSystemKeyPrefix(systemKey)) {
+    return null;
+  }
+  const workspace = String(workspaceBaseDir || '')
+    .trim()
+    .toLowerCase();
+  if (workspace === 'role-assistant' || workspace === 'enterprise-knowledge') {
+    return null;
+  }
+  return (
+    `System key '${systemKey}' uses a reserved prefix (ra- or ek-). ` +
+    'Role Assistant packages use role-assistant/ra-{roleKey}/; ' +
+    'Enterprise Knowledge uses ek- keys from platform generators only.'
+  );
+}
+
+module.exports = {
+  RESERVED_SYSTEM_KEY_PREFIXES,
+  hasReservedPlatformSystemKeyPrefix,
+  reservedSystemKeyError
+};

package/lib/validation/validate-external-file.js

@@ -10,7 +10,11 @@
 
 const fs = require('fs');
 const yaml = require('js-yaml');
-const { loadExternalSystemSchema, loadExternalDataSourceSchema } = require('../utils/schema-loader');
+const {
+  loadExternalSystemSchema,
+  loadExternalDataSourceSchema,
+  loadRoleAssistantSettingsSchema
+} = require('../utils/schema-loader');
 const { formatValidationErrors } = require('../utils/error-formatter');
 const { validateFieldReferences } = require('../datasource/field-reference-validator');
 const { validateAbac } = require('../datasource/abac-validator');
@@ -53,6 +57,9 @@ function getValidatorForType(normalizedType) {
   if (normalizedType === 'datasource') {
     return loadExternalDataSourceSchema();
   }
+  if (normalizedType === 'role-assistant-settings') {
+    return loadRoleAssistantSettingsSchema();
+  }
   throw new Error(`Unknown file type: ${normalizedType}`);
 }