73 lines
3.9 KiB
Markdown
73 lines
3.9 KiB
Markdown
# AGENTS.md (Codex CLI guidance)
|
||
|
||
This repository is a screen reader. Prioritize accessibility, correctness, and stability over “clever” changes.
|
||
|
||
## System interactions
|
||
- If a command requires `sudo`, stop and ask the user to run it (no password entry is possible from here).
|
||
|
||
## Build / run quick refs
|
||
- Local dev build + install: `./build-local.sh`
|
||
- Quick local sanity checks: `./test-local.sh`
|
||
- Clean local artifacts/install: `./clean-local.sh`
|
||
- Meson (manual):
|
||
- `meson setup _build --prefix=$HOME/.local`
|
||
- `meson compile -C _build`
|
||
- `meson install -C _build`
|
||
|
||
## Runtime target and testing rules
|
||
- Make source changes in this repo, not in `~/.local/lib/python*/site-packages/cthulhu/`, unless the user explicitly asks for an installed-package hotfix.
|
||
- If you confirm the active import comes from `~/.local/...`, that does **not** mean you should edit there. It means you should update the repo and then run `./build-local.sh` to replace the installed copy for testing.
|
||
- Default test/apply workflow for local Cthulhu fixes:
|
||
- edit repo files
|
||
- run `./build-local.sh`
|
||
- reproduce/test against the refreshed `~/.local` install
|
||
- If repo and installed behavior differ, prefer rebuilding with `./build-local.sh` over patching the installed package directly.
|
||
- Treat direct edits under `~/.local/.../cthulhu/` as an exception path that requires explicit user approval.
|
||
|
||
## Coding guidelines
|
||
- **When modifying existing code:** follow the surrounding code’s conventions.
|
||
- **When writing new code from scratch:** prefer
|
||
- variables: `camelCase`
|
||
- functions/methods: `snake_case`
|
||
- classes: `PascalCase`
|
||
- Keep changes clean and well-structured; avoid layering short-term workarounds when a focused fix is possible.
|
||
- Add debug logs where helpful for troubleshooting. When adding timestamps to logs, use: `"Message [timestamp]"` (message first).
|
||
|
||
## Accessibility requirements (high priority)
|
||
### General
|
||
- Screen-reader-first UX: assume non-visual navigation.
|
||
- No keyboard traps; Tab/Shift+Tab must move through all controls.
|
||
- Use clear, complete labels (e.g., “Confirm Password”, not “Confirm”).
|
||
- **No Speech-Dispatcher usage in GUI apps** (no `spd-say`); rely on the accessibility API.
|
||
|
||
### Python GTK (Gtk 3)
|
||
- Associate labels with controls (mnemonics + buddy widget):
|
||
- `label.set_use_underline(True)`
|
||
- `label.set_mnemonic_widget(entry)`
|
||
- For `Gtk.TextView`, call `set_accepts_tab(False)` so Tab moves focus.
|
||
- For custom widgets, set accessible name/role via ATK where applicable.
|
||
|
||
### PySide6 / Qt
|
||
- Set `setAccessibleName()` on all widgets.
|
||
- Associate labels via `setBuddy()`.
|
||
- Use `setAccessibleDescription()` when extra context is needed.
|
||
|
||
## Shell script rules
|
||
- **Bash variables must be `camelCase`** (except system env vars like `ACCESSIBILITY_ENABLED`).
|
||
- If you edit a `#!/usr/bin/env bash`, `#!/bin/bash`, or POSIX `sh` script, run `shellcheck` and fix issues.
|
||
- Avoid colorized output unless explicitly requested (accessibility-first; keep scripts simple).
|
||
|
||
## Plugins (Cthulhu)
|
||
- System plugins live in `src/cthulhu/plugins/`.
|
||
- Follow existing plugin patterns (keybinding registration, GTK dialog/window patterns, debug logging).
|
||
- Ensure plugin install integration is wired via Meson (`src/cthulhu/plugins/meson.build` + plugin subdir `meson.build`).
|
||
|
||
## Meson install reminder (important)
|
||
- If you add new Python modules under `src/cthulhu/`, update `src/cthulhu/meson.build` so they get installed (otherwise imports can fail after install).
|
||
- If you add a new plugin directory, update `src/cthulhu/plugins/meson.build` and add a `meson.build` in the plugin directory.
|
||
|
||
## Common Cthulhu agent mistakes
|
||
- Checking the import origin, seeing `~/.local/...`, and then editing the installed package instead of the repo.
|
||
- Forgetting that `./build-local.sh` is the normal way to apply repo changes into the installed copy for testing.
|
||
- Making repo fixes and then diagnosing the old installed copy without rebuilding.
|