feat: complete native execution and Steam discovery

2026-07-18 20:11:52 -04:00
parent 514f87dacb
commit bc0090c63d
42 changed files with 6403 additions and 97 deletions
@@ -0,0 +1,51 @@
+# Native game manifests
+
+Native discovery is opt-in. Place one schema-versioned TOML file per game under
+`${XDG_CONFIG_HOME:-$HOME/.config}/kiln/native/`. Discovery is authoritative and
+read-only; it does not scan arbitrary system applications.
+
+## Direct executable
+
+```toml
+schema_version = 1
+id = "openmw"
+name = "OpenMW"
+install_path = "/games/openmw"
+executable = "/games/openmw/openmw"
+arguments = ["--replace"]
+```
+
+`id` becomes `native:<id>`. `install_path` and `executable` must be absolute,
+normalized UTF-8 paths. Arguments are passed directly and are never evaluated by a
+shell.
+
+## Approved Desktop Entry
+
+```toml
+schema_version = 1
+id = "supertuxkart"
+name = "SuperTuxKart"
+install_path = "/usr/bin"
+desktop_entry = "/usr/share/applications/supertuxkart.desktop"
+```
+
+The explicit path is the approval boundary. The adapter accepts Application entries,
+parses `Exec=` without a shell, expands `%%`, `%c`, `%i`, and `%k`, and omits file/URL
+codes because no files or URLs are supplied. Unknown field codes, malformed quoting,
+symlinks, invalid UTF-8, files over 64 KiB, and mixed executable/Desktop Entry sources
+fail closed.
+
+## Commands and state
+
+```text
+kiln list [--json]
+kiln search <query> [--json]
+kiln info <id-or-name> [--json]
+kiln scan [--provider native] [--no-cache] [--json]
+kiln launch <id-or-name> --dry-run [--json]
+kiln launch <id-or-name> [--json]
+```
+
+Installation identity remains in the Phase 1 XDG state registry. Native stdout and
+stderr append to `${XDG_STATE_HOME:-$HOME/.local/state}/kiln/logs/native.log` with mode
+`0600`. A non-zero child exit returns a structured `launch-failed` error.