@tikoci/quickchr 0.5.0 → 0.5.2

package/src/cli/flags.ts

@@ -25,7 +25,7 @@ const CREATE_FLAGS = [
 /** `start` also boots, so it owns the run-time flags on top of the create set. */
 const START_ONLY_FLAGS = [
 	"all", "dry-run", "wait", "background", "bg", "fg", "foreground",
-	"install-deps", "timeout-extra",
+	"timeout-extra",
 	"license-level", "license-account", "license-password",
 ] as const;
 
@@ -96,10 +96,15 @@ export const VALUE_FLAGS: ReadonlySet<string> = new Set([
  *  that `--add-network` already expresses in general (#164). Removing them silently would
  *  repeat the defect they were removed for: a flag that is accepted and does nothing. A
  *  removed name stays known for as long as anyone might still type it, and says what
- *  replaced it. */
+ *  replaced it.
+ *
+ *  `--install-deps` is the same defect from the other side: `start` accepted it from
+ *  the beginning and nothing ever read it (#193). It never installed anything, so the
+ *  replacement is the command that names what to install. */
 export const REMOVED_FLAGS: ReadonlyMap<string, string> = new Map([
 	["vmnet-shared", "--add-network shared"],
 	["vmnet-bridge", "--add-network bridged:<iface>"],
+	["install-deps", "quickchr doctor (it never installed anything; doctor lists missing host dependencies and how to install them)"],
 ]);
 
 /** Value-taking flags with a documented `--no-` spelling, where `false` is a real

package/src/cli/index.ts

@@ -1390,7 +1390,13 @@ function printReadinessTip(name: string, version: string): void {
 	tip(`wait for readiness with: centrs retrieve --quickchr ${name} /system/resource${via} --wait 5m`);
 }
 
-async function cmdStart(argv: string[]) {
+/** Single-target start's status word: a machine this call created says so (#194). */
+function startStatusLine(created: boolean, noWait: boolean): string {
+	if (noWait) return `${created ? "created" : "launched"} — not waiting for RouterOS (--no-wait)`;
+	return created ? "created and started" : "started";
+}
+
+export async function cmdStart(argv: string[]) {
 	const { flags, positional } = parseFlags(argv);
 	applyTimeoutExtraShortFlag(argv, flags, positional);
 	rejectUnknownFlags(flags, START_FLAGS, "start");
@@ -1474,7 +1480,6 @@ async function cmdStart(argv: string[]) {
 		bootSize: flag(flags, "boot-size"),
 		extraDisks: flagList(flags, "add-disk").length > 0 ? flagList(flags, "add-disk") : undefined,
 		extraPorts: flagList(flags, "forward").flatMap(expandForwardSpec),
-		installDeps: flagBool(flags, "install-deps"),
 		dryRun: flagBool(flags, "dry-run"),
 		timeoutExtra: await resolveTimeoutExtraMs(flags),
 	};
@@ -1505,10 +1510,10 @@ async function cmdStart(argv: string[]) {
 	}
 
 	opts.disableAdmin = flagOptionalBool(flags, "disable-admin");
+	// No name, or a name no machine has: this call creates the machine (#194).
+	const target = opts.name ? QuickCHR.get(opts.name) : null;
 	{
-		const { QuickCHR } = await import("../lib/quickchr.ts");
 		const { isProvisioningWindowOpen } = await import("../lib/provisioning-window.ts");
-		const target = opts.name ? QuickCHR.get(opts.name) : null;
 		// No machine yet, or one that was added and never booted: still a first boot,
 		// so the setting applies. Only a closed window suppresses it — otherwise a
 		// plain `quickchr start <booted-name>` would ask to provision a booted guest
@@ -1573,7 +1578,7 @@ async function cmdStart(argv: string[]) {
 	} else {
 		const creds = await resolveDisplayCredentials(instance.state);
 		const v6 = isRouterOs6(instance.state.version);
-		console.log(`${statusIcon("running")} ${bold(instance.name)} ${opts.wait === false ? "launched — not waiting for RouterOS (--no-wait)" : "started"}`);
+		console.log(`${statusIcon("running")} ${bold(instance.name)} ${startStatusLine(!target, opts.wait === false)}`);
 		console.log(`  Version: ${instance.state.version} (${instance.state.arch})${v6 ? `  ${dim("boot-only: no REST, no provisioning")}` : ""}`);
 		console.log(`  Network: ${formatNetworks(instance.state.networks ?? [])}`);
 		console.log(`  Ports:   ${formatPorts(instance.state.ports)}`);
@@ -2236,7 +2241,7 @@ async function cmdDisk(argv: string[]) {
 
 	const { QuickCHR } = await import("../lib/quickchr.ts");
 	const { bold, dim, machineNotFoundMessage } = await import("./format.ts");
-	const { getDiskInfo } = await import("../lib/disk.ts");
+	const { bootDiskFormatOf, bootDiskPath, getDiskInfo } = await import("../lib/disk.ts");
 	const { join } = await import("node:path");
 	const { existsSync } = await import("node:fs");
 	const { findQemuImg } = await import("../lib/platform.ts");
@@ -2259,10 +2264,8 @@ async function cmdDisk(argv: string[]) {
 	console.log(bold(`Disks for ${name}\n`));
 
 	// Boot disk
-	const bootPath = state.bootDiskFormat === "qcow2"
-		? join(state.machineDir, "boot.qcow2")
-		: join(state.machineDir, "disk.img");
-	const bootFormat = state.bootDiskFormat ?? "raw";
+	const bootFormat = bootDiskFormatOf(state);
+	const bootPath = bootDiskPath(state.machineDir, bootFormat);
 
 	if (qemuImg && existsSync(bootPath)) {
 		try {
@@ -2835,7 +2838,7 @@ async function cmdCache(argv: string[]) {
 		return;
 	}
 
-	const { listCacheEntries, pruneCache, parseSizeString, formatSizeBytes } = await import("../lib/cache.ts");
+	const { cacheInventory, countEntries, pruneCache, parseSizeString, formatSizeBytes } = await import("../lib/cache.ts");
 
 	const parseDuration = (s: string): number => {
 		const m = s.match(/^(\d+(?:\.\d+)?)([smhdw])$/);
@@ -2847,6 +2850,11 @@ async function cmdCache(argv: string[]) {
 	};
 	const parseSize = parseSizeString;
 	const formatSize = formatSizeBytes;
+	const printFailedDeletes = (failed: Array<{ entry: { basename: string }; error: string }>) => {
+		if (failed.length === 0) return;
+		console.error(`Could not delete ${countEntries(failed.length)} (kept, not counted as freed):`);
+		for (const { entry, error } of failed) console.error(`  - ${entry.basename}: ${error}`);
+	};
 	const formatAge = (ms: number): string => {
 		const s = Math.floor(ms / 1000);
 		if (s < 60) return `${s}s`;
@@ -2897,13 +2905,14 @@ async function cmdCache(argv: string[]) {
 		}
 		case "list":
 		case "ls": {
-			const entries = listCacheEntries();
+			const { entries, unmanagedBytes } = cacheInventory();
 			if (flags.json === true) {
 				console.log(JSON.stringify(entries, null, 2));
 				return;
 			}
 			if (entries.length === 0) {
-				console.log("No cached images.");
+				console.log("No cache entries.");
+				if (unmanagedBytes > 0) console.log(`Other files: ${formatSize(unmanagedBytes)} (not written by quickchr; never pruned)`);
 				return;
 			}
 			const now = Date.now();
@@ -2930,7 +2939,8 @@ async function cmdCache(argv: string[]) {
 				);
 			}
 			const total = entries.reduce((s, e) => s + e.sizeBytes, 0);
-			console.log(`\nTotal: ${entries.length} image(s), ${formatSize(total)}`);
+			console.log(`\nTotal: ${countEntries(entries.length)}, ${formatSize(total)}`);
+			if (unmanagedBytes > 0) console.log(`Other files: ${formatSize(unmanagedBytes)} (not written by quickchr; never pruned)`);
 			break;
 		}
 		case "prune": {
@@ -2944,29 +2954,33 @@ async function cmdCache(argv: string[]) {
 			}
 			const result = pruneCache(opts);
 			const verb = opts.dryRun ? "Would evict" : "Evicted";
-			if (result.evicted.length === 0) {
+			if (result.evicted.length === 0 && result.failed.length === 0) {
 				console.log("Nothing to evict.");
-			} else {
-				console.log(`${verb} ${result.evicted.length} image(s):`);
+			} else if (result.evicted.length > 0) {
+				console.log(`${verb} ${countEntries(result.evicted.length)}:`);
 				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)}`);
+				console.log(`${opts.dryRun ? "Would free" : "Freed"}: ${formatSize(result.freedBytes)}`);
 			}
+			printFailedDeletes(result.failed);
+			if (result.failed.length > 0) process.exitCode = 1;
 			break;
 		}
 		case "clear": {
 			if (flags.all !== true) {
-				console.error("cache clear: refuses without --all (deletes all non-in-use cached images)");
+				console.error("cache clear: refuses without --all (deletes all non-in-use cache entries)");
 				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)}`);
+			console.log(`${verb} ${countEntries(result.evicted.length)}, ${flags["dry-run"] === true ? "would free" : "freed"} ${formatSize(result.freedBytes)}`);
+			printFailedDeletes(result.failed);
+			if (result.failed.length > 0) process.exitCode = 1;
 			if (result.kept.some((e) => e.inUse)) {
 				const inUse = result.kept.filter((e) => e.inUse);
-				console.log(`Kept ${inUse.length} in-use image(s):`);
+				console.log(`Kept ${inUse.length} in-use cache ${inUse.length === 1 ? "entry" : "entries"}:`);
 				for (const e of inUse) console.log(`  - ${e.basename}`);
 			}
 			break;
@@ -2992,7 +3006,7 @@ async function cmdSettings(argv: string[]) {
 
 	const displayValue = (key: string, value: unknown): string => {
 		if (value === undefined) return "(unset)";
-		if (key === "cache-max-size" && typeof value === "number") return formatSizeBytes(value);
+		if ((key === "cache-max-size" || key === "storage-reserve") && typeof value === "number") return formatSizeBytes(value);
 		if (key === "timeout-extra" && typeof value === "number") return `${value}s`;
 		return String(value);
 	};
@@ -3079,7 +3093,7 @@ async function cmdDoctor(argv: string[] = []) {
 	const staleImages = await findStaleCacheImages();
 	if (staleImages.length > 0) {
 		const longTerm = staleImages[0]?.olderThan;
-		console.log(`Note: ${staleImages.length} cached image(s) older than current long-term (${longTerm}):`);
+		console.log(`Note: ${staleImages.length} cache item(s) older than current long-term (${longTerm}):`);
 		for (const e of staleImages) console.log(`  - ${e.basename} (${e.version})`);
 		console.log("  Hint: 'quickchr cache prune --older-than " + longTerm + "' to evict them.");
 		console.log();
@@ -3174,6 +3188,7 @@ Commands:
   console <name>          Attach to serial console of a running instance
   exec <name> <command>   Run a RouterOS CLI command on a running instance
                           (raw /rest/execute — see 'quickchr exec --help' for centrs)
+  qga <name> <operation>  Query the QEMU Guest Agent (x86 only)
   remove [<name>|--all]   Remove instance(s) and disk
   clean [<name>|--all]    Reset instance disk to fresh image
   get <name> [group]      Show machine config (license, device-mode, admin)
@@ -3182,7 +3197,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 [add|key|list|prune|clear] Manage cached CHR images
+  cache [add|key|list|prune|clear] Manage cached CHR images and packages
   settings [print|get|set|reset]  Manage quickchr's own global settings (quickchr.env)
   completions             Manage shell completions (Tab completion)
   logs <name>             Tail the QEMU log for an instance
@@ -3218,7 +3233,7 @@ options still work on older versions when the required host tools are installed.
 ${ROUTEROS6_HELP}
 
 Options:
-  --name <name>         Instance name (required)
+  --name <name>         Instance name (auto-generated if omitted)
   --version <ver>       RouterOS version (e.g., 7.22.1)
   --channel <ch>        Channel: stable, long-term, testing, development
   --arch <arch>         Architecture: arm64, x86, auto (default: host native)
@@ -3242,6 +3257,7 @@ Options:
   --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
+  --secure-login        Create a managed login; use --disable-admin to disable admin
   --no-secure-login     Keep admin with no password (skip managed account)
   --port-base <port>    Starting port number (default: auto-allocated from 9100)
   --no-winbox           Exclude WinBox port mapping
@@ -3292,12 +3308,19 @@ Examples:
   quickchr exec my-chr ":put [:serialize to=json [/ip/address/print]]"
   quickchr exec my-chr "/log/info message=hello"
 
+Exit status:
+  0 means the command was delivered, not that RouterOS accepted it. A rejected
+  command (e.g. "failure: invalid user name") still exits 0, with
+  RouterOS's message as the output. For a pass/fail exit code, use centrs
+  (a write command needs --yes when not run at a TTY):
+    centrs execute --quickchr <name> --yes <command>
+
 ${CENTRS_SEE_ALSO}`);
 			break;
 		case "start":
 			console.log(`quickchr start [<name>] [options]
 
-  <name>              Restart an existing stopped machine by name.
+  <name>              Restart a stopped machine; an unknown name creates a fresh machine.
                       Omit to see a list of stopped machines.
 
 Creation flags below apply when using 'start' to create a new machine in one step.
@@ -3345,6 +3368,7 @@ Options:
                         btest:9200-9210:2000-2010/udp.
   --add-user <u:p>      Create user with name:password
   --disable-admin       Disable the default admin account
+  --secure-login        Create a managed login; use --disable-admin to disable admin
   --no-secure-login     Keep admin with no password (skip managed account)
   --port-base <port>    Starting port number (default: auto-allocated from 9100)
   --no-winbox           Exclude WinBox port mapping
@@ -3606,7 +3630,9 @@ Options:
 		case "cache":
 			console.log(`quickchr cache <add|key|list|prune|clear> [options]
 
-Manage cached CHR images in the data dir cache directory.
+Manage cached CHR images and package archives in the data dir cache directory.
+An all-packages archive and its extraction are one entry; an interrupted download
+is a partial entry. Files quickchr did not write are reported, never deleted.
 
 Subcommands:
   add [--channel <ch> | --version <ver>] [--arch <arch>] [--json]
@@ -3614,14 +3640,16 @@ Subcommands:
   key [--channel <ch> | --version <ver>] [--arch <arch>] [--json]
                                       Print cache directory, resolved version, and architecture for CI.
                                       Without --json, output is GITHUB_OUTPUT-compatible key=value lines.
-  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>.
+  list [--json]                       List cache entries (basename, version, arch, size, age, in-use).
+  prune [options]                     Evict cache entries per policy. Never evicts in-use entries.
+    --older-than <ver>                Evict entries with version < <ver>.
+    --max-age <dur>                   Evict entries not used for longer than duration (e.g. 7d, 24h).
+    --max-size <size>                 Evict entries until total size <= <size>: partial downloads
+                                      first, then oldest RouterOS version.
     --dry-run                         Show what would be evicted without deleting.
-  clear --all                         Delete all non-in-use cached images.
+  clear --all                         Delete all non-in-use cache entries.
 
+A failed delete is listed on stderr, is not counted as freed, and exits 1.
 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 — override via 'quickchr settings set cache-max-size <size>'
@@ -3641,6 +3669,8 @@ Managed keys:
                     auto|tcg|hvf|kvm (default: auto = detect)
   cache-max-size    Auto-prune cap applied after each successful start.
                     Size string (e.g. 2G, 512M). (default: 2G)
+  storage-reserve   Free space creating a machine or filling the cache must
+                    leave, beyond what it writes. Size string. (default: 2G)
   timeout-extra     Default for 'start's --timeout-extra/-T when omitted.
                     Non-negative integer seconds. (default: 0)
   secure-login      Default for 'add'/'start's --secure-login when neither

package/src/cli/wizard.ts

@@ -37,6 +37,9 @@ export function resolveUserChoiceOptions(
 
 /** Run the interactive wizard using @clack/prompts. */
 export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<void> {
+	const { requireQemuImg } = await import("../lib/platform.ts");
+	requireQemuImg();
+
 	// Dynamic import — only loaded when wizard is actually used
 	const clack = await import("@clack/prompts");
 	const { QuickCHR } = await import("../lib/quickchr.ts");
@@ -148,75 +151,68 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 	});
 	if (clack.isCancel(mem)) { clack.cancel("Cancelled."); process.exit(0); }
 
-	// 4b. Disk configuration — requires qemu-img; skip gracefully if absent
+	// 4b. Disk configuration — qemu-img was checked before any prompts
 	let bootSize: string | undefined;
 	let bootDiskFormat: "qcow2" | "raw" = "qcow2";
 	const extraDisks: string[] = [];
 
-	const { findQemuImg, getQemuInstallHint } = await import("../lib/platform.ts");
 	const { isValidDiskSize } = await import("../lib/disk.ts");
-	const qemuImg = findQemuImg();
+	const diskFormatChoice = await clack.select({
+		message: "Boot disk format:",
+		options: [
+			{ value: "qcow2", label: "qcow2 (recommended)", hint: "supports snapshots and resize" },
+			{ value: "raw", label: "raw", hint: "no resize support" },
+		],
+		initialValue: "qcow2",
+	});
+	if (clack.isCancel(diskFormatChoice)) { clack.cancel("Cancelled."); process.exit(0); }
+	bootDiskFormat = diskFormatChoice as "qcow2" | "raw";
 
-	if (!qemuImg) {
-		clack.log.warn(`Disk features (boot resize, extra disks) require qemu-img. Run 'quickchr doctor' to confirm setup. ${getQemuInstallHint()}`);
-	} else {
-		const diskFormatChoice = await clack.select({
-			message: "Boot disk format:",
-			options: [
-				{ value: "qcow2", label: "qcow2 (recommended)", hint: "supports snapshots and resize" },
-				{ value: "raw", label: "raw", hint: "no resize support" },
-			],
-			initialValue: "qcow2",
+	if (bootDiskFormat === "qcow2") {
+		const wantBootResize = await clack.confirm({
+			message: "Resize the boot disk? (default is ~128 MB)",
+			initialValue: false,
 		});
-		if (clack.isCancel(diskFormatChoice)) { clack.cancel("Cancelled."); process.exit(0); }
-		bootDiskFormat = diskFormatChoice as "qcow2" | "raw";
-
-		if (bootDiskFormat === "qcow2") {
-			const wantBootResize = await clack.confirm({
-				message: "Resize the boot disk? (default is ~128 MB)",
-				initialValue: false,
+		if (clack.isCancel(wantBootResize)) { clack.cancel("Cancelled."); process.exit(0); }
+
+		if (wantBootResize) {
+			const size = await clack.text({
+				message: "Boot disk size (e.g., 512M, 1G, 2G):",
+				validate: (v) => {
+					if (!isValidDiskSize(v)) return "Size like 512M, 1G, or 2048";
+				},
 			});
-			if (clack.isCancel(wantBootResize)) { clack.cancel("Cancelled."); process.exit(0); }
-
-			if (wantBootResize) {
-				const size = await clack.text({
-					message: "Boot disk size (e.g., 512M, 1G, 2G):",
-					validate: (v) => {
-						if (!isValidDiskSize(v)) return "Size like 512M, 1G, or 2048";
-					},
-				});
-				if (clack.isCancel(size)) { clack.cancel("Cancelled."); process.exit(0); }
-				bootSize = size.trim();
-			}
-		} else {
-			clack.log.info("Raw boot disk selected — boot resize is disabled.");
+			if (clack.isCancel(size)) { clack.cancel("Cancelled."); process.exit(0); }
+			bootSize = size.trim();
 		}
+	} else {
+		clack.log.info("Raw boot disk selected — boot resize is disabled.");
+	}
 
-		const wantExtraDisks = await clack.confirm({
-			message: "Add extra blank disks?",
-			initialValue: false,
-		});
-		if (clack.isCancel(wantExtraDisks)) { clack.cancel("Cancelled."); process.exit(0); }
-
-		if (wantExtraDisks) {
-			let addMore = true;
-			while (addMore) {
-				const diskSize = await clack.text({
-					message: `Extra disk ${extraDisks.length + 1} size (e.g., 64M, 512M, 1G):`,
-					validate: (v) => {
-						if (!isValidDiskSize(v)) return "Size like 64M, 512M, or 1G";
-					},
-				});
-				if (clack.isCancel(diskSize)) { clack.cancel("Cancelled."); process.exit(0); }
-				extraDisks.push(diskSize.trim());
+	const wantExtraDisks = await clack.confirm({
+		message: "Add extra blank disks?",
+		initialValue: false,
+	});
+	if (clack.isCancel(wantExtraDisks)) { clack.cancel("Cancelled."); process.exit(0); }
+
+	if (wantExtraDisks) {
+		let addMore = true;
+		while (addMore) {
+			const diskSize = await clack.text({
+				message: `Extra disk ${extraDisks.length + 1} size (e.g., 64M, 512M, 1G):`,
+				validate: (v) => {
+					if (!isValidDiskSize(v)) return "Size like 64M, 512M, or 1G";
+				},
+			});
+			if (clack.isCancel(diskSize)) { clack.cancel("Cancelled."); process.exit(0); }
+			extraDisks.push(diskSize.trim());
 
-				const another = await clack.confirm({
-					message: "Add another disk?",
-					initialValue: false,
-				});
-				if (clack.isCancel(another)) { clack.cancel("Cancelled."); process.exit(0); }
-				addMore = another;
-			}
+			const another = await clack.confirm({
+				message: "Add another disk?",
+				initialValue: false,
+			});
+			if (clack.isCancel(another)) { clack.cancel("Cancelled."); process.exit(0); }
+			addMore = another;
 		}
 	}