@aifabrix/builder 2.44.5 → 2.45.0

package/lib/cli/infra-guided.js

@@ -0,0 +1,460 @@
+/**
+ * @fileoverview Guided (non-verbose) UX for infra/platform commands.
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+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 { 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 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 healthCheck = require('../utils/health-check');
+const { prepareUrlsLocalRegistryForUpPlatform } = require('../commands/up-common');
+const { assertDevInfraUp } = require('../commands/dev-infra-gate');
+const {
+  emitSystemBuilderAppManifestLineIfTTY
+} = require('../utils/manifest-source-emit');
+
+const SEPARATOR = '────────────────────────────────────────';
+
+function title(text) {
+  return chalk.bold(text);
+}
+
+function shouldUseSpinner() {
+  return Boolean(process && process.stdout && process.stdout.isTTY);
+}
+
+function startSpinner(text) {
+  if (!shouldUseSpinner()) {
+    logger.log(formatProgress(text));
+    return null;
+  }
+  return ora({ text, spinner: 'dots' }).start();
+}
+
+function stopSpinnerSuccess(spinner, text) {
+  if (!spinner) {
+    logger.log(formatSuccessLine(text));
+    return;
+  }
+  spinner.succeed(text);
+}
+
+async function getRunningContainerNameForApp(appName) {
+  const apps = await infra.getAppStatus();
+  const hit = (apps || []).find(a => a && a.name === appName && a.container);
+  return hit ? hit.container : null;
+}
+
+async function hasErrorLogs(appName, opts = {}) {
+  const tailLines = Number.isFinite(opts.tailLines) ? opts.tailLines : 200;
+  const container = await getRunningContainerNameForApp(appName);
+  if (!container) return false;
+  const { stdout } = await execWithDockerEnv(`docker logs --tail ${tailLines} ${container}`);
+  const lines = String(stdout || '').split('\n');
+  return lines.some(line => passesLevelFilter(getLogLevel(line), 'error'));
+}
+
+async function validateAppErrorLogs(appNames) {
+  const names = Array.isArray(appNames) ? appNames : [];
+  const bad = [];
+  for (const name of names) {
+    try {
+      const hasErrors = await hasErrorLogs(name, { tailLines: 300 });
+      if (hasErrors) {
+        bad.push(name);
+      }
+    } catch {
+      // ignore per-app log failures
+    }
+  }
+  if (bad.length === 0) {
+    return;
+  }
+  logger.log(chalk.yellow('⚠ Some services reported error logs'));
+  for (const name of bad) {
+    logger.log(chalk.gray(`  Run: aifabrix logs ${name} -l error`));
+  }
+  logger.log('');
+}
+
+async function waitForAppReady(appName, opts = {}) {
+  const timeoutSeconds = Number.isFinite(opts.timeoutSeconds) ? opts.timeoutSeconds : 90;
+  const builderPath = pathsUtil.getBuilderPath(appName);
+  const configPath = pathsUtil.resolveApplicationConfigPath(builderPath);
+  const appConfig = loadConfigFile(configPath) || {};
+
+  const apps = await infra.getAppStatus();
+  const hit = (apps || []).find(a => a && a.name === appName && typeof a.url === 'string');
+  const portMatch = hit && hit.url ? hit.url.match(/:(\d+)$/) : null;
+  const hostPort = portMatch ? parseInt(portMatch[1], 10) : null;
+  if (!hostPort) {
+    throw new Error(`Could not determine host port for ${appName}`);
+  }
+
+  const userCfg = await config.getConfig();
+  const healthRunOpts = { profile: 'docker' };
+  if (userCfg && userCfg.traefik === true) {
+    healthRunOpts.traefikEnabled = true;
+  }
+  await healthCheck.waitForHealthCheck(appName, timeoutSeconds, hostPort, appConfig, false, healthRunOpts);
+}
+
+function resolveInfraHost(remoteServer) {
+  const raw = String(remoteServer || '').trim().replace(/\/+$/, '');
+  if (!raw) return 'localhost';
+  try {
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `http://${raw}`;
+    const u = new URL(withScheme);
+    return u.hostname || 'localhost';
+  } catch {
+    // Fallback for non-URL strings.
+    return raw.replace(/^https?:\/\//i, '').split('/')[0].split(':')[0] || 'localhost';
+  }
+}
+
+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);
+  }
+
+  // No Traefik front-door routing: publicBase is localhost + published port unless Traefik/proxy opts into remote.
+  return String(publicBase).replace(/\/+$/, '');
+}
+
+function logSection(label, value) {
+  logger.log(title(label));
+  logger.log(`  ${value}`);
+  logger.log('');
+}
+
+function logFooterStart(label) {
+  logger.log('');
+  logger.log(SEPARATOR);
+  logger.log(title(label));
+  logger.log(SEPARATOR);
+  logger.log('');
+}
+
+function logFooterEnd() {
+  logger.log(SEPARATOR);
+}
+
+async function logPlatformReadyFooter() {
+  const [controllerUrl, dataplaneUrl, keycloakUrl] = await Promise.all([
+    resolveControllerUrl(),
+    computeAppBaseUrl('dataplane'),
+    computeAppBaseUrl('keycloak')
+  ]);
+  const cfg = await config.getConfig();
+  const env = (cfg && cfg.environment) ? cfg.environment : 'dev';
+
+  logFooterStart('Platform Ready');
+  logSection('Environment', env);
+  logSection('Miso Controller', controllerUrl);
+  logSection('Dataplane (DEV)', dataplaneUrl);
+  logSection('Keycloak', keycloakUrl);
+  logSection('API Documentation', `${dataplaneUrl}/api/docs`);
+  logSection('Knowledge Base', 'https://docs.aifabrix.ai');
+  logSection('Getting Started', 'https://docs.aifabrix.ai/get-started');
+  logFooterEnd();
+}
+
+async function logMisoReadyFooter() {
+  const [controllerUrl, keycloakUrl] = await Promise.all([
+    resolveControllerUrl(),
+    computeAppBaseUrl('keycloak')
+  ]);
+  logFooterStart('Miso Ready');
+  logSection('Miso Controller', controllerUrl);
+  logSection('Keycloak', keycloakUrl);
+  logFooterEnd();
+}
+
+async function logDataplaneReadyFooter() {
+  const dataplaneUrl = await computeAppBaseUrl('dataplane');
+  const cfg = await config.getConfig();
+  const env = (cfg && cfg.environment) ? cfg.environment : 'dev';
+  logFooterStart('Dataplane Ready');
+  logSection('Environment', env);
+  logSection('Dataplane (DEV)', dataplaneUrl);
+  logSection('API Documentation', `${dataplaneUrl}/api/docs`);
+  logFooterEnd();
+}
+
+async function getInfraHostAndPorts() {
+  const developerId = await config.getDeveloperId();
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  const ports = devConfig.getDevPorts(idNum);
+  const cfg = await config.getConfig();
+  const traefikOn = Boolean(cfg && cfg.traefik === true);
+  const remoteServer = traefikOn ? await config.getRemoteServer() : null;
+  const host = resolveInfraHost(remoteServer);
+  return { idNum, ports, host };
+}
+
+async function runGuidedUpInfra(options, runUpInfraCommand) {
+  logger.log('');
+  logger.log(title('AI Fabrix Infrastructure Setup'));
+  logger.log(SEPARATOR);
+  logger.log('');
+  const spin = startSpinner('Starting infrastructure services...');
+  await withMutedLogger(() => runUpInfraCommand(options), {
+    allow: (msg) => {
+      if (typeof msg !== 'string') return false;
+      return (
+        msg.includes('✔ Developer ID set to') ||
+        msg.includes('✔ Traefik enabled and saved to config') ||
+        msg.includes('✔ Traefik disabled and saved to config') ||
+        msg.includes('✔ pgAdmin enabled and saved to config') ||
+        msg.includes('✔ pgAdmin disabled and saved to config') ||
+        msg.includes('✔ Redis Commander enabled and saved to config') ||
+        msg.includes('✔ Redis Commander disabled and saved to config')
+      );
+    }
+  });
+  stopSpinnerSuccess(spin, 'Infrastructure ready');
+
+  const [{ idNum, ports, host }, cfg] = await Promise.all([
+    getInfraHostAndPorts(),
+    config.getConfig()
+  ]);
+
+  logFooterStart('Infra Ready');
+  logSection('Developer', `dev${String(idNum).padStart(2, '0')} (id: ${idNum})`);
+  logSection('Postgres', `${host}:${ports.postgres}`);
+  logSection('Redis', `${host}:${ports.redis}`);
+  if (cfg.pgadmin !== false) logSection('pgAdmin', `http://${host}:${ports.pgadmin}`);
+  if (cfg.redisCommander !== false) logSection('Redis Commander', `http://${host}:${ports.redisCommander}`);
+  if (cfg.traefik) logSection('Traefik', `http://${host}:${ports.traefikHttp}`);
+  if (cfg.tlsEnabled === true) logSection('TLS mode', 'on');
+  logFooterEnd();
+}
+
+async function runGuidedUpMiso(options, handleUpMiso) {
+  logger.log('');
+  logger.log(title('AI Fabrix Platform Setup'));
+  logger.log(SEPARATOR);
+  logger.log('');
+  const kcSpin = startSpinner('Starting Keycloak...');
+  await withMutedLogger(() => handleUpMiso({ ...options, platformInstall: true }));
+  stopSpinnerSuccess(kcSpin, 'Keycloak ready');
+  logger.log('');
+  const mcSpin = startSpinner('Starting Miso Controller...');
+  await waitForAppReady('miso-controller', { timeoutSeconds: 120 });
+  stopSpinnerSuccess(mcSpin, 'Miso Controller ready');
+  await logMisoReadyFooter();
+  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".
+  const infraSpin = startSpinner('Checking infrastructure...');
+  try {
+    await assertDevInfraUp({ quietSuccess: true });
+    stopSpinnerSuccess(infraSpin, 'Infrastructure is up');
+  } catch (infraErr) {
+    // Match up-miso: one error block from handleCommandError only (no spinner.fail / extra hints).
+    if (infraSpin) infraSpin.stop();
+    throw infraErr;
+  }
+  // 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);
+
+  logger.log('');
+  emitSystemBuilderAppManifestLineIfTTY(logger, 'dataplane');
+  const dpSpin = startSpinner('Starting Dataplane...');
+  await withMutedLogger(() =>
+    handleUpDataplane({ ...options, platformInstall: true, skipInfraCheck: true })
+  );
+  stopSpinnerSuccess(dpSpin, 'Dataplane ready');
+  await validateAppErrorLogs(['dataplane']);
+  await logDataplaneReadyFooter();
+}
+
+/**
+ * Guided-mode summary after `up-platform --force` (printed under the platform header).
+ * @param {{ deviceCleared: number, clientCleared: number, environment: string, defaultControllerUrl: string }} forceSummary
+ * @param {string[]} cleanedApps
+ */
+function logUpPlatformForceCleanSummary(forceSummary, cleanedApps) {
+  const check = successGlyph();
+  logger.log(chalk.bold('Clean installation files'));
+  logger.log(
+    chalk.gray(
+      ` ${check} Cleared ${forceSummary.deviceCleared} device token(s) and ${forceSummary.clientCleared} client token(s)`
+    )
+  );
+  logger.log(chalk.gray(` ${check} Environment set to ${forceSummary.environment}`));
+  logger.log(
+    chalk.gray(
+      ` ${check} Default controller set to ${forceSummary.defaultControllerUrl} (run aifabrix login after platform is up)`
+    )
+  );
+  for (const appName of cleanedApps || []) {
+    logger.log(chalk.gray(` ${check} Cleaned builder/${appName}`));
+  }
+  logger.log('');
+}
+
+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('');
+}
+
+async function runGuidedAuthStep(handleLogin) {
+  const spin = startSpinner('Authenticating...');
+  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;
+  }
+  // Compact device-login already prints a success line; don't duplicate it.
+  if (spin) spin.stop();
+}
+
+async function runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso) {
+  emitSystemBuilderAppManifestLineIfTTY(logger, 'keycloak');
+  const kcSpin = startSpinner('Starting Keycloak...');
+  await withMutedLogger(() => handleUpMiso({ ...options, platformInstall: true }));
+  stopSpinnerSuccess(kcSpin, 'Keycloak ready');
+  logger.log('');
+  emitSystemBuilderAppManifestLineIfTTY(logger, 'miso-controller');
+  const mcSpin = startSpinner('Starting Miso Controller...');
+  await waitForAppReady('miso-controller', { timeoutSeconds: 120 });
+  stopSpinnerSuccess(mcSpin, 'Miso Controller ready');
+  logger.log('');
+}
+
+async function runGuidedDataplaneInstallPhase(options, handleUpDataplane) {
+  logger.log('');
+  emitSystemBuilderAppManifestLineIfTTY(logger, 'dataplane');
+  const dpSpin = startSpinner('Starting Dataplane...');
+  await withMutedLogger(() =>
+    handleUpDataplane({ ...options, platformInstall: true, skipInfraCheck: true })
+  );
+  stopSpinnerSuccess(dpSpin, 'Dataplane ready');
+}
+
+async function runGuidedUpPlatform(options, handleUpMiso, handleUpDataplane, handleLogin, forceCleanSummary = null) {
+  logGuidedPlatformSetupHeader();
+  if (forceCleanSummary && forceCleanSummary.forceSummary) {
+    logUpPlatformForceCleanSummary(forceCleanSummary.forceSummary, forceCleanSummary.cleanedApps);
+  }
+
+  await withMutedLogger(() => prepareUrlsLocalRegistryForUpPlatform());
+  await runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso);
+  await runGuidedAuthStep(handleLogin);
+  await runGuidedDataplaneInstallPhase(options, handleUpDataplane);
+  await validateAppErrorLogs(['miso-controller', 'dataplane']);
+  await logPlatformReadyFooter();
+}
+
+function logStoppedServices(cfg) {
+  logger.log(title('Stopped'));
+  logger.log('  postgres');
+  logger.log('  redis');
+  if (cfg.pgadmin !== false) logger.log('  pgadmin');
+  if (cfg.redisCommander !== false) logger.log('  redis-commander');
+  if (cfg.traefik) logger.log('  traefik');
+  logger.log('');
+}
+
+async function runGuidedDownInfra(appName, options, infra, appLib) {
+  logger.log('');
+  logger.log(title('AI Fabrix Shutdown'));
+  logger.log(SEPARATOR);
+  logger.log('');
+
+  const spin = startSpinner('Stopping infrastructure...');
+  await withMutedLogger(async() => {
+    if (typeof appName === 'string' && appName.trim().length > 0) {
+      await appLib.downApp(appName, { volumes: !!options.volumes });
+      return;
+    }
+    if (options.volumes) await infra.stopInfraWithVolumes();
+    else await infra.stopInfra();
+  });
+  stopSpinnerSuccess(spin, 'Infrastructure stopped');
+
+  const developerId = await config.getDeveloperId();
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  const cfg = await config.getConfig();
+
+  logFooterStart('Stopped');
+  logSection('Developer', `dev${String(idNum).padStart(2, '0')} (id: ${idNum})`);
+  logStoppedServices(cfg);
+  if (options.volumes) {
+    logger.log(chalk.yellow('⚠ Volumes removed: all local data deleted'));
+    logger.log('');
+  }
+  logFooterEnd();
+}
+
+module.exports = {
+  runGuidedUpInfra,
+  runGuidedUpMiso,
+  runGuidedUpDataplane,
+  runGuidedUpPlatform,
+  runGuidedDownInfra
+};
+

package/lib/cli/installation-log-command.js

@@ -0,0 +1,73 @@
+/**
+ * Shared completion hook for infra/platform CLI commands (installation.log).
+ *
+ * @fileoverview installation.log CLI helper
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const config = require('../core/config');
+const installationLog = require('../utils/installation-log');
+
+/**
+ * @param {Object} params
+ * @param {string} params.command
+ * @param {Object} params.options
+ * @param {Date} params.startedAt
+ * @param {'success'|'failure'} params.outcome
+ * @param {Error} [params.error]
+ * @param {string[]} [params.platformAppList]
+ * @param {Object} [params.cleanup]
+ * @param {boolean} [params.upPlatformForce]
+ * @param {boolean} [params.omitInfraSection]
+ * @returns {Promise<void>}
+ */
+async function recordInfraInstallationCommand(params) {
+  const {
+    command,
+    options,
+    startedAt,
+    outcome,
+    error,
+    platformAppList,
+    cleanup,
+    upPlatformForce,
+    omitInfraSection
+  } = params;
+
+  const completedAt = new Date();
+  let cfg = {};
+  try {
+    cfg = await config.getConfig();
+  } catch {
+    cfg = {};
+  }
+
+  try {
+    await installationLog.appendInstallationRecord({
+      command,
+      outcome,
+      startedAt,
+      completedAt,
+      options,
+      infra: !omitInfraSection && cfg ? { cfg, options } : undefined,
+      platformAppList,
+      cleanup,
+      upPlatformForce: upPlatformForce === true,
+      configExtra: {
+        controllerUrl: await installationLog.resolveControllerUrlForLog(),
+        adminEmail: await installationLog.resolveAdminEmailPresence()
+      },
+      error,
+      errorCode: error && error.code ? String(error.code) : undefined
+    });
+  } catch {
+    // never block CLI on log failure
+  }
+}
+
+module.exports = {
+  recordInfraInstallationCommand
+};

package/lib/cli/setup-app.js

@@ -31,6 +31,19 @@ Example:
   $ aifabrix push myapp -t v1.0.0
 `;
 
+const LOGS_HELP_AFTER = `
+Examples:
+  $ aifabrix logs miso-controller -l error
+  $ aifabrix logs miso-controller -f
+  $ aifabrix logs dataplane -l warn
+  $ aifabrix logs dataplane -f -t 100
+  $ aifabrix logs keycloak -f -t 0
+
+Notes:
+  - Platform apps use names such as miso-controller, dataplane, keycloak (see aifabrix run).
+  - Use -t 0 (--tail 0) for the full buffered log; default is 100 lines.
+`;
+
 /**
  * Normalize options for external system creation
  * @param {Object} options - Raw CLI options
@@ -188,19 +201,31 @@ See integration/hubspot-test/wizard-hubspot-e2e.yaml for an example.`;
 
 function registerRunCommand(program) {
   const runHelp = `
-In dev: use --reload for sync and mount (requires remote server with Mutagen, or local Docker).
+In dev: use --reload for live code in the container. Before start, the CLI prints a "Reload (dev)" section: direct bind mount when the Docker engine is on this machine, or Mutagen when the engine is remote.
 Examples:
   $ aifabrix run myapp
   $ aifabrix run myapp --env tst
   $ aifabrix run myapp --tag v1.0.0
-  $ aifabrix run myapp --reload`;
+  $ 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')
     .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')
     .option('-e, --env <env>', 'Environment: dev (default), tst, or pro', 'dev')
-    .option('--reload', 'In dev: use sync and mount (requires remote server; Mutagen or local Docker)')
+    .option('--base', 'Use manifest base image only (skip local developer-scoped tag preference)')
+    .option('--reload', 'In dev: mount workspace into container (Mutagen only if docker-endpoint is a remote host)')
+    .option(
+      '--proxy',
+      'Use Traefik/front-door public URL hints when infra has Traefik and application.yaml enables frontDoorRouting (default: on)',
+      true
+    )
+    .option(
+      '--no-proxy',
+      'Docker declarative public url://* use localhost + published port (saves applications.<app>.proxy: false); overrides --proxy'
+    )
     .addHelpText('after', runHelp)
     .action(async(appName, options) => {
       try {
@@ -219,6 +244,7 @@ function setupBuildRunLogsDownCommands(program) {
     .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.')
+    .option('--base', 'Also tag the manifest base image name (after developer-scoped build when developer id > 0)')
     .action(async(appName, options) => {
       try {
         const imageTag = await app.buildApp(appName, options);
@@ -236,6 +262,7 @@ function setupBuildRunLogsDownCommands(program) {
     .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)')
+    .addHelpText('after', LOGS_HELP_AFTER)
     .action(async(appName, options) => {
       try {
         const { runAppLogs } = require('../commands/app-logs');
@@ -328,6 +355,7 @@ function setupPushDeployDockerfileCommands(program) {
     .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('--repository-url <url>', 'Repository URL for pipeline validation (default: application.yaml repository.repositoryUrl, else https://github.com/aifabrix/<appKey>)')
     .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')