steam-shortcuts 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. steam_shortcuts-0.1.0/LICENSE +21 -0
  2. steam_shortcuts-0.1.0/PKG-INFO +167 -0
  3. steam_shortcuts-0.1.0/README.md +137 -0
  4. steam_shortcuts-0.1.0/pyproject.toml +68 -0
  5. steam_shortcuts-0.1.0/setup.cfg +4 -0
  6. steam_shortcuts-0.1.0/src/steam_shortcuts/__init__.py +32 -0
  7. steam_shortcuts-0.1.0/src/steam_shortcuts/api.py +167 -0
  8. steam_shortcuts-0.1.0/src/steam_shortcuts/cli.py +169 -0
  9. steam_shortcuts-0.1.0/src/steam_shortcuts/discovery.py +127 -0
  10. steam_shortcuts-0.1.0/src/steam_shortcuts/errors.py +78 -0
  11. steam_shortcuts-0.1.0/src/steam_shortcuts/models.py +56 -0
  12. steam_shortcuts-0.1.0/src/steam_shortcuts/process.py +36 -0
  13. steam_shortcuts-0.1.0/src/steam_shortcuts/service.py +222 -0
  14. steam_shortcuts-0.1.0/src/steam_shortcuts/vdf_store.py +173 -0
  15. steam_shortcuts-0.1.0/src/steam_shortcuts.egg-info/PKG-INFO +167 -0
  16. steam_shortcuts-0.1.0/src/steam_shortcuts.egg-info/SOURCES.txt +26 -0
  17. steam_shortcuts-0.1.0/src/steam_shortcuts.egg-info/dependency_links.txt +1 -0
  18. steam_shortcuts-0.1.0/src/steam_shortcuts.egg-info/entry_points.txt +2 -0
  19. steam_shortcuts-0.1.0/src/steam_shortcuts.egg-info/requires.txt +9 -0
  20. steam_shortcuts-0.1.0/src/steam_shortcuts.egg-info/top_level.txt +1 -0
  21. steam_shortcuts-0.1.0/tests/test_api_cli.py +119 -0
  22. steam_shortcuts-0.1.0/tests/test_cli.py +6 -0
  23. steam_shortcuts-0.1.0/tests/test_discovery.py +49 -0
  24. steam_shortcuts-0.1.0/tests/test_models.py +61 -0
  25. steam_shortcuts-0.1.0/tests/test_process.py +61 -0
  26. steam_shortcuts-0.1.0/tests/test_service.py +121 -0
  27. steam_shortcuts-0.1.0/tests/test_transaction.py +94 -0
  28. steam_shortcuts-0.1.0/tests/test_vdf_store.py +54 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rodrigo Machado
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,167 @@
1
+ Metadata-Version: 2.4
2
+ Name: steam-shortcuts
3
+ Version: 0.1.0
4
+ Summary: Safely add non-Steam shortcuts through a Python API and CLI.
5
+ Author: Rodrigo Machado
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/msrodrigobr/steam-shortcuts
8
+ Project-URL: Source, https://github.com/msrodrigobr/steam-shortcuts
9
+ Project-URL: Issues, https://github.com/msrodrigobr/steam-shortcuts/issues
10
+ Keywords: steam,shortcuts,games,automation
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: End Users/Desktop
13
+ Classifier: Operating System :: MacOS
14
+ Classifier: Operating System :: Microsoft :: Windows
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Requires-Python: >=3.10
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: psutil<8,>=5.9
22
+ Requires-Dist: vdf<4,>=3.4
23
+ Provides-Extra: dev
24
+ Requires-Dist: build<2,>=1.2; extra == "dev"
25
+ Requires-Dist: mypy<3,>=1.0; extra == "dev"
26
+ Requires-Dist: pytest<10,>=8; extra == "dev"
27
+ Requires-Dist: ruff<1,>=0.10; extra == "dev"
28
+ Requires-Dist: types-psutil<8,>=7; extra == "dev"
29
+ Dynamic: license-file
30
+
31
+ # steam-shortcuts
32
+
33
+ A portable Python library and command-line tool for adding non-Steam shortcuts to a local Steam profile without GUI automation.
34
+
35
+ It edits only Steam's per-user binary `userdata/<steam-id>/config/shortcuts.vdf`, never `localconfig.vdf`. Before replacing an existing shortcut file it creates a timestamped sibling backup, uses an atomic replacement, then rereads the VDF and verifies the exact shortcut it added.
36
+
37
+ Steam must be fully closed before using `add`. The tool refuses to write if it detects the main `steam` or `steam.exe` process. It will not murder Steam for you; that is a feature, not a missing feature.
38
+
39
+ ## Status and support
40
+
41
+ - Windows is the primary acceptance target for Windows executable paths.
42
+ - Steam discovery supports Windows registry/default locations, common Linux locations (including Flatpak), and macOS.
43
+ - If a Steam root has multiple numeric profiles, `--steam-id` is required. The tool never guesses an account.
44
+ - The first release intentionally does not add artwork, modify Steam Cloud or `localconfig.vdf`, restart Steam, launch games, or drive the Steam UI.
45
+
46
+ ## Install
47
+
48
+ Until this distribution is published, install a checkout into an isolated `pipx` environment:
49
+
50
+ ```text
51
+ pipx install .
52
+ steam-shortcuts --help
53
+ ```
54
+
55
+ After a published release exists, the equivalent will be:
56
+
57
+ ```text
58
+ pipx install steam-shortcuts
59
+ ```
60
+
61
+ After a published release exists, use it as a library in another Python project:
62
+
63
+ ```text
64
+ python -m pip install steam-shortcuts
65
+ ```
66
+
67
+ ## Command-line use
68
+
69
+ First, inspect the local Steam installation and profiles:
70
+
71
+ ```text
72
+ steam-shortcuts detect --json
73
+ steam-shortcuts list --steam-id 123456789 --json
74
+ ```
75
+
76
+ Add a Windows executable. Quote the shell argument normally; do not add the internal Steam quotes yourself:
77
+
78
+ ```text
79
+ steam-shortcuts add \
80
+ --steam-id 123456789 \
81
+ --name "My Game" \
82
+ --exe "D:\Games\My Game\Game.exe" \
83
+ --start-dir "D:\Games\My Game" \
84
+ --args "--windowed" \
85
+ --tag "Local" \
86
+ --json
87
+ ```
88
+
89
+ Use `--dry-run` first whenever you are doing something unusual. It validates Steam discovery, profile selection, the executable, duplicates, and the planned fields without writing a VDF or backup:
90
+
91
+ ```text
92
+ steam-shortcuts add \
93
+ --steam-id 123456789 \
94
+ --name "My Game" \
95
+ --exe "D:\Games\My Game\Game.exe" \
96
+ --dry-run --json
97
+ ```
98
+
99
+ For portable or nonstandard installs, give the Steam root — the directory that contains `userdata`, not the VDF file itself:
100
+
101
+ ```text
102
+ steam-shortcuts add \
103
+ --steam-root "E:\PortableSteam" \
104
+ --steam-id 123456789 \
105
+ --name "My Game" \
106
+ --exe "D:\Games\My Game\Game.exe"
107
+ ```
108
+
109
+ A successful JSON result includes `status`, `profile_id`, `shortcuts_path`, a 32-bit shortcut ID, `steam://rungameid/...`, and `backup_path`. Rerunning the exact name/executable combination returns `already_exists` and creates no backup. Reusing an executable under a different display name is deliberately a conflict rather than a surprise duplicate.
110
+
111
+ Restart Steam normally after a successful add so it reloads `shortcuts.vdf`; then the item should appear in the library.
112
+
113
+ ## Python API
114
+
115
+ ```python
116
+ from pathlib import Path
117
+ from steam_shortcuts import add_shortcut
118
+
119
+ result = add_shortcut(
120
+ name="My Game",
121
+ executable=Path(r"D:\Games\My Game\Game.exe"),
122
+ start_dir=Path(r"D:\Games\My Game"),
123
+ launch_options="--windowed",
124
+ tags=("Local",),
125
+ steam_id="123456789", # omit only when exactly one profile exists
126
+ )
127
+
128
+ print(result.status, result.run_game_url, result.backup_path)
129
+ ```
130
+
131
+ The API and CLI run on the same local user account that owns the Steam profile. They do not communicate with a Steam account, web API, or remote computer.
132
+
133
+ ## Recovery
134
+
135
+ For an existing VDF, every successful mutation creates a sibling backup named like:
136
+
137
+ ```text
138
+ shortcuts.vdf.bak.20261112T020000Z
139
+ ```
140
+
141
+ If Steam rejects or does not show an added shortcut:
142
+
143
+ 1. Fully exit Steam.
144
+ 2. Preserve the current `shortcuts.vdf` for investigation instead of deleting it.
145
+ 3. Replace it with the timestamped `.bak.*` file from the same directory.
146
+ 4. Start Steam and verify the prior library state.
147
+
148
+ A malformed VDF is rejected without overwriting it. Keep that file and its error message; it is evidence, not clutter.
149
+
150
+ ## Development
151
+
152
+ ```text
153
+ python -m venv .venv
154
+ .venv/bin/python -m pip install -e ".[dev]"
155
+ .venv/bin/python -m pytest -q
156
+ .venv/bin/ruff check .
157
+ .venv/bin/mypy src
158
+ .venv/bin/python -m build
159
+ ```
160
+
161
+ See `docs/acceptance-test.md` for the real Steam-client validation procedure.
162
+
163
+ ## Public releases
164
+
165
+ Public releases are created by pushing a semantic version tag such as `v0.1.0`. The release workflow rebuilds the package, runs tests, linting, and type checks, then publishes with PyPI Trusted Publishing through GitHub OIDC. It intentionally contains no long-lived PyPI API token.
166
+
167
+ Before the first release, configure a pending PyPI trusted publisher for project `steam-shortcuts`, GitHub owner `msrodrigobr`, repository `steam-shortcuts`, workflow filename `publish.yml`, and the protected GitHub environment `pypi`. A pending publisher does not reserve a project name; publish promptly after configuration.
@@ -0,0 +1,137 @@
1
+ # steam-shortcuts
2
+
3
+ A portable Python library and command-line tool for adding non-Steam shortcuts to a local Steam profile without GUI automation.
4
+
5
+ It edits only Steam's per-user binary `userdata/<steam-id>/config/shortcuts.vdf`, never `localconfig.vdf`. Before replacing an existing shortcut file it creates a timestamped sibling backup, uses an atomic replacement, then rereads the VDF and verifies the exact shortcut it added.
6
+
7
+ Steam must be fully closed before using `add`. The tool refuses to write if it detects the main `steam` or `steam.exe` process. It will not murder Steam for you; that is a feature, not a missing feature.
8
+
9
+ ## Status and support
10
+
11
+ - Windows is the primary acceptance target for Windows executable paths.
12
+ - Steam discovery supports Windows registry/default locations, common Linux locations (including Flatpak), and macOS.
13
+ - If a Steam root has multiple numeric profiles, `--steam-id` is required. The tool never guesses an account.
14
+ - The first release intentionally does not add artwork, modify Steam Cloud or `localconfig.vdf`, restart Steam, launch games, or drive the Steam UI.
15
+
16
+ ## Install
17
+
18
+ Until this distribution is published, install a checkout into an isolated `pipx` environment:
19
+
20
+ ```text
21
+ pipx install .
22
+ steam-shortcuts --help
23
+ ```
24
+
25
+ After a published release exists, the equivalent will be:
26
+
27
+ ```text
28
+ pipx install steam-shortcuts
29
+ ```
30
+
31
+ After a published release exists, use it as a library in another Python project:
32
+
33
+ ```text
34
+ python -m pip install steam-shortcuts
35
+ ```
36
+
37
+ ## Command-line use
38
+
39
+ First, inspect the local Steam installation and profiles:
40
+
41
+ ```text
42
+ steam-shortcuts detect --json
43
+ steam-shortcuts list --steam-id 123456789 --json
44
+ ```
45
+
46
+ Add a Windows executable. Quote the shell argument normally; do not add the internal Steam quotes yourself:
47
+
48
+ ```text
49
+ steam-shortcuts add \
50
+ --steam-id 123456789 \
51
+ --name "My Game" \
52
+ --exe "D:\Games\My Game\Game.exe" \
53
+ --start-dir "D:\Games\My Game" \
54
+ --args "--windowed" \
55
+ --tag "Local" \
56
+ --json
57
+ ```
58
+
59
+ Use `--dry-run` first whenever you are doing something unusual. It validates Steam discovery, profile selection, the executable, duplicates, and the planned fields without writing a VDF or backup:
60
+
61
+ ```text
62
+ steam-shortcuts add \
63
+ --steam-id 123456789 \
64
+ --name "My Game" \
65
+ --exe "D:\Games\My Game\Game.exe" \
66
+ --dry-run --json
67
+ ```
68
+
69
+ For portable or nonstandard installs, give the Steam root — the directory that contains `userdata`, not the VDF file itself:
70
+
71
+ ```text
72
+ steam-shortcuts add \
73
+ --steam-root "E:\PortableSteam" \
74
+ --steam-id 123456789 \
75
+ --name "My Game" \
76
+ --exe "D:\Games\My Game\Game.exe"
77
+ ```
78
+
79
+ A successful JSON result includes `status`, `profile_id`, `shortcuts_path`, a 32-bit shortcut ID, `steam://rungameid/...`, and `backup_path`. Rerunning the exact name/executable combination returns `already_exists` and creates no backup. Reusing an executable under a different display name is deliberately a conflict rather than a surprise duplicate.
80
+
81
+ Restart Steam normally after a successful add so it reloads `shortcuts.vdf`; then the item should appear in the library.
82
+
83
+ ## Python API
84
+
85
+ ```python
86
+ from pathlib import Path
87
+ from steam_shortcuts import add_shortcut
88
+
89
+ result = add_shortcut(
90
+ name="My Game",
91
+ executable=Path(r"D:\Games\My Game\Game.exe"),
92
+ start_dir=Path(r"D:\Games\My Game"),
93
+ launch_options="--windowed",
94
+ tags=("Local",),
95
+ steam_id="123456789", # omit only when exactly one profile exists
96
+ )
97
+
98
+ print(result.status, result.run_game_url, result.backup_path)
99
+ ```
100
+
101
+ The API and CLI run on the same local user account that owns the Steam profile. They do not communicate with a Steam account, web API, or remote computer.
102
+
103
+ ## Recovery
104
+
105
+ For an existing VDF, every successful mutation creates a sibling backup named like:
106
+
107
+ ```text
108
+ shortcuts.vdf.bak.20261112T020000Z
109
+ ```
110
+
111
+ If Steam rejects or does not show an added shortcut:
112
+
113
+ 1. Fully exit Steam.
114
+ 2. Preserve the current `shortcuts.vdf` for investigation instead of deleting it.
115
+ 3. Replace it with the timestamped `.bak.*` file from the same directory.
116
+ 4. Start Steam and verify the prior library state.
117
+
118
+ A malformed VDF is rejected without overwriting it. Keep that file and its error message; it is evidence, not clutter.
119
+
120
+ ## Development
121
+
122
+ ```text
123
+ python -m venv .venv
124
+ .venv/bin/python -m pip install -e ".[dev]"
125
+ .venv/bin/python -m pytest -q
126
+ .venv/bin/ruff check .
127
+ .venv/bin/mypy src
128
+ .venv/bin/python -m build
129
+ ```
130
+
131
+ See `docs/acceptance-test.md` for the real Steam-client validation procedure.
132
+
133
+ ## Public releases
134
+
135
+ Public releases are created by pushing a semantic version tag such as `v0.1.0`. The release workflow rebuilds the package, runs tests, linting, and type checks, then publishes with PyPI Trusted Publishing through GitHub OIDC. It intentionally contains no long-lived PyPI API token.
136
+
137
+ Before the first release, configure a pending PyPI trusted publisher for project `steam-shortcuts`, GitHub owner `msrodrigobr`, repository `steam-shortcuts`, workflow filename `publish.yml`, and the protected GitHub environment `pypi`. A pending publisher does not reserve a project name; publish promptly after configuration.
@@ -0,0 +1,68 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "steam-shortcuts"
7
+ version = "0.1.0"
8
+ description = "Safely add non-Steam shortcuts through a Python API and CLI."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{name = "Rodrigo Machado"}]
14
+ keywords = ["steam", "shortcuts", "games", "automation"]
15
+ classifiers = [
16
+ "Development Status :: 3 - Alpha",
17
+ "Intended Audience :: End Users/Desktop",
18
+ "Operating System :: MacOS",
19
+ "Operating System :: Microsoft :: Windows",
20
+ "Operating System :: POSIX :: Linux",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3 :: Only",
23
+ ]
24
+ dependencies = [
25
+ "psutil>=5.9,<8",
26
+ "vdf>=3.4,<4",
27
+ ]
28
+
29
+ [project.urls]
30
+ Homepage = "https://github.com/msrodrigobr/steam-shortcuts"
31
+ Source = "https://github.com/msrodrigobr/steam-shortcuts"
32
+ Issues = "https://github.com/msrodrigobr/steam-shortcuts/issues"
33
+
34
+ [project.scripts]
35
+ steam-shortcuts = "steam_shortcuts.cli:main"
36
+
37
+ [project.optional-dependencies]
38
+ dev = [
39
+ "build>=1.2,<2",
40
+ "mypy>=1.0,<3",
41
+ "pytest>=8,<10",
42
+ "ruff>=0.10,<1",
43
+ "types-psutil>=7,<8",
44
+ ]
45
+
46
+ [tool.setuptools]
47
+ package-dir = {"" = "src"}
48
+
49
+ [tool.setuptools.packages.find]
50
+ where = ["src"]
51
+
52
+ [tool.pytest.ini_options]
53
+ pythonpath = ["src"]
54
+ testpaths = ["tests"]
55
+ addopts = "-ra"
56
+
57
+ [tool.ruff]
58
+ line-length = 100
59
+ target-version = "py310"
60
+
61
+ [tool.ruff.lint]
62
+ select = ["E", "F", "I", "UP", "B", "SIM"]
63
+
64
+ [tool.mypy]
65
+ files = ["src"]
66
+ python_version = "3.10"
67
+ strict = true
68
+ warn_unreachable = true
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,32 @@
1
+ """Portable, safe management of local Steam non-Steam shortcuts."""
2
+
3
+ from .api import add_shortcut
4
+ from .errors import (
5
+ InvalidExecutable,
6
+ InvalidShortcutFile,
7
+ ProfileNotFound,
8
+ ProfileSelectionRequired,
9
+ ShortcutConflict,
10
+ ShortcutVerificationFailed,
11
+ SteamNotFound,
12
+ SteamRunning,
13
+ )
14
+ from .models import ShortcutRequest, ShortcutResult, SteamProfile
15
+
16
+ __version__ = "0.1.0"
17
+
18
+ __all__ = [
19
+ "add_shortcut",
20
+ "InvalidShortcutFile",
21
+ "InvalidExecutable",
22
+ "ProfileNotFound",
23
+ "ProfileSelectionRequired",
24
+ "ShortcutConflict",
25
+ "ShortcutVerificationFailed",
26
+ "ShortcutRequest",
27
+ "ShortcutResult",
28
+ "SteamNotFound",
29
+ "SteamProfile",
30
+ "SteamRunning",
31
+ "__version__",
32
+ ]
@@ -0,0 +1,167 @@
1
+ """Public library API for local Steam shortcut management."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Iterable
6
+ from dataclasses import dataclass
7
+ from pathlib import Path
8
+
9
+ from .discovery import discover_steam_root, list_profile_ids, select_profile
10
+ from .models import ShortcutRequest, ShortcutResult, SteamProfile
11
+ from .process import ensure_steam_not_running
12
+ from .service import (
13
+ ShortcutAdditionPlan,
14
+ add_shortcut_to_profile,
15
+ plan_shortcut_addition,
16
+ to_unsigned_int32,
17
+ )
18
+ from .vdf_store import VdfMap, VdfValue, load_shortcuts
19
+
20
+
21
+ @dataclass(frozen=True, slots=True)
22
+ class SteamInstallation:
23
+ """A discovered Steam root and the numeric user profiles beneath it."""
24
+
25
+ steam_root: Path
26
+ profile_ids: tuple[str, ...]
27
+
28
+
29
+ @dataclass(frozen=True, slots=True)
30
+ class ShortcutPreview:
31
+ """An addition plan resolved to one Steam profile without a file write."""
32
+
33
+ steam_root: Path
34
+ profile: SteamProfile
35
+ plan: ShortcutAdditionPlan
36
+
37
+
38
+ @dataclass(frozen=True, slots=True)
39
+ class ShortcutListing:
40
+ """A shortcut shown by the list API."""
41
+
42
+ index: str
43
+ name: str
44
+ executable: str
45
+ app_id: int | None
46
+
47
+
48
+ def detect_steam(steam_root: Path | None = None) -> SteamInstallation:
49
+ """Discover Steam and return its selectable local profiles."""
50
+ root = discover_steam_root(steam_root)
51
+ return SteamInstallation(steam_root=root, profile_ids=list_profile_ids(root))
52
+
53
+
54
+ def list_shortcuts(
55
+ *,
56
+ steam_root: Path | None = None,
57
+ steam_id: str | None = None,
58
+ ) -> tuple[SteamProfile, tuple[ShortcutListing, ...]]:
59
+ """List non-Steam shortcuts from exactly one selected profile."""
60
+ installation = detect_steam(steam_root)
61
+ profile = select_profile(installation.steam_root, steam_id)
62
+ root = load_shortcuts(profile.shortcuts_path)
63
+ shortcuts = _shortcut_map(root)
64
+ listings = tuple(
65
+ _listing(index, entry)
66
+ for index, entry in sorted(shortcuts.items(), key=_shortcut_sort_key)
67
+ if isinstance(entry, dict)
68
+ )
69
+ return profile, listings
70
+
71
+
72
+ def preview_shortcut(
73
+ *,
74
+ name: str,
75
+ executable: Path,
76
+ start_dir: Path | None = None,
77
+ launch_options: str = "",
78
+ icon: Path | None = None,
79
+ tags: Iterable[str] = (),
80
+ steam_root: Path | None = None,
81
+ steam_id: str | None = None,
82
+ ) -> ShortcutPreview:
83
+ """Resolve and validate an add operation without changing Steam files."""
84
+ installation = detect_steam(steam_root)
85
+ ensure_steam_not_running()
86
+ profile = select_profile(installation.steam_root, steam_id)
87
+ request = ShortcutRequest(
88
+ name=name,
89
+ executable=executable,
90
+ start_dir=start_dir,
91
+ launch_options=launch_options,
92
+ icon=icon,
93
+ tags=tuple(tags),
94
+ )
95
+ plan = plan_shortcut_addition(load_shortcuts(profile.shortcuts_path), request)
96
+ return ShortcutPreview(steam_root=installation.steam_root, profile=profile, plan=plan)
97
+
98
+
99
+ def add_shortcut(
100
+ *,
101
+ name: str,
102
+ executable: Path,
103
+ start_dir: Path | None = None,
104
+ launch_options: str = "",
105
+ icon: Path | None = None,
106
+ tags: Iterable[str] = (),
107
+ steam_root: Path | None = None,
108
+ steam_id: str | None = None,
109
+ ) -> ShortcutResult:
110
+ """Safely add a non-Steam shortcut and return its verified result."""
111
+ tag_values = tuple(tags)
112
+ preview = preview_shortcut(
113
+ name=name,
114
+ executable=executable,
115
+ start_dir=start_dir,
116
+ launch_options=launch_options,
117
+ icon=icon,
118
+ tags=tag_values,
119
+ steam_root=steam_root,
120
+ steam_id=steam_id,
121
+ )
122
+ request = ShortcutRequest(
123
+ name=name,
124
+ executable=executable,
125
+ start_dir=start_dir,
126
+ launch_options=launch_options,
127
+ icon=icon,
128
+ tags=tag_values,
129
+ )
130
+ return add_shortcut_to_profile(
131
+ preview.profile.shortcuts_path,
132
+ preview.profile.profile_id,
133
+ request,
134
+ )
135
+
136
+
137
+ def _shortcut_map(root: VdfMap) -> dict[str, VdfValue]:
138
+ shortcuts = root["shortcuts"]
139
+ if not isinstance(shortcuts, dict):
140
+ raise ValueError("'shortcuts' must be a mapping")
141
+ return shortcuts
142
+
143
+
144
+ def _listing(index: str, entry: dict[str, VdfValue]) -> ShortcutListing:
145
+ name = entry.get("AppName", entry.get("appname", ""))
146
+ executable = entry.get("Exe", entry.get("exe", ""))
147
+ raw_app_id = entry.get("appid")
148
+ app_id = (
149
+ to_unsigned_int32(raw_app_id)
150
+ if isinstance(raw_app_id, int) and not isinstance(raw_app_id, bool)
151
+ else None
152
+ )
153
+ return ShortcutListing(
154
+ index=index,
155
+ name=name if isinstance(name, str) else "",
156
+ executable=_unquote(executable) if isinstance(executable, str) else "",
157
+ app_id=app_id,
158
+ )
159
+
160
+
161
+ def _shortcut_sort_key(item: tuple[str, VdfValue]) -> tuple[int, int | str]:
162
+ index, _ = item
163
+ return (0, int(index)) if index.isdecimal() else (1, index)
164
+
165
+
166
+ def _unquote(value: str) -> str:
167
+ return value.strip().removeprefix('"').removesuffix('"')