@aifabrix/builder 2.37.9 → 2.39.0

package/lib/api/external-systems.api.js

@@ -9,6 +9,7 @@ const { ApiClient } = require('./index');
 /**
  * List external systems
  * GET /api/v1/external/systems
+ * @requiresPermission {Dataplane} external-system:read
  * @async
  * @function listExternalSystems
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -32,6 +33,7 @@ async function listExternalSystems(dataplaneUrl, authConfig, options = {}) {
 /**
  * Create external system
  * POST /api/v1/external/systems
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function createExternalSystem
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -50,12 +52,16 @@ async function createExternalSystem(dataplaneUrl, authConfig, systemData) {
 /**
  * Get external system details
  * GET /api/v1/external/systems/{systemIdOrKey}
+ * @requiresPermission {Dataplane} external-system:read
  * @async
  * @function getExternalSystem
  * @param {string} dataplaneUrl - Dataplane base URL
  * @param {string} systemIdOrKey - System ID or key
  * @param {Object} authConfig - Authentication configuration
- * @returns {Promise<Object>} External system details response
+ * @returns {Promise<Object>} External system details response. May include optional fields:
+ *   - {string} [mcpServerUrl] - Full URL of external system MCP server when configured
+ *   - {string} [apiDocumentUrl] - Full URL of API document (OpenAPI spec) when configured
+ *   - {string} [openApiDocsPageUrl] - Full URL of dataplane API docs page when showOpenApiDocs is true
  * @throws {Error} If request fails
  */
 async function getExternalSystem(dataplaneUrl, systemIdOrKey, authConfig) {
@@ -66,6 +72,7 @@ async function getExternalSystem(dataplaneUrl, systemIdOrKey, authConfig) {
 /**
  * Update external system
  * PUT /api/v1/external/systems/{systemIdOrKey}
+ * @requiresPermission {Dataplane} external-system:update
  * @async
  * @function updateExternalSystem
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -85,6 +92,7 @@ async function updateExternalSystem(dataplaneUrl, systemIdOrKey, authConfig, upd
 /**
  * Delete external system (soft delete)
  * DELETE /api/v1/external/systems/{systemIdOrKey}
+ * @requiresPermission {Dataplane} external-system:delete
  * @async
  * @function deleteExternalSystem
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -101,6 +109,7 @@ async function deleteExternalSystem(dataplaneUrl, systemIdOrKey, authConfig) {
 /**
  * Get full config with application schema and dataSources
  * GET /api/v1/external/systems/{systemIdOrKey}/config
+ * @requiresPermission {Dataplane} external-system:read
  * @async
  * @function getExternalSystemConfig
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -117,6 +126,7 @@ async function getExternalSystemConfig(dataplaneUrl, systemIdOrKey, authConfig)
 /**
  * Create external system from integration template
  * POST /api/v1/external/systems/from-template
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function createFromTemplate
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -138,6 +148,7 @@ async function createFromTemplate(dataplaneUrl, authConfig, templateData) {
 /**
  * List OpenAPI files for system
  * GET /api/v1/external/systems/{systemIdOrKey}/openapi-files
+ * @requiresPermission {Dataplane} external-system:read
  * @async
  * @function listOpenAPIFiles
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -157,6 +168,7 @@ async function listOpenAPIFiles(dataplaneUrl, systemIdOrKey, authConfig, options
 /**
  * List OpenAPI endpoints for system
  * GET /api/v1/external/systems/{systemIdOrKey}/openapi-endpoints
+ * @requiresPermission {Dataplane} external-system:read
  * @async
  * @function listOpenAPIEndpoints
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -176,6 +188,7 @@ async function listOpenAPIEndpoints(dataplaneUrl, systemIdOrKey, authConfig, opt
 /**
  * Publish external system
  * POST /api/v1/external/systems/{systemIdOrKey}/publish
+ * @requiresPermission {Dataplane} external-system:update (or publish scope per dataplane spec)
  * @async
  * @function publishExternalSystem
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -196,6 +209,7 @@ async function publishExternalSystem(dataplaneUrl, systemIdOrKey, authConfig, pu
 /**
  * Rollback external system to version
  * POST /api/v1/external/systems/{systemIdOrKey}/rollback
+ * @requiresPermission {Dataplane} external-system:update
  * @async
  * @function rollbackExternalSystem
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -216,6 +230,7 @@ async function rollbackExternalSystem(dataplaneUrl, systemIdOrKey, authConfig, r
 /**
  * Save external system as integration template
  * POST /api/v1/external/systems/{systemIdOrKey}/save-template
+ * @requiresPermission {Dataplane} external-system:update
  * @async
  * @function saveAsTemplate
  * @param {string} dataplaneUrl - Dataplane base URL

package/lib/api/pipeline.api.js

@@ -9,6 +9,7 @@ const { ApiClient } = require('./index');
 /**
  * Validate deployment configuration
  * POST /api/v1/pipeline/{envKey}/validate
+ * @requiresPermission {Controller} applications:deploy
  * @async
  * @function validatePipeline
  * @param {string} controllerUrl - Controller base URL
@@ -31,6 +32,7 @@ async function validatePipeline(controllerUrl, envKey, authConfig, validationDat
 /**
  * Deploy application using validateToken
  * POST /api/v1/pipeline/{envKey}/deploy
+ * @requiresPermission {Controller} applications:deploy
  * @async
  * @function deployPipeline
  * @param {string} controllerUrl - Controller base URL
@@ -52,6 +54,7 @@ async function deployPipeline(controllerUrl, envKey, authConfig, deployData) {
 /**
  * Get deployment status for CI/CD
  * GET /api/v1/pipeline/{envKey}/deployments/{deploymentId}
+ * @requiresPermission {Controller} applications:deploy
  * @async
  * @function getPipelineDeployment
  * @param {string} controllerUrl - Controller base URL
@@ -69,6 +72,7 @@ async function getPipelineDeployment(controllerUrl, envKey, deploymentId, authCo
 /**
  * Pipeline health check
  * GET /api/v1/pipeline/{envKey}/health
+ * @requiresPermission {Controller} Public (no auth required)
  * @async
  * @function getPipelineHealth
  * @param {string} controllerUrl - Controller base URL
@@ -87,7 +91,7 @@ async function getPipelineHealth(controllerUrl, envKey) {
  * Request body: external system JSON (external-system.schema.json). Optional field in body:
  * generateMcpContract (boolean, default true). Optional: generateOpenApiContract (boolean).
  * Do not use query parameters for MCP; use the field in the body only.
- *
+ * @requiresPermission {Dataplane} Authenticated (oauth2: [])
  * @async
  * @function publishSystemViaPipeline
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -107,7 +111,7 @@ async function publishSystemViaPipeline(dataplaneUrl, authConfig, systemConfig)
  * Publish datasource via dataplane pipeline endpoint
  * POST /api/v1/pipeline/{systemKey}/publish
  * No generateMcpContract for this endpoint; dataplane always uses default (MCP generated).
- *
+ * @requiresPermission {Dataplane} Authenticated (oauth2: [])
  * @async
  * @function publishDatasourceViaPipeline
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -127,6 +131,7 @@ async function publishDatasourceViaPipeline(dataplaneUrl, systemKey, authConfig,
 /**
  * Test datasource via dataplane pipeline endpoint
  * POST /api/v1/pipeline/{systemKey}/{datasourceKey}/test
+ * @requiresPermission {Dataplane} Authenticated (oauth2: [])
  * @async
  * @function testDatasourceViaPipeline
  * @param {Object} params - Function parameters
@@ -156,6 +161,7 @@ async function testDatasourceViaPipeline({ dataplaneUrl, systemKey, datasourceKe
 /**
  * Deploy external system via dataplane pipeline endpoint
  * POST /api/v1/pipeline/deploy
+ * @requiresPermission {Dataplane} Authenticated (oauth2: [])
  * @async
  * @function deployExternalSystemViaPipeline
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -174,6 +180,7 @@ async function deployExternalSystemViaPipeline(dataplaneUrl, authConfig, systemC
 /**
  * Deploy datasource via dataplane pipeline endpoint
  * POST /api/v1/pipeline/{systemKey}/deploy
+ * @requiresPermission {Dataplane} Authenticated (oauth2: [])
  * @async
  * @function deployDatasourceViaPipeline
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -196,7 +203,7 @@ async function deployDatasourceViaPipeline(dataplaneUrl, systemKey, authConfig,
  * Body: { version, application, dataSources }. Include application.generateMcpContract
  * and/or application.generateOpenApiContract to control contract generation when
  * publishing this upload (publish reads from stored config; no query param on publish).
- *
+ * @requiresPermission {Dataplane} Authenticated (oauth2: [])
  * @async
  * @function uploadApplicationViaPipeline
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -215,6 +222,7 @@ async function uploadApplicationViaPipeline(dataplaneUrl, authConfig, applicatio
 /**
  * Validate upload via dataplane pipeline endpoint
  * POST /api/v1/pipeline/upload/{uploadId}/validate
+ * @requiresPermission {Dataplane} Authenticated (oauth2: [])
  * @async
  * @function validateUploadViaPipeline
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -235,7 +243,7 @@ async function validateUploadViaPipeline(dataplaneUrl, uploadId, authConfig) {
  * that was uploaded (application.generateMcpContract, application.generateOpenApiContract).
  * To control MCP/OpenAPI, include those fields in the application object when calling
  * uploadApplicationViaPipeline.
- *
+ * @requiresPermission {Dataplane} Authenticated (oauth2: [])
  * @async
  * @function publishUploadViaPipeline
  * @param {string} dataplaneUrl - Dataplane base URL

package/lib/api/service-users.api.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Service users API functions (create service user with one-time secret)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { ApiClient } = require('./index');
+
+/**
+ * Create a service user (username, email, redirectUris, groupIds); return one-time secret
+ * POST /api/v1/service-users
+ * @requiresPermission {Controller} service-user:create
+ * @async
+ * @function createServiceUser
+ * @param {string} controllerUrl - Controller base URL
+ * @param {Object} authConfig - Authentication configuration (bearer or client-credentials)
+ * @param {Object} body - Request body
+ * @param {string} body.username - Username (required)
+ * @param {string} body.email - Email (required)
+ * @param {string[]} body.redirectUris - Redirect URIs for OAuth2 (required, min 1)
+ * @param {string[]} body.groupNames - Group names (required, e.g. AI-Fabrix-Developers)
+ * @param {string} [body.description] - Optional description
+ * @returns {Promise<Object>} Response with clientId and one-time clientSecret
+ * @throws {Error} If request fails (400/401/403 or network)
+ */
+async function createServiceUser(controllerUrl, authConfig, body) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post('/api/v1/service-users', {
+    body: {
+      username: body.username,
+      email: body.email,
+      redirectUris: body.redirectUris,
+      groupNames: body.groupNames,
+      description: body.description
+    }
+  });
+}
+
+module.exports = {
+  createServiceUser
+};

package/lib/api/types/applications.types.js

@@ -30,7 +30,7 @@
  * @property {string} displayName - Human-readable application name
  * @property {string} description - Application description
  * @property {string} type - Azure application type ('webapp' | 'functionapp' | 'api' | 'service' | 'external')
- * @property {string} deploymentKey - SHA256 hash of deployment manifest
+ * @property {string} [deploymentKey] - SHA256 hash of deployment manifest (Controller adds internally)
  * @property {string} [image] - Container image reference
  * @property {string} [registryMode] - Registry mode ('acr' | 'external' | 'public')
  * @property {number} [port] - Application port number

package/lib/api/types/deployments.types.js

@@ -30,7 +30,7 @@
  * @property {string} displayName - Human-readable application name
  * @property {string} description - Application description
  * @property {string} type - Azure application type
- * @property {string} deploymentKey - SHA256 hash of deployment manifest
+ * @property {string} [deploymentKey] - SHA256 hash of deployment manifest (Controller adds internally)
  * @property {*} [additionalProperties] - Additional configuration properties
  */
 

package/lib/api/types/pipeline.types.js

@@ -11,7 +11,7 @@
  * @property {string} displayName - Human-readable application name
  * @property {string} description - Application description
  * @property {string} type - Azure application type
- * @property {string} deploymentKey - SHA256 hash of deployment manifest
+ * @property {string} [deploymentKey] - SHA256 hash of deployment manifest (Controller adds internally)
  * @property {*} [additionalProperties] - Additional configuration properties
  */
 

package/lib/api/types/service-users.types.js

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Service users API type definitions
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Service user create request body (builder sends this to controller)
+ * @typedef {Object} ServiceUserCreateRequest
+ * @property {string} username - Username (1–100 chars, e.g. api-client-001)
+ * @property {string} email - Email address
+ * @property {string[]} redirectUris - Allowed redirect URIs for OAuth2 (min 1)
+ * @property {string[]} groupNames - Group names to assign (e.g. AI-Fabrix-Developers)
+ * @property {string} [description] - Optional description (max 500 chars)
+ */
+
+/**
+ * Service user create response (clientSecret is one-time-only; store at creation time)
+ * @typedef {Object} ServiceUserCreateResponse
+ * @property {string} clientId - Stable identifier for the service user
+ * @property {string} clientSecret - One-time-only secret; not returned by any other endpoint
+ * @property {boolean} [success] - Optional wrapper flag
+ * @property {string} [createdAt] - Optional creation timestamp (ISO 8601)
+ */

package/lib/api/wizard.api.js

@@ -10,6 +10,7 @@ const { uploadFile } = require('../utils/file-upload');
 /**
  * Create wizard session
  * POST /api/v1/wizard/sessions
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function createWizardSession
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -33,6 +34,7 @@ async function createWizardSession(dataplaneUrl, authConfig, mode, systemIdOrKey
 /**
  * Get wizard session
  * GET /api/v1/wizard/sessions/{sessionId}
+ * @requiresPermission {Dataplane} external-system:read or external-system:create
  * @async
  * @function getWizardSession
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -49,6 +51,7 @@ async function getWizardSession(dataplaneUrl, sessionId, authConfig) {
 /**
  * Update wizard session
  * PUT /api/v1/wizard/sessions/{sessionId}
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function updateWizardSession
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -80,6 +83,7 @@ async function updateWizardSession(dataplaneUrl, sessionId, authConfig, updateDa
 /**
  * Delete wizard session
  * DELETE /api/v1/wizard/sessions/{sessionId}
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function deleteWizardSession
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -96,6 +100,7 @@ async function deleteWizardSession(dataplaneUrl, sessionId, authConfig) {
 /**
  * Get wizard session progress
  * GET /api/v1/wizard/sessions/{sessionId}/progress
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function getWizardProgress
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -112,6 +117,7 @@ async function getWizardProgress(dataplaneUrl, sessionId, authConfig) {
 /**
  * Parse OpenAPI file or URL
  * POST /api/v1/wizard/parse-openapi
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function parseOpenApi
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -133,6 +139,7 @@ async function parseOpenApi(dataplaneUrl, authConfig, openApiFilePathOrUrl, isUr
 /**
  * Credential selection for wizard
  * POST /api/v1/wizard/credential-selection
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function credentialSelection
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -154,6 +161,7 @@ async function credentialSelection(dataplaneUrl, authConfig, selectionData) {
 /**
  * Detect API type from OpenAPI spec
  * POST /api/v1/wizard/detect-type
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function detectType
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -172,6 +180,7 @@ async function detectType(dataplaneUrl, authConfig, openapiSpec) {
 /**
  * Generate configuration via AI
  * POST /api/v1/wizard/generate-config
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function generateConfig
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -202,6 +211,7 @@ async function generateConfig(dataplaneUrl, authConfig, config) {
 /**
  * Generate configuration via AI (streaming)
  * POST /api/v1/wizard/generate-config-stream
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function generateConfigStream
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -220,6 +230,7 @@ async function generateConfigStream(dataplaneUrl, authConfig, config) {
 /**
  * Validate wizard configuration
  * POST /api/v1/wizard/validate
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function validateWizardConfig
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -242,6 +253,7 @@ async function validateWizardConfig(dataplaneUrl, authConfig, systemConfig, data
 /**
  * Validate all completed wizard steps
  * GET /api/v1/wizard/sessions/{sessionId}/validate
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function validateAllSteps
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -258,6 +270,7 @@ async function validateAllSteps(dataplaneUrl, sessionId, authConfig) {
 /**
  * Validate specific wizard step
  * POST /api/v1/wizard/sessions/{sessionId}/validate-step
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function validateStep
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -275,6 +288,7 @@ async function validateStep(dataplaneUrl, sessionId, authConfig, stepNumber) {
 /**
  * Get configuration preview with summaries
  * GET /api/v1/wizard/preview/{sessionId}
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function getPreview
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -291,6 +305,7 @@ async function getPreview(dataplaneUrl, sessionId, authConfig) {
 /**
  * Test MCP server connection
  * POST /api/v1/wizard/test-mcp-connection
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function testMcpConnection
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -313,6 +328,7 @@ async function testMcpConnection(dataplaneUrl, authConfig, serverUrl, token) {
 /**
  * Get deployment documentation for a system (from dataplane DB only)
  * GET /api/v1/wizard/deployment-docs/{systemKey}
+ * @requiresPermission {Dataplane} external-system:read
  * @async
  * @function getDeploymentDocs
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -330,6 +346,7 @@ async function getDeploymentDocs(dataplaneUrl, authConfig, systemKey) {
  * Generate deployment documentation with variables.yaml and deploy JSON for better quality
  * POST /api/v1/wizard/deployment-docs/{systemKey}
  * Sends deployJson and variablesYaml in the request body so the dataplane can align README with the integration folder.
+ * @requiresPermission {Dataplane} external-system:update
  * @async
  * @function postDeploymentDocs
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -353,6 +370,7 @@ async function postDeploymentDocs(dataplaneUrl, authConfig, systemKey, body = nu
  * GET /api/v1/wizard/platforms
  * Expected response: { platforms: [ { key: string, displayName?: string } ] } or equivalent.
  * On 404 or error, returns empty array (caller should hide "Known platform" choice).
+ * @requiresPermission {Dataplane} external-system:read or unauthenticated
  * @async
  * @function getWizardPlatforms
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -370,6 +388,26 @@ async function getWizardPlatforms(dataplaneUrl, authConfig) {
   }
 }
 
+/**
+ * List credentials for wizard selection (Step 3)
+ * GET /api/v1/wizard/credentials
+ * @requiresPermission {Dataplane} credential:read or external-system:create
+ * @async
+ * @function listWizardCredentials
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} [options] - Query options
+ * @param {boolean} [options.activeOnly] - If true, return only active credentials
+ * @returns {Promise<Object>} Response with credentials list (e.g. data.credentials or data.items)
+ * @throws {Error} If request fails
+ */
+async function listWizardCredentials(dataplaneUrl, authConfig, options = {}) {
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  return await client.get('/api/v1/wizard/credentials', {
+    params: options
+  });
+}
+
 module.exports = {
   createWizardSession,
   getWizardSession,
@@ -388,5 +426,6 @@ module.exports = {
   testMcpConnection,
   getDeploymentDocs,
   postDeploymentDocs,
-  getWizardPlatforms
+  getWizardPlatforms,
+  listWizardCredentials
 };

package/lib/app/deploy.js

@@ -17,6 +17,7 @@ const pushUtils = require('../deployment/push');
 const logger = require('../utils/logger');
 const { detectAppType, getBuilderPath, getIntegrationPath } = require('../utils/paths');
 const { checkApplicationExists } = require('../utils/app-existence');
+const { getApplicationStatus } = require('../api/applications.api');
 const { loadDeploymentConfig } = require('./deploy-config');
 
 /**
@@ -218,6 +219,26 @@ function displayDeploymentResults(result) {
   }
 }
 
+/**
+ * Fetches app URL from controller application status and displays it.
+ * On API failure or missing URL, shows controllerUrl so the user always sees where the app is.
+ * @param {string} controllerUrl - Controller base URL (used as fallback)
+ * @param {string} envKey - Environment key
+ * @param {string} appKey - Application key (manifest.key)
+ * @param {Object} authConfig - Auth used for deployment (same as for status)
+ */
+async function displayAppUrlFromController(controllerUrl, envKey, appKey, authConfig) {
+  let url = null;
+  try {
+    const res = await getApplicationStatus(controllerUrl, envKey, appKey, authConfig);
+    const body = res?.data;
+    url = (body && (body.url || body.data?.url)) || res?.url || null;
+  } catch (_) {
+    // Use controllerUrl fallback below
+  }
+  logger.log(chalk.green(`   ✓ App running at ${url || controllerUrl}`));
+}
+
 /**
  * Check if app is external and handle external deployment.
  * When options.type === 'external', forces deployment from integration/<app> (no app register needed).
@@ -272,6 +293,59 @@ function validateImageIsPullable(imageRef, appName) {
   }
 }
 
+/**
+ * Throws an error when deployment status is failed or cancelled
+ * @param {string} status - Status value
+ * @param {Object} statusObj - Full status object from result
+ * @throws {Error}
+ */
+function throwIfDeploymentFailed(status, statusObj) {
+  if (status !== 'failed' && status !== 'cancelled') return;
+  const msg =
+    statusObj.message ||
+    statusObj.error ||
+    (status === 'cancelled' ? 'Deployment cancelled' : 'Deployment failed');
+  const err = new Error(`Deployment ${status}: ${msg}`);
+  err.formatted = `Deployment ${status}.\n\n${msg}`;
+  err.deploymentStatus = statusObj;
+  throw err;
+}
+
+/**
+ * Enhances 401 error with rotate-secret hint when app exists
+ * @param {Error} error - Caught error
+ * @param {boolean} appExists - Whether app exists in controller
+ * @param {string} appName - Application name
+ * @param {string} envKey - Environment key
+ * @throws {Error} Enhanced or original error
+ */
+function enhanceAuthErrorIfNeeded(error, appExists, appName, envKey) {
+  if (!appExists || error.status !== 401 || error.message.includes('rotate-secret')) {
+    throw error;
+  }
+  const enhancedError = new Error(
+    `${error.message}\n\n💡 The application '${appName}' exists in environment '${envKey}'. ` +
+      `To fix invalid credentials, rotate the application secret:\n   aifabrix app rotate-secret ${appName}`
+  );
+  enhancedError.status = 401;
+  enhancedError.formatted = error.formatted || enhancedError.message;
+  throw enhancedError;
+}
+
+/**
+ * Apply image/registry overrides from options to manifest
+ * @param {Object} manifest - Deployment manifest
+ * @param {Object} options - Deployment options
+ */
+function applyManifestOverrides(manifest, options) {
+  if (options.imageOverride || options.image) {
+    manifest.image = options.imageOverride || options.image;
+  }
+  if (options.registryMode) {
+    manifest.registryMode = options.registryMode;
+  }
+}
+
 /**
  * Execute standard application deployment flow
  * @async
@@ -283,38 +357,29 @@ function validateImageIsPullable(imageRef, appName) {
 async function executeStandardDeployment(appName, options) {
   const config = await loadDeploymentConfig(appName, options);
   const controllerUrl = config.controllerUrl || 'unknown';
-
-  // Check if application exists before deployment
   const appExists = await checkApplicationExists(appName, controllerUrl, config.envKey, config.auth);
 
   const { manifest, manifestPath } = await generateAndValidateManifest(appName);
-  if (options.imageOverride || options.image) {
-    manifest.image = options.imageOverride || options.image;
-  }
-  if (options.registryMode) {
-    manifest.registryMode = options.registryMode;
-  }
-
+  applyManifestOverrides(manifest, options);
   validateImageIsPullable(manifest.image, appName);
-
   displayDeploymentInfo(manifest, manifestPath);
 
   try {
     const result = await executeDeployment(manifest, config);
     displayDeploymentResults(result);
-    return { result, controllerUrl, appExists };
-  } catch (error) {
-    // Enhance error if app exists and credentials are invalid
-    if (appExists && error.status === 401 && !error.message.includes('rotate-secret')) {
-      const enhancedError = new Error(
-        `${error.message}\n\n💡 The application '${appName}' exists in environment '${config.envKey}'. ` +
-        `To fix invalid credentials, rotate the application secret:\n   aifabrix app rotate-secret ${appName}`
+    const status = result.status?.status;
+    throwIfDeploymentFailed(status, result.status || {});
+    if (status === 'completed') {
+      await displayAppUrlFromController(
+        config.controllerUrl,
+        config.envKey,
+        manifest.key,
+        config.auth
       );
-      enhancedError.status = 401;
-      enhancedError.formatted = error.formatted || enhancedError.message;
-      throw enhancedError;
     }
-    throw error;
+    return { result, controllerUrl, appExists };
+  } catch (error) {
+    enhanceAuthErrorIfNeeded(error, appExists, appName, config.envKey);
   }
 }
 

package/lib/app/rotate-secret.js

@@ -9,7 +9,7 @@
  */
 
 const chalk = require('chalk');
-const { getConfig, normalizeControllerUrl, resolveEnvironment } = require('../core/config');
+const { getConfig, normalizeControllerUrl, resolveEnvironment, clearClientToken } = require('../core/config');
 const { resolveControllerUrl } = require('../utils/controller-url');
 const { getOrRefreshDeviceToken } = require('../utils/token-manager');
 const { rotateApplicationSecret } = require('../api/applications.api');
@@ -324,6 +324,8 @@ async function executeRotation(appKey, actualControllerUrl, environment, token)
   const { credentials, message } = validateResponse(response);
   await saveCredentialsLocally(appKey, credentials, actualControllerUrl);
   displayRotationResults(appKey, environment, credentials, actualControllerUrl, message);
+  // Clear cached client token so next deploy uses new credentials (avoids "Invalid or expired credentials" when running deploy/up-dataplane immediately after rotate)
+  await clearClientToken(environment, appKey);
 }
 
 /**