mirror of
https://github.com/kuhyx/steam-backlog-enforcer.git
synced 2026-11-22 23:02:19 +01:00
The installer ships as the steam_installer package beside steam_backlog_enforcer, with its tests, docs and Proton lock. The enforcer's fast install now starts the installer from this checkout. Both appinfo.vdf readers share one key-value decoder (steam_installer.appinfo_kv), and the duplicated test fixtures and helpers are folded into conftest and _cli_helpers so the whole-tree duplicate-code check is clean. check_requirements_sync treats sibling packages as first-party. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WzxdWZCxnNWLtpVwFLVk9w
208 lines
7.3 KiB
Python
208 lines
7.3 KiB
Python
"""Detect the fake "fully installed" state anonymous steamcmd leaves behind.
|
|
|
|
`steamcmd +login anonymous +app_update <paid appid>` has no licence for the
|
|
app. It does not say so. It transfers nothing, prints
|
|
|
|
Update state (0x0) unknown, progress: 0.00 (0 / 0)
|
|
Success! App '284160' fully installed.
|
|
|
|
exits 0, and writes a manifest claiming StateFlags=4 with SizeOnDisk=0 and an
|
|
empty InstalledDepots block. Reproduced on this machine on 2026-09-11.
|
|
|
|
That manifest is not harmless. A running Steam client reads it, concludes the
|
|
app is installed but out of date, and starts downloading the whole game by
|
|
itself -- which is exactly what happened, to the tune of 22 GB.
|
|
|
|
Two outcomes, and only one of them deletes anything:
|
|
|
|
* **Cold ghost** -- the lie and nothing else. Safe to clear away.
|
|
* **Warm ghost** -- the same manifest, but Steam has since staged real content
|
|
into `steamapps/downloading/<appid>/`. Those bytes are worth keeping: the
|
|
whole point of this tool is to make installs faster, and deleting a partial
|
|
download to start over is the opposite. Warm ghosts are routed to
|
|
`takeover`, never to `repair`.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass
|
|
import time
|
|
from typing import TYPE_CHECKING, Any
|
|
|
|
from steam_installer import manifest_write, recognize, vdf
|
|
|
|
if TYPE_CHECKING:
|
|
import logging
|
|
from pathlib import Path
|
|
|
|
from steam_installer.library import SteamLibrary
|
|
|
|
INSTALLED_STATE_FLAG = 4
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class GhostReport:
|
|
"""What the scan found about one app's manifest."""
|
|
|
|
appid: int
|
|
manifest_path: Path
|
|
install_dir: Path | None
|
|
content_bytes: int
|
|
staging_bytes: int
|
|
reasons: tuple[str, ...]
|
|
|
|
@property
|
|
def is_ghost(self) -> bool:
|
|
"""Whether the manifest claims an install with nothing behind it."""
|
|
return bool(self.reasons)
|
|
|
|
@property
|
|
def is_warm(self) -> bool:
|
|
"""Steam has staged real content for this app; it must not be deleted."""
|
|
return self.staging_bytes > 0
|
|
|
|
|
|
def staging_size(library: SteamLibrary, appid: int) -> int:
|
|
"""Bytes of staged content for *appid* in *library*."""
|
|
staged = library.steamapps / "downloading" / str(appid)
|
|
if not staged.is_dir():
|
|
return 0
|
|
return sum(f.stat().st_size for f in staged.rglob("*") if f.is_file())
|
|
|
|
|
|
def _install_dir(library: SteamLibrary, app_state: dict[str, Any]) -> Path | None:
|
|
installdir = app_state.get("installdir")
|
|
if not isinstance(installdir, str) or not installdir:
|
|
return None
|
|
return library.common / installdir
|
|
|
|
|
|
def _load_state(manifest_path: Path, appid: int) -> dict[str, Any] | None:
|
|
"""The manifest's AppState, or None when it is absent, unparsable or foreign."""
|
|
if not manifest_path.is_file():
|
|
return None
|
|
try:
|
|
app_state = recognize.read_app_state(manifest_path)
|
|
except vdf.VdfParseError:
|
|
return None
|
|
if str(app_state.get("appid", "")) != str(appid):
|
|
return None
|
|
return app_state
|
|
|
|
|
|
def _looks_installed_but_empty(
|
|
app_state: dict[str, Any], content_bytes: int, install_dir: Path | None
|
|
) -> bool:
|
|
"""Every ghost condition at once; one failing condition rules a ghost out."""
|
|
state_flags = app_state.get("StateFlags", "")
|
|
if not (str(state_flags).isdigit() and int(state_flags) & INSTALLED_STATE_FLAG):
|
|
return False
|
|
if app_state.get("InstalledDepots"):
|
|
return False
|
|
if str(app_state.get("SizeOnDisk", "0")) != "0" or content_bytes:
|
|
return False
|
|
# Our own downloader's cache means a real run is in progress against this
|
|
# directory; an empty install dir mid-download is not a ghost.
|
|
return not (
|
|
install_dir is not None
|
|
and recognize.discover_cached_depot_manifests(install_dir)
|
|
)
|
|
|
|
|
|
def inspect(library: SteamLibrary, appid: int) -> GhostReport:
|
|
"""Classify `appid` in `library`. An empty `reasons` means it is not a ghost.
|
|
|
|
Every condition is required. They are deliberately a conjunction: a real
|
|
install fails several of them at once, and a single `or` anywhere in this
|
|
chain is the difference between cleaning up a lie and deleting someone's
|
|
game.
|
|
"""
|
|
manifest_path = library.steamapps / f"appmanifest_{appid}.acf"
|
|
app_state = _load_state(manifest_path, appid)
|
|
if app_state is None:
|
|
return GhostReport(appid, manifest_path, None, 0, 0, ())
|
|
|
|
install_dir = _install_dir(library, app_state)
|
|
content_bytes = (
|
|
manifest_write.measure_content_size(install_dir)
|
|
if install_dir is not None and install_dir.is_dir()
|
|
else 0
|
|
)
|
|
staged = staging_size(library, appid)
|
|
if not _looks_installed_but_empty(app_state, content_bytes, install_dir):
|
|
return GhostReport(appid, manifest_path, install_dir, content_bytes, staged, ())
|
|
|
|
return GhostReport(
|
|
appid,
|
|
manifest_path,
|
|
install_dir,
|
|
content_bytes,
|
|
staged,
|
|
(
|
|
f"manifest claims StateFlags={app_state.get('StateFlags')} (installed)",
|
|
"InstalledDepots is empty",
|
|
"SizeOnDisk is 0",
|
|
"no game content on disk",
|
|
),
|
|
)
|
|
|
|
|
|
def scan(libraries: list[SteamLibrary]) -> list[GhostReport]:
|
|
"""Every ghost across every library, checked one manifest at a time."""
|
|
found: list[GhostReport] = []
|
|
for library in libraries:
|
|
if not library.steamapps.is_dir():
|
|
continue
|
|
for manifest in sorted(library.steamapps.glob("appmanifest_*.acf")):
|
|
digits = manifest.stem.removeprefix("appmanifest_")
|
|
if not digits.isdigit():
|
|
continue
|
|
report = inspect(library, int(digits))
|
|
if report.is_ghost:
|
|
found.append(report)
|
|
return found
|
|
|
|
|
|
def repair(
|
|
report: GhostReport, logger: logging.Logger, *, now_unix: int | None = None
|
|
) -> list[Path]:
|
|
"""Clear a COLD ghost away. Returns the paths it touched.
|
|
|
|
Refuses a warm ghost outright: those bytes belong to `takeover`.
|
|
"""
|
|
if not report.is_ghost:
|
|
msg = f"appid {report.appid} is not a ghost; refusing to touch it"
|
|
raise ValueError(msg)
|
|
if report.is_warm:
|
|
msg = (
|
|
f"appid {report.appid} has {report.staging_bytes / 1e9:.1f} GB of staged "
|
|
"Steam content. That is a partial download, not a ghost to delete -- "
|
|
"install it normally so the bytes are reused."
|
|
)
|
|
raise ValueError(msg)
|
|
|
|
stamp = int(time.time()) if now_unix is None else now_unix
|
|
touched: list[Path] = []
|
|
|
|
# Rename rather than unlink: reversible, atomic, and it leaves the evidence
|
|
# on disk if the diagnosis was somehow wrong.
|
|
backup = report.manifest_path.with_name(
|
|
f"{report.manifest_path.name}.ghost-{stamp}"
|
|
)
|
|
report.manifest_path.rename(backup)
|
|
logger.info("Moved bogus manifest to %s", backup)
|
|
touched.append(backup)
|
|
|
|
if report.install_dir is not None and report.install_dir.is_dir():
|
|
try:
|
|
# rmdir, never rmtree: the kernel refuses a non-empty directory, so
|
|
# a real install cannot be destroyed here even if inspect() were wrong.
|
|
report.install_dir.rmdir()
|
|
except OSError as exc:
|
|
logger.warning("Left %s in place: %s", report.install_dir, exc)
|
|
else:
|
|
logger.info("Removed empty %s", report.install_dir)
|
|
touched.append(report.install_dir)
|
|
|
|
return touched
|