Porting Test Drive II from SNES to PC, Part 6: Portable tooling, not personal tooling

One of the cleanup gates in this repo looked trivial at first:

"Remove hard-coded personal Mesen paths from promoted scripts and Makefiles."

It sounds like housekeeping. It was not.

This is the kind of problem that makes a reverse-engineering repo quietly less reusable over time. The code still works on one machine, the docs still look plausible, and the examples still run for the person who wrote them. But the project stops being portable in practice.

That is exactly the kind of debt that compounds.

The actual wrappers were already in decent shape

The interesting part of this checkpoint is that the runtime wrappers themselves were mostly not the problem anymore.

For example:

• validation/run_mesen_capture.sh already resolves Mesen via:
  • MESEN_BIN
  • MESEN_RELEASE_DIR/Mesen
  • Mesen or mesen on PATH
• tools/run_mesen_ppu_extract.sh already derives the release directory from:
  • MESEN_BIN
  • MESEN_RELEASE_DIR
  • PATH

That means the real portability leak had shifted.

The repo was still carrying machine-specific assumptions in the promoted tooling surface:

• README command examples
• explanatory notes about where Mesen "normally" lived
• usage snippets copied forward from one working environment

That is an important distinction.

The code path can be portable while the documented workflow is still personal.

If the examples tell every future contributor to use one person's home directory, then the project is not actually portable yet.

The repo needed a guard, not just cleaner prose

This checkpoint is commit 3e10bbc on 2026-03-20.

The key addition is small:

• tools/check_portability_paths.py
• make -C tools portability-path-check

That check now fails if the promoted tooling surface reintroduces personal-machine paths like:

• /home/nivando-soares/...
• specific local Mesen release tree assumptions
• local download-folder references

That matters more than it might seem.

Without a guard, cleanup notes drift back into the repo one copied command at a time.

With a guard, the project can now say something enforceable:

"Promoted scripts, Makefiles, and the main tooling READMEs are expected to stay machine-agnostic."

That is a much stronger contract than "we should try to remember not to do that again."

The docs were part of the bug

The README updates in this checkpoint are not cosmetic.

The repo now documents the Mesen path model in terms of portable inputs:

• MESEN_BIN
• MESEN_RELEASE_DIR
• PATH

And the examples now use:

• repo-relative output prefixes like tools/out/...
• generic placeholders like /path/to/mesen/release

instead of hard-coded home-directory paths.

That is the right boundary for a project like this.

The repo should describe:

• what environment variable or CLI input is needed
• what output tree gets written
• what command shape is expected

It should not silently encode the author's workstation layout as part of the interface.

This checkpoint was intentionally scoped

There is an important nuance here.

This checkpoint does not mean the entire repository is now free of absolute paths.

Historical generated artifacts and some long-form docs still include absolute paths inside committed evidence bundles or older notes. Those are real cleanup candidates, but they are a different problem.

This checkpoint closed a narrower and more important gate:

• the promoted tooling surface is now portable by default
• the main wrapper behavior is documented in portable terms
• the repo now has a machine check to stop regressions

That is enough to move the cleanup track forward without pretending every historical artifact was rewritten in the same pass.

That kind of scope control matters. Cleanup work gets noisy fast when a repo mixes:

• active tooling contracts
• historical evidence bundles
• generated outputs
• old narrative notes

This checkpoint chose the surface that actually affects daily use and future regressions.

That was the right tradeoff.

Why this matters to the port itself

This is not just "developer experience."

The port plan is now deep enough into the intro/bootstrap/composition work that tooling portability changes the project velocity directly.

The active roadmap still includes:

• the 958..977 bootstrap gap
• the 986+ final-screen composition gap
• more callback-family replacement beyond frame 1093
• validation output hardening

All of that work depends on being able to trust the tooling layer.

If the tooling surface is machine-specific, then every future run has extra friction:

• "Which Mesen build did this assume?"
• "Is this path part of the workflow or just one person's shell history?"
• "Can another machine reproduce this without editing the command first?"

Those are wasted questions.

The better outcome is what this checkpoint moved toward:

• the wrapper behavior is explicit
• the environment contract is explicit
• the path assumptions are explicit
• regressions are caught automatically

That is the sort of infrastructure work that keeps archaeology and runtime work moving instead of stalling on setup drift.

The next cleanup target is more interesting

With the ignore-policy checkpoint and the portability-path checkpoint both in place, the cleanup track is now in better shape:

• generated output is quieter by default
• promoted tooling is less personal and more reproducible

The next valuable hardening target is not "more path cleanup."

It is validation isolation:

• stop leaning on mutable shared LuaScriptData output as the default surface
• keep moving toward per-run outputs and clearer machine-readable contracts

That is where the repo can buy more real leverage now.

But it was still worth stopping to close this path issue properly first.

Because portability is one of those properties that only looks minor right up until the day the tooling stops being transferable.

This checkpoint makes that less likely.