@akash-chowdhury-24/deployhub 2.0.7 → 2.0.9

package/package.json

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

package/src/commands/doctor.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { execa } from 'execa';
 import fs from 'fs-extra';
 import path from 'path';
+import os from 'os';
 import axios from 'axios';
 import { loadConfig, loadEnv } from '../core/config.js';
 import { testProvider } from '../storage/index.js';
@@ -19,6 +20,8 @@ import {
   formatDeployPathWriteFailure,
 } from '../utils/shell-quote.js';
 import { formatPasswordlessSudoGuidance } from '../utils/nginx.js';
+import { checkImagePullability } from '../utils/docker-image-deploy.js';
+import { namespaceExists } from '../utils/kubernetes-namespace.js';
 
 /**
  * @typedef {{ name: string, pass: boolean, message: string }} CheckResult
@@ -410,6 +413,66 @@ async function runDeploymentChecks(config, envName, envConfig) {
         }
       })
     );
+
+    checks.push(
+      await runCheck('Kubernetes namespace', async () => {
+        const ns = process.env.KUBE_NAMESPACE || config.project || 'default';
+        const kubeconfig =
+          process.env.KUBECONFIG || path.join(os.homedir(), '.kube', 'config');
+        const context = process.env.KUBE_CONTEXT || '';
+        const expanded = kubeconfig.replace(/^~/, os.homedir());
+        const kubectlEnv = { ...process.env, KUBECONFIG: path.resolve(expanded) };
+
+        /** @param {string[]} baseArgs */
+        function kubectlClusterArgs(baseArgs) {
+          const args = [...baseArgs];
+          if (context) args.push('--context', context);
+          return args;
+        }
+
+        const exists = await namespaceExists(ns, {
+          kubectlArgs: kubectlClusterArgs,
+          getKubectlEnv: () => kubectlEnv,
+        });
+
+        if (exists) {
+          return {
+            name: 'Kubernetes namespace',
+            pass: true,
+            message: `Namespace '${ns}' exists`,
+          };
+        }
+        return {
+          name: 'Kubernetes namespace',
+          pass: true,
+          message: `Namespace '${ns}' does not exist yet — deploy will prompt locally or auto-create in CI (kubectl create namespace ${ns})`,
+        };
+      })
+    );
+
+    checks.push(
+      await runCheck('Container image pullable', async () => {
+        const result = await checkImagePullability(config, process.env);
+        return {
+          name: 'Container image pullable',
+          pass: result.ok,
+          message: result.message,
+        };
+      })
+    );
+  }
+
+  if (deployType === 'docker' && process.env.DOCKER_REGISTRY_USERNAME && process.env.DOCKER_REGISTRY_TOKEN) {
+    checks.push(
+      await runCheck('Container image pullable', async () => {
+        const result = await checkImagePullability(config, process.env);
+        return {
+          name: 'Container image pullable',
+          pass: result.ok,
+          message: result.message,
+        };
+      })
+    );
   }
 
   if (deployType === 'ec2' && process.env.EC2_INSTANCE_ID) {

package/src/deployment/deployment-env.js

@@ -309,19 +309,18 @@ export const DEPLOYMENT_ENV_DEFS = {
       optionalReason: 'defaults to your project name or "default" if unset',
       comment: [
         'Kubernetes namespace for your deployment.',
-        'Create one first if needed: kubectl create namespace my-app',
+        'If missing, deployhub deploy prompts to create it locally (or auto-creates in CI).',
       ],
       example: 'my-app',
       when: 'optional',
     },
     {
       key: 'DOCKER_IMAGE_NAME',
-      optionalReason: 'only required if your manifests need an image override at deploy time',
       comment: [
-        'Container image to deploy (must match manifests or be overridden).',
+        'Container image to build, push, and deploy.',
+        'Kubernetes clusters pull from a registry — local-only Docker images will not work.',
       ],
       example: 'ghcr.io/myorg/myapp',
-      when: 'optional',
     },
     {
       key: 'DOCKER_IMAGE_TAG',
@@ -332,6 +331,30 @@ export const DEPLOYMENT_ENV_DEFS = {
       example: 'latest',
       when: 'optional',
     },
+    {
+      key: 'DOCKER_REGISTRY_URL',
+      optionalReason: 'leave empty for Docker Hub',
+      comment: [
+        'Container registry URL. Leave empty for Docker Hub.',
+        'Examples: https://index.docker.io/v1/ | https://ghcr.io',
+      ],
+      when: 'optional',
+    },
+    {
+      key: 'DOCKER_REGISTRY_USERNAME',
+      comment: [
+        'Registry username — required to push so the cluster can pull your image.',
+        'Even public Docker Hub repos require authentication to push.',
+      ],
+      example: 'myuser',
+    },
+    {
+      key: 'DOCKER_REGISTRY_TOKEN',
+      comment: [
+        'Registry password or personal access token — required to push so the cluster can pull.',
+        'Docker Hub: access token. GHCR: GitHub PAT with write:packages.',
+      ],
+    },
     {
       key: 'KUBE_IMAGE_PULL_SECRET',
       optionalReason: 'only required when pulling from a private container registry',
@@ -683,21 +706,27 @@ export const DEPLOYMENT_GUIDE = {
     before: [
       'An existing Kubernetes cluster (DeployHub does not provision clusters).',
       'kubectl installed and configured (kubectl cluster-info works).',
+      'A container registry account — clusters pull images from a registry, not your local Docker daemon.',
+      'Registry credentials (username + token) to push your image so the cluster can pull it.',
       'Kubernetes manifests (Deployment, Service, etc.) in your repo or artifact.',
       'Cluster access from CI: kubeconfig or cloud-specific auth for GitHub Actions.',
     ],
     automates: [
       'Lists available kubectl contexts during init so you pick from a menu.',
       'Auto-detects ~/.kube/config if present.',
-      'Generates complete .env.example for kubeconfig, context, and namespace.',
+      'Generates complete .env.example for kubeconfig, context, namespace, and registry settings.',
       'Tests cluster connectivity during init.',
+      'Builds and pushes your container image during deployhub build/deploy (pipeline docker stage).',
     ],
     after: [
       'Ensure your kubeconfig context points to the correct cluster.',
-      'Create namespace if needed: kubectl create namespace YOUR_NAMESPACE',
-      'For private registries: kubectl create secret docker-registry ... and set KUBE_IMAGE_PULL_SECRET.',
-      'Copy .env.example to .env; add KUBECONFIG contents or auth secrets to GitHub Actions.',
-      'Run deployhub doctor, then git push origin main.',
+      'Namespace is created on first deploy if missing (prompt locally; auto-create in CI). Or: kubectl create namespace YOUR_NAMESPACE',
+      'Copy .env.example to .env and set DOCKER_IMAGE_NAME, DOCKER_REGISTRY_USERNAME, and DOCKER_REGISTRY_TOKEN.',
+      'Skipping registry credentials will very likely cause ImagePullBackOff — the cluster cannot see local Docker images.',
+      'For private registries: also create kubectl create secret docker-registry ... and set KUBE_IMAGE_PULL_SECRET.',
+      'Add the GitHub Secrets listed below (Settings → Secrets and variables → Actions).',
+      'Run deployhub doctor to verify cluster access and that your image is pullable.',
+      'git push origin main to trigger your first deployment.',
     ],
   },
 };

package/src/deployment/init-prompts.js

@@ -94,6 +94,23 @@ async function promptKubernetesDeployment(base, projectName, projectType) {
       message: 'Container image name (e.g. ghcr.io/myorg/myapp):',
       default: projectName,
     },
+    {
+      type: 'input',
+      name: 'dockerRegistryUrl',
+      message: 'Registry URL (leave empty for Docker Hub):',
+    },
+    {
+      type: 'input',
+      name: 'dockerRegistryUsername',
+      message:
+        'Registry username (required — needed to push your image so the cluster can pull it):',
+    },
+    {
+      type: 'password',
+      name: 'dockerRegistryToken',
+      message:
+        'Registry token/password (required — needed to push your image so the cluster can pull it):',
+    },
     {
       type: 'input',
       name: 'healthUrl',
@@ -115,6 +132,9 @@ async function promptKubernetesDeployment(base, projectName, projectType) {
     kubeContext: kubeAnswers.kubeContext,
     kubeNamespace: kubeAnswers.kubeNamespace,
     dockerImageName: kubeAnswers.dockerImageName,
+    dockerRegistryUrl: kubeAnswers.dockerRegistryUrl,
+    dockerRegistryUsername: kubeAnswers.dockerRegistryUsername,
+    dockerRegistryToken: kubeAnswers.dockerRegistryToken,
     healthUrl: kubeAnswers.healthUrl,
   };
 }
@@ -366,6 +386,7 @@ export function buildServerEnvEntry(
     envEntry.kubeContext = deployAnswers.kubeContext;
     envEntry.kubeNamespace = deployAnswers.kubeNamespace || projectName;
     envEntry.dockerImageName = deployAnswers.dockerImageName || projectName;
+    envEntry.dockerRegistryUrl = deployAnswers.dockerRegistryUrl || '';
     return envEntry;
   }
 
@@ -418,7 +439,7 @@ export function buildServerEnvEntry(
  * @returns {Record<string, string>|null}
  */
 export function getDockerEnvSecrets(deployAnswers) {
-  if (deployAnswers.deployType !== 'docker') return null;
+  if (!['docker', 'kubernetes'].includes(deployAnswers.deployType)) return null;
 
   /** @type {Record<string, string>} */
   const vars = {};

package/src/deployment/providers/docker.js

@@ -1,18 +1,6 @@
 import { execa } from 'execa';
-import fs from 'fs-extra';
-import path from 'path';
 import { createLogger } from '../../logger/index.js';
-import { extractArtifact } from '../../artifact/engine.js';
-import {
-  describeInterpretedBackendGap,
-  generateDotnetRuntimeDockerfile,
-  generateFrontendRuntimeDockerfile,
-  generateGoRuntimeDockerfile,
-  generateSpringRuntimeDockerfile,
-  isFrontendStaticFramework,
-  isInterpretedBackendFramework,
-  resolveDockerImageRef,
-} from '../../utils/docker-image.js';
+import { createDockerImageDeployContext } from '../../utils/docker-image-deploy.js';
 
 /**
  * @param {import('../../core/config.js').DeployHubConfig} config
@@ -21,277 +9,8 @@ import {
  */
 export function createDockerProvider(config, envName, env = process.env) {
   const log = createLogger('docker');
-
-  const { fullImage, latestImage, legacyLatestImage, imageTag } =
-    resolveDockerImageRef(config, env);
-  const registryUrl = env.DOCKER_REGISTRY_URL || '';
-  const registryUser = env.DOCKER_REGISTRY_USERNAME || '';
-  const registryToken = env.DOCKER_REGISTRY_TOKEN || '';
-  const dockerHost = env.DOCKER_HOST || '';
-
-  function getDockerEnv() {
-    /** @type {Record<string, string>} */
-    const dockerEnv = { ...process.env };
-    if (dockerHost) dockerEnv.DOCKER_HOST = dockerHost;
-    if (env.DOCKER_TLS_VERIFY) dockerEnv.DOCKER_TLS_VERIFY = env.DOCKER_TLS_VERIFY;
-    if (env.DOCKER_CERT_PATH) dockerEnv.DOCKER_CERT_PATH = env.DOCKER_CERT_PATH;
-    return dockerEnv;
-  }
-
-  function hasRegistryCredentials() {
-    return Boolean(registryUser && registryToken);
-  }
-
-  async function dockerLogin() {
-    if (!hasRegistryCredentials()) return;
-    const registry = registryUrl || 'https://index.docker.io/v1/';
-    log.info('Logging in to container registry...');
-    await execa(
-      'docker',
-      ['login', registry, '-u', registryUser, '--password-stdin'],
-      {
-        input: registryToken,
-        stdio: ['pipe', 'inherit', 'inherit'],
-        env: getDockerEnv(),
-      }
-    );
-  }
-
-  /**
-   * Push only when registry credentials are configured. Avoids a noisy failed
-   * push to Docker Hub for local-only image names.
-   */
-  async function maybePushImage() {
-    if (!hasRegistryCredentials()) {
-      log.info(
-        'docker push skipped (DOCKER_REGISTRY_USERNAME/TOKEN not set — local image only)'
-      );
-      return;
-    }
-
-    log.info(`Pushing ${fullImage} to registry...`);
-    await execa('docker', ['push', fullImage], {
-      stdio: 'inherit',
-      env: getDockerEnv(),
-    });
-    log.success(`Pushed ${fullImage}`);
-  }
-
-  /**
-   * @param {string} ref
-   */
-  async function imageExists(ref) {
-    try {
-      await execa('docker', ['image', 'inspect', ref], {
-        stdio: 'pipe',
-        env: getDockerEnv(),
-      });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Prefer the image already built during the pipeline `docker` stage.
-   * Retag when the pipeline used `:latest` and deploy needs a version tag.
-   */
-  async function ensureImageFromPipeline() {
-    if (await imageExists(fullImage)) {
-      log.info(`Reusing existing image ${fullImage}`);
-      return true;
-    }
-
-    const candidates = [...new Set([latestImage, legacyLatestImage])].filter(
-      (ref) => ref !== fullImage
-    );
-
-    for (const candidate of candidates) {
-      if (!(await imageExists(candidate))) continue;
-      log.info(`Re-tagging pipeline image ${candidate} → ${fullImage}`);
-      await execa('docker', ['tag', candidate, fullImage], {
-        stdio: 'inherit',
-        env: getDockerEnv(),
-      });
-      return true;
-    }
-
-    return false;
-  }
-
-  /**
-   * Backend artifacts omit lockfiles/node_modules. Prefer a pre-built binary
-   * runtime image when present; otherwise fail with an actionable error.
-   * @param {string} buildContext
-   * @param {Record<string, unknown>} metadata
-   * @param {string} framework
-   * @param {number} port
-   */
-  async function prepareBackendBuildContext(buildContext, metadata, framework, port) {
-    if (framework === 'spring') {
-      const targetDir = path.join(buildContext, 'target');
-      if (await fs.pathExists(targetDir)) {
-        const jars = (await fs.readdir(targetDir)).filter((f) => f.endsWith('.jar'));
-        if (jars.length > 0) {
-          const jarRel = `target/${jars[0]}`;
-          log.info(`Building runtime image from pre-built JAR (${jarRel})...`);
-          await fs.writeFile(
-            path.join(buildContext, 'Dockerfile'),
-            generateSpringRuntimeDockerfile(jarRel, port)
-          );
-          return;
-        }
-      }
-    }
-
-    if (framework === 'go') {
-      const binDir = path.join(buildContext, 'bin');
-      if (await fs.pathExists(binDir)) {
-        const bins = await fs.readdir(binDir);
-        if (bins.length > 0) {
-          const binRel = `bin/${bins[0]}`;
-          log.info(`Building runtime image from pre-built Go binary (${binRel})...`);
-          await fs.writeFile(
-            path.join(buildContext, 'Dockerfile'),
-            generateGoRuntimeDockerfile(binRel, port)
-          );
-          return;
-        }
-      }
-    }
-
-    if (framework === 'dotnet') {
-      const publishDir =
-        /** @type {string} */ (metadata.buildOutput) ||
-        config.buildOutput ||
-        'publish';
-      const publishPath = path.join(buildContext, publishDir);
-      if (await fs.pathExists(publishPath)) {
-        log.info(`Building runtime image from pre-built .NET output (${publishDir}/)...`);
-        await fs.writeFile(
-          path.join(buildContext, 'Dockerfile'),
-          generateDotnetRuntimeDockerfile(publishDir, port)
-        );
-        return;
-      }
-    }
-
-    const dockerfilePath = path.join(buildContext, 'Dockerfile');
-    if (!(await fs.pathExists(dockerfilePath))) {
-      throw new Error(
-        'No Dockerfile found in artifact and no pipeline image to reuse. ' +
-          'Add a Dockerfile and enable pipeline.docker so the image is built from project source.'
-      );
-    }
-
-    // Interpreted backends (Node/Python/PHP/Ruby): never rebuild from artifact.
-    // Artifacts ship source + manifest files, not installed dependency trees.
-    if (isInterpretedBackendFramework(framework)) {
-      const gap = describeInterpretedBackendGap(framework);
-      throw new Error(
-        `Cannot rebuild ${gap.ecosystem} backend image "${fullImage}" from the packaged artifact.\n` +
-          `Backend artifacts include source/manifests but not ${gap.missing}, ` +
-          `so Dockerfiles that run \`${gap.installCmd}\` cannot reliably succeed from the artifact alone.\n\n` +
-          'What to do instead:\n' +
-          '  1. Enable pipeline.docker in deployhub.config.json (default when Docker deploy is selected).\n' +
-          '  2. Run a full `deployhub build` so the image is built from the project root (with full deps).\n' +
-          '  3. Deploy will reuse that local image (retag/push/run) — it will not rebuild from the artifact.\n\n' +
-          `Standalone \`deployhub deploy\` without a pre-built local image is not supported for ${gap.ecosystem} backends.`
-      );
-    }
-
-    // Remaining backends (unknown frameworks): try the packaged Dockerfile, but warn.
-    log.warn(
-      'Building backend image from extracted artifact. Prefer pipeline.docker so the image ' +
-        'is built once from full project source, then reused on deploy.'
-    );
-  }
-
-  /**
-   * Standalone deploy fallback: extract the packaged artifact and build a
-   * runtime image from pre-built output (frontend) or compiled backend artifacts.
-   * Never builds from artifactDir root — that only has zip/metadata + a source Dockerfile.
-   * @param {string} artifactDir
-   */
-  async function buildFromArtifactContents(artifactDir) {
-    const zipPath = path.join(artifactDir, 'artifact.zip');
-    if (!(await fs.pathExists(zipPath))) {
-      throw new Error(
-        `No local image found for ${fullImage} and no artifact.zip to build from. ` +
-          'Enable pipeline.docker so the image is built from project source, or run deployhub build first.'
-      );
-    }
-
-    const buildContext = path.join(artifactDir, '_docker_build');
-    await fs.remove(buildContext);
-    await extractArtifact(artifactDir, buildContext);
-
-    try {
-      const metadataPath = path.join(buildContext, 'metadata.json');
-      const metadata = (await fs.pathExists(metadataPath))
-        ? await fs.readJson(metadataPath)
-        : {};
-
-      const projectType = metadata.projectType || config.projectType || 'frontend';
-      const framework =
-        metadata.framework ||
-        config.framework ||
-        config.frontend?.framework ||
-        '';
-      const buildOutput =
-        metadata.buildOutput ||
-        config.buildOutput ||
-        config.frontend?.buildOutput ||
-        'dist';
-      const port =
-        Number(metadata.port) ||
-        config.port ||
-        config.backend?.port ||
-        3000;
-
-      const composePath = path.join(buildContext, 'docker-compose.yml');
-      if (await fs.pathExists(composePath)) {
-        log.info('Building via docker compose from extracted artifact...');
-        await execa('docker', ['compose', 'up', '-d', '--build'], {
-          cwd: buildContext,
-          stdio: 'inherit',
-          env: getDockerEnv(),
-        });
-        return { ranCompose: true };
-      }
-
-      const isStaticFrontend =
-        projectType === 'frontend' || isFrontendStaticFramework(framework);
-
-      if (isStaticFrontend) {
-        const outputDir = path.join(buildContext, buildOutput);
-        if (!(await fs.pathExists(outputDir))) {
-          throw new Error(
-            `Frontend artifact is missing build output "${buildOutput}". ` +
-              'Cannot build a runtime image from this artifact.'
-          );
-        }
-        log.info(
-          `Building runtime image from pre-built ${buildOutput}/ (no source rebuild)...`
-        );
-        await fs.writeFile(
-          path.join(buildContext, 'Dockerfile'),
-          generateFrontendRuntimeDockerfile(buildOutput)
-        );
-      } else {
-        await prepareBackendBuildContext(buildContext, metadata, framework, port);
-      }
-
-      await execa('docker', ['build', '-t', fullImage, '.'], {
-        cwd: buildContext,
-        stdio: 'inherit',
-        env: getDockerEnv(),
-      });
-      return { ranCompose: false };
-    } finally {
-      await fs.remove(buildContext).catch(() => {});
-    }
-  }
+  const imageOps = createDockerImageDeployContext(config, env, log);
+  const { fullImage, getDockerEnv, ensureImageReadyForDeploy } = imageOps;
 
   /**
    * @param {string} artifactDir
@@ -300,31 +19,12 @@ export function createDockerProvider(config, envName, env = process.env) {
     log.info(`Deploying via Docker (image: ${fullImage})...`);
     const dockerEnv = getDockerEnv();
 
-    await dockerLogin();
-
-    const reused = await ensureImageFromPipeline();
-    let ranCompose = false;
-
-    if (!reused) {
-      const result = await buildFromArtifactContents(artifactDir);
-      ranCompose = Boolean(result?.ranCompose);
-    }
-
-    if (ranCompose) {
+    const result = await ensureImageReadyForDeploy(artifactDir);
+    if (result.ranCompose) {
       log.success('Docker deployment complete');
       return;
     }
 
-    await maybePushImage();
-
-    // Keep :latest in sync when deploy uses a version tag
-    if (imageTag !== 'latest' && fullImage !== latestImage) {
-      await execa('docker', ['tag', fullImage, latestImage], {
-        stdio: 'pipe',
-        env: dockerEnv,
-      }).catch(() => {});
-    }
-
     await execa(
       'docker',
       ['rm', '-f', config.project],

package/src/deployment/providers/kubernetes.js

@@ -4,6 +4,8 @@ import path from 'path';
 import os from 'os';
 import { createLogger } from '../../logger/index.js';
 import { sanitizeK8sName } from '../../utils/kubernetes-manifests.js';
+import { createDockerImageDeployContext } from '../../utils/docker-image-deploy.js';
+import { ensureKubernetesNamespace } from '../../utils/kubernetes-namespace.js';
 
 /**
  * @param {import('../../core/config.js').DeployHubConfig} config
@@ -12,6 +14,7 @@ import { sanitizeK8sName } from '../../utils/kubernetes-manifests.js';
  */
 export function createKubernetesProvider(config, envName, env = process.env) {
   const log = createLogger('kubernetes');
+  const imageOps = createDockerImageDeployContext(config, env, log);
 
   const kubeconfig = env.KUBECONFIG || path.join(os.homedir(), '.kube', 'config');
   const context = env.KUBE_CONTEXT || '';
@@ -24,12 +27,22 @@ export function createKubernetesProvider(config, envName, env = process.env) {
   }
 
   /**
+   * Cluster-scoped kubectl args (context only). Used for Namespace get/create.
    * @param {string[]} baseArgs
    */
-  function kubectlArgs(baseArgs) {
+  function kubectlClusterArgs(baseArgs) {
     /** @type {string[]} */
     const args = [...baseArgs];
     if (context) args.push('--context', context);
+    return args;
+  }
+
+  /**
+   * @param {string[]} baseArgs
+   */
+  function kubectlArgs(baseArgs) {
+    /** @type {string[]} */
+    const args = kubectlClusterArgs(baseArgs);
     if (namespace) args.push('--namespace', namespace);
     return args;
   }
@@ -51,6 +64,21 @@ export function createKubernetesProvider(config, envName, env = process.env) {
       );
     }
 
+    log.info(`Ensuring container image ${imageOps.fullImage} is built and pushed before apply...`);
+    const imageResult = await imageOps.ensureImageReadyForDeploy(artifactDir);
+    if (imageResult.ranCompose) {
+      log.warn(
+        'docker compose was used — ensure the cluster can pull the resulting image from your registry.'
+      );
+    }
+
+    await ensureKubernetesNamespace({
+      namespace,
+      log,
+      kubectlArgs: kubectlClusterArgs,
+      getKubectlEnv,
+    });
+
     const applyTarget = (await fs.pathExists(path.join(manifestDir, 'k8s')))
       ? path.join(manifestDir, 'k8s')
       : manifestDir;

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

@@ -0,0 +1,420 @@
+import { execa } from 'execa';
+import fs from 'fs-extra';
+import path from 'path';
+import { extractArtifact } from '../artifact/engine.js';
+import {
+  describeInterpretedBackendGap,
+  generateDotnetRuntimeDockerfile,
+  generateFrontendRuntimeDockerfile,
+  generateGoRuntimeDockerfile,
+  generateSpringRuntimeDockerfile,
+  isFrontendStaticFramework,
+  isInterpretedBackendFramework,
+  resolveDockerImageRef,
+} from './docker-image.js';
+
+/**
+ * Shared Docker image build, reuse, push, and pullability logic used by
+ * docker and kubernetes deploy providers.
+ *
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {Record<string, string>} [env]
+ * @param {{ info: Function, warn: Function, success: Function }} log
+ */
+export function createDockerImageDeployContext(config, env = process.env, log) {
+  const { fullImage, latestImage, legacyLatestImage, imageTag } =
+    resolveDockerImageRef(config, env);
+  const registryUrl = env.DOCKER_REGISTRY_URL || '';
+  const registryUser = env.DOCKER_REGISTRY_USERNAME || '';
+  const registryToken = env.DOCKER_REGISTRY_TOKEN || '';
+  const dockerHost = env.DOCKER_HOST || '';
+
+  function getDockerEnv() {
+    /** @type {Record<string, string>} */
+    const dockerEnv = { ...process.env };
+    if (dockerHost) dockerEnv.DOCKER_HOST = dockerHost;
+    if (env.DOCKER_TLS_VERIFY) dockerEnv.DOCKER_TLS_VERIFY = env.DOCKER_TLS_VERIFY;
+    if (env.DOCKER_CERT_PATH) dockerEnv.DOCKER_CERT_PATH = env.DOCKER_CERT_PATH;
+    return dockerEnv;
+  }
+
+  function hasRegistryCredentials() {
+    return Boolean(registryUser && registryToken);
+  }
+
+  async function dockerLogin() {
+    if (!hasRegistryCredentials()) return;
+    const registry = registryUrl || 'https://index.docker.io/v1/';
+    log.info('Logging in to container registry...');
+    await execa(
+      'docker',
+      ['login', registry, '-u', registryUser, '--password-stdin'],
+      {
+        input: registryToken,
+        stdio: ['pipe', 'inherit', 'inherit'],
+        env: getDockerEnv(),
+      }
+    );
+  }
+
+  /**
+   * Push only when registry credentials are configured. Avoids a noisy failed
+   * push to Docker Hub for local-only image names.
+   */
+  async function maybePushImage() {
+    if (!hasRegistryCredentials()) {
+      log.info(
+        'docker push skipped (DOCKER_REGISTRY_USERNAME/TOKEN not set — local image only)'
+      );
+      return;
+    }
+
+    log.info(`Pushing ${fullImage} to registry...`);
+    await execa('docker', ['push', fullImage], {
+      stdio: 'inherit',
+      env: getDockerEnv(),
+    });
+    log.success(`Pushed ${fullImage}`);
+  }
+
+  /**
+   * @param {string} ref
+   */
+  async function imageExistsLocally(ref) {
+    try {
+      await execa('docker', ['image', 'inspect', ref], {
+        stdio: 'pipe',
+        env: getDockerEnv(),
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Prefer the image already built during the pipeline `docker` stage.
+   * Retag when the pipeline used `:latest` and deploy needs a version tag.
+   */
+  async function ensureImageFromPipeline() {
+    if (await imageExistsLocally(fullImage)) {
+      log.info(`Reusing existing image ${fullImage}`);
+      return true;
+    }
+
+    const candidates = [...new Set([latestImage, legacyLatestImage])].filter(
+      (ref) => ref !== fullImage
+    );
+
+    for (const candidate of candidates) {
+      if (!(await imageExistsLocally(candidate))) continue;
+      log.info(`Re-tagging pipeline image ${candidate} → ${fullImage}`);
+      await execa('docker', ['tag', candidate, fullImage], {
+        stdio: 'inherit',
+        env: getDockerEnv(),
+      });
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * @param {string} buildContext
+   * @param {Record<string, unknown>} metadata
+   * @param {string} framework
+   * @param {number} port
+   */
+  async function prepareBackendBuildContext(buildContext, metadata, framework, port) {
+    if (framework === 'spring') {
+      const targetDir = path.join(buildContext, 'target');
+      if (await fs.pathExists(targetDir)) {
+        const jars = (await fs.readdir(targetDir)).filter((f) => f.endsWith('.jar'));
+        if (jars.length > 0) {
+          const jarRel = `target/${jars[0]}`;
+          log.info(`Building runtime image from pre-built JAR (${jarRel})...`);
+          await fs.writeFile(
+            path.join(buildContext, 'Dockerfile'),
+            generateSpringRuntimeDockerfile(jarRel, port)
+          );
+          return;
+        }
+      }
+    }
+
+    if (framework === 'go') {
+      const binDir = path.join(buildContext, 'bin');
+      if (await fs.pathExists(binDir)) {
+        const bins = await fs.readdir(binDir);
+        if (bins.length > 0) {
+          const binRel = `bin/${bins[0]}`;
+          log.info(`Building runtime image from pre-built Go binary (${binRel})...`);
+          await fs.writeFile(
+            path.join(buildContext, 'Dockerfile'),
+            generateGoRuntimeDockerfile(binRel, port)
+          );
+          return;
+        }
+      }
+    }
+
+    if (framework === 'dotnet') {
+      const publishDir =
+        /** @type {string} */ (metadata.buildOutput) ||
+        config.buildOutput ||
+        'publish';
+      const publishPath = path.join(buildContext, publishDir);
+      if (await fs.pathExists(publishPath)) {
+        log.info(`Building runtime image from pre-built .NET output (${publishDir}/)...`);
+        await fs.writeFile(
+          path.join(buildContext, 'Dockerfile'),
+          generateDotnetRuntimeDockerfile(publishDir, port)
+        );
+        return;
+      }
+    }
+
+    const dockerfilePath = path.join(buildContext, 'Dockerfile');
+    if (!(await fs.pathExists(dockerfilePath))) {
+      throw new Error(
+        'No Dockerfile found in artifact and no pipeline image to reuse. ' +
+          'Add a Dockerfile and enable pipeline.docker so the image is built from project source.'
+      );
+    }
+
+    if (isInterpretedBackendFramework(framework)) {
+      const gap = describeInterpretedBackendGap(framework);
+      throw new Error(
+        `Cannot rebuild ${gap.ecosystem} backend image "${fullImage}" from the packaged artifact.\n` +
+          `Backend artifacts include source/manifests but not ${gap.missing}, ` +
+          `so Dockerfiles that run \`${gap.installCmd}\` cannot reliably succeed from the artifact alone.\n\n` +
+          'What to do instead:\n' +
+          '  1. Enable pipeline.docker in deployhub.config.json (default when Docker deploy is selected).\n' +
+          '  2. Run a full `deployhub build` so the image is built from the project root (with full deps).\n' +
+          '  3. Deploy will reuse that local image (retag/push/run) — it will not rebuild from the artifact.\n\n' +
+          `Standalone \`deployhub deploy\` without a pre-built local image is not supported for ${gap.ecosystem} backends.`
+      );
+    }
+
+    log.warn(
+      'Building backend image from extracted artifact. Prefer pipeline.docker so the image ' +
+        'is built once from full project source, then reused on deploy.'
+    );
+  }
+
+  /**
+   * @param {string} artifactDir
+   */
+  async function buildFromArtifactContents(artifactDir) {
+    const zipPath = path.join(artifactDir, 'artifact.zip');
+    if (!(await fs.pathExists(zipPath))) {
+      throw new Error(
+        `No local image found for ${fullImage} and no artifact.zip to build from. ` +
+          'Enable pipeline.docker so the image is built from project source, or run deployhub build first.'
+      );
+    }
+
+    const buildContext = path.join(artifactDir, '_docker_build');
+    await fs.remove(buildContext);
+    await extractArtifact(artifactDir, buildContext);
+
+    try {
+      const metadataPath = path.join(buildContext, 'metadata.json');
+      const metadata = (await fs.pathExists(metadataPath))
+        ? await fs.readJson(metadataPath)
+        : {};
+
+      const projectType = metadata.projectType || config.projectType || 'frontend';
+      const framework =
+        metadata.framework ||
+        config.framework ||
+        config.frontend?.framework ||
+        '';
+      const buildOutput =
+        metadata.buildOutput ||
+        config.buildOutput ||
+        config.frontend?.buildOutput ||
+        'dist';
+      const port =
+        Number(metadata.port) ||
+        config.port ||
+        config.backend?.port ||
+        3000;
+
+      const composePath = path.join(buildContext, 'docker-compose.yml');
+      if (await fs.pathExists(composePath)) {
+        log.info('Building via docker compose from extracted artifact...');
+        await execa('docker', ['compose', 'up', '-d', '--build'], {
+          cwd: buildContext,
+          stdio: 'inherit',
+          env: getDockerEnv(),
+        });
+        return { ranCompose: true };
+      }
+
+      const isStaticFrontend =
+        projectType === 'frontend' || isFrontendStaticFramework(framework);
+
+      if (isStaticFrontend) {
+        const outputDir = path.join(buildContext, buildOutput);
+        if (!(await fs.pathExists(outputDir))) {
+          throw new Error(
+            `Frontend artifact is missing build output "${buildOutput}". ` +
+              'Cannot build a runtime image from this artifact.'
+          );
+        }
+        log.info(
+          `Building runtime image from pre-built ${buildOutput}/ (no source rebuild)...`
+        );
+        await fs.writeFile(
+          path.join(buildContext, 'Dockerfile'),
+          generateFrontendRuntimeDockerfile(buildOutput)
+        );
+      } else {
+        await prepareBackendBuildContext(buildContext, metadata, framework, port);
+      }
+
+      await execa('docker', ['build', '-t', fullImage, '.'], {
+        cwd: buildContext,
+        stdio: 'inherit',
+        env: getDockerEnv(),
+      });
+      return { ranCompose: false };
+    } finally {
+      await fs.remove(buildContext).catch(() => {});
+    }
+  }
+
+  /**
+   * Ensure a deployable image exists locally, then push when credentials are set.
+   * @param {string} artifactDir
+   * @param {{ skipPush?: boolean }} [options]
+   */
+  async function ensureImageReadyForDeploy(artifactDir, options = {}) {
+    await dockerLogin();
+
+    const reused = await ensureImageFromPipeline();
+    let ranCompose = false;
+
+    if (!reused) {
+      const result = await buildFromArtifactContents(artifactDir);
+      ranCompose = Boolean(result?.ranCompose);
+    }
+
+    if (ranCompose) {
+      return { ranCompose: true };
+    }
+
+    if (!options.skipPush) {
+      await maybePushImage();
+    }
+
+    const dockerEnv = getDockerEnv();
+    if (imageTag !== 'latest' && fullImage !== latestImage) {
+      await execa('docker', ['tag', fullImage, latestImage], {
+        stdio: 'pipe',
+        env: dockerEnv,
+      }).catch(() => {});
+    }
+
+    return { ranCompose: false };
+  }
+
+  return {
+    fullImage,
+    latestImage,
+    imageTag,
+    getDockerEnv,
+    hasRegistryCredentials,
+    dockerLogin,
+    maybePushImage,
+    ensureImageFromPipeline,
+    buildFromArtifactContents,
+    ensureImageReadyForDeploy,
+  };
+}
+
+/**
+ * Verify that an image:tag exists in a registry and is accessible with current credentials.
+ *
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {Record<string, string>} [env]
+ * @returns {Promise<{ ok: boolean, message: string }>}
+ */
+export async function checkImagePullability(config, env = process.env) {
+  const { fullImage } = resolveDockerImageRef(config, env);
+  const registryUser = env.DOCKER_REGISTRY_USERNAME || '';
+  const registryToken = env.DOCKER_REGISTRY_TOKEN || '';
+  const registryUrl = env.DOCKER_REGISTRY_URL || '';
+  const dockerHost = env.DOCKER_HOST || '';
+
+  /** @type {Record<string, string>} */
+  const dockerEnv = { ...process.env };
+  if (dockerHost) dockerEnv.DOCKER_HOST = dockerHost;
+  if (env.DOCKER_TLS_VERIFY) dockerEnv.DOCKER_TLS_VERIFY = env.DOCKER_TLS_VERIFY;
+  if (env.DOCKER_CERT_PATH) dockerEnv.DOCKER_CERT_PATH = env.DOCKER_CERT_PATH;
+
+  if (registryUser && registryToken) {
+    const registry = registryUrl || 'https://index.docker.io/v1/';
+    try {
+      await execa(
+        'docker',
+        ['login', registry, '-u', registryUser, '--password-stdin'],
+        {
+          input: registryToken,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          env: dockerEnv,
+        }
+      );
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return {
+        ok: false,
+        message:
+          `Image ${fullImage} is not pullable — registry login failed (${msg}). ` +
+          'Check DOCKER_REGISTRY_USERNAME and DOCKER_REGISTRY_TOKEN.',
+      };
+    }
+  }
+
+  try {
+    await execa('docker', ['manifest', 'inspect', fullImage], {
+      stdio: 'pipe',
+      env: dockerEnv,
+    });
+    return { ok: true, message: `Image ${fullImage} is pullable` };
+  } catch (err) {
+    const stderr =
+      err instanceof Error && 'stderr' in err
+        ? String(/** @type {{ stderr?: string }} */ (err).stderr || '')
+        : '';
+    const combined = `${err instanceof Error ? err.message : String(err)} ${stderr}`.toLowerCase();
+
+    let hint = '';
+    if (combined.includes('unauthorized') || combined.includes('authentication required')) {
+      hint =
+        'The image may exist but is private and inaccessible with your current credentials. ' +
+        'Set DOCKER_REGISTRY_USERNAME and DOCKER_REGISTRY_TOKEN, or configure KUBE_IMAGE_PULL_SECRET for the cluster.';
+    } else if (combined.includes('not found') || combined.includes('manifest unknown')) {
+      hint =
+        'The image does not exist in the registry yet.';
+    } else if (combined.includes('denied')) {
+      hint = 'Access denied — check registry credentials and repository permissions.';
+    } else {
+      hint = 'Verify the image name/tag and registry connectivity.';
+    }
+
+    const hasCreds = Boolean(registryUser && registryToken);
+
+    return {
+      ok: false,
+      message:
+        `Image ${fullImage} is not pullable. ${hint}\n` +
+        (hasCreds
+          ? '  DeployHub will build and push this image automatically during your next `deployhub build`.\n'
+          : '  If you have DOCKER_REGISTRY_USERNAME/DOCKER_REGISTRY_TOKEN configured, DeployHub will build and push this image automatically during your next `deployhub build`.\n' +
+            '  If not, either configure those variables, or push the image manually before deploying:\n') +
+        `    docker push ${fullImage}`,
+    };
+  }
+}

package/src/utils/interactive.js

@@ -0,0 +1,27 @@
+/**
+ * Detect whether the CLI can safely prompt the user.
+ * Non-interactive when stdin is not a TTY, or when common CI env vars are set.
+ *
+ * @param {{ env?: NodeJS.ProcessEnv, stdinIsTTY?: boolean|null }} [options]
+ * @returns {boolean}
+ */
+export function isInteractive(options = {}) {
+  const env = options.env || process.env;
+  const stdinIsTTY =
+    options.stdinIsTTY !== undefined ? options.stdinIsTTY : Boolean(process.stdin.isTTY);
+
+  if (env.CI === 'true' || env.CI === '1') return false;
+  if (env.GITHUB_ACTIONS === 'true' || env.GITHUB_ACTIONS === '1') return false;
+  if (!stdinIsTTY) return false;
+  return true;
+}
+
+/**
+ * @param {{ env?: NodeJS.ProcessEnv, stdinIsTTY?: boolean|null }} [options]
+ * @returns {boolean}
+ */
+export function isNonInteractive(options = {}) {
+  return !isInteractive(options);
+}
+
+export default { isInteractive, isNonInteractive };

package/src/utils/kubernetes-namespace.js

@@ -0,0 +1,130 @@
+import { execa } from 'execa';
+import inquirer from 'inquirer';
+import { isInteractive } from './interactive.js';
+
+/**
+ * @param {unknown} err
+ * @returns {string}
+ */
+function kubectlErrorDetail(err) {
+  if (err && typeof err === 'object' && 'stderr' in err) {
+    const stderr = String(/** @type {{ stderr?: unknown }} */ (err).stderr || '').trim();
+    if (stderr) return stderr;
+  }
+  if (err instanceof Error && err.message) return err.message;
+  return String(err);
+}
+
+/**
+ * Check whether a namespace exists using a cluster-scoped get that exits 0 for
+ * both found and missing. Non-zero exits (auth, connectivity, bad kubeconfig)
+ * are rethrown — they must not be treated as "not found".
+ *
+ * @param {string} namespace
+ * @param {{
+ *   kubectlArgs?: (args: string[]) => string[],
+ *   getKubectlEnv?: () => NodeJS.ProcessEnv,
+ *   execaFn?: typeof execa,
+ * }} [options]
+ * @returns {Promise<boolean>}
+ */
+export async function namespaceExists(namespace, options = {}) {
+  const kubectlArgs = options.kubectlArgs || ((args) => args);
+  const getKubectlEnv = options.getKubectlEnv || (() => process.env);
+  const execaFn = options.execaFn || execa;
+
+  try {
+    const { stdout } = await execaFn(
+      'kubectl',
+      kubectlArgs(['get', 'namespace', namespace, '--ignore-not-found', '-o', 'name']),
+      {
+        stdio: 'pipe',
+        env: getKubectlEnv(),
+      }
+    );
+    return Boolean(stdout && String(stdout).trim());
+  } catch (err) {
+    throw new Error(
+      `Failed to check whether namespace '${namespace}' exists: ${kubectlErrorDetail(err)}`,
+      { cause: err instanceof Error ? err : undefined }
+    );
+  }
+}
+
+/**
+ * @param {string} namespace
+ * @returns {Promise<boolean>}
+ */
+async function defaultConfirmCreate(namespace) {
+  const { create } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'create',
+      message: `Namespace '${namespace}' does not exist. Create it now?`,
+      default: true,
+    },
+  ]);
+  return Boolean(create);
+}
+
+/**
+ * Ensure the target namespace exists before kubectl apply.
+ * Interactive: prompt to create. CI / non-TTY: auto-create with a clear log.
+ * Connectivity/auth failures from the existence check abort before create/prompt.
+ *
+ * @param {{
+ *   namespace: string,
+ *   log: { info: Function, warn: Function, success: Function, error?: Function },
+ *   kubectlArgs?: (args: string[]) => string[],
+ *   getKubectlEnv?: () => NodeJS.ProcessEnv,
+ *   execaFn?: typeof execa,
+ *   confirmFn?: (namespace: string) => Promise<boolean>,
+ *   interactive?: boolean,
+ * }} options
+ * @returns {Promise<{ existed: boolean, created: boolean }>}
+ */
+export async function ensureKubernetesNamespace(options) {
+  const {
+    namespace,
+    log,
+    kubectlArgs = (args) => args,
+    getKubectlEnv = () => process.env,
+    execaFn = execa,
+    confirmFn = defaultConfirmCreate,
+    interactive = isInteractive(),
+  } = options;
+
+  if (!namespace) {
+    throw new Error('Kubernetes namespace is empty — set KUBE_NAMESPACE or config.project.');
+  }
+
+  // Throws on auth/connectivity/kubeconfig errors — only false means genuine NotFound.
+  if (await namespaceExists(namespace, { kubectlArgs, getKubectlEnv, execaFn })) {
+    return { existed: true, created: false };
+  }
+
+  log.warn(`Namespace '${namespace}' was not found on the cluster.`);
+
+  let shouldCreate = true;
+  if (interactive) {
+    shouldCreate = await confirmFn(namespace);
+    if (!shouldCreate) {
+      throw new Error(
+        `Namespace '${namespace}' does not exist. Create it manually with: kubectl create namespace ${namespace}`
+      );
+    }
+  } else {
+    log.info(
+      `Non-interactive session detected — creating namespace '${namespace}' automatically.`
+    );
+  }
+
+  await execaFn('kubectl', kubectlArgs(['create', 'namespace', namespace]), {
+    stdio: 'inherit',
+    env: getKubectlEnv(),
+  });
+  log.success(`Created namespace '${namespace}'`);
+  return { existed: false, created: true };
+}
+
+export default { namespaceExists, ensureKubernetesNamespace };