Crafter.Debug/README.md

# Crafter.Debug

Runtime debugging for AI agents, and for people. An app built with Crafter.Debug can be inspected and driven while it runs. From a shell, `crafter-debug` can:
- call the commands the app registers;
- read and set its watched state;
- pause it, step it, and pause it when a condition holds;
- wait for conditions, frames or events;
- trace values over frames;
- read its log;
- take screenshots.

Breakpoints and memory stay with a debugger; `crafter-debug debugger` prints how to attach one.

```console
$ crafter-build --debug-api -r &              # the app's debug build, in the background
$ ./build/crafter-debug ls --wait 60s
game  id 4f1c09a2b7e3d851  pid 3 (sandbox 48211)  up 4s  port 41207
$ ./build/crafter-debug call Lobby_Start && ./build/crafter-debug wait --frames 30
frame 342
$ ./build/crafter-debug pause --when 'fort1.core.hp <= 0' && ./build/crafter-debug call Player_Fire
$ ./build/crafter-debug wait --paused
paused at frame 1840: 'fort1.core.hp <= 0' became true
$ ./build/crafter-debug log --since-frame 1790 --level warn
   1838  WARN   physics    brace 17 strain 4.2 > limit  Forts3D-Brace.cpp:212
   1839  CHECK  physics    body 9 has mass -0  (x3)  Forts3D-Physics.cpp:88
$ ./build/crafter-debug screenshot
/home/me/game/build/crafter-debug-shots/game-1793488099646.png (2215871 bytes)
```

## How it fits together

| Piece | What it is |
|---|---|
| **The library**, `Crafter.Debug` | Linked into the app's debug builds only. A `Debug::Session` serves requests on 127.0.0.1 over QUIC, with a random port and a token, and runs the ones that touch the app on the app's own thread, between frames, in `Debug::Pump()`. |
| **The client**, `crafter-debug` | Built in the same pass as the app, from the same sources. The launcher `build/crafter-debug` runs it inside the CrafterBuild Flatpak sandbox it was built for. Nothing the Flatpak compiles runs on the host. |
| **Discovery** | Each running app writes `$HOME/.cache/crafter-debug/instances/<id>.json` (its user's only) and holds a lock while it lives. The client finds apps there, across Flatpak sandboxes, and forgets the ones that died. |
| **The build helper**, `Crafter.Debug.Build` | Loaded into a consumer's `project.cpp` by `#pragma crafter dependency`. It adds the library under the consumer's own debug flag and writes the launcher. |

## Adding it to a project

**1. In `project.cpp`**, load the helper and call `Debug::Use` with your own flag:

```cpp
import std;
import Crafter.Build;
#pragma crafter dependency "https://forgejo.catcrafts.net/Catcrafts/Crafter.Debug.git" project "tooling/project.cpp"
import Crafter.Debug.Build;
using namespace Crafter;

extern "C" Configuration CrafterBuildProject(std::span<const std::string_view> args) {
    Configuration cfg;
    // ...
    const ArgQuery opts = ApplyStandardArgs(cfg, args);
    std::vector<std::string> depArgs;                     // your args minus your own flags
    for (const std::string_view arg : args) {
        if (arg != "--debug-api") depArgs.emplace_back(arg);
    }
    // ...give depArgs to every other dependency too...
    Debug::Use(cfg, { .enabled = opts.Has("--debug-api"), .flag = "--debug-api",
                      .define = "MYAPP_DEBUG_API", .args = depArgs });
    // ...
}
```

**What `Use` does with the flag:**
- **Flag on, native Linux target:** it adds the define and the library, from the checkout the pragma names, and writes `build/crafter-debug`.
- **Otherwise:** it adds nothing, and release builds never link Crafter.Debug. Until a debug build has run, `build/crafter-debug` is a stub that says to build one.

A dependency that two paths in the build graph share must get the **same arg list on both**. Otherwise crafter-build refuses the graph with "module … built twice". Build one `depArgs` and give it to every dependency, as above.

**2. In `main`**, start a session and pump it once per frame. Gate the parts the agent should be able to pause:

```cpp
import MyApp.DebugShim;                                   // see "Without #ifdefs" below
ThreadPool::Start();                                      // the session's transport runs on the pool
#ifdef MYAPP_DEBUG_API
    Debug::Session debug({ .name = "MyApp" });
    MyApp::RegisterDebug();                               // your commands and watches
#endif
while (running && !Debug::QuitRequested()) {
    Debug::Pump();
    while (acc >= dt && Debug::Advance()) { sim.Tick(); acc -= dt; }
    render();
}
```

The `Session` must be destroyed before `main` returns and before `ThreadPool::Stop()`, because msquic waits for open connections at exit. A stack object in `main`, as above, does that.

**3. Register what the agent needs** in debug-only source files, which `project.cpp` adds only under the flag. See "The app side" below.

**4. For agents**, Crafter.Build merges Crafter.Debug's notes into your `AGENTS.md`. Check three things:
- **Your project needs an `AGENTS.template.md`.** Without one, crafter-build writes no `AGENTS.md`.
- **Name your debug flag in it.** The merged notes say "build with the project's debug flag", and only you know which flag that is.
- **If the repository has a `CLAUDE.md`, put `@AGENTS.md` in it.** Claude Code ignores `AGENTS.md` whenever a `CLAUDE.md` applies.

Optionally, allow `Bash(./build/crafter-debug *)` in `.claude/settings.json`.

**Working on Crafter.Debug itself next to a consumer:** point the pragma at your checkout:
- **A local path,** `#pragma crafter dependency "../Crafter.Debug" project "tooling/project.cpp"`, uses the working tree.
- **A file URL,** `"file:///…/Crafter.Debug"`, is a git source, so it uses the committed state.

Pragmas are read as plain text, so neither `#if` nor a flag can switch them.

## The app side

Everything is in `import Crafter.Debug;`, namespace `Crafter::Debug`.

### Commands

```cpp
struct AimArgs {
    Debug::Required<std::int32_t> slot;      // must be passed
    float yaw = 0;                           // optional; the default shows in `help`
    float pitch = 0;
};
Debug::Command("Player_SetAim", "Aim the slot's turret, in degrees.",
    [](const AimArgs& a) -> Debug::Result<> {
        Game* g = CurrentGame();
        if (!g) return Debug::Error{ "InvalidScene", "not in a game; call Lobby_Start first" };
        g->Aim(*a.slot, a.yaw, a.pitch);
        return {};
    });
```

**Arguments:**
- A handler takes nothing, or one argument type. That is usually an aggregate, whose fields are found by reflection, so no serialization code is written; `Debug::Value` gives raw JSON.
- Fields a call leaves out keep their default member initializers.
- A call with mistakes is answered with every one of them, each with its path and the likely intended name, and never reaches the handler: `slot: missing, and this field is required; yw: unknown field; did you mean 'yaw'?`.

**Results:** a handler returns `void`, any value with a codec, `Debug::Result<T>`, or `Debug::Async<T>`.
- `Debug::Result<T>` is a value or a `Debug::Error{code, message}`. Write the message for the agent: what went wrong and the next step.
- `Debug::Async<T>` is for results that take frames, such as a GPU readback. Its poller runs once per `Pump` until it yields, and the caller simply waits:

```cpp
Debug::Command("Sim_StateHash", "Hash of the GPU sim state.", []() -> Debug::Async<StateHash> {
    Physics::RequestCapture();
    return Debug::Async<StateHash>([]() -> std::optional<StateHash> {
        if (!Physics::CaptureReady()) return std::nullopt;
        return HashCapture();
    });
});
```

A handler that throws is answered with an `Exception` error. The exception does not unwind into the frame loop.

### Watches and samples

```cpp
Debug::Watch("physics.gravity", Physics::gravity, { .min = -50, .max = 0, .help = "m/s^2" });   // read and write
Debug::Watch("scene", [] { return SceneName(); });                                               // read only
Debug::Watch("lives", [] { return lives; }, [](const std::int32_t& v) -> Debug::Result<> {       // through a setter
    if (v < 0) return Debug::Error{ "Negative", "lives cannot be negative" };
    lives = v;
    return {};
});
Debug::Sample("xpbd.residual", residual);    // from hot code, any thread; keeps a history for `trace --history`
```

**Paths read into values:**
- `get bodies[3].pos.y` reads the watch `bodies`.
- `set fort1.core.pos.x 5` reads `fort1.core.pos`, replaces `x`, and writes the whole value back.

**Where they run:** getters, setters and handlers are only ever called on the thread that calls `Pump`, so they read app state without locking. Registering and unregistering are safe from any thread.

### Groups

Registrations that end with their owner, under a prefix:

```cpp
class Fort {
    Core core;
    Debug::Group debug;
public:
    explicit Fort(std::int32_t slot) : debug(std::format("fort{}", slot)) {
        debug.Watch("core.hp", core.hp);
        debug.Command("Explode", "Blow it up.", [this] { core.Explode(); });
    }
};
```

A `Group` can't be copied or moved, so neither can a class that holds one. Its watches refer to the members they were given, and a move would leave them pointing at the old object. Keep such objects in place: `std::unique_ptr`, `std::deque` or `std::list`, not `std::vector`.

### The timeline

```cpp
Debug::Log("net", "peer {} joined slot {}", peerId, slot);        // also LogWarn, LogError
Debug::Emit("MatchEnded", MatchEnded{ .winnerSlot = 1 });          // `wait --event MatchEnded`
if (!Debug::Check(mass > 0, "physics", "body {} has mass {}", id, mass)) return;   // a soft assert
```

**One timeline:** every entry carries the frame and the source location, next to the agent's own actions. The format strings are checked at compile time.

**`Check`:**
- It returns its condition, and only formats the message when the condition fails.
- A check that fails every frame is counted every time, but its entries are thinned out, so it cannot flood the log.
- `pause --on-check` pauses the app within the frame of the next failure; `--trap` also stops an attached debugger there.

**Without `#ifdef`s:** the frame-loop and timeline calls can be left in release code. Wrap them in a small module of your own that forwards to Crafter.Debug in debug builds and does nothing otherwise. It is one of your own sources, so your define reaches it:

```cpp
export module MyApp.DebugShim;
import std;
#ifdef MYAPP_DEBUG_API
export import Crafter.Debug;
#else
export namespace Crafter::Debug {
    inline void Pump() {}
    inline bool Advance() { return true; }
    inline bool Paused() { return false; }
    inline std::uint32_t TakeSteps() { return 0; }
    inline bool QuitRequested() { return false; }
    template<class... A> void Log(A&&...) {}
    template<class... A> void LogWarn(A&&...) {}
    template<class... A> void LogError(A&&...) {}
    template<class... A> bool Check(bool ok, A&&...) { return ok; }
    template<class... A> void Emit(A&&...) {}
    template<class T> void Sample(std::string_view, const T&) {}
}
#endif
```

### Pause and step

Pausing holds only what the app gates. Rendering and `Pump` keep running, so the agent can still read state, take screenshots and step.

```cpp
// A frame loop:
while (acc >= dt && Debug::Advance()) { sim.Tick(); acc -= dt; }      // false while paused, true once per step

// A fixed-step loop that must not spiral when resumed:
if (Debug::Paused()) {
    for (std::uint32_t n = Debug::TakeSteps(); n > 0; --n) sim.Tick();
    acc = 0;
} else {
    while (acc >= dt) { sim.Tick(); acc -= dt; }
}
```

Pausing an app that never calls `Advance` or `Paused` is refused, rather than silently doing nothing.

### Screenshots

`Debug::SetCapture` tells the session where PNGs come from. It is called on the `Pump` thread and returns the bytes when they are ready. With Crafter.Graphics:

```cpp
Debug::SetCapture([&window] {
    const fs::path file = fs::temp_directory_path() / "crafter-debug-capture.png";
    window.CaptureNextFrame(file);
    return Debug::Async<std::vector<std::byte>>([&window, file]() -> std::optional<std::vector<std::byte>> {
        if (window.pendingCapture) return std::nullopt;            // the next Render writes it
        std::vector<std::byte> png(fs::file_size(file));
        std::ifstream(file, std::ios::binary).read(reinterpret_cast<char*>(png.data()), static_cast<std::streamsize>(png.size()));
        return png;
    });
});
```

**Pumping:** with Crafter.Graphics, call `Debug::Pump()` from `window.onBeforeUpdate`.

**Hidden windows:** a window that is hidden or minimized stops updating, and with it `Pump`. Give such windows `window.updateInterval` with `PresentMode::Mailbox`.

The PNG travels over the connection, and the client writes it where the agent asked. Paths aren't passed, because the app and the client are in different sandboxes, each with a private `/tmp`.

### Your own types

A field can be any type with a codec. Codecs exist for:
- `bool`, integers, floating point, `std::string`;
- scoped enums, by name;
- `std::optional`, `std::vector`, `std::array`, string-keyed maps;
- `Debug::Value`, `Debug::Required<T>`, and aggregates.

For anything else, specialize `Debug::Codec<T>` with `Encode`, `Decode` and `Describe`; `Crafter.Debug.Core-Codec.cppm` shows the shape.

Reflection works without C++26 `<meta>`, so it has limits:
- **Aggregates only:** public members, no bases with members, no reference or const members, default-constructible fields.
- **Enums:** scoped enums get names for values in -128..127, and `EnumRange` widens that. Other enums travel as integers.

## The agent side

From the consumer's directory:

```
./build/crafter-debug ls [--wait 60s]          ./build/crafter-debug wait '<cond>' | --frames n | --event E | --paused
./build/crafter-debug status                   ./build/crafter-debug trace <path> [--frames 60] [--history]
./build/crafter-debug cmds [glob]              ./build/crafter-debug log [--level warn] [--cat c] [--grep s] [--follow]
./build/crafter-debug help <name>              ./build/crafter-debug screenshot [-o file.png]
./build/crafter-debug call <cmd> k=v ...       ./build/crafter-debug pause [--when c] [--on-check [--trap]] [--clear]
./build/crafter-debug get <path|glob> ...      ./build/crafter-debug resume | step [n] | quit [--force]
./build/crafter-debug set <path> <value>       ./build/crafter-debug debugger | guide
```

`./build/crafter-debug guide` is the full reference.

**Exit codes:** 0 done, 2 usage, 3 no instance, 4 app and client speak different protocols, 5 timed out, 6 the app answered an error.

**Timeouts:** a request that times out before the app's next `Pump` is guaranteed not to have run. A request with no reply is diagnosed and the next step printed. The cases are:
- the app has exited;
- it is stopped in a debugger;
- it no longer calls `Pump`.

**Stopping an app:**
- `quit` ends it cleanly. `quit --force` ends it even when its main loop is stuck.
- `kill -KILL <sandbox pid>` ends the whole `-r` sandbox from the host; `ls` shows that pid.
- With `--die-with-parent` in the crafter-build alias, stopping the background `-r` task stops the app too.

**Debuggers:** `crafter-debug debugger` prints `flatpak enter <instance> lldb -p <pid>`, or `gdb`, which runs the debugger inside the app's own sandbox. A debugger started in another `flatpak run` cannot see the app's pid namespace. The session allows any process of the user to attach, which Yama's ptrace_scope 1 requires.

**Version skew:** the client is built with the app. If an app from an older build is still running, the client compares the protocol and source id recorded at discovery:
- **Different protocol:** it refuses with exit 4, and prints the command that runs the app's own client.
- **Different sources:** it only warns.

## Developing Crafter.Debug

```bash
crafter-build test                  # every test
crafter-build test 'Should*Client*'
cd examples/Basic && crafter-build --debug-api -r
```

- **Library and core tests** run in-process, against a `Session` built with `listen = false` and a fake transport.
- **`ShouldRunClientCommands`** runs the real client against a real session that way.
- **`AGENTS.template.md`** has the conventions.

Licensed LGPL-3.0-only; the examples are MIT.