@tikoci/quickchr 0.4.7 → 0.4.8

package/MANUAL.md

@@ -152,8 +152,9 @@ directory, downloads the RouterOS image (cached), and writes
 | `--no-api-ssl` | false | Exclude API-SSL port |
 | `--port-base <n>` | auto from 9100 | First port of the 10-port block |
 
-`--vmnet-shared` and `--vmnet-bridge <iface>` are deprecated aliases for
-`--add-network shared` / `--add-network bridged:<iface>`.
+`--vmnet-shared` and `--vmnet-bridge <iface>` have been removed. Use
+`--add-network shared` and `--add-network bridged:<iface>`; either old spelling is
+an error naming its replacement, not a silently ignored flag.
 
 #### `start [name]`
 
@@ -219,6 +220,19 @@ Without a name: tabular summary of every machine. With a name: detailed
 view including credentials and connection tips. `--json` for
 machine-readable output.
 
+A machine whose `machine.json` cannot be read — unreadable on disk, not valid JSON, or
+valid JSON that is not usable machine state — still appears, as a row marked
+`unreadable` followed by `quickchr remove <name>`. A `saveMachine()` interrupted by a
+disk-full or a power loss is the usual cause. The listing exits 0: it succeeded, and the
+broken entry is named rather than silently dropped. In `--json` that entry is
+`{"name": …, "status": "unreadable", "error": …}` with no machine fields.
+
+Naming that machine in a command that has to *use* its state — `list <name>`, `stop`,
+`clean`, `env` — fails with `STATE_ERROR` naming the file, because a lookup you asked
+for by name is not an enumeration. `quickchr remove <name>` is the exception, and has to
+be: it is the command whose job is to clear that state, so it treats an unreadable
+machine as a directory to delete rather than state to load.
+
 #### `get <name> [license | device-mode | admin] [--json]`
 
 Live REST query. Hits the running CHR and returns the requested group
@@ -265,8 +279,9 @@ Tail the per-machine `qemu.log`. `--follow` streams new output;
 
 `networks` enumerates host interfaces and their alias resolution
 (`wifi`, `ethernet`, `auto`). `networks sockets` lists registered
-named L2 sockets; `networks sockets create <name>` reserves a port for a
-new tunnel.
+named L2 sockets and the transport each one uses; `networks sockets create <name>`
+registers a new link, taking `--mode` to pick that transport (the default needs no
+port at all).
 
 #### `version [--json]`
 
@@ -392,6 +407,43 @@ shell completions if not yet configured.
 
 Print or install shell completions. With no arg, detects current shell.
 
+#### `cache [add|key|list|prune|clear]`
+
+Manage downloaded CHR images. `cache add` resolves and downloads an image only;
+it does not check QEMU, create a machine, or boot RouterOS. A cache hit is an
+idempotent success.
+
+```bash
+quickchr cache add --channel stable --arch x86
+quickchr cache add --version 7.24.4 --arch arm64 --json
+quickchr cache key --channel stable --arch x86
+# dir=/Users/me/.local/share/quickchr/cache
+# version=7.24.4
+# arch=x86
+quickchr cache key --version 7.24.4 --arch x86 --json
+# {"dir":".../quickchr/cache","version":"7.24.4","arch":"x86"}
+```
+
+`--channel` and `--version` are mutually exclusive. When neither is supplied,
+`default-channel` applies; both subcommands use `default-arch`. A pinned
+version makes no network request in `cache key`. If channel resolution is
+offline, `cache key` prints the stable `unresolved` sentinel and exits 0 so a CI
+cache lookup cannot red the job; `cache add` fails because it cannot download an
+unknown image. Without `--json`, `cache key` emits `key=value` lines that can be
+appended directly to `$GITHUB_OUTPUT`.
+
+```yaml
+- id: chr-cache
+  run: quickchr cache key --channel stable --arch x86 >> "$GITHUB_OUTPUT"
+- uses: actions/cache/restore@v5
+  with:
+    path: ${{ steps.chr-cache.outputs.dir }}
+    key: chr-${{ runner.os }}-${{ steps.chr-cache.outputs.version }}
+```
+
+`--json` intentionally emits one JSON object for programmatic parsing; use the
+default output form when writing step outputs directly.
+
 #### `settings [print|get|set|reset] [key] [value] [--json]`
 
 Manage quickchr's own global preferences — repeated flags/defaults that
@@ -449,6 +501,7 @@ mutate any machine's `machine.json`.
 | `QUICKCHR_SERIAL_LOG` | `=1` tees the guest serial console to `<machineDir>/serial.log`. **Secret-bearing** — serial provisioning types the generated password in cleartext |
 | `QUICKCHR_DEEP_BOOT_DIAGNOSTICS` | `=1` lets a boot-timeout capture write to the guest (a mangle counting rule + host probes) to localize a silent packet drop. Skipped when `QUICKCHR_PRESERVE_ON_FAILURE=1` |
 | `MIKROTIK_WEB_ACCOUNT`, `MIKROTIK_WEB_PASSWORD` | License credentials fallback |
+| `QUICKCHR_NO_TIPS` | `=1` suppresses the dim `tip:` lines quickchr prints on stderr |
 | `NO_COLOR` | Disable ANSI styling |
 
 `--json` is honored on `list`, `status`, `get`, `env`, `snapshot`, and a
@@ -456,6 +509,26 @@ few others; `inspect` is always JSON and accepts `--json` for parity. Check
 `quickchr help <command>`. Errors are caught at the top level and exit `1`
 with a `[code] message` line plus the install hint when present.
 
+**Help.** `--help` / `-h` on any subcommand prints that subcommand's help, exits `0`,
+and touches no state — including `quickchr add --help`, which is a machine-creating
+command. Anything after a bare `--` is your payload and is never scanned for flags:
+
+```bash
+quickchr exec my-chr -- ":put [/system/resource/get version]"
+```
+
+**Unknown flags.** `add` and `start` reject a flag they do not know rather than
+ignoring it, and suggest the closest match. The read-only commands still tolerate
+stray arguments.
+
+**Names.** Machine and named-socket names may contain letters, digits, `.`, `_`
+and `-`, must start with a letter or digit, and are capped at 64 characters. Both
+become a directory or file name under the data dir (§8).
+
+**Tips.** quickchr prints an occasional one-line `tip:` on **stderr** pointing at a
+better-suited command or tool. They never go to stdout, so piping `--json` output is
+unaffected. `QUICKCHR_NO_TIPS=1` turns them off.
+
 ---
 
 ## 4. Library API reference
@@ -471,6 +544,9 @@ QuickCHR.start(opts?: StartOptions): Promise<ChrInstance>
 QuickCHR.add(opts?: StartOptions): Promise<MachineState>
 QuickCHR.list(): MachineState[]
 QuickCHR.get(name: string): ChrInstance | null
+QuickCHR.listUnreadable(): Array<{ name: string; error: string }>
+QuickCHR.listOrphans(): string[]
+QuickCHR.removeOrphan(name: string): boolean
 QuickCHR.doctor(): Promise<DoctorResult>
 QuickCHR.resolveVersion(channel: Channel): Promise<string>
 ```
@@ -489,6 +565,31 @@ process).
 loads `machine.json`, refreshes PID liveness, and returns a runtime
 handle. `list()` is `get()` for everything in `machines/`.
 
+`listOrphans()` / `removeOrphan()` cover the gap between the two: a directory under
+`machines/` with no readable `machine.json`, left by a create that a crash or a
+SIGKILL interrupted. It still occupies the name, so `add()` refuses it, but no
+machine answers to it.
+
+How `get()` and `list()` behave depends on *why* the state is unreadable, and the
+two differ — a targeted lookup fails, an enumeration does not:
+
+| State | `get(name)` | `list()` |
+|---|---|---|
+| `machine.json` missing | `null` | omits it |
+| `machine.json` present but unreadable (read error, invalid JSON, or valid JSON that is not machine state) | **throws** `STATE_ERROR`, naming the file and `quickchr remove <name>` | skips it; `listUnreadable()` names it, and `quickchr list` shows it as a row |
+
+`listUnreadable()` returns `{ name, error }` for every machine in the second row — the
+file is present but cannot be turned into state, whether because the read failed, the
+JSON is invalid, or the parsed value is not a machine — so nothing is dropped without
+being reported somewhere. A
+directory with *no* `machine.json` is not in it; that is a create that never finished,
+and `listOrphans()` covers it.
+
+`listOrphans()` and `removeOrphan()` treat both the same — unreadable is unreadable —
+so `quickchr remove <name>` clears either. `removeOrphan()` returns `false` for a real
+machine (use `get(name)?.remove()` for those) and for a name that does not exist, and
+throws `INVALID_NAME` for a name that is not a usable path segment.
+
 ### `ChrInstance`
 
 **At a glance** — every method on a running instance:
@@ -496,7 +597,7 @@ handle. `list()` is `get()` for everything in `machines/`.
 | Group | Member | Purpose |
 |---|---|---|
 | Identity | `name`, `state`, `ports`, `restUrl`, `sshPort`, `portBase` | Static metadata persisted in `machine.json` |
-| Capture | `captureInterface`, `tzspGatewayIp` | Platform-correct values for TZSP capture (`tshark -i …`) and RouterOS streaming target |
+| Capture | `captureInterface`, `hostGatewayIp` | Platform-correct values for TZSP capture (`tshark -i …`) and the guest→host address any UDP emitter targets |
 | Lifecycle | `waitForBoot()`, `waitFor(fn, ms?)`, `stop()`, `remove()`, `clean()`, `destroy()` | Boot readiness, custom polling, teardown |
 | Comms | `rest()`, `exec()`, `monitor()`, `serial()`, `qga()` | REST, RouterOS CLI, QEMU monitor, serial console, QGA (x86 only) |
 | Provisioning | `license()`, `setDeviceMode()`, `availablePackages()`, `installPackage()` | Post-boot configuration |
@@ -513,7 +614,8 @@ interface ChrInstance {
   sshPort: number;
   portBase: number;           // start of this instance's reserved port block
   captureInterface: string;   // "lo0" on macOS, "any" on Linux — for TZSP capture
-  tzspGatewayIp: string;      // "10.0.2.2" — QEMU slirp host gateway
+  hostGatewayIp: string;      // "10.0.2.2" — the host, as seen from inside the guest
+  tzspGatewayIp: string;      // deprecated alias for hostGatewayIp (#26)
 
   waitForBoot(timeoutMs?: number): Promise<boolean>;
   waitFor(condition: () => Promise<boolean>, timeoutMs?: number): Promise<boolean>;
@@ -643,7 +745,7 @@ const chr = await QuickCHR.start({
 ```
 
 To **receive** UDP a guest sends, no forward is needed — bind an *unconnected*
-host socket and have the guest send to `chr.tzspGatewayIp` (`10.0.2.2`); see
+host socket and have the guest send to `chr.hostGatewayIp` (`10.0.2.2`); see
 [`docs/networking-recipes.md`](docs/networking-recipes.md) §2 and
 [`examples/udp-gateway/`](examples/udp-gateway/).
 
@@ -684,6 +786,24 @@ The entry also re-exports the lower-level version helpers for pre-flight checks:
 `isProvisioningSupportedVersion` (validate a version against the provisioning floor
 before calling `start()`).
 
+### Cache helpers
+
+`cacheKey()` and `cacheAdd()` are the library equivalents of the CLI cache
+subcommands:
+
+```ts
+import { cacheAdd, cacheKey, CACHE_VERSION_UNRESOLVED } from "@tikoci/quickchr";
+
+const { dir, version, arch } = await cacheKey({ channel: "stable", arch: "x86" });
+if (version !== CACHE_VERSION_UNRESOLVED) {
+  await cacheAdd({ version, arch });
+}
+```
+
+`cacheKey({ version })` validates the pin without resolving a channel.
+`cacheAdd()` returns `{ dir, version, arch, path, cacheHit }`; it only downloads
+and extracts the image and never creates or boots a machine.
+
 ---
 
 ## 5. Provisioning pipeline
@@ -810,7 +930,7 @@ Picking among the specifiers/forwards by *goal* — full guide with recipes in
 |---|---|---|---|---|
 | `user` | SLiRP user-mode NAT, hostfwd port mapping | no | no | via hostfwd ports only |
 | `socket::<name>` | L2 socket pair between two VMs sharing the name | no | yes | no |
-| `socket-listen:<port>` / `socket-connect:<port>` / `socket-mcast:<group>:<port>` | low-level QEMU socket netdevs | no | yes | no |
+| `socket:listen:<port>` / `socket:connect:<port>` / `socket:mcast:<group>:<port>` | low-level QEMU socket netdevs | no | yes | no |
 | `shared` | NAT'd L3 with DHCP from the host | yes (or `socket_vmnet` rootless) | yes | yes |
 | `bridged:<iface>` | L2 bridged onto host iface | yes (or `socket_vmnet` rootless) | yes | yes |
 | `tap:<iface>` | pre-created TAP, no quickchr setup | depends | yes | yes |
@@ -821,15 +941,64 @@ Resolution chains:
 - **`shared`** on macOS: socket_vmnet daemon → vmnet-shared (root-only QEMU). On Linux: pre-created TAP owned by the user, else root-created TAP+bridge.
 - **`bridged:<iface>`** on macOS: socket_vmnet bridged → vmnet-bridged (root). On Linux: TAP attached to a bridge containing the named iface.
 
+> The table lists the strings the **CLI** takes. The library's equivalents are the
+> `NetworkSpecifier` type names, which are spelled with a dash rather than a colon:
+> `socket:listen:5000` on the command line is `{ type: "socket-listen", port: 5000 }`
+> in TypeScript.
+
 ### Named L2 sockets
 
-`quickchr networks sockets create lab-sw1` reserves a port and stores
-metadata in `<dataDir>/networks/lab-sw1.json`. Two machines using
-`--add-network socket::lab-sw1` form an L2 tunnel: the first to start
-listens on the port; the second connects.
+`quickchr networks sockets create lab-sw1` registers a link in
+`<dataDir>/networks/lab-sw1.json`, and two machines using
+`--add-network socket::lab-sw1` join it. A link carries a **transport**, fixed when
+the name is created and printed by `start`, `networks sockets` and `create` itself —
+you never have to open a file under the data dir to find out what your link is.
 
-quickchr unregisters socket members on `stop`/`remove`/`clean` so port
-allocation can recycle.
+| `--mode` | Transport | Machines | Start order | Notes |
+|---|---|---|---|---|
+| `dgram` (default on macOS/Linux) | a pair of unix datagram sockets | 2 | either first | no host port, no UDP syscalls; needs QEMU 7.2+ |
+| `listen-connect` (default on Windows) | TCP pair on loopback | 2 | the listening end first | the first machine to *join* takes the listening end and keeps it; a connector never retries, so start that machine first |
+| `mcast` | UDP multicast on `230.0.0.1` | any number | any | the only N-way segment — **and the only one that fails silently** |
+
+`mcast` is worth the warning it prints at create time. Three separate hazards, all with
+the same signature — interfaces up, addresses assigned, 100% packet loss, nothing logged:
+
+- **It does not deliver on macOS.** QEMU's multicast socket omits `SO_REUSEPORT`, which
+  macOS/BSD require before two sockets on one group both receive.
+- **It is refused where unconnected UDP sends are blocked** — seccomp-filtered sandboxes
+  and some CI containers, including on Linux. The group still joins cleanly; only the
+  send is denied.
+- **It is not confined to your machine.** quickchr does not pass `localaddr=`, so the
+  group rides the host's default multicast interface rather than loopback. Another
+  machine on your LAN using the same group joins your segment.
+
+Use it when you genuinely need more than two machines on one segment, give it a group of
+its own, and check the link before you trust it. For two machines, `dgram` is both
+confined to the filesystem and able to refuse a bad configuration up front.
+
+The two-machine modes hold their ends in named slots, so a machine that stops and
+starts again comes back on the same end. That is what makes a restart safe, and it is
+also why `listen-connect` has a start order at all: the roles are fixed when the two
+machines first join, and from then on the listening end has to be running before the
+connecting one starts, because QEMU's `connect=` fails silently and never retries.
+`dgram` has no such constraint — either end may start first, every time. A third machine is refused, with a pointer
+to `--mode mcast`:
+
+```console
+$ quickchr start --name chr3 --add-network socket::lab-sw1
+Error [NETWORK_UNAVAILABLE]: Named socket "lab-sw1" is a dgram link and carries 2
+machines; chr1 and chr2 already hold both ends. Stop one of them, or create an N-way
+segment with 'quickchr networks sockets create <name> --mode mcast'.
+```
+
+quickchr unregisters socket members on `stop`/`remove`/`clean`, which frees the end
+for another machine. `networks sockets remove` refuses a link that still has members —
+removing it unlinks the endpoint sockets, which would kill a running link without
+saying so.
+
+Joining a link takes a registry lock, so `quickchr start a & quickchr start b &` is
+safe: without it both machines claim the same endpoint and are handed the same socket
+path.
 
 For platform internals (vmnet quirks, TAP creation, bridged-mode
 restrictions, half-open SLiRP under TCG), see `docs/networking.md`.
@@ -1066,6 +1235,22 @@ derived Basic auth header. Do not commit or publicly log these values.
 `quickchr exec <name> <command>` and `chr.exec(command, opts)` both
 funnel through the same transport selector.
 
+> **`exec` does not validate your command.** It is a pipe: whatever you pass is what
+> RouterOS is asked to run, and a malformed command comes back as RouterOS's own
+> rejection. For anything beyond a one-liner, use
+> [centrs](https://github.com/tikoci/centrs), which checks a command against the
+> device's own command tree *before* running it and has per-path help:
+>
+> ```bash
+> centrs retrieve --quickchr my-chr /system/resource   # read state
+> centrs execute  --quickchr my-chr <command>          # read/write command
+> centrs explain  <command>                            # analyze without running
+> ```
+>
+> centrs resolves the machine's live connection facts through `quickchr inspect`
+> (see [`docs/centrs-interface.md`](./docs/centrs-interface.md)) — it never reads
+> `machine.json`, and neither should you.
+
 ### Transports
 
 | `--via` | Source | Notes |

package/README.md

@@ -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
 
@@ -247,11 +251,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
 ```
@@ -377,6 +385,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 +432,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.4.8",
   "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,194 @@
+// 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", "background", "bg", "fg", "foreground",
+	"install-deps", "timeout-extra",
+	"license-level", "license-account", "license-password",
+] as const;
+
+export const ADD_FLAGS: readonly string[] = CREATE_FLAGS;
+export const START_FLAGS: readonly string[] = [...CREATE_FLAGS, ...START_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);
 		}