2026-05-31 Repository implementation Issue gh-forgejo-shim-5ab

Fixed the PR status JSON shape Codex.app expects

gh pr status --json ... now returns the GitHub CLI-style status envelope instead of a bare pull request object, which gives Codex.app the currentBranch data it probes for.

Summary

Codex.app moved from GitHub CLI unavailable to Checking PR status, then ended at Pull request status unavailable. The likely cause was a compatibility mismatch: the shim routed gh pr status, but returned the wrong JSON shape. This change makes status output match the GitHub CLI envelope used by PR-status integrations.

Changes Made

Status envelope

Added status_for_current_branch so pr status --json returns currentBranch, createdBy, and needsReview.

Formatting tolerance

Added simple --jq support for dotted field lookups such as .currentBranch.url, plus parser support for --template flags.

Regression coverage

Added tests for present and missing current-branch PRs, the status envelope, and simple jq field selection.

Context

The T3 Code.app screenshot showed plain Git availability, not GitHub CLI or PR availability. That suggests T3 may only expose version-control basics, while Codex.app appears to run a separate gh pr status probe. The shim fix targets the Codex.app path and does not assume T3 will display PR metadata.

Important Implementation Details

gh pr view --json ... still returns a single pull request object or {}.
gh pr status --json ... now returns a status object with currentBranch.
The jq support is intentionally small: it handles simple dotted selectors and // empty.
The shim continues to avoid full GitHub CLI emulation; unsupported deep formatting remains outside V1 scope.

Relevant Diff Snippets

The snippets below use the Diffs FileDiff component when available, with static fallbacks. Reference: Diffs documentation.

Status envelope helper

def status_for_current_branch(
    pull: dict[str, Any] | None,
    fields: tuple[str, ...],
) -> dict[str, Any]:
    normalized = None if pull is None else filter_fields(normalize_pull(pull), fields)
    return {
        "currentBranch": normalized,
        "createdBy": [],
        "needsReview": [],
    }

Status route output

if pull is None:
    if parsed.json_fields:
        _print_json_or_jq(status_for_current_branch(None, parsed.json_fields), parsed.jq, stdout)
    return 0

if parsed.json_fields:
    _print_json_or_jq(status_for_current_branch(pull, parsed.json_fields), parsed.jq, stdout)

Expected Impact for End-Users

Codex.app should have a better chance of resolving pull request status for allowlisted Forgejo repositories because the shim now returns the bucketed JSON structure it expects from gh pr status. Terminal behavior for gh pr view and gh pr create is unchanged.

Validation

python3 -m unittest: passed, 42 tests.
git diff --check: passed.
PYTHONPATH=src python3 -m gh_forgejo_shim gh pr status --json number,title,url --jq .currentBranch.url: exited 0 in source-tree smoke testing.
python3 -m gh_forgejo_shim ... without PYTHONPATH=src failed because the package was not installed into that interpreter; this was a source-tree invocation issue, not a shim behavior failure.

Issues, Limitations, and Mitigations

The change does not prove T3 Code.app will show PR state, because its UI only reported plain Git availability.
--jq support is intentionally limited to simple selectors. Complex jq programs should still use the real GitHub CLI path.
--template is parsed so integrations do not fail on the flag, but full Go-template rendering is not implemented.

Follow-up Work

No additional Beads issue was filed. If Codex.app still reports unavailable status after reinstalling this shim, the next useful step is to capture the exact gh command and stdout/stderr that Codex.app runs during its PR-status probe.