@tikoci/quickchr 0.4.7 → 0.4.8

package/src/lib/state.ts

@@ -7,6 +7,7 @@ import { join, } from "node:path";
 import type { MachineState, } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
 import { networkModeToConfigs } from "./network.ts";
+import { assertPathSafeName, isPathSafeName } from "./names.ts";
 
 /** Get the quickchr data directory root. Override with QUICKCHR_DATA_DIR env var. */
 export function getDataDir(): string {
@@ -91,12 +92,72 @@ export function saveMachine(state: MachineState): void {
 	writeFileSync(machineJsonPath(state.name), JSON.stringify(state, null, "\t") + "\n");
 }
 
-/** Load machine state from disk. Returns undefined if not found. */
+/** The fields every caller dereferences without guarding, with the `typeof` each must
+ *  answer. Deliberately not a schema: it is the set that turns a bad file into a crash
+ *  somewhere else, which is the thing being prevented. `cpu`/`mem` are absent because a
+ *  missing one prints oddly rather than throwing, and a narrow check cannot wrongly
+ *  condemn a machine that works today. `networks` is absent because `loadMachine()`
+ *  migrates it just below.
+ *
+ *  Every field listed here has been required on `MachineState` since the commit that
+ *  introduced it (5cfe052), so no `machine.json` any version of quickchr wrote can be
+ *  condemned by this check — which is the thing that would make it worse than the bug
+ *  it fixes. */
+const REQUIRED_STATE_FIELDS: ReadonlyArray<[keyof MachineState, "string" | "number" | "object"]> = [
+	["name", "string"],
+	["version", "string"],
+	["arch", "string"],
+	["status", "string"],
+	["machineDir", "string"],
+	["portBase", "number"],
+	["ports", "object"],
+	["packages", "object"],
+];
+
+/** Why `parsed` is not usable as a `MachineState`, or `undefined` when it is.
+ *
+ *  Parsing successfully is not the same as being state. `{"name":"lab"}` parses, and
+ *  `JSON.parse` is happy with `null` and `[]` too; casting any of them to `MachineState`
+ *  only moves the failure — `{"name":"lab"}` reached `formatPorts(m.ports)` and aborted
+ *  `quickchr list` exactly as an unparseable file used to (#165). */
+function stateShapeProblem(parsed: unknown): string | undefined {
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return "not a JSON object";
+	}
+	const record = parsed as Record<string, unknown>;
+	const bad = REQUIRED_STATE_FIELDS
+		.filter(([key, kind]) => typeof record[key] !== kind || record[key] === null)
+		.map(([key]) => key);
+	return bad.length > 0 ? `missing or invalid: ${bad.join(", ")}` : undefined;
+}
+
+/** Load machine state from disk. Returns undefined if not found.
+ *
+ *  Throws `STATE_ERROR` when the file is there but unusable. A targeted lookup by name
+ *  has to fail: the caller named *this* machine, and answering `undefined` would report
+ *  a machine that exists on disk as one that never did. `loadAllMachines()` is the
+ *  enumeration and takes the other policy — see `tryLoadMachine()` (#165). */
 export function loadMachine(name: string): MachineState | undefined {
 	const path = machineJsonPath(name);
 	if (!existsSync(path)) return undefined;
-	const data = readFileSync(path, "utf-8");
-	const state = JSON.parse(data) as MachineState;
+	let state: MachineState;
+	try {
+		state = JSON.parse(readFileSync(path, "utf-8")) as MachineState;
+	} catch (e) {
+		throw new QuickCHRError(
+			"STATE_ERROR",
+			`Machine "${name}" has an unreadable machine.json (${e instanceof Error ? e.message : String(e)})`,
+			`Inspect ${path}, or clear the machine with 'quickchr remove ${name}'`,
+		);
+	}
+	const shapeProblem = stateShapeProblem(state);
+	if (shapeProblem) {
+		throw new QuickCHRError(
+			"STATE_ERROR",
+			`Machine "${name}" has an unreadable machine.json (${shapeProblem})`,
+			`Inspect ${path}, or clear the machine with 'quickchr remove ${name}'`,
+		);
+	}
 	// Migrate legacy `network` field → `networks` array
 	if (!state.networks && (state as unknown as Record<string, unknown>).network) {
 		const legacy = (state as unknown as Record<string, unknown>).network as MachineState["networks"][0]["specifier"] | "user" | "vmnet-shared" | { type: "vmnet-bridge"; iface: string };
@@ -107,7 +168,33 @@ export function loadMachine(name: string): MachineState | undefined {
 	return state;
 }
 
-/** Load all machine states. */
+/** The three things a machine directory can turn out to be.
+ *
+ *  `loadMachine()` collapses `missing` and `unreadable` into "undefined or throw", which
+ *  is the right contract for a lookup and the wrong one for an enumeration. This keeps
+ *  them apart so each caller can pick (#165). Internal for now: promoting it to public
+ *  API is a rename if #58 lands. */
+type MachineLoad =
+	| { status: "ok"; state: MachineState }
+	| { status: "missing" }
+	| { status: "unreadable"; error: string };
+
+/** `loadMachine()` without the throw. */
+function tryLoadMachine(name: string): MachineLoad {
+	try {
+		const state = loadMachine(name);
+		return state ? { status: "ok", state } : { status: "missing" };
+	} catch (e) {
+		return { status: "unreadable", error: e instanceof Error ? e.message : String(e) };
+	}
+}
+
+/** Load all machine states, skipping directories with no usable `machine.json`.
+ *
+ *  An enumeration is best-effort across many: one corrupt file used to abort the whole
+ *  listing, which loses the state of every healthy machine as well. Nothing is hidden by
+ *  the skip — `listUnreadableMachines()` names what was left out, and `quickchr list`
+ *  shows it as a row (#165). */
 export function loadAllMachines(): MachineState[] {
 	const dir = getMachinesDir();
 	if (!existsSync(dir)) return [];
@@ -117,13 +204,27 @@ export function loadAllMachines(): MachineState[] {
 
 	for (const entry of entries) {
 		if (!entry.isDirectory()) continue;
-		const state = loadMachine(entry.name);
-		if (state) machines.push(state);
+		const loaded = tryLoadMachine(entry.name);
+		if (loaded.status === "ok") machines.push(loaded.state);
 	}
 
 	return machines;
 }
 
+/** Every machine directory whose `machine.json` exists but cannot be read.
+ *
+ *  Distinct from `listOrphanMachineDirs()`, which also counts a directory with no
+ *  `machine.json` at all — a create that never finished. This one is a machine that did
+ *  exist and whose state went bad, so it still holds a disk image worth naming. */
+export function listUnreadableMachines(): Array<{ name: string; error: string }> {
+	const out: Array<{ name: string; error: string }> = [];
+	for (const name of listMachineNames()) {
+		const loaded = tryLoadMachine(name);
+		if (loaded.status === "unreadable") out.push({ name, error: loaded.error });
+	}
+	return out;
+}
+
 /** Get all existing machine names. */
 export function listMachineNames(): string[] {
 	const dir = getMachinesDir();
@@ -133,13 +234,53 @@ export function listMachineNames(): string[] {
 		.map((e) => e.name);
 }
 
+/** True when `name` has a machine directory but no readable `machine.json` — a create
+ *  that did not finish. `list` cannot show it and `start` cannot boot it, but
+ *  `listMachineNames()` (directory-based) still counts it, so it blocks re-add (#155). */
+export function isOrphanMachineDir(name: string): boolean {
+	// A traversal name resolves to a directory that exists and holds no machine.json —
+	// the data dir itself, for ".." — so the path check has to come first or the
+	// predicate answers "orphan" about something that is not a machine directory.
+	if (!isPathSafeName(name)) return false;
+	const dir = getMachineDir(name);
+	if (!existsSync(dir)) return false;
+	return !isReadableMachine(name);
+}
+
+/** Every machine directory with no readable `machine.json`. */
+export function listOrphanMachineDirs(): string[] {
+	return listMachineNames().filter((name) => !isReadableMachine(name));
+}
+
+/** A truncated or corrupt `machine.json` is as unusable as a missing one, and both make
+ *  the directory an orphan. */
+function isReadableMachine(name: string): boolean {
+	return tryLoadMachine(name).status === "ok";
+}
+
 /** Get all port bases currently in use by existing machines. */
 export function getUsedPortBases(): number[] {
 	return loadAllMachines().map((m) => m.portBase);
 }
 
+/** Every NIC MAC currently assigned across all machines.
+ *  Passed to `assignMacs()` so a new machine cannot be handed an address another
+ *  machine already presents on a shared L2 segment (#154). */
+export function getUsedMacs(): Set<string> {
+	const macs = new Set<string>();
+	for (const m of loadAllMachines()) {
+		for (const n of m.networks ?? []) {
+			if (n.mac) macs.add(n.mac);
+		}
+	}
+	return macs;
+}
+
 /** Delete a machine and all its files. */
 export function removeMachine(name: string): void {
+	// This is an `rmSync(..., { recursive: true })`; the name must never be able to
+	// point outside machines/<name>/.
+	assertPathSafeName(name, "machine");
 	const dir = getMachineDir(name);
 	if (!existsSync(dir)) {
 		throw new QuickCHRError("MACHINE_NOT_FOUND", `Machine "${name}" not found`);

package/src/lib/types.ts

@@ -55,13 +55,14 @@ export type NetworkMode =
  * - **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).
+ * - **L2 link between two VMs** → `{type:"socket", name}`, a named link whose
+ *   transport (`dgram`, `listen-connect`, `mcast`) is fixed when the name is created;
+ *   or `socket-listen`/`socket-connect`/`socket-mcast` for a raw netdev.
  * - **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}.
+ * needs no extra NIC and no forward — see {@link ChrInstance.hostGatewayIp}.
  */
 export type NetworkSpecifier =
 	/** SLIRP user-mode NAT + `hostfwd` port mapping. Management default; the only
@@ -106,6 +107,12 @@ export interface NetworkConfig {
 	specifier: NetworkSpecifier;
 	/** QEMU netdev id (net0, net1, ...). */
 	id: string;
+	/** Locally-administered MAC, assigned at creation and persisted so it survives
+	 *  restart. Without it QEMU hands every guest the same default sequence and two
+	 *  machines on one L2 segment collide — see `deriveMac` in `network.ts` (#154).
+	 *  Never reassigned: changing it on a booted machine orphans RouterOS's interface
+	 *  identity. Absent on machines created before #154, which keep QEMU's defaults. */
+	mac?: string;
 	/** Resolved QEMU args (populated at launch time, not persisted). */
 	resolved?: ResolvedNetwork;
 }
@@ -170,6 +177,11 @@ export const SERVICE_NAMES = Object.keys(SERVICE_PORTS) as ServiceName[];
 export const PORTS_PER_BLOCK = 10;
 export const DEFAULT_PORT_BASE = 9100;
 
+/** QEMU user-mode (SLIRP) gateway — the host's address as seen from inside a guest.
+ *  Fixed by QEMU's built-in 10.0.2.0/24 user network; surfaced on a running instance
+ *  as {@link ChrInstance.hostGatewayIp}. */
+export const HOST_GATEWAY_IP = "10.0.2.2";
+
 /**
  * TCP endpoint for QEMU IPC channels on Windows.
  * Used instead of named pipes when QEMU's Winsock bind() can't handle \\.\pipe\ paths.
@@ -341,7 +353,7 @@ export interface StartOptions {
 	 *  {@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`.
+	 *  {@link ChrInstance.hostGatewayIp} and `docs/networking-recipes.md`.
 	 *  @example
 	 *  extraPorts: [{ name: "snmp", host: 9161, guest: 161, proto: "udp" }]
 	 *  @example
@@ -591,8 +603,16 @@ export interface ChrInstance {
 	 *  `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`);
+	 *  await instance.exec(`/tool/sniffer/set streaming-server=${instance.hostGatewayIp}:37008`);
 	 */
+	hostGatewayIp: string;
+	/** @deprecated Renamed to {@link ChrInstance.hostGatewayIp} — the value was never
+	 *  TZSP-specific, it is the host as seen from inside the guest and carries any
+	 *  guest→host UDP (remote syslog, NetFlow, a plain socket). The old name led
+	 *  readers to assume a sniffer-only primitive.
+	 *
+	 *  Still populated with the identical value, and will be removed no earlier than
+	 *  the next minor. Migration is a rename at the call site — nothing else changes. */
 	tzspGatewayIp: string;
 
 	/** Check or wait for REST API readiness.
@@ -805,6 +825,10 @@ export type ErrorCode =
 	| "INVALID_VERSION"
 	| "INVALID_ARCH"
 	| "INVALID_NAME"
+	// A flag or argument the CLI cannot honour as written — a removed flag name, or a
+	// value it will not accept. Distinct from INVALID_SETTING_VALUE, which is about a
+	// stored setting rather than what was typed.
+	| "INVALID_ARGUMENT"
 	| "INVALID_DISK_SIZE"
 	| "MACHINE_LOCKED"
 	| "EXEC_FAILED"