Catcrafts/Crafter.Debug
Watch
2
0
Fork
You've already forked Crafter.Debug
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Crafter.Debug/project.cpp

234 lines
9.9 KiB
C++
Raw Normal View History

feat(tooling): wire consumers in through Debug::Use and a launcher A consumer loads Crafter.Debug.Build through #pragma crafter dependency "<Crafter.Debug>" project "tooling/project.cpp" and calls Debug::Use in its own CrafterBuildProject, the way Crafter.LintRules gets in. With the consumer's flag on, Use adds the library from the checkout the pragma loaded, and writes build/crafter-debug: a POSIX sh launcher for the client that library builds. The client is one of the library's dependencies, so a debug build compiles it in the same pass as the app, from the same sources. Why a launcher and not a script: every `crafter-build run` loads the whole project first, which costs 13-28 s per call on 3DForts (a git pull per unpinned dependency plus rescanning sources), while the launcher is one sandbox start, 0.08 s. A client built in the Flatpak links the Flatpak's libc++ against the runtime's glibc, so the launcher starts it through `flatpak run` and never on the host itself; inside a CrafterBuild sandbox it runs it directly. The library, the client and examples/Basic are placeholders that prove the wiring: the debug build writes a launcher whose client exists, a plain build has no Crafter::Debug symbols and keeps the notes from tooling/AGENTS.consumer.md, and a fresh plain build writes a stub that names the flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:18:07 +01:00
// SPDX-License-Identifier: LGPL-3.0-only
// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
feat(cli): crafter-debug, the client agents drive an app with Cli::Run is the whole client but its transport, so tests run it in process against a real Session; main will hand it the QUIC connection. - Commands: ls, status, cmds, help, call, get, set, pause, resume, step, wait, trace, log (with --follow), screenshot, quit, debugger, guide and version, with -i, --json and --timeout. - call types key=value from the command's argument schema (slot=1 is a number, name=1 a string, at.x=3 nests), so agents need no JSON for simple calls; a value that cannot fit its field is a usage error before anything is sent. - The instance comes from discovery; one running instance needs no -i. The record's protocol is checked before any request: a mismatch exits 4, says which side is newer and prints the app's own client. Other sources only warn. - A request with no reply is diagnosed: the app has exited, stopped in a debugger (with the attach command), or no longer calls Pump (with what to change). Exit codes: 2 usage, 3 no instance, 4 version, 5 timeout, 6 the app's error. - Output is short by default, arrays cut at 20 with a note; --json prints everything. `guide` is the full reference for agents. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 02:03:38 +01:00
// Four configurations:
feat(discovery): find live instances across sandboxes; build info Each app writes $HOME/.cache/crafter-debug/instances/<id>.json (0600, in a 0700 directory) and holds an flock on <id>.lock while it lives. Every `flatpak run` is its own pid namespace, so pids collide and can neither name an instance nor tell whether it lives; a random id names it and the lock says it lives, since flock works across sandboxes on the shared filesystem. An app killed without its destructor leaves its files with the lock free, and the next listing removes them. The lock is created under a temporary name, locked, then renamed, as in Crafter.Review's LifetimeLock, so it is never seen unlocked while its app lives. Inside a Flatpak the record also carries the sandbox's instance id (for `flatpak enter`) and the host pid of its init (to end the whole sandbox from the host). project.cpp now generates :BuildInfo per core variant: a hash of the library's sources and the path of the client built with it. App and client share the core, so they report the same id exactly when built from the same sources; this is the safety net under building the client in the same pass as the app. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:56:31 +01:00
// Crafter.Debug.Core what the app and the client share (values, codecs,
// the protocol, discovery, build info)
feat(cli): crafter-debug, the client agents drive an app with Cli::Run is the whole client but its transport, so tests run it in process against a real Session; main will hand it the QUIC connection. - Commands: ls, status, cmds, help, call, get, set, pause, resume, step, wait, trace, log (with --follow), screenshot, quit, debugger, guide and version, with -i, --json and --timeout. - call types key=value from the command's argument schema (slot=1 is a number, name=1 a string, at.x=3 nests), so agents need no JSON for simple calls; a value that cannot fit its field is a usage error before anything is sent. - The instance comes from discovery; one running instance needs no -i. The record's protocol is checked before any request: a mismatch exits 4, says which side is newer and prints the app's own client. Other sources only warn. - A request with no reply is diagnosed: the app has exited, stopped in a debugger (with the attach command), or no longer calls Pump (with what to change). Exit codes: 2 usage, 3 no instance, 4 version, 5 timeout, 6 the app's error. - Output is short by default, arrays cut at 20 with a note; --json prints everything. `guide` is the full reference for agents. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 02:03:38 +01:00
// Crafter.Debug.Cli the client's code, a library so tests can run it
feat(core): Value, reflection, codecs and results, shared by app and client Crafter.Debug.Core is what the app side and the crafter-debug client both need, without the session: - Value: a JSON value with its own parser and printer, so no consumer interface sees a JSON library. Integers stay integers and whole doubles stay doubles; NaN and the infinities, which JSON cannot spell, are written as strings rather than hidden, because a debugger must not lose a NaN; invalid UTF-8 is replaced so output always parses. Objects keep insertion order, the order an agent reads. - Reflect: aggregate members and names through structured-binding packs and source_location, taken from Crafter.DB, plus scoped-enum names by probing a range of values. Self-tested with static_asserts so a compiler that changes function_name()'s shape fails the build. - Codec<T>: encode, decode and describe for bool, integers, floating point, strings, enums, optional, vector, array, string-keyed maps, Value, Required<T> and every aggregate. Decode reports every problem in a call with its path and, for a typo, the likely intended name, and never throws: a bad call cannot take an app down, which a wrongly typed parameter could in 3DForts' hand-written from_json. - Result, Error and Async: handler results, including ones that take frames to arrive, so callers need no ready:false polling. project.cpp now builds Crafter.Debug.Core as its own library, used by both the app library and the client. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:31:58 +01:00
// crafter.debug-cli the client, crafter-debug
feat(cli): crafter-debug, the client agents drive an app with Cli::Run is the whole client but its transport, so tests run it in process against a real Session; main will hand it the QUIC connection. - Commands: ls, status, cmds, help, call, get, set, pause, resume, step, wait, trace, log (with --follow), screenshot, quit, debugger, guide and version, with -i, --json and --timeout. - call types key=value from the command's argument schema (slot=1 is a number, name=1 a string, at.x=3 nests), so agents need no JSON for simple calls; a value that cannot fit its field is a usage error before anything is sent. - The instance comes from discovery; one running instance needs no -i. The record's protocol is checked before any request: a mismatch exits 4, says which side is newer and prints the app's own client. Other sources only warn. - A request with no reply is diagnosed: the app has exited, stopped in a debugger (with the attach command), or no longer calls Pump (with what to change). Exit codes: 2 usage, 3 no instance, 4 version, 5 timeout, 6 the app's error. - Output is short by default, arrays cut at 20 with a note; --json prints everything. `guide` is the full reference for agents. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 02:03:38 +01:00
// Crafter.Debug what an app links (returned), depending on the core
// and the client
feat(core): Value, reflection, codecs and results, shared by app and client Crafter.Debug.Core is what the app side and the crafter-debug client both need, without the session: - Value: a JSON value with its own parser and printer, so no consumer interface sees a JSON library. Integers stay integers and whole doubles stay doubles; NaN and the infinities, which JSON cannot spell, are written as strings rather than hidden, because a debugger must not lose a NaN; invalid UTF-8 is replaced so output always parses. Objects keep insertion order, the order an agent reads. - Reflect: aggregate members and names through structured-binding packs and source_location, taken from Crafter.DB, plus scoped-enum names by probing a range of values. Self-tested with static_asserts so a compiler that changes function_name()'s shape fails the build. - Codec<T>: encode, decode and describe for bool, integers, floating point, strings, enums, optional, vector, array, string-keyed maps, Value, Required<T> and every aggregate. Decode reports every problem in a call with its path and, for a typo, the likely intended name, and never throws: a bad call cannot take an app down, which a wrongly typed parameter could in 3DForts' hand-written from_json. - Result, Error and Async: handler results, including ones that take frames to arrive, so callers need no ready:false polling. project.cpp now builds Crafter.Debug.Core as its own library, used by both the app library and the client. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:31:58 +01:00
// The client is one of the library's dependencies only so that a consumer's
// debug build compiles it in the same pass as the app; an executable adds no
// link flags to what depends on it. Consumers load this file through
// Debug::Use (tooling/), which also writes their launcher.
feat(transport): serve the session over QUIC on loopback A Session with listen = true (the default) now listens on 127.0.0.1 with the ALPN crafter-debug/1 and writes its discovery record (port, token, protocol, source id, client path), which goes first when it ends. One request per stream the client opens: the request and a FIN in, zero or more stream lines and then the reply and a FIN out, one JSON object per line. It holds no thread while nothing arrives. Crafter.Network delivers a new stream on the pool, its bytes on msquic's worker through OnRecieve, and replies leave through SendAsync, which never waits. The handler, which takes the session's mutex, runs on a pool task rather than inside the stream's callback, so no msquic worker ever waits on the session, and the session's threads only send, which Network allows under any lock. Stream wrappers are let go outside every lock their callbacks take. The rules head the implementation. Limits: a request over 1 MiB is answered with an error, not buffered, and a log follower more than 8 MiB behind is reset. quit --force exits 200 ms after its reply was taken, from a thread of its own, since "sent" means msquic has the bytes, not that they left. A client killed without closing is let go at the 10 s idle timeout. The Session refuses a pool without a worker: Network hands it new streams there, and with Start(1) nothing would run them. The partition exports nothing, so an app's view of the module is unchanged and it does not see Crafter.Network's types. Crafter.Network comes from forgejo, unpinned, with the args unchanged; --local takes ../Crafter.Network, and $CRAFTER_DEBUG_NETWORK any project.cpp, for the branch the callback API is on until it lands. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 03:06:56 +01:00
//
// The library and the client talk QUIC through Crafter.Network, which comes
chore(transport): drop the CRAFTER_DEBUG_NETWORK hook The transport needed Crafter.Network's callback API, which lived on an unpushed branch, so project.cpp took Network from whatever project.cpp $CRAFTER_DEBUG_NETWORK named. That API and the ~ClientQUIC fix are on Network's master now (79a2f12), so the hook goes: Network comes from forgejo, unpinned, or from ../Crafter.Network with --local, as before. The notes and the README stop telling people to set it, and say which Network the transport needs. Every test passes with Network cloned from forgejo, and the example builds and is driven end to end that way. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 18:04:22 +01:00
// from forgejo, or with --local from the checkout beside this one.
feat(tooling): wire consumers in through Debug::Use and a launcher A consumer loads Crafter.Debug.Build through #pragma crafter dependency "<Crafter.Debug>" project "tooling/project.cpp" and calls Debug::Use in its own CrafterBuildProject, the way Crafter.LintRules gets in. With the consumer's flag on, Use adds the library from the checkout the pragma loaded, and writes build/crafter-debug: a POSIX sh launcher for the client that library builds. The client is one of the library's dependencies, so a debug build compiles it in the same pass as the app, from the same sources. Why a launcher and not a script: every `crafter-build run` loads the whole project first, which costs 13-28 s per call on 3DForts (a git pull per unpinned dependency plus rescanning sources), while the launcher is one sandbox start, 0.08 s. A client built in the Flatpak links the Flatpak's libc++ against the runtime's glibc, so the launcher starts it through `flatpak run` and never on the host itself; inside a CrafterBuild sandbox it runs it directly. The library, the client and examples/Basic are placeholders that prove the wiring: the debug build writes a launcher whose client exists, a plain build has no Crafter::Debug symbols and keeps the notes from tooling/AGENTS.consumer.md, and a fresh plain build writes a stub that names the flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:18:07 +01:00
import std;
import Crafter.Build;
namespace fs = std::filesystem;
using namespace Crafter;
namespace {
// The configurations this file makes besides the one it returns, at
// stable addresses for the pointers in `dependencies`. One set per load,
// not statics: a static would keep the first load's args for every load.
std::deque<Configuration> owned;
// This file's directory. A configuration a project file makes for itself
// keeps the path it is given, and "./" would later resolve against the
// consumer's directory instead of this one.
fs::path Root() {
return fs::path(std::source_location::current().file_name()).parent_path();
}
feat(core): Value, reflection, codecs and results, shared by app and client Crafter.Debug.Core is what the app side and the crafter-debug client both need, without the session: - Value: a JSON value with its own parser and printer, so no consumer interface sees a JSON library. Integers stay integers and whole doubles stay doubles; NaN and the infinities, which JSON cannot spell, are written as strings rather than hidden, because a debugger must not lose a NaN; invalid UTF-8 is replaced so output always parses. Objects keep insertion order, the order an agent reads. - Reflect: aggregate members and names through structured-binding packs and source_location, taken from Crafter.DB, plus scoped-enum names by probing a range of values. Self-tested with static_asserts so a compiler that changes function_name()'s shape fails the build. - Codec<T>: encode, decode and describe for bool, integers, floating point, strings, enums, optional, vector, array, string-keyed maps, Value, Required<T> and every aggregate. Decode reports every problem in a call with its path and, for a typo, the likely intended name, and never throws: a bad call cannot take an app down, which a wrongly typed parameter could in 3DForts' hand-written from_json. - Result, Error and Async: handler results, including ones that take frames to arrive, so callers need no ready:false polling. project.cpp now builds Crafter.Debug.Core as its own library, used by both the app library and the client. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:31:58 +01:00
feat(transport): serve the session over QUIC on loopback A Session with listen = true (the default) now listens on 127.0.0.1 with the ALPN crafter-debug/1 and writes its discovery record (port, token, protocol, source id, client path), which goes first when it ends. One request per stream the client opens: the request and a FIN in, zero or more stream lines and then the reply and a FIN out, one JSON object per line. It holds no thread while nothing arrives. Crafter.Network delivers a new stream on the pool, its bytes on msquic's worker through OnRecieve, and replies leave through SendAsync, which never waits. The handler, which takes the session's mutex, runs on a pool task rather than inside the stream's callback, so no msquic worker ever waits on the session, and the session's threads only send, which Network allows under any lock. Stream wrappers are let go outside every lock their callbacks take. The rules head the implementation. Limits: a request over 1 MiB is answered with an error, not buffered, and a log follower more than 8 MiB behind is reset. quit --force exits 200 ms after its reply was taken, from a thread of its own, since "sent" means msquic has the bytes, not that they left. A client killed without closing is let go at the 10 s idle timeout. The Session refuses a pool without a worker: Network hands it new streams there, and with Start(1) nothing would run them. The partition exports nothing, so an app's view of the module is unchanged and it does not see Crafter.Network's types. Crafter.Network comes from forgejo, unpinned, with the args unchanged; --local takes ../Crafter.Network, and $CRAFTER_DEBUG_NETWORK any project.cpp, for the branch the callback API is on until it lands. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 03:06:56 +01:00
// Crafter.Network, with the args unchanged: a consumer that also uses
// it passes the same ones, so both resolve to one configuration rather
// than one module built twice.
Configuration* Network(std::span<const std::string_view> args) {
const std::vector<std::string> forwarded(args.begin(), args.end());
if (std::ranges::find(args, std::string_view("--local")) != args.end()) {
return LocalProject({ .projectFile = Root().parent_path() / "Crafter.Network" / "project.cpp", .args = forwarded });
}
return GitProject({
.source = { .url = "https://forgejo.catcrafts.net/Catcrafts/Crafter.Network.git" },
.args = forwarded,
});
}
feat(registry): commands, watches, samples, the timeline and conditions The app side of Crafter.Debug, minus the session: - Command(name, description, handler): the handler takes nothing or one argument struct and returns void, a value, Result<T> or Async<T>. Arguments are decoded before it runs, so a mistyped call is answered with every mistake and never reaches it; a throwing handler becomes an Exception error instead of unwinding into the frame loop. This replaces 3DForts' three-file pattern per verb. - Watch(path, variable | getter [, setter]) with bounds, help and read-only, and Sample(path, value) from any thread with a frame-stamped history. Paths resolve into values ("bodies[1].pos.y") and set the same way, writing a member writes the whole value back. Unknown paths and commands get a suggestion. - Group: registrations under a prefix that end with their owner. Not movable, so neither is its owner: its watches refer to the owner's members, and a move would leave them pointing at the old object. - Log, LogWarn, LogError, Check and Emit on one frame-stamped timeline, with source locations captured without macros. A check failing every frame is counted every time but stored sparsely, and the session's listener hears every failure. - Condition: what `wait` and `pause --when` evaluate each frame. A condition that cannot be decided reports why instead of being false, which would make a wait hang. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:40:59 +01:00
// Tests of the core, linked against it alone.
feat(discovery): find live instances across sandboxes; build info Each app writes $HOME/.cache/crafter-debug/instances/<id>.json (0600, in a 0700 directory) and holds an flock on <id>.lock while it lives. Every `flatpak run` is its own pid namespace, so pids collide and can neither name an instance nor tell whether it lives; a random id names it and the lock says it lives, since flock works across sandboxes on the shared filesystem. An app killed without its destructor leaves its files with the lock free, and the next listing removes them. The lock is created under a temporary name, locked, then renamed, as in Crafter.Review's LifetimeLock, so it is never seen unlocked while its app lives. Inside a Flatpak the record also carries the sandbox's instance id (for `flatpak enter`) and the host pid of its init (to end the whole sandbox from the host). project.cpp now generates :BuildInfo per core variant: a hash of the library's sources and the path of the client built with it. App and client share the core, so they report the same id exactly when built from the same sources; this is the safety net under building the client in the same pass as the app. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:56:31 +01:00
constexpr std::array<std::string_view, 5> coreTests = {
feat(core): Value, reflection, codecs and results, shared by app and client Crafter.Debug.Core is what the app side and the crafter-debug client both need, without the session: - Value: a JSON value with its own parser and printer, so no consumer interface sees a JSON library. Integers stay integers and whole doubles stay doubles; NaN and the infinities, which JSON cannot spell, are written as strings rather than hidden, because a debugger must not lose a NaN; invalid UTF-8 is replaced so output always parses. Objects keep insertion order, the order an agent reads. - Reflect: aggregate members and names through structured-binding packs and source_location, taken from Crafter.DB, plus scoped-enum names by probing a range of values. Self-tested with static_asserts so a compiler that changes function_name()'s shape fails the build. - Codec<T>: encode, decode and describe for bool, integers, floating point, strings, enums, optional, vector, array, string-keyed maps, Value, Required<T> and every aggregate. Decode reports every problem in a call with its path and, for a typo, the likely intended name, and never throws: a bad call cannot take an app down, which a wrongly typed parameter could in 3DForts' hand-written from_json. - Result, Error and Async: handler results, including ones that take frames to arrive, so callers need no ready:false polling. project.cpp now builds Crafter.Debug.Core as its own library, used by both the app library and the client. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:31:58 +01:00
"ShouldRoundTripJson",
"ShouldRoundTripAggregates",
"ShouldReportDecodeErrorsWithPaths",
"ShouldDescribeDefaultsAndRequired",
feat(discovery): find live instances across sandboxes; build info Each app writes $HOME/.cache/crafter-debug/instances/<id>.json (0600, in a 0700 directory) and holds an flock on <id>.lock while it lives. Every `flatpak run` is its own pid namespace, so pids collide and can neither name an instance nor tell whether it lives; a random id names it and the lock says it lives, since flock works across sandboxes on the shared filesystem. An app killed without its destructor leaves its files with the lock free, and the next listing removes them. The lock is created under a temporary name, locked, then renamed, as in Crafter.Review's LifetimeLock, so it is never seen unlocked while its app lives. Inside a Flatpak the record also carries the sandbox's instance id (for `flatpak enter`) and the host pid of its init (to end the whole sandbox from the host). project.cpp now generates :BuildInfo per core variant: a hash of the library's sources and the path of the client built with it. App and client share the core, so they report the same id exactly when built from the same sources; this is the safety net under building the client in the same pass as the app. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:56:31 +01:00
"ShouldDiscoverLiveInstances",
feat(core): Value, reflection, codecs and results, shared by app and client Crafter.Debug.Core is what the app side and the crafter-debug client both need, without the session: - Value: a JSON value with its own parser and printer, so no consumer interface sees a JSON library. Integers stay integers and whole doubles stay doubles; NaN and the infinities, which JSON cannot spell, are written as strings rather than hidden, because a debugger must not lose a NaN; invalid UTF-8 is replaced so output always parses. Objects keep insertion order, the order an agent reads. - Reflect: aggregate members and names through structured-binding packs and source_location, taken from Crafter.DB, plus scoped-enum names by probing a range of values. Self-tested with static_asserts so a compiler that changes function_name()'s shape fails the build. - Codec<T>: encode, decode and describe for bool, integers, floating point, strings, enums, optional, vector, array, string-keyed maps, Value, Required<T> and every aggregate. Decode reports every problem in a call with its path and, for a typo, the likely intended name, and never throws: a bad call cannot take an app down, which a wrongly typed parameter could in 3DForts' hand-written from_json. - Result, Error and Async: handler results, including ones that take frames to arrive, so callers need no ready:false polling. project.cpp now builds Crafter.Debug.Core as its own library, used by both the app library and the client. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:31:58 +01:00
};
feat(registry): commands, watches, samples, the timeline and conditions The app side of Crafter.Debug, minus the session: - Command(name, description, handler): the handler takes nothing or one argument struct and returns void, a value, Result<T> or Async<T>. Arguments are decoded before it runs, so a mistyped call is answered with every mistake and never reaches it; a throwing handler becomes an Exception error instead of unwinding into the frame loop. This replaces 3DForts' three-file pattern per verb. - Watch(path, variable | getter [, setter]) with bounds, help and read-only, and Sample(path, value) from any thread with a frame-stamped history. Paths resolve into values ("bodies[1].pos.y") and set the same way, writing a member writes the whole value back. Unknown paths and commands get a suggestion. - Group: registrations under a prefix that end with their owner. Not movable, so neither is its owner: its watches refer to the owner's members, and a move would leave them pointing at the old object. - Log, LogWarn, LogError, Check and Emit on one frame-stamped timeline, with source locations captured without macros. A check failing every frame is counted every time but stored sparsely, and the session's listener hears every failure. - Condition: what `wait` and `pause --when` evaluate each frame. A condition that cannot be decided reports why instead of being false, which would make a wait hang. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:40:59 +01:00
// Tests of the app library.
feat(session): serve requests without blocking a thread, pause and step The app's end of the connection, independent of the transport, which reaches it through Detail::Exchange: one request's way back, safe from any thread and never blocking. - What needs only the session's own state (hello, status, list, log, pause, resume) is answered on the transport thread. What touches the app (calls, get, set, trace, screenshot) queues for the next Pump and runs on the app's thread between frames. Waits and steps reply from the Pump that sees them satisfied, events from the thread that emits them. No request ever holds a thread while it waits. - A request whose timeout passes before Pump is answered Timeout and is guaranteed not to have run, so an agent never wonders whether a command went through; an Async result arrives on the Pump it is ready; requests left when the Session ends are answered ShuttingDown. - Advance() for frame loops and Paused()/TakeSteps() for fixed-step loops hold what the app gates on them; pausing an app that gates nothing is refused instead of silently doing nothing. pause --when stops the frame its condition holds; pause --on-check stops before the next Advance in the frame a check fails, optionally raising SIGTRAP for an attached debugger. - A wait that times out says what its condition's paths were; a log follower gets matching entries in order, from the backlog on, and is dropped when it cannot keep up. - Request parameters go through Codec, so a mistyped request gets the same did-you-mean replies a mistyped command does. The session sets PR_SET_PTRACER_ANY so a debugger the agent starts can attach. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:53:15 +01:00
constexpr std::array<std::string_view, 7> libraryTests = {
feat(registry): commands, watches, samples, the timeline and conditions The app side of Crafter.Debug, minus the session: - Command(name, description, handler): the handler takes nothing or one argument struct and returns void, a value, Result<T> or Async<T>. Arguments are decoded before it runs, so a mistyped call is answered with every mistake and never reaches it; a throwing handler becomes an Exception error instead of unwinding into the frame loop. This replaces 3DForts' three-file pattern per verb. - Watch(path, variable | getter [, setter]) with bounds, help and read-only, and Sample(path, value) from any thread with a frame-stamped history. Paths resolve into values ("bodies[1].pos.y") and set the same way, writing a member writes the whole value back. Unknown paths and commands get a suggestion. - Group: registrations under a prefix that end with their owner. Not movable, so neither is its owner: its watches refer to the owner's members, and a move would leave them pointing at the old object. - Log, LogWarn, LogError, Check and Emit on one frame-stamped timeline, with source locations captured without macros. A check failing every frame is counted every time but stored sparsely, and the session's listener hears every failure. - Condition: what `wait` and `pause --when` evaluate each frame. A condition that cannot be decided reports why instead of being false, which would make a wait hang. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:40:59 +01:00
"ShouldInvokeCommands",
"ShouldResolveWatchPaths",
"ShouldRecordTimeline",
"ShouldEvaluateConditions",
feat(session): serve requests without blocking a thread, pause and step The app's end of the connection, independent of the transport, which reaches it through Detail::Exchange: one request's way back, safe from any thread and never blocking. - What needs only the session's own state (hello, status, list, log, pause, resume) is answered on the transport thread. What touches the app (calls, get, set, trace, screenshot) queues for the next Pump and runs on the app's thread between frames. Waits and steps reply from the Pump that sees them satisfied, events from the thread that emits them. No request ever holds a thread while it waits. - A request whose timeout passes before Pump is answered Timeout and is guaranteed not to have run, so an agent never wonders whether a command went through; an Async result arrives on the Pump it is ready; requests left when the Session ends are answered ShuttingDown. - Advance() for frame loops and Paused()/TakeSteps() for fixed-step loops hold what the app gates on them; pausing an app that gates nothing is refused instead of silently doing nothing. pause --when stops the frame its condition holds; pause --on-check stops before the next Advance in the frame a check fails, optionally raising SIGTRAP for an attached debugger. - A wait that times out says what its condition's paths were; a log follower gets matching entries in order, from the backlog on, and is dropped when it cannot keep up. - Request parameters go through Codec, so a mistyped request gets the same did-you-mean replies a mistyped command does. The session sets PR_SET_PTRACER_ANY so a debugger the agent starts can attach. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:53:15 +01:00
"ShouldAnswerRequests",
"ShouldPauseAndStep",
"ShouldWaitTraceAndFollow",
feat(registry): commands, watches, samples, the timeline and conditions The app side of Crafter.Debug, minus the session: - Command(name, description, handler): the handler takes nothing or one argument struct and returns void, a value, Result<T> or Async<T>. Arguments are decoded before it runs, so a mistyped call is answered with every mistake and never reaches it; a throwing handler becomes an Exception error instead of unwinding into the frame loop. This replaces 3DForts' three-file pattern per verb. - Watch(path, variable | getter [, setter]) with bounds, help and read-only, and Sample(path, value) from any thread with a frame-stamped history. Paths resolve into values ("bodies[1].pos.y") and set the same way, writing a member writes the whole value back. Unknown paths and commands get a suggestion. - Group: registrations under a prefix that end with their owner. Not movable, so neither is its owner: its watches refer to the owner's members, and a move would leave them pointing at the old object. - Log, LogWarn, LogError, Check and Emit on one frame-stamped timeline, with source locations captured without macros. A check failing every frame is counted every time but stored sparsely, and the session's listener hears every failure. - Condition: what `wait` and `pause --when` evaluate each frame. A condition that cannot be decided reports why instead of being false, which would make a wait hang. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:40:59 +01:00
};
feat(discovery): find live instances across sandboxes; build info Each app writes $HOME/.cache/crafter-debug/instances/<id>.json (0600, in a 0700 directory) and holds an flock on <id>.lock while it lives. Every `flatpak run` is its own pid namespace, so pids collide and can neither name an instance nor tell whether it lives; a random id names it and the lock says it lives, since flock works across sandboxes on the shared filesystem. An app killed without its destructor leaves its files with the lock free, and the next listing removes them. The lock is created under a temporary name, locked, then renamed, as in Crafter.Review's LifetimeLock, so it is never seen unlocked while its app lives. Inside a Flatpak the record also carries the sandbox's instance id (for `flatpak enter`) and the host pid of its init (to end the whole sandbox from the host). project.cpp now generates :BuildInfo per core variant: a hash of the library's sources and the path of the client built with it. App and client share the core, so they report the same id exactly when built from the same sources; this is the safety net under building the client in the same pass as the app. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:56:31 +01:00
std::string ReadFile(const fs::path& path) {
std::ifstream in(path, std::ios::binary);
return std::string((std::istreambuf_iterator<char>(in)), std::istreambuf_iterator<char>());
}
// FNV-1a over the path and bytes of every source, in a fixed order: what
// the app and the client compare to tell they came from the same code.
std::string SourceId() {
std::vector<fs::path> files;
for (const std::string_view dir : { "interfaces", "implementations" }) {
std::error_code ec;
for (const fs::directory_entry& entry : fs::recursive_directory_iterator(Root() / dir, ec)) {
if (entry.is_regular_file() && (entry.path().extension() == ".cppm" || entry.path().extension() == ".cpp")) files.push_back(entry.path());
}
}
std::ranges::sort(files);
std::uint64_t hash = 14695981039346656037ULL;
const auto mix = [&](std::string_view bytes) {
for (const char c : bytes) {
hash ^= static_cast<std::uint8_t>(c);
hash *= 1099511628211ULL;
}
};
for (const fs::path& file : files) {
mix(file.lexically_relative(Root()).generic_string());
mix(ReadFile(file));
}
return std::format("{:016x}", hash);
}
void WriteIfChanged(const fs::path& file, const std::string& text) {
if (fs::exists(file) && ReadFile(file) == text) return;
fs::create_directories(file.parent_path());
std::ofstream(file, std::ios::binary | std::ios::trunc) << text;
}
// Generates the definitions of :BuildInfo for this variant of the core and
// returns the source to compile, without its extension.
fs::path GenerateBuildInfo(const Configuration& core, const Configuration& client) {
const fs::path source = Root() / "build" / "generated" / core.VariantId() / "Crafter.Debug.Core-BuildInfo";
const fs::path clientPath = client.BinDir() / client.outputName;
WriteIfChanged(fs::path(source).concat(".cpp"), std::format(
"// Generated by Crafter.Debug's project.cpp whenever the sources or the client's\n"
"// path change. Not to be edited.\n"
"module Crafter.Debug.Core:BuildInfo_impl;\n"
"import std;\n"
"import :BuildInfo;\n"
"\n"
"std::string_view Crafter::Debug::Detail::SourceId() {{\n"
" return \"{}\";\n"
"}}\n"
"\n"
"std::string_view Crafter::Debug::Detail::ClientPath() {{\n"
" return R\"crafter-debug({})crafter-debug\";\n"
"}}\n",
SourceId(), clientPath.string()));
return source;
}
feat(tooling): wire consumers in through Debug::Use and a launcher A consumer loads Crafter.Debug.Build through #pragma crafter dependency "<Crafter.Debug>" project "tooling/project.cpp" and calls Debug::Use in its own CrafterBuildProject, the way Crafter.LintRules gets in. With the consumer's flag on, Use adds the library from the checkout the pragma loaded, and writes build/crafter-debug: a POSIX sh launcher for the client that library builds. The client is one of the library's dependencies, so a debug build compiles it in the same pass as the app, from the same sources. Why a launcher and not a script: every `crafter-build run` loads the whole project first, which costs 13-28 s per call on 3DForts (a git pull per unpinned dependency plus rescanning sources), while the launcher is one sandbox start, 0.08 s. A client built in the Flatpak links the Flatpak's libc++ against the runtime's glibc, so the launcher starts it through `flatpak run` and never on the host itself; inside a CrafterBuild sandbox it runs it directly. The library, the client and examples/Basic are placeholders that prove the wiring: the debug build writes a launcher whose client exists, a plain build has no Crafter::Debug symbols and keeps the notes from tooling/AGENTS.consumer.md, and a fresh plain build writes a stub that names the flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:18:07 +01:00
}
extern "C" Configuration CrafterBuildProject(std::span<const std::string_view> args) {
Configuration cfg;
cfg.path = "./";
cfg.name = "Crafter.Debug";
cfg.outputName = "Crafter.Debug";
cfg.type = ConfigurationType::LibraryStatic;
ApplyStandardArgs(cfg, args);
feat(core): Value, reflection, codecs and results, shared by app and client Crafter.Debug.Core is what the app side and the crafter-debug client both need, without the session: - Value: a JSON value with its own parser and printer, so no consumer interface sees a JSON library. Integers stay integers and whole doubles stay doubles; NaN and the infinities, which JSON cannot spell, are written as strings rather than hidden, because a debugger must not lose a NaN; invalid UTF-8 is replaced so output always parses. Objects keep insertion order, the order an agent reads. - Reflect: aggregate members and names through structured-binding packs and source_location, taken from Crafter.DB, plus scoped-enum names by probing a range of values. Self-tested with static_asserts so a compiler that changes function_name()'s shape fails the build. - Codec<T>: encode, decode and describe for bool, integers, floating point, strings, enums, optional, vector, array, string-keyed maps, Value, Required<T> and every aggregate. Decode reports every problem in a call with its path and, for a typo, the likely intended name, and never throws: a bad call cannot take an app down, which a wrongly typed parameter could in 3DForts' hand-written from_json. - Result, Error and Async: handler results, including ones that take frames to arrive, so callers need no ready:false polling. project.cpp now builds Crafter.Debug.Core as its own library, used by both the app library and the client. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:31:58 +01:00
feat(transport): serve the session over QUIC on loopback A Session with listen = true (the default) now listens on 127.0.0.1 with the ALPN crafter-debug/1 and writes its discovery record (port, token, protocol, source id, client path), which goes first when it ends. One request per stream the client opens: the request and a FIN in, zero or more stream lines and then the reply and a FIN out, one JSON object per line. It holds no thread while nothing arrives. Crafter.Network delivers a new stream on the pool, its bytes on msquic's worker through OnRecieve, and replies leave through SendAsync, which never waits. The handler, which takes the session's mutex, runs on a pool task rather than inside the stream's callback, so no msquic worker ever waits on the session, and the session's threads only send, which Network allows under any lock. Stream wrappers are let go outside every lock their callbacks take. The rules head the implementation. Limits: a request over 1 MiB is answered with an error, not buffered, and a log follower more than 8 MiB behind is reset. quit --force exits 200 ms after its reply was taken, from a thread of its own, since "sent" means msquic has the bytes, not that they left. A client killed without closing is let go at the 10 s idle timeout. The Session refuses a pool without a worker: Network hands it new streams there, and with Start(1) nothing would run them. The partition exports nothing, so an app's view of the module is unchanged and it does not see Crafter.Network's types. Crafter.Network comes from forgejo, unpinned, with the args unchanged; --local takes ../Crafter.Network, and $CRAFTER_DEBUG_NETWORK any project.cpp, for the branch the callback API is on until it lands. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 03:06:56 +01:00
Configuration* network = Network(args);
feat(core): Value, reflection, codecs and results, shared by app and client Crafter.Debug.Core is what the app side and the crafter-debug client both need, without the session: - Value: a JSON value with its own parser and printer, so no consumer interface sees a JSON library. Integers stay integers and whole doubles stay doubles; NaN and the infinities, which JSON cannot spell, are written as strings rather than hidden, because a debugger must not lose a NaN; invalid UTF-8 is replaced so output always parses. Objects keep insertion order, the order an agent reads. - Reflect: aggregate members and names through structured-binding packs and source_location, taken from Crafter.DB, plus scoped-enum names by probing a range of values. Self-tested with static_asserts so a compiler that changes function_name()'s shape fails the build. - Codec<T>: encode, decode and describe for bool, integers, floating point, strings, enums, optional, vector, array, string-keyed maps, Value, Required<T> and every aggregate. Decode reports every problem in a call with its path and, for a typo, the likely intended name, and never throws: a bad call cannot take an app down, which a wrongly typed parameter could in 3DForts' hand-written from_json. - Result, Error and Async: handler results, including ones that take frames to arrive, so callers need no ready:false polling. project.cpp now builds Crafter.Debug.Core as its own library, used by both the app library and the client. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:31:58 +01:00
Configuration& core = owned.emplace_back();
core.path = Root();
core.name = "Crafter.Debug.Core";
core.outputName = "Crafter.Debug.Core";
core.type = ConfigurationType::LibraryStatic;
ApplyStandardArgs(core, args);
feat(tooling): wire consumers in through Debug::Use and a launcher A consumer loads Crafter.Debug.Build through #pragma crafter dependency "<Crafter.Debug>" project "tooling/project.cpp" and calls Debug::Use in its own CrafterBuildProject, the way Crafter.LintRules gets in. With the consumer's flag on, Use adds the library from the checkout the pragma loaded, and writes build/crafter-debug: a POSIX sh launcher for the client that library builds. The client is one of the library's dependencies, so a debug build compiles it in the same pass as the app, from the same sources. Why a launcher and not a script: every `crafter-build run` loads the whole project first, which costs 13-28 s per call on 3DForts (a git pull per unpinned dependency plus rescanning sources), while the launcher is one sandbox start, 0.08 s. A client built in the Flatpak links the Flatpak's libc++ against the runtime's glibc, so the launcher starts it through `flatpak run` and never on the host itself; inside a CrafterBuild sandbox it runs it directly. The library, the client and examples/Basic are placeholders that prove the wiring: the debug build writes a launcher whose client exists, a plain build has no Crafter::Debug symbols and keeps the notes from tooling/AGENTS.consumer.md, and a fresh plain build writes a stub that names the flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:18:07 +01:00
feat(core): Value, reflection, codecs and results, shared by app and client Crafter.Debug.Core is what the app side and the crafter-debug client both need, without the session: - Value: a JSON value with its own parser and printer, so no consumer interface sees a JSON library. Integers stay integers and whole doubles stay doubles; NaN and the infinities, which JSON cannot spell, are written as strings rather than hidden, because a debugger must not lose a NaN; invalid UTF-8 is replaced so output always parses. Objects keep insertion order, the order an agent reads. - Reflect: aggregate members and names through structured-binding packs and source_location, taken from Crafter.DB, plus scoped-enum names by probing a range of values. Self-tested with static_asserts so a compiler that changes function_name()'s shape fails the build. - Codec<T>: encode, decode and describe for bool, integers, floating point, strings, enums, optional, vector, array, string-keyed maps, Value, Required<T> and every aggregate. Decode reports every problem in a call with its path and, for a typo, the likely intended name, and never throws: a bad call cannot take an app down, which a wrongly typed parameter could in 3DForts' hand-written from_json. - Result, Error and Async: handler results, including ones that take frames to arrive, so callers need no ready:false polling. project.cpp now builds Crafter.Debug.Core as its own library, used by both the app library and the client. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:31:58 +01:00
// The client, built for the library's target. Not through
// ApplyStandardArgs: a consumer's --lib would make it a library.
feat(tooling): wire consumers in through Debug::Use and a launcher A consumer loads Crafter.Debug.Build through #pragma crafter dependency "<Crafter.Debug>" project "tooling/project.cpp" and calls Debug::Use in its own CrafterBuildProject, the way Crafter.LintRules gets in. With the consumer's flag on, Use adds the library from the checkout the pragma loaded, and writes build/crafter-debug: a POSIX sh launcher for the client that library builds. The client is one of the library's dependencies, so a debug build compiles it in the same pass as the app, from the same sources. Why a launcher and not a script: every `crafter-build run` loads the whole project first, which costs 13-28 s per call on 3DForts (a git pull per unpinned dependency plus rescanning sources), while the launcher is one sandbox start, 0.08 s. A client built in the Flatpak links the Flatpak's libc++ against the runtime's glibc, so the launcher starts it through `flatpak run` and never on the host itself; inside a CrafterBuild sandbox it runs it directly. The library, the client and examples/Basic are placeholders that prove the wiring: the debug build writes a launcher whose client exists, a plain build has no Crafter::Debug symbols and keeps the notes from tooling/AGENTS.consumer.md, and a fresh plain build writes a stub that names the flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:18:07 +01:00
Configuration& client = owned.emplace_back();
client.path = Root();
client.name = "crafter.debug-cli";
client.outputName = "crafter-debug";
client.type = ConfigurationType::Executable;
client.target = cfg.target;
client.march = cfg.march;
client.mtune = cfg.mtune;
client.sysroot = cfg.sysroot;
client.debug = cfg.debug;
feat(cli): crafter-debug, the client agents drive an app with Cli::Run is the whole client but its transport, so tests run it in process against a real Session; main will hand it the QUIC connection. - Commands: ls, status, cmds, help, call, get, set, pause, resume, step, wait, trace, log (with --follow), screenshot, quit, debugger, guide and version, with -i, --json and --timeout. - call types key=value from the command's argument schema (slot=1 is a number, name=1 a string, at.x=3 nests), so agents need no JSON for simple calls; a value that cannot fit its field is a usage error before anything is sent. - The instance comes from discovery; one running instance needs no -i. The record's protocol is checked before any request: a mismatch exits 4, says which side is newer and prints the app's own client. Other sources only warn. - A request with no reply is diagnosed: the app has exited, stopped in a debugger (with the attach command), or no longer calls Pump (with what to change). Exit codes: 2 usage, 3 no instance, 4 version, 5 timeout, 6 the app's error. - Output is short by default, arrays cut at 20 with a note; --json prints everything. `guide` is the full reference for agents. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 02:03:38 +01:00
// The client's code as a library, so tests can run it in process.
Configuration& cli = owned.emplace_back();
cli.path = Root();
cli.name = "Crafter.Debug.Cli";
cli.outputName = "Crafter.Debug.Cli";
cli.type = ConfigurationType::LibraryStatic;
cli.target = cfg.target;
cli.march = cfg.march;
cli.mtune = cfg.mtune;
cli.sysroot = cfg.sysroot;
cli.debug = cfg.debug;
feat(cli): reach instances over QUIC crafter-debug had a placeholder transport that reported every instance unreachable. Cli::ConnectQuic dials 127.0.0.1 at the port in the discovery record on the first call, keeps the connection for the next, and dials again after one is lost. Each call opens a stream, sends the request with a FIN, and reads lines: one with a result or an error is the reply, anything before it a stream line for onLine, which runs on the calling thread so a slow terminal never stalls msquic's worker. Past the deadline the stream is aborted and the call times out. The handshake gives up after 3 s, and keep-alives every 2 s hold a quiet follow or a long wait open under the 10 s idle timeout. main starts a pool with one worker, which Network reports some failures on, and ends with _Exit once Run has closed its connections, since msquic's teardown at exit waits on connections. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 03:07:09 +01:00
cli.dependencies = { &core, network };
feat(cli): crafter-debug, the client agents drive an app with Cli::Run is the whole client but its transport, so tests run it in process against a real Session; main will hand it the QUIC connection. - Commands: ls, status, cmds, help, call, get, set, pause, resume, step, wait, trace, log (with --follow), screenshot, quit, debugger, guide and version, with -i, --json and --timeout. - call types key=value from the command's argument schema (slot=1 is a number, name=1 a string, at.x=3 nests), so agents need no JSON for simple calls; a value that cannot fit its field is a usage error before anything is sent. - The instance comes from discovery; one running instance needs no -i. The record's protocol is checked before any request: a mismatch exits 4, says which side is newer and prints the app's own client. Other sources only warn. - A request with no reply is diagnosed: the app has exited, stopped in a debugger (with the attach command), or no longer calls Pump (with what to change). Exit codes: 2 usage, 3 no instance, 4 version, 5 timeout, 6 the app's error. - Output is short by default, arrays cut at 20 with a note; --json prints everything. `guide` is the full reference for agents. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 02:03:38 +01:00
client.dependencies = { &cli };
feat(discovery): find live instances across sandboxes; build info Each app writes $HOME/.cache/crafter-debug/instances/<id>.json (0600, in a 0700 directory) and holds an flock on <id>.lock while it lives. Every `flatpak run` is its own pid namespace, so pids collide and can neither name an instance nor tell whether it lives; a random id names it and the lock says it lives, since flock works across sandboxes on the shared filesystem. An app killed without its destructor leaves its files with the lock free, and the next listing removes them. The lock is created under a temporary name, locked, then renamed, as in Crafter.Review's LifetimeLock, so it is never seen unlocked while its app lives. Inside a Flatpak the record also carries the sandbox's instance id (for `flatpak enter`) and the host pid of its init (to end the whole sandbox from the host). project.cpp now generates :BuildInfo per core variant: a hash of the library's sources and the path of the client built with it. App and client share the core, so they report the same id exactly when built from the same sources; this is the safety net under building the client in the same pass as the app. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:56:31 +01:00
{
std::array<fs::path, 8> interfaces = {
"interfaces/Crafter.Debug.Core-Value",
"interfaces/Crafter.Debug.Core-Reflect",
"interfaces/Crafter.Debug.Core-Codec",
"interfaces/Crafter.Debug.Core-Result",
"interfaces/Crafter.Debug.Core-Protocol",
"interfaces/Crafter.Debug.Core-BuildInfo",
"interfaces/Crafter.Debug.Core-Discovery",
"interfaces/Crafter.Debug.Core",
};
std::array<fs::path, 5> implementations = {
"implementations/Crafter.Debug.Core-Value",
"implementations/Crafter.Debug.Core-Codec",
"implementations/Crafter.Debug.Core-Protocol",
"implementations/Crafter.Debug.Core-Discovery",
GenerateBuildInfo(core, client),
};
core.GetInterfacesAndImplementations(interfaces, implementations);
}
feat(cli): crafter-debug, the client agents drive an app with Cli::Run is the whole client but its transport, so tests run it in process against a real Session; main will hand it the QUIC connection. - Commands: ls, status, cmds, help, call, get, set, pause, resume, step, wait, trace, log (with --follow), screenshot, quit, debugger, guide and version, with -i, --json and --timeout. - call types key=value from the command's argument schema (slot=1 is a number, name=1 a string, at.x=3 nests), so agents need no JSON for simple calls; a value that cannot fit its field is a usage error before anything is sent. - The instance comes from discovery; one running instance needs no -i. The record's protocol is checked before any request: a mismatch exits 4, says which side is newer and prints the app's own client. Other sources only warn. - A request with no reply is diagnosed: the app has exited, stopped in a debugger (with the attach command), or no longer calls Pump (with what to change). Exit codes: 2 usage, 3 no instance, 4 version, 5 timeout, 6 the app's error. - Output is short by default, arrays cut at 20 with a note; --json prints everything. `guide` is the full reference for agents. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 02:03:38 +01:00
{
feat(cli): reach instances over QUIC crafter-debug had a placeholder transport that reported every instance unreachable. Cli::ConnectQuic dials 127.0.0.1 at the port in the discovery record on the first call, keeps the connection for the next, and dials again after one is lost. Each call opens a stream, sends the request with a FIN, and reads lines: one with a result or an error is the reply, anything before it a stream line for onLine, which runs on the calling thread so a slow terminal never stalls msquic's worker. Past the deadline the stream is aborted and the call times out. The handshake gives up after 3 s, and keep-alives every 2 s hold a quiet follow or a long wait open under the 10 s idle timeout. main starts a pool with one worker, which Network reports some failures on, and ends with _Exit once Run has closed its connections, since msquic's teardown at exit waits on connections. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 03:07:09 +01:00
std::array<fs::path, 3> interfaces = { "interfaces/Crafter.Debug.Cli-Client", "interfaces/Crafter.Debug.Cli-Quic", "interfaces/Crafter.Debug.Cli" };
std::array<fs::path, 2> implementations = { "implementations/Crafter.Debug.Cli-Client", "implementations/Crafter.Debug.Cli-Quic" };
feat(cli): crafter-debug, the client agents drive an app with Cli::Run is the whole client but its transport, so tests run it in process against a real Session; main will hand it the QUIC connection. - Commands: ls, status, cmds, help, call, get, set, pause, resume, step, wait, trace, log (with --follow), screenshot, quit, debugger, guide and version, with -i, --json and --timeout. - call types key=value from the command's argument schema (slot=1 is a number, name=1 a string, at.x=3 nests), so agents need no JSON for simple calls; a value that cannot fit its field is a usage error before anything is sent. - The instance comes from discovery; one running instance needs no -i. The record's protocol is checked before any request: a mismatch exits 4, says which side is newer and prints the app's own client. Other sources only warn. - A request with no reply is diagnosed: the app has exited, stopped in a debugger (with the attach command), or no longer calls Pump (with what to change). Exit codes: 2 usage, 3 no instance, 4 version, 5 timeout, 6 the app's error. - Output is short by default, arrays cut at 20 with a note; --json prints everything. `guide` is the full reference for agents. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 02:03:38 +01:00
cli.GetInterfacesAndImplementations(interfaces, implementations);
}
feat(tooling): wire consumers in through Debug::Use and a launcher A consumer loads Crafter.Debug.Build through #pragma crafter dependency "<Crafter.Debug>" project "tooling/project.cpp" and calls Debug::Use in its own CrafterBuildProject, the way Crafter.LintRules gets in. With the consumer's flag on, Use adds the library from the checkout the pragma loaded, and writes build/crafter-debug: a POSIX sh launcher for the client that library builds. The client is one of the library's dependencies, so a debug build compiles it in the same pass as the app, from the same sources. Why a launcher and not a script: every `crafter-build run` loads the whole project first, which costs 13-28 s per call on 3DForts (a git pull per unpinned dependency plus rescanning sources), while the launcher is one sandbox start, 0.08 s. A client built in the Flatpak links the Flatpak's libc++ against the runtime's glibc, so the launcher starts it through `flatpak run` and never on the host itself; inside a CrafterBuild sandbox it runs it directly. The library, the client and examples/Basic are placeholders that prove the wiring: the debug build writes a launcher whose client exists, a plain build has no Crafter::Debug symbols and keeps the notes from tooling/AGENTS.consumer.md, and a fresh plain build writes a stub that names the flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:18:07 +01:00
{
std::array<fs::path, 0> interfaces = {};
std::array<fs::path, 1> implementations = { "implementations/main" };
client.GetInterfacesAndImplementations(interfaces, implementations);
}
feat(core): Value, reflection, codecs and results, shared by app and client Crafter.Debug.Core is what the app side and the crafter-debug client both need, without the session: - Value: a JSON value with its own parser and printer, so no consumer interface sees a JSON library. Integers stay integers and whole doubles stay doubles; NaN and the infinities, which JSON cannot spell, are written as strings rather than hidden, because a debugger must not lose a NaN; invalid UTF-8 is replaced so output always parses. Objects keep insertion order, the order an agent reads. - Reflect: aggregate members and names through structured-binding packs and source_location, taken from Crafter.DB, plus scoped-enum names by probing a range of values. Self-tested with static_asserts so a compiler that changes function_name()'s shape fails the build. - Codec<T>: encode, decode and describe for bool, integers, floating point, strings, enums, optional, vector, array, string-keyed maps, Value, Required<T> and every aggregate. Decode reports every problem in a call with its path and, for a typo, the likely intended name, and never throws: a bad call cannot take an app down, which a wrongly typed parameter could in 3DForts' hand-written from_json. - Result, Error and Async: handler results, including ones that take frames to arrive, so callers need no ready:false polling. project.cpp now builds Crafter.Debug.Core as its own library, used by both the app library and the client. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:31:58 +01:00
feat(transport): serve the session over QUIC on loopback A Session with listen = true (the default) now listens on 127.0.0.1 with the ALPN crafter-debug/1 and writes its discovery record (port, token, protocol, source id, client path), which goes first when it ends. One request per stream the client opens: the request and a FIN in, zero or more stream lines and then the reply and a FIN out, one JSON object per line. It holds no thread while nothing arrives. Crafter.Network delivers a new stream on the pool, its bytes on msquic's worker through OnRecieve, and replies leave through SendAsync, which never waits. The handler, which takes the session's mutex, runs on a pool task rather than inside the stream's callback, so no msquic worker ever waits on the session, and the session's threads only send, which Network allows under any lock. Stream wrappers are let go outside every lock their callbacks take. The rules head the implementation. Limits: a request over 1 MiB is answered with an error, not buffered, and a log follower more than 8 MiB behind is reset. quit --force exits 200 ms after its reply was taken, from a thread of its own, since "sent" means msquic has the bytes, not that they left. A client killed without closing is let go at the 10 s idle timeout. The Session refuses a pool without a worker: Network hands it new streams there, and with Start(1) nothing would run them. The partition exports nothing, so an app's view of the module is unchanged and it does not see Crafter.Network's types. Crafter.Network comes from forgejo, unpinned, with the args unchanged; --local takes ../Crafter.Network, and $CRAFTER_DEBUG_NETWORK any project.cpp, for the branch the callback API is on until it lands. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 03:06:56 +01:00
cfg.dependencies = { &core, &client, network };
feat(core): Value, reflection, codecs and results, shared by app and client Crafter.Debug.Core is what the app side and the crafter-debug client both need, without the session: - Value: a JSON value with its own parser and printer, so no consumer interface sees a JSON library. Integers stay integers and whole doubles stay doubles; NaN and the infinities, which JSON cannot spell, are written as strings rather than hidden, because a debugger must not lose a NaN; invalid UTF-8 is replaced so output always parses. Objects keep insertion order, the order an agent reads. - Reflect: aggregate members and names through structured-binding packs and source_location, taken from Crafter.DB, plus scoped-enum names by probing a range of values. Self-tested with static_asserts so a compiler that changes function_name()'s shape fails the build. - Codec<T>: encode, decode and describe for bool, integers, floating point, strings, enums, optional, vector, array, string-keyed maps, Value, Required<T> and every aggregate. Decode reports every problem in a call with its path and, for a typo, the likely intended name, and never throws: a bad call cannot take an app down, which a wrongly typed parameter could in 3DForts' hand-written from_json. - Result, Error and Async: handler results, including ones that take frames to arrive, so callers need no ready:false polling. project.cpp now builds Crafter.Debug.Core as its own library, used by both the app library and the client. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:31:58 +01:00
{
feat(transport): serve the session over QUIC on loopback A Session with listen = true (the default) now listens on 127.0.0.1 with the ALPN crafter-debug/1 and writes its discovery record (port, token, protocol, source id, client path), which goes first when it ends. One request per stream the client opens: the request and a FIN in, zero or more stream lines and then the reply and a FIN out, one JSON object per line. It holds no thread while nothing arrives. Crafter.Network delivers a new stream on the pool, its bytes on msquic's worker through OnRecieve, and replies leave through SendAsync, which never waits. The handler, which takes the session's mutex, runs on a pool task rather than inside the stream's callback, so no msquic worker ever waits on the session, and the session's threads only send, which Network allows under any lock. Stream wrappers are let go outside every lock their callbacks take. The rules head the implementation. Limits: a request over 1 MiB is answered with an error, not buffered, and a log follower more than 8 MiB behind is reset. quit --force exits 200 ms after its reply was taken, from a thread of its own, since "sent" means msquic has the bytes, not that they left. A client killed without closing is let go at the 10 s idle timeout. The Session refuses a pool without a worker: Network hands it new streams there, and with Start(1) nothing would run them. The partition exports nothing, so an app's view of the module is unchanged and it does not see Crafter.Network's types. Crafter.Network comes from forgejo, unpinned, with the args unchanged; --local takes ../Crafter.Network, and $CRAFTER_DEBUG_NETWORK any project.cpp, for the branch the callback API is on until it lands. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 03:06:56 +01:00
std::array<fs::path, 6> interfaces = {
feat(registry): commands, watches, samples, the timeline and conditions The app side of Crafter.Debug, minus the session: - Command(name, description, handler): the handler takes nothing or one argument struct and returns void, a value, Result<T> or Async<T>. Arguments are decoded before it runs, so a mistyped call is answered with every mistake and never reaches it; a throwing handler becomes an Exception error instead of unwinding into the frame loop. This replaces 3DForts' three-file pattern per verb. - Watch(path, variable | getter [, setter]) with bounds, help and read-only, and Sample(path, value) from any thread with a frame-stamped history. Paths resolve into values ("bodies[1].pos.y") and set the same way, writing a member writes the whole value back. Unknown paths and commands get a suggestion. - Group: registrations under a prefix that end with their owner. Not movable, so neither is its owner: its watches refer to the owner's members, and a move would leave them pointing at the old object. - Log, LogWarn, LogError, Check and Emit on one frame-stamped timeline, with source locations captured without macros. A check failing every frame is counted every time but stored sparsely, and the session's listener hears every failure. - Condition: what `wait` and `pause --when` evaluate each frame. A condition that cannot be decided reports why instead of being false, which would make a wait hang. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:40:59 +01:00
"interfaces/Crafter.Debug-Registry",
"interfaces/Crafter.Debug-Timeline",
"interfaces/Crafter.Debug-Condition",
feat(session): serve requests without blocking a thread, pause and step The app's end of the connection, independent of the transport, which reaches it through Detail::Exchange: one request's way back, safe from any thread and never blocking. - What needs only the session's own state (hello, status, list, log, pause, resume) is answered on the transport thread. What touches the app (calls, get, set, trace, screenshot) queues for the next Pump and runs on the app's thread between frames. Waits and steps reply from the Pump that sees them satisfied, events from the thread that emits them. No request ever holds a thread while it waits. - A request whose timeout passes before Pump is answered Timeout and is guaranteed not to have run, so an agent never wonders whether a command went through; an Async result arrives on the Pump it is ready; requests left when the Session ends are answered ShuttingDown. - Advance() for frame loops and Paused()/TakeSteps() for fixed-step loops hold what the app gates on them; pausing an app that gates nothing is refused instead of silently doing nothing. pause --when stops the frame its condition holds; pause --on-check stops before the next Advance in the frame a check fails, optionally raising SIGTRAP for an attached debugger. - A wait that times out says what its condition's paths were; a log follower gets matching entries in order, from the backlog on, and is dropped when it cannot keep up. - Request parameters go through Codec, so a mistyped request gets the same did-you-mean replies a mistyped command does. The session sets PR_SET_PTRACER_ANY so a debugger the agent starts can attach. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:53:15 +01:00
"interfaces/Crafter.Debug-Session",
feat(transport): serve the session over QUIC on loopback A Session with listen = true (the default) now listens on 127.0.0.1 with the ALPN crafter-debug/1 and writes its discovery record (port, token, protocol, source id, client path), which goes first when it ends. One request per stream the client opens: the request and a FIN in, zero or more stream lines and then the reply and a FIN out, one JSON object per line. It holds no thread while nothing arrives. Crafter.Network delivers a new stream on the pool, its bytes on msquic's worker through OnRecieve, and replies leave through SendAsync, which never waits. The handler, which takes the session's mutex, runs on a pool task rather than inside the stream's callback, so no msquic worker ever waits on the session, and the session's threads only send, which Network allows under any lock. Stream wrappers are let go outside every lock their callbacks take. The rules head the implementation. Limits: a request over 1 MiB is answered with an error, not buffered, and a log follower more than 8 MiB behind is reset. quit --force exits 200 ms after its reply was taken, from a thread of its own, since "sent" means msquic has the bytes, not that they left. A client killed without closing is let go at the 10 s idle timeout. The Session refuses a pool without a worker: Network hands it new streams there, and with Start(1) nothing would run them. The partition exports nothing, so an app's view of the module is unchanged and it does not see Crafter.Network's types. Crafter.Network comes from forgejo, unpinned, with the args unchanged; --local takes ../Crafter.Network, and $CRAFTER_DEBUG_NETWORK any project.cpp, for the branch the callback API is on until it lands. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 03:06:56 +01:00
"interfaces/Crafter.Debug-Transport",
feat(registry): commands, watches, samples, the timeline and conditions The app side of Crafter.Debug, minus the session: - Command(name, description, handler): the handler takes nothing or one argument struct and returns void, a value, Result<T> or Async<T>. Arguments are decoded before it runs, so a mistyped call is answered with every mistake and never reaches it; a throwing handler becomes an Exception error instead of unwinding into the frame loop. This replaces 3DForts' three-file pattern per verb. - Watch(path, variable | getter [, setter]) with bounds, help and read-only, and Sample(path, value) from any thread with a frame-stamped history. Paths resolve into values ("bodies[1].pos.y") and set the same way, writing a member writes the whole value back. Unknown paths and commands get a suggestion. - Group: registrations under a prefix that end with their owner. Not movable, so neither is its owner: its watches refer to the owner's members, and a move would leave them pointing at the old object. - Log, LogWarn, LogError, Check and Emit on one frame-stamped timeline, with source locations captured without macros. A check failing every frame is counted every time but stored sparsely, and the session's listener hears every failure. - Condition: what `wait` and `pause --when` evaluate each frame. A condition that cannot be decided reports why instead of being false, which would make a wait hang. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:40:59 +01:00
"interfaces/Crafter.Debug",
};
feat(transport): serve the session over QUIC on loopback A Session with listen = true (the default) now listens on 127.0.0.1 with the ALPN crafter-debug/1 and writes its discovery record (port, token, protocol, source id, client path), which goes first when it ends. One request per stream the client opens: the request and a FIN in, zero or more stream lines and then the reply and a FIN out, one JSON object per line. It holds no thread while nothing arrives. Crafter.Network delivers a new stream on the pool, its bytes on msquic's worker through OnRecieve, and replies leave through SendAsync, which never waits. The handler, which takes the session's mutex, runs on a pool task rather than inside the stream's callback, so no msquic worker ever waits on the session, and the session's threads only send, which Network allows under any lock. Stream wrappers are let go outside every lock their callbacks take. The rules head the implementation. Limits: a request over 1 MiB is answered with an error, not buffered, and a log follower more than 8 MiB behind is reset. quit --force exits 200 ms after its reply was taken, from a thread of its own, since "sent" means msquic has the bytes, not that they left. A client killed without closing is let go at the 10 s idle timeout. The Session refuses a pool without a worker: Network hands it new streams there, and with Start(1) nothing would run them. The partition exports nothing, so an app's view of the module is unchanged and it does not see Crafter.Network's types. Crafter.Network comes from forgejo, unpinned, with the args unchanged; --local takes ../Crafter.Network, and $CRAFTER_DEBUG_NETWORK any project.cpp, for the branch the callback API is on until it lands. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 03:06:56 +01:00
std::array<fs::path, 5> implementations = {
feat(registry): commands, watches, samples, the timeline and conditions The app side of Crafter.Debug, minus the session: - Command(name, description, handler): the handler takes nothing or one argument struct and returns void, a value, Result<T> or Async<T>. Arguments are decoded before it runs, so a mistyped call is answered with every mistake and never reaches it; a throwing handler becomes an Exception error instead of unwinding into the frame loop. This replaces 3DForts' three-file pattern per verb. - Watch(path, variable | getter [, setter]) with bounds, help and read-only, and Sample(path, value) from any thread with a frame-stamped history. Paths resolve into values ("bodies[1].pos.y") and set the same way, writing a member writes the whole value back. Unknown paths and commands get a suggestion. - Group: registrations under a prefix that end with their owner. Not movable, so neither is its owner: its watches refer to the owner's members, and a move would leave them pointing at the old object. - Log, LogWarn, LogError, Check and Emit on one frame-stamped timeline, with source locations captured without macros. A check failing every frame is counted every time but stored sparsely, and the session's listener hears every failure. - Condition: what `wait` and `pause --when` evaluate each frame. A condition that cannot be decided reports why instead of being false, which would make a wait hang. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:40:59 +01:00
"implementations/Crafter.Debug-Registry",
"implementations/Crafter.Debug-Timeline",
"implementations/Crafter.Debug-Condition",
feat(session): serve requests without blocking a thread, pause and step The app's end of the connection, independent of the transport, which reaches it through Detail::Exchange: one request's way back, safe from any thread and never blocking. - What needs only the session's own state (hello, status, list, log, pause, resume) is answered on the transport thread. What touches the app (calls, get, set, trace, screenshot) queues for the next Pump and runs on the app's thread between frames. Waits and steps reply from the Pump that sees them satisfied, events from the thread that emits them. No request ever holds a thread while it waits. - A request whose timeout passes before Pump is answered Timeout and is guaranteed not to have run, so an agent never wonders whether a command went through; an Async result arrives on the Pump it is ready; requests left when the Session ends are answered ShuttingDown. - Advance() for frame loops and Paused()/TakeSteps() for fixed-step loops hold what the app gates on them; pausing an app that gates nothing is refused instead of silently doing nothing. pause --when stops the frame its condition holds; pause --on-check stops before the next Advance in the frame a check fails, optionally raising SIGTRAP for an attached debugger. - A wait that times out says what its condition's paths were; a log follower gets matching entries in order, from the backlog on, and is dropped when it cannot keep up. - Request parameters go through Codec, so a mistyped request gets the same did-you-mean replies a mistyped command does. The session sets PR_SET_PTRACER_ANY so a debugger the agent starts can attach. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:53:15 +01:00
"implementations/Crafter.Debug-Session",
feat(transport): serve the session over QUIC on loopback A Session with listen = true (the default) now listens on 127.0.0.1 with the ALPN crafter-debug/1 and writes its discovery record (port, token, protocol, source id, client path), which goes first when it ends. One request per stream the client opens: the request and a FIN in, zero or more stream lines and then the reply and a FIN out, one JSON object per line. It holds no thread while nothing arrives. Crafter.Network delivers a new stream on the pool, its bytes on msquic's worker through OnRecieve, and replies leave through SendAsync, which never waits. The handler, which takes the session's mutex, runs on a pool task rather than inside the stream's callback, so no msquic worker ever waits on the session, and the session's threads only send, which Network allows under any lock. Stream wrappers are let go outside every lock their callbacks take. The rules head the implementation. Limits: a request over 1 MiB is answered with an error, not buffered, and a log follower more than 8 MiB behind is reset. quit --force exits 200 ms after its reply was taken, from a thread of its own, since "sent" means msquic has the bytes, not that they left. A client killed without closing is let go at the 10 s idle timeout. The Session refuses a pool without a worker: Network hands it new streams there, and with Start(1) nothing would run them. The partition exports nothing, so an app's view of the module is unchanged and it does not see Crafter.Network's types. Crafter.Network comes from forgejo, unpinned, with the args unchanged; --local takes ../Crafter.Network, and $CRAFTER_DEBUG_NETWORK any project.cpp, for the branch the callback API is on until it lands. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 03:06:56 +01:00
"implementations/Crafter.Debug-Transport",
feat(registry): commands, watches, samples, the timeline and conditions The app side of Crafter.Debug, minus the session: - Command(name, description, handler): the handler takes nothing or one argument struct and returns void, a value, Result<T> or Async<T>. Arguments are decoded before it runs, so a mistyped call is answered with every mistake and never reaches it; a throwing handler becomes an Exception error instead of unwinding into the frame loop. This replaces 3DForts' three-file pattern per verb. - Watch(path, variable | getter [, setter]) with bounds, help and read-only, and Sample(path, value) from any thread with a frame-stamped history. Paths resolve into values ("bodies[1].pos.y") and set the same way, writing a member writes the whole value back. Unknown paths and commands get a suggestion. - Group: registrations under a prefix that end with their owner. Not movable, so neither is its owner: its watches refer to the owner's members, and a move would leave them pointing at the old object. - Log, LogWarn, LogError, Check and Emit on one frame-stamped timeline, with source locations captured without macros. A check failing every frame is counted every time but stored sparsely, and the session's listener hears every failure. - Condition: what `wait` and `pause --when` evaluate each frame. A condition that cannot be decided reports why instead of being false, which would make a wait hang. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:40:59 +01:00
};
feat(core): Value, reflection, codecs and results, shared by app and client Crafter.Debug.Core is what the app side and the crafter-debug client both need, without the session: - Value: a JSON value with its own parser and printer, so no consumer interface sees a JSON library. Integers stay integers and whole doubles stay doubles; NaN and the infinities, which JSON cannot spell, are written as strings rather than hidden, because a debugger must not lose a NaN; invalid UTF-8 is replaced so output always parses. Objects keep insertion order, the order an agent reads. - Reflect: aggregate members and names through structured-binding packs and source_location, taken from Crafter.DB, plus scoped-enum names by probing a range of values. Self-tested with static_asserts so a compiler that changes function_name()'s shape fails the build. - Codec<T>: encode, decode and describe for bool, integers, floating point, strings, enums, optional, vector, array, string-keyed maps, Value, Required<T> and every aggregate. Decode reports every problem in a call with its path and, for a typo, the likely intended name, and never throws: a bad call cannot take an app down, which a wrongly typed parameter could in 3DForts' hand-written from_json. - Result, Error and Async: handler results, including ones that take frames to arrive, so callers need no ready:false polling. project.cpp now builds Crafter.Debug.Core as its own library, used by both the app library and the client. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:31:58 +01:00
cfg.GetInterfacesAndImplementations(interfaces, implementations);
}
// Tests only when this is the project being built: a consumer's load of
// this file has no use for them.
if (IsTopLevelProject()) {
feat(registry): commands, watches, samples, the timeline and conditions The app side of Crafter.Debug, minus the session: - Command(name, description, handler): the handler takes nothing or one argument struct and returns void, a value, Result<T> or Async<T>. Arguments are decoded before it runs, so a mistyped call is answered with every mistake and never reaches it; a throwing handler becomes an Exception error instead of unwinding into the frame loop. This replaces 3DForts' three-file pattern per verb. - Watch(path, variable | getter [, setter]) with bounds, help and read-only, and Sample(path, value) from any thread with a frame-stamped history. Paths resolve into values ("bodies[1].pos.y") and set the same way, writing a member writes the whole value back. Unknown paths and commands get a suggestion. - Group: registrations under a prefix that end with their owner. Not movable, so neither is its owner: its watches refer to the owner's members, and a move would leave them pointing at the old object. - Log, LogWarn, LogError, Check and Emit on one frame-stamped timeline, with source locations captured without macros. A check failing every frame is counted every time but stored sparsely, and the session's listener hears every failure. - Condition: what `wait` and `pause --when` evaluate each frame. A condition that cannot be decided reports why instead of being false, which would make a wait hang. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:40:59 +01:00
for (const std::string_view test : coreTests) cfg.AddTest(test).Dependencies({ &core });
for (const std::string_view test : libraryTests) cfg.AddTest(test).Dependencies({ &cfg });
feat(cli): crafter-debug, the client agents drive an app with Cli::Run is the whole client but its transport, so tests run it in process against a real Session; main will hand it the QUIC connection. - Commands: ls, status, cmds, help, call, get, set, pause, resume, step, wait, trace, log (with --follow), screenshot, quit, debugger, guide and version, with -i, --json and --timeout. - call types key=value from the command's argument schema (slot=1 is a number, name=1 a string, at.x=3 nests), so agents need no JSON for simple calls; a value that cannot fit its field is a usage error before anything is sent. - The instance comes from discovery; one running instance needs no -i. The record's protocol is checked before any request: a mismatch exits 4, says which side is newer and prints the app's own client. Other sources only warn. - A request with no reply is diagnosed: the app has exited, stopped in a debugger (with the attach command), or no longer calls Pump (with what to change). Exit codes: 2 usage, 3 no instance, 4 version, 5 timeout, 6 the app's error. - Output is short by default, arrays cut at 20 with a note; --json prints everything. `guide` is the full reference for agents. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 02:03:38 +01:00
cfg.AddTest("ShouldRunClientCommands").Dependencies({ &cfg, &cli });
test(transport): drive a listening session over loopback ShouldServeOverQuic runs a Session that listens for real and reaches it with the client's own transport. It covers: - the discovery record, and its removal when the Session ends; - status, call, a mistyped command, get and set, and log --follow streaming as entries are logged and ending on time; - six clients at once, and eight streams at once on one connection; - a wrong token, a request that isn't JSON, and one over 1 MiB, each answered with an error; - ending the Session with a follower waiting, which is told "shutting down" and is not sent a backlog it asked none of; - a client finding the port dead in milliseconds. The shutdown reply went missing in 4 runs of 30 until Crafter.Network's ~ClientQUIC let stopped streams finish before closing; 50 of 50 pass since. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 03:07:09 +01:00
cfg.AddTest("ShouldServeOverQuic").Dependencies({ &cfg, &cli });
feat(core): Value, reflection, codecs and results, shared by app and client Crafter.Debug.Core is what the app side and the crafter-debug client both need, without the session: - Value: a JSON value with its own parser and printer, so no consumer interface sees a JSON library. Integers stay integers and whole doubles stay doubles; NaN and the infinities, which JSON cannot spell, are written as strings rather than hidden, because a debugger must not lose a NaN; invalid UTF-8 is replaced so output always parses. Objects keep insertion order, the order an agent reads. - Reflect: aggregate members and names through structured-binding packs and source_location, taken from Crafter.DB, plus scoped-enum names by probing a range of values. Self-tested with static_asserts so a compiler that changes function_name()'s shape fails the build. - Codec<T>: encode, decode and describe for bool, integers, floating point, strings, enums, optional, vector, array, string-keyed maps, Value, Required<T> and every aggregate. Decode reports every problem in a call with its path and, for a typo, the likely intended name, and never throws: a bad call cannot take an app down, which a wrongly typed parameter could in 3DForts' hand-written from_json. - Result, Error and Async: handler results, including ones that take frames to arrive, so callers need no ready:false polling. project.cpp now builds Crafter.Debug.Core as its own library, used by both the app library and the client. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:31:58 +01:00
}
feat(tooling): wire consumers in through Debug::Use and a launcher A consumer loads Crafter.Debug.Build through #pragma crafter dependency "<Crafter.Debug>" project "tooling/project.cpp" and calls Debug::Use in its own CrafterBuildProject, the way Crafter.LintRules gets in. With the consumer's flag on, Use adds the library from the checkout the pragma loaded, and writes build/crafter-debug: a POSIX sh launcher for the client that library builds. The client is one of the library's dependencies, so a debug build compiles it in the same pass as the app, from the same sources. Why a launcher and not a script: every `crafter-build run` loads the whole project first, which costs 13-28 s per call on 3DForts (a git pull per unpinned dependency plus rescanning sources), while the launcher is one sandbox start, 0.08 s. A client built in the Flatpak links the Flatpak's libc++ against the runtime's glibc, so the launcher starts it through `flatpak run` and never on the host itself; inside a CrafterBuild sandbox it runs it directly. The library, the client and examples/Basic are placeholders that prove the wiring: the debug build writes a launcher whose client exists, a plain build has no Crafter::Debug symbols and keeps the notes from tooling/AGENTS.consumer.md, and a fresh plain build writes a stub that names the flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:18:07 +01:00
return cfg;
}
Reference in a new issue Copy permalink