hmbown--codewhale/docs/rfcs/FILE_DECOMPOSITION_0_9_0.md

# RFC: File Decomposition for v0.9.0

**Status (2026-07-12): still valuable, needs redesign.** The original
`config.rs` plan was overtaken by events: `config.rs` shrank to ~7.0k lines via
a different module split (`crates/tui/src/config/`), and the provider-churn
problem it targeted was mostly solved by the Models.dev catalog + ProviderLake
(#4184–#4188) rather than by file moves. Meanwhile the render/CLI monoliths
grew — `ui.rs` 9.4k → 13.6k, `main.rs` 8.0k → 12.1k — so any revival of this
RFC should re-scope around `ui.rs` and `main.rs`. The migration method
(§"Migration strategy": git mv + re-exports, no functional changes) remains
the right approach.

## Problem

Six files exceed 5,000 lines. The worst offenders accumulate provider-specific
logic, test code, and UI rendering in single translation units. This makes
provider additions touch 15+ files and makes code review fragile.

### Current state (lines, v0.8.6x era — see status note for v0.8.68 numbers)

| File | Lines | Contents |
|------|-------|----------|
| `crates/tui/src/config.rs` | 10,046 | Provider resolution, env handling, model aliases, capability matrix, 2,000+ lines of tests |
| `crates/tui/src/tui/ui.rs` | 9,400 | TUI render loop, input handling, command dispatch, /logout clearing |
| `crates/tui/src/tui/ui/tests.rs` | 8,360 | Tests for ui.rs |
| `crates/tui/src/main.rs` | 7,998 | CLI arg parsing, mode selection, startup |
| `crates/tui/src/tui/app.rs` | 7,256 | Application state struct and lifecycle |
| `crates/tui/src/runtime_threads.rs` | 5,454 | Async runtime orchestration |

## Proposed decomposition

### 1. `config.rs` → provider module tree

Split `crates/tui/src/config.rs` into:

```
crates/tui/src/config/
├── mod.rs              # Re-exports, Config struct, load/save
├── provider.rs         # ApiProvider enum, parse/as_str/display_name/all
├── capability.rs       # ProviderCapability, provider_capability()
├── model_resolution.rs # wire_model_for_provider, normalize_model_name_for_provider
├── env.rs              # EnvGuard, env var precedence, per-provider env handling
├── constants.rs        # All DEFAULT_*_MODEL and DEFAULT_*_BASE_URL constants
└── tests/              # Test module
    ├── mod.rs
    ├── provider.rs
    ├── capability.rs
    ├── model_resolution.rs
    └── env.rs
```

**Why:** Every new provider currently requires edits to ~20 match arms scattered
across one 10K-line file. With constants in their own module and resolution
logic isolated, adding a provider becomes: add constants, add enum variant, add
one match arm per function. The drift check script can validate each sub-module
independently.

### 2. `ui.rs` → view modules

Split `crates/tui/src/tui/ui.rs` into:

```
crates/tui/src/tui/
├── ui.rs               # Core render loop, frame dispatch (keep under 2,000 lines)
├── input.rs            # Keyboard/mouse input handling
├── command_dispatch.rs # /command routing, /logout, /config
└── status_bar.rs       # Status bar rendering
```

**Why:** The /logout clearing logic, command dispatch, and render loop are
independent concerns. `ui.rs` currently has a 6,200-line function body for
`execute_command_input` that mixes input parsing, command routing, and state
mutation.

### 3. `main.rs` → CLI module

Split `crates/tui/src/main.rs` into:

```
crates/tui/src/cli/
├── mod.rs              # Cli struct, arg parsing
├── args.rs             # Argument definitions
└── startup.rs          # Mode selection, config loading, resume logic
```

**Why:** `main.rs` at 8K lines suggests the CLI definition has outgrown a
single file. Separating arg definitions from startup logic makes the entry
point readable.

### 4. Provider additions should be data-driven

The current provider pattern requires touching:
- `config.rs`: 20+ match arms
- `cli/src/lib.rs`: 4+ match arms
- `agent/src/lib.rs`: static registry
- `tui/provider_picker.rs`: picker list
- `docs/PROVIDERS.md`: registry table
- `config.example.toml`: example section
- `README.md`: env vars table
- `scripts/check-provider-registry.py`: drift check

A data-driven approach would define each provider as a struct with its
constants, env vars, capability metadata, and display name — then derive the
match arms from the data. This is a larger refactor but would reduce provider
additions to a single file change.

## Priority

1. **config.rs decomposition** — highest impact, most provider churn happens here
2. **ui.rs decomposition** — second highest, /logout and command dispatch are independent
3. **Data-driven providers** — aspirational for v0.9.0, requires trait design

## Migration strategy

Each decomposition should be a standalone PR that:
1. Creates the new module tree
2. Moves code with `git mv` (preserves history)
3. Adds `pub use` re-exports in the old file location (zero API change)
4. Runs the full test suite
5. Removes the re-exports in a follow-up PR once consumers are updated

No functional changes in decomposition PRs. Keep them boring.