@tikoci/quickchr 0.2.0 → 0.3.1

package/README.md

@@ -150,7 +150,7 @@ quickchr doctor
 |------|-------------|---------|
 | `--version <ver>` | RouterOS version (e.g., 7.22.1) | Latest stable |
 | `--channel <ch>` | stable, long-term, testing, development | stable |
-| `--arch <arch>` | arm64 or x86 | Host native |
+| `--arch <arch>` | arm64, x86, or auto | Host native |
 | `--name <name>` | Instance name | Auto-generated |
 | `--cpu <n>` | vCPU count | 1 |
 | `--mem <mb>` | Memory in MB | 512 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/quickchr",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
   "module": "src/index.ts",
   "main": "src/index.ts",

package/src/cli/index.ts

@@ -5,6 +5,7 @@
 
 import type { StartOptions, Arch, Channel, ServiceName, NetworkSpecifier } from "../lib/types.ts";
 import { parseNetworkSpecifier } from "../lib/network.ts";
+import { parseForwardSpec } from "../lib/forward-spec.ts";
 import {
 	MIN_PROVISION_VERSION,
 	PROVISIONING_BOOT_ONLY_SUMMARY,
@@ -181,6 +182,9 @@ async function main() {
 			case "net":
 				await cmdNetworks(args.slice(1));
 				break;
+			case "cache":
+				await cmdCache(args.slice(1));
+				break;
 			case "version":
 			case "--version":
 			case "-v":
@@ -474,7 +478,7 @@ async function cmdAdd(argv: string[]) {
 	const opts: StartOptions = {
 		version: flag(flags, "version"),
 		channel: flag(flags, "channel") as Channel | undefined,
-		arch: flag(flags, "arch") as Arch | undefined,
+		arch: flag(flags, "arch") as Arch | "auto" | undefined,
 		name: flag(flags, "name") ?? positional[0],
 		cpu: flag(flags, "cpu") ? Number(flag(flags, "cpu")) : undefined,
 		mem: flag(flags, "mem") ? Number(flag(flags, "mem")) : undefined,
@@ -489,6 +493,7 @@ async function cmdAdd(argv: string[]) {
 		bootDiskFormat: (flag(flags, "boot-disk-format") as StartOptions["bootDiskFormat"] | undefined) ?? "qcow2",
 		bootSize: flag(flags, "boot-size"),
 		extraDisks: flagList(flags, "add-disk").length > 0 ? flagList(flags, "add-disk") : undefined,
+		extraPorts: flagList(flags, "forward").map(parseForwardSpec),
 	};
 
 	const deviceModeValue = flag(flags, "device-mode");
@@ -1155,7 +1160,7 @@ async function cmdStart(argv: string[]) {
 	const opts: StartOptions = {
 		version: flag(flags, "version"),
 		channel: flag(flags, "channel") as Channel | undefined,
-		arch: flag(flags, "arch") as Arch | undefined,
+		arch: flag(flags, "arch") as Arch | "auto" | undefined,
 		name: flag(flags, "name") ?? positional[0],
 		cpu: flag(flags, "cpu") ? Number(flag(flags, "cpu")) : undefined,
 		mem: flag(flags, "mem") ? Number(flag(flags, "mem")) : undefined,
@@ -1170,6 +1175,7 @@ async function cmdStart(argv: string[]) {
 		bootDiskFormat: (flag(flags, "boot-disk-format") as StartOptions["bootDiskFormat"] | undefined) ?? "qcow2",
 		bootSize: flag(flags, "boot-size"),
 		extraDisks: flagList(flags, "add-disk").length > 0 ? flagList(flags, "add-disk") : undefined,
+		extraPorts: flagList(flags, "forward").map(parseForwardSpec),
 		installDeps: flagBool(flags, "install-deps"),
 		dryRun: flagBool(flags, "dry-run"),
 		timeoutExtra: parseInt(flag(flags, "timeout-extra") ?? flag(flags, "T") ?? "0", 10) * 1000 || undefined,
@@ -2249,6 +2255,130 @@ async function cmdLogs(argv: string[]) {
 	}
 }
 
+async function cmdCache(argv: string[]) {
+	const { flags, positional } = parseFlags(argv);
+	const sub = positional[0] ?? "list";
+
+	if (sub === "help" || sub === "--help" || sub === "-h") {
+		printCommandHelp("cache");
+		return;
+	}
+
+	const { listCacheEntries, pruneCache } = await import("../lib/cache.ts");
+
+	const parseDuration = (s: string): number => {
+		const m = s.match(/^(\d+(?:\.\d+)?)([smhdw])$/);
+		if (!m) throw new Error(`Invalid duration "${s}" (use Ns/Nm/Nh/Nd/Nw, e.g. 7d)`);
+		const n = Number.parseFloat(m[1] ?? "0");
+		const unit = m[2];
+		const mult: Record<string, number> = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+		return Math.floor(n * (mult[unit ?? ""] ?? 0));
+	};
+	const parseSize = (s: string): number => {
+		const m = s.match(/^(\d+(?:\.\d+)?)([KMGT]?)i?B?$/i);
+		if (!m) throw new Error(`Invalid size "${s}" (use NK/NM/NG/NT, e.g. 2G)`);
+		const n = Number.parseFloat(m[1] ?? "0");
+		const unit = (m[2] ?? "").toUpperCase();
+		const mult: Record<string, number> = { "": 1, K: 1024, M: 1024 ** 2, G: 1024 ** 3, T: 1024 ** 4 };
+		return Math.floor(n * (mult[unit] ?? 1));
+	};
+	const formatSize = (b: number): string => {
+		if (b >= 1024 ** 3) return `${(b / 1024 ** 3).toFixed(2)} GiB`;
+		if (b >= 1024 ** 2) return `${(b / 1024 ** 2).toFixed(1)} MiB`;
+		if (b >= 1024) return `${(b / 1024).toFixed(1)} KiB`;
+		return `${b} B`;
+	};
+	const formatAge = (ms: number): string => {
+		const s = Math.floor(ms / 1000);
+		if (s < 60) return `${s}s`;
+		if (s < 3600) return `${Math.floor(s / 60)}m`;
+		if (s < 86400) return `${Math.floor(s / 3600)}h`;
+		return `${Math.floor(s / 86400)}d`;
+	};
+
+	switch (sub) {
+		case "list":
+		case "ls": {
+			const entries = listCacheEntries();
+			if (flags.json === true) {
+				console.log(JSON.stringify(entries, null, 2));
+				return;
+			}
+			if (entries.length === 0) {
+				console.log("No cached images.");
+				return;
+			}
+			const now = Date.now();
+			const rows = entries.map((e) => ({
+				basename: e.basename,
+				version: e.version,
+				arch: e.arch,
+				size: formatSize(e.sizeBytes),
+				age: formatAge(now - e.mtimeMs),
+				inUse: e.inUse ? "yes" : "no",
+			}));
+			const widths = {
+				basename: Math.max(8, ...rows.map((r) => r.basename.length)),
+				version: Math.max(7, ...rows.map((r) => r.version.length)),
+				arch: Math.max(4, ...rows.map((r) => r.arch.length)),
+				size: Math.max(8, ...rows.map((r) => r.size.length)),
+				age: Math.max(3, ...rows.map((r) => r.age.length)),
+			};
+			const header = `${"BASENAME".padEnd(widths.basename)}  ${"VERSION".padEnd(widths.version)}  ${"ARCH".padEnd(widths.arch)}  ${"SIZE".padEnd(widths.size)}  ${"AGE".padEnd(widths.age)}  IN-USE`;
+			console.log(header);
+			for (const r of rows) {
+				console.log(
+					`${r.basename.padEnd(widths.basename)}  ${r.version.padEnd(widths.version)}  ${r.arch.padEnd(widths.arch)}  ${r.size.padEnd(widths.size)}  ${r.age.padEnd(widths.age)}  ${r.inUse}`,
+				);
+			}
+			const total = entries.reduce((s, e) => s + e.sizeBytes, 0);
+			console.log(`\nTotal: ${entries.length} image(s), ${formatSize(total)}`);
+			break;
+		}
+		case "prune": {
+			const opts: Parameters<typeof pruneCache>[0] = { dryRun: flags["dry-run"] === true };
+			if (typeof flags["older-than"] === "string") opts.olderThan = flags["older-than"];
+			if (typeof flags["max-age"] === "string") opts.maxAgeMs = parseDuration(flags["max-age"]);
+			if (typeof flags["max-size"] === "string") opts.maxSizeBytes = parseSize(flags["max-size"]);
+			if (opts.olderThan === undefined && opts.maxAgeMs === undefined && opts.maxSizeBytes === undefined) {
+				console.error("cache prune: provide at least one of --older-than, --max-age, --max-size");
+				process.exit(1);
+			}
+			const result = pruneCache(opts);
+			const verb = opts.dryRun ? "Would evict" : "Evicted";
+			if (result.evicted.length === 0) {
+				console.log("Nothing to evict.");
+			} else {
+				console.log(`${verb} ${result.evicted.length} image(s):`);
+				for (const e of result.evicted) {
+					const reason = result.reasons[e.basename] ?? "policy";
+					console.log(`  - ${e.basename} (${formatSize(e.sizeBytes)}) — ${reason}`);
+				}
+				console.log(`Freed: ${formatSize(result.freedBytes)}`);
+			}
+			break;
+		}
+		case "clear": {
+			if (flags.all !== true) {
+				console.error("cache clear: refuses without --all (deletes all non-in-use cached images)");
+				process.exit(1);
+			}
+			const result = pruneCache({ maxSizeBytes: 0, dryRun: flags["dry-run"] === true });
+			const verb = flags["dry-run"] === true ? "Would delete" : "Deleted";
+			console.log(`${verb} ${result.evicted.length} image(s), freed ${formatSize(result.freedBytes)}`);
+			if (result.kept.some((e) => e.inUse)) {
+				const inUse = result.kept.filter((e) => e.inUse);
+				console.log(`Kept ${inUse.length} in-use image(s):`);
+				for (const e of inUse) console.log(`  - ${e.basename}`);
+			}
+			break;
+		}
+		default:
+			console.error(`Unknown cache subcommand: ${sub}\nRun 'quickchr help cache' for usage.`);
+			process.exit(1);
+	}
+}
+
 async function cmdDoctor() {
 	const { QuickCHR } = await import("../lib/quickchr.ts");
 	const { statusIcon, bold } = await import("./format.ts");
@@ -2261,6 +2391,27 @@ async function cmdDoctor() {
 	}
 
 	console.log();
+
+	// Best-effort: warn about cache entries older than current long-term.
+	try {
+		const { listCacheEntries } = await import("../lib/cache.ts");
+		const { resolveVersion, compareRouterOsVersion } = await import("../lib/versions.ts");
+		const entries = listCacheEntries();
+		if (entries.length > 0) {
+			const longTerm = await resolveVersion("long-term");
+			const stale = entries.filter((e) => {
+				if (e.version === "unknown" || e.inUse) return false;
+				try { return compareRouterOsVersion(e.version, longTerm) < 0; } catch { return false; }
+			});
+			if (stale.length > 0) {
+				console.log(`Note: ${stale.length} cached image(s) older than current long-term (${longTerm}):`);
+				for (const e of stale) console.log(`  - ${e.basename} (${e.version})`);
+				console.log("  Hint: 'quickchr cache prune --older-than " + longTerm + "' to evict them.");
+				console.log();
+			}
+		}
+	} catch { /* offline or no cache — silent */ }
+
 	if (result.ok) {
 		console.log("All checks passed.");
 	} else {
@@ -2316,6 +2467,7 @@ Commands:
   disk <name>             Show disk details for an instance
   snapshot <name> [cmd]   Manage snapshots (list/save/load/delete)
   networks                Network discovery & socket management
+  cache [list|prune|clear] Manage cached CHR images
   completions             Manage shell completions (Tab completion)
   logs <name>             Tail the QEMU log for an instance
   doctor                  Check prerequisites
@@ -2351,13 +2503,18 @@ Options:
   --name <name>         Instance name (required)
   --version <ver>       RouterOS version (e.g., 7.22.1)
   --channel <ch>        Channel: stable, long-term, testing, development
-  --arch <arch>         Architecture: arm64, x86 (default: host native)
+  --arch <arch>         Architecture: arm64, x86, auto (default: host native)
   --cpu <n>             vCPU count (default: 1)
   --mem <mb>            RAM in MB (default: 512)
 	--boot-disk-format <f> Boot disk format: qcow2|raw (default: qcow2)
 	--boot-size <size>    Resize boot disk (e.g., 512M, 2G) — qcow2 only, requires qemu-img
 	--add-disk <size>     Add an extra blank qcow2 disk (repeatable, requires qemu-img)
   --add-package <pkg>   Extra package to install on first boot (repeatable)
+  --forward <spec>      Add an extra hostfwd port (repeatable). Spec:
+                        name[:host[:guest]][/proto]. Examples:
+                          --forward smb              (host auto, guest 445/tcp from registry)
+                          --forward winbox:9300      (host pinned, guest from registry)
+                          --forward myapp:9200:7777/udp  (fully explicit)
   --install-all-packages  Install all packages on first boot
   --add-user <u:p>      Create user on first boot (name:password)
   --disable-admin       Disable the default admin account on first boot
@@ -2424,7 +2581,7 @@ Options:
   --fg / --foreground   Run in foreground — serial console on stdio
   --version <ver>       RouterOS version (e.g., 7.22.1)
   --channel <ch>        Channel: stable, long-term, testing, development
-  --arch <arch>         Architecture: arm64, x86 (default: host native)
+  --arch <arch>         Architecture: arm64, x86, auto (default: host native)
   --name <name>         Instance name
   --cpu <n>             vCPU count (default: 1)
   --mem <mb>            RAM in MB (default: 512)
@@ -2432,6 +2589,9 @@ Options:
 	--boot-size <size>    Resize boot disk (e.g., 512M, 2G) — qcow2 only, requires qemu-img
 	--add-disk <size>     Add an extra blank qcow2 disk (repeatable, requires qemu-img)
   --add-package <pkg>   Extra package to install (repeatable)
+  --forward <spec>      Add an extra hostfwd port (repeatable). Spec:
+                        name[:host[:guest]][/proto]. Examples: smb,
+                        winbox:9300, myapp:9200:7777/udp.
   --add-user <u:p>      Create user with name:password
   --disable-admin       Disable the default admin account
   --no-secure-login     Keep admin with no password (skip managed account)
@@ -2617,6 +2777,24 @@ Credential resolution order (highest priority first):
 		case "net":
 			showNetworksHelp();
 			break;
+		case "cache":
+			console.log(`quickchr cache <list|prune|clear> [options]
+
+Manage cached CHR images in the data dir cache directory.
+
+Subcommands:
+  list [--json]                       List cached images (basename, version, arch, size, age, in-use).
+  prune [options]                     Evict cached images per policy. Never evicts in-use images.
+    --older-than <ver>                Evict images with version < <ver>.
+    --max-age <dur>                   Evict images older than duration (e.g. 7d, 24h).
+    --max-size <size>                 Evict oldest-version images until total size <= <size>.
+    --dry-run                         Show what would be evicted without deleting.
+  clear --all                         Delete all non-in-use cached images.
+
+Duration: <N>(s|m|h|d|w)   Size: <N>(K|M|G|T)[i][B] (case-insensitive, IEC binary).
+
+Default auto-prune cap: 2 GiB (applied after each successful start).`);
+			break;
 		default:
 			console.log(`No detailed help for '${command}'.`);
 	}

package/src/index.ts

@@ -15,7 +15,7 @@
  *
  * ## Key exports
  * - {@link QuickCHR} — Main class with static methods: `start()`, `add()`, `list()`, `get()`, `doctor()`
- * - {@link ChrInstance} — Runtime handle returned by `start()`: `stop()`, `remove()`, `rest()`, `exec()`, `snapshot`, etc.
+ * - {@link ChrInstance} — Runtime handle returned by `start()`: `stop()`, `remove()`, `rest()`, `exec()`, `upload()`, `download()`, `snapshot`, etc.
  * - {@link StartOptions} — All options for creating/starting a CHR instance
  * - {@link QuickCHRError} — Typed errors with codes like `MISSING_QEMU`, `TIMEOUT`, `EXEC_FAILED`
  *
@@ -119,6 +119,13 @@ export type { MikrotikCredentials, InstanceCredentials } from "./lib/credentials
 // Package utilities
 export { downloadPackages, listAvailablePackages, downloadAndListPackages, installPackages, installAllPackages } from "./lib/packages.ts";
 
+// Guest port registry
+export { WELL_KNOWN_GUEST_PORTS, lookupGuestPort } from "./lib/guest-ports.ts";
+export type { GuestPortDef } from "./lib/guest-ports.ts";
+
+// Forward spec parsing
+export { parseForwardSpec } from "./lib/forward-spec.ts";
+
 // Logging
 export { createLogger } from "./lib/log.ts";
 export type { ProgressLogger } from "./lib/log.ts";

package/src/lib/auth.ts

@@ -17,6 +17,11 @@ export interface ResolvedAuth {
 	user: string;
 }
 
+export interface ResolvedCreds {
+	user: string;
+	password: string;
+}
+
 /**
  * Resolve the best credentials for a machine.
  *
@@ -66,3 +71,19 @@ export function resolveAuth(
 		user: "admin",
 	};
 }
+
+/**
+ * Resolve raw username + password for a machine (same priority as {@link resolveAuth}).
+ * Used by transports that need the password in cleartext — SCP, SSH, SFTP.
+ */
+export function resolveCreds(
+	state: Pick<MachineState, "name" | "user" | "disableAdmin">,
+	user?: string,
+	password?: string,
+): ResolvedCreds {
+	if (user !== undefined) return { user, password: password ?? "" };
+	if (state.user) return { user: state.user.name, password: state.user.password };
+	const stored = getInstanceCredentials(state.name);
+	if (stored) return { user: stored.user, password: stored.password };
+	return { user: "admin", password: "" };
+}

package/src/lib/cache.ts

@@ -0,0 +1,251 @@
+/**
+ * Cache retention policy for downloaded CHR images.
+ *
+ * - Default cap: 2 GB total cache size (size-based eviction).
+ * - Eviction order: oldest RouterOS version first, mtime tiebreaker.
+ * - Never evicts an image referenced by any machine (running or stopped).
+ * - Callers can pin extra versions via `protectVersions` (e.g. current long-term).
+ */
+
+import { existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { getCacheDir, loadAllMachines } from "./state.ts";
+import { chrImageBasename, compareRouterOsVersion, isValidVersion } from "./versions.ts";
+import type { Arch } from "./types.ts";
+
+export const DEFAULT_CACHE_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+
+export interface CacheEntry {
+	path: string;
+	basename: string;
+	version: string;
+	arch: Arch | "unknown";
+	sizeBytes: number;
+	mtimeMs: number;
+	inUse: boolean;
+}
+
+export interface PruneOptions {
+	cacheDir?: string;
+	maxSizeBytes?: number;
+	maxAgeMs?: number;
+	olderThan?: string;
+	protectVersions?: string[];
+	dryRun?: boolean;
+}
+
+export interface PruneResult {
+	evicted: CacheEntry[];
+	kept: CacheEntry[];
+	freedBytes: number;
+	reasons: Record<string, string>;
+}
+
+/** Parse a cached file basename into version + arch. Returns "unknown" parts when unparseable. */
+export function parseCacheBasename(basename: string): { version: string; arch: Arch | "unknown" } {
+	// Strip recognized cache extensions (.img, .img.zip).
+	let stem = basename;
+	if (stem.endsWith(".img.zip")) stem = stem.slice(0, -".img.zip".length);
+	else if (stem.endsWith(".zip")) stem = stem.slice(0, -".zip".length);
+	else if (stem.endsWith(".img")) stem = stem.slice(0, -".img".length);
+
+	// chr-<version>[-arm64]
+	const m = stem.match(/^chr-(\d+\.\d+(?:\.\d+)?(?:beta\d+|rc\d+)?)(-arm64)?$/);
+	if (!m) return { version: "unknown", arch: "unknown" };
+	const version = m[1] ?? "unknown";
+	const arch: Arch = m[2] ? "arm64" : "x86";
+	if (!isValidVersion(version)) return { version: "unknown", arch };
+	return { version, arch };
+}
+
+function inUseSet(): Set<string> {
+	const set = new Set<string>();
+	let machines: ReturnType<typeof loadAllMachines>;
+	try {
+		machines = loadAllMachines();
+	} catch {
+		return set;
+	}
+	for (const m of machines) {
+		if (!m.version || !m.arch) continue;
+		set.add(`${chrImageBasename(m.version, m.arch)}.img`);
+		set.add(`${chrImageBasename(m.version, m.arch)}.img.zip`);
+	}
+	return set;
+}
+
+/** List cache entries with parsed metadata and in-use status. */
+export function listCacheEntries(cacheDir?: string): CacheEntry[] {
+	const dir = cacheDir ?? getCacheDir();
+	if (!existsSync(dir)) return [];
+	const used = inUseSet();
+	const out: CacheEntry[] = [];
+	for (const name of readdirSync(dir)) {
+		const full = join(dir, name);
+		let stat: ReturnType<typeof statSync>;
+		try {
+			stat = statSync(full);
+		} catch {
+			continue;
+		}
+		if (!stat.isFile()) continue;
+		if (!name.endsWith(".img") && !name.endsWith(".img.zip")) continue;
+		const { version, arch } = parseCacheBasename(name);
+		out.push({
+			path: full,
+			basename: name,
+			version,
+			arch,
+			sizeBytes: stat.size,
+			mtimeMs: stat.mtimeMs,
+			inUse: used.has(name),
+		});
+	}
+	return out;
+}
+
+function compareVersionsSafe(a: string, b: string): number {
+	if (a === b) return 0;
+	if (a === "unknown") return -1;
+	if (b === "unknown") return 1;
+	try {
+		return compareRouterOsVersion(a, b);
+	} catch {
+		return 0;
+	}
+}
+
+/**
+ * Apply the cache retention policy. Returns what was (or would be) evicted.
+ *
+ * Eviction proceeds only when at least one of these conditions is set and met:
+ *   - `maxSizeBytes`: total bytes exceed cap
+ *   - `maxAgeMs`: any entry older than threshold
+ *   - `olderThan`: any entry's parsed version older than threshold
+ *
+ * In-use entries and `protectVersions` entries are never evicted.
+ */
+export function pruneCache(opts: PruneOptions = {}): PruneResult {
+	const entries = listCacheEntries(opts.cacheDir);
+	const protect = new Set(opts.protectVersions ?? []);
+	const dryRun = opts.dryRun ?? false;
+	const now = Date.now();
+
+	const reasons: Record<string, string> = {};
+	const evicted: CacheEntry[] = [];
+	const kept: CacheEntry[] = [];
+
+	const protectedEntries: CacheEntry[] = [];
+	const candidates: CacheEntry[] = [];
+
+	for (const e of entries) {
+		if (e.inUse) {
+			protectedEntries.push(e);
+			continue;
+		}
+		if (protect.has(e.version)) {
+			protectedEntries.push(e);
+			continue;
+		}
+		candidates.push(e);
+	}
+
+	candidates.sort((a, b) => {
+		const v = compareVersionsSafe(a.version, b.version);
+		if (v !== 0) return v;
+		return a.mtimeMs - b.mtimeMs;
+	});
+
+	const evict = (e: CacheEntry, reason: string) => {
+		evicted.push(e);
+		reasons[e.basename] = reason;
+		if (!dryRun) {
+			try { unlinkSync(e.path); } catch { /* best-effort */ }
+		}
+	};
+
+	const remaining: CacheEntry[] = [];
+
+	if (opts.olderThan) {
+		const threshold = opts.olderThan;
+		for (const e of candidates) {
+			if (e.version !== "unknown" && compareVersionsSafe(e.version, threshold) < 0) {
+				evict(e, `version ${e.version} < ${threshold}`);
+			} else {
+				remaining.push(e);
+			}
+		}
+	} else {
+		remaining.push(...candidates);
+	}
+
+	const remainingAfterAge: CacheEntry[] = [];
+	if (opts.maxAgeMs !== undefined) {
+		const maxAge = opts.maxAgeMs;
+		for (const e of remaining) {
+			if (now - e.mtimeMs > maxAge) {
+				evict(e, `age ${(Math.floor((now - e.mtimeMs) / 1000))}s > ${Math.floor(maxAge / 1000)}s`);
+			} else {
+				remainingAfterAge.push(e);
+			}
+		}
+	} else {
+		remainingAfterAge.push(...remaining);
+	}
+
+	const keptSoFar: CacheEntry[] = [...remainingAfterAge];
+
+	if (opts.maxSizeBytes !== undefined) {
+		const cap = opts.maxSizeBytes;
+		const totalSize = (es: CacheEntry[]) => es.reduce((s, x) => s + x.sizeBytes, 0);
+		let total = totalSize(protectedEntries) + totalSize(keptSoFar);
+		while (total > cap && keptSoFar.length > 0) {
+			const victim = keptSoFar.shift();
+			if (!victim) break;
+			evict(victim, `size cap ${cap} exceeded (oldest version)`);
+			total -= victim.sizeBytes;
+		}
+	}
+
+	for (const e of protectedEntries) {
+		kept.push(e);
+		if (e.inUse) reasons[e.basename] ??= "in use";
+		else reasons[e.basename] ??= `protected (version ${e.version})`;
+	}
+	for (const e of keptSoFar) {
+		kept.push(e);
+		reasons[e.basename] ??= "kept";
+	}
+
+	const freedBytes = evicted.reduce((s, e) => s + e.sizeBytes, 0);
+	return { evicted, kept, freedBytes, reasons };
+}
+
+/**
+ * Best-effort auto-prune used by `start()` after a successful boot.
+ * Never throws — failures are swallowed and logged.
+ */
+export function autoPruneIfOverCap(opts: { logger?: (msg: string) => void; cacheDir?: string; maxSizeBytes?: number; protectVersions?: string[] } = {}): PruneResult {
+	const cap = opts.maxSizeBytes ?? DEFAULT_CACHE_MAX_BYTES;
+	try {
+		const entries = listCacheEntries(opts.cacheDir);
+		const total = entries.reduce((s, e) => s + e.sizeBytes, 0);
+		if (total <= cap) {
+			return { evicted: [], kept: entries, freedBytes: 0, reasons: {} };
+		}
+		const result = pruneCache({
+			cacheDir: opts.cacheDir,
+			maxSizeBytes: cap,
+			protectVersions: opts.protectVersions,
+		});
+		if (opts.logger && result.evicted.length > 0) {
+			opts.logger(`cache: evicted ${result.evicted.length} image(s), freed ${(result.freedBytes / 1024 / 1024).toFixed(1)} MiB`);
+		}
+		return result;
+	} catch (e) {
+		if (opts.logger) {
+			opts.logger(`cache: auto-prune skipped: ${e instanceof Error ? e.message : String(e)}`);
+		}
+		return { evicted: [], kept: [], freedBytes: 0, reasons: {} };
+	}
+}