@aifabrix/builder 2.40.0 → 2.41.0

package/lib/app/run-helpers.js

@@ -17,8 +17,6 @@ const { exec } = require('child_process');
 const { loadConfigFile } = require('../utils/config-format');
 const { promisify } = require('util');
 const validator = require('../validation/validator');
-const infra = require('../infrastructure');
-const secrets = require('../core/secrets');
 const config = require('../core/config');
 const buildCopy = require('../utils/build-copy');
 const logger = require('../utils/logger');
@@ -27,7 +25,10 @@ const composeGenerator = require('../utils/compose-generator');
 const dockerUtils = require('../utils/docker');
 const containerHelpers = require('../utils/app-run-containers');
 const pathsUtil = require('../utils/paths');
+const runEnvCompose = require('./run-env-compose');
+const { resolveEnvOutputPath, writeEnvOutputForReload, writeEnvOutputForLocal } = require('../utils/env-copy');
 const { resolveVersionForApp } = require('../utils/image-version');
+const { parseImageOverride } = require('../utils/parse-image-ref');
 
 const execAsync = promisify(exec);
 
@@ -160,6 +161,28 @@ async function resolveAndUpdateVersion(appName, appConfig, debug) {
   }
 }
 
+/**
+ * Resolve image name and tag from app config and optional run override.
+ * @param {string} appName - Application name
+ * @param {Object} appConfig - Application configuration
+ * @param {Object} runOptions - Run options; runOptions.image overrides config
+ * @returns {{ imageName: string, imageTag: string }} imageName and imageTag
+ */
+function resolveRunImage(appName, appConfig, runOptions) {
+  const imageOverride = runOptions && runOptions.image;
+  if (imageOverride) {
+    const parsed = parseImageOverride(imageOverride);
+    return {
+      imageName: parsed ? parsed.name : composeGenerator.getImageName(appConfig, appName),
+      imageTag: parsed ? parsed.tag : (appConfig.image && appConfig.image.tag) || 'latest'
+    };
+  }
+  return {
+    imageName: composeGenerator.getImageName(appConfig, appName),
+    imageTag: (appConfig.image && appConfig.image.tag) || 'latest'
+  };
+}
+
 /**
  * Checks prerequisites: Docker image and (optionally) infrastructure
  * @async
@@ -167,11 +190,11 @@ async function resolveAndUpdateVersion(appName, appConfig, debug) {
  * @param {Object} appConfig - Application configuration
  * @param {boolean} [debug=false] - Enable debug logging
  * @param {boolean} [skipInfraCheck=false] - When true, skip infra health check (e.g. when caller already verified, e.g. up-miso)
+ * @param {Object} [runOptions] - Run options; when runOptions.image is set, that image is checked instead of config-derived
  * @throws {Error} If prerequisites are not met
  */
-async function checkPrerequisites(appName, appConfig, debug = false, skipInfraCheck = false) {
-  const imageName = composeGenerator.getImageName(appConfig, appName);
-  const imageTag = appConfig.image?.tag || 'latest';
+async function checkPrerequisites(appName, appConfig, debug = false, skipInfraCheck = false, runOptions = {}) {
+  const { imageName, imageTag } = resolveRunImage(appName, appConfig, runOptions);
   const fullImageName = `${imageName}:${imageTag}`;
 
   if (debug) {
@@ -181,7 +204,11 @@ async function checkPrerequisites(appName, appConfig, debug = false, skipInfraCh
   logger.log(chalk.blue(`Checking if image ${fullImageName} exists...`));
   const imageExists = await checkImageExists(imageName, imageTag, debug);
   if (!imageExists) {
-    throw new Error(`Docker image ${fullImageName} not found\nRun 'aifabrix build ${appName}' first`);
+    const isTemplateApp = TEMPLATE_APP_KEYS.includes(appName);
+    const hint = isTemplateApp
+      ? `Pull the image (e.g. docker pull ${fullImageName}) or use --image ${appName}=<image> for up-miso/up-dataplane.`
+      : `Run 'aifabrix build ${appName}' first`;
+    throw new Error(`Docker image ${fullImageName} not found\n${hint}`);
   }
   logger.log(chalk.green(`✓ Image ${fullImageName} found`));
 
@@ -200,6 +227,7 @@ async function checkPrerequisites(appName, appConfig, debug = false, skipInfraCh
  */
 async function checkInfraHealthOrThrow(debug) {
   logger.log(chalk.blue('Checking infrastructure health...'));
+  const infra = require('../infrastructure');
   const infraHealth = await infra.checkInfraHealth();
   if (debug) {
     logger.log(chalk.gray(`[DEBUG] Infrastructure health: ${JSON.stringify(infraHealth, null, 2)}`));
@@ -230,73 +258,20 @@ async function ensureDevDirectory(appName, developerId) {
 }
 
 /**
- * Generate or update .env file for Docker
- * @async
- * @param {string} appName - Application name
- * @param {string} builderEnvPath - Path to builder .env file
- * @param {boolean} [skipOutputPath=false] - When true, skip copying to envOutputPath (e.g. up-miso/up-dataplane, no local code)
- */
-async function ensureEnvFile(appName, builderEnvPath, skipOutputPath = false) {
-  if (!fsSync.existsSync(builderEnvPath)) {
-    logger.log(chalk.yellow('Generating .env file from template...'));
-    await secrets.generateEnvFile(appName, null, 'docker', false, skipOutputPath);
-  } else {
-    logger.log(chalk.blue('Updating .env file for Docker environment...'));
-    await secrets.generateEnvFile(appName, null, 'docker', false, skipOutputPath);
-  }
-}
-
-/**
- * Copy .env file to dev directory
- * @async
- * @param {string} builderEnvPath - Path to builder .env file
- * @param {string} devEnvPath - Path to dev .env file
- */
-async function copyEnvToDev(builderEnvPath, devEnvPath) {
-  if (fsSync.existsSync(builderEnvPath)) {
-    await fs.copyFile(builderEnvPath, devEnvPath);
-  }
-}
-
-/**
- * Handle envOutputPath configuration
- * @async
- * @param {string} appName - Application name
- * @param {string} configPath - Path to application config file
- * @param {string} builderEnvPath - Path to builder .env file
- * @param {string} devEnvPath - Path to dev .env file
- * @param {boolean} [skipOutputPath=false] - When true, skip (e.g. up-miso/up-dataplane, no local code)
- */
-async function handleEnvOutputPath(appName, configPath, builderEnvPath, devEnvPath, skipOutputPath = false) {
-  if (skipOutputPath) {
-    return;
-  }
-  let variables;
-  try {
-    variables = loadConfigFile(configPath);
-  } catch {
-    return;
-  }
-
-  if (variables?.build?.envOutputPath && variables.build.envOutputPath !== null) {
-    logger.log(chalk.blue('Ensuring .env file in apps/ directory is updated for Docker...'));
-    await secrets.generateEnvFile(appName, null, 'docker');
-    await copyEnvToDev(builderEnvPath, devEnvPath);
-  }
-}
-
-/**
- * Calculate compose port from options or app config
- * @param {Object} options - Run options
+ * Calculate host port for docker-compose mapping (first port in "host:container").
+ * Uses application.yaml top-level port (not localPort). Second port is always containerPort from config.
+ * Example: keycloak port 8082, containerPort 8080 → "8082:8080"; miso-controller port 3000 → "3000:3000".
+ *
+ * @param {Object} options - Run options (may include port override)
  * @param {Object} appConfig - Application configuration
  * @param {string} developerId - Developer ID
- * @returns {number} Port number
+ * @returns {number} Host port number
  */
 function calculateComposePort(options, appConfig, developerId) {
   if (options.port) {
     return options.port;
   }
-  const basePort = appConfig.port || 3000;
+  const basePort = appConfig.port ?? 3000;
   const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
   return idNum === 0 ? basePort : basePort + (idNum * 100);
 }
@@ -313,84 +288,104 @@ function calculateComposePort(options, appConfig, developerId) {
 async function generateComposeFile(appName, appConfig, composeOptions, devDir) {
   logger.log(chalk.blue('Generating Docker Compose configuration...'));
   const composeContent = await composeGenerator.generateDockerCompose(appName, appConfig, composeOptions);
+  runEnvCompose.assertNoPasswordLiteralsInCompose(composeContent);
   const tempComposePath = path.join(devDir, 'docker-compose.yaml');
   await fs.writeFile(tempComposePath, composeContent);
   return tempComposePath;
 }
 
 /**
- * Prepares environment: ensures .env file and generates Docker Compose
+ * Writes .env to envOutputPath when application.yaml build.envOutputPath is set.
  * @async
  * @param {string} appName - Application name
  * @param {Object} appConfig - Application configuration
- * @param {Object} options - Run options
- * @returns {Promise<string>} Path to generated compose file
+ * @param {string} runEnvPath - Path to .env.run
+ * @param {Object} options - Run options (reload flag)
+ */
+async function writeEnvOutputIfConfigured(appName, appConfig, runEnvPath, options) {
+  if (options && options.skipEnvOutputPath === true) return;
+  const envOutputPathRaw = appConfig.build?.envOutputPath;
+  if (!envOutputPathRaw || typeof envOutputPathRaw !== 'string' || envOutputPathRaw.trim() === '') {
+    return;
+  }
+  const configPath = path.join(pathsUtil.getBuilderPath(appName), 'application.yaml');
+  const outputPath = resolveEnvOutputPath(envOutputPathRaw.trim(), configPath);
+  const outputDir = path.dirname(outputPath);
+  if (!fsSync.existsSync(outputDir)) {
+    await fs.mkdir(outputDir, { recursive: true });
+  }
+  if (options.reload) {
+    await writeEnvOutputForReload(outputPath, runEnvPath);
+  } else {
+    await writeEnvOutputForLocal(appName, outputPath);
+  }
+}
+
+/**
+ * Prepares environment: clean applications dir, build two .env files (app-only + start-only), generate Docker Compose.
+ * .env.run = app container only (no admin secrets). .env.run.admin = db-init/start only (POSTGRES_PASSWORD etc.), deleted after run.
+ *
+ * @async
+ * @param {string} appName - Application name
+ * @param {Object} appConfig - Application configuration
+ * @param {Object} options - Run options (may include envFilePath, devMountPath from caller)
+ * @returns {Promise<{ composePath: string, runEnvPath: string, runEnvAdminPath: string }>} Paths to compose and both run .env files (delete after success)
  */
 async function prepareEnvironment(appName, appConfig, options) {
   const developerId = await config.getDeveloperId();
   const devDir = await ensureDevDirectory(appName, developerId);
-  const skipEnvOutputPath = options.skipEnvOutputPath === true;
 
-  // Generate/update .env file (respect AIFABRIX_BUILDER_DIR when set by up-miso/up-dataplane)
-  const builderEnvPath = path.join(pathsUtil.getBuilderPath(appName), '.env');
-  await ensureEnvFile(appName, builderEnvPath, skipEnvOutputPath);
+  runEnvCompose.cleanApplicationsDir(developerId);
+  logger.log(chalk.blue('Building merged .env (admin + app secrets)...'));
+  const { runEnvPath, runEnvAdminPath } = await runEnvCompose.buildMergedRunEnvAndWrite(appName, appConfig, devDir);
 
-  // Copy .env to dev directory
-  const devEnvPath = path.join(devDir, '.env');
-  await copyEnvToDev(builderEnvPath, devEnvPath);
+  const composeOptions = {
+    ...options,
+    envFilePath: runEnvPath,
+    dbInitEnvFilePath: runEnvAdminPath
+  };
+  composeOptions.port = calculateComposePort(composeOptions, appConfig, developerId);
+  const composePath = await generateComposeFile(appName, appConfig, composeOptions, devDir);
 
-  // Handle envOutputPath if configured (skipped when skipEnvOutputPath e.g. up-miso/up-dataplane)
-  let configPath;
-  try {
-    configPath = pathsUtil.resolveApplicationConfigPath(devDir);
-  } catch {
-    configPath = null;
-  }
-  if (configPath) {
-    await handleEnvOutputPath(appName, configPath, builderEnvPath, devEnvPath, skipEnvOutputPath);
-  }
+  await writeEnvOutputIfConfigured(appName, appConfig, runEnvPath, options);
 
-  // Generate Docker Compose
-  const composeOptions = { ...options };
-  composeOptions.port = calculateComposePort(composeOptions, appConfig, developerId);
-  return await generateComposeFile(appName, appConfig, composeOptions, devDir);
+  return { composePath, runEnvPath, runEnvAdminPath };
 }
 
 /**
- * Prepare environment variables from admin secrets
+ * Prepare environment variables for docker compose (no secrets in host env; compose uses env_file).
  * @async
  * @param {boolean} debug - Enable debug logging
- * @returns {Promise<Object>} Environment variables object
+ * @returns {Promise<Object>} Environment variables object for child process
  */
 async function prepareContainerEnv(debug) {
-  const adminSecretsPath = await infra.ensureAdminSecrets();
-  if (debug) {
-    logger.log(chalk.gray(`[DEBUG] Admin secrets path: ${adminSecretsPath}`));
-  }
+  const env = { ...process.env };
 
-  const adminSecretsContent = fsSync.readFileSync(adminSecretsPath, 'utf8');
-  const postgresPasswordMatch = adminSecretsContent.match(/^POSTGRES_PASSWORD=(.+)$/m);
-  const postgresPassword = postgresPasswordMatch ? postgresPasswordMatch[1] : '';
+  if (typeof process.getuid === 'function' && typeof process.getgid === 'function') {
+    env.AIFABRIX_UID = String(process.getuid());
+    env.AIFABRIX_GID = String(process.getgid());
+  } else {
+    env.AIFABRIX_UID = '1000';
+    env.AIFABRIX_GID = '1000';
+  }
 
-  const env = {
-    ...process.env,
-    ADMIN_SECRETS_PATH: adminSecretsPath,
-    POSTGRES_PASSWORD: postgresPassword
-  };
+  const { getRemoteDockerEnv } = require('../utils/remote-docker-env');
+  const remoteDocker = await getRemoteDockerEnv();
+  Object.assign(env, remoteDocker);
 
   if (debug) {
-    logger.log(chalk.gray(`[DEBUG] Environment variables: ADMIN_SECRETS_PATH=${adminSecretsPath}, POSTGRES_PASSWORD=${postgresPassword ? '***' : '(not set)'}`));
+    logger.log(chalk.gray('[DEBUG] Container env prepared (secrets via env_file)'));
   }
 
   return env;
 }
 
 /**
- * Execute docker-compose up command
+ * Execute docker-compose up command. Services get env from env_file in the compose (e.g. .env.run).
  * @async
  * @param {string} composeCmdBase - Base compose command
  * @param {string} composePath - Path to compose file
- * @param {Object} env - Environment variables
+ * @param {Object} env - Environment variables for the child process
  * @param {boolean} debug - Enable debug logging
  */
 async function executeComposeUp(composeCmdBase, composePath, env, debug) {
@@ -403,37 +398,44 @@ async function executeComposeUp(composeCmdBase, composePath, env, debug) {
 }
 
 /**
- * Starts the container and waits for health check
+ * Starts the container and waits for health check. Deletes run .env files after success (ISO 27K).
  * @async
  * @param {string} appName - Application name
  * @param {string} composePath - Path to Docker Compose file
  * @param {number} port - Application port
  * @param {Object} appConfig - Application configuration
- * @param {boolean} [debug=false] - Enable debug logging
+ * @param {Object} [opts] - Options
+ * @param {boolean} [opts.debug=false] - Enable debug logging
+ * @param {string|null} [opts.runEnvPath=null] - Path to .env.run (app-only) to delete after successful start
+ * @param {string|null} [opts.runEnvAdminPath=null] - Path to .env.run.admin (start-only) to delete after successful start
  * @throws {Error} If container fails to start or become healthy
  */
-async function startContainer(appName, composePath, port, appConfig = null, debug = false) {
+async function startContainer(appName, composePath, port, appConfig = null, opts = {}) {
+  const { debug = false, runEnvPath = null, runEnvAdminPath = null } = opts;
   logger.log(chalk.blue(`Starting ${appName}...`));
 
-  // Ensure Docker + Compose available and determine correct compose command
   const composeCmdBase = await dockerUtils.ensureDockerAndCompose().then(() => dockerUtils.getComposeCommand());
-
-  // Prepare environment variables
   const env = await prepareContainerEnv(debug);
-
-  // Execute compose up
   await executeComposeUp(composeCmdBase, composePath, env, debug);
 
-  // Get container name and log status
   const idNum = typeof appConfig.developerId === 'string' ? parseInt(appConfig.developerId, 10) : appConfig.developerId;
   const containerName = idNum === 0 ? `aifabrix-${appName}` : `aifabrix-dev${appConfig.developerId}-${appName}`;
   logger.log(chalk.green(`✓ Container ${containerName} started`));
   await containerHelpers.logContainerStatus(containerName, debug);
 
-  // Wait for health check
   const healthCheckPath = appConfig?.healthCheck?.path || '/health';
   logger.log(chalk.blue(`Waiting for application to be healthy at http://localhost:${port}${healthCheckPath}...`));
   await waitForHealthCheck(appName, 90, port, appConfig, debug);
+
+  for (const p of [runEnvPath, runEnvAdminPath]) {
+    if (p && typeof p === 'string') {
+      try {
+        await fs.unlink(p);
+      } catch (err) {
+        if (err.code !== 'ENOENT') logger.log(chalk.yellow(`Warning: could not remove run .env: ${err.message}`));
+      }
+    }
+  }
 }
 
 /**
@@ -461,6 +463,7 @@ module.exports = {
   checkPrerequisites,
   prepareEnvironment,
   startContainer,
-  displayRunStatus
+  displayRunStatus,
+  cleanApplicationsDir: runEnvCompose.cleanApplicationsDir
 };
 

package/lib/app/run.js

@@ -14,14 +14,50 @@ const { exec } = require('child_process');
 const { promisify } = require('util');
 const config = require('../core/config');
 const logger = require('../utils/logger');
+const pathsUtil = require('../utils/paths');
 const { checkPortAvailable, waitForHealthCheck } = require('../utils/health-check');
 const composeGenerator = require('../utils/compose-generator');
 const containerHelpers = require('../utils/app-run-containers');
+const mutagen = require('../utils/mutagen');
 // Helper functions extracted to reduce file size and complexity
 const helpers = require('./run-helpers');
 
 const execAsync = promisify(exec);
 
+/**
+ * True if host is localhost or 127.0.0.1 (case-insensitive).
+ * @param {string} host - Hostname or empty
+ * @returns {boolean}
+ */
+function isLocalhostHost(host) {
+  if (!host || typeof host !== 'string') return false;
+  const h = host.trim().toLowerCase();
+  return h === 'localhost' || h === '127.0.0.1';
+}
+
+/**
+ * True if the given URL or endpoint string refers to localhost (host is localhost or 127.0.0.1).
+ * Handles tcp://localhost:2376, https://127.0.0.1:8443, etc.
+ * @param {string} urlOrEndpoint - URL (e.g. https://localhost:8443) or Docker endpoint (e.g. tcp://localhost:2376)
+ * @returns {boolean}
+ */
+function isLocalhostEndpoint(urlOrEndpoint) {
+  if (!urlOrEndpoint || typeof urlOrEndpoint !== 'string') return false;
+  const s = urlOrEndpoint.trim();
+  if (!s) return false;
+  try {
+    if (s.startsWith('tcp://') || s.startsWith('unix://')) {
+      const rest = s.replace(/^tcp:\/\//i, '').replace(/^unix:\/\//i, '');
+      const host = rest.split('/')[0].split(':')[0];
+      return isLocalhostHost(host);
+    }
+    const u = new URL(s);
+    return isLocalhostHost(u.hostname);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Validate app for run and check if it's an external system
  * @async
@@ -106,6 +142,48 @@ async function calculateHostPort(appConfig, options, debug) {
   return hostPort;
 }
 
+/**
+ * When run --reload in dev with remote: ensure Mutagen sync session; return remote path for compose mount.
+ * Uses codePath (resolved build.context) as Mutagen local path so one config field drives both local and remote.
+ * When Docker endpoint, remote-server, or sync-ssh-host is localhost/127.0.0.1, returns null (no sync; use local path).
+ *
+ * @param {string} appName - Application name
+ * @param {string} developerId - Developer ID
+ * @param {boolean} debug - Debug flag
+ * @param {string} codePath - Resolved build.context (absolute path to app code)
+ * @param {string} [remoteSyncPath] - Optional relative path under user-mutagen-folder (from build.remoteSyncPath); when unset, defaults to dev/<appKey>
+ * @returns {Promise<string|null>} Remote path for -v mount or null if not remote/reload or already on server (localhost)
+ * @throws {Error} If --reload but remote not configured, or Mutagen install fails
+ */
+async function ensureReloadSync(appName, developerId, debug, codePath, remoteSyncPath) {
+  const endpoint = await config.getDockerEndpoint();
+  const serverUrl = await config.getRemoteServer();
+  if (!endpoint && !serverUrl) return null;
+  const syncSshHost = await config.getSyncSshHost();
+  if (isLocalhostEndpoint(endpoint) || isLocalhostEndpoint(serverUrl) || isLocalhostHost(syncSshHost || '')) {
+    if (debug) logger.log(chalk.gray('[DEBUG] Docker/remote/sync host is localhost; skipping Mutagen, using local path'));
+    return null;
+  }
+  const [userMutagenFolder, syncSshUser] = await Promise.all([
+    config.getUserMutagenFolder(),
+    config.getSyncSshUser()
+  ]);
+  if (!userMutagenFolder || !syncSshUser || !syncSshHost) {
+    throw new Error(
+      'run --reload requires remote server sync settings. Run "aifabrix dev init" or set user-mutagen-folder, sync-ssh-user, sync-ssh-host in config.'
+    );
+  }
+  const mutagenPath = await mutagen.ensureMutagenPath(logger.log);
+  const remotePath = mutagen.getRemotePath(userMutagenFolder, appName, remoteSyncPath);
+  const sshUrl = mutagen.getSyncSshUrl(syncSshUser, syncSshHost, remotePath);
+  const sessionName = mutagen.getSessionName(developerId, appName);
+  const localPath = (codePath && typeof codePath === 'string') ? codePath : pathsUtil.getBuilderPath(appName);
+  if (debug) logger.log(chalk.gray(`[DEBUG] Mutagen sync: ${sessionName} ${localPath} <-> ${sshUrl}`));
+  logger.log(chalk.blue('Ensuring Mutagen sync session...'));
+  await mutagen.ensureSyncSession(mutagenPath, sessionName, localPath, sshUrl);
+  return remotePath;
+}
+
 /**
  * Load and configure application
  * @async
@@ -132,16 +210,20 @@ async function loadAndConfigureApp(appName, debug) {
  * @param {string} tempComposePath - Path to compose file
  * @param {number} hostPort - Host port
  * @param {Object} appConfig - Application configuration
- * @param {boolean} debug - Debug flag
+ * @param {Object} opts - Options (debug, runEnvPath, runEnvAdminPath)
  * @throws {Error} If container start fails
  */
-async function startAppContainer(appName, tempComposePath, hostPort, appConfig, debug) {
+async function startAppContainer(appName, tempComposePath, hostPort, appConfig, opts) {
+  const { debug, runEnvPath = null, runEnvAdminPath = null } = opts;
   try {
-    await helpers.startContainer(appName, tempComposePath, hostPort, appConfig, debug);
+    await helpers.startContainer(appName, tempComposePath, hostPort, appConfig, { debug, runEnvPath, runEnvAdminPath });
     await helpers.displayRunStatus(appName, hostPort, appConfig);
   } catch (error) {
     logger.log(chalk.yellow(`\n⚠️  Compose file preserved at: ${tempComposePath}`));
     logger.log(chalk.yellow('   Review the file to debug issues'));
+    if (runEnvPath || runEnvAdminPath) {
+      logger.log(chalk.yellow('   Run .env file(s) (contain secrets) were not deleted; remove them manually if desired.'));
+    }
     if (debug) {
       logger.log(chalk.gray(`[DEBUG] Error during container start: ${error.message}`));
     }
@@ -149,6 +231,54 @@ async function startAppContainer(appName, tempComposePath, hostPort, appConfig,
   }
 }
 
+/**
+ * Resolve run options (paths and optional reload sync) for prepareAppRun.
+ * @param {string} appName - Application name
+ * @param {Object} appConfig - Application configuration
+ * @param {Object} options - Run options
+ * @param {string} envKey - Environment key (dev/tst/pro)
+ * @param {boolean} debug - Debug flag
+ * @returns {Promise<Object>} Run options with optional devMountPath
+ */
+async function resolveRunOptions(appName, appConfig, options, envKey, debug) {
+  const runOptions = { ...options, env: envKey };
+  const builderPath = pathsUtil.getBuilderPath(appName);
+  const codePath = pathsUtil.resolveBuildContext(builderPath, appConfig.build?.context || '.');
+  if (options.reload && envKey === 'dev') {
+    const remoteSyncPath = appConfig.build?.remoteSyncPath;
+    const remotePath = await ensureReloadSync(appName, appConfig.developerId, debug, codePath, remoteSyncPath);
+    runOptions.devMountPath = remotePath || codePath;
+  }
+  return runOptions;
+}
+
+/**
+ * Prepare run: validate app, load config, check prereqs, stop existing container, resolve port and reload, prepare env.
+ * @param {string} appName - Application name
+ * @param {Object} options - Run options
+ * @param {boolean} debug - Debug flag
+ * @returns {Promise<{ appConfig: Object, tempComposePath: string, hostPort: number }|null>} Prepared run context or null if should not continue
+ */
+async function prepareAppRun(appName, options, debug) {
+  const envKey = (options.env || 'dev').toLowerCase();
+  if (envKey !== 'dev' && envKey !== 'tst' && envKey !== 'pro') {
+    throw new Error('--env must be dev, tst, or pro');
+  }
+  const shouldContinue = await validateAppForRun(appName, debug);
+  if (!shouldContinue) {
+    return null;
+  }
+  const appConfig = await loadAndConfigureApp(appName, debug);
+  await helpers.checkPrerequisites(appName, appConfig, debug, options.skipInfraCheck === true, options);
+  await checkAndStopContainer(appName, appConfig.developerId, debug);
+  const hostPort = await calculateHostPort(appConfig, options, debug);
+  const runOptions = await resolveRunOptions(appName, appConfig, options, envKey, debug);
+  const { composePath: tempComposePath, runEnvPath, runEnvAdminPath } = await helpers.prepareEnvironment(appName, appConfig, runOptions);
+  const result = { appConfig, tempComposePath, hostPort, runEnvPath, runEnvAdminPath };
+  if (runOptions.devMountPath) result.devMountPath = runOptions.devMountPath;
+  return result;
+}
+
 /**
  * Runs the application locally using Docker
  * Starts container with proper port mapping and environment
@@ -168,40 +298,27 @@ async function startAppContainer(appName, tempComposePath, hostPort, appConfig,
  */
 async function runApp(appName, options = {}) {
   const debug = options.debug || false;
-
   if (debug) {
     logger.log(chalk.gray(`[DEBUG] Starting run process for: ${appName}`));
     logger.log(chalk.gray(`[DEBUG] Options: ${JSON.stringify(options, null, 2)}`));
   }
-
   try {
-    // Validate app for run and check if external
-    const shouldContinue = await validateAppForRun(appName, debug);
-    if (!shouldContinue) {
+    const prepared = await prepareAppRun(appName, options, debug);
+    if (!prepared) {
       return;
     }
-
-    // Load and configure application
-    const appConfig = await loadAndConfigureApp(appName, debug);
-
-    // Check prerequisites: image and (unless skipped) infrastructure
-    await helpers.checkPrerequisites(appName, appConfig, debug, options.skipInfraCheck === true);
-
-    // Check if container is already running and stop it if needed
-    await checkAndStopContainer(appName, appConfig.developerId, debug);
-
-    // Calculate host port and validate it's available
-    const hostPort = await calculateHostPort(appConfig, options, debug);
-
-    // Prepare environment: ensure .env file and generate Docker Compose
-    const tempComposePath = await helpers.prepareEnvironment(appName, appConfig, options);
     if (debug) {
-      logger.log(chalk.gray(`[DEBUG] Compose file generated: ${tempComposePath}`));
+      logger.log(chalk.gray(`[DEBUG] Compose file generated: ${prepared.tempComposePath}`));
     }
-
-    // Start container and display status
-    await startAppContainer(appName, tempComposePath, hostPort, appConfig, debug);
-
+    if (options.reload && prepared.devMountPath) {
+      logger.log(chalk.gray('With --reload: workspace mounted from host at /app (container runs as your user for write access).'));
+      logger.log(chalk.gray(`  Host path: ${prepared.devMountPath}`));
+    }
+    await startAppContainer(appName, prepared.tempComposePath, prepared.hostPort, prepared.appConfig, {
+      debug,
+      runEnvPath: prepared.runEnvPath,
+      runEnvAdminPath: prepared.runEnvAdminPath
+    });
   } catch (error) {
     if (debug) {
       logger.log(chalk.gray(`[DEBUG] Run failed: ${error.message}`));
@@ -243,6 +360,9 @@ async function restartApp(appName) {
 module.exports = {
   runApp,
   restartApp,
+  ensureReloadSync,
+  isLocalhostHost,
+  isLocalhostEndpoint,
   checkImageExists: helpers.checkImageExists,
   checkContainerRunning: helpers.checkContainerRunning,
   stopAndRemoveContainer: helpers.stopAndRemoveContainer,

package/lib/app/show.js

@@ -171,7 +171,9 @@ function healthStrFromVariables(variables) {
 function buildStrFromVariables(variables) {
   const build = variables.build;
   if (!build) return '—';
-  return `${build.language || '—'}, localPort ${build.localPort || '—'}`;
+  const port = variables.port ?? build.containerPort;
+  const portStr = (port !== undefined && port !== null) ? `port ${port}` : '';
+  return [build.language || '—', portStr].filter(Boolean).join(', ') || '—';
 }
 
 function buildApplicationFromVariables(variables) {
@@ -438,7 +440,8 @@ function formatBuildForDisplay(build) {
   if (!build) return '—';
   const parts = [];
   if (build.language) parts.push(build.language);
-  if (build.localPort !== undefined && build.localPort !== null) parts.push(`localPort ${build.localPort}`);
+  const port = build.port ?? build.localPort;
+  if (port !== undefined && port !== null) parts.push(`port ${port}`);
   if (build.dockerfile) parts.push('dockerfile');
   if (build.envOutputPath) parts.push(`envOutputPath: ${build.envOutputPath}`);
   return parts.length ? parts.join(', ') : '—';

package/lib/build/index.js

@@ -26,6 +26,7 @@ const dockerBuild = require('../utils/docker-build');
 const buildCopy = require('../utils/build-copy');
 const { buildDevImageName } = require('../utils/image-name');
 const buildHelpers = require('../utils/build-helpers');
+const secretsEnvWrite = require('../core/secrets-env-write');
 
 /**
  * Loads application config for an application
@@ -410,11 +411,18 @@ async function buildApp(appName, options = {}) {
       appConfig
     }, options, buildHelpers);
 
-    // 5. Execute Docker build
+    // 5. Resolve NPM_TOKEN/PYPI_TOKEN for private registries and pass as build-args
+    const envMap = await secretsEnvWrite.resolveAndGetEnvMap(appName, { environment: 'docker' });
+    const buildArgs = {};
+    if (envMap.NPM_TOKEN) buildArgs.NPM_TOKEN = envMap.NPM_TOKEN;
+    if (envMap.PYPI_TOKEN) buildArgs.PYPI_TOKEN = envMap.PYPI_TOKEN;
+    const buildOptions = { ...options, buildArgs };
+
+    // 6. Execute Docker build
     const tag = options.tag || 'latest';
-    await dockerBuild.executeDockerBuildWithTag(effectiveImageName, imageName, dockerfilePath, contextPath, tag, options);
+    await dockerBuild.executeDockerBuildWithTag(effectiveImageName, imageName, dockerfilePath, contextPath, tag, buildOptions);
 
-    // 6. Post-build tasks
+    // 7. Post-build tasks
     await postBuildTasks(appName, buildConfig);
 
     logger.log(chalk.green('\n✅ Build completed successfully!'));