@akash-chowdhury-24/deployhub 2.0.2 → 2.0.3

package/README.md

@@ -610,20 +610,23 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 - [ ] 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`
 - 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 |
 |----------|-------------|---------|-----------------|
@@ -669,19 +672,22 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 - [ ] 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`
 - 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 |
 |----------|-------------|---------|-----------------|
@@ -699,18 +705,21 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 - [ ] 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`
 
 **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 |
 |----------|-------------|---------|-----------------|
@@ -727,18 +736,21 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 - [ ] 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`
 
 **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.3",
   "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,10 @@ import {
   getDeploymentSecretKeys,
 } from '../deployment/deployment-env.js';
 import { testSshConnectivity, validateSshKeyForDoctor, testSshHostReachability } from '../deployment/init-helpers.js';
+import {
+  buildDeployPathWriteTestCommand,
+  formatDeployPathWriteFailure,
+} from '../utils/shell-quote.js';
 
 /**
  * @typedef {{ name: string, pass: boolean, message: string }} CheckResult
@@ -56,6 +60,28 @@ 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
  * @param {string} envName
@@ -131,6 +157,56 @@ 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),
+          };
+        })
+      );
+    }
+
     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

@@ -4,6 +4,7 @@ import path from 'path';
 import os from 'os';
 import { createLogger } from '../../logger/index.js';
 import { getNginxSitePath } 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 +13,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 +91,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 +133,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 +161,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 +177,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,47 +195,47 @@ 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');
   }
@@ -239,11 +250,11 @@ export function createSshProvider(config, envName, env = process.env) {
 
     await exec(
       ssh,
-      `sudo cp ${nginxConfRemote} ${sitePath} 2>/dev/null || sudo cp ${targetPath}/nginx.conf ${sitePath}`
+      `sudo cp ${sh(nginxConfRemote)} ${sh(sitePath)} 2>/dev/null || sudo cp ${sh(`${targetPath}/nginx.conf`)} ${sh(sitePath)}`
     );
     await exec(
       ssh,
-      `sudo ln -sf ${sitePath} /etc/nginx/sites-enabled/${path.basename(sitePath)}`
+      `sudo ln -sf ${sh(sitePath)} ${sh(`/etc/nginx/sites-enabled/${path.basename(sitePath)}`)}`
     );
     await exec(ssh, 'sudo nginx -t');
     await exec(ssh, 'sudo systemctl reload nginx');
@@ -255,8 +266,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 +287,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 +307,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 +324,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 +336,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 +350,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/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();
+}