Module pathutil 

Functions

is_broad_or_unsafe_root

Returns true if the directory is too broad to be a valid project root. Rejects home directory, filesystem root, . (bare CWD), and agent sandbox directories (.claude, .codex). Used to prevent writing project-scoped data (overlays, policies) into the global ~/.lean-ctx/ data directory.

is_data_dir_collision

Returns true if project_root collides with the lean-ctx data directory. This prevents project-scoped files (overlays.json, policies.json) from being written into ~/.lean-ctx/ or ~/.config/lean-ctx/.

normalize_tool_path

Normalize paths from any client format to a consistent OS-native form. Handles MSYS2/Git Bash (/c/Users/... -> C:/Users/...), mixed separators, double slashes, and trailing slashes. Uses forward slashes for consistency.

safe_canonicalize

Canonicalize a path and strip the Windows verbatim/extended-length prefix (\\?\) that std::fs::canonicalize adds on Windows. This prefix breaks many tools and string-based path comparisons.

safe_canonicalize_bounded

Canonicalize with a timeout guard. Protects against hangs on WSL2 DrvFS, Windows reparse points, NFS, FUSE, sshfs, and other slow filesystems. Falls back to the original path if canonicalize doesn’t complete within the timeout. Self-healing: after a timeout, subsequent calls to slow mounts skip the thread entirely.

safe_canonicalize_or_self

Like safe_canonicalize but returns the original path on failure.

safe_project_data_dir

Returns the project-scoped .lean-ctx/ directory if the project root is safe. Returns Err if the project root collides with the global data directory.

strip_verbatim

Remove the \\?\ / //?/ verbatim prefix from a PathBuf. Handles both regular verbatim (\\?\C:\...) and UNC verbatim (\\?\UNC\...).

strip_verbatim_str

Remove the \\?\ / //?/ verbatim prefix from a path string. Returns Some(cleaned) if a prefix was found, None otherwise.