@aifabrix/builder 2.43.0 → 2.44.0

package/lib/cli/setup-service-user.js

@@ -174,7 +174,7 @@ function addUpdateRedirectUrisCommand(serviceUser) {
 function setupServiceUserCommands(program) {
   const serviceUser = program
     .command('service-user')
-    .description('Create and manage service users (API clients) for integrations and CI')
+    .description('OAuth service users on Controller (integrations, CI)')
     .addHelpText('after', HELP_AFTER);
   addCreateCommand(serviceUser);
   addListCommand(serviceUser);

package/lib/cli/setup-utility.js

@@ -1,3 +1,4 @@
+const { formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
 /**
  * CLI utility command setup (resolve, json, split-json, show, validate, diff).
  *
@@ -15,6 +16,19 @@ const logger = require('../utils/logger');
 const { handleCommandError, logOfflinePathWhenType } = require('../utils/cli-utils');
 const { detectAppType, getDeployJsonPath, getResolveAppPath } = require('../utils/paths');
 
+const JSON_HELP_AFTER = `
+Example:
+  $ aifabrix json myapp
+Generates *-deploy.json (or application-schema.json) for commit before deploy.
+`;
+
+const VALIDATE_HELP_AFTER = `
+Examples:
+  $ aifabrix validate myapp
+  $ aifabrix validate --integration
+  $ aifabrix validate --builder
+`;
+
 /**
  * Resolve app path and type for split-json (integration first, then builder).
  *
@@ -67,7 +81,7 @@ async function handleSplitJsonCommand(appName, options) {
  * @returns {void}
  */
 function logSplitJsonResult(result) {
-  logger.log(chalk.green('\n✓ Successfully split deployment JSON into component files:'));
+  logger.log(formatSuccessParagraph('Successfully split deployment JSON into component files:'));
   logger.log(`  • env.template: ${result.envTemplate}`);
   logger.log(`  • application.yaml: ${result.variables}`);
   if (result.systemFile) {
@@ -88,7 +102,7 @@ function logSplitJsonResult(result) {
 
 function setupResolveCommand(program) {
   program.command('resolve <app>')
-    .description('Generate .env file from template and validate application files')
+    .description('Generate .env from template; optional validate after')
     .option('-f, --force', 'Generate missing secret keys in secrets file')
     .option('--skip-validation', 'Skip file validation after generating .env')
     .action(async(appName, options) => {
@@ -101,7 +115,7 @@ function setupResolveCommand(program) {
           options.force,
           { appPath, envOnly, skipOutputPath: false, preserveFromPath: null }
         );
-        logger.log(`✓ Generated .env file: ${envPath}`);
+        logger.log(`✔ Generated .env file: ${envPath}`);
         if (envOnly) {
           logger.log(chalk.gray('  (env-only mode: validation skipped; no application.yaml)'));
         } else if (!options.skipValidation) {
@@ -109,7 +123,7 @@ function setupResolveCommand(program) {
           const result = await validate.validateAppOrFile(appName);
           validate.displayValidationResults(result);
           if (!result.valid) {
-            logger.log(chalk.yellow('\n⚠️  Validation found errors. Fix them before deploying.'));
+            logger.log(chalk.yellow('\n⚠  Validation found errors. Fix them before deploying.'));
             process.exit(1);
           }
         }
@@ -122,19 +136,20 @@ function setupResolveCommand(program) {
 
 function setupJsonCommand(program) {
   program.command('json <app>')
-    .description('Generate deployment JSON to disk (<app>-deploy.json). Use before commit so version control has the correct file.')
+    .description('Write deployment JSON to disk for version control')
+    .addHelpText('after', JSON_HELP_AFTER)
     .action(async(appName, options) => {
       try {
         const result = await generator.generateDeployJsonWithValidation(appName, options);
         if (result.success) {
           const fileName = result.path.includes('application-schema.json') ? 'application-schema.json' : 'deployment JSON';
-          logger.log(`✓ Generated ${fileName}: ${result.path}`);
+          logger.log(`✔ Generated ${fileName}: ${result.path}`);
           if (result.validation.warnings && result.validation.warnings.length > 0) {
-            logger.log('\n⚠️  Warnings:');
+            logger.log('\n⚠  Warnings:');
             result.validation.warnings.forEach(w => logger.log(`   • ${w}`));
           }
         } else {
-          logger.log('❌ Validation failed:');
+          logger.log('✖ Validation failed:');
           (result.validation.errors || []).forEach(e => logger.log(`   • ${e}`));
           process.exit(1);
         }
@@ -147,7 +162,7 @@ function setupJsonCommand(program) {
 
 function setupSplitJsonCommand(program) {
   program.command('split-json <app>')
-    .description('Split deployment JSON into component files (env.template, application.yaml, rbac.yml, README.md)')
+    .description('Split deploy JSON into env.template, application.yaml, rbac, README, …')
     .option('-o, --output <dir>', 'Output directory for component files (defaults to same directory as JSON)')
     .action(async(appName, options) => {
       try {
@@ -160,13 +175,13 @@ function setupSplitJsonCommand(program) {
 }
 
 function setupRepairCommand(program) {
-  program.command('repair <app>')
-    .description('Repair external integration config: fix drift (file lists, app key, datasource alignment, rbac, manifest)')
+  program.command('repair <systemKey>')
+    .description('Fix external integration drift (files, RBAC, manifest, …)')
     .option('--auth <method>', 'Set authentication method (oauth2, aad, apikey, basic, queryParam, oidc, hmac, none); updates system file and env.template')
     .option('--doc', 'Regenerate README.md from deployment manifest')
     .option('--dry-run', 'Report changes only; do not write')
     .option('--rbac', 'Ensure RBAC permissions per datasource and add default Admin/Reader roles if none exist')
-    .option('--expose', 'Set exposed.attributes on each datasource to all fieldMappings.attributes keys')
+    .option('--expose', 'Set exposed.schema on each datasource from all fieldMappings.attributes keys (metadata.<key>); removes deprecated exposed.attributes if present')
     .option('--sync', 'Add default sync section to datasources that lack it')
     .option('--test', 'Generate testPayload.payloadTemplate and testPayload.expectedResult from attributes')
     .action(async(appName, options) => {
@@ -196,9 +211,9 @@ function setupRepairCommand(program) {
           logger.log(chalk.yellow('\nWould apply:'));
           result.changes.forEach(c => logger.log(chalk.gray(`  ${c}`)));
         } else if (result.updated) {
-          logger.log(chalk.green('\n✓ Repaired external integration config.'));
+          logger.log(formatSuccessParagraph('Repaired external integration config.'));
         } else if (result.readmeRegenerated) {
-          logger.log(chalk.green('\n✓ Regenerated README.md from deployment manifest.'));
+          logger.log(formatSuccessParagraph('Regenerated README.md from deployment manifest.'));
         } else {
           logger.log(chalk.gray('No changes needed; config already matches files on disk.'));
         }
@@ -211,7 +226,7 @@ function setupRepairCommand(program) {
 
 function setupConvertCommand(program) {
   program.command('convert <app>')
-    .description('Convert integration/external system and datasource config files between JSON and YAML')
+    .description('Convert integration config files between JSON and YAML')
     .option('--format <format>', 'Target format: json | yaml (required unless config format is set)')
     .option('-f, --force', 'Skip confirmation prompt')
     .action(async(appName, options) => {
@@ -229,7 +244,7 @@ function setupConvertCommand(program) {
         }
         const { runConvert } = require('../commands/convert');
         const { converted, deleted } = await runConvert(appName, { format: normalized, force: options.force });
-        logger.log(chalk.green('\n✓ Convert complete.'));
+        logger.log(formatSuccessParagraph('Convert complete.'));
         converted.forEach(p => logger.log(`  • ${p}`));
         if (deleted.length > 0) {
           logger.log(chalk.gray('  Removed old files:'));
@@ -243,8 +258,8 @@ function setupConvertCommand(program) {
 }
 
 function setupShowCommand(program) {
-  program.command('show <appKey>')
-    .description('Show application info from local builder/ or integration/ (offline) or from controller (--online)')
+  program.command('show <app>')
+    .description('Show app from local tree (default) or controller (--online)')
     .option('--online', 'Fetch application data from the controller')
     .option('--json', 'Output as JSON')
     .action(async(appKey, options) => {
@@ -303,7 +318,8 @@ async function runValidateCommand(appOrFile, options) {
 
 function setupValidateDiffCommands(program) {
   program.command('validate [appOrFile]')
-    .description('Validate application or external integration file; use --integration or --builder to validate all apps')
+    .description('Validate one app/file or all under integration/ or builder/')
+    .addHelpText('after', VALIDATE_HELP_AFTER)
     .option('--format <format>', 'Output format: json | default (human-readable)')
     .option('--integration', 'Validate all applications under integration/')
     .option('--builder', 'Validate all applications under builder/')
@@ -315,7 +331,7 @@ function setupValidateDiffCommands(program) {
     });
 
   program.command('diff <file1> <file2>')
-    .description('Compare two configuration files (for deployment pipeline)')
+    .description('Diff two config files (optional schema validate)')
     .option('--no-validate', 'Skip schema validation (type check still applied)')
     .action(async(file1, file2, cmd) => {
       try {

package/lib/commands/app-down.js

@@ -1,3 +1,4 @@
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 /**
  * Down-app command – stop container, optionally volumes, then remove image if unused
  *
@@ -7,14 +8,11 @@
  */
 
 const chalk = require('chalk');
-const { exec } = require('child_process');
-const { promisify } = require('util');
 const logger = require('../utils/logger');
 const config = require('../core/config');
 const containerHelpers = require('../utils/app-run-containers');
 const { downApp } = require('../app/down');
-
-const execAsync = promisify(exec);
+const { execWithDockerEnv } = require('../utils/docker-exec');
 
 /**
  * Get image ID of a running container (sha or name:tag)
@@ -24,7 +22,7 @@ const execAsync = promisify(exec);
  */
 async function getContainerImageId(containerName) {
   try {
-    const { stdout } = await execAsync(
+    const { stdout } = await execWithDockerEnv(
       `docker inspect --format='{{.Image}}' ${containerName}`,
       { encoding: 'utf8' }
     );
@@ -43,8 +41,8 @@ async function getContainerImageId(containerName) {
 async function removeImageIfUnused(imageId) {
   if (!imageId) return;
   try {
-    await execAsync(`docker rmi ${imageId}`);
-    logger.log(chalk.green(`✓ Image ${imageId} removed`));
+    await execWithDockerEnv(`docker rmi ${imageId}`);
+    logger.log(formatSuccessLine(`Image ${imageId} removed`));
   } catch (err) {
     const msg = (err && err.message) || '';
     if (msg.includes('in use') || msg.includes('is being used')) {

package/lib/commands/app-install.js

@@ -1,3 +1,4 @@
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 /**
  * Install command – run install (dependencies) inside app container (dev: running; tst: ephemeral with .env).
  *
@@ -81,7 +82,7 @@ async function runInstallInDev(appName, developerId, installCmd) {
   logger.log(chalk.blue(`Running install in container ${containerName}: ${installCmd}\n`));
   const cmd = installCommandForReadOnlyApp(installCmd);
   const envFilePath = await secretsEnvWrite.resolveAndWriteEnvFile(appName, {});
-  return runDockerExec(containerName, cmd, envFilePath);
+  return await runDockerExec(containerName, cmd, envFilePath);
 }
 
 /**
@@ -92,7 +93,9 @@ async function runInstallInDev(appName, developerId, installCmd) {
  * @param {string|null} [envFilePath] - Path to resolved .env for --env-file (optional; when set, install has registry tokens)
  * @returns {Promise<number>} Exit code
  */
-function runDockerExec(containerName, cmd, envFilePath = null) {
+async function runDockerExec(containerName, cmd, envFilePath = null) {
+  const { getDockerExecEnv } = require('../utils/remote-docker-env');
+  const dockerEnv = await getDockerExecEnv();
   return new Promise((resolve) => {
     const args = [
       'exec',
@@ -106,7 +109,8 @@ function runDockerExec(containerName, cmd, envFilePath = null) {
     args.push(containerName, 'sh', '-c', cmd);
     const proc = spawn('docker', args, {
       stdio: 'inherit',
-      shell: false
+      shell: false,
+      env: dockerEnv
     });
     proc.on('close', code => resolve(code !== null ? code : 1));
     proc.on('error', () => resolve(1));
@@ -120,7 +124,9 @@ function runDockerExec(containerName, cmd, envFilePath = null) {
  * @param {string|null} [envFilePath] - Path to .env file for --env-file (optional)
  * @returns {Promise<number>} Exit code
  */
-function runDockerRunEphemeral(fullImage, cmd, envFilePath = null) {
+async function runDockerRunEphemeral(fullImage, cmd, envFilePath = null) {
+  const { getDockerExecEnv } = require('../utils/remote-docker-env');
+  const dockerEnv = await getDockerExecEnv();
   return new Promise((resolve) => {
     const args = ['run', '--rm', '-e', `TMPDIR=${TMPDIR_VALUE}`, '-e', `npm_config_store_dir=${PNPM_STORE_DIR}`, '-e', 'CI=true'];
     if (envFilePath) {
@@ -129,7 +135,8 @@ function runDockerRunEphemeral(fullImage, cmd, envFilePath = null) {
     args.push(fullImage, 'sh', '-c', cmd);
     const proc = spawn('docker', args, {
       stdio: 'inherit',
-      shell: false
+      shell: false,
+      env: dockerEnv
     });
     proc.on('close', code => resolve(code !== null ? code : 1));
     proc.on('error', () => resolve(1));
@@ -157,7 +164,7 @@ async function runAppInstall(appName, options = {}) {
   if (env === 'dev') {
     const code = await runInstallInDev(appName, developerId, installCmd);
     if (code !== 0) process.exit(code);
-    logger.log(chalk.green('✓ Install completed'));
+    logger.log(formatSuccessLine('Install completed'));
     return;
   }
 
@@ -166,7 +173,7 @@ async function runAppInstall(appName, options = {}) {
   const cmd = installCommandForReadOnlyApp(installCmd);
   const code = await runDockerRunEphemeral(fullImage, cmd, envFilePath);
   if (code !== 0) process.exit(code);
-  logger.log(chalk.green('✓ Install completed'));
+  logger.log(formatSuccessLine('Install completed'));
 }
 
 module.exports = { runAppInstall, getInstallCommand };

package/lib/commands/app-logs.js

@@ -7,15 +7,14 @@
  */
 
 const chalk = require('chalk');
-const { exec, spawn } = require('child_process');
+const { spawn } = require('child_process');
 const readline = require('readline');
-const { promisify } = require('util');
 const logger = require('../utils/logger');
 const config = require('../core/config');
 const containerHelpers = require('../utils/app-run-containers');
 const { validateAppName } = require('../app/push');
 
-const execAsync = promisify(exec);
+const { execWithDockerEnv } = require('../utils/docker-exec');
 
 /** Default number of log lines */
 const DEFAULT_TAIL_LINES = 100;
@@ -132,7 +131,7 @@ function passesLevelFilter(lineLevel, minLevel) {
  */
 async function dumpMaskedEnv(containerName) {
   try {
-    const { stdout } = await execAsync(`docker exec ${containerName} env`, { encoding: 'utf8', timeout: 5000 });
+    const { stdout } = await execWithDockerEnv(`docker exec ${containerName} env`, { encoding: 'utf8', timeout: 5000 });
     const lines = stdout.split('\n').filter((l) => l.trim());
     if (lines.length === 0) return;
     logger.log(chalk.bold('\n--- Environment (sensitive values masked) ---\n'));
@@ -156,6 +155,8 @@ async function dumpMaskedEnv(containerName) {
  * @returns {Promise<void>}
  */
 async function runDockerLogs(containerName, options) {
+  const { getDockerExecEnv } = require('../utils/remote-docker-env');
+  const dockerEnv = await getDockerExecEnv();
   const args = options.tail === 0 ? ['logs', containerName] : ['logs', '--tail', String(options.tail), containerName];
   const minLevel =
     options.level !== undefined && options.level !== null && options.level !== ''
@@ -164,14 +165,14 @@ async function runDockerLogs(containerName, options) {
 
   if (minLevel === null || minLevel === undefined || !LOG_LEVELS.includes(minLevel)) {
     return new Promise((resolve, reject) => {
-      const proc = spawn('docker', args, { stdio: 'inherit' });
+      const proc = spawn('docker', args, { stdio: 'inherit', env: dockerEnv });
       proc.on('error', reject);
       proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`docker logs exited with ${code}`))));
     });
   }
 
   return new Promise((resolve, reject) => {
-    const proc = spawn('docker', args, { stdio: ['inherit', 'pipe', 'pipe'] });
+    const proc = spawn('docker', args, { stdio: ['inherit', 'pipe', 'pipe'], env: dockerEnv });
     proc.on('error', reject);
 
     function onLine(line) {
@@ -213,7 +214,9 @@ async function runDockerLogs(containerName, options) {
  * @param {number} [tail] - Lines to show (0 = full, omit --tail)
  * @param {string|null} [minLevel] - Minimum log level to show (debug|info|warn|error)
  */
-function runDockerLogsFollow(containerName, tail, minLevel) {
+async function runDockerLogsFollow(containerName, tail, minLevel) {
+  const { getDockerExecEnv } = require('../utils/remote-docker-env');
+  const dockerEnv = await getDockerExecEnv();
   const args = tail === 0 ? ['logs', '-f', containerName] : ['logs', '-f', '--tail', String(tail), containerName];
   const level =
     minLevel !== undefined && minLevel !== null && minLevel !== ''
@@ -222,7 +225,7 @@ function runDockerLogsFollow(containerName, tail, minLevel) {
   const useFilter = level !== null && level !== undefined && LOG_LEVELS.includes(level);
 
   if (!useFilter) {
-    const proc = spawn('docker', args, { stdio: 'inherit' });
+    const proc = spawn('docker', args, { stdio: 'inherit', env: dockerEnv });
     proc.on('error', (err) => {
       logger.log(chalk.red(`Error: ${err.message}`));
       process.exit(1);
@@ -233,7 +236,7 @@ function runDockerLogsFollow(containerName, tail, minLevel) {
     return;
   }
 
-  const proc = spawn('docker', args, { stdio: ['inherit', 'pipe', 'pipe'] });
+  const proc = spawn('docker', args, { stdio: ['inherit', 'pipe', 'pipe'], env: dockerEnv });
   proc.on('error', (err) => {
     logger.log(chalk.red(`Error: ${err.message}`));
     process.exit(1);
@@ -286,7 +289,7 @@ async function runAppLogs(appKey, options = {}) {
   }
 
   if (follow) {
-    runDockerLogsFollow(containerName, tail, level);
+    await runDockerLogsFollow(containerName, tail, level);
     return;
   }
 

package/lib/commands/app-shell.js

@@ -48,6 +48,8 @@ async function runAppShell(appName, _options = {}) {
 
   logger.log(chalk.blue(`Opening shell in ${containerName} (exit with 'exit' or Ctrl+D)...\n`));
 
+  const { getDockerExecEnv } = require('../utils/remote-docker-env');
+  const dockerEnv = await getDockerExecEnv();
   const envFilePath = await secretsEnvWrite.resolveAndWriteEnvFile(appName, {});
   const proc = spawn('docker', [
     'exec', '-it',
@@ -57,7 +59,8 @@ async function runAppShell(appName, _options = {}) {
     'sh'
   ], {
     stdio: 'inherit',
-    shell: false
+    shell: false,
+    env: dockerEnv
   });
 
   return new Promise((resolve, reject) => {

package/lib/commands/app-test.js

@@ -7,8 +7,8 @@
  */
 
 const { spawn } = require('child_process');
-const chalk = require('chalk');
 const logger = require('../utils/logger');
+const { infoLine, formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 const config = require('../core/config');
 const containerHelpers = require('../utils/app-run-containers');
 const composeGenerator = require('../utils/compose-generator');
@@ -97,9 +97,9 @@ async function runTestsInDev(appName, developerId, testCmd) {
       `Container ${containerName} is not running.\nRun 'aifabrix run ${appName}' first.`
     );
   }
-  logger.log(chalk.blue(`Running tests in container ${containerName}: ${testCmd}\n`));
+  logger.log(infoLine(`ℹ Running tests in container ${containerName}: ${testCmd}\n`));
   const envFilePath = await secretsEnvWrite.resolveAndWriteEnvFile(appName, {});
-  return runDockerExec(containerName, testCmd, envFilePath);
+  return await runDockerExec(containerName, testCmd, envFilePath);
 }
 
 /**
@@ -123,14 +123,14 @@ async function runAppTest(appName, options = {}) {
   if (env === 'dev') {
     const code = await runTestsInDev(appName, developerId, testCmd);
     if (code !== 0) process.exit(code);
-    logger.log(chalk.green('✓ Tests completed'));
+    logger.log(formatSuccessLine('Tests completed.'));
     return;
   }
-  logger.log(chalk.blue(`Running tests in ephemeral container (${fullImage}): ${testCmd}\n`));
+  logger.log(infoLine(`ℹ Running tests in ephemeral container (${fullImage}): ${testCmd}\n`));
   const envFilePath = await secretsEnvWrite.resolveAndWriteEnvFile(appName, {});
   const code = await runDockerRunEphemeral(fullImage, testCmd, envFilePath);
   if (code !== 0) process.exit(code);
-  logger.log(chalk.green('✓ Tests completed'));
+  logger.log(formatSuccessLine('Tests completed.'));
 }
 
 /**
@@ -141,14 +141,17 @@ async function runAppTest(appName, options = {}) {
  * @param {string|null} [envFilePath] - Path to resolved .env for --env-file (optional)
  * @returns {Promise<number>} Exit code
  */
-function runDockerExec(containerName, testCmd, envFilePath = null) {
+async function runDockerExec(containerName, testCmd, envFilePath = null) {
+  const { getDockerExecEnv } = require('../utils/remote-docker-env');
+  const dockerEnv = await getDockerExecEnv();
   return new Promise((resolve) => {
     const args = ['exec'];
     if (envFilePath) args.push('--env-file', envFilePath);
     args.push(containerName, 'sh', '-c', testCmd);
     const proc = spawn('docker', args, {
       stdio: 'inherit',
-      shell: false
+      shell: false,
+      env: dockerEnv
     });
     proc.on('close', code => resolve(code !== null ? code : 1));
     proc.on('error', () => resolve(1));
@@ -162,14 +165,17 @@ function runDockerExec(containerName, testCmd, envFilePath = null) {
  * @param {string|null} [envFilePath] - Path to .env for docker run --env-file (optional)
  * @returns {Promise<number>} Exit code
  */
-function runDockerRunEphemeral(fullImage, testCmd, envFilePath = null) {
+async function runDockerRunEphemeral(fullImage, testCmd, envFilePath = null) {
+  const { getDockerExecEnv } = require('../utils/remote-docker-env');
+  const dockerEnv = await getDockerExecEnv();
   return new Promise((resolve) => {
     const args = ['run', '--rm'];
     if (envFilePath) args.push('--env-file', envFilePath);
     args.push(fullImage, 'sh', '-c', testCmd);
     const proc = spawn('docker', args, {
       stdio: 'inherit',
-      shell: false
+      shell: false,
+      env: dockerEnv
     });
     proc.on('close', code => resolve(code !== null ? code : 1));
     proc.on('error', () => resolve(1));
@@ -197,14 +203,14 @@ async function runAppTestE2e(appName, options = {}) {
   if (env === 'dev') {
     const code = await runTestsInDev(appName, developerId, cmd);
     if (code !== 0) process.exit(code);
-    logger.log(chalk.green('✓ Test-e2e completed'));
+    logger.log(formatSuccessLine('Test-e2e completed.'));
     return;
   }
-  logger.log(chalk.blue(`Running test-e2e in ephemeral container (${fullImage}): ${cmd}\n`));
+  logger.log(infoLine(`ℹ Running test-e2e in ephemeral container (${fullImage}): ${cmd}\n`));
   const envFilePath = await secretsEnvWrite.resolveAndWriteEnvFile(appName, {});
   const code = await runDockerRunEphemeral(fullImage, cmd, envFilePath);
   if (code !== 0) process.exit(code);
-  logger.log(chalk.green('✓ Test-e2e completed'));
+  logger.log(formatSuccessLine('Test-e2e completed.'));
 }
 
 /**
@@ -229,14 +235,14 @@ async function runAppTestIntegration(appName, options = {}) {
   if (env === 'dev') {
     const code = await runTestsInDev(appName, developerId, cmd);
     if (code !== 0) process.exit(code);
-    logger.log(chalk.green('✓ Test-integration completed'));
+    logger.log(formatSuccessLine('Test-integration completed.'));
     return;
   }
-  logger.log(chalk.blue(`Running test-integration in ephemeral container (${fullImage}): ${cmd}\n`));
+  logger.log(infoLine(`ℹ Running test-integration in ephemeral container (${fullImage}): ${cmd}\n`));
   const envFilePath = await secretsEnvWrite.resolveAndWriteEnvFile(appName, {});
   const code = await runDockerRunEphemeral(fullImage, cmd, envFilePath);
   if (code !== 0) process.exit(code);
-  logger.log(chalk.green('✓ Test-integration completed'));
+  logger.log(formatSuccessLine('Test-integration completed.'));
 }
 
 /**
@@ -260,14 +266,14 @@ async function runAppLint(appName, options = {}) {
   if (env === 'dev') {
     const code = await runTestsInDev(appName, developerId, cmd);
     if (code !== 0) process.exit(code);
-    logger.log(chalk.green('✓ Lint completed'));
+    logger.log(formatSuccessLine('Lint completed.'));
     return;
   }
-  logger.log(chalk.blue(`Running lint in ephemeral container (${fullImage}): ${cmd}\n`));
+  logger.log(infoLine(`ℹ Running lint in ephemeral container (${fullImage}): ${cmd}\n`));
   const envFilePath = await secretsEnvWrite.resolveAndWriteEnvFile(appName, {});
   const code = await runDockerRunEphemeral(fullImage, cmd, envFilePath);
   if (code !== 0) process.exit(code);
-  logger.log(chalk.green('✓ Lint completed'));
+  logger.log(formatSuccessLine('Lint completed.'));
 }
 
 module.exports = {

package/lib/commands/app.js

@@ -1,3 +1,4 @@
+const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
 /**
  * AI Fabrix Builder - Application Registration Commands
  *
@@ -17,9 +18,20 @@ const { rotateSecret } = require('../app/rotate-secret');
 const { showApp } = require('../app/show');
 const { runAppDeploymentList } = require('./deployment-list');
 
+const APP_HELP_AFTER = `
+Subcommands:
+  register <appKey>     Register app; get pipeline client id/secret
+  list                  Applications in current environment
+  rotate-secret <key>   New ClientSecret (shown once)
+  show <key>            From controller (like show --online)
+  deployment <key>      Deployment history for app
+
+Requires: aifabrix login
+`;
+
 function setupAppRegisterCommand(app) {
   app.command('register <appKey>')
-    .description('Register application and get pipeline credentials')
+    .description('Register app; receive pipeline credentials')
     .option('-p, --port <port>', 'Application port (default: from application.yaml)')
     .option('-u, --url <url>', 'Application URL. If omitted: app.url, deployment.dataplaneUrl or deployment.appUrl in application.yaml; else http://localhost:{port})')
     .option('-n, --name <name>', 'Override display name')
@@ -28,7 +40,7 @@ function setupAppRegisterCommand(app) {
       try {
         await registerApplication(appKey, options);
       } catch (error) {
-        logger.error(chalk.red('❌ Registration failed:'), error.message);
+        logger.error(formatBlockingError('Registration failed:'), error.message);
         process.exit(1);
       }
     });
@@ -36,12 +48,12 @@ function setupAppRegisterCommand(app) {
 
 function setupAppListCommand(app) {
   app.command('list')
-    .description('List applications')
+    .description('List apps in current environment')
     .action(async(options) => {
       try {
         await listApplications(options);
       } catch (error) {
-        logger.error(chalk.red('❌ Failed to list applications:'), error.message);
+        logger.error(formatBlockingError('Failed to list applications:'), error.message);
         process.exit(1);
       }
     });
@@ -49,20 +61,20 @@ function setupAppListCommand(app) {
 
 function setupAppRotateSecretCommand(app) {
   app.command('rotate-secret <appKey>')
-    .description('Rotate pipeline ClientSecret for an application')
+    .description('Rotate pipeline ClientSecret (one-time display)')
     .action(async(appKey, options) => {
       try {
         await rotateSecret(appKey, options);
       } catch (error) {
-        logger.error(chalk.red('❌ Rotation failed:'), error.message);
+        logger.error(formatBlockingError('Rotation failed:'), error.message);
         process.exit(1);
       }
     });
 }
 
 function setupAppShowCommand(app) {
-  app.command('show <appKey>')
-    .description('Show application from controller (online). Same as aifabrix show <appKey> --online')
+  app.command('show <app>')
+    .description('App details from controller (same as show --online)')
     .option('--online', 'Fetch from controller (default for this command)')
     .option('--json', 'Output as JSON')
     .option('--permissions', 'Show only list of permissions')
@@ -78,7 +90,7 @@ function setupAppShowCommand(app) {
 
 function setupAppDeploymentCommand(app) {
   app.command('deployment <appKey>')
-    .description('List last N deployments for an application in current environment (default pageSize=50)')
+    .description('List recent deployments for app in current environment')
     .option('--controller <url>', 'Controller URL (default: from config)')
     .option('--environment <env>', 'Environment key (default: from config)')
     .option('--page-size <n>', 'Items per page', '50')
@@ -102,7 +114,7 @@ function setupAppDeploymentCommand(app) {
  * @param {Command} program - Commander program instance
  */
 function setupAppCommands(program) {
-  const app = program.command('app').description('Manage applications');
+  const app = program.command('app').description('Controller apps: register, list, secrets, deploy history').addHelpText('after', APP_HELP_AFTER);
   setupAppRegisterCommand(app);
   setupAppListCommand(app);
   setupAppRotateSecretCommand(app);