@aifabrix/builder 2.53.1 → 2.54.1

package/lib/core/secrets-env-content.js

@@ -29,7 +29,13 @@ const {
   applyDockerEnvOverride,
   getContainerPortFromDockerEnv
 } = require('./secrets-docker-env');
-const { getContainerPortFromPath, loadVariablesFromPath } = require('../utils/port-resolver');
+const {
+  getContainerPortFromPath,
+  loadVariablesFromPath,
+  isExternalAppDoc,
+  isExternalAppPath,
+  stripListenPortEnvLines
+} = require('../utils/port-resolver');
 const secretsEnsure = require('./secrets-ensure');
 const { resolveSecretsPath, getActualSecretsPath } = require('../utils/secrets-path');
 const pathsUtil = require('../utils/paths');
@@ -163,9 +169,14 @@ async function applyDockerTransformations(resolved, variablesPath) {
   envVars.REDIS_PORT = String(redisPort);
   envVars.DB_HOST = dbHost;
   envVars.DB_PORT = String(dbPort);
-  envVars.PORT = String(containerPort);
+  if (!isExternalAppDoc(appDoc)) {
+    envVars.PORT = String(containerPort);
+  }
   resolved = interpolateEnvVars(resolved, envVars);
   resolved = rewriteDockerManifestPublicPortEnvLine(resolved, envVars, appDoc);
+  if (isExternalAppDoc(appDoc)) {
+    return resolved;
+  }
   return updatePortForDocker(resolved, variablesPath);
 }
 
@@ -389,10 +400,13 @@ function resolveEnvContentToWrite(resolved, pathToPreserve, options = {}) {
 async function writeResolvedEnv({ appName, envPath, resolved, variablesPath, secretsPath, opts }) {
   const preservePath = opts.preserveFromPath !== undefined && opts.preserveFromPath !== null ? opts.preserveFromPath : null;
   const pathToPreserve = preservePath !== null ? preservePath : envPath;
-  const toWrite = resolveEnvContentToWrite(resolved, pathToPreserve, {
+  let toWrite = resolveEnvContentToWrite(resolved, pathToPreserve, {
     freshEnv: opts.freshEnv === true,
     pruneOrphanKv: opts.envOnly === true && opts.freshEnv !== true
   });
+  if (isExternalAppPath(variablesPath) && !/^PORT\s*=/m.test(resolved || '')) {
+    toWrite = stripListenPortEnvLines(toWrite);
+  }
   fs.writeFileSync(envPath, toWrite, { mode: 0o600 });
 
   if (!opts.skipOutputPath) {

package/lib/datasource/capability/capability-manifest.js

@@ -27,11 +27,8 @@ const DEFAULT_RISK_BY_KEY = {
 };
 
 const RESOURCE_TYPE_MAP = {
-  conversation: 'message',
   user: 'employee',
   person: 'employee',
-  record: 'document',
-  folder: 'document',
   country: 'organization',
   report: 'document',
   calendar: 'event',

package/lib/datasource/capability/copy-test-payload.js

@@ -1,5 +1,8 @@
 /**
  * Clone testPayload.scenarios rows when copying a capability.
+ * Deep-clones whole scenario objects and rewrites operation only. Nested row gold
+ * (expectedRows and related keys) is copied as-is; it may be wrong for --as —
+ * the author must edit after copy. Does not invent gold.
  *
  * @fileoverview Used by applyCapabilityCopy when includeTestPayload is true
  * @author AI Fabrix Team

package/lib/external-system/deploy-helpers.js

@@ -170,6 +170,30 @@ async function uploadDigitalWorkerIfNeeded(appName, options, _compact, manifest)
   });
 }
 
+async function deployRoleAssistantShellIfNeeded(appName, options, baseDir) {
+  const { isRoleAssistantWorkspace } = require('../utils/platform-shell-package');
+  if (!isRoleAssistantWorkspace(baseDir)) {
+    return null;
+  }
+  const { formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
+  const logger = require('../utils/logger');
+  if (options.json !== true) {
+    logger.log(
+      formatSuccessParagraph(
+        'Role Assistant deployment uses settings and Evidence upload (no Connected System publish).'
+      )
+    );
+  }
+  const { uploadExternalSystem } = require('../commands/upload');
+  return uploadExternalSystem(appName, {
+    ...options,
+    uploadStatus: 'published',
+    silentResolve: false,
+    suppressPipelineSpinner: false,
+    syncMode: false
+  });
+}
+
 module.exports = {
   loadVariablesYaml,
   validateSingleSystemFile,
@@ -177,6 +201,7 @@ module.exports = {
   validateSingleDatasourceFile,
   validateDatasourceFiles,
   extractSystemKey,
-  uploadDigitalWorkerIfNeeded
+  uploadDigitalWorkerIfNeeded,
+  deployRoleAssistantShellIfNeeded
 };
 

package/lib/external-system/deploy.js

@@ -30,7 +30,7 @@ const { displayValidationResults } = require('../validation/validate-display');
 const { syncDeployJsonFromSources } = require('./sync-deploy-manifest');
 const { runDeployGateOrchestrator } = require('../commands/deploy-gate-orchestrator');
 const { runPostPublishDataSync } = require('../commands/run-post-publish-data-sync');
-const { uploadDigitalWorkerIfNeeded } = require('./deploy-helpers');
+const { uploadDigitalWorkerIfNeeded, deployRoleAssistantShellIfNeeded } = require('./deploy-helpers');
 
 /**
  * Validates manifest on dataplane (dry-run) before controller deploy.
@@ -412,17 +412,13 @@ async function validateDataplaneManifestForDeploy(manifest, authConfig, dataplan
   }
 }
 
-async function runExternalSystemDeployFlow(appName, options) {
-  const compact = options.verbose !== true;
-  const { appPath } = await detectAppType(appName);
-  logOfflinePathWhenType(appPath);
+async function runConnectedSystemDeployAfterDetect(appName, options, compact) {
   if (!compact) {
     logger.log(chalk.blue(`\n🚀 Deploying external system: ${appName}`));
   }
   await validateExternalSystemForDeploy(appName, options, compact);
   const gateOutcomes = await runDeployGateOrchestrator(appName, {
     ...options,
-    // Compact deploy still shows step progress; only JSON mode stays fully quiet.
     quietDeployUi: options.json === true
   });
   await syncDeployJsonFromSources(appName);
@@ -453,6 +449,14 @@ async function runExternalSystemDeployFlow(appName, options) {
   });
 }
 
+async function runExternalSystemDeployFlow(appName, options) {
+  const compact = options.verbose !== true;
+  const { appPath, baseDir } = await detectAppType(appName);
+  logOfflinePathWhenType(appPath);
+  const shellResult = await deployRoleAssistantShellIfNeeded(appName, options, baseDir);
+  return shellResult || runConnectedSystemDeployAfterDetect(appName, options, compact);
+}
+
 /**
  * Deploys external system via controller pipeline (same as regular apps)
  *

package/lib/external-system/download-helpers.js

@@ -36,7 +36,30 @@ const {
 const path = require('path');
 
 /** Runtime/API fields that must not appear on external-system manifests. */
-const NON_MANIFEST_SYSTEM_KEYS = ['showOpenApiDocs'];
+const NON_MANIFEST_SYSTEM_KEYS = ['showOpenApiDocs', 'rbac'];
+
+/**
+ * Coerce system dataSources to unique string keys (dataplane may return objects).
+ * @param {*} dataSources
+ * @returns {string[]}
+ */
+function normalizeManifestDataSourceKeys(dataSources) {
+  if (!Array.isArray(dataSources)) {
+    return [];
+  }
+  const keys = [];
+  const seen = new Set();
+  for (const item of dataSources) {
+    const raw = typeof item === 'string' ? item : item && item.key;
+    const key = typeof raw === 'string' ? raw.trim() : '';
+    if (!key || seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    keys.push(key);
+  }
+  return keys;
+}
 
 /**
  * True when cwd looks like a product/workspace repo (integration, builder, or EK tree).
@@ -114,6 +137,9 @@ function sanitizeDownloadedApplication(application) {
   for (const key of NON_MANIFEST_SYSTEM_KEYS) {
     delete cleaned[key];
   }
+  if (Array.isArray(cleaned.dataSources)) {
+    cleaned.dataSources = normalizeManifestDataSourceKeys(cleaned.dataSources);
+  }
   return cleaned;
 }
 
@@ -296,6 +322,7 @@ module.exports = {
   runConvertToJsonIfRequested,
   generateVariablesYaml,
   generateReadme,
-  NON_MANIFEST_SYSTEM_KEYS
+  NON_MANIFEST_SYSTEM_KEYS,
+  normalizeManifestDataSourceKeys
 };
 

package/lib/external-system/download-role-assistant.js

@@ -1,17 +1,36 @@
 /**
  * Role Assistant sidecar handling during external-system download.
  *
- * @fileoverview Post-download evidence/knowledge/workflow actions for digitalWorker systems
+ * @fileoverview Platform-shell download (digitalWorker / enterpriseKnowledge) plus RA sidecars
  * @author AI Fabrix Team
- * @version 1.0.0
+ * @version 1.1.0
  */
 
 'use strict';
 
+const path = require('path');
 const logger = require('../utils/logger');
-const { formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const {
+  formatWarningLine,
+  formatSuccessLine,
+  metadata
+} = require('../utils/cli-test-layout-chalk');
 const { exportRoleAssistantKnowledge, logKnowledgeExportSummary } = require('../role-assistant/knowledge-sync');
 const { exportRoleAssistantEvidence, logRoleAssistantEvidenceExportSummary } = require('../role-assistant/evidence-sync');
+const { writeOrMergeRoleAssistantSettings } = require('../role-assistant/settings');
+const {
+  isDigitalWorkerKind,
+  isEnterpriseKnowledgeKind,
+  isPlatformShellKind
+} = require('../utils/platform-shell-package');
+
+const CONNECTED_SYSTEM_DRY_RUN_FILES = [
+  'deploy.json',
+  'application.yaml',
+  'system.yaml',
+  'env.template',
+  'README.md'
+];
 
 async function maybeExportRoleAssistantEvidenceArtifacts(systemKey, manifest, dataplaneUrl, authConfig, options) {
   try {
@@ -50,6 +69,66 @@ async function runRoleAssistantDownloadSidecars(params) {
   await maybeExportRoleAssistantKnowledgeArtifacts(systemKey, manifest, dataplaneUrl, authConfig, options);
 }
 
+function logConnectedSystemDryRunFiles(systemKey) {
+  logger.log(metadata('Would create:'));
+  CONNECTED_SYSTEM_DRY_RUN_FILES.forEach((name) => {
+    const fileName = name === 'deploy.json' || name === 'system.yaml'
+      ? `${systemKey}-${name}`
+      : name;
+    logger.log(metadata(`  - integration/${systemKey}/${fileName}`));
+  });
+}
+
+function handleDownloadDryRun(systemKey, dataplaneUrl, application) {
+  logger.log(formatWarningLine('Dry run mode: no files written.'));
+  logger.log(metadata(`Would fetch: ${dataplaneUrl}/api/v1/external/systems/${systemKey}/config`));
+  if (isEnterpriseKnowledgeKind(application)) {
+    logger.log(metadata('Would not write local package files.'));
+    return;
+  }
+  if (isDigitalWorkerKind(application)) {
+    logger.log(metadata('Would create:'));
+    logger.log(metadata(`  - role-assistant/${systemKey}/role-assistant.yaml`));
+    return;
+  }
+  logConnectedSystemDryRunFiles(systemKey);
+}
+
+async function downloadDigitalWorkerPackage(params) {
+  const { systemKey, manifest, dataplaneUrl, authConfig, options = {} } = params;
+  const yamlPath = writeOrMergeRoleAssistantSettings(systemKey, {
+    force: options.force === true,
+    pathOptions: options.pathOptions || {}
+  });
+  logger.log(formatSuccessLine(`Wrote ${path.relative(process.cwd(), yamlPath)}`));
+  await runRoleAssistantDownloadSidecars({
+    systemKey,
+    manifest,
+    dataplaneUrl,
+    authConfig,
+    options
+  });
+  return true;
+}
+
+async function downloadPlatformShellIfNeeded(params) {
+  const application = params.manifest && params.manifest.application;
+  if (!isPlatformShellKind(application)) {
+    return false;
+  }
+  if (isEnterpriseKnowledgeKind(application)) {
+    logger.log(
+      formatSuccessLine(
+        `Enterprise Knowledge '${params.systemKey}' stays on the platform; no local package files written.`
+      )
+    );
+    return true;
+  }
+  return downloadDigitalWorkerPackage(params);
+}
+
 module.exports = {
-  runRoleAssistantDownloadSidecars
+  runRoleAssistantDownloadSidecars,
+  downloadPlatformShellIfNeeded,
+  handleDownloadDryRun
 };

package/lib/external-system/download.js

@@ -31,7 +31,7 @@ const readline = require('readline');
 const yaml = require('js-yaml');
 const { getExternalSystemConfig } = require('../api/external-systems.api');
 const { getDeploymentAuth, requireBearerForDataplanePipeline } = require('../utils/token-manager');
-const { getConfig } = require('../core/config');
+const { getConfig, getFormat } = require('../core/config');
 const { retemplateConfigurationForDownload, retemplateAllVariableDefinitions } = require('../utils/configuration-env-resolver');
 const { syncRuntimeConfigurationFromDataplane } = require('../utils/runtime-configuration-download');
 const logger = require('../utils/logger');
@@ -41,12 +41,17 @@ const {
   validateSystemType,
   validateDownloadedData,
   sanitizeDownloadedApplication,
+  normalizeManifestDataSourceKeys,
   resolveDownloadDestinationPath,
   logDownloadCommandHeader,
   displayDownloadSuccess,
   runConvertToJsonIfRequested
 } = require('./download-helpers');
-const { runRoleAssistantDownloadSidecars } = require('./download-role-assistant');
+const {
+  runRoleAssistantDownloadSidecars,
+  downloadPlatformShellIfNeeded,
+  handleDownloadDryRun
+} = require('./download-role-assistant');
 
 /**
  * Setup authentication and get dataplane URL
@@ -187,10 +192,14 @@ function augmentConfigurationWithAuthSecrets(system) {
  * @returns {Object} Deploy JSON object for splitDeployJson
  */
 function buildDeployJsonFromManifest(application, dataSources, version) {
-  const dataSourcesKeys = Array.isArray(dataSources)
-    ? dataSources.map(ds => (ds && ds.key) ? ds.key : ds)
-    : [];
-  const system = { ...application, dataSources: application.dataSources || dataSourcesKeys };
+  const fromApp = normalizeManifestDataSourceKeys(application.dataSources);
+  const fromInline = normalizeManifestDataSourceKeys(
+    Array.isArray(dataSources) ? dataSources.map(ds => (ds && ds.key) ? ds.key : ds) : []
+  );
+  const system = {
+    ...application,
+    dataSources: fromApp.length ? fromApp : fromInline
+  };
   augmentConfigurationWithAuthSecrets(system);
   const deploy = { system, dataSources };
   if (version) deploy.version = version;
@@ -211,26 +220,6 @@ function validateSystemKeyFormat(systemKey) {
   }
 }
 
-/**
- * Handle dry run mode
- * @param {string} systemKey - System key
- * @param {string} dataplaneUrl - Dataplane URL
- */
-function handleDryRun(systemKey, dataplaneUrl) {
-  logger.log(formatWarningLine('Dry run mode: no files written.'));
-  logger.log(metadata(`Would fetch: ${dataplaneUrl}/api/v1/external/systems/${systemKey}/config`));
-  logger.log(metadata('Would create:'));
-  [
-    `integration/${systemKey}/${systemKey}-deploy.json`,
-    `integration/${systemKey}/application.yaml`,
-    `integration/${systemKey}/${systemKey}-system.yaml`,
-    `integration/${systemKey}/env.template`,
-    `integration/${systemKey}/README.md`
-  ].forEach(rel => {
-    logger.log(metadata(`  - ${rel}`));
-  });
-}
-
 /**
  * Validate and log downloaded data
  * @param {Object} application - Application configuration
@@ -406,9 +395,21 @@ async function finalizeDownloadArtifacts({
  * @param {Object} [options]
  * @returns {Promise<void>}
  */
+async function resolveDownloadFormat(requested) {
+  const raw = typeof requested === 'string' ? requested.trim().toLowerCase() : '';
+  if (raw === 'json' || raw === 'yaml') {
+    return raw;
+  }
+  const fromConfig = await getFormat();
+  if (fromConfig === 'json' || fromConfig === 'yaml') {
+    return fromConfig;
+  }
+  return 'yaml';
+}
+
 async function downloadExternalSystem(systemKey, options = {}) {
   validateSystemKeyFormat(systemKey);
-  const format = (options.format || 'yaml').toLowerCase();
+  const format = await resolveDownloadFormat(options.format);
 
   try {
     logDownloadCommandHeader(systemKey);
@@ -418,12 +419,21 @@ async function downloadExternalSystem(systemKey, options = {}) {
       options,
       config
     );
+    const manifest = await downloadFullManifest(dataplaneUrl, systemKey, authConfig, options);
     if (options.dryRun) {
-      handleDryRun(systemKey, dataplaneUrl);
+      handleDownloadDryRun(systemKey, dataplaneUrl, manifest.application);
+      return;
+    }
+    const platformHandled = await downloadPlatformShellIfNeeded({
+      systemKey,
+      manifest,
+      dataplaneUrl,
+      authConfig,
+      options
+    });
+    if (platformHandled) {
       return;
     }
-
-    const manifest = await downloadFullManifest(dataplaneUrl, systemKey, authConfig, options);
     validateAndLogDownloadedData(manifest.application, manifest.dataSources);
     const finalPath = resolveDownloadDestinationPath(systemKey, manifest.application);
     await processDownloadedSystem(

package/lib/external-system/sync-deploy-manifest.js

@@ -21,8 +21,9 @@ const logger = require('../utils/logger');
  * @returns {Promise<string>} Absolute path to the written deploy JSON file
  */
 async function syncDeployJsonFromSources(systemKey, opts = {}) {
-  const deployPath = await generator.generateDeployJson(systemKey, {});
-  if (!opts.quiet) {
+  const { quiet, ...generateOpts } = opts;
+  const deployPath = await generator.generateDeployJson(systemKey, generateOpts);
+  if (!quiet) {
     logger.log(formatSuccessLine(`Updated deployment manifest: ${deployPath}`));
   }
   return deployPath;

package/lib/external-system/upload-identity.js

@@ -0,0 +1,42 @@
+/**
+ * Fail closed when an upload payload's keys do not match the target system.
+ *
+ * @fileoverview Same contract as dataplane system_key_mismatch
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Object} payload
+ * @param {string} systemKey
+ * @returns {void}
+ */
+function assertUploadPackageIdentity(payload, systemKey) {
+  if (!payload || typeof payload !== 'object') {
+    throw new Error('Upload payload is required.');
+  }
+  const applicationKey =
+    payload.application && typeof payload.application.key === 'string'
+      ? payload.application.key
+      : '';
+  if (applicationKey !== systemKey) {
+    throw new Error(
+      `systemKey '${applicationKey}' does not match expected system key '${systemKey}'`
+    );
+  }
+  const dataSources = Array.isArray(payload.dataSources) ? payload.dataSources : [];
+  for (const ds of dataSources) {
+    if (!ds || ds.systemKey === systemKey) {
+      continue;
+    }
+    throw new Error(
+      `systemKey '${ds.systemKey}' does not match expected system key '${systemKey}'`
+    );
+  }
+}
+
+module.exports = {
+  assertUploadPackageIdentity
+};

package/lib/generator/index.js

@@ -298,26 +298,30 @@ async function writeRegularDeployJson(appName, appPath, appType) {
   return jsonPath;
 }
 
-async function generateDeployJson(appName, options = {}) {
-  if (!appName || typeof appName !== 'string') {
-    throw new Error('App name is required and must be a string');
-  }
-  let appPath;
-  let isExternal;
-  let appType;
+async function resolveDeployJsonAppContext(appName, options) {
   if (options.appPath) {
-    appPath = path.resolve(options.appPath);
+    const appPath = path.resolve(options.appPath);
     const configPath = resolveApplicationConfigPath(appPath);
     const { loadConfigFile } = require('../utils/config-format');
     const variables = loadConfigFile(configPath);
-    appType = variables?.app?.type || 'external';
-    isExternal = appType === 'external';
-  } else {
-    const detected = await detectAppType(appName, options);
-    appPath = detected.appPath;
-    isExternal = detected.isExternal;
-    appType = detected.appType;
+    const appType = variables?.app?.type || 'external';
+    return { appPath, appType, isExternal: appType === 'external' };
+  }
+  const detected = await detectAppType(appName, options);
+  const { throwIfPlatformShellHasNoDeployJson } = require('../utils/platform-shell-package');
+  throwIfPlatformShellHasNoDeployJson(appName, detected.baseDir);
+  return {
+    appPath: detected.appPath,
+    isExternal: detected.isExternal,
+    appType: detected.appType
+  };
+}
+
+async function generateDeployJson(appName, options = {}) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
   }
+  const { appPath, isExternal, appType } = await resolveDeployJsonAppContext(appName, options);
   logOfflinePathWhenType(appPath);
   if (isExternal) {
     return writeExternalDeployJson(appName, appPath, options);

package/lib/generator/split.js

@@ -15,6 +15,18 @@ const { parseImageReference } = require('./parse-image');
 const { generateReadmeFromDeployJson } = require('./split-readme');
 const { extractVariablesYaml, getExternalDatasourceFileName } = require('./split-variables');
 const { generateExternalEnvTemplateContent } = require('../utils/external-env-template');
+const { normalizeManifestDataSourceKeys } = require('../external-system/download-helpers');
+
+/**
+ * System YAML payload: omit runtime RBAC fields and coerce dataSources to keys.
+ * @param {Object} system
+ * @returns {Object}
+ */
+function systemYamlPayload(system) {
+  const { roles: _roles, permissions: _permissions, rbac: _rbac, ...rest } = system;
+  rest.dataSources = normalizeManifestDataSourceKeys(rest.dataSources);
+  return rest;
+}
 
 /**
  * Converts configuration array back to env.template format
@@ -339,9 +351,8 @@ async function writeExternalSystemAndDatasourceFiles(outputDir, deployment) {
   const system = deployment.system;
   const systemKey = system.key || 'external-system';
   const dataSourcesList = deployment.dataSources || deployment.datasources || [];
-  const { roles: _roles, permissions: _permissions, ...systemWithoutRbac } = system;
   const systemPath = path.join(outputDir, `${systemKey}-system.yaml`);
-  await writeComponentFile(systemPath, yaml.dump(systemWithoutRbac, { indent: 2, lineWidth: -1 }));
+  await writeComponentFile(systemPath, yaml.dump(systemYamlPayload(system), { indent: 2, lineWidth: -1 }));
   const datasourcePaths = await writeDatasourceFiles(outputDir, systemKey, dataSourcesList);
   return { systemFile: systemPath, datasourceFiles: datasourcePaths };
 }