# 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 ` - `reset ` - `export [name-or-path]` - `import ` ### `profile` - `list` - `tree` - `create ` - `duplicate ` - `show ` - `export [name-or-path]` - `import ` - `env set ` - `env unset ` - `env list ` - `env clear ` - `set ` - `reset ` - `inherit ` - `clear-inherit ` - `delete ` ### `game` - `list [matcher]` - `show ` - `bind ` - `unbind ` - `rename ` - `note ` - `clear-note ` - `forget ` ### `notify` - `test` ### `completion` - `` prints the raw script - `install ` installs shell integration - `path ` 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.