@celilo/cli 0.5.0-alpha.9 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.5.0-alpha.9",
+  "version": "0.6.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -52,7 +52,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1024.0",
-    "@celilo/capabilities": "^0.4.2",
+    "@celilo/capabilities": "^0.5.0",
     "@celilo/cli-display": "^0.1.9",
     "@celilo/event-bus": "^0.1.7",
     "@clack/prompts": "^1.1.0",

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

@@ -6,7 +6,7 @@ import {
   findNodeForVmid,
   pollTaskUntilDone,
   selectFreeVmid,
-  selectIsoStorage,
+  selectImportStorage,
   summarizeNodeCapacities,
 } from './proxmox';
 
@@ -137,38 +137,48 @@ describe('filterVmTemplates — extract VM templates from a /nodes/{node}/qemu l
   });
 });
 
-describe('selectIsoStorage — pick a storage that accepts iso content', () => {
-  test('returns the first active, enabled storage whose content includes iso', () => {
+describe('selectImportStorage — pick a storage that accepts import content', () => {
+  test('returns the first active, enabled storage whose content includes import', () => {
     const storages = [
       { storage: 'local-lvm', content: 'images,rootdir', active: 1, enabled: 1 },
-      { storage: 'local', content: 'iso,vztmpl,backup', active: 1, enabled: 1 },
+      { storage: 'local', content: 'import,vztmpl,backup', active: 1, enabled: 1 },
     ];
-    expect(selectIsoStorage(storages)).toBe('local');
+    expect(selectImportStorage(storages)).toBe('local');
   });
 
-  test('skips an iso-capable storage that is inactive', () => {
+  test('does NOT pick an iso-only storage (import-from rejects iso content)', () => {
+    // Regression guard: the cloud image must land in the import namespace, not
+    // iso/, or the VM-create `import-from=` fails with `has wrong type 'iso'`.
     const storages = [
-      { storage: 'cold', content: 'iso', active: 0, enabled: 1 },
-      { storage: 'local', content: 'iso', active: 1, enabled: 1 },
+      { storage: 'iso-only', content: 'iso,vztmpl,backup', active: 1, enabled: 1 },
+      { storage: 'data', content: 'import,images', active: 1, enabled: 1 },
     ];
-    expect(selectIsoStorage(storages)).toBe('local');
+    expect(selectImportStorage(storages)).toBe('data');
   });
 
-  test('skips an iso-capable storage that is disabled', () => {
+  test('skips an import-capable storage that is inactive', () => {
     const storages = [
-      { storage: 'off', content: 'iso', active: 1, enabled: 0 },
-      { storage: 'local', content: 'iso', active: 1, enabled: 1 },
+      { storage: 'cold', content: 'import', active: 0, enabled: 1 },
+      { storage: 'local', content: 'import', active: 1, enabled: 1 },
     ];
-    expect(selectIsoStorage(storages)).toBe('local');
+    expect(selectImportStorage(storages)).toBe('local');
   });
 
-  test('returns null when no storage accepts iso content', () => {
+  test('skips an import-capable storage that is disabled', () => {
+    const storages = [
+      { storage: 'off', content: 'import', active: 1, enabled: 0 },
+      { storage: 'local', content: 'import', active: 1, enabled: 1 },
+    ];
+    expect(selectImportStorage(storages)).toBe('local');
+  });
+
+  test('returns null when no storage accepts import content', () => {
     const storages = [{ storage: 'local-lvm', content: 'images,rootdir', active: 1, enabled: 1 }];
-    expect(selectIsoStorage(storages)).toBeNull();
+    expect(selectImportStorage(storages)).toBeNull();
   });
 
   test('returns null for an empty storage list', () => {
-    expect(selectIsoStorage([])).toBeNull();
+    expect(selectImportStorage([])).toBeNull();
   });
 });
 
@@ -200,15 +210,15 @@ describe('selectFreeVmid — first free VMID >= minVmid (template hygiene)', ()
   });
 });
 
-describe('buildCloudImageVolid — volid for a cloud image on iso storage', () => {
-  test('places the filename under the storage iso/ namespace', () => {
+describe('buildCloudImageVolid — volid for a cloud image on import storage', () => {
+  test('places the filename under the storage import/ namespace', () => {
     expect(buildCloudImageVolid('local', 'noble-server-cloudimg-amd64.img')).toBe(
-      'local:iso/noble-server-cloudimg-amd64.img',
+      'local:import/noble-server-cloudimg-amd64.img',
     );
   });
 
   test('works with an arbitrary storage name', () => {
-    expect(buildCloudImageVolid('nas-iso', 'jammy.img')).toBe('nas-iso:iso/jammy.img');
+    expect(buildCloudImageVolid('nas', 'jammy.img')).toBe('nas:import/jammy.img');
   });
 });
 

package/src/api-clients/proxmox.ts

@@ -890,30 +890,38 @@ export async function listVmTemplates(
   return { success: true, data: filterVmTemplates(result.data) };
 }
 
-/** Storage row shape (subset) used when picking ISO-capable storage. */
+/** Storage row shape (subset) used when picking import-capable storage. */
 type ProxmoxStorageRow = { storage: string; content: string; active: number; enabled: number };
 
 /**
- * Pick the first active, enabled storage that accepts `iso` content. Pure
+ * Pick the first active, enabled storage that accepts `import` content. Pure
  * selection logic, split from the network call for testability (Rule 10).
  * Returns the storage name, or null when none qualifies.
+ *
+ * Must be `import`, NOT `iso`: the cloud image is consumed via the VM-create
+ * `import-from=` parameter, which Proxmox only accepts from a source on a
+ * storage whose content type is `images` or `import`. A `.img` downloaded to
+ * the `iso/` namespace is rejected with `has wrong type 'iso'`. The
+ * `download-url` endpoint accepts `content=import` on PVE 8.2+, so we download
+ * straight into the import namespace. (PVE 8.2+; node fleet is 9.x.)
  */
-export function selectIsoStorage(storages: ProxmoxStorageRow[]): string | null {
-  const iso = storages.find((s) => s.active && s.enabled && s.content.includes('iso'));
-  return iso?.storage ?? null;
+export function selectImportStorage(storages: ProxmoxStorageRow[]): string | null {
+  const match = storages.find((s) => s.active && s.enabled && s.content.includes('import'));
+  return match?.storage ?? null;
 }
 
 /**
- * Find a storage on the node that accepts `iso` content (for downloading cloud
- * images). Returns the storage name, or null if none found.
+ * Find a storage on the node that accepts `import` content (for downloading
+ * cloud images that will be imported as a VM disk). Returns the storage name,
+ * or null if none found.
  */
-export async function findIsoStorage(
+export async function findImportStorage(
   credentials: ProxmoxCredentials,
   nodeName: string,
 ): Promise<ProxmoxResult<string | null>> {
   const result = await listNodeStorage(credentials, nodeName);
   if (!result.success) return result;
-  return { success: true, data: selectIsoStorage(result.data) };
+  return { success: true, data: selectImportStorage(result.data) };
 }
 
 /**
@@ -953,20 +961,22 @@ export async function findFreeTemplateVmid(
 }
 
 /**
- * Download a cloud image URL to ISO storage on the node. Returns a UPID for
- * status polling. Requires PVE 7.2+ (`download-url` endpoint).
+ * Download a cloud image URL to `import` storage on the node. Returns a UPID
+ * for status polling. Requires PVE 8.2+ (`download-url` with `content=import`).
+ * The image MUST land in the import namespace (not iso) so the VM-create
+ * `import-from=` accepts it — see selectImportStorage.
  */
 export async function downloadCloudImage(
   credentials: ProxmoxCredentials,
   nodeName: string,
-  isoStorage: string,
+  importStorage: string,
   url: string,
   filename: string,
 ): Promise<ProxmoxResult<string>> {
   return makeProxmoxPost<string>(
     credentials,
-    `/nodes/${nodeName}/storage/${isoStorage}/download-url`,
-    { url, filename, content: 'iso' },
+    `/nodes/${nodeName}/storage/${importStorage}/download-url`,
+    { url, filename, content: 'import' },
   );
 }
 
@@ -1003,13 +1013,14 @@ export async function pollTaskUntilDone(
 }
 
 /**
- * Build the volid for a cloud image downloaded to ISO storage. Pure path
+ * Build the volid for a cloud image downloaded to `import` storage. Pure path
  * construction, split out for testability (Rule 10) — mirrors buildTemplatePath.
- * Proxmox's `download-url` with `content=iso` stores the `.img` under the
- * storage's `iso/` namespace, so the volid is `<storage>:iso/<filename>`.
+ * Proxmox's `download-url` with `content=import` stores the `.img` under the
+ * storage's `import/` namespace, so the volid is `<storage>:import/<filename>`.
+ * This is the namespace the VM-create `import-from=` accepts (iso/ is rejected).
  */
-export function buildCloudImageVolid(isoStorage: string, filename: string): string {
-  return `${isoStorage}:iso/${filename}`;
+export function buildCloudImageVolid(importStorage: string, filename: string): string {
+  return `${importStorage}:import/${filename}`;
 }
 
 export interface CreateVmFromCloudImageParams {
@@ -1017,8 +1028,8 @@ export interface CreateVmFromCloudImageParams {
   nodeName: string;
   vmid: number;
   name: string;
-  /** Volume ID of the downloaded cloud image, e.g. `local:iso/noble-server-cloudimg-amd64.img` */
-  isoVolid: string;
+  /** Volume ID of the downloaded cloud image, e.g. `local:import/noble-server-cloudimg-amd64.img` */
+  imageVolid: string;
   /** Storage for the imported VM disk and the cloud-init drive */
   diskStorage: string;
 }
@@ -1038,7 +1049,7 @@ export interface CreateVmFromCloudImageParams {
 export async function createVmFromCloudImage(
   params: CreateVmFromCloudImageParams,
 ): Promise<ProxmoxResult<string>> {
-  const { credentials, nodeName, vmid, name, isoVolid, diskStorage } = params;
+  const { credentials, nodeName, vmid, name, imageVolid, diskStorage } = params;
   return makeProxmoxPost<string>(credentials, `/nodes/${nodeName}/qemu`, {
     vmid: String(vmid),
     name,
@@ -1050,7 +1061,7 @@ export async function createVmFromCloudImage(
     serial0: 'socket',
     vga: 'serial0',
     boot: 'order=scsi0',
-    scsi0: `${diskStorage}:0,import-from=${isoVolid}`,
+    scsi0: `${diskStorage}:0,import-from=${imageVolid}`,
     ide2: `${diskStorage}:cloudinit`,
   });
 }

package/src/cli/command-registry.ts

@@ -435,6 +435,25 @@ export const COMMANDS: CommandDef[] = [
           },
         ],
       },
+      {
+        name: 'upgrade',
+        description:
+          'Upgrade a module to its latest registry version: update → backup (posture-gated) → deploy → verify. No id = the CD poll: upgrade every auto_upgrade module with a newer version.',
+        args: [
+          {
+            name: 'id',
+            description: 'Module ID (omit to poll all auto_upgrade modules)',
+            completion: 'module_ids',
+          },
+        ],
+        flags: [
+          {
+            name: 'registry',
+            description: 'Registry URL (defaults to configured registry)',
+            takesValue: true,
+          },
+        ],
+      },
       {
         name: 'verify',
         description: 'Verify module integrity (signature + checksums)',

package/src/cli/commands/module-update.test.ts

@@ -0,0 +1,252 @@
+/**
+ * Unit tests for the version-change classifier used by `module update`'s
+ * registry-sweep mode, plus integration tests for `updateOne`'s
+ * `displayVersion` / `quiet` opts that drive the cleaner sweep output.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { eq } from 'drizzle-orm';
+import { type DbClient, getDb } from '../../db/client';
+import { modules } from '../../db/schema';
+import { classifyVersionChange, updateOne } from './module-update';
+
+describe('classifyVersionChange', () => {
+  test('identical versions are up-to-date', () => {
+    expect(classifyVersionChange('1.0.0', '1.0.0')).toBe('up-to-date');
+    expect(classifyVersionChange('1.0.0+3', '1.0.0+3')).toBe('up-to-date');
+    expect(classifyVersionChange('2.4.7+5', '2.4.7+5')).toBe('up-to-date');
+  });
+
+  test('major bump → breaking', () => {
+    expect(classifyVersionChange('1.0.0+3', '2.0.0+1')).toBe('major');
+    expect(classifyVersionChange('1.5.9', '2.0.0')).toBe('major');
+    // Even a tiny step into the next major counts as breaking; the
+    // operator decides whether to take it.
+    expect(classifyVersionChange('1.0.0+9', '2.0.0+0')).toBe('major');
+  });
+
+  test('minor bump → non-breaking', () => {
+    expect(classifyVersionChange('1.0.0+3', '1.1.0+1')).toBe('minor');
+    expect(classifyVersionChange('2.5.0', '2.6.0')).toBe('minor');
+  });
+
+  test('patch bump → non-breaking', () => {
+    expect(classifyVersionChange('1.0.0+3', '1.0.1+1')).toBe('patch');
+    expect(classifyVersionChange('2.5.7', '2.5.8')).toBe('patch');
+  });
+
+  test('revision-only bump (+N) → patch (non-breaking)', () => {
+    // Exact case the user is hitting today: same code, fresh publish.
+    expect(classifyVersionChange('1.0.0+3', '1.0.0+4')).toBe('patch');
+    expect(classifyVersionChange('namecheap-1.0.0', 'namecheap-1.0.0+5')).not.toBe('major');
+    expect(classifyVersionChange('3.1.0+0', '3.1.0+9')).toBe('patch');
+  });
+
+  test('installed ahead of registry → ahead (skip silently)', () => {
+    // Operator pushed locally without publishing — registry is stale.
+    expect(classifyVersionChange('2.0.0+1', '1.5.0+9')).toBe('ahead');
+    expect(classifyVersionChange('1.0.1', '1.0.0')).toBe('ahead');
+    expect(classifyVersionChange('1.0.0+5', '1.0.0+3')).toBe('ahead');
+  });
+
+  test('tolerates `v` / `=` prefixes', () => {
+    expect(classifyVersionChange('v1.0.0+3', 'v1.0.0+4')).toBe('patch');
+    expect(classifyVersionChange('=1.0.0', '=1.1.0')).toBe('minor');
+  });
+
+  test('missing patch / revision segments default to 0', () => {
+    expect(classifyVersionChange('1.0', '1.0.1')).toBe('patch');
+    expect(classifyVersionChange('1.0', '2.0')).toBe('major');
+    expect(classifyVersionChange('1.0.0', '1.0.0+1')).toBe('patch');
+  });
+});
+
+describe('updateOne — displayVersion and quiet', () => {
+  let tempDir: string;
+  let srcDir: string;
+  let installedDir: string;
+  let db: DbClient;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'celilo-upgrade-'));
+    process.env.CELILO_DB_PATH = join(tempDir, 'test.db');
+    process.env.CELILO_ORIGINAL_CWD = tempDir;
+
+    // Pre-installed module landing zone (where files get copied to).
+    installedDir = join(tempDir, 'installed', 'testmod');
+    mkdirSync(installedDir, { recursive: true });
+
+    // "New" source dir we're upgrading from (mimics a registry extract).
+    srcDir = join(tempDir, 'src');
+    mkdirSync(srcDir, { recursive: true });
+    writeFileSync(
+      join(srcDir, 'manifest.yml'),
+      `celilo_contract: "1.0"
+id: testmod
+name: Test Module
+version: 1.0.0
+description: fixture
+`,
+    );
+
+    db = getDb();
+    // Seed the modules table with the "currently installed" record.
+    // We deliberately put a registry-style version string in here so
+    // displayVersion-less upgrades preserve the previousVersion field.
+    db.insert(modules)
+      .values({
+        id: 'testmod',
+        name: 'Test Module',
+        sourcePath: installedDir,
+        version: '1.0.0+5',
+        manifestData: {
+          celilo_contract: '1.0',
+          id: 'testmod',
+          name: 'Test Module',
+          version: '1.0.0',
+        },
+      })
+      .run();
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+    process.env.CELILO_DB_PATH = undefined;
+    process.env.CELILO_ORIGINAL_CWD = undefined;
+  });
+
+  test('returns previousVersion + newVersion in the success outcome', async () => {
+    const result = await updateOne(srcDir, db, {}, { quiet: true });
+    expect(result.status).toBe('success');
+    if (result.status !== 'success') return; // narrow for ts
+    expect(result.moduleId).toBe('testmod');
+    expect(result.previousVersion).toBe('1.0.0+5');
+    // No displayVersion supplied → falls back to the new manifest's
+    // semver core (no +N visible to the operator from a path upgrade).
+    expect(result.newVersion).toBe('1.0.0');
+  });
+
+  test('displayVersion is persisted to modules.version (so +N survives)', async () => {
+    // The bug case: registry says 1.0.0+6, manifest says 1.0.0. Without
+    // displayVersion, the +6 was dropped on the floor and `module list`
+    // rolled back to "1.0.0", masking the actual installed revision.
+    const result = await updateOne(srcDir, db, {}, { quiet: true, displayVersion: '1.0.0+6' });
+    expect(result.status).toBe('success');
+    if (result.status !== 'success') return;
+    expect(result.newVersion).toBe('1.0.0+6');
+
+    const row = db.select().from(modules).all()[0];
+    expect(row.version).toBe('1.0.0+6');
+  });
+
+  test('quiet=true suppresses the per-call log lines (caller renders its own)', async () => {
+    // We can't easily intercept @clack's log output without adding test
+    // hooks, so instead we exercise that the call simply succeeds and
+    // returns the structured outcome — the sweep relies on this to
+    // render its own output without duplicates. A non-quiet call
+    // exercises the same code path with the log lines enabled; both
+    // return the same shape.
+    const quietResult = await updateOne(srcDir, db, {}, { quiet: true });
+    expect(quietResult.status).toBe('success');
+    if (quietResult.status !== 'success') return;
+    expect(quietResult.newVersion).toBe('1.0.0');
+  });
+
+  // Regression for the namecheap stale-findings problem: the upgrade
+  // path MUST overwrite manifestData with the new manifest — otherwise
+  // any subsequent audit (or any code path that reads from the DB)
+  // sees the OLD manifest's required vars even after the operator
+  // upgraded to a version that removed them. The user hit this on
+  // celilo-mgmt: namecheap@3.1.1+6 dropped the `domains` variable, but
+  // post-upgrade the audit still complained "required config 'domains'
+  // is not set" because the DB's manifestData hadn't been refreshed.
+  test('persists new manifest to modules.manifestData (not just .version)', async () => {
+    // Write a brand-new manifest.yml in srcDir that REMOVES a
+    // variable the old DB record had. After upgrade, the modules
+    // row's manifestData should reflect the removal.
+    writeFileSync(
+      join(srcDir, 'manifest.yml'),
+      `celilo_contract: "1.0"
+id: testmod
+name: Test Module Renamed
+version: 2.0.0
+description: fixture v2
+variables:
+  owns: []
+  imports: []
+`,
+    );
+    // Simulate the DB starting in a state where manifestData has a
+    // `variables.owns` array — the namecheap-3.1.0 → 3.1.1 case.
+    db.update(modules)
+      .set({
+        manifestData: {
+          celilo_contract: '1.0',
+          id: 'testmod',
+          name: 'Test Module',
+          version: '1.0.0',
+          variables: { owns: [{ name: 'domains', type: 'array', required: true }], imports: [] },
+        },
+      })
+      .where(eq(modules.id, 'testmod'))
+      .run();
+
+    const result = await updateOne(srcDir, db, {}, { quiet: true, displayVersion: '2.0.0+1' });
+    expect(result.status).toBe('success');
+
+    const row = db.select().from(modules).all()[0];
+    // version field updates (this part already worked):
+    expect(row.version).toBe('2.0.0+1');
+    expect(row.name).toBe('Test Module Renamed');
+    // manifestData reflects the NEW manifest — the dropped variable
+    // is gone. This is the regression assertion.
+    const manifest = row.manifestData as {
+      version: string;
+      name: string;
+      variables?: { owns: unknown[] };
+    };
+    expect(manifest.version).toBe('2.0.0');
+    expect(manifest.name).toBe('Test Module Renamed');
+    expect(manifest.variables?.owns ?? []).toEqual([]);
+  });
+
+  // Regression for ISS-0091: `module update` used to skip event-bus
+  // subscription registration (only `module import` did it), so a
+  // refreshed module silently lost its reconcile subscriptions — found
+  // live when caddy's reconcile_routes subscription vanished after a
+  // path-based update.
+  test('registers the new manifest subscriptions on the bus (ISS-0091)', async () => {
+    process.env.EVENT_BUS_DB = join(tempDir, 'events.db');
+    try {
+      writeFileSync(
+        join(srcDir, 'manifest.yml'),
+        `celilo_contract: "1.0"
+id: testmod
+name: Test Module
+version: 1.1.0
+description: fixture with subscriptions
+subscriptions:
+  - name: testmod-tick
+    pattern: timer.tick.15m
+    handler: "true"
+`,
+      );
+      const result = await updateOne(srcDir, db, {}, { quiet: true });
+      expect(result.status).toBe('success');
+
+      const { openBus, defineEvents } = await import('@celilo/event-bus');
+      const bus = openBus({ dbPath: join(tempDir, 'events.db'), events: defineEvents({}) });
+      try {
+        // Subscriber names are scoped `<module-id>.<sub-name>` on the bus.
+        expect(bus.getSubscriberByName('testmod.testmod-tick')).not.toBeNull();
+      } finally {
+        bus.close();
+      }
+    } finally {
+      process.env.EVENT_BUS_DB = undefined;
+    }
+  });
+});