gh-forgejo-shim Rust Rewrite Plan

This plan tracks a full rewrite of the installed runtime from Python to Rust. The final product should not start Python when Codex, a terminal, or another tool runs gh, gfj, or gh-forgejo-shim.

Epicgh-forgejo-shim-d60 - epic: full Rust rewrite of gh-forgejo-shim runtime

Planninggh-forgejo-shim-qbu - planning: document Rust rewrite implementation plan

RuleThe target is zero Python. Python may be used temporarily as a parity oracle while Rust is being built. Any Python left after phase 10 requires a separate decision bead and cannot be installed runtime code.

Why This Rewrite Exists

The current shim puts Python in front of gh. That adds startup and import cost even when the repo is a normal GitHub repo that should delegate to the real GitHub CLI. Codex can interpret slow or intermediate command states as unavailable branch or pull request state. Rust should make the front door fast and make Forgejo-routed commands native.

Dependency Shape

phase 01
  -> phase 02
       -> phase 03
       -> phase 04
       -> phase 05

phase 03 + phase 04 + phase 05
  -> phase 06
  -> phase 08

phase 06
  -> phase 07

phase 03
  -> phase 09

phase 07 + phase 08 + phase 09
  -> phase 10

Phase Table

Order Bead Priority Depends On Parallel Work Plain English Outcome Subagents
01 gh-forgejo-shim-3sl P0 None None Freeze current Python behavior as the contract so Rust has exact outputs, errors, trace records, and performance budgets to match. Use explorer subagents for contract inventory. One integrator owns final fixtures.
02 gh-forgejo-shim-dqf P1 Phase 01 None Create the Cargo workspace, binaries, and test harness without changing the installed user workflow. Avoid parallel implementers. Use one verifier after scaffold exists.
03 gh-forgejo-shim-gxo P1 Phase 02 Phases 04 and 05 Build the fast native dispatcher so GitHub repos delegate to real gh without Python startup. Split route detection, real gh discovery, and timing verification.
04 gh-forgejo-shim-z9l P2 Phase 02 Phases 03 and 05 Port config and auth so existing host allowlists, env vars, stored tokens, and Keychain behavior keep working. Split config, token discovery, and Keychain/fallback storage.
05 gh-forgejo-shim-98v P2 Phase 02 Phases 03 and 04 Port the Forgejo HTTP client and all GitHub-shaped normalization used by command handlers. Split HTTP client, normalization, and field/jq/template helpers.
06 gh-forgejo-shim-fon P2 Phases 03, 04, and 05 Phase 08 Port read-only gh compatibility: status, list, view, checks, repo view, api user, and issue reads. Split by command family after shared helpers are stable.
07 gh-forgejo-shim-bk1 P3 Phase 06 Phase 08, late phase 09 Port mutating workflows such as PR creation, comments, checkout, issue creation, and auth writes. Split by mutation family; checkout/git subprocess behavior gets its own worker.
08 gh-forgejo-shim-184 P3 Phases 03, 04, and 05 Phase 07 Port setup and diagnostics: doctor, bootstrap, shim install, GUI PATH, trace summary, smoke, and git recorder. Split setup, doctor/bootstrap, trace tools, and macOS GUI PATH.
09 gh-forgejo-shim-ppc P3 Phase 03 Later command phases after binary shape exists Create the Rust-first packaging and release path, including migration from old pipx installs. Split artifacts, CI/release, installer path, and migration docs.
10 gh-forgejo-shim-k1e P4 Phases 07, 08, and 09 None Switch the product to Rust, remove Python runtime code, update docs, and close the epic. Use verifier subagents only. One owner performs deletion and cutover.

What Each Phase Must Protect

GitHub Repositories

GitHub repos must delegate to real gh quickly. The Rust dispatcher must avoid Python startup and must not accidentally route github.com through Forgejo behavior.

Forgejo Repositories

Allowlisted Forgejo repos must keep the GitHub-shaped behavior that Codex expects: PR lists, PR status, repo view, issue views, auth probes, and check rollups.

Existing Users

Current config files, auth files, Keychain entries, and managed shim markers must keep working or have a documented migration command.

Diagnostics

Trace files are part of the debugging contract. Redaction, output sizes, route decisions, and raw git recorder behavior must be preserved.

Final Definition Of Done