@aifabrix/builder 2.38.0 → 2.39.0

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/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
@@ -373,6 +391,7 @@ 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

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);
 }
 
 /**

package/lib/app/run-helpers.js

@@ -31,6 +31,9 @@ const { resolveVersionForApp } = require('../utils/image-version');
 
 const execAsync = promisify(exec);
 
+/** Template apps (keycloak, miso-controller, dataplane) - never update variables.yaml when running */
+const TEMPLATE_APP_KEYS = ['keycloak', 'miso-controller', 'dataplane'];
+
 // Re-export container helper functions
 const checkImageExists = containerHelpers.checkImageExists;
 const checkContainerRunning = containerHelpers.checkContainerRunning;
@@ -140,15 +143,17 @@ async function validateAppConfiguration(appName) {
 }
 
 /**
- * Resolves version from image and updates builder/variables.yaml when running
+ * Resolves version from image and updates builder/variables.yaml when running.
+ * Template apps (keycloak, miso-controller, dataplane) are never updated - variables.yaml stays pristine.
  * @async
  * @param {string} appName - Application name
  * @param {Object} appConfig - Application configuration
  * @param {boolean} debug - Enable debug logging
  */
 async function resolveAndUpdateVersion(appName, appConfig, debug) {
+  const isTemplateApp = TEMPLATE_APP_KEYS.includes(appName);
   const resolved = await resolveVersionForApp(appName, appConfig, {
-    updateBuilder: true,
+    updateBuilder: !isTemplateApp,
     builderPath: pathsUtil.getBuilderPath(appName)
   });
   if (resolved.fromImage && resolved.updated && debug) {

package/lib/app/show-display.js

@@ -31,14 +31,21 @@ function logApplicationRequired(a) {
   logger.log(`  Port:          ${port}`);
 }
 
+const APPLICATION_OPTIONAL_FIELDS = [
+  { key: 'deploymentKey', label: 'Deployment' },
+  { key: 'image', label: 'Image' },
+  { key: 'registryMode', label: 'Registry' },
+  { key: 'healthCheck', label: 'Health' },
+  { key: 'build', label: 'Build' },
+  { key: 'status', label: 'Status' },
+  { key: 'url', label: 'URL' },
+  { key: 'internalUrl', label: 'Internal URL' }
+];
+
 function logApplicationOptional(a) {
-  if (a.deploymentKey !== undefined) logger.log(`  Deployment:    ${a.deploymentKey ?? '—'}`);
-  if (a.image !== undefined) logger.log(`  Image:         ${a.image ?? '—'}`);
-  if (a.registryMode !== undefined) logger.log(`  Registry:      ${a.registryMode ?? '—'}`);
-  if (a.healthCheck !== undefined) logger.log(`  Health:        ${a.healthCheck ?? '—'}`);
-  if (a.build !== undefined) logger.log(`  Build:         ${a.build ?? '—'}`);
-  if (a.status !== undefined) logger.log(`  Status:        ${a.status ?? '—'}`);
-  if (a.url !== undefined) logger.log(`  URL:           ${a.url ?? '—'}`);
+  APPLICATION_OPTIONAL_FIELDS.forEach(({ key, label }) => {
+    if (a[key] !== undefined) logger.log(`  ${(label + ':').padEnd(16)} ${a[key] ?? '—'}`);
+  });
 }
 
 function logApplicationFields(a) {
@@ -75,10 +82,15 @@ function logRolesSection(roles) {
   });
 }
 
-function logPermissionsSection(permissions) {
-  if (permissions.length === 0) return;
+function logPermissionsSection(permissions, opts = {}) {
+  const showWhenEmpty = opts.showWhenEmpty || false;
+  if (permissions.length === 0 && !showWhenEmpty) return;
   logger.log('');
   logger.log('🛡️ Permissions');
+  if (permissions.length === 0) {
+    logger.log('  (none)');
+    return;
+  }
   permissions.forEach((p) => {
     const name = p.name ?? '—';
     const roleList = (p.roles || []).join(', ');
@@ -186,8 +198,10 @@ function logExternalSystemSection(ext) {
 /**
  * Format and print human-readable show output (offline or online).
  * @param {Object} summary - Unified summary (buildOfflineSummaryFromDeployJson or buildOnlineSummary)
+ * @param {Object} [options] - Display options
+ * @param {boolean} [options.permissionsOnly] - When true, output only source and Permissions section
  */
-function display(summary) {
+function display(summary, options = {}) {
   const a = summary.application;
   const roles = summary.roles ?? a.roles ?? [];
   const permissions = summary.permissions ?? a.permissions ?? [];
@@ -197,9 +211,14 @@ function display(summary) {
   const dbNames = Array.isArray(databases) ? databases.map((d) => (d && d.name) || d).filter(Boolean) : [];
 
   logSourceAndHeader(summary);
+  if (options.permissionsOnly) {
+    logPermissionsSection(permissions, { showWhenEmpty: true });
+    logger.log('');
+    return;
+  }
   logApplicationSection(a, summary.isExternal);
   logRolesSection(roles);
-  logPermissionsSection(permissions);
+  /* Permissions section shown only when --permissions is set (permissionsOnly mode) */
   logAuthSection(authentication);
   logConfigurationsSection(portalInputConfigurations);
   logDatabasesSection(dbNames);