steam-backlog-enforcer/DOCS-web-install.md
Krzysztof kuhy Rudnicki 94a0e8a1c3 Add map-installed Proton map view and apply job
GET /api/compat serves every installed game's compat-tool decision as
rows from the installer's own code (steam_installer/compat_rows.py, the
rows --map-installed now logs from), cached by file stats. The Library
page gets a Proton map view (sortable, filterable, fuzzy search, hash
state, 30 s poll) and a map-installed job: POST checks the ids, the
phrase "map N games" and the game-running guard; the job re-checks
them and streams --map-installed --apply --yes --appids.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWZCxnNWLtpVwFLVk9w
2026-11-22 21:43:23 +01:00

107 lines
5.9 KiB
Markdown

# `install`, `repair-ghosts` and `map-installed` jobs
Part of the web control API ([DOCS-web-control-api.md](DOCS-web-control-api.md));
the TS mirror of the result is `InstallResultData` in `web/src/api/contract.ts`.
All three params are optional (`_command_params.PARAMS["install"]`):
- `target` (string): an AppID, a Steam URL (`…/app/<id>/…`) or a name, as
the installer's own `TARGET` argument. The job resolves it, never the
installer: inside the games allowed today, which are `allowed_games(state)`
plus the approved exceptions (named from the owned records). AppIDs and URLs
are parsed locally; names match exact title first, then substring (case
ignored), with no Steam search. Several matches → a `choice` prompt; no
match, or an id outside that set → the job fails (`locked`) and no
installer runs. The installer only ever gets the checked `--appid`.
Without `target`, the job offers every allowed game not yet fully
installed, approved exceptions included (`choice` when more than one).
- `dry_run` (bool): runs only `steam_installer.cli --appid <id> --dry-run`
and relays its report as `log` lines. No manifest is queued, Steam is not
closed, there is no `steam://` fallback, so it is allowed while a game runs.
An installer failure fails the job (`op_failed`).
- `valve_proton` (bool): passes `--valve-proton` to the installer.
The result `data` is `InstallResultData` `{app_id, dry_run,
fast_install_skipped}` once a game was chosen (else the assignment). The
installer closes Steam, so a real install while a game runs skips the fast
path (`_fast_install._refusal`) and Steam's own download starts:
`fast_install_skipped` is then `"game_running"`, and the UI paints the
`result.game-running` mark on the result (`result.dry-run` for a dry run).
## `repair-ghosts`
`./run.sh repair-ghosts` and the `repair-ghosts` job (Library page, icon
`cmd.repair-ghosts`) run the installer's `--repair-ghosts`
(`main/repair_ghosts.py`): every cold ghost manifest is renamed to
`*.ghost-<unix>` and its empty folder removed; a ghost with staged bytes is
only reported (`DOCS-steam-installer.md`, "Ghost installs"). No params, result
`data` = the assignment, an installer failure is `op_failed`.
The installer does not close Steam here, but it rewrites the library under a
client that may be reading it, so it gets `install`'s guard
(`_steam_restart_guard.game_is_running`).
| Command | Phrase (exact) | Checked |
|---|---|---|
| `repair-ghosts` | `delete ghost manifests` | at `POST /api/jobs` (`_web_jobs._PRECHECKED`), then again in the job |
At `POST /api/jobs` the phrase is checked first (`400 wrong_phrase`), then the
guard (`409 game_running`). Either refusal creates no job. The job re-checks
both, because a game can start in between. The UI paints the
`result.game-running` mark on a `game_running` refusal.
## Proton map: `GET /api/compat` and `map-installed`
`GET /api/compat` (`_compat_view.compat_view`) returns
`{tool, tool_ready, rows}`: one row per installed game, built by
`steam_installer.compat_rows.rows` (the same rows `--map-installed` logs, so
the view cannot disagree with the apply). A row is
`{app_id, name, current, priority, decided, reasons, note, map, changes,
cached}` (`CompatRow` in `web/src/api/contract.ts`); `null` in `current` or
`decided` means Valve's default. Steam's own tools are not rows. An unreadable
Steam, app cache or overrides file is `502 op_failed`.
Deciding parses the ~10 MB app cache, so the payload is kept in memory and
rebuilt only when a file it was decided from changes (`cache_key`: app cache,
`config.vdf`, `libraryfolders.vdf`, every `appmanifest_*.acf`, the overrides,
the tool's `VERSION`, the anti-cheat cache and its 6 h age window). A GET
never waits on the network unless that anti-cheat cache is older.
`./run.sh map-installed` and the `map-installed` job (Library page, view
`#view=compat`, icon `cmd.map-installed`) run the installer's
`--map-installed --apply --yes --appids <ids>` (`main/map_installed.py`). The
apply closes Steam (Steam rewrites `config.vdf` on exit), maps each game the
decision proves safe to the native Proton and starts Steam again, so it refuses
while a game runs (`409 game_running`). The job streams the installer's
output as `log` lines and has a 180 s timer.
Param `appids` (string, optional): comma-separated installed app ids. Absent,
the job maps every game whose row has `changes: true`. Ids that are not
installed, not digits, or an empty list are `400 invalid_params`
(`_compat_view.checked_appids`). The installer gets exactly the ids the phrase
counted, never "everything". The result `data` is `{app_ids: [...]}`.
| Command | Phrase (exact) | Checked |
|---|---|---|
| `map-installed` | `map {appid_count} games`, e.g. `map 3 games` | at `POST /api/jobs` (`_web_jobs._PRECHECKED`), then again in the job |
The count is part of the phrase, so a stale count is a wrong phrase. At
`POST /api/jobs` the ids are checked first (`400 invalid_params`, `502
op_failed` when Steam is unreadable), then the phrase (`400 wrong_phrase`),
then the guard (`409 game_running`). Each refusal creates no job. The UI fills
`{appid_count}` from the same ids (`fillPhrase` in `web/src/commands/catalog.ts`).
The view (`web/src/library/compatTable.ts`, state in `compatState.ts`) has
sortable columns, per-column filters, fuzzy search, a 30 s poll and row
checkboxes for games that change; with none ticked, Map applies to every
visible changing game. Its state lives in the URL hash, keys prefixed `c.`
because the cover grid owns `q` and `sort` in the same hash:
| Key | Meaning |
|---|---|
| `view=compat` | show the Proton map |
| `c.sort=<col>`, `c.dir=asc\|desc` | sort column (`name`, `app_id`, `current`, `decided`, `why`, `changes`) and direction; default `changes` ascending |
| `c.q=<text>` | fuzzy search |
| `c.f.<col>=<text>` | filter: substring for `name` and `why`, exact option for `current`, `decided`, `changes` (`changes` or `same`) |
| `c.f.app_id=<min>..<max>` | app id range, either side optional |