@aifabrix/builder 2.42.1 → 2.44.0

package/lib/build/index.js

@@ -1,3 +1,4 @@
+const { formatSuccessLine, formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
 /**
  * AI Fabrix Builder Build Functions
  *
@@ -127,7 +128,9 @@ async function generateDockerfile(appNameOrPath, language, config, buildConfig =
 
   const template = dockerfileUtils.loadDockerfileTemplate(language);
   const isAppFlag = buildConfig.context === '../..';
-  const appSourcePath = isAppFlag ? `apps/${appName}/` : '.';
+  // Use "./" (not ".") so Dockerfile lines are "COPY ./requirements*.txt" — a bare "."
+  // concatenates with "requirements" and becomes ".requirements*.txt", which matches nothing.
+  const appSourcePath = isAppFlag ? `apps/${appName}/` : './';
 
   const templateVars = {
     port: config.port || 3000,
@@ -185,11 +188,11 @@ async function generateDockerfile(appNameOrPath, language, config, buildConfig =
 async function postBuildTasks(appName, buildConfig) {
   try {
     const envPath = await secrets.generateEnvFile(appName, buildConfig.secrets, 'docker');
-    logger.log(chalk.green(`✓ Generated .env file: ${envPath}`));
+    logger.log(formatSuccessLine(`Generated .env file: ${envPath}`));
     // Note: processEnvVariables is already called by generateEnvFile to generate local .env
     // at the envOutputPath, so we don't need to manually copy the docker .env file
   } catch (error) {
-    logger.log(chalk.yellow(`⚠️  Warning: Could not generate .env file: ${error.message}`));
+    logger.log(chalk.yellow(`⚠  Warning: Could not generate .env file: ${error.message}`));
   }
 }
 
@@ -229,7 +232,7 @@ async function copyApplicationSourceFiles(appName, devDir) {
   const appsPath = path.join(process.cwd(), 'apps', appName);
   if (fsSync.existsSync(appsPath)) {
     await buildCopy.copyAppSourceFiles(appsPath, devDir);
-    logger.log(chalk.green(`✓ Copied application source files from apps/${appName}`));
+    logger.log(formatSuccessLine(`Copied application source files from apps/${appName}`));
     return true;
   }
   return false;
@@ -253,12 +256,12 @@ async function copyTemplateFilesIfNeeded(devDir, language, buildConfig, options)
     const projectRoot = getProjectRoot();
     const templatePath = path.join(projectRoot, 'templates', 'typescript');
     await buildCopy.copyTemplateFilesToDevDir(templatePath, devDir, detectedLanguage);
-    logger.log(chalk.green(`✓ Generated application files from ${detectedLanguage} template`));
+    logger.log(formatSuccessLine(`Generated application files from ${detectedLanguage} template`));
   } else if (detectedLanguage === 'python' && !fsSync.existsSync(requirementsPath)) {
     const projectRoot = getProjectRoot();
     const templatePath = path.join(projectRoot, 'templates', 'python');
     await buildCopy.copyTemplateFilesToDevDir(templatePath, devDir, detectedLanguage);
-    logger.log(chalk.green(`✓ Generated application files from ${detectedLanguage} template`));
+    logger.log(formatSuccessLine(`Generated application files from ${detectedLanguage} template`));
   }
 }
 
@@ -268,7 +271,7 @@ async function prepareDevDirectory(appName, buildConfig, options) {
   const directoryName = idNum === 0 ? 'applications' : `dev-${developerId}`;
   logger.log(chalk.blue(`Copying files to developer-specific directory (${directoryName})...`));
   const devDir = await buildCopy.copyBuilderToDevDirectory(appName, developerId);
-  logger.log(chalk.green(`✓ Files copied to: ${devDir}`));
+  logger.log(formatSuccessLine(`Files copied to: ${devDir}`));
 
   const { config: appConfig, imageName } = await buildHelpers.loadAndValidateConfig(appName);
   const effectiveImageName = buildDevImageName(imageName, developerId);
@@ -294,7 +297,7 @@ function prepareBuildContext(buildConfig, devDir) {
   // Check if context is using old format (../appName) - these are incompatible with dev directory structure
   if (buildConfig.context && buildConfig.context.startsWith('../') && buildConfig.context !== '../..') {
     // Old format detected - always use devDir instead
-    logger.log(chalk.yellow(`⚠️  Warning: Build context uses old format: ${buildConfig.context}`));
+    logger.log(chalk.yellow(`⚠  Warning: Build context uses old format: ${buildConfig.context}`));
     logger.log(chalk.yellow(`   Using dev directory instead: ${devDir}`));
     contextPath = devDir;
   } else if (buildConfig.context && buildConfig.context !== '../..') {
@@ -353,7 +356,7 @@ async function handleDockerfileGeneration(appName, params, options, buildHelpers
     language = 'typescript';
   }
   if (!hasExistingDockerfile) {
-    logger.log(chalk.green(`✓ Detected language: ${language}`));
+    logger.log(formatSuccessLine(`Detected language: ${language}`));
   }
 
   // Determine Dockerfile (needs context path to generate in correct location)
@@ -425,7 +428,7 @@ async function buildApp(appName, options = {}) {
     // 7. Post-build tasks
     await postBuildTasks(appName, buildConfig);
 
-    logger.log(chalk.green('\n✅ Build completed successfully!'));
+    logger.log(formatSuccessParagraph('Build completed successfully!'));
     return `${imageName}:${tag}`;
 
   } catch (error) {

package/lib/cli/index.js

@@ -17,6 +17,7 @@ const { setupEnvironmentCommands } = require('./setup-environment');
 const { setupUtilityCommands } = require('./setup-utility');
 const { setupDevCommands } = require('./setup-dev');
 const { setupSecretsCommands } = require('./setup-secrets');
+const { setupParametersCommands } = require('./setup-parameters');
 const { setupExternalSystemCommands } = require('./setup-external-system');
 const { setupAppCommands: setupAppManagementCommands } = require('../commands/app');
 const { setupDatasourceCommands } = require('../commands/datasource');
@@ -40,6 +41,7 @@ function setupCommands(program) {
   setupExternalSystemCommands(program);
   setupDevCommands(program);
   setupSecretsCommands(program);
+  setupParametersCommands(program);
 }
 
 module.exports = {

package/lib/cli/setup-app.help.js

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Help text blocks for app-level CLI commands.
+ */
+
+'use strict';
+
+const TEST_HELP_AFTER = `
+Examples:
+  # External system (integration/<systemKey>/) — local validation
+  $ aifabrix test hubspot
+  $ aifabrix test hubspot -v
+  $ aifabrix test hubspot -d
+
+  # Builder app (builder/<app>/) — runs in container
+  $ aifabrix test myapp -e dev
+  $ aifabrix test myapp -e tst
+
+Notes:
+  - To run unit test for one datasource, use:
+      aifabrix datasource test <datasourceKey>
+  - To run integration test, use:
+      aifabrix test-integration <app>
+  - Option --sync is not supported here (local validation only); use upload or dataplane test commands with --sync.
+`;
+
+const TEST_INTEGRATION_HELP_AFTER = `
+Examples:
+  # External system (integration/<systemKey>/) — integration health across datasources via dataplane
+  $ aifabrix test-integration hubspot
+  $ aifabrix test-integration hubspot -v
+  $ aifabrix test-integration hubspot -d
+
+  # Builder app (builder/<app>/) — runs in container
+  $ aifabrix test-integration myapp -e dev
+  $ aifabrix test-integration myapp -e tst
+
+Notes:
+  - To run integration test for one datasource, use:
+      aifabrix datasource test-integration <datasourceKey>
+  - To run E2E test, use:
+      aifabrix test-e2e <app>
+  - Optional --sync publishes local files to the dataplane first (external integration under integration/<systemKey>/ only).
+`;
+
+const TEST_E2E_HELP_AFTER = `
+Examples:
+  # External system (integration/<systemKey>/) — E2E across datasources via dataplane
+  $ aifabrix test-e2e hubspot
+  $ aifabrix test-e2e hubspot -v
+  $ aifabrix test-e2e hubspot -d
+
+  # Builder app (builder/<app>/) — runs in container
+  $ aifabrix test-e2e myapp -e dev
+  $ aifabrix test-e2e myapp -e tst
+
+Notes:
+  - To run E2E for one datasource, use:
+      aifabrix datasource test-e2e <datasourceKey>
+  - Optional --sync publishes local files to the dataplane first (external integration only).
+`;
+
+module.exports = {
+  TEST_HELP_AFTER,
+  TEST_INTEGRATION_HELP_AFTER,
+  TEST_E2E_HELP_AFTER
+};
+

package/lib/cli/setup-app.js

@@ -1,3 +1,4 @@
+const { formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
 /**
  * CLI application lifecycle command setup (create, wizard, build, run, push, deploy, dockerfile).
  *
@@ -11,6 +12,24 @@ const path = require('path');
 const app = require('../app');
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
+const { setupInstallTestE2eLintCommands } = require('./setup-app.test-commands');
+
+const CREATE_HELP_AFTER = `
+Examples:
+  $ aifabrix create myapi --type webapp -l typescript
+  $ aifabrix create mycrm --wizard
+`;
+
+const DEPLOY_HELP_AFTER = `
+Examples:
+  $ aifabrix deploy myapp
+  $ aifabrix deploy myext --local
+`;
+
+const PUSH_HELP_AFTER = `
+Example:
+  $ aifabrix push myapp -t v1.0.0
+`;
 
 /**
  * Normalize options for external system creation
@@ -102,7 +121,8 @@ async function handleCreateCommand(appName, options) {
 
 function setupCreateCommand(program) {
   program.command('create <app>')
-    .description('Create new application with configuration files')
+    .description('Scaffold builder or external app (flags or --wizard)')
+    .addHelpText('after', CREATE_HELP_AFTER)
     .option('-p, --port <port>', 'Application port', '3000')
     .option('-d, --database', 'Requires database')
     .option('-r, --redis', 'Requires Redis')
@@ -140,17 +160,17 @@ Examples:
   $ aifabrix wizard my-integration --silent  Run headless with integration/my-integration/wizard.yaml (no prompts)
   $ aifabrix wizard -a my-integration   Same as above (app name set)
   $ aifabrix wizard --config wizard.yaml  Run headless from a wizard config file
-  $ aifabrix wizard hubspot-test-v2 --debug  Enable debug output and save debug manifests on validation failure
+  $ aifabrix wizard hubspot-test --debug  Enable debug output and save debug manifests on validation failure
 
-Config path: When appName is provided, integration/<appName>/wizard.yaml is used for load/save and error.log.
+Config path: When appName is provided, integration/<systemKey>/wizard.yaml is used for load/save and error.log.
 To change settings after a run, edit that file and run "aifabrix wizard <app>" again.
 Headless config must include: appName, mode (create-system|add-datasource), source (type + filePath/url/platform).
-See integration/hubspot/wizard-hubspot-e2e.yaml for an example.`;
+See integration/hubspot-test/wizard-hubspot-e2e.yaml for an example.`;
   program.command('wizard [appName]')
-    .description('Create or extend external systems (OpenAPI, MCP, or known platforms like HubSpot) via guided steps or a config file')
+    .description('Guided external system setup (OpenAPI, MCP, HubSpot, …) or headless wizard.yaml')
     .option('-a, --app <app>', 'Application name (synonym for positional appName)')
     .option('--config <file>', 'Run headless using a wizard.yaml file (appName, mode, source, credential, preferences)')
-    .option('--silent', 'Run with saved integration/<app>/wizard.yaml only; no prompts (requires app name and existing wizard.yaml)')
+    .option('--silent', 'Run with saved integration/<systemKey>/wizard.yaml only; no prompts (requires app name and existing wizard.yaml)')
     .option('--debug', 'Enable debug output and save debug manifests on validation failure')
     .addHelpText('after', wizardHelp)
     .action(async(positionalAppName, options) => {
@@ -172,9 +192,10 @@ In dev: use --reload for sync and mount (requires remote server with Mutagen, or
 Examples:
   $ aifabrix run myapp
   $ aifabrix run myapp --env tst
+  $ aifabrix run myapp --tag v1.0.0
   $ aifabrix run myapp --reload`;
   program.command('run <app>')
-    .description('Run application locally (or remotely on your Docker host)')
+    .description('Run app locally or on remote Docker host')
     .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 application.yaml image.tag')
@@ -193,14 +214,15 @@ Examples:
 
 function setupBuildRunLogsDownCommands(program) {
   program.command('build <app>')
-    .description('Build container image (auto-detects runtime)')
+    .description('Build Docker image (auto-detect runtime)')
     .option('-l, --language <lang>', 'Override language detection')
     .option('-f, --force-template', 'Force rebuild from template')
+    .option('--no-cache', 'Full Docker rebuild (disable layer cache); use after Dockerfile or context fixes')
     .option('-t, --tag <tag>', 'Image tag (default: latest). Set image.tag in application.yaml to match for deploy.')
     .action(async(appName, options) => {
       try {
         const imageTag = await app.buildApp(appName, options);
-        logger.log(`✅ Built image: ${imageTag}`);
+        logger.log(`✔ Built image: ${imageTag}`);
       } catch (error) {
         handleCommandError(error, 'build');
         process.exit(1);
@@ -210,7 +232,7 @@ function setupBuildRunLogsDownCommands(program) {
   registerRunCommand(program);
 
   program.command('logs <app>')
-    .description('Show application container logs (and optional env summary with secrets masked)')
+    .description('Tail app container logs (optional env summary; secrets masked)')
     .option('-f', 'Follow log stream')
     .option('-t, --tail <lines>', 'Number of lines (default: 100); 0 = full list', '100')
     .option('-l, --level <level>', 'Show only logs at this level or above (debug|info|warn|error)')
@@ -227,7 +249,7 @@ function setupBuildRunLogsDownCommands(program) {
     });
 
   program.command('down-app <app>')
-    .description('Stop and remove application container; optionally remove volume and image')
+    .description('Stop and remove app container (--volumes removes data volume)')
     .option('--volumes', 'Remove application Docker volume')
     .action(async(appName, options) => {
       try {
@@ -242,7 +264,7 @@ function setupBuildRunLogsDownCommands(program) {
 
 function setupShellTestStopCommands(program) {
   program.command('stop <app>')
-    .description('Stop and remove application container (alias for down-app)')
+    .description('Alias for down-app: stop and remove container')
     .option('--volumes', 'Remove application Docker volume')
     .action(async(appName, options) => {
       try {
@@ -255,7 +277,7 @@ function setupShellTestStopCommands(program) {
     });
 
   program.command('shell <app>')
-    .description('Open interactive shell in the application container')
+    .description('Interactive shell in running or ephemeral container')
     .option('--env <env>', 'Environment (dev|tst); dev uses running container', 'dev')
     .action(async(appName, options) => {
       try {
@@ -266,105 +288,20 @@ function setupShellTestStopCommands(program) {
         process.exit(1);
       }
     });
-
-  program.command('test <app>')
-    .description('Run tests (builder app: in container; external system: local validation)')
-    .option('--env <env>', 'For builder app: dev (running container) or tst (ephemeral)', 'dev')
-    .option('-d, --datasource <key>', 'For external system: test specific datasource only')
-    .option('-v, --verbose', 'Verbose output')
-    .action(async(appName, options) => {
-      try {
-        const pathsUtil = require('../utils/paths');
-        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-        if (appType && appType.baseDir === 'integration') {
-          const test = require('../external-system/test');
-          const results = await test.testExternalSystem(appName, options);
-          test.displayTestResults(results, options.verbose);
-          if (!results.valid) process.exit(1);
-        } else {
-          const { runAppTest } = require('../commands/app-test');
-          await runAppTest(appName, { env: options.env });
-        }
-      } catch (error) {
-        handleCommandError(error, 'test');
-        process.exit(1);
-      }
-    });
 }
 
-async function runTestE2ECommand(appName, options) {
-  const pathsUtil = require('../utils/paths');
-  const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-  if (appType && appType.baseDir === 'integration') {
-    const { runTestE2EForExternalSystem } = require('../commands/test-e2e-external');
-    const { success, results } = await runTestE2EForExternalSystem(appName, {
-      env: options.env,
-      debug: options.debug,
-      verbose: options.verbose,
-      async: options.async !== false
-    });
-    results.forEach(r => {
-      const icon = r.success ? chalk.green('✓') : chalk.red('✗');
-      const msg = r.error ? `${r.key}: ${r.error}` : r.key;
-      logger.log(`  ${icon} ${msg}`);
-    });
-    if (!success) process.exit(1);
-    return;
-  }
-  const { runAppTestE2e } = require('../commands/app-test');
-  await runAppTestE2e(appName, { env: options.env });
-}
-
-function setupInstallTestE2eLintCommands(program) {
-  program.command('install <app>')
-    .description('Install dependencies in container (builder apps only)')
-    .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
-    .action(async(appName, options) => {
-      try {
-        const pathsUtil = require('../utils/paths');
-        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-        if (appType && appType.baseDir === 'integration') {
-          logger.log(chalk.gray('Install is for builder applications only. Use aifabrix shell <app> to run commands in external setups.'));
-          return;
-        }
-        const { runAppInstall } = require('../commands/app-install');
-        await runAppInstall(appName, { env: options.env });
-      } catch (error) {
-        handleCommandError(error, 'install');
-        process.exit(1);
-      }
-    });
-
-  program.command('test-e2e <app>')
-    .description('Run e2e tests (builder: in container; external system: all datasources via dataplane)')
-    .option('-e, --env <env>', 'Environment: dev, tst, or pro (builder: dev/tst for container)')
-    .option('-v, --verbose', 'Show detailed step output and poll progress')
-    .option('--debug', 'Include debug output and write log to integration/<app>/logs/')
-    .option('--no-async', 'Use sync mode (no polling); single POST per datasource')
-    .action(async(appName, options) => {
-      try {
-        await runTestE2ECommand(appName, options);
-      } catch (error) {
-        handleCommandError(error, 'test-e2e');
-        process.exit(1);
-      }
-    });
-
-  program.command('lint <app>')
-    .description('Run lint in container (builder apps only)')
-    .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
+function setupDockerfileGenerateCommand(program) {
+  program.command('dockerfile <app>')
+    .description('Generate Dockerfile from detected runtime')
+    .option('-l, --language <lang>', 'Override language detection')
+    .option('-f, --force', 'Overwrite existing Dockerfile')
     .action(async(appName, options) => {
       try {
-        const pathsUtil = require('../utils/paths');
-        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-        if (appType && appType.baseDir === 'integration') {
-          logger.log(chalk.gray('lint is for builder applications only. Use aifabrix shell <app> then make lint or pnpm lint.'));
-          return;
-        }
-        const { runAppLint } = require('../commands/app-test');
-        await runAppLint(appName, { env: options.env });
+        const dockerfilePath = await app.generateDockerfileForApp(appName, options);
+        logger.log(formatSuccessParagraph('Dockerfile generated successfully!'));
+        logger.log(chalk.gray(`Location: ${dockerfilePath}`));
       } catch (error) {
-        handleCommandError(error, 'lint');
+        handleCommandError(error, 'dockerfile');
         process.exit(1);
       }
     });
@@ -373,6 +310,7 @@ function setupInstallTestE2eLintCommands(program) {
 function setupPushDeployDockerfileCommands(program) {
   program.command('push <app>')
     .description('Push image to Azure Container Registry')
+    .addHelpText('after', PUSH_HELP_AFTER)
     .option('-r, --registry <registry>', 'ACR registry URL (overrides application.yaml)')
     .option('-t, --tag <tag>', 'Image tag(s) - comma-separated for multiple (default: latest)')
     .action(async(appName, options) => {
@@ -385,15 +323,26 @@ function setupPushDeployDockerfileCommands(program) {
     });
 
   program.command('deploy <app>')
-    .description('Deploy to Azure or locally via Miso Controller')
+    .description('Deploy via Miso Controller (Azure or --local)')
+    .addHelpText('after', DEPLOY_HELP_AFTER)
     .option('--local', 'Send manifest to controller then run app locally (app: same as aifabrix run <app>; external: restart dataplane)')
     .option('--client-id <id>', 'Client ID (overrides config)')
     .option('--client-secret <secret>', 'Client Secret (overrides config)')
     .option('--poll', 'Poll for deployment status', true)
     .option('--no-poll', 'Do not poll for status')
+    .option('--probe', 'After external deploy, run dataplane runtime checks (validation/run); slower')
+    .option('--probe-timeout <ms>', 'Timeout for --probe on external deploy (default: 120000)', '120000')
     .action(async(appName, options) => {
       try {
-        const opts = { ...options, local: !!options.local };
+        const probeTimeout =
+          options.probeTimeout === undefined || options.probeTimeout === null
+            ? 120000
+            : Number(options.probeTimeout);
+        const opts = {
+          ...options,
+          local: !!options.local,
+          probeTimeout: Number.isFinite(probeTimeout) ? probeTimeout : 120000
+        };
         const outcome = await app.deployApp(appName, opts);
         if (opts.local && outcome) {
           if (outcome.usedExternalDeploy) await app.restartApp('dataplane');
@@ -405,20 +354,7 @@ function setupPushDeployDockerfileCommands(program) {
       }
     });
 
-  program.command('dockerfile <app>')
-    .description('Generate Dockerfile for an application')
-    .option('-l, --language <lang>', 'Override language detection')
-    .option('-f, --force', 'Overwrite existing Dockerfile')
-    .action(async(appName, options) => {
-      try {
-        const dockerfilePath = await app.generateDockerfileForApp(appName, options);
-        logger.log(chalk.green('\n✅ Dockerfile generated successfully!'));
-        logger.log(chalk.gray(`Location: ${dockerfilePath}`));
-      } catch (error) {
-        handleCommandError(error, 'dockerfile');
-        process.exit(1);
-      }
-    });
+  setupDockerfileGenerateCommand(program);
 }
 
 /**

package/lib/cli/setup-app.test-commands.js

@@ -0,0 +1,179 @@
+/**
+ * @fileoverview CLI test/install/lint command setup (builder app + external integration dispatch).
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const { TEST_HELP_AFTER, TEST_E2E_HELP_AFTER } = require('./setup-app.help');
+
+function setupTestCommand(program) {
+  program.command('test <app>')
+    .description('Tests: builder in container; external = local validation')
+    .option('-e, --env <env>', 'For builder app: dev (running container) or tst (ephemeral)', 'dev')
+    .option('-v, --verbose', 'Verbose output')
+    .option('-d, --debug', 'Write debug log to integration/<systemKey>/logs/ (external only)')
+    .option(
+      '--sync',
+      'Not supported for this command (local validation only). Use aifabrix upload <systemKey> or dataplane test commands with --sync.'
+    )
+    .addHelpText('after', TEST_HELP_AFTER)
+    .action(async(appName, options, cmd) => {
+      try {
+        const rawArgs = Array.isArray(cmd?.rawArgs) ? cmd.rawArgs : [];
+        const envExplicit = rawArgs.includes('-e') || rawArgs.includes('--env');
+        const pathsUtil = require('../utils/paths');
+        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+        if (options.sync === true) {
+          throw new Error(
+            'Option --sync is not supported for aifabrix test (local or container runs do not publish to the dataplane). ' +
+              'Use: aifabrix upload <systemKey>, then aifabrix test-integration <systemKey> --sync or aifabrix datasource test-integration <datasourceKey> --sync.'
+          );
+        }
+        if (appType && appType.baseDir === 'integration') {
+          const test = require('../external-system/test');
+          const externalOpts = {
+            ...options,
+            // Keep help default but don't override auth/env behavior unless user explicitly set it.
+            env: envExplicit ? options.env : undefined
+          };
+          const results = await test.testExternalSystem(appName, externalOpts);
+          test.displayTestResults(results, options.verbose, appName);
+          if (!results.valid) process.exit(1);
+          return;
+        }
+        const { runAppTest } = require('../commands/app-test');
+        await runAppTest(appName, { env: options.env });
+      } catch (error) {
+        handleCommandError(error, 'test');
+        process.exit(1);
+      }
+    });
+}
+
+async function runTestE2ECommand(appName, options) {
+  const pathsUtil = require('../utils/paths');
+  const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+  if (options.sync === true && appType && appType.baseDir === 'builder') {
+    throw new Error(
+      'Option --sync applies only to external integration E2E (integration/<systemKey>/). ' +
+        'Remove --sync for builder app E2E, or use aifabrix upload from the integration folder first.'
+    );
+  }
+  if (appType && appType.baseDir === 'integration') {
+    const { runTestE2EForExternalSystem } = require('../commands/test-e2e-external');
+    const { success, results } = await runTestE2EForExternalSystem(appName, {
+      env: options.env,
+      debug: options.debug,
+      verbose: options.verbose,
+      async: options.async !== false,
+      sync: options.sync === true
+    });
+    const { displayIntegrationTestResults } = require('../utils/external-system-display');
+    displayIntegrationTestResults(
+      {
+        systemKey: appName,
+        success,
+        datasourceResults: results.map(r => ({
+          key: r.key,
+          success: r.success,
+          error: r.error,
+          skipped: false,
+          datasourceTestRun: r.datasourceTestRun
+        }))
+      },
+      options.verbose,
+      { debug: options.debug, runType: 'e2e' }
+    );
+    if (!success) process.exit(1);
+    return;
+  }
+  const { runAppTestE2e } = require('../commands/app-test');
+  await runAppTestE2e(appName, { env: options.env });
+}
+
+function setupInstallCommand(program) {
+  program.command('install <app>')
+    .description('Install deps in container (builder apps only)')
+    .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
+    .action(async(appName, options) => {
+      try {
+        const pathsUtil = require('../utils/paths');
+        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+        if (appType && appType.baseDir === 'integration') {
+          logger.log(
+            chalk.gray('Install is for builder applications only. Use aifabrix shell <app> to run commands in external setups.')
+          );
+          return;
+        }
+        const { runAppInstall } = require('../commands/app-install');
+        await runAppInstall(appName, { env: options.env });
+      } catch (error) {
+        handleCommandError(error, 'install');
+        process.exit(1);
+      }
+    });
+}
+
+function setupTestE2eCommand(program) {
+  program.command('test-e2e <app>')
+    .description('E2E: builder in container; external = all datasources via dataplane')
+    .option('-e, --env <env>', 'Environment: dev, tst, or pro (builder: dev/tst for container)', 'dev')
+    .option('-v, --verbose', 'Show detailed step output and poll progress')
+    .option('-d, --debug', 'Include debug output and write log to integration/<systemKey>/logs/')
+    .option(
+      '--sync',
+      'Publish local system and datasource files to the dataplane before running E2E (same as aifabrix upload <systemKey>; external integration only)'
+    )
+    .addHelpText('after', TEST_E2E_HELP_AFTER)
+    .action(async(appName, options, cmd) => {
+      try {
+        const rawArgs = Array.isArray(cmd?.rawArgs) ? cmd.rawArgs : [];
+        const envExplicit = rawArgs.includes('-e') || rawArgs.includes('--env');
+        const externalOpts = {
+          ...options,
+          env: envExplicit ? options.env : undefined,
+          async: true // system-level command surface omits --no-async; always poll for completeness
+        };
+        await runTestE2ECommand(appName, externalOpts);
+      } catch (error) {
+        handleCommandError(error, 'test-e2e');
+        process.exit(1);
+      }
+    });
+}
+
+function setupLintCommand(program) {
+  program.command('lint <app>')
+    .description('Lint in container (builder apps only)')
+    .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
+    .action(async(appName, options) => {
+      try {
+        const pathsUtil = require('../utils/paths');
+        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+        if (appType && appType.baseDir === 'integration') {
+          logger.log(chalk.gray('lint is for builder applications only. Use aifabrix shell <app> then make lint or pnpm lint.'));
+          return;
+        }
+        const { runAppLint } = require('../commands/app-test');
+        await runAppLint(appName, { env: options.env });
+      } catch (error) {
+        handleCommandError(error, 'lint');
+        process.exit(1);
+      }
+    });
+}
+
+function setupInstallTestE2eLintCommands(program) {
+  setupInstallCommand(program);
+  setupTestCommand(program);
+  setupTestE2eCommand(program);
+  setupLintCommand(program);
+}
+
+module.exports = {
+  setupInstallTestE2eLintCommands
+};
+