@akash-chowdhury-24/deployhub 2.0.21 → 2.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akash-chowdhury-24/deployhub",
-  "version": "2.0.21",
+  "version": "2.0.22",
   "description": "Zero-configuration deployment and artifact manager",
   "type": "module",
   "main": "./src/cli/index.js",

package/src/adapters/dotnet.adapter.js

@@ -23,8 +23,13 @@ function create(config, cwd) {
     },
 
     async build() {
-      log.info(`Running: ${config.buildCommand}`);
-      const [cmd, ...args] = config.buildCommand.split(' ');
+      const buildCommand = config.buildCommand;
+      if (buildCommand == null || String(buildCommand).trim() === '') {
+        log.info('No build step required — skipping');
+        return;
+      }
+      log.info(`Running: ${buildCommand}`);
+      const [cmd, ...args] = String(buildCommand).split(' ');
       await execa(cmd, args, { cwd, stdio: 'inherit', shell: true });
     },
 

package/src/adapters/go.adapter.js

@@ -22,8 +22,13 @@ function create(config, cwd) {
     },
 
     async build() {
-      log.info(`Running: ${config.buildCommand}`);
-      const [cmd, ...args] = config.buildCommand.split(' ');
+      const buildCommand = config.buildCommand;
+      if (buildCommand == null || String(buildCommand).trim() === '') {
+        log.info('No build step required — skipping');
+        return;
+      }
+      log.info(`Running: ${buildCommand}`);
+      const [cmd, ...args] = String(buildCommand).split(' ');
       await execa(cmd, args, { cwd, stdio: 'inherit', shell: true });
     },
 

package/src/adapters/java.adapter.js

@@ -28,8 +28,13 @@ function create(config, cwd) {
     },
 
     async build() {
-      log.info(`Running: ${config.buildCommand}`);
-      const [cmd, ...args] = config.buildCommand.split(' ');
+      const buildCommand = config.buildCommand;
+      if (buildCommand == null || String(buildCommand).trim() === '') {
+        log.info('No build step required — skipping');
+        return;
+      }
+      log.info(`Running: ${buildCommand}`);
+      const [cmd, ...args] = String(buildCommand).split(' ');
       await execa(cmd, args, { cwd, stdio: 'inherit', shell: true });
     },
 

package/src/adapters/node.adapter.js

@@ -50,13 +50,13 @@ function create(config, cwd) {
         (config.projectType === 'both' ? config.frontend?.buildCommand : null) ||
         (config.projectType === 'backend' ? config.backend?.buildCommand : null);
 
-      if (!buildCommand) {
-        log.info('No build command configured, skipping');
+      if (buildCommand == null || String(buildCommand).trim() === '') {
+        log.info('No build step required — skipping');
         return;
       }
 
       log.info(`Running build: ${buildCommand}`);
-      const [cmd, ...args] = buildCommand.split(' ');
+      const [cmd, ...args] = String(buildCommand).split(' ');
       await execa(cmd, args, { cwd, stdio: 'inherit', shell: true });
     },
 

package/src/adapters/php.adapter.js

@@ -25,8 +25,13 @@ function create(config, cwd) {
     },
 
     async build() {
-      log.info(`Running: ${config.buildCommand}`);
-      const [cmd, ...args] = config.buildCommand.split(' ');
+      const buildCommand = config.buildCommand;
+      if (buildCommand == null || String(buildCommand).trim() === '') {
+        log.info('No build step required — skipping');
+        return;
+      }
+      log.info(`Running: ${buildCommand}`);
+      const [cmd, ...args] = String(buildCommand).split(' ');
       await execa(cmd, args, { cwd, stdio: 'inherit', shell: true });
     },
 

package/src/adapters/python.adapter.js

@@ -34,8 +34,13 @@ function create(config, cwd) {
     },
 
     async build() {
-      log.info(`Running: ${config.buildCommand}`);
-      const [cmd, ...args] = config.buildCommand.split(' ');
+      const buildCommand = config.buildCommand;
+      if (buildCommand == null || String(buildCommand).trim() === '') {
+        log.info('No build step required — skipping');
+        return;
+      }
+      log.info(`Running: ${buildCommand}`);
+      const [cmd, ...args] = String(buildCommand).split(' ');
       await execa(cmd, args, { cwd, stdio: 'inherit', shell: true });
     },
 

package/src/adapters/rails.adapter.js

@@ -40,13 +40,20 @@ function create(config, cwd) {
     },
 
     async build() {
-      const buildCommand = config.buildCommand || 'bundle exec rails assets:precompile';
-      if (!buildCommand) {
-        log.info('No build command configured, skipping');
+      // Explicit null/"" means skip (API-only Rails, etc.). Undefined keeps the
+      // conventional assets:precompile default from the Rails detector.
+      if (config.buildCommand === null || config.buildCommand === '') {
+        log.info('No build step required — skipping');
+        return;
+      }
+      const buildCommand =
+        config.buildCommand || 'bundle exec rails assets:precompile';
+      if (!String(buildCommand).trim()) {
+        log.info('No build step required — skipping');
         return;
       }
       log.info(`Running build: ${buildCommand}`);
-      const [cmd, ...args] = buildCommand.split(' ');
+      const [cmd, ...args] = String(buildCommand).split(' ');
       await execa(cmd, args, { cwd, stdio: 'inherit', shell: true });
     },
 

package/src/artifact/engine.js

@@ -19,6 +19,7 @@ import {
   getEnvSettings,
   resolveDefaultEnvironmentName,
 } from '../core/config.js';
+import { detectDjangoWsgiPackageDir } from '../utils/python-app-target.js';
 
 /**
  * @param {string} cwd
@@ -71,21 +72,26 @@ function resolveArtifactType(config) {
  */
 function resolveBuildSettings(config) {
   if (config.projectType === 'both' && config.backend) {
+    const buildCommand = config.backend.buildCommand ?? null;
     return {
       buildOutput: config.backend.buildOutput || '.',
       framework: config.backend.framework,
       startCommand: config.backend.startCommand || null,
       port: config.backend.port || 3000,
-      buildCommand: config.backend.buildCommand ?? null,
+      buildCommand,
     };
   }
 
+  const buildCommand = config.buildCommand ?? null;
+  const isBackend = config.projectType === 'backend';
   return {
-    buildOutput: config.buildOutput || 'dist',
+    // Backend packages are source trees (or compiled jars/binaries under a known
+    // output dir when set). Never default backends to frontend-style "dist".
+    buildOutput: config.buildOutput || (isBackend ? '.' : 'dist'),
     framework: config.framework || 'node',
     startCommand: config.startCommand || null,
     port: config.port || 3000,
-    buildCommand: config.buildCommand ?? null,
+    buildCommand,
   };
 }
 
@@ -194,14 +200,47 @@ async function stageBackendArtifact(cwd, stagingDir, config) {
 
   if (['express', 'nestjs', 'fastify', 'koa', 'nextjs'].includes(framework)) {
     await copyIfExists(cwd, stagingDir, 'package.json');
-  } else if (['fastapi', 'django', 'flask'].includes(framework)) {
+    await copyIfExists(cwd, stagingDir, 'package-lock.json');
+  } else if (['fastapi', 'django', 'flask', 'python'].includes(framework)) {
+    // Source-only packages: root entrypoints + manifests (no dist/).
     await copyIfExists(cwd, stagingDir, 'requirements.txt');
-    if (framework === 'django' && (await fs.pathExists(path.join(cwd, 'manage.py')))) {
-      await copyIfExists(cwd, stagingDir, 'manage.py');
+    await copyIfExists(cwd, stagingDir, 'pyproject.toml');
+    await copyIfExists(cwd, stagingDir, 'Pipfile');
+    await copyIfExists(cwd, stagingDir, 'Pipfile.lock');
+    await copyIfExists(cwd, stagingDir, 'setup.py');
+    await copyIfExists(cwd, stagingDir, 'manage.py');
+    await copyIfExists(cwd, stagingDir, 'main.py');
+    await copyIfExists(cwd, stagingDir, 'app.py');
+    await copyIfExists(cwd, stagingDir, 'wsgi.py');
+    await copyIfExists(cwd, stagingDir, 'asgi.py');
+    await copyDirectoryIfExists(cwd, stagingDir, 'app');
+    await copyDirectoryIfExists(cwd, stagingDir, 'apps');
+    // Django project package often sits next to manage.py (e.g. config/, mysite/).
+    // `config/` is already copied above for all backends; also copy the detected
+    // package that owns wsgi.py when it is not config/app/apps.
+    if (framework === 'django') {
+      await copyDirectoryIfExists(cwd, stagingDir, 'templates');
+      await copyDirectoryIfExists(cwd, stagingDir, 'static');
+      const wsgiPkg = detectDjangoWsgiPackageDir(cwd);
+      if (
+        wsgiPkg &&
+        !['app', 'apps', 'config', 'templates', 'static', 'src'].includes(wsgiPkg)
+      ) {
+        await copyDirectoryIfExists(cwd, stagingDir, wsgiPkg);
+      }
     }
-  } else if (['laravel', 'symfony'].includes(framework)) {
+  } else if (['laravel', 'symfony', 'php'].includes(framework)) {
     await copyIfExists(cwd, stagingDir, 'composer.json');
     await copyIfExists(cwd, stagingDir, 'composer.lock');
+    await copyIfExists(cwd, stagingDir, 'artisan');
+    await copyDirectoryIfExists(cwd, stagingDir, 'app');
+    await copyDirectoryIfExists(cwd, stagingDir, 'bootstrap');
+    await copyDirectoryIfExists(cwd, stagingDir, 'public');
+    await copyDirectoryIfExists(cwd, stagingDir, 'routes');
+    await copyDirectoryIfExists(cwd, stagingDir, 'database');
+    await copyDirectoryIfExists(cwd, stagingDir, 'resources');
+    await copyDirectoryIfExists(cwd, stagingDir, 'storage');
+    await copyDirectoryIfExists(cwd, stagingDir, 'bin');
   } else if (framework === 'spring') {
     await copyIfExists(cwd, stagingDir, 'pom.xml');
     const targetDir = path.join(cwd, 'target');
@@ -226,11 +265,19 @@ async function stageBackendArtifact(cwd, stagingDir, config) {
     await copyIfExists(cwd, stagingDir, 'Gemfile');
     await copyIfExists(cwd, stagingDir, 'Gemfile.lock');
     await copyIfExists(cwd, stagingDir, 'config.ru');
+    await copyIfExists(cwd, stagingDir, 'Rakefile');
+    await copyDirectoryIfExists(cwd, stagingDir, 'app');
+    await copyDirectoryIfExists(cwd, stagingDir, 'bin');
+    await copyDirectoryIfExists(cwd, stagingDir, 'lib');
+    await copyDirectoryIfExists(cwd, stagingDir, 'db');
+    await copyDirectoryIfExists(cwd, stagingDir, 'public');
   } else {
     await copyIfExists(cwd, stagingDir, 'package.json');
     await copyIfExists(cwd, stagingDir, 'requirements.txt');
   }
 
+  // Only copy a named build-output dir when it actually exists (compiled langs).
+  // Skip '.' / 'src' — source is already staged above; never invent an empty dist/.
   if (settings.buildOutput && settings.buildOutput !== '.' && settings.buildOutput !== 'src') {
     const built = path.join(cwd, settings.buildOutput);
     if (await fs.pathExists(built) && !['target', 'bin', 'publish'].includes(settings.buildOutput)) {
@@ -309,6 +356,7 @@ export async function createArtifact(config, deployedTargets = [], cwd = process
     projectType: artifactType,
     framework: settings.framework,
     buildOutput: settings.buildOutput,
+    buildCommand: settings.buildCommand,
     startCommand: settings.startCommand,
     port: settings.port,
     generatedBy: getGeneratedByMetadata(),
@@ -320,6 +368,8 @@ export async function createArtifact(config, deployedTargets = [], cwd = process
     metadata.frontend = frontend;
     metadata.backend = {
       framework: settings.framework,
+      buildOutput: settings.buildOutput,
+      buildCommand: settings.buildCommand,
       startCommand: settings.startCommand,
       port: settings.port,
     };

package/src/cli/fatal-error.js

@@ -0,0 +1,46 @@
+import chalk from 'chalk';
+
+/**
+ * Format an unexpected CLI error for the user — message only, never a stack
+ * or pkg snapshot paths like `C:\snapshot\...` / `/snapshot/...`.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+export function formatFatalCliError(err) {
+  const raw = err instanceof Error ? err.message : String(err);
+  const message = raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !/[/\\]snapshot[/\\]/i.test(line) && !/^\s*at\s+/.test(line))
+    .join(' ')
+    .trim() || 'Unknown error';
+
+  return (
+    `Unexpected error: ${message}\n` +
+    `  If this persists, open an issue with the command you ran.`
+  );
+}
+
+/**
+ * @param {unknown} err
+ * @param {(msg: string) => void} [write]
+ */
+export function reportFatalCliError(err, write = console.error) {
+  write(chalk.red(formatFatalCliError(err)));
+}
+
+/**
+ * Last-resort handlers so unexpected failures never dump a raw Node stack
+ * (especially ugly under pkg: `C:\\snapshot\\DeployHub\\...`).
+ */
+export function installCliFatalHandlers() {
+  process.on('uncaughtException', (err) => {
+    reportFatalCliError(err);
+    process.exit(1);
+  });
+  process.on('unhandledRejection', (reason) => {
+    reportFatalCliError(reason instanceof Error ? reason : new Error(String(reason)));
+    process.exit(1);
+  });
+}

package/src/cli/index.js

@@ -17,7 +17,12 @@ import { registerSyncWorkflowsCommand } from '../commands/sync-workflows.js';
 import { registerSyncK8sPortsCommand } from '../commands/sync-k8s-ports.js';
 import { registerEnvCommand } from '../commands/env.js';
 import { formatVersionOutput, printBanner, shouldShowBanner } from '../utils/author.js';
+import {
+  installCliFatalHandlers,
+  reportFatalCliError,
+} from './fatal-error.js';
 
+installCliFatalHandlers();
 loadEnv();
 
 const program = new Command();
@@ -48,4 +53,7 @@ registerSyncWorkflowsCommand(program);
 registerSyncK8sPortsCommand(program);
 registerEnvCommand(program);
 
-program.parse();
+program.parseAsync(process.argv).catch((err) => {
+  reportFatalCliError(err);
+  process.exit(1);
+});

package/src/commands/artifact.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
-import { loadConfig, loadEnv } from '../core/config.js';
+import { loadEnv } from '../core/config.js';
+import { loadConfigOrExit } from '../core/load-config-or-exit.js';
 import {
   createArtifact,
   listLocalArtifacts,
@@ -25,7 +26,7 @@ export function registerArtifactCommand(program) {
     .description('Create artifact from current build output')
     .action(async () => {
       loadEnv();
-      const config = await loadConfig();
+      const config = await loadConfigOrExit();
       const result = await createArtifact(config, [], process.cwd());
       console.log(chalk.green(`Artifact created: ${result.artifactDir}`));
     });
@@ -36,7 +37,7 @@ export function registerArtifactCommand(program) {
     .option('--remote', 'Also list builds from remote history.json')
     .action(async (opts) => {
       loadEnv();
-      const config = await loadConfig();
+      const config = await loadConfigOrExit();
       const artifacts = await listLocalArtifacts();
 
       console.log(chalk.bold('\nLocal artifacts:\n'));
@@ -91,7 +92,7 @@ export function registerArtifactCommand(program) {
     .description('Download and extract an artifact by buildId or legacy semver')
     .action(async (versionOrBuildId) => {
       loadEnv();
-      const config = await loadConfig();
+      const config = await loadConfigOrExit();
       const cwd = process.cwd();
       const needle = String(versionOrBuildId).replace(/^v/i, '');
 

package/src/commands/build.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
-import { loadConfig, loadEnv } from '../core/config.js';
+import { loadEnv } from '../core/config.js';
+import { loadConfigOrExit } from '../core/load-config-or-exit.js';
 import { runPipeline } from '../core/pipeline.js';
 import { buildPipelineStages } from '../core/stages.js';
 
@@ -13,14 +14,7 @@ export function registerBuildCommand(program) {
     .action(async () => {
       loadEnv();
       const cwd = process.cwd();
-
-      let config;
-      try {
-        config = await loadConfig(cwd);
-      } catch (err) {
-        console.error(chalk.red(err instanceof Error ? err.message : String(err)));
-        process.exit(1);
-      }
+      const config = await loadConfigOrExit(cwd);
 
       /** @type {Record<string, unknown>} */
       const state = {};

package/src/commands/deploy.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
-import { loadConfig, loadEnv } from '../core/config.js';
+import { loadEnv } from '../core/config.js';
+import { loadConfigOrExit } from '../core/load-config-or-exit.js';
 import { resolveEnvTargets } from '../core/environments.js';
 import { runPipeline } from '../core/pipeline.js';
 import { listLocalArtifacts } from '../artifact/engine.js';
@@ -26,7 +27,7 @@ export function registerDeployCommand(program) {
     .action(async (opts) => {
       loadEnv();
       const cwd = process.cwd();
-      const config = await loadConfig(cwd);
+      const config = await loadConfigOrExit(cwd);
       const log = createLogger('deploy');
 
       let targets;

package/src/commands/doctor.js

@@ -4,7 +4,8 @@ import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
 import axios from 'axios';
-import { loadConfig, loadEnv, getEnvMethod, getEnvSettings } from '../core/config.js';
+import { loadEnv, getEnvMethod, getEnvSettings } from '../core/config.js';
+import { loadConfigOrExit } from '../core/load-config-or-exit.js';
 import {
   isEnvEnabled,
   resolveDefaultEnvironmentName,
@@ -612,6 +613,41 @@ async function runBackendProcessChecks(config, envName, deployType = 'ssh') {
   }
 
   if (PYTHON_FRAMEWORKS.has(framework)) {
+    checks.push(
+      await runCheck('Python 3', async () => {
+        const result = await provider.runRemoteCheck('command -v python3');
+        if (result.pass) {
+          return { name: 'Python 3', pass: true, message: 'python3 found on PATH' };
+        }
+        return {
+          name: 'Python 3',
+          pass: false,
+          message:
+            'python3 not found on PATH — install it on the server ' +
+            '(Amazon Linux: sudo yum install -y python3; Ubuntu: sudo apt-get install -y python3)',
+        };
+      })
+    );
+
+    checks.push(
+      await runCheck('pip', async () => {
+        // Deploy runs `pip install -r requirements.txt`; accept pip3 or pip.
+        const result = await provider.runRemoteCheck(
+          'command -v pip3 >/dev/null 2>&1 || command -v pip >/dev/null 2>&1'
+        );
+        if (result.pass) {
+          return { name: 'pip', pass: true, message: 'pip3 or pip found on PATH' };
+        }
+        return {
+          name: 'pip',
+          pass: false,
+          message:
+            'pip/pip3 not found on PATH — install it on the server ' +
+            '(Amazon Linux: sudo yum install -y python3-pip; Ubuntu: sudo apt-get install -y python3-pip)',
+        };
+      })
+    );
+
     checks.push(
       await runCheck('gunicorn', async () => {
         const result = await provider.runRemoteCheck('which gunicorn || gunicorn --version');
@@ -705,6 +741,8 @@ export function registerDoctorCommand(program) {
     .action(async (opts) => {
       loadEnv();
       const cwd = process.cwd();
+      // Doctor requires a project config — fail cleanly before any checks (no null.storage crash).
+      const config = await loadConfigOrExit(cwd);
       /** @type {CheckResult[]} */
       const results = [];
       /** @type {Set<string>} names of checks that must not fail the summary */
@@ -746,17 +784,6 @@ export function registerDoctorCommand(program) {
 
       results.push(
         await runCheck('Build command', async () => {
-          let config;
-          try {
-            config = await loadConfig(cwd);
-          } catch {
-            return {
-              name: 'Build command',
-              pass: false,
-              message: 'deployhub.config.json not found — run deployhub init',
-            };
-          }
-
           if (config.projectType === 'backend' && !config.buildCommand) {
             return {
               name: 'Build command',
@@ -794,14 +821,7 @@ export function registerDoctorCommand(program) {
         })
       );
 
-      let config = null;
-      try {
-        config = await loadConfig(cwd);
-      } catch {
-        // handled above
-      }
-
-      if (config) {
+      {
         for (const provider of config.storage || []) {
           const label = provider.charAt(0).toUpperCase() + provider.slice(1);
           if (provider === 'aws') {
@@ -946,10 +966,6 @@ export function registerDoctorCommand(program) {
 
       results.push(
         await runCheck('Secrets', async () => {
-          if (!config) {
-            return { name: 'Secrets', pass: false, message: 'No config found' };
-          }
-
           /** @type {string[]} */
           const required = [];
           for (const provider of config.storage || []) {
@@ -984,7 +1000,7 @@ export function registerDoctorCommand(program) {
       );
 
       // Explicit CI-prefixed secret reminders for non-grandfathered environments
-      if (config) {
+      {
         const inCi = process.env.GITHUB_ACTIONS === 'true' || process.env.CI === 'true';
         for (const envName of Object.keys(config.environments || {})) {
           const env = config.environments[envName];

package/src/commands/env.js

@@ -1,10 +1,10 @@
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import {
-  loadConfig,
   loadEnv,
   saveConfig,
 } from '../core/config.js';
+import { loadConfigOrExit } from '../core/load-config-or-exit.js';
 import {
   getEnabledEnvironmentNames,
   getEnvMethod,
@@ -72,7 +72,7 @@ export function registerEnvCommand(program) {
     .description('List configured environments')
     .action(async () => {
       loadEnv();
-      const config = await loadConfig();
+      const config = await loadConfigOrExit();
       const names = Object.keys(config.environments || {});
       if (names.length === 0) {
         console.log(chalk.yellow('No environments configured. Run: deployhub env add <name>'));
@@ -117,7 +117,7 @@ export function registerEnvCommand(program) {
     .action(async (rawName, opts) => {
       loadEnv();
       const cwd = process.cwd();
-      const config = await loadConfig(cwd);
+      const config = await loadConfigOrExit(cwd);
       const log = createLogger('env');
 
       const nameCheck = validateEnvironmentName(rawName, Object.keys(config.environments || {}));
@@ -233,7 +233,7 @@ export function registerEnvCommand(program) {
     .action(async (name) => {
       loadEnv();
       const cwd = process.cwd();
-      const config = await loadConfig(cwd);
+      const config = await loadConfigOrExit(cwd);
       if (!config.environments[name]) {
         console.error(chalk.red(`Environment "${name}" not found.`));
         process.exit(1);
@@ -251,7 +251,7 @@ export function registerEnvCommand(program) {
     .action(async (name) => {
       loadEnv();
       const cwd = process.cwd();
-      const config = await loadConfig(cwd);
+      const config = await loadConfigOrExit(cwd);
       if (!config.environments[name]) {
         console.error(chalk.red(`Environment "${name}" not found.`));
         process.exit(1);
@@ -269,7 +269,7 @@ export function registerEnvCommand(program) {
     .action(async (name) => {
       loadEnv();
       const cwd = process.cwd();
-      const config = await loadConfig(cwd);
+      const config = await loadConfigOrExit(cwd);
       if (!config.environments[name]) {
         console.error(chalk.red(`Environment "${name}" not found.`));
         process.exit(1);

package/src/commands/rollback.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
-import { loadConfig, loadEnv } from '../core/config.js';
+import { loadEnv } from '../core/config.js';
+import { loadConfigOrExit } from '../core/load-config-or-exit.js';
 import { resolveEnvTargets } from '../core/environments.js';
 import {
   rollbackToVersion,
@@ -23,7 +24,7 @@ export function registerRollbackCommand(program) {
     )
     .action(async (versionOrBuildId, opts) => {
       loadEnv();
-      const config = await loadConfig();
+      const config = await loadConfigOrExit();
       const log = createLogger('rollback');
 
       let targets;

package/src/commands/storage.js

@@ -93,14 +93,8 @@ export function registerStorageCommand(program) {
     .description('List configured storage providers and status')
     .action(async () => {
       loadEnv();
-      let config;
-      try {
-        const { loadConfig } = await import('../core/config.js');
-        config = await loadConfig();
-      } catch {
-        console.error(chalk.red('Run deployhub init first'));
-        process.exit(1);
-      }
+      const { loadConfigOrExit } = await import('../core/load-config-or-exit.js');
+      const config = await loadConfigOrExit();
 
       const results = await testAllProviders(config.storage);
       console.log(chalk.bold('\nStorage Providers:\n'));

package/src/commands/sync-k8s-ports.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
-import { loadConfig, loadEnv } from '../core/config.js';
+import { loadEnv } from '../core/config.js';
+import { loadConfigOrExit } from '../core/load-config-or-exit.js';
 import { resolveContainerPort } from '../utils/dockerfile-expose.js';
 import {
   getDefaultKubernetesManifestPaths,
@@ -23,7 +24,7 @@ export function registerSyncK8sPortsCommand(program) {
     .action(async () => {
       loadEnv();
       const cwd = process.cwd();
-      const config = await loadConfig(cwd);
+      const config = await loadConfigOrExit(cwd);
 
       const { deploymentPath, servicePath } = getDefaultKubernetesManifestPaths(cwd);
       const hasDeployment = await fs.pathExists(deploymentPath);

package/src/commands/sync-workflows.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
-import { loadConfig, loadEnv } from '../core/config.js';
+import { loadEnv } from '../core/config.js';
+import { loadConfigOrExit } from '../core/load-config-or-exit.js';
 import { getEnabledEnvironmentNames } from '../core/environments.js';
 import {
   writeWorkflowFile,
@@ -20,7 +21,7 @@ export function registerSyncWorkflowsCommand(program) {
     .action(async () => {
       loadEnv();
       const cwd = process.cwd();
-      const config = await loadConfig(cwd);
+      const config = await loadConfigOrExit(cwd);
 
       const storage = config.storage || [];
       const environments = config.environments || {};

package/src/commands/verify.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
-import { loadConfig, loadEnv } from '../core/config.js';
+import { loadEnv } from '../core/config.js';
+import { loadConfigOrExit } from '../core/load-config-or-exit.js';
 import { resolveEnvTargets } from '../core/environments.js';
 import {
   anyEnvHasResolvableHealthCheckUrl,
@@ -86,7 +87,7 @@ export function registerVerifyCommand(program) {
     )
     .action(async (opts) => {
       loadEnv();
-      const config = await loadConfig();
+      const config = await loadConfigOrExit();
 
       let outcome;
       try {

package/src/core/load-config-or-exit.js

@@ -0,0 +1,37 @@
+import chalk from 'chalk';
+import { loadConfig } from './config.js';
+
+/**
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isConfigMissingError(err) {
+  return err instanceof Error && /Config not found/i.test(err.message);
+}
+
+/**
+ * User-facing missing-config message (no stack, no snapshot paths).
+ */
+export function printMissingConfigError() {
+  console.error(chalk.red('✗ No deployhub.config.json found in this directory.'));
+  console.error(chalk.red("  Run 'deployhub init' first to set up your project."));
+}
+
+/**
+ * Load config or print a clean error and exit (never throws to the caller).
+ * @param {string} [cwd]
+ * @returns {Promise<import('./config.js').DeployHubConfig>}
+ */
+export async function loadConfigOrExit(cwd = process.cwd()) {
+  try {
+    return await loadConfig(cwd);
+  } catch (err) {
+    if (isConfigMissingError(err)) {
+      printMissingConfigError();
+    } else {
+      console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+    }
+    process.exit(1);
+    throw err;
+  }
+}

package/src/core/stages.js

@@ -144,6 +144,8 @@ export function buildPipelineStages(config, cwd, state) {
           return;
         }
 
+        // Adapters themselves null-guard buildCommand; this stage always
+        // invokes build() so interpreted backends can log the skip cleanly.
         const adapter = getAdapter(ctx.config.framework, ctx.config, ctx.cwd);
         await adapter.build();
       },

package/src/deployment/init-prompts.js

@@ -24,6 +24,32 @@ export const SERVER_DEPLOY_TYPES = [
 
 const SSH_BASED = ['ssh', 'ec2', 'azure-vm', 'gcp-vm'];
 
+const NODE_PM2_FRAMEWORKS = new Set([
+  'express',
+  'nestjs',
+  'fastify',
+  'koa',
+  'nextjs',
+  'node',
+]);
+
+/**
+ * User-facing label for the backend process identity field (`appName`).
+ * Node backends use PM2; other languages use DEPLOYHUB_APP + PID files.
+ *
+ * @param {string|undefined|null} framework
+ * @param {string} projectName
+ * @param {'frontend'|'backend'|'both'} projectType
+ * @returns {string}
+ */
+export function backendProcessNamePromptMessage(framework, projectName, projectType) {
+  const backendFramework = String(framework || '').toLowerCase();
+  const usesPm2 = !backendFramework || NODE_PM2_FRAMEWORKS.has(backendFramework);
+  const example = projectType === 'both' ? `${projectName}-api` : projectName;
+  return usesPm2
+    ? `PM2 process name for your backend (e.g. ${example}):`
+    : `Process name for your backend (identifies this app's process on the server, e.g. ${example}):`;
+}
 /**
  * Prompt for one environment's deployment method + method-specific config.
  * Shared by `deployhub init` and `deployhub env add`.
@@ -427,7 +453,11 @@ async function promptSshBasedDeployment(base, projectName, projectType, backendC
     questions.push({
       type: 'input',
       name: 'appName',
-      message: `PM2 process name for your backend (e.g. ${projectName}-api):`,
+      message: backendProcessNamePromptMessage(
+        /** @type {string|undefined} */ (backendConfig?.framework),
+        projectName,
+        projectType
+      ),
       default: projectType === 'both' ? `${projectName}-api` : projectName,
     });
   }

package/src/deployment/providers/ssh.js

@@ -12,6 +12,7 @@ import {
 } from '../../utils/nginx.js';
 import { resolvePm2AppName } from '../../utils/pm2-app-name.js';
 import { shellQuote, formatRemoteCommandFailure } from '../../utils/shell-quote.js';
+import { extractGunicornTarget } from '../../utils/python-app-target.js';
 
 /** @type {Set<string>} */
 const NODE_FRAMEWORKS = new Set(['express', 'nestjs', 'fastify', 'koa', 'nextjs', 'node']);
@@ -171,8 +172,43 @@ export function createSshProvider(config, envName, env = process.env) {
     await exec(ssh, `pkill -f ${sh(markerJvm)} || true`);
   }
 
+  /**
+   * After starting a backend, wait briefly and confirm the PID file's process
+   * is still alive. Not a health check — only catches immediate crash.
+   * `port` is closed over from createSshProvider (settings.port / config.port).
+   *
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @param {string} targetPath
+   * @param {string} [logFile] — defaults to targetPath/app.log
+   */
+  async function assertPidAliveAfterStart(ssh, targetPath, logFile) {
+    const pidFile = `${targetPath}/.deployhub.pid`;
+    const log = logFile || `${targetPath}/app.log`;
+    const verifyCmd =
+      `sleep 2; ` +
+      `pid="$(cat ${sh(pidFile)} 2>/dev/null | tr -cd '0-9')"; ` +
+      `if [ -z "$pid" ] || [ ! -d "/proc/$pid" ]; then ` +
+      `echo "DEPLOYHUB_PROCESS_DIED: process exited immediately after start (pidfile=${sh(pidFile)}). Last lines of ${sh(log)}:"; ` +
+      `tail -n 40 ${sh(log)} 2>/dev/null || echo "(no app.log)"; ` +
+      `exit 1; ` +
+      `fi`;
+
+    try {
+      await exec(ssh, verifyCmd);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `Backend process for "${appName}" died immediately after start at ${targetPath}. ` +
+          `Check dependencies, entrypoint, and port ${port}.\n${detail}`
+      );
+    }
+  }
+
   /**
    * Start a nohup process with DEPLOYHUB_APP marker and write PID file.
+   * After launch, wait briefly and confirm the PID is still alive — otherwise
+   * surface app.log and fail the deploy (nohup+echo $! alone always "succeeds").
+   *
    * @param {import('node-ssh').NodeSSH} ssh
    * @param {string} targetPath
    * @param {string} command — command body after `nohup` (no trailing &)
@@ -184,6 +220,7 @@ export function createSshProvider(config, envName, env = process.env) {
       ssh,
       `cd ${dir} && DEPLOYHUB_APP=${sh(appName)} nohup ${command} > app.log 2>&1 & echo $! > ${sh(pidFile)}`
     );
+    await assertPidAliveAfterStart(ssh, targetPath);
   }
 
   /**
@@ -234,13 +271,21 @@ export function createSshProvider(config, envName, env = process.env) {
           `uvicorn main:app --host 0.0.0.0 --port ${port}`
         );
       } else {
-        // gunicorn --daemon writes its own PID; still set DEPLOYHUB_APP for pkill fallback.
-        const appTarget =
+        // gunicorn --daemon writes the master PID to --pid (same .deployhub.pid).
+        // --error-logfile + --capture-output give us a log to surface on immediate death
+        // (daemonized stdout/stderr otherwise vanish).
+        const logFile = `${targetPath}/app.log`;
+        const fallbackTarget =
           framework === 'django' ? 'config.wsgi:application' : 'app:app';
+        const appTarget =
+          extractGunicornTarget(startCommand) || fallbackTarget;
         await exec(
           ssh,
-          `cd ${dir} && DEPLOYHUB_APP=${sh(appName)} gunicorn ${appTarget} --name ${sh(`deployhub-${appName}`)} --bind 0.0.0.0:${port} --pid ${sh(pidFile)} --daemon`
+          `cd ${dir} && DEPLOYHUB_APP=${sh(appName)} gunicorn ${appTarget} ` +
+            `--name ${sh(`deployhub-${appName}`)} --bind 0.0.0.0:${port} ` +
+            `--pid ${sh(pidFile)} --error-logfile ${sh(logFile)} --capture-output --daemon`
         );
+        await assertPidAliveAfterStart(ssh, targetPath, logFile);
       }
       return;
     }

package/src/detectors/backend.detector.js

@@ -1,5 +1,9 @@
 import fs from 'fs-extra';
 import path from 'path';
+import {
+  detectDjangoWsgiTarget,
+  detectFlaskAppTarget,
+} from '../utils/python-app-target.js';
 
 /**
  * @typedef {Object} BackendDetectorResult
@@ -76,6 +80,7 @@ const FRAMEWORKS = {
     defaults: {
       language: 'python',
       buildCommand: null,
+      // Fallback only — getBackendInfo overrides via detectDjangoWsgiTarget(cwd)
       startCommand: 'gunicorn config.wsgi:application --bind 0.0.0.0:8000',
       buildOutput: '.',
       testCommand: 'python manage.py test',
@@ -87,6 +92,7 @@ const FRAMEWORKS = {
     defaults: {
       language: 'python',
       buildCommand: null,
+      // Fallback only — getBackendInfo overrides via detectFlaskAppTarget(cwd)
       startCommand: 'gunicorn app:app --bind 0.0.0.0:5000',
       buildOutput: '.',
       testCommand: 'pytest',
@@ -261,6 +267,7 @@ export function getBackendInfo(framework, cwd = process.cwd()) {
   let buildCommand = def.defaults.buildCommand;
   let startCommand = def.defaults.startCommand;
   let testCommand = def.defaults.testCommand;
+  const port = def.defaults.port;
 
   if (def.defaults.language === 'node') {
     if (scripts.build) buildCommand = 'npm run build';
@@ -268,6 +275,14 @@ export function getBackendInfo(framework, cwd = process.cwd()) {
     if (scripts.test) testCommand = 'npm test';
   }
 
+  if (framework === 'django') {
+    const target = detectDjangoWsgiTarget(cwd);
+    startCommand = `gunicorn ${target} --bind 0.0.0.0:${port}`;
+  } else if (framework === 'flask') {
+    const target = detectFlaskAppTarget(cwd);
+    startCommand = `gunicorn ${target} --bind 0.0.0.0:${port}`;
+  }
+
   return {
     projectType: 'backend',
     framework,
@@ -277,7 +292,7 @@ export function getBackendInfo(framework, cwd = process.cwd()) {
     buildOutput: def.defaults.buildOutput,
     testCommand,
     hasDocker,
-    port: def.defaults.port,
+    port,
   };
 }
 

package/src/detectors/php.js

@@ -6,10 +6,11 @@ function detect(cwd = process.cwd()) {
 }
 
 function getInfo(cwd = process.cwd()) {
+  // Composer install belongs in the install stage, not a compile/build step.
   return {
     framework: 'php',
-    buildCommand: 'composer install --no-dev --optimize-autoloader',
-    buildOutput: 'public',
+    buildCommand: null,
+    buildOutput: '.',
     hasDocker: fs.existsSync(path.join(cwd, 'Dockerfile')),
   };
 }

package/src/detectors/python.js

@@ -11,10 +11,11 @@ function detect(cwd = process.cwd()) {
 
 function getInfo(cwd = process.cwd()) {
   const hasDocker = fs.existsSync(path.join(cwd, 'Dockerfile'));
+  // Deps install belongs in the install stage (pip), not a compile/build step.
   return {
     framework: 'python',
-    buildCommand: 'pip install -r requirements.txt',
-    buildOutput: 'dist',
+    buildCommand: null,
+    buildOutput: '.',
     hasDocker,
   };
 }

package/src/utils/docker-image-deploy.js

@@ -319,9 +319,17 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
 
     let reused = false;
     if (!options.skipImageReuse) {
+      // Normal deploy: prefer pipeline image (exact tag, then :latest retag).
       reused = await ensureImageFromPipeline(imageRef);
+    } else if (await imageExistsLocally(imageRef)) {
+      // Rollback: never retag :latest onto an older buildId, but DO use the
+      // exact restored buildId image if it is already present locally.
+      log.info(`Using restored image ${imageRef} (skipImageReuse — no :latest retag)`);
+      reused = true;
     } else {
-      log.info(`Skipping local image reuse — rebuilding ${imageRef} from artifact`);
+      log.info(
+        `Target image ${imageRef} not found locally — attempting rebuild from artifact`
+      );
     }
 
     let ranCompose = false;

package/src/utils/python-app-target.js

@@ -0,0 +1,247 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+/** Directories to skip when walking for wsgi.py / Flask entrypoints. */
+const SKIP_DIRS = new Set([
+  'venv',
+  '.venv',
+  'env',
+  '.env',
+  'node_modules',
+  '__pycache__',
+  '.git',
+  '.tox',
+  'site-packages',
+  'dist',
+  'build',
+  '.eggs',
+]);
+
+/**
+ * @param {string} startCommand
+ * @returns {string|null} e.g. `myapp.wsgi:application` or `app:app`
+ */
+export function extractGunicornTarget(startCommand) {
+  if (!startCommand || typeof startCommand !== 'string') return null;
+  const tokens = startCommand.trim().split(/\s+/);
+  const gIdx = tokens.findIndex((t) => t === 'gunicorn' || t.endsWith('/gunicorn'));
+  if (gIdx < 0) return null;
+  for (let i = gIdx + 1; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t.startsWith('-')) {
+      // skip flag and its value when it looks like `--bind 0.0.0.0:8000`
+      if (
+        t === '-b' ||
+        t === '--bind' ||
+        t === '-c' ||
+        t === '--config' ||
+        t === '-n' ||
+        t === '--name' ||
+        t === '-p' ||
+        t === '--pid' ||
+        t === '-w' ||
+        t === '--workers' ||
+        t === '--chdir' ||
+        t === '-e' ||
+        t === '--env' ||
+        t === '--error-logfile' ||
+        t === '--access-logfile' ||
+        t === '--log-file'
+      ) {
+        i += 1;
+      }
+      continue;
+    }
+    // gunicorn app target is module:callable
+    if (/^[A-Za-z_][\w.]*:[A-Za-z_]\w*$/.test(t)) {
+      return t;
+    }
+  }
+  return null;
+}
+
+/**
+ * Walk cwd for files named `wsgi.py`, skipping venvs etc.
+ * @param {string} cwd
+ * @param {number} [maxDepth]
+ * @returns {string[]} absolute paths
+ */
+function findWsgiFiles(cwd, maxDepth = 4) {
+  /** @type {string[]} */
+  const found = [];
+
+  /**
+   * @param {string} dir
+   * @param {number} depth
+   */
+  function walk(dir, depth) {
+    if (depth > maxDepth || found.length >= 20) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const ent of entries) {
+      if (ent.name.startsWith('.') && ent.name !== '.venv') {
+        // skip hidden except we already skip .venv via SKIP_DIRS
+        if (ent.isDirectory()) continue;
+      }
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (SKIP_DIRS.has(ent.name)) continue;
+        walk(full, depth + 1);
+      } else if (ent.isFile() && ent.name === 'wsgi.py') {
+        found.push(full);
+      }
+    }
+  }
+
+  walk(cwd, 0);
+  return found;
+}
+
+/**
+ * Convert absolute wsgi.py path under cwd to gunicorn target `pkg.wsgi:application`.
+ * @param {string} cwd
+ * @param {string} wsgiAbs
+ * @returns {string|null}
+ */
+export function wsgiPathToGunicornTarget(cwd, wsgiAbs) {
+  const rel = path.relative(cwd, wsgiAbs);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  const noExt = rel.replace(/\.py$/i, '');
+  const parts = noExt.split(/[/\\]/).filter(Boolean);
+  if (parts.length === 0) return null;
+  // Invalid if any segment is not a Python identifier
+  if (parts.some((p) => !/^[A-Za-z_]\w*$/.test(p))) return null;
+  return `${parts.join('.')}:application`;
+}
+
+/**
+ * Package directory containing wsgi.py relative to cwd (e.g. `myapp`), or null if root wsgi.py.
+ * @param {string} cwd
+ * @returns {string|null} relative dir name, or '' for root-level wsgi.py, or null if none
+ */
+export function detectDjangoWsgiPackageDir(cwd) {
+  const wsgiAbs = pickPreferredWsgiFile(cwd);
+  if (!wsgiAbs) return null;
+  const rel = path.relative(cwd, path.dirname(wsgiAbs));
+  if (!rel || rel === '.') return '';
+  // Only copy the top-level package segment (myapp/wsgi.py → myapp)
+  const top = rel.split(/[/\\]/)[0];
+  return top || '';
+}
+
+/**
+ * Prefer standard startproject layout (one level down from manage.py), then config/, then any.
+ * @param {string} cwd
+ * @returns {string|null} absolute path to wsgi.py
+ */
+function pickPreferredWsgiFile(cwd) {
+  const files = findWsgiFiles(cwd);
+  if (files.length === 0) return null;
+
+  const hasManage = fs.existsSync(path.join(cwd, 'manage.py'));
+
+  // Prefer <pkg>/wsgi.py directly under cwd when manage.py exists (django-admin startproject)
+  if (hasManage) {
+    const oneLevel = files.filter((f) => {
+      const rel = path.relative(cwd, f);
+      const parts = rel.split(/[/\\]/);
+      return parts.length === 2 && parts[1] === 'wsgi.py';
+    });
+    if (oneLevel.length === 1) return oneLevel[0];
+    // Prefer config/wsgi.py when present among one-level candidates (cookiecutter)
+    const configOne = oneLevel.find((f) => path.basename(path.dirname(f)) === 'config');
+    if (configOne) return configOne;
+    if (oneLevel.length > 0) return oneLevel[0];
+  }
+
+  const configWsgi = files.find((f) => {
+    const rel = path.relative(cwd, f).replace(/\\/g, '/');
+    return rel === 'config/wsgi.py';
+  });
+  if (configWsgi) return configWsgi;
+
+  const rootWsgi = files.find((f) => path.dirname(f) === path.resolve(cwd));
+  if (rootWsgi) return rootWsgi;
+
+  return files[0];
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {string} gunicorn target, e.g. `myapp.wsgi:application`
+ */
+export function detectDjangoWsgiTarget(cwd = process.cwd()) {
+  const wsgiAbs = pickPreferredWsgiFile(cwd);
+  if (!wsgiAbs) return 'config.wsgi:application';
+  return wsgiPathToGunicornTarget(cwd, wsgiAbs) || 'config.wsgi:application';
+}
+
+/**
+ * @param {string} filePath
+ * @returns {'app'|'application'|null}
+ */
+function detectFlaskCallableName(filePath) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+  // Prefer explicit assignment / factory patterns for `app` then `application`
+  if (
+    /\bapp\s*=\s*/.test(content) ||
+    /\bcreate_app\s*\(/.test(content) ||
+    /\bFlask\s*\(/.test(content)
+  ) {
+    // If both exist, prefer `application` only when `app` is absent as assignment
+    if (/\bapp\s*=\s*/.test(content) || /\bFlask\s*\(/.test(content)) {
+      if (/\bapplication\s*=\s*/.test(content) && !/\bapp\s*=\s*/.test(content)) {
+        return 'application';
+      }
+      return 'app';
+    }
+  }
+  if (/\bapplication\s*=\s*/.test(content)) return 'application';
+  return null;
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {string} gunicorn target, e.g. `app:app`
+ */
+export function detectFlaskAppTarget(cwd = process.cwd()) {
+  const candidates = ['app.py', 'wsgi.py', 'application.py'];
+  for (const name of candidates) {
+    const full = path.join(cwd, name);
+    if (!fs.existsSync(full)) continue;
+    const callable = detectFlaskCallableName(full);
+    if (callable) {
+      const mod = name.replace(/\.py$/i, '');
+      return `${mod}:${callable}`;
+    }
+  }
+  // Module package app/__init__.py or app/app.py
+  const pkgInit = path.join(cwd, 'app', '__init__.py');
+  if (fs.existsSync(pkgInit)) {
+    const callable = detectFlaskCallableName(pkgInit);
+    if (callable) return `app:${callable}`;
+  }
+  const pkgApp = path.join(cwd, 'app', 'app.py');
+  if (fs.existsSync(pkgApp)) {
+    const callable = detectFlaskCallableName(pkgApp);
+    if (callable) return `app.app:${callable}`;
+  }
+  return 'app:app';
+}
+
+export default {
+  extractGunicornTarget,
+  detectDjangoWsgiTarget,
+  detectFlaskAppTarget,
+  detectDjangoWsgiPackageDir,
+  wsgiPathToGunicornTarget,
+};