@aifabrix/builder 2.45.0 → 2.46.0

package/lib/cli/infra-guided-auth.js

@@ -0,0 +1,109 @@
+/**
+ * Guided platform install authentication (device login URL + Dataplane recovery).
+ *
+ * @fileoverview Auth helpers for infra-guided up-platform / setup
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const config = require('../core/config');
+const { resolvePlatformControllerUrl } = require('../utils/platform-controller-url');
+const { withMutedLogger } = require('../utils/with-muted-logger');
+const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
+const { isAuthenticationError } = require('../utils/cli-utils');
+const { resolveControllerUrl, isPlatformAuthValidForController } = require('../utils/controller-url');
+
+/**
+ * @param {Object} authOpts
+ * @returns {Promise<string>}
+ */
+async function resolveGuidedAuthControllerUrl(authOpts = {}) {
+  return (
+    authOpts.platformControllerUrl ||
+    (await config.getPlatformControllerUrl()) ||
+    (await resolvePlatformControllerUrl())
+  );
+}
+
+/**
+ * @async
+ * @param {Function} handleLoginFn
+ * @param {string} controllerUrl
+ * @param {{ skipDataplaneVersionRefresh?: boolean }} [opts]
+ * @returns {Promise<void>}
+ */
+async function runGuidedDeviceLogin(handleLoginFn, controllerUrl, opts = {}) {
+  await handleLoginFn({
+    method: 'device',
+    controller: controllerUrl,
+    environment: 'dev',
+    compact: true,
+    skipDataplaneVersionRefresh: opts.skipDataplaneVersionRefresh === true,
+    exitOnFailure: false
+  });
+}
+
+/**
+ * @async
+ * @param {Function} handleLoginFn
+ * @param {Object} authOpts
+ * @param {{ startSpinner: Function, stopSpinnerSuccess: Function }} spinners
+ * @returns {Promise<void>}
+ */
+async function runGuidedAuthStep(handleLoginFn, authOpts, spinners) {
+  const spin = spinners.startSpinner('Authenticating...');
+  const controllerUrl = await resolveGuidedAuthControllerUrl(authOpts);
+  const skipLogin =
+    authOpts.skipLoginIfAuthenticated === true ||
+    (await isPlatformAuthValidForController(controllerUrl));
+  try {
+    if (skipLogin) {
+      spinners.stopSpinnerSuccess(spin, 'Already authenticated');
+      return;
+    }
+    await runGuidedDeviceLogin(handleLoginFn, controllerUrl, { skipDataplaneVersionRefresh: true });
+  } catch (authErr) {
+    if (spin) spin.fail('Authentication required');
+    logger.error(formatBlockingError('Authentication required. Complete sign-in in your browser.'));
+    await runGuidedDeviceLogin(handleLoginFn, controllerUrl, { skipDataplaneVersionRefresh: true });
+  }
+  spinners.stopSpinnerSuccess(spin, 'Authenticated');
+}
+
+/**
+ * @async
+ * @param {Object} options
+ * @param {Function} handleUpDataplane
+ * @param {Function} handleLoginFn
+ * @param {string} controllerUrl
+ * @returns {Promise<void>}
+ */
+async function runGuidedDataplaneWithAuthRecovery(options, handleUpDataplane, handleLoginFn, controllerUrl) {
+  try {
+    await withMutedLogger(() =>
+      handleUpDataplane({ ...options, platformInstall: true, skipInfraCheck: true })
+    );
+  } catch (error) {
+    if (!isAuthenticationError(error)) {
+      throw error;
+    }
+    const loginUrl = error.controllerUrl || controllerUrl || (await resolveControllerUrl());
+    logger.log('');
+    logger.log(chalk.yellow('Device login required to register and deploy Dataplane.'));
+    await runGuidedDeviceLogin(handleLoginFn, loginUrl, { skipDataplaneVersionRefresh: false });
+    await withMutedLogger(() =>
+      handleUpDataplane({ ...options, platformInstall: true, skipInfraCheck: true })
+    );
+  }
+}
+
+module.exports = {
+  resolveGuidedAuthControllerUrl,
+  runGuidedDeviceLogin,
+  runGuidedAuthStep,
+  runGuidedDataplaneWithAuthRecovery
+};

package/lib/cli/infra-guided.js

@@ -10,16 +10,19 @@ const config = require('../core/config');
 const devConfig = require('../utils/dev-config');
 const pathsUtil = require('../utils/paths');
 const { loadConfigFile } = require('../utils/config-format');
-const { resolveControllerUrl } = require('../utils/controller-url');
+const { computeAppBaseUrl, resolvePlatformControllerUrl } = require('../utils/platform-controller-url');
 const { withMutedLogger } = require('../utils/with-muted-logger');
-const { formatBlockingError, formatProgress, formatSuccessLine, successGlyph } = require('../utils/cli-test-layout-chalk');
-const { computePublicUrlBaseString } = require('../utils/url-declarative-public-base');
-const { joinUrlPath, normalizeFrontDoorPatternForHealth } = require('../utils/health-check-url');
+const { formatProgress, formatSuccessLine, successGlyph } = require('../utils/cli-test-layout-chalk');
 const ora = require('ora');
 const infra = require('../infrastructure');
 const { execWithDockerEnv } = require('../utils/docker-exec');
 const { getLogLevel, passesLevelFilter } = require('../commands/app-logs');
 const { handleLogin } = require('../commands/login');
+const {
+  resolveGuidedAuthControllerUrl,
+  runGuidedAuthStep,
+  runGuidedDataplaneWithAuthRecovery
+} = require('./infra-guided-auth');
 const healthCheck = require('../utils/health-check');
 const { prepareUrlsLocalRegistryForUpPlatform } = require('../commands/up-common');
 const { assertDevInfraUp } = require('../commands/dev-infra-gate');
@@ -126,44 +129,17 @@ function resolveInfraHost(remoteServer) {
   }
 }
 
-async function computeAppBaseUrl(appName) {
-  const builderPath = pathsUtil.getBuilderPath(appName);
-  const configPath = pathsUtil.resolveApplicationConfigPath(builderPath);
-  const variables = loadConfigFile(configPath) || {};
-  const basePort = Number(variables.port || 3000);
-  const developerIdRaw = await config.getDeveloperId();
-  const developerIdNum = typeof developerIdRaw === 'string' ? parseInt(developerIdRaw, 10) : developerIdRaw;
-  const userCfg = await config.getConfig();
-  const remoteServer = await config.getRemoteServer();
-  const infraTlsEnabled = Boolean(userCfg && userCfg.tlsEnabled);
-
-  const fd = variables.frontDoorRouting || null;
-  const frontDoorEnabled = Boolean(fd && fd.enabled === true);
-  const traefikOn = Boolean(userCfg && userCfg.traefik);
-  const pathActive = Boolean(traefikOn && frontDoorEnabled);
-
-  const publicBase = computePublicUrlBaseString({
-    traefik: traefikOn,
-    pathActive,
-    hostTemplate: fd ? fd.host : null,
-    tls: fd ? fd.tls : true,
-    developerIdRaw,
-    remoteServer,
-    // These guided bootstrap commands start services via Docker Compose, so we want the
-    // docker-published host port (no workstation +10 offset).
-    profile: 'docker',
-    listenPort: basePort,
-    developerIdNum,
-    infraTlsEnabled
-  });
-
-  if (pathActive) {
-    const mount = normalizeFrontDoorPatternForHealth(fd.pattern);
-    return joinUrlPath(publicBase, mount);
+/**
+ * Prefer stored platform controller URL, then compute from routing rules.
+ * @async
+ * @returns {Promise<string>}
+ */
+async function resolvePlatformControllerUrlForDisplay() {
+  const stored = await config.getPlatformControllerUrl();
+  if (stored) {
+    return stored;
   }
-
-  // No Traefik front-door routing: publicBase is localhost + published port unless Traefik/proxy opts into remote.
-  return String(publicBase).replace(/\/+$/, '');
+  return resolvePlatformControllerUrl();
 }
 
 function logSection(label, value) {
@@ -186,7 +162,7 @@ function logFooterEnd() {
 
 async function logPlatformReadyFooter() {
   const [controllerUrl, dataplaneUrl, keycloakUrl] = await Promise.all([
-    resolveControllerUrl(),
+    resolvePlatformControllerUrlForDisplay(),
     computeAppBaseUrl('dataplane'),
     computeAppBaseUrl('keycloak')
   ]);
@@ -206,7 +182,7 @@ async function logPlatformReadyFooter() {
 
 async function logMisoReadyFooter() {
   const [controllerUrl, keycloakUrl] = await Promise.all([
-    resolveControllerUrl(),
+    resolvePlatformControllerUrlForDisplay(),
     computeAppBaseUrl('keycloak')
   ]);
   logFooterStart('Miso Ready');
@@ -280,6 +256,8 @@ async function runGuidedUpMiso(options, handleUpMiso) {
   logger.log(title('AI Fabrix Platform Setup'));
   logger.log(SEPARATOR);
   logger.log('');
+  logPlatformSetupDurationHint('platform');
+  logger.log('');
   const kcSpin = startSpinner('Starting Keycloak...');
   await withMutedLogger(() => handleUpMiso({ ...options, platformInstall: true }));
   stopSpinnerSuccess(kcSpin, 'Keycloak ready');
@@ -291,13 +269,11 @@ async function runGuidedUpMiso(options, handleUpMiso) {
   await validateAppErrorLogs(['miso-controller']);
 }
 
-async function runGuidedUpDataplane(options, handleUpDataplane) {
-  logger.log('');
-  logger.log(title('AI Fabrix Dataplane Setup'));
-  logger.log(SEPARATOR);
-  logger.log('');
-  // Infra must be checked before auth: device login talks to the controller, which needs
-  // Postgres/Redis when the controller runs locally — a down infra looks like "network error".
+/**
+ * Infra must be checked before auth: device login talks to the controller, which needs
+ * Postgres/Redis when the controller runs locally — a down infra looks like "network error".
+ */
+async function assertDevInfraForGuidedDataplane() {
   const infraSpin = startSpinner('Checking infrastructure...');
   try {
     await assertDevInfraUp({ quietSuccess: true });
@@ -307,11 +283,21 @@ async function runGuidedUpDataplane(options, handleUpDataplane) {
     if (infraSpin) infraSpin.stop();
     throw infraErr;
   }
+}
+
+async function runGuidedUpDataplane(options, handleUpDataplane) {
+  logger.log('');
+  logger.log(title('AI Fabrix Dataplane Setup'));
+  logger.log(SEPARATOR);
+  logger.log('');
+  logPlatformSetupDurationHint('dataplane');
+  logger.log('');
+  await assertDevInfraForGuidedDataplane();
   // Avoid an outer long-running spinner here: up-dataplane has multiple internal
   // phases and may print some output. An outer spinner causes "spinner over spinner"
   // rendering artifacts. Instead, do the same single auth step as up-platform, then
   // show one spinner for the dataplane install/run phase.
-  await runGuidedAuthStep(handleLogin);
+  await runGuidedAuthStep(handleLogin, {}, { startSpinner, stopSpinnerSuccess });
 
   logger.log('');
   emitSystemBuilderAppManifestLineIfTTY(logger, 'dataplane');
@@ -320,6 +306,7 @@ async function runGuidedUpDataplane(options, handleUpDataplane) {
     handleUpDataplane({ ...options, platformInstall: true, skipInfraCheck: true })
   );
   stopSpinnerSuccess(dpSpin, 'Dataplane ready');
+  await refreshDataplaneVersionAfterPlatformInstall();
   await validateAppErrorLogs(['dataplane']);
   await logDataplaneReadyFooter();
 }
@@ -330,6 +317,8 @@ async function runGuidedUpDataplane(options, handleUpDataplane) {
  * @param {string[]} cleanedApps
  */
 function logUpPlatformForceCleanSummary(forceSummary, cleanedApps) {
+  const { isSetupQuietOutput } = require('../utils/setup-quiet-output');
+  if (isSetupQuietOutput()) return;
   const check = successGlyph();
   logger.log(chalk.bold('Clean installation files'));
   logger.log(
@@ -349,27 +338,35 @@ function logUpPlatformForceCleanSummary(forceSummary, cleanedApps) {
   logger.log('');
 }
 
+/**
+ * Yellow notice before long-running platform/dataplane install steps (setup and guided up-*).
+ * @param {'platform'|'dataplane'} [scope]
+ */
+function logPlatformSetupDurationHint(scope = 'platform') {
+  const line =
+    scope === 'dataplane'
+      ? 'Installation may take a few minutes. Authenticating and starting Dataplane — please wait.'
+      : 'Installation may take a few minutes. Keycloak, Miso Controller, and Dataplane are starting — please wait.';
+  logger.log(chalk.yellow(`⚠ ${line}`));
+}
+
 function logGuidedPlatformSetupHeader() {
   logger.log('');
   logger.log(title('AI Fabrix Platform Setup'));
   logger.log(SEPARATOR);
-  logger.log(chalk.gray('This may take a few minutes...'));
+  logger.log('');
+  logPlatformSetupDurationHint('platform');
   logger.log('');
 }
 
-async function runGuidedAuthStep(handleLogin) {
-  const spin = startSpinner('Authenticating...');
+async function refreshDataplaneVersionAfterPlatformInstall() {
   try {
-    const controllerUrl = await resolveControllerUrl();
-    await handleLogin({ method: 'device', controller: controllerUrl, environment: 'dev', compact: true });
-  } catch (authErr) {
-    if (spin) spin.fail('Authentication failed');
-    logger.error(formatBlockingError('Authentication failed'));
-    logger.log(chalk.gray('\nRun:\n  af login\n\nThen retry:\n  af up-platform\n'));
-    throw authErr;
+    const { tryRefreshDataplaneVersionAfterLogin } = require('../commands/auth-status-dataplane-version');
+    const controllerUrl = await resolvePlatformControllerUrlForDisplay();
+    await tryRefreshDataplaneVersionAfterLogin(controllerUrl, {});
+  } catch {
+    // best-effort only
   }
-  // Compact device-login already prints a success line; don't duplicate it.
-  if (spin) spin.stop();
 }
 
 async function runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso) {
@@ -385,14 +382,27 @@ async function runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso) {
   logger.log('');
 }
 
-async function runGuidedDataplaneInstallPhase(options, handleUpDataplane) {
+async function runGuidedDataplaneInstallPhase(options, handleUpDataplane, handleLoginFn, controllerUrl) {
   logger.log('');
   emitSystemBuilderAppManifestLineIfTTY(logger, 'dataplane');
   const dpSpin = startSpinner('Starting Dataplane...');
-  await withMutedLogger(() =>
-    handleUpDataplane({ ...options, platformInstall: true, skipInfraCheck: true })
-  );
+  const platformMode = await config.getSetupPlatformMode();
+  if (platformMode === 'full') {
+    // Full platform: three dataplane containers + per-env registrations.
+    const envKeys = ['pro', 'dev', 'tst'];
+    for (const envKey of envKeys) {
+      await runGuidedDataplaneWithAuthRecovery(
+        { ...options, envKey, runEnvKey: envKey, allowNonDev: true },
+        handleUpDataplane,
+        handleLoginFn,
+        controllerUrl
+      );
+    }
+  } else {
+    await runGuidedDataplaneWithAuthRecovery(options, handleUpDataplane, handleLoginFn, controllerUrl);
+  }
   stopSpinnerSuccess(dpSpin, 'Dataplane ready');
+  await refreshDataplaneVersionAfterPlatformInstall();
 }
 
 async function runGuidedUpPlatform(options, handleUpMiso, handleUpDataplane, handleLogin, forceCleanSummary = null) {
@@ -401,10 +411,22 @@ async function runGuidedUpPlatform(options, handleUpMiso, handleUpDataplane, han
     logUpPlatformForceCleanSummary(forceCleanSummary.forceSummary, forceCleanSummary.cleanedApps);
   }
 
+  const authOpts = {
+    platformControllerUrl: options && options.platformControllerUrl,
+    skipLoginIfAuthenticated: options && options.skipLoginIfAuthenticated === true
+  };
+
   await withMutedLogger(() => prepareUrlsLocalRegistryForUpPlatform());
   await runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso);
-  await runGuidedAuthStep(handleLogin);
-  await runGuidedDataplaneInstallPhase(options, handleUpDataplane);
+  if (options && options.requireKeycloakRealm === true) {
+    const { waitForKeycloakRealmReady } = require('../utils/keycloak-realm-ready');
+    const realmSpin = startSpinner('Waiting for Keycloak realm (aifabrix)...');
+    await waitForKeycloakRealmReady({ timeoutSeconds: 180 });
+    stopSpinnerSuccess(realmSpin, 'Keycloak realm ready');
+  }
+  await runGuidedAuthStep(handleLogin, authOpts, { startSpinner, stopSpinnerSuccess });
+  const controllerUrl = await resolveGuidedAuthControllerUrl(authOpts);
+  await runGuidedDataplaneInstallPhase(options, handleUpDataplane, handleLogin, controllerUrl);
   await validateAppErrorLogs(['miso-controller', 'dataplane']);
   await logPlatformReadyFooter();
 }

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

@@ -56,12 +56,29 @@ Examples:
 Notes:
   - To run E2E for one datasource, use:
       aifabrix datasource test-e2e <datasourceKey>
-  - External integration: local system and datasource files are published to the dataplane before E2E (same as upload). Use --no-sync to exercise only config already deployed. The old --sync flag is a no-op (kept for scripts).
+  - External integration: local system and datasource files are published to the dataplane before E2E (same as upload). Use --no-sync to exercise only config already deployed.
+`;
+
+const IDENTITY_HELP_AFTER = `
+Examples:
+  # Bulk seed from demo users.csv (test-protection prefix) + sync + cache purge
+  $ aifabrix identity apply --file ./users.csv --filter-prefix test-protection -e dev --sync --purge-cache
+  $ aifabrix identity sync -e dev --purge-cache
+  $ aifabrix identity cache clear
+
+  # Single user / group
+  $ aifabrix identity user create --email alice@example.com --first-name Alice --last-name HR
+  $ aifabrix identity group create --name test-protection-sales-fi --description "Sales Finland"
+
+Notes:
+  - Requires aifabrix login (controller token). See docs/commands/identity-management.md.
+  - Prefer identity apply over SQL in tests/fixtures/protection/optional-dev-identity-dataplane.sql.
 `;
 
 module.exports = {
   TEST_HELP_AFTER,
   TEST_INTEGRATION_HELP_AFTER,
-  TEST_E2E_HELP_AFTER
+  TEST_E2E_HELP_AFTER,
+  IDENTITY_HELP_AFTER
 };
 

package/lib/cli/setup-app.js

@@ -16,14 +16,49 @@ const { setupInstallTestE2eLintCommands } = require('./setup-app.test-commands')
 
 const CREATE_HELP_AFTER = `
 Examples:
+  # Builder app → builder/<appKey>/
   $ aifabrix create myapi --type webapp -l typescript
-  $ aifabrix create mycrm --wizard
+  $ aifabrix create mysvc --type api -l python
+
+  # External system → integration/<systemKey>/ (default --type external)
+  $ aifabrix create hubspot --wizard
+  $ aifabrix create mycrm --type external --display-name "My CRM" --description "..." \\
+      --system-type openapi --auth-type oauth2 --entity-type recordStorage --datasources 1
+
+Positional: appKey for builder types; systemKey for --type external (folder under integration/).
+Prefer aifabrix wizard [systemKey] for guided external setup.
 `;
 
 const DEPLOY_HELP_AFTER = `
 Examples:
+  # Local — builder app (builder/<appKey>/)
   $ aifabrix deploy myapp
-  $ aifabrix deploy myext --local
+  $ aifabrix deploy myapp --local
+
+  # Local — external system (integration/<systemKey>/); manifest regenerated on deploy
+  $ aifabrix deploy hubspot-demo
+  $ aifabrix deploy hubspot-demo --local
+  $ aifabrix deploy hubspot-demo --probe
+
+  # CI/CD — builder app (GitHub Actions / Azure DevOps; pipeline client credentials in secrets)
+  $ aifabrix validate myapp
+  $ aifabrix build myapp
+  $ aifabrix push myapp --registry $ACR_REGISTRY --tag $IMAGE_TAG
+  $ aifabrix deploy myapp \\
+      --client-id "$DEV_MISO_CLIENTID" \\
+      --client-secret "$DEV_MISO_CLIENTSECRET" \\
+      --no-poll
+
+  # CI/CD — external integration (after upload/tests; promote to controller)
+  $ aifabrix validate hubspot-demo
+  $ aifabrix upload hubspot-demo --probe
+  $ aifabrix deploy hubspot-demo --probe --no-poll
+
+Notes:
+  - Login or set MISO_CONTROLLER_URL + environment (aifabrix login / aifabrix auth).
+  - CI: register once (aifabrix app register <appKey>), store DEV_MISO_CLIENTID and DEV_MISO_CLIENTSECRET in pipeline secrets.
+  - upload = dataplane publish for dev iteration; deploy = controller validate + deploy (Azure or local Docker).
+  - --repository-url overrides repo URL for pipeline validate (default: application.yaml repository.repositoryUrl).
 `;
 
 const PUSH_HELP_AFTER = `
@@ -133,8 +168,8 @@ async function handleCreateCommand(appName, options) {
 }
 
 function setupCreateCommand(program) {
-  program.command('create <app>')
-    .description('Scaffold builder or external app (flags or --wizard)')
+  program.command('create <appKey|systemKey>')
+    .description('Create builder app (builder/<appKey>/) or external system (integration/<systemKey>/; --type, flags, or --wizard)')
     .addHelpText('after', CREATE_HELP_AFTER)
     .option('-p, --port <port>', 'Application port', '3000')
     .option('-d, --database', 'Requires database')
@@ -148,7 +183,7 @@ function setupCreateCommand(program) {
     .option('-g, --github', 'Generate GitHub Actions workflows')
     .option('--github-steps <steps>', 'Extra GitHub workflow steps (comma-separated, e.g., npm,test)')
     .option('--main-branch <branch>', 'Main branch name for workflows', 'main')
-    .option('--wizard', 'Use interactive wizard for external system creation')
+    .option('--wizard', 'Run wizard for external system (systemKey → integration/<systemKey>/; same as aifabrix wizard)')
     .option('--display-name <name>', 'External system display name')
     .option('--description <desc>', 'External system description')
     .option('--system-type <type>', 'External system type (openapi, mcp, custom)')
@@ -209,8 +244,8 @@ Examples:
   $ aifabrix run myapp --base
   $ aifabrix run myapp --reload
   $ aifabrix run myapp --no-proxy   # same as --proxy false: localhost for Docker declarative public URLs; saves applications.<app>.proxy: false`;
-  program.command('run <app>')
-    .description('Run app locally or on remote Docker host')
+  program.command('run <appKey>')
+    .description('Run builder app by appKey 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')
@@ -238,8 +273,8 @@ Examples:
 }
 
 function setupBuildRunLogsDownCommands(program) {
-  program.command('build <app>')
-    .description('Build Docker image (auto-detect runtime)')
+  program.command('build <appKey>')
+    .description('Build Docker image for builder appKey (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')
@@ -257,8 +292,8 @@ function setupBuildRunLogsDownCommands(program) {
 
   registerRunCommand(program);
 
-  program.command('logs <app>')
-    .description('Tail app container logs (optional env summary; secrets masked)')
+  program.command('logs <appKey>')
+    .description('Tail container logs for appKey (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)')
@@ -275,8 +310,8 @@ function setupBuildRunLogsDownCommands(program) {
       }
     });
 
-  program.command('down-app <app>')
-    .description('Stop and remove app container (--volumes removes data volume)')
+  program.command('down-app <appKey>')
+    .description('Stop and remove container for appKey (--volumes removes data volume)')
     .option('--volumes', 'Remove application Docker volume')
     .action(async(appName, options) => {
       try {
@@ -290,8 +325,8 @@ function setupBuildRunLogsDownCommands(program) {
 }
 
 function setupShellTestStopCommands(program) {
-  program.command('stop <app>')
-    .description('Alias for down-app: stop and remove container')
+  program.command('stop <appKey>')
+    .description('Alias for down-app: stop and remove container for appKey')
     .option('--volumes', 'Remove application Docker volume')
     .action(async(appName, options) => {
       try {
@@ -303,8 +338,8 @@ function setupShellTestStopCommands(program) {
       }
     });
 
-  program.command('shell <app>')
-    .description('Interactive shell in running or ephemeral container')
+  program.command('shell <appKey>')
+    .description('Interactive shell in container for builder appKey')
     .option('--env <env>', 'Environment (dev|tst); dev uses running container', 'dev')
     .action(async(appName, options) => {
       try {
@@ -318,8 +353,8 @@ function setupShellTestStopCommands(program) {
 }
 
 function setupDockerfileGenerateCommand(program) {
-  program.command('dockerfile <app>')
-    .description('Generate Dockerfile from detected runtime')
+  program.command('dockerfile <appKey>')
+    .description('Generate Dockerfile for builder appKey from detected runtime')
     .option('-l, --language <lang>', 'Override language detection')
     .option('-f, --force', 'Overwrite existing Dockerfile')
     .action(async(appName, options) => {
@@ -335,8 +370,8 @@ function setupDockerfileGenerateCommand(program) {
 }
 
 function setupPushDeployDockerfileCommands(program) {
-  program.command('push <app>')
-    .description('Push image to Azure Container Registry')
+  program.command('push <appKey>')
+    .description('Push builder appKey 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)')
@@ -349,8 +384,8 @@ function setupPushDeployDockerfileCommands(program) {
       }
     });
 
-  program.command('deploy <app>')
-    .description('Deploy via Miso Controller (Azure or --local)')
+  program.command('deploy <appKey|systemKey>')
+    .description('Deploy builder app or external system 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)')