@celilo/cli 0.5.0-alpha.5 → 0.5.0-alpha.7

package/src/cli/commands/proxmox-vm-template-build.ts

@@ -0,0 +1,164 @@
+/**
+ * Build a cloud-init Ubuntu VM template on Proxmox via the API (no SSH needed).
+ * Called from service-add-proxmox when the operator opts in.
+ *
+ * Steps:
+ *   1. Find ISO-capable storage on the target node.
+ *   2. Find a free template VMID (>= 9000, outside celilo's IPAM range).
+ *   3. Download Ubuntu 24.04 cloud image to ISO storage. (~2–5 min)
+ *   4. Create a VM with the cloud image imported as its boot disk + a cloud-init
+ *      CDROM drive. (~30s)
+ *   5. Convert the VM to a template. (~5s)
+ *
+ * The finished template is a blank cloud-init base — no credentials, IP, or SSH
+ * keys baked in. celilo's terraform sets those at clone time (ipconfig0, sshkeys,
+ * ciuser, nameserver). Requires PVE 8.0+ (the storage download-url endpoint is
+ * 7.2+, but importing the disk via `import-from` in the VM-create call is 8.0+,
+ * so the build as a whole needs 8.0+).
+ */
+
+import type { ProxmoxCredentials, ProxmoxVmTemplate } from '../../api-clients/proxmox';
+import {
+  buildCloudImageVolid,
+  convertVmToTemplate,
+  createVmFromCloudImage,
+  deleteVm,
+  downloadCloudImage,
+  findFreeTemplateVmid,
+  findIsoStorage,
+  listVmTemplates,
+  pollTaskUntilDone,
+} from '../../api-clients/proxmox';
+import { FuelGauge } from '../fuel-gauge';
+
+const UBUNTU_2404_AMD64_URL =
+  'https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img';
+const UBUNTU_2404_AMD64_FILENAME = 'noble-server-cloudimg-amd64.img';
+const DEFAULT_TEMPLATE_NAME = 'ubuntu-2404-cloudinit';
+
+export interface VmTemplateBuildParams {
+  credentials: ProxmoxCredentials;
+  nodeName: string;
+  diskStorage: string;
+}
+
+/**
+ * List existing VM templates on the node. Returns an empty array (not an error)
+ * if the API call fails — the caller treats failure as "no templates found".
+ */
+export async function detectExistingVmTemplates(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+): Promise<ProxmoxVmTemplate[]> {
+  const result = await listVmTemplates(credentials, nodeName);
+  return result.success ? result.data : [];
+}
+
+/**
+ * Build a cloud-init Ubuntu 24.04 VM template on the Proxmox node.
+ * Shows a FuelGauge progress indicator — takes 2–10 min depending on the
+ * operator's internet connection (image download is ~600 MB).
+ * Returns the template name (e.g. "ubuntu-2404-cloudinit").
+ * Cleans up the VM on failure so the operator isn't left with a partial guest.
+ */
+export async function buildCloudInitTemplate(params: VmTemplateBuildParams): Promise<string> {
+  const { credentials, nodeName, diskStorage } = params;
+  const gauge = new FuelGauge('Building cloud-init VM template');
+  gauge.start();
+
+  let vmid: number | null = null;
+
+  try {
+    // Step 1: find ISO storage
+    gauge.addOutput('Finding ISO-capable storage on the node…');
+    const isoStorageResult = await findIsoStorage(credentials, nodeName);
+    if (!isoStorageResult.success) {
+      throw new Error(`Could not list node storage: ${isoStorageResult.message}`);
+    }
+    const isoStorage = isoStorageResult.data;
+    if (!isoStorage) {
+      throw new Error(
+        'No ISO-capable storage found on the node. ' +
+          "Enable 'iso' content on a storage (typically 'local') in the Proxmox UI: " +
+          'Datacenter → Storage → Edit → Content.',
+      );
+    }
+    gauge.addOutput(`ISO storage: ${isoStorage}`);
+
+    // Step 2: find a free template VMID
+    gauge.addOutput('Finding a free template VMID (>= 9000)…');
+    const vmidResult = await findFreeTemplateVmid(credentials, nodeName);
+    if (!vmidResult.success) throw new Error(`VMID lookup failed: ${vmidResult.message}`);
+    vmid = vmidResult.data;
+    gauge.addOutput(`Using VMID ${vmid}`);
+
+    // Step 3: download cloud image to ISO storage
+    gauge.addOutput(
+      `Downloading Ubuntu 24.04 cloud image to '${isoStorage}' (~600 MB, may take several minutes)…`,
+    );
+    const downloadResult = await downloadCloudImage(
+      credentials,
+      nodeName,
+      isoStorage,
+      UBUNTU_2404_AMD64_URL,
+      UBUNTU_2404_AMD64_FILENAME,
+    );
+    if (!downloadResult.success) {
+      if (downloadResult.message.includes('403') || downloadResult.message.includes('not found')) {
+        throw new Error(
+          `Proxmox storage download-url endpoint rejected the request. This endpoint requires Proxmox VE 7.2+. Error: ${downloadResult.message}`,
+        );
+      }
+      throw new Error(`Cloud image download failed: ${downloadResult.message}`);
+    }
+    gauge.addOutput('Waiting for download to complete…');
+    await pollTaskUntilDone(credentials, nodeName, downloadResult.data, 600_000);
+    gauge.addOutput('Cloud image downloaded');
+
+    // Step 4: create VM from cloud image
+    const isoVolid = buildCloudImageVolid(isoStorage, UBUNTU_2404_AMD64_FILENAME);
+    gauge.addOutput(`Creating VM ${vmid} '${DEFAULT_TEMPLATE_NAME}' (importing disk)…`);
+    const createResult = await createVmFromCloudImage({
+      credentials,
+      nodeName,
+      vmid,
+      name: DEFAULT_TEMPLATE_NAME,
+      isoVolid,
+      diskStorage,
+    });
+    if (!createResult.success) {
+      throw new Error(`VM creation failed: ${createResult.message}`);
+    }
+    gauge.addOutput('Waiting for disk import to complete…');
+    await pollTaskUntilDone(credentials, nodeName, createResult.data, 120_000);
+    gauge.addOutput('VM created');
+
+    // Step 5: convert to template
+    gauge.addOutput(`Converting VM ${vmid} to a template…`);
+    const templateResult = await convertVmToTemplate(credentials, nodeName, vmid);
+    if (!templateResult.success) {
+      throw new Error(`Convert-to-template failed: ${templateResult.message}`);
+    }
+    await pollTaskUntilDone(credentials, nodeName, templateResult.data, 60_000);
+
+    gauge.stop(true);
+    return DEFAULT_TEMPLATE_NAME;
+  } catch (error) {
+    gauge.stop(false);
+
+    // Best-effort cleanup — remove the partially-created VM so the operator
+    // isn't left with a stranded guest.
+    if (vmid !== null) {
+      try {
+        const del = await deleteVm(credentials, nodeName, vmid);
+        if (del.success) {
+          console.log(`✗ Cleaned up VM ${vmid} after build failure`);
+        }
+      } catch {
+        console.log(`⚠ Could not clean up VM ${vmid} — delete it manually in the Proxmox UI`);
+      }
+    }
+
+    throw error;
+  }
+}

package/src/cli/commands/service-add-proxmox.ts

@@ -23,6 +23,7 @@ import {
   runApplianceDownload,
   selectUbuntuApplianceFromCatalog,
 } from './proxmox-template-selection';
+import { buildCloudInitTemplate, detectExistingVmTemplates } from './proxmox-vm-template-build';
 
 /**
  * Handle service add proxmox command
@@ -122,14 +123,71 @@ export async function handleServiceAddProxmox(
       validate: validateRequired('Storage'),
     });
 
-    // Find storage that supports vztmpl content. We do this BEFORE prompting
-    // for a template so the user only ever sees one storage in subsequent
-    // messages, and so the saved volid uses the right storage.
+    // Build credentials here — needed for VM template detection below and
+    // for LXC template catalog lookup further down.
     const credentials = {
       api_url: apiUrl,
       api_token_id: apiTokenId,
       api_token_secret: apiTokenSecret,
     };
+
+    // VM template for `requires.system.type: vm` modules.
+    // Auto-detect existing templates on the node; offer to build if none found.
+    // See v2/PROXMOX_VM_TEMPLATE.md.
+    let vmTemplate: string | undefined;
+    const existingTemplates = await detectExistingVmTemplates(credentials, targetNode);
+    if (existingTemplates.length > 0) {
+      const templateChoice = await p.select({
+        message: 'VM template for VM-type modules:',
+        options: [
+          ...existingTemplates.map((t) => ({
+            value: t.name,
+            label: `${t.name} (VMID ${t.vmid})`,
+          })),
+          { value: '__build__', label: 'Build a new Ubuntu 24.04 cloud-init template now' },
+          { value: '__skip__', label: 'Skip — I only need LXC modules' },
+        ],
+      });
+      if (p.isCancel(templateChoice)) {
+        p.cancel('Operation cancelled');
+        return { success: false, error: 'Cancelled by user' };
+      }
+      if (templateChoice === '__build__') {
+        vmTemplate = await buildCloudInitTemplate({
+          credentials,
+          nodeName: targetNode,
+          diskStorage: storage,
+        });
+      } else if (templateChoice !== '__skip__') {
+        vmTemplate = templateChoice;
+      }
+    } else {
+      const shouldBuild = await p.confirm({
+        message: 'No VM templates found. Build a Ubuntu 24.04 cloud-init template now? (~2–10 min)',
+        initialValue: false,
+      });
+      if (p.isCancel(shouldBuild)) {
+        p.cancel('Operation cancelled');
+        return { success: false, error: 'Cancelled by user' };
+      }
+      if (shouldBuild) {
+        vmTemplate = await buildCloudInitTemplate({
+          credentials,
+          nodeName: targetNode,
+          diskStorage: storage,
+        });
+      } else {
+        const manualEntry = await promptText({
+          message: 'VM template name (optional — leave blank to skip):',
+          placeholder: 'e.g., ubuntu-2404-cloudinit',
+        });
+        vmTemplate = manualEntry?.trim() || undefined;
+      }
+    }
+
+    // Find storage that supports vztmpl content. We do this BEFORE prompting
+    // for a template so the user only ever sees one storage in subsequent
+    // messages, and so the saved volid uses the right storage.
     console.log('\nFinding storage for templates...');
     const storageListResult = await listNodeStorage(credentials, targetNode);
 
@@ -178,6 +236,7 @@ export async function handleServiceAddProxmox(
         default_target_node: targetNode,
         lxc_template: lxcTemplate,
         storage,
+        ...(vmTemplate ? { vm_template: vmTemplate } : {}),
       },
     });
 

package/src/cli/commands/service-reconfigure.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  type ProxmoxProviderConfig,
+  buildVmTemplateChoices,
+  resolveReconfiguredProviderConfig,
+} from './service-reconfigure';
+
+describe('buildVmTemplateChoices — VM-template reconfigure menu', () => {
+  const templates = [
+    { vmid: 9000, name: 'ubuntu-2404-cloudinit' },
+    { vmid: 9001, name: 'ubuntu-2204-cloudinit' },
+  ];
+
+  test('current set + detected templates: keep first, others (current deduped), build, clear', () => {
+    const choices = buildVmTemplateChoices('ubuntu-2404-cloudinit', templates);
+    expect(choices.map((c) => c.value)).toEqual([
+      '__keep__',
+      'ubuntu-2204-cloudinit', // the other detected template — current is not re-listed
+      '__build__',
+      '__clear__',
+    ]);
+    expect(choices[0].label).toBe('Keep current (ubuntu-2404-cloudinit)');
+  });
+
+  test('current unset: no keep/clear; detected templates, build, then skip', () => {
+    const choices = buildVmTemplateChoices(undefined, templates);
+    expect(choices.map((c) => c.value)).toEqual([
+      'ubuntu-2404-cloudinit',
+      'ubuntu-2204-cloudinit',
+      '__build__',
+      '__skip__',
+    ]);
+  });
+
+  test('current set, no templates detected: keep, build, clear', () => {
+    const choices = buildVmTemplateChoices('ubuntu-2404-cloudinit', []);
+    expect(choices.map((c) => c.value)).toEqual(['__keep__', '__build__', '__clear__']);
+  });
+
+  test('current unset, no templates detected: build, skip', () => {
+    const choices = buildVmTemplateChoices(undefined, []);
+    expect(choices.map((c) => c.value)).toEqual(['__build__', '__skip__']);
+  });
+
+  test('a detected template carries its VMID in the label', () => {
+    const choices = buildVmTemplateChoices(undefined, [{ vmid: 9002, name: 'debian-12' }]);
+    expect(choices[0]).toEqual({ value: 'debian-12', label: 'debian-12 (VMID 9002)' });
+  });
+});
+
+describe('resolveReconfiguredProviderConfig — drop-bug guard (ISS-0128)', () => {
+  const current: ProxmoxProviderConfig = {
+    default_target_node: 'pve',
+    lxc_template: 'local:vztmpl/ubuntu-24.04.tar.zst',
+    storage: 'local-lvm',
+    vm_template: 'ubuntu-2404-cloudinit',
+  };
+
+  test('keeping the VM template (edit echoes current) preserves it while applying other edits', () => {
+    const result = resolveReconfiguredProviderConfig({
+      default_target_node: 'pve2',
+      lxc_template: 'local:vztmpl/ubuntu-24.04-2.tar.zst',
+      storage: 'fast-lvm',
+      vm_template: 'ubuntu-2404-cloudinit', // VM_KEEP resolves to the current value
+    });
+    expect(result).toEqual({
+      default_target_node: 'pve2',
+      lxc_template: 'local:vztmpl/ubuntu-24.04-2.tar.zst',
+      storage: 'fast-lvm',
+      vm_template: 'ubuntu-2404-cloudinit',
+    });
+  });
+
+  test('the pre-fix behavior would have dropped vm_template — guard against regressing', () => {
+    // Reconfiguring only the LXC fields must NOT lose the VM template: the
+    // handler threads currentConfig.vm_template through as the edit value.
+    const result = resolveReconfiguredProviderConfig({
+      default_target_node: current.default_target_node,
+      lxc_template: 'local:vztmpl/new.tar.zst',
+      storage: current.storage,
+      vm_template: current.vm_template,
+    });
+    expect(result.vm_template).toBe('ubuntu-2404-cloudinit');
+  });
+
+  test('clearing (undefined edit) removes the field entirely, not sets it undefined', () => {
+    const result = resolveReconfiguredProviderConfig({
+      default_target_node: 'pve',
+      lxc_template: current.lxc_template,
+      storage: current.storage,
+      vm_template: undefined,
+    });
+    expect('vm_template' in result).toBe(false);
+  });
+
+  test('setting a new template overwrites the old', () => {
+    const result = resolveReconfiguredProviderConfig({
+      default_target_node: 'pve',
+      lxc_template: current.lxc_template,
+      storage: current.storage,
+      vm_template: 'debian-12-cloudinit',
+    });
+    expect(result.vm_template).toBe('debian-12-cloudinit');
+  });
+
+  test('no VM template edit leaves it absent', () => {
+    const result = resolveReconfiguredProviderConfig({
+      default_target_node: 'pve',
+      lxc_template: 'local:vztmpl/x.tar.zst',
+      storage: 'local-lvm',
+      vm_template: undefined,
+    });
+    expect('vm_template' in result).toBe(false);
+  });
+});

package/src/cli/commands/service-reconfigure.ts

@@ -6,6 +6,7 @@
 import * as p from '@clack/prompts';
 import {
   type ProxmoxCredentials,
+  type ProxmoxVmTemplate,
   buildTemplatePath,
   extractTemplateFilename,
   listAvailableTemplates,
@@ -23,11 +24,84 @@ import {
   runApplianceDownload,
   selectUbuntuApplianceFromCatalog,
 } from './proxmox-template-selection';
+import { buildCloudInitTemplate, detectExistingVmTemplates } from './proxmox-vm-template-build';
 
-interface ProxmoxProviderConfig {
+// A `type` (not `interface`) so it carries an implicit index signature and is
+// assignable to the loose `Record<string, unknown>` providerConfig column.
+export type ProxmoxProviderConfig = {
   default_target_node: string;
   lxc_template: string;
   storage: string;
+  // VM template to clone for `requires.system.type: vm` modules. Optional —
+  // a service may only ever host LXC modules. MUST be carried through a
+  // reconfigure (ISS-0128): updateServiceProviderConfig replaces the whole
+  // column, so dropping it here silently deletes the operator's template.
+  vm_template?: string;
+};
+
+// Sentinel choices for the VM-template reconfigure step (non-template values
+// returned by the select). Any other value is an existing template name.
+const VM_KEEP = '__keep__';
+const VM_BUILD = '__build__';
+const VM_CLEAR = '__clear__';
+const VM_SKIP = '__skip__';
+
+export interface VmTemplateChoice {
+  value: string;
+  label: string;
+}
+
+/**
+ * Build the select options for the VM-template reconfigure step, given the
+ * current value and the templates detected on the node. Pure — no I/O — so the
+ * menu is unit-testable and a headless caller (ISS-0127) can resolve a choice
+ * without a prompt.
+ */
+export function buildVmTemplateChoices(
+  current: string | undefined,
+  existing: ProxmoxVmTemplate[],
+): VmTemplateChoice[] {
+  const choices: VmTemplateChoice[] = [];
+  if (current) {
+    choices.push({ value: VM_KEEP, label: `Keep current (${current})` });
+  }
+  for (const template of existing) {
+    if (template.name === current) continue;
+    choices.push({ value: template.name, label: `${template.name} (VMID ${template.vmid})` });
+  }
+  choices.push({ value: VM_BUILD, label: 'Build a new Ubuntu 24.04 cloud-init template now' });
+  choices.push(
+    current
+      ? { value: VM_CLEAR, label: 'Clear — remove the VM template' }
+      : { value: VM_SKIP, label: 'Skip — no VM template' },
+  );
+  return choices;
+}
+
+/**
+ * Resolve the full providerConfig to persist from the reconfigure interview's
+ * resolved values. The caller seeds every field from the current config (via the
+ * prompt defaults and the VM-template choice), so the result is a function of
+ * `edits` alone. vm_template is included only when set — a falsy value clears it
+ * rather than persisting an undefined key. This is the guard for the
+ * wholesale-replace drop bug (ISS-0128): vm_template is a first-class edit, not
+ * an afterthought that gets omitted from the written object.
+ */
+export function resolveReconfiguredProviderConfig(edits: {
+  default_target_node: string;
+  lxc_template: string;
+  storage: string;
+  vm_template: string | undefined;
+}): ProxmoxProviderConfig {
+  const config: ProxmoxProviderConfig = {
+    default_target_node: edits.default_target_node,
+    lxc_template: edits.lxc_template,
+    storage: edits.storage,
+  };
+  if (edits.vm_template) {
+    config.vm_template = edits.vm_template;
+  }
+  return config;
 }
 
 export async function handleServiceReconfigure(
@@ -64,7 +138,8 @@ export async function handleServiceReconfigure(
     console.log('Current configuration:');
     console.log(`  Target node: ${currentConfig.default_target_node}`);
     console.log(`  Storage: ${currentConfig.storage}`);
-    console.log(`  Template: ${currentConfig.lxc_template}`);
+    console.log(`  LXC template: ${currentConfig.lxc_template}`);
+    console.log(`  VM template: ${currentConfig.vm_template ?? '(none)'}`);
     console.log('');
 
     // Re-prompt for configurable fields with current values as defaults
@@ -159,18 +234,48 @@ export async function handleServiceReconfigure(
       console.log(`✓ Template '${templateFilename}' found`);
     }
 
-    // Update service configuration
-    await updateServiceProviderConfig(service.id, {
+    // VM template (for `requires.system.type: vm` modules). Keep the current
+    // value, swap to another detected template, build a new one, or clear it.
+    // Without this step a reconfigure would silently drop vm_template (ISS-0128).
+    let vmTemplate = currentConfig.vm_template;
+    const existingTemplates = await detectExistingVmTemplates(credentials, targetNode);
+    const vmChoice = await p.select({
+      message: 'VM template for VM-type modules:',
+      options: buildVmTemplateChoices(currentConfig.vm_template, existingTemplates),
+    });
+    if (p.isCancel(vmChoice)) {
+      p.cancel('Operation cancelled');
+      return { success: false, error: 'Cancelled by user' };
+    }
+    if (vmChoice === VM_BUILD) {
+      vmTemplate = await buildCloudInitTemplate({
+        credentials,
+        nodeName: targetNode,
+        diskStorage: storage,
+      });
+    } else if (vmChoice === VM_CLEAR || vmChoice === VM_SKIP) {
+      vmTemplate = undefined;
+    } else if (vmChoice !== VM_KEEP) {
+      vmTemplate = vmChoice; // an existing template name
+    }
+    // VM_KEEP leaves vmTemplate at currentConfig.vm_template.
+
+    // Update service configuration. resolveReconfiguredProviderConfig preserves
+    // every existing key and carries vm_template forward (ISS-0128 drop guard).
+    const newConfig = resolveReconfiguredProviderConfig({
       default_target_node: targetNode,
       lxc_template: lxcTemplate,
       storage,
+      vm_template: vmTemplate,
     });
+    await updateServiceProviderConfig(service.id, newConfig);
 
     celiloOutro(
       `Service '${serviceId}' reconfigured successfully!\n\n` +
         `  Target node: ${targetNode}\n` +
         `  Storage: ${storage}\n` +
-        `  Template: ${lxcTemplate}\n\n` +
+        `  LXC template: ${lxcTemplate}\n` +
+        `  VM template: ${vmTemplate ?? '(none)'}\n\n` +
         `Next steps:\n  - Verify: celilo service verify ${serviceId}\n  - Deploy: celilo module deploy <module-id>`,
     );
 

package/src/cli/index.ts

@@ -287,7 +287,7 @@ Examples:
   celilo events tail --type deploy.completed.lunacycle   # filter by type
   celilo events emit deploy.completed.lunacycle '{}'     # operator-fired event
   celilo events tail --type 'config.required.*'          # see pending deploy questions
-  celilo events reply 42 '"lunacycle.net"'               # answer query #42 (config)
+  celilo events reply 42 '"example.net"'               # answer query #42 (config)
 `;
   return { success: true, message: helpText.trim() };
 }
@@ -1091,7 +1091,7 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
           '',
           'Examples:',
           '  celilo hook run namecheap validate_config --debug',
-          '  celilo hook run namecheap container_created vps_ip=138.68.140.177',
+          '  celilo hook run namecheap container_created vps_ip=192.0.2.30',
         ].join('\n'),
       };
     }