Skip to main content

Module path_shadow

Module path_shadow 

Source
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 install leftover),
  • 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§

ShadowReport
A resolved PATH-shadow situation: the install we believe we are vs the install a bare symforge invocation actually runs.

Enums§

ShadowKind
How a PATH-first symforge that is NOT our install is shadowing us.

Functions§

detect_shadow
Detect whether a stale install shadows our_binary on $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 name on $PATH, in PATH order (first = what a bare name invocation runs). Splits PATH by the OS separator; for each directory it checks dir/name and, on Windows, the PATHEXT variants (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).