@tikoci/quickchr 0.4.5 → 0.4.7

package/src/lib/platform.ts

@@ -3,8 +3,11 @@
  */
 
 import { existsSync, readdirSync, statSync } from "node:fs";
-import type { EfiFirmwarePaths, HostInterface, PackageManager, PlatformInfo, SocketVmnetInfo } from "./types.ts";
-import { QuickCHRError as QError } from "./types.ts";
+import type { AccelMode, EfiFirmwarePaths, HostInterface, PackageManager, PlatformInfo, SocketVmnetInfo } from "./types.ts";
+import { QuickCHRError as QError, parseAccelMode } from "./types.ts";
+// settings-file.ts, not settings.ts: the latter's graph (cache → state → network
+// → platform) is a cycle that would load eagerly on every CLI start.
+import { loadSettingsFileDefaults } from "./settings-file.ts";
 
 /** UEFI firmware search paths by platform. */
 const EFI_CODE_PATHS = [
@@ -111,14 +114,11 @@ export function qgaKvmWarning(): string | null {
 	);
 }
 
-/** Whether guestArch requires cross-architecture emulation (TCG) on this host.
- *  Cross-arch emulation is significantly slower and needs more memory/timeout.
- *  arm64 guest on x86_64 host → TCG (slow).
- *  x86 guest on any host → HVF or KVM when available (fast). */
+/** Whether guestArch differs from the physical host CPU architecture.
+ *  Cross-arch TCG is significantly slower and needs more memory/timeout. */
 export function isCrossArchEmulation(guestArch: "x86" | "arm64"): boolean {
-	// x86 CHR is always runnable under HVF/KVM or TCG — never "slow" cross-arch.
-	// arm64 CHR on an arm64 host uses HVF/KVM; on an x86_64 host it falls back to TCG.
-	return guestArch === "arm64" && process.arch !== "arm64";
+	const hostIsArm64 = isAppleSiliconHost() || (process.platform !== "darwin" && process.arch === "arm64");
+	return (guestArch === "arm64") !== hostIsArm64;
 }
 
 /**
@@ -138,8 +138,132 @@ export function accelTimeoutFactor(accel: string, crossArch: boolean): number {
 	return crossArch ? 15.0 : 4.0;
 }
 
+/**
+ * Whether the physical host is Apple Silicon, including when quickchr itself
+ * runs as an x64 process under Rosetta.
+ *
+ * Apple Silicon implements **no AArch32 at any exception level**: its
+ * `ID_AA64PFR0_EL1` reports AArch64-only for EL0 and EL1, and HVF passes that
+ * hardware register straight through to the guest (the `-cpu` model is inert
+ * under HVF).  Current arm64 CHR images ship an AArch64 kernel over a *32-bit
+ * ARM* userspace — the appended initramfs `/init` is `ELF 32-bit LSB ARM
+ * EABI5`, and the system package holds 101 further ARM32 executables — so the
+ * guest kernel never sets `ARM64_HAS_32BIT_EL0`, `execve("/init")` returns
+ * -ENOEXEC, and Linux panics ~0.08 s in with "No working init found".
+ * TCG's emulated CPU models do provide AArch32 EL0, so the same image boots.
+ *
+ * This is an image-artifact incompatibility, not an accelerator or CPU-model
+ * bug: no QEMU flag and no macOS VMM can present a feature the silicon does not
+ * implement.  See docs/m4-hvf-arm64-investigation.md and tikoci/quickchr#97.
+ */
+let appleSiliconHostMemo: boolean | undefined;
+
+export function isAppleSiliconHost(): boolean {
+	if (process.platform !== "darwin") return false;
+	if (process.arch === "arm64") return true;
+	if (process.arch !== "x64") return false;
+	if (appleSiliconHostMemo !== undefined) return appleSiliconHostMemo;
+	try {
+		const result = Bun.spawnSync(["sysctl", "-n", "sysctl.proc_translated"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		appleSiliconHostMemo =
+			result.exitCode === 0 &&
+			new TextDecoder().decode(result.stdout).trim() === "1";
+	} catch {
+		appleSiliconHostMemo = false;
+	}
+	return appleSiliconHostMemo;
+}
+
+/** @internal Test-only: clear the memoized Rosetta probe between mocked runs. */
+export function resetAppleSiliconHostCache(): void {
+	appleSiliconHostMemo = undefined;
+}
+
+/**
+ * Process-level accelerator override, set by `--accel` (CLI) or by a library
+ * caller.  Highest tier of the documented precedence chain
+ * (flag > QUICKCHR_ACCEL env > quickchr.env > built-in "auto"); `undefined`
+ * means "not set, fall through to the settings tiers".
+ */
+let accelOverride: AccelMode | undefined;
+
+/** Force the accelerator for the rest of this process, or clear with undefined. */
+export function setAccelOverride(mode: AccelMode | undefined): void {
+	accelOverride = mode;
+}
+
+/**
+ * Resolve the accelerator override: process override > QUICKCHR_ACCEL env >
+ * quickchr.env > "auto".  Mirrors settings.ts's `accel` key resolution (same
+ * tiers, same validator) but reads the file tier directly to stay out of that
+ * module's import cycle.  Throws INVALID_SETTING_VALUE on an unrecognized mode.
+ */
+export function resolveAccelOverride(): AccelMode {
+	return resolveAccelOverrideWithSource().mode;
+}
+
+/** Which tier supplied the accelerator, for messages that must say *why*. */
+export type AccelOverrideSource = "flag" | "env" | "file" | "default";
+
+/**
+ * As resolveAccelOverride(), but also reports the tier the value came from.
+ * With three override tiers, "TCG because ~/.config/quickchr/quickchr.env says
+ * so" and "TCG because you passed --accel" are very different support answers,
+ * so the launch note names the source rather than guessing at it.
+ */
+export function resolveAccelOverrideWithSource(): { mode: AccelMode; source: AccelOverrideSource } {
+	if (accelOverride !== undefined) return { mode: accelOverride, source: "flag" };
+	const envRaw = process.env.QUICKCHR_ACCEL;
+	if (envRaw !== undefined) return { mode: parseAccelMode(envRaw), source: "env" };
+	const fileRaw = loadSettingsFileDefaults().QUICKCHR_ACCEL;
+	if (fileRaw !== undefined) return { mode: parseAccelMode(fileRaw), source: "file" };
+	return { mode: "auto", source: "default" };
+}
+
+/**
+ * User-facing name of the override tier — the thing the user would actually go
+ * edit.  Shared by the launch note and `doctor` so both name the same source;
+ * never print the raw AccelOverrideSource enum, which is internal.
+ */
+export function accelSourceLabel(source: AccelOverrideSource): string {
+	if (source === "flag") return "--accel";
+	if (source === "env") return "QUICKCHR_ACCEL";
+	if (source === "file") return "quickchr.env";
+	return "auto-detection";
+}
+
+/**
+ * One-line note about how the accelerator was chosen, or null when there is
+ * nothing worth saying.  Surfaced at launch so a user on slow emulation — or
+ * one who forced a mode that is known not to boot — understands why.
+ */
+export function accelNote(guestArch: "x86" | "arm64", accel: string): string | null {
+	const { mode: forced, source } = resolveAccelOverrideWithSource();
+	if (forced !== "auto") {
+		const base = `Accelerator configured as "${forced}" via ${accelSourceLabel(source)} — auto-detection bypassed.`;
+		if (guestArch === "arm64" && forced === "hvf" && isAppleSiliconHost()) {
+			return `${base} Note: arm64 CHR images still ship a 32-bit ARM userspace, which Apple Silicon cannot execute under HVF — expect "No working init found" unless MikroTik has shipped an AArch64-only image (tikoci/quickchr#97).`;
+		}
+		return base;
+	}
+	if (guestArch !== "arm64" || accel !== "tcg" || !isAppleSiliconHost()) return null;
+	return (
+		"arm64 CHR is running under TCG on Apple Silicon: the image's appended " +
+		"initramfs /init and most of its system package are 32-bit ARM, and Apple " +
+		"CPUs implement no AArch32 at any exception level, so an HVF guest panics " +
+		'with "No working init found". TCG is slower but boots. Override with ' +
+		"--accel hvf once MikroTik ships an AArch64-only arm64 image (tikoci/quickchr#97)."
+	);
+}
+
 /** Detect available QEMU acceleration for a guest architecture. */
 export async function detectAccel(guestArch: "x86" | "arm64"): Promise<string> {
+	const forced = resolveAccelOverride();
+	if (forced !== "auto") return forced;
+
 	const hostOs = process.platform;
 	const hostArch = process.arch; // "x64" | "arm64"
 
@@ -157,9 +281,10 @@ export async function detectAccel(guestArch: "x86" | "arm64"): Promise<string> {
 	}
 
 	if (hostOs === "darwin") {
-		// Apple Hypervisor Framework (HVF) is a system capability, not a per-process one.
-		// It is available if kern.hv_support=1, regardless of whether the bun process
-		// itself is arm64 native or running via Rosetta (process.arch="x64").
+		// Apple Hypervisor Framework only runs guests matching the physical host
+		// architecture. Rosetta can translate the quickchr process, but it cannot
+		// make x86 HVF guests run on Apple Silicon.
+		const appleSilicon = isAppleSiliconHost();
 		try {
 			const hvResult = Bun.spawnSync(["sysctl", "-n", "kern.hv_support"], {
 				stdout: "pipe",
@@ -167,13 +292,22 @@ export async function detectAccel(guestArch: "x86" | "arm64"): Promise<string> {
 			});
 			const hv = new TextDecoder().decode(hvResult.stdout).trim();
 			if (hv === "1") {
-				if (guestArch === "x86") return "hvf";
-				// arm64 guest HVF requires a native arm64 host process.
-				// Use process.arch — on Intel Macs this is "x64" so arm64 guests get TCG,
-				// which is correct (Intel can't run arm64 HVF). On Apple Silicon, native
-				// bun reports "arm64" and gets HVF. Rosetta bun reports "x64" and gets TCG
-				// (acceptable — arm64 TCG on Apple Silicon still boots in <5 min).
-				if (process.arch === "arm64") return "hvf";
+				if (guestArch === "x86" && !appleSilicon) return "hvf";
+				// arm64 guest: falls through to TCG on every macOS host.
+				//
+				// On Intel Macs process.arch is "x64" and arm64 HVF is impossible.
+				// On Apple Silicon HVF *is* available but must not be used: no Apple
+				// CPU implements AArch32 at any exception level, and current arm64 CHR
+				// images require a 32-bit ARM userspace, so an HVF guest panics at init
+				// (see isAppleSiliconHost()).  arm64 TCG still boots, but is slower.
+				//
+				// Restore signal (#97) is the *guest artifact*, not the host or QEMU
+				// version: a future arm64 CHR whose appended /init and system-package
+				// executables are all AArch64, verified by a real HVF boot.  Until then
+				// `--accel hvf` / QUICKCHR_ACCEL=hvf is the escape hatch for testing.
+				//
+				// x86 guests also fall through on Apple Silicon because HVF cannot
+				// virtualize across architectures; their escape hatch is the same.
 			}
 		} catch { /* fall through */ }
 	}

package/src/lib/qemu.ts

@@ -13,6 +13,7 @@ import { detectAccel, requireQemu, requireFirmware, requireQemuImg } from "./pla
 import { buildHostfwdString } from "./network.ts";
 import { ensureDir } from "./state.ts";
 import { restGet } from "./rest.ts";
+import { classifyProbeError, recordBootProbe, serialLogEnabled, type BootProbeStats } from "./diagnostics.ts";
 
 export interface QemuLaunchConfig {
 	arch: Arch;
@@ -221,12 +222,20 @@ function buildChannelArgs(
 		qgaSock = `path=${join(machineDir, "qga.sock")}`;
 	}
 
+	// QUICKCHR_SERIAL_LOG=1 tees the serial console to <machineDir>/serial.log via
+	// the QEMU chardev `logfile=` option. Opt-in, never default: serial-console
+	// provisioning types the generated user password in cleartext (provision.ts
+	// provisionViaConsole), so this log is secret-bearing. It is the only record of
+	// what RouterOS printed when a boot never reaches REST — the socket chardev
+	// keeps no history, so connecting after the failure shows nothing (#79).
+	const serialLog = serialLogEnabled() ? `,logfile=${join(machineDir, "serial.log")},logappend=on` : "";
+
 	if (background) {
 		// Background: all channels on sockets/pipes
 		args.push(
 			"-chardev", `socket,id=monitor0,${monitorSock},server=on,wait=off`,
 			"-mon", "chardev=monitor0,mode=readline",
-			"-chardev", `socket,id=serial0,${serialSock},server=on,wait=off`,
+			"-chardev", `socket,id=serial0,${serialSock},server=on,wait=off${serialLog}`,
 			"-serial", "chardev:serial0",
 		);
 	} else {
@@ -517,9 +526,11 @@ export async function waitForBoot(
 	httpPort: number,
 	timeoutMs: number = 120_000,
 	auth: string = `Basic ${btoa("admin:")}`,
+	stats?: BootProbeStats,
 ): Promise<boolean> {
 	const url = `http://127.0.0.1:${httpPort}/rest/system/resource`;
-	const deadline = Date.now() + timeoutMs;
+	const start = Date.now();
+	const deadline = start + timeoutMs;
 	let consecutiveReady = 0;
 
 	while (Date.now() < deadline) {
@@ -530,6 +541,7 @@ export async function waitForBoot(
 				// Auth rejected — the REST layer is up and responded, even though
 				// we cannot validate the body. Count as ready.
 				consecutiveReady++;
+				recordBootProbe(stats, Date.now() - start, "unauthorized", String(status));
 			} else if (status >= 200 && status < 300) {
 				// RouterOS REST may return wrong data (array body) briefly after boot —
 				// a startup race. Only accept once the body is the expected singleton object.
@@ -537,17 +549,24 @@ export async function waitForBoot(
 				try { parsed = JSON.parse(body); } catch { /* ignore */ }
 				if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && "board-name" in (parsed as object)) {
 					consecutiveReady++;
+					recordBootProbe(stats, Date.now() - start, "ready");
 				} else {
 					consecutiveReady = 0; // wrong body — REST not fully initialized yet
+					recordBootProbe(stats, Date.now() - start, "wrong-body", body.slice(0, 80));
 				}
 			} else {
 				consecutiveReady = 0;
+				recordBootProbe(stats, Date.now() - start, "http-error", String(status));
 			}
 
 			if (consecutiveReady >= 2) return true;
-		} catch {
-			// ECONNRESET, connection refused, timeout — not ready yet
+		} catch (e) {
+			// ECONNRESET, connection refused, timeout — not ready yet. Which one it
+			// was is the whole diagnosis when a boot never completes (#79), so it is
+			// classified rather than swallowed.
 			consecutiveReady = 0;
+			const { outcome, detail } = classifyProbeError(e);
+			recordBootProbe(stats, Date.now() - start, outcome, detail);
 		}
 		await Bun.sleep(2000);
 	}