@tikoci/quickchr 0.4.1 → 0.4.3

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

@@ -125,8 +125,25 @@ 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";
 export type { ProgressLogger } from "./lib/log.ts";
+
+// Version & channel utilities
+export { CHANNELS } from "./lib/types.ts";
+export {
+	resolveVersion,
+	resolveAllVersions,
+	isValidVersion,
+	parseVersionParts,
+	compareRouterOsVersion,
+	isProvisioningSupportedVersion,
+	channelMaturity,
+	classifyChannels,
+	selectActiveChannels,
+	resolveChannelStatuses,
+	resolveActiveChannels,
+} from "./lib/versions.ts";
+export type { ChannelMaturity, ChannelStatus } from "./lib/versions.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/net.ts

@@ -1,22 +1,30 @@
 /**
  * Resilient HTTP fetch for MikroTik's download hosts.
  *
- * On GitHub-hosted CI runners the system DNS resolver returns `ESERVFAIL`
- * (slowly — 2 to 26 s) for `upgrade.mikrotik.com` / `download.mikrotik.com` via
- * both `getaddrinfo` and c-ares-over-resolv.conf, so a plain `fetch` either
- * times out or (when the stub hands back only the unreachable AAAA) fails with
- * Bun's `errno: 0` ConnectionRefused / FailedToOpenSocket. A direct query to a
- * public resolver answers in ~10 ms, and the hosts are dual-stack with a
- * reachable IPv4. quickchr is expected to run unattended in CI, so it resolves
- * these hosts itself rather than trusting the runner's broken resolver.
+ * Primary path: a plain `fetch` on the system resolver. This is tried first,
+ * accepting the latency cost when it fails — usually small, but up to the
+ * resolver's own failure time (the broken CI stub below took 2–26 s). It is
+ * dual-stack (happy eyeballs) and on par with curl/most tools, and it honors
+ * local DNS configuration —
+ * `/etc/hosts` pins, VPN/split-horizon DNS, mirror redirects, IPv6-only egress —
+ * which a forced public-DNS+IPv4 path would silently override and could itself
+ * turn into a fresh failure mode. So we stay "normal" unless the normal path
+ * actually breaks.
  *
- * Strategy: resolve the A record by querying a public DNS server directly
- * (bypassing the host's resolv.conf), then connect to the IPv4 literal,
- * preserving the `Host` header and TLS SNI so certificate validation still
- * passes. Fall back to a normal `fetch` (system resolver, dual-stack) when the
- * public-DNS path is unavailable — e.g. a network that blocks public resolvers
- * — so this stays correct off CI. HTTP responses and aborts/timeouts pass
- * through unchanged; they are never retried.
+ * Fallback: some environments (notably GitHub-hosted CI runners, observed
+ * 2026-06) have a broken/slow stub resolver that returns `ESERVFAIL` — slowly,
+ * 2 to 26 s — for `upgrade.mikrotik.com` / `download.mikrotik.com`, or hands back
+ * only an unreachable AAAA, surfacing as Bun's `errno: 0` ConnectionRefused /
+ * FailedToOpenSocket. When the normal fetch fails *that* way (a connection-class
+ * error), we retry by resolving the A record against a public DNS server
+ * directly (~10 ms), bypassing the host's resolv.conf, and connecting to the
+ * IPv4 literal with the `Host` header and TLS SNI preserved so certificate
+ * validation still passes.
+ *
+ * Only connection-class failures trigger the fallback; HTTP responses (incl.
+ * 5xx) and aborts (`AbortError`, e.g. from `AbortSignal.timeout`) pass through
+ * unchanged and are never retried. (A low-level connect `ETIMEDOUT` is a
+ * connection-class failure and *is* retried — see `isConnectionFailure`.)
  */
 
 import { promises as dns } from "node:dns";
@@ -28,13 +36,14 @@ const DNS_TIMEOUT_MS = 3000;
  * True for the connection-class failures raised when a socket cannot be opened
  * (e.g. IPv4 blocked on an IPv6-only network, or Bun's `errno: 0`
  * ConnectionRefused / FailedToOpenSocket against an unreachable address), plus
- * the standard connect errors. Excludes aborts/timeouts and HTTP-level outcomes
- * (those carry a Response and never throw here). Used to decide whether to fall
- * back from the IPv4 attempt to a normal dual-stack fetch.
+ * the standard connect errors. Excludes `AbortError` (aborts/`AbortSignal`
+ * timeouts) and HTTP-level outcomes (those carry a Response and never throw
+ * here). Used to decide whether to fall back from the normal fetch to the
+ * public-DNS IPv4 attempt.
  */
 export function isConnectionFailure(err: unknown): boolean {
 	if (!err || typeof err !== "object") return false;
-	const e = err as { name?: string; code?: string; cause?: { code?: string } };
+	const e = err as { name?: string; code?: string; errno?: number; cause?: { code?: string } };
 	if (e.name === "AbortError") return false;
 	const code = e.code ?? e.cause?.code;
 	if (
@@ -49,10 +58,12 @@ export function isConnectionFailure(err: unknown): boolean {
 	) {
 		return true;
 	}
-	// Bun wraps low-level connect failures as a bare TypeError ("Unable to
-	// connect…"). Treat those as retriable too; a wrong guess only costs one
-	// normal fetch, which then surfaces the real error if it also fails.
-	return e.name === "TypeError";
+	// Bun has also surfaced low-level connect failures as a `TypeError` carrying
+	// `errno: 0` (its connect-failure marker; the typed `code`s above catch the
+	// current form — Bun 1.3 throws an `Error` with `code: "ConnectionRefused"`,
+	// confirmed by probe). Gate on that marker so an unrelated `TypeError` (a real
+	// bug) surfaces immediately instead of triggering a pointless DNS retry.
+	return e.name === "TypeError" && e.errno === 0;
 }
 
 /** Rewrite a URL to target an explicit IPv4 literal, preserving port/path/query. */
@@ -64,10 +75,11 @@ export function toIpv4Url(url: string, address: string): string {
 
 /**
  * Resolve a host's A record via public DNS servers directly, bypassing the
- * host's resolv.conf (which is broken for these names on CI runners). Returns
- * undefined — never throws — when public DNS is unreachable or has no answer,
- * so the caller can fall back to a normal fetch. Bounded by DNS_TIMEOUT_MS so a
- * blocked resolver does not stall the request.
+ * host's resolv.conf. Used only as the fallback path, after a normal fetch has
+ * already failed with a connection-class error (e.g. a broken stub resolver on
+ * CI runners). Returns undefined — never throws — when public DNS is unreachable
+ * or has no answer, so the caller can surface the original failure. Bounded by
+ * DNS_TIMEOUT_MS so a blocked resolver does not stall the request.
  */
 async function resolveIpv4(host: string): Promise<string | undefined> {
 	const resolver = new dns.Resolver();
@@ -88,6 +100,12 @@ async function resolveIpv4(host: string): Promise<string | undefined> {
 	}
 }
 
+/**
+ * Fetch `url` but connect to an explicit IPv4 `address`, keeping HTTP and TLS
+ * pointed at the original host: the `Host` header and TLS SNI (`serverName`) are
+ * set to the URL's hostname so virtual-hosting routing and certificate
+ * validation still pass against the IP literal. The failback transport.
+ */
 async function fetchOverIpv4(
 	url: string,
 	address: string,
@@ -99,25 +117,31 @@ async function fetchOverIpv4(
 	return fetch(toIpv4Url(url, address), {
 		...init,
 		headers,
-		tls: { serverName: host, ...init?.tls },
+		// serverName last: it must pin to the real host for cert validation against
+		// the IP literal — a caller-provided init.tls.serverName must not override it.
+		tls: { ...init?.tls, serverName: host },
 	});
 }
 
 /**
- * `fetch()` that resolves dual-stack hosts via public DNS and connects over
- * IPv4, so it survives a broken/slow system resolver (e.g. GitHub-hosted CI
- * runners). Falls back to a normal `fetch` when public DNS is unavailable.
- * Behaves like `fetch` for HTTP responses and aborts.
+ * `fetch()` that tries the system resolver first (a normal dual-stack fetch)
+ * and, only when that fails with a connection-class error, falls back to
+ * resolving via public DNS and connecting over the IPv4 literal — so it survives
+ * a broken/slow system resolver (e.g. GitHub-hosted CI runners) without
+ * overriding local DNS in the common case. Behaves like `fetch` for HTTP
+ * responses and aborts.
  */
 export async function fetchResilient(url: string, init?: BunFetchRequestInit): Promise<Response> {
-	const address = await resolveIpv4(new URL(url).hostname);
-	if (address) {
-		try {
-			return await fetchOverIpv4(url, address, init);
-		} catch (err) {
-			if (!isConnectionFailure(err)) throw err;
-			// IPv4 unreachable (e.g. IPv6-only egress) — fall through to a normal fetch.
-		}
+	try {
+		return await fetch(url, init);
+	} catch (err) {
+		// Only a connection-class failure (e.g. a broken/slow stub resolver, or an
+		// unreachable AAAA) is worth the public-DNS workaround. Aborts (AbortError)
+		// and everything else propagate unchanged.
+		if (!isConnectionFailure(err)) throw err;
+		const address = await resolveIpv4(new URL(url).hostname);
+		// Public DNS can't help (unreachable / no answer) — surface the original failure.
+		if (address === undefined) throw err;
+		return fetchOverIpv4(url, address, init);
 	}
-	return fetch(url, init);
 }

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");
+}