@punktfunk/plugin-desktop (0.1.0)
Installation
@punktfunk:registry=https://git.unom.io/api/packages/unom/npm/npm install @punktfunk/plugin-desktop@0.1.0"@punktfunk/plugin-desktop": "0.1.0"About this package
@punktfunk/plugin-desktop
Adds every Linux desktop entry that calls itself a game — a distro package, a Flatpak, a
hand-written .desktop launcher — to a Punktfunk host's library, with its icon as art.
Install it from the host's plugin store (Library → Game sources → Add a source), or:
punktfunk-host plugins add desktop
Nothing to configure. If you keep .desktop files somewhere non-standard, add the directories in
Library → Game sources → Desktop entries → Settings.
What is read
The applications/ directory of every XDG data root, in precedence order — $XDG_DATA_HOME
(~/.local/share), each $XDG_DATA_DIRS entry (/usr/local/share:/usr/share) — plus the Flatpak
exports (~/.local/share/flatpak/exports/share, /var/lib/flatpak/exports/share), one
subdirectory deep. The first directory to define a desktop-file id owns it, so a user-level copy
with NoDisplay=true hides the system one, exactly as it does in your app menu.
A file becomes a game when it is Type=Application, lists Game in Categories, has an Exec,
is not NoDisplay, Hidden or Terminal, and its TryExec (if any) exists. The launchers this
library already covers — Steam, Lutris, Heroic, Bottles, RetroArch, itch — are skipped, and so is
any shortcut they wrote for one of their games (steam://, lutris:, heroic://, bottles-cli):
those titles come from their own plugins, with the ids and art those give them.
Art is the entry's Icon: an absolute .png/.jpg, or a name looked up in the hicolor theme
(512 down to 64 px) and /usr/share/pixmaps. SVG is never used; the host refuses it.
How a game starts
Entries carry no command. When you pick one, the host asks this plugin what to run and gets the
Exec line with its field codes stripped, run from Path= — or flatpak run <app-id> for a
Flatpak. The command is the game, so the session ends when it exits.
Config fields
| Field | Meaning |
|---|---|
extraDirs |
More directories holding .desktop files, scanned after the standard ones. |
Commands
punktfunk-plugin-desktop detect # is this a Linux desktop with an applications dir?
punktfunk-plugin-desktop scan --preview # what WOULD be synced, as JSON (works with no host)
punktfunk-plugin-desktop uninstall # drop the games and release the store claim
The kit's parity verb has no baseline here: the host never had a built-in desktop-entry scanner.
Platform caveat
Linux only. On any other platform detect reports absent and the library stays empty.
Development
bun install
bun run typecheck && bun test && bun run build
This needs @punktfunk/plugin-kit 0.4.5 (the launch field). Until it is published, bun.lock
is not committed; the first install after the kit lands regenerates it.
The framework — store claim, sync engine, __config, CLI verbs, and the file helpers — lives in
@punktfunk/plugin-kit/library.
This package is the desktop-entry part: find the directories, parse the files, map games to entries,
answer the launch ask. See design/library-scanner-plugins.md in the main repo.
License
MIT OR Apache-2.0.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @punktfunk/plugin-kit | ^0.4.5 |
| effect | 4.0.0-beta.99 |
Development Dependencies
| ID | Version |
|---|---|
| @biomejs/biome | ^2.5.2 |
| @types/bun | ^1.3.0 |
| typescript | ^5.9.3 |