mikropkl CLAUDE.md

CLAUDE.md — Project Context for AI Agents

This file documents the mikropkl project for AI coding agents. Read it before making changes.

Project Purpose

mikropkl produces declarative virtual machine packages for MikroTik RouterOS CHR using pkl. The primary output is UTM bundles (.utm directories) for macOS, with QEMU launch scripts (qemu.sh + qemu.cfg) for Linux and CI testing.

The goal is to streamline getting RouterOS CHR running — whether checking a config on an older version, trying a new feature, or bringing up multiple CHRs for network testing. Without mikropkl, getting CHR running involves downloading images from MikroTik, navigating several UI dialogs or constructing long qemu-system-* command lines. mikropkl replaces all that with declarative pkl manifests and make.

Two delivery paths:

• UTM (macOS-first): utm://downloadVM?url=... one-click install, or download ZIP and open. UTM handles the VM lifecycle.
• QEMU (macOS + Linux): Each .utm bundle includes qemu.sh + qemu.cfg. Unpack the ZIP, run ./qemu.sh, get a RouterOS prompt. Also used for CI validation.

The .utm bundle is a ZIP archive — structurally portable. A future mikropkl CLI tool could manage QEMU-based instances from ~/.local/ or ~/.mikropkl/, providing a Linux-native experience similar to UTM's on macOS.

Platform focus: macOS and Linux. Windows/WSL is not a target — we won't document setup steps, but QEMU on WSL should work since the scripts are POSIX shell. If someone reports a WSL issue, we'd consider it. The core challenge on Windows is that there's no default virtualization platform equivalent to KVM or Apple's Hypervisor.framework, so the kind of automation mikropkl does doesn't map cleanly to "brew install qemu" or "apt install qemu".

Directory Structure

Makefile              ← two-phase build orchestration (source of truth for building)
Manifests/            ← one .pkl file per machine variant (amend Templates/)
Templates/            ← mid-level pkl templates (amend Pkl/utmzip.pkl)
Pkl/                  ← core pkl modules
  utmzip.pkl          ← root module: defines all file outputs for a .utm bundle
  QemuCfg.pkl         ← generates qemu.cfg (ini) + qemu.sh (launcher) for direct QEMU use
  Libvirt.pkl         ← generates libvirt.xml (experimental, disabled by default)
  CHR.pkl             ← RouterOS CHR download URL logic and SVG icon helpers
  UTM.pkl             ← UTM-specific types (SystemArchitecture, BackendType, etc.)
  Randomish.pkl       ← deterministic pseudo-random helpers (MAC address generation)
  URL.pkl, SVG.pkl    ← helper modules
  chr-version.pkl     ← resolves RouterOS version from release channel (env: CHR_VERSION)
Files/
  efi_vars.fd         ← UEFI variable store (copied into Apple-backend bundles)
  QEMU.md             ← user-facing QEMU deployment guide
Machines/             ← build output (git-ignored except .url/.size placeholders)
Tests/                ← anchor tests (see Tests/README.md); `make test`, no QEMU needed
Lab/                  ← local experiments, debug scripts, investigation notes (NOT build artifacts)
  libvirt/            ← libvirt experiment docs and notes (see LIBVIRT.md inside)
  qemu-arm64/         ← QEMU aarch64 boot investigation (see NOTES.md inside)
  x86-direct-kernel/  ← x86 direct kernel boot experiments (see NOTES.md inside)
.github/workflows/
  chr.yaml            ← builds and releases UTM packages to GitHub Releases
  test.yaml           ← anchor tests on push/PR (no QEMU): accel decision table
  qemu-test.yaml      ← boots each QEMU machine via qemu.sh and runs REST API checks
  libvirt-test.yaml   ← historical: precursor to qemu-test.yaml (parses XML → raw QEMU)
  auto.yaml           ← automated trigger for chr.yaml on new RouterOS versions