nvm: Node versions and shell state
A learning project for nvm: visualize runtime intent without changing the machine
Design a proposed read-only PATH and .nvmrc explorer that separates syntax, resolution and execution and avoids unsafe automatic installation.
What you will learn
- Teach the state transitions with synthetic inputs
- Keep read-only learning separate from provisioning
- Build on fixtures, then test understanding
Before you start
- Basic shell commands and process environments
- Distinguish runtime installation from runtime selection
Diagnose requested versus active Node versions and design explicit setup and verification boundaries.
Key takeaways
- Separate requested, available, selected and running states.
- Synthetic visualization must not silently become installation automation.
- Evaluate understanding of precedence before adding animation complexity.
Teach the state transitions with synthetic inputs
A useful educational extension could display a requested version, available-version inventory, incoming PATH and the transformed path side by side. Show each search entry in order and identify which executable would be considered first under the simplified model. Label aliases and shell functions as additional resolution layers rather than pretending a string diagram can inspect every real shell.
A second view could parse synthetic .nvmrc content and show comments removed, the returned bare request and the separate unresolved availability question. The unknown-string fixture is especially useful: a learner should recognize successful parsing without concluding that installation succeeded. This is a proposed interface, not a feature shipped by nvm or by this article.
Keep read-only learning separate from provisioning
Do not load a user profile, source arbitrary shell files or install the typed version merely to produce a visualization. Use explicit synthetic examples first. If importing real environment data is later added, make that action local and optional, redact personal paths and never collect authorization headers or other credentials.
An accessible ordered list and SVG diagram can explain precedence and state transitions without a 3D engine. A Three.js scene would need a demonstrated learning benefit to justify its additional interaction and rendering work. The essential test is whether a reader can predict a shadowed command or distinguish requested from active version.
Build on fixtures, then test understanding
The 16 helper cases can seed regression expectations for empty paths, preserved prefixes, duplicate entries and parser failures. Keep the source revision visible and explain that the diagnostic adapter does not reproduce upstream color formatting. If a model disagrees with a newly inspected revision, show a versioned difference rather than silently changing the lesson.
A sensible next milestone is a keyboard-operable static prototype with complete language labels, followed by learner prediction tasks. No interactive application, measured learning improvement or automated environment repair was delivered here. The chapter SVG illustrates the proposed workflow, while the source experiment establishes only the narrower transformations already executed.
Implementation steps
- 1
Define synthetic PATH and .nvmrc fixtures.
- 2
Show parsing and availability as distinct states.
- 3
Build a keyboard-readable explanation without executing user input.
- 4
Version the model and test learners’ predictions.
Copy-ready example
{
"proposal": "read-only runtime intent explorer",
"status": "not implemented",
"sourceUserProfiles": false,
"installTypedVersion": false,
"collectCredentials": false,
"learningTask": "distinguish request, resolution and active process"
}Frequently asked questions
Is the explorer available in nvm now?
No. It is an editorial proposal based on the inspected source and bounded fixtures, not an existing product interface.
Why start with SVG instead of Three.js?
Ordered paths and state transitions are well suited to accessible 2D explanations. Extra rendering complexity should follow demonstrated educational value.
Sources
- nvm.shSource checked 2026-09-08
- test/fast/Unit tests/nvm_change_pathSource checked 2026-09-08
- test/fast/Unit tests/nvm_strip_pathSource checked 2026-09-08