@akash-chowdhury-24/deployhub 2.0.26 → 2.0.28

package/src/deployment/init-prompts.js

@@ -81,7 +81,12 @@ export async function promptServerDeployment(
         'Non-interactive env add requires --method <ssh|docker|ec2|azure-vm|gcp-vm|kubernetes>.'
       );
     }
-    return buildNonInteractiveDeployAnswers(options.deployType, projectName, options.envName);
+    return buildNonInteractiveDeployAnswers(
+      options.deployType,
+      projectName,
+      options.envName,
+      existingEnvNames
+    );
   }
 
   /** @type {import('inquirer').QuestionCollection} */
@@ -122,7 +127,9 @@ export async function promptServerDeployment(
   const deployType = base.deployType;
 
   if (deployType === 'kubernetes') {
-    return promptKubernetesDeployment(base, projectName, projectType);
+    return promptKubernetesDeployment(base, projectName, projectType, {
+      existingEnvNames,
+    });
   }
 
   if (deployType === 'docker') {
@@ -137,8 +144,14 @@ export async function promptServerDeployment(
  * @param {string} deployType
  * @param {string} projectName
  * @param {string} [envName]
+ * @param {string[]} [existingEnvNames]
  */
-function buildNonInteractiveDeployAnswers(deployType, projectName, envName) {
+function buildNonInteractiveDeployAnswers(
+  deployType,
+  projectName,
+  envName,
+  existingEnvNames = []
+) {
   const base = { deployType, envName: envName || 'default' };
   if (deployType === 'docker') {
     return {
@@ -156,7 +169,11 @@ function buildNonInteractiveDeployAnswers(deployType, projectName, envName) {
       ...base,
       kubeconfig: '~/.kube/config',
       kubeContext: '',
-      kubeNamespace: projectName,
+      kubeNamespace: suggestKubeNamespaceDefault(
+        projectName,
+        base.envName,
+        existingEnvNames
+      ),
       dockerImageName: projectName,
       dockerRegistryUrl: '',
       dockerRegistryUsername: '',
@@ -176,14 +193,39 @@ function buildNonInteractiveDeployAnswers(deployType, projectName, envName) {
   };
 }
 
+/**
+ * Suggested Kubernetes namespace for prompts / --yes defaults.
+ * First environment → bare project name; additional envs → `{project}-{envName}`
+ * so the suggested default matches resolveKubeNamespace auto-scoping behavior.
+ *
+ * @param {string} projectName
+ * @param {string} envName
+ * @param {string[]} existingEnvNames
+ * @returns {string}
+ */
+export function suggestKubeNamespaceDefault(projectName, envName, existingEnvNames = []) {
+  if ((existingEnvNames || []).length > 0) {
+    return `${projectName}-${envName}`;
+  }
+  return projectName;
+}
+
 /**
  * @param {Record<string, string>} base
  * @param {string} projectName
  * @param {'frontend'|'backend'|'both'} projectType
+ * @param {{ existingEnvNames?: string[] }} [options]
  */
-async function promptKubernetesDeployment(base, projectName, projectType) {
+async function promptKubernetesDeployment(base, projectName, projectType, options = {}) {
   const defaultKubeconfig = await detectKubeconfigPath();
   const contexts = await listKubeContexts();
+  const envName = base.envName || 'production';
+  const existingEnvNames = options.existingEnvNames || [];
+  const namespaceDefault = suggestKubeNamespaceDefault(
+    projectName,
+    envName,
+    existingEnvNames
+  );
 
   const kubeAnswers = await inquirer.prompt([
     {
@@ -202,8 +244,11 @@ async function promptKubernetesDeployment(base, projectName, projectType) {
     {
       type: 'input',
       name: 'kubeNamespace',
-      message: 'Kubernetes namespace (e.g. my-app or default):',
-      default: projectName,
+      message:
+        existingEnvNames.length > 0
+          ? `Kubernetes namespace (suggested ${namespaceDefault} so it does not collide with existing envs):`
+          : 'Kubernetes namespace (e.g. my-app or default):',
+      default: namespaceDefault,
     },
     {
       type: 'input',

package/src/deployment/providers/azure-vm.js

@@ -11,9 +11,11 @@ import { getEnvSettings } from '../../core/config.js';
 export function createAzureVmProvider(config, envName, env = process.env) {
   const log = createLogger('azure-vm');
   const settings = getEnvSettings(config.environments[envName]);
-  const subscriptionId = env.AZURE_SUBSCRIPTION_ID || settings.azureSubscriptionId;
-  const resourceGroup = env.AZURE_RESOURCE_GROUP || settings.azureResourceGroup;
-  const vmName = env.AZURE_VM_NAME || settings.azureVmName;
+  const subscriptionId =
+    env.AZURE_VM_LOOKUP_SUBSCRIPTION_ID || settings.azureSubscriptionId;
+  const resourceGroup =
+    env.AZURE_VM_LOOKUP_RESOURCE_GROUP || settings.azureResourceGroup;
+  const vmName = env.AZURE_VM_LOOKUP_VM_NAME || settings.azureVmName;
 
   async function resolveHost() {
     if (settings.host || env.SSH_HOST) {
@@ -23,7 +25,7 @@ export function createAzureVmProvider(config, envName, env = process.env) {
     if (!subscriptionId || !resourceGroup || !vmName) {
       throw new Error(
         'Could not resolve host via Azure VM lookup, and no SSH_HOST was set — ' +
-          'provide SSH_HOST (VM public IP/DNS) or set AZURE_SUBSCRIPTION_ID, AZURE_RESOURCE_GROUP, and AZURE_VM_NAME for auto lookup.'
+          'provide SSH_HOST (VM public IP/DNS) or set AZURE_VM_LOOKUP_SUBSCRIPTION_ID, AZURE_VM_LOOKUP_RESOURCE_GROUP, and AZURE_VM_LOOKUP_VM_NAME for auto lookup.'
       );
     }
 

package/src/deployment/providers/ec2.js

@@ -12,7 +12,8 @@ export function createEc2Provider(config, envName, env = process.env) {
   const log = createLogger('ec2');
   const settings = getEnvSettings(config.environments[envName]);
   const instanceId = env.EC2_INSTANCE_ID || settings.ec2InstanceId;
-  const region = env.AWS_REGION || settings.awsRegion || 'us-east-1';
+  const region =
+    env.EC2_LOOKUP_AWS_REGION || settings.awsRegion || 'us-east-1';
 
   async function resolveHost() {
     if (settings.host || env.SSH_HOST) {
@@ -30,8 +31,12 @@ export function createEc2Provider(config, envName, env = process.env) {
 
     /** @type {Record<string, string>} */
     const awsEnv = { ...process.env };
-    if (env.AWS_ACCESS_KEY_ID) awsEnv.AWS_ACCESS_KEY_ID = env.AWS_ACCESS_KEY_ID;
-    if (env.AWS_SECRET_ACCESS_KEY) awsEnv.AWS_SECRET_ACCESS_KEY = env.AWS_SECRET_ACCESS_KEY;
+    if (env.EC2_LOOKUP_AWS_ACCESS_KEY_ID) {
+      awsEnv.AWS_ACCESS_KEY_ID = env.EC2_LOOKUP_AWS_ACCESS_KEY_ID;
+    }
+    if (env.EC2_LOOKUP_AWS_SECRET_ACCESS_KEY) {
+      awsEnv.AWS_SECRET_ACCESS_KEY = env.EC2_LOOKUP_AWS_SECRET_ACCESS_KEY;
+    }
     awsEnv.AWS_DEFAULT_REGION = region;
 
     try {

package/src/deployment/providers/gcp-vm.js

@@ -11,7 +11,7 @@ import { getEnvSettings } from '../../core/config.js';
 export function createGcpVmProvider(config, envName, env = process.env) {
   const log = createLogger('gcp-vm');
   const settings = getEnvSettings(config.environments[envName]);
-  const projectId = env.GCP_PROJECT_ID || settings.gcpProjectId;
+  const projectId = env.GCP_VM_LOOKUP_PROJECT_ID || settings.gcpProjectId;
   const zone = env.GCP_ZONE || settings.gcpZone;
   const instanceName = env.GCP_INSTANCE_NAME || settings.gcpInstanceName;
 
@@ -23,7 +23,7 @@ export function createGcpVmProvider(config, envName, env = process.env) {
     if (!projectId || !zone || !instanceName) {
       throw new Error(
         'Could not resolve host via GCP instance lookup, and no SSH_HOST was set — ' +
-          'provide SSH_HOST (instance external IP/DNS) or set GCP_PROJECT_ID, GCP_ZONE, and GCP_INSTANCE_NAME for auto lookup.'
+          'provide SSH_HOST (instance external IP/DNS) or set GCP_VM_LOOKUP_PROJECT_ID, GCP_ZONE, and GCP_INSTANCE_NAME for auto lookup.'
       );
     }
 
@@ -31,8 +31,8 @@ export function createGcpVmProvider(config, envName, env = process.env) {
 
     /** @type {Record<string, string>} */
     const gcpEnv = { ...process.env };
-    if (env.GCP_KEY_FILE) {
-      gcpEnv.GOOGLE_APPLICATION_CREDENTIALS = env.GCP_KEY_FILE;
+    if (env.GCP_VM_LOOKUP_KEY_FILE) {
+      gcpEnv.GOOGLE_APPLICATION_CREDENTIALS = env.GCP_VM_LOOKUP_KEY_FILE;
     }
 
     try {

package/src/deployment/providers/ssh.js

@@ -426,10 +426,10 @@ export function createSshProvider(config, envName, env = process.env) {
       return;
     }
 
-    if (framework === 'rails') {
+    if (framework === 'rails' || framework === 'ruby') {
       await exec(ssh, `cd ${dir} && bundle install --deployment`);
       await stopScopedBackendProcess(ssh, targetPath);
-      await startScopedNohup(ssh, targetPath, `bundle exec puma -p ${port}`);
+      await startScopedNohup(ssh, targetPath, `bundle exec puma -b tcp://0.0.0.0:${port}`);
       return;
     }
 

package/src/detectors/backend.detector.js

@@ -64,6 +64,20 @@ const FRAMEWORKS = {
       port: 3000,
     },
   },
+  node: {
+    // After named Node frameworks: package.json backend without Express/Nest/Fastify/Koa.
+    // Exclude obvious frontend-only trees so React/Vue apps are not labeled "node".
+    detect: (cwd) =>
+      fs.existsSync(path.join(cwd, 'package.json')) && !isLikelyFrontendPackage(cwd),
+    defaults: {
+      language: 'node',
+      buildCommand: null,
+      startCommand: 'npm start',
+      buildOutput: '.',
+      testCommand: 'npm test',
+      port: 3000,
+    },
+  },
   fastapi: {
     detect: (cwd) => fileContains(cwd, 'requirements.txt', 'fastapi'),
     defaults: {
@@ -99,6 +113,20 @@ const FRAMEWORKS = {
       port: 5000,
     },
   },
+  python: {
+    detect: (cwd) =>
+      fs.existsSync(path.join(cwd, 'requirements.txt')) ||
+      fs.existsSync(path.join(cwd, 'pyproject.toml')) ||
+      fs.existsSync(path.join(cwd, 'setup.py')),
+    defaults: {
+      language: 'python',
+      buildCommand: null,
+      startCommand: 'python -m http.server 8000 --bind 0.0.0.0',
+      buildOutput: '.',
+      testCommand: 'pytest',
+      port: 8000,
+    },
+  },
   laravel: {
     detect: (cwd) => hasComposerPackage(cwd, 'laravel/framework'),
     defaults: {
@@ -115,12 +143,25 @@ const FRAMEWORKS = {
     defaults: {
       language: 'php',
       buildCommand: null,
-      startCommand: 'php-fpm',
+      startCommand: 'php -S 0.0.0.0:80 -t public',
       buildOutput: '.',
       testCommand: 'php bin/phpunit',
       port: 80,
     },
   },
+  php: {
+    // After Laravel/Symfony: composer.json without those frameworks, or bare .php sources.
+    detect: (cwd) =>
+      fs.existsSync(path.join(cwd, 'composer.json')) || hasPhpSources(cwd),
+    defaults: {
+      language: 'php',
+      buildCommand: null,
+      startCommand: 'php -S 0.0.0.0:80 -t .',
+      buildOutput: '.',
+      testCommand: null,
+      port: 80,
+    },
+  },
   spring: {
     detect: (cwd) => fileContains(cwd, 'pom.xml', 'spring-boot'),
     defaults: {
@@ -132,6 +173,20 @@ const FRAMEWORKS = {
       port: 8080,
     },
   },
+  java: {
+    detect: (cwd) =>
+      fs.existsSync(path.join(cwd, 'pom.xml')) ||
+      fs.existsSync(path.join(cwd, 'build.gradle')) ||
+      fs.existsSync(path.join(cwd, 'build.gradle.kts')),
+    defaults: {
+      language: 'java',
+      buildCommand: 'mvn package',
+      startCommand: 'java -jar target/*.jar',
+      buildOutput: 'target',
+      testCommand: 'mvn test',
+      port: 8080,
+    },
+  },
   go: {
     detect: (cwd) => fs.existsSync(path.join(cwd, 'go.mod')),
     defaults: {
@@ -165,12 +220,23 @@ const FRAMEWORKS = {
     defaults: {
       language: 'ruby',
       buildCommand: 'bundle exec rake assets:precompile',
-      startCommand: 'bundle exec puma',
+      startCommand: 'bundle exec puma -b tcp://0.0.0.0:3000',
       buildOutput: '.',
       testCommand: 'bundle exec rspec',
       port: 3000,
     },
   },
+  ruby: {
+    detect: (cwd) => fs.existsSync(path.join(cwd, 'Gemfile')),
+    defaults: {
+      language: 'ruby',
+      buildCommand: null,
+      startCommand: 'bundle exec puma -b tcp://0.0.0.0:9292',
+      buildOutput: '.',
+      testCommand: 'bundle exec rspec',
+      port: 9292,
+    },
+  },
 };
 
 const DETECTION_ORDER = [
@@ -178,15 +244,20 @@ const DETECTION_ORDER = [
   'express',
   'fastify',
   'koa',
+  'node',
   'fastapi',
   'django',
   'flask',
+  'python',
   'laravel',
   'symfony',
+  'php',
   'spring',
+  'java',
   'go',
   'dotnet',
   'rails',
+  'ruby',
 ];
 
 /**
@@ -201,6 +272,22 @@ function hasPackageDep(cwd, dep) {
   return !!deps[dep];
 }
 
+/**
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+function isLikelyFrontendPackage(cwd) {
+  return [
+    'react',
+    'vue',
+    '@angular/core',
+    'svelte',
+    'astro',
+    'next',
+    'vite',
+  ].some((dep) => hasPackageDep(cwd, dep));
+}
+
 /**
  * @param {string} cwd
  * @param {string} filename
@@ -225,6 +312,24 @@ function hasComposerPackage(cwd, packageName) {
   return !!deps[packageName];
 }
 
+/**
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+function hasPhpSources(cwd) {
+  try {
+    const root = fs.readdirSync(cwd);
+    if (root.some((f) => f.endsWith('.php'))) return true;
+    const publicDir = path.join(cwd, 'public');
+    if (fs.existsSync(publicDir) && fs.statSync(publicDir).isDirectory()) {
+      return fs.readdirSync(publicDir).some((f) => f.endsWith('.php'));
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
 /**
  * @param {string} [cwd]
  * @returns {string|null}

package/src/detectors/index.js

@@ -43,13 +43,14 @@ export async function detectFramework(cwd = process.cwd()) {
   for (const detector of legacyDetectors) {
     if (detector.detect(cwd)) {
       const info = detector.getInfo(cwd);
+      const backendLegacy = new Set(['node', 'php', 'python', 'java', 'go', 'dotnet', 'ruby']);
       return {
         ...info,
-        projectType: info.framework === 'node' ? 'backend' : 'frontend',
+        projectType: backendLegacy.has(info.framework) ? 'backend' : 'frontend',
         language: info.framework,
         startCommand: null,
         testCommand: 'npm test',
-        port: 3000,
+        port: info.framework === 'php' ? 80 : info.framework === 'ruby' ? 9292 : 3000,
       };
     }
   }

package/src/utils/credential-inventory.js

@@ -0,0 +1,292 @@
+/**
+ * Canonical credential / env-var inventory for storage × deployment collision audits.
+ *
+ * Storage lists are the COMPLETE runtime reads from src/storage/providers/*.js
+ * (plus schema keys from PROVIDER_ENV_MAP). Deployment lists come from
+ * DEPLOYMENT_ENV_DEFS / DEPLOYMENT_ENV_KEYS (the declared complete method sets).
+ *
+ * Keep this module in sync when adding providers or methods — the matrix test
+ * fails if storage and deployment declare overlapping bare names.
+ */
+
+import { DEPLOYMENT_ENV_KEYS } from '../deployment/deployment-env.js';
+
+/** Storage provider ids in matrix order. */
+export const STORAGE_PROVIDER_ORDER = [
+  'aws',
+  'azure',
+  'gcp',
+  'gdrive',
+  'dropbox',
+  'ftp',
+  'local',
+];
+
+/** Deployment method ids in matrix order. */
+export const DEPLOYMENT_METHOD_ORDER = [
+  'ssh',
+  'ec2',
+  'azure-vm',
+  'gcp-vm',
+  'docker',
+  'kubernetes',
+];
+
+/**
+ * Complete env vars each storage provider reads at runtime.
+ * Local: no credentials — DEPLOYHUB_LOCAL_STORAGE_DIR is an optional test pin only
+ * (listed under runtimeExtras, not as a credential).
+ *
+ * @type {Record<string, string[]>}
+ */
+export const STORAGE_RUNTIME_ENV_KEYS = {
+  aws: [
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_BUCKET',
+    'AWS_REGION',
+  ],
+  azure: ['AZURE_CONNECTION_STRING', 'AZURE_CONTAINER'],
+  gcp: ['GCP_PROJECT_ID', 'GCP_KEY_FILE', 'GCP_BUCKET'],
+  gdrive: [
+    'GDRIVE_CLIENT_ID',
+    'GDRIVE_CLIENT_SECRET',
+    'GDRIVE_REFRESH_TOKEN',
+    'GDRIVE_FOLDER_ID',
+  ],
+  dropbox: ['DROPBOX_ACCESS_TOKEN'],
+  ftp: ['FTP_HOST', 'FTP_USER', 'FTP_PASSWORD', 'FTP_PORT', 'FTP_PATH'],
+  local: [],
+};
+
+/**
+ * Non-credential runtime extras (optional paths / tuning). Not treated as
+ * storage credentials for collision purposes, but tracked for schema-drift docs.
+ *
+ * @type {Record<string, string[]>}
+ */
+export const STORAGE_RUNTIME_EXTRAS = {
+  local: ['DEPLOYHUB_LOCAL_STORAGE_DIR'],
+};
+
+/**
+ * Complete declared deployment method env keys (core + optional + CI).
+ * @type {Record<string, string[]>}
+ */
+export const DEPLOYMENT_RUNTIME_ENV_KEYS = {
+  ssh: DEPLOYMENT_ENV_KEYS.ssh,
+  ec2: DEPLOYMENT_ENV_KEYS.ec2,
+  'azure-vm': DEPLOYMENT_ENV_KEYS['azure-vm'],
+  'gcp-vm': DEPLOYMENT_ENV_KEYS['gcp-vm'],
+  docker: DEPLOYMENT_ENV_KEYS.docker,
+  kubernetes: DEPLOYMENT_ENV_KEYS.kubernetes,
+};
+
+/**
+ * SSH runtime also reads these tuning knobs (not in DEPLOYMENT_ENV_DEFS).
+ * Not credentials; listed for inventory completeness.
+ */
+export const SSH_RUNTIME_TUNING_KEYS = [
+  'DEPLOYHUB_SSH_EXEC_TIMEOUT_MS',
+  'DEPLOYHUB_SSH_START_TIMEOUT_MS',
+];
+
+/**
+ * Intentional same-name sharing across deployment methods (same concern).
+ * Separated per-environment by the existing secret-prefixing system when
+ * multiple environments exist.
+ *
+ * @type {{ methods: [string, string], keys: string[], reason: string }[]}
+ */
+export const SHARED_BY_DESIGN_DEPLOY_PAIRS = [
+  {
+    methods: ['ssh', 'ec2'],
+    keys: [
+      'SSH_HOST',
+      'SSH_USER',
+      'SSH_KEY_PATH',
+      'SSH_SSH_PORT',
+      'SSH_DEPLOY_PATH',
+      'SSH_APP_NAME',
+      'SSH_PORT',
+      'SSH_KEY',
+    ],
+    reason: 'EC2 wraps SSH after optional host lookup — same SSH concern',
+  },
+  {
+    methods: ['ssh', 'azure-vm'],
+    keys: [
+      'SSH_HOST',
+      'SSH_USER',
+      'SSH_KEY_PATH',
+      'SSH_SSH_PORT',
+      'SSH_DEPLOY_PATH',
+      'SSH_APP_NAME',
+      'SSH_PORT',
+      'SSH_KEY',
+    ],
+    reason: 'Azure VM wraps SSH after optional host lookup — same SSH concern',
+  },
+  {
+    methods: ['ssh', 'gcp-vm'],
+    keys: [
+      'SSH_HOST',
+      'SSH_USER',
+      'SSH_KEY_PATH',
+      'SSH_SSH_PORT',
+      'SSH_DEPLOY_PATH',
+      'SSH_APP_NAME',
+      'SSH_PORT',
+      'SSH_KEY',
+    ],
+    reason: 'GCP VM wraps SSH after optional host lookup — same SSH concern',
+  },
+  {
+    methods: ['ec2', 'azure-vm'],
+    keys: [
+      'SSH_HOST',
+      'SSH_USER',
+      'SSH_KEY_PATH',
+      'SSH_SSH_PORT',
+      'SSH_DEPLOY_PATH',
+      'SSH_APP_NAME',
+      'SSH_PORT',
+      'SSH_KEY',
+    ],
+    reason: 'Both SSH-based cloud VMs share the SSH credential namespace',
+  },
+  {
+    methods: ['ec2', 'gcp-vm'],
+    keys: [
+      'SSH_HOST',
+      'SSH_USER',
+      'SSH_KEY_PATH',
+      'SSH_SSH_PORT',
+      'SSH_DEPLOY_PATH',
+      'SSH_APP_NAME',
+      'SSH_PORT',
+      'SSH_KEY',
+    ],
+    reason: 'Both SSH-based cloud VMs share the SSH credential namespace',
+  },
+  {
+    methods: ['azure-vm', 'gcp-vm'],
+    keys: [
+      'SSH_HOST',
+      'SSH_USER',
+      'SSH_KEY_PATH',
+      'SSH_SSH_PORT',
+      'SSH_DEPLOY_PATH',
+      'SSH_APP_NAME',
+      'SSH_PORT',
+      'SSH_KEY',
+    ],
+    reason: 'Both SSH-based cloud VMs share the SSH credential namespace',
+  },
+  {
+    methods: ['docker', 'kubernetes'],
+    keys: [
+      'DOCKER_IMAGE_NAME',
+      'DOCKER_IMAGE_TAG',
+      'DOCKER_REGISTRY_URL',
+      'DOCKER_REGISTRY_USERNAME',
+      'DOCKER_REGISTRY_TOKEN',
+    ],
+    reason:
+      'Same container-registry concern — Kubernetes builds/pushes via the same Docker image helpers',
+  },
+];
+
+/**
+ * @param {string[]} a
+ * @param {string[]} b
+ * @returns {string[]}
+ */
+export function intersectKeys(a, b) {
+  const setB = new Set(b);
+  return a.filter((k) => setB.has(k)).sort();
+}
+
+/**
+ * Every storage × deployment overlap cell.
+ * Empty array = no overlap.
+ *
+ * @returns {Record<string, Record<string, string[]>>}
+ */
+export function buildStorageDeployOverlapMatrix() {
+  /** @type {Record<string, Record<string, string[]>>} */
+  const matrix = {};
+  for (const storageId of STORAGE_PROVIDER_ORDER) {
+    matrix[storageId] = {};
+    const storageKeys = STORAGE_RUNTIME_ENV_KEYS[storageId] || [];
+    for (const method of DEPLOYMENT_METHOD_ORDER) {
+      const deployKeys = DEPLOYMENT_RUNTIME_ENV_KEYS[method] || [];
+      matrix[storageId][method] = intersectKeys(storageKeys, deployKeys);
+    }
+  }
+  return matrix;
+}
+
+/**
+ * Flatten all unintended storage×deploy collisions (should be empty).
+ * @returns {{ storage: string, method: string, keys: string[] }[]}
+ */
+export function listStorageDeployCollisions() {
+  const matrix = buildStorageDeployOverlapMatrix();
+  /** @type {{ storage: string, method: string, keys: string[] }[]} */
+  const hits = [];
+  for (const storageId of STORAGE_PROVIDER_ORDER) {
+    for (const method of DEPLOYMENT_METHOD_ORDER) {
+      const keys = matrix[storageId][method];
+      if (keys.length > 0) {
+        hits.push({ storage: storageId, method, keys });
+      }
+    }
+  }
+  return hits;
+}
+
+/**
+ * Deploy×deploy shared keys, classified against SHARED_BY_DESIGN_DEPLOY_PAIRS.
+ * @returns {{ a: string, b: string, keys: string[], designed: boolean, reason?: string }[]}
+ */
+export function listDeployDeployShares() {
+  /** @type {{ a: string, b: string, keys: string[], designed: boolean, reason?: string }[]} */
+  const rows = [];
+  for (let i = 0; i < DEPLOYMENT_METHOD_ORDER.length; i++) {
+    for (let j = i + 1; j < DEPLOYMENT_METHOD_ORDER.length; j++) {
+      const a = DEPLOYMENT_METHOD_ORDER[i];
+      const b = DEPLOYMENT_METHOD_ORDER[j];
+      const keys = intersectKeys(
+        DEPLOYMENT_RUNTIME_ENV_KEYS[a] || [],
+        DEPLOYMENT_RUNTIME_ENV_KEYS[b] || []
+      );
+      if (keys.length === 0) continue;
+      const designed = SHARED_BY_DESIGN_DEPLOY_PAIRS.find(
+        (p) =>
+          (p.methods[0] === a && p.methods[1] === b) ||
+          (p.methods[0] === b && p.methods[1] === a)
+      );
+      const unexpected = designed
+        ? keys.filter((k) => !designed.keys.includes(k))
+        : keys;
+      rows.push({
+        a,
+        b,
+        keys,
+        designed: Boolean(designed) && unexpected.length === 0,
+        reason: designed?.reason,
+      });
+      if (designed && unexpected.length > 0) {
+        rows.push({
+          a,
+          b,
+          keys: unexpected,
+          designed: false,
+          reason: `unexpected share beyond designed set for ${a}∩${b}`,
+        });
+      }
+    }
+  }
+  return rows;
+}