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.