Appearance
C++
The C++ / MSVC / engine stack pack. It wraps the build loop and the tools that hang off it – build, test, profile, crash-triage, include-graph reach – into Nushell scripts that turn raw toolchain output into a structured table an agent can read instead of a wall of console text, and it guards C++ edits against stale SFML 2 patterns before they ever reach the compiler. Everything here is on demand, because a build or a debug session costs, with one exception: the SFML 3 guard, which fires on every C++ edit. Each tool degrades clean when its toolchain is absent, and every wrapper splits a live subcommand from a parse subcommand that reads a captured log – so you can exercise the whole pack, and fixture-test it, without MSVC on the box.
In Practice
Build and read the diagnostics as a table. You want a build that returns data, not scrollback, so you run:
nu .claude/stack/cpp/msbuild.nu build MyGame.sln --config Debug --platform x64It resolves MSBuild through vswhere (no hardcoded Visual Studio version), runs it, and parses every diagnostic line into a record. Errors sort before warnings, so the things that stopped the build sit on top:
build MyGame.sln [Debug|x64], 2 errors, 1 warnings
project file line col severity code message
MyGame src/player.cpp 88 12 error C2664 cannot convert argument 1 from 'int' to 'Entity&'
MyGame player.obj error LNK2019 unresolved external symbol Entity::update
MyGame src/enemy.cpp 40 9 warning C4101 unreferenced local variable 'i'If MSBuild or the sln is not there it says so and returns rather than half-running, and parse <logfile> gives the same table from a build log you captured earlier – no toolchain required.
Look up the fix an error code already cost you. The second time an LNK2019 lands you should not re-derive the fix, so --explain joins each error code to a banked one:
nu .claude/stack/cpp/msbuild.nu parse build.log --errors-only --explainIt reads .claude/memory/lessons/compile-errors.jsonl, matches each code against the stored lessons, and adds an explain column holding the fix from the last time you solved it:
parsed build.log, 2 errors, 1 warnings
file code message explain
player.obj LNK2019 unresolved external symbol Entity::update add the missing .lib to the linker input or define the symbol
src/player.cpp C2664 cannot convert argument 1 from 'int' to 'Entity&'A code with no banked fix just leaves the column empty. When you do solve one, you bank it keyed by the code, and the bridge remembers it next time.
The guard bounces an SFML 2-ism. You edit a C++ file and reach for the old event loop out of muscle memory:
cpp
if (event.type == sf::Event::Closed)
window.close();The PostToolUse guard reads the saved file, matches the .type == pattern, exits non-zero, and puts the SFML 3 fix on stderr where Claude reads it back:
sfml3-guard, D:/game/src/app.cpp has sfml 2-isms, sfml 3 changed these:
line 42, sfml3 Event is a variant, theres no .type, use event.is<sf::Event::Closed>() or event.getIf<sf::Event::KeyPressed>()
see .claude/memory/lessons/sfml.md for the migration notes if the memory part is installedAn example outcome. The edit never compiles wrong – the guard catches the variant slip the moment the file is written, hands back the exact SFML 3 form, and the next write lands clean. The checks key on sf:: and event. tokens, so plain C++ with no SFML in it is never touched, and any internal error fails open rather than blocking the edit.
Build and Test
msbuild.nu
The build loop – build [sln] finds MSBuild via vswhere, runs it, and parses the log into a diagnostics table (project, file, line, col, severity, code, message), errors sorted before warnings. parse <logfile> does the same on a captured log. --errors-only drops the warnings, --explain joins a past fix per error code, --raw dumps the log untouched. It is the loop the rest of the pack reads from.
run-tests.nu
The test output contract – run <binary> runs the engine's test binary and parse <logfile> reads a captured one, both emitting a fixed schema: suite, test, status, duration_ms, message, with status one of pass, fail, or skip. The parser targets GoogleTest console output by default; swap parse-gtest for a Catch2 or doctest parser when the framework is settled, and the schema stays fixed so nothing downstream cares which one won. Failure context between a test's RUN and its FAILED line is folded into the failing row's message.
Diagnosis
run-profiler.nu
The profiler summariser – top <capture> reads a JSON or CSV zone dump the engine emits and prints the top N hotspots (zone, calls, self_ms, total_ms, pct), aggregating repeated zones and ranking by self time, or by total with --sort total. The reader normalizes the common column names, so a Tracy, Optick, or custom dump all land in the same shape; swap read-capture when the real format is named and the hotspot schema holds.
crash-triage.nu
The minidump reader – dump <dmp> drives cdb (from the Windows SDK / Debugging Tools) with .ecxr, k, and lm, then pulls a five-line summary out: the exception, the faulting frame, and the top frames. It needs cdb on PATH and _NT_SYMBOL_PATH pointed at your build output for named frames – an unresolved stack still summarises, just with module and offset. parse <cdb-output-file> works on captured output, so the summariser is exercisable without a debugger.
blast-radius.nu
The include-graph reach – of <header> <logfile> names the translation units a header edit forces a rebuild of, walking a reverse include graph parsed from a build log captured with /showIncludes; --direct stops at the immediate includers, --count returns just the number. map <logfile> ranks the heaviest headers by how many files pull them. It carries no compiler of its own – it reads the log – which is what makes it fixture-testable.
Guard
sfml3-guard.nu
The post-edit gate – a PostToolUse hook on C++ files that bounces SFML 2-isms before they compile-fail: the event.type variant access, pollEvent with an out-param, unscoped sf::Keyboard keys, rect .left / .width members, default-constructed sf::Text and sf::Sound, and sf::VideoMode from two ints. It is string and regex checks only, no semantics, keyed on sf:: and event. tokens so plain C++ is never touched. A violation exits 2 with the SFML 3 fix on stderr; a clean or unreadable file exits 0, and any internal error fails open.
settings-fragment.json
The hook wiring – the PostToolUse block, matcher Edit|Write|MultiEdit, that registers sfml3-guard.nu. It ships with the pack; merge its entry into the target project's .claude/settings.json, alongside style-lint if the hooks pack is in, since a hook that is copied but not wired is silently inert.
The compile-error bridge
--explain is the seam between a build and the lesson store. It reads the compile-errors.jsonl slice straight off disk – it does not depend on lessons.nu being on the path – and per diagnostic looks the error code up in the banked lessons' when-and-do text, dropping the stored fix into an explain column. The discipline that feeds it is simple: when a compile error gets solved, bank it as a compile-errors lesson keyed by its code, and the next build that hits the same code surfaces the fix already written.
The memory part must be installed for the bridge to have a store to read. Without it, --explain simply leaves the column empty rather than failing.
The parse Convention
Every wrapper is built so its parser can run without the thing it wraps. The tools that drive a live toolchain each split a costing verb from a parse verb over a captured log; the two that already read an emitted artifact need no live toolchain at all. The schema on the right is fixed, so anything downstream reads the same shape whichever framework, profiler, or debugger produced the input.
| tool | live verb (costs) | on a captured artifact | fixed schema |
|---|---|---|---|
msbuild.nu | build [sln] | parse <log> | project, file, line, col, severity, code, message |
run-tests.nu | run <binary> | parse <log> | suite, test, status, duration_ms, message |
crash-triage.nu | dump <dmp> | parse <cdb-output> | exception, faulting_frame, top_frames |
run-profiler.nu | – | top <capture> | zone, calls, self_ms, total_ms, pct |
blast-radius.nu | – | of / map <log> | reverse include graph |
The parse-side subcommands are also the fixture-testable ones: feed them a saved log and they exercise the full parse path with no MSVC, cdb, or profiler on the machine.
Connects to
- Bridged to memory –
--explainreads thecompile-errorslesson slice to annotate error codes, and the SFML 3 guard points at thesfmlslice for the full migration notes. Both degrade clean when the memory part is not installed. - Fired by hooks –
sfml3-guard.nuis a PostToolUse gate, wired through the pack'ssettings-fragment.jsonand merged alongside the hooks pack's own gates like style-lint. - Placed by the installer – the pack copies into a target project's
.claude/stack/cpp/; the natvis-writer visualiser ships as its own separate skill part, installed on its own.