@aifabrix/builder 2.37.9 → 2.38.0

package/README.md

@@ -9,6 +9,25 @@ Install the AI Fabrix platform and test it locally. Then add external integratio
 
 ---
 
+## Why AI Fabrix Builder?
+
+- **Build perspective:** Everything is driven by declarative config and JSON schemas—no hidden logic, AI assistant–friendly.
+- **Industry standards and security:** Follow industry standards and high security (e.g. ISO 27k); no secrets in version control.
+- **Full lifecycle in your version control:** Configuration, apps, and integrations live in your own VCS (GitHub, GitLab, Azure DevOps).
+- **One tool from day one:** Single CLI for local infra, app and integration creation, build, run, and deploy—same workflow for apps and integrations.
+- **Consistency and production readiness:** Schema-driven; deploy apps and integrations to the same controller/dataplane; production-ready secrets with `kv://` and Azure Key Vault.
+- **Application development:** Use **[miso-client](https://github.com/esystemsdev/aifabrix-miso-client)** for TypeScript and Python to talk to the dataplane and controller (see [templates/applications/dataplane/README.md](templates/applications/dataplane/README.md) and the repo for usage).
+
+---
+
+## Prerequisites
+
+- **Node.js 18+** – Recommended for running the CLI.
+- **AI Fabrix Azure / platform:** Install from **Azure Marketplace** or run via **Docker** (e.g. `aifabrix up-platform`). You need **full access to Docker** (docker commands) where applicable.
+- **Secrets before platform:** Add secrets (e.g. OpenAI or Azure OpenAI) **before** running `aifabrix up-platform`; the platform reads them from the place you configure. See [Infrastructure](docs/infrastructure.md) and secrets configuration.
+
+---
+
 ## Install
 
 ```bash

package/integration/hubspot/hubspot-deploy.json

@@ -839,6 +839,5 @@
   ],
   "requiresDatabase": false,
   "requiresRedis": false,
-  "requiresStorage": false,
-  "deploymentKey": "9b5209bed2ef1eccb04fa83be73a74cf3a9c84d5d2580a95028d34fdb8db78a8"
+  "requiresStorage": false
 }

package/lib/api/applications.api.js

@@ -153,6 +153,27 @@ async function rotateApplicationSecret(controllerUrl, envKey, appKey, authConfig
   return await client.post(`/api/v1/environments/${envKey}/applications/${appKey}/rotate-secret`);
 }
 
+/**
+ * Get application status (metadata only, no configuration)
+ * GET /api/v1/environments/{envKey}/applications/{appKey}/status
+ * Auth: bearer token or pipeline client credentials for that application.
+ *
+ * @async
+ * @function getApplicationStatus
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} envKey - Environment key
+ * @param {string} appKey - Application key
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Promise<Object>} Response with data: { id, key, displayName, url, internalUrl, port, status, runtimeStatus, environmentId, createdAt, updatedAt, image, description }
+ * @throws {Error} If request fails
+ */
+async function getApplicationStatus(controllerUrl, envKey, appKey, authConfig) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(
+    `/api/v1/environments/${envKey}/applications/${appKey}/status`
+  );
+}
+
 module.exports = {
   listApplications,
   createApplication,
@@ -160,6 +181,7 @@ module.exports = {
   updateApplication,
   deleteApplication,
   registerApplication,
-  rotateApplicationSecret
+  rotateApplicationSecret,
+  getApplicationStatus
 };
 

package/lib/api/credentials.api.js

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Credentials API functions (controller/dataplane credential list)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { ApiClient } = require('./index');
+
+/**
+ * List credentials from controller or dataplane
+ * GET /api/v1/credential
+ * Used by `aifabrix credential list`. Call with controller or dataplane base URL per deployment.
+ *
+ * @async
+ * @function listCredentials
+ * @param {string} baseUrl - Controller or dataplane base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} [options] - List options
+ * @param {boolean} [options.activeOnly] - If true, return only active credentials
+ * @param {number} [options.page] - Page number
+ * @param {number} [options.pageSize] - Items per page
+ * @returns {Promise<Object>} Response with credentials (e.g. data.credentials or data.items)
+ * @throws {Error} If request fails
+ */
+async function listCredentials(baseUrl, authConfig, options = {}) {
+  const client = new ApiClient(baseUrl, authConfig);
+  return await client.get('/api/v1/credential', {
+    params: options
+  });
+}
+
+module.exports = {
+  listCredentials
+};

package/lib/api/deployments.api.js

@@ -116,10 +116,37 @@ async function getDeploymentLogs(controllerUrl, envKey, deploymentId, authConfig
   });
 }
 
+/**
+ * List deployments for a single application in an environment
+ * GET /api/v1/environments/{envKey}/applications/{appKey}/deployments
+ *
+ * @async
+ * @function listApplicationDeployments
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} envKey - Environment key
+ * @param {string} appKey - Application key
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} [options] - List options
+ * @param {number} [options.page] - Page number
+ * @param {number} [options.pageSize] - Items per page (default 50)
+ * @param {string} [options.sort] - Sort parameter
+ * @param {string} [options.filter] - Filter parameter
+ * @returns {Promise<Object>} Paginated list of deployments for the application
+ * @throws {Error} If request fails
+ */
+async function listApplicationDeployments(controllerUrl, envKey, appKey, authConfig, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(
+    `/api/v1/environments/${envKey}/applications/${appKey}/deployments`,
+    { params: options }
+  );
+}
+
 module.exports = {
   deployApplication,
   deployEnvironment,
   listDeployments,
+  listApplicationDeployments,
   getDeployment,
   getDeploymentLogs
 };

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/wizard.api.js

@@ -370,6 +370,25 @@ async function getWizardPlatforms(dataplaneUrl, authConfig) {
   }
 }
 
+/**
+ * List credentials for wizard selection (Step 3)
+ * GET /api/v1/wizard/credentials
+ * @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 +407,6 @@ module.exports = {
   testMcpConnection,
   getDeploymentDocs,
   postDeploymentDocs,
-  getWizardPlatforms
+  getWizardPlatforms,
+  listWizardCredentials
 };

package/lib/app/run-helpers.js

@@ -27,6 +27,7 @@ const composeGenerator = require('../utils/compose-generator');
 const dockerUtils = require('../utils/docker');
 const containerHelpers = require('../utils/app-run-containers');
 const pathsUtil = require('../utils/paths');
+const { resolveVersionForApp } = require('../utils/image-version');
 
 const execAsync = promisify(exec);
 
@@ -138,6 +139,23 @@ async function validateAppConfiguration(appName) {
   return appConfig;
 }
 
+/**
+ * Resolves version from image and updates builder/variables.yaml when running
+ * @async
+ * @param {string} appName - Application name
+ * @param {Object} appConfig - Application configuration
+ * @param {boolean} debug - Enable debug logging
+ */
+async function resolveAndUpdateVersion(appName, appConfig, debug) {
+  const resolved = await resolveVersionForApp(appName, appConfig, {
+    updateBuilder: true,
+    builderPath: pathsUtil.getBuilderPath(appName)
+  });
+  if (resolved.fromImage && resolved.updated && debug) {
+    logger.log(chalk.gray(`[DEBUG] Updated app.version to ${resolved.version} from image`));
+  }
+}
+
 /**
  * Checks prerequisites: Docker image and (optionally) infrastructure
  * @async
@@ -163,10 +181,20 @@ async function checkPrerequisites(appName, appConfig, debug = false, skipInfraCh
   }
   logger.log(chalk.green(`✓ Image ${fullImageName} found`));
 
-  if (skipInfraCheck) {
-    return;
+  await resolveAndUpdateVersion(appName, appConfig, debug);
+
+  if (!skipInfraCheck) {
+    await checkInfraHealthOrThrow(debug);
   }
+}
 
+/**
+ * Checks infrastructure health and throws if unhealthy
+ * @async
+ * @param {boolean} debug - Enable debug logging
+ * @throws {Error} If infrastructure is not healthy
+ */
+async function checkInfraHealthOrThrow(debug) {
   logger.log(chalk.blue('Checking infrastructure health...'));
   const infraHealth = await infra.checkInfraHealth();
   if (debug) {

package/lib/cli/index.js

@@ -20,6 +20,7 @@ const { setupSecretsCommands } = require('./setup-secrets');
 const { setupExternalSystemCommands } = require('./setup-external-system');
 const { setupAppCommands: setupAppManagementCommands } = require('../commands/app');
 const { setupDatasourceCommands } = require('../commands/datasource');
+const { setupCredentialDeploymentCommands } = require('./setup-credential-deployment');
 
 /**
  * Sets up all CLI commands on the Commander program instance
@@ -33,6 +34,7 @@ function setupCommands(program) {
   setupAppManagementCommands(program);
   setupDatasourceCommands(program);
   setupUtilityCommands(program);
+  setupCredentialDeploymentCommands(program);
   setupExternalSystemCommands(program);
   setupDevCommands(program);
   setupSecretsCommands(program);

package/lib/cli/setup-app.js

@@ -173,6 +173,7 @@ See integration/hubspot/wizard-hubspot-e2e.yaml for an example.`)
     .description('Run application locally')
     .option('-p, --port <port>', 'Override local port')
     .option('-d, --debug', 'Enable debug output with detailed container information')
+    .option('-t, --tag <tag>', 'Image tag to run (e.g. v1.0.0); overrides variables.yaml image.tag')
     .action(async(appName, options) => {
       try {
         await app.runApp(appName, options);
@@ -182,6 +183,37 @@ See integration/hubspot/wizard-hubspot-e2e.yaml for an example.`)
       }
     });
 
+  program.command('logs <app>')
+    .description('Show application container logs (and optional env summary with secrets masked)')
+    .option('-f', 'Follow log stream')
+    .option('-t, --tail <lines>', 'Number of lines (default: 100); 0 = full list', '100')
+    .action(async(appName, options) => {
+      try {
+        const { runAppLogs } = require('../commands/app-logs');
+        const tailNum = parseInt(options.tail, 10);
+        await runAppLogs(appName, {
+          follow: options.f,
+          tail: Number.isNaN(tailNum) ? 100 : tailNum
+        });
+      } catch (error) {
+        handleCommandError(error, 'logs');
+        process.exit(1);
+      }
+    });
+
+  program.command('down-app <app>')
+    .description('Stop and remove application container; optionally remove volume and image')
+    .option('--volumes', 'Remove application Docker volume')
+    .action(async(appName, options) => {
+      try {
+        const { runDownAppWithImageRemoval } = require('../commands/app-down');
+        await runDownAppWithImageRemoval(appName, { volumes: options.volumes });
+      } catch (error) {
+        handleCommandError(error, 'down-app');
+        process.exit(1);
+      }
+    });
+
   program.command('push <app>')
     .description('Push image to Azure Container Registry')
     .option('-r, --registry <registry>', 'ACR registry URL (overrides variables.yaml)')

package/lib/cli/setup-credential-deployment.js

@@ -0,0 +1,72 @@
+/**
+ * CLI credential and deployment list command setup.
+ * Commands: credential list, deployment list.
+ *
+ * @fileoverview Credential and deployment list CLI definitions
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const { runCredentialList } = require('../commands/credential-list');
+const { runDeploymentList } = require('../commands/deployment-list');
+
+/**
+ * Sets up credential and deployment list commands
+ * @param {Command} program - Commander program instance
+ */
+function setupCredentialDeploymentCommands(program) {
+  const credential = program
+    .command('credential')
+    .description('Manage credentials');
+
+  credential
+    .command('list')
+    .description('List credentials from controller/dataplane (GET /api/v1/credential)')
+    .option('--controller <url>', 'Controller URL (default: from config)')
+    .option('--active-only', 'List only active credentials')
+    .option('--page-size <n>', 'Items per page', '50')
+    .action(async(options) => {
+      try {
+        const opts = {
+          controller: options.controller,
+          activeOnly: options.activeOnly,
+          pageSize: parseInt(options.pageSize, 10) || 50
+        };
+        await runCredentialList(opts);
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        handleCommandError(error, 'credential list');
+        process.exit(1);
+      }
+    });
+
+  const deployment = program
+    .command('deployment')
+    .description('List deployments');
+
+  deployment
+    .command('list')
+    .description('List last N deployments for current environment (default pageSize=50)')
+    .option('--controller <url>', 'Controller URL (default: from config)')
+    .option('--environment <env>', 'Environment key (default: from config)')
+    .option('--page-size <n>', 'Items per page', '50')
+    .action(async(options) => {
+      try {
+        const opts = {
+          controller: options.controller,
+          environment: options.environment,
+          pageSize: parseInt(options.pageSize, 10) || 50
+        };
+        await runDeploymentList(opts);
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        handleCommandError(error, 'deployment list');
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = { setupCredentialDeploymentCommands };

package/lib/cli/setup-utility.js

@@ -1,5 +1,5 @@
 /**
- * CLI utility command setup (resolve, json, split-json, genkey, show, validate, diff).
+ * CLI utility command setup (resolve, json, split-json, show, validate, diff).
  *
  * @fileoverview Utility command definitions for AI Fabrix Builder CLI
  * @author AI Fabrix Team
@@ -127,30 +127,6 @@ function setupUtilityCommands(program) {
       }
     });
 
-  program.command('genkey <app>')
-    .description('Generate deployment key')
-    .action(async(appName) => {
-      try {
-        const jsonPath = await generator.generateDeployJson(appName);
-
-        const jsonContent = fs.readFileSync(jsonPath, 'utf8');
-        const deployment = JSON.parse(jsonContent);
-
-        const key = deployment.deploymentKey;
-
-        if (!key) {
-          throw new Error('deploymentKey not found in generated JSON');
-        }
-
-        logger.log(`\nDeployment key for ${appName}:`);
-        logger.log(key);
-        logger.log(chalk.gray(`\nGenerated from: ${jsonPath}`));
-      } catch (error) {
-        handleCommandError(error, 'genkey');
-        process.exit(1);
-      }
-    });
-
   program.command('show <appKey>')
     .description('Show application info from local builder/ or integration/ (offline) or from controller (--online)')
     .option('--online', 'Fetch application data from the controller')

package/lib/commands/app-down.js

@@ -0,0 +1,80 @@
+/**
+ * Down-app command – stop container, optionally volumes, then remove image if unused
+ *
+ * @fileoverview Down-app command implementation
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+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);
+
+/**
+ * Get image ID of a running container (sha or name:tag)
+ * @async
+ * @param {string} containerName - Docker container name
+ * @returns {Promise<string|null>} Image ID or null if container not found / not running
+ */
+async function getContainerImageId(containerName) {
+  try {
+    const { stdout } = await execAsync(
+      `docker inspect --format='{{.Image}}' ${containerName}`,
+      { encoding: 'utf8' }
+    );
+    const id = (stdout && stdout.trim()) || null;
+    return id || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Remove Docker image by ID; ignore "in use" or "no such image"
+ * @async
+ * @param {string} imageId - Image ID (sha or name:tag)
+ */
+async function removeImageIfUnused(imageId) {
+  if (!imageId) return;
+  try {
+    await execAsync(`docker rmi ${imageId}`);
+    logger.log(chalk.green(`✓ Image ${imageId} removed`));
+  } catch (err) {
+    const msg = (err && err.message) || '';
+    if (msg.includes('in use') || msg.includes('is being used')) {
+      logger.log(chalk.gray(`Image ${imageId} still in use by another container; not removed`));
+    } else if (msg.includes('No such image')) {
+      logger.log(chalk.gray(`Image ${imageId} not found (already removed)`));
+    } else {
+      logger.log(chalk.yellow(`Could not remove image: ${msg}`));
+    }
+  }
+}
+
+/**
+ * Run down-app: get image from container, stop/remove container (and optionally volume), then remove image if unused
+ * @async
+ * @param {string} appName - Application name
+ * @param {Object} options - { volumes: boolean }
+ * @returns {Promise<void>}
+ */
+async function runDownAppWithImageRemoval(appName, options = {}) {
+  const developerId = await config.getDeveloperId();
+  const containerName = containerHelpers.getContainerName(appName, developerId);
+  const imageId = await getContainerImageId(containerName);
+
+  await downApp(appName, options);
+  await removeImageIfUnused(imageId);
+}
+
+module.exports = {
+  runDownAppWithImageRemoval,
+  getContainerImageId,
+  removeImageIfUnused
+};

package/lib/commands/app-logs.js

@@ -0,0 +1,146 @@
+/**
+ * App logs command – show container env (masked) and docker logs for an app
+ *
+ * @fileoverview App logs command implementation
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const { exec, spawn } = 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 { validateAppName } = require('../app/push');
+
+const execAsync = promisify(exec);
+
+/** Default number of log lines */
+const DEFAULT_TAIL_LINES = 100;
+
+/** Env key patterns that indicate a secret (mask value) */
+const SECRET_KEY_PATTERN = /password|secret|token|credential|api[_-]?key/i;
+
+/** Prefixes to strip before checking key (avoids masking KEYCLOAK_SERVER_URL etc.) */
+const KEY_PREFIXES_TO_STRIP = /^KEYCLOAK_|^KEY_VAULT_/;
+
+/** URL with embedded credentials: scheme://user:password@host → scheme://user:***@host */
+const URL_CREDENTIAL_PATTERN = /(\w+:\/\/)([^:@]*):([^@]+)@/g;
+
+/**
+ * Masks a single env line if the key looks like a secret or value contains URL credentials
+ * @param {string} line - Line in form KEY=value
+ * @returns {string} Same line or KEY=*** or value with masked URL credentials
+ */
+function maskEnvLine(line) {
+  const eq = line.indexOf('=');
+  if (eq <= 0) return line;
+  const key = line.slice(0, eq);
+  const value = line.slice(eq + 1);
+
+  const keyForCheck = key.replace(KEY_PREFIXES_TO_STRIP, '');
+  const isSecretKey = SECRET_KEY_PATTERN.test(keyForCheck);
+
+  const maskedValue = value.replace(URL_CREDENTIAL_PATTERN, '$1$2:***@');
+  const hasUrlCredentials = maskedValue !== value;
+
+  if (isSecretKey) return `${key}=***`;
+  if (hasUrlCredentials) return `${key}=${maskedValue}`;
+  return line;
+}
+
+/**
+ * Dump container env (masked) and print to logger
+ * @async
+ * @param {string} containerName - Docker container name
+ * @returns {Promise<void>}
+ */
+async function dumpMaskedEnv(containerName) {
+  try {
+    const { stdout } = await execAsync(`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'));
+    lines.sort((a, b) => {
+      const keyA = a.indexOf('=') > 0 ? a.slice(0, a.indexOf('=')) : a;
+      const keyB = b.indexOf('=') > 0 ? b.slice(0, b.indexOf('=')) : b;
+      return keyA.localeCompare(keyB);
+    });
+    lines.forEach((line) => logger.log(maskEnvLine(line)));
+    logger.log(chalk.gray('\n--- Logs ---\n'));
+  } catch (err) {
+    logger.log(chalk.gray('(Could not read container env; container may be stopped)\n'));
+  }
+}
+
+/**
+ * Run docker logs (non-follow): tail N lines or full (tail 0)
+ * @async
+ * @param {string} containerName - Docker container name
+ * @param {Object} options - { tail: number } (0 = full, no limit)
+ * @returns {Promise<void>}
+ */
+async function runDockerLogs(containerName, options) {
+  const args = options.tail === 0 ? ['logs', containerName] : ['logs', '--tail', String(options.tail), containerName];
+  return new Promise((resolve, reject) => {
+    const proc = spawn('docker', args, { stdio: 'inherit' });
+    proc.on('error', reject);
+    proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`docker logs exited with ${code}`))));
+  });
+}
+
+/**
+ * Run docker logs --follow (stream), optionally with tail
+ * @param {string} containerName - Docker container name
+ * @param {number} [tail] - Lines to show (0 = full, omit --tail)
+ */
+function runDockerLogsFollow(containerName, tail) {
+  const args = tail === 0 ? ['logs', '-f', containerName] : ['logs', '-f', '--tail', String(tail), containerName];
+  const proc = spawn('docker', args, { stdio: 'inherit' });
+  proc.on('error', (err) => {
+    logger.log(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  });
+  proc.on('close', (code) => {
+    if (code !== 0 && code !== null) process.exit(code);
+  });
+}
+
+/**
+ * Run app logs command: optional env dump (masked), then docker logs
+ * @async
+ * @param {string} appKey - Application key (app name)
+ * @param {Object} options - CLI options
+ * @param {boolean} [options.follow] - Follow log stream (-f)
+ * @param {number} [options.tail] - Number of lines (default 100; 0 = full list)
+ * @returns {Promise<void>}
+ */
+async function runAppLogs(appKey, options = {}) {
+  validateAppName(appKey);
+  const developerId = await config.getDeveloperId();
+  const containerName = containerHelpers.getContainerName(appKey, developerId);
+
+  const follow = !!options.follow;
+  const tail = typeof options.tail === 'number' ? options.tail : DEFAULT_TAIL_LINES;
+
+  logger.log(chalk.blue(`Container: ${containerName}\n`));
+
+  if (!follow) {
+    await dumpMaskedEnv(containerName);
+  }
+
+  if (follow) {
+    runDockerLogsFollow(containerName, tail);
+    return;
+  }
+
+  try {
+    await runDockerLogs(containerName, { tail });
+  } catch (err) {
+    logger.log(chalk.red(`Error: ${err.message}`));
+    throw new Error(`Failed to show logs: ${err.message}`);
+  }
+}
+
+module.exports = { runAppLogs, maskEnvLine };