Removed ripgrep call to cut down on dependencies.
This commit is contained in:
Storm Dragon
@@ -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.
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user