@tikoci/quickchr 0.2.0

package/DESIGN.md

@@ -0,0 +1,193 @@
+# quickchr Design
+
+> Architecture and rationale. For the user-facing reference (every CLI
+> command, every library API, provisioning, channels, networking, errors)
+> see **[MANUAL.md](./MANUAL.md)**.
+
+## Architecture
+
+quickchr is a TypeScript/Bun CLI + importable library to manage MikroTik CHR virtual machines via QEMU.
+
+### Layers
+
+```text
+CLI (src/cli/)          ← Arg parsing, wizard, formatting
+    ↓
+Library API (src/lib/quickchr.ts)  ← QuickCHR class, ChrInstance
+    ↓
+Modules (src/lib/)      ← qemu, images, versions, network, state, ...
+```
+
+- **CLI** — git-style subcommands + interactive wizard. Thin layer over the library.
+- **Library** — `QuickCHR` class with static methods: `start()`, `list()`, `get()`, `doctor()`. Returns `ChrInstance` handles with `stop()`, `remove()`, `rest()`, `monitor()`, etc.
+- **Modules** — Pure functions for QEMU arg building, image download, port allocation, state persistence.
+
+### Key Design Decisions
+
+1. **JSON state, not SQLite** — Portable to Windows without native deps. Each machine gets a `machine.json` file in `~/.local/share/quickchr/machines/<name>/`.
+
+2. **Port block allocation** — 10 ports per instance (base + 0-9). Default starts at 9100. Avoids conflicts by scanning existing machines and probe-binding.
+
+3. **No shell scripts** — QEMU args built entirely in TypeScript. Enables Windows support and testability.
+
+4. **Optional qcow2** — Default boot disk uses raw `.img` (MikroTik provides them). Users can opt into `qcow2` format for boot resize and QEMU snapshot/restore support. Requires `qemu-img` when enabled.
+
+5. **ARM64 VirtIO rule** — Never use `if=virtio` on aarch64 `virt` machine. Always explicit `-device virtio-blk-pci,drive=drive0`.
+
+6. **Class-based API** — `QuickCHR` is a class with static methods for clean namespacing. `ChrInstance` is an interface implemented as a plain object with closures.
+
+## Port Layout
+
+| Offset | Service    | Guest Port |
+|--------|------------|------------|
+| +0     | HTTP/REST  | 80         |
+| +1     | HTTPS      | 443        |
+| +2     | SSH        | 22         |
+| +3     | API        | 8728       |
+| +4     | API-SSL    | 8729       |
+| +5     | WinBox     | 8291       |
+| +6—9   | Custom     | —          |
+
+## Storage Layout
+
+```text
+~/.local/share/quickchr/
+├── cache/                     # Downloaded images
+│   ├── chr-7.22.1.img.zip
+│   ├── chr-7.22.1.img
+│   └── ...
+├── machines/
+│   └── 7.22.1-arm64-1/
+│       ├── machine.json       # Config + state
+│       ├── disk.img           # Working copy
+│       ├── efi-vars.fd        # UEFI vars (arm64)
+│       ├── monitor.sock       # QEMU monitor
+│       ├── serial.sock        # Serial console
+│       ├── qga.sock           # QGA (x86 only)
+│       ├── qemu.pid           # PID file
+│       └── qemu.log           # Output log
+└── config.json                # Global config
+```
+
+## Platform Support
+
+| Platform               | x86 CHR | arm64 CHR | Notes |
+|------------------------|---------|-----------|-------|
+| macOS x86_64           | HVF     | TCG       | Intel Mac |
+| macOS arm64 (native)   | HVF     | HVF       | Apple Silicon, bun is arm64 |
+| macOS arm64 (Rosetta)  | HVF     | TCG       | bun is x86_64; arm64 HVF skipped |
+| Linux x86_64           | KVM     | TCG       | KVM requires `/dev/kvm` writable |
+| Linux aarch64          | TCG     | KVM       | x86 TCG on arm64 Linux |
+| Windows x86_64         | TCG     | TCG       | HVF/KVM not available |
+
+**Acceleration detection** (`detectAccel`):
+- macOS: checks `kern.hv_support` via sysctl; for arm64 guest additionally checks `process.arch === "arm64"` (native bun = Apple Silicon).
+- Linux: checks `/dev/kvm` writability.
+- Falling back to TCG is always safe, just slower (~20s x86 TCG boot on Apple Silicon; ~2 min arm64 TCG on Intel).
+
+## CI System
+
+**Workflow**: `.github/workflows/ci.yml`
+
+Three jobs — lint and unit-tests run in parallel; integration is gated on both:
+
+```
+lint                    unit-tests                windows-unit-tests
+Biome + tsc --noEmit    bun test test/unit/       bun test test/unit/
+                        --coverage                (windows-latest, always)
+        ↘               ↙
+        integration (matrix)
+          linux/x86_64  (always)
+          linux/aarch64 (always)
+          macos/arm64   (workflow_dispatch: macos=true)
+          macos/x86_64  (workflow_dispatch: macos=true)
+```
+
+**Integration matrix**: Each runner boots a CHR matching its native arch.  `detectAccel()`
+selects KVM/HVF/TCG automatically — no per-runner overrides needed.
+
+**Coverage**: `bun test test/unit/ --coverage` output is parsed and compared against
+thresholds (default 75% functions, 60% lines).  Failures emit `::warning::` annotations
+but do NOT block merges (`continue-on-error: true`).  Thresholds are overridable via
+dispatch inputs `min-funcs` / `min-lines`.
+
+**Artifacts** (details in `.github/instructions/ci.instructions.md`):
+- `coverage-report` — full per-file coverage table (14 days)
+- `integration-logs-{platform}` — bun test output + machine.json + qemu.log (7 days)
+
+**Publish workflow** (`.github/workflows/publish.yml`): triggers on `v*` tags;
+runs lint + typecheck + unit tests before npm publish.
+
+## Design Principles
+
+### Scope Boundary — QEMU Expert, Not Orchestrator
+
+quickchr manages individual CHR instances. Multi-router topologies, test matrices, and workflow orchestration are **out of scope** for the CLI and library. Provide `examples/` with Makefiles and `bun:test` scripts to inspire, but don't build a framework. Users (and their AI agents) compose quickchr instances into whatever topology they need — we give them reliable building blocks.
+
+### Networking — Discover, Don't Configure
+
+For advanced networking (TAP interfaces, bridges), quickchr **discovers and presents options** but does not manage OS-level network configuration. On macOS, vmnet is straightforward (root + a QEMU flag). On Linux, TAP requires editing system files that vary by distro and network manager — that's the user's domain. quickchr will enumerate available interfaces, generate the correct QEMU flags, and link to tikoci docs for setup guides.
+
+#### SLiRP hostfwd — Why User-Mode Must Be ether1
+
+QEMU SLiRP (`-netdev user`) hostfwd **requires** the guest to have an IP address (default `10.0.2.15`) on the SLiRP-connected interface. Without it, `hostfwd` accepts TCP connections on the host side (creating a half-open state) but the guest never receives data — HTTP requests hang until timeout.
+
+RouterOS auto-creates a DHCP client only on ether1. SLiRP includes a DHCP server that assigns `10.0.2.15`. Therefore **SLiRP must be ether1** for zero-config provisioning. This is why `user` is always the first network in multi-NIC configurations.
+
+When adding shared/bridged as ether2+, a manual DHCP client is needed:
+```
+POST /rest/ip/dhcp-client/add
+{"interface":"ether2","use-peer-dns":"yes","add-default-route":"yes","default-route-distance":"2"}
+```
+
+The `default-route-distance=2` ensures the shared route is backup — SLiRP ether1 remains the primary gateway, avoiding ECMP dual-gateway side effects.
+
+**TCG hazard:** SLiRP half-open connections (TCP connect succeeds, data never flows) burn the full per-probe HTTP timeout in `waitForBoot`. Under cross-arch TCG where TCP round-trips are slow, this compounds badly. Lab: `test/lab/slirp-hostfwd/`.
+
+### Platform Priority
+
+macOS → Linux → Windows. Mac and Linux share most code paths with minor `#ifdef`-style branches. Windows is tracked but lower priority — larger RouterOS admin audience there, but fewer recipes and harder to test. Windows CI runner planned after the existing macOS/Linux matrix is stable.
+
+### CLI Design
+
+Tighten before expanding. New subcommands (`logs`, `exec`, `console`) wait for a full command tree review. The CLI should be discoverable without paging `--help` — shell completions help more than a long command list. Use multipass and virsh as reference points for symmetry, not to copy.
+
+### RouterOS Verification
+
+Always read back what we write. One extra REST API call after a provisioning action (license, user, package) catches version-specific command drift early. Surface errors with actionable hints rather than silent failures.
+
+### Provisioning Scope
+
+quickchr provisions at first boot and (optionally) on restart:
+- **User creation** — create user, set password, optionally disable admin
+- **Package install** — SCP `.npk` files, reboot to activate
+- **License** — `/system/license/renew` for trial
+- **Device-mode** — `/system/device-mode/update mode=rose container=yes ...` for restricted features (containers, traffic-gen, routerboard). Opt-in: not configured unless explicitly requested via CLI `--device-mode` or API `deviceMode` option. CHR ships with `mode=advanced` which is sufficient for most use cases. Device-mode requires a hard QEMU power-cycle to confirm changes — this is the MikroTik-mandated confirmation mechanism (physical button press on real hardware, cold reboot on VM). The wizard defaults to `rose` when the user opts in, since it enables containers. See: https://help.mikrotik.com/docs/spaces/ROS/pages/93749258/Device-mode
+- **Config import** — planned: load `.rsc` or `.backup` at creation time
+
+Provisioning via REST API is preferred (simple HTTP calls). Serial console provisioning (prompt detection + buffer tracking, as in chr-armed) is a fallback for locked environments. Key lessons from chr-armed serial work: use `\r` not `\r\n` on PTY; accumulate buffer with offset tracking to prevent re-matching; detect prompts dynamically, don't use fixed delays.
+
+### Exec Transport Design
+
+`quickchr exec` supports multiple transports via `--via=auto|ssh|rest|qga`:
+- **auto** (default) — currently REST only; future: try SSH first, fall back to REST `/execute`
+- **rest** (implemented) — POST to `/rest/execute` with `{"script": "<command>"}` (RouterOS 7.1+). No SSH needed. 60-second server-side timeout. Uses `resolveAuth()` for smart credential resolution.
+- **ssh** (planned) — full RouterOS CLI, supports interactive commands, requires `sshpass`
+- **qga** (implemented) — QEMU Guest Agent commands (x86 only today, ARM64 pending MikroTik fix)
+
+**Credential resolution** (`src/lib/auth.ts`): Priority order is (1) explicit `--user`/`--password` override, (2) provisioned user from `machine.json` (`state.user`), (3) CHR default `admin:` (empty password). Both `exec()` and `rest()` on ChrInstance use this.
+
+Output formatting via `--json` flag. RouterOS trick for structured output: wrap commands in `[:serialize to=json [<routeros-cmd>]]` to get JSON from any CLI command. For REST-to-CLI mapping, see tikoci/restraml `lookup.html`.
+
+### Examples Philosophy
+
+Three representations of each scenario, targeting different audiences:
+- **Makefile** — recipe-driven, targets as documentation (tikoci tradition, see tikoci/netinstall). Agents read targets; humans run `make`.
+- **bun:test** — library API, TypeScript. First-class integration tests. The "source of truth."
+- **Python** — subprocess around CLI. The language agents and network engineers both reach for. Demonstrates quickchr is a real tool, not just a library.
+
+Building examples early is a form of "anchor testing" for the CLI surface — it finds ergonomic issues before we commit to new commands.
+
+### Document Maintenance
+
+DESIGN.md and BACKLOG.md are living documents. At the end of any significant work session, agents should review whether new implementation details, design decisions, or discovered constraints belong in DESIGN.md, and whether completed/new work should update BACKLOG.md. Treat this as a lightweight checklist, not a gate.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tikoci and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,334 @@
+# quickchr
+
+> **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.
+
+CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU.
+
+## Quick Start
+
+### Prerequisites
+
+- [Bun](https://bun.sh) runtime
+- [QEMU](https://www.qemu.org) with `qemu-system-x86_64` and/or `qemu-system-aarch64`
+- `qemu-img` for disk resize and extra-disk features (`--boot-size`, `--add-disk`, `quickchr disk`)
+- UEFI firmware (edk2) for arm64 CHR
+
+Install QEMU:
+
+```bash
+# macOS
+brew install qemu
+
+# Ubuntu/Debian
+sudo apt install qemu-system-x86 qemu-system-arm qemu-efi-aarch64 qemu-utils
+
+# Fedora/RHEL
+sudo dnf install qemu-kvm qemu-system-aarch64 edk2-aarch64 qemu-img
+
+# Arch
+sudo pacman -S qemu-full
+```
+
+```powershell
+# Windows — install QEMU (qemu-img is included)
+winget install SoftwareFreedomConservancy.QEMU
+
+# Install Bun (PowerShell — matches bun.sh official install docs)
+powershell -c "irm bun.sh/install.ps1 | iex"
+# Alternative: winget install Oven-sh.Bun
+```
+
+### Install
+
+CLI:
+
+```bash
+bun install -g @tikoci/quickchr
+quickchr doctor
+```
+
+Library:
+
+```bash
+bun add @tikoci/quickchr
+```
+
+### CLI Usage
+
+The easiest way to start is the interactive wizard — it walks through
+every option and starts the CHR for you:
+
+```bash
+quickchr setup
+```
+
+![quickchr setup wizard walkthrough](./docs/images/wizard-demo.gif)
+
+Or run `quickchr` with no arguments on a TTY to get the same wizard
+automatically. See [MANUAL.md §3 setup](./MANUAL.md#setup) for a
+step-by-step breakdown of every wizard prompt.
+
+All wizard options are also available as flags for scripting:
+
+```bash
+# Create a machine without starting it
+quickchr add --name my-chr --channel stable --arch arm64
+
+# Create with a resized boot disk and extra blank disks
+quickchr add --name lab --boot-size 1G --add-disk 512M --add-disk 2G
+
+# Start an existing machine
+quickchr start my-chr
+
+# Create and start in one step
+quickchr start --name throwaway --version 7.22.1 --boot-size 2G
+
+# List instances (table view)
+quickchr list
+
+# Detailed status for one instance
+quickchr status my-chr
+
+# Stop an instance
+quickchr stop my-chr
+
+# Stop all instances
+quickchr stop --all
+
+# Run a RouterOS CLI command on a running instance
+quickchr exec my-chr /system/resource/print
+quickchr exec my-chr ":put [/system/routerboard/get serial-number]"
+
+# Attach to serial console of a running instance (exit: Ctrl-A X)
+quickchr console my-chr
+
+# Tail QEMU log
+quickchr logs my-chr
+quickchr logs my-chr --follow
+
+# Query live machine config (license, device-mode, admin users)
+quickchr get my-chr
+quickchr get my-chr license
+quickchr get my-chr device-mode --json
+
+# Manage snapshots (requires qcow2 boot disk)
+quickchr snapshot my-chr list
+quickchr snapshot my-chr save before-upgrade
+quickchr snapshot my-chr load before-upgrade
+quickchr snapshot my-chr delete before-upgrade
+
+# Apply or renew a trial license
+quickchr license my-chr
+
+# Network discovery and virtual socket management
+quickchr networks
+quickchr networks sockets
+
+# Set up shell completions (bash/zsh/fish)
+quickchr completions
+
+# Reset disk to fresh image
+quickchr clean my-chr
+
+# Inspect disk layout
+quickchr disk lab
+
+# Remove instance entirely
+quickchr remove my-chr
+
+# Check prerequisites
+quickchr doctor
+```
+
+### Create / Start Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--version <ver>` | RouterOS version (e.g., 7.22.1) | Latest stable |
+| `--channel <ch>` | stable, long-term, testing, development | stable |
+| `--arch <arch>` | arm64 or x86 | Host native |
+| `--name <name>` | Instance name | Auto-generated |
+| `--cpu <n>` | vCPU count | 1 |
+| `--mem <mb>` | Memory in MB | 512 |
+| `--boot-disk-format <f>` | Boot disk format: qcow2\|raw | qcow2 |
+| `--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`. | |
+| `--bg` / `--background` | Run in background (default) | true |
+| `--fg` / `--foreground` | Run in foreground — serial console on stdio | |
+| `--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 | |
+| `--disable-admin` | Disable the default admin account | |
+| `--no-secure-login` | Keep admin with no password (skip managed account creation) | |
+| `--add-network <spec>` | Add a network NIC (repeatable). Specs: `user`, `shared`, `bridged:<iface>`, `socket::<name>`, `tap:<iface>`. Default: single user NIC. | |
+| `--no-network` | Start with no NICs (headless) | |
+| `--no-winbox` | Exclude WinBox port mapping | |
+| `--no-api-ssl` | Exclude API-SSL port mapping | |
+| `--license-level <l>` | Apply trial license: p1, p10, unlimited | |
+| `--license-account <a>` | MikroTik account email | env `MIKROTIK_WEB_ACCOUNT` |
+| `--license-password <p>` | MikroTik account password | env `MIKROTIK_WEB_PASSWORD` |
+| `--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 | |
+| `--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 | |
+
+### RouterOS Provisioning Support Policy
+
+quickchr separates **boot-only** machine management from **post-boot provisioning**.
+
+- **Boot-only / QEMU-local features work on older RouterOS 7.x builds:** image download, boot/start, disk resize, extra disks, network attachment, and port mappings.
+- **Post-boot provisioning is validated/tested on RouterOS 7.20.8+ only:** package install, managed login or custom user creation, disabling admin, CHR license operations, and device-mode changes.
+- This is a **quickchr support policy**, not a RouterOS claim that older versions can never work. We intentionally stop at the first long-term baseline to avoid version-specific provisioning traps that are not covered by tests.
+- If you plan to provision, prefer **`--channel long-term`** or an explicit version **`>= 7.20.8`**.
+
+| Feature | Minimum RouterOS | Notes |
+|---------|------------------|-------|
+| Boot / start / stop | Any RouterOS 7.x | Boot-only path; no post-boot RouterOS mutations |
+| 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 |
+| Package install / install-all-packages | 7.20.8+ | Post-boot provisioning |
+| License apply / renew | 7.20.8+ | Post-boot provisioning |
+| Device-mode changes | 7.20.8+ | Post-boot provisioning; intentionally unsupported below the baseline |
+
+### Background vs Foreground Mode
+
+By default `quickchr start` runs QEMU in the **background**: QEMU is spawned as a detached process and the command returns once CHR has booted. Use `quickchr list`, `quickchr status`, and `quickchr stop` to manage it.
+
+```bash
+# Background (default) — returns after CHR finishes booting
+quickchr start --channel stable
+
+# Foreground — serial console attached to your terminal
+quickchr start --channel stable --fg
+```
+
+In **foreground** mode, your terminal becomes the CHR serial console. Use these key sequences:
+
+| Key | Action |
+|-----|--------|
+| `Ctrl-A X` | Exit QEMU and return to shell |
+| `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.
+
+### Disk Support
+
+- The CHR boot image starts as raw. Using `--boot-size` converts it to qcow2 and resizes it before first boot.
+- Extra disks from `--add-disk` are always created as blank qcow2 images.
+- `quickchr clean <name>` removes any resized boot disk and extra disks, then recreates them from the saved machine config.
+- `quickchr disk <name>` shows the stored disk layout. If `qemu-img` is installed, it also shows virtual and actual sizes.
+- `quickchr snapshot` manages qcow2 internal snapshots (requires a qcow2 boot disk).
+
+### Multi-NIC Networking
+
+By default each CHR gets a single user-mode NIC (SLIRP). Use `--add-network` to add more NICs or replace the default:
+
+```bash
+# Two CHRs on a shared L2 segment via socket_vmnet (macOS) or bridge (Linux)
+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)
+quickchr networks sockets create lab-switch
+quickchr start --name r1 --add-network socket::lab-switch
+quickchr start --name r2 --add-network socket::lab-switch
+
+# Bridge to a physical interface
+quickchr start --name gw --add-network user --add-network bridged:en0
+```
+
+### Port Layout
+
+Each instance gets a block of 10 ports. With the default base of 9100, the first instance maps:
+
+| Offset | Service | Default port |
+|--------|---------|-------------|
+| +0 | HTTP / REST / WebFig | 9100 |
+| +1 | HTTPS | 9101 |
+| +2 | SSH | 9102 |
+| +3 | RouterOS API | 9103 |
+| +4 | RouterOS API-SSL | 9104 |
+| +5 | WinBox | 9105 |
+| +6–+9 | Reserved (spare) | 9106–9109 |
+
+The second instance gets 9110–9119, and so on.
+
+### Library Usage
+
+```typescript
+import { QuickCHR } from "@tikoci/quickchr";
+
+// Start a CHR instance
+const chr = await QuickCHR.start({
+  name: "disk-lab",
+  channel: "stable",
+  arch: "arm64",
+  mem: 512,
+  bootSize: "1G",
+  extraDisks: ["512M", "2G"],
+});
+
+// Use REST API
+const info = await chr.rest("/system/resource");
+console.log(info);
+
+// Run a RouterOS CLI command
+const result = await chr.exec("/system/resource/print");
+console.log(result);
+
+// Stop (or remove)
+await chr.stop();
+await chr.remove();
+
+console.log(chr.state.bootDiskFormat); // "qcow2"
+console.log(chr.state.extraDisks);     // ["512M", "2G"]
+```
+
+### Use in Tests
+
+```typescript
+import { describe, test, afterAll, expect } from "bun:test";
+import { QuickCHR } from "@tikoci/quickchr";
+
+let chr: Awaited<ReturnType<typeof QuickCHR.start>>;
+
+test("boot CHR and check version", async () => {
+  chr = await QuickCHR.start({ channel: "stable" });
+
+  const resource = await chr.rest("/system/resource");
+  expect(resource["board-name"]).toBe("CHR");
+}, 120_000);
+
+afterAll(async () => {
+  if (chr) await chr.remove();
+});
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `MIKROTIK_WEB_ACCOUNT` | MikroTik.com account email (for license renewal) |
+| `MIKROTIK_WEB_PASSWORD` | MikroTik.com password (for license renewal) |
+| `QUICKCHR_INTEGRATION` | Set to `1` to run integration tests |
+
+## Documentation
+
+- **[MANUAL.md](./MANUAL.md)** — complete reference: every CLI command,
+  every library API, provisioning, channels, networking, storage,
+  errors. Source-checked.
+- **[DESIGN.md](./DESIGN.md)** — architecture, layers, design principles.
+- **[CONTRIBUTING.md](./CONTRIBUTING.md)** — dev setup and `bun run check`.
+- **[CHANGELOG.md](./CHANGELOG.md)** — release history.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@tikoci/quickchr",
+  "version": "0.2.0",
+  "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
+  "module": "src/index.ts",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "bin": {
+    "quickchr": "src/cli/index.ts"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "DESIGN.md"
+  ],
+  "scripts": {
+    "check": "bun run lint:biome && bun run lint:typecheck && bun run lint:markdown",
+    "lint": "biome check . && tsc --noEmit",
+    "lint:biome": "biome check .",
+    "lint:typecheck": "tsc --noEmit",
+    "lint:markdown": "bunx markdownlint-cli2 '**/*.md'",
+    "test": "bun test test/unit/",
+    "test:examples": "bun test examples/",
+    "test:integration": "QUICKCHR_INTEGRATION=1 bun test test/integration/",
+    "test:all": "QUICKCHR_INTEGRATION=1 bun test test/unit/ test/integration/ examples/",
+    "dev": "bun run src/cli/index.ts",
+    "release": "bun scripts/release.ts",
+    "install:deps:ubuntu": "sudo apt-get --yes install qemu-system-x86 qemu-system-arm qemu-efi-aarch64 qemu-utils socat && curl -fsSL https://bun.sh/install | bash"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@types/bun": "^1.3.11",
+    "markdownlint-cli2": "^0.21.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "fflate": "^0.8.2",
+    "typescript": "^5"
+  },
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tikoci/quickchr.git"
+  },
+  "keywords": [
+    "mikrotik",
+    "routeros",
+    "chr",
+    "qemu",
+    "virtualization",
+    "network-testing"
+  ]
+}