code-yeongyu / code-yeongyu/oh-my-openagent

[Architecture] Resolving V8 initialization races by decoupling the internal shared barrel

Open
#3,989 2 comments 0 reactions 1 assignee Claimed by @code-yeongyu View on GitHub
enhancement triage:needs-investigation
Dominant language
TypeScript
Stars
69.2k
Forks
5.7k
Avg merge
3h 2m
Merged PRs (30d)
620

Description

### Context & Motivation

First of all, amazing work on the recent architectural updates! As the `oh-my-openagent` project scales with more complex asynchronous features (like background agents and loaders), the module resolution graph has naturally grown quite large.

While running some codebase graph analysis, I noticed that the centralized `src/shared/index.ts` barrel file is currently acting as a massive bottleneck, generating **91 circular dependency chains** across the `src/` directory.

While the `CONTRIBUTING.md` correctly encourages the Barrel Pattern for clean public APIs, utilizing it for *internal cross-module imports* (especially for low-level utilities like `logger` or `normalizeSDKResponse`) creates unintended consequences in Node.js/Bun.

### The Technical Impact

When a core file imports a basic utility from `../shared`, the engine inadvertently evaluates the entire high-level dependency tree bound to that barrel. This leads to:
1. **Temporal Dead Zones (TDZ) & Race Conditions**: Unpredictable module initialization order, which can cause subtle runtime bugs during CLI startup or Agent spawning.
2. **Brittle Test Suites**: Module mocks (in `bun test`) become highly unstable or leak because the barrel loads unexpected files into the test environment.

### Proposed Solution: Internal Leaf-First Decoupling

I propose a slight optimization to the current convention: **Keep barrels for external/public APIs, but enforce direct leaf-file imports for internal wiring.**

**Example:**
Instead of:
```typescript
import { log } from "../shared"
```
We optimize to:
```typescript
import { log } from "../shared/logger"
```

I have mapped the graph and ran an AST script to safely perform this decoupling across the ~180 affected files. The circular dependency count drops from 91 to 0 for these paths, and `bun run typecheck` remains pristine (0 errors).

👉 **I have opened a PR implementing this architecture below for your review.**

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.