@tikoci/quickchr 0.4.2 → 0.4.3

package/src/lib/secrets.ts

@@ -12,11 +12,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { homedir } from "node:os";
-
-function configDir(): string {
-	return join(process.env.HOME ?? process.env.USERPROFILE ?? homedir(), ".config", "quickchr");
-}
+import { quickchrConfigDir } from "./paths.ts";
 
 /** True when the Bun.secrets API is available at runtime. */
 function hasBunSecrets(): boolean {
@@ -32,7 +28,7 @@ function hasBunSecrets(): boolean {
 function configPath(service: string): string {
 	// One JSON file per service, keyed by name
 	const safeName = service.replace(/[^a-zA-Z0-9._-]/g, "_");
-	return join(configDir(), `${safeName}.json`);
+	return join(quickchrConfigDir(), `${safeName}.json`);
 }
 
 function readConfigStore(service: string): Record<string, string> {
@@ -129,5 +125,5 @@ export async function secretDelete(service: string, name: string): Promise<boole
 /** Human-readable label for where secrets are stored. */
 export function secretStorageLabel(): string {
 	if (hasBunSecrets()) return "OS credential store (via Bun.secrets)";
-	return `config file (${configDir()})`;
+	return `config file (${quickchrConfigDir()})`;
 }

package/src/lib/settings.ts

@@ -0,0 +1,373 @@
+/**
+ * quickchr's own user-scoped settings — global preferences with no per-machine
+ * home, stored at ~/.config/quickchr/quickchr.env (dotenv-style: one
+ * QUICKCHR_KEY=value line per managed setting).
+ *
+ * Precedence per key (highest wins): CLI flag > QUICKCHR_<KEY> env var >
+ * quickchr.env > built-in default. This module only resolves the middle two
+ * tiers (env, file) plus the built-in default — callers compose
+ * `flagValue ?? resolveSetting(attr).value` themselves, so an explicit CLI
+ * flag never runs through the settings validator.
+ *
+ * Does not read or write machine.json / MachineState — settings are CLI-start
+ * input resolution, never per-machine config.
+ */
+
+import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, fsyncSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { ARCHES, CHANNELS, QuickCHRError } from "./types.ts";
+import type { Channel } from "./types.ts";
+import { parseSizeString, DEFAULT_CACHE_MAX_BYTES } from "./cache.ts";
+import { quickchrConfigDir } from "./paths.ts";
+
+export type SettingsValue = string | number | boolean;
+export type SettingsSource = "env" | "file" | "default";
+
+export interface SettingsKeyDef {
+	/** Kebab-case CLI-facing name, e.g. "default-channel". */
+	attr: string;
+	/** QUICKCHR_* env var name. */
+	envKey: string;
+	/** Parse + validate raw input (from env or file). Throws INVALID_SETTING_VALUE on bad input. */
+	parse: (raw: string) => SettingsValue;
+	/** Canonical on-disk/display form. */
+	serialize: (value: SettingsValue) => string;
+	/** Concrete built-in default when settings get/print should report one.
+	 *  Omit only when "unset" has meaning distinct from a concrete value. */
+	builtinDefault?: SettingsValue;
+}
+
+function parseChannel(raw: string): SettingsValue {
+	if (!(CHANNELS as readonly string[]).includes(raw)) {
+		throw new QuickCHRError("INVALID_SETTING_VALUE", `Invalid value "${raw}" for default-channel — must be one of ${CHANNELS.join(", ")}`);
+	}
+	return raw;
+}
+
+function parseArchSetting(raw: string): SettingsValue {
+	const allowed = [...ARCHES, "auto"];
+	if (!allowed.includes(raw)) {
+		throw new QuickCHRError("INVALID_SETTING_VALUE", `Invalid value "${raw}" for default-arch — must be one of ${allowed.join(", ")}`);
+	}
+	return raw;
+}
+
+function parseCacheMaxSize(raw: string): SettingsValue {
+	try {
+		return parseSizeString(raw);
+	} catch (e) {
+		throw new QuickCHRError("INVALID_SETTING_VALUE", `Invalid value "${raw}" for cache-max-size — ${e instanceof Error ? e.message : String(e)}`);
+	}
+}
+
+/** Shared with the CLI's own `--timeout-extra`/`-T` flag validation (cmdStart in
+ *  src/cli/index.ts) so the same non-negative-integer rule applies whether the
+ *  value comes from a flag, QUICKCHR_TIMEOUT_EXTRA, or quickchr.env. */
+export function parseTimeoutExtraSeconds(raw: string): number {
+	const n = Number(raw);
+	if (!Number.isInteger(n) || n < 0) {
+		throw new QuickCHRError("INVALID_SETTING_VALUE", `Invalid value "${raw}" for timeout-extra — must be a non-negative integer number of seconds`);
+	}
+	return n;
+}
+
+function parseSecureLogin(raw: string): SettingsValue {
+	const v = raw.trim().toLowerCase();
+	if (["true", "1", "yes", "on"].includes(v)) return true;
+	if (["false", "0", "no", "off"].includes(v)) return false;
+	throw new QuickCHRError("INVALID_SETTING_VALUE", `Invalid value "${raw}" for secure-login — must be a boolean (true/false)`);
+}
+
+export const SETTINGS_KEYS: readonly SettingsKeyDef[] = [
+	{
+		attr: "default-channel",
+		envKey: "QUICKCHR_DEFAULT_CHANNEL",
+		builtinDefault: "stable" satisfies Channel,
+		parse: parseChannel,
+		serialize: (v) => String(v),
+	},
+	{
+		attr: "default-arch",
+		envKey: "QUICKCHR_DEFAULT_ARCH",
+		builtinDefault: "auto",
+		parse: parseArchSetting,
+		serialize: (v) => String(v),
+	},
+	{
+		attr: "cache-max-size",
+		envKey: "QUICKCHR_CACHE_MAX_SIZE",
+		builtinDefault: DEFAULT_CACHE_MAX_BYTES,
+		parse: parseCacheMaxSize,
+		serialize: (v) => String(v),
+	},
+	{
+		attr: "timeout-extra",
+		envKey: "QUICKCHR_TIMEOUT_EXTRA",
+		builtinDefault: 0,
+		parse: parseTimeoutExtraSeconds,
+		serialize: (v) => String(v),
+	},
+	{
+		// No builtinDefault: unlike the other 4 keys, the wizard needs to distinguish
+		// "not configured" from "explicitly false" (src/cli/wizard.ts's userChoice
+		// initialValue only pre-highlights "admin" when the setting is concretely
+		// false) — a builtinDefault here would collapse that distinction and always
+		// show "admin" even when nothing is configured. `resolveSecureLoginFlag`'s
+		// own `=== true` check is unaffected either way. "(unset)" in `settings print`
+		// means the consumer's own default (false / blank-admin) applies — see
+		// MANUAL.md's settings table.
+		attr: "secure-login",
+		envKey: "QUICKCHR_SECURE_LOGIN",
+		parse: parseSecureLogin,
+		serialize: (v) => (v ? "true" : "false"),
+	},
+];
+
+export const SETTINGS_FILE_NAME = "quickchr.env";
+
+/** ~/.config/quickchr/quickchr.env */
+export function settingsFilePath(): string {
+	return join(quickchrConfigDir(), SETTINGS_FILE_NAME);
+}
+
+/** Accepts "default-channel" | "QUICKCHR_DEFAULT_CHANNEL" | "DEFAULT_CHANNEL" | "default_channel". */
+export function lookupSettingsKey(input: string): SettingsKeyDef | undefined {
+	let name = input.trim();
+	if (/^quickchr[_-]/i.test(name)) {
+		name = name.replace(/^quickchr[_-]/i, "");
+	}
+	name = name.toLowerCase().replace(/_/g, "-");
+	return SETTINGS_KEYS.find((def) => def.attr === name);
+}
+
+function unknownKeyError(input: string): QuickCHRError {
+	return new QuickCHRError(
+		"INVALID_SETTING_KEY",
+		`"${input}" is not a recognized quickchr setting.`,
+		"Run 'quickchr settings print' to see the managed keys.",
+	);
+}
+
+// --- File IO ---
+
+/** Raw non-empty lines, in file order. [] if the file doesn't exist. */
+export function readSettingsFileLines(): string[] {
+	const path = settingsFilePath();
+	if (!existsSync(path)) return [];
+	const text = readFileSync(path, "utf-8");
+	const lines = text.split("\n");
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	return lines;
+}
+
+/** Parse QUICKCHR_*=value lines into a flat map. Blank/comment lines ignored; later dup wins. */
+export function parseSettingsFileLines(lines: readonly string[]): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (const rawLine of lines) {
+		const line = rawLine.trim();
+		if (line.length === 0 || line.startsWith("#")) continue;
+		const eq = line.indexOf("=");
+		if (eq <= 0) continue;
+		const key = line.slice(0, eq).trim();
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+		result[key] = line.slice(eq + 1).trim();
+	}
+	return result;
+}
+
+/** The `file` tier every resolver call reads. {} when the file is absent. */
+export function loadSettingsFileDefaults(): Record<string, string> {
+	return parseSettingsFileLines(readSettingsFileLines());
+}
+
+function lineEnvKey(line: string): string | undefined {
+	const trimmed = line.trim();
+	if (trimmed.length === 0 || trimmed.startsWith("#")) return undefined;
+	const eq = trimmed.indexOf("=");
+	if (eq <= 0) return undefined;
+	return trimmed.slice(0, eq).trim();
+}
+
+function matchingLineIndices(lines: readonly string[], envKey: string): number[] {
+	const indices: number[] = [];
+	for (let i = 0; i < lines.length; i++) {
+		if (lineEnvKey(lines[i] ?? "") === envKey) indices.push(i);
+	}
+	return indices;
+}
+
+function rawValueAtLine(lines: readonly string[], index: number): string {
+	const line = (lines[index] ?? "").trim();
+	return line.slice(line.indexOf("=") + 1).trim();
+}
+
+/** Atomic write: temp file in the same dir + fsync + rename, single .bak copy. Creates the dir on first write. */
+function writeSettingsFileLinesSync(lines: readonly string[]): void {
+	const path = settingsFilePath();
+	const dir = dirname(path);
+	mkdirSync(dir, { recursive: true });
+	if (existsSync(path)) {
+		try {
+			copyFileSync(path, `${path}.bak`);
+		} catch {
+			// best-effort
+		}
+	}
+	const content = lines.length > 0 ? `${lines.join("\n")}\n` : "";
+	const tempPath = join(dir, `.${basename(path)}.tmp.${process.pid}.${Date.now().toString(36)}`);
+	writeFileSync(tempPath, content, "utf-8");
+	const fd = openSync(tempPath, "r+");
+	try {
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+	try {
+		renameSync(tempPath, path);
+	} catch (e) {
+		try {
+			unlinkSync(tempPath);
+		} catch {
+			// ignore
+		}
+		throw e;
+	}
+}
+
+// --- Resolution ---
+
+export interface ResolvedSetting {
+	value: SettingsValue | undefined;
+	source: SettingsSource;
+}
+
+/**
+ * 3-tier resolver: env > file > builtinDefault (undefined if none). Throws
+ * INVALID_SETTING_KEY for an unrecognized attr, INVALID_SETTING_VALUE if the
+ * env var or file line's value fails validation. Never sees a CLI flag value —
+ * callers compose `flagValue ?? resolveSetting(attr).value` themselves.
+ */
+export function resolveSetting(attr: string, env: NodeJS.ProcessEnv = process.env): ResolvedSetting {
+	const def = lookupSettingsKey(attr);
+	if (!def) throw unknownKeyError(attr);
+
+	const envRaw = env[def.envKey];
+	if (envRaw !== undefined) {
+		return { value: def.parse(envRaw), source: "env" };
+	}
+
+	const fileDefaults = loadSettingsFileDefaults();
+	const fileRaw = fileDefaults[def.envKey];
+	if (fileRaw !== undefined) {
+		return { value: def.parse(fileRaw), source: "file" };
+	}
+
+	return { value: def.builtinDefault, source: "default" };
+}
+
+export interface SettingsGetResult extends ResolvedSetting {
+	key: string;
+}
+
+/** Strict — throws on an unrecognized key or a malformed env/file value. */
+export function settingsGet(attr: string, env: NodeJS.ProcessEnv = process.env): SettingsGetResult {
+	const def = lookupSettingsKey(attr);
+	if (!def) throw unknownKeyError(attr);
+	return { key: def.attr, ...resolveSetting(attr, env) };
+}
+
+/** Tolerant — a malformed single value reports its raw string + source rather than throwing,
+ *  so one bad line doesn't break the whole table. */
+export function settingsPrint(env: NodeJS.ProcessEnv = process.env): SettingsGetResult[] {
+	return SETTINGS_KEYS.map((def) => {
+		try {
+			return { key: def.attr, ...resolveSetting(def.attr, env) };
+		} catch {
+			const envRaw = env[def.envKey];
+			if (envRaw !== undefined) return { key: def.attr, value: envRaw, source: "env" as const };
+			const fileRaw = loadSettingsFileDefaults()[def.envKey];
+			return { key: def.attr, value: fileRaw, source: "file" as const };
+		}
+	});
+}
+
+export interface SettingsSetResult {
+	key: string;
+	previous: SettingsValue | undefined;
+	value: SettingsValue;
+}
+
+/** Validates, writes ONE line, preserves all other file content (comments, blank lines,
+ *  foreign vars) byte-for-byte verbatim. */
+export function settingsSet(attr: string, rawValue: string): SettingsSetResult {
+	const def = lookupSettingsKey(attr);
+	if (!def) throw unknownKeyError(attr);
+
+	const parsed = def.parse(rawValue);
+
+	const lines = readSettingsFileLines();
+	const indices = matchingLineIndices(lines, def.envKey);
+	const index = indices.at(-1) ?? -1;
+	const previousRaw = index >= 0 ? rawValueAtLine(lines, index) : undefined;
+	let previous: SettingsValue | undefined;
+	if (previousRaw !== undefined) {
+		try {
+			previous = def.parse(previousRaw);
+		} catch {
+			previous = previousRaw;
+		}
+	}
+
+	const newLine = `${def.envKey}=${def.serialize(parsed)}`;
+	if (index >= 0) {
+		lines[index] = newLine;
+		for (let i = indices.length - 2; i >= 0; i--) {
+			lines.splice(indices[i] ?? -1, 1);
+		}
+	} else {
+		lines.push(newLine);
+	}
+	writeSettingsFileLinesSync(lines);
+
+	return { key: def.attr, previous, value: parsed };
+}
+
+export interface SettingsResetResult {
+	cleared: string[];
+}
+
+/** No attr → clears every managed-key line, preserving foreign/comment lines. reset ALWAYS
+ *  deletes the line, never blanks it (a blank "KEY=" line is still "set" to a bash-sourced file). */
+export function settingsReset(attr?: string): SettingsResetResult {
+	if (attr !== undefined) {
+		const def = lookupSettingsKey(attr);
+		if (!def) throw unknownKeyError(attr);
+		const lines = readSettingsFileLines();
+		const indices = matchingLineIndices(lines, def.envKey);
+		if (indices.length === 0) return { cleared: [] };
+		for (let i = indices.length - 1; i >= 0; i--) {
+			lines.splice(indices[i] ?? -1, 1);
+		}
+		writeSettingsFileLinesSync(lines);
+		return { cleared: [def.attr] };
+	}
+
+	const lines = readSettingsFileLines();
+	const managedEnvKeys = new Map(SETTINGS_KEYS.map((def) => [def.envKey, def.attr]));
+	const cleared: string[] = [];
+	const kept = lines.filter((line) => {
+		const trimmed = line.trim();
+		if (trimmed.length === 0 || trimmed.startsWith("#")) return true;
+		const eq = trimmed.indexOf("=");
+		if (eq <= 0) return true;
+		const key = trimmed.slice(0, eq).trim();
+		const attrName = managedEnvKeys.get(key);
+		if (attrName === undefined) return true;
+		cleared.push(attrName);
+		return false;
+	});
+	if (cleared.length > 0) {
+		writeSettingsFileLinesSync(kept);
+	}
+	return { cleared };
+}

package/src/lib/state.ts

@@ -2,7 +2,7 @@
  * Machine state persistence — JSON files in ~/.local/share/quickchr/machines/.
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync, statSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync, statSync } from "node:fs";
 import { join, } from "node:path";
 import type { MachineState, } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
@@ -24,6 +24,47 @@ export function getMachinesDir(): string {
 	return join(getDataDir(), "machines");
 }
 
+/** One line per successful boot, appended to <dataDir>/boot-log.ndjson — local
+ *  boot-history for users ("how slow are my boots") and the durable CI metrics
+ *  feed (machine dirs are removed by tests, machine.json alone is not enough). */
+export interface BootLogEntry {
+	ts: string;
+	name: string;
+	version: string;
+	arch: string;
+	accel: string;
+	bootMs: number;
+	/** Host platform, `process.platform` ("linux" | "darwin" | "win32"). */
+	host: string;
+}
+
+const BOOT_LOG_MAX_LINES = 1000;
+const BOOT_LOG_KEEP_LINES = 500;
+
+/** Path to the boot-history log. */
+export function bootLogPath(): string {
+	return join(getDataDir(), "boot-log.ndjson");
+}
+
+/** Append a boot record; rotates to the newest BOOT_LOG_KEEP_LINES when the
+ *  log exceeds BOOT_LOG_MAX_LINES.
+ *
+ *  Append-first (single appendFileSync call, atomic for one-line writes on
+ *  every platform we run on) so concurrent boots — parallel bun test workers
+ *  each booting a CHR — never clobber each other's entries in the common path.
+ *  Only the rare rotation (once per ~500 boots) does a read-rewrite; an append
+ *  racing that millisecond window CAN be lost. Accepted: this is a boot-history
+ *  metrics log, not a ledger, and a lockfile is not worth the complexity. */
+export function appendBootLog(entry: BootLogEntry): void {
+	const path = bootLogPath();
+	ensureDir(getDataDir());
+	appendFileSync(path, `${JSON.stringify(entry)}\n`);
+	const lines = readFileSync(path, "utf-8").split("\n").filter(Boolean);
+	if (lines.length > BOOT_LOG_MAX_LINES) {
+		writeFileSync(path, `${lines.slice(-BOOT_LOG_KEEP_LINES).join("\n")}\n`);
+	}
+}
+
 /** Get the cache directory. */
 export function getCacheDir(): string {
 	return join(getDataDir(), "cache");

package/src/lib/types.ts

@@ -25,17 +25,44 @@ export type NetworkMode =
  * Network specifier — expresses user intent for a network interface.
  * Generic specifiers (user, socket, shared, bridged) are cross-platform;
  * explicit specifiers (vmnet-shared, vmnet-bridged, tap) bypass platform resolution.
+ *
+ * Pick by traffic shape (full guide: `docs/networking-recipes.md`):
+ * - **Management / host→guest TCP+UDP services** → `"user"` (SLIRP + `hostfwd`).
+ *   Keep `"user"` first (ether1) so RouterOS' DHCP client gets `10.0.2.15`.
+ * - **Host needs to see guest L2 frames** (MNDP, MAC-Telnet, raw Ethernet,
+ *   broadcasts) → `{type:"socket-connect", port}` against a host TCP server
+ *   (rootless, cross-platform; recipe in `docs/mndp.md`).
+ * - **L2 link between two VMs** → `{type:"socket", name}` (named pair) or
+ *   `socket-listen`/`socket-connect`/`socket-mcast` (low-level).
+ * - **Real LAN / DHCP-from-host presence** → `"shared"` or `{type:"bridged", iface}`
+ *   (rootless via socket_vmnet on macOS / pre-created TAP on Linux).
+ *
+ * Note: receiving guest-*originated* UDP (e.g. a guest replying to `10.0.2.2`)
+ * needs no extra NIC and no forward — see {@link ChrInstance.tzspGatewayIp}.
  */
 export type NetworkSpecifier =
+	/** SLIRP user-mode NAT + `hostfwd` port mapping. Management default; the only
+	 *  NIC that makes `extraPorts`/`--forward` reachable. Terminates Layer 2. */
 	| "user"
+	/** L2 socket pair between two VMs sharing a registered `name` (`quickchr networks sockets`). */
 	| { type: "socket"; name: string }
+	/** Low-level QEMU `socket` netdev that binds and listens (`0.0.0.0:port`). */
 	| { type: "socket-listen"; port: number }
+	/** Low-level QEMU `socket` netdev that connects to `127.0.0.1:port`. The
+	 *  rootless, cross-platform way for a host process to receive guest L2 frames. */
 	| { type: "socket-connect"; port: number }
+	/** Multi-VM L2 segment over UDP multicast. Works on Linux/CI; **broken on macOS**
+	 *  (QEMU sets only `SO_REUSEADDR`). */
 	| { type: "socket-mcast"; group: string; port: number }
+	/** NAT'd L3 with DHCP from the host; resolves to socket_vmnet/vmnet (macOS) or TAP (Linux). */
 	| "shared"
+	/** L2 bridged onto a host interface; resolves like `"shared"` but bridged. */
 	| { type: "bridged"; iface: string }
+	/** Explicit macOS vmnet-shared (bypasses resolution; runs QEMU as root). */
 	| "vmnet-shared"
+	/** Explicit macOS vmnet-bridged (bypasses resolution; runs QEMU as root). */
 	| { type: "vmnet-bridged"; iface: string }
+	/** Pre-created user-owned TAP on Linux (no quickchr setup). */
 	| { type: "tap"; ifname: string };
 
 /** Result of resolving a NetworkSpecifier on a specific platform. */
@@ -82,10 +109,24 @@ export interface SocketVmnetInfo {
 	bridgedSockets: Record<string, string>;
 }
 
+/** A single host→guest port forward, realized as one QEMU SLIRP `hostfwd`
+ *  directive (`hostfwd=<proto>::<host>-:<guest>`).
+ *
+ *  This is the programmatic equivalent of one CLI `--forward` spec. Build them
+ *  by hand, or parse spec strings with {@link parseForwardSpec} (single port) /
+ *  {@link expandForwardSpec} (port ranges). Forwards only reach the guest over a
+ *  user-mode (`"user"`) NIC — see the networking recipes guide
+ *  (`docs/networking-recipes.md`) for which mechanism fits which traffic shape. */
 export interface PortMapping {
+	/** Label for this forward; also the key in `MachineState.ports` and what
+	 *  `quickchr list` shows. Must be unique within a machine. */
 	name: string;
+	/** Host-side port. `0` (or omitted) auto-allocates from the instance's port block. */
 	host: number;
+	/** Guest-side (RouterOS) port the forward targets. */
 	guest: number;
+	/** Transport — carried verbatim into the `hostfwd` directive. `udp` is fully
+	 *  supported (e.g. SNMP, syslog, bandwidth-test data ports). */
 	proto: "tcp" | "udp";
 }
 
@@ -181,6 +222,10 @@ export interface MachineState extends MachineConfig {
 	pid?: number;
 	/** Path to the machine directory. */
 	machineDir: string;
+	/** Accelerator resolved for the most recent boot ("kvm" | "hvf" | "tcg"). */
+	lastAccel?: string;
+	/** Wall-clock ms from QEMU spawn to REST-ready for the most recent boot. */
+	lastBootMs?: number;
 }
 
 // --- Start Options ---
@@ -241,13 +286,38 @@ export interface StartOptions {
 	portBase?: number;
 	/** Services to exclude from port mappings (e.g. ["winbox", "api-ssl"]). */
 	excludePorts?: ServiceName[];
-	/** Additional custom port mappings appended to the default set. */
+	/** Additional host→guest port forwards appended to the default service set —
+	 *  the library equivalent of the CLI `--forward` flag. Each becomes one SLIRP
+	 *  `hostfwd` directive and only works over a `"user"` NIC.
+	 *
+	 *  `proto` may be `"tcp"` or `"udp"`. To turn CLI-style spec strings into this
+	 *  array, use {@link parseForwardSpec} (single port) or {@link expandForwardSpec}
+	 *  (port ranges, e.g. dynamic UDP data ports). `WELL_KNOWN_GUEST_PORTS` /
+	 *  {@link lookupGuestPort} resolve guest port + proto for common service names.
+	 *
+	 *  For *receiving* guest-originated UDP (no forward needed), see
+	 *  {@link ChrInstance.tzspGatewayIp} and `docs/networking-recipes.md`.
+	 *  @example
+	 *  extraPorts: [{ name: "snmp", host: 9161, guest: 161, proto: "udp" }]
+	 *  @example
+	 *  // dynamic UDP data ports via a range spec:
+	 *  extraPorts: expandForwardSpec("btest:9200-9210:2000-2010/udp")
+	 */
 	extraPorts?: PortMapping[];
 	/** @deprecated Use `networks` instead. Kept for backward compatibility. */
 	network?: NetworkMode;
-	/** Network interfaces. Each entry becomes a NIC on the CHR.
-	 *  Default (when omitted): single user-mode NIC.
-	 *  When specified: count of entries = count of NICs (explicit control). */
+	/** Network interfaces — the library equivalent of repeated `--add-network` flags.
+	 *  Each entry becomes a NIC on the CHR, in order (so `networks[0]` is ether1).
+	 *  Default (when omitted): a single `"user"` NIC.
+	 *  When specified: count of entries = count of NICs (explicit control).
+	 *
+	 *  Keep `"user"` first for management/`hostfwd`; add a second NIC for L2 work.
+	 *  See {@link NetworkSpecifier} for which specifier fits which traffic shape,
+	 *  and `docs/networking-recipes.md` / `docs/mndp.md` for runnable recipes.
+	 *  @example
+	 *  // management + host-visible L2 (e.g. to receive MNDP on the host):
+	 *  networks: ["user", { type: "socket-connect", port: hostTcpServerPort }]
+	 */
 	networks?: NetworkSpecifier[];
 	/** Install OS-level dependencies (QEMU, firmware) automatically if missing. */
 	installDeps?: boolean;
@@ -361,10 +431,19 @@ export interface ChrInstance {
 	 *  Pass directly to tshark: `tshark -i ${instance.captureInterface} -f "udp port 37008"`
 	 *  Only meaningful when the instance has a user-mode (`"user"`) network interface. */
 	captureInterface: string;
-	/** QEMU user-mode networking gateway IP — the host's address as seen from inside the VM.
-	 *  Use this as the RouterOS `/tool/sniffer` streaming-server target so TZSP traffic
-	 *  reaches the host. Always `"10.0.2.2"` for QEMU slirp user-mode networking.
+	/** QEMU user-mode (SLIRP) gateway IP — the host's address as seen from inside the VM.
+	 *  Always `"10.0.2.2"` for QEMU slirp user-mode networking.
+	 *
+	 *  This is the general **guest→host UDP** primitive, not just for TZSP: any
+	 *  datagram the guest sends to `10.0.2.2:<port>` is delivered to a host process
+	 *  bound on loopback at `<port>` (capture it on {@link captureInterface}) with
+	 *  **no `hostfwd` and no extra NIC**. The host socket must be left **unconnected**
+	 *  (use `recvfrom`, not `connect`) — a connected socket filters out the
+	 *  gateway-origin datagrams. This covers guest-originated UDP (syslog, NetFlow,
+	 *  TZSP) and a guest server replying to the gateway. Recipe + lab evidence:
+	 *  `docs/networking-recipes.md`, `examples/udp-gateway/`.
 	 *  @example
+	 *  // RouterOS TZSP sniffer streaming to the host:
 	 *  await instance.exec(`/tool/sniffer/set streaming-server=${instance.tzspGatewayIp}:37008`);
 	 */
 	tzspGatewayIp: string;
@@ -575,7 +654,10 @@ export type ErrorCode =
 	| "INVALID_FORWARD_SPEC"
 	| "PROVISIONING_VERSION_UNSUPPORTED"
 	| "INSUFFICIENT_DISK_SPACE"
-	| "STATE_ERROR";
+	| "STATE_ERROR"
+	| "INVALID_SIZE_STRING"
+	| "INVALID_SETTING_KEY"
+	| "INVALID_SETTING_VALUE";
 
 export class QuickCHRError extends Error {
 	code: ErrorCode;