Skip to content

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 x64

It 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 --explain

It 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 installed

An 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.

toollive verb (costs)on a captured artifactfixed schema
msbuild.nubuild [sln]parse <log>project, file, line, col, severity, code, message
run-tests.nurun <binary>parse <log>suite, test, status, duration_ms, message
crash-triage.nudump <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 – --explain reads the compile-errors lesson slice to annotate error codes, and the SFML 3 guard points at the sfml slice for the full migration notes. Both degrade clean when the memory part is not installed.
  • Fired by hooks – sfml3-guard.nu is a PostToolUse gate, wired through the pack's settings-fragment.json and 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.