## Crafter.Debug

This app can be driven while it runs: call its commands, read and set its state, pause and step it, wait for conditions, read its log, take screenshots.

- Start its debug build in the background, since it does not exit: `crafter-build <debug flag> -r`. This project's notes above name the flag, usually `--debug-api`.
- Drive it with `./build/crafter-debug` from the project directory:
  - `ls --wait 60s` until it is listed; `status`, `cmds`, `help <command>`, `get '*'`
  - `call <command> key=value ...`, `set <path> <value>`
  - `pause --when '<condition>'` then `wait --paused`; `step 3`, `resume`
  - `wait '<condition>'`, `wait --frames 30`, `wait --event <Name>`
  - `trace <path> --frames 120`, `log --level warn`, `log --follow` (under Monitor)
  - `screenshot`: open the PNG it prints with Read
  - `quit` when done
- `./build/crafter-debug guide` is the full reference. Errors name the next step.
- Exit codes: 2 usage, 3 no instance, 4 app and client from different versions, 5 timed out, 6 the app answered an error.

Gotchas:
- Requests run when the app calls `Debug::Pump()`, once per frame. `status` shows when it last did.
- `pause` and `step` only hold what the app gates on `Debug::Advance()` or `Debug::Paused()`.
- Stopping the background `-r` task can leave the app running. Stop it with `./build/crafter-debug quit`, or `quit --force` if its loop is stuck.
- Run long `wait`s in the background, and chain short steps with `&&`.
- For breakpoints and memory, `./build/crafter-debug debugger` prints how to attach lldb or gdb inside the app's sandbox.
- To give the agent more to work with, register commands and watches in the app's debug-only code (`Debug::Command`, `Debug::Watch`, `Debug::Group`). Crafter.Debug's README shows how.