@tikoci/quickchr 0.4.2 → 0.4.4

package/src/cli/wizard.ts

@@ -5,12 +5,43 @@
 import type { Arch, Channel, DeviceModeOptions, LicenseLevel, LicenseOptions, NetworkSpecifier, StartOptions } from "../lib/types.ts";
 import { CHANNELS, ARCHES, knownPackagesForArch } from "../lib/types.ts";
 
+export type WizardUserChoice = "custom" | "managed" | "admin";
+
+export interface WizardUserChoiceResult {
+	user?: { name: string; password: string };
+	disableAdmin: boolean;
+	secureLogin?: boolean;
+}
+
+/**
+ * Maps the wizard's "CHR login setup" choice to StartOptions fields. Pulled out as a
+ * pure function (rather than inlined in runWizard) so it's unit-testable without
+ * mocking the entire @clack/prompts prompt sequence — "managed" must set both
+ * disableAdmin AND secureLogin, since provision() only auto-creates the replacement
+ * quickchr account when secureLogin === true (src/lib/provision.ts); disableAdmin
+ * alone would disable the default account with no replacement login provisioned.
+ */
+export function resolveUserChoiceOptions(
+	userChoice: WizardUserChoice,
+	customUser?: { name: string; password: string },
+): WizardUserChoiceResult {
+	if (userChoice === "custom") {
+		return { user: customUser, disableAdmin: true };
+	}
+	if (userChoice === "managed") {
+		return { disableAdmin: true, secureLogin: true };
+	}
+	// "admin" — keep admin with no password
+	return { disableAdmin: false, secureLogin: false };
+}
+
 /** Run the interactive wizard using @clack/prompts. */
 export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<void> {
 	// Dynamic import — only loaded when wizard is actually used
 	const clack = await import("@clack/prompts");
 	const { QuickCHR } = await import("../lib/quickchr.ts");
 	const { formatPorts, bold } = await import("./format.ts");
+	const { resolveSetting } = await import("../lib/settings.ts");
 
 	clack.intro("quickchr — MikroTik CHR Manager");
 	if (wizardOpts?.firstRun) {
@@ -31,6 +62,7 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 	let channel: Channel | undefined;
 
 	if (versionSource === "channel") {
+		const defaultChannel = resolveSetting("default-channel").value as Channel;
 		const ch = await clack.select({
 			message: "Select channel:",
 			options: CHANNELS.map((c) => ({
@@ -38,7 +70,7 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 				label: c,
 				hint: c === "long-term" ? "recommended for provisioning" : undefined,
 			})),
-			initialValue: "long-term" as Channel,
+			initialValue: defaultChannel,
 		});
 		if (clack.isCancel(ch)) { clack.cancel("Cancelled."); process.exit(0); }
 		channel = ch;
@@ -57,6 +89,8 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 
 	// 2. Architecture
 	const hostArch = process.arch === "arm64" ? "arm64" : "x86";
+	const settingArch = resolveSetting("default-arch").value as Arch | "auto";
+	const archInitial: Arch = settingArch === "auto" ? hostArch : settingArch;
 	const arch = await clack.select({
 		message: "Architecture:",
 		options: ARCHES.map((a) => ({
@@ -64,7 +98,7 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 			label: a,
 			hint: a === hostArch ? "host native" : "emulated (slower)",
 		})),
-		initialValue: hostArch as Arch,
+		initialValue: archInitial,
 	});
 	if (clack.isCancel(arch)) { clack.cancel("Cancelled."); process.exit(0); }
 
@@ -304,7 +338,7 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 	} = await import("../lib/versions.ts");
 	let resolvedVersion = version ?? await resolveVersion(channel ?? "long-term");
 	version = resolvedVersion;
-	let provisioningSupported = isProvisioningSupportedVersion(resolvedVersion);
+	const provisioningSupported = isProvisioningSupportedVersion(resolvedVersion);
 
 	let installAllPackages = false;
 	let packages: string[] = [];
@@ -346,7 +380,6 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 			channel = "long-term";
 			resolvedVersion = await resolveVersion(channel);
 			version = resolvedVersion;
-			provisioningSupported = true;
 			wantProvision = await askProvisionChoice();
 		}
 	}
@@ -428,6 +461,7 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 		}
 
 		// 6c. User setup
+		const secureLoginSetting = resolveSetting("secure-login").value;
 		const userChoice = await clack.select({
 			message: "CHR login setup:",
 			options: [
@@ -435,10 +469,11 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 				{ value: "custom", label: "Custom user", hint: "you provide username + password" },
 				{ value: "admin", label: "Keep admin with no password", hint: "less secure" },
 			],
-			initialValue: "managed",
+			initialValue: secureLoginSetting === false ? "admin" : "managed",
 		});
 		if (clack.isCancel(userChoice)) { clack.cancel("Cancelled."); process.exit(0); }
 
+		let customUser: { name: string; password: string } | undefined;
 		if (userChoice === "custom") {
 			const userName = await clack.text({
 				message: "Username:",
@@ -449,14 +484,9 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 			const userPass = await clack.password({ message: "Password:" });
 			if (clack.isCancel(userPass)) { clack.cancel("Cancelled."); process.exit(0); }
 
-			user = { name: userName, password: userPass };
-			disableAdmin = true;
-		} else if (userChoice === "managed") {
-			disableAdmin = true;
-		} else {
-			// "admin" — keep admin with no password
-			secureLogin = false;
+			customUser = { name: userName, password: userPass };
 		}
+		({ user, disableAdmin, secureLogin } = resolveUserChoiceOptions(userChoice as WizardUserChoice, customUser));
 
 		// 6d. License
 		const wantLicense = await clack.confirm({

package/src/index.ts

@@ -32,6 +32,8 @@ export type {
 	Channel,
 	ChrInstance,
 	ChrPorts,
+	CustomForward,
+	Descriptor,
 	DeviceModeOptions,
 	DoctorCheck,
 	DoctorResult,
@@ -44,11 +46,11 @@ export type {
 	LicenseLevel,
 	LicenseOptions,
 	MachineConfig,
-	MachineDescriptor,
 	MachineState,
 	NetworkConfig,
 	NetworkMode,
 	NetworkSpecifier,
+	NetworkTopologyEntry,
 	PackageManager,
 	PlatformInfo,
 	PortMapping,
@@ -59,12 +61,14 @@ export type {
 	QgaNetworkIpAddress,
 	QgaOsInfo,
 	QgaTimezone,
+	ServiceEndpoint,
 	ServiceName,
 	SnapshotInfo,
+	SshServiceEndpoint,
 	StartOptions,
 } from "./lib/types.ts";
 
-export { QuickCHRError } from "./lib/types.ts";
+export { QuickCHRError, SERVICE_IDS, QUICKCHR_DESCRIPTOR_VERSION } from "./lib/types.ts";
 export type { ErrorCode, HostInterface } from "./lib/types.ts";
 
 // Interface detection
@@ -125,7 +129,7 @@ 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";
+export { parseForwardSpec, expandForwardSpec, FORWARD_RANGE_MAX } from "./lib/forward-spec.ts";
 
 // Logging
 export { createLogger } from "./lib/log.ts";

package/src/lib/cache.ts

@@ -11,10 +11,28 @@ 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";
+import { QuickCHRError, type Arch } from "./types.ts";
 
 export const DEFAULT_CACHE_MAX_BYTES = 2 * 1024 * 1024 * 1024;
 
+/** Parse a human size string (NK/NM/NG/NT, IEC binary, case-insensitive) to bytes. */
+export function parseSizeString(s: string): number {
+	const m = s.match(/^(\d+(?:\.\d+)?)([KMGT]?)i?B?$/i);
+	if (!m) throw new QuickCHRError("INVALID_SIZE_STRING", `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));
+}
+
+/** Format a byte count as a human size (IEC binary), matching cache list's display. */
+export function formatSizeBytes(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`;
+}
+
 export interface CacheEntry {
 	path: string;
 	basename: string;

package/src/lib/channels.ts

@@ -54,7 +54,22 @@ export function channelFileExists(path: string): boolean {
 	return existsSync(path);
 }
 
-/** Send a command to the QEMU monitor and return the response. */
+/** Strip ANSI escapes and the monitor's per-character command echo, leaving
+ *  just the response body. The echo hid real errors from callers: QEMU renders
+ *  the typed command as incremental `cmd\x1b[K\x1b[D…` fragments before the
+ *  first newline, so an `Error: …` response never appeared at string start and
+ *  `savevm`/`loadvm` failures were silently swallowed (#31). */
+export function cleanMonitorResponse(raw: string): string {
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escapes are the point
+	const noAnsi = raw.replace(/\u001b\[[0-9;]*[A-Za-z]/g, "");
+	const lines = noAnsi.split(/\r?\n/);
+	// Everything before the first newline is the echoed command; the response
+	// (possibly multi-line, possibly empty) follows.
+	return lines.slice(1).join("\n").trim();
+}
+
+/** Send a command to the QEMU monitor and return the cleaned response
+ *  (command echo and ANSI control sequences stripped — see cleanMonitorResponse). */
 export async function monitorCommand(
 	machineDir: string,
 	command: string,
@@ -92,9 +107,9 @@ export async function monitorCommand(
 				buffer = "";
 				socket.write(command + "\n");
 			} else if (sentCommand && buffer.includes("(qemu)")) {
-				// Got response — strip the prompt
+				// Got response — strip the prompt, the command echo, and ANSI noise
 				clearTimeout(timeout);
-				const response = buffer.replace(/\(qemu\)\s*/g, "").trim();
+				const response = cleanMonitorResponse(buffer.replace(/\(qemu\)\s*/g, ""));
 				socket.destroy();
 				resolve(response);
 			}
@@ -105,7 +120,7 @@ export async function monitorCommand(
 		socket.on("close", () => {
 			clearTimeout(timeout);
 			if (sentCommand) {
-				resolve(buffer.replace(/\(qemu\)\s*/g, "").trim());
+				resolve(cleanMonitorResponse(buffer.replace(/\(qemu\)\s*/g, "")));
 			} else {
 				reject(new QuickCHRError("MACHINE_STOPPED", "Monitor socket closed before command could be sent"));
 			}

package/src/lib/completions.ts

@@ -328,7 +328,7 @@ _quickchr() {
         cword=${D}COMP_CWORD
     }
 
-    local commands="add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor setup completions version help"
+    local commands="add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor settings setup completions version help"
 
     if [[ ${D}cword -eq 1 ]]; then
         COMPREPLY=( $(compgen -W "${D}commands" -- "${D}cur") )
@@ -402,6 +402,7 @@ _quickchr() {
                 'networks:Network discovery and socket management'
                 'net:Network discovery (alias)'
                 'doctor:Check prerequisites'
+                'settings:Manage global quickchr settings'
                 'setup:Interactive setup wizard'
                 'completions:Manage shell completions'
                 'version:Show version info'
@@ -434,7 +435,7 @@ _quickchr() {
                     _describe 'option' opts
                     ;;
                 help)
-                    local commands=(add start stop list status inspect env remove clean console exec qga license disk snapshot networks doctor setup completions version)
+                    local commands=(add start stop list status inspect env remove clean console exec qga license disk snapshot networks doctor settings setup completions version)
                     _describe 'command' commands
                     ;;
             esac
@@ -450,7 +451,7 @@ function generateFishCompletion(): string {
 	return `# quickchr fish completion
 # Generated by quickchr. Fish auto-loads files from ~/.config/fish/completions/.
 
-set -l quickchr_commands add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor setup completions version help
+set -l quickchr_commands add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor settings setup completions version help
 
 # Disable file completions globally for quickchr
 complete -c quickchr -f
@@ -490,6 +491,8 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "networks net" -d "Network discovery and socket management"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "doctor"      -d "Check prerequisites"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "settings"    -d "Manage global quickchr settings"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "setup"       -d "Interactive setup wizard"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\

package/src/lib/disk.ts

@@ -260,8 +260,11 @@ export function parseSnapshotList(monitorOutput: string): SnapshotInfo[] {
 		// 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         --"
+		// VM CLOCK hour width varies by QEMU version (2-digit on 8.x runners,
+		// 4-digit on 11.x brew builds) and the ICOUNT column may be absent —
+		// accept both so list() doesn't silently return [] on older QEMU.
 		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,
+			/^\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{2,4}:\d{2}:\d{2}\.\d+)(?:\s+(\S+))?/i,
 		);
 		if (!match) continue;
 
@@ -274,7 +277,7 @@ export function parseSnapshotList(monitorOutput: string): SnapshotInfo[] {
 			vmStateSize: parseVmSize(vmSizeStr),
 			date: dateStr.replace(" ", "T") + "Z",
 			vmClock: vmClock,
-			icount: icountStr === "--" ? undefined : Number(icountStr),
+			icount: icountStr && icountStr !== "--" ? Number(icountStr) : undefined,
 		});
 	}
 

package/src/lib/forward-spec.ts

@@ -1,7 +1,9 @@
 /**
- * Parse a CLI `--forward` spec into a `PortMapping`.
+ * Parse a CLI `--forward` spec into one or more `PortMapping`s.
  *
- * Grammar: `name[:host[:guest]][/proto]`
+ * Two grammars share this file:
+ *
+ * **Single port** — `parseForwardSpec`, grammar `name[:host[:guest]][/proto]`:
  *
  * - `name` — required. If it matches a key/alias in `WELL_KNOWN_GUEST_PORTS`,
  *   missing `guest` and `proto` are filled from the registry. The original
@@ -14,7 +16,16 @@
  * - `proto` — optional. Defaults from registry, else `tcp`. Must be `tcp` or
  *   `udp`.
  *
- * Throws `QuickCHRError("INVALID_FORWARD_SPEC", ...)` with the original spec
+ * **Port range** — `expandForwardSpec`, grammar
+ * `name:hostStart-hostEnd[:guestStart-guestEnd][/proto]`. Expands to one
+ * `PortMapping` per port (QEMU `hostfwd` has no native range — each port needs
+ * its own directive). Useful for L3 peer protocols with dynamic data ports
+ * (e.g. RouterOS bandwidth-test allocates UDP ports at runtime). See the rules
+ * on `expandForwardSpec` below. `expandForwardSpec` is the range-aware entry
+ * point and delegates to `parseForwardSpec` for non-range specs, so callers can
+ * always use `expandForwardSpec` (the CLI does).
+ *
+ * Both throw `QuickCHRError("INVALID_FORWARD_SPEC", ...)` with the original spec
  * embedded in the message on any parse error.
  */
 
@@ -90,3 +101,129 @@ export function parseForwardSpec(spec: string): PortMapping {
 
 	return { name, host, guest, proto };
 }
+
+/** Max ports a single range `--forward` may span, bounding the generated
+ *  `hostfwd` string (one directive per port). */
+export const FORWARD_RANGE_MAX = 64;
+
+function parseRange(
+	spec: string,
+	raw: string,
+	label: string,
+): { start: number; end: number } {
+	const dash = raw.indexOf("-");
+	const startRaw = raw.slice(0, dash);
+	const endRaw = raw.slice(dash + 1);
+	const start = parsePort(spec, startRaw, `${label} range start`, false);
+	const end = parsePort(spec, endRaw, `${label} range end`, false);
+	if (end < start) {
+		fail(spec, `${label} range end ${end} is below start ${start}`);
+	}
+	return { start, end };
+}
+
+/**
+ * Range-aware front door for `--forward` specs. Returns a `PortMapping[]`.
+ *
+ * For a single-port spec (no `-` in the host/guest segment) this returns
+ * `[parseForwardSpec(spec)]` unchanged. For a range spec
+ * `name:hostStart-hostEnd[:guestStart-guestEnd][/proto]` it expands to one
+ * `PortMapping` per port, named `\`${name}-${hostPort}\`` so each is a distinct
+ * key in the machine's port map.
+ *
+ * Range rules:
+ * - **Host range is required** — ranges are not auto-allocated. The per-instance
+ *   port block (10 ports) can't guarantee a contiguous run, so range host ports
+ *   must be explicit. They are then collision-checked like any explicit
+ *   `extraPorts` host (`validateExplicitExtraPorts`).
+ * - **Guest range is optional** — defaults to the same numbers as the host
+ *   range. When given it must be the **same length** as the host range.
+ * - **`proto`** defaults from the `WELL_KNOWN_GUEST_PORTS` registry (by `name`),
+ *   else `tcp`; an explicit `/proto` suffix wins.
+ * - Reversed ranges (end < start) and spans over {@link FORWARD_RANGE_MAX} ports
+ *   throw `INVALID_FORWARD_SPEC`.
+ *
+ * @example
+ * expandForwardSpec("btest:9200-9202:2000-2002/udp");
+ * // → [{name:"btest-9200",host:9200,guest:2000,proto:"udp"}, … 9201/2001, 9202/2002]
+ * @example
+ * expandForwardSpec("smb"); // single port → [{name:"smb",host:0,guest:445,proto:"tcp"}]
+ */
+export function expandForwardSpec(spec: string): PortMapping[] {
+	if (!spec?.trim()) {
+		throw new QuickCHRError("INVALID_FORWARD_SPEC", "Empty --forward spec");
+	}
+	const trimmed = spec.trim();
+
+	// Split off /proto suffix (so a range's "-" can't be confused with anything).
+	let body = trimmed;
+	let protoStr: string | undefined;
+	const slash = trimmed.lastIndexOf("/");
+	if (slash !== -1) {
+		body = trimmed.slice(0, slash);
+		protoStr = trimmed.slice(slash + 1).toLowerCase();
+		if (protoStr !== "tcp" && protoStr !== "udp") {
+			fail(spec, `protocol must be "tcp" or "udp", got "${protoStr}"`);
+		}
+	}
+
+	const parts = body.split(":");
+	const hasRange = Boolean(parts[1]?.includes("-") || parts[2]?.includes("-"));
+	if (!hasRange) {
+		return [parseForwardSpec(spec)];
+	}
+
+	if (parts.length > 3) {
+		fail(spec, `too many ":" segments (expected name:hostStart-hostEnd[:guestStart-guestEnd])`);
+	}
+	const name = parts[0]?.trim() ?? "";
+	if (!name) {
+		fail(spec, "name is required");
+	}
+
+	const hostSegment = parts[1];
+	if (!hostSegment?.includes("-")) {
+		fail(
+			spec,
+			"a range --forward requires an explicit host range (e.g. 9200-9210); ranges are not auto-allocated",
+		);
+	}
+	const hostRange = parseRange(spec, hostSegment, "host");
+
+	const guestSegment = parts[2];
+	let guestRange: { start: number; end: number };
+	if (guestSegment !== undefined && guestSegment !== "") {
+		if (!guestSegment.includes("-")) {
+			fail(
+				spec,
+				`guest segment "${guestSegment}" must be a range matching the host range (e.g. 2000-2010), not a single port`,
+			);
+		}
+		guestRange = parseRange(spec, guestSegment, "guest");
+	} else {
+		// guest range omitted → default to the host range's port numbers
+		guestRange = { start: hostRange.start, end: hostRange.end };
+	}
+
+	const hostCount = hostRange.end - hostRange.start + 1;
+	const guestCount = guestRange.end - guestRange.start + 1;
+	if (hostCount !== guestCount) {
+		fail(
+			spec,
+			`host range (${hostCount} ports) and guest range (${guestCount} ports) must be the same length`,
+		);
+	}
+	if (hostCount > FORWARD_RANGE_MAX) {
+		fail(spec, `range spans ${hostCount} ports, exceeding the ${FORWARD_RANGE_MAX}-port cap`);
+	}
+
+	const known = lookupGuestPort(name);
+	const proto: "tcp" | "udp" = (protoStr as "tcp" | "udp" | undefined) ?? known?.proto ?? "tcp";
+
+	const mappings: PortMapping[] = [];
+	for (let i = 0; i < hostCount; i++) {
+		const host = hostRange.start + i;
+		mappings.push({ name: `${name}-${host}`, host, guest: guestRange.start + i, proto });
+	}
+	return mappings;
+}

package/src/lib/paths.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared filesystem paths for quickchr's config-tier (XDG_CONFIG-like) files.
+ */
+
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/** ~/.config/quickchr — used by secrets.ts (credential fallback files) and
+ *  settings.ts (quickchr.env). Single source of truth so those modules never
+ *  drift on the HOME/USERPROFILE fallback chain. */
+export function quickchrConfigDir(): string {
+	return join(process.env.HOME ?? process.env.USERPROFILE ?? homedir(), ".config", "quickchr");
+}