Refactor source boundaries to reduce dependency coupling
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 715
Description
> [!IMPORTANT]
> Reserved for @cv. Do not self-assign this issue. Do not open an implementation PR unless @cv requests help.
## Problem
The source layout has command, action, domain, adapter, and state layers. Transitional folders now contain multiple product concepts and stack layers.
Current examples include:
- `src/lib/onboard/`: 358 production files and about 66,600 lines.
- `src/lib/actions/`: 227 production files and about 50,900 lines.
- `src/lib/state/registry.ts`: more than 100 production dependents.
- `src/lib/onboard.ts`: more than 200 direct runtime dependencies.
- Runtime dependency cycles cross actions, sandbox configuration, shields, messaging, policy, onboarding, and plugin entry code.
Large flat folders make ownership unclear. Broad modules increase change impact and test scope. Runtime cycles make module initialization order part of behavior.
## Desired outcome
Use feature ownership first. Use explicit layers inside each feature.
Keep these repository-wide layers:
- `src/commands/` for oclif command adapters.
- `src/composition/` for dependency wiring.
- `src/platform/` for Docker, OpenShell, process, filesystem, and HTTP adapters.
- `src/cli/` for CLI framework and presentation code.
- `src/foundation/` for dependency-light primitives.
Put product behavior under feature-owned modules such as onboarding, sandboxes, inference, messaging, policy, shields, sessions, MCP, and credentials.
## Constraints
- Preserve supported behavior and persisted data formats.
- Use compatibility exports only for current consumers.
- Do not add a new integration or product surface.
- Keep PRs issue-scoped and mechanically reviewable.
- Add guardrails before structural changes.
- Ratchet each measured hotspot downward.
- Keep runtime dependency graphs acyclic.
- Require cross-feature imports to use an explicit public module.
## Work sequence
1. Add dependency guardrails and baseline ratchets (#7692).
2. Remove bounded runtime dependency cycles (#7693).
3. Split the sandbox registry into narrow persistence seams (#7694).
4. Eliminate the remaining runtime dependency cycles (#7745).
5. Decompose onboarding into phase composition (#7695).
6. Move sandbox actions into feature-owned application modules (#7696).
7. Separate shipped runtime assets from contributor tooling (#7697).
8. Complete OpenClaw agent artifact co-location (#7698).
9. Reorganize integration tests by feature and contract (#7699).
Items 1 through 4 are complete. Item 5 is in progress.
Item 5 has these remaining phases:
- Extract messaging application ownership (#9170).
- Extract gateway lifecycle ownership (#9171).
- Extract provider selection and review ownership after the current gateway PR (#9169). PR #9037 resolved the prior dependency.
- Enforce the zero-decision entry boundary after #9169 (#9172).
Items 6 through 9 remain open.
## Completion criteria
- Guardrails report file fan-in, fan-out, cycles, and flat-folder counts.
- Ratchets prevent a measured hotspot from increasing.
- Runtime dependency cycles are absent from production TypeScript.
- High fan-in modules expose narrow and stable contracts.
- Composition roots contain dependency wiring and no product decisions.
- Transitional root-file counts decrease to zero or an approved remainder.
- Targeted tests and architecture checks pass for each PR.
Contributor guide
Assessment
This issue has not been assessed yet.