@celilo/cli 0.3.16 → 0.3.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "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`',
@@ -267,27 +255,21 @@ export const COMMANDS: CommandDef[] = [
     subcommands: [
       {
         name: 'import',
-        description: 'Import a module (file <path> | public-registry <name>)',
-        subcommands: [
-          {
-            name: 'file',
-            description: 'Import from local filesystem',
-            args: [{ name: 'path', description: 'Module path', completion: 'directories' }],
-          },
+        description:
+          'Import a module from the registry (bare name) or from a local path (./, /, ~, or *.netapp)',
+        args: [
           {
-            name: 'public-registry',
-            description: 'Import from celilo.computer registry',
-            args: [{ name: 'name', description: 'Module name' }],
-            flags: [
-              {
-                name: 'registry',
-                description: 'Registry URL (overrides default celilo.computer)',
-                takesValue: true,
-              },
-            ],
+            name: 'name-or-path',
+            description: 'Module name (registry) or filesystem path',
+            completion: 'directories',
           },
         ],
         flags: [
+          {
+            name: 'registry',
+            description: 'Registry URL (overrides default celilo.computer)',
+            takesValue: true,
+          },
           {
             name: 'target',
             description: 'Target directory',
@@ -489,12 +471,6 @@ export const COMMANDS: CommandDef[] = [
           },
         ],
       },
-      {
-        name: 'install',
-        description: 'Download and import a module from the registry',
-        args: [{ name: 'name', description: 'Module name' }],
-        flags: [{ name: 'registry', description: 'Registry URL', takesValue: true }],
-      },
       {
         name: 'search',
         description: 'Search the module registry',
@@ -815,6 +791,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-routing.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Tests for the import-routing rule that disambiguates between
+ *   `celilo module import caddy`             → registry
+ *   `celilo module import ./modules/caddy`   → local path
+ *
+ * Pure function over the argument string; no network, no filesystem.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { classifyImportArg } from './module-import';
+
+describe('classifyImportArg', () => {
+  test('routes bare kebab names to the registry', () => {
+    expect(classifyImportArg('caddy')).toBe('name');
+    expect(classifyImportArg('homebridge')).toBe('name');
+    expect(classifyImportArg('dns-external')).toBe('name');
+    expect(classifyImportArg('a')).toBe('name');
+  });
+
+  test('routes leading-dot relative paths to the filesystem', () => {
+    expect(classifyImportArg('./modules/caddy')).toBe('path');
+    expect(classifyImportArg('../caddy')).toBe('path');
+    expect(classifyImportArg('./caddy')).toBe('path');
+  });
+
+  test('routes leading-slash absolute paths to the filesystem', () => {
+    expect(classifyImportArg('/tmp/caddy')).toBe('path');
+    expect(classifyImportArg('/abs/path/to/module')).toBe('path');
+  });
+
+  test('routes tilde-expanded paths to the filesystem', () => {
+    expect(classifyImportArg('~')).toBe('path');
+    expect(classifyImportArg('~/dev/caddy')).toBe('path');
+  });
+
+  test('routes any path containing / to the filesystem', () => {
+    expect(classifyImportArg('modules/caddy')).toBe('path');
+    expect(classifyImportArg('a/b/c')).toBe('path');
+  });
+
+  test('routes .netapp filenames to the filesystem (registry never serves them by name)', () => {
+    expect(classifyImportArg('caddy.netapp')).toBe('path');
+    expect(classifyImportArg('homebridge-1.0.0.netapp')).toBe('path');
+  });
+
+  test('does not confuse versioned names with paths (no slash, no .netapp)', () => {
+    // Future: registry may accept `name@version` syntax. Today this routes
+    // to "name" — KEBAB_NAME validation in handleModuleImport will reject
+    // until the syntax is implemented.
+    expect(classifyImportArg('caddy@1.0.0')).toBe('name');
+  });
+});