Expand description
Proactive PATH-shadow detection.
The 99% install path is npm install -g symforge. But the symforge that a
bare invocation actually RUNS is whatever comes FIRST on $PATH — which may
be a DIFFERENT, stale install that shadows the one the user just installed:
- a root-owned
/usr/local/bin/symforge(apt/sudo make installleftover), - a Windows npm-global bleeding into a WSL shell via
/mnt/c/..., - an nvm-vs-system prefix mismatch (a “foreign” npm prefix winning on PATH).
When that happens, npm install -g symforge reports success and the registry
shows the new version, yet which symforge keeps resolving the stale shadow.
This module RESOLVES every symforge on $PATH, compares the first hit to
the binary we believe we are, classifies the shadow, and produces a warning
that ends with the EXACT remediation commands. It NEVER executes them.
Pure-ish: PATH/string/path logic plus a single best-effort, bounded version
probe (<shadow> --version) that can never hang. Server-only — wired into
cli::init, cli::update, and protocol health.
Structs§
- Shadow
Report - A resolved PATH-shadow situation: the install we believe we are vs the
install a bare
symforgeinvocation actually runs.
Enums§
- Shadow
Kind - How a PATH-first
symforgethat is NOT our install is shadowing us.
Functions§
- detect_
shadow - Detect whether a stale install shadows
our_binaryon$PATH. - format_
shadow_ warning - A clear, plain-ASCII, multi-line warning ending with EXACT remediation commands tailored to the shadow’s kind, paths, and versions. Never executes anything — the user runs the commands in their own shell.
- format_
shadow_ warning_ compact - One-line compact banner for the compact health surface, where a multi-line block is too heavy. Names the kind and both paths/versions and points at the full warning for the exact commands.
- which_
all - Resolve EVERY
nameon$PATH, in PATH order (first = what a barenameinvocation runs). SplitsPATHby the OS separator; for each directory it checksdir/nameand, on Windows, thePATHEXTvariants (name.exe,name.cmd, …). Only existing regular files are collected. Order is preserved and duplicates are de-duped (a dir repeated on PATH yields one hit).