gamewrap/PROJECT_MAP.md

PROJECT_MAP.md

Auto-generated project index. Update this file whenever you add, remove, or significantly change a file or feature.

Last updated: 2026-03-21 - reworked into a more operational map focused on edit paths, persistence contracts, and update triggers

---

🗺️ Project Overview

gamewrap is a Rust CLI for Linux/Steam users who want short Steam launch options while still applying MangoHud, GameMode, profile-based behavior, diagnostics, and shareable setup files. It uses clap for the CLI, TOML for persistence/share formats, and XDG config/state paths for local data.

---

🏗️ Architecture Summary

• Steam launch path: parse implicit Steam launch -> inspect real executable -> resolve defaults/profile/binding -> build env/wrapper plan -> exec target
• Management path: parse subcommand -> load config/state as needed -> mutate or render -> save TOML back to XDG paths
• Shell completion path: completion hook runs before normal CLI parsing and asks live config/state for dynamic candidates

Representative flow:

gamewrap %command% -> src/lib.rs -> src/cli.rs -> src/detect.rs -> src/profile.rs -> src/launch.rs -> src/env.rs -> exec

---

📁 File & Folder Map

Path	Role	Notes
Cargo.toml	Crate manifest	Dependency and package metadata; clap_complete uses dynamic completion support.
Cargo.lock	Lockfile	Pinned dependency graph.
README.md	User docs	Install, command examples, sharing, completion, Steam usage.
PROJECT_MAP.md	Persistent project index	This file. Keep concise and tactical.
docs/roadmap.md	Deferred planning	Future integrations, packaging direction, product scope.
src/main.rs	Binary entry point	Converts AppError into stderr + notifier + exit code.
src/lib.rs	Library entry point	Runs completion hook first, then normal CLI parse/dispatch.
src/cli.rs	Command surface and dispatch	Owns top-level commands, parsing, command execution, and many user-facing error paths.
src/color.rs	Terminal color helpers	Enables ANSI styling only when NO_COLOR is unset and stdout is a TTY.
src/completion.rs	Completion engine	Generates/install shell scripts and dynamic candidates for settings, profiles, and observed games.
src/config/mod.rs	Config/state I/O	XDG path discovery, TOML load/save, CLI rendering of config/profile views.
src/config/schema.rs	Persistent structs	Settings, ResolvedSettings, ProfileConfig, ConfigFile, ObservedGame, StateFile.
src/config/keys.rs	Setting mutation helpers	Friendly key parsing and value application/reset logic.
src/profile.rs	Resolution + validation	Resolves inherited profiles and validates parent chains/binding targets.
src/bindings.rs	Binding operations	Matching logic, set/remove binding, resolve profile for executable/observed game.
src/detect.rs	Executable detection	Pulls real game executable out of Steam/Proton wrapper shapes and records observed launches.
src/launch.rs	Launch planning/execution	Dependency checks, dry-run rendering, final command execution.
src/env.rs	Env shaping	Steam-context detection, host-library injection decisions, env var construction.
src/doctor.rs	Doctor rendering	Formats preflight results.
src/status.rs	Status rendering	Formats dependency/config/state summary.
src/help.rs	Long-form help text	Shared topic help and top-level examples.
src/error.rs	Error model	Exit-code-bearing error categories and constructors.
src/notify.rs	GUI failure notifier	zenity / kdialog / xmessage / notify-send selection and popup logic.
src/share.rs	Share/import formats	Resolved full-config and single-profile portable TOML formats.
tests/cli_matrix.rs	Integration CLI coverage	End-to-end command validation in isolated XDG temp envs.

Skip target/ and other generated artifacts when extending this map.

---

🧭 Hot Paths

Add or change a CLI command

• Edit: src/cli.rs
• Usually also update: src/help.rs, README.md, tests/cli_matrix.rs
• If command affects config/state formats: src/config/schema.rs, src/share.rs, this map

Change config keys or setting behavior

• Edit: src/config/keys.rs, src/config/schema.rs
• Usually also update: src/config/mod.rs, src/profile.rs, src/help.rs, completion candidates in src/completion.rs, tests

Change profile behavior

• Edit: src/profile.rs
• Usually also update: src/cli.rs, src/config/mod.rs, src/share.rs, tests

Change binding or game matching behavior

• Edit: src/bindings.rs, src/detect.rs
• Usually also update: src/cli.rs, src/completion.rs, tests

Change launch/runtime behavior

• Edit: src/launch.rs, src/env.rs
• Usually also update: src/doctor.rs, src/status.rs, help/docs, tests

Change shell completion behavior

• Edit: src/completion.rs
• Usually also update: src/cli.rs, src/help.rs, README.md, tests

Change import/export/share behavior

• Edit: src/share.rs
• Usually also update: src/cli.rs, README.md, src/help.rs, tests

---

🔑 Key Concepts & Domain Terms

• Defaults: global baseline settings from config
• Profile: reusable settings bundle; may inherit from another named profile
• Binding: matcher string mapping a known executable/path to a profile
• Observed game: recorded launch entry with executable, path, last launched profile, optional note/display name, launch count, and last launch timestamp
• Resolved settings: effective values after applying defaults + inheritance + explicit overrides
• Steam context: environment where implicit launch mode and GUI failure notifications are enabled
• Share format: portable resolved export file, distinct from the sparse internal config layout

---

🔗 Persistence Contracts

Internal local files

• Config path: ~/.config/gamewrap/config.toml
• State path: ~/.local/state/gamewrap/state.toml
• Config file is sparse/raw:
  • stores only explicit overrides
  • profiles may be empty and may inherit from parents
  • bindings are stored separately

Portable share files

• Full config export suffix: .gamewrap.toml
• Profile export suffix: .gamewrap-profile.toml
• Export commands write resolved values, not sparse internal overrides
• Profile import creates a standalone explicit profile with no inheritance
• Per-profile env overrides are stored as an optional env-vars map on profile settings and merge through inheritance; child keys override parent keys
• Pre/post launch hook commands are stored as optional string settings; pre-launch runs before exec, while post-launch is persisted/displayed but deferred until wrapped launching exists
• Config import accepts:
  • current resolved share format
  • legacy raw config format as fallback

---

🖥️ User-Facing Command Surface

Top-level commands

• help
• status
• doctor
• run
• dry-run
• last
• config
• profile
• game
• notify
• completion

config

• show
• edit
• set <setting> <value>
• reset <setting>
• export [name-or-path]
• import <name-or-path>

profile

• list
• tree
• create <name>
• duplicate <src> <dst>
• show <name>
• export <name> [name-or-path]
• import <name-or-path>
• env set <name> <key> <value>
• env unset <name> <key>
• env list <name>
• env clear <name>
• set <name> <setting> <value>
• reset <name> <setting>
• inherit <name> <parent>
• clear-inherit <name>
• delete <name>

game

• list [matcher]
• show <matcher>
• bind <matcher> <profile>
• unbind <matcher>
• rename <matcher> <name>
• note <matcher> <text...>
• clear-note <matcher>
• forget <matcher>

notify

• test

completion

• <shell> prints the raw script
• install <shell> installs shell integration
• path <shell> shows where the script/startup wiring lives

---

🧪 Test Coverage Map

• Unit tests live inline in several src/* modules
• Integration coverage lives in tests/cli_matrix.rs

If you change:

• command surface -> update tests/cli_matrix.rs
• share/import/export formats -> update tests/cli_matrix.rs and src/share.rs tests
• completion install/candidates -> update tests/cli_matrix.rs and src/completion.rs tests
• profile inheritance logic -> update src/profile.rs tests and related CLI matrix cases

---

🧩 Feature Areas & Ownership Map

• CLI / UX: src/cli.rs, src/help.rs, README.md
• Persistence: src/config/*, src/share.rs
• Profiles / inheritance: src/profile.rs
• Game observation / matching / bindings: src/detect.rs, src/bindings.rs
• Launch execution: src/launch.rs, src/env.rs
• Diagnostics: src/doctor.rs, src/status.rs
• Failure popup behavior: src/main.rs, src/notify.rs
• Completion UX: src/completion.rs

---

⚠️ Known Issues / Tech Debt

• README.md has a Quick Start numbering/order inconsistency and could use a cleanup pass.
• Completion still includes generic clap-level suggestions like --help in some contexts; dynamic candidates are layered on top, not full custom shell UX.
• Elvish completion install is not as automated as bash/zsh/fish/PowerShell.
• Project still has no Git repo/public release metadata/package workflow despite the roadmap discussing future distribution.

---

🔄 Update Triggers

Update this file when:

• a top-level command or subcommand is added/removed/renamed
• a persisted file path or format changes
• a new top-level source module is added
• a new major feature area appears
• the launch/completion/share architecture changes materially

Do not update this file for:

• tiny wording tweaks
• purely internal refactors that do not change ownership or edit paths
• dependency version bumps unless they change how the project is operated

---

📝 Change Log (agent session)

• [2026-03-21] Initial map created for the current gamewrap Rust CLI structure and feature set.
• [2026-03-21] Reworked the map into a more tactical index centered on hot paths, persistence contracts, command surface, and update triggers.
• [2026-05-31] Added TTY/NO_COLOR-aware ANSI output helpers for doctor and status rendering.
• [2026-05-31] Added game forget, config edit, profile list/tree improvements, and notify test commands.
• [2026-05-31] Added gamescope settings, launch wrapping, dependency diagnostics, completion candidates, and docs.
• [2026-05-31] Added observed-game display names, launch timestamps/counts, last, game rename, and fps-cap.
• [2026-05-31] Added per-profile env overrides, vkBasalt support, and Proton esync/fsync compatibility controls.
• [2026-05-31] Added pre-launch shell hooks plus persisted/dry-run/doctor visibility for deferred post-launch hooks.