From 7ec9ef3b8707c9aaf8a2a8d7cc7cd564587a650d Mon Sep 17 00:00:00 2001 From: Storm Dragon Date: Thu, 20 Aug 2026 22:15:55 -0400 Subject: [PATCH] Removed ripgrep call to cut down on dependencies. --- AGENTS.md | 105 +++++++++++++++++++++++++++++++++++++++++++ audiogame-manager.sh | 4 +- 2 files changed, 107 insertions(+), 2 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..863e7a0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,105 @@ +# AGENTS.md + +## Project Purpose + +Audiogame Manager installs and launches Windows audio games under Wine or UMU/Proton on Linux. Contributions must preserve keyboard and screen-reader accessibility in both console `dialog` and graphical `yad` modes. + +## Repository Map + +- `audiogame-manager.sh`: main entry point, game menu, launcher, removal flow, and shared runtime state. +- `.install/`: one sourced Bash installer per game. The filename, minus `.sh`, is the game name shown in the install menu. +- `.includes/`: shared bottle, UMU, download, dialog, desktop, help, update, and URL helpers. +- `.includes/ipfs.sh`: centralized IPFS URLs for core files and games. +- `game-scripts/`: scripts installed or used by particular games after installation. +- `speech/`: speech-related helper and setup scripts. +- `wine/`: distribution-specific dependency installers and Wine utilities. +- `tests/`: isolated shell regression tests with mocked external programs. + +## Runtime Architecture + +- This is a Bash project, not a POSIX `sh` project. Arrays, associative arrays, `mapfile`, `[[ ... ]]`, and Bash parameter expansion are used intentionally. +- Installer files in `.install/` are sourced by the main process. They share functions and exported state from `audiogame-manager.sh` and `.includes/`; they are not independent programs. +- Common installer state includes `game`, `cache`, `WINEPREFIX`, `WINEARCH`, `winetricksSettings`, and helper functions such as `download`, `install_wine_bottle`, `install_proton_bottle`, `install_with_progress`, `add_launcher`, and `add_umu_launcher`. +- The launcher configuration is pipe-delimited. Keep its field order compatible with `create_game_array()` and `process_launcher_flags()`. +- Native Wine and UMU/Proton are separate backends. Use the helpers for the selected backend; do not mix their bottle paths, environment setup, launcher functions, or shutdown functions. +- The main script performs dependency checks, bottle setup, update checks, and other startup work before command dispatch. Do not source it casually in tests. Source the smallest `.includes/` file needed and mock its external commands. + +## Game Installer Conventions + +- Name a new installer `.install/Game Name.sh`; that filename becomes the menu label. +- A first line beginning with `#//` hides an installer from the menu. Preserve this convention when editing disabled installers. +- Quote paths and expansions, especially game names and Windows paths containing spaces. +- Use `download` so caching, progress reporting, retries, and validation remain consistent. +- Use `install_with_progress` for archive extraction or copies that could otherwise prompt invisibly. Extraction must be non-interactive and safe to repeat. +- Use `install_wine_bottle` plus `add_launcher` for the Wine backend. +- Use `install_proton_bottle`, the UMU helpers, and `add_umu_launcher` for the UMU backend. +- After installation, verify the expected executable exists before recording a launcher when failure would otherwise produce a broken menu entry. +- Set game-specific environment or winetricks values in the installer rather than changing global defaults for one game. +- Prefer idempotent installation steps. Re-running an installer should not hang on overwrite prompts or silently corrupt an existing bottle. +- Do not delete a shared Wine or Proton bottle to remove one game. Removal code must target only the selected game's files and launcher entry. + +## Portability and Dependencies + +- Contributors and coding agents may use any locally installed tools, including ripgrep (`rg`), while searching, reviewing, testing, or editing the repository. This restriction applies only to commands invoked by scripts shipped to users. +- Keep commands used by shipped scripts portable. Do not make runtime code depend on ripgrep or other modern command-line tools that are not commonly installed by default when classic Unix tools can provide the required behavior. +- Prefer broadly available classic Unix tools such as `grep`, `sed`, `awk`, and `find` when they provide the required behavior. +- A nonstandard runtime dependency is acceptable when there is no practical portable alternative, but it must be declared and checked rather than assumed. +- Add every new runtime dependency to `.includes/checkup.sh`, including its `packageList` entry so `audiogame-manager.sh -P` reports it. Update the relevant distribution-specific dependency scripts under `wine/` when they manage packages for that platform. +- If Audiogame Manager cannot perform its basic startup or core functions without a dependency, also add it to the startup checks in `check_requirements()` alongside critical commands such as `sox` and `dialog`. +- Do not assume a developer's interactive shell aliases, local utilities, desktop session, or current working directory are available. +- Resolve repository files relative to `scriptDir` or `BASH_SOURCE`, as appropriate. +- Do not add compatibility fallbacks or legacy paths unless they are an explicit requirement. + +## Shell Style + +- Follow the surrounding file's style and keep edits narrowly scoped. +- For new code, use camelCase variables and snake_case functions. Use PascalCase only for class-like concepts if any are introduced. +- Quote variable expansions unless intentional splitting or pattern matching is required. +- Prefer arrays for argument lists; do not construct commands in strings and evaluate them. +- Treat sourced shared globals deliberately. Add a focused ShellCheck suppression with a reason when a value is populated by the caller; do not broadly silence actionable warnings. +- Logging timestamps follow the message: `message [date]`. +- Do not add colored output unless requested. + +## Accessibility and Interaction + +- Screen-reader and keyboard users are first-class users. +- Use the `agm_*` wrappers from `.includes/dialog-interface.sh` instead of invoking `dialog` or `yad` directly. Changes must continue to work in both interfaces. +- Keep every workflow operable without a mouse. Do not introduce keyboard traps or communicate state only through color, sound, or visual layout. +- Do not use `spd-say` or direct Speech Dispatcher calls in graphical interfaces. Expose information through accessible controls and the existing dialog wrappers. +- Avoid commands that can stop at an invisible prompt behind a progress box. Supply non-interactive flags and handle failures explicitly. +- When changing accessibility behavior, verify the exact affected console and GUI workflow when those environments are available. Automated shell checks do not prove live screen-reader behavior. + +## Downloads, URLs, and External State + +- Treat remote URLs, archive layouts, executable names, and installer behavior as changeable external state. Verify them when working on a download or installer rather than relying on an old report. +- Keep reusable IPFS references centralized in `.includes/ipfs.sh` and preserve their explicit `filename` query when the cache filename depends on it. +- Never include credentials, private tokens, personal usernames, or live user paths in code, fixtures, logs, or examples. +- Do not run destructive installer or removal tests against the real home directory, Wine prefixes, or game data. + +## Testing and Verification + +- For every edited Bash or `.sh` file, run: + + ```bash + bash -n path/to/file.sh + shellcheck path/to/file.sh + ``` + +- Fix real ShellCheck findings. A narrow suppression is acceptable for intentionally sourced globals or dynamic source paths when it includes a reason. +- Run the smallest relevant test under `tests/`. Tests must use a temporary directory, replace external programs with stubs, and avoid network, GUI, Wine, and real user-state changes. +- For UMU helper changes, run: + + ```bash + bash tests/umu_backend_tests.sh + ``` + +- For changes spanning many shell files, syntax-check every changed shell file rather than assuming one successful check covers sourced code. +- Before handing work back, run `git diff --check` and inspect `git status --short --untracked-files=all` plus the final diff. +- Distinguish automated verification from live acceptance. Installer, Wine, audio, focus, controller, and screen-reader behavior may still require a real installation or launch test. + +## Repository Hygiene + +- Preserve unrelated tracked and untracked work. Do not reset, clean, overwrite, or incorporate files outside the requested scope. +- Do not edit generated caches, Wine prefixes, downloaded game data, or logs as source changes. +- Keep contributor changes reviewable; avoid unrelated formatting or refactors in installer fixes. +- Do not commit, merge, push, or alter remote state unless explicitly requested. diff --git a/audiogame-manager.sh b/audiogame-manager.sh index 1359236..bd9c014 100755 --- a/audiogame-manager.sh +++ b/audiogame-manager.sh @@ -33,7 +33,7 @@ start_nvda2speechd() { if [[ "$nvda2speechdStarted" == "true" ]]; then return fi - if ! ss -ltnp | rg 3457 | grep -q 'cthulhu'; then + if ! ss -ltnp | grep 3457 | grep -q 'cthulhu'; then if [[ -x "${XDG_DATA_HOME:-$HOME/.local/share}/audiogame-manager/nvda2speechd" ]]; then local translateSetting="${TRANSLATE:-unset}" local translateFromSetting="${TRANSLATE_FROM:-unset}" @@ -344,7 +344,7 @@ EOF echo "Set Microsoft Mike as default voice for wine64" # Setup nvda2speechd for accessibility if needed - if ! ss -ltnp | rg 3457 | grep -q 'cthulhu'; then + if ! ss -ltnp | grep 3457 | grep -q 'cthulhu'; then echo "# Setting up accessibility support..." download "${nvda2speechdBinary}" if [[ ! -f "${XDG_DATA_HOME:-$HOME/.local/share}/audiogame-manager/nvda2speechd" ]]; then