fix(doctor): detect environment-installed entry points (no false 'Venv entry point not found')

[andrexibiza]

Related #49529 #68505

What does this PR do?

Fixes hermes doctor's false-positive "Venv entry point not found"
warning on installs where the console entry point lives in the active
environment's scripts dir rather than venv/bin/ or .venv/bin/
(#49529).

Root cause

run_doctor's Command Installation check only looked for the entry point
at PROJECT_ROOT/venv/bin/hermes or PROJECT_ROOT/.venv/bin/hermes.
For a wheel/venv-installed environment, PROJECT_ROOT points inside
site-packages and the console script lives under the environment's
scripts directory (e.g. /srv/hermes/venv/bin/hermes on POSIX,
...\venv\Scripts\hermes.exe on Windows). The check warned "not found"
even though hermes worked, and suggested an editable pip install -e
reinstall that was wrong for that layout.

The fix

• When the source-checkout candidates don't match, consult
  sysconfig.get_path("scripts") on the active venv (detected via
  sys.prefix != base_prefix) and accept the entry point found there.
• A wheel venv's console script is already installed in the active
  environment — requiring a global ~/.local/bin symlink would turn a
  healthy isolated venv into a false failure, so the check now reports
  "Active environment entry point needs no global symlink" instead.
• The --fix path no longer suggests pip install -e '.[all]' for
  wheel-installed environments (that would rewrite the install layout);
  it suggests the correct pip install --force-reinstall hermes-agent.
• The existing "Venv entry point not found" warning + editable-install
  hint remains for genuine source checkouts where the entry point really
  is missing.

Credit

Cherry-picked from #68505 by @YuYigeng (authorship preserved in git
history). The PR was closed without merging; this ships the code with the
conflict against current main resolved.

How to test

pytest tests/hermes_cli/test_doctor_command_install.py -v
# 7 tests: 5 wheel-venv/entry-point regressions + 2 existing (Unix-only,
# skipped on Windows; run in CI's Linux slice)

The new tests cover: wheel venv needs no global symlink (both --fix
modes), wheel venv with missing entry point avoids the editable-install
fix, and the existing source-checkout cases stay intact.

What platforms were tested?

• Windows 11 native: detection logic verified directly (sysconfig scripts
  dir resolves the wheel entry point); the full suite is Unix-only
  (symlink semantics) and runs in CI's Linux slices.
• git diff --check clean; attribution audit clean.

Why this matters to users

Before: hermes doctor on any non-source install falsely reported the
entry point missing and pushed users toward an editable reinstall —
scary, wrong, and potentially destructive to a working layout.

After: doctor recognizes environment-installed entry points, stops
demanding a global symlink for healthy venvs, and suggests the correct
reinstall command when something genuinely is missing.

Fixes #49529

• Bug fix (non-breaking change that fixes an issue)
• New feature
• Breaking change

Checklist

• Code follows repo style (reuses sysconfig, no new env vars)
• Self-review complete
• Tests added (wheel-venv regressions; Unix-only, run in CI)
• Detection logic verified on Windows directly
• git diff --check clean
• Credit: implementation from fix(doctor): detect wheel-installed virtualenv entry points #68505 by @YuYigeng, cherry-picked with authorship preserved

[monerostar]

Native Win11 review (monerostar) — gap on Windows entry-point names

Host: Windows 11 (build 26200). Real Hermes install at
C:\Users\Admin\AppData\Local\hermes\hermes-agent with active venv
...\hermes-agent\venv (Python 3.11.15).

Intent is right

Looking past PROJECT_ROOT/{venv,.venv}/bin/hermes into the active environment's sysconfig scripts dir is the correct fix direction for wheel / non-editable layouts (#49529). The "no global symlink needed when env entry point is the truth" branch is also right.

But the Windows console script is still missed

On this daily-driver install the entry point is hermes.exe, not bare hermes:

sysconfig scripts dir =
  C:\Users\Admin\AppData\Local\hermes\hermes-agent\venv\Scripts

  hermes        → missing
  hermes.exe    → present
  hermes.cmd    → missing
  hermes.bat    → missing

Replaying this PR's detection literally against that env:

PROJECT_ROOT/venv/bin/hermes     → False
PROJECT_ROOT/.venv/bin/hermes    → False
{scripts}/hermes                 → False   # only name the PR checks
{scripts}/hermes.exe             → True    # real entry point
FINAL _venv_bin                  → None
→ still warns "Venv entry point not found"

So on a healthy Windows Hermes install the false positive remains.

Source-checkout path has the same Windows hole

Even when PROJECT_ROOT is the install tree (it has pyproject.toml here), the first loop only probes POSIX venv/bin/hermes. The real file is:

PROJECT_ROOT/venv/Scripts/hermes.exe  → present
PROJECT_ROOT/venv/bin/hermes          → missing

Suggested minimal fix

When building candidates, include the platform script name:

_names = ("hermes.exe", "hermes.cmd", "hermes.bat", "hermes") if os.name == "nt" else ("hermes",)
# for each scripts dir (PROJECT_ROOT/{venv,.venv}/Scripts or bin, plus sysconfig scripts):
#   for name in _names: candidate = dir / name

Also probe Scripts (not only bin) under PROJECT_ROOT/{venv,.venv}/ on Windows.

Tests

Current tests create project/venv/bin/hermes and skip several cases on win32, so CI stays green without covering this layout. A Windows-oriented unit test that plants Scripts/hermes.exe (and asserts no warn) would lock the fix.

Happy to re-verify on this host once .exe / Scripts are in the candidate list — the POSIX/env-scripts half already looks solid.

[andrexibiza]

Thank you for the native Win11 review — the gap is real and now fixed. The environment-scripts detection only checked bare hermes, which misses the actual console script on Windows. Commit 7238551c8 now scans all platform name variants (hermes, hermes.exe, hermes.cmd, hermes.bat) in the sysconfig scripts dir, with two regression tests: the Win11 layout (only hermes.exe present → detected, no false "Venv entry point not found") and the missing-console-script case (still warns). Verified: 2 new tests pass on this host (the 7 existing POSIX tests remain skipped on win32 as marked).

The fix is pushed to the PR branch — PROJECT_ROOT/{venv,.venv}/bin/hermes → venv\Scripts\hermes.exe detection now resolves to True for the daily-driver layout you described.

[andrexibiza]

@monerostar — accepted as the native Windows residual. The candidate search must cover Scripts as well as bin, and Windows names must include hermes.exe, hermes.cmd, and hermes.bat; the current tests do not exercise that native layout because they create POSIX-style paths and skip the relevant Windows cases.

I have recorded the Windows-native regression test as part of the fix surface. This PR is not treated as complete while a healthy Windows install still reports the entry point missing.

Source comment: #77428 (comment)

[monerostar]

Native Win11 re-check (monerostar) — residual closed on tip e6c862d9f

Host: Windows 11 build 26200. Real install
C:\Users\Admin\AppData\Local\hermes\hermes-agent
venv Python 3.11.15, active sysconfig scripts dir = ...\venv\Scripts.

Live layout on this box

venv\Scripts\hermes.exe       present
venv\Scripts\hermes           missing
venv\bin\hermes               missing (POSIX path)

Main vs this PR

• main: the whole Command Installation section is behind if sys.platform != "win32", so Windows never runs entry-point detection and cannot emit the false "Venv entry point not found" from that path.
• PR tip: detection runs on all platforms. On this install it walks hermes → hermes.exe → finds venv\Scripts\hermes.exe and would report OK (Venv entry point exists (venv\Scripts\hermes.exe)). No missing-entry-point warn.

Tests (PR worktree, install venv pytest)

tests/hermes_cli/test_doctor_command_install.py
2 passed, 7 skipped

The two Win-only cases land here: native Scripts\hermes.exe layout, and missing-console-script still warns. Skips are the POSIX symlink cases.

Take

The Win residual from the earlier review is fixed on this tip. Healthy daily-driver install no longer false-fails entry-point detection under the PR logic. Looks good from this host.

[andrexibiza]

Thanks for the native Win11 re-check. I independently ran the targeted doctor tests on the PR tip: 2 passed, 7 skipped (the POSIX-only cases are skipped on Windows), and git diff --check passes. The Scripts\hermes.exe path and Windows console-script variants are covered; this residual is addressed.