2026-05-31 Repository implementation Issue gh-forgejo-shim-bjt

Relaxed the shim PATH doctor check

The doctor command now checks whether the managed shim is the first executable named gh, instead of requiring ~/.local/bin to be the first directory in PATH.

Summary

Fixed a false warning in gh-forgejo-shim doctor. The user had ~/.local/bin before the real Homebrew gh, but other harmless directories appeared earlier in PATH. That should be valid because none of those earlier directories provided gh.

Changes Made

Doctor behavior

Replaced the directory-first check with executable resolution. The shim path passes when ~/.local/bin/gh is the first runnable gh found in PATH.

Safety checks

The doctor now warns when the file at the shim location exists but is not managed by this project, or when another gh executable resolves before the managed shim.

Tests

Updated doctor tests to cover harmless earlier PATH directories, a competing earlier gh, and an unmanaged file at the shim path.

Context

The user's shell has Codex, npm, and bun paths before ~/.local/bin. That is common and does not matter unless one of those directories contains a gh executable. The old doctor logic treated that layout as suspicious even when which -a gh showed the shim winning correctly.

No changes were made to /Users/kell/.zshrc.

Important Implementation Details

run_checks still verifies the wrapper exists and is marked as managed by gh-forgejo-shim.
The first executable named gh is found by scanning PATH in shell order.
Path.samefile is used when possible so equivalent paths compare correctly.

Relevant Diff Snippets

The snippet below is rendered with the Diffs FileDiff component when available, with a static fallback for offline viewing. Reference: Diffs documentation.

Doctor shim path check

if wrapper.exists() and is_managed_shim(wrapper):
    first_gh = _first_program("gh", values.get("PATH", ""))
    if first_gh and _same_file(first_gh, wrapper):
        detail = f"{wrapper} is the first gh in PATH"
        ok = True
    elif first_gh:
        detail = f"gh resolves to {first_gh} before {wrapper}"
        ok = False

Expected Impact for End-Users

Users no longer need ~/.local/bin to be literally first in PATH. The setup is considered healthy as long as the managed shim is the first gh command the shell would run.

Validation

python3 -m unittest: passed, 34 tests.
python3 -m compileall -q src tests: passed.
Source-version doctor smoke test against the user's current PATH shape reported [ok] shim path: /Users/kell/.local/bin/gh is the first gh in PATH.

Issues, Limitations, and Mitigations

The installed pipx copy must be refreshed before the user's normal gh-forgejo-shim doctor command sees this fix.
The local smoke test did not use the user's auth token because the agent shell did not inherit it; auth behavior was not changed in this task.

Follow-up Work

No new follow-up Beads issues were needed for this targeted bug fix.