@aifabrix/builder 2.42.1 → 2.44.0

package/lib/app/index.js

@@ -10,7 +10,7 @@
  */
 
 const fs = require('fs').promises;
-const { readExistingEnv } = require('../core/env-reader');
+const envReaderModule = require('../core/env-reader');
 const build = require('../build');
 const appRun = require('./run');
 const { promptForOptions } = require('./prompts');
@@ -34,6 +34,29 @@ const {
 const path = require('path');
 const secretsEnsure = require('../core/secrets-ensure');
 
+/**
+ * Ensures secrets from env.template. On EACCES (e.g. secrets path under a read-only tree), uses getPrimaryUserSecretsLocalPath().
+ * @param {string} envTemplatePath - Path to env.template
+ * @returns {Promise<void>}
+ */
+async function ensureSecretsFromNewAppEnvTemplate(envTemplatePath) {
+  try {
+    await secretsEnsure.ensureSecretsFromEnvTemplate(envTemplatePath, {});
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return;
+    }
+    if (err.code === 'EACCES' || (err.message && String(err.message).includes('EACCES'))) {
+      const { getPrimaryUserSecretsLocalPath } = require('../utils/paths');
+      await secretsEnsure.ensureSecretsFromEnvTemplate(envTemplatePath, {
+        preferredFilePath: getPrimaryUserSecretsLocalPath()
+      });
+      return;
+    }
+    throw err;
+  }
+}
+
 /**
  * Creates new application with scaffolded configuration files
  * Prompts for configuration options and generates builder/ folder structure
@@ -125,19 +148,15 @@ async function generateApplicationFiles(finalAppPath, appName, config, options)
   await fs.mkdir(finalAppPath, { recursive: true });
   await processTemplateFiles(options.template, finalAppPath, appName, options, config);
 
-  const existingEnv = await readExistingEnv(process.cwd());
+  const existingEnv = await envReaderModule.readExistingEnv(finalAppPath);
   const envConversionMessage = existingEnv
-    ? '\n✓ Found existing .env file - sensitive values will be converted to kv:// references'
+    ? '\n✔ Found existing .env file - sensitive values will be converted to kv:// references'
     : '';
 
   await generateConfigFiles(finalAppPath, appName, config, existingEnv);
 
   const envTemplatePath = path.join(finalAppPath, 'env.template');
-  try {
-    await secretsEnsure.ensureSecretsFromEnvTemplate(envTemplatePath, {});
-  } catch (err) {
-    if (err.code !== 'ENOENT') throw err;
-  }
+  await ensureSecretsFromNewAppEnvTemplate(envTemplatePath);
 
   // Generate external system files if type is external
   if (config.type === 'external') {

package/lib/app/list.js

@@ -1,3 +1,4 @@
+const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
 /**
  * AI Fabrix Builder - App List Command
  *
@@ -85,7 +86,7 @@ function extractApplications(response) {
     extractWrappedPaginatedItems(apiResponse);
 
   if (!applications) {
-    logger.error(chalk.red('❌ Invalid response: expected data array or items array'));
+    logger.error(formatBlockingError('Invalid response: expected data array or items array'));
     logger.error(chalk.gray('\nAPI response type:'), typeof apiResponse);
     logger.error(chalk.gray('API response:'), JSON.stringify(apiResponse, null, 2));
     logger.error(chalk.gray('\nFull response for debugging:'));
@@ -166,11 +167,11 @@ function displayApplications(applications, environment, controllerUrl) {
   applications.forEach((app) => {
     const isExternal = app.configuration?.type === 'external';
     const externalIcon = isExternal ? '🔗 ' : '';
-    const hasPipeline = app.configuration?.pipeline?.isActive ? '✓' : '✗';
+    const hasPipeline = app.configuration?.pipeline?.isActive ? '✔' : '✖';
     const urlAndPort = formatUrlAndPort(app);
     logger.log(`${externalIcon}${hasPipeline} ${chalk.cyan(app.key)} - ${app.displayName} (${app.status || 'unknown'})${urlAndPort}`);
   });
-  logger.log(chalk.gray('  To show details for an app: aifabrix app show <appKey>\n'));
+  logger.log(chalk.gray('  To show details for an app: aifabrix app show <app>\n'));
 }
 
 /**
@@ -246,7 +247,7 @@ async function getListAuthToken(controllerUrl, config) {
     const authResult = await tryGetTokenFromController(controllerUrl);
     if (!authResult || !authResult.token) {
       // No token found for explicitly provided controller URL
-      logger.error(chalk.red(`❌ No authentication token found for controller: ${controllerUrl}`));
+      logger.error(formatBlockingError(`No authentication token found for controller: ${controllerUrl}`));
       logger.error(chalk.gray('Please login to this controller using: aifabrix login'));
       process.exit(1);
       // Return to prevent further execution in tests where process.exit is mocked
@@ -300,7 +301,7 @@ async function listApplications(options = {}) {
 
   const controllerUrl = options.controller || (await resolveControllerUrl());
   if (!controllerUrl) {
-    logger.error(chalk.red('❌ Controller URL is required. Run "aifabrix login" to set the controller URL in config.yaml'));
+    logger.error(formatBlockingError('Controller URL is required. Run "aifabrix login" to set the controller URL in config.yaml'));
     process.exit(1);
     return;
   }
@@ -321,7 +322,7 @@ async function listApplications(options = {}) {
     const applications = handleListResponse(response, actualControllerUrl);
     displayApplications(applications, environment, actualControllerUrl);
   } catch (error) {
-    logger.error(chalk.red(`❌ Failed to list applications from controller: ${actualControllerUrl}`));
+    logger.error(formatBlockingError(`Failed to list applications from controller: ${actualControllerUrl}`));
     logger.error(chalk.gray(`Error: ${error.message}`));
     process.exit(1);
   }

package/lib/app/push.js

@@ -1,3 +1,4 @@
+const { formatSuccessLine, formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
 /**
  * Application Push Utilities
  *
@@ -143,7 +144,7 @@ async function validatePushConfig(registry, imageName, appName) {
  */
 async function authenticateWithRegistry(registry) {
   if (await pushUtils.checkACRAuthentication(registry)) {
-    logger.log(chalk.green(`✓ Already authenticated with ${registry}`));
+    logger.log(formatSuccessLine(`Already authenticated with ${registry}`));
   } else {
     await pushUtils.authenticateACR(registry);
   }
@@ -189,7 +190,7 @@ async function pushImageTags(imageName, registry, tags) {
  * @param {Array<string>} tags - Image tags
  */
 function displayPushResults(registry, imageName, tags) {
-  logger.log(chalk.green(`\n✓ Successfully pushed ${tags.length} tag(s) to ${registry}`));
+  logger.log(formatSuccessParagraph(`Successfully pushed ${tags.length} tag(s) to ${registry}`));
   logger.log(chalk.gray(`Image: ${registry}/${imageName}:*`));
   logger.log(chalk.gray(`Tags: ${tags.join(', ')}`));
 }
@@ -208,7 +209,7 @@ async function pushApp(appName, options = {}) {
   try {
     const { isExternal } = await detectAppType(appName);
     if (isExternal) {
-      logger.log(chalk.yellow('⚠️  External systems don\'t require Docker images. Skipping push...'));
+      logger.log(chalk.yellow('⚠  External systems don\'t require Docker images. Skipping push...'));
       return;
     }
   } catch (error) {

package/lib/app/register.js

@@ -1,3 +1,4 @@
+const { formatSuccessLine, formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
 /**
  * AI Fabrix Builder - App Register Command
  *
@@ -22,6 +23,8 @@ const {
 const { checkAuthentication } = require('../utils/app-register-auth');
 const { callRegisterApi } = require('../utils/app-register-api');
 const { displayRegistrationResults, getEnvironmentPrefix } = require('../utils/app-register-display');
+const pathsUtil = require('../utils/paths');
+const { refreshUrlsLocalRegistryFromBuilder } = require('../utils/urls-local-registry');
 
 /**
  * Build registration data payload from app configuration
@@ -62,8 +65,8 @@ function buildRegistrationData(appConfig, options) {
       registrationData.image = imageValue;
     }
 
-    // URL: always set when we have port so controller DB has it. Precedence: --url, variables (app.url, deployment.dataplaneUrl, deployment.appUrl), else http://localhost:{localPort|port}
-    const portForUrl = appConfig.localPort ?? appConfig.port;
+    // URL: default uses manifest listen port; host mapping uses url:// in env.template at resolve time
+    const portForUrl = appConfig.port;
     if (portForUrl) {
       registrationData.url = options.url || appConfig.url || `http://localhost:${portForUrl}`;
     }
@@ -97,15 +100,15 @@ async function saveLocalCredentials(responseData, apiUrl) {
     // Regenerate .env file with updated credentials
     try {
       await generateEnvFile(registeredAppKey, null, 'local');
-      logger.log(chalk.green('✓ .env file updated with new credentials'));
+      logger.log(formatSuccessLine('.env file updated with new credentials'));
     } catch (error) {
-      logger.warn(chalk.yellow(`⚠️  Could not regenerate .env file: ${error.message}`));
+      logger.warn(chalk.yellow(`⚠  Could not regenerate .env file: ${error.message}`));
     }
 
-    logger.log(chalk.green('\n✓ Credentials saved to ~/.aifabrix/secrets.local.yaml'));
-    logger.log(chalk.green('✓ env.template updated with MISO_CLIENTID, MISO_CLIENTSECRET, and MISO_CONTROLLER_URL\n'));
+    logger.log(formatSuccessParagraph('Credentials saved to ~/.aifabrix/secrets.local.yaml'));
+    logger.log(formatSuccessLine('env.template updated with MISO_CLIENTID, MISO_CLIENTSECRET, and MISO_CONTROLLER_URL\n'));
   } catch (error) {
-    logger.warn(chalk.yellow(`⚠️  Could not save credentials locally: ${error.message}`));
+    logger.warn(chalk.yellow(`⚠  Could not save credentials locally: ${error.message}`));
   }
 }
 
@@ -150,7 +153,9 @@ async function registerApplication(appKey, options = {}) {
   logger.log(chalk.blue('📋 Registering application...\n'));
 
   const { resolveControllerUrl } = require('../utils/controller-url');
-  const { resolveEnvironment } = require('../core/config');
+  const config = require('../core/config');
+  await config.ensureSecretsEncryptionKey();
+  const { resolveEnvironment } = config;
 
   // Load application config
   const { variables, created } = await loadVariablesYaml(appKey);
@@ -177,6 +182,12 @@ async function registerApplication(appKey, options = {}) {
     registrationData
   );
 
+  try {
+    refreshUrlsLocalRegistryFromBuilder(pathsUtil.getProjectRoot());
+  } catch (error) {
+    logger.warn(chalk.yellow(`⚠  Could not refresh URLs registry: ${error.message}`));
+  }
+
   // Save credentials and display results (pass display name we sent so output shows it when API returns key as displayName)
   await saveLocalCredentials(responseData, authConfig.apiUrl);
   displayRegistrationResults(responseData, authConfig.apiUrl, environment, registrationData.displayName);

package/lib/app/rotate-secret.js

@@ -1,3 +1,4 @@
+const { formatBlockingError, formatSuccessLine, formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
 /**
  * AI Fabrix Builder - App Rotate Secret Command
  *
@@ -70,7 +71,7 @@ function validateEnvironment(environment) {
 async function resolveControllerAndEnvironment() {
   const controllerUrl = await resolveControllerUrl();
   if (!controllerUrl) {
-    logger.error(chalk.red('❌ Controller URL is required. Run "aifabrix login" to set the controller URL in config.yaml'));
+    logger.error(formatBlockingError('Controller URL is required. Run "aifabrix login" to set the controller URL in config.yaml'));
     process.exit(1);
   }
   const environment = await resolveEnvironment();
@@ -135,7 +136,7 @@ function extractCredentials(response) {
  */
 function validateResponse(response) {
   if (!response.data || typeof response.data !== 'object') {
-    logger.error(chalk.red('❌ Invalid response: missing data'));
+    logger.error(formatBlockingError('Invalid response: missing data'));
     logger.error(chalk.gray('\nAPI response type:'), typeof response.data);
     logger.error(chalk.gray('API response:'), JSON.stringify(response.data, null, 2));
     logger.error(chalk.gray('\nFull response for debugging:'));
@@ -146,7 +147,7 @@ function validateResponse(response) {
   const result = extractCredentials(response);
 
   if (!result) {
-    logger.error(chalk.red('❌ Invalid response: missing or invalid credentials'));
+    logger.error(formatBlockingError('Invalid response: missing or invalid credentials'));
     logger.error(chalk.gray('\nAPI response type:'), typeof response.data);
     logger.error(chalk.gray('API response:'), JSON.stringify(response.data, null, 2));
     logger.error(chalk.gray('\nFull response for debugging:'));
@@ -166,7 +167,7 @@ function validateResponse(response) {
  * @param {string} [message] - Optional message from API
  */
 function displayRotationResults(appKey, environment, credentials, apiUrl, message) {
-  logger.log(chalk.green('✅ Secret rotated successfully!\n'));
+  logger.log(formatSuccessLine('Secret rotated successfully!\n'));
   logger.log(chalk.bold('📋 Application Details:'));
   logger.log(`   Key:         ${appKey}`);
   logger.log(`   Environment: ${environment}`);
@@ -206,7 +207,7 @@ async function getTokenFromUrl(controllerUrl) {
       };
     }
   } catch (error) {
-    logger.error(chalk.red(`❌ Failed to authenticate with controller: ${controllerUrl}`));
+    logger.error(formatBlockingError(`Failed to authenticate with controller: ${controllerUrl}`));
     logger.error(chalk.gray(`Error: ${error.message}`));
     process.exit(1);
   }
@@ -287,18 +288,18 @@ async function saveCredentialsLocally(appKey, credentials, actualControllerUrl)
       // Regenerate .env file with updated credentials
       try {
         await generateEnvFile(appKey, null, 'local');
-        logger.log(chalk.green('✓ .env file updated with new credentials'));
+        logger.log(formatSuccessLine('.env file updated with new credentials'));
       } catch (error) {
-        logger.warn(chalk.yellow(`⚠️  Could not regenerate .env file: ${error.message}`));
+        logger.warn(chalk.yellow(`⚠  Could not regenerate .env file: ${error.message}`));
       }
 
-      logger.log(chalk.green('\n✓ Credentials saved to ~/.aifabrix/secrets.local.yaml'));
-      logger.log(chalk.green('✓ env.template updated with MISO_CLIENTID, MISO_CLIENTSECRET, and MISO_CONTROLLER_URL\n'));
+      logger.log(formatSuccessParagraph('Credentials saved to ~/.aifabrix/secrets.local.yaml'));
+      logger.log(formatSuccessLine('env.template updated with MISO_CLIENTID, MISO_CLIENTSECRET, and MISO_CONTROLLER_URL\n'));
     } else {
-      logger.log(chalk.green('\n✓ Credentials saved to ~/.aifabrix/secrets.local.yaml\n'));
+      logger.log(formatSuccessParagraph('Credentials saved to ~/.aifabrix/secrets.local.yaml\n'));
     }
   } catch (error) {
-    logger.warn(chalk.yellow(`⚠️  Could not save credentials locally: ${error.message}`));
+    logger.warn(chalk.yellow(`⚠  Could not save credentials locally: ${error.message}`));
   }
 }
 
@@ -337,7 +338,10 @@ async function executeRotation(appKey, actualControllerUrl, environment, token)
  * @throws {Error} If rotation fails
  */
 async function rotateSecret(appKey, _options = {}) {
-  logger.log(chalk.yellow('⚠️  This will invalidate the old ClientSecret!\n'));
+  logger.log(chalk.yellow('⚠  This will invalidate the old ClientSecret!\n'));
+
+  const { ensureSecretsEncryptionKey } = require('../core/config');
+  await ensureSecretsEncryptionKey();
 
   const { controllerUrl, environment } = await resolveControllerAndEnvironment();
   const config = await getConfig();
@@ -346,7 +350,7 @@ async function rotateSecret(appKey, _options = {}) {
   try {
     await executeRotation(appKey, actualControllerUrl, environment, token);
   } catch (error) {
-    logger.error(chalk.red(`❌ Failed to rotate secret via controller: ${actualControllerUrl}`));
+    logger.error(formatBlockingError(`Failed to rotate secret via controller: ${actualControllerUrl}`));
     logger.error(chalk.gray(`Error: ${error.message}`));
     process.exit(1);
   }

package/lib/app/run-container-start.js

@@ -0,0 +1,184 @@
+/**
+ * Docker Compose up and docker-run fallback for `aifabrix run`.
+ *
+ * @fileoverview Extracted from run-helpers to keep file size within limits
+ */
+
+'use strict';
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+
+const fs = require('fs').promises;
+const chalk = require('chalk');
+const { exec } = require('child_process');
+const { promisify } = require('util');
+const logger = require('../utils/logger');
+const dockerUtils = require('../utils/docker');
+const containerHelpers = require('../utils/app-run-containers');
+const healthCheck = require('../utils/health-check');
+const runDockerFallback = require('./run-docker-fallback');
+const { resolveRunImage } = require('./run-resolve-image');
+
+const execAsync = promisify(exec);
+
+/**
+ * Logs and runs docker when Compose CLI is missing (narrow eligibility).
+ * @async
+ * @param {string} appName
+ * @param {Object} appConfig
+ * @param {number} port
+ * @param {Object} opts
+ */
+async function emitAndRunDockerFallback(appName, appConfig, port, opts) {
+  const { debug, runEnvPath, runOptions, misoEnvironment } = opts;
+  logger.log(
+    chalk.yellow(
+      'Docker Compose not found; using docker run (apps without database/redis only). ' +
+        'Install docker-compose-plugin for full compose support.'
+    )
+  );
+  const { imageName, imageTag } = resolveRunImage(appName, appConfig, runOptions);
+  await runDockerFallback.executeDockerRunUp({
+    appName,
+    appConfig,
+    hostPort: port,
+    fullImage: `${imageName}:${imageTag}`,
+    runEnvPath,
+    misoEnvironment,
+    debug
+  });
+}
+
+/**
+ * Prepares env for docker compose child process (UID/GID + remote docker).
+ * @async
+ * @param {boolean} debug
+ * @returns {Promise<Object>}
+ */
+async function prepareContainerEnv(debug) {
+  const { getDockerExecEnv } = require('../utils/remote-docker-env');
+  const env = await getDockerExecEnv();
+
+  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';
+  }
+
+  if (debug) {
+    logger.log(chalk.gray('[DEBUG] Container env prepared (secrets via env_file)'));
+  }
+
+  return env;
+}
+
+/**
+ * @async
+ * @param {string} composeCmdBase
+ * @param {string} composePath
+ * @param {Object} env
+ * @param {boolean} debug
+ */
+async function executeComposeUp(composeCmdBase, composePath, env, debug) {
+  const composeCmd = `${composeCmdBase} -f "${composePath}" up -d`;
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Executing: ${composeCmd}`));
+    logger.log(chalk.gray(`[DEBUG] Compose file: ${composePath}`));
+  }
+  await execAsync(composeCmd, { env });
+}
+
+/**
+ * Log status, wait for HTTP health, delete run .env files.
+ * @async
+ * @param {string} appName
+ * @param {number} port
+ * @param {Object} appConfig
+ * @param {{ debug: boolean, runEnvPath: string|null, runEnvAdminPath: string|null }} o
+ */
+async function waitForHealthyAndCleanupEnvFiles(appName, port, appConfig, o) {
+  const { debug, runEnvPath, runEnvAdminPath, runOptions = {} } = o;
+  const ro = runOptions || {};
+  const scopeOpts =
+    ro.effectiveEnvironmentScopedResources === true && ro.env
+      ? { effectiveEnvironmentScopedResources: true, env: String(ro.env).toLowerCase() }
+      : null;
+  const containerName = containerHelpers.getContainerName(appName, appConfig.developerId, scopeOpts);
+  logger.log(formatSuccessLine(`Container ${containerName} started`));
+  await containerHelpers.logContainerStatus(containerName, debug);
+
+  const healthCheckPath = appConfig?.healthCheck?.path || '/health';
+  const healthUrl = (typeof healthCheck.computeHealthCheckUrl === 'function')
+    ? await healthCheck.computeHealthCheckUrl(appName, port, appConfig, { runOptions: ro })
+    : null;
+  // Keep a stable fallback in the message if URL computation fails for any reason.
+  const displayUrl = (healthUrl && typeof healthUrl === 'string')
+    ? healthUrl
+    : `http://localhost:${port}${healthCheckPath}`;
+  logger.log(chalk.blue(`Waiting for application to be healthy at ${displayUrl}...`));
+  await healthCheck.waitForHealthCheck(appName, 90, port, appConfig, debug, ro);
+
+  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}`));
+      }
+    }
+  }
+}
+
+/**
+ * Starts the container and waits for health check. Deletes run .env files after success (ISO 27K).
+ * @async
+ * @param {string} appName
+ * @param {string} composePath
+ * @param {number} port
+ * @param {Object} appConfig
+ * @param {Object} [opts]
+ */
+async function startContainer(appName, composePath, port, appConfig = null, opts = {}) {
+  const {
+    debug = false,
+    runEnvPath = null,
+    runEnvAdminPath = null,
+    runOptions = {},
+    devMountPath = null,
+    misoEnvironment = 'dev'
+  } = opts;
+  logger.log(chalk.blue(`Starting ${appName}...`));
+
+  let composeCmdBase;
+  let usedDockerRunFallback = false;
+  try {
+    composeCmdBase = await dockerUtils.ensureDockerAndCompose();
+  } catch (composeErr) {
+    if (runDockerFallback.canUseDockerRunWithoutCompose(appConfig, { devMountPath })) {
+      await emitAndRunDockerFallback(appName, appConfig, port, {
+        debug,
+        runEnvPath,
+        runOptions,
+        misoEnvironment
+      });
+      usedDockerRunFallback = true;
+    } else {
+      throw composeErr;
+    }
+  }
+
+  if (!usedDockerRunFallback) {
+    const env = await prepareContainerEnv(debug);
+    await executeComposeUp(composeCmdBase, composePath, env, debug);
+  }
+
+  await waitForHealthyAndCleanupEnvFiles(appName, port, appConfig, {
+    debug,
+    runEnvPath,
+    runEnvAdminPath,
+    runOptions
+  });
+}
+
+module.exports = { startContainer, prepareContainerEnv, executeComposeUp };

package/lib/app/run-docker-fallback.js

@@ -0,0 +1,108 @@
+/**
+ * Fallback `docker run` when Docker Compose CLI is missing — narrow case only.
+ *
+ * @fileoverview Apps that declare no Postgres/Redis in application.yaml can start
+ *   with plain Docker; same eligibility as skipping local infra health.
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { execWithDockerEnv } = require('../utils/docker-exec');
+const { getContainerPort } = require('../utils/port-resolver');
+const { getAppInfraRequirements } = require('./run-infra-requirements');
+
+/**
+ * Shell-single-quote a string for use inside a POSIX sh -c style command.
+ * @param {string} value
+ * @returns {string}
+ */
+function shellSingleQuote(value) {
+  const s = String(value);
+  return '\'' + s.replace(/'/g, '\'\\\'\'') + '\'';
+}
+
+/**
+ * Named volume for /mnt/data (must match templates/typescript/docker-compose.hbs).
+ * @param {string} appName
+ * @param {string|number} developerId
+ * @returns {string}
+ */
+function storageVolumeName(appName, developerId) {
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  if (idNum === 0) {
+    return `aifabrix_${appName}_data`;
+  }
+  return `aifabrix_dev${developerId}_${appName}_data`;
+}
+
+/**
+ * True when safe to emulate compose with `docker run` if Compose is unavailable.
+ * @param {Object} appConfig
+ * @param {{ devMountPath?: string|null }} startOpts
+ * @returns {boolean}
+ */
+function canUseDockerRunWithoutCompose(appConfig, startOpts) {
+  const req = getAppInfraRequirements(appConfig);
+  if (!req || req.needsPostgres || req.needsRedis) {
+    return false;
+  }
+  if (appConfig.frontDoorRouting && appConfig.frontDoorRouting.enabled === true) {
+    return false;
+  }
+  if (startOpts.devMountPath) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * @param {Object} o
+ * @param {string} o.appName
+ * @param {Object} o.appConfig
+ * @param {number} o.hostPort
+ * @param {string} o.fullImage image:tag
+ * @param {string|null} o.runEnvPath
+ * @param {string} o.misoEnvironment
+ * @param {boolean} o.debug
+ * @returns {Promise<void>}
+ */
+async function executeDockerRunUp(o) {
+  const { appName, appConfig, hostPort, fullImage, runEnvPath, misoEnvironment, debug } = o;
+  const idNum = typeof appConfig.developerId === 'string' ? parseInt(appConfig.developerId, 10) : appConfig.developerId;
+  const containerName = idNum === 0 ? `aifabrix-${appName}` : `aifabrix-dev${appConfig.developerId}-${appName}`;
+  const containerPort = getContainerPort(appConfig, 3000);
+
+  const needsStorage =
+    appConfig.requires?.storage === true ||
+    appConfig.services?.storage === true;
+
+  const parts = [
+    'docker run -d',
+    `--name ${shellSingleQuote(containerName)}`,
+    '--restart unless-stopped',
+    `-p ${hostPort}:${containerPort}`,
+    `-e MISO_ENVIRONMENT=${shellSingleQuote(misoEnvironment)}`
+  ];
+
+  if (needsStorage) {
+    parts.push(`-v ${shellSingleQuote(storageVolumeName(appName, appConfig.developerId))}:/mnt/data`);
+  }
+  if (runEnvPath && typeof runEnvPath === 'string') {
+    parts.push(`--env-file ${shellSingleQuote(runEnvPath)}`);
+  }
+  parts.push(shellSingleQuote(fullImage));
+
+  const cmd = parts.join(' ');
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Docker run fallback: ${cmd.replace(/env-file [^ ]+/, 'env-file <redacted>')}`));
+  }
+  await execWithDockerEnv(cmd);
+}
+
+module.exports = {
+  canUseDockerRunWithoutCompose,
+  executeDockerRunUp,
+  storageVolumeName
+};