@akash-chowdhury-24/deployhub 2.0.30 → 2.0.32

package/README.md

@@ -855,7 +855,7 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 1. Set `DOCKER_IMAGE_NAME` in `.env` (e.g. `myuser/myapp` for Docker Hub)
 2. For private registries (or any push): set `DOCKER_REGISTRY_USERNAME` and `DOCKER_REGISTRY_TOKEN`
 3. Leave `DOCKER_IMAGE_TAG` unset for a unique tag each build — set it only if you intentionally want a fixed tag
-4. For remote Docker: set `DOCKER_HOST` (e.g. `ssh://ubuntu@203.0.113.10`)
+4. For a remote Linux host, choose **Remote Linux server via SSH** at init (`remote.mode: "ssh"`) and set `SSH_HOST`, `SSH_USER`, `SSH_KEY_PATH` — DeployHub runs `docker pull`/`run` over node-ssh. Use `DOCKER_HOST` only for the advanced raw CLI transport (`tcp://` or a custom `ssh://` setup you already manage)
 5. Run `deployhub doctor`, then `git push origin main`
 
 | Variable | Description | Example | Where to get it |
@@ -865,7 +865,8 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 | `DOCKER_REGISTRY_URL` | Registry URL (optional) | `https://ghcr.io` | Registry docs |
 | `DOCKER_REGISTRY_USERNAME` | Registry user | `myuser` | Registry account |
 | `DOCKER_REGISTRY_TOKEN` | Registry password/token | *(secret)* | Docker Hub / GHCR PAT |
-| `DOCKER_HOST` | Remote daemon (optional) | `ssh://ubuntu@host` | Remote Docker setup |
+| `DOCKER_HOST` | Advanced raw daemon URI (optional) | `tcp://host:2376` | Only if you manage TLS/ssh:// yourself |
+| `SSH_HOST` / `SSH_USER` / `SSH_KEY_PATH` | Remote Linux via SSH (`remote.mode: ssh`) | `203.0.113.10` / `ubuntu` / `~/.ssh/key.pem` | Same names as EC2 |
 
 ### AWS EC2
 

package/package.json

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

package/src/artifact/engine.js

@@ -19,7 +19,6 @@ import {
   getEnvSettings,
   resolveDefaultEnvironmentName,
 } from '../core/config.js';
-import { detectDjangoWsgiPackageDir } from '../utils/python-app-target.js';
 
 /**
  * @param {string} cwd
@@ -183,66 +182,117 @@ async function stageFrontendArtifact(cwd, stagingDir, config) {
  * @param {string} stagingDir
  * @param {import('../core/config.js').DeployHubConfig} config
  */
+/** Dirs/files that must never be packed into a backend artifact. */
+const BACKEND_STAGE_EXCLUDE = new Set([
+  'node_modules',
+  '.git',
+  '.github',
+  'artifact',
+  '.deployhub',
+  '.deployhub-storage',
+  '.deployhub-restore',
+  '.deployhub-doctor-test',
+  'coverage',
+  '.venv',
+  'venv',
+  '__pycache__',
+  'vendor',
+  '.idea',
+  '.vscode',
+  '.nyc_output',
+]);
+
+/**
+ * Copy the backend project tree into staging, skipping install caches and VCS.
+ * Allowlists previously omitted root entrypoints (server.js, main.go, index.php)
+ * which made SSH `npm start` / binary start fail even though CI built fine.
+ *
+ * @param {string} cwd
+ * @param {string} stagingDir
+ * @param {Set<string>} extraExclude
+ */
+async function copyBackendSourceTree(cwd, stagingDir, extraExclude = new Set()) {
+  const exclude = new Set([...BACKEND_STAGE_EXCLUDE, ...extraExclude]);
+  let entries = [];
+  try {
+    entries = await fs.readdir(cwd, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const ent of entries) {
+    if (exclude.has(ent.name)) continue;
+    if (ent.name.startsWith('.env') && ent.name !== '.env.example') continue;
+    const src = path.join(cwd, ent.name);
+    const dest = path.join(stagingDir, ent.name);
+    if (ent.isDirectory()) {
+      await fs.copy(src, dest, {
+        filter: (p) => {
+          const base = path.basename(p);
+          if (exclude.has(base)) return false;
+          if (base === '__pycache__' || base === 'node_modules' || base === '.git') {
+            return false;
+          }
+          return true;
+        },
+      });
+    } else {
+      await fs.copy(src, dest);
+    }
+  }
+}
+
+/**
+ * @param {string} stagingDir
+ */
+async function removeStagingDir(stagingDir) {
+  let lastErr;
+  for (let attempt = 0; attempt < 6; attempt++) {
+    try {
+      await fs.remove(stagingDir);
+      return;
+    } catch (err) {
+      lastErr = err;
+      await new Promise((r) => setTimeout(r, 50 * (attempt + 1)));
+    }
+  }
+  const message = lastErr instanceof Error ? lastErr.message : String(lastErr);
+  createLogger('artifact').warn(
+    `Could not remove staging dir after zip (artifact is still valid): ${message}`
+  );
+}
+
 async function stageBackendArtifact(cwd, stagingDir, config) {
   const settings = resolveBuildSettings(config);
   const framework = settings.framework;
 
-  await copyDirectoryIfExists(cwd, stagingDir, 'src');
-
-  for (const file of ['Dockerfile', 'docker-compose.yml', '.env.example']) {
-    await copyIfExists(cwd, stagingDir, file);
+  /** @type {Set<string>} */
+  const extraExclude = new Set();
+  // Compiled output is re-added selectively below (jars / publish / bin).
+  if (framework === 'spring' || framework === 'java') extraExclude.add('target');
+  if (framework === 'dotnet') {
+    extraExclude.add('bin');
+    extraExclude.add('obj');
   }
 
+  await copyBackendSourceTree(cwd, stagingDir, extraExclude);
+
   await copyKubernetesManifestsIfPresent(cwd, stagingDir);
 
-  await copyDirectoryIfExists(cwd, stagingDir, 'config');
-  await copyDirectoryIfExists(cwd, stagingDir, 'migrations');
-
-  if (['express', 'nestjs', 'fastify', 'koa', 'nextjs'].includes(framework)) {
-    await copyIfExists(cwd, stagingDir, 'package.json');
-    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');
-    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);
+  if (['laravel', 'symfony', 'php'].includes(framework)) {
+    // storage/logs is written by php-fpm (www-data). Packing live logs is useless
+    // and unpacking them on the next deploy is a common permission-denied unzip.
+    const logsDir = path.join(stagingDir, 'storage', 'logs');
+    if (await fs.pathExists(logsDir)) {
+      const logFiles = await fs.readdir(logsDir);
+      for (const f of logFiles) {
+        if (f === '.gitignore') continue;
+        await fs.remove(path.join(logsDir, f));
       }
     }
-  } 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' || framework === 'java') {
-    await copyIfExists(cwd, stagingDir, 'pom.xml');
+  }
+
+  if (framework === 'spring' || framework === 'java') {
     const targetDir = path.join(cwd, 'target');
     if (await fs.pathExists(targetDir)) {
       await fs.ensureDir(path.join(stagingDir, 'target'));
@@ -251,37 +301,20 @@ async function stageBackendArtifact(cwd, stagingDir, config) {
         await fs.copy(path.join(targetDir, jar), path.join(stagingDir, 'target', jar));
       }
     }
-  } else if (framework === 'go') {
-    await copyIfExists(cwd, stagingDir, 'go.mod');
-    await copyIfExists(cwd, stagingDir, 'go.sum');
-    await copyDirectoryIfExists(cwd, stagingDir, 'bin');
   } else if (framework === 'dotnet') {
-    const files = await fs.readdir(cwd);
-    for (const f of files.filter((name) => name.endsWith('.csproj'))) {
-      await copyIfExists(cwd, stagingDir, f);
-    }
     await copyDirectoryIfExists(cwd, stagingDir, settings.buildOutput || 'publish');
-  } else if (framework === 'rails' || framework === 'ruby') {
-    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/.
+  // Named build-output dir (nestjs dist/, etc.) when it exists and was not excluded.
   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)) {
-      await fs.copy(built, path.join(stagingDir, settings.buildOutput));
+    const staged = path.join(stagingDir, settings.buildOutput);
+    if (
+      (await fs.pathExists(built)) &&
+      !(await fs.pathExists(staged)) &&
+      !['target', 'bin', 'publish'].includes(settings.buildOutput)
+    ) {
+      await fs.copy(built, staged);
     }
   }
 }
@@ -417,18 +450,13 @@ ${getArtifactReadmeFooter()}`;
   const checksums = await generateChecksums(stagingDir);
   const checksumContent = formatChecksums(checksums);
   await fs.writeFile(path.join(artifactDir, 'checksums.txt'), checksumContent);
-  await fs.writeFile(path.join(stagingDir, 'checksums.txt'), checksumContent);
   await fs.writeJson(
-    path.join(stagingDir, 'deployment.json'),
+    path.join(artifactDir, 'deployment.json'),
     { targets: deployedTargets, deployedAt: timestamp },
     { spaces: 2 }
   );
-  await fs.writeFile(
-    path.join(stagingDir, 'release-notes.md'),
-    await getReleaseNotes(cwd)
-  );
 
-  await fs.remove(stagingDir);
+  await removeStagingDir(stagingDir);
   log.success(`Artifact created at ${artifactDir}`);
 
   return { artifactDir, zipPath };

package/src/commands/doctor.js

@@ -31,6 +31,15 @@ import { formatPasswordlessSudoGuidance } from '../utils/nginx.js';
 import { checkImagePullability } from '../utils/docker-image-deploy.js';
 import { namespaceExists } from '../utils/kubernetes-namespace.js';
 import { resolvePhpVersion } from '../utils/php-version.js';
+import {
+  resolveDockerSshTarget,
+  probeRemoteDockerPs,
+  formatRemoteDockerSshFailure,
+  formatRemoteDockerNotInstalled,
+  formatRemoteDockerPermissionDenied,
+  formatRemoteDockerDaemonOk,
+} from '../utils/docker-remote.js';
+import { resolveDockerRemoteMode } from '../utils/docker-remote-mode.js';
 import {
   buildPhpFpmUnitListCommand,
   formatPhpFpmMissingError,
@@ -183,14 +192,16 @@ export async function runDeploymentChecks(config, envName, envConfig) {
 
   /** @type {CheckResult[]} */
   const checks = [];
-  const requiredKeys = getDeploymentEnvKeys(deployType, config);
+  const requiredKeys = getDeploymentEnvKeys(deployType, config, settings);
 
   checks.push(
     await runCheck(`${deployType} env vars`, async () => {
       const missing = requiredKeys.filter((k) => {
         if (k === 'SSH_KEY_PATH') {
-          return !process.env.SSH_KEY_PATH && !process.env.SSH_KEY;
+          return !process.env.SSH_KEY_PATH && !process.env.SSH_KEY && !settings.keyPath;
         }
+        if (k === 'SSH_HOST') return !(settings.host || process.env.SSH_HOST);
+        if (k === 'SSH_USER') return !(settings.user || process.env.SSH_USER);
         return !process.env[k];
       });
       if (missing.length > 0) {
@@ -447,22 +458,139 @@ export async function runDeploymentChecks(config, envName, envConfig) {
   }
 
   if (deployType === 'docker') {
-    checks.push(
-      await runCheck('Docker daemon', async () => {
-        try {
-          const provider = getDeploymentProvider('docker', config, envName);
-          await provider.testConnection();
-          return { name: 'Docker daemon', pass: true, message: 'Docker daemon reachable' };
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : String(err);
+    const dockerRemoteMode = resolveDockerRemoteMode(settings, process.env);
+
+    if (dockerRemoteMode === 'ssh') {
+      const target = resolveDockerSshTarget(settings, process.env);
+      const host = target.host;
+      const user = target.user;
+      const keyPath = target.keyPath;
+      const sshPort = target.sshPort;
+
+      checks.push(
+        await runCheck('SSH key', async () => {
+          const result = await validateSshKeyForDoctor(
+            keyPath ? String(keyPath) : undefined,
+            process.env.SSH_KEY
+          );
+          return {
+            name: 'SSH key',
+            pass: result.ok,
+            message: result.message,
+          };
+        })
+      );
+
+      checks.push(
+        await runCheck('SSH host reachability', async () => {
+          if (!host) {
+            return {
+              name: 'SSH host reachability',
+              pass: false,
+              message: 'SSH_HOST is required — set it in .env to your server IP or hostname.',
+            };
+          }
+          const result = await testSshHostReachability(String(host), sshPort);
+          return {
+            name: 'SSH host reachability',
+            pass: result.ok,
+            message: result.message,
+          };
+        })
+      );
+
+      checks.push(
+        await runCheck('Remote Docker daemon reachable', async () => {
+          const probe = await probeRemoteDockerPs(target);
+          if (!probe.sshOk) {
+            return {
+              name: 'Remote Docker daemon reachable',
+              pass: false,
+              message: formatRemoteDockerSshFailure(host, user),
+            };
+          }
+          if (probe.kind === 'not-installed') {
+            return {
+              name: 'Remote Docker daemon reachable',
+              pass: false,
+              message: formatRemoteDockerNotInstalled(host, user),
+            };
+          }
+          if (probe.kind === 'ok' || probe.kind === 'permission') {
+            return {
+              name: 'Remote Docker daemon reachable',
+              pass: true,
+              message: formatRemoteDockerDaemonOk(host, user),
+            };
+          }
           return {
-            name: 'Docker daemon',
+            name: 'Remote Docker daemon reachable',
             pass: false,
-            message: `Docker not reachable — ${msg}. Install Docker or set DOCKER_HOST for a remote daemon.`,
+            message:
+              probe.detail ||
+              `Remote Docker daemon is not reachable (${user}@${host}).`,
           };
-        }
-      })
-    );
+        })
+      );
+
+      checks.push(
+        await runCheck('Remote Docker permission', async () => {
+          const probe = await probeRemoteDockerPs(target);
+          if (!probe.sshOk) {
+            return {
+              name: 'Remote Docker permission',
+              pass: false,
+              message: formatRemoteDockerSshFailure(host, user),
+            };
+          }
+          if (probe.kind === 'permission') {
+            return {
+              name: 'Remote Docker permission',
+              pass: false,
+              message: formatRemoteDockerPermissionDenied(host, user),
+            };
+          }
+          if (probe.kind === 'ok') {
+            return {
+              name: 'Remote Docker permission',
+              pass: true,
+              message: `SSH user '${user}' can access the Docker daemon on ${host}`,
+            };
+          }
+          if (probe.kind === 'not-installed') {
+            return {
+              name: 'Remote Docker permission',
+              pass: false,
+              message: formatRemoteDockerNotInstalled(host, user),
+            };
+          }
+          return {
+            name: 'Remote Docker permission',
+            pass: false,
+            message:
+              probe.detail ||
+              `Cannot verify Docker permissions for '${user}' on ${host}.`,
+          };
+        })
+      );
+    } else {
+      checks.push(
+        await runCheck('Docker daemon', async () => {
+          try {
+            const provider = getDeploymentProvider('docker', config, envName);
+            await provider.testConnection();
+            return { name: 'Docker daemon', pass: true, message: 'Docker daemon reachable' };
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+              name: 'Docker daemon',
+              pass: false,
+              message: `Docker not reachable — ${msg}. Install Docker or set DOCKER_HOST for a remote daemon.`,
+            };
+          }
+        })
+      );
+    }
   }
 
   if (deployType === 'kubernetes') {
@@ -644,7 +772,6 @@ async function runBackendProcessChecks(config, envName, deployType = 'ssh') {
 
     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'
         );
@@ -661,24 +788,11 @@ async function runBackendProcessChecks(config, envName, deployType = 'ssh') {
       })
     );
 
-    checks.push(
-      await runCheck('gunicorn', async () => {
-        const result = await provider.runRemoteCheck('which gunicorn || gunicorn --version');
-        if (result.pass) {
-          return { name: 'gunicorn', pass: true, message: 'gunicorn available' };
-        }
-        return {
-          name: 'gunicorn',
-          pass: false,
-          message: 'not found — run: pip install gunicorn',
-        };
-      })
-    );
-
+    // FastAPI SSH starts uvicorn, not gunicorn. Requiring gunicorn here is a false failure.
     if (framework === 'fastapi') {
       checks.push(
         await runCheck('uvicorn', async () => {
-          const result = await provider.runRemoteCheck('which uvicorn || uvicorn --version');
+          const result = await provider.runRemoteCheck('command -v uvicorn >/dev/null 2>&1 || uvicorn --version');
           if (result.pass) {
             return { name: 'uvicorn', pass: true, message: 'uvicorn available' };
           }
@@ -689,6 +803,20 @@ async function runBackendProcessChecks(config, envName, deployType = 'ssh') {
           };
         })
       );
+    } else {
+      checks.push(
+        await runCheck('gunicorn', async () => {
+          const result = await provider.runRemoteCheck('command -v gunicorn >/dev/null 2>&1 || gunicorn --version');
+          if (result.pass) {
+            return { name: 'gunicorn', pass: true, message: 'gunicorn available' };
+          }
+          return {
+            name: 'gunicorn',
+            pass: false,
+            message: 'not found — run: pip install gunicorn',
+          };
+        })
+      );
     }
   }
 
@@ -767,7 +895,7 @@ async function runBackendProcessChecks(config, envName, deployType = 'ssh') {
         }
 
         const active = await provider.runRemoteCheck(
-          `systemctl is-active ${pick.unit}`
+          `sudo -n systemctl is-active ${pick.unit}`
         );
         if (active.pass && String(active.message).includes('active')) {
           const note =
@@ -793,11 +921,28 @@ async function runBackendProcessChecks(config, envName, deployType = 'ssh') {
 
     checks.push(
       await runCheck('nginx', async () => {
-        const result = await provider.runRemoteCheck('systemctl is-active nginx');
+        const installed = await provider.runRemoteCheck(
+          'command -v nginx >/dev/null 2>&1 && echo yes'
+        );
+        if (!installed.pass || !String(installed.message).includes('yes')) {
+          return {
+            name: 'nginx',
+            pass: false,
+            message:
+              'nginx not found on PATH — install it (Amazon Linux: sudo dnf install -y nginx; Ubuntu: sudo apt install nginx), then: sudo systemctl enable --now nginx',
+          };
+        }
+        const result = await provider.runRemoteCheck('sudo -n systemctl is-active nginx');
         if (result.pass && result.message.includes('active')) {
           return { name: 'nginx', pass: true, message: 'nginx running' };
         }
-        return { name: 'nginx', pass: false, message: 'nginx not running' };
+        return {
+          name: 'nginx',
+          pass: false,
+          message:
+            `nginx is installed but not active (systemctl is-active: ${result.message}). ` +
+            'Start it with: sudo systemctl enable --now nginx',
+        };
       })
     );
   }
@@ -823,6 +968,53 @@ async function runBackendProcessChecks(config, envName, deployType = 'ssh') {
     );
   }
 
+  if (framework === 'dotnet') {
+    checks.push(
+      await runCheck('.NET runtime', async () => {
+        const result = await provider.runRemoteCheck('dotnet --version');
+        if (result.pass) {
+          return { name: '.NET runtime', pass: true, message: `dotnet ${result.message.split('\n')[0] || 'found'}` };
+        }
+        return {
+          name: '.NET runtime',
+          pass: false,
+          message:
+            'dotnet not found on PATH — install the ASP.NET Core runtime on the server ' +
+            '(SSH deploy runs `dotnet <dll>` after extract)',
+        };
+      })
+    );
+  }
+
+  if (framework === 'rails' || framework === 'ruby') {
+    checks.push(
+      await runCheck('Ruby', async () => {
+        const result = await provider.runRemoteCheck('command -v ruby >/dev/null 2>&1 && ruby -v');
+        if (result.pass) {
+          return { name: 'Ruby', pass: true, message: result.message.split('\n')[0] || 'ruby found' };
+        }
+        return {
+          name: 'Ruby',
+          pass: false,
+          message: 'ruby not found on PATH — install Ruby 3.2+ on the server (SSH deploy runs bundle install)',
+        };
+      })
+    );
+    checks.push(
+      await runCheck('Bundler', async () => {
+        const result = await provider.runRemoteCheck('command -v bundle');
+        if (result.pass) {
+          return { name: 'Bundler', pass: true, message: 'bundle found on PATH' };
+        }
+        return {
+          name: 'Bundler',
+          pass: false,
+          message: 'bundle not found on PATH — run: gem install bundler',
+        };
+      })
+    );
+  }
+
   return checks;
 }
 
@@ -1078,7 +1270,9 @@ export function registerDoctorCommand(program) {
             const method = getEnvMethod(env);
             if (!method) continue;
             // Local/.env uses unprefixed names; prefixed CI names are checked separately below.
-            required.push(...getDeploymentSecretKeys(method, config));
+            required.push(
+              ...getDeploymentSecretKeys(method, config, getEnvSettings(env))
+            );
           }
 
           const unique = [...new Set(required)];
@@ -1115,7 +1309,7 @@ export function registerDoctorCommand(program) {
             config,
             config.environments
           );
-          const baseKeys = getDeploymentSecretKeys(method, config);
+          const baseKeys = getDeploymentSecretKeys(method, config, getEnvSettings(env));
 
           for (let i = 0; i < baseKeys.length; i++) {
             const base = baseKeys[i];

package/src/core/config.js

@@ -54,6 +54,16 @@ const MethodConfigSchema = z
     dockerImageName: z.string().optional(),
     dockerRegistryUrl: z.string().optional(),
     dockerHost: z.string().optional(),
+    /**
+     * Docker-method only. Kubernetes must ignore this — it deploys via kubectl,
+     * never a remote Docker daemon. `ssh` = node-ssh + remote docker CLI;
+     * `local` = this machine; `raw` = unmanaged DOCKER_HOST (ssh:// or tcp://).
+     */
+    remote: z
+      .object({
+        mode: z.enum(['ssh', 'local', 'raw']),
+      })
+      .optional(),
     healthCheckUrl: z.string().optional(),
     appName: z.string().optional(),
     framework: z.string().optional(),