@celilo/cli 0.3.16 → 0.3.18

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

@@ -1,7 +1,23 @@
 /**
  * Module import command
+ *
+ * Single entry point for both registry and local-source imports. Routing
+ * is determined by the shape of the argument:
+ *
+ *   celilo module import caddy                 → registry  (kebab name)
+ *   celilo module import ./modules/caddy       → local dir  (relative path)
+ *   celilo module import /tmp/caddy.netapp     → local file (absolute path)
+ *   celilo module import ~/dev/caddy           → local dir  (tilde-expanded)
+ *   celilo module import caddy.netapp          → local file (.netapp extension)
+ *
+ * The previous CLI surface had three overlapping commands for this:
+ * `module install` (registry-only shorthand), `module import public-registry`
+ * (registry, verbose), and `module import file` (local, verbose). All have
+ * been collapsed into this one command — the routing rule below is the
+ * canonical disambiguator.
  */
 
+import { existsSync } from 'node:fs';
 import { unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
@@ -14,47 +30,74 @@ import type { CommandResult } from '../types';
 import { generateTypesForImportedModule } from './module-types';
 
 const USAGE = `Usage:
-  celilo module import file <path>              Import from local filesystem
-  celilo module import public-registry <name>   Import from celilo.computer registry`;
+  celilo module import <name>      Import from celilo.computer registry
+  celilo module import <path>      Import from a local directory or .netapp file
+
+Examples:
+  celilo module import caddy
+  celilo module import ./modules/caddy
+  celilo module import /tmp/caddy.netapp`;
 
 /**
- * Handle module import command
+ * Decide whether the user's argument should route to local-filesystem
+ * import or registry import. Path-like arguments win — see header comment
+ * for the routing rules. Anything else is treated as a registry name
+ * (validated against the kebab-case rule before the network call).
  *
- * Usage: celilo module import file <path> [--target <path>]
- *        celilo module import public-registry <name>
- *        celilo module import <path>  (alias for "file", kept for compatibility)
+ * Exposed for tests; not exported from the package.
  */
+export function classifyImportArg(arg: string): 'path' | 'name' {
+  if (arg.startsWith('/') || arg.startsWith('./') || arg.startsWith('../')) return 'path';
+  if (arg.startsWith('~/') || arg === '~') return 'path';
+  if (arg.includes('/')) return 'path';
+  if (arg.endsWith('.netapp')) return 'path';
+  return 'name';
+}
+
+const KEBAB_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
 export async function handleModuleImport(
   args: string[],
   flags: Record<string, string | boolean>,
 ): Promise<CommandResult> {
-  const subcommand = getArg(args, 0);
+  const arg = getArg(args, 0);
 
-  if (!subcommand) {
-    return { success: false, error: `Subcommand required.\n\n${USAGE}` };
+  if (!arg) {
+    return { success: false, error: `Module name or path required.\n\n${USAGE}` };
   }
 
-  if (subcommand === 'public-registry') {
-    const moduleName = getArg(args, 1);
-    if (!moduleName) {
-      return { success: false, error: `Module name required.\n\n${USAGE}` };
+  if (classifyImportArg(arg) === 'name') {
+    if (!KEBAB_NAME.test(arg)) {
+      return {
+        success: false,
+        error: `Not a valid module name or path: '${arg}'.\n\n${USAGE}\n\nModule names are kebab-case (lowercase letters, digits, hyphens). For local paths, use ./, /, ~/, or include / in the argument.`,
+      };
     }
-    return handlePublicRegistryImport(moduleName, flags);
+    return handlePublicRegistryImport(arg, flags);
   }
 
-  // Resolve the source path: "file <path>" or bare "<path>" alias
-  const sourcePath = subcommand === 'file' ? getArg(args, 1) : subcommand;
-
-  if (!sourcePath) {
-    return { success: false, error: `Path required.\n\n${USAGE}` };
-  }
+  return handleFileImport(arg, flags);
+}
 
-  // Resolve paths
+async function handleFileImport(
+  sourcePath: string,
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
   const resolvedSourcePath = resolve(sourcePath);
   const targetBasePath = getFlag(flags, 'target', getModuleStoragePath());
   const resolvedTargetBasePath = resolve(targetBasePath);
 
-  // Import module
+  // Surface a more useful error than "module directory does not exist"
+  // when the user typed a registry name with a typo (e.g. `caddy/` or
+  // `./caddy`) but no such directory is present. Helps them realize
+  // they probably wanted the registry form.
+  if (!existsSync(resolvedSourcePath)) {
+    return {
+      success: false,
+      error: `Path does not exist: ${resolvedSourcePath}\n\nIf you meant the registry, use a bare module name (no leading ./ or /):\n  celilo module import <name>`,
+    };
+  }
+
   const db = getDb();
   const result = await importModule({
     sourcePath: resolvedSourcePath,
@@ -141,17 +184,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 ────────────────────────────
 

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');
+  });
+});