From b4114a173265cc91d52465cd5598053764632f32 Mon Sep 17 00:00:00 2001 From: Rick Peters Date: Thu, 24 Sep 2026 10:05:46 +0200 Subject: [PATCH 1/6] feat: Visible wizard runs, one-step VM reset and screenshots; skill updates - scripts/vmreset.sh, vmwatch.sh (wizard in a visible Konsole), vmshot.sh. - vmstate.sh: DKMS per kernel, DKMS override, headers service, dark LnF, wallpaper, layout backup. - cmp.sh: also kcminputrc and ksplashrc. - Skill: pitfalls and checks from testing cachyos-gamescope-boot 0.7.0. --- .claude/skills/cachyos-vm-testing/SKILL.md | 65 ++++++++++++++++++++-- README.md | 3 + scripts/cmp.sh | 2 +- scripts/vmreset.sh | 45 +++++++++++++++ scripts/vmshot.sh | 18 ++++++ scripts/vmstate.sh | 5 +- scripts/vmwatch.sh | 32 +++++++++++ 7 files changed, 164 insertions(+), 6 deletions(-) create mode 100755 scripts/vmreset.sh create mode 100755 scripts/vmshot.sh create mode 100755 scripts/vmwatch.sh diff --git a/.claude/skills/cachyos-vm-testing/SKILL.md b/.claude/skills/cachyos-vm-testing/SKILL.md index e73e811..5638fe7 100644 --- a/.claude/skills/cachyos-vm-testing/SKILL.md +++ b/.claude/skills/cachyos-vm-testing/SKILL.md @@ -9,16 +9,35 @@ The wizard (`setup-gamescope-boot.sh` + `lib/*.sh`) opens a menu that detects which components are on and toggles them to match the user's choice. Menu order: 1. SteamOS conversion (boot into gaming mode via autologin, Return to Gaming Mode shortcut, Steam desktop autostart) -2. SteamOS theme (Vapor) +2. SteamOS theme (installs `cachyos-vapor` and applies the Vapor global theme with its desktop and window layout; needs a running Plasma session) 3. Steam Deck/Machine icons (`STEAM_GAMEPADUI_ARGS -steamos3`) 4. Single user mode (SDDM, no lock screen/user switching/log out; enabling it enables 1, disabling 1 disables it) -5. Steam Machine support (only on DMI Valve/Fremont: leds-valve-dkms-git, udev rule, steamos-manager) +5. Steam Machine support (only on DMI Valve/Fremont: leds-valve-dkms-git built for every kernel via `/etc/dkms/leds-valve-dkms.conf`, `ensure-kernel-headers.service`, udev rule, steamos-manager) Undo journals live in `~/.local/state/cachyos-gamescope-boot/` in the guest. Run everything from the root of this repo on the host. Defaults: user `theupriser`, SSH port `2222` (the scripts take `VM_USER` / `VM_PORT` / `VM_HOST`). +The VM's disk, `vars*.fd` and `run.sh` copy may live outside the repo +(`~/vms/cachyos-test` on the main dev machine). Find it with +`readlink /proc/$(pgrep -f '^qemu-system')/cwd` when the VM runs; the +snapshot commands below run in that directory. `scripts/vmreset.sh` takes +`VM_DIR` and defaults to the repo if it holds `disk.qcow2`, else `~/vms/cachyos-test`. + +## Quick start (the usual loop) + +```bash +scripts/vmreset.sh --fremont # restore ssh-ready, boot, mount repo, autologin, wait for Plasma +scripts/cmp.sh save # baseline of the KDE configs +scripts/vmwatch.sh '1\n3\n\ny\nn\n' "Theme only" # wizard in a visible Konsole in the VM +scripts/vmstate.sh # component state +scripts/vmshot.sh /path/shot.png # screenshot, then view it +``` + +Prefer `vmwatch.sh` over `vmrun.sh` when the user is watching the QEMU +window: `vmrun.sh` runs invisibly over SSH, so they see nothing happen. + ## VM lifecycle Start in the background: @@ -68,6 +87,10 @@ sudoers rule for the test user. ## Mounting the project repo +The mount is lost on every reboot (unless the fstab line below was added). +Without it the wizard fails with `/mnt/setup-gamescope-boot.sh: No such file +or directory`, which is easy to miss in filtered output. Remount after each reboot. + The repo (`REPO`, default `~/projects/cachyos-gamescope-boot`) is shared read-write as 9p tag `repo`. The `ssh-ready` snapshot does not mount it: @@ -124,9 +147,24 @@ restart question. | `'2\n\ny\nn\n'` | toggle the theme | | `'a\ny\nn\n'` | re-apply what is on | | `'q\n'` | just show the menu | +| `'1\n3\n\ny\nn\n'` | from all-off: theme only (Steam Machine too with `--fremont`; add `5\n` to drop it) | +| `'1\n\ny\nn\n'` | from a state where 1 is off: turn the conversion on | + +**Know the starting ticks before choosing input.** When *everything* is off +(fresh snapshot, or after turning the last component off), the menu treats it +as a first run and pre-ticks **all** components, so `2` means "theme off, +rest on". Otherwise the ticks show what is on now. Unticking 1 also unticks 4, +and ticking 4 ticks 1 again, so `'1\n3\n4\n...'` ends with the conversion on. +When unsure, run `'q\n'` first and read the ticks. + +`a` only re-applies components that are already on: it does not retry one that +failed. Re-applying the conversion also resets the autologin session to +gamescope, so set it back to plasma before the next reboot (below). ## Gamescope does not render in this VM +(Also after any re-apply that includes the conversion.) + No suitable Vulkan (venus is unstable with the host NVIDIA driver). After enabling the conversion, before rebooting: @@ -157,6 +195,11 @@ DM, set the session, start it). `scripts/cmp.sh save` stores a baseline of the KDE/GTK configs in the guest (`~/.cache/vm-baseline`, not `/tmp`); `scripts/cmp.sh` diffs against it. +After changing the theme, `cmp.sh` should show only spectacle's +`kglobalshortcutsrc` entries (from screenshots) and keys whose value equals +`~/.config/kdedefaults` (e.g. `ColorScheme=BreezeDark`, `widgetStyle=Breeze`): +KDE drops or writes those on its own. + ## Reboot checks - Single user mode on: SDDM autologin without greeter: `pgrep sddm-greeter` empty, `plasmashell` running. @@ -170,20 +213,27 @@ autologin, then (all passed last run; `scripts/vmstate.sh` after every step): 1. Fresh run turning everything on (`'\ny\nn\n'`), set session to plasma, reboot. 2. Rerun: all shown on, "Everything is already the way you want it". 3. `a` re-apply: no duplicate journal entries. -4. Theme off: look restored (CachyOS wallpaper, floating 30px panel, `org.cachyos.hello` launcher icon). +4. Theme on: Steam Deck wallpaper, full-width 46px panel, `distributor-logo-steamdeck` launcher icon, `dark-lnf=com.valve.vapor.desktop` (Brightness & Color's Dark Mode toggle is on, hint "Switch to Breeze"); with single user on, kickoff keeps `primaryActions=3`. Theme off: CachyOS wallpaper, floating 30px panel, CachyOS launcher icon, BreezeDark colors (not light), `cachyos-vapor` removed, `cmp.sh` clean. 5. Single user off: switches to plasmalogin + sync bridge + sudoers; shortcut Exec uses `sudo -n`. 6. Single user on: back to SDDM. 7. Icons + Steam Machine support off: driver, udev rule, modules-load, steamos-manager removed; yay kept. +7b. DKMS: `vmstate.sh` shows `installed` for every kernel. Headers at boot: + `sudo pacman -R --noconfirm linux-cachyos-lts-headers` (DKMS drops the LTS + build), set the session to plasma, reboot, then `journalctl -b -u + ensure-kernel-headers` shows the install and DKMS lists LTS again. 8. Conversion off: single user auto-unticked, plasmalogin `[Autologin]` back to CachyOS's `Session=plasma`, journals empty. 9. Remove the test autologin file, reboot: normal login screen. ## Visual checks +`scripts/vmshot.sh ` does the below. Starting `spectacle` straight +from SSH core-dumps; it has to run as a user unit (`systemd-run --user --wait`). + ```bash ssh -p 2222 -o BatchMode=yes theupriser@localhost bash -s << 'EOF' export XDG_RUNTIME_DIR=/run/user/1000 WAYLAND_DISPLAY=wayland-0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus qdbus6 org.kde.plasmashell /PlasmaShell org.kde.PlasmaShell.activateLauncherMenu # optional, toggles -sleep 1; spectacle -b -n -f -o /tmp/x.png +sleep 1; systemd-run --user --wait -q spectacle -b -n -f -o /tmp/x.png EOF scp -P 2222 theupriser@localhost:/tmp/x.png /tmp/x.png # then view it ``` @@ -194,6 +244,13 @@ them with `systemd-run --user `. ## Pitfalls +- Broken mirror: `mirror5.krfoss.org` served a bad `.sig` ("Maximum file size + exceeded"), failing the conversion's package install. Comment it out: + `sudo sed -i '/krfoss/s/^Server/#Server/' /etc/pacman.d/*mirrorlist*`. +- Windows open in the snapshot (System Settings, CachyOS Hello) show stale + data (e.g. a theme list from before `cachyos-vapor`) and cover screenshots; + `vmreset.sh` closes them. + - The guest's `/tmp` is cleared on reboot; keep baselines elsewhere. - The fake Fremont DMI makes leds-valve load 17 LED nodes, but there is no real hardware. - shellcheck: `sudo pacman -S shellcheck`, then in `/mnt`: diff --git a/README.md b/README.md index 3877ae5..ec0caf6 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,10 @@ read-write as 9p tag `repo`; in the guest: ## Helper scripts +- `scripts/vmreset.sh [--fremont]`: restore `ssh-ready`, boot, mount the repo, autologin into Plasma - `scripts/vmrun.sh ''`: run the wizard in the guest's Plasma session with scripted input +- `scripts/vmwatch.sh '' [label]`: same, but in a visible Konsole window in the VM +- `scripts/vmshot.sh `: screenshot the guest's desktop - `scripts/vmstate.sh`: print the state of every wizard component - `scripts/cmp.sh [save]`: save / diff the guest's KDE configs against a baseline diff --git a/scripts/cmp.sh b/scripts/cmp.sh index ab4976f..4239285 100755 --- a/scripts/cmp.sh +++ b/scripts/cmp.sh @@ -10,7 +10,7 @@ mode="${1:-diff}" # The guest login shell is fish, so pass values in through the bash script itself. { printf 'mode=%q base=%q\n' "$mode" "${BASELINE:-}"; cat << 'REMOTE' base="${base:-$HOME/.cache/vm-baseline}" -files="kdeglobals plasmarc plasmashellrc kwinrc kwinrulesrc konsolerc kscreenlockerrc kglobalshortcutsrc gtk-3.0/settings.ini gtk-4.0/settings.ini plasma-org.kde.plasma.desktop-appletsrc" +files="kdeglobals kcminputrc ksplashrc plasmarc plasmashellrc kwinrc kwinrulesrc konsolerc kscreenlockerrc kglobalshortcutsrc gtk-3.0/settings.ini gtk-4.0/settings.ini plasma-org.kde.plasma.desktop-appletsrc" if [ "$mode" = save ]; then for f in $files; do mkdir -p "$(dirname "$base/config/$f")"; cp -f ~/.config/"$f" "$base/config/$f" 2>/dev/null || true; done echo "baseline saved to $base"; exit 0 diff --git a/scripts/vmreset.sh b/scripts/vmreset.sh new file mode 100755 index 0000000..335ffc4 --- /dev/null +++ b/scripts/vmreset.sh @@ -0,0 +1,45 @@ +#!/bin/bash +# Reset the test VM to a snapshot and bring it up logged in to Plasma: +# power off, restore the snapshot (disk + vars.fd), start it, mount the repo +# on /mnt, set up the test autologin and wait for plasmashell. +# scripts/vmreset.sh [run.sh flags...] e.g. scripts/vmreset.sh --fremont +# Env: VM_USER / VM_PORT / VM_HOST, SNAPSHOT (ssh-ready), +# VM_DIR (where disk.qcow2 lives: this repo if it has one, else ~/vms/cachyos-test), +# VM_LOG (QEMU output, default $VM_DIR/vm.log). +set -euo pipefail +. "$(dirname "$0")/common.sh" +repo="$(cd "$(dirname "$0")/.." && pwd)" +if [[ -z "${VM_DIR:-}" ]]; then + if [[ -f "$repo/disk.qcow2" ]]; then VM_DIR="$repo"; else VM_DIR="$HOME/vms/cachyos-test"; fi +fi +SNAPSHOT="${SNAPSHOT:-ssh-ready}" +VM_LOG="${VM_LOG:-$VM_DIR/vm.log}" + +if pgrep -f '^qemu-system' >/dev/null; then + echo "Powering off the running VM..." + vm_ssh sudo systemctl poweroff 2>/dev/null || true + for _ in $(seq 60); do pgrep -f '^qemu-system' >/dev/null || break; sleep 2; done + pgrep -f '^qemu-system' >/dev/null && { echo "VM didn't shut down; stop it first." >&2; exit 1; } +fi + +echo "Restoring snapshot '$SNAPSHOT' in $VM_DIR..." +cd "$VM_DIR" +qemu-img snapshot -a "$SNAPSHOT" disk.qcow2 +cp "vars.$SNAPSHOT.fd" vars.fd + +echo "Starting the VM ($*)..." +nohup ./run.sh "$@" > "$VM_LOG" 2>&1 & +for _ in $(seq 100); do vm_ssh -o ConnectTimeout=3 true 2>/dev/null && break; sleep 3; done +vm_ssh true || { echo "No SSH after 5 minutes; see $VM_LOG" >&2; exit 1; } + +vm_ssh bash -s << 'REMOTE' +sudo mount -t 9p -o trans=virtio,version=9p2000.L repo /mnt +sudo mkdir -p /etc/plasmalogin.conf.d +printf '[Autologin]\nUser=%s\nSession=plasma.desktop\n' "$USER" | sudo tee /etc/plasmalogin.conf.d/00-test-autologin.conf >/dev/null +sudo systemctl restart plasmalogin +for _ in $(seq 40); do pgrep -u "$USER" -x plasmashell >/dev/null && break; sleep 3; done +sleep 10 +# Windows the snapshot opens at login would cover the screenshots. +pkill -u "$USER" systemsettings; pkill -u "$USER" cachyos-hello +pgrep -u "$USER" -x plasmashell >/dev/null && echo "Logged in to Plasma." || { echo "Plasma did not start." >&2; exit 1; } +REMOTE diff --git a/scripts/vmshot.sh b/scripts/vmshot.sh new file mode 100755 index 0000000..42dee5d --- /dev/null +++ b/scripts/vmshot.sh @@ -0,0 +1,18 @@ +#!/bin/bash +# Screenshot the guest's Plasma session to a file on the host. +# scripts/vmshot.sh +# spectacle started straight from SSH crashes; run it as a user unit so it +# gets the session's environment. +# Env: VM_USER (theupriser), VM_PORT (2222), VM_HOST (localhost), GUEST_UID (1000). +set -euo pipefail +. "$(dirname "$0")/common.sh" +out="${1:?usage: $0 }" +{ printf 'uid=%q\n' "${GUEST_UID:-1000}"; cat << 'REMOTE' +export XDG_RUNTIME_DIR=/run/user/$uid DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$uid/bus +rm -f /tmp/vmshot.png +sleep 2 +systemd-run --user --wait -q spectacle -b -n -f -o /tmp/vmshot.png +REMOTE +} | vm_ssh bash -s +scp -q -P "$VM_PORT" "$VM_USER@$VM_HOST:/tmp/vmshot.png" "$out" +echo "$out" diff --git a/scripts/vmstate.sh b/scripts/vmstate.sh index 3e7e271..e6151eb 100755 --- a/scripts/vmstate.sh +++ b/scripts/vmstate.sh @@ -9,11 +9,14 @@ echo "DM=$(systemctl show -p Id --value display-manager) sddm-autologin=$(yn /et echo "plasmalogin [Autologin]: $(sed -n '/^\[Autologin\]/,/^\[/p' /etc/plasmalogin.conf | grep -v '^\[' | tr '\n' ' ')" echo "shortcut=$(grep -h Exec= ~/Desktop/*Gaming*.desktop 2>/dev/null || echo none)" echo "steam-unit=$([ -f ~/.config/systemd/user/steam-desktop-autostart.service ] && systemctl --user is-enabled steam-desktop-autostart.service || echo none) glyphs=$(yn ~/.config/environment.d/99-gamescope-steam-glyphs.conf)" -echo "lnf=$(kreadconfig6 --file kdeglobals --group KDE --key LookAndFeelPackage) scheme=$(kreadconfig6 --file kdeglobals --group General --key ColorScheme) gtk=$(kreadconfig6 --file ~/.config/gtk-3.0/settings.ini --group Settings --key gtk-theme-name) font=$(kreadconfig6 --file kdeglobals --group General --key font)" +echo "lnf=$(kreadconfig6 --file kdeglobals --group KDE --key LookAndFeelPackage) dark-lnf=$(kreadconfig6 --file kdeglobals --group KDE --key DefaultDarkLookAndFeel) scheme=$(kreadconfig6 --file kdeglobals --group General --key ColorScheme) cursor=$(kreadconfig6 --file kcminputrc --group Mouse --key cursorTheme) vapor-pkg=$(pacman -Q cachyos-vapor 2>/dev/null || echo none) layout-backup=$(yn ~/.local/state/cachyos-gamescope-boot/theme-layout)" +echo "wallpaper: $(grep -h '^Image=' ~/.config/plasma-org.kde.plasma.desktop-appletsrc | sort -u | tr '\n' ' ')" echo "lock_screen=$(kreadconfig6 --file kdeglobals --group 'KDE Action Restrictions' --key action/lock_screen) autolock=$(kreadconfig6 --file kscreenlockerrc --group Daemon --key Autolock) metaL=$(kreadconfig6 --file kglobalshortcutsrc --group ksmserver --key 'Lock Session' | cut -c1-12)" echo "panel: $(grep -A1 '^\[PlasmaViews\]\[Panel [0-9]*\]$' ~/.config/plasmashellrc | grep floating | tr '\n' ' ') $(grep -h 'thickness' ~/.config/plasmashellrc | tr '\n' ' ')" echo "kickoff: $(grep -E '^(primaryActions|systemFavorites|icon)=' ~/.config/plasma-org.kde.plasma.desktop-appletsrc | tr '\n' ' ')" echo "leds-pkg=$(pacman -Q leds-valve-dkms-git 2>/dev/null || echo none) steamos-manager=$(pacman -Q steamos-manager 2>/dev/null || echo none)/$(systemctl is-active steamos-manager 2>/dev/null) udev=$(yn /etc/udev/rules.d/70-valve-leds-user.rules) module=$(lsmod | grep -c leds_valve) leds=$(ls /sys/class/leds | grep -c valve)" +echo "dkms: $(dkms status leds-valve-dkms 2>/dev/null | cut -d, -f2- | sed 's/, x86_64//' | tr '\n' ';') kernels: $(ls /usr/lib/modules | tr '\n' ' ')" +echo "dkms-override=$(yn /etc/dkms/leds-valve-dkms.conf) headers-check=$(systemctl is-enabled ensure-kernel-headers.service 2>/dev/null || echo none)" echo "leds-owner=$(stat -c %U /sys/class/leds/valve-leds*/brightness 2>/dev/null | sort -u | tr '\n' ' ')" j=~/.local/state/cachyos-gamescope-boot echo "journals: $(ls "$j" 2>/dev/null | tr '\n' ' ')" diff --git a/scripts/vmwatch.sh b/scripts/vmwatch.sh new file mode 100755 index 0000000..22d71ca --- /dev/null +++ b/scripts/vmwatch.sh @@ -0,0 +1,32 @@ +#!/bin/bash +# Like vmrun.sh, but run the wizard in a visible Konsole window inside the +# guest's Plasma session, so someone at the QEMU window can follow along. +# Waits for the wizard to finish, then prints its log. The window stays open. +# scripts/vmwatch.sh '' ["label shown in the window"] +# Env: VM_USER (theupriser), VM_PORT (2222), VM_HOST (localhost), +# GUEST_REPO (/mnt), GUEST_UID (1000), WAIT (seconds, default 1800). +set -euo pipefail +. "$(dirname "$0")/common.sh" +input="${1:?usage: $0 '' [label]}" +label="${2:-Running the wizard}" +# The guest login shell is fish, so pass values in through the bash script itself. +{ printf 'input=%q label=%q repo=%q uid=%q wait=%q\n' "$input" "$label" "${GUEST_REPO:-/mnt}" \ + "${GUEST_UID:-1000}" "${WAIT:-1800}"; cat << 'REMOTE' +export XDG_RUNTIME_DIR=/run/user/$uid DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$uid/bus +[ -x "$repo/setup-gamescope-boot.sh" ] || { echo "$repo/setup-gamescope-boot.sh missing: mount the repo (lost after a reboot)" >&2; exit 1; } +rm -f /tmp/wizard.done +{ + echo '#!/bin/bash' + printf 'echo %q; echo %q; sleep 3\n' ">>> $label" ">>> menu input: $input" + # shellcheck disable=SC2016 + printf 'printf %q | %q 2>&1 | tee /tmp/wizard.log\n' "$input" "$repo/setup-gamescope-boot.sh" + echo 'touch /tmp/wizard.done' +} > /tmp/vmwatch-run.sh +chmod +x /tmp/vmwatch-run.sh +pkill -u "$USER" -x konsole || true +systemd-run --user -q konsole --hold -e /tmp/vmwatch-run.sh +for _ in $(seq $((wait / 2))); do [ -f /tmp/wizard.done ] && break; sleep 2; done +[ -f /tmp/wizard.done ] || echo "(still running after ${wait}s)" +sed 's/\x1b\[[0-9;]*m//g' /tmp/wizard.log +REMOTE +} | vm_ssh bash -s 2>&1 From 3733f9400a037c7568aa292bf76c07a942206902 Mon Sep 17 00:00:00 2001 From: Rick Peters Date: Thu, 24 Sep 2026 10:05:47 +0200 Subject: [PATCH 2/6] docs: Changelog --- .gitignore | 1 + CHANGELOG.md | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 CHANGELOG.md diff --git a/.gitignore b/.gitignore index cbdeb74..5791d2b 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ /* !/.gitignore !/README.md +!/CHANGELOG.md !/run.sh !/run.ps1 !/get-iso.sh diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..644bceb --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,35 @@ +# Changelog + +All notable changes, per version and per commit. Versions follow +[Semantic Versioning](https://semver.org/) and were numbered from the start +of the history. + +## 0.2.0 - 2026-09-24 + +Watchable test runs and the lessons from testing cachyos-gamescope-boot 0.7.0 +(cachyos-vapor theme, LED driver on every kernel). + +- `b4114a1` **feat: Visible wizard runs, one-step VM reset and screenshots; skill updates** + - `scripts/vmreset.sh [--fremont]`: restore `ssh-ready`, boot, mount the repo, + set up the test autologin and wait for Plasma. + - `scripts/vmwatch.sh '' [label]`: run the wizard in a visible Konsole + in the VM, so someone at the QEMU window can follow along. + - `scripts/vmshot.sh `: screenshot via a user unit (spectacle + crashes when started straight from SSH). + - `scripts/vmstate.sh`: DKMS status per kernel, the DKMS override, the kernel + headers service, the dark look-and-feel, the wallpaper and the theme's + layout backup. + - `scripts/cmp.sh`: also compares `kcminputrc` and `ksplashrc`. + - Skill: VM directory outside the repo, the menu's first-run pre-ticks and + the conversion/single-user coupling, the repo mount lost on reboot, + re-applying the conversion resets the session to gamescope, the new + theme and LED checks in the test matrix, and the broken mirror workaround. +- **docs: Changelog** + +## 0.1.1 - 2026-09-23 + +- `d2cf240` **fix: Document how to add the host SSH key to the VM** + +## 0.1.0 - 2026-09-23 + +- `97c5c56` **fix: Add CachyOS test VM dev environment and VM testing skill** From 3cdf2e11d8e9270a6f8a453a0b9fba2e841e0712 Mon Sep 17 00:00:00 2001 From: Rick Peters Date: Thu, 24 Sep 2026 10:40:36 +0200 Subject: [PATCH 3/6] feat: Fake BIOS version for testing the BIOS update item - run.sh: BIOS_VERSION=... reports that BIOS version to the guest (SMBIOS type 0). - Skill: testing the BIOS item with WIZARD_BIOS_DRY_RUN=1, and the wizard's menu loop. --- .claude/skills/cachyos-vm-testing/SKILL.md | 13 +++++++++++++ CHANGELOG.md | 7 ++++++- run.sh | 5 ++++- 3 files changed, 23 insertions(+), 2 deletions(-) diff --git a/.claude/skills/cachyos-vm-testing/SKILL.md b/.claude/skills/cachyos-vm-testing/SKILL.md index 5638fe7..e43a434 100644 --- a/.claude/skills/cachyos-vm-testing/SKILL.md +++ b/.claude/skills/cachyos-vm-testing/SKILL.md @@ -224,6 +224,19 @@ autologin, then (all passed last run; `scripts/vmstate.sh` after every step): 8. Conversion off: single user auto-unticked, plasmalogin `[Autologin]` back to CachyOS's `Session=plasma`, journals empty. 9. Remove the test autologin file, reboot: normal login screen. +## BIOS update item + +Only shown with `--fremont`, and only tickable when the guest's BIOS version +differs from Valve's newest. Fake an older one with +`BIOS_VERSION=F7F0107 ./run.sh --fremont` (SMBIOS type 0; `vmreset.sh` passes +the environment through). fwupd correctly refuses the firmware in the VM +("not for this machine's hardware"), so walk the whole flow with +`WIZARD_BIOS_DRY_RUN=1` (skips only that check, never flashes). Scripted: +`printf '6\n\ny\ny\nUPDATE\n\nq\n' | WIZARD_BIOS_DRY_RUN=1 /mnt/setup-gamescope-boot.sh`. + +The wizard loops back to the menu after every run (Enter, or `m`/`r` when a +restart is needed) until `q`; scripted input that runs out ends it like `q`. + ## Visual checks `scripts/vmshot.sh ` does the below. Starting `spectacle` straight diff --git a/CHANGELOG.md b/CHANGELOG.md index 644bceb..20d4a8b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,7 +24,12 @@ Watchable test runs and the lessons from testing cachyos-gamescope-boot 0.7.0 the conversion/single-user coupling, the repo mount lost on reboot, re-applying the conversion resets the session to gamescope, the new theme and LED checks in the test matrix, and the broken mirror workaround. -- **docs: Changelog** +- `3733f94` **docs: Changelog** +- **feat: Fake BIOS version for testing the BIOS update item** + - `BIOS_VERSION=F7F0107 ./run.sh ...` makes the guest report that BIOS + version (SMBIOS type 0), so the wizard offers the update. + - Skill: testing the BIOS item with `WIZARD_BIOS_DRY_RUN=1`, and the + wizard's menu loop. ## 0.1.1 - 2026-09-23 diff --git a/run.sh b/run.sh index 3a8abdf..aa9efaa 100755 --- a/run.sh +++ b/run.sh @@ -6,6 +6,8 @@ # --vulkan expose Vulkan to the guest (venus; needed by gamescope, can be unstable) # --fremont report the Valve Steam Machine's DMI data (for testing the wizard) # REPO defaults to $HOME/projects/cachyos-gamescope-boot. +# BIOS_VERSION=F7F0107 makes the guest report that BIOS version (DMI), e.g. +# to test the wizard's BIOS update item; the firmware itself doesn't change. # The repo is shared into the guest; mount it there with: # sudo mount -t 9p -o trans=virtio,version=9p2000.L repo /mnt # First-time SSH setup, inside the guest: @@ -17,13 +19,14 @@ repo="${REPO:-$HOME/projects/cachyos-gamescope-boot}" cdrom=() smbios=() gpu=virtio-vga-gl,xres=1920,yres=1080 +[[ -n "${BIOS_VERSION:-}" ]] && smbios+=(-smbios "type=0,version=$BIOS_VERSION") for arg in "$@"; do case "$arg" in install) cdrom=(-cdrom cachyos.iso -boot d) ;; --nvidia) export __NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia \ __EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/10_nvidia.json ;; --vulkan) gpu+=,hostmem=4G,blob=true,venus=true ;; - --fremont) smbios=(-smbios type=1,manufacturer=Valve,product=Fremont -smbios type=2,manufacturer=Valve,product=Fremont) ;; + --fremont) smbios+=(-smbios type=1,manufacturer=Valve,product=Fremont -smbios type=2,manufacturer=Valve,product=Fremont) ;; *) echo "unknown argument: $arg" >&2; exit 1 ;; esac done From c6abfd2ea8abd1dfb5786c7f150b5d291d99ab35 Mon Sep 17 00:00:00 2001 From: Rick Peters Date: Thu, 24 Sep 2026 12:28:13 +0200 Subject: [PATCH 4/6] docs: Renamed to steamify-cachyos-dev, for Steamify CachyOS README and skill point to github.com/theupriser/steamify-cachyos; local paths keep their names. --- .claude/skills/cachyos-vm-testing/SKILL.md | 4 ++-- CHANGELOG.md | 6 +++++- README.md | 7 ++++--- 3 files changed, 11 insertions(+), 6 deletions(-) diff --git a/.claude/skills/cachyos-vm-testing/SKILL.md b/.claude/skills/cachyos-vm-testing/SKILL.md index e43a434..1870e0f 100644 --- a/.claude/skills/cachyos-vm-testing/SKILL.md +++ b/.claude/skills/cachyos-vm-testing/SKILL.md @@ -1,9 +1,9 @@ --- name: cachyos-vm-testing -description: Use when testing cachyos-gamescope-boot (setup-gamescope-boot.sh) changes in the CachyOS QEMU test VM - starting/stopping the VM, restoring snapshots, running the wizard over SSH with scripted menu input, checking each component's state, reboot checks and screenshots. +description: Use when testing Steamify CachyOS (repo steamify-cachyos, setup-gamescope-boot.sh) changes in the CachyOS QEMU test VM - starting/stopping the VM, restoring snapshots, running the wizard over SSH with scripted menu input, checking each component's state, reboot checks and screenshots. --- -# Testing cachyos-gamescope-boot in the CachyOS VM +# Testing Steamify CachyOS in the CachyOS VM The wizard (`setup-gamescope-boot.sh` + `lib/*.sh`) opens a menu that detects which components are on and toggles them to match the user's choice. Menu order: diff --git a/CHANGELOG.md b/CHANGELOG.md index 20d4a8b..4366329 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,11 +25,15 @@ Watchable test runs and the lessons from testing cachyos-gamescope-boot 0.7.0 re-applying the conversion resets the session to gamescope, the new theme and LED checks in the test matrix, and the broken mirror workaround. - `3733f94` **docs: Changelog** -- **feat: Fake BIOS version for testing the BIOS update item** +- `3cdf2e1` **feat: Fake BIOS version for testing the BIOS update item** - `BIOS_VERSION=F7F0107 ./run.sh ...` makes the guest report that BIOS version (SMBIOS type 0), so the wizard offers the update. - Skill: testing the BIOS item with `WIZARD_BIOS_DRY_RUN=1`, and the wizard's menu loop. +- **docs: Renamed to steamify-cachyos-dev, for Steamify CachyOS** + - README and skill point to `github.com/theupriser/steamify-cachyos`; the + local clone's default path (`REPO`) and the guest's state directory keep + their old names. ## 0.1.1 - 2026-09-23 diff --git a/README.md b/README.md index ec0caf6..57e1763 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -# cachyos-gamescope-boot dev environment +# Steamify CachyOS dev environment A QEMU/KVM test VM running CachyOS (KDE Plasma 6) for developing and testing -[cachyos-gamescope-boot](https://github.com/theupriser/cachyos-gamescope-boot), +[Steamify CachyOS](https://github.com/theupriser/steamify-cachyos), plus helper scripts and a Claude Code skill that documents the test workflow. Only scripts and docs live here. The ISO, disk image, UEFI variable stores, @@ -102,7 +102,8 @@ read-write as 9p tag `repo`; in the guest: - `--nvidia`: render the guest's virtio-gpu (virgl) on the host NVIDIA dGPU - `--vulkan`: expose Vulkan to the guest (venus; unstable) - `--fremont`: fake the Valve Steam Machine (Fremont) DMI data via `-smbios` -- `REPO` defaults to `$HOME/projects/cachyos-gamescope-boot` +- `REPO` defaults to `$HOME/projects/cachyos-gamescope-boot` (the local clone of + [steamify-cachyos](https://github.com/theupriser/steamify-cachyos)) ## Helper scripts From 8c48858f540d647c10bb8070a113707762929e5d Mon Sep 17 00:00:00 2001 From: Rick Peters Date: Thu, 24 Sep 2026 12:33:51 +0200 Subject: [PATCH 5/6] chore: The wizard's script is now steamify.sh vmrun.sh, vmwatch.sh, the skill and the README run /mnt/steamify.sh. --- .claude/skills/cachyos-vm-testing/SKILL.md | 12 ++++++------ CHANGELOG.md | 4 +++- run.ps1 | 2 +- run.sh | 2 +- scripts/vmrun.sh | 2 +- scripts/vmwatch.sh | 4 ++-- 6 files changed, 14 insertions(+), 12 deletions(-) diff --git a/.claude/skills/cachyos-vm-testing/SKILL.md b/.claude/skills/cachyos-vm-testing/SKILL.md index 1870e0f..2a5fa0a 100644 --- a/.claude/skills/cachyos-vm-testing/SKILL.md +++ b/.claude/skills/cachyos-vm-testing/SKILL.md @@ -1,11 +1,11 @@ --- name: cachyos-vm-testing -description: Use when testing Steamify CachyOS (repo steamify-cachyos, setup-gamescope-boot.sh) changes in the CachyOS QEMU test VM - starting/stopping the VM, restoring snapshots, running the wizard over SSH with scripted menu input, checking each component's state, reboot checks and screenshots. +description: Use when testing Steamify CachyOS (repo steamify-cachyos, steamify.sh) changes in the CachyOS QEMU test VM - starting/stopping the VM, restoring snapshots, running the wizard over SSH with scripted menu input, checking each component's state, reboot checks and screenshots. --- # Testing Steamify CachyOS in the CachyOS VM -The wizard (`setup-gamescope-boot.sh` + `lib/*.sh`) opens a menu that detects +The wizard (`steamify.sh` + `lib/*.sh`) opens a menu that detects which components are on and toggles them to match the user's choice. Menu order: 1. SteamOS conversion (boot into gaming mode via autologin, Return to Gaming Mode shortcut, Steam desktop autostart) @@ -88,7 +88,7 @@ sudoers rule for the test user. ## Mounting the project repo The mount is lost on every reboot (unless the fstab line below was added). -Without it the wizard fails with `/mnt/setup-gamescope-boot.sh: No such file +Without it the wizard fails with `/mnt/steamify.sh: No such file or directory`, which is easy to miss in filtered output. Remount after each reboot. The repo (`REPO`, default `~/projects/cachyos-gamescope-boot`) is shared @@ -134,7 +134,7 @@ guest). Manually, in the guest: ```bash export XDG_RUNTIME_DIR=/run/user/1000 WAYLAND_DISPLAY=wayland-0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus -printf '\ny\nn\n' | /mnt/setup-gamescope-boot.sh +printf '\ny\nn\n' | /mnt/steamify.sh ``` Menu input: a number toggles a component, an empty line continues, `a` @@ -232,7 +232,7 @@ differs from Valve's newest. Fake an older one with the environment through). fwupd correctly refuses the firmware in the VM ("not for this machine's hardware"), so walk the whole flow with `WIZARD_BIOS_DRY_RUN=1` (skips only that check, never flashes). Scripted: -`printf '6\n\ny\ny\nUPDATE\n\nq\n' | WIZARD_BIOS_DRY_RUN=1 /mnt/setup-gamescope-boot.sh`. +`printf '6\n\ny\ny\nUPDATE\n\nq\n' | WIZARD_BIOS_DRY_RUN=1 /mnt/steamify.sh`. The wizard loops back to the menu after every run (Enter, or `m`/`r` when a restart is needed) until `q`; scripted input that runs out ends it like `q`. @@ -267,7 +267,7 @@ them with `systemd-run --user `. - The guest's `/tmp` is cleared on reboot; keep baselines elsewhere. - The fake Fremont DMI makes leds-valve load 17 LED nodes, but there is no real hardware. - shellcheck: `sudo pacman -S shellcheck`, then in `/mnt`: - `shellcheck -S warning -x setup-gamescope-boot.sh lib/*.sh` + `shellcheck -S warning -x steamify.sh lib/*.sh` (SC2154/SC2034 cross-file warnings are false positives). - This repo's `.gitignore` is an allowlist: it ignores everything and un-ignores only the tracked scripts/docs. Add any new tracked file to it diff --git a/CHANGELOG.md b/CHANGELOG.md index 4366329..6fc0ac1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,10 +30,12 @@ Watchable test runs and the lessons from testing cachyos-gamescope-boot 0.7.0 version (SMBIOS type 0), so the wizard offers the update. - Skill: testing the BIOS item with `WIZARD_BIOS_DRY_RUN=1`, and the wizard's menu loop. -- **docs: Renamed to steamify-cachyos-dev, for Steamify CachyOS** +- `c6abfd2` **docs: Renamed to steamify-cachyos-dev, for Steamify CachyOS** - README and skill point to `github.com/theupriser/steamify-cachyos`; the local clone's default path (`REPO`) and the guest's state directory keep their old names. +- **chore: The wizard's script is now steamify.sh** + - `vmrun.sh`, `vmwatch.sh`, the skill and the README run `/mnt/steamify.sh`. ## 0.1.1 - 2026-09-23 diff --git a/run.ps1 b/run.ps1 index 7a18a25..642a212 100644 --- a/run.ps1 +++ b/run.ps1 @@ -1,4 +1,4 @@ -# CachyOS test VM for setup-gamescope-boot.sh -- Windows version. +# CachyOS test VM for steamify.sh -- Windows version. # .\run.ps1 [-Install] # Needs QEMU for Windows (https://qemu.weilnetz.de/w64/) and the Windows # feature "Windows Hypervisor Platform" (for -accel whpx). diff --git a/run.sh b/run.sh index aa9efaa..ee96192 100755 --- a/run.sh +++ b/run.sh @@ -1,5 +1,5 @@ #!/bin/bash -# CachyOS test VM for setup-gamescope-boot.sh. +# CachyOS test VM for steamify.sh. # [REPO=/path/to/cachyos-gamescope-boot] ./run.sh [install] [--nvidia] [--vulkan] [--fremont] # install boot the installer ISO # --nvidia render the guest's virtio-gpu (virgl) on the host NVIDIA dGPU diff --git a/scripts/vmrun.sh b/scripts/vmrun.sh index 5e8f37f..39393a1 100755 --- a/scripts/vmrun.sh +++ b/scripts/vmrun.sh @@ -15,7 +15,7 @@ GUEST_UID="${GUEST_UID:-1000}" export XDG_RUNTIME_DIR=/run/user/$uid WAYLAND_DISPLAY=wayland-0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$uid/bus log=/tmp/wizard.log # shellcheck disable=SC2059 -printf "$input" | "$repo/setup-gamescope-boot.sh" > "$log" 2>&1; echo "exit=$?" >> "$log" +printf "$input" | "$repo/steamify.sh" > "$log" 2>&1; echo "exit=$?" >> "$log" cat "$log" REMOTE } | vm_ssh bash -s 2>&1 | sed 's/\x1b\[[0-9;]*m//g' diff --git a/scripts/vmwatch.sh b/scripts/vmwatch.sh index 22d71ca..22273ba 100755 --- a/scripts/vmwatch.sh +++ b/scripts/vmwatch.sh @@ -13,13 +13,13 @@ label="${2:-Running the wizard}" { printf 'input=%q label=%q repo=%q uid=%q wait=%q\n' "$input" "$label" "${GUEST_REPO:-/mnt}" \ "${GUEST_UID:-1000}" "${WAIT:-1800}"; cat << 'REMOTE' export XDG_RUNTIME_DIR=/run/user/$uid DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$uid/bus -[ -x "$repo/setup-gamescope-boot.sh" ] || { echo "$repo/setup-gamescope-boot.sh missing: mount the repo (lost after a reboot)" >&2; exit 1; } +[ -x "$repo/steamify.sh" ] || { echo "$repo/steamify.sh missing: mount the repo (lost after a reboot)" >&2; exit 1; } rm -f /tmp/wizard.done { echo '#!/bin/bash' printf 'echo %q; echo %q; sleep 3\n' ">>> $label" ">>> menu input: $input" # shellcheck disable=SC2016 - printf 'printf %q | %q 2>&1 | tee /tmp/wizard.log\n' "$input" "$repo/setup-gamescope-boot.sh" + printf 'printf %q | %q 2>&1 | tee /tmp/wizard.log\n' "$input" "$repo/steamify.sh" echo 'touch /tmp/wizard.done' } > /tmp/vmwatch-run.sh chmod +x /tmp/vmwatch-run.sh From f27dd866a1683e4b14ebd369f920264e7ce04189 Mon Sep 17 00:00:00 2001 From: Rick Peters Date: Thu, 24 Sep 2026 13:06:23 +0200 Subject: [PATCH 6/6] feat: Release testing, cleaner resets and screenshots; skill updates - vmwatch.sh --release: run the newest GitHub release in the VM. - vmreset.sh: skip the broken krfoss mirror, install shellcheck. - vmshot.sh --clean: close Steam, CachyOS Hello and Konsole first. - Skill: items 1-7, menu loop and restart question, current inputs, finish on a fresh snapshot, release testing, Steamify shortcut, zsh pitfall. --- .claude/skills/cachyos-vm-testing/SKILL.md | 91 +++++++++++++++++----- CHANGELOG.md | 10 ++- README.md | 7 +- scripts/vmreset.sh | 8 +- scripts/vmshot.sh | 17 +++- scripts/vmwatch.sh | 25 ++++-- 6 files changed, 124 insertions(+), 34 deletions(-) diff --git a/.claude/skills/cachyos-vm-testing/SKILL.md b/.claude/skills/cachyos-vm-testing/SKILL.md index 2a5fa0a..7eff040 100644 --- a/.claude/skills/cachyos-vm-testing/SKILL.md +++ b/.claude/skills/cachyos-vm-testing/SKILL.md @@ -12,7 +12,11 @@ which components are on and toggles them to match the user's choice. Menu order: 2. SteamOS theme (installs `cachyos-vapor` and applies the Vapor global theme with its desktop and window layout; needs a running Plasma session) 3. Steam Deck/Machine icons (`STEAM_GAMEPADUI_ARGS -steamos3`) 4. Single user mode (SDDM, no lock screen/user switching/log out; enabling it enables 1, disabling 1 disables it) -5. Steam Machine support (only on DMI Valve/Fremont: leds-valve-dkms-git built for every kernel via `/etc/dkms/leds-valve-dkms.conf`, `ensure-kernel-headers.service`, udev rule, steamos-manager) +5. Steamify shortcut (desktop icon + launcher entry that `curl | bash` the newest release; its gear icon is a release asset) +6. Steam Machine support (only on DMI Valve/Fremont: leds-valve-dkms-git built for every kernel via `/etc/dkms/leds-valve-dkms.conf`, `ensure-kernel-headers.service`, udev rule, steamos-manager, powerdevilrc) +7. Update BIOS (only on Fremont, an opt-in action, never pre-ticked; tickable only when Valve has a newer BIOS) + +Without `--fremont` the menu has only 1-5. Undo journals live in `~/.local/state/cachyos-gamescope-boot/` in the guest. @@ -29,12 +33,23 @@ snapshot commands below run in that directory. `scripts/vmreset.sh` takes ```bash scripts/vmreset.sh --fremont # restore ssh-ready, boot, mount repo, autologin, wait for Plasma + # (also skips the broken krfoss mirror, installs shellcheck) scripts/cmp.sh save # baseline of the KDE configs -scripts/vmwatch.sh '1\n3\n\ny\nn\n' "Theme only" # wizard in a visible Konsole in the VM +scripts/vmwatch.sh '1\n3\n\ny\n' "Theme only" # wizard in a visible Konsole in the VM +scripts/vmwatch.sh --release '\ny\nm\nq\n' "Full run" # the newest GitHub release instead of /mnt scripts/vmstate.sh # component state -scripts/vmshot.sh /path/shot.png # screenshot, then view it +scripts/vmshot.sh --clean /path/shot.png # screenshot (--clean: close Steam/Hello/Konsole first) ``` +**Always finish on a fresh `ssh-ready` snapshot**, ideally with `--release` +once published. Re-applying or toggling on an already set-up VM hides +first-install bugs: the DKMS override silently failed on a fresh system +(`/etc/dkms` doesn't exist before `dkms` is installed), which no re-apply +showed because `dkms` was there already. + +Long runs (full install: packages, yay, DKMS) take 10+ minutes: run them +with `run_in_background` and wait with an until-loop, not chained sleeps. + Prefer `vmwatch.sh` over `vmrun.sh` when the user is watching the QEMU window: `vmrun.sh` runs invisibly over SSH, so they see nothing happen. @@ -134,21 +149,26 @@ guest). Manually, in the guest: ```bash export XDG_RUNTIME_DIR=/run/user/1000 WAYLAND_DISPLAY=wayland-0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus -printf '\ny\nn\n' | /mnt/steamify.sh +printf '\ny\nm\nq\n' | /mnt/steamify.sh ``` Menu input: a number toggles a component, an empty line continues, `a` -re-applies what is on, `q` quits. Then `y` answers "Go ahead?" and `n` the -restart question. +re-applies what is on, `q` quits; then `y` answers "Go ahead?". The wizard +**loops**: after a run it asks for Enter (back to the menu), or `[m]`/`[r]` +(menu / restart now) when a restart is needed. On `q` with a restart pending +it asks "Restart now? [Y/n]" (default **yes**): `n` goes back to the menu and +the next `q` asks again. Input that runs out quits without restarting, so end +scripted input right after the last `q` (or with `n`), never with an empty +line at the restart question. | Input | Meaning | |---|---| -| `'\ny\nn\n'` | first run, accept all | -| `'2\n\ny\nn\n'` | toggle the theme | -| `'a\ny\nn\n'` | re-apply what is on | +| `'\ny\nm\nq\n'` | first run, accept all (not the BIOS item), back to the menu, quit | +| `'2\n\ny\n'` | toggle the theme | +| `'a\ny\nm\nq\n'` | re-apply what is on (includes the conversion, so a restart is pending) | | `'q\n'` | just show the menu | -| `'1\n3\n\ny\nn\n'` | from all-off: theme only (Steam Machine too with `--fremont`; add `5\n` to drop it) | -| `'1\n\ny\nn\n'` | from a state where 1 is off: turn the conversion on | +| `'1\n3\n5\n\ny\n'` | from all-off: theme only (with `--fremont` also add `6\n` to drop Steam Machine support) | +| `'1\n\ny\n'` | from a state where 1 is off: turn the conversion on | **Know the starting ticks before choosing input.** When *everything* is off (fresh snapshot, or after turning the last component off), the menu treats it @@ -200,6 +220,16 @@ After changing the theme, `cmp.sh` should show only spectacle's `~/.config/kdedefaults` (e.g. `ColorScheme=BreezeDark`, `widgetStyle=Breeze`): KDE drops or writes those on its own. +## Testing the newest release + +`scripts/vmwatch.sh --release ''` downloads +`releases/latest/download/steamify.sh` in the guest and runs it with the piped +input (`WIZARD_KEEP_STDIN=1`; the bundle otherwise reattaches the terminal). +Release assets only exist from the version that added them: before v0.9.0 was +published, `steamify.sh` and the shortcut's `steam-gaming-settings.svg` gave +404 and the shortcut fell back to Steam's icon. Check a release with +`curl -sIL -o /dev/null -w '%{http_code}' .../releases/latest/download/`. + ## Reboot checks - Single user mode on: SDDM autologin without greeter: `pgrep sddm-greeter` empty, `plasmashell` running. @@ -210,7 +240,9 @@ KDE drops or writes those on its own. Reset to `ssh-ready`, start with `--fremont`, mount the repo, enable test autologin, then (all passed last run; `scripts/vmstate.sh` after every step): -1. Fresh run turning everything on (`'\ny\nn\n'`), set session to plasma, reboot. +1. Fresh run turning everything on (`'\ny\nm\nq\n'`), set session to plasma, reboot: + SDDM logs straight in, Vapor desktop, three desktop icons (Return to Gaming + Mode, Steam, Steamify CachyOS with the gear icon), LEDs loaded (17 nodes). 2. Rerun: all shown on, "Everything is already the way you want it". 3. `a` re-apply: no duplicate journal entries. 4. Theme on: Steam Deck wallpaper, full-width 46px panel, `distributor-logo-steamdeck` launcher icon, `dark-lnf=com.valve.vapor.desktop` (Brightness & Color's Dark Mode toggle is on, hint "Switch to Breeze"); with single user on, kickoff keeps `primaryActions=3`. Theme off: CachyOS wallpaper, floating 30px panel, CachyOS launcher icon, BreezeDark colors (not light), `cachyos-vapor` removed, `cmp.sh` clean. @@ -232,14 +264,26 @@ differs from Valve's newest. Fake an older one with the environment through). fwupd correctly refuses the firmware in the VM ("not for this machine's hardware"), so walk the whole flow with `WIZARD_BIOS_DRY_RUN=1` (skips only that check, never flashes). Scripted: -`printf '6\n\ny\ny\nUPDATE\n\nq\n' | WIZARD_BIOS_DRY_RUN=1 /mnt/steamify.sh`. +`printf '7\n\ny\ny\nUPDATE\nm\nq\nn\n' | WIZARD_BIOS_DRY_RUN=1 /mnt/steamify.sh` +(BIOS is item 7 with `--fremont`; the final `n` answers the restart question). -The wizard loops back to the menu after every run (Enter, or `m`/`r` when a -restart is needed) until `q`; scripted input that runs out ends it like `q`. +A successful dry run counts as staged, so `[m]`/`[r]` and the restart question +on `q` show up too; in dry-run mode "restart" only prints. + +## Steamify shortcut + +Test a double-click with `systemd-run --user kioclient exec +~/Desktop/cachyos-gamescope-boot-wizard.desktop`. If Plasma opens the file in +Kate instead, it saw the file before it was executable. After the wizard the +window counts down 10 seconds and closes; after an error (e.g. 404) it waits +for Enter. ## Visual checks -`scripts/vmshot.sh ` does the below. Starting `spectacle` straight +`scripts/vmshot.sh [--clean] ` does the below. After a reboot, Steam's +sign-in window and CachyOS Hello cover the desktop: `--clean` shuts Steam down +(closing only `steamwebhelper` leaves a black window) and closes Hello and the +wizard's Konsole. Steam comes back at the next login. Starting `spectacle` straight from SSH core-dumps; it has to run as a user unit (`systemd-run --user --wait`). ```bash @@ -258,17 +302,22 @@ them with `systemd-run --user `. ## Pitfalls - Broken mirror: `mirror5.krfoss.org` served a bad `.sig` ("Maximum file size - exceeded"), failing the conversion's package install. Comment it out: - `sudo sed -i '/krfoss/s/^Server/#Server/' /etc/pacman.d/*mirrorlist*`. + exceeded"), failing the conversion's package install. `vmreset.sh` comments + it out; by hand: `sudo sed -i '/krfoss/s/^Server/#Server/' /etc/pacman.d/*mirrorlist*`. +- The snapshot has no shellcheck; `vmreset.sh` installs it. Check the bundle + like CI: `.github/tools/bundle.sh` on the host, then in the guest + `cd /mnt && shellcheck -S warning -e SC2034,SC2154 dist/steamify.sh`. +- The host shell is zsh: `$var` holding several file names isn't split + (`sed -i ... $files` gets one "name"); use `xargs`. - Windows open in the snapshot (System Settings, CachyOS Hello) show stale data (e.g. a theme list from before `cachyos-vapor`) and cover screenshots; `vmreset.sh` closes them. - The guest's `/tmp` is cleared on reboot; keep baselines elsewhere. - The fake Fremont DMI makes leds-valve load 17 LED nodes, but there is no real hardware. -- shellcheck: `sudo pacman -S shellcheck`, then in `/mnt`: - `shellcheck -S warning -x steamify.sh lib/*.sh` - (SC2154/SC2034 cross-file warnings are false positives). +- Per-file shellcheck (`shellcheck -S warning -x steamify.sh lib/*.sh` in + `/mnt`) shows SC2154/SC2034 cross-file false positives; the bundle check + above is the one CI runs. - This repo's `.gitignore` is an allowlist: it ignores everything and un-ignores only the tracked scripts/docs. Add any new tracked file to it explicitly, or git will silently ignore it. diff --git a/CHANGELOG.md b/CHANGELOG.md index 6fc0ac1..20e7b81 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,8 +34,16 @@ Watchable test runs and the lessons from testing cachyos-gamescope-boot 0.7.0 - README and skill point to `github.com/theupriser/steamify-cachyos`; the local clone's default path (`REPO`) and the guest's state directory keep their old names. -- **chore: The wizard's script is now steamify.sh** +- `8c48858` **chore: The wizard's script is now steamify.sh** - `vmrun.sh`, `vmwatch.sh`, the skill and the README run `/mnt/steamify.sh`. +- **feat: Release testing, cleaner resets and screenshots; skill updates** + - `vmwatch.sh --release` runs the newest GitHub release in the VM. + - `vmreset.sh` skips the broken krfoss mirror and installs shellcheck. + - `vmshot.sh --clean` closes Steam, CachyOS Hello and Konsole first. + - Skill: menu items 1-7 and the new menu loop/restart question, current + scripted inputs, always finishing on a fresh snapshot (the DKMS bug only + showed there), testing releases and their assets, the Steamify shortcut, + and the zsh word-splitting pitfall. ## 0.1.1 - 2026-09-23 diff --git a/README.md b/README.md index 57e1763..4d3d73a 100644 --- a/README.md +++ b/README.md @@ -108,9 +108,12 @@ read-write as 9p tag `repo`; in the guest: ## Helper scripts - `scripts/vmreset.sh [--fremont]`: restore `ssh-ready`, boot, mount the repo, autologin into Plasma + (and skip the broken krfoss mirror, install shellcheck) - `scripts/vmrun.sh ''`: run the wizard in the guest's Plasma session with scripted input -- `scripts/vmwatch.sh '' [label]`: same, but in a visible Konsole window in the VM -- `scripts/vmshot.sh `: screenshot the guest's desktop +- `scripts/vmwatch.sh [--release] '' [label]`: same, but in a visible Konsole window + in the VM; `--release` runs the newest GitHub release instead of the mounted repo +- `scripts/vmshot.sh [--clean] `: screenshot the guest's desktop (`--clean` closes + Steam, CachyOS Hello and Konsole first) - `scripts/vmstate.sh`: print the state of every wizard component - `scripts/cmp.sh [save]`: save / diff the guest's KDE configs against a baseline diff --git a/scripts/vmreset.sh b/scripts/vmreset.sh index 335ffc4..a6cce10 100755 --- a/scripts/vmreset.sh +++ b/scripts/vmreset.sh @@ -1,7 +1,8 @@ #!/bin/bash # Reset the test VM to a snapshot and bring it up logged in to Plasma: # power off, restore the snapshot (disk + vars.fd), start it, mount the repo -# on /mnt, set up the test autologin and wait for plasmashell. +# on /mnt, set up the test autologin and wait for plasmashell; also skips +# the broken krfoss mirror and installs shellcheck. # scripts/vmreset.sh [run.sh flags...] e.g. scripts/vmreset.sh --fremont # Env: VM_USER / VM_PORT / VM_HOST, SNAPSHOT (ssh-ready), # VM_DIR (where disk.qcow2 lives: this repo if it has one, else ~/vms/cachyos-test), @@ -41,5 +42,10 @@ for _ in $(seq 40); do pgrep -u "$USER" -x plasmashell >/dev/null && break; slee sleep 10 # Windows the snapshot opens at login would cover the screenshots. pkill -u "$USER" systemsettings; pkill -u "$USER" cachyos-hello +# mirror5.krfoss.org served a broken .sig ("Maximum file size exceeded"), +# which fails the conversion's package install; skip it. +for f in /etc/pacman.d/*mirrorlist*; do sudo sed -i '/krfoss/s/^Server/#Server/' "$f"; done +# shellcheck, for checking the bundle like CI does (not in the snapshot). +sudo pacman -S --needed --noconfirm shellcheck >/dev/null 2>&1 || echo "Couldn't install shellcheck." >&2 pgrep -u "$USER" -x plasmashell >/dev/null && echo "Logged in to Plasma." || { echo "Plasma did not start." >&2; exit 1; } REMOTE diff --git a/scripts/vmshot.sh b/scripts/vmshot.sh index 42dee5d..a311496 100755 --- a/scripts/vmshot.sh +++ b/scripts/vmshot.sh @@ -1,15 +1,26 @@ #!/bin/bash # Screenshot the guest's Plasma session to a file on the host. -# scripts/vmshot.sh +# scripts/vmshot.sh [--clean] +# --clean first close what starts with the session and covers the desktop +# (Steam, CachyOS Hello) and the wizard's Konsole. # spectacle started straight from SSH crashes; run it as a user unit so it # gets the session's environment. # Env: VM_USER (theupriser), VM_PORT (2222), VM_HOST (localhost), GUEST_UID (1000). set -euo pipefail . "$(dirname "$0")/common.sh" -out="${1:?usage: $0 }" -{ printf 'uid=%q\n' "${GUEST_UID:-1000}"; cat << 'REMOTE' +clean="" +[[ "${1:-}" == --clean ]] && { clean=1; shift; } +out="${1:?usage: $0 [--clean] }" +{ printf 'uid=%q clean=%q\n' "${GUEST_UID:-1000}" "$clean"; cat << 'REMOTE' export XDG_RUNTIME_DIR=/run/user/$uid DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$uid/bus rm -f /tmp/vmshot.png +if [ -n "$clean" ]; then + # Steam as a whole: closing only its web helper leaves a black window. + # It comes back at the next login (steam-desktop-autostart). + steam -shutdown >/dev/null 2>&1 & sleep 5; pkill -u "$USER" -x steam; pkill -u "$USER" -x steamwebhelper + pkill -u "$USER" cachyos-hello; pkill -u "$USER" -x konsole + sleep 2 +fi sleep 2 systemd-run --user --wait -q spectacle -b -n -f -o /tmp/vmshot.png REMOTE diff --git a/scripts/vmwatch.sh b/scripts/vmwatch.sh index 22273ba..9622f0b 100755 --- a/scripts/vmwatch.sh +++ b/scripts/vmwatch.sh @@ -2,24 +2,37 @@ # Like vmrun.sh, but run the wizard in a visible Konsole window inside the # guest's Plasma session, so someone at the QEMU window can follow along. # Waits for the wizard to finish, then prints its log. The window stays open. -# scripts/vmwatch.sh '' ["label shown in the window"] +# scripts/vmwatch.sh [--release] '' ["label shown in the window"] +# --release run the newest release from GitHub instead of the mounted repo +# (downloaded; WIZARD_KEEP_STDIN=1 keeps the piped menu input). # Env: VM_USER (theupriser), VM_PORT (2222), VM_HOST (localhost), # GUEST_REPO (/mnt), GUEST_UID (1000), WAIT (seconds, default 1800). set -euo pipefail . "$(dirname "$0")/common.sh" -input="${1:?usage: $0 '' [label]}" +release="" +[[ "${1:-}" == --release ]] && { release=1; shift; } +input="${1:?usage: $0 [--release] '' [label]}" label="${2:-Running the wizard}" # The guest login shell is fish, so pass values in through the bash script itself. -{ printf 'input=%q label=%q repo=%q uid=%q wait=%q\n' "$input" "$label" "${GUEST_REPO:-/mnt}" \ - "${GUEST_UID:-1000}" "${WAIT:-1800}"; cat << 'REMOTE' +{ printf 'input=%q label=%q repo=%q uid=%q wait=%q release=%q\n' "$input" "$label" "${GUEST_REPO:-/mnt}" \ + "${GUEST_UID:-1000}" "${WAIT:-1800}" "$release"; cat << 'REMOTE' export XDG_RUNTIME_DIR=/run/user/$uid DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$uid/bus -[ -x "$repo/steamify.sh" ] || { echo "$repo/steamify.sh missing: mount the repo (lost after a reboot)" >&2; exit 1; } +if [ -n "$release" ]; then + wizard=/tmp/steamify-release.sh + curl -fsSL https://github.com/theupriser/steamify-cachyos/releases/latest/download/steamify.sh -o "$wizard" || + { echo "Couldn't download the newest release." >&2; exit 1; } + run="WIZARD_KEEP_STDIN=1 bash $wizard" + label="$label ($(grep -m1 '^VERSION=' "$wizard") from GitHub)" +else + [ -x "$repo/steamify.sh" ] || { echo "$repo/steamify.sh missing: mount the repo (lost after a reboot)" >&2; exit 1; } + run="$repo/steamify.sh" +fi rm -f /tmp/wizard.done { echo '#!/bin/bash' printf 'echo %q; echo %q; sleep 3\n' ">>> $label" ">>> menu input: $input" # shellcheck disable=SC2016 - printf 'printf %q | %q 2>&1 | tee /tmp/wizard.log\n' "$input" "$repo/steamify.sh" + printf 'printf %q | %s 2>&1 | tee /tmp/wizard.log\n' "$input" "$run" echo 'touch /tmp/wizard.done' } > /tmp/vmwatch-run.sh chmod +x /tmp/vmwatch-run.sh