elestio 1.0.2 → 1.1.0

package/src/commands/clusters.js

@@ -0,0 +1,337 @@
+import { apiRequest } from '../api.js';
+import { loadConfig } from '../config.js';
+import { log, colors, formatTable, outputJson, formatPrice } from '../utils.js';
+import {
+  CLUSTER_TEMPLATE_IDS, CLUSTER_MAX_NODES,
+  minClusterNodes, supportsClustering, supportsMultiMaster
+} from '../constants.js';
+import { getTemplates } from './templates.js';
+import { listServicesRaw, deleteService } from './services.js';
+
+const APPID = 'CloudVM';
+
+function requireProject(projectId) {
+  const pid = projectId || loadConfig().defaultProject;
+  if (!pid) {
+    throw new Error('Project ID required. Use --project or set a default with: elestio config --set-default-project <id>');
+  }
+  return String(pid);
+}
+
+// ── Read ──
+
+export async function listClustersRaw(projectId = null, includeDeleted = false) {
+  const response = await apiRequest('/api/clusters/getClusters', 'POST', {
+    appid: APPID,
+    projectId: requireProject(projectId),
+    isActiveCluster: !includeDeleted
+  });
+
+  if (response.status === 'KO') throw new Error(response.message || 'Failed to list clusters');
+  return response.clusters || [];
+}
+
+export async function listClusters(projectId = null, json = false) {
+  const clusters = await listClustersRaw(projectId);
+
+  if (json) { outputJson(clusters); return clusters; }
+  if (clusters.length === 0) {
+    log('info', 'No clusters in this project. Create one with: elestio deploy <template> --cluster');
+    return [];
+  }
+
+  const rows = clusters.map(c => ({
+    id: c.id,
+    templateName: c.templateName || 'N/A',
+    mode: c.replicationMode || 'N/A',
+    nodes: `${c.totalNodes ?? c.nbNodes ?? '?'}`,
+    status: c.status || 'N/A',
+    cname: c.cname || 'pending',
+    cost: c.totalCost ? formatPrice(c.totalCost) : 'N/A'
+  }));
+
+  console.log(`\n${colors.bold}Clusters (${clusters.length})${colors.reset}\n`);
+  console.log(formatTable(rows, [
+    { key: 'id', label: 'ID' },
+    { key: 'templateName', label: 'Software' },
+    { key: 'mode', label: 'Mode' },
+    { key: 'nodes', label: 'Nodes' },
+    { key: 'status', label: 'Status' },
+    { key: 'cname', label: 'CNAME' },
+    { key: 'cost', label: 'Cost' }
+  ]));
+  console.log('');
+  return clusters;
+}
+
+/**
+ * The API keys cluster lookups on the primary node's provider server ID, not
+ * on the cluster ID, so resolve one from the other.
+ */
+export async function getClusterInfo(clusterId, projectId = null) {
+  const clusters = await listClustersRaw(projectId);
+  const cluster = clusters.find(c => String(c.id) === String(clusterId));
+  if (!cluster) throw new Error(`Cluster ${clusterId} not found in this project`);
+
+  const response = await apiRequest('/api/clusters/getClusterInfos', 'POST', {
+    appid: APPID,
+    projectId: requireProject(projectId),
+    serviceId: String(cluster.primaryProviderServerID)
+  });
+
+  if (response.status === 'KO') throw new Error(response.message || 'Failed to get cluster info');
+  return { ...cluster, ...(response.clusters || {}) };
+}
+
+export async function showCluster(clusterId, projectId = null, json = false) {
+  const info = await getClusterInfo(clusterId, projectId);
+  const nodes = await listNodesRaw(info, projectId);
+
+  if (json) { outputJson({ ...info, nodes }); return info; }
+
+  console.log(`\n${colors.bold}Cluster ${info.id} - ${info.templateName || 'N/A'}${colors.reset}\n`);
+  console.log(`  Status:      ${info.status || 'N/A'} (${info.deploymentStatus || 'N/A'})`);
+  console.log(`  Mode:        ${info.replicationMode || 'N/A'}`);
+  console.log(`  Nodes:       ${info.totalNodes ?? info.nbNodes ?? nodes.length}`);
+  console.log(`  CNAME:       ${info.cname || 'pending'}`);
+  console.log(`  Primary:     vmID ${info.primaryProviderServerID || 'N/A'}`);
+  console.log(`  Provider:    ${info.provider || 'N/A'} / ${info.datacenter || 'N/A'}`);
+  console.log(`  Firewall:    ${info.isFirewallActivated ? 'enabled' : 'disabled'}`);
+  console.log(`  Protected:   ${info.isProtected ? 'yes' : 'no'}`);
+  console.log(`  Failover:    ${info.isFailoverEnabled ? 'automatic' : 'manual only'}`);
+  if (info.totalCost) console.log(`  Cost:        ${formatPrice(info.totalCost)}`);
+
+  if (nodes.length > 0) {
+    console.log(`\n${colors.bold}Nodes${colors.reset}\n`);
+    console.log(formatTable(nodeRows(nodes, info), NODE_COLUMNS));
+  }
+  console.log('');
+  return info;
+}
+
+/**
+ * Replicas carry the primary's serverID in their clusterID field, not the
+ * cluster's own ID. getActivesNodesByClusterID works the same way and only
+ * returns providerServerIDs, while promote needs the full node record, so the
+ * nodes are picked out of the project's services instead.
+ */
+export function selectClusterNodes(services, cluster) {
+  const primary = services.find(s =>
+    (cluster.primaryServerID && String(s.id) === String(cluster.primaryServerID)) ||
+    String(s.vmID) === String(cluster.primaryProviderServerID)
+  );
+  if (!primary) return [];
+
+  const replicas = services.filter(s => s !== primary && String(s.clusterID) === String(primary.id));
+  return [primary, ...replicas];
+}
+
+export async function listNodesRaw(cluster, projectId = null) {
+  const services = await listServicesRaw(requireProject(projectId));
+  return selectClusterNodes(services, cluster);
+}
+
+const NODE_COLUMNS = [
+  { key: 'role', label: 'Role' },
+  { key: 'vmID', label: 'vmID' },
+  { key: 'displayName', label: 'Name' },
+  { key: 'status', label: 'Status' },
+  { key: 'ipv4', label: 'IP' },
+  { key: 'datacenter', label: 'Region' }
+];
+
+function nodeRows(nodes, info) {
+  const primaryVmId = info ? String(info.primaryProviderServerID) : null;
+  return nodes.map(n => ({
+    role: String(n.vmID) === primaryVmId ? 'primary' : 'replica',
+    vmID: n.vmID ?? 'N/A',
+    displayName: n.displayName || n.serverName || 'N/A',
+    status: n.status || 'N/A',
+    ipv4: n.ipv4 || 'pending',
+    datacenter: n.datacenter || 'N/A'
+  }));
+}
+
+export async function listNodes(clusterId, projectId = null, json = false) {
+  const info = await getClusterInfo(clusterId, projectId);
+  const nodes = await listNodesRaw(info, projectId);
+
+  if (json) { outputJson(nodes); return nodes; }
+  if (nodes.length === 0) { log('info', `No active nodes on cluster ${clusterId}`); return []; }
+
+  console.log(`\n${colors.bold}Nodes of cluster ${clusterId}${colors.reset}\n`);
+  console.log(formatTable(nodeRows(nodes, info), NODE_COLUMNS));
+  console.log('');
+  return nodes;
+}
+
+// ── Actions ──
+
+async function doActionOnCluster(clusterId, action) {
+  const response = await apiRequest('/api/clusters/DoActionOnCluster', 'POST', {
+    clusterID: String(clusterId),
+    action
+  });
+
+  if (response.status === 'KO') throw new Error(response.message || `Action "${action}" failed`);
+  return response;
+}
+
+export async function lockCluster(clusterId) {
+  const result = await doActionOnCluster(clusterId, 'lock');
+  log('success', `Cluster ${clusterId} locked (termination protection enabled)`);
+  return result;
+}
+
+export async function unlockCluster(clusterId) {
+  const result = await doActionOnCluster(clusterId, 'unlock');
+  log('success', `Cluster ${clusterId} unlocked`);
+  return result;
+}
+
+const TOGGLES = { on: true, enable: true, true: true, off: false, disable: false, false: false };
+
+export function parseToggle(value) {
+  const key = String(value ?? '').toLowerCase();
+  if (!(key in TOGGLES)) throw new Error('Expected on|off');
+  return TOGGLES[key];
+}
+
+/**
+ * handleFailover does not fail over: it is the dashboard's automatic-failover
+ * switch, and it sets isFailoverEnabled to !currentStatus. The wanted state is
+ * therefore sent as its opposite.
+ */
+export function buildFailoverPayload(clusterId, enabled) {
+  return { clusterID: String(clusterId), action: 'handleFailover', currentStatus: enabled ? 0 : 1 };
+}
+
+export async function setAutoFailover(clusterId, state) {
+  const enabled = parseToggle(state);
+  const response = await apiRequest('/api/clusters/DoActionOnCluster', 'POST', buildFailoverPayload(clusterId, enabled));
+
+  if (response.status === 'KO') throw new Error(response.message || 'Failed to update automatic failover');
+  log('success', `Automatic failover ${enabled ? 'enabled' : 'disabled'} on cluster ${clusterId}`);
+  return response;
+}
+
+export async function resyncCluster(clusterId, projectId, force) {
+  if (!force) {
+    throw new Error('Re-sync erases all data on the replicas and replaces it with a copy of the primary. Re-run with --force.');
+  }
+
+  const response = await apiRequest('/api/clusters/resyncCluster', 'POST', {
+    appid: APPID,
+    projectId: requireProject(projectId),
+    clusterID: String(clusterId),
+    type: 'resync'
+  });
+
+  if (response.status === 'KO') throw new Error(response.message || 'Re-sync failed');
+  log('success', `Re-sync requested on cluster ${clusterId}. You will be emailed when it completes.`);
+  return response;
+}
+
+/**
+ * Promoting a replica needs the whole node record plus the cluster's CNAME, so
+ * both are resolved here rather than asked of the caller.
+ */
+export async function promoteNode(clusterId, vmID, projectId, force) {
+  if (!force) {
+    throw new Error(`Promoting vmID ${vmID} demotes the current primary. Re-run with --force.`);
+  }
+
+  const pid = requireProject(projectId);
+  const info = await getClusterInfo(clusterId, pid);
+  const nodes = await listNodesRaw(info, pid);
+
+  const node = nodes.find(n => String(n.vmID) === String(vmID));
+  if (!node) {
+    const available = nodes.map(n => n.vmID).join(', ') || 'none';
+    throw new Error(`vmID ${vmID} is not an active node of cluster ${clusterId}. Active nodes: ${available}`);
+  }
+  if (String(node.vmID) === String(info.primaryProviderServerID)) {
+    throw new Error(`vmID ${vmID} is already the primary of cluster ${clusterId}`);
+  }
+
+  const response = await apiRequest('/api/clusters/promoteNode', 'POST', {
+    appid: APPID,
+    projectId: pid,
+    serviceId: String(info.primaryProviderServerID),
+    clusterId: String(clusterId),
+    cname: info.cname,
+    currentNode: {
+      userID: node.userID,
+      id: node.id,
+      vmID: node.vmID,
+      provider: node.provider,
+      datacenter: node.datacenter,
+      cname: node.cname,
+      clusterID: node.clusterID,
+      template: node.template
+    }
+  });
+
+  if (response.status === 'KO') throw new Error(response.message || 'Promotion failed');
+  log('success', `vmID ${vmID} is being promoted to primary of cluster ${clusterId}`);
+  return response;
+}
+
+/**
+ * There is no cluster delete endpoint: deleting the primary service deletes
+ * every node with it. The primary changes after a promote, so it is looked up
+ * rather than asked of the caller.
+ */
+export function clusterDeletionTarget(info) {
+  if (info.isProtected) {
+    throw new Error(`Cluster ${info.id} is locked. Unlock it first with: elestio clusters unlock ${info.id}`);
+  }
+  if (!info.primaryProviderServerID) throw new Error(`Cluster ${info.id} has no known primary node`);
+  return String(info.primaryProviderServerID);
+}
+
+export async function deleteCluster(clusterId, projectId, force) {
+  if (!force) {
+    throw new Error(`Deleting cluster ${clusterId} deletes every node and its data. Re-run with --force.`);
+  }
+
+  const pid = requireProject(projectId);
+  const info = await getClusterInfo(clusterId, pid);
+  const vmID = clusterDeletionTarget(info);
+  const nodes = await listNodesRaw(info, pid);
+
+  await deleteService(vmID, { force: true, project: pid });
+  log('success', `Cluster ${clusterId} deletion initiated (${nodes.length || info.nbNodes} nodes)`);
+}
+
+// ── Catalog ──
+
+export async function listClusterTemplates(json = false) {
+  const templates = await getTemplates();
+
+  // The catalog's own isCluster flag is authoritative and stays current; the
+  // constant is only a fallback for when the catalog cannot be reached.
+  const clusterable = templates.filter(t => supportsClustering(t));
+  const rows = (clusterable.length > 0 ? clusterable : CLUSTER_TEMPLATE_IDS.map(id => ({ id, title: `(unlisted #${id})`, category: 'N/A' })))
+    .map(t => ({
+      id: t.id,
+      title: t.title,
+      category: t.category || 'N/A',
+      minNodes: minClusterNodes(t.id),
+      modes: supportsMultiMaster(t.id) ? 'primary-replica, multi-master' : 'primary-replica'
+    }))
+    .sort((a, b) => a.title.localeCompare(b.title));
+
+  if (json) { outputJson(rows); return rows; }
+
+  console.log(`\n${colors.bold}Templates that support clustering (${rows.length})${colors.reset}\n`);
+  console.log(formatTable(rows, [
+    { key: 'id', label: 'ID' },
+    { key: 'title', label: 'Software' },
+    { key: 'category', label: 'Category' },
+    { key: 'minNodes', label: 'Min nodes' },
+    { key: 'modes', label: 'Modes' }
+  ]));
+  console.log(`\n  Max nodes: ${CLUSTER_MAX_NODES}. Deploy with: ${colors.cyan}elestio deploy <software> --cluster --nodes <n>${colors.reset}\n`);
+  return rows;
+}

package/src/commands/services.js

@@ -1,7 +1,9 @@
 import { apiRequest } from '../api.js';
 import { loadConfig } from '../config.js';
 import { findTemplate } from './templates.js';
-import { formatTable, formatService, formatPrice, colors, log, sleep, validateServerName, outputJson } from '../utils.js';
+import { formatTable, formatService, colors, log, sleep, validateServerName, outputJson } from '../utils.js';
+import { buildCreateServerPayload, validateClusterOptions, describeCluster } from '../payloads/server.js';
+import { parseVmIDs, deploymentProgress } from '../deployment.js';
 
 async function listProjectsRaw() {
   const response = await apiRequest('/api/projects/getList');
@@ -127,14 +129,30 @@ export async function deployService(templateNameOrId, options = {}) {
   const isCicd = template.title?.toLowerCase().includes('ci-cd') || templateNameOrId?.toLowerCase() === 'cicd';
   const serviceType = isCicd ? 'CICD' : 'Service';
 
+  // Validated before anything is created: a rejected cluster still bills the
+  // VMs the provider has already started.
+  const cluster = options.cluster
+    ? validateClusterOptions({ mode: options.clusterMode, nodes: options.nodes }, template)
+    : null;
+
+  if (cluster && isCicd) throw new Error('A CI/CD target cannot be deployed as a cluster');
+
+  const payload = buildCreateServerPayload({
+    template, projectId, serverName, serverType, datacenter, provider,
+    support, adminEmail, version, serviceType, cluster,
+    pipelineName: options.pipelineName, cicdMode: options.cicdMode
+  });
+
   if (options.dryRun) {
     const preview = {
       template: template.title, templateId: template.id, version,
-      projectId, serverName, provider, datacenter, serverType, support, adminEmail, serviceType
+      projectId, serverName, provider, datacenter, serverType, support, adminEmail, serviceType,
+      cluster: cluster ? { mode: cluster.mode, nodes: cluster.nodes, isReplica: cluster.isReplica } : null,
+      topology: describeCluster(cluster)
     };
 
     if (options.json) {
-      outputJson({ dryRun: true, ...preview });
+      outputJson({ dryRun: true, ...preview, payload });
       return preview;
     }
 
@@ -148,6 +166,8 @@ export async function deployService(templateNameOrId, options = {}) {
     console.log(`  Size:       ${serverType}`);
     console.log(`  Support:    ${support}`);
     console.log(`  Admin:      ${adminEmail}`);
+    console.log(`  Topology:   ${describeCluster(cluster)}`);
+    if (cluster) console.log(`  ${colors.yellow}Billing is per VM: ${cluster.nodes} VMs will be created.${colors.reset}`);
     console.log('');
     log('info', 'To deploy, run the same command without --dry-run');
     return preview;
@@ -156,17 +176,7 @@ export async function deployService(templateNameOrId, options = {}) {
   log('info', `Deploying ${template.title} (ID: ${template.id})`);
   log('info', `  Project: ${projectId} | Name: ${serverName}`);
   log('info', `  Provider: ${provider} | Size: ${serverType} @ ${datacenter}`);
-
-  const payload = {
-    templateID: String(template.id), serverType, datacenter,
-    providerName: provider, serverName, appid: 'Cloudxx',
-    data: 'data', support, projectId: String(projectId),
-    version, adminEmail, deploymentServiceType: 'normal', serviceType
-  };
-
-  if (isCicd) {
-    payload.cicdPayload = { pipelineName: options.pipelineName || serverName };
-  }
+  if (cluster) log('info', `  Cluster: ${describeCluster(cluster)}`);
 
   const response = await apiRequest('/api/servers/createServer', 'POST', payload);
 
@@ -175,6 +185,7 @@ export async function deployService(templateNameOrId, options = {}) {
   }
 
   log('success', `Deployment started! Provider Server ID: ${response.providerServerID}`);
+  if (cluster) log('info', 'Replicas are configured after the primary is up; follow progress with: elestio clusters list');
 
   if (options.wait !== false) {
     log('info', 'Waiting for deployment to complete...');
@@ -185,26 +196,27 @@ export async function deployService(templateNameOrId, options = {}) {
 }
 
 export async function waitForDeployment(vmID, projectId, timeoutMs = 600000) {
+  const ids = parseVmIDs(vmID);
+  if (ids.length === 0) throw new Error('No vmID to wait for');
+
   const start = Date.now();
-  let lastStatus = '';
+  let lastSummary = '';
 
   while (Date.now() - start < timeoutMs) {
-    const services = await listServicesRaw(projectId);
-    const svc = services.find(s =>
-      String(s.vmID) === String(vmID) || String(s.providerServerID) === String(vmID)
-    );
+    const progress = deploymentProgress(await listServicesRaw(projectId), ids);
 
-    if (!svc) { await sleep(10000); continue; }
+    if (progress.services.length === 0) { await sleep(10000); continue; }
 
-    if (svc.deploymentStatus !== lastStatus) {
-      lastStatus = svc.deploymentStatus;
-      log('info', `Status: ${svc.deploymentStatus}`);
+    if (progress.summary !== lastSummary) {
+      lastSummary = progress.summary;
+      log('info', `Status: ${progress.summary}`);
     }
 
-    if (svc.deploymentStatus === 'Deployed' && svc.status === 'running') {
+    if (progress.done) {
       log('success', 'Deployment complete!');
-      console.log('\n' + formatService(svc) + '\n');
-      return svc;
+      for (const svc of progress.services) console.log('\n' + formatService(svc));
+      console.log('');
+      return ids.length === 1 ? progress.services[0] : progress.services;
     }
 
     await sleep(15000);

package/src/config.js

@@ -21,6 +21,15 @@ const DEFAULT_CONFIG = {
 function ensureDir() {
   if (!fs.existsSync(ELESTIO_DIR)) {
     fs.mkdirSync(ELESTIO_DIR, { mode: 0o700, recursive: true });
+    return;
+  }
+
+  // A directory created by an older version (or restored from a backup) may be
+  // group/world readable; both files below hold credentials.
+  try {
+    fs.chmodSync(ELESTIO_DIR, 0o700);
+  } catch {
+    // ignore
   }
 }
 
@@ -48,6 +57,11 @@ export function saveCredentials(email, apiToken) {
     JSON.stringify({ email, apiToken }, null, 2),
     { mode: 0o600 }
   );
+  try {
+    fs.chmodSync(CREDENTIALS_PATH, 0o600);
+  } catch {
+    // ignore
+  }
 }
 
 // ── Config (jwt, defaults, defaultProject) ──
@@ -74,9 +88,15 @@ export function loadConfig() {
 
 export function saveConfig(config) {
   ensureDir();
-  // Never persist credentials in config.json
+  // Never persist the API token in config.json -- but the JWT it does hold is a
+  // bearer credential, so the file is owner-only like the credentials file.
   const { email, apiToken, ...safeConfig } = config;
-  fs.writeFileSync(CONFIG_PATH, JSON.stringify(safeConfig, null, 2));
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(safeConfig, null, 2), { mode: 0o600 });
+  try {
+    fs.chmodSync(CONFIG_PATH, 0o600);
+  } catch {
+    // ignore
+  }
 }
 
 // ── Exports ──

package/src/constants.js

@@ -0,0 +1,76 @@
+// ── Clustering ──
+//
+// The catalog marks clusterable software with isCluster=1, and that is what we
+// trust: it tracks new templates on its own. The list below is only the offline
+// fallback for when a template object is unavailable -- it mirrors the
+// dashboard's hardcoded list and is therefore always at risk of lagging.
+
+export const CLUSTER_TEMPLATE_IDS = [
+  3,   // Redis
+  11,  // PostgreSQL
+  12,  // MySQL
+  45,  // TimescaleDB
+  54,  // N8N
+  66,  // Vaultwarden
+  75,  // KeyDB
+  93,  // ClickHouse
+  108, // Keycloak
+  183, // Vault
+  195, // OpenSearch
+  212, // RabbitMQ
+  309, // Nebula
+  436, // Valkey
+  467, // rke2
+  488, // Nats
+  490, // pgvector
+  497  // pgDuckDB
+];
+
+// Quorum-based software needs an odd number of nodes to elect a leader.
+export const CLUSTER_MIN_THREE_NODES = [93, 183, 195, 212, 467, 488];
+
+// Only MySQL offers writes on more than one node.
+export const CLUSTER_MULTI_MASTER_TEMPLATE_IDS = [12];
+
+export const CLUSTER_MAX_NODES = 15;
+
+export const CLUSTER_MODES = ['primary-replica', 'multi-master'];
+
+/**
+ * Minimum node count (primary included) accepted for a template.
+ */
+export function minClusterNodes(templateId) {
+  return CLUSTER_MIN_THREE_NODES.includes(Number(templateId)) ? 3 : 2;
+}
+
+/**
+ * @param {object|number} template  a catalog template, or just its ID
+ */
+export function supportsClustering(template) {
+  if (template && typeof template === 'object' && template.isCluster !== undefined) {
+    return Number(template.isCluster) === 1;
+  }
+  const id = Number(template && typeof template === 'object' ? template.id : template);
+  return CLUSTER_TEMPLATE_IDS.includes(id);
+}
+
+export function supportsMultiMaster(templateId) {
+  return CLUSTER_MULTI_MASTER_TEMPLATE_IDS.includes(Number(templateId));
+}
+
+// ── CI/CD ──
+
+export const CICD_TARGET_TEMPLATE_ID = 234;
+
+// Accepted by createServer's cicdPayload.CICDMode and by createCiCdExistServer.
+export const CICD_MODES = ['GITHUB', 'GITLAB', 'GITLAB_SELF_HOSTED', 'DockerCompose'];
+
+// Where `elestio cicd deploy-template` sources catalog software from.
+export const TEMPLATE_REPO_OWNER = 'elestio-examples';
+export const TEMPLATE_REPO_HOST = 'https://github.com';
+
+export const RUNTIME_PRESETS = {
+  static: { runtime: 'staticSPA', buildDir: '/dist', framework: 'Vite.js', buildCmd: 'npm run build', runCmd: '', installCmd: 'npm install', version: '20', containerPort: '3000' },
+  node: { runtime: 'NodeJs', buildDir: '/', framework: 'No Framework', buildCmd: 'npm run build', runCmd: 'npm start', installCmd: 'npm install', version: '20', containerPort: '3000' },
+  docker: { runtime: 'NodeJs', buildDir: '/', framework: 'NoFramework', buildCmd: '', runCmd: '', installCmd: '', version: '20', containerPort: '3000' }
+};

package/src/deployment.js

@@ -0,0 +1,33 @@
+/**
+ * Deployment tracking, kept free of I/O so it can be tested.
+ *
+ * createServer answers a single service with one providerServerID, but a
+ * cluster with every node in one comma-separated string ("947349,947350").
+ * Comparing that string to a service's vmID never matches, so waiting on a
+ * cluster used to run until the timeout.
+ */
+
+export function parseVmIDs(value) {
+  const parts = Array.isArray(value) ? value : String(value ?? '').split(',');
+  return parts.map(id => String(id).trim()).filter(Boolean);
+}
+
+function matches(service, id) {
+  return String(service.vmID) === id || String(service.providerServerID) === id;
+}
+
+function isReady(service) {
+  return service.deploymentStatus === 'Deployed' && service.status === 'running';
+}
+
+export function deploymentProgress(services, ids) {
+  const found = ids.map(id => ({ id, service: services.find(s => matches(s, id)) }));
+  const present = found.filter(f => f.service);
+
+  return {
+    services: present.map(f => f.service),
+    missing: found.filter(f => !f.service).map(f => f.id),
+    done: ids.length > 0 && present.length === ids.length && present.every(f => isReady(f.service)),
+    summary: present.map(f => `${f.id}: ${f.service.deploymentStatus}`).join(', ')
+  };
+}