@tikoci/quickchr 0.2.0

package/src/lib/device-mode.ts

@@ -0,0 +1,283 @@
+/**
+ * RouterOS device-mode provisioning helpers.
+ */
+
+import type { DeviceModeOptions } from "./types.ts";
+import { QuickCHRError } from "./types.ts";
+import { restGet, restPost } from "./rest.ts";
+
+export const KNOWN_DEVICE_MODES = ["home", "advanced", "basic", "rose"] as const;
+
+export const KNOWN_DEVICE_MODE_FEATURES = [
+	"scheduler",
+	"socks",
+	"fetch",
+	"pptp",
+	"l2tp",
+	"bandwidth-test",
+	"traffic-gen",
+	"sniffer",
+	"ipsec",
+	"romon",
+	"proxy",
+	"hotspot",
+	"smb",
+	"email",
+	"zerotier",
+	"container",
+	"install-any-version",
+	"partitions",
+	"routerboard",
+] as const;
+
+const KNOWN_MODE_SET = new Set<string>(KNOWN_DEVICE_MODES);
+const KNOWN_FEATURE_SET = new Set<string>(KNOWN_DEVICE_MODE_FEATURES);
+const SKIP_VALUES = new Set<string>(["skip", "none", "off", "disabled"]);
+
+type DeviceModeBool = "yes" | "no";
+
+export interface ResolvedDeviceModeOptions {
+	skip: boolean;
+	mode?: string;
+	features: Record<string, DeviceModeBool>;
+	warnings: string[];
+}
+
+export interface DeviceModeVerification {
+	ok: boolean;
+	mismatches: string[];
+	expected: Record<string, string>;
+	actual: Record<string, string>;
+}
+
+function norm(value: string): string {
+	return value.trim().toLowerCase();
+}
+
+function normalizeFeatureList(list: string[] | undefined): string[] {
+	if (!list) return [];
+	const values = list
+		.flatMap((item) => item.split(","))
+		.map((item) => norm(item))
+		.filter(Boolean);
+	return [...new Set(values)];
+}
+
+function toYesNo(value: unknown): string {
+	if (typeof value === "boolean") return value ? "yes" : "no";
+	if (typeof value === "number") return value > 0 ? "yes" : "no";
+	const normalized = String(value ?? "").trim().toLowerCase();
+	if (["yes", "true", "on", "enabled", "1"].includes(normalized)) return "yes";
+	if (["no", "false", "off", "disabled", "0"].includes(normalized)) return "no";
+	return normalized;
+}
+
+export function resolveDeviceModeOptions(options?: DeviceModeOptions): ResolvedDeviceModeOptions {
+	if (!options) {
+		return { skip: true, features: {}, warnings: [] };
+	}
+	const warnings: string[] = [];
+	const requestedMode = norm(options.mode ?? "auto");
+
+	if (SKIP_VALUES.has(requestedMode)) {
+		if ((options?.enable?.length ?? 0) > 0 || (options?.disable?.length ?? 0) > 0) {
+			warnings.push("device-mode=skip ignores --device-mode-enable/disable values");
+		}
+		return { skip: true, features: {}, warnings };
+	}
+
+	let mode = requestedMode;
+	if (mode === "enterprise") {
+		mode = "advanced";
+		warnings.push("device-mode mode 'enterprise' is legacy; using 'advanced'");
+	}
+	if (mode === "auto") {
+		mode = "rose";
+	}
+	if (!KNOWN_MODE_SET.has(mode)) {
+		warnings.push(`unknown device-mode '${mode}' (allowed; RouterOS will validate)`);
+	}
+
+	const enable = new Set(normalizeFeatureList(options?.enable));
+	const disable = new Set(normalizeFeatureList(options?.disable));
+
+	const conflicting: string[] = [];
+	for (const feature of enable) {
+		if (disable.has(feature)) {
+			conflicting.push(feature);
+			warnings.push(`device-mode feature '${feature}' set in both enable and disable; using disable`);
+		}
+	}
+	for (const feature of conflicting) {
+		enable.delete(feature);
+	}
+
+	const features: Record<string, DeviceModeBool> = {};
+	for (const feature of enable) {
+		if (!KNOWN_FEATURE_SET.has(feature)) {
+			warnings.push(`unknown device-mode feature '${feature}' in enable list (allowed; RouterOS will validate)`);
+		}
+		features[feature] = "yes";
+	}
+	for (const feature of disable) {
+		if (!KNOWN_FEATURE_SET.has(feature)) {
+			warnings.push(`unknown device-mode feature '${feature}' in disable list (allowed; RouterOS will validate)`);
+		}
+		features[feature] = "no";
+	}
+
+	return {
+		skip: false,
+		mode,
+		features,
+		warnings,
+	};
+}
+
+export function shouldApplyDeviceMode(options: ResolvedDeviceModeOptions): boolean {
+	return !options.skip && !!(options.mode || Object.keys(options.features).length > 0);
+}
+
+export function formatDeviceModeSelection(options: ResolvedDeviceModeOptions): string {
+	if (options.skip) return "skip";
+	const parts: string[] = [];
+	if (options.mode) parts.push(`mode=${options.mode}`);
+	for (const [name, value] of Object.entries(options.features)) {
+		parts.push(`${name}=${value}`);
+	}
+	return parts.join(" ");
+}
+
+/** Wait until the device-mode REST endpoint is reachable with default admin auth. */
+export async function waitForDeviceModeApi(httpPort: number, timeoutMs: number = 60_000): Promise<void> {
+	const auth = `Basic ${btoa("admin:")}`;
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		try {
+			const { status } = await restGet(
+				`http://127.0.0.1:${httpPort}/rest/system/device-mode`,
+				auth,
+				3000,
+			);
+
+			if (status >= 200 && status < 300) {
+				return;
+			}
+
+			if (status === 401) {
+				throw new QuickCHRError("PROCESS_FAILED", `Device-mode API auth failed: HTTP 401`);
+			}
+		} catch (error) {
+			if (error instanceof QuickCHRError) {
+				throw error;
+			}
+		}
+
+		await Bun.sleep(1000);
+	}
+
+	throw new QuickCHRError("BOOT_TIMEOUT", `Device-mode API did not become ready on port ${httpPort}`);
+}
+
+/**
+ * Fire the device-mode update request without awaiting its response.
+ *
+ * RouterOS blocks the HTTP connection waiting for power-cycle confirmation (up to 5 minutes).
+ * The caller MUST kill the QEMU process while this request is pending to confirm the change.
+ * The connection error (ECONNRESET) that results when QEMU exits is expected — suppress it.
+ *
+ * Uses restPost (node:http + agent:false) to bypass Bun's connection pool.
+ * The 300s timeout is a safety limit — the caller is expected to kill QEMU well before then.
+ */
+export function startDeviceModeUpdate(httpPort: number, options: ResolvedDeviceModeOptions): Promise<{ status: number; body: string }> {
+	if (!shouldApplyDeviceMode(options)) {
+		return Promise.resolve({ status: 200, body: "" });
+	}
+
+	const payload: Record<string, string> = {};
+	if (options.mode) payload.mode = options.mode;
+	for (const [name, value] of Object.entries(options.features)) {
+		payload[name] = value;
+	}
+
+	const auth = `Basic ${btoa("admin:")}`;
+	return restPost(
+		`http://127.0.0.1:${httpPort}/rest/system/device-mode/update`,
+		auth,
+		payload,
+		300_000, // Safety timeout — QEMU kill should resolve this first
+	);
+}
+
+export async function readDeviceMode(httpPort: number): Promise<Record<string, string>> {
+	const auth = `Basic ${btoa("admin:")}`;
+	const { status, body } = await restGet(
+		`http://127.0.0.1:${httpPort}/rest/system/device-mode`,
+		auth,
+		30_000,
+	);
+
+	if (status < 200 || status >= 300) {
+		throw new QuickCHRError(
+			"PROCESS_FAILED",
+			`Failed to read device-mode: HTTP ${status} - ${body}`,
+		);
+	}
+
+	let data: unknown;
+	try { data = JSON.parse(body); } catch {
+		throw new QuickCHRError("PROCESS_FAILED", "Invalid /system/device-mode REST response (not JSON)");
+	}
+
+	const record = Array.isArray(data) ? data[0] : data;
+	if (!record || typeof record !== "object") {
+		throw new QuickCHRError("PROCESS_FAILED", "Invalid /system/device-mode REST response");
+	}
+
+	// Guard: /system/resource data instead of device-mode — REST startup race.
+	if ("board-name" in (record as Record<string, unknown>) || "architecture-name" in (record as Record<string, unknown>)) {
+		throw new QuickCHRError(
+			"PROCESS_FAILED",
+			"GET /rest/system/device-mode returned system resource data — REST API not fully initialized",
+		);
+	}
+
+	const normalized: Record<string, string> = {};
+	for (const [key, value] of Object.entries(record)) {
+		normalized[norm(key)] = toYesNo(value);
+	}
+	return normalized;
+}
+
+export function verifyDeviceMode(
+	options: ResolvedDeviceModeOptions,
+	actual: Record<string, string>,
+): DeviceModeVerification {
+	const expected: Record<string, string> = {};
+	if (options.mode) {
+		expected.mode = norm(options.mode);
+	}
+	for (const [name, value] of Object.entries(options.features)) {
+		expected[norm(name)] = value;
+	}
+
+	const mismatches: string[] = [];
+	for (const [key, expectedValue] of Object.entries(expected)) {
+		const actualValue = actual[key];
+		if (!actualValue) {
+			mismatches.push(`${key}: expected=${expectedValue}, actual=(missing)`);
+			continue;
+		}
+		const actualNorm = key === "mode" ? norm(actualValue) : toYesNo(actualValue);
+		if (actualNorm !== expectedValue) {
+			mismatches.push(`${key}: expected=${expectedValue}, actual=${actualNorm}`);
+		}
+	}
+
+	return {
+		ok: mismatches.length === 0,
+		mismatches,
+		expected,
+		actual,
+	};
+}

package/src/lib/disk.ts

@@ -0,0 +1,400 @@
+/**
+ * Disk management — qemu-img wrapper for boot disk resizing, extra disk creation,
+ * and qcow2 snapshot operations.
+ *
+ * All extra disks are qcow2.  Boot disk stays raw unless the user selects qcow2
+ * format (or requests resize, which implies qcow2).  qcow2 enables QEMU
+ * snapshot/restore via `savevm`/`loadvm` monitor commands.
+ *
+ * Snapshot operations:
+ *  - {@link parseSnapshotList} — parse QEMU monitor `info snapshots` text into {@link SnapshotInfo}[]
+ *  - {@link listSnapshots} — get structured snapshot data from a qcow2 image via `qemu-img info`
+ *  - {@link formatSnapshotTable} — render snapshot list as a human-readable ANSI table
+ */
+
+import { join } from "node:path";
+import { existsSync, unlinkSync } from "node:fs";
+import type { BootDiskFormat, SnapshotInfo } from "./types.ts";
+import { QuickCHRError } from "./types.ts";
+import { requireQemuImg } from "./platform.ts";
+
+const DISK_SIZE_RE = /^\d+[KMGT]?$/i;
+
+export interface DiskInfo {
+	format: string;
+	virtualSize: number;
+	actualSize: number;
+	filename: string;
+}
+
+/** True when a disk size string is valid for qemu-img (e.g. 512M, 1G, 2048). */
+export function isValidDiskSize(size: string): boolean {
+	return DISK_SIZE_RE.test(size.trim());
+}
+
+function normalizeDiskSize(size: string, label: string): string {
+	const normalized = size.trim().toUpperCase();
+	if (!isValidDiskSize(normalized)) {
+		throw new QuickCHRError(
+			"INVALID_DISK_SIZE",
+			`Invalid ${label}: ${JSON.stringify(size)}. Use values like 64M, 512M, 1G, or 2048.`,
+		);
+	}
+	return normalized;
+}
+
+/** Normalize and validate disk-related options.
+ *  If any disk feature is requested, also validates that qemu-img is present. */
+export function normalizeDiskOptions(
+	bootSize?: string,
+	extraDisks?: string[],
+ 	bootDiskFormat?: BootDiskFormat,
+): { bootSize?: string; extraDisks?: string[]; bootDiskFormat: BootDiskFormat } {
+ 	const format: BootDiskFormat = bootDiskFormat ?? (bootSize ? "qcow2" : "raw");
+
+	if (format === "raw" && bootSize) {
+		throw new QuickCHRError(
+			"INVALID_DISK_SIZE",
+			"Raw boot disks cannot be resized. Use bootDiskFormat=\"qcow2\" (or --boot-disk-format qcow2) to enable resizing.",
+		);
+	}
+
+	if (format === "raw" && !bootSize && (!extraDisks || extraDisks.length === 0)) {
+		return {
+			bootSize: bootSize?.trim() || undefined,
+			extraDisks,
+			bootDiskFormat: format,
+		};
+	}
+
+	requireQemuImg();
+
+	return {
+		bootSize: bootSize ? normalizeDiskSize(bootSize, "boot disk size") : undefined,
+		extraDisks: extraDisks && extraDisks.length > 0
+			? extraDisks.map((size, index) => normalizeDiskSize(size, `extra disk ${index + 1} size`))
+			: undefined,
+		bootDiskFormat: format,
+	};
+}
+
+/** Create a blank qcow2 disk image. */
+export async function createQcow2Disk(path: string, size: string): Promise<void> {
+	const qemuImg = requireQemuImg();
+	const proc = Bun.spawn([qemuImg, "create", "-f", "qcow2", path, size], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const exitCode = await proc.exited;
+	if (exitCode !== 0) {
+		const stderr = await new Response(proc.stderr).text();
+		throw new QuickCHRError("PROCESS_FAILED", `qemu-img create failed: ${stderr.trim()}`);
+	}
+}
+
+/** Convert a raw disk image to qcow2. */
+export async function convertRawToQcow2(rawPath: string, qcow2Path: string): Promise<void> {
+	const qemuImg = requireQemuImg();
+	const proc = Bun.spawn([qemuImg, "convert", "-f", "raw", "-O", "qcow2", rawPath, qcow2Path], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const exitCode = await proc.exited;
+	if (exitCode !== 0) {
+		const stderr = await new Response(proc.stderr).text();
+		throw new QuickCHRError("PROCESS_FAILED", `qemu-img convert failed: ${stderr.trim()}`);
+	}
+}
+
+/** Resize a qcow2 disk image. */
+export async function resizeQcow2(path: string, size: string): Promise<void> {
+	const qemuImg = requireQemuImg();
+	const proc = Bun.spawn([qemuImg, "resize", path, size], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const exitCode = await proc.exited;
+	if (exitCode !== 0) {
+		const stderr = await new Response(proc.stderr).text();
+		throw new QuickCHRError("PROCESS_FAILED", `qemu-img resize failed: ${stderr.trim()}`);
+	}
+}
+
+/** Get disk info via qemu-img info --output=json. */
+export async function getDiskInfo(path: string): Promise<DiskInfo> {
+	const qemuImg = requireQemuImg();
+	const proc = Bun.spawn([qemuImg, "info", "--output=json", path], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const exitCode = await proc.exited;
+	if (exitCode !== 0) {
+		const stderr = await new Response(proc.stderr).text();
+		throw new QuickCHRError("PROCESS_FAILED", `qemu-img info failed: ${stderr.trim()}`);
+	}
+	const stdout = await new Response(proc.stdout).text();
+	const info = JSON.parse(stdout);
+	return {
+		format: info.format,
+		virtualSize: info["virtual-size"],
+		actualSize: info["actual-size"],
+		filename: info.filename,
+	};
+}
+
+/**
+ * Prepare the boot disk for a machine.
+ * If bootSize is specified, converts the raw disk.img to boot.qcow2 and resizes it.
+ * Otherwise returns the raw disk.img as-is.
+ */
+export async function prepareBootDisk(
+	machineDir: string,
+	bootSize?: string,
+	bootDiskFormat?: BootDiskFormat,
+): Promise<{ path: string; format: BootDiskFormat }> {
+	const format: BootDiskFormat = bootDiskFormat ?? (bootSize ? "qcow2" : "raw");
+	const rawPath = join(machineDir, "disk.img");
+
+	if (format === "raw") {
+		return { path: rawPath, format: "raw" };
+	}
+
+	const qcow2Path = join(machineDir, "boot.qcow2");
+	if (!existsSync(qcow2Path)) {
+		await convertRawToQcow2(rawPath, qcow2Path);
+	}
+	if (bootSize) {
+		await resizeQcow2(qcow2Path, bootSize);
+	}
+	return { path: qcow2Path, format: "qcow2" };
+}
+
+/**
+ * Create extra blank qcow2 disks in the machine directory.
+ * Named disk1.qcow2, disk2.qcow2, etc.
+ */
+export async function prepareExtraDisks(
+	machineDir: string,
+	sizes: string[],
+): Promise<{ path: string; format: "qcow2" }[]> {
+	const results: { path: string; format: "qcow2" }[] = [];
+	for (let i = 0; i < sizes.length; i++) {
+		const diskPath = join(machineDir, `disk${i + 1}.qcow2`);
+		await createQcow2Disk(diskPath, sizes[i] as string);
+		results.push({ path: diskPath, format: "qcow2" });
+	}
+	return results;
+}
+
+/** Ensure disk artifacts referenced by machine state exist on disk.
+ *  Used both for new-machine creation and to heal older add()-created states
+ *  that predate eager disk materialization. */
+export async function ensureConfiguredDisks(
+	machineDir: string,
+	bootSize?: string,
+	extraDiskSizes?: string[],
+	bootDiskFormat?: BootDiskFormat,
+): Promise<{
+	bootDisk: { path: string; format: BootDiskFormat };
+	extraDisks?: { path: string; format: "qcow2" }[];
+}> {
+	const format: BootDiskFormat = bootDiskFormat ?? (bootSize ? "qcow2" : "raw");
+	const bootDisk = format === "raw"
+		? { path: join(machineDir, "disk.img"), format: "raw" as const }
+		: (existsSync(join(machineDir, "boot.qcow2"))
+			? { path: join(machineDir, "boot.qcow2"), format: "qcow2" as const }
+			: await prepareBootDisk(machineDir, bootSize, "qcow2"));
+
+	let extraDisks: { path: string; format: "qcow2" }[] | undefined;
+	if (extraDiskSizes && extraDiskSizes.length > 0) {
+		extraDisks = [];
+		for (let i = 0; i < extraDiskSizes.length; i++) {
+			const diskPath = join(machineDir, `disk${i + 1}.qcow2`);
+			if (!existsSync(diskPath)) {
+				await createQcow2Disk(diskPath, extraDiskSizes[i] as string);
+			}
+			extraDisks.push({ path: diskPath, format: "qcow2" });
+		}
+	}
+
+	return { bootDisk, extraDisks };
+}
+
+/**
+ * Remove extra disk files from a machine directory.
+ * Cleans up disk1.qcow2, disk2.qcow2, etc. and boot.qcow2 if present.
+ */
+export function cleanDiskFiles(machineDir: string): void {
+	// Remove boot.qcow2
+	const bootQcow2 = join(machineDir, "boot.qcow2");
+	if (existsSync(bootQcow2)) {
+		try { unlinkSync(bootQcow2); } catch { /* ignore */ }
+	}
+	// Remove extra disks (disk1.qcow2, disk2.qcow2, ...)
+	for (let i = 1; i <= 64; i++) {
+		const diskPath = join(machineDir, `disk${i}.qcow2`);
+		if (!existsSync(diskPath)) break;
+		try { unlinkSync(diskPath); } catch { /* ignore */ }
+	}
+}
+
+// --- Snapshot operations ---
+
+/**
+ * Parse QEMU monitor `info snapshots` text output into structured data.
+ *
+ * The monitor returns lines like:
+ * ```
+ * ID        TAG               VM SIZE                DATE        VM CLOCK     ICOUNT
+ * --        test              113 MiB 2026-04-14 00:47:19  0000:01:17.163         --
+ * ```
+ *
+ * @param monitorOutput - Raw text from `instance.monitor("info snapshots")`
+ * @returns Parsed snapshot list (empty array if no snapshots exist)
+ */
+export function parseSnapshotList(monitorOutput: string): SnapshotInfo[] {
+	const lines = monitorOutput.split("\n");
+	const snapshots: SnapshotInfo[] = [];
+
+	for (const line of lines) {
+		// Match snapshot data lines: ID, TAG, VM SIZE, DATE (YYYY-MM-DD HH:MM:SS), VM CLOCK, ICOUNT
+		// Example: "--      test              113 MiB 2026-04-14 00:47:19  0000:01:17.163         --"
+		// Example: "1       snap1             113 MiB 2026-04-14 00:47:19  0000:01:17.163         --"
+		const match = line.match(
+			/^\s*(\S+)\s+(\S+)\s+(\d+(?:\.\d+)?\s*(?:[KMGT]i?B|bytes?))\s+(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2})\s+(\d{4}:\d{2}:\d{2}\.\d+)\s+(\S+)/i,
+		);
+		if (!match) continue;
+
+		const [, id, name, vmSizeStr, dateStr, vmClock, icountStr] = match;
+		if (!id || !name || !vmSizeStr || !dateStr || !vmClock) continue;
+
+		snapshots.push({
+			id: id === "--" ? "0" : id,
+			name: name,
+			vmStateSize: parseVmSize(vmSizeStr),
+			date: dateStr.replace(" ", "T") + "Z",
+			vmClock: vmClock,
+			icount: icountStr === "--" ? undefined : Number(icountStr),
+		});
+	}
+
+	return snapshots;
+}
+
+/** Parse a human-readable VM size string ("113 MiB", "2.1 GiB") to bytes. */
+function parseVmSize(sizeStr: string): number {
+	const match = sizeStr.match(/^([\d.]+)\s*([KMGT]i?B|bytes?)?$/i);
+	if (!match) return 0;
+	const value = Number.parseFloat(match[1] ?? "0");
+	const unit = (match[2] ?? "").toLowerCase();
+	const multipliers: Record<string, number> = {
+		"": 1, "b": 1, "byte": 1, "bytes": 1,
+		"kib": 1024, "kb": 1000,
+		"mib": 1024 * 1024, "mb": 1000 * 1000,
+		"gib": 1024 ** 3, "gb": 1000 ** 3,
+		"tib": 1024 ** 4, "tb": 1000 ** 4,
+	};
+	return Math.round(value * (multipliers[unit] ?? 1));
+}
+
+/**
+ * List snapshots stored in a qcow2 disk image using `qemu-img info`.
+ *
+ * Works on both running and stopped machines (reads the qcow2 metadata directly).
+ * Returns an empty array for raw disks or images with no snapshots.
+ *
+ * @param diskPath - Path to the qcow2 disk image file
+ * @returns Structured snapshot list with size information
+ */
+export async function listSnapshots(diskPath: string): Promise<SnapshotInfo[]> {
+	const qemuImg = requireQemuImg();
+	const proc = Bun.spawn([qemuImg, "info", "--output=json", "-U", diskPath], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const exitCode = await proc.exited;
+	if (exitCode !== 0) {
+		return [];
+	}
+	const stdout = await new Response(proc.stdout).text();
+	try {
+		const info = JSON.parse(stdout) as {
+			snapshots?: Array<{
+				id: string;
+				name: string;
+				"vm-state-size": number;
+				"date-sec": number;
+				"date-nsec": number;
+				"vm-clock-sec": number;
+				"vm-clock-nsec": number;
+				"icount"?: number;
+			}>;
+		};
+		if (!info.snapshots || info.snapshots.length === 0) return [];
+
+		return info.snapshots.map((s) => {
+			const date = new Date(s["date-sec"] * 1000);
+			const clockSec = s["vm-clock-sec"];
+			const hours = Math.floor(clockSec / 3600);
+			const mins = Math.floor((clockSec % 3600) / 60);
+			const secs = clockSec % 60;
+			const ms = Math.floor(s["vm-clock-nsec"] / 1_000_000);
+
+			return {
+				id: s.id,
+				name: s.name,
+				vmStateSize: s["vm-state-size"],
+				date: date.toISOString(),
+				vmClock: `${String(hours).padStart(4, "0")}:${String(mins).padStart(2, "0")}:${String(secs).padStart(2, "0")}.${String(ms).padStart(3, "0")}`,
+				icount: s.icount,
+			};
+		});
+	} catch {
+		return [];
+	}
+}
+
+/** Format bytes as a compact human-readable size (e.g. "113 MiB", "2.1 GiB"). */
+export function formatDiskSize(bytes: number): string {
+	if (bytes >= 1024 ** 3) return `${(bytes / 1024 ** 3).toFixed(1)} GiB`;
+	if (bytes >= 1024 ** 2) return `${(bytes / (1024 * 1024)).toFixed(0)} MiB`;
+	if (bytes >= 1024) return `${(bytes / 1024).toFixed(0)} KiB`;
+	return `${bytes} B`;
+}
+
+/**
+ * Format a snapshot list as a human-readable table string.
+ *
+ * Produces a compact table suitable for terminal display:
+ * ```
+ *   #  NAME           SIZE      DATE                 VM CLOCK
+ *   1  baseline       113 MiB   2026-04-14 00:47     0001:17:00
+ *   2  after-config   118 MiB   2026-04-14 01:02     0001:32:15
+ * ```
+ *
+ * @param snapshots - Parsed snapshot list from {@link parseSnapshotList} or {@link listSnapshots}
+ * @returns Formatted table string (no trailing newline), or "No snapshots." if empty
+ */
+export function formatSnapshotTable(snapshots: SnapshotInfo[]): string {
+	if (snapshots.length === 0) return "No snapshots.";
+
+	const headers = ["#", "NAME", "SIZE", "DATE", "VM CLOCK"];
+	const rows = snapshots.map((s) => [
+		s.id,
+		s.name,
+		formatDiskSize(s.vmStateSize),
+		s.date.replace("T", " ").replace(/:\d{2}(?:\.\d+)?Z$/, "").replace("Z", ""),
+		s.vmClock,
+	]);
+
+	const widths = headers.map((h, i) =>
+		Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)),
+	);
+
+	const headerLine = headers.map((h, i) => h.padEnd(widths[i] ?? 0)).join("  ");
+	const dataLines = rows.map((row) =>
+		row.map((cell, i) => cell.padEnd(widths[i] ?? 0)).join("  "),
+	);
+
+	return [headerLine, ...dataLines].join("\n");
+}