@akash-chowdhury-24/deployhub 2.0.2 → 2.0.4

package/README.md

@@ -604,26 +604,61 @@ DeployHub supports six deployment targets. Pick based on what infrastructure you
 
 Each method below follows the same structure: **prerequisites** (before `deployhub init`), **what DeployHub automates**, **after init** (matches terminal output), and a **variable reference**.
 
+### One-time server setup (before your first deploy)
+
+SSH-based methods (SSH, EC2, Azure VM, GCP VM) require a few one-time steps on the server **before your first deploy**. DeployHub does not silently change ownership or sudo policy for you.
+
+SSH into your server once and run:
+
+```bash
+sudo mkdir -p /var/www/your-app-name
+sudo chown your-ssh-user:your-ssh-user /var/www/your-app-name
+```
+
+Replace `/var/www/your-app-name` with your actual deploy path and `your-ssh-user` with your configured `SSH_USER` (e.g. `ec2-user` on Amazon Linux, `ubuntu` on Ubuntu). Without this, DeployHub cannot write your build output — `deployhub doctor` will catch it and show the exact fix.
+
+**Frontend deploys** that auto-activate `nginx.conf` also need **passwordless sudo** for Nginx test/reload (and `cp` into `/etc/nginx/`). After installing Nginx, run `sudo visudo` and add a line like:
+
+```bash
+your-ssh-user ALL=(ALL) NOPASSWD: /usr/sbin/nginx, /bin/cp, /usr/bin/cp, /bin/systemctl, /usr/bin/systemctl
+```
+
+> **Security note:** This example grants broad privileges — unrestricted `cp` (any source/destination) and `systemctl` (any unit/action), not just Nginx. That keeps setup simple but is a significant trust boundary. For production, prefer a dedicated deploy user and a **narrow wrapper script** (e.g. `/usr/local/bin/deployhub-nginx-reload` that only copies to your project's config path and runs `nginx -t` + reload), then grant `NOPASSWD` only for that script. The line above is a starting point for dev/test servers; tighten it before production.
+
+Install Nginx if it is not already present:
+
+- **Amazon Linux / RHEL:** `sudo yum install -y nginx && sudo systemctl enable --now nginx`
+- **Ubuntu / Debian:** `sudo apt install -y nginx`
+
+DeployHub detects whether the server uses Debian-style `sites-available` or RHEL-style `conf.d` at deploy time and writes a **uniquely named** config file for your project only — it does not overwrite unrelated Nginx configs.
+
 ### SSH
 
 **Prerequisites (before `deployhub init`):**
+- [ ] Complete **[one-time server setup](#one-time-server-setup-before-your-first-deploy)** (deploy path ownership + Nginx/sudo for frontends)
 - [ ] A Linux server with SSH enabled
 - [ ] Private SSH key file (.pem/.key) and public key in `authorized_keys`
 - [ ] Port 22 open in firewall for your IP
+- [ ] Deploy directory writable by your SSH user (e.g. `sudo mkdir -p /var/www/my-app && sudo chown ubuntu:ubuntu /var/www/my-app` — `/var/www` is root-owned on most fresh Linux images)
 - [ ] App runtime on server (Node.js, Python, etc.) for backends
 
 **What DeployHub automates:**
 - Complete `.env.example` with commented variables
 - SSH key permission check (offers to `chmod 600`)
 - SSH connectivity test during `init`
+- Deploy path write-permission check during `deployhub doctor`
+- Nginx layout detection (Debian `sites-available` vs RHEL `conf.d`) at deploy time
+- Nginx config test (`nginx -t`) before reload
+- Passwordless sudo and Nginx checks during `deployhub doctor` (frontend)
 - Artifact upload, extract, app restart (PM2, gunicorn, etc.)
 
 **After `init`:**
 1. Ensure port 22 is open in your server firewall
-2. Copy `.env.example` → `.env`; set `SSH_HOST`, `SSH_USER`, `SSH_KEY_PATH`
-3. Add GitHub Secrets: `SSH_HOST`, `SSH_USER`, `SSH_KEY` (paste private key for CI)
-4. Run `deployhub doctor`
-5. `git push origin main`
+2. Ensure your deploy directory exists and is owned by your SSH user (see prerequisite above if `deployhub doctor` reports permission denied)
+3. Copy `.env.example` → `.env`; set `SSH_HOST`, `SSH_USER`, `SSH_KEY_PATH`
+4. Add GitHub Secrets: `SSH_HOST`, `SSH_USER`, `SSH_KEY` (paste private key for CI)
+5. Run `deployhub doctor`
+6. `git push origin main`
 
 | Variable | Description | Example | Where to get it |
 |----------|-------------|---------|-----------------|
@@ -666,22 +701,28 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 ### AWS EC2
 
 **Prerequisites:**
+- [ ] Complete **[one-time server setup](#one-time-server-setup-before-your-first-deploy)** (`ec2-user` on Amazon Linux)
 - [ ] EC2 instance launched in AWS Console (DeployHub does not create it)
 - [ ] Key pair `.pem` downloaded at launch
 - [ ] Security group: inbound SSH (22) from your IP
+- [ ] Deploy directory writable by your SSH user (e.g. `sudo mkdir -p /var/www/my-app && sudo chown ec2-user:ec2-user /var/www/my-app` — `/var/www` is root-owned on Amazon Linux by default)
 - [ ] App runtime on instance for backends
 
 **What DeployHub automates:**
 - EC2-specific `.env.example` (SSH + optional AWS API vars)
 - SSH key validation and connectivity test
+- Deploy path write-permission check during `deployhub doctor`
+- Nginx layout detection and config test before reload (frontend)
+- Passwordless sudo and Nginx checks during `deployhub doctor` (frontend)
 - OS user suggestion from AMI hint (ubuntu, ec2-user)
 - Optional public IP lookup via `EC2_INSTANCE_ID` + AWS CLI
 
 **After `init`:**
 1. AWS Console → EC2 → Security Groups → Inbound rules → SSH port 22 from My IP
-2. Copy `.env.example` → `.env`; set `SSH_KEY_PATH`, `SSH_HOST` (or `EC2_INSTANCE_ID` + AWS creds)
-3. GitHub Secrets: `SSH_HOST`, `SSH_USER`, `SSH_KEY`, plus `AWS_*` if using instance ID lookup
-4. Run `deployhub doctor`, then `git push origin main`
+2. Ensure your deploy directory exists and is owned by your SSH user (see prerequisite above if `deployhub doctor` reports permission denied)
+3. Copy `.env.example` → `.env`; set `SSH_KEY_PATH`, `SSH_HOST` (or `EC2_INSTANCE_ID` + AWS creds)
+4. GitHub Secrets: `SSH_HOST`, `SSH_USER`, `SSH_KEY`, plus `AWS_*` if using instance ID lookup
+5. Run `deployhub doctor`, then `git push origin main`
 
 | Variable | Description | Example | Where to get it |
 |----------|-------------|---------|-----------------|
@@ -696,21 +737,27 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 ### Azure VM
 
 **Prerequisites:**
+- [ ] Complete **[one-time server setup](#one-time-server-setup-before-your-first-deploy)** (`azureuser` or your VM login user)
 - [ ] Azure VM created in Portal (DeployHub does not provision it)
 - [ ] NSG rule allowing inbound SSH (port 22)
 - [ ] SSH public key on the VM
+- [ ] Deploy directory writable by your SSH user (e.g. `sudo mkdir -p /var/www/my-app && sudo chown azureuser:azureuser /var/www/my-app`)
 - [ ] App runtime for backends
 
 **What DeployHub automates:**
 - Azure VM `.env.example` with SSH + optional Azure API vars
 - Auto-detects subscription ID via `az` CLI if logged in
 - SSH key validation and connectivity test
+- Deploy path write-permission check during `deployhub doctor`
+- Nginx layout detection and config test before reload (frontend)
+- Passwordless sudo and Nginx checks during `deployhub doctor` (frontend)
 
 **After `init`:**
 1. Azure Portal → VM → Networking → allow SSH (22) from your IP
-2. Copy `.env.example` → `.env`; set `SSH_HOST`, `SSH_USER`, `SSH_KEY_PATH`
-3. For CI: add `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET` as GitHub Secrets
-4. Run `deployhub doctor`, then `git push origin main`
+2. Ensure your deploy directory exists and is owned by your SSH user (see prerequisite above if `deployhub doctor` reports permission denied)
+3. Copy `.env.example` → `.env`; set `SSH_HOST`, `SSH_USER`, `SSH_KEY_PATH`
+4. For CI: add `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET` as GitHub Secrets
+5. Run `deployhub doctor`, then `git push origin main`
 
 | Variable | Description | Example | Where to get it |
 |----------|-------------|---------|-----------------|
@@ -724,21 +771,27 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 ### GCP VM
 
 **Prerequisites:**
+- [ ] Complete **[one-time server setup](#one-time-server-setup-before-your-first-deploy)** (your GCP SSH username)
 - [ ] Compute Engine VM created (DeployHub does not create it)
 - [ ] Firewall rule allowing `tcp:22` (default `default-allow-ssh` may exist)
 - [ ] SSH public key in **Metadata → SSH Keys** (GCP uses metadata keys, not launch key pairs like AWS)
+- [ ] Deploy directory writable by your SSH user (e.g. `sudo mkdir -p /var/www/my-app && sudo chown $USER:$USER /var/www/my-app`)
 - [ ] App runtime for backends
 
 **What DeployHub automates:**
 - GCP VM `.env.example` with SSH + optional GCP API vars
 - Auto-detects project ID via `gcloud` if authenticated
 - SSH key validation and connectivity test
+- Deploy path write-permission check during `deployhub doctor`
+- Nginx layout detection and config test before reload (frontend)
+- Passwordless sudo and Nginx checks during `deployhub doctor` (frontend)
 
 **After `init`:**
 1. GCP Console → VPC → Firewall → ensure SSH (tcp:22) allowed from your IP
 2. Add SSH public key: Console → Compute Engine → Metadata → SSH Keys
-3. Copy `.env.example` → `.env`; set `SSH_HOST`, `SSH_USER`, `SSH_KEY_PATH`
-4. Run `deployhub doctor`, then `git push origin main`
+3. Ensure your deploy directory exists and is owned by your SSH user (see prerequisite above if `deployhub doctor` reports permission denied)
+4. Copy `.env.example` → `.env`; set `SSH_HOST`, `SSH_USER`, `SSH_KEY_PATH`
+5. Run `deployhub doctor`, then `git push origin main`
 
 | Variable | Description | Example | Where to get it |
 |----------|-------------|---------|-----------------|

package/package.json

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

package/src/commands/deploy.js

@@ -71,7 +71,7 @@ export function registerDeployCommand(program) {
 
       const { failure } = await runPipeline(stages, { config, cwd, state });
       if (failure) {
-        console.error(chalk.red(`Deploy failed: ${failure.message}`));
+        console.error(chalk.red(failure.message));
         process.exit(1);
       }
 

package/src/commands/doctor.js

@@ -14,6 +14,11 @@ import {
   getDeploymentSecretKeys,
 } from '../deployment/deployment-env.js';
 import { testSshConnectivity, validateSshKeyForDoctor, testSshHostReachability } from '../deployment/init-helpers.js';
+import {
+  buildDeployPathWriteTestCommand,
+  formatDeployPathWriteFailure,
+} from '../utils/shell-quote.js';
+import { formatPasswordlessSudoGuidance } from '../utils/nginx.js';
 
 /**
  * @typedef {{ name: string, pass: boolean, message: string }} CheckResult
@@ -56,6 +61,38 @@ function resolveBackendFramework(config) {
 /** @type {Set<string>} */
 const SSH_DEPLOY_TYPES = new Set(['ssh', 'ec2', 'azure-vm', 'gcp-vm']);
 
+/**
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {Record<string, unknown>} envConfig
+ * @returns {string[]}
+ */
+function resolveSshDeployPaths(config, envConfig) {
+  /** @type {string[]} */
+  const paths = [];
+
+  if (config.projectType === 'both') {
+    if (envConfig.frontendDeployPath) paths.push(String(envConfig.frontendDeployPath));
+    if (envConfig.backendDeployPath) paths.push(String(envConfig.backendDeployPath));
+    else if (envConfig.path) paths.push(String(envConfig.path));
+  } else {
+    const deployPath =
+      envConfig.deployPath || envConfig.path || process.env.SSH_DEPLOY_PATH;
+    if (deployPath) paths.push(String(deployPath));
+  }
+
+  return [...new Set(paths.filter(Boolean))];
+}
+
+/**
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @returns {boolean}
+ */
+function needsNginxActivationForDeploy(config) {
+  if (config.projectType === 'backend') return false;
+  if (config.projectType === 'frontend' && config.framework === 'nextjs') return false;
+  return true;
+}
+
 /**
  * @param {import('../core/config.js').DeployHubConfig} config
  * @param {string} envName
@@ -131,6 +168,199 @@ async function runDeploymentChecks(config, envName, envConfig) {
       })
     );
 
+    const deployPaths = resolveSshDeployPaths(config, envConfig);
+    const sshUser = String(user || process.env.SSH_USER || 'your-user');
+
+    for (const deployPath of deployPaths) {
+      const checkName = `Deploy path write (${deployPath})`;
+      checks.push(
+        await runCheck(checkName, async () => {
+          if (!host || !user) {
+            return {
+              name: checkName,
+              pass: false,
+              message: 'SSH_HOST and SSH_USER are required for deploy path write test.',
+            };
+          }
+          if (!keyPath && !process.env.SSH_KEY) {
+            return {
+              name: checkName,
+              pass: false,
+              message: 'SSH_KEY_PATH or SSH_KEY is required for deploy path write test.',
+            };
+          }
+
+          const provider = getDeploymentProvider(deployType, config, envName);
+          if (!provider.runRemoteCheck) {
+            return {
+              name: checkName,
+              pass: false,
+              message: 'Deploy provider does not support remote checks.',
+            };
+          }
+
+          const command = buildDeployPathWriteTestCommand(deployPath);
+          const result = await provider.runRemoteCheck(command);
+          if (result.pass) {
+            return {
+              name: checkName,
+              pass: true,
+              message: `Write access OK for ${deployPath}`,
+            };
+          }
+
+          return {
+            name: checkName,
+            pass: false,
+            message: formatDeployPathWriteFailure(deployPath, sshUser, result.message),
+          };
+        })
+      );
+    }
+
+    if (needsNginxActivationForDeploy(config)) {
+      checks.push(
+        await runCheck('Nginx installed', async () => {
+          if (!host || !user) {
+            return {
+              name: 'Nginx installed',
+              pass: false,
+              message: 'SSH_HOST and SSH_USER are required to check Nginx on the server.',
+            };
+          }
+          if (!keyPath && !process.env.SSH_KEY) {
+            return {
+              name: 'Nginx installed',
+              pass: false,
+              message: 'SSH_KEY_PATH or SSH_KEY is required to check Nginx on the server.',
+            };
+          }
+
+          const provider = getDeploymentProvider(deployType, config, envName);
+          if (!provider.runRemoteCheck) {
+            return {
+              name: 'Nginx installed',
+              pass: false,
+              message: 'Deploy provider does not support remote checks.',
+            };
+          }
+
+          const result = await provider.runRemoteCheck('command -v nginx >/dev/null 2>&1 && echo yes');
+          if (result.pass && result.message.includes('yes')) {
+            return { name: 'Nginx installed', pass: true, message: 'Nginx installed on server' };
+          }
+          return {
+            name: 'Nginx installed',
+            pass: false,
+            message:
+              'Nginx not found on server — install it first (e.g. sudo yum install nginx on Amazon Linux, or sudo apt install nginx on Ubuntu).',
+          };
+        })
+      );
+
+      checks.push(
+        await runCheck('Passwordless sudo', async () => {
+          if (!host || !user) {
+            return {
+              name: 'Passwordless sudo',
+              pass: false,
+              message: 'SSH_HOST and SSH_USER are required for sudo check.',
+            };
+          }
+          if (!keyPath && !process.env.SSH_KEY) {
+            return {
+              name: 'Passwordless sudo',
+              pass: false,
+              message: 'SSH_KEY_PATH or SSH_KEY is required for sudo check.',
+            };
+          }
+
+          const provider = getDeploymentProvider(deployType, config, envName);
+          if (!provider.runRemoteCheck) {
+            return {
+              name: 'Passwordless sudo',
+              pass: false,
+              message: 'Deploy provider does not support remote checks.',
+            };
+          }
+
+          const result = await provider.runRemoteCheck('sudo -n true');
+          if (result.pass) {
+            return {
+              name: 'Passwordless sudo',
+              pass: true,
+              message: 'Non-interactive sudo available (required for Nginx config activation)',
+            };
+          }
+          return {
+            name: 'Passwordless sudo',
+            pass: false,
+            message: formatPasswordlessSudoGuidance(sshUser),
+          };
+        })
+      );
+
+      checks.push(
+        await runCheck('Nginx sudo access', async () => {
+          if (!host || !user) {
+            return {
+              name: 'Nginx sudo access',
+              pass: false,
+              message: 'SSH_HOST and SSH_USER are required for Nginx sudo check.',
+            };
+          }
+          if (!keyPath && !process.env.SSH_KEY) {
+            return {
+              name: 'Nginx sudo access',
+              pass: false,
+              message: 'SSH_KEY_PATH or SSH_KEY is required for Nginx sudo check.',
+            };
+          }
+
+          const provider = getDeploymentProvider(deployType, config, envName);
+          if (!provider.runRemoteCheck) {
+            return {
+              name: 'Nginx sudo access',
+              pass: false,
+              message: 'Deploy provider does not support remote checks.',
+            };
+          }
+
+          const nginxInstalled = await provider.runRemoteCheck('command -v nginx >/dev/null 2>&1 && echo yes');
+          if (!nginxInstalled.pass || !nginxInstalled.message.includes('yes')) {
+            return {
+              name: 'Nginx sudo access',
+              pass: false,
+              message: 'Skipped — install Nginx first.',
+            };
+          }
+
+          const sudoOk = await provider.runRemoteCheck('sudo -n true');
+          if (!sudoOk.pass) {
+            return {
+              name: 'Nginx sudo access',
+              pass: false,
+              message: 'Skipped — configure passwordless sudo first.',
+            };
+          }
+
+          const result = await provider.runRemoteCheck('sudo -n nginx -t 2>&1');
+          if (result.pass) {
+            return {
+              name: 'Nginx sudo access',
+              pass: true,
+              message: 'sudo nginx -t OK (can test config before reload)',
+            };
+          }
+          return {
+            name: 'Nginx sudo access',
+            pass: false,
+            message: `sudo nginx -t failed — ${result.message}. Check Nginx install and sudoers (see README one-time server setup).`,
+          };
+        })
+      );
+    }
+
     const isBackend = config.projectType === 'backend' || config.projectType === 'both';
     if (isBackend) {
       const backendChecks = await runBackendProcessChecks(config, envName, deployType);

package/src/commands/init.js

@@ -27,6 +27,7 @@ import {
   SSH_BASED,
 } from '../deployment/init-prompts.js';
 import { printDeploymentNextSteps } from '../deployment/deployment-env.js';
+import { confirmValueIfContainsSpaces } from '../deployment/init-helpers.js';
 
 const FRONTEND_CHOICES = [
   { name: 'React', value: 'react' },
@@ -221,7 +222,7 @@ export function registerInitCommand(program) {
       const defaultName = path.basename(cwd) || 'my-app';
       const cliSource = DEFAULT_NPM_CLI_SOURCE;
 
-      const { projectName } = await inquirer.prompt([
+      let { projectName } = await inquirer.prompt([
         {
           type: 'input',
           name: 'projectName',
@@ -230,6 +231,8 @@ export function registerInitCommand(program) {
         },
       ]);
 
+      projectName = await confirmValueIfContainsSpaces(projectName, 'project name');
+
       const { projectType } = await inquirer.prompt([
         {
           type: 'list',

package/src/deployment/init-helpers.js

@@ -6,6 +6,7 @@ import { execa } from 'execa';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { NodeSSH } from 'node-ssh';
+import { toKebabCase } from '../utils/shell-quote.js';
 
 /** @type {Record<string, string>} */
 export const OS_USER_DEFAULTS = {
@@ -329,6 +330,87 @@ export async function testKubeConnectivity(kubeconfig, context) {
   }
 }
 
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {Promise<string>}
+ */
+export async function confirmValueIfContainsSpaces(value, label) {
+  if (!/\s/.test(value)) return value;
+
+  const suggested = toKebabCase(value);
+  console.log(chalk.yellow(`\n  ⚠ Your ${label} contains spaces: "${value}"`));
+  console.log(
+    chalk.gray(
+      `  Spaces in paths can cause shell issues on the server. Suggested: "${suggested || value.replace(/\s+/g, '-')}"`
+    )
+  );
+
+  const { choice } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'choice',
+      message: 'How would you like to proceed?',
+      choices: [
+        {
+          name: `Use suggested: ${suggested || value.replace(/\s+/g, '-')}`,
+          value: 'suggested',
+        },
+        { name: `Keep original: ${value}`, value: 'keep' },
+        { name: 'Enter a different value', value: 'custom' },
+      ],
+    },
+  ]);
+
+  if (choice === 'suggested') {
+    return suggested || value.replace(/\s+/g, '-');
+  }
+  if (choice === 'keep') {
+    return value;
+  }
+
+  const { custom } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'custom',
+      message: `${label}:`,
+      default: suggested || value.replace(/\s+/g, '-'),
+    },
+  ]);
+  return custom;
+}
+
+/**
+ * @param {Record<string, string>} sshAnswers
+ * @param {'frontend'|'backend'|'both'} projectType
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function resolveDeployPathsWithSpaceWarning(sshAnswers, projectType) {
+  if (projectType !== 'both' && sshAnswers.deployPath) {
+    sshAnswers.deployPath = await confirmValueIfContainsSpaces(
+      sshAnswers.deployPath,
+      'deploy path'
+    );
+  }
+
+  if (projectType === 'both') {
+    if (sshAnswers.frontendDeployPath) {
+      sshAnswers.frontendDeployPath = await confirmValueIfContainsSpaces(
+        sshAnswers.frontendDeployPath,
+        'frontend deploy path'
+      );
+    }
+    if (sshAnswers.backendDeployPath) {
+      sshAnswers.backendDeployPath = await confirmValueIfContainsSpaces(
+        sshAnswers.backendDeployPath,
+        'backend deploy path'
+      );
+    }
+  }
+
+  return sshAnswers;
+}
+
 /**
  * Run SSH key validation + connectivity test after init prompts.
  * @param {{ host: string, user: string, keyPath?: string, sshPort?: number, deployType: string }} opts

package/src/deployment/init-prompts.js

@@ -7,6 +7,7 @@ import {
   detectAzureSubscriptionId,
   detectGcpProjectId,
   runSshInitValidation,
+  resolveDeployPathsWithSpaceWarning,
   testKubeConnectivity,
   getDeployTypeLabel,
 } from './init-helpers.js';
@@ -327,6 +328,7 @@ async function promptSshBasedDeployment(base, projectName, projectType, backendC
   });
 
   const sshAnswers = await inquirer.prompt(questions);
+  await resolveDeployPathsWithSpaceWarning(sshAnswers, projectType);
 
   await runSshInitValidation({
     host: sshAnswers.host,

package/src/deployment/providers/ssh.js

@@ -3,7 +3,12 @@ import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
 import { createLogger } from '../../logger/index.js';
-import { getNginxSitePath } from '../../utils/nginx.js';
+import {
+  getNginxSitesAvailablePath,
+  getNginxSitesEnabledPath,
+  getNginxConfDPath,
+} from '../../utils/nginx.js';
+import { shellQuote, formatRemoteCommandFailure } from '../../utils/shell-quote.js';
 
 /** @type {Set<string>} */
 const NODE_FRAMEWORKS = new Set(['express', 'nestjs', 'fastify', 'koa', 'nextjs', 'node']);
@@ -12,6 +17,8 @@ const PYTHON_FRAMEWORKS = new Set(['fastapi', 'django', 'flask', 'python']);
 /** @type {Set<string>} */
 const PHP_FRAMEWORKS = new Set(['laravel', 'symfony', 'php']);
 
+const sh = shellQuote;
+
 /**
  * @param {import('../../core/config.js').DeployHubConfig} config
  * @param {string} envName
@@ -88,7 +95,14 @@ export function createSshProvider(config, envName, env = process.env) {
     log.info(`$ ${command}`);
     const result = await ssh.execCommand(command);
     if (result.code !== 0 && result.code !== null) {
-      log.warn(`Command exited with code ${result.code}: ${result.stderr || result.stdout}`);
+      const message = formatRemoteCommandFailure(
+        command,
+        result.code,
+        result.stderr,
+        result.stdout
+      );
+      log.error(message);
+      throw new Error(message);
     }
     return result;
   }
@@ -123,26 +137,27 @@ export function createSshProvider(config, envName, env = process.env) {
   async function runBackendStartSequence(ssh, targetPath) {
     const framework = resolveFramework();
     const startCommand = resolveStartCommand();
+    const dir = sh(targetPath);
 
     if (NODE_FRAMEWORKS.has(framework)) {
-      await exec(ssh, `cd ${targetPath} && npm install --production`);
+      await exec(ssh, `cd ${dir} && npm install --production`);
       const start = startCommand || 'npm start';
       if (start === 'npm start') {
         await exec(
           ssh,
-          `cd ${targetPath} && pm2 restart ${appName} || pm2 start npm --name "${appName}" -- start`
+          `cd ${dir} && pm2 restart ${sh(appName)} || pm2 start npm --name ${sh(appName)} -- start`
         );
       } else if (start.startsWith('npm run ')) {
         const script = start.replace('npm run ', '');
         await exec(
           ssh,
-          `cd ${targetPath} && pm2 restart ${appName} || pm2 start npm --name "${appName}" -- run ${script}`
+          `cd ${dir} && pm2 restart ${sh(appName)} || pm2 start npm --name ${sh(appName)} -- run ${script}`
         );
       } else {
         const [cmd, ...args] = start.split(' ');
         await exec(
           ssh,
-          `cd ${targetPath} && pm2 restart ${appName} || pm2 start ${cmd} --name "${appName}" -- ${args.join(' ')}`
+          `cd ${dir} && pm2 restart ${sh(appName)} || pm2 start ${cmd} --name ${sh(appName)} -- ${args.join(' ')}`
         );
       }
       await exec(ssh, 'pm2 save');
@@ -150,15 +165,15 @@ export function createSshProvider(config, envName, env = process.env) {
     }
 
     if (PYTHON_FRAMEWORKS.has(framework)) {
-      await exec(ssh, `cd ${targetPath} && pip install -r requirements.txt`);
+      await exec(ssh, `cd ${dir} && pip install -r requirements.txt`);
       if (framework === 'django') {
-        await exec(ssh, `cd ${targetPath} && python manage.py migrate`);
+        await exec(ssh, `cd ${dir} && python manage.py migrate`);
       }
       if (framework === 'fastapi') {
         await exec(ssh, 'pkill uvicorn || true');
         await exec(
           ssh,
-          `cd ${targetPath} && nohup uvicorn main:app --host 0.0.0.0 --port ${port} > app.log 2>&1 &`
+          `cd ${dir} && nohup uvicorn main:app --host 0.0.0.0 --port ${port} > app.log 2>&1 &`
         );
       } else {
         await exec(ssh, 'pkill gunicorn || true');
@@ -166,17 +181,17 @@ export function createSshProvider(config, envName, env = process.env) {
           framework === 'django' ? 'config.wsgi:application' : 'app:app';
         await exec(
           ssh,
-          `cd ${targetPath} && nohup gunicorn ${appTarget} --bind 0.0.0.0:${port} --daemon`
+          `cd ${dir} && nohup gunicorn ${appTarget} --bind 0.0.0.0:${port} --daemon`
         );
       }
       return;
     }
 
     if (PHP_FRAMEWORKS.has(framework)) {
-      await exec(ssh, `cd ${targetPath} && composer install --no-dev`);
+      await exec(ssh, `cd ${dir} && composer install --no-dev`);
       if (framework === 'laravel') {
-        await exec(ssh, `cd ${targetPath} && php artisan migrate --force`);
-        await exec(ssh, `cd ${targetPath} && php artisan config:cache`);
+        await exec(ssh, `cd ${dir} && php artisan migrate --force`);
+        await exec(ssh, `cd ${dir} && php artisan config:cache`);
       }
       await exec(ssh, 'sudo systemctl restart php8.2-fpm');
       await exec(ssh, 'sudo systemctl reload nginx');
@@ -184,69 +199,130 @@ export function createSshProvider(config, envName, env = process.env) {
     }
 
     if (framework === 'spring' || framework === 'java') {
-      await exec(ssh, `cd ${targetPath} && pkill -f "*.jar" || true`);
+      await exec(ssh, `cd ${dir} && pkill -f "*.jar" || true`);
       await exec(
         ssh,
-        `cd ${targetPath} && nohup java -jar target/*.jar > app.log 2>&1 &`
+        `cd ${dir} && nohup java -jar target/*.jar > app.log 2>&1 &`
       );
       return;
     }
 
     if (framework === 'go') {
-      await exec(ssh, `cd ${targetPath} && pkill ${appName} || true`);
+      await exec(ssh, `cd ${dir} && pkill ${sh(appName)} || true`);
       await exec(
         ssh,
-        `cd ${targetPath} && nohup ./bin/app > app.log 2>&1 &`
+        `cd ${dir} && nohup ./bin/app > app.log 2>&1 &`
       );
       return;
     }
 
     if (framework === 'dotnet') {
-      await exec(ssh, `cd ${targetPath} && pkill -f "dotnet" || true`);
+      await exec(ssh, `cd ${dir} && pkill -f "dotnet" || true`);
       const dll = startCommand?.replace('dotnet ', '') || 'App.dll';
       await exec(
         ssh,
-        `cd ${targetPath} && nohup dotnet ${dll} > app.log 2>&1 &`
+        `cd ${dir} && nohup dotnet ${dll} > app.log 2>&1 &`
       );
       return;
     }
 
     if (framework === 'rails') {
-      await exec(ssh, `cd ${targetPath} && bundle install --deployment`);
-      await exec(ssh, `cd ${targetPath} && pkill puma || true`);
+      await exec(ssh, `cd ${dir} && bundle install --deployment`);
+      await exec(ssh, `cd ${dir} && pkill puma || true`);
       await exec(
         ssh,
-        `cd ${targetPath} && nohup bundle exec puma -p ${port} > app.log 2>&1 &`
+        `cd ${dir} && nohup bundle exec puma -p ${port} > app.log 2>&1 &`
       );
       return;
     }
 
-    await exec(ssh, `cd ${targetPath} && npm install --production`);
+    await exec(ssh, `cd ${dir} && npm install --production`);
     await exec(
       ssh,
-      `cd ${targetPath} && pm2 restart ${appName} || pm2 start npm --name "${appName}" -- start`
+      `cd ${dir} && pm2 restart ${sh(appName)} || pm2 start npm --name ${sh(appName)} -- start`
     );
     await exec(ssh, 'pm2 save');
   }
 
+  /**
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @param {string} remotePath
+   * @param {'f'|'d'} [kind='f']
+   */
+  async function remotePathExists(ssh, remotePath, kind = 'f') {
+    const flag = kind === 'd' ? '-d' : '-f';
+    const result = await ssh.execCommand(`test ${flag} ${sh(remotePath)} && echo yes`);
+    return result.code === 0 && result.stdout.trim() === 'yes';
+  }
+
+  /**
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @param {string} command
+   */
+  async function remoteCommandExists(ssh, command) {
+    const result = await ssh.execCommand(`command -v ${sh(command)} >/dev/null 2>&1 && echo yes`);
+    return result.code === 0 && result.stdout.trim() === 'yes';
+  }
+
+  /**
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @returns {Promise<'debian'|'rhel'>}
+   */
+  async function detectNginxLayout(ssh) {
+    if (await remotePathExists(ssh, '/etc/nginx/sites-available', 'd')) {
+      return 'debian';
+    }
+    return 'rhel';
+  }
+
+  /**
+   * @param {import('node-ssh').NodeSSH} ssh
+   */
+  async function reloadNginx(ssh) {
+    await exec(ssh, 'sudo systemctl reload nginx 2>/dev/null || sudo nginx -s reload');
+  }
+
   /**
    * @param {import('node-ssh').NodeSSH} ssh
    * @param {string} targetPath
    */
   async function setupNginx(ssh, targetPath) {
-    const sitePath = getNginxSitePath(config.project);
     const nginxConfRemote = `${targetPath}/nginx.conf`;
 
-    await exec(
-      ssh,
-      `sudo cp ${nginxConfRemote} ${sitePath} 2>/dev/null || sudo cp ${targetPath}/nginx.conf ${sitePath}`
-    );
-    await exec(
-      ssh,
-      `sudo ln -sf ${sitePath} /etc/nginx/sites-enabled/${path.basename(sitePath)}`
+    if (!(await remoteCommandExists(ssh, 'nginx'))) {
+      throw new Error(
+        'Nginx is not installed on the server. Install it first (e.g. sudo yum install nginx on Amazon Linux, or sudo apt install nginx on Ubuntu), then re-run deploy.'
+      );
+    }
+
+    if (!(await remotePathExists(ssh, nginxConfRemote))) {
+      throw new Error(
+        `Nginx config not found at ${nginxConfRemote} — artifact may be missing nginx.conf.`
+      );
+    }
+
+    const layout = await detectNginxLayout(ssh);
+    log.info(
+      layout === 'debian'
+        ? 'Detected Nginx layout: Debian/Ubuntu (sites-available)'
+        : 'Detected Nginx layout: RHEL/Amazon Linux (conf.d)'
     );
+
+    if (layout === 'debian') {
+      const sitePath = getNginxSitesAvailablePath(config.project);
+      const enabledPath = getNginxSitesEnabledPath(config.project);
+      await exec(ssh, `sudo cp ${sh(nginxConfRemote)} ${sh(sitePath)}`);
+      await exec(ssh, `sudo ln -sf ${sh(sitePath)} ${sh(enabledPath)}`);
+      log.info(`Nginx config installed: ${sitePath}`);
+    } else {
+      const confPath = getNginxConfDPath(config.project);
+      await exec(ssh, `sudo cp ${sh(nginxConfRemote)} ${sh(confPath)}`);
+      log.info(`Nginx config installed: ${confPath}`);
+    }
+
     await exec(ssh, 'sudo nginx -t');
-    await exec(ssh, 'sudo systemctl reload nginx');
+    await reloadNginx(ssh);
+    log.success('Nginx config tested and reloaded');
   }
 
   /**
@@ -255,8 +331,8 @@ export function createSshProvider(config, envName, env = process.env) {
    * @param {string} targetPath
    */
   async function extractToPath(ssh, remoteZip, targetPath) {
-    await exec(ssh, `mkdir -p ${targetPath}`);
-    await exec(ssh, `unzip -o ${remoteZip} -d ${targetPath}`);
+    await exec(ssh, `mkdir -p ${sh(targetPath)}`);
+    await exec(ssh, `unzip -o ${sh(remoteZip)} -d ${sh(targetPath)}`);
   }
 
   /**
@@ -276,19 +352,19 @@ export function createSshProvider(config, envName, env = process.env) {
 
       if (projectType === 'both') {
         const remoteStaging = `/tmp/deployhub-staging-${Date.now()}`;
-        await exec(ssh, `mkdir -p ${remoteStaging}`);
-        await exec(ssh, `unzip -o ${remoteZip} -d ${remoteStaging}`);
+        await exec(ssh, `mkdir -p ${sh(remoteStaging)}`);
+        await exec(ssh, `unzip -o ${sh(remoteZip)} -d ${sh(remoteStaging)}`);
 
-        await exec(ssh, `mkdir -p ${frontendDeployPath}`);
+        await exec(ssh, `mkdir -p ${sh(frontendDeployPath)}`);
         await exec(
           ssh,
-          `rsync -a ${remoteStaging}/ ${frontendDeployPath}/ --exclude backend || cp -r ${remoteStaging}/* ${frontendDeployPath}/`
+          `rsync -a ${sh(remoteStaging)}/ ${sh(frontendDeployPath)}/ --exclude backend || cp -r ${sh(remoteStaging)}/* ${sh(frontendDeployPath)}/`
         );
 
-        await exec(ssh, `mkdir -p ${backendDeployPath}`);
+        await exec(ssh, `mkdir -p ${sh(backendDeployPath)}`);
         await exec(
           ssh,
-          `rsync -a ${remoteStaging}/backend/ ${backendDeployPath}/ || cp -r ${remoteStaging}/backend/* ${backendDeployPath}/`
+          `rsync -a ${sh(remoteStaging)}/backend/ ${sh(backendDeployPath)}/ || cp -r ${sh(remoteStaging)}/backend/* ${sh(backendDeployPath)}/`
         );
 
         if (await remoteFileExists(ssh, `${frontendDeployPath}/nginx.conf`)) {
@@ -296,7 +372,7 @@ export function createSshProvider(config, envName, env = process.env) {
         }
 
         await runBackendStartSequence(ssh, backendDeployPath);
-        await exec(ssh, `rm -rf ${remoteStaging}`);
+        await exec(ssh, `rm -rf ${sh(remoteStaging)}`);
       } else if (projectType === 'backend') {
         log.info(`Backend deploy path: ${deployPath}`);
         await extractToPath(ssh, remoteZip, deployPath);
@@ -313,7 +389,7 @@ export function createSshProvider(config, envName, env = process.env) {
         }
       }
 
-      await exec(ssh, `rm -f ${remoteZip}`);
+      await exec(ssh, `rm -f ${sh(remoteZip)}`);
       log.success('Deployment complete');
     } finally {
       ssh.dispose();
@@ -325,8 +401,8 @@ export function createSshProvider(config, envName, env = process.env) {
    * @param {string} remotePath
    */
   async function remoteFileExists(ssh, remotePath) {
-    const result = await ssh.execCommand(`test -f ${remotePath} && echo yes`);
-    return result.stdout.trim() === 'yes';
+    const result = await ssh.execCommand(`test -f ${sh(remotePath)} && echo yes`);
+    return result.code === 0 && result.stdout.trim() === 'yes';
   }
 
   async function rollback(artifactDir) {
@@ -339,7 +415,7 @@ export function createSshProvider(config, envName, env = process.env) {
 
     const ssh = await connect();
     try {
-      const result = await ssh.execCommand(`curl -sf -o /dev/null -w "%{http_code}" "${url}"`);
+      const result = await ssh.execCommand(`curl -sf -o /dev/null -w "%{http_code}" ${sh(url)}`);
       return result.stdout.trim().startsWith('2');
     } finally {
       ssh.dispose();

package/src/utils/nginx.js

@@ -1,3 +1,12 @@
+/**
+ * Sanitize a project name for use in Nginx config file paths.
+ * @param {string} projectName
+ * @returns {string}
+ */
+export function sanitizeNginxProjectName(projectName) {
+  return projectName.replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+
 /**
  * Generate nginx server block config for SPA frontend deployments.
  *
@@ -22,13 +31,61 @@ export function generateNginxConfig(projectName, deployPath, buildOutput = 'dist
 `;
 }
 
+/**
+ * Debian/Ubuntu: sites-available path for this project.
+ * @param {string} projectName
+ * @returns {string}
+ */
+export function getNginxSitesAvailablePath(projectName) {
+  return `/etc/nginx/sites-available/${sanitizeNginxProjectName(projectName)}`;
+}
+
+/**
+ * Debian/Ubuntu: sites-enabled symlink path for this project.
+ * @param {string} projectName
+ * @returns {string}
+ */
+export function getNginxSitesEnabledPath(projectName) {
+  return `/etc/nginx/sites-enabled/${sanitizeNginxProjectName(projectName)}`;
+}
+
+/**
+ * RHEL/Amazon Linux: conf.d drop-in path for this project.
+ * @param {string} projectName
+ * @returns {string}
+ */
+export function getNginxConfDPath(projectName) {
+  return `/etc/nginx/conf.d/${sanitizeNginxProjectName(projectName)}.conf`;
+}
+
 /**
  * @param {string} projectName
  * @returns {string}
  */
 export function getNginxSitePath(projectName) {
-  const safeName = projectName.replace(/[^a-zA-Z0-9_-]/g, '-');
-  return `/etc/nginx/sites-available/${safeName}`;
+  return getNginxSitesAvailablePath(projectName);
+}
+
+/**
+ * @param {string} sshUser
+ * @returns {string}
+ */
+export function formatPasswordlessSudoGuidance(sshUser) {
+  return (
+    `Passwordless sudo required to activate Nginx config during deploy.\n` +
+    `  On your server, run sudo visudo and add a line like:\n` +
+    `    ${sshUser} ALL=(ALL) NOPASSWD: /usr/sbin/nginx, /bin/cp, /usr/bin/cp, /bin/systemctl, /usr/bin/systemctl\n` +
+    `  (replace ${sshUser} with your SSH_USER)\n` +
+    `  Security: this grants broad cp/systemctl access — see README one-time server setup for a production-hardening note.`
+  );
 }
 
-export default { generateNginxConfig, getNginxSitePath };
+export default {
+  generateNginxConfig,
+  sanitizeNginxProjectName,
+  getNginxSitesAvailablePath,
+  getNginxSitesEnabledPath,
+  getNginxConfDPath,
+  getNginxSitePath,
+  formatPasswordlessSudoGuidance,
+};

package/src/utils/shell-quote.js

@@ -0,0 +1,64 @@
+/**
+ * Wrap a value for safe interpolation into a POSIX shell command string.
+ * Uses single quotes; embedded single quotes are escaped as '\''.
+ * @param {string} value
+ * @returns {string}
+ */
+export function shellQuote(value) {
+  if (value == null) return "''";
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * @param {string} command
+ * @param {number|null|undefined} code
+ * @param {string} [stderr]
+ * @param {string} [stdout]
+ * @returns {string}
+ */
+export function formatRemoteCommandFailure(command, code, stderr, stdout) {
+  const cmdName = command.trim().split(/\s+/)[0] || 'command';
+  const detail = (stderr || stdout || '').trim();
+  return `Deploy failed: ${cmdName} exited with code ${code}${detail ? `: ${detail}` : ''}`;
+}
+
+/**
+ * Remote shell command that verifies write access to a deploy directory.
+ * @param {string} deployPath
+ * @returns {string}
+ */
+export function buildDeployPathWriteTestCommand(deployPath) {
+  const dir = shellQuote(deployPath);
+  const testFile = shellQuote(`${deployPath}/.deployhub-write-test`);
+  return `mkdir -p ${dir} && touch ${testFile} && rm -f ${testFile}`;
+}
+
+/**
+ * @param {string} deployPath
+ * @param {string} sshUser
+ * @param {string} [errorDetail]
+ * @returns {string}
+ */
+export function formatDeployPathWriteFailure(deployPath, sshUser, errorDetail) {
+  const reason = errorDetail ? ` (${errorDetail.trim()})` : '';
+  const quotedPath = shellQuote(deployPath);
+  return (
+    `Cannot write to ${deployPath} on the server${reason}.\n` +
+    `  Run this on your server first:\n` +
+    `    sudo mkdir -p ${quotedPath}\n` +
+    `    sudo chown ${sshUser}:${sshUser} ${quotedPath}\n` +
+    `  (replace ${sshUser} with your actual SSH_USER if different)`
+  );
+}
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+export function toKebabCase(name) {
+  return name
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-zA-Z0-9-_]/g, '')
+    .toLowerCase();
+}