@celilo/cli 0.3.16 → 0.3.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

package/src/api-clients/proxmox.ts

@@ -501,40 +501,29 @@ export async function listAvailableTemplates(
 }
 
 /**
- * Download an LXC template from Proxmox repository
- * Returns task ID (UPID) for tracking download progress
+ * Make an authenticated POST request to the Proxmox API.
+ * Shares connection/auth handling with makeProxmoxRequest; the only differences
+ * are the verb and the form-encoded body.
  */
-export async function downloadTemplate(
+async function makeProxmoxPost<T>(
   credentials: ProxmoxCredentials,
-  nodeName: string,
-  storageName: string,
-  templateUrl: string,
-): Promise<ProxmoxResult<string>> {
+  path: string,
+  params: Record<string, string>,
+): Promise<ProxmoxResult<T>> {
   return new Promise((resolve) => {
     try {
       const { api_url, api_token_id, api_token_secret } = credentials;
       const authHeader = `PVEAPIToken=${api_token_id}=${api_token_secret}`;
-      const fullUrl = `${api_url}/nodes/${nodeName}/storage/${storageName}/download-url`;
+      const fullUrl = `${api_url}${path}`;
       const url = new URL(fullUrl);
+      const postData = new URLSearchParams(params).toString();
 
       if (process.env.DEBUG) {
-        console.log(`[Proxmox] Download template: ${fullUrl}`);
-        console.log(`[Proxmox] Template URL: ${templateUrl}`);
-        console.log(`[Proxmox] Storage: ${storageName}`);
+        console.log(`[Proxmox] POST: ${fullUrl}`);
+        console.log(`[Proxmox] Body: ${postData}`);
       }
 
-      const agent = new https.Agent({
-        rejectUnauthorized: false,
-      });
-
-      // POST request with form data
-      // Note: Proxmox requires 'filename' parameter for download-url endpoint
-      const filename = templateUrl.split('/').pop() || 'template.tar.zst';
-      const postData = new URLSearchParams({
-        url: templateUrl,
-        content: 'vztmpl',
-        filename: filename,
-      }).toString();
+      const agent = new https.Agent({ rejectUnauthorized: false });
 
       const req = https.request(
         {
@@ -551,33 +540,31 @@ export async function downloadTemplate(
         },
         (res) => {
           let body = '';
-
           res.on('data', (chunk) => {
             body += chunk;
           });
-
           res.on('end', () => {
             const statusCode = res.statusCode || 0;
 
             if (statusCode < 200 || statusCode >= 300) {
-              if (process.env.DEBUG || statusCode === 400) {
-                console.error(`[Proxmox] Download failed: ${body}`);
+              if (process.env.DEBUG || statusCode >= 400) {
+                console.error(`[Proxmox] POST ${path} failed (${statusCode}): ${body}`);
               }
               resolve({
                 success: false,
-                message: `Download request failed with status ${statusCode}: ${body}`,
+                message: `Request failed with status ${statusCode}: ${body}`,
                 details: { status: statusCode, response: body },
               });
               return;
             }
 
             try {
-              const data = JSON.parse(body) as ProxmoxApiResponse<string>;
+              const data = JSON.parse(body) as ProxmoxApiResponse<T>;
               resolve({ success: true, data: data.data });
             } catch (error) {
               resolve({
                 success: false,
-                message: 'Failed to parse download response',
+                message: 'Failed to parse response',
                 details: { error: String(error), body },
               });
             }
@@ -588,7 +575,7 @@ export async function downloadTemplate(
       req.on('error', (error) => {
         resolve({
           success: false,
-          message: `Download request failed: ${error.message}`,
+          message: `Request failed: ${error.message}`,
           details: { error: String(error) },
         });
       });
@@ -598,13 +585,67 @@ export async function downloadTemplate(
     } catch (error) {
       resolve({
         success: false,
-        message: `Download failed: ${error instanceof Error ? error.message : String(error)}`,
+        message: `Request failed: ${error instanceof Error ? error.message : String(error)}`,
         details: { error: String(error) },
       });
     }
   });
 }
 
+/**
+ * Entry from Proxmox's appliance catalog (`pveam available`). The `template`
+ * field is the canonical filename (revision included) that should be passed to
+ * downloadAppliance; constructing it ourselves is a known foot-gun because
+ * Proxmox refreshes revisions over time.
+ */
+export interface ProxmoxAppliance {
+  /** Full canonical filename, e.g. "ubuntu-24.04-standard_24.04-2_amd64.tar.zst" */
+  template: string;
+  /** Package family, e.g. "ubuntu-24.04-standard" */
+  package: string;
+  /** Version including revision, e.g. "24.04-2" */
+  version: string;
+  /** Template type, typically "lxc" */
+  type?: string;
+  /** Operating system, e.g. "ubuntu" */
+  os?: string;
+  /** Section, e.g. "system" — what `pveam available --section system` filters on */
+  section?: string;
+  /** Display headline */
+  headline?: string;
+}
+
+/**
+ * List the LXC templates Proxmox knows are downloadable from its mirror.
+ * Wraps `GET /nodes/{node}/aplinfo` — the same data source `pveam available`
+ * uses. Use this rather than building URLs against download.proxmox.com so
+ * that revision bumps (e.g. ubuntu-24.04 -1 → -2) are picked up automatically.
+ */
+export async function listAvailableAppliances(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+): Promise<ProxmoxResult<ProxmoxAppliance[]>> {
+  return makeProxmoxRequest(credentials, `/nodes/${nodeName}/aplinfo`);
+}
+
+/**
+ * Start a download of an appliance template from Proxmox's mirror.
+ * `templateName` must be the exact `template` field from listAvailableAppliances
+ * (the same string `pveam download <storage> <template>` accepts).
+ * Returns a UPID for status polling via checkTaskStatus.
+ */
+export async function downloadAppliance(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+  storageName: string,
+  templateName: string,
+): Promise<ProxmoxResult<string>> {
+  return makeProxmoxPost<string>(credentials, `/nodes/${nodeName}/aplinfo`, {
+    storage: storageName,
+    template: templateName,
+  });
+}
+
 /**
  * Check status of a running task (UPID)
  * Returns task status and completion percentage
@@ -619,15 +660,6 @@ export async function checkTaskStatus(
   return makeProxmoxRequest(credentials, `/nodes/${nodeName}/tasks/${encodedUpid}/status`);
 }
 
-/**
- * Build template URL for downloading from Proxmox repository
- */
-export function buildTemplateUrl(ubuntuVersion: string): string {
-  // Proxmox mirrors Ubuntu cloud images
-  // Format: http://download.proxmox.com/images/system/ubuntu-{version}-standard_{version}-1_amd64.tar.zst
-  return `http://download.proxmox.com/images/system/ubuntu-${ubuntuVersion}-standard_${ubuntuVersion}-1_amd64.tar.zst`;
-}
-
 /**
  * Extract template filename from full template path
  * Format: "local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst" -> "ubuntu-22.04-standard_22.04-1_amd64.tar.zst"
@@ -639,11 +671,11 @@ export function extractTemplateFilename(templatePath: string): string {
 }
 
 /**
- * Build full template path from components
+ * Build full template path (volid) from a storage name and the canonical
+ * template filename returned by listAvailableAppliances.
  */
-export function buildTemplatePath(storageName: string, ubuntuVersion: string): string {
-  const filename = `ubuntu-${ubuntuVersion}-standard_${ubuntuVersion}-1_amd64.tar.zst`;
-  return `${storageName}:vztmpl/${filename}`;
+export function buildTemplatePath(storageName: string, templateFilename: string): string {
+  return `${storageName}:vztmpl/${templateFilename}`;
 }
 
 /**

package/src/cli/command-registry.ts

@@ -66,18 +66,6 @@ export const COMMANDS: CommandDef[] = [
     name: 'status',
     description: 'Show system and module status',
   },
-  {
-    name: 'doctor',
-    description: 'Diagnose @celilo/* version drift between the running CLI and the workspace',
-    flags: [
-      {
-        name: 'fix',
-        description:
-          'Repair drift by `bun link`-ing each drifted @celilo/* package from the workspace',
-        takesValue: false,
-      },
-    ],
-  },
   {
     name: 'audit',
     description: 'Top-level alias for `system audit`',
@@ -815,6 +803,18 @@ export const COMMANDS: CommandDef[] = [
           },
         ],
       },
+      {
+        name: 'doctor',
+        description: 'Diagnose system prerequisites and @celilo/* version drift',
+        flags: [
+          {
+            name: 'fix',
+            description:
+              'Repair drift by `bun link`-ing each drifted @celilo/* package from the workspace',
+            takesValue: false,
+          },
+        ],
+      },
     ],
   },
   {

package/src/cli/commands/completion.ts

@@ -4,7 +4,7 @@
  */
 
 import { COMMANDS } from '../command-registry';
-import { generateBashCompletion } from '../completion';
+import { generateBashCompletion, generateFishCompletion } from '../completion';
 import { generateRichZshCompletion } from '../generate-zsh-completion';
 import { celiloIntro } from '../prompts';
 import type { CommandResult } from '../types';
@@ -32,6 +32,7 @@ export async function handleCompletion(
 Usage:
   celilo completion bash    Generate bash completion script
   celilo completion zsh     Generate zsh completion script
+  celilo completion fish    Generate fish completion script
 
 Install zsh completions:
   celilo completion zsh > ~/.zsh/completions/_celilo
@@ -41,19 +42,15 @@ Install zsh completions:
     }
 
     if (shell === 'bash') {
-      const script = generateBashCompletion();
-      return {
-        success: true,
-        message: script,
-      };
+      return { success: true, message: generateBashCompletion() };
     }
 
     if (shell === 'zsh') {
-      const script = generateRichZshCompletion(COMMANDS);
-      return {
-        success: true,
-        message: script,
-      };
+      return { success: true, message: generateRichZshCompletion(COMMANDS) };
+    }
+
+    if (shell === 'fish') {
+      return { success: true, message: generateFishCompletion() };
     }
 
     celiloIntro('Shell Completion');
@@ -65,6 +62,7 @@ Install zsh completions:
 Supported shells:
   bash  Generate bash completion script
   zsh   Generate zsh completion script
+  fish  Generate fish completion script
 
 Usage:
   # Bash
@@ -76,6 +74,9 @@ Usage:
   celilo completion zsh > ~/.zsh/completions/_celilo
   # OR for user install:
   celilo completion zsh > /usr/local/share/zsh/site-functions/_celilo
+
+  # Fish
+  celilo completion fish > ~/.config/fish/completions/celilo.fish
 `,
     };
   } catch (error) {

package/src/cli/commands/module-check.ts

@@ -0,0 +1,158 @@
+/**
+ * `celilo module check <path>` — drift detection for third-party modules.
+ *
+ * Runs every checker in services/module-validator against the module
+ * at <path> (defaults to ".") and reports a human-friendly summary or
+ * a structured JSON payload.
+ *
+ * Flags:
+ *   --no-build      Skip `bunx tsc --noEmit`. Useful for fast iteration
+ *                   or when the module has no TypeScript surface.
+ *   --json          Emit the structured Check[] payload instead of the
+ *                   formatted text. Good for CI.
+ *   --strict        Treat warnings as failures (any non-OK is non-zero).
+ *
+ * Exit codes:
+ *   - all checks pass (or only warns) → success
+ *   - one or more fails → CommandError (CLI exits 1)
+ *   - --strict turns warns into fails too
+ *
+ * Pure filesystem + manifest + npm. No DB writes.
+ */
+
+import { resolve } from 'node:path';
+import { type Check, runChecks } from '../../services/module-validator';
+import { hasFlag } from '../parser';
+import type { CommandResult } from '../types';
+
+interface CheckOptions {
+  noBuild: boolean;
+  json: boolean;
+  strict: boolean;
+}
+
+function parseOptions(flags: Record<string, string | boolean>): CheckOptions {
+  return {
+    noBuild: hasFlag(flags, 'no-build'),
+    json: hasFlag(flags, 'json'),
+    strict: hasFlag(flags, 'strict'),
+  };
+}
+
+function summarize(checks: Check[]): { ok: number; warn: number; fail: number } {
+  const summary = { ok: 0, warn: 0, fail: 0 };
+  for (const c of checks) summary[c.status]++;
+  return summary;
+}
+
+function statusIcon(status: Check['status']): string {
+  switch (status) {
+    case 'ok':
+      return '✓';
+    case 'warn':
+      return '!';
+    case 'fail':
+      return '✗';
+  }
+}
+
+function formatTextReport(modulePath: string, checks: Check[]): string {
+  const lines: string[] = [`Module check: ${modulePath}`, ''];
+  const byCategory = new Map<string, Check[]>();
+  for (const check of checks) {
+    const list = byCategory.get(check.category) ?? [];
+    list.push(check);
+    byCategory.set(check.category, list);
+  }
+
+  const order: Check['category'][] = [
+    'manifest_schema',
+    'contract_version',
+    'capability',
+    'workspace_dep',
+    'git_hygiene',
+    'typescript_build',
+  ];
+  for (const category of order) {
+    const items = byCategory.get(category);
+    if (!items || items.length === 0) continue;
+    lines.push(formatCategoryHeader(category));
+    for (const c of items) {
+      lines.push(`  ${statusIcon(c.status)} ${c.name}`);
+      lines.push(`      ${c.message}`);
+      if (c.suggestedValue && c.status !== 'ok') {
+        lines.push(`      suggest: ${c.suggestedValue}`);
+      }
+      if (c.migrationUrl) {
+        lines.push(`      migration: ${c.migrationUrl}`);
+      }
+    }
+    lines.push('');
+  }
+
+  const summary = summarize(checks);
+  lines.push(`Summary: ${summary.ok} ok, ${summary.warn} warn, ${summary.fail} fail`);
+  return lines.join('\n');
+}
+
+function formatCategoryHeader(category: Check['category']): string {
+  switch (category) {
+    case 'manifest_schema':
+      return 'Manifest schema:';
+    case 'contract_version':
+      return 'Contract version:';
+    case 'capability':
+      return 'Capability versions:';
+    case 'workspace_dep':
+      return 'Workspace deps (@celilo/*):';
+    case 'git_hygiene':
+      return 'Publish readiness (git):';
+    case 'typescript_build':
+      return 'TypeScript build:';
+  }
+}
+
+function formatJsonReport(modulePath: string, checks: Check[]): string {
+  return JSON.stringify(
+    {
+      module: { path: modulePath },
+      checks,
+      summary: summarize(checks),
+    },
+    null,
+    2,
+  );
+}
+
+export async function handleModuleCheck(
+  args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const options = parseOptions(flags);
+  const modulePath = resolve(args[0] ?? '.');
+
+  const checks = await runChecks(modulePath, { noBuild: options.noBuild });
+  const summary = summarize(checks);
+
+  const message = options.json
+    ? formatJsonReport(modulePath, checks)
+    : formatTextReport(modulePath, checks);
+
+  const hasFails = summary.fail > 0;
+  const hasWarns = summary.warn > 0;
+  const failed = hasFails || (options.strict && hasWarns);
+
+  if (failed) {
+    return {
+      success: false,
+      error: message,
+    };
+  }
+
+  return {
+    success: true,
+    message,
+    rawOutput: options.json,
+    data: { checks, summary },
+  };
+}

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

@@ -141,17 +141,17 @@ async function handlePublicRegistryImport(
       return { success: false, error: result.error, details: result.details };
     }
 
-    const typesPath = await generateTypesForImportedModule(result.targetPath);
-    const typesMessage = typesPath ? `\nGenerated types: ${shortenPath(typesPath)}` : '';
-
+    // Type-generation is a developer-mode aid for module AUTHORS editing
+    // hook scripts in the source tree. Registry installs are black-box
+    // dependencies — the operator isn't editing them — so skipping the
+    // type-gen pass saves the work and keeps the install output clean.
     return {
       success: true,
-      message: `Imported ${result.moduleId}@${latest.vers}\nFiles: ${shortenPath(result.targetPath)}${typesMessage}`,
+      message: `Imported ${result.moduleId}@${latest.vers}\nFiles: ${shortenPath(result.targetPath)}`,
       data: {
         moduleId: result.moduleId,
         version: latest.vers,
         targetPath: result.targetPath,
-        typesPath: typesPath ?? undefined,
       },
     };
   } finally {

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

@@ -15,7 +15,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import type { IndexEntry } from '../../registry/client';
-import { handleModulePublish, resolveToken, validateCapabilityVersions } from './module-publish';
+import { handleModulePublish, resolveToken } from './module-publish';
 
 const TEST_DIR = `/tmp/test-module-publish-${Date.now()}`;
 
@@ -155,95 +155,8 @@ describe('revision auto-detection algorithm', () => {
   });
 });
 
-// ── Strict-publish: capability version validation (CELILO_UPDATE D4) ──────────
-//
-// Manifest-claimed versions for known capabilities must match the framework's
-// runtime registry; mismatches refuse the publish.
-
-describe('validateCapabilityVersions', () => {
-  test('no errors when no capabilities are declared', () => {
-    expect(validateCapabilityVersions({ id: 'x', version: '1.0.0' })).toEqual([]);
-  });
-
-  test('no errors when provides matches the runtime registry exactly', () => {
-    expect(
-      validateCapabilityVersions({
-        id: 'caddy',
-        version: '3.0.0',
-        provides: { capabilities: [{ name: 'public_web', version: '3.0.0' }] },
-      }),
-    ).toEqual([]);
-  });
-
-  test('error when provides[X].version differs from runtime', () => {
-    // The runtime is set to 3.0.0 for public_web; claiming 1.0.0 is a bug.
-    const errors = validateCapabilityVersions({
-      id: 'caddy',
-      version: '1.0.0',
-      provides: { capabilities: [{ name: 'public_web', version: '1.0.0' }] },
-    });
-    expect(errors).toHaveLength(1);
-    expect(errors[0]).toContain('provides[public_web]');
-    expect(errors[0]).toContain('1.0.0');
-    expect(errors[0]).toContain('3.0.0');
-  });
-
-  test('error when provides[X].version is newer than runtime', () => {
-    const errors = validateCapabilityVersions({
-      id: 'caddy',
-      version: '4.0.0',
-      provides: { capabilities: [{ name: 'public_web', version: '4.0.0' }] },
-    });
-    expect(errors).toHaveLength(1);
-    expect(errors[0]).toContain('provides[public_web]');
-  });
-
-  test('skips capabilities not in the framework registry (third-party)', () => {
-    expect(
-      validateCapabilityVersions({
-        id: 'odd',
-        version: '1.0.0',
-        provides: { capabilities: [{ name: 'custom_metric', version: '99.0.0' }] },
-      }),
-    ).toEqual([]);
-  });
-
-  test('error when requires[X].version is a higher major than runtime', () => {
-    // Framework can't satisfy a requirement it doesn't know about.
-    const errors = validateCapabilityVersions({
-      id: 'lunacycle',
-      version: '1.0.0',
-      requires: { capabilities: [{ name: 'idp', version: '2.0.0' }] },
-    });
-    expect(errors).toHaveLength(1);
-    expect(errors[0]).toContain('requires[idp]');
-  });
-
-  test('no error when requires[X].version is at most the runtime version', () => {
-    // dns_registrar runtime is 4.0.0; consumer requiring 4.0.0 is fine.
-    expect(
-      validateCapabilityVersions({
-        id: 'caddy',
-        version: '1.0.0',
-        requires: { capabilities: [{ name: 'dns_registrar', version: '4.0.0' }] },
-      }),
-    ).toEqual([]);
-  });
-
-  test('reports multiple errors at once', () => {
-    const errors = validateCapabilityVersions({
-      id: 'broken',
-      version: '1.0.0',
-      provides: {
-        capabilities: [
-          { name: 'public_web', version: '99.0.0' },
-          { name: 'idp', version: '99.0.0' },
-        ],
-      },
-    });
-    expect(errors).toHaveLength(2);
-  });
-});
+// validateCapabilityVersions tests live with the function in
+// services/module-validator/capability-versions.test.ts.
 
 // ── Token resolution: --token → env → secret store ────────────────────────────