Native Auth Helpers For gh-forgejo-shim

Summary

Implemented gh-forgejo-shim auth login/import/status/logout. Login and import validate tokens with Forgejo, save them in shim-owned storage, and add the host to the allowlist so routed gh pr, gh issue, and gh repo commands can use the token from GUI-launched apps.

Changes Made

• Added native auth storage helpers in auth.py, including macOS Keychain support through security and a 0600 fallback file at ~/.config/gh-forgejo-shim/auth.json.
• Added token source discovery with source labels, host-specific import behavior, stored-token lookup, status checks, and logout deletion.
• Added ForgejoClient.get_current_user for lightweight token validation through /api/v1/user.
• Added the auth CLI group and prompt handling for optional hosts and hidden token entry.
• Updated routed gh behavior indirectly by making discover_fj_token read stored shim auth after env vars.
• Updated doctor, bootstrap, README, configuration docs, rollback docs, and contributing guidance.
• Added focused tests for storage permissions, host-specific discovery, CLI login/import/status/logout, and bootstrap repair hints.

Context

Before this change, the shim could find tokens from env vars and a few existing Forgejo CLI config files, but it could not manage its own auth. That left GUI-launched apps such as Codex dependent on inherited shell state or unrelated tool config. The new commands make auth a direct shim setup step.

Important Implementation Details

• Env vars still win for the current process: FJ_SHIM_TOKEN, FORGEJO_TOKEN, GITEA_TOKEN, then FJ_TOKEN.
• Stored shim auth is checked after env vars and before best-effort external config discovery.
• Host-specific external discovery no longer falls back to unrelated tokens from other hosts.
• auth login and auth import validate before writing storage, then call config add-host behavior.
• auth status never prints token values. It distinguishes durable shim auth from env or external config tokens that should be imported for GUI use.
• auth logout removes shim-owned auth only; it does not edit env vars or third-party CLI config files.

Relevant Diff Snippets

This intentionally excerpted, server-rendered patch shows the core auth storage and CLI surfaces. The full diff also includes docs and test coverage.

Expected Impact for End-Users

Users can run gh-forgejo-shim auth login git.example.com once, restart GUI tools if needed, and then use normal GitHub-style commands such as gh pr view, gh pr create, and gh pr status in Forgejo repositories without exporting tokens into each shell or app launch environment.

Validation

• python3 -m unittest: 82 tests passed.
• python3 -m compileall -q src tests: passed.
• PYTHONPATH=src python3 -m gh_forgejo_shim auth --help: confirmed the auth command group exposes login, import, status, and logout.
• PYTHONPATH=src python3 -m gh_forgejo_shim auth status git.example.invalid: confirmed unrelated host configs are not treated as valid auth.
• git diff --check: passed before turn document generation.

Issues, Limitations, and Mitigations

• Validation currently builds Forgejo API URLs with HTTPS, matching the existing repository URL assumptions in the shim. Local HTTP-only Forgejo installs may need a future explicit option.
• macOS Keychain writes can fail because of local keychain policy or prompts. The implementation falls back to the owner-only auth file and reports the storage location.
• auth status reports token availability without live validation, so it remains fast and secret-safe. Login/import perform live validation before saving.

Follow-up Work

No required follow-up issue was filed for this turn. A future enhancement could add explicit validation URL options for HTTP-only or self-signed local Forgejo instances if users run into that environment.