2026-05-31 Repository implementation Issue gh-forgejo-shim-1e9

Added macOS fj auth discovery for Codex.app

The shim now reads the current fj CLI macOS auth file, so GUI apps can find Forgejo tokens without inheriting shell-only environment variables.

Summary

Fixed Codex.app token visibility by adding ~/Library/Application Support/Cyborus.forgejo-cli/keys.json to the auth discovery path. This lets gh-forgejo-shim doctor report auth as found inside Codex even when FJ_SHIM_TOKEN, FORGEJO_TOKEN, GITEA_TOKEN, and FJ_TOKEN are absent from the process environment.

Changes Made

Auth discovery

Added the macOS fj keys file to the candidate list before Linux-style config locations. Existing env token precedence is unchanged.

Documentation

Updated configuration docs to explain the macOS fj path and why it matters for GUI apps.

Tests

Added auth tests covering env token precedence, macOS keys JSON discovery, and env-over-file behavior.

Context

The user's normal terminal saw a Forgejo token, but this Codex process did not. Relaunching Codex only helps if the token is set in the environment inherited by macOS GUI apps. The better product behavior is to read the token from fj's own persisted auth store.

The inspected local file shape was redacted during analysis. No token value was printed or copied into source, tests, or documentation.

Important Implementation Details

Env tokens still win in this order: FJ_SHIM_TOKEN, FORGEJO_TOKEN, GITEA_TOKEN, FJ_TOKEN.
The macOS fj config is JSON and stores per-host entries under hosts.
The existing recursive token finder handles that JSON shape without a new parser.

Relevant Diff Snippets

The snippet below uses the Diffs FileDiff component when available, with a static fallback. Reference: Diffs documentation.

macOS fj config candidate

candidates = [
    base / "Library" / "Application Support" / "Cyborus.forgejo-cli" / "keys.json",
    base / ".config" / "fj" / "config.json",
    base / ".config" / "fj" / "config.yml",
]

Expected Impact for End-Users

Users who already logged in with fj auth login or fj auth add-key on macOS should not need to expose a token through GUI app environment variables. Codex.app can run the shim and discover Forgejo auth through the same persisted fj config.

Validation

python3 -m unittest: passed, 37 tests.
python3 -m compileall -q src tests: passed.
Source-version doctor smoke test with all token env vars removed: [ok] auth token: found.

Issues, Limitations, and Mitigations

The installed pipx copy needs to be refreshed before the normal command sees this fix.
This does not implement native shim login, which remains intentionally out of V1 scope.
If future fj versions move their macOS auth file, the candidate list may need another path.

Follow-up Work

No new follow-up Beads issues were needed for this focused auth-discovery fix.