dev/docs/code-refactor-plan.md

Code/Core Refactor – Wrapper-first Reset Plan

Goals

• Keep upstream codex-* crates pristine so we can fast-forward to openai/codex:main without hand-merging fork logic every time.
• Host all fork-only functionality (binaries, features, modules, assets) under parallel code-* crates that depend on the upstream crates.
• Preserve a working build throughout the transition so we can ship fixes while the migration is underway.

High-Level Strategy

We briefly diverged with piecemeal module copies. To simplify, we will:

What to Avoid

We already tried copying modules into code-* while leaving the originals in codex-*; nothing pointed at the new copies, merges stayed painful, and the workspace exploded in size. This plan keeps the forked tree separate from the start so every step removes upstream churn instead of doubling it.

1. Duplicate the tree once, then freeze upstream

   • Move (via git mv) the existing codex-rs/ working tree into code-rs/ so history follows the forked code.
   • Run a scripted rename that turns every crate/package prefix codex- → code- inside the moved tree (Cargo manifests, feature names, use statements, module paths, tool configs).
   • Update workspace manifests, scripts, and build tooling so the renamed crates compile from their new location. Verify with ./build-fast.sh.

2. Restore upstream into codex-rs/

   • Check out the latest openai/codex:main tree into codex-rs/.
   • Confirm codex-rs/ contains zero fork-only files (just upstream).
   • Keep both trees side by side: code-rs/ (fork) and codex-rs/ (baseline).

3. Bridge and prune incrementally

   • Point binaries and downstream crates at the code-* versions first so the product keeps working.
   • For each fork feature area (TUI, app-server, CLI, core, browser, etc.) decide whether we can extend upstream codex-* code or must keep the forked implementation. Favor reusing large upstream sections where the integration cost is manageable; otherwise, maintain the fork logic and document why it diverges.
   • When we do integrate, prefer targeted extension points or light wrappers instead of one-to-one rewrites, and retire duplicate modules only after the shared path is verified.
   • After each feature area decision, re-run ./build-fast.sh and capture any remaining fork patches in the matching codex-* crate for future cleanup.

4. Ongoing maintenance

   • Pull upstream changes directly into codex-rs/, resolve conflicts only in code-rs/ when APIs shift, and document deltas in docs/fork-enhancements.md.
   • Track remaining wrapper-only surface in a status doc (e.g. docs/tui-module-migration-status.md).

Execution Checklist

1. DONE (2025-10-04): Snapshot current state (branch + optional tag) so we can recover if the reset uncovers regressions. Created snapshot/pre-upstream-reset-20251004 (branch) and snapshot-pre-upstream-reset-20251004 (tag) before upstream restore work begins.
2. DONE (2025-10-04): Duplicate codex-rs/ into code-rs/ so history follows the fork. Bulk-renamed all crates/binaries from codex-* to code-*, fixed module/file names, updated manifests, and confirmed ./build-fast.sh --workspace code passes.
3. DONE (2025-10-04): Update shared tooling (build-fast.sh) to target both workspaces and keep existing codex builds green (./build-fast.sh).
4. DONE (2025-10-04): Audited all scripts, docs, and SDK samples to swap codex-rs/… references over to code-rs/… (see commits touching build-fast.sh, scripts/ci-tests.sh, TypeScript SDK, installation docs).
5. DONE (2025-10-04): Checked out upstream codex-rs/ at openai/codex@d7acd146 and re-ran ./build-fast.sh --workspace codex plus ./build-fast.sh --workspace code to confirm both workspaces build.
6. DONE (2025-10-04): Captured subsystem decisions in docs/subsystem-migration-status.md, highlighting where we will reuse upstream code versus keep fork-specialised wrappers.
7. DONE (2025-10-04): Scheduled recurring code-rs/ dead-code sweeps and documented the cadence in docs/code-dead-code-sweeps.md.
8. DONE (2025-10-04): Opened docs/code-crate-parity-tracker.md to record when forked crates reach parity with upstream so we can delete duplicates ahead of releases.

Tracking

• Maintain per-area migration status docs under docs/.
• Record any upstream patches we must keep in codex-* (policy/legal) so future merges understand why they exist.
• Treat ./build-fast.sh as the sole required validation step after each migration chunk; fix all warnings before landing.