@tikoci/quickchr 0.4.7 → 0.5.0

package/README.md

@@ -2,9 +2,9 @@
 
 > **Experimental** — quickchr is under active development. Most testing has been on
 > macOS (Apple Silicon + Intel), with CI on Linux (x86_64 + aarch64). Windows support
-> is early-stage: unit tests pass on `windows-latest` CI, but integration tests
-> (running a real CHR via QEMU for Windows) are not yet automated. Expect rough edges
-> on Windows — bug reports welcome.
+> is early-stage: unit tests pass on `windows-latest` CI, and a weekly sweep boots a real
+> CHR on Windows (TCG, anchor smoke subset only). Expect rough edges on Windows — bug
+> reports welcome.
 
 CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU.
 
@@ -141,6 +141,10 @@ quickchr settings set default-channel long-term
 quickchr settings set secure-login true
 quickchr settings print
 
+# Resolve/cache an image without creating or booting a machine
+quickchr cache key --channel stable
+quickchr cache add --channel stable --arch x86
+
 # Reset disk to fresh image
 quickchr clean my-chr
 
@@ -154,6 +158,11 @@ quickchr remove my-chr
 quickchr doctor
 ```
 
+`quickchr stop <name>` terminates QEMU (a power cut). For an explicit guest
+shutdown request, use `quickchr shutdown <name> [--timeout <seconds>]` (default
+10 seconds, or `QUICKCHR_SHUTDOWN_TIMEOUT`). It waits for QEMU to exit and clearly
+reports a forced power cut if the guest does not stop within the grace budget.
+
 ### Create / Start Options
 
 | Flag | Description | Default |
@@ -168,8 +177,9 @@ quickchr doctor
 | `--boot-size <size>` | Resize boot disk (e.g., 512M, 2G). Requires `qemu-img`. | |
 | `--add-disk <size>` | Attach an extra blank qcow2 disk. Repeatable. Requires `qemu-img`. | |
 | `--forward <spec>` | Add or pin a QEMU SLiRP hostfwd mapping. Repeatable. | |
-| `--bg` / `--background` | Run in background (default) | true |
+| `--no-wait` | Return once QEMU is running; readiness is up to the caller. Not with provisioning flags or `--fg` | |
 | `--fg` / `--foreground` | Run in foreground — serial console on stdio | |
+| `--bg` / `--background` | **Deprecated, does nothing** — background is already the default. Warns; use `--no-wait` to return early | |
 | `--add-package <pkg>` | Extra package to install (repeatable) | |
 | `--install-all-packages` | Install all packages from `all_packages.zip` | |
 | `--add-user <user:pass>` | Create a user after boot | |
@@ -200,7 +210,7 @@ quickchr separates **boot-only** machine management from **post-boot provisionin
 
 | Feature | Minimum RouterOS | Notes |
 |---------|------------------|-------|
-| Boot / start / stop | Any RouterOS 7.x | Boot-only path; no post-boot RouterOS mutations |
+| Boot / start / stop | Any RouterOS 7.x; RouterOS 6 on x86 (best-effort) | Boot-only path; no post-boot RouterOS mutations. 6.x has no REST: readiness is a native-API login, and provisioning is refused — see MANUAL "RouterOS 6 (boot-only)" |
 | Disk resize / extra disks / disk inspection | Any RouterOS 7.x | Requires host `qemu-img`; QEMU-local only |
 | Network attachment / port mappings | Any RouterOS 7.x | QEMU networking setup; not provisioning |
 | Managed login / custom user / disable-admin | 7.20.8+ | Post-boot provisioning |
@@ -247,11 +257,15 @@ By default each CHR gets a single user-mode NIC (SLIRP). Use `--add-network` to
 quickchr start --name router1 --add-network user --add-network shared
 quickchr start --name router2 --add-network user --add-network shared
 
-# Named virtual socket (L2 tunnel between CHRs)
+# Named virtual socket (L2 link between two CHRs; either may start first)
 quickchr networks sockets create lab-switch
 quickchr start --name r1 --add-network socket::lab-switch
 quickchr start --name r2 --add-network socket::lab-switch
 
+# More than two machines on one segment needs UDP multicast, which does not work
+# on macOS or where UDP is blocked — and fails silently when it does not
+quickchr networks sockets create lab-segment --mode mcast
+
 # Bridge to a physical interface
 quickchr start --name gw --add-network user --add-network bridged:en0
 ```
@@ -351,7 +365,8 @@ const result = await chr.exec("/system/resource/print");
 console.log(result);
 
 // Stop (or remove)
-await chr.stop();
+await chr.stop(); // power cut for normal teardown
+// Alternatively, replace stop() above with: await chr.shutdown({ timeoutMs: 10_000 });
 await chr.remove();
 
 console.log(chr.state.bootDiskFormat); // "qcow2"
@@ -377,6 +392,25 @@ await resolveActiveChannels();
 `7.24` < `7.24.1`). The same map is available from the CLI via
 `quickchr version --json`. See [MANUAL.md](./MANUAL.md) → *Version & channel helpers*.
 
+### Cache API
+
+CI can resolve cache identity and download an image without booting QEMU:
+
+```typescript
+import { CACHE_VERSION_UNRESOLVED, cacheAdd, cacheKey } from "@tikoci/quickchr";
+
+const identity = await cacheKey({ channel: "stable", arch: "x86" });
+// { dir: "/home/runner/.local/share/quickchr/cache", version: "7.24.4", arch: "x86" }
+
+if (identity.version !== CACHE_VERSION_UNRESOLVED) {
+  await cacheAdd({ version: identity.version, arch: "x86" });
+}
+```
+
+An explicit version never performs channel resolution. Offline channel lookup
+returns `version: "unresolved"` from `cacheKey`; `cacheAdd` remains strict and
+fails when it cannot resolve or download the requested image.
+
 ### Use in Tests
 
 ```typescript
@@ -405,7 +439,7 @@ afterAll(async () => {
 | `MIKROTIK_WEB_PASSWORD` | MikroTik.com password (for license renewal) |
 | `QUICKCHR_DEFAULT_CHANNEL`, `QUICKCHR_DEFAULT_ARCH`, `QUICKCHR_CACHE_MAX_SIZE`, `QUICKCHR_TIMEOUT_EXTRA`, `QUICKCHR_SECURE_LOGIN` | Env-tier overrides for the 5 `quickchr settings` keys — see [MANUAL.md §3 `settings`](./MANUAL.md#3-cli-command-reference) |
 | `QUICKCHR_INTEGRATION` | Set to `1` to run integration tests |
-| `QUICKCHR_TEST_TARGET` | Integration tests only: RouterOS channel (`stable`/`long-term`/`testing`/`development`) or pinned version (e.g. `7.22.1`) to boot. Empty = `stable`. The Integration workflow (`integration.yml`) sets this from its `routeros-target` dispatch input to test a release across platforms |
+| `QUICKCHR_TEST_TARGET` | Integration tests only: RouterOS channel (`stable`/`long-term`/`testing`/`development`) or pinned version (e.g. `7.22.1`) to boot. Empty = `stable`. The Integration workflow resolves each `routeros-target` once, then sets this to that exact pin across platforms |
 
 The full list (including `QUICKCHR_DATA_DIR`, `QUICKCHR_NO_PROMPT`, `QUICKCHR_DEBUG`,
 `NO_COLOR`) is in [MANUAL.md §11](./MANUAL.md#11-auth-secrets-environment-variables).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/quickchr",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
   "module": "src/index.ts",
   "main": "src/index.ts",
@@ -21,14 +21,16 @@
     "MANUAL.md"
   ],
   "scripts": {
-    "check": "bun run lint:biome && bun run lint:typecheck && bun run lint:markdown && bun run lint:cspell && bun run lint:examples && bun run lint:shell",
+    "check": "bun run lint:biome && bun run lint:typecheck && bun run lint:markdown && bun run lint:cspell && bun run lint:examples && bun run lint:specifiers && bun run lint:shell && bun run lint:bun-pin",
     "lint": "biome check . && tsc --noEmit",
     "lint:biome": "biome check .",
     "lint:typecheck": "tsc --noEmit",
     "lint:markdown": "bunx markdownlint-cli2 '**/*.md'",
     "lint:cspell": "cspell lint . --no-progress",
     "lint:examples": "bun run scripts/validate-examples.ts",
+    "lint:specifiers": "bun run scripts/validate-network-specifiers.ts",
     "lint:shell": "sh scripts/lint-shell.sh",
+    "lint:bun-pin": "bun run scripts/check-bun-pin.ts",
     "test": "bun test test/unit/",
     "test:examples": "bun test examples/",
     "smoke:examples": "QUICKCHR_INTEGRATION=1 EXAMPLES_SMOKE=1 bun test test/integration/examples-smoke.test.ts",

package/src/cli/flags.ts

@@ -0,0 +1,208 @@
+// cspell:ignore hlep
+/**
+ * Known-flag registry for the machine-creating commands.
+ *
+ * `parseFlags` accepts any `--flag`, and `add`/`start` read only the ones they know.
+ * An unrecognised flag was therefore inert: `quickchr add --hlep` created a machine and
+ * downloaded 43 MB, and `quickchr add --help` did the same (#156). A typo that creates
+ * state is not a good default, so these two commands check their flags first.
+ *
+ * Only `add` and `start` are strict. They are the commands that create machines and
+ * download images; the read-only commands can keep tolerating stray arguments.
+ */
+
+/** Flag names as `parseFlags` reports them: no leading dashes, and `--no-x` arrives as `x`. */
+const CREATE_FLAGS = [
+	"version", "channel", "arch", "name", "cpu", "mem", "accel",
+	"add-package", "install-all-packages",
+	"port-base", "forward", "winbox", "api-ssl",
+	"add-network", "network",
+	"boot-disk-format", "boot-size", "add-disk",
+	"device-mode", "device-mode-enable", "device-mode-disable",
+	"add-user", "disable-admin", "secure-login",
+] as const;
+
+/** `start` also boots, so it owns the run-time flags on top of the create set. */
+const START_ONLY_FLAGS = [
+	"all", "dry-run", "wait", "background", "bg", "fg", "foreground",
+	"install-deps", "timeout-extra",
+	"license-level", "license-account", "license-password",
+] as const;
+
+/** `set` applies a change to a machine that has already booted, so it takes the
+ *  post-boot subset of the provisioning flags plus `--license`'s credential flags.
+ *
+ *  It is listed here for the **valueless** check, not for strictness: `set` still
+ *  tolerates an unknown flag like every other non-creating command. The check that
+ *  matters is arity — `quickchr set lab --device-mode` with no value parses as a
+ *  boolean and would otherwise reach "Nothing to set", which blames the user for the
+ *  wrong thing. */
+const SET_ONLY_FLAGS = [
+	"name", "license", "level", "account", "password",
+	"device-mode", "device-mode-enable", "device-mode-disable",
+] as const;
+
+export const ADD_FLAGS: readonly string[] = CREATE_FLAGS;
+export const START_FLAGS: readonly string[] = [...CREATE_FLAGS, ...START_ONLY_FLAGS];
+export const SET_FLAGS: readonly string[] = SET_ONLY_FLAGS;
+
+/** Every flag that takes a value, across every command — `parseFlags`'s arity table.
+ *
+ *  This is the parser's input, not only a validation list. Without it `parseFlags`
+ *  guessed each flag's arity from the shape of the next argument — *if it does not start
+ *  with `--`, consume it as the value* — which is one rule doing two jobs and getting one
+ *  of them wrong: a boolean flag swallowed the following positional, so
+ *  `quickchr start --vmnet-shared lab` set `vmnet-shared="lab"` and lost the machine name
+ *  (#164). A flag absent from this set is boolean and never consumes an argument.
+ *
+ *  It is also what makes a missing value visible. `parseFlags` stores `true` when a
+ *  value-taking flag is followed by another flag or by nothing, and `flag()` turns a
+ *  boolean back into `undefined` — so `quickchr add --name --version 7.24.3` used to
+ *  reach `add()` with no name at all and quietly create an auto-named machine. Checking
+ *  names alone does not catch that; the value has to be checked too.
+ *
+ *  `--no-x` (which parses as `false`) is a deliberate negation, not a missing value,
+ *  so only an explicit `true` is rejected.
+ *
+ *  Both directions are asserted mechanically against the CLI source in
+ *  `test/unit/cli-flag-arity.test.ts` — every name read as a value is here, and no name
+ *  read as a boolean is — and the scan covers direct access (`flags["older-than"]`) as
+ *  well as the helpers, because that is where the first gap was. A new flag cannot skip
+ *  this table by being forgotten; the audit is the test's job, not a reviewer's. */
+export const VALUE_FLAGS: ReadonlySet<string> = new Set([
+	// add / start
+	"version", "channel", "arch", "name", "cpu", "mem", "accel",
+	"add-package", "port-base", "forward",
+	"add-network",
+	"boot-disk-format", "boot-size", "add-disk",
+	"device-mode", "device-mode-enable", "device-mode-disable",
+	"add-user", "timeout-extra",
+	"license-level", "license-account", "license-password",
+	// exec / qga / console
+	"via", "user", "password", "timeout", "path", "data", "script",
+	// set --license
+	"account", "level",
+	// networks sockets create
+	"mode", "port", "group",
+	// completions / logs
+	"shell", "lines",
+	// cache prune
+	"older-than", "max-age", "max-size",
+]);
+
+/** Flags that quickchr used to accept, and what to write instead.
+ *
+ *  `--vmnet-shared` / `--vmnet-bridge <iface>` were special cases for one network type
+ *  that `--add-network` already expresses in general (#164). Removing them silently would
+ *  repeat the defect they were removed for: a flag that is accepted and does nothing. A
+ *  removed name stays known for as long as anyone might still type it, and says what
+ *  replaced it. */
+export const REMOVED_FLAGS: ReadonlyMap<string, string> = new Map([
+	["vmnet-shared", "--add-network shared"],
+	["vmnet-bridge", "--add-network bridged:<iface>"],
+]);
+
+/** Value-taking flags with a documented `--no-` spelling, where `false` is a real
+ *  instruction rather than a value that went missing. `--no-device-mode` is the only
+ *  one today; it is listed in `start --help`. Exported for the arity audit, which would
+ *  otherwise read `flags["device-mode"] === false` as proof that it is a boolean. */
+export const NEGATABLE_VALUE_FLAGS: ReadonlySet<string> = new Set(["device-mode"]);
+
+/** Flags given without the value they require.
+ *
+ *  Both spellings have to be caught. `--name` followed by another flag parses as
+ *  `true`, and `--no-name` parses as `false`; either way `flag()` returns `undefined`
+ *  and the machine gets an auto-generated name. Only a string (or a repeatable flag's
+ *  string[]) is a value. */
+export function valuelessFlags(
+	flags: Record<string, string | boolean | string[]>,
+	known: readonly string[],
+): Array<{ name: string; negated: boolean }> {
+	const result: Array<{ name: string; negated: boolean }> = [];
+	for (const name of Object.keys(flags)) {
+		if (!known.includes(name) || !VALUE_FLAGS.has(name)) continue;
+		const value = flags[name];
+		if (typeof value === "string" || Array.isArray(value)) continue;
+		if (value === false && NEGATABLE_VALUE_FLAGS.has(name)) continue;
+		result.push({ name, negated: value === false });
+	}
+	return result;
+}
+
+/** Human-readable complaint for `valuelessFlags()` output. Empty when nothing is missing. */
+export function valuelessFlagMessage(
+	valueless: ReadonlyArray<{ name: string; negated: boolean }>,
+	command: string,
+): string {
+	if (valueless.length === 0) return "";
+	const lines = valueless.map(({ name, negated }) =>
+		negated
+			? `  --no-${name}  (not a supported negation — --${name} takes a value)`
+			: `  --${name} <value>`,
+	);
+	return [
+		`Error: flag${valueless.length > 1 ? "s" : ""} for 'quickchr ${command}' missing a value:`,
+		...lines,
+		`Run 'quickchr ${command} --help' for the full list.`,
+	].join("\n");
+}
+
+function editDistance(a: string, b: string): number {
+	// One rolling row — the suggestion only needs the distance, never the edit script.
+	let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+	for (let i = 1; i <= a.length; i++) {
+		const current = [i, ...Array<number>(b.length).fill(0)];
+		for (let j = 1; j <= b.length; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			current[j] = Math.min(
+				(previous[j] ?? 0) + 1,
+				(current[j - 1] ?? 0) + 1,
+				(previous[j - 1] ?? 0) + cost,
+			);
+		}
+		previous = current;
+	}
+	return previous[b.length] ?? 0;
+}
+
+/** The closest known flag to `name`, when one is close enough to be worth suggesting. */
+export function suggestFlag(name: string, known: readonly string[]): string | undefined {
+	let best: string | undefined;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	for (const candidate of known) {
+		const d = editDistance(name, candidate);
+		if (d < bestDistance) {
+			bestDistance = d;
+			best = candidate;
+		}
+	}
+	// 1/3 of the flag's length, so short flags need a near-exact match and long ones
+	// tolerate a transposition or two.
+	return bestDistance <= Math.max(1, Math.floor(name.length / 3)) ? best : undefined;
+}
+
+/** Every flag in `flags` that `known` does not list, with a suggestion where there is one. */
+export function unknownFlags(
+	flags: Record<string, string | boolean | string[]>,
+	known: readonly string[],
+): Array<{ name: string; suggestion?: string }> {
+	return Object.keys(flags)
+		.filter((name) => !known.includes(name))
+		.map((name) => ({ name, suggestion: suggestFlag(name, known) }));
+}
+
+/** Human-readable complaint for `unknownFlags()` output. Empty when nothing is unknown. */
+export function unknownFlagMessage(
+	unknown: Array<{ name: string; suggestion?: string }>,
+	command: string,
+): string {
+	if (unknown.length === 0) return "";
+	const lines = unknown.map(({ name, suggestion }) =>
+		suggestion ? `  --${name}  (did you mean --${suggestion}?)` : `  --${name}`,
+	);
+	return [
+		`Error: unknown flag${unknown.length > 1 ? "s" : ""} for 'quickchr ${command}':`,
+		...lines,
+		`Run 'quickchr ${command} --help' for the full list.`,
+	].join("\n");
+}

package/src/cli/format.ts

@@ -2,12 +2,21 @@
  * CLI output formatting — tables, colors, status indicators.
  */
 
-import { listMachineNames } from "../lib/state.ts";
+import { listMachineNames, listOrphanMachineDirs } from "../lib/state.ts";
 
 /** Format a "machine not found" error with helpful suggestions. */
 export function machineNotFoundMessage(name: string): string {
-	const names = listMachineNames();
+	// listMachineNames() is directory-based, so it also returns half-created machines.
+	// Offering one as "Available" is what made `remove` name a machine in the same
+	// breath as refusing to find it (#155) — so orphans get their own line.
+	const orphans = listOrphanMachineDirs();
+	const names = listMachineNames().filter((n) => !orphans.includes(n));
 	let msg = `Machine "${name}" not found.`;
+	if (orphans.includes(name)) {
+		msg = `Machine "${name}" has a leftover directory with no readable machine.json — a create that did not finish.`;
+		msg += `\n  Clear it with: quickchr remove ${name}`;
+		return msg;
+	}
 	if (names.length === 0) {
 		msg += `\n  No machines exist. Create one: quickchr start`;
 	} else if (names.length <= 5) {
@@ -15,6 +24,9 @@ export function machineNotFoundMessage(name: string): string {
 	} else {
 		msg += `\n  Run 'quickchr list' to see available machines.`;
 	}
+	if (orphans.length > 0) {
+		msg += `\n  Leftover directories (no readable machine.json): ${orphans.join(", ")} — clear with 'quickchr remove <name>'`;
+	}
 	return msg;
 }
 
@@ -113,7 +125,12 @@ export function formatNetworks(networks: { specifier: unknown; id: string }[]):
 			if (s.type === "socket-listen") return `socket:listen:${s.port}`;
 			if (s.type === "socket-connect") return `socket:connect:${s.port}`;
 			if (s.type === "socket-mcast") return `socket:mcast:${s.group}:${s.port}`;
-			if (s.type === "socket-named") return `socket::${s.name}`;
+			// `{type:"socket"}` is what `parseNetworkSpecifier` emits. This tested for
+			// "socket-named", a type name nothing ever produced, so the branch could not
+			// match and every named socket fell through to JSON.stringify — part of why
+			// the field report had to open machine.json to find out what its link was
+			// (#158).
+			if (s.type === "socket") return `socket::${s.name}`;
 			if (s.type === "tap") return `tap:${s.ifname}`;
 			return JSON.stringify(spec);
 		}