@tikoci/quickchr 0.4.8 → 0.5.0

package/src/lib/shutdown.ts

@@ -0,0 +1,49 @@
+/** Bounded guest shutdown, independently observing process exit (#143). */
+import { QuickCHRError } from "./types.ts";
+import type { ShutdownResult } from "./types.ts";
+
+export const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
+
+export function validateShutdownTimeout(timeoutMs: number): number {
+	// node:http timers cannot represent a larger delay; overflow becomes a 1 ms timer.
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+		throw new QuickCHRError("INVALID_ARGUMENT", "shutdown timeoutMs must be a positive integer no greater than 2147483647 milliseconds");
+	}
+	return timeoutMs;
+}
+
+/** The process observer is separate from the request: RouterOS can return HTTP 400
+ * `interrupted` while successfully halting. Request must enforce its timeout (exec does). */
+export async function shutdownGuest(
+	timeoutMs: number,
+	request: (timeoutMs: number) => Promise<unknown>,
+	isRunning: () => boolean,
+	forceStop: () => Promise<unknown>,
+): Promise<ShutdownResult> {
+	const deadline = performance.now() + timeoutMs;
+	let requestError: string | undefined;
+	const pending = Promise.resolve().then(() => request(Math.max(1, Math.ceil(deadline - performance.now())))).catch((error: unknown) => {
+		requestError = error instanceof Error ? error.message : String(error);
+	});
+	while (isRunning() && performance.now() < deadline) {
+		await Bun.sleep(Math.min(100, Math.max(1, deadline - performance.now())));
+	}
+	const guestExited = !isRunning();
+	// exec's HTTP timer settles this within the same grace budget, including when
+	// QEMU exits while its HTTP response is still pending. Never replay the request.
+	await pending;
+	if (guestExited || !isRunning()) {
+		return { outcome: "guest-exited", ...(requestError === undefined ? {} : { requestError }) };
+	}
+
+	try {
+		await forceStop();
+	} catch {
+		if (isRunning()) throw new QuickCHRError("STATE_ERROR", "shutdown could not terminate QEMU; machine remains running");
+	}
+	// stopQemu sends SIGKILL after its SIGTERM wait but does not await that exit.
+	const killDeadline = performance.now() + 1000;
+	while (isRunning() && performance.now() < killDeadline) await Bun.sleep(50);
+	if (isRunning()) throw new QuickCHRError("STATE_ERROR", "shutdown could not confirm QEMU exit; machine remains running");
+	return { outcome: "forced", ...(requestError === undefined ? {} : { requestError }) };
+}

package/src/lib/socket-registry.ts

@@ -142,8 +142,8 @@ const LOCK_TIMEOUT_MS = 5_000;
  *  A two-process repro lost an endpoint on 12 of 12 rounds.
  *
  *  `quickchr start a & quickchr start b &` is the shape that hits this, and it is
- *  exactly how the field report drove its multi-CHR lab. The per-machine
- *  `.start-lock` cannot help: the two contenders are different machines. */
+ *  exactly how the field report drove its multi-CHR lab. The per-machine lock
+ *  cannot help: the two contenders are different machines. */
 const _heldLocks = new Set<string>();
 
 /** How long a lock file may be unreadable before it counts as abandoned.

package/src/lib/state.ts

@@ -2,7 +2,7 @@
  * Machine state persistence — JSON files in ~/.local/share/quickchr/machines/.
  */
 
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync, statSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, rmSync, statSync } from "node:fs";
 import { join, } from "node:path";
 import type { MachineState, } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
@@ -285,9 +285,71 @@ export function removeMachine(name: string): void {
 	if (!existsSync(dir)) {
 		throw new QuickCHRError("MACHINE_NOT_FOUND", `Machine "${name}" not found`);
 	}
-	rmSync(dir, { recursive: true, force: true });
+	// Out of `machines/` in one step, then deleted. A recursive delete in place removes
+	// entries one by one, so there is a window where the machine lock (`.lock/`, inside
+	// the directory) is gone while the directory is not, and a waiter or a same-named
+	// create could take a fresh lock in a directory that is being deleted. After the
+	// rename the name is simply free.
+	//
+	// There is no in-place fallback, because it would reopen exactly that window. A
+	// rename can fail briefly while a scanner or indexer holds a handle (Windows refuses
+	// to rename a directory with one open), so it is retried. If it still fails, the
+	// directory is left alone and the failure is reported.
+	const trashDir = join(getDataDir(), ".removing");
+	const trash = join(trashDir, `${name}.${process.pid}.${crypto.randomUUID()}`);
+	ensureDir(trashDir);
+	sweepAbandonedRemovals(trashDir);
+	for (let attempt = 1; ; attempt++) {
+		try {
+			renameSync(dir, trash);
+			break;
+		} catch (e) {
+			if (attempt >= REMOVE_RENAME_ATTEMPTS) {
+				throw new QuickCHRError(
+					"STATE_ERROR",
+					`Could not remove machine "${name}": moving ${dir} aside failed (${(e as Error).message}). ` +
+					`The directory was left in place — close anything using it and run 'quickchr remove ${name}' again.`,
+				);
+			}
+			Bun.sleepSync(REMOVE_RENAME_RETRY_MS);
+		}
+	}
+	// The name is already free, so a failed delete does not fail the removal. The
+	// files stay under `.removing/` and the next removal sweeps them.
+	try {
+		rmSync(trash, { recursive: true, force: true });
+	} catch (e) {
+		console.warn(`Warning: machine "${name}" is removed, but deleting its files at ${trash} failed (${(e as Error).message}). The next 'quickchr remove' retries it, or delete that directory by hand.`);
+	}
 }
 
+/** Delete what earlier removals moved aside and did not finish deleting: a delete that
+ *  failed, or a process that stopped after its rename. Each entry is
+ *  `<name>.<pid>.<uuid>`. One whose pid is alive in another process is still being
+ *  deleted, so it is left alone. Best effort: a failure here never fails a removal. */
+function sweepAbandonedRemovals(trashDir: string): void {
+	let entries: string[];
+	try { entries = readdirSync(trashDir); } catch { return; }
+	for (const entry of entries) {
+		const pid = Number(entry.split(".").at(-2));
+		if (!Number.isInteger(pid) || pid <= 0) continue;
+		if (pid !== process.pid) {
+			try {
+				process.kill(pid, 0);
+				continue; // still being deleted by that process
+			} catch (e) {
+				if ((e as NodeJS.ErrnoException).code === "EPERM") continue;
+			}
+		}
+		try { rmSync(join(trashDir, entry), { recursive: true, force: true }); } catch { /* next time */ }
+	}
+}
+
+/** How long `removeMachine()` keeps trying to move a directory aside: about 2 s in
+ *  all, enough for a scanner to let go of a handle. */
+const REMOVE_RENAME_ATTEMPTS = 10;
+const REMOVE_RENAME_RETRY_MS = 200;
+
 /** Update the status of a machine. */
 export function updateMachineStatus(
 	name: string,

package/src/lib/types.ts

@@ -234,7 +234,8 @@ export interface MachineConfig {
 	deviceMode?: DeviceModeOptions;
 	user?: { name: string; password: string };
 	disableAdmin?: boolean;
-	/** Create a 'quickchr' managed account with a generated password.  Defaults to true. */
+	/** Managed-login intent, recorded at `add()`/`start()`. Same rule as
+	 *  {@link StartOptions.secureLogin}: only an explicit `true` creates the account. */
 	secureLogin?: boolean;
 	portBase: number;
 	excludePorts: ServiceName[];
@@ -250,6 +251,34 @@ export interface MachineConfig {
 	bootDiskFormat?: BootDiskFormat;
 }
 
+/** One provisioning step, as recorded on {@link ProvisioningRecord.steps}. */
+export type ProvisioningStep =
+	| "packages"
+	| "deviceMode"
+	| "license"
+	| "user"
+	| "disableAdmin"
+	| "secureLogin";
+
+/**
+ * What provisioning actually landed on the *current* guest disk (#176).
+ *
+ * Absent means the guest has never been provisioned. `clean()` clears it along with
+ * the disk, which is what reopens the provisioning window — `lastStartedAt` cannot
+ * carry this, because it records that QEMU was launched, not that the guest was
+ * configured, and the two come apart at every `clean()`.
+ */
+export interface ProvisioningRecord {
+	/** ISO timestamp of the last time quickchr applied provisioning to this disk —
+	 *  a first-boot run, or a post-boot step such as `setDeviceMode()`. */
+	at: string;
+	/** Steps that have run on this disk, accumulated: a first-boot run stamps the set
+	 *  it applied, and a post-boot step adds itself. Not a full inventory of the guest —
+	 *  a step absent here was not applied *by quickchr*, which is a weaker claim than
+	 *  "not present". */
+	steps: ProvisioningStep[];
+}
+
 /**
  * Facts about the SSH keypair quickchr generated and installed for its managed
  * user during provisioning. Persisted on {@link MachineState} so consumers (the
@@ -272,7 +301,14 @@ export interface ManagedSshKey {
 
 export interface MachineState extends MachineConfig {
 	createdAt: string;
+	/** Last QEMU spawn. Stamped before the guest is known to have booted, so it says
+	 *  nothing about whether the guest was configured — see {@link provisioning}.
+	 *  Cleared by `clean()`, which replaces the disk that boot belonged to. */
 	lastStartedAt?: string;
+	/** Provisioning that landed on the current disk, if any (#176). */
+	provisioning?: ProvisioningRecord;
+	/** Last `clean()`, which reset the disk to the factory image. */
+	cleanedAt?: string;
 	status: "stopped" | "running" | "error";
 	pid?: number;
 	/** Path to the machine directory. */
@@ -298,7 +334,8 @@ export interface MachineState extends MachineConfig {
  * requires SCP upload + reboot cycle, typically 60–120s extra on native acceleration).
  */
 export interface StartOptions {
-	/** RouterOS version to use (e.g. "7.22.1"). Mutually exclusive with `channel`.
+	/** RouterOS version to use (e.g. "7.22.1"). Takes precedence over `channel`:
+	 *  passing both uses `version` and warns that `channel` was ignored.
 	 *  As a convenience, a channel name (e.g. "long-term") is also accepted here and
 	 *  resolves the same as `channel: "long-term"` — but this emits a warning, since
 	 *  `channel` is the self-documenting field for that case. */
@@ -315,12 +352,27 @@ export interface StartOptions {
 	cpu?: number;
 	/** Memory in MiB. Default: 512 (1024 for cross-arch TCG emulation). */
 	mem?: number;
-	/** Run QEMU in background (true, default) or foreground with serial console on stdio (false). */
+	/** Run QEMU in background (true, default) or foreground with serial console on stdio (false).
+	 *  This only decides where the serial console goes — it never made `start()` return
+	 *  sooner. That is {@link StartOptions.wait}. */
 	background?: boolean;
+	/** Wait for the guest to become ready before resolving (true, default). `false`
+	 *  resolves as soon as QEMU is confirmed running — past `spawnQemu`'s early-exit
+	 *  check, with state and ports persisted — and leaves readiness to the caller, e.g.
+	 *  `centrs retrieve --quickchr <name> /system/resource --wait 5m` (#159).
+	 *
+	 *  Provisioning runs against the booted guest, so it cannot be combined with
+	 *  `wait: false` — including first-boot options `add()` recorded. Both are refused
+	 *  (`INVALID_ARGUMENT`) rather than silently skipped, as is `background: false`,
+	 *  which blocks on the serial console regardless. */
+	wait?: boolean;
 	/** Extra packages to install after boot.
 	 *  This is quickchr provisioning, so it is validated/tested on RouterOS 7.20.8+ only. */
 	packages?: string[];
 	/** Install all packages from the all_packages ZIP (overrides packages[]).
+	 *  On the first start of an `add()`-created machine, leaving this unset keeps what
+	 *  `add()` recorded; an explicit `false` overrides it. The same holds for
+	 *  `disableAdmin` and `secureLogin`.
 	 *  This is quickchr provisioning, so it is validated/tested on RouterOS 7.20.8+ only. */
 	installAllPackages?: boolean;
 	/** Create a user after boot.
@@ -329,8 +381,12 @@ export interface StartOptions {
 	/** Disable the default admin account after boot.
 	 *  This is quickchr provisioning, so it is validated/tested on RouterOS 7.20.8+ only. */
 	disableAdmin?: boolean;
-	/** Create a 'quickchr' managed account with a generated password.  Defaults to true.
-	 *  Set to false to keep admin with no password (exec still works).
+	/** Create a 'quickchr' managed account with a generated password. **Only an explicit
+	 *  `true` does this.** Unset and `false` are the same: the machine keeps the factory
+	 *  `admin` login with an empty password (exec still works). The CLI resolves the
+	 *  `secure-login` setting into this field, so it can be `true` without the flag.
+	 *  This is the one statement of the rule — `MachineState.secureLogin` and
+	 *  `provision()` point here.
 	 *  Enabling the managed login path is quickchr provisioning, so it is validated/tested
 	 *  on RouterOS 7.20.8+ only. */
 	secureLogin?: boolean;
@@ -560,6 +616,20 @@ export interface ChrLoadSample {
 	memUsedMb: number;
 }
 
+/** Options for an explicit guest shutdown. Library values do not read environment settings. */
+export interface ShutdownOptions {
+	/** Guest request + exit-wait budget in milliseconds (default 10,000).
+	 * Lock acquisition and hard-stop escalation have separate bounded waits. */
+	timeoutMs?: number;
+}
+
+export interface ShutdownResult {
+	/** Observed guest exit is not a guarantee of application/storage durability. */
+	outcome: "guest-exited" | "forced" | "already-stopped";
+	/** Request failure can accompany successful guest exit (HTTP 400 interrupted). */
+	requestError?: string;
+}
+
 /**
  * Runtime handle for a CHR virtual machine.
  *
@@ -568,7 +638,9 @@ export interface ChrLoadSample {
  * snapshots, licensing, and lifecycle management.
  *
  * After `QuickCHR.start()` resolves, the instance is REST-ready — all requested
- * provisioning (packages, license, device-mode, user creation) has completed.
+ * provisioning (packages, license, device-mode, user creation) has completed —
+ * unless it was started with `wait: false`, or is a RouterOS 6 guest (no REST:
+ * `rest()` and REST `exec()` throw `REST_UNAVAILABLE`).
  */
 export interface ChrInstance {
 	name: string;
@@ -606,20 +678,12 @@ export interface ChrInstance {
 	 *  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.
-	 *  After `QuickCHR.start()` with provisioning options (installAllPackages, license, etc.),
-	 *  the returned instance is already REST-reachable — this returns immediately.
-	 *  Call this only when starting without provisioning, or as a safety check after a manual stop/restart. */
-	/** @param stats Optional out-param; each REST readiness probe is classified
+
+	/** Check or wait for readiness — REST, or a native-API login on RouterOS 6 (#182).
+	 *  After `QuickCHR.start()` the returned instance is already ready, so this returns
+	 *  immediately. Call it after `start({ wait: false })`, or as a safety check after a
+	 *  manual stop/restart. */
+	/** @param stats Optional out-param; each REST or native-API readiness probe is classified
 	 *  into it (see diagnostics.ts BootProbeStats) so a failed wait can explain
 	 *  whether the forwarded port ever answered. */
 	waitForBoot(timeoutMs?: number, stats?: BootProbeStats): Promise<boolean>;
@@ -641,7 +705,12 @@ export interface ChrInstance {
 	 *  }, 30_000);
 	 */
 	waitFor(condition: () => Promise<boolean>, timeoutMs?: number): Promise<boolean>;
+	/** Power cut: terminate QEMU with SIGTERM, then SIGKILL if needed.
+	 * Pending guest configuration may be lost. Use shutdown() to request guest shutdown. */
 	stop(): Promise<void>;
+	/** Request /system/shutdown once over REST, wait for QEMU exit, then hard-stop
+	 * if needed. Reports forced fallback explicitly; preserves disks and credentials. */
+	shutdown(options?: ShutdownOptions): Promise<ShutdownResult>;
 	remove(): Promise<void>;
 	clean(): Promise<void>;
 	/** Stop and permanently delete this instance (disk + state). Equivalent to stop() then remove(). */
@@ -838,6 +907,13 @@ export type ErrorCode =
 	| "INVALID_NETWORK"
 	| "INVALID_FORWARD_SPEC"
 	| "PROVISIONING_VERSION_UNSUPPORTED"
+	// A provisioning option handed to a machine whose provisioning window has closed:
+	// the guest has booted, so quickchr cannot assume it still holds the default
+	// configuration provisioning expects. Never silently dropped (#176).
+	| "PROVISIONING_WINDOW_CLOSED"
+	// An operation that needs the REST API, on a guest that has none — RouterOS 6, a
+	// boot-only target (#182). Thrown up front instead of letting the request time out.
+	| "REST_UNAVAILABLE"
 	| "INSUFFICIENT_DISK_SPACE"
 	| "STATE_ERROR"
 	| "INVALID_SIZE_STRING"

package/src/lib/versions.ts

@@ -35,6 +35,11 @@ export const ROUTEROS_COMPATIBILITY_MATRIX: RouterOsCompatibilityRow[] = [
 		minimumVersion: "any RouterOS 7.x",
 		notes: "QEMU networking setup before or during boot.",
 	},
+	{
+		feature: "Boot / start / stop on RouterOS 6",
+		minimumVersion: "6.x (x86 only)",
+		notes: "Best-effort boot-only target for v6→v7 migration testing (#182). CLI only; readiness is a native-API login; no provisioning, no REST operations.",
+	},
 	{
 		feature: "Managed login, custom user, disable-admin",
 		minimumVersion: MIN_PROVISION_VERSION,
@@ -242,12 +247,61 @@ export function isProvisioningSupportedVersion(
 	return compareRouterOsVersion(version, minimumVersion) >= 0;
 }
 
+/**
+ * RouterOS 6 is a best-effort **boot-only** target (#182): quickchr downloads, boots and
+ * tracks a 6.x CHR, and does nothing else to it. It exists so a tool driving a v6→v7
+ * migration (tikoci/centrs#386) has a disposable 6.x router to test against — it is not
+ * RouterOS 6 support. CLI only: the wizard does not offer it.
+ *
+ * 6.x has no REST API, so readiness is a native-API `/login` (see `readinessProbeFor()`
+ * in qemu.ts), every provisioning step is refused, and anything that reads or writes
+ * through REST fails with `REST_UNAVAILABLE` rather than timing out.
+ */
+export function isRouterOs6(version: string): boolean {
+	return /^6\./.test(version);
+}
+
+export const ROUTEROS6_BOOT_ONLY =
+	"RouterOS 6 is a best-effort boot-only target: quickchr downloads, boots and tracks it, and runs no provisioning or REST operations on it.";
+
+/** MikroTik publishes RouterOS 6 CHR images for x86 only — `chr-6.49.23-arm64.img.zip`
+ *  is a 404 (checked 2026-10-21). Refused before the download that would say so less
+ *  clearly. */
+export function assertRouterOs6Arch(version: string, arch: Arch): void {
+	if (!isRouterOs6(version) || arch === "x86") return;
+	throw new QuickCHRError(
+		"INVALID_ARCH",
+		`RouterOS ${version} has no ${arch} CHR image — MikroTik publishes RouterOS 6 CHR for x86 only. Pass --arch x86 (arch: "x86").`,
+	);
+}
+
+/** Refuse an operation that needs REST on a guest that cannot have it. The message
+ *  leads with "RouterOS 6: not available" so a caller scanning for the reason finds it
+ *  first, and names the transport that does work. */
+export function assertRestAvailable(machine: { name: string; version: string }, operation: string): void {
+	if (!isRouterOs6(machine.version)) return;
+	throw new QuickCHRError(
+		"REST_UNAVAILABLE",
+		`RouterOS 6: not available — ${operation} uses the REST API, which RouterOS ${machine.version} does not have. ` +
+		`${ROUTEROS6_BOOT_ONLY} Reach it over the native API instead, e.g. ` +
+		`centrs retrieve --quickchr ${machine.name} /system/resource --via native-api --no-validate ` +
+		"(centrs validates against the 7.x command tree, so a 6.x read skips it)",
+	);
+}
+
 /** Guard provisioning operations to reduce version-dependent failure modes. */
 export function assertProvisioningSupportedVersion(
 	version: string,
 	operation: string,
 	minimumVersion = MIN_PROVISION_VERSION,
 ): void {
+	if (isRouterOs6(version)) {
+		throw new QuickCHRError(
+			"PROVISIONING_VERSION_UNSUPPORTED",
+			`Cannot ${operation} on RouterOS ${version}. ${ROUTEROS6_BOOT_ONLY}`,
+			`Drop the provisioning options to boot ${version} as it ships, or use RouterOS ${minimumVersion}+ for ${PROVISIONING_FEATURE_SUMMARY}.`,
+		);
+	}
 	if (isProvisioningSupportedVersion(version, minimumVersion)) return;
 
 	throw new QuickCHRError(