steamlayer-core 0.1.0__tar.gz

steamlayer_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 layeredtools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

steamlayer_core-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: steamlayer-core
+Version: 0.1.0
+Summary: Emulator-agnostic engine for identifying Steam games, patching DRM, and hydrating DLC metadata.
+License-Expression: MIT
+Project-URL: Source, https://github.com/layeredtools/steamlayer-core
+Project-URL: Issues, https://github.com/layeredtools/steamlayer-core/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Environment :: Console
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.33.1
+Dynamic: license-file
+
+<div align="center">
+
+# steamlayer-core
+
+[![PyPI](https://img.shields.io/pypi/v/steamlayer-core)](https://pypi.org/project/steamlayer-core/)
+[![Python](https://img.shields.io/pypi/pyversions/steamlayer-core)](https://pypi.org/project/steamlayer-core/)
+[![CI](https://img.shields.io/github/actions/workflow/status/layeredtools/steamlayer-core/ci.yml?branch=main&label=ci)](https://github.com/layeredtools/steamlayer-core/actions)
+[![License](https://img.shields.io/github/license/layeredtools/steamlayer-core)](LICENSE)
+
+The emulator-agnostic engine behind SteamLayer. Handles Steam game identification,
+DRM patching, and DLC hydration — with no opinion about which emulator you use.
+</div>
+
+## Overview
+
+`steamlayer-core` is a Python library that provides a clean pipeline for:
+
+1. **Resolving** a game directory to its Steam AppID (local files → app index → store search → disambiguation)
+2. **Patching** the game by swapping Steam API DLLs with emulator binaries and writing config
+3. **Unpatching** to restore the original files from a local backup vault
+4. **Fetching DLC metadata** for a given AppID, with disk caching
+
+The library is designed to be embedded inside higher-level tools. It has no `print()` or
+`input()` calls anywhere — all user interaction is delegated to injected callbacks.
+
+---
+
+## Installation
+
+```bash
+pip install steamlayer-core
+```
+
+Python 3.13+ is required.
+
+---
+
+## Quick start
+
+### One-shot functions
+
+The simplest way to use the library. Each call opens its own HTTP session and closes it
+when done.
+
+```python
+from pathlib import Path
+from steamlayer_core.api import resolve_game, patch_game
+
+# 1. Identify the game — resolve_game checks the directory for a steam_appid.txt
+#    or an appmanifest_*.acf file first. If found, no network call is made.
+game = resolve_game(Path("C:/games/Euro Truck Simulator 2"))
+print(game.appid, game.game_name)  # 227300, Euro Truck Simulator 2
+
+# 2. Patch it (requires a VendorProvider and ConfigWriter from your emulator layer)
+result = patch_game(game, Path("C:/games/Euro Truck Simulator 2"), vendor=vendor, config_writer=writer)
+print(result.patched_files)
+```
+
+If no local marker is found, the engine falls back to the app index and then a live
+store search. You can also skip the path entirely and trigger a web search directly by
+passing the game name as a string:
+
+```python
+# No path — goes straight to index/store search
+game = resolve_game("Euro Truck Simulator 2")
+```
+
+### Stateful client
+
+Use `SteamLayerClient` when you need to reuse a single HTTP session across multiple
+operations, wire progress callbacks once, or manage the lifecycle explicitly.
+
+```python
+from pathlib import Path
+from steamlayer_core import SteamLayerClient
+
+with SteamLayerClient(vendor=vendor, config_writer=writer, progress=my_progress_hook) as client:
+    game = client.resolve(Path("C:/games/Euro Truck Simulator 2"))
+    dlcs = client.fetch_dlcs(game.appid)
+    result = client.patch(game, Path("C:/games/Euro Truck Simulator 2"))
+```
+
+### Reverting a patch
+
+```python
+from steamlayer_core.api import SteamLayerClient
+
+with SteamLayerClient() as client:
+    if client.is_patched(game_path):
+        restored = client.unpatch(game_path)
+        print(f"Restored {len(restored)} file(s)")
+```
+
+
+## Core concepts
+
+### Resolution waterfall
+
+When you call `resolve()` or `resolve_game()`, the engine tries each strategy in order,
+stopping as soon as a confident match is found:
+
+```
+Game directory
+      │
+      ▼
+Local file inspection    (steam_appid.txt, appmanifest_*.acf, ...)
+      │ no match
+      ▼
+App index lookup         (offline index bundled with the library)
+      │ no match / low confidence
+      ▼
+Steam store search       (live web query, skipped if allow_network=False)
+      │ ambiguous
+      ▼
+Disambiguation callback  (your on_disambiguation handler, or AmbiguousMatchError)
+```
+
+### Emulator agnosticism
+
+`steamlayer-core` never references a specific emulator. It interacts with two
+protocols that you implement (or get from an emulator-specific package):
+
+| Protocol | Responsibility |
+|---|---|
+| `VendorProvider` | Supplies the emulator DLL binaries to be written into the game directory |
+| `ConfigWriter` | Defines what config files to write and where (AppID, DLC list, etc.) |
+
+This means the same core library can drive Goldberg, or any future emulator, just by
+swapping the injected implementations.
+
+### Backup vault
+
+Before any file is overwritten, `patch()` creates a local vault inside the game
+directory. `unpatch()` reads exclusively from this vault — it does not need to know
+which emulator was used. `purge_vault=True` (default) deletes the vault after a
+successful restore.
+
+### DLC caching
+
+`fetch_dlcs()` caches results to `~/.steamlayer/.cache/dlcs_{appid}.json`. Subsequent
+calls within the TTL window never touch the network. The cache path and TTL are
+configurable via `SteamlayerOptions`.
+
+
+## Design principles
+
+- **No I/O side-effects.** No `print()`, no `input()`, no logging to stdout. Progress
+  and interaction are surfaced through injected callbacks.
+- **Protocol-based injection.** `VendorProvider`, `ConfigWriter`, `HTTPClientProtocol`,
+  and the handler callbacks are all protocols. Mock any of them in tests without
+  subclassing.
+  implementation detail and may change between minor versions.
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome. Please open an issue before starting significant
+work so we can discuss the approach.
+
+```bash
+git clone https://github.com/your-org/steamlayer-core
+cd steamlayer-core
+pip install -e ".[dev]"
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

steamlayer_core-0.1.0/README.md

@@ -0,0 +1,171 @@
+<div align="center">
+
+# steamlayer-core
+
+[![PyPI](https://img.shields.io/pypi/v/steamlayer-core)](https://pypi.org/project/steamlayer-core/)
+[![Python](https://img.shields.io/pypi/pyversions/steamlayer-core)](https://pypi.org/project/steamlayer-core/)
+[![CI](https://img.shields.io/github/actions/workflow/status/layeredtools/steamlayer-core/ci.yml?branch=main&label=ci)](https://github.com/layeredtools/steamlayer-core/actions)
+[![License](https://img.shields.io/github/license/layeredtools/steamlayer-core)](LICENSE)
+
+The emulator-agnostic engine behind SteamLayer. Handles Steam game identification,
+DRM patching, and DLC hydration — with no opinion about which emulator you use.
+</div>
+
+## Overview
+
+`steamlayer-core` is a Python library that provides a clean pipeline for:
+
+1. **Resolving** a game directory to its Steam AppID (local files → app index → store search → disambiguation)
+2. **Patching** the game by swapping Steam API DLLs with emulator binaries and writing config
+3. **Unpatching** to restore the original files from a local backup vault
+4. **Fetching DLC metadata** for a given AppID, with disk caching
+
+The library is designed to be embedded inside higher-level tools. It has no `print()` or
+`input()` calls anywhere — all user interaction is delegated to injected callbacks.
+
+---
+
+## Installation
+
+```bash
+pip install steamlayer-core
+```
+
+Python 3.13+ is required.
+
+---
+
+## Quick start
+
+### One-shot functions
+
+The simplest way to use the library. Each call opens its own HTTP session and closes it
+when done.
+
+```python
+from pathlib import Path
+from steamlayer_core.api import resolve_game, patch_game
+
+# 1. Identify the game — resolve_game checks the directory for a steam_appid.txt
+#    or an appmanifest_*.acf file first. If found, no network call is made.
+game = resolve_game(Path("C:/games/Euro Truck Simulator 2"))
+print(game.appid, game.game_name)  # 227300, Euro Truck Simulator 2
+
+# 2. Patch it (requires a VendorProvider and ConfigWriter from your emulator layer)
+result = patch_game(game, Path("C:/games/Euro Truck Simulator 2"), vendor=vendor, config_writer=writer)
+print(result.patched_files)
+```
+
+If no local marker is found, the engine falls back to the app index and then a live
+store search. You can also skip the path entirely and trigger a web search directly by
+passing the game name as a string:
+
+```python
+# No path — goes straight to index/store search
+game = resolve_game("Euro Truck Simulator 2")
+```
+
+### Stateful client
+
+Use `SteamLayerClient` when you need to reuse a single HTTP session across multiple
+operations, wire progress callbacks once, or manage the lifecycle explicitly.
+
+```python
+from pathlib import Path
+from steamlayer_core import SteamLayerClient
+
+with SteamLayerClient(vendor=vendor, config_writer=writer, progress=my_progress_hook) as client:
+    game = client.resolve(Path("C:/games/Euro Truck Simulator 2"))
+    dlcs = client.fetch_dlcs(game.appid)
+    result = client.patch(game, Path("C:/games/Euro Truck Simulator 2"))
+```
+
+### Reverting a patch
+
+```python
+from steamlayer_core.api import SteamLayerClient
+
+with SteamLayerClient() as client:
+    if client.is_patched(game_path):
+        restored = client.unpatch(game_path)
+        print(f"Restored {len(restored)} file(s)")
+```
+
+
+## Core concepts
+
+### Resolution waterfall
+
+When you call `resolve()` or `resolve_game()`, the engine tries each strategy in order,
+stopping as soon as a confident match is found:
+
+```
+Game directory
+      │
+      ▼
+Local file inspection    (steam_appid.txt, appmanifest_*.acf, ...)
+      │ no match
+      ▼
+App index lookup         (offline index bundled with the library)
+      │ no match / low confidence
+      ▼
+Steam store search       (live web query, skipped if allow_network=False)
+      │ ambiguous
+      ▼
+Disambiguation callback  (your on_disambiguation handler, or AmbiguousMatchError)
+```
+
+### Emulator agnosticism
+
+`steamlayer-core` never references a specific emulator. It interacts with two
+protocols that you implement (or get from an emulator-specific package):
+
+| Protocol | Responsibility |
+|---|---|
+| `VendorProvider` | Supplies the emulator DLL binaries to be written into the game directory |
+| `ConfigWriter` | Defines what config files to write and where (AppID, DLC list, etc.) |
+
+This means the same core library can drive Goldberg, or any future emulator, just by
+swapping the injected implementations.
+
+### Backup vault
+
+Before any file is overwritten, `patch()` creates a local vault inside the game
+directory. `unpatch()` reads exclusively from this vault — it does not need to know
+which emulator was used. `purge_vault=True` (default) deletes the vault after a
+successful restore.
+
+### DLC caching
+
+`fetch_dlcs()` caches results to `~/.steamlayer/.cache/dlcs_{appid}.json`. Subsequent
+calls within the TTL window never touch the network. The cache path and TTL are
+configurable via `SteamlayerOptions`.
+
+
+## Design principles
+
+- **No I/O side-effects.** No `print()`, no `input()`, no logging to stdout. Progress
+  and interaction are surfaced through injected callbacks.
+- **Protocol-based injection.** `VendorProvider`, `ConfigWriter`, `HTTPClientProtocol`,
+  and the handler callbacks are all protocols. Mock any of them in tests without
+  subclassing.
+  implementation detail and may change between minor versions.
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome. Please open an issue before starting significant
+work so we can discuss the approach.
+
+```bash
+git clone https://github.com/your-org/steamlayer-core
+cd steamlayer-core
+pip install -e ".[dev]"
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

steamlayer_core-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "steamlayer-core"
+version = "0.1.0"
+description = "Emulator-agnostic engine for identifying Steam games, patching DRM, and hydrating DLC metadata."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+requires-python = ">=3.13"
+dependencies = [
+    "requests>=2.33.1",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Operating System :: Microsoft :: Windows",
+    "Environment :: Console",
+]
+
+[project.urls]
+Source = "https://github.com/layeredtools/steamlayer-core"
+Issues = "https://github.com/layeredtools/steamlayer-core/issues"
+
+[dependency-groups]
+dev = [
+    "mkdocs-material>=9.7.6",
+    "mkdocstrings[python]>=1.0.4",
+    "mypy>=1.20.0",
+    "pre-commit>=4.5.1",
+    "pytest>=9.0.3",
+    "rich>=15.0.0",
+    "ruff>=0.15.10",
+    "types-requests>=2.33.0.20260408",
+]
+
+[tool.ruff]
+line-length = 115
+target-version = "py313"
+fix = true
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.mypy]
+python_version = "3.13"
+strict = false
+warn_unused_ignores = false
+
+[[tool.mypy.overrides]]
+module = "steamlayer.tests.*"
+ignore_errors = true

steamlayer_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

steamlayer_core-0.1.0/steamlayer_core/__init__.py

@@ -0,0 +1,110 @@
+"""
+steamlayer-core
+===============
+A headless, I/O-free library for Steam game identification, DLC hydration,
+and emulator-agnostic patching.
+
+Quick start
+-----------
+::
+
+    from pathlib import Path
+    from steamlayer_core import SteamLayerClient, GoldbergLocalVendorProvider, GoldbergConfigWriter
+
+    with SteamLayerClient(
+        vendor=GoldbergLocalVendorProvider(Path("./vendors")),
+        config_writer=GoldbergConfigWriter(),
+    ) as client:
+        game = client.resolve(Path("/games/Portal 2"))
+        result = client.patch(game, Path("/games/Portal 2"))
+        print(result.targets_patched)
+
+Public surface
+--------------
+Only the names imported here are considered stable API.  Everything else is
+an implementation detail subject to change without notice.
+"""
+
+from steamlayer_core.adapters import (
+    FixedConfirmationHandler,
+    FixedDisambiguationHandler,
+)
+from steamlayer_core.api import SteamLayerClient, fetch_dlcs, patch_game, resolve_game
+from steamlayer_core.domain.events import AmbiguousMatchEvent, LowConfidenceEvent
+from steamlayer_core.domain.exceptions import (
+    AmbiguousMatchError,
+    AppIDNotFoundError,
+    ConfigurationError,
+    DLCCacheError,
+    DLCHydrationError,
+    EmulatorBinaryError,
+    LowConfidenceError,
+    PatchError,
+    SteamLayerError,
+    VaultError,
+)
+from steamlayer_core.domain.models import (
+    DiscoveryResult,
+    DLCInfo,
+    ResolutionSource,
+    ResolvedGame,
+    SteamlayerOptions,
+)
+from steamlayer_core.patching.config import GoldbergConfigWriter
+from steamlayer_core.patching.engine import PatchEngine
+from steamlayer_core.patching.models import PatchResult, PatchTarget
+from steamlayer_core.patching.vendors import GoldbergLocalVendorProvider, LocalVendorProvider
+from steamlayer_core.protocols import (
+    ConfigWriter,
+    ConfirmationHandler,
+    DisambiguationHandler,
+    ProgressCallback,
+    VendorProvider,
+)
+
+__all__ = [
+    # Client
+    "SteamLayerClient",
+    # API functions
+    "resolve_game",
+    "patch_game",
+    "fetch_dlcs",
+    # Models
+    "SteamlayerOptions",
+    "ResolvedGame",
+    "DiscoveryResult",
+    "ResolutionSource",
+    "DLCInfo",
+    # Events
+    "AmbiguousMatchEvent",
+    "LowConfidenceEvent",
+    # Exceptions
+    "SteamLayerError",
+    "AppIDNotFoundError",
+    "AmbiguousMatchError",
+    "LowConfidenceError",
+    "PatchError",
+    "VaultError",
+    "EmulatorBinaryError",
+    "DLCHydrationError",
+    "DLCCacheError",
+    "ConfigurationError",
+    # Protocols
+    "ConfigWriter",
+    "ConfirmationHandler",
+    "DisambiguationHandler",
+    "ProgressCallback",
+    "VendorProvider",
+    # Adapters
+    "FixedDisambiguationHandler",
+    "FixedConfirmationHandler",
+    # Vendors
+    "LocalVendorProvider",
+    "GoldbergLocalVendorProvider",
+    # Patching
+    "PatchEngine",
+    "PatchResult",
+    "PatchTarget",
+    # Config writers
+    "GoldbergConfigWriter",
+]

steamlayer_core-0.1.0/steamlayer_core/_version.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("steamlayer-core")
+except PackageNotFoundError:
+    __version__ = "dev"

steamlayer_core-0.1.0/steamlayer_core/adapters.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from steamlayer_core.domain.exceptions import AppIDNotFoundError, AppIDResolutionError
+
+if TYPE_CHECKING:
+    from steamlayer_core.domain.events import AmbiguousMatchEvent, LowConfidenceEvent
+    from steamlayer_core.domain.models import DiscoveryResult
+
+logger = logging.getLogger(__name__)
+
+
+class FixedDisambiguationHandler:
+    """
+    Adapter used when the user has already provided a specific AppID (e.g., via CLI).
+    Instead of asking, it searches the candidates for a match and returns it.
+    """
+
+    def __init__(self, target_appid: int) -> None:
+        self.target_appid = target_appid
+
+    def handle_disambiguation(self, event: AmbiguousMatchEvent) -> DiscoveryResult:
+        logger.debug(f"Fixed handler looking for AppID {self.target_appid} in candidates.")
+
+        for candidate in event.candidates:
+            if candidate.appid == self.target_appid:
+                return candidate
+
+        raise ValueError(f"Provided AppID {self.target_appid} not found in resolution candidates.")
+
+
+class FixedConfirmationHandler:
+    """
+    Adapter used for 'non-interactive' mode (e.g., a --yes flag).
+    Automatically accepts or rejects low-confidence matches.
+    """
+
+    def __init__(self, auto_confirm: bool = True) -> None:
+        self.auto_confirm = auto_confirm
+
+    def handle_confirmation(self, event: LowConfidenceEvent) -> DiscoveryResult:
+        logger.info(
+            f"Auto-confirming ({self.auto_confirm}) match for {event.game_folder_name} "
+            f"with confidence {event.candidate.confidence:.2f}"
+        )
+        if self.auto_confirm:
+            return event.candidate
+        raise AppIDNotFoundError(event.game_folder_name)
+
+
+class CLIHandler:
+    """
+    The primary interactive adapter for terminal users.
+    """
+
+    def handle_disambiguation(self, event: AmbiguousMatchEvent) -> DiscoveryResult:
+        print(f"\n[!] Multiple matches found for folder: '{event.game_folder_name}'")
+        for i, c in enumerate(event.candidates, 1):
+            print(f"  {i}) {c.game_name} (AppID: {c.appid}) [Confidence: {c.confidence:.2f}]")
+
+        while True:
+            choice = input("\nSelect the correct game (or 'q' to abort): ").strip().lower()
+            if choice == "q":
+                raise KeyboardInterrupt()
+            if choice.isdigit() and 1 <= int(choice) <= len(event.candidates):
+                return event.candidates[int(choice) - 1]
+
+    def handle_confirmation(self, event: LowConfidenceEvent) -> DiscoveryResult:
+        print(f"\n[?] Low confidence match for '{event.game_folder_name}':")
+        print(f"    Suggested: {event.candidate.game_name} (AppID: {event.candidate.appid})")
+        print(f"    Confidence: {event.candidate.confidence:.2f} (Threshold: {event.threshold:.2f})")
+
+        choice = input("Is this correct? [y/N]: ").strip().lower()
+        if choice == "y":
+            return event.candidate
+        raise AppIDResolutionError("User rejected candidate.")