@aifabrix/builder 2.51.0 → 2.52.0

package/lib/commands/verify-operations-step-plan.js

@@ -66,6 +66,17 @@ function buildE2eStep(systemKey, options) {
       ok: () => true
     };
   }
+  if (shouldSkipE2eForRoleAssistant(systemKey, options)) {
+    return {
+      key: 'e2e',
+      run: async() => ({
+        success: true,
+        skipped: true,
+        reason: 'role-assistant-auth-none'
+      }),
+      ok: () => true
+    };
+  }
   return {
     key: 'e2e',
     run: (progress) =>
@@ -88,6 +99,26 @@ function buildE2eStep(systemKey, options) {
   };
 }
 
+/**
+ * Role Assistant packages use authType none + nested builder-api CIP.
+ * Live capacity E2E expects a system baseUrl credential and is not the RA certify path.
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {boolean}
+ */
+function shouldSkipE2eForRoleAssistant(systemKey, options) {
+  if (options.forceE2e === true) {
+    return false;
+  }
+  try {
+    const { resolveAppWorkspace } = require('../utils/app-path-resolve');
+    const { baseDir } = resolveAppWorkspace(systemKey, {});
+    return baseDir === 'role-assistant';
+  } catch {
+    return false;
+  }
+}
+
 /**
  * @param {string} systemKey
  * @param {Object} options

package/lib/commands/verify-trust-command-action.js

@@ -17,12 +17,9 @@ const { buildJsonEnvelope } = require('../lifecycle/json-envelope');
 async function runVerifyTrustCommandAction(appName, options, cmd) {
   const opts = normalizeTestTrustCliOptions(options, cmd);
   const pathsUtil = require('../utils/paths');
+  const { assertCertifyExternalWorkspace } = require('../utils/certify-external-workspace');
   const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-  if (!appType || appType.baseDir !== 'integration') {
-    throw new Error(
-      'verify-trust applies to external integration folders only (integration/<systemKey>/).'
-    );
-  }
+  assertCertifyExternalWorkspace(appType && appType.baseDir, 'verify-trust');
 
   const result = await runVerifyTrustForExternalSystem(appName, {
     env: opts.env,

package/lib/commands/wizard-core-helpers.js

@@ -232,15 +232,19 @@ function buildPlatformConfigPayload({ credentialIdOrKey, datasourceKeys, configu
 }
 
 /**
- * Extract configuration from API response
+ * Extract configuration from API response.
+ * add-datasource generation returns datasourceConfig(s) only (systemConfig is null by design).
+ * Callers must load the existing workspace system when systemConfig is missing.
  * @param {Object} generateResponse - API response
  * @returns {Object} Extracted configuration
  */
 function extractConfigurationFromResponse(generateResponse) {
-  const systemConfig = generateResponse.data?.systemConfig;
+  const systemConfig = generateResponse.data?.systemConfig || null;
   const datasourceConfigs = generateResponse.data?.datasourceConfigs ||
     (generateResponse.data?.datasourceConfig ? [generateResponse.data.datasourceConfig] : []);
-  if (!systemConfig) throw new Error('System configuration not found');
+  if (!systemConfig && (!Array.isArray(datasourceConfigs) || datasourceConfigs.length === 0)) {
+    throw new Error('System configuration not found');
+  }
   return { systemConfig, datasourceConfigs, systemKey: generateResponse.data?.systemKey };
 }
 

package/lib/commands/wizard-core.js

@@ -312,6 +312,72 @@ async function callGenerateApi(dataplaneUrl, authConfig, options, prefs) {
   return await generateConfig(dataplaneUrl, authConfig, configPayload);
 }
 
+/**
+ * Load existing system JSON/YAML from the integration workspace (add-datasource).
+ * @param {string} appName - Integration app / system key
+ * @returns {Object|null}
+ */
+function loadExistingWorkspaceSystemConfig(appName) {
+  if (!appName || typeof appName !== 'string') {
+    return null;
+  }
+  const { getIntegrationPath } = require('../utils/paths');
+  const { loadConfigFile } = require('../utils/config-format');
+  const fsSync = require('fs');
+  const appPath = getIntegrationPath(appName);
+  for (const ext of ['.json', '.yaml', '.yml']) {
+    const candidate = path.join(appPath, `${appName}-system${ext}`);
+    if (fsSync.existsSync(candidate)) {
+      try {
+        return loadConfigFile(candidate);
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {Object|null|undefined} systemConfig
+ * @param {Object} options
+ * @returns {Object}
+ */
+function resolveSystemConfigForWizardMode(systemConfig, options) {
+  if (systemConfig) {
+    return systemConfig;
+  }
+  if (options.mode === 'add-datasource') {
+    const existing = loadExistingWorkspaceSystemConfig(
+      options.appName || options.systemIdOrKey
+    );
+    if (!existing) {
+      throw new Error(
+        'System configuration not found for add-datasource. ' +
+          'Run create-system wizard first so the workspace has a system file.'
+      );
+    }
+    return existing;
+  }
+  throw new Error('System configuration not found');
+}
+
+/**
+ * @param {Object} generateResponse
+ * @param {Object} prefs
+ * @param {Object} options
+ * @returns {Promise<void>}
+ */
+async function maybeWriteWizardDebugLog(generateResponse, prefs, options) {
+  if (!prefs.debug || !options.appName) {
+    return;
+  }
+  const debugLog = generateResponse.data?.debugLog;
+  if (debugLog && typeof debugLog === 'string') {
+    await writeDebugLog(options.appName, debugLog);
+  }
+}
+
 async function handleConfigurationGeneration(dataplaneUrl, authConfig, options) {
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 5: Generate Configuration'));
   const prefs = buildConfigPreferences(options.configPrefs);
@@ -320,18 +386,21 @@ async function handleConfigurationGeneration(dataplaneUrl, authConfig, options)
     const generateResponse = await callGenerateApi(dataplaneUrl, authConfig, options, prefs);
     spinner.stop();
     if (!generateResponse.success) {
-      await saveDebugManifestOnErrorAndThrow(generateResponse, { enableDebug: prefs.debug, appName: options.appName });
+      await saveDebugManifestOnErrorAndThrow(generateResponse, {
+        enableDebug: prefs.debug,
+        appName: options.appName
+      });
     }
     const result = extractConfigurationFromResponse(generateResponse);
-    const normalized = normalizeWizardConfigs(result.systemConfig, result.datasourceConfigs);
-    if (prefs.debug && options.appName) {
-      const debugLog = generateResponse.data?.debugLog;
-      if (debugLog && typeof debugLog === 'string') {
-        await writeDebugLog(options.appName, debugLog);
-      }
-    }
+    const systemConfig = resolveSystemConfigForWizardMode(result.systemConfig, options);
+    const normalized = normalizeWizardConfigs(systemConfig, result.datasourceConfigs);
+    await maybeWriteWizardDebugLog(generateResponse, prefs, options);
     logger.log(formatSuccessLine('Configuration generated successfully'));
-    return { systemConfig: normalized.systemConfig, datasourceConfigs: normalized.datasourceConfigs, systemKey: result.systemKey };
+    return {
+      systemConfig: normalized.systemConfig,
+      datasourceConfigs: normalized.datasourceConfigs,
+      systemKey: result.systemKey || options.systemIdOrKey || options.appName
+    };
   } catch (error) {
     spinner.stop();
     throw error;

package/lib/datasource/bulk-loader-run-batches.js

@@ -70,19 +70,21 @@ function recordBatchSuccess(state, index, response, batchRecords) {
  * @returns {Promise<{ batches: Object[], totals: Object }>}
  */
 async function uploadRecordBatches(params) {
-  const { chunks, syncType, dataplaneUrl, datasourceKey, authConfig } = params;
+  const { chunks, syncType, dataplaneUrl, datasourceKey, authConfig, timeoutMs } = params;
   const state = {
     batches: [],
     totals: { insertedCount: 0, updatedCount: 0, failedCount: 0 },
     chunkCount: chunks.length
   };
+  const transportOpts =
+    timeoutMs !== undefined && timeoutMs !== null ? { timeoutMs } : {};
 
   for (let i = 0; i < chunks.length; i += 1) {
     const batchRecords = chunks[i];
     const body = { syncType, sync: false, records: batchRecords };
     try {
       const response = await withTransientRetry(() =>
-        bulkSyncRecords(dataplaneUrl, datasourceKey, authConfig, body)
+        bulkSyncRecords(dataplaneUrl, datasourceKey, authConfig, body, transportOpts)
       );
       recordBatchSuccess(state, i, response, batchRecords);
     } catch (err) {

package/lib/datasource/bulk-loader-service.js

@@ -81,12 +81,16 @@ async function executeDatasourceLoadWork(params) {
     return { ...result, context: ctx };
   }
 
+  const timeoutMs = options.timeoutMs
+    ? parseInt(String(options.timeoutMs), 10)
+    : undefined;
   const { batches, totals } = await uploadRecordBatches({
     chunks: chunkRecords(records, batchSize),
     syncType,
     dataplaneUrl: ctx.dataplaneUrl,
     datasourceKey: ctx.datasourceKey,
-    authConfig: ctx.authConfig
+    authConfig: ctx.authConfig,
+    timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : undefined
   });
 
   return { ...result, batches, totals, context: ctx };

package/lib/datasource/datasource-identifier.js

@@ -7,7 +7,7 @@
 'use strict';
 
 const path = require('path');
-const { getIntegrationPath } = require('../utils/paths');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadConfigFile } = require('../utils/config-format');
 
@@ -65,12 +65,13 @@ function pickIntegrationAppForDatasourceIdentifier(identifier, appNames) {
 }
 
 /**
- * List manifest datasource files for an integration app.
+ * List manifest datasource files for an external authoring app
+ * (integration/, role-assistant/, or enterprise-knowledge/).
  * @param {string} appKey
  * @returns {{ appPath: string, schemaBasePath: string, datasourceFiles: string[] }|null}
  */
 function listDatasourceFilesForApp(appKey) {
-  const appPath = getIntegrationPath(appKey);
+  const appPath = resolveExternalSystemPath(appKey);
   let config;
   try {
     const configPath = resolveApplicationConfigPath(appPath);

package/lib/datasource/datasource-validate-summary.js

@@ -167,10 +167,10 @@ function assembleSummary(parsed) {
     foreignKeys: fks,
     dimensionKeys,
     dimensions,
-    exposedProfileNames: summarizeExposedProfileNames(parsed),
-    openapiLine: oa.openapiLine,
     hasOpenapi: oa.hasOpenapi,
+    openapiLine: oa.openapiLine,
     capabilityKeys: oa.capabilityKeys,
+    exposedProfileNames: summarizeExposedProfileNames(parsed),
     testPayloadLine: summarizeTestPayloadLine(parsed),
     hasTestPayload: !!parsed.testPayload && typeof parsed.testPayload === 'object',
     syncLine: summarizeSyncLine(sync)

package/lib/datasource/integration-context.js

@@ -6,7 +6,7 @@
 
 const path = require('path');
 const fs = require('fs').promises;
-const { getIntegrationPath } = require('../utils/paths');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadConfigFile } = require('../utils/config-format');
 const {
@@ -15,11 +15,11 @@ const {
 } = require('./datasource-identifier');
 
 /**
- * @param {string} appKey - Integration app key
+ * @param {string} appKey - Integration / role-assistant / EK app key
  * @returns {Promise<string>} systemKey
  */
 async function getSystemKeyFromAppKey(appKey) {
-  const appPath = getIntegrationPath(appKey);
+  const appPath = resolveExternalSystemPath(appKey);
   const configPath = resolveApplicationConfigPath(appPath);
   const config = loadConfigFile(configPath);
   if (!config.externalIntegration || !config.externalIntegration.systems || config.externalIntegration.systems.length === 0) {

package/lib/datasource/resolve-app.js

@@ -2,15 +2,20 @@
  * Resolve app key for datasource commands from explicit --app, cwd, scan, or key parse.
  * @fileoverview App resolution for datasource test-e2e, test-integration, log-e2e, log-integration
  * @author AI Fabrix Team
- * @version 2.0.0
+ * @version 2.1.0
  */
 
+'use strict';
+
 const fs = require('fs');
 const {
-  getIntegrationPath,
   listIntegrationAppNames,
+  listEnterpriseKnowledgeAnchors,
+  getRoleAssistantRoot,
+  getCwdRoleAssistantRoot,
   resolveIntegrationAppKeyFromCwd
 } = require('../utils/paths');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const {
   appHasDatasourceIdentifier,
   pickIntegrationAppForDatasourceIdentifier
@@ -21,6 +26,80 @@ function appHasDatasourceKey(appKey, datasourceKey) {
   return appHasDatasourceIdentifier(appKey, datasourceKey);
 }
 
+/**
+ * @param {string} appKey
+ * @returns {boolean}
+ */
+function externalAppPathExists(appKey) {
+  try {
+    const appPath = resolveExternalSystemPath(appKey);
+    return Boolean(appPath && fs.existsSync(appPath));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {Set<string>} diskNames
+ */
+function addRoleAssistantAppDirs(root, diskNames) {
+  if (!root || !fs.existsSync(root)) {
+    return;
+  }
+  let entries;
+  try {
+    entries = fs.readdirSync(root);
+  } catch {
+    return;
+  }
+  const pathJoin = require('path').join;
+  for (const name of entries) {
+    if (!name || name.startsWith('.')) {
+      continue;
+    }
+    try {
+      if (fs.statSync(pathJoin(root, name)).isDirectory()) {
+        diskNames.add(name);
+      }
+    } catch {
+      // skip
+    }
+  }
+}
+
+/**
+ * List app folders under role-assistant/ (cwd + materialization).
+ * @returns {string[]}
+ */
+function listRoleAssistantAppNames() {
+  const diskNames = new Set();
+  const roots = new Set();
+  const cwdRoot = getCwdRoleAssistantRoot();
+  if (cwdRoot) {
+    roots.add(cwdRoot);
+  }
+  roots.add(getRoleAssistantRoot());
+  for (const root of roots) {
+    addRoleAssistantAppDirs(root, diskNames);
+  }
+  return [...diskNames].sort();
+}
+
+/**
+ * External authoring apps: integration + role-assistant + enterprise-knowledge.
+ * @returns {string[]}
+ */
+function listExternalAuthoringAppNames() {
+  return [
+    ...new Set([
+      ...listIntegrationAppNames(),
+      ...listRoleAssistantAppNames(),
+      ...listEnterpriseKnowledgeAnchors()
+    ])
+  ].sort();
+}
+
 /**
  * @param {string} key
  * @param {string} [explicitApp]
@@ -31,7 +110,7 @@ function resolveFromExplicitApp(key, explicitApp) {
     return null;
   }
   const appKey = explicitApp.trim();
-  if (fs.existsSync(getIntegrationPath(appKey))) {
+  if (externalAppPathExists(appKey)) {
     return { appKey };
   }
   return null;
@@ -71,15 +150,16 @@ function resolveFromPrefixOrSegments(key, appNames) {
     return null;
   }
   const candidate = segments.slice(0, -1).join('-');
-  const candidatePath = getIntegrationPath(candidate);
-  if (fs.existsSync(candidatePath) && appHasDatasourceIdentifier(candidate, key)) {
+  if (externalAppPathExists(candidate) && appHasDatasourceIdentifier(candidate, key)) {
     return { appKey: candidate };
   }
   return null;
 }
 
 const RESOLVE_APP_HINT =
-  'Could not determine app context. Use --app <app>, a datasource key, a datasource JSON filename (e.g. myapp-datasource-contacts), or run from integration/<systemKey>/ directory.';
+  'Could not determine app context. Use --app <app>, a datasource key, a datasource JSON filename ' +
+  '(e.g. myapp-datasource-contacts), or run from integration/<systemKey>/, ' +
+  'role-assistant/<systemKey>/, or enterprise-knowledge/<systemKey>/.';
 
 /**
  * Resolve app key for a datasource: explicit --app, cwd, scan by key, or parse key convention.
@@ -108,7 +188,7 @@ async function resolveAppKeyForDatasource(datasourceKey, explicitApp) {
     return { appKey: fromCwd };
   }
 
-  const appNames = listIntegrationAppNames();
+  const appNames = listExternalAuthoringAppNames();
   const scanned = resolveFromAppScan(key, appNames);
   if (scanned) {
     return scanned;
@@ -124,5 +204,7 @@ async function resolveAppKeyForDatasource(datasourceKey, explicitApp) {
 
 module.exports = {
   resolveAppKeyForDatasource,
-  appHasDatasourceKey
+  appHasDatasourceKey,
+  listExternalAuthoringAppNames,
+  listRoleAssistantAppNames
 };

package/lib/datasource/test-e2e.js

@@ -9,7 +9,6 @@ const path = require('path');
 const fs = require('fs').promises;
 const chalk = require('chalk');
 const logger = require('../utils/logger');
-const { getIntegrationPath } = require('../utils/paths');
 const { resolveAppKeyForDatasource } = require('./resolve-app');
 const { formatProgress, formatSuccessLine, infoLine } = require('../utils/cli-test-layout-chalk');
 const { runUnifiedDatasourceValidation } = require('./unified-validation-run');
@@ -94,7 +93,8 @@ async function resolvePrimaryKeyValue(value) {
 }
 
 function e2eIntegrationLogDir(appKey) {
-  return path.dirname(getIntegrationPath(appKey));
+  const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
+  return path.dirname(resolveExternalSystemPath(appKey));
 }
 
 /**

package/lib/datasource/unified-validation-run-body.js

@@ -12,6 +12,16 @@ const {
 const testHelpers = require('../utils/external-system-test-helpers');
 const { withStageOnValidationRunBody } = require('../utils/validation-run-stage');
 
+/**
+ * @param {Object} datasource
+ * @returns {boolean}
+ */
+function isVoidCipInput(datasource) {
+  const execution = datasource && typeof datasource === 'object' ? datasource.execution : null;
+  const cip = execution && typeof execution === 'object' ? execution.cip : null;
+  return String((cip && cip.inputType) || '').trim().toLowerCase() === 'void';
+}
+
 /**
  * @param {Object} params
  * @param {string} params.systemKey
@@ -31,7 +41,11 @@ async function buildUnifiedValidationBody(params) {
     const customPayload = await testHelpers.loadCustomPayload(payloadPath);
     payloadTemplate = testHelpers.determinePayloadTemplate(datasource, datasourceKey, customPayload);
     if (runType === 'integration' && !payloadTemplate) {
-      throw new Error(`No test payload found for datasource '${datasourceKey}'`);
+      if (isVoidCipInput(datasource)) {
+        payloadTemplate = {};
+      } else {
+        throw new Error(`No test payload found for datasource '${datasourceKey}'`);
+      }
     }
   }
 

package/lib/datasource/unified-validation-run-resolve.js

@@ -4,7 +4,7 @@
  * @version 2.0.0
  */
 
-const { getIntegrationPath } = require('../utils/paths');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadConfigFile } = require('../utils/config-format');
 const {
@@ -48,7 +48,7 @@ function findDatasourceFileByIdentifier(appPath, schemaBasePath, datasourceFiles
  * @returns {{ datasource: Object, datasourcePath: string, datasourceKey: string }}
  */
 function loadDatasourceForApp(appKey, datasourceKey, findDatasourceFileByKey) {
-  const appPath = getIntegrationPath(appKey);
+  const appPath = resolveExternalSystemPath(appKey);
   const config = loadConfigFile(resolveApplicationConfigPath(appPath));
   const schemaBasePath = config.externalIntegration?.schemaBasePath || './';
   const datasourceFiles = config.externalIntegration?.dataSources || [];

package/lib/datasource/validate.js

@@ -242,9 +242,7 @@ async function validateDatasourceFile(filePathOrKey) {
     };
   }
 
-  const fieldRefErrors = validateFieldReferences(parsed);
-  const abacErrors = validateAbac(parsed);
-  const postSchemaErrors = [...fieldRefErrors, ...abacErrors];
+  const postSchemaErrors = collectPostSchemaErrors(parsed);
   if (postSchemaErrors.length > 0) {
     return {
       valid: false,
@@ -264,6 +262,17 @@ async function validateDatasourceFile(filePathOrKey) {
   };
 }
 
+/**
+ * @param {object} parsed
+ * @returns {string[]}
+ */
+function collectPostSchemaErrors(parsed) {
+  return [
+    ...validateFieldReferences(parsed),
+    ...validateAbac(parsed)
+  ];
+}
+
 /**
  * Validates parsed datasource JSON (same rules as {@link validateDatasourceFile}, without reading a file).
  *
@@ -294,9 +303,7 @@ function validateDatasourceParsed(parsed) {
     };
   }
 
-  const fieldRefErrors = validateFieldReferences(parsed);
-  const abacErrors = validateAbac(parsed);
-  const postSchemaErrors = [...fieldRefErrors, ...abacErrors];
+  const postSchemaErrors = collectPostSchemaErrors(parsed);
   if (postSchemaErrors.length > 0) {
     return {
       valid: false,

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

@@ -133,12 +133,50 @@ function extractSystemKey(systemFilePath) {
   return systemFileName.replace(/-deploy$/, '');
 }
 
+/**
+ * Role Assistant (digitalWorker) deploy uses upload, not controller deploy.
+ * @async
+ * @param {string} appName - Application name
+ * @param {Object} options - Deploy options
+ * @param {boolean} compact - Quiet UI when true
+ * @param {Object} manifest - Controller manifest
+ * @returns {Promise<Object|null>} Upload result, or null when not a digital worker
+ */
+async function uploadDigitalWorkerIfNeeded(appName, options, _compact, manifest) {
+  const systemKind =
+    manifest && manifest.system && typeof manifest.system.systemKind === 'string'
+      ? manifest.system.systemKind.trim()
+      : '';
+  if (systemKind !== 'digitalWorker') {
+    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 upload pipeline (controller deploy is skipped).'
+      )
+    );
+  }
+  const { uploadExternalSystem } = require('../commands/upload');
+  return uploadExternalSystem(appName, {
+    ...options,
+    uploadStatus: 'published',
+    // Match standalone `af upload` progress for the final publish.
+    silentResolve: false,
+    suppressPipelineSpinner: false,
+    syncMode: false
+  });
+}
+
 module.exports = {
   loadVariablesYaml,
   validateSingleSystemFile,
   validateSystemFiles,
   validateSingleDatasourceFile,
   validateDatasourceFiles,
-  extractSystemKey
+  extractSystemKey,
+  uploadDigitalWorkerIfNeeded
 };
 

package/lib/external-system/deploy.js

@@ -30,6 +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');
 
 /**
  * Validates manifest on dataplane (dry-run) before controller deploy.
@@ -342,8 +343,20 @@ async function executeDeployAndDisplay(manifest, controllerUrl, environment, aut
  * @param {Object} options - Deployment options
  * @returns {Promise<Object>} Deployment configuration
  */
-async function prepareDeploymentConfig(appName, _options) {
+async function prepareDeploymentConfig(appName, options = {}) {
   const { resolveEnvironment } = require('../core/config');
+  if (options.authConfig && (options.authConfig.token || options.authConfig.clientId)) {
+    const environment = options.environment || (await resolveEnvironment());
+    let controllerUrl = options.controllerUrl || '';
+    if (!controllerUrl) {
+      controllerUrl = await resolveControllerUrl();
+    }
+    if (!controllerUrl) {
+      throw new Error('Controller URL is required. Run "aifabrix login" first.');
+    }
+    return { environment, controllerUrl, authConfig: options.authConfig };
+  }
+
   const environment = await resolveEnvironment();
   const controllerUrl = await resolveControllerUrl();
   const authConfig = await getDeploymentAuth(controllerUrl, environment, appName);
@@ -413,24 +426,27 @@ async function runExternalSystemDeployFlow(appName, options) {
   const compact = options.verbose !== true;
   const { appPath } = await detectAppType(appName);
   logOfflinePathWhenType(appPath);
-
   if (!compact) {
     logger.log(chalk.blue(`\n🚀 Deploying external system: ${appName}`));
   }
-
   await validateExternalSystemForDeploy(appName, options, compact);
-
   const gateOutcomes = await runDeployGateOrchestrator(appName, {
     ...options,
-    quietDeployUi: compact
+    // Compact deploy still shows step progress; only JSON mode stays fully quiet.
+    quietDeployUi: options.json === true
   });
-
   await syncDeployJsonFromSources(appName);
-
   const manifest = await generateControllerManifest(appName, options);
-
+  const digitalWorkerResult = await uploadDigitalWorkerIfNeeded(
+    appName,
+    options,
+    compact,
+    manifest
+  );
+  if (digitalWorkerResult) {
+    return digitalWorkerResult;
+  }
   const { environment, controllerUrl, authConfig } = await prepareDeploymentConfig(appName, options);
-
   let dataplaneUrl;
   try {
     dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig, {
@@ -439,9 +455,7 @@ async function runExternalSystemDeployFlow(appName, options) {
   } catch (err) {
     throw new Error(`Failed to resolve dataplane URL before deploy: ${err.message}`);
   }
-
   await validateDataplaneManifestForDeploy(manifest, authConfig, dataplaneUrl, compact);
-
   return executeDeployAndDisplay(manifest, controllerUrl, environment, authConfig, {
     ...options,
     gateOutcomes,