Codex skill for development added. Tested by using it to set up Play Palace.
This commit is contained in:
Storm Dragon
76
.codex/skills/linux-game-manager-dev/references/core-map.md
Normal file
76
.codex/skills/linux-game-manager-dev/references/core-map.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# Linux Game Manager Core Map
|
||||
|
||||
Last refreshed: 2026-02-21
|
||||
|
||||
## Top-Level Structure
|
||||
|
||||
- `linux-game-manager.sh`: Main orchestrator, UI wrappers, CLI option handling, install/remove/update flows, cache and settings behavior.
|
||||
- `.install/`: Per-game installer scripts sourced by `game_installer`.
|
||||
- `.launch/`: Per-game launch scripts (`.game`) and runnable entries (`.sh`, usually symlinks).
|
||||
- `.update/`: Optional per-game update scripts expected to define `run_update()`.
|
||||
- `speech/speak_window_title.sh`: Accessibility helper for announcing focused window titles.
|
||||
- `README.md`: Project summary and high-level behavior notes.
|
||||
- `.files/`: Game-specific auxiliary assets/scripts used by some installers or launchers.
|
||||
|
||||
## Catalog Snapshot
|
||||
|
||||
- Installers: 38 (`.install/*.sh`)
|
||||
- Launcher definitions: 38 (`.launch/*.game`)
|
||||
- Launcher runnable entries: 26 (`.launch/*.sh`, both symlinks and files)
|
||||
- Update scripts: 5 (`.update/*.sh`)
|
||||
|
||||
Regenerate this snapshot with:
|
||||
|
||||
```bash
|
||||
python3 .codex/skills/linux-game-manager-dev/scripts/audit_game_catalog.py
|
||||
```
|
||||
|
||||
## Main Runtime Flows
|
||||
|
||||
1. **Install flow**
|
||||
- `game_installer` builds menu from `.install/*.sh`.
|
||||
- Selected installer is sourced in the current shell.
|
||||
- If `.launch/<game>.game` exists and `.launch/<game>.sh` does not, the manager creates a symlink.
|
||||
|
||||
2. **Launch flow**
|
||||
- `game_launcher` enumerates `.launch/*.sh` entries.
|
||||
- Entries with first line `#//` are skipped.
|
||||
- Selected launcher is sourced/executed.
|
||||
|
||||
3. **Removal flow**
|
||||
- `game_removal` resolves launcher entry to real script.
|
||||
- It extracts the first `installPath`-containing line from launcher script to infer directory to remove.
|
||||
- If no `installPath` reference is found, only launcher entry is removed.
|
||||
|
||||
4. **Update flow**
|
||||
- `game_update` lists `.update/*.sh`.
|
||||
- Selected updater is sourced.
|
||||
- `run_update()` is called and must exist.
|
||||
|
||||
## CLI Surface
|
||||
|
||||
- `-i`: install game
|
||||
- `-r`: remove game
|
||||
- `-u`: update game
|
||||
- `-t`: show number of available games
|
||||
- `-C`: clear cache
|
||||
- `-D`: create desktop launcher
|
||||
- `-L`: show license
|
||||
- `-h`: show help
|
||||
- `-N`: enable no-cache mode
|
||||
- `-R`: force redownload mode
|
||||
|
||||
## Config and State
|
||||
|
||||
- Cache: `${XDG_CACHE_HOME:-$HOME/.cache}/linux-game-manager`
|
||||
- Config base: `${XDG_CONFIG_HOME:-$HOME/.config}/storm-games/linux-game-manager`
|
||||
- Settings overrides: `settings.conf` in config base
|
||||
- Default install root: `${HOME}/.local/games`
|
||||
|
||||
## Contributor Pitfalls
|
||||
|
||||
- Mismatched `.install/<Game>.sh` vs `.launch/<Game>.game` names create orphaned or invisible entries.
|
||||
- Missing `installPath` reference in launcher prevents full uninstall.
|
||||
- Missing `run_update()` in `.update` scripts breaks update flow.
|
||||
- Bypassing shared download helpers risks cache and validation regressions.
|
||||
- For `uv`-based Python games that use `accessible-output2`, include a host copy of `libspeechd.so.2` and export `LD_LIBRARY_PATH` from the launcher to avoid distro packaging differences.
|
||||
@@ -0,0 +1,134 @@
|
||||
# Game Extension Workflow
|
||||
|
||||
Use this workflow whenever adding, renaming, removing, or substantially changing a game.
|
||||
|
||||
## Add a New Game
|
||||
|
||||
1. Create installer script:
|
||||
- Path: `.install/<Game Name>.sh`
|
||||
- Keep first line active (do not start with `#//`).
|
||||
- Reuse manager helpers (`check_architecture`, `check_dependencies`, `download`, `download_named`, `get_installer`, `ui_*`).
|
||||
- Install into a deterministic path under `${installPath}`.
|
||||
|
||||
2. Create launcher definition:
|
||||
- Path: `.launch/<Game Name>.game`
|
||||
- Keep base filename identical to installer (`<Game Name>`).
|
||||
- Include an explicit install-path variable based on `installPath`, for example:
|
||||
|
||||
```bash
|
||||
gamePath="${installPath}/MyGame"
|
||||
```
|
||||
|
||||
- Run the game from that path.
|
||||
|
||||
3. Optional update script:
|
||||
- Path: `.update/<Game Name>.sh`
|
||||
- Implement `run_update()` (required by update flow).
|
||||
|
||||
4. Let installer create runnable launcher entry:
|
||||
- The manager auto-creates `.launch/<Game Name>.sh` symlink when installer completes and `.game` exists.
|
||||
|
||||
## Rename a Game Safely
|
||||
|
||||
1. Rename `.install/<Old>.sh` to `.install/<New>.sh`.
|
||||
2. Rename `.launch/<Old>.game` to `.launch/<New>.game`.
|
||||
3. Rename `.update/<Old>.sh` if present.
|
||||
4. Remove stale `.launch/<Old>.sh` if still present.
|
||||
5. Re-run catalog audit and manual checks.
|
||||
|
||||
## Remove a Game From Repo
|
||||
|
||||
1. Delete `.install/<Game>.sh`.
|
||||
2. Delete `.launch/<Game>.game`.
|
||||
3. Delete `.launch/<Game>.sh` if tracked.
|
||||
4. Delete `.update/<Game>.sh` if present.
|
||||
5. Run catalog audit to confirm no orphan entries remain.
|
||||
|
||||
## Disable Policy (Important)
|
||||
|
||||
When a request says "disable <game>" without more detail:
|
||||
|
||||
1. Default behavior: disable installs only.
|
||||
- Add `#//` to first line of `.install/<Game Name>.sh`.
|
||||
- Do not disable `.launch/<Game Name>.game` by default.
|
||||
- This preserves playability for users who already have the game installed.
|
||||
|
||||
2. If user explicitly requests complete disable:
|
||||
- Add `#//` to first line of both:
|
||||
- `.install/<Game Name>.sh`
|
||||
- `.launch/<Game Name>.game`
|
||||
|
||||
3. If wording is ambiguous but could imply full disable/removal:
|
||||
- Ask a short clarification question before changing launcher/removal behavior.
|
||||
|
||||
## Manual Validation Checklist
|
||||
|
||||
1. Run installer flow:
|
||||
|
||||
```bash
|
||||
./linux-game-manager.sh -i
|
||||
```
|
||||
|
||||
2. Confirm launcher files exist:
|
||||
|
||||
```bash
|
||||
ls ".launch/<Game Name>.game" ".launch/<Game Name>.sh"
|
||||
```
|
||||
|
||||
3. Run launcher flow:
|
||||
|
||||
```bash
|
||||
./linux-game-manager.sh
|
||||
```
|
||||
|
||||
4. Run removal flow:
|
||||
|
||||
```bash
|
||||
./linux-game-manager.sh -r
|
||||
```
|
||||
|
||||
5. If updater exists, run update flow:
|
||||
|
||||
```bash
|
||||
./linux-game-manager.sh -u
|
||||
```
|
||||
|
||||
6. Run consistency audit:
|
||||
|
||||
```bash
|
||||
python3 .codex/skills/linux-game-manager-dev/scripts/audit_game_catalog.py
|
||||
```
|
||||
|
||||
## Script Authoring Rules
|
||||
|
||||
- Use camelCase variable names.
|
||||
- Use snake_case for function names.
|
||||
- Keep scripts robust when sourced in the manager shell.
|
||||
- Avoid introducing unnecessary colorized output.
|
||||
- For edited bash scripts, run shellcheck and fix all errors.
|
||||
- If `shellcheck` is not installed, prompt the user to install it first (see `references/tooling-prereqs.md`).
|
||||
|
||||
## Pattern: uv + Speech Dispatcher Host Libraries
|
||||
|
||||
Use this pattern for Python games installed with `uv` when runtime speech support depends on system `libspeechd`.
|
||||
|
||||
1. In installer script:
|
||||
- Check dependencies: `git` and `uv`.
|
||||
- Clone game repository into `${installPath}/<GameRepoDir>`.
|
||||
- Run `uv sync` in the project directory that contains `pyproject.toml`.
|
||||
- Locate `libspeechd.so.2` from host system using:
|
||||
- `ldconfig -p` when available.
|
||||
- Fallback paths for common distros:
|
||||
- `/usr/lib/libspeechd.so.2` (Arch-style)
|
||||
- `/usr/lib/x86_64-linux-gnu/libspeechd.so.2` (Debian/Ubuntu-style)
|
||||
- `/usr/lib64/libspeechd.so.2` and related `/lib*` fallbacks
|
||||
- Copy resolved library into a game-local directory such as:
|
||||
- `${installPath}/<GameRepoDir>/<RuntimePath>/.host-libs/libspeechd.so.2`
|
||||
- Fail with a clear message if library is not found.
|
||||
|
||||
2. In launcher script:
|
||||
- Export `LD_LIBRARY_PATH` with the game-local `.host-libs` directory prepended.
|
||||
- Launch via `uv run ...` from the same directory used for `uv sync`.
|
||||
|
||||
3. Removal safety:
|
||||
- Ensure first `installPath` line in launcher points to a path that lets `game_removal` infer the game root correctly.
|
||||
@@ -0,0 +1,53 @@
|
||||
# Skill Maintenance (Critical)
|
||||
|
||||
This skill is only trustworthy if it is refreshed immediately after behavior changes.
|
||||
|
||||
## Mandatory Refresh Triggers
|
||||
|
||||
Run this maintenance workflow whenever any of these change:
|
||||
|
||||
- `linux-game-manager.sh`
|
||||
- Anything in `.install/`
|
||||
- Anything in `.launch/`
|
||||
- Anything in `.update/`
|
||||
- Anything in `speech/`
|
||||
- `README.md`
|
||||
- Any game lifecycle contract (install path usage, symlink behavior, update function contracts, CLI flags)
|
||||
|
||||
## Refresh Workflow
|
||||
|
||||
1. Run catalog audit and capture output:
|
||||
|
||||
```bash
|
||||
python3 .codex/skills/linux-game-manager-dev/scripts/audit_game_catalog.py
|
||||
```
|
||||
|
||||
2. Re-check core flow definitions in `linux-game-manager.sh`:
|
||||
|
||||
```bash
|
||||
rg -n "game_installer|game_launcher|game_removal|game_update|getopts|help\\(" linux-game-manager.sh
|
||||
```
|
||||
|
||||
3. Update skill references:
|
||||
- Update `references/core-map.md` catalog snapshot if counts changed.
|
||||
- Update `references/core-map.md` flow descriptions if behavior changed.
|
||||
- Update `references/game-extension.md` if onboarding or naming rules changed.
|
||||
- Update this file if refresh triggers or process changed.
|
||||
|
||||
4. Validate the skill structure:
|
||||
|
||||
```bash
|
||||
python3 /home/storm/.codex/skills/.system/skill-creator/scripts/quick_validate.py .codex/skills/linux-game-manager-dev
|
||||
```
|
||||
|
||||
5. If any bash scripts changed, run shellcheck on edited files and fix all errors.
|
||||
- If `shellcheck` is missing, pause and prompt the user to install it using `references/tooling-prereqs.md`.
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
Do not consider maintenance complete until all are true:
|
||||
|
||||
1. Catalog audit shows no critical mismatches, and any warnings are reviewed.
|
||||
2. All changed behavior is reflected in skill reference files.
|
||||
3. Skill passes `quick_validate.py`.
|
||||
4. Any edited bash scripts are shellcheck-clean.
|
||||
@@ -0,0 +1,38 @@
|
||||
# Tooling Prerequisites
|
||||
|
||||
## Required Tool for Bash Changes
|
||||
|
||||
- `shellcheck` is mandatory whenever editing any bash/sh file in this repository.
|
||||
- If `shellcheck` is not available, prompt the user to install it before continuing validation.
|
||||
|
||||
Check availability:
|
||||
|
||||
```bash
|
||||
command -v shellcheck
|
||||
```
|
||||
|
||||
## Prompt Template
|
||||
|
||||
Use this exact style when missing:
|
||||
|
||||
`shellcheck is required for bash/sh edits in linux-game-manager. Please install it, then I will continue validation.`
|
||||
|
||||
## Install Commands by Common Distro Family
|
||||
|
||||
- Arch/Manjaro:
|
||||
- `sudo pacman -S shellcheck`
|
||||
- Debian/Ubuntu/Linux Mint/Pop!_OS:
|
||||
- `sudo apt update && sudo apt install -y shellcheck`
|
||||
- Fedora/RHEL/CentOS Stream:
|
||||
- `sudo dnf install -y ShellCheck`
|
||||
- openSUSE:
|
||||
- `sudo zypper install -y ShellCheck`
|
||||
- Alpine:
|
||||
- `sudo apk add shellcheck`
|
||||
|
||||
If distro is unknown, ask the user what distribution they are on and provide the matching package command.
|
||||
|
||||
## Notes for LGM Collaboration
|
||||
|
||||
- Do not skip shellcheck for “small” bash changes.
|
||||
- Fix all shellcheck errors; warnings may be suppressed only when required by sourced-global patterns and with a short comment.
|
||||
Reference in New Issue
Block a user