@tikoci/quickchr 0.4.8 → 0.5.1

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.
 
@@ -57,6 +57,23 @@ Library:
 bun add @tikoci/quickchr
 ```
 
+### Prerelease QA (0.5.1)
+
+0.5.1 is published to npm `next` first; the unqualified install above uses `latest`,
+and 0.5.1 is promoted there once QA passes. After 0.5.1 is published, pin it for
+reproducible CLI or library QA:
+
+```bash
+bun install -g @tikoci/quickchr@0.5.1
+bun add @tikoci/quickchr@0.5.1
+quickchr --version
+```
+
+Use `@next` instead of `@0.5.1` to follow later candidates. See the
+[0.5.1 changelog](./CHANGELOG.md#051--2026-10-22) for the changes since 0.5.0,
+including storage admission, cache accounting, and disk preservation fixes.
+The [0.5.0 notes](./CHANGELOG.md#050--2026-10-22) cover migration from 0.4.x.
+
 ### CLI Usage
 
 The easiest way to start is the interactive wizard — it walks through
@@ -158,6 +175,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 |
@@ -172,8 +194,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 | |
@@ -189,6 +212,7 @@ quickchr doctor
 | `--device-mode <m>` | Configure device-mode: rose\|advanced\|basic\|home\|auto\|skip | |
 | `--device-mode-enable <f>` | Set one or more device-mode flags to yes | |
 | `--device-mode-disable <f>` | Set one or more device-mode flags to no | |
+| `--no-device-mode` | Skip device-mode provisioning entirely | |
 | `--port-base <port>` | Starting port number | Auto (9100+) |
 | `--timeout-extra <s>` | Add extra seconds to the auto-computed boot timeout | |
 | `--dry-run` | Print what would run without executing | |
@@ -204,7 +228,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 |
@@ -232,7 +256,7 @@ In **foreground** mode, your terminal becomes the CHR serial console. Use these
 | `Ctrl-A C` | Toggle QEMU monitor (`quit` to force-stop) |
 | `Ctrl-A H` | List all key shortcuts |
 
-> **Note:** Background QEMU processes are true OS-level orphans — `quickchr` does not use shell job control (`&`). After the command returns you can close the terminal and QEMU keeps running. Use `quickchr stop <name>` to shut it down cleanly.
+> **Note:** Background QEMU processes are true OS-level orphans — `quickchr` does not use shell job control (`&`). After the command returns you can close the terminal and QEMU keeps running. `quickchr stop <name>` ends it with a power cut; `quickchr shutdown <name>` asks the guest to shut down first, and still falls back to a power cut if it does not exit in time.
 
 ### Disk Support
 
@@ -359,7 +383,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"
@@ -430,7 +455,7 @@ afterAll(async () => {
 |----------|-------------|
 | `MIKROTIK_WEB_ACCOUNT` | MikroTik.com account email (for license renewal) |
 | `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_DEFAULT_CHANNEL`, `QUICKCHR_DEFAULT_ARCH`, `QUICKCHR_ACCEL`, `QUICKCHR_CACHE_MAX_SIZE`, `QUICKCHR_STORAGE_RESERVE`, `QUICKCHR_TIMEOUT_EXTRA`, `QUICKCHR_SECURE_LOGIN` | Env-tier overrides for the 7 `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 resolves each `routeros-target` once, then sets this to that exact pin across platforms |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/quickchr",
-  "version": "0.4.8",
+  "version": "0.5.1",
   "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
   "module": "src/index.ts",
   "main": "src/index.ts",
@@ -25,7 +25,7 @@
     "lint": "biome check . && tsc --noEmit",
     "lint:biome": "biome check .",
     "lint:typecheck": "tsc --noEmit",
-    "lint:markdown": "bunx markdownlint-cli2 '**/*.md'",
+    "lint:markdown": "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",

package/src/cli/flags.ts

@@ -24,13 +24,27 @@ const CREATE_FLAGS = [
 
 /** `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",
+	"all", "dry-run", "wait", "background", "bg", "fg", "foreground",
+	"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.
  *
@@ -82,10 +96,15 @@ export const VALUE_FLAGS: ReadonlySet<string> = new Set([
  *  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. */
+ *  replaced it.
+ *
+ *  `--install-deps` is the same defect from the other side: `start` accepted it from
+ *  the beginning and nothing ever read it (#193). It never installed anything, so the
+ *  replacement is the command that names what to install. */
 export const REMOVED_FLAGS: ReadonlyMap<string, string> = new Map([
 	["vmnet-shared", "--add-network shared"],
 	["vmnet-bridge", "--add-network bridged:<iface>"],
+	["install-deps", "quickchr doctor (it never installed anything; doctor lists missing host dependencies and how to install them)"],
 ]);
 
 /** Value-taking flags with a documented `--no-` spelling, where `false` is a real