kuhyx/steam-backlog-enforcer
1
0
Fork 0
mirror of https://github.com/kuhyx/steam-backlog-enforcer.git synced 2026-11-10 19:07:05 +01:00
Code Issues Actions 5 Packages Projects Releases Wiki Activity
81 Commits 1 Branch 0 Tags 6.8 MiB
Python 77.8%
TypeScript 19.9%
CSS 1.3%
Shell 0.6%
Astro 0.3%
21fe2f7742
Go to file
Krzysztof kuhy Rudnicki 21fe2f7742 Stop the enforcer launching Steam and notifications as root 
The enforce service runs as root (no User=) but sets DISPLAY=:0, so any GUI
it starts lands on the desktop session. Two resolvers disagreed about who to
drop privileges to:

  library_hider._resolve_desktop_user()  read STEAM_ENFORCER_DESKTOP_USER
  game_install._get_real_user()          read only SUDO_USER or USER

systemd sets neither of the latter, so _get_real_user() returned None under
the service and every `geteuid() == 0 and real_user and ...` guard fell
through to running as root. Steam answered with a zenity modal ("Cannot run
as root user", /usr/lib/steam/steam:261) on screen.

Confirmed from the live process tree: root `bash /usr/lib/steam/steam
-cef-disable-gpu ... steam://install/618510` with a root zenity child. It
never reached the journal, because that text goes to zenity and _run_as_user
sends child output to DEVNULL.

- _desktop_env: add resolve_desktop_user/desktop_uid/desktop_user_cmd. Only
  the argv builder is shared, never the spawn call: tests/_no_subprocess.py
  patches subprocess per module by name, so a spawn site in an unpatched
  module could fire a real `sudo -u kuhy steam`.
- game_install._get_real_user: delegate to the shared resolver. This alone
  also fixes the root `steam -silent` in _ensure_steam_running and the
  no-op os.chown on new appmanifests.
- _trigger_steam_install / enforcer.send_notification: drop privileges.
  send_notification had no DBUS_SESSION_BUS_ADDRESS, so it silently reached
  nobody for all six of its callers.
- _run_as_user: fail closed. Running unchanged as root when no desktop user
  resolves is what put the modal on screen; refuse and log instead.

Also stop the retry storm behind it. steamapps does not exist (Steam has
never completed sign-in), so is_game_installed() was always False and the
loop re-triggered every allowed game every pass: 1656 attempts in 30
minutes, service RSS 1.5 GB (peak 4.3 GB), a FileNotFoundError traceback
each time. Guard install_game and _reinstall_missing_allowed on
steam_library_ready() -- a missing library means no install can succeed by
any route, so this is a correctness check rather than a tuned retry limit.

The module splits here are forced by the pre-commit 250-line gate, which
blocks any commit touching an over-cap file: game_install, library_hider and
_enforce_loop were already over before this change. They are split by
responsibility (_cdp transport, _steam_launch lifecycle, _steam_process
spawning, _steam_errors, _steam_client, _game_names, game_uninstall,
_enforce_steps, _owned_apps_cache, _echo, _protected_apps). game_install and
library_hider re-export their old public names, so the 15 modules that
import from them are untouched by this commit.

Verified as real root under the unit's environment: argv is now
`sudo -u kuhy env DISPLAY=:0 ... xdg-open steam://install/...` for both the
installer and notify-send; three enforce passes spawn no process and log
once; _run_as_user refuses with no desktop user. After restart: 0 retries,
0 tracebacks, 0 root-owned files under ~/.local/share/Steam, RSS 342 MB.

1311 tests pass. _desktop_env and _steam_state at 100% branch coverage.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016A1EYiv7e7HGhET84oa9M3
2026-08-24 13:55:44 +02:00
.github/workflows chore: set up as standalone repo 2026-05-28 07:21:29 +02:00
docs/explanations feat(enforcer): raise manual pick cap from 2 to 3 concurrent games 2026-07-23 18:05:29 +02:00
pacman-hooks Add a daily gaming-time budget with a binary-level cutoff 2026-08-04 20:00:08 +02:00
prompts Add a continuation prompt for the 250-line cap refactor 2026-08-23 20:55:24 +02:00
scripts Add the 250-line file-length gate as a pre-commit hook 2026-08-23 19:27:09 +02:00
steam_backlog_enforcer Stop the enforcer launching Steam and notifications as root 2026-08-24 13:55:44 +02:00
web test(web): cover the 3 pre-existing branch-coverage gaps in SummaryCards 2026-07-22 17:40:25 +02:00
.gitignore Add CI-mirror pre-push gate + requirements-sync check 2026-07-11 17:47:14 +02:00
.mcp.json Add MCP server exposing the enforcer to Claude Code 2026-07-10 21:05:17 +02:00
.pre-commit-config.yaml Add the 250-line file-length gate as a pre-commit hook 2026-08-23 19:27:09 +02:00
CLAUDE.md feat: add block-gaming command (Stage 4) + guard-lib migration cleanup 2026-07-04 11:45:54 +02:00
DESIGN_AUDIT_TODO.md Add a design-rules audit against the new safe-design-rules checklist 2026-07-21 15:25:20 +02:00
install.sh Stop a non-interactive install aborting on the service prompt 2026-08-24 13:04:00 +02:00
pyproject.toml Add the 250-line file-length gate as a pre-commit hook 2026-08-23 19:27:09 +02:00
README.md Add MCP server exposing the enforcer to Claude Code 2026-07-10 21:05:17 +02:00
refactor_claude_todo.md Update refactor_claude_todo.md counts after gate exemption fixes 2026-08-14 16:03:01 +02:00
requirements.txt Pin mcp below 2.0 so CI can import mcp.server.fastmcp again 2026-08-04 20:07:09 +02:00
run.sh feat: add block-gaming command (Stage 4) + guard-lib migration cleanup 2026-07-04 11:45:54 +02:00
steam-backlog-enforcer.service Add a daily gaming-time budget with a binary-level cutoff 2026-08-04 20:00:08 +02:00

README.md

Steam Backlog Enforcer

Forces you to 100% complete one Steam game at a time before moving on.

Features

  • Achievement tracking: Picks the next game by shortest HLTB completionist time
  • Store blocking: Blocks store.steampowered.com via /etc/hosts
  • Game uninstalling: Removes all installed games except the assigned one
  • Process enforcement: Kills unauthorized game processes
  • Tampering detection: Detects achievement unlocks on non-assigned games
  • HLTB integration: Estimates completion time with persistent cache

Setup

python -m python_pkg.steam_backlog_enforcer.main setup

Commands

Command Description
scan Scan library, fetch HLTB data, assign game
check Check if assigned game is complete
status Show current assignment and blocking
list List incomplete games from snapshot
skip Skip the currently assigned game
enforce Run enforcer (block, uninstall, kill)
unblock Remove store blocking
reset Reset all state
installed List currently installed Steam games
uninstall Interactively uninstall non-assigned games
setup First-time configuration

Enforce mode

sudo python -m python_pkg.steam_backlog_enforcer.main enforce

This will:

  1. Block Steam store in /etc/hosts
  2. Uninstall all games except the assigned one
  3. Continuously kill any unauthorized game processes

Game Uninstall

Directly removes appmanifest files and game directories from ~/.local/share/Steam/steamapps/. Preserves Proton versions and Steam Linux Runtime.

python -m python_pkg.steam_backlog_enforcer.main uninstall

MCP server (Claude Code integration)

The enforcer exposes an MCP server (steam_backlog_enforcer._mcp) so Claude Code and its subagents can query the backlog and drive it through typed tools.

  • Read tools: get_dataset, get_status, get_stats, list_backlog.
  • Gated write tools: pick_manual, block_gaming — each defaults to a dry-run preview; pass confirm=true to actually apply. These write tools must never be added to a permission allowlist (a subagent could otherwise bypass the human confirmation).

The mcp SDK is an optional dependency (pip install -e '.[mcp]'), kept out of the CLI/systemd system-python path. One-time setup of the dedicated venv that Claude Code spawns:

./scripts/setup_mcp.sh

Registration lives in the checked-in .mcp.json (project scope). Restart Claude Code in this repo and approve the project MCP-server prompt for it to load. Verify with claude mcp list.