@aifabrix/builder 2.40.2 → 2.41.0

package/lib/cli/setup-secrets.js

@@ -1,5 +1,5 @@
 /**
- * CLI secrets and security command setup (secrets set, secure).
+ * CLI secret and security command setup (secret set, secure).
  *
  * @fileoverview Secrets command definitions for AI Fabrix Builder CLI
  * @author AI Fabrix Team
@@ -8,18 +8,50 @@
 
 const { handleCommandError } = require('../utils/cli-utils');
 const { handleSecretsSet } = require('../commands/secrets-set');
+const { handleSecretsList } = require('../commands/secrets-list');
+const { handleSecretsRemove } = require('../commands/secrets-remove');
+const { handleSecretsValidate } = require('../commands/secrets-validate');
 const { handleSecure } = require('../commands/secure');
 
+function setupSecretValidateCommand(secretCmd) {
+  secretCmd
+    .command('validate [path]')
+    .description('Validate secrets file (YAML structure and optional naming convention)')
+    .option('--naming', 'Check key names against *KeyVault convention')
+    .action(async(pathArg, options) => {
+      try {
+        const result = await handleSecretsValidate(pathArg, options);
+        if (!result.valid) process.exit(1);
+      } catch (error) {
+        handleCommandError(error, 'secret validate');
+        process.exit(1);
+      }
+    });
+}
+
 /**
  * Sets up secrets and security commands
  * @param {Command} program - Commander program instance
  */
 function setupSecretsCommands(program) {
-  const secretsCmd = program
-    .command('secrets')
+  const secretCmd = program
+    .command('secret')
     .description('Manage secrets in secrets files');
 
-  secretsCmd
+  secretCmd
+    .command('list')
+    .description('List secret keys (user or shared; use --shared for shared)')
+    .option('--shared', 'List shared secrets (from config aifabrix-secrets or remote API)')
+    .action(async(options) => {
+      try {
+        await handleSecretsList(options);
+      } catch (error) {
+        handleCommandError(error, 'secret list');
+        process.exit(1);
+      }
+    });
+
+  secretCmd
     .command('set <key> <value>')
     .description('Set a secret value in secrets file')
     .option('--shared', 'Save to general secrets file (from config.yaml aifabrix-secrets) instead of user secrets')
@@ -27,11 +59,26 @@ function setupSecretsCommands(program) {
       try {
         await handleSecretsSet(key, value, options);
       } catch (error) {
-        handleCommandError(error, 'secrets set');
+        handleCommandError(error, 'secret set');
+        process.exit(1);
+      }
+    });
+
+  secretCmd
+    .command('remove <key>')
+    .description('Remove a secret by key')
+    .option('--shared', 'Remove from shared secrets (file or remote API)')
+    .action(async(key, options) => {
+      try {
+        await handleSecretsRemove(key, options);
+      } catch (error) {
+        handleCommandError(error, 'secret remove');
         process.exit(1);
       }
     });
 
+  setupSecretValidateCommand(secretCmd);
+
   program.command('secure')
     .description('Encrypt secrets in secrets.local.yaml files for ISO 27001 compliance')
     .option('--secrets-encryption <key>', 'Encryption key (32 bytes, hex or base64)')

package/lib/cli/setup-utility.js

@@ -13,7 +13,7 @@ const secrets = require('../core/secrets');
 const generator = require('../generator');
 const logger = require('../utils/logger');
 const { handleCommandError, logOfflinePathWhenType } = require('../utils/cli-utils');
-const { detectAppType, getDeployJsonPath } = require('../utils/paths');
+const { detectAppType, getDeployJsonPath, getResolveAppPath } = require('../utils/paths');
 
 /**
  * Resolve app path and type for split-json (integration first, then builder).
@@ -89,9 +89,18 @@ function setupResolveCommand(program) {
     .option('--skip-validation', 'Skip file validation after generating .env')
     .action(async(appName, options) => {
       try {
-        const envPath = await secrets.generateEnvFile(appName, undefined, 'docker', options.force);
+        const { appPath, envOnly } = await getResolveAppPath(appName);
+        const envPath = await secrets.generateEnvFile(
+          appName,
+          undefined,
+          'docker',
+          options.force,
+          { appPath, envOnly, skipOutputPath: false, preserveFromPath: null }
+        );
         logger.log(`✓ Generated .env file: ${envPath}`);
-        if (!options.skipValidation) {
+        if (envOnly) {
+          logger.log(chalk.gray('  (env-only mode: validation skipped; no application.yaml)'));
+        } else if (!options.skipValidation) {
           const validate = require('../validation/validate');
           const result = await validate.validateAppOrFile(appName);
           validate.displayValidationResults(result);

package/lib/commands/app-install.js

@@ -0,0 +1,172 @@
+/**
+ * Install command – run install (dependencies) inside app container (dev: running; tst: ephemeral with .env).
+ *
+ * @fileoverview App install command for builder apps (plan 73)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { spawn } = require('child_process');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const config = require('../core/config');
+const containerHelpers = require('../utils/app-run-containers');
+const composeGenerator = require('../utils/compose-generator');
+const pathsUtil = require('../utils/paths');
+const { loadConfigFile } = require('../utils/config-format');
+const secretsEnvWrite = require('../core/secrets-env-write');
+
+/**
+ * Load application config for builder app.
+ * @param {string} appName - Application name
+ * @returns {Object} Application config
+ */
+function loadAppConfig(appName) {
+  const builderPath = pathsUtil.getBuilderPath(appName);
+  const configPath = pathsUtil.resolveApplicationConfigPath(builderPath);
+  return loadConfigFile(configPath);
+}
+
+/** Env set so install/test/lint use a writable temp dir in the container (e.g. when /app is read-only). */
+const TMPDIR_VALUE = '/tmp';
+
+/** pnpm store in /tmp when /app is read-only (avoids EACCES on _tmp_ files in project root). */
+const PNPM_STORE_DIR = '/tmp/.pnpm-store';
+
+/**
+ * Ensure install command can run when /app is read-only: use TMPDIR and pnpm --store-dir.
+ * @param {string} cmd - Raw install command (e.g. "pnpm install")
+ * @returns {string} Command (possibly with --store-dir for pnpm)
+ */
+function installCommandForReadOnlyApp(cmd) {
+  const t = typeof cmd === 'string' ? cmd.trim() : '';
+  if (t === 'pnpm install' || t.startsWith('pnpm install ') ||
+      t === 'pnpm i' || t.startsWith('pnpm i ')) {
+    return t.includes('--store-dir') ? t : `${t} --store-dir ${PNPM_STORE_DIR}`;
+  }
+  return t;
+}
+
+/**
+ * Resolve install command from application config (language or build.scripts).
+ * @param {Object} appConfig - Application config
+ * @returns {string} Shell command to run install (e.g. "pnpm install" or "make install")
+ */
+function getInstallCommand(appConfig) {
+  const build = appConfig.build;
+  const scripts = (build && build.scripts) || appConfig.scripts;
+  if (scripts && typeof scripts.install === 'string' && scripts.install.trim()) {
+    return scripts.install.trim();
+  }
+  const lang = (build && build.language || appConfig.language || 'typescript').toLowerCase();
+  return lang === 'python' ? 'make install' : 'pnpm install';
+}
+
+/**
+ * Run install in dev (exec in running container).
+ * Resolves app .env (including NPM_TOKEN/PYPI_TOKEN from kv://) and passes it so install has registry tokens.
+ * @param {string} appName - Application name
+ * @param {string|number} developerId - Developer ID
+ * @param {string} installCmd - Install command
+ * @returns {Promise<number>} Exit code
+ */
+async function runInstallInDev(appName, developerId, installCmd) {
+  const containerName = containerHelpers.getContainerName(appName, developerId);
+  const isRunning = await containerHelpers.checkContainerRunning(appName, developerId);
+  if (!isRunning) {
+    throw new Error(
+      `Container ${containerName} is not running.\nRun 'aifabrix run ${appName}' first.`
+    );
+  }
+  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);
+}
+
+/**
+ * Run command in container via docker exec; stream output. Returns exit code.
+ * Uses -e TMPDIR, pnpm store, CI; when envFilePath is set passes --env-file so NPM_TOKEN/PYPI_TOKEN (from kv://) are available.
+ * @param {string} containerName - Container name
+ * @param {string} cmd - Shell command
+ * @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) {
+  return new Promise((resolve) => {
+    const args = [
+      'exec',
+      '-e', `TMPDIR=${TMPDIR_VALUE}`,
+      '-e', `npm_config_store_dir=${PNPM_STORE_DIR}`,
+      '-e', 'CI=true'
+    ];
+    if (envFilePath) {
+      args.push('--env-file', envFilePath);
+    }
+    args.push(containerName, 'sh', '-c', cmd);
+    const proc = spawn('docker', args, {
+      stdio: 'inherit',
+      shell: false
+    });
+    proc.on('close', code => resolve(code !== null ? code : 1));
+    proc.on('error', () => resolve(1));
+  });
+}
+
+/**
+ * Run command in ephemeral container with optional env file; stream output. Returns exit code.
+ * @param {string} fullImage - Image:tag
+ * @param {string} cmd - Shell command
+ * @param {string|null} [envFilePath] - Path to .env file for --env-file (optional)
+ * @returns {Promise<number>} Exit code
+ */
+function runDockerRunEphemeral(fullImage, cmd, envFilePath = null) {
+  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) {
+      args.push('--env-file', envFilePath);
+    }
+    args.push(fullImage, 'sh', '-c', cmd);
+    const proc = spawn('docker', args, {
+      stdio: 'inherit',
+      shell: false
+    });
+    proc.on('close', code => resolve(code !== null ? code : 1));
+    proc.on('error', () => resolve(1));
+  });
+}
+
+/**
+ * Run install for a builder app. DEV: exec in running container; TST: ephemeral with resolved .env.
+ * @param {string} appName - Application name
+ * @param {Object} [options] - { env: 'dev'|'tst' }
+ * @returns {Promise<void>}
+ */
+async function runAppInstall(appName, options = {}) {
+  const env = (options.env || 'dev').toLowerCase();
+  if (env !== 'dev' && env !== 'tst') {
+    throw new Error('--env must be dev or tst');
+  }
+  const appConfig = loadAppConfig(appName);
+  const installCmd = getInstallCommand(appConfig);
+  const developerId = await config.getDeveloperId();
+  const imageName = composeGenerator.getImageName(appConfig, appName);
+  const imageTag = (appConfig.image && appConfig.image.tag) ? appConfig.image.tag : 'latest';
+  const fullImage = `${imageName}:${imageTag}`;
+
+  if (env === 'dev') {
+    const code = await runInstallInDev(appName, developerId, installCmd);
+    if (code !== 0) process.exit(code);
+    logger.log(chalk.green('✓ Install completed'));
+    return;
+  }
+
+  logger.log(chalk.blue(`Running install in ephemeral container (${fullImage}): ${installCmd}\n`));
+  const envFilePath = await secretsEnvWrite.resolveAndWriteEnvFile(appName, {});
+  const cmd = installCommandForReadOnlyApp(installCmd);
+  const code = await runDockerRunEphemeral(fullImage, cmd, envFilePath);
+  if (code !== 0) process.exit(code);
+  logger.log(chalk.green('✓ Install completed'));
+}
+
+module.exports = { runAppInstall, getInstallCommand };

package/lib/commands/app-shell.js

@@ -0,0 +1,75 @@
+/**
+ * Shell command – open an interactive shell in the app container (docker exec -it).
+ *
+ * @fileoverview App shell command implementation
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { spawn } = require('child_process');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const config = require('../core/config');
+const containerHelpers = require('../utils/app-run-containers');
+const pathsUtil = require('../utils/paths');
+const secretsEnvWrite = require('../core/secrets-env-write');
+
+/**
+ * Load application config for builder app (used to ensure app exists).
+ * @param {string} appName - Application name
+ * @returns {Object} Application config
+ */
+function loadAppConfig(appName) {
+  const { loadConfigFile } = require('../utils/config-format');
+  const builderPath = pathsUtil.getBuilderPath(appName);
+  const configPath = pathsUtil.resolveApplicationConfigPath(builderPath);
+  return loadConfigFile(configPath);
+}
+
+/**
+ * Run interactive shell in the application container. Uses sh.
+ * Resolves app .env (including NPM_TOKEN/PYPI_TOKEN from kv://) and passes it via --env-file so the shell has registry tokens.
+ * @param {string} appName - Application name
+ * @param {Object} [options] - Options (e.g. --env for future remote)
+ * @returns {Promise<void>} Resolves when shell exits
+ */
+async function runAppShell(appName, _options = {}) {
+  loadAppConfig(appName);
+
+  const developerId = await config.getDeveloperId();
+  const containerName = containerHelpers.getContainerName(appName, developerId);
+  const isRunning = await containerHelpers.checkContainerRunning(appName, developerId);
+
+  if (!isRunning) {
+    throw new Error(
+      `Container ${containerName} is not running.\nRun 'aifabrix run ${appName}' first.`
+    );
+  }
+
+  logger.log(chalk.blue(`Opening shell in ${containerName} (exit with 'exit' or Ctrl+D)...\n`));
+
+  const envFilePath = await secretsEnvWrite.resolveAndWriteEnvFile(appName, {});
+  const proc = spawn('docker', [
+    'exec', '-it',
+    '--env-file', envFilePath,
+    '-e', 'TMPDIR=/tmp',
+    containerName,
+    'sh'
+  ], {
+    stdio: 'inherit',
+    shell: false
+  });
+
+  return new Promise((resolve, reject) => {
+    proc.on('close', code => {
+      if (code !== 0 && code !== null) {
+        reject(new Error(`Shell exited with code ${code}`));
+      } else {
+        resolve();
+      }
+    });
+    proc.on('error', err => reject(err));
+  });
+}
+
+module.exports = { runAppShell };

package/lib/commands/app-test.js

@@ -0,0 +1,282 @@
+/**
+ * Test command – run tests inside app container (dev: running container; tst: ephemeral).
+ *
+ * @fileoverview App test command for builder apps (plan 65: dev = in container, tst = ephemeral)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { spawn } = require('child_process');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const config = require('../core/config');
+const containerHelpers = require('../utils/app-run-containers');
+const composeGenerator = require('../utils/compose-generator');
+const pathsUtil = require('../utils/paths');
+const { loadConfigFile } = require('../utils/config-format');
+const secretsEnvWrite = require('../core/secrets-env-write');
+
+/**
+ * Load application config for builder app.
+ * @param {string} appName - Application name
+ * @returns {Object} Application config
+ */
+function loadAppConfig(appName) {
+  const builderPath = pathsUtil.getBuilderPath(appName);
+  const configPath = pathsUtil.resolveApplicationConfigPath(builderPath);
+  return loadConfigFile(configPath);
+}
+
+/**
+ * Resolve test command from application config (language or build.scripts).
+ * @param {Object} appConfig - Application config
+ * @returns {string} Shell command to run tests (e.g. "pnpm test" or "make test")
+ */
+function getTestCommand(appConfig) {
+  const scripts = appConfig.build?.scripts || appConfig.scripts;
+  if (scripts && typeof scripts.test === 'string' && scripts.test.trim()) {
+    return scripts.test.trim();
+  }
+  const lang = (appConfig.build?.language || appConfig.language || 'typescript').toLowerCase();
+  return lang === 'python' ? 'make test' : 'pnpm test';
+}
+
+/**
+ * Resolve test:e2e command from application config.
+ * @param {Object} appConfig - Application config
+ * @returns {string} Shell command (e.g. "pnpm test:e2e" or "make test:e2e")
+ */
+function getTestE2eCommand(appConfig) {
+  const scripts = appConfig.build?.scripts || appConfig.scripts;
+  const cmd = scripts?.['test:e2e'] || scripts?.testE2e;
+  if (typeof cmd === 'string' && cmd.trim()) return cmd.trim();
+  const lang = (appConfig.build?.language || appConfig.language || 'typescript').toLowerCase();
+  return lang === 'python' ? 'make test:e2e' : 'pnpm test:e2e';
+}
+
+/**
+ * Resolve test:integration command from application config (aifabrix test-integration <app>).
+ * Defaults to test:e2e when not set so builder apps can run integration-style tests.
+ * @param {Object} appConfig - Application config
+ * @returns {string} Shell command (e.g. "pnpm test:integration" or "make test-integration")
+ */
+function getTestIntegrationCommand(appConfig) {
+  const scripts = appConfig.build?.scripts || appConfig.scripts;
+  const cmd = scripts?.['test:integration'] || scripts?.testIntegration;
+  if (typeof cmd === 'string' && cmd.trim()) return cmd.trim();
+  return getTestE2eCommand(appConfig);
+}
+
+/**
+ * Resolve lint command from application config.
+ * @param {Object} appConfig - Application config
+ * @returns {string} Shell command (e.g. "pnpm lint" or "make lint")
+ */
+function getLintCommand(appConfig) {
+  const scripts = appConfig.build?.scripts || appConfig.scripts;
+  if (scripts && typeof scripts.lint === 'string' && scripts.lint.trim()) {
+    return scripts.lint.trim();
+  }
+  const lang = (appConfig.build?.language || appConfig.language || 'typescript').toLowerCase();
+  return lang === 'python' ? 'make lint' : 'pnpm lint';
+}
+
+/**
+ * Run tests in dev (exec in running container).
+ * Resolves app .env (including NPM_TOKEN/PYPI_TOKEN) and passes it so tests have registry tokens.
+ * @param {string} appName - Application name
+ * @param {string|number} developerId - Developer ID
+ * @param {string} testCmd - Test command
+ * @returns {Promise<number>} Exit code
+ */
+async function runTestsInDev(appName, developerId, testCmd) {
+  const containerName = containerHelpers.getContainerName(appName, developerId);
+  const isRunning = await containerHelpers.checkContainerRunning(appName, developerId);
+  if (!isRunning) {
+    throw new Error(
+      `Container ${containerName} is not running.\nRun 'aifabrix run ${appName}' first.`
+    );
+  }
+  logger.log(chalk.blue(`Running tests in container ${containerName}: ${testCmd}\n`));
+  const envFilePath = await secretsEnvWrite.resolveAndWriteEnvFile(appName, {});
+  return runDockerExec(containerName, testCmd, envFilePath);
+}
+
+/**
+ * Run tests for a builder app. DEV: exec in running container; TST: ephemeral container.
+ * @param {string} appName - Application name
+ * @param {Object} [options] - { env: 'dev'|'tst' }
+ * @returns {Promise<void>}
+ */
+async function runAppTest(appName, options = {}) {
+  const env = (options.env || 'dev').toLowerCase();
+  if (env !== 'dev' && env !== 'tst') {
+    throw new Error('--env must be dev or tst');
+  }
+  const appConfig = loadAppConfig(appName);
+  const testCmd = getTestCommand(appConfig);
+  const developerId = await config.getDeveloperId();
+  const imageName = composeGenerator.getImageName(appConfig, appName);
+  const imageTag = appConfig.image?.tag || 'latest';
+  const fullImage = `${imageName}:${imageTag}`;
+
+  if (env === 'dev') {
+    const code = await runTestsInDev(appName, developerId, testCmd);
+    if (code !== 0) process.exit(code);
+    logger.log(chalk.green('✓ Tests completed'));
+    return;
+  }
+  logger.log(chalk.blue(`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'));
+}
+
+/**
+ * Run command in container via docker exec; stream output. Returns exit code.
+ * When envFilePath is set, passes --env-file so NPM_TOKEN/PYPI_TOKEN (from kv://) are available.
+ * @param {string} containerName - Container name
+ * @param {string} testCmd - Shell command
+ * @param {string|null} [envFilePath] - Path to resolved .env for --env-file (optional)
+ * @returns {Promise<number>} Exit code
+ */
+function runDockerExec(containerName, testCmd, envFilePath = null) {
+  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
+    });
+    proc.on('close', code => resolve(code !== null ? code : 1));
+    proc.on('error', () => resolve(1));
+  });
+}
+
+/**
+ * Run command in ephemeral container; optional --env-file. Returns exit code.
+ * @param {string} fullImage - Image:tag
+ * @param {string} testCmd - Shell command
+ * @param {string|null} [envFilePath] - Path to .env for docker run --env-file (optional)
+ * @returns {Promise<number>} Exit code
+ */
+function runDockerRunEphemeral(fullImage, testCmd, envFilePath = null) {
+  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
+    });
+    proc.on('close', code => resolve(code !== null ? code : 1));
+    proc.on('error', () => resolve(1));
+  });
+}
+
+/**
+ * Run test-e2e for a builder app. DEV: exec in running container; TST: ephemeral with .env.
+ * @param {string} appName - Application name
+ * @param {Object} [options] - { env: 'dev'|'tst' }
+ * @returns {Promise<void>}
+ */
+async function runAppTestE2e(appName, options = {}) {
+  const env = (options.env || 'dev').toLowerCase();
+  if (env !== 'dev' && env !== 'tst') {
+    throw new Error('--env must be dev or tst');
+  }
+  const appConfig = loadAppConfig(appName);
+  const cmd = getTestE2eCommand(appConfig);
+  const developerId = await config.getDeveloperId();
+  const imageName = composeGenerator.getImageName(appConfig, appName);
+  const imageTag = appConfig.image?.tag || 'latest';
+  const fullImage = `${imageName}:${imageTag}`;
+
+  if (env === 'dev') {
+    const code = await runTestsInDev(appName, developerId, cmd);
+    if (code !== 0) process.exit(code);
+    logger.log(chalk.green('✓ Test-e2e completed'));
+    return;
+  }
+  logger.log(chalk.blue(`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'));
+}
+
+/**
+ * Run test-integration for a builder app (integration tests in container). DEV: exec in running container; TST: ephemeral with .env.
+ * Uses build.scripts.testIntegration or test:integration; falls back to test:e2e when not set.
+ * @param {string} appName - Application name
+ * @param {Object} [options] - { env: 'dev'|'tst' }
+ * @returns {Promise<void>}
+ */
+async function runAppTestIntegration(appName, options = {}) {
+  const env = (options.env || 'dev').toLowerCase();
+  if (env !== 'dev' && env !== 'tst') {
+    throw new Error('--env must be dev or tst');
+  }
+  const appConfig = loadAppConfig(appName);
+  const cmd = getTestIntegrationCommand(appConfig);
+  const developerId = await config.getDeveloperId();
+  const imageName = composeGenerator.getImageName(appConfig, appName);
+  const imageTag = appConfig.image?.tag || 'latest';
+  const fullImage = `${imageName}:${imageTag}`;
+
+  if (env === 'dev') {
+    const code = await runTestsInDev(appName, developerId, cmd);
+    if (code !== 0) process.exit(code);
+    logger.log(chalk.green('✓ Test-integration completed'));
+    return;
+  }
+  logger.log(chalk.blue(`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'));
+}
+
+/**
+ * Run lint for a builder app. DEV: exec in running container; TST: ephemeral with .env.
+ * @param {string} appName - Application name
+ * @param {Object} [options] - { env: 'dev'|'tst' }
+ * @returns {Promise<void>}
+ */
+async function runAppLint(appName, options = {}) {
+  const env = (options.env || 'dev').toLowerCase();
+  if (env !== 'dev' && env !== 'tst') {
+    throw new Error('--env must be dev or tst');
+  }
+  const appConfig = loadAppConfig(appName);
+  const cmd = getLintCommand(appConfig);
+  const developerId = await config.getDeveloperId();
+  const imageName = composeGenerator.getImageName(appConfig, appName);
+  const imageTag = appConfig.image?.tag || 'latest';
+  const fullImage = `${imageName}:${imageTag}`;
+
+  if (env === 'dev') {
+    const code = await runTestsInDev(appName, developerId, cmd);
+    if (code !== 0) process.exit(code);
+    logger.log(chalk.green('✓ Lint completed'));
+    return;
+  }
+  logger.log(chalk.blue(`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'));
+}
+
+module.exports = {
+  runAppTest,
+  getTestCommand,
+  getTestE2eCommand,
+  getTestIntegrationCommand,
+  getLintCommand,
+  runAppTestE2e,
+  runAppTestIntegration,
+  runAppLint
+};

package/lib/commands/app.js

@@ -21,7 +21,7 @@ function setupAppRegisterCommand(app) {
   app.command('register <appKey>')
     .description('Register application and get 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:{build.localPort or port}')
+    .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')
     .option('-d, --description <desc>', 'Override description')
     .action(async(appKey, options) => {