@celilo/cli 0.3.16 → 0.3.17

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

@@ -35,16 +35,10 @@
  * timestamp / CLI version / optional --message.
  */
 
-import { spawnSync } from 'node:child_process';
 import { rm } from 'node:fs/promises';
 import { readFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
-import {
-  CAPABILITY_CONTRACT_VERSIONS,
-  type KnownCapabilityName,
-  compareProviderToRuntime,
-} from '@celilo/capabilities';
 import { parse as parseYaml } from 'yaml';
 import { buildModule } from '../../module/packaging/build';
 import {
@@ -55,122 +49,18 @@ import {
 } from '../../module/packaging/release-metadata';
 import { RegistryClient } from '../../registry/client';
 import { CrossModuleDataManager } from '../../services/cross-module-data-manager';
+import {
+  type ManifestForCapabilityCheck,
+  validateCapabilityVersions,
+} from '../../services/module-validator/capability-versions';
+import { checkModuleStale } from '../../services/module-validator/git-hygiene';
 import { getFlag, hasFlag } from '../parser';
 import type { CommandResult } from '../types';
 
-interface ManifestCapabilityClaim {
-  name: string;
-  version: string;
-}
-
-interface ManifestForPublish {
+interface ManifestForPublish extends ManifestForCapabilityCheck {
   id: string;
   version: string;
-  provides?: { capabilities?: ManifestCapabilityClaim[] };
-  requires?: { capabilities?: ManifestCapabilityClaim[] };
-}
-
-function isKnownCapability(name: string): name is KnownCapabilityName {
-  return name in CAPABILITY_CONTRACT_VERSIONS;
-}
-
-/**
- * Strict-publish: every `provides[X].version` must match the framework's
- * runtime registry; every `requires[X].version` must be at most the
- * framework's runtime version (consumers can require older minors of
- * still-supported majors).
- *
- * Exported for testing.
- */
-export function validateCapabilityVersions(manifest: ManifestForPublish): string[] {
-  const errors: string[] = [];
-
-  for (const p of manifest.provides?.capabilities ?? []) {
-    if (!isKnownCapability(p.name)) continue;
-    const runtime = CAPABILITY_CONTRACT_VERSIONS[p.name];
-    const r = compareProviderToRuntime(p.version, runtime);
-    if (!r.compatible) {
-      errors.push(
-        `provides[${p.name}].version is ${p.version} but framework registry is ${runtime} ` +
-          `(${r.reason}). Update the manifest, then retry.`,
-      );
-    }
-  }
-
-  for (const need of manifest.requires?.capabilities ?? []) {
-    if (!isKnownCapability(need.name)) continue;
-    const runtime = CAPABILITY_CONTRACT_VERSIONS[need.name];
-    // Treat the runtime as the de-facto provider for publish-time validation:
-    // if a consumer's manifest claims it requires a contract newer than the
-    // framework even has registered, no in-tree provider can satisfy it.
-    const r = compareProviderToRuntime(need.version, runtime);
-    if (!r.compatible && r.reason === 'major_mismatch_higher') {
-      errors.push(
-        `requires[${need.name}].version is ${need.version} but framework registry is ${runtime}. Bump the framework before publishing, or lower the manifest version.`,
-      );
-    }
-  }
-
-  return errors;
-}
-
-/**
- * Look up the SHA of the last commit touching the given pathspecs. Returns
- * null on any git failure (no repo, never-committed file, etc.) — callers
- * treat that as "can't determine, skip the check."
- */
-function lastCommitTouching(pathspec: string[]): string | null {
-  const r = spawnSync('git', ['log', '-1', '--format=%H', '--', ...pathspec], {
-    stdio: ['ignore', 'pipe', 'ignore'],
-    encoding: 'utf-8',
-  });
-  if (r.status !== 0) return null;
-  const sha = r.stdout.trim();
-  return sha || null;
-}
-
-function isAncestor(maybeAncestor: string, descendant: string): boolean {
-  const r = spawnSync('git', ['merge-base', '--is-ancestor', maybeAncestor, descendant], {
-    stdio: 'ignore',
-  });
-  return r.status === 0;
-}
-
-export interface StalenessIssue {
-  moduleDir: string;
-  lastSrcCommit: string;
-  lastManifestCommit: string;
-}
-
-/**
- * Detect "I edited module src but forgot to bump (or touch) manifest.yml."
- *
- * Returns null when the manifest is the most recently-touched file in the
- * dir (or when neither side has any commit history — e.g. brand-new module
- * not yet committed). Returns a StalenessIssue when src has commits AFTER
- * the last manifest.yml change — the operator must bump the manifest
- * (semver change → reset +N to 1) or just touch it (release-only change →
- * auto-bump +N), then re-publish.
- *
- * Exported for testing.
- */
-export function checkModuleStale(moduleDir: string): StalenessIssue | null {
-  const manifestPath = join(moduleDir, 'manifest.yml');
-  const lastManifest = lastCommitTouching([manifestPath]);
-  // Excluding manifest.yml from the "src" pathspec is the whole point — we
-  // want to know if anything ELSE in the dir moved past it. node_modules and
-  // common build outputs are gitignored already, but be explicit defensively.
-  const lastSrc = lastCommitTouching([
-    moduleDir,
-    `:(exclude)${manifestPath}`,
-    `:(exclude)${moduleDir}/node_modules`,
-    `:(exclude)${moduleDir}/dist`,
-  ]);
-  if (!lastManifest || !lastSrc) return null;
-  if (lastSrc === lastManifest) return null; // same commit changed both
-  if (!isAncestor(lastManifest, lastSrc)) return null; // manifest moved last
-
-  return { moduleDir, lastSrcCommit: lastSrc, lastManifestCommit: lastManifest };
+  description?: string;
 }
 
 /**
@@ -378,7 +268,13 @@ export async function publishOneModule(
   const client = new RegistryClient(opts.registryUrl || undefined);
   try {
     console.log(`Publishing ${name}@${version} to ${client.baseUrl}...`);
-    await client.publish({ name, version, netappPath: buildResult.packagePath, token: opts.token });
+    await client.publish({
+      name,
+      version,
+      netappPath: buildResult.packagePath,
+      token: opts.token,
+      description: manifest.description?.trim() || undefined,
+    });
   } catch (err) {
     return {
       moduleDir,

package/src/cli/commands/proxmox-template-selection.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, test } from 'bun:test';
+import type { ProxmoxAppliance } from '../../api-clients/proxmox';
+import { buildUbuntuOptions, pickInitialTemplate } from './proxmox-template-selection';
+
+// Snapshot of `pveam available --section system` filtered to Ubuntu, taken
+// 2026-05-08. The point of these tests is to lock in the catalog-driven
+// behavior that replaced the hardcoded `-1` revision URL.
+const catalog: ProxmoxAppliance[] = [
+  {
+    template: 'ubuntu-22.04-standard_22.04-1_amd64.tar.zst',
+    package: 'ubuntu-22.04-standard',
+    version: '22.04-1',
+    section: 'system',
+    os: 'ubuntu',
+    type: 'lxc',
+  },
+  {
+    template: 'ubuntu-24.04-standard_24.04-2_amd64.tar.zst',
+    package: 'ubuntu-24.04-standard',
+    version: '24.04-2',
+    section: 'system',
+    os: 'ubuntu',
+    type: 'lxc',
+  },
+  {
+    template: 'ubuntu-24.10-standard_24.10-1_amd64.tar.zst',
+    package: 'ubuntu-24.10-standard',
+    version: '24.10-1',
+    section: 'system',
+    os: 'ubuntu',
+    type: 'lxc',
+  },
+  {
+    template: 'ubuntu-25.04-standard_25.04-1.1_amd64.tar.zst',
+    package: 'ubuntu-25.04-standard',
+    version: '25.04-1.1',
+    section: 'system',
+    os: 'ubuntu',
+    type: 'lxc',
+  },
+  {
+    template: 'ubuntu-26.04-standard_26.04-1_amd64.tar.zst',
+    package: 'ubuntu-26.04-standard',
+    version: '26.04-1',
+    section: 'system',
+    os: 'ubuntu',
+    type: 'lxc',
+  },
+];
+
+describe('buildUbuntuOptions', () => {
+  test('returns Ubuntu options sorted newest-first', () => {
+    const options = buildUbuntuOptions(catalog);
+    expect(options.map((o) => o.appliance.package)).toEqual([
+      'ubuntu-26.04-standard',
+      'ubuntu-25.04-standard',
+      'ubuntu-24.10-standard',
+      'ubuntu-24.04-standard',
+      'ubuntu-22.04-standard',
+    ]);
+  });
+
+  test('flags LTS releases correctly', () => {
+    const options = buildUbuntuOptions(catalog);
+    const ltsByPackage = Object.fromEntries(options.map((o) => [o.appliance.package, o.isLts]));
+    expect(ltsByPackage).toEqual({
+      'ubuntu-22.04-standard': true,
+      'ubuntu-24.04-standard': true,
+      'ubuntu-24.10-standard': false,
+      'ubuntu-25.04-standard': false,
+      'ubuntu-26.04-standard': true,
+    });
+  });
+
+  test('drops non-Ubuntu and non-system entries', () => {
+    const mixed: ProxmoxAppliance[] = [
+      ...catalog,
+      {
+        template: 'debian-12-standard_12.7-1_amd64.tar.zst',
+        package: 'debian-12-standard',
+        version: '12.7-1',
+        section: 'system',
+        os: 'debian',
+      },
+      {
+        template: 'ubuntu-24.04-special_24.04-1_amd64.tar.zst',
+        package: 'ubuntu-24.04-standard',
+        version: '24.04-1',
+        section: 'turnkeylinux',
+        os: 'ubuntu',
+      },
+    ];
+    const options = buildUbuntuOptions(mixed);
+    expect(options).toHaveLength(catalog.length);
+    expect(options.every((o) => (o.appliance.section ?? 'system') === 'system')).toBe(true);
+  });
+
+  test('returns empty array when nothing matches', () => {
+    expect(buildUbuntuOptions([])).toEqual([]);
+  });
+});
+
+describe('pickInitialTemplate', () => {
+  const options = buildUbuntuOptions(catalog);
+
+  test('defaults to newest LTS when no current template given', () => {
+    expect(pickInitialTemplate(options)).toBe('ubuntu-26.04-standard_26.04-1_amd64.tar.zst');
+  });
+
+  test('exact match wins when revision still on mirror', () => {
+    expect(pickInitialTemplate(options, 'ubuntu-22.04-standard_22.04-1_amd64.tar.zst')).toBe(
+      'ubuntu-22.04-standard_22.04-1_amd64.tar.zst',
+    );
+  });
+
+  test('falls back to family match when revision has been refreshed', () => {
+    // The case that motivated the refactor: user has stale -1 cached, mirror has -2.
+    expect(pickInitialTemplate(options, 'ubuntu-24.04-standard_24.04-1_amd64.tar.zst')).toBe(
+      'ubuntu-24.04-standard_24.04-2_amd64.tar.zst',
+    );
+  });
+
+  test('falls through to newest LTS when current does not match any family', () => {
+    expect(pickInitialTemplate(options, 'ubuntu-18.04-standard_18.04-1_amd64.tar.zst')).toBe(
+      'ubuntu-26.04-standard_26.04-1_amd64.tar.zst',
+    );
+  });
+
+  test('returns undefined for empty options', () => {
+    expect(pickInitialTemplate([])).toBeUndefined();
+  });
+
+  test('falls back to newest entry when no LTS in catalog', () => {
+    const noLts = buildUbuntuOptions([
+      {
+        template: 'ubuntu-25.04-standard_25.04-1.1_amd64.tar.zst',
+        package: 'ubuntu-25.04-standard',
+        version: '25.04-1.1',
+        section: 'system',
+      },
+      {
+        template: 'ubuntu-24.10-standard_24.10-1_amd64.tar.zst',
+        package: 'ubuntu-24.10-standard',
+        version: '24.10-1',
+        section: 'system',
+      },
+    ]);
+    expect(pickInitialTemplate(noLts)).toBe('ubuntu-25.04-standard_25.04-1.1_amd64.tar.zst');
+  });
+});

package/src/cli/commands/proxmox-template-selection.ts

@@ -0,0 +1,258 @@
+/**
+ * Proxmox template selection — shared between `service add proxmox` and
+ * `service reconfigure`. Queries Proxmox's live appliance catalog
+ * (`pveam available`) and prompts the user to pick an Ubuntu LXC template by
+ * canonical name.
+ *
+ * Why this exists: Proxmox bumps template revisions over time
+ * (ubuntu-24.04 went from -1 to -2, 25.04 ships as -1.1) and an older home-lab
+ * deployment guide naming `-1` produces 404s on the mirror. Using the catalog
+ * means the canonical filename always matches what `pveam download` accepts.
+ */
+
+import * as p from '@clack/prompts';
+import {
+  type ProxmoxAppliance,
+  type ProxmoxCredentials,
+  checkTaskStatus,
+  downloadAppliance,
+  listAvailableAppliances,
+} from '../../api-clients/proxmox';
+import { FuelGauge } from '../fuel-gauge';
+import { promptText } from '../prompts';
+import { validateRequired } from '../validators';
+
+export interface UbuntuTemplateChoice {
+  /** Canonical filename, e.g. "ubuntu-24.04-standard_24.04-2_amd64.tar.zst" */
+  template: string;
+  /**
+   * 'catalog' = filename came from Proxmox's aplinfo, so it's known good for
+   * downloadAppliance. 'manual' = user typed it because aplinfo was unavailable;
+   * caller should expect they'll need to `pveam download` themselves.
+   */
+  source: 'catalog' | 'manual';
+}
+
+export type TemplateSelectionResult =
+  | { kind: 'selected'; choice: UbuntuTemplateChoice }
+  | { kind: 'cancelled' }
+  | { kind: 'error'; message: string };
+
+interface ParsedUbuntu {
+  appliance: ProxmoxAppliance;
+  major: number;
+  minor: number;
+  isLts: boolean;
+}
+
+function parseUbuntuPackage(appliance: ProxmoxAppliance): ParsedUbuntu | null {
+  const match = appliance.package.match(/^ubuntu-(\d+)\.(\d+)-standard$/);
+  if (!match) return null;
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  // Ubuntu LTS = even major, .04 minor (20.04, 22.04, 24.04, 26.04, ...).
+  const isLts = minor === 4 && major % 2 === 0;
+  return { appliance, major, minor, isLts };
+}
+
+function compareDescending(a: ParsedUbuntu, b: ParsedUbuntu): number {
+  if (a.major !== b.major) return b.major - a.major;
+  return b.minor - a.minor;
+}
+
+/**
+ * Build the option list used by the select prompt and tests.
+ * Exported so tests can assert on filtering/sorting without mocking @clack.
+ */
+export function buildUbuntuOptions(appliances: ProxmoxAppliance[]): ParsedUbuntu[] {
+  return appliances
+    .map(parseUbuntuPackage)
+    .filter((entry): entry is ParsedUbuntu => entry !== null)
+    .filter((entry) => (entry.appliance.section ?? 'system') === 'system')
+    .sort(compareDescending);
+}
+
+/**
+ * Pre-select rule:
+ *   1. Exact match on currentTemplate (reconfigure with current revision still on mirror).
+ *   2. Family match on currentTemplate package (e.g. user has 24.04 -1 cached, mirror has -2).
+ *   3. Newest LTS in the catalog.
+ *   4. Newest entry overall.
+ */
+export function pickInitialTemplate(
+  options: ParsedUbuntu[],
+  currentTemplate?: string,
+): string | undefined {
+  if (options.length === 0) return undefined;
+
+  if (currentTemplate) {
+    const exact = options.find((e) => e.appliance.template === currentTemplate);
+    if (exact) return exact.appliance.template;
+
+    const familyName = currentTemplate.match(/^(ubuntu-\d+\.\d+-standard)/)?.[1];
+    if (familyName) {
+      const family = options.find((e) => e.appliance.package === familyName);
+      if (family) return family.appliance.template;
+    }
+  }
+
+  const newestLts = options.find((e) => e.isLts);
+  return (newestLts ?? options[0]).appliance.template;
+}
+
+export async function selectUbuntuApplianceFromCatalog(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+  opts: { currentTemplate?: string } = {},
+): Promise<TemplateSelectionResult> {
+  console.log('\nFetching Proxmox template catalog...');
+  const result = await listAvailableAppliances(credentials, nodeName);
+
+  if (!result.success) {
+    console.log(`⚠ Could not fetch template catalog from Proxmox: ${result.message}`);
+    console.log('  You can still configure the service by entering a template filename manually.');
+    console.log(
+      '  After saving, run `pveam download <storage> <template>` on the Proxmox host before deploying.',
+    );
+
+    const manual = await promptText({
+      message: 'Template filename:',
+      placeholder: 'ubuntu-24.04-standard_24.04-2_amd64.tar.zst',
+      validate: validateRequired('Template filename'),
+    });
+
+    if (typeof manual !== 'string' || manual.trim() === '') {
+      return { kind: 'cancelled' };
+    }
+
+    return { kind: 'selected', choice: { template: manual.trim(), source: 'manual' } };
+  }
+
+  const options = buildUbuntuOptions(result.data);
+
+  if (options.length === 0) {
+    return {
+      kind: 'error',
+      message:
+        'Proxmox aplinfo returned no Ubuntu standard templates. Run `pveam update` on the Proxmox host and re-try.',
+    };
+  }
+
+  const initialValue = pickInitialTemplate(options, opts.currentTemplate);
+
+  const selection = await p.select<string>({
+    message: 'Default Ubuntu template:',
+    options: options.map((e) => ({
+      value: e.appliance.template,
+      label: `Ubuntu ${e.major}.${String(e.minor).padStart(2, '0')}${e.isLts ? ' LTS' : ''}`,
+      hint: e.isLts
+        ? `revision ${e.appliance.version}`
+        : `revision ${e.appliance.version} · non-LTS`,
+    })),
+    initialValue,
+  });
+
+  if (p.isCancel(selection)) {
+    return { kind: 'cancelled' };
+  }
+
+  return { kind: 'selected', choice: { template: selection, source: 'catalog' } };
+}
+
+export interface ApplianceDownloadOutcome {
+  /** True iff the template ended up available in the chosen storage. */
+  ready: boolean;
+  /**
+   * One of:
+   *   'started-failed' — POST to aplinfo failed (Proxmox rejected the request).
+   *   'task-failed'    — Download started but pveam exited non-OK (typically exit 8 = HTTP error).
+   *   'timeout'        — Polling exhausted the budget without seeing 'stopped'.
+   *   'ok'             — pveam exited 0 and template should now exist in storage.
+   */
+  reason: 'started-failed' | 'task-failed' | 'timeout' | 'ok';
+  /** The pveam exit status when reason='task-failed', or null otherwise. */
+  exitStatus?: string;
+  /** The error message from Proxmox when reason='started-failed'. */
+  startError?: string;
+}
+
+export interface RunApplianceDownloadInput {
+  credentials: ProxmoxCredentials;
+  targetNode: string;
+  templateStorage: string;
+  templateFilename: string;
+  /** Polling budget in 5s ticks; defaults to 60 (= 5 minutes). */
+  maxAttempts?: number;
+  /** Override the default 5000ms tick — primarily to keep tests fast. */
+  pollIntervalMs?: number;
+}
+
+/**
+ * Trigger a `pveam download` on the Proxmox host and poll until it finishes.
+ * Drives a FuelGauge for user-visible progress. Distinguishes real failures
+ * (Proxmox rejected the start, or pveam exited non-OK) from timeout, so the
+ * caller can render an accurate next-steps message instead of always blaming
+ * "5-minute timeout" for any non-success path (the bug that motivated this
+ * refactor).
+ */
+export async function runApplianceDownload(
+  input: RunApplianceDownloadInput,
+): Promise<ApplianceDownloadOutcome> {
+  const {
+    credentials,
+    targetNode,
+    templateStorage,
+    templateFilename,
+    maxAttempts = 60,
+    pollIntervalMs = 5000,
+  } = input;
+
+  const startResult = await downloadAppliance(
+    credentials,
+    targetNode,
+    templateStorage,
+    templateFilename,
+  );
+
+  if (!startResult.success) {
+    console.log(`\n✗ Failed to start download: ${startResult.message}`);
+    return { ready: false, reason: 'started-failed', startError: startResult.message };
+  }
+
+  const upid = startResult.data;
+  const gauge = new FuelGauge(`Downloading ${templateFilename}`);
+  gauge.start();
+
+  let attempts = 0;
+  while (attempts < maxAttempts) {
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    attempts++;
+
+    const statusResult = await checkTaskStatus(credentials, targetNode, upid);
+    if (!statusResult.success) {
+      gauge.addOutput(`Waiting for status... (${attempts * 5}s elapsed)`);
+      continue;
+    }
+
+    if (statusResult.data.status !== 'stopped') {
+      gauge.addOutput(`Status: ${statusResult.data.status} (${attempts * 5}s elapsed)`);
+      continue;
+    }
+
+    const exit = statusResult.data.exitstatus;
+    if (exit === 'OK') {
+      gauge.stop(true);
+      return { ready: true, reason: 'ok' };
+    }
+
+    gauge.stop(false);
+    console.log(`\n✗ pveam download failed: ${exit ?? 'unknown exit status'}`);
+    return { ready: false, reason: 'task-failed', exitStatus: exit ?? undefined };
+  }
+
+  gauge.stop(false);
+  console.log(
+    `\n✗ Template download did not complete within ${(maxAttempts * pollIntervalMs) / 1000}s`,
+  );
+  return { ready: false, reason: 'timeout' };
+}