@tikoci/quickchr 0.4.7 → 0.5.0

package/src/lib/lock.ts

@@ -0,0 +1,497 @@
+/**
+ * Cross-process file locks: the per-machine lifecycle lock and the data-dir-wide
+ * allocation lock.
+ *
+ * One primitive for both. A lock is a directory holding an append-only log of
+ * numbered records, and the **highest number is the lock's state**: a live holder's
+ * record means held; a released marker, a dead holder's record, or no record at all
+ * means free. Taking the lock is creating record top+1, published with `link()` so only
+ * one contender can create it and it never exists half-written. Releasing appends a
+ * released marker. Superseded records are collected by the holder while it holds.
+ *
+ * No recovery deletes a record another process may hold. A path has no
+ * compare-and-delete, so deleting a dead holder's lock by path leaves a window between
+ * judging it dead and deleting it, and a successor installed in that window is
+ * deleted too. Rename-aside-and-compare had that window, and so did a reap guard
+ * recovered by age (Codex review of #190, both reproduced). Here, recovering from a
+ * dead holder is just claiming the next number.
+ *
+ * **A claim is checked against the exact record it judged free**, not just that
+ * record's number. Every record carries a unique token, so once created, a claim
+ * stands only if nothing higher exists and its predecessor is still byte-for-byte
+ * what was judged. That turns away a contender that slept through other claims, or
+ * through the log being deleted and started again. A number can recur; a record
+ * cannot.
+ *
+ * **A machine's lock lives and dies with `machines/<name>/`**, so nothing is kept
+ * after a machine is gone. Only a holder deletes a lock directory: `remove()` takes
+ * the machine's directory with its lock inside, and a failed create discards what it
+ * made.
+ *
+ * A directory can be removed and a same-named one created while some process is
+ * paused holding paths into the old lock. So **every record is named for the lock's
+ * incarnation**, `<id>.<gen>`, with the id published once per directory. A stale
+ * process's paths cannot reach the new incarnation's records, and a claim re-checks
+ * that its id is still current before it stands. On top of that, a holder does all its
+ * destructive cleanup before it publishes its released marker, because from that
+ * moment it is no longer the holder.
+ *
+ * A holder records `{ pid, op, at, token }`. The pid decides liveness, the op and age
+ * go into `MACHINE_LOCKED` so the refusal can say what is holding the machine, and a
+ * creation carries its port/MAC reservation (#140).
+ *
+ * The lock is deliberately not reentrant. Two async operations in one process are as
+ * much in conflict as two processes are — a `stop()` and a `start()` in one
+ * `Promise.all` must be ordered — so a lock held by this pid is a lock held by someone
+ * else. Code that already holds a machine's lock calls the `*UnderLock` lifecycle
+ * helpers in quickchr.ts rather than the public methods.
+ */
+
+import { linkSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { QuickCHRError } from "./types.ts";
+import { getDataDir, getMachinesDir } from "./state.ts";
+
+/** What a lock holder is doing. `foreground` is a start whose QEMU runs attached to
+ *  the caller's terminal: it holds the lock until the VM exits, so waiting for it is
+ *  never useful. */
+export type LockOperation =
+	| "add"
+	| "start"
+	| "foreground"
+	| "stop"
+	| "shutdown"
+	| "clean"
+	| "remove"
+	| "device-mode"
+	| "remove-orphan"
+	| "allocate";
+
+/** Resources a machine creation has claimed but not yet persisted in `machine.json`.
+ *  Carried in the creator's machine lock, so it lives exactly as long as the create
+ *  does and dies with a crashed creator's pid (#140). */
+export interface ResourceReservation {
+	portBase: number;
+	macs: string[];
+}
+
+export interface LockRecord {
+	pid: number;
+	op: LockOperation;
+	at: string;
+	token: string;
+	reserve?: ResourceReservation;
+	/** A released marker: the holder before it let go. */
+	released?: true;
+}
+
+export interface HeldLock {
+	readonly path: string;
+	/** Append a released marker after this holder's record. Idempotent, and a no-op
+	 *  once the holder has deleted the lock's directory. */
+	release(): void;
+}
+
+export interface AcquireLockOptions {
+	/** How long to wait for a live holder. 0 (the default) fails immediately. */
+	waitMs?: number;
+	/** A pre-0.5 `.start-lock` to honour alongside this lock. */
+	legacyPath?: string;
+	/** Called once, when the first attempt finds a live holder and waiting begins. */
+	onWait?: (holder: LockRecord) => void;
+	reserve?: ResourceReservation;
+	/** Noun for the refusal message, e.g. `Machine "foo"`. */
+	subject?: string;
+}
+
+/** The pre-0.5 lock file, in the machine directory. For one release a live holder is
+ *  honoured, so a machine locked by an older quickchr is not taken from under it. A
+ *  dead one is ignored, not deleted: the older quickchr recovers its own stale file. */
+const LEGACY_MACHINE_LOCK_FILE = ".start-lock";
+const POLL_MS = 100;
+/** A record that does not parse only counts as abandoned once it is this old. An older
+ *  quickchr creates `.start-lock` empty and fills it in with a second syscall. */
+const UNREADABLE_GRACE_MS = 500;
+
+/** A machine's lock, inside its directory so it goes when the machine does. */
+export function machineLockPath(machineDir: string): string {
+	return join(machineDir, ".lock");
+}
+
+/** Where an older quickchr locks a machine. */
+export function legacyMachineLockPath(machineDir: string): string {
+	return join(machineDir, LEGACY_MACHINE_LOCK_FILE);
+}
+
+/** Held across the read → probe → claim window of a machine creation, so two creates
+ *  cannot pick the same port block or MAC (#140). Lives in the data dir root, not in
+ *  `machines/`, where it would be listed as a machine. One fixed directory: its log
+ *  collects down to two records. */
+export function allocationLockPath(): string {
+	return join(getDataDir(), ".allocate.lock");
+}
+
+/** Test seam: called after each change this module makes inside a lock directory, so
+ *  a test can interleave another contender at exactly that point. */
+let mutationObserver: ((op: "link" | "unlink", path: string) => void) | undefined;
+export function _observeLockMutations(fn: typeof mutationObserver): void {
+	mutationObserver = fn;
+}
+
+function parseRecord(text: string): LockRecord | undefined {
+	const trimmed = text.trim();
+	// A legacy `.start-lock` holds a bare pid.
+	if (/^\d+$/.test(trimmed)) {
+		return { pid: Number.parseInt(trimmed, 10), op: "start", at: "", token: "" };
+	}
+	try {
+		const parsed = JSON.parse(trimmed) as Partial<LockRecord>;
+		if (typeof parsed.pid === "number" && parsed.pid > 0 && typeof parsed.op === "string") {
+			return parsed as LockRecord;
+		}
+	} catch { /* fall through */ }
+	return undefined;
+}
+
+type Inspection =
+	| { state: "absent" }
+	| { state: "live"; record: LockRecord }
+	| { state: "free"; raw: string }
+	| { state: "unknown" };
+
+function isAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		// EPERM: the process exists but belongs to someone else.
+		return (e as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+function readRaw(path: string): string | undefined {
+	try {
+		return readFileSync(path, "utf-8");
+	} catch {
+		return undefined;
+	}
+}
+
+/** One record file. `unknown` is a file whose holder cannot be checked: unreadable
+ *  (EACCES from another user's lock, EISDIR, I/O), or unparseable and new enough that
+ *  its writer may not have finished. */
+function inspect(path: string): Inspection {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf-8");
+	} catch (e) {
+		return (e as NodeJS.ErrnoException).code === "ENOENT" ? { state: "absent" } : { state: "unknown" };
+	}
+	const record = parseRecord(raw);
+	if (!record) {
+		let ageMs = Number.POSITIVE_INFINITY;
+		try { ageMs = Date.now() - statSync(path).mtimeMs; } catch { /* gone */ }
+		return ageMs > UNREADABLE_GRACE_MS ? { state: "free", raw } : { state: "unknown" };
+	}
+	if (record.released) return { state: "free", raw };
+	return isAlive(record.pid) ? { state: "live", record } : { state: "free", raw };
+}
+
+function missing(lockDir: string): QuickCHRError {
+	return new QuickCHRError("MACHINE_NOT_FOUND", `${dirname(lockDir)} no longer exists — the machine was removed.`);
+}
+
+/** The record numbers of one incarnation of a lock. A lock whose parent directory has
+ *  gone belongs to a machine that was removed. */
+function generations(lockDir: string, id: string): number[] {
+	const prefix = `${id}.`;
+	try {
+		return readdirSync(lockDir)
+			.filter((f) => f.startsWith(prefix) && /^\d+$/.test(f.slice(prefix.length)))
+			.map((f) => Number(f.slice(prefix.length)));
+	} catch (e) {
+		if ((e as NodeJS.ErrnoException).code === "ENOENT") throw missing(lockDir);
+		throw e;
+	}
+}
+
+function recordPath(lockDir: string, id: string, gen: number): string {
+	return join(lockDir, `${id}.${gen}`);
+}
+
+/** The lock directory's incarnation id, published once when the directory is first
+ *  used, or undefined if it has none yet and `create` is false.
+ *
+ *  Every record is named `<id>.<gen>`. A machine directory can be removed and created
+ *  again under the same name, and a process paused across that still holds paths into
+ *  the old lock. With the id in every name, those paths cannot reach the new lock's
+ *  records: a collect, a rejected-claim cleanup or a released marker from a stale
+ *  process touches only names nobody reads any more (Codex review of #190). */
+function incarnation(lockDir: string, create: boolean): string | undefined {
+	const idPath = join(lockDir, "id");
+	const read = () => readRaw(idPath)?.trim() || undefined;
+	const existing = read();
+	if (existing || !create) return existing;
+	linkNew(idPath, crypto.randomUUID());
+	const id = read();
+	if (!id) throw missing(lockDir);
+	return id;
+}
+
+/** The lock directory, created if its parent exists. Never the parent: a waiter must
+ *  not bring a removed machine's directory back as an empty orphan. */
+function ensureLockDir(lockDir: string): void {
+	try {
+		mkdirSync(lockDir);
+	} catch (e) {
+		const code = (e as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") throw missing(lockDir);
+		if (code !== "EEXIST") throw e;
+	}
+}
+
+/** Publish `content` at `path` only if nothing is there. Written to a temp file and
+ *  `link()`ed into place, so the file never exists half-written. */
+function linkNew(path: string, content: string): boolean {
+	const tmp = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+	try {
+		writeFileSync(tmp, content);
+	} catch (e) {
+		if ((e as NodeJS.ErrnoException).code === "ENOENT") throw missing(dirname(path));
+		throw e;
+	}
+	try {
+		linkSync(tmp, path);
+		mutationObserver?.("link", path);
+		return true;
+	} catch (e) {
+		const code = (e as NodeJS.ErrnoException).code;
+		if (code === "EEXIST") return false;
+		if (code === "ENOENT") throw missing(dirname(path));
+		throw e;
+	} finally {
+		try { unlinkSync(tmp); } catch { /* ignore */ }
+	}
+}
+
+/** Delete superseded records of one incarnation below `keepFrom`. Only a holder calls
+ *  this, and only while it holds the lock: never the top, and never in a replacement
+ *  directory, whose records carry another id. */
+function collect(lockDir: string, id: string, keepFrom: number): void {
+	let gens: number[];
+	try { gens = generations(lockDir, id); } catch { return; }
+	for (const gen of gens) {
+		if (gen >= keepFrom) continue;
+		const path = recordPath(lockDir, id, gen);
+		try {
+			unlinkSync(path);
+			mutationObserver?.("unlink", path);
+		} catch { /* another collector got it */ }
+	}
+}
+
+type Top = { gen: number; seen: Inspection } | undefined;
+
+/** The top record of an incarnation, or `"vanished"` when it went between listing and
+ *  reading — a holder collected it — and the caller should look again. */
+function readTop(lockDir: string, id: string): Top | "vanished" {
+	const gens = generations(lockDir, id);
+	if (gens.length === 0) return undefined;
+	const gen = Math.max(...gens);
+	const seen = inspect(recordPath(lockDir, id, gen));
+	return seen.state === "absent" ? "vanished" : { gen, seen };
+}
+
+/** Try to take incarnation `id` of the lock as record `gen`, having judged record
+ *  `gen - 1` free with contents `judgedRaw` (or the incarnation empty, for `gen` 1 with
+ *  no `judgedRaw`). Returns the lock, or undefined when another contender got there
+ *  first or the judgement turned out to be stale.
+ *
+ *  The claim stands only if, once created, it is the top, it follows exactly the
+ *  record judged, and `id` is still the directory's incarnation. When `id` is still
+ *  current after the first two checks, this record is the lock's live top, so nobody
+ *  else holds it and nobody can remove the directory in between. */
+export function claim(
+	lockDir: string,
+	id: string,
+	gen: number,
+	op: LockOperation,
+	judgedRaw?: string,
+	reserve?: ResourceReservation,
+): HeldLock | undefined {
+	const record: LockRecord = {
+		pid: process.pid,
+		op,
+		at: new Date().toISOString(),
+		token: crypto.randomUUID(),
+		...(reserve ? { reserve } : {}),
+	};
+	const raw = `${JSON.stringify(record)}\n`;
+	const path = recordPath(lockDir, id, gen);
+	if (!linkNew(path, raw)) return undefined;
+
+	const gens = generations(lockDir, id);
+	const isTop = !gens.some((g) => g > gen);
+	const followsJudged = judgedRaw === undefined
+		? gen === 1 && gens.length === 1
+		: readRaw(recordPath(lockDir, id, gen - 1)) === judgedRaw;
+	if (!isTop || !followsJudged || incarnation(lockDir, false) !== id) {
+		// Our own name, in our incarnation: if the directory has been replaced since,
+		// this name means nothing in the new one.
+		try { unlinkSync(path); } catch { /* collected already, or the directory went */ }
+		mutationObserver?.("unlink", path);
+		return undefined;
+	}
+	collect(lockDir, id, gen);
+	return heldLock(lockDir, id, gen, record, raw);
+}
+
+function heldLock(lockDir: string, id: string, gen: number, record: LockRecord, raw: string): HeldLock {
+	let released = false;
+	return {
+		path: lockDir,
+		release() {
+			if (released) return;
+			released = true;
+			// Gone means this holder deleted the directory — remove(), or a failed create
+			// discarding what it made.
+			if (readRaw(recordPath(lockDir, id, gen)) !== raw) return;
+			// Everything destructive happens first, while this is still the holder. Once
+			// the marker is published another process can take the lock, remove the
+			// machine and let a same-named one start over, so nothing may be deleted by
+			// path after that point.
+			collect(lockDir, id, gen);
+			const marker: LockRecord = { ...record, released: true, at: new Date().toISOString() };
+			delete marker.reserve;
+			// EEXIST (a false return) means someone judged this holder dead and took over:
+			// nothing of ours is left to release. A missing directory means the same. Any
+			// other failure (ENOSPC, EACCES) means the marker was not written and the lock
+			// is still held, so it is thrown, and a later release() may try again.
+			try {
+				linkNew(recordPath(lockDir, id, gen + 1), `${JSON.stringify(marker)}\n`);
+			} catch (e) {
+				if (e instanceof QuickCHRError && e.code === "MACHINE_NOT_FOUND") return;
+				released = false;
+				throw e;
+			}
+		},
+	};
+}
+
+function describeHolder(holder: LockRecord | undefined): string {
+	if (!holder) return "another operation (its lock record is unreadable or still being written)";
+	const age = holder.at ? Math.max(0, Math.round((Date.now() - Date.parse(holder.at)) / 1000)) : undefined;
+	return `\`${holder.op}\` (pid ${holder.pid}${age !== undefined && !Number.isNaN(age) ? `) since ${age}s` : ")"}`;
+}
+
+function lockedError(subject: string, holder: LockRecord | undefined, waitedMs: number): QuickCHRError {
+	const waited = waitedMs > 0 ? ` after waiting ${Math.round(waitedMs / 1000)}s` : "";
+	const hint = holder?.op === "foreground"
+		? " It is running in the foreground: quit it from that console (Ctrl-A X)."
+		: "";
+	return new QuickCHRError("MACHINE_LOCKED", `${subject} is locked by ${describeHolder(holder)}${waited}.${hint}`);
+}
+
+/** Whether a legacy `.start-lock` stands in the way, and its holder when that can be
+ *  read. One that is unreadable, or so new its holder may still be writing it, blocks:
+ *  going ahead in that window would run alongside an older quickchr. */
+function legacyBlocker(legacyPath: string | undefined): { holder: LockRecord | undefined } | undefined {
+	if (!legacyPath) return undefined;
+	const seen = inspect(legacyPath);
+	if (seen.state === "live") return { holder: seen.record };
+	if (seen.state === "unknown") return { holder: undefined };
+	return undefined;
+}
+
+/** One attempt: the lock, or the holder in the way (undefined when its record cannot
+ *  be read). */
+function attempt(lockDir: string, op: LockOperation, opts: AcquireLockOptions): { lock: HeldLock } | { holder: LockRecord | undefined } {
+	ensureLockDir(lockDir);
+	for (;;) {
+		const id = incarnation(lockDir, true) as string;
+		const top = readTop(lockDir, id);
+		if (top === "vanished") continue;
+		if (top?.seen.state === "live") return { holder: top.seen.record };
+		if (top?.seen.state === "unknown") return { holder: undefined };
+		const judged = top?.seen.state === "free" ? top.seen.raw : undefined;
+		const lock = claim(lockDir, id, (top?.gen ?? 0) + 1, op, judged, opts.reserve);
+		if (!lock) continue;
+		const legacy = legacyBlocker(opts.legacyPath);
+		if (!legacy) return { lock };
+		lock.release();
+		return legacy;
+	}
+}
+
+/** Take a lock or fail now with `MACHINE_LOCKED`. A dead holder's lock is taken over
+ *  on sight. Synchronous, for callers whose answer to a live holder is always "no" — a
+ *  second `start` of one machine would only boot it twice. Throws `MACHINE_NOT_FOUND`
+ *  if the lock's machine directory does not exist. */
+export function acquireLockNow(lockPath: string, op: LockOperation, opts: Omit<AcquireLockOptions, "waitMs" | "onWait"> = {}): HeldLock {
+	const result = attempt(lockPath, op, opts);
+	if ("lock" in result) return result.lock;
+	throw lockedError(opts.subject ?? "Machine", result.holder, 0);
+}
+
+/** Take a lock, waiting up to `waitMs` for a live holder to release it. A dead holder's
+ *  lock is taken over on sight; a `foreground` holder is never waited for, since it
+ *  keeps the lock until its VM exits.
+ *
+ *  Throws `MACHINE_LOCKED` naming the holder's operation, pid and age when the wait
+ *  runs out, and `MACHINE_NOT_FOUND` if the machine is removed while this caller
+ *  waits. */
+export async function acquireLock(lockPath: string, op: LockOperation, opts: AcquireLockOptions = {}): Promise<HeldLock> {
+	const waitMs = opts.waitMs ?? 0;
+	const started = Date.now();
+	let notified = false;
+	for (;;) {
+		const result = attempt(lockPath, op, opts);
+		if ("lock" in result) return result.lock;
+		const { holder } = result;
+		const waited = Date.now() - started;
+		if (waited >= waitMs || holder?.op === "foreground") {
+			throw lockedError(opts.subject ?? "Machine", holder, waited);
+		}
+		if (!notified && holder) {
+			notified = true;
+			opts.onWait?.(holder);
+		}
+		await Bun.sleep(Math.min(POLL_MS, waitMs - waited));
+	}
+}
+
+/** The live holder of a lock, if any. */
+export function currentHolder(lockPath: string): LockRecord | undefined {
+	for (;;) {
+		let top: Top | "vanished";
+		try {
+			const id = incarnation(lockPath, false);
+			if (!id) return undefined;
+			top = readTop(lockPath, id);
+		} catch {
+			return undefined; // no lock directory, so no holder
+		}
+		if (top === "vanished") continue;
+		return top?.seen.state === "live" ? top.seen.record : undefined;
+	}
+}
+
+/** Machines whose creation is in flight, with the port block and MACs each has
+ *  claimed. Read from the creators' live machine locks; a crashed creator's
+ *  reservation disappears with its pid. */
+export function listReservations(exceptName?: string): Array<{ name: string } & ResourceReservation> {
+	const machinesDir = getMachinesDir();
+	let names: string[];
+	try {
+		names = readdirSync(machinesDir);
+	} catch {
+		return [];
+	}
+	const out: Array<{ name: string } & ResourceReservation> = [];
+	for (const name of names) {
+		if (name === exceptName) continue;
+		const holder = currentHolder(machineLockPath(join(machinesDir, name)));
+		if (holder?.reserve) out.push({ name, ...holder.reserve });
+	}
+	return out;
+}

package/src/lib/names.ts

@@ -0,0 +1,96 @@
+/**
+ * Resource-name validation — machine names and named-socket names.
+ *
+ * Both become a path segment under the data dir (`machines/<name>/`,
+ * `networks/<name>.json`), so a name is not free text: it has to be safe to join
+ * onto a path and safe to type back into a command. A name starting with `-`
+ * also reads as a flag everywhere it is echoed (`quickchr remove --help`), which
+ * is how `networks sockets create --help` persisted a socket called `--help` (#156).
+ */
+
+import { QuickCHRError } from "./types.ts";
+
+/** Letters, digits, dot, underscore, hyphen — the charset already produced by
+ *  `generateMachineName()` (e.g. `7.24.4-x86-1`), minus anything a shell or a
+ *  path would reinterpret. */
+const VALID_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+const MAX_NAME_LENGTH = 64;
+
+/** Throw `INVALID_NAME` unless `name` is safe as both a path segment and a CLI argument.
+ *  `kind` names the resource in the message ("machine", "named socket"). */
+export function assertValidResourceName(name: string, kind: string): void {
+	const reject = (why: string) => {
+		throw new QuickCHRError("INVALID_NAME", `Invalid ${kind} name "${name}" — ${why}`);
+	};
+
+	if (name.length === 0) reject("names cannot be empty");
+	if (name.startsWith("-")) reject(`names cannot start with "-" (it would be read as a flag)`);
+	if (name.length > MAX_NAME_LENGTH) reject(`names are limited to ${MAX_NAME_LENGTH} characters`);
+	if (!VALID_NAME.test(name)) {
+		reject("names may contain only letters, digits, dot, underscore and hyphen, and must start with a letter or digit");
+	}
+}
+
+/** The weaker rule that applies to a name being *used*, not created.
+ *
+ *  `assertValidResourceName()` cannot guard a lookup or a delete: machines created
+ *  under the older, looser rules have to stay addressable. But a name still becomes a
+ *  path segment, and `join(machinesDir, name)` happily normalizes `..` into the data
+ *  directory itself — so `removeOrphan("..")` would `rmSync` every machine, the cache
+ *  and the socket registry. This is the minimum that stops that while passing every
+ *  name a real machine can have. */
+export function isPathSafeName(name: string): boolean {
+	if (name.length === 0) return false;
+	if (name === "." || name === "..") return false;
+	if (name.includes("/") || name.includes("\0")) return false;
+	// `\` is a path separator on Windows and an ordinary filename character on POSIX.
+	// Rejecting it everywhere would strand a machine named `lab\old` under the older,
+	// looser creation rules: `list` still shows it, so `remove` has to still clear it.
+	if (process.platform === "win32" && name.includes("\\")) return false;
+	return true;
+}
+
+/** Throwing form of {@link isPathSafeName}, for the paths that delete. */
+export function assertPathSafeName(name: string, kind: string): void {
+	if (!isPathSafeName(name)) {
+		throw new QuickCHRError(
+			"INVALID_NAME",
+			`Invalid ${kind} name ${JSON.stringify(name)} — a name cannot be empty, "." or "..", or contain a path separator`,
+		);
+	}
+}
+
+/** Non-throwing form, for callers that want to branch rather than fail. */
+export function isValidResourceName(name: string): boolean {
+	try {
+		assertValidResourceName(name, "resource");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** POSIX-shell-safe form of `value`, for a command quickchr prints for someone to run.
+ *
+ *  Needed because `assertValidResourceName()` only guards names at *creation*. A
+ *  lookup has to keep older, looser names addressable — `isPathSafeName()` above
+ *  rejects only empty, `.`, `..` and a path separator — so a real machine can be
+ *  called `lab old` or `my;lab`, and `quickchr set lab old --device-mode rose` pasted
+ *  into a shell addresses a machine called `lab`. Device-mode feature names have the
+ *  same problem from the other end: `resolveDeviceModeOptions()` deliberately passes
+ *  unknown features through for forward compatibility, so a typo with a space in it
+ *  reaches the printed command intact.
+ *
+ *  Values that need no quoting are returned unchanged, because the overwhelmingly
+ *  common case is an ordinary name and a command in quotes reads like machine output
+ *  rather than something a person would type.
+ *
+ *  What this does **not** fix: a legacy name starting with `-` is read as a flag no
+ *  matter how it is quoted, since quoting is the shell's business and the flag parse
+ *  is quickchr's. New names cannot start with `-` (#156); an old one that does needs
+ *  renaming, not escaping. */
+export function shellQuote(value: string): string {
+	if (value.length > 0 && /^[A-Za-z0-9._:=@,+/-]+$/.test(value)) return value;
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}