@tikoci/quickchr 0.2.0

package/src/index.ts

@@ -0,0 +1,124 @@
+/**
+ * @module @tikoci/quickchr
+ *
+ * CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU.
+ *
+ * ## Quick start
+ * ```ts
+ * import { QuickCHR } from "@tikoci/quickchr";
+ *
+ * const chr = await QuickCHR.start({ channel: "stable" });
+ * const info = await chr.rest("/system/resource");
+ * console.log(info);
+ * await chr.remove();
+ * ```
+ *
+ * ## Key exports
+ * - {@link QuickCHR} — Main class with static methods: `start()`, `add()`, `list()`, `get()`, `doctor()`
+ * - {@link ChrInstance} — Runtime handle returned by `start()`: `stop()`, `remove()`, `rest()`, `exec()`, `snapshot`, etc.
+ * - {@link StartOptions} — All options for creating/starting a CHR instance
+ * - {@link QuickCHRError} — Typed errors with codes like `MISSING_QEMU`, `TIMEOUT`, `EXEC_FAILED`
+ *
+ * @packageDocumentation
+ */
+
+// Main class
+export { QuickCHR } from "./lib/quickchr.ts";
+
+// Types
+export type {
+	Arch,
+	BootDiskFormat,
+	Channel,
+	ChrInstance,
+	ChrPorts,
+	DeviceModeOptions,
+	DoctorCheck,
+	DoctorResult,
+	EfiFirmwarePaths,
+	ExecOptions,
+	ExecResult,
+	ExecTransport,
+	ChrLoadSample,
+	LicenseInput,
+	LicenseLevel,
+	LicenseOptions,
+	MachineConfig,
+	MachineState,
+	NetworkConfig,
+	NetworkMode,
+	NetworkSpecifier,
+	PackageManager,
+	PlatformInfo,
+	PortMapping,
+	QgaCommand,
+	QgaExecResult,
+	QgaFsFreezeStatus,
+	QgaNetworkInterface,
+	QgaNetworkIpAddress,
+	QgaOsInfo,
+	QgaTimezone,
+	ServiceName,
+	SnapshotInfo,
+	StartOptions,
+} from "./lib/types.ts";
+
+export { QuickCHRError } from "./lib/types.ts";
+export type { ErrorCode, HostInterface } from "./lib/types.ts";
+
+// Interface detection
+export { detectPhysicalInterfaces, resolveInterfaceAlias } from "./lib/platform.ts";
+
+// Disk utilities
+export { getDiskInfo, createQcow2Disk, listSnapshots, parseSnapshotList, formatSnapshotTable, formatDiskSize } from "./lib/disk.ts";
+export type { DiskInfo } from "./lib/disk.ts";
+
+// Auth utilities
+export { resolveAuth } from "./lib/auth.ts";
+export type { ResolvedAuth } from "./lib/auth.ts";
+
+// Exec utilities
+export { restExecute } from "./lib/exec.ts";
+
+// QGA (QEMU Guest Agent) utilities
+export {
+	qgaExec,
+	qgaProbe,
+	qgaSync,
+	qgaInfo,
+	qgaPing,
+	qgaGetOsInfo,
+	qgaGetHostName,
+	qgaGetTime,
+	qgaGetTimezone,
+	qgaGetNetworkInterfaces,
+	qgaFsFreezeStatus,
+	qgaFsFreezeFreeze,
+	qgaFsFreezeThaw,
+	qgaShutdown,
+	qgaFileWrite,
+	qgaFileRead,
+} from "./lib/qga.ts";
+export type { QgaCommandInfo } from "./lib/qga.ts";
+
+// Console exec utilities
+export { consoleExec, isConsoleReady, stripAnsi } from "./lib/console.ts";
+
+// Channel utilities
+export { isQgaReady } from "./lib/channels.ts";
+
+// License utilities
+export { renewLicense, getLicenseInfo } from "./lib/license.ts";
+export type { LicenseInfo } from "./lib/license.ts";
+
+// Credential utilities
+export { getStoredCredentials, saveCredentials, deleteCredentials, credentialStorageLabel } from "./lib/credentials.ts";
+export { getInstanceCredentials, saveInstanceCredentials, deleteInstanceCredentials } from "./lib/credentials.ts";
+export type { MikrotikCredentials, InstanceCredentials } from "./lib/credentials.ts";
+
+// Package utilities
+export { downloadPackages, listAvailablePackages, downloadAndListPackages, installPackages, installAllPackages } from "./lib/packages.ts";
+
+// Logging
+export { createLogger } from "./lib/log.ts";
+export type { ProgressLogger } from "./lib/log.ts";

package/src/lib/auth.ts

@@ -0,0 +1,68 @@
+/**
+ * Credential resolution for CHR instances.
+ *
+ * Centralises the logic for choosing which username:password to use when
+ * talking to a running RouterOS instance.  Today this is a thin helper;
+ * it becomes the extension point for credential profiles, SSH keys, and
+ * user-preference overrides.
+ */
+
+import type { MachineState } from "./types.ts";
+import { getInstanceCredentials } from "./credentials.ts";
+
+export interface ResolvedAuth {
+	/** HTTP Basic Authorization header value. */
+	header: string;
+	/** Username that was resolved (for display / logging). */
+	user: string;
+}
+
+/**
+ * Resolve the best credentials for a machine.
+ *
+ * Priority:
+ *   1. Explicit overrides (`user` + `password` args) — caller knows best.
+ *   2. Provisioned user stored in machine.json (`state.user`).
+ *   3. Per-instance credentials stored in config file (written during provisioning).
+ *   4. CHR default: `admin` with empty password.
+ *
+ * When `state.disableAdmin` is true and no provisioned user exists the
+ * default admin credentials are unlikely to work.  We still return them
+ * (the caller will get a 401) rather than throwing — the caller may have
+ * re-enabled admin or created a user out-of-band.
+ */
+export function resolveAuth(
+	state: Pick<MachineState, "name" | "user" | "disableAdmin">,
+	user?: string,
+	password?: string,
+): ResolvedAuth {
+	if (user !== undefined) {
+		return {
+			header: `Basic ${btoa(`${user}:${password ?? ""}`)}`,
+			user,
+		};
+	}
+
+	// state.user is the canonical provisioned user written to machine.json.
+	// Check this first — no I/O, no keychain, no blocking.
+	if (state.user) {
+		return {
+			header: `Basic ${btoa(`${state.user.name}:${state.user.password}`)}`,
+			user: state.user.name,
+		};
+	}
+
+	// Check per-instance credentials stored in config file (sync, no keychain).
+	const stored = getInstanceCredentials(state.name);
+	if (stored) {
+		return {
+			header: `Basic ${btoa(`${stored.user}:${stored.password}`)}`,
+			user: stored.user,
+		};
+	}
+
+	return {
+		header: `Basic ${btoa("admin:")}`,
+		user: "admin",
+	};
+}

package/src/lib/channels.ts

@@ -0,0 +1,222 @@
+/**
+ * Communication channels — QEMU monitor, serial console, QGA (QEMU Guest Agent).
+ *
+ * Uses Unix domain sockets stored in the machine directory.
+ * QGA protocol implementation lives in qga.ts — this module provides
+ * the high-level qgaCommand() wrapper with arch guards and path resolution.
+ */
+
+import { existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import { connect } from "node:net";
+import type { Arch, ChannelTcpEndpoint, QgaCommand } from "./types.ts";
+import { QuickCHRError } from "./types.ts";
+import { qgaProbe, qgaRawCommand } from "./qga.ts";
+import { qgaKvmWarning } from "./platform.ts";
+
+/**
+ * Resolve the IPC path for a QEMU channel (monitor, serial, qga).
+ * On Unix: a .sock file in machineDir.
+ * On Windows: a named pipe — both QEMU and Node.js net.connect() recognize \\.\pipe\ paths.
+ */
+export function channelPath(machineDir: string, channel: "monitor" | "serial" | "qga"): string {
+	if (process.platform === "win32") {
+		return `\\\\.\\pipe\\quickchr-${basename(machineDir)}-${channel}`;
+	}
+	return join(machineDir, `${channel}.sock`);
+}
+
+/**
+ * Resolve the IPC connection options for a QEMU channel.
+ * On Windows with a portBase, returns a TCP endpoint (QEMU's Winsock bind() can't handle named pipes).
+ * Otherwise returns the socket path string (Unix socket or Windows named pipe fallback).
+ */
+export function channelEndpoint(
+	machineDir: string,
+	channel: "monitor" | "serial" | "qga",
+	portBase?: number,
+): string | ChannelTcpEndpoint {
+	if (process.platform === "win32" && portBase !== undefined) {
+		const OFFSETS: Record<string, number> = { monitor: 6, serial: 7, qga: 8 };
+		return { host: "127.0.0.1", port: portBase + (OFFSETS[channel] ?? 6) };
+	}
+	return channelPath(machineDir, channel);
+}
+
+/** Return true if the channel IPC endpoint can be checked via existsSync (Unix only). */
+export function channelFileExists(path: string): boolean {
+	if (process.platform === "win32") {
+		// Named pipes don't appear as regular filesystem entries — let connect() fail instead.
+		return true;
+	}
+	return existsSync(path);
+}
+
+/** Send a command to the QEMU monitor and return the response. */
+export async function monitorCommand(
+	machineDir: string,
+	command: string,
+	timeoutMs: number = 5000,
+	portBase?: number,
+): Promise<string> {
+	const socketPath = channelPath(machineDir, "monitor");
+	if (!channelFileExists(socketPath)) {
+		throw new QuickCHRError(
+			"MACHINE_STOPPED",
+			"Monitor socket not found — is the machine running in background mode?",
+		);
+	}
+
+	const endpoint = channelEndpoint(machineDir, "monitor", portBase);
+
+	return new Promise((resolve, reject) => {
+		const timeout = setTimeout(() => {
+			socket.destroy();
+			reject(new QuickCHRError("BOOT_TIMEOUT", "Monitor command timed out"));
+		}, timeoutMs);
+
+		let buffer = "";
+		let sentCommand = false;
+
+		const socket = typeof endpoint === "string"
+			? connect({ path: endpoint })
+			: connect(endpoint.port, endpoint.host);
+
+		socket.on("data", (data) => {
+			buffer += data.toString();
+			// Wait for the (qemu) prompt before sending command
+			if (!sentCommand && buffer.includes("(qemu)")) {
+				sentCommand = true;
+				buffer = "";
+				socket.write(command + "\n");
+			} else if (sentCommand && buffer.includes("(qemu)")) {
+				// Got response — strip the prompt
+				clearTimeout(timeout);
+				const response = buffer.replace(/\(qemu\)\s*/g, "").trim();
+				socket.destroy();
+				resolve(response);
+			}
+		});
+
+		// When the socket closes after we've already sent the command, QEMU exited.
+		// This is the normal outcome for `quit` — no further (qemu) prompt is sent.
+		socket.on("close", () => {
+			clearTimeout(timeout);
+			if (sentCommand) {
+				resolve(buffer.replace(/\(qemu\)\s*/g, "").trim());
+			} else {
+				reject(new QuickCHRError("MACHINE_STOPPED", "Monitor socket closed before command could be sent"));
+			}
+		});
+
+		socket.on("error", (err) => {
+			clearTimeout(timeout);
+			const code = (err as NodeJS.ErrnoException).code;
+			// ENOENT = named pipe not found (Windows); ECONNREFUSED = server not listening
+			if (code === "ENOENT" || code === "ECONNREFUSED") {
+				reject(new QuickCHRError("MACHINE_STOPPED", "Monitor not available — is the machine running in background mode?"));
+			} else {
+				reject(new QuickCHRError("PROCESS_FAILED", `Monitor connection failed: ${err.message}`));
+			}
+		});
+	});
+}
+
+/** Get a readable/writable stream pair for the serial console. */
+export function serialStreams(machineDir: string, portBase?: number): {
+	readable: ReadableStream<Uint8Array>;
+	writable: WritableStream<Uint8Array>;
+} {
+	const socketPath = channelPath(machineDir, "serial");
+	if (!channelFileExists(socketPath)) {
+		throw new QuickCHRError(
+			"MACHINE_STOPPED",
+			"Serial socket not found — is the machine running in background mode?",
+		);
+	}
+
+	const endpoint = channelEndpoint(machineDir, "serial", portBase);
+	const socket = typeof endpoint === "string"
+		? connect({ path: endpoint })
+		: connect(endpoint.port, endpoint.host);
+
+	const readable = new ReadableStream<Uint8Array>({
+		start(controller) {
+			socket.on("data", (chunk: Buffer) => {
+				controller.enqueue(new Uint8Array(chunk));
+			});
+			socket.on("end", () => controller.close());
+			socket.on("error", (err) => controller.error(err));
+		},
+		cancel() {
+			socket.destroy();
+		},
+	});
+
+	const writable = new WritableStream<Uint8Array>({
+		write(chunk) {
+			return new Promise((resolve, reject) => {
+				socket.write(chunk, (err) => {
+					if (err) reject(err);
+					else resolve();
+				});
+			});
+		},
+		close() {
+			socket.destroy();
+		},
+	});
+
+	return { readable, writable };
+}
+
+/** Send a QGA (QEMU Guest Agent) command via Unix socket. x86 only.
+ *  Delegates to qga.ts for protocol handling — this wrapper adds arch guard,
+ *  KVM availability warning, and socket path resolution. */
+export async function qgaCommand(
+	machineDir: string,
+	arch: Arch,
+	command: QgaCommand,
+	args?: object,
+	timeoutMs: number = 10000,
+	portBase?: number,
+): Promise<unknown> {
+	if (arch === "arm64") {
+		throw new QuickCHRError(
+			"QGA_UNSUPPORTED",
+			"QEMU Guest Agent is not yet functional on ARM64 CHR — MikroTik arm64 guest agent support is planned but not yet released",
+		);
+	}
+
+	const kvmWarning = qgaKvmWarning();
+	if (kvmWarning) {
+		console.warn(kvmWarning);
+	}
+
+	const socketPath = channelPath(machineDir, "qga");
+	if (!channelFileExists(socketPath)) {
+		throw new QuickCHRError(
+			"MACHINE_STOPPED",
+			"QGA socket not found — is the machine running in background mode?",
+		);
+	}
+
+	const endpoint = channelEndpoint(machineDir, "qga", portBase);
+	return qgaRawCommand(endpoint, command, args as Record<string, unknown> | undefined, timeoutMs);
+}
+
+/** Check whether QGA is available and responding for a machine. */
+export function isQgaReady(
+	machineDir: string,
+	arch: Arch,
+	portBase?: number,
+): Promise<boolean> {
+	if (arch === "arm64") return Promise.resolve(false);
+
+	const socketPath = channelPath(machineDir, "qga");
+	// On Unix, skip the connect attempt entirely if the socket file doesn't exist.
+	if (process.platform !== "win32" && !existsSync(socketPath)) return Promise.resolve(false);
+
+	const endpoint = channelEndpoint(machineDir, "qga", portBase);
+	return qgaProbe(endpoint, 5000);
+}