@celilo/cli 0.5.0-alpha.9 → 0.6.0

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

@@ -1,571 +1,276 @@
 /**
- * Module update command
+ * `celilo module upgrade [name]` — the build-bus CD verb (ISS-0138) + the
+ * registry-poll it drives (ISS-0139). v2/BUILD_BUS.md.
  *
- * Updates module code (manifest, scripts, templates) while preserving state
- * (configs, secrets, infrastructure, capabilities).
+ *   module upgrade <name>   one module: registry-latest → update → [backup,
+ *                           posture-gated] → deploy → verify.
+ *   module upgrade          NO name = the CD poll: every INSTALLED module that
+ *                           opted into `auto_upgrade` and has a newer registry
+ *                           version, upgraded the same way. This is what the
+ *                           timer-driven CD job runs.
  *
- * Usage: celilo module update <path>
- *
- * The module ID is read from the manifest at the given path.
+ * `module update` refreshes the stored definition; `module deploy` applies it;
+ * `module upgrade` is the safe compound. Fast/safe posture is derived
+ * (deploy-posture.ts): a low-risk revision/patch skips the backup, a minor/major
+ * backs up first.
  */
 
-import { cpSync, existsSync, readFileSync, readdirSync } from 'node:fs';
-import { unlink } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
 import { eq } from 'drizzle-orm';
-import { parse as parseYaml } from 'yaml';
-import { registerModuleCapabilities } from '../../capabilities/registration';
-import { getDb } from '../../db/client';
-import { capabilities, modules } from '../../db/schema';
-import { ModuleManifestSchema } from '../../manifest/schema';
+import { type DbClient, getDb } from '../../db/client';
+import { modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
-import { cleanupTempDir, extractPackage } from '../../module/packaging/extract';
 import { RegistryClient } from '../../registry/client';
-import { askConfirm, withInterviewSession } from '../../services/bus-interview';
-import { getFlag } from '../parser';
+import { createModuleBackup } from '../../services/backup-create';
+import { type UpgradePolicy, resolveDeployPosture } from '../../services/deploy-posture';
+import { runModuleHealthCheck } from '../../services/health-runner';
+import { getModuleConfigValue } from '../../services/module-config';
+import { deployModule } from '../../services/module-deploy';
+import { getArg, getFlag } from '../parser';
 import { log } from '../prompts';
 import type { CommandResult } from '../types';
+import { classifyVersionChange, fetchAndUpdate } from './module-update';
 
-type UpgradeOutcome =
-  | {
-      status: 'success';
-      moduleId: string;
-      /** Version that was on disk before the upgrade (manifest.yml semver). */
-      previousVersion: string;
-      /** Version that's now installed. Includes +N revision when known
-       *  (registry-driven upgrades pass the canonical "1.0.0+5" form;
-       *  path-driven upgrades fall back to the manifest semver). */
-      newVersion: string;
-    }
-  | { status: 'failed'; moduleId: string; error: string }
-  // `skipped` means the path expanded from a glob but isn't an
-  // upgradable target — either no manifest at all (probably a non-
-  // module sibling like `modules/archive/`) or a real module that
-  // isn't installed in this celilo. Treated as a soft pass so
-  // `celilo module update modules/*` does what users expect.
-  | { status: 'skipped'; moduleId: string; reason: string };
+const VALID_POLICIES: readonly UpgradePolicy[] = ['by-semver', 'always-safe', 'always-fast'];
 
 /**
- * Tunables for `upgradeOne`. Quiet mode silences the per-call log
- * lines so callers driving a batch (the registry sweep) can render
- * their own structured output without duplicates. `displayVersion`
- * lets the registry caller carry the canonical `+N` revision through
- * to both the DB column and the success log.
+ * Pick the effective upgrade policy. Pure (Rule 10): operator config override
+ * wins over the manifest default; an unknown/absent value falls back to
+ * `by-semver`.
  */
-interface UpgradeOpts {
-  quiet?: boolean;
-  displayVersion?: string;
+export function pickUpgradePolicy(
+  fromConfig: string | undefined,
+  fromManifest: string | undefined,
+): UpgradePolicy {
+  const candidate = fromConfig ?? fromManifest;
+  return VALID_POLICIES.includes(candidate as UpgradePolicy)
+    ? (candidate as UpgradePolicy)
+    : 'by-semver';
 }
 
 /**
- * Parse a celilo version string into [major, minor, patch, revision].
- * Celilo's published versions look like `1.0.0+3` — semver core plus a
- * publish revision suffix (the +N resets on every semver bump). Missing
- * segments default to 0; non-numeric segments are clamped to 0 so we
- * never throw on weird upstream input.
+ * Resolve whether a module opts into auto-upgrade by the poll. Pure (Rule 10):
+ * operator config override wins over the manifest default; the default is OFF
+ * (opt-in — a production module isn't auto-upgraded unless chosen).
  */
-function parseModuleVersion(v: string): [number, number, number, number] {
-  const cleaned = v.replace(/^[v=]+/, '');
-  const [core, rev] = cleaned.split('+');
-  const parts = (core ?? '').split('.');
-  const num = (s: string | undefined) => {
-    const n = Number(s ?? '0');
-    return Number.isNaN(n) ? 0 : n;
-  };
-  return [num(parts[0]), num(parts[1]), num(parts[2]), num(rev)];
+export function pickAutoUpgrade(
+  fromConfig: string | boolean | undefined,
+  fromManifest: boolean | undefined,
+): boolean {
+  if (typeof fromConfig === 'boolean') return fromConfig;
+  if (fromConfig === 'true') return true;
+  if (fromConfig === 'false') return false;
+  return fromManifest ?? false;
 }
 
-export type VersionChangeKind = 'up-to-date' | 'ahead' | 'patch' | 'minor' | 'major';
+export interface PollCandidate {
+  moduleId: string;
+  installed: string;
+  /** Latest registry version, or null when the module isn't on the registry. */
+  latest: string | null;
+  autoUpgrade: boolean;
+}
 
-/**
- * Classify a registry-side update relative to the installed version.
- *   `major` = breaking (semver-major bump). Operator must approve.
- *   `minor` = additive feature. Auto-applied.
- *   `patch` = bugfix or revision-only (+N) bump. Auto-applied.
- *   `up-to-date` = identical version.
- *   `ahead` = installed is newer than registry. Skip silently — usually
- *             means the operator pushed locally without publishing.
- *
- * Exported for unit tests.
- */
-export function classifyVersionChange(installed: string, latest: string): VersionChangeKind {
-  const [aMaj, aMin, aPat, aRev] = parseModuleVersion(installed);
-  const [bMaj, bMin, bPat, bRev] = parseModuleVersion(latest);
-  if (bMaj > aMaj) return 'major';
-  if (bMaj < aMaj) return 'ahead';
-  if (bMin > aMin) return 'minor';
-  if (bMin < aMin) return 'ahead';
-  if (bPat > aPat) return 'patch';
-  if (bPat < aPat) return 'ahead';
-  if (bRev > aRev) return 'patch';
-  if (bRev < aRev) return 'ahead';
-  return 'up-to-date';
+export interface PollTarget {
+  moduleId: string;
+  from: string;
+  to: string;
 }
 
 /**
- * Download a module package from the registry into a temp file and run
- * the standard upgradeOne path against it. Cleans the temp file in a
- * finally block so a mid-flight failure doesn't leak a tar.zst on disk.
+ * Pure: which candidates the poll should upgrade — opted into auto_upgrade AND a
+ * newer registry version exists. (Rule 10; the I/O — registry queries — happens
+ * in the caller.)
  */
-export async function fetchAndUpgrade(
-  client: RegistryClient,
-  moduleId: string,
-  version: string,
-  db: ReturnType<typeof getDb>,
-  flags: Record<string, string | boolean>,
-): Promise<UpgradeOutcome> {
-  const tmpPath = join(tmpdir(), `${moduleId}-${version}-${Date.now()}.netapp`);
-  try {
-    const pkgData = await client.download(moduleId, version);
-    await Bun.write(tmpPath, pkgData);
-  } catch (err) {
-    return {
-      status: 'failed',
-      moduleId,
-      error: `Download failed: ${err instanceof Error ? err.message : String(err)}`,
-    };
-  }
-  try {
-    // Registry packages are pre-verified at publish time; skip the
-    // signature check here to match `module import`'s registry path.
-    // `quiet: true` suppresses upgradeOne's per-call log lines so the
-    // sweep can render its own structured per-module output without
-    // duplicates. `displayVersion: version` carries the registry's
-    // canonical "X.Y.Z+N" through to both the DB column and the success
-    // log line — without it, output would say "v1.0.0 → v1.0.0" because
-    // the manifest semver doesn't include the +N revision.
-    return await upgradeOne(
-      tmpPath,
-      db,
-      { ...flags, 'skip-verify': true },
-      { quiet: true, displayVersion: version },
-    );
-  } finally {
-    try {
-      await unlink(tmpPath);
-    } catch {}
+export function selectPollTargets(candidates: PollCandidate[]): PollTarget[] {
+  const targets: PollTarget[] = [];
+  for (const c of candidates) {
+    if (!c.autoUpgrade || !c.latest) continue;
+    const change = classifyVersionChange(c.installed, c.latest);
+    if (change === 'up-to-date' || change === 'ahead') continue;
+    targets.push({ moduleId: c.moduleId, from: c.installed, to: c.latest });
   }
+  return targets;
+}
+
+/** Resolve a module's auto_upgrade flag from config (override) + manifest (default). */
+function resolveAutoUpgrade(moduleId: string, manifest: ModuleManifest): boolean {
+  const cfg = getModuleConfigValue(moduleId, 'auto_upgrade');
+  const fromConfig =
+    typeof cfg?.value === 'string' || typeof cfg?.value === 'boolean' ? cfg.value : undefined;
+  return pickAutoUpgrade(
+    fromConfig,
+    (manifest as ModuleManifest & { auto_upgrade?: boolean }).auto_upgrade,
+  );
 }
 
 /**
- * Upgrade a single module from a source path
+ * Upgrade ONE module to a known target version: posture → update → backup →
+ * deploy → verify. The shared core for both the single-module command and the
+ * poll. `mod` is the current DB row; `targetVersion` is the registry latest.
  */
-export async function upgradeOne(
-  sourcePath: string,
-  db: ReturnType<typeof getDb>,
-  flags: Record<string, string | boolean> = {},
-  opts: UpgradeOpts = {},
-): Promise<UpgradeOutcome> {
-  const originalCwd = process.env.CELILO_ORIGINAL_CWD || process.cwd();
-  const importPath = resolve(originalCwd, sourcePath);
-  if (!existsSync(importPath)) {
-    return {
-      status: 'failed',
-      moduleId: sourcePath,
-      error: `Source path not found: ${importPath}`,
-    };
+async function upgradeOneModule(
+  mod: typeof modules.$inferSelect,
+  targetVersion: string,
+  client: RegistryClient,
+  db: DbClient,
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const moduleId = mod.id;
+  const manifest = mod.manifestData as ModuleManifest;
+
+  // Posture.
+  const configPolicy = getModuleConfigValue(moduleId, 'upgrade_policy');
+  const modulePolicy = pickUpgradePolicy(
+    typeof configPolicy?.value === 'string' ? configPolicy.value : undefined,
+    (manifest as ModuleManifest & { upgrade_policy?: string }).upgrade_policy,
+  );
+  // Per-release deploy_posture override lives in the .netapp release metadata;
+  // reading it requires fetching the package first. Deferred — the classifier
+  // supports it (deploy-posture.ts) and no app stamps it yet.
+  const { posture, reason } = resolveDeployPosture({
+    installed: mod.version,
+    next: targetVersion,
+    releasePosture: null,
+    modulePolicy,
+  });
+  log.info(`Upgrading ${moduleId} ${mod.version} → ${targetVersion} (${posture} — ${reason})`);
+
+  // Update (refresh stored def).
+  const updated = await fetchAndUpdate(client, moduleId, targetVersion, db, flags);
+  if (updated.status !== 'success') {
+    const why = updated.status === 'failed' ? updated.error : updated.reason;
+    return { success: false, error: `Update failed for ${moduleId}: ${why}` };
   }
 
-  // Handle .netapp packages: extract to temp dir
-  let actualPath = importPath;
-  let tempDir: string | null = null;
-
-  if (importPath.endsWith('.netapp')) {
-    const extractResult = await extractPackage(importPath);
-    if (!extractResult.success || !extractResult.tempDir) {
-      return {
-        status: 'failed',
-        moduleId: sourcePath,
-        error: extractResult.error || 'Failed to extract package',
-      };
-    }
-    tempDir = extractResult.tempDir;
-    actualPath = tempDir;
-
-    // Skip signature verification if --skip-verify
-    if (flags['skip-verify'] !== true) {
-      const { verifyPackageIntegrity } = await import('../../module/packaging/extract');
-      const verifyResult = await verifyPackageIntegrity(tempDir);
-      if (!verifyResult.success) {
-        await cleanupTempDir(tempDir);
+  // Safe → back up first (when there's a backup hook).
+  if (posture === 'safe') {
+    if (manifest.hooks?.on_backup) {
+      const backup = await createModuleBackup(moduleId);
+      if (!backup.success) {
         return {
-          status: 'failed',
-          moduleId: sourcePath,
-          error: verifyResult.error || 'Package verification failed',
+          success: false,
+          error: `Pre-upgrade backup failed for ${moduleId}: ${backup.error}`,
         };
       }
-    } else if (!opts.quiet) {
-      log.warn('Skipping package signature verification (--skip-verify)');
+      log.success(`Backed up ${moduleId} before deploy`);
+    } else {
+      log.warn(`${moduleId} has no on_backup hook — proceeding without a pre-upgrade backup`);
     }
   }
 
-  const manifestPath = join(actualPath, 'manifest.yml');
-  if (!existsSync(manifestPath)) {
-    if (tempDir) await cleanupTempDir(tempDir);
-    // No manifest means the path isn't a module directory at all —
-    // a likely outcome of `module update modules/*` matching a
-    // non-module sibling. Skip silently rather than fail the batch.
+  // Deploy (idempotent).
+  const deployed = await deployModule(moduleId, db, {});
+  if (!deployed.success) {
     return {
-      status: 'skipped',
-      moduleId: sourcePath,
-      reason: 'not a module directory (no manifest.yml)',
+      success: false,
+      error: `Deploy failed for ${moduleId} (now at ${targetVersion}): ${deployed.error}`,
     };
   }
 
-  let newManifest: ModuleManifest;
-  try {
-    const raw = readFileSync(manifestPath, 'utf-8');
-    const parsed = parseYaml(raw);
-    newManifest = ModuleManifestSchema.parse(parsed);
-  } catch (err) {
-    if (tempDir) await cleanupTempDir(tempDir);
-    const msg = err instanceof Error ? err.message : String(err);
-    return { status: 'failed', moduleId: sourcePath, error: `Invalid manifest: ${msg}` };
-  }
-
-  const moduleId = newManifest.id;
-
-  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
-  if (!module) {
-    if (tempDir) await cleanupTempDir(tempDir);
-    // Module isn't installed in this celilo. Don't fail the batch —
-    // `module update modules/*` should keep going for everything
-    // that IS installed. Caller surfaces the skip count so the user
-    // sees what was passed over.
+  // Verify.
+  const health = await runModuleHealthCheck(moduleId, db, {});
+  if (health.status === 'unhealthy' || health.status === 'error') {
     return {
-      status: 'skipped',
-      moduleId,
-      reason: `not installed (run 'celilo module import ${sourcePath}' to add)`,
+      success: false,
+      error: `Upgraded ${moduleId} to ${targetVersion} but post-deploy verify failed (health: ${health.status}${health.error ? ` — ${health.error}` : ''}).`,
     };
   }
+  const verifyNote = health.status === 'degraded' ? ' (health: degraded)' : '';
+  return {
+    success: true,
+    message: `Upgraded ${moduleId} ${mod.version} → ${targetVersion} (${posture}); verified${verifyNote}.`,
+  };
+}
 
-  // Old version comes from the DB so we capture whatever was last
-  // recorded (which IS the registry-versioned form, e.g. "1.0.0+5",
-  // for registry-driven installs/upgrades).
-  const previousVersion = module.version;
-  // New version: prefer the caller-supplied display version (registry's
-  // canonical "X.Y.Z+N"), fall back to the manifest semver core when
-  // upgrading from a local path.
-  const newVersion = opts.displayVersion ?? newManifest.version;
-  if (!opts.quiet) {
-    log.info(`Upgrading ${moduleId}: ${previousVersion} → ${newVersion}`);
-  }
-
-  // Copy new module files, preserving generated output and state
-  const installedPath = module.sourcePath;
-  const preserveDirs = new Set(['generated', 'screenshots', 'cookies.json']);
-
-  const skipDirs = new Set(['.git', 'node_modules', '.next', '.cache']);
-  const entries = readdirSync(actualPath);
-  for (const entry of entries) {
-    if (preserveDirs.has(entry) || skipDirs.has(entry)) continue;
-    const src = join(actualPath, entry);
-    const dest = join(installedPath, entry);
-    cpSync(src, dest, { recursive: true, force: true });
-  }
-
-  // Clean up temp dir if we extracted a .netapp
-  if (tempDir) await cleanupTempDir(tempDir);
-
-  // Update manifest in database. We persist the display version (with
-  // +N when known) so subsequent `module list` / `module update` calls
-  // see the same version string the registry reported.
-  db.update(modules)
-    .set({
-      manifestData: newManifest as unknown as Record<string, unknown>,
-      version: newVersion,
-      name: newManifest.name,
-    })
-    .where(eq(modules.id, moduleId))
-    .run();
-
-  // Re-register capabilities
-  db.delete(capabilities).where(eq(capabilities.moduleId, moduleId)).run();
-
-  if (newManifest.provides?.capabilities && newManifest.provides.capabilities.length > 0) {
-    const regResult = await registerModuleCapabilities(moduleId, newManifest, db.$client);
-    if (!regResult.success && !opts.quiet) {
-      // Capability re-registration warnings are useful when upgrading
-      // from a path (operator iterating on dev module); for the
-      // registry sweep, the caller will surface them itself if needed.
-      log.warn(`  ${moduleId}: capability re-registration warning: ${regResult.error}`);
-    }
-  }
-
-  // (Re-)register event-bus subscriptions from the new manifest —
-  // mirrors import.ts (ISS-0091: update used to skip this, so a
-  // refreshed module silently lost its reconcile subscriptions).
-  // registerModuleSubscriptions is idempotent; best-effort like import:
-  // a bus problem shouldn't wedge the upgrade, but must be loud.
-  try {
-    const { registerModuleSubscriptions } = await import('../../services/module-subscriptions');
-    registerModuleSubscriptions(newManifest, installedPath);
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    log.warn(`  ${moduleId}: failed to register event-bus subscriptions: ${msg}`);
-    log.warn(
-      '  Module upgraded, but reactive flows on the event bus will not fire until this is fixed.',
-    );
-  }
-
-  if (!opts.quiet) {
-    log.success(`Upgraded ${moduleId} (${previousVersion} → ${newVersion})`);
-  }
-  return { status: 'success', moduleId, previousVersion, newVersion };
+/** Latest registry version for a module, or null when absent. */
+async function latestRegistryVersion(
+  client: RegistryClient,
+  moduleId: string,
+): Promise<string | null> {
+  const entries = await client.getIndex(moduleId);
+  return entries.length > 0 ? (client.latestVersion(entries)?.vers ?? null) : null;
 }
 
 /**
- * Handle module upgrade command
- *
- * @param args - Command arguments: [path, path, ...]
- * @returns Command result
+ * The CD poll (ISS-0139): upgrade every INSTALLED module that opted into
+ * auto_upgrade and has a newer registry version. This is what the timer-driven
+ * CD job runs (install-mode gating — ISS-0142 — applies at the scheduling layer).
  */
-export async function handleModuleUpgrade(
-  args: string[],
-  flags: Record<string, string | boolean> = {},
+async function runRegistryPoll(
+  db: DbClient,
+  flags: Record<string, string | boolean>,
 ): Promise<CommandResult> {
-  const db = getDb();
+  const client = new RegistryClient(getFlag(flags, 'registry', '') || undefined);
+  const installed = db.select().from(modules).all();
 
-  // Zero args = registry sweep: walk every installed module, pick up
-  // any non-breaking update from the registry automatically, and
-  // prompt per-module for breaking (semver-major) updates.
-  if (args.length === 0) {
-    return runRegistrySweep(db, flags);
+  const candidates: PollCandidate[] = [];
+  const rowById = new Map<string, typeof modules.$inferSelect>();
+  for (const mod of installed) {
+    rowById.set(mod.id, mod);
+    candidates.push({
+      moduleId: mod.id,
+      installed: mod.version,
+      latest: await latestRegistryVersion(client, mod.id),
+      autoUpgrade: resolveAutoUpgrade(mod.id, mod.manifestData as ModuleManifest),
+    });
   }
 
-  const results: UpgradeOutcome[] = [];
-
-  for (const path of args) {
-    const result = await upgradeOne(path, db, flags);
-    results.push(result);
+  const targets = selectPollTargets(candidates);
+  if (targets.length === 0) {
+    return { success: true, message: 'Registry poll: all auto_upgrade modules are up to date.' };
   }
 
-  const succeeded = results.filter(
-    (r): r is Extract<UpgradeOutcome, { status: 'success' }> => r.status === 'success',
-  );
-  const failed = results.filter(
-    (r): r is Extract<UpgradeOutcome, { status: 'failed' }> => r.status === 'failed',
-  );
-  const skipped = results.filter(
-    (r): r is Extract<UpgradeOutcome, { status: 'skipped' }> => r.status === 'skipped',
-  );
-
-  // Skips that fall under a wildcard expansion (e.g. modules/* picking
-  // up `modules/archive/`) shouldn't even be mentioned — they're not
-  // signal. Skips for "module not installed" ARE signal because the
-  // user explicitly named the path; surface those.
-  const meaningfulSkips = skipped.filter((r) => !r.reason.startsWith('not a module directory'));
-
-  if (failed.length > 0) {
-    const errors = failed.map((r) => `  ${r.moduleId}: ${r.error}`).join('\n');
-    const parts: string[] = [];
-    if (succeeded.length > 0) {
-      parts.push(
-        `Upgraded ${succeeded.length} module(s): ${succeeded.map((r) => r.moduleId).join(', ')}`,
-      );
-    }
-    if (meaningfulSkips.length > 0) {
-      const skipLines = meaningfulSkips.map((r) => `  ${r.moduleId}: ${r.reason}`).join('\n');
-      parts.push(`Skipped ${meaningfulSkips.length}:\n${skipLines}`);
-    }
-    parts.push(`Failed ${failed.length}:\n${errors}`);
-    return { success: false, error: parts.join('\n\n') };
+  log.info(`Registry poll: ${targets.length} module(s) to upgrade.`);
+  const upgraded: string[] = [];
+  const failed: string[] = [];
+  // Serial, in installed order. (Strict provider-before-consumer ordering via
+  // topologicalOrder is a refinement; the poll is idempotent + re-runs.)
+  for (const t of targets) {
+    const mod = rowById.get(t.moduleId);
+    if (!mod) continue;
+    const result = await upgradeOneModule(mod, t.to, client, db, flags);
+    if (result.success) upgraded.push(`${t.moduleId}→${t.to}`);
+    else failed.push(`${t.moduleId}: ${result.error}`);
   }
 
-  const lines: string[] = [];
-  if (succeeded.length > 0) {
-    lines.push(
-      `Updated ${succeeded.length} module(s): ${succeeded.map((r) => r.moduleId).join(', ')}`,
-    );
-  }
-  if (meaningfulSkips.length > 0) {
-    const skipLines = meaningfulSkips.map((r) => `  ${r.moduleId}: ${r.reason}`).join('\n');
-    lines.push(`Skipped ${meaningfulSkips.length}:\n${skipLines}`);
-  }
-  if (lines.length === 0) {
-    // Every arg was a non-module sibling — odd but not a failure.
-    lines.push(
-      `No modules to update (${results.length} path(s) skipped — none had a manifest.yml)`,
-    );
+  if (failed.length > 0) {
+    return {
+      success: false,
+      error: `Registry poll: upgraded ${upgraded.length}, FAILED ${failed.length}:\n  ${failed.join('\n  ')}`,
+    };
   }
-  return { success: true, message: lines.join('\n\n') };
-}
-
-interface UpdatePlan {
-  moduleId: string;
-  installedVersion: string;
-  targetVersion: string;
-  classification: Exclude<VersionChangeKind, 'up-to-date' | 'ahead'>;
+  return {
+    success: true,
+    message: `Registry poll: upgraded ${upgraded.length} — ${upgraded.join(', ')}.`,
+  };
 }
 
-/**
- * Walk every installed module, query the registry, and produce a plan.
- * Auto-apply non-breaking updates (patch/minor); prompt per-module for
- * breaking (major) updates. Modules absent from the registry are
- * surfaced as a skip — typically these are local-only modules the
- * operator imported from a path, never published.
- */
-async function runRegistrySweep(
-  db: ReturnType<typeof getDb>,
-  flags: Record<string, string | boolean>,
+export async function handleModuleUpgrade(
+  args: string[],
+  flags: Record<string, string | boolean> = {},
 ): Promise<CommandResult> {
-  const installed = db.select().from(modules).all();
-  if (installed.length === 0) {
-    return { success: true, message: 'No modules installed.' };
-  }
-
-  const registryUrl = getFlag(flags, 'registry', '');
-  const client = new RegistryClient(registryUrl || undefined);
-
-  log.info(`Checking ${installed.length} installed module(s) against the registry…`);
-
-  const plans: UpdatePlan[] = [];
-  const upToDate: string[] = [];
-  const notInRegistry: string[] = [];
-  const errored: Array<{ moduleId: string; error: string }> = [];
+  const db = getDb();
+  const moduleId = getArg(args, 0);
 
-  for (const mod of installed) {
-    try {
-      const entries = await client.getIndex(mod.id);
-      if (entries.length === 0) {
-        notInRegistry.push(mod.id);
-        continue;
-      }
-      const latest = client.latestVersion(entries);
-      if (!latest) {
-        // All versions yanked.
-        notInRegistry.push(mod.id);
-        continue;
-      }
-      const cmp = classifyVersionChange(mod.version, latest.vers);
-      if (cmp === 'up-to-date' || cmp === 'ahead') {
-        upToDate.push(mod.id);
-        continue;
-      }
-      plans.push({
-        moduleId: mod.id,
-        installedVersion: mod.version,
-        targetVersion: latest.vers,
-        classification: cmp,
-      });
-    } catch (err) {
-      errored.push({
-        moduleId: mod.id,
-        error: err instanceof Error ? err.message : String(err),
-      });
-    }
+  // No name → the CD poll over all auto_upgrade modules.
+  if (!moduleId) {
+    return runRegistryPoll(db, flags);
   }
 
-  if (plans.length === 0) {
-    const lines: string[] = ['All installed modules are up to date.'];
-    if (notInRegistry.length > 0) {
-      lines.push(`Not in registry: ${notInRegistry.join(', ')}`);
-    }
-    if (errored.length > 0) {
-      lines.push(`Registry errors: ${errored.map((e) => `${e.moduleId} (${e.error})`).join('; ')}`);
-    }
-    return { success: true, message: lines.join('\n') };
+  const mod = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!mod) {
+    return { success: false, error: `Module not found: ${moduleId}` };
   }
 
-  const nonBreaking = plans.filter((p) => p.classification !== 'major');
-  const breaking = plans.filter((p) => p.classification === 'major');
-
-  let appliedNonBreaking = 0;
-  const failed: Array<{ moduleId: string; error: string }> = [];
-
-  if (nonBreaking.length > 0) {
-    log.info(`Auto-applying ${nonBreaking.length} non-breaking update(s):`);
-    for (const plan of nonBreaking) {
-      const result = await fetchAndUpgrade(client, plan.moduleId, plan.targetVersion, db, flags);
-      if (result.status === 'failed') {
-        failed.push({ moduleId: plan.moduleId, error: result.error });
-        console.log(
-          `  ✗ ${plan.moduleId.padEnd(30)} ${plan.installedVersion} → ${plan.targetVersion}  (${plan.classification}, FAILED)`,
-        );
-      } else if (result.status === 'success') {
-        appliedNonBreaking++;
-        console.log(
-          `  ✓ ${plan.moduleId.padEnd(30)} ${result.previousVersion} → ${result.newVersion}  (${plan.classification})`,
-        );
-      }
-      // status === 'skipped' shouldn't happen for registry-fetched packages
-      // (we know the module is installed; the package definitely has a
-      // manifest), but treat it as a no-op if it does.
-    }
+  const client = new RegistryClient(getFlag(flags, 'registry', '') || undefined);
+  const latest = await latestRegistryVersion(client, moduleId);
+  if (!latest) {
+    return { success: false, error: `${moduleId} is not on the registry — nothing to upgrade to.` };
   }
-
-  let appliedBreaking = 0;
-  let skippedBreaking = 0;
-
-  if (breaking.length > 0) {
-    log.info('\nBreaking updates available — review required (semver-major bump):');
-    for (const plan of breaking) {
-      console.log(
-        `  ⚠ ${plan.moduleId.padEnd(30)} ${plan.installedVersion} → ${plan.targetVersion}`,
-      );
-    }
-    log.message('Each breaking update will be applied only on explicit confirmation.\n');
-
-    for (const plan of breaking) {
-      const proceed = await withInterviewSession(() =>
-        askConfirm({
-          scope: `module-upgrade:${plan.moduleId}`,
-          key: 'apply_breaking',
-          message: `Apply breaking update for ${plan.moduleId} (${plan.installedVersion} → ${plan.targetVersion})?`,
-          defaultValue: false,
-        }),
-      );
-      if (!proceed) {
-        skippedBreaking++;
-        continue;
-      }
-      const result = await fetchAndUpgrade(client, plan.moduleId, plan.targetVersion, db, flags);
-      if (result.status === 'failed') {
-        failed.push({ moduleId: plan.moduleId, error: result.error });
-        console.log(
-          `  ✗ ${plan.moduleId.padEnd(30)} ${plan.installedVersion} → ${plan.targetVersion}  (major, FAILED)`,
-        );
-      } else if (result.status === 'success') {
-        appliedBreaking++;
-        console.log(
-          `  ✓ ${plan.moduleId.padEnd(30)} ${result.previousVersion} → ${result.newVersion}  (major)`,
-        );
-      }
-    }
+  const change = classifyVersionChange(mod.version, latest);
+  if (change === 'up-to-date' || change === 'ahead') {
+    return { success: true, message: `${moduleId} is already up to date (${mod.version}).` };
   }
 
-  // Summary
-  const summary: string[] = [];
-  const totalApplied = appliedNonBreaking + appliedBreaking;
-  if (totalApplied > 0) {
-    const parts = [`${appliedNonBreaking} non-breaking`];
-    if (appliedBreaking > 0) parts.push(`${appliedBreaking} breaking`);
-    summary.push(`Applied ${totalApplied} update(s) (${parts.join(', ')}).`);
-  } else {
-    summary.push('No updates applied.');
-  }
-  if (skippedBreaking > 0) {
-    summary.push(`Skipped ${skippedBreaking} breaking update(s) (operator declined).`);
-  }
-  if (notInRegistry.length > 0) {
-    summary.push(`Not in registry (${notInRegistry.length}): ${notInRegistry.join(', ')}`);
-  }
-  if (errored.length > 0) {
-    summary.push(
-      `Registry errors (${errored.length}): ${errored.map((e) => `${e.moduleId} — ${e.error}`).join('; ')}`,
-    );
-  }
-  if (failed.length > 0) {
-    return {
-      success: false,
-      error: [
-        ...summary,
-        '',
-        'Failures:',
-        ...failed.map((f) => `  ${f.moduleId}: ${f.error}`),
-      ].join('\n'),
-    };
-  }
-  return { success: true, message: summary.join('\n') };
+  return upgradeOneModule(mod, latest, client, db, flags);
 }