@celilo/cli 0.5.0-alpha.8 → 0.5.0-alpha.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.5.0-alpha.8",
+  "version": "0.5.0-alpha.9",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

package/src/api-clients/proxmox.test.ts

@@ -1,11 +1,13 @@
 import { describe, expect, test } from 'bun:test';
 import {
+  type ProxmoxClusterResource,
   buildCloudImageVolid,
   filterVmTemplates,
   findNodeForVmid,
   pollTaskUntilDone,
   selectFreeVmid,
   selectIsoStorage,
+  summarizeNodeCapacities,
 } from './proxmox';
 
 describe('findNodeForVmid (ISS-0090 — Proxmox is source of truth for current location)', () => {
@@ -36,6 +38,82 @@ describe('findNodeForVmid (ISS-0090 — Proxmox is source of truth for current l
   });
 });
 
+describe('summarizeNodeCapacities (ISS-0060 — per-node capacity reconciled from Proxmox)', () => {
+  const GB = 1024 * 1024 * 1024;
+  const resources: ProxmoxClusterResource[] = [
+    {
+      type: 'node',
+      node: 'node3',
+      status: 'online',
+      maxmem: 16 * GB,
+      mem: 4 * GB,
+      maxcpu: 8,
+      cpu: 0.25,
+      maxdisk: 200 * GB,
+      disk: 50 * GB,
+      uptime: 3600,
+    },
+    {
+      type: 'node',
+      node: 'node2',
+      status: 'offline',
+      maxmem: 8 * GB,
+      mem: 7 * GB,
+      maxcpu: 4,
+      cpu: 0.9,
+      maxdisk: 100 * GB,
+      disk: 90 * GB,
+      uptime: 0,
+    },
+    // Guest + storage rows must be ignored.
+    { type: 'lxc', vmid: 200, node: 'node2', status: 'running' },
+    { type: 'storage', node: 'node3', status: 'available' },
+  ];
+
+  test('derives free RAM/CPU/disk and online state from node rows only', () => {
+    const caps = summarizeNodeCapacities(resources);
+    expect(caps).toHaveLength(2); // guest + storage rows dropped
+    // Sorted by node name → node2 first.
+    expect(caps[0]).toEqual({
+      node: 'node2',
+      online: false,
+      memTotalMb: 8192,
+      memFreeMb: 1024,
+      cpuCores: 4,
+      cpuUsedPct: 90,
+      diskTotalGb: 100,
+      diskFreeGb: 10,
+      uptimeSec: 0,
+    });
+    expect(caps[1]).toMatchObject({
+      node: 'node3',
+      online: true,
+      memFreeMb: 12288,
+      cpuUsedPct: 25,
+      diskFreeGb: 150,
+    });
+  });
+
+  test('tolerates missing fields (treats absent capacity as 0, offline unless status==online)', () => {
+    const caps = summarizeNodeCapacities([{ type: 'node', node: 'bare' }]);
+    expect(caps[0]).toEqual({
+      node: 'bare',
+      online: false,
+      memTotalMb: 0,
+      memFreeMb: 0,
+      cpuCores: 0,
+      cpuUsedPct: 0,
+      diskTotalGb: 0,
+      diskFreeGb: 0,
+      uptimeSec: 0,
+    });
+  });
+
+  test('empty inventory → no nodes', () => {
+    expect(summarizeNodeCapacities([])).toEqual([]);
+  });
+});
+
 describe('filterVmTemplates — extract VM templates from a /nodes/{node}/qemu listing', () => {
   test('keeps only guests flagged template===1 and projects to {vmid, name}', () => {
     const guests = [

package/src/api-clients/proxmox.ts

@@ -28,7 +28,7 @@ interface ProxmoxError {
   details?: Record<string, unknown>;
 }
 
-type ProxmoxResult<T> = { success: true; data: T } | ProxmoxError;
+export type ProxmoxResult<T> = { success: true; data: T } | ProxmoxError;
 
 /**
  * Make an authenticated API request to Proxmox
@@ -543,6 +543,101 @@ export function findNodeForVmid(
   return match?.node ?? null;
 }
 
+/**
+ * One row from `GET /cluster/resources`. The list is heterogeneous — `type`
+ * discriminates node / storage / guest rows. For `type: 'node'`, `status` is
+ * 'online'/'offline' and the mem/cpu/disk fields describe the node's capacity;
+ * for guests it's 'running'/'stopped' and `vmid` is set.
+ */
+export interface ProxmoxClusterResource {
+  type: string;
+  node?: string;
+  status?: string;
+  vmid?: number;
+  maxmem?: number; // bytes (node total RAM)
+  mem?: number; // bytes (node RAM in use)
+  maxcpu?: number; // cores
+  cpu?: number; // load fraction 0..1
+  maxdisk?: number; // bytes (node total disk on the relevant storage)
+  disk?: number; // bytes (disk in use)
+  uptime?: number; // seconds
+}
+
+/** Per-node capacity reconciled from Proxmox (reality, never a cached DB value). */
+export interface ProxmoxNodeCapacity {
+  node: string;
+  online: boolean;
+  memTotalMb: number;
+  memFreeMb: number;
+  cpuCores: number;
+  cpuUsedPct: number; // 0..100
+  diskTotalGb: number;
+  diskFreeGb: number;
+  uptimeSec: number;
+}
+
+const BYTES_PER_MB = 1024 * 1024;
+const BYTES_PER_GB = 1024 * 1024 * 1024;
+
+/**
+ * Summarize per-node capacity from a `/cluster/resources` list. Pure (Rule 10) —
+ * split from the network call for unit testing. Only `type: 'node'` rows count;
+ * guest and storage rows are ignored. Sorted by node name for stable output.
+ */
+export function summarizeNodeCapacities(
+  resources: ProxmoxClusterResource[],
+): ProxmoxNodeCapacity[] {
+  return resources
+    .filter((r): r is ProxmoxClusterResource & { node: string } => r.type === 'node' && !!r.node)
+    .map((r) => {
+      const maxmem = r.maxmem ?? 0;
+      const mem = r.mem ?? 0;
+      const maxdisk = r.maxdisk ?? 0;
+      const disk = r.disk ?? 0;
+      return {
+        node: r.node,
+        online: r.status === 'online',
+        memTotalMb: Math.round(maxmem / BYTES_PER_MB),
+        memFreeMb: Math.round((maxmem - mem) / BYTES_PER_MB),
+        cpuCores: r.maxcpu ?? 0,
+        cpuUsedPct: Math.round((r.cpu ?? 0) * 100),
+        diskTotalGb: Math.round(maxdisk / BYTES_PER_GB),
+        diskFreeGb: Math.round((maxdisk - disk) / BYTES_PER_GB),
+        uptimeSec: r.uptime ?? 0,
+      };
+    })
+    .sort((a, b) => a.node.localeCompare(b.node));
+}
+
+/**
+ * Cohesive Proxmox introspection client (ISS-0060). Wraps the credentials so
+ * callers don't thread them through every call, and centralizes the live reads
+ * that let celilo treat Proxmox — not a cached DB row — as the source of truth
+ * for where containers live and how much room each node has.
+ */
+export class ProxmoxClient {
+  constructor(private readonly credentials: ProxmoxCredentials) {}
+
+  /** Raw cluster resource inventory (node + guest + storage rows). */
+  async clusterResources(): Promise<ProxmoxResult<ProxmoxClusterResource[]>> {
+    return makeProxmoxRequest<ProxmoxClusterResource[]>(this.credentials, '/cluster/resources');
+  }
+
+  /** Live per-node capacity (RAM/CPU/disk/online), reconciled from Proxmox. */
+  async nodeCapacities(): Promise<ProxmoxResult<ProxmoxNodeCapacity[]>> {
+    const result = await this.clusterResources();
+    if (!result.success) return result;
+    return { success: true, data: summarizeNodeCapacities(result.data) };
+  }
+
+  /** The node a VMID currently lives on, or null if it isn't created yet. */
+  async nodeForVmid(vmid: number): Promise<ProxmoxResult<string | null>> {
+    const result = await this.clusterResources();
+    if (!result.success) return result;
+    return { success: true, data: findNodeForVmid(result.data, vmid) };
+  }
+}
+
 /**
  * List available LXC templates in storage
  */

package/src/cli/command-registry.ts

@@ -666,8 +666,16 @@ export const COMMANDS: CommandDef[] = [
             description: 'Add Proxmox container service',
             flags: [
               { name: 'api-url', description: 'Proxmox API URL', takesValue: true },
-              { name: 'token-id', description: 'API token ID', takesValue: true },
-              { name: 'token-secret', description: 'API token secret', takesValue: true },
+              {
+                name: 'api-token-id',
+                description: 'API token ID (or $PROXMOX_API_TOKEN_ID)',
+                takesValue: true,
+              },
+              {
+                name: 'api-token-secret',
+                description: 'API token secret (or $PROXMOX_API_TOKEN_SECRET)',
+                takesValue: true,
+              },
               { name: 'node', description: 'Target node', takesValue: true },
               {
                 name: 'zone',
@@ -682,7 +690,11 @@ export const COMMANDS: CommandDef[] = [
             name: 'digitalocean',
             description: 'Add DigitalOcean container service',
             flags: [
-              { name: 'api-token', description: 'DigitalOcean API token', takesValue: true },
+              {
+                name: 'api-token',
+                description: 'DigitalOcean API token (or $DIGITALOCEAN_API_TOKEN)',
+                takesValue: true,
+              },
               { name: 'region', description: 'Region', takesValue: true },
               {
                 name: 'zone',
@@ -1057,6 +1069,23 @@ export const COMMANDS: CommandDef[] = [
       },
     ],
   },
+  {
+    name: 'proxmox',
+    description: 'Proxmox cluster introspection (nodes, capacity)',
+    subcommands: [
+      {
+        name: 'node',
+        description: 'Proxmox node operations',
+        subcommands: [
+          {
+            name: 'list',
+            description: 'List cluster nodes with live capacity (RAM/CPU/disk)',
+            args: [{ name: 'service-id', description: 'Proxmox service (optional if only one)' }],
+          },
+        ],
+      },
+    ],
+  },
   {
     name: 'subscribers',
     description: 'Manage build-bus subscribers (cross-machine publish-event delivery)',

package/src/cli/commands/backup-delete.ts

@@ -3,9 +3,9 @@
  * Delete a specific backup entry and its storage file.
  */
 
-import * as p from '@clack/prompts';
 import { deleteBackupRecord, formatSize, getBackup } from '../../services/backup-metadata';
 import { createStorageProvider, getBackupStorage } from '../../services/backup-storage';
+import { askConfirm, withInterviewSession } from '../../services/bus-interview';
 import { celiloIntro, celiloOutro } from '../prompts';
 import type { CommandResult } from '../types';
 
@@ -40,13 +40,16 @@ export async function handleBackupDelete(
     console.log(`  → ${storage?.storageId ?? '?'}: ${backup.storagePath}\n`);
 
     if (!flags.force) {
-      const confirmed = await p.confirm({
-        message: 'Delete this backup?',
-        initialValue: false,
-      });
+      const confirmed = await withInterviewSession(() =>
+        askConfirm({
+          scope: `backup:${backupId}`,
+          key: 'delete',
+          message: 'Delete this backup?',
+          defaultValue: false,
+        }),
+      );
 
-      if (p.isCancel(confirmed) || !confirmed) {
-        p.cancel('Operation cancelled');
+      if (!confirmed) {
         return { success: false, error: 'Cancelled by user' };
       }
     }

package/src/cli/commands/backup-import.ts

@@ -5,8 +5,8 @@
 
 import { existsSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
-import * as p from '@clack/prompts';
 import { formatSize } from '../../services/backup-metadata';
+import { askConfirm, withInterviewSession } from '../../services/bus-interview';
 import { celiloIntro, celiloOutro } from '../prompts';
 import type { CommandResult } from '../types';
 
@@ -54,13 +54,16 @@ export async function handleBackupImport(
 
     // Confirm unless --yes
     if (!flags.yes) {
-      const confirmed = await p.confirm({
-        message: `Import this file as a backup for ${moduleId}?`,
-        initialValue: true,
-      });
-
-      if (p.isCancel(confirmed) || !confirmed) {
-        p.cancel('Import cancelled');
+      const confirmed = await withInterviewSession(() =>
+        askConfirm({
+          scope: `backup-import:${moduleId}`,
+          key: 'import',
+          message: `Import this file as a backup for ${moduleId}?`,
+          defaultValue: true,
+        }),
+      );
+
+      if (!confirmed) {
         return { success: false, error: 'Cancelled by user' };
       }
     }

package/src/cli/commands/backup-restore.ts

@@ -3,10 +3,10 @@
  * Restores from a backup archive, executing the module's on_restore hook.
  */
 
-import * as p from '@clack/prompts';
 import { formatSize, getBackup } from '../../services/backup-metadata';
 import { restoreModuleBackup, restoreSystemStateBackup } from '../../services/backup-restore';
 import { getBackupStorage } from '../../services/backup-storage';
+import { askConfirm, withInterviewSession } from '../../services/bus-interview';
 import { celiloIntro, celiloOutro } from '../prompts';
 import type { CommandResult } from '../types';
 
@@ -66,13 +66,16 @@ export async function handleBackupRestore(
 
     // Confirm unless --yes
     if (!flags.yes) {
-      const confirmed = await p.confirm({
-        message: 'Proceed with restore?',
-        initialValue: false,
-      });
-
-      if (p.isCancel(confirmed) || !confirmed) {
-        p.cancel('Restore cancelled');
+      const confirmed = await withInterviewSession(() =>
+        askConfirm({
+          scope: `backup-restore:${backupId}`,
+          key: 'proceed',
+          message: 'Proceed with restore?',
+          defaultValue: false,
+        }),
+      );
+
+      if (!confirmed) {
         return { success: false, error: 'Cancelled by user' };
       }
     }

package/src/cli/commands/events.ts

@@ -389,7 +389,7 @@ export async function handleEventsRepair(): Promise<CommandResult> {
   }
 }
 
-const INTERVIEW_FAMILIES = ['config', 'secret', 'ensure', 'aspect'] as const;
+const INTERVIEW_FAMILIES = ['config', 'secret', 'ensure', 'aspect', 'interview'] as const;
 type InterviewFamily = (typeof INTERVIEW_FAMILIES)[number];
 
 /** Classify a query event type into its interview family, or null if it isn't one. */
@@ -398,6 +398,7 @@ function interviewFamily(type: string): InterviewFamily | null {
   if (type.startsWith('secret.required.')) return 'secret';
   if (type.startsWith('ensure.required.')) return 'ensure';
   if (type.startsWith('aspect.required.')) return 'aspect';
+  if (type.startsWith('interview.required.')) return 'interview';
   return null;
 }
 
@@ -428,6 +429,10 @@ function interviewFamily(type: string): InterviewFamily | null {
  *                                base-module aspect, 'false' refuses it (ISS-0027).
  *                                Replies { consented }; the deploy records the
  *                                approval/denial.
+ *   - interview.required.<scope>.<key> → value is the answer itself, shaped per
+ *                                the question's kind ('"node3"', 'true',
+ *                                '["a","b"]'); replies { value }. The generic
+ *                                operator-command interview family (ISS-0127).
  */
 export async function handleEventsReply(
   args: string[],
@@ -476,7 +481,7 @@ export async function handleEventsReply(
       return {
         success: false,
         error: `Event ${queryId} is type '${query.type}', not an interview query.
-  Expected one of: config.required.* / secret.required.* / ensure.required.* / aspect.required.*`,
+  Expected one of: config.required.* / secret.required.* / ensure.required.* / aspect.required.* / interview.required.*`,
       };
     }
 
@@ -496,7 +501,7 @@ export async function handleEventsReply(
       });
     }
 
-    if (family === 'config') {
+    if (family === 'config' || family === 'interview') {
       bus.emitRaw(`${query.type}.reply`, { value }, { replyFor: queryId, emittedBy });
       return jsonResult({ ok: true, status: 'replied', queryId, type: query.type, family, value });
     }