feat(linux): packaged AppImage + release workflow (#168)

[jonocodes]

Phase 0 of #168.

What

Zero-toolchain Linux install. A self-contained AppImage carries a private Python runtime, the built client, and the layouts; a small sudo helper owns the parts an AppImage cannot (udev rule + input group) plus the user-level pieces (desktop focus watcher, icon, XDG autostart).

Changes

• packaging/linux/ — PyInstaller onedir spec + launcher.py, AppDir glue (AppRun, deckd.desktop, committed PNG icons), and install-system-integration.sh (idempotent, state-tracked, with --uninstall).
• daemon/deckd/app_bundle.py — platform-agnostic packaging helpers extracted from macos_app so the macOS and Linux bundles can't drift; macos_app re-exports them unchanged.
• daemon/deckd/linux_app.py — XDG data dir/log, layouts.linux overlay, first-run seeding, build_argv, and --extract-integration (copy the AppDir's integration assets out).
• .github/workflows/release-linux.yml — x86_64 + aarch64 matrix, --help + extraction smoke tests, attaches the AppImages and the helper script to the tag.
• Justfile — build-linux-appimage, install-system-integration.
• Docs — ADR-0012 (AppImage primary; Flatpak/Snap rejected) and a GUIDE section.

Decision

AppImage, not Flatpak/Snap: a sandbox cannot write the udev rule, see /dev/uinput, reach the session bus unfiltered, or install the compositor plugin. The root step is unavoidable on every channel, so it's an explicit sudo helper. Details and rejected options in ADR-0012.

Verification (NixOS 26.05 / GNOME 50 Wayland, x86_64)

• just build-linux-appimage → dist/deckd-0.0.1-x86_64.AppImage (22.9 MB). Boots (--help), serves /health and the bundled client, seeds layouts into ~/.local/share/deckd/layouts, writes deckd.log.
• Input injection end-to-end: WS key/jog produce real evdev events; typed deckd injected this through the packaged daemon into a focused Text Editor on the live session, sent ctrl+s, and the saved file contained exactly that text.
• Live focus (v6 extension loaded at shell startup): daemon reports started_ok: true, focus changes select layouts (org.gnome.Console → layout=org.gnome.Console), RaiseApp/RaiseWindow work, scripts/smoke_focus_live.py passes.
• Install helper, install→uninstall lifecycle sandboxed as namespace-root: udev rule + extension + icon + autostart installed; --uninstall removes only what it created (a pre-existing input membership/extension is preserved).
• pytest 776 passed, pyright daemon clean, bash -n + flag checks, workflow YAML parses.

Fixes found during verification

• 6f12aab — binfmt AppImage wrappers (NixOS programs.appimage) bypass --appimage-extract; the launcher now offers --extract-integration and the helper falls back to it. --uninstall is state-gated (/var/lib/deckd/system-integration.<user>.state) so it can't clobber a NixOS/home-manager install.
• 40a8cd0 — ship the app icon: committed PNGs at the AppDir root (PNG .DirIcon), hicolor 192/512 copies, and an integration-tree copy the helper installs into the user's theme with Icon=deckd.

Not verified

• Autostart-at-login with the real helper: needs a sudo run plus a login on a machine without an existing deckd service; the sandbox verified the entry it writes.
• The release workflow hasn't run on GitHub yet; the first v* tag exercises it.

Follow-up

• Linux AppImage helper: pkexec front-end + uaccess-first (drop mandatory input group) #173 — pkexec front-end + uaccess-first (drop the mandatory input group/re-login).

[jonocodes]

Linux verification (NixOS 26.05 / GNOME 50 Wayland, x86_64)

Worked through the "Not verified (needs a Linux box)" list.

Built: just build-linux-appimage → dist/deckd-0.0.1-x86_64.AppImage (22.9 MB). Local note: PyInstaller needs objdump on PATH (binutils); Ubuntu CI gets it from build-essential.

Booted the frozen payload (--help, then a real run):

• /health ok, bundled client served (GET / → 200), layouts seeded once into ~/.local/share/deckd/layouts, deckd.log written.
• Its uinput device is created; injected shift, ctrl+t, and a jog over the WS protocol and read the events back from the created /dev/input/eventN — key press/release and REL_WHEEL all land.

Install helper (sandboxed as namespace-root; privileged side effects redirected to temp paths):

• install: udev rule + GNOME extension (v6) + autostart written; pre-existing input membership left alone.
• --uninstall: removes exactly what it installed; the pre-existing group membership/extension are untouched.

Live desktop session (v6 extension loaded at shell startup):

• Packaged daemon: focus.backend=GnomeShellFocusBackend, started_ok: true; opening Console produced focus -> AppInfo(app_id='org.gnome.Console', ...) (layout=org.gnome.Console).
• RaiseApp("Paseo") (v6-only) → true; RaiseWindow(<id>) → true; bogus id declined.
• scripts/smoke_focus_live.py against the live bus: PASS.
• Real input injection: typed deckd injected this through the packaged daemon into a focused Text Editor, sent ctrl+s, and the saved file contained exactly that text.

Two fixes found by this run (6f12aab):

1. binfmt AppImage wrappers break --appimage-extract. NixOS's programs.appimage (and any binfmt handler) runs the payload directly, so the embedded runtime never sees the flag and the helper found no assets. Added a --extract-integration DIR flag to the frozen launcher and a fallback in the helper; the release workflow now smoke-tests it. This also affects FUSE-less systems that rely on the runtime's extract-and-run fallback.
2. --uninstall was unconditional — it removed the user's input membership and focus extension even when they pre-existed (NixOS/home-manager or a source install on the same box). Install now records what it changed in /var/lib/deckd/system-integration.<user>.state and uninstall only undoes that.

Not tested: autostart-at-login with the real helper. It needs a sudo run plus another login, and on this machine it would collide with an existing Nix deckd.service on :8765 — the sandbox run verified the entry it writes.

pytest 773 passed; pyright daemon clean; bash -n + flag checks on the helper.

[jonocodes]

Icon: merged main (branding, 585eec3) and used the committed PNGs in the AppImage build instead of rendering the SVG at build time. The AppDir now carries deckd.png at the root (appimagetool makes a PNG .DirIcon), 192/512 copies under usr/share/icons/hicolor, and one in usr/share/deckd/integration. The install helper copies it to ~/.local/share/icons/hicolor/512x512/apps/deckd.png and sets Icon=deckd on the autostart entry (state-gated, so --uninstall removes it). Also dropped the now-unused librsvg2-bin CI dep and extended the extraction smoke test. Commit 40a8cd0.