Skip to content

refactor: reorganize src/ directory structure (835 files, 0 TS errors)#1583

Merged
piorpua merged 19 commits intomainfrom
refactor/process-structure
Mar 20, 2026
Merged

refactor: reorganize src/ directory structure (835 files, 0 TS errors)#1583
piorpua merged 19 commits intomainfrom
refactor/process-structure

Conversation

@kaizhou-lab
Copy link
Copy Markdown
Collaborator

Summary

  • Reorganize src/ directory structure to comply with the 10-item-per-directory convention
  • Consolidate all main-process modules under src/process/ and shared modules under src/common/
  • Fix all 194 stale import paths globally, achieving 0 TypeScript module-not-found errors

Changes

Phase 1: Module Migration into src/process/

  • Move worker/, webserver/, channels/, extensions/, agent/ from src/ root into src/process/
  • Update all import paths and config aliases (@worker/, @process/)

Phase 2: Root Directory Cleanup

  • Move types/, shared/, adapter/, models/ and loose files into src/common/
  • Move assistant/, skills/, builtinMcp/ into src/process/

Phase 3: Documentation Updates

  • Update docs/tech/architecture.md, docs/conventions/file-structure.md, AGENTS.md

Phase 4: Sub-directory Reorganization

  • src/process/ (24 → 11 items): merge assistant/ + skills/ + builtinMcp/resources/, database/ + i18n/services/, 9 loose .ts files → utils/
  • src/common/ (28 → 8 items): create api/, chat/, config/ groups; flatten nested types/types/

Phase 5: Global Path Fixes

  • Fix 194 TS2307 errors: broken relative paths, stale @process/ aliases, dynamic imports
  • Add barrel index.ts for common/utils/ and process/utils/
  • Fix 2 pre-existing type errors (fsBridge ResourceType, AcpConfigSelector Set type)

Directory Structure (After)

src/
├── common/        (8 items: adapter, api, chat, config, types, update, utils, index.ts)
├── process/       (11 items: agent, bridge, channels, extensions, resources, services, task, utils, webserver, worker, index.ts)
├── renderer/
├── index.ts
└── preload.ts

Related Issue

Closes #1582

Test Plan

  • bunx tsc --noEmit — 0 errors (down from 194 TS2307)
  • bun run test — 92/100 test files pass, 1109/1130 tests pass
  • Remaining 4 failing test files are pre-existing runtime issues (native module loading, database init)
  • Verify electron-vite build succeeds
  • Smoke test the app to confirm runtime behavior

- Move 7 readme translations (readme_{ch,es,jp,ko,pt,tr,tw}.md) to docs/readme/
- Move CODE_STYLE.md, SERVER_DEPLOY_GUIDE.md, WEBUI_GUIDE.md to docs/
- Update all cross-references in readme.md, WEBUI_GUIDE.md, install-ubuntu.sh
- Create lifecycle/ (ExtensionEventBus, hotReload, lifecycle, statePersistence)
- Create sandbox/ (sandbox, sandboxWorker, permissions, pathSafety)
- Create protocol/ (assetProtocol, uiProtocol)
- Move utility resolvers to resolvers/utils/
- Update all imports in source and test files
Bridge subdirectories: conversation/, system/, data/, agent/, platform/
Task subdirectories: managers/, middleware/, worker/
Update all imports in source and test files
- Move skills/ → src/skills/, assistant/ → src/assistant/
- Update electron-builder.yml files and asarUnpack paths
- Update electron.vite.config.ts viteStaticCopy source paths
- Update assistantPresets.ts resourceDir references
- Update initStorage.ts and fsBridge.ts resource resolution
  with fallback paths for both viteStaticCopy and direct inclusion
- Update skillsMarket test paths
- adapter/ → common/adapter/ (cross-process bridge)
- types/ → common/types/ (shared type declarations)
- shared/ → common/ (merge i18n-config.json)
- shims/ → common/shims/ (module alias shims)
- utils/ → process/utils/ (main-process utilities)
- assistant/ → process/assistant/ (static resources)
- skills/ → process/skills/ (static resources)
- Update all import paths and config references
- assistant/ + skills/ + builtinMcp/ → resources/
- database/ + i18n/ → services/
- 9 loose .ts files → utils/
…t paths globally

Common directory restructure:
- api/ ← adapters/, ApiKeyManager.ts, RotatingApiClient.ts, ClientFactory.ts
- adapter/ ← keep + ipcBridge.ts
- chat/ ← chatLib.ts, atCommandParser.ts, imageGenCore.ts, document/, slash/, navigation/, approval/
- config/ ← appEnv.ts, constants.ts, storage.ts, storageKeys.ts, presets/, i18n.ts, i18n-config.json
- types/ ← keep + codex/ (flatten nested types/types/)
- update/ ← keep + updateTypes.ts
- utils/ ← keep + utils.ts + shims/ (add index.ts re-export)
- index.ts

Also fix 194 stale TS2307 module-not-found errors across the entire codebase:
- Fix broken relative paths in process/bridge/, task/, services/, utils/
- Flatten bridge/index.ts subdirectory references (system/, conversation/, agent/, data/, platform/)
- Fix task/ internal paths (managers/, worker/, middleware/ subdirs removed)
- Convert deep relative paths to @/ and @process/ absolute aliases
- Add process/utils/index.ts re-export barrel
- Update all test file import paths
- Fix dynamic import() and type-position import() paths
- fsBridge.ts: add 'assistant' to ResourceType union for dev path resolution
- AcpConfigSelector.tsx: fix type annotation Set<AcpBackend> instead of AcpBackend[]
Adopt main's full-coverage strategy with updated paths for new directory structure:
- src/shims/** → src/common/utils/shims/**
- src/types/** → src/common/types/**
- src/shared/** → src/common/config/i18n-config.json
- architecture/SKILL.md: update decision tree paths to src/process/
- pr-review/SKILL.md: update priority order paths
- codecov.yml: update ignore paths (shims→common/utils/shims, types→common/types)
- renderer/main.tsx: fix adapter/browser import to @/common/adapter/browser
- Fix i18n scripts path: src/shared/ → src/common/config/ (generate-i18n-types.js, check-i18n.js)
- Add ES2023 lib to tsconfig.json for toSorted/toReversed support
- Fix oxfmt formatting across 29 files
- Fix circular dependency in src/process/utils/ (utils.ts ↔ initStorage.ts)
- Fix stale mock paths in tests after directory restructuring:
  - @/process/initStorage → @process/utils/initStorage
  - @/webserver → @process/webserver
  - @process/message → @process/utils/message
  - @process/task/worker/workerTaskManagerSingleton → @process/task/workerTaskManagerSingleton
- Add missing electron mock properties (app, ipcMain) in webuiConfig and cronService tests
- Update src/shared references in AGENTS.md, i18n skill, and architecture skill docs
@piorpua piorpua merged commit 399272f into main Mar 20, 2026
21 checks passed
@kaizhou-lab kaizhou-lab deleted the refactor/process-structure branch March 20, 2026 04:11
kaizhou-lab pushed a commit that referenced this pull request Mar 20, 2026
The refactoring in PR #1583 changed `import { getSystemDir } from
'./initStorage'` to a lazy `require('./initStorage')` to break a
circular dependency. However, Vite/Rollup does not transform dynamic
`require()` relative paths in bundled output, causing
`copyFilesToDirectory` to throw "Cannot find module './initStorage'"
at runtime when `files` is a non-empty or empty array (not undefined).

This broke the second message in ACP conversations because the first
message passes `files: undefined` (skipping the require), while
subsequent messages pass `files: []` (empty array), which reaches the
broken require call.

Replace `require('./initStorage')` with a static import. The circular
dependency between utils.ts and initStorage.ts is safe because
`getSystemDir` is only called at runtime inside function bodies, not
during module initialization. This matches the pre-refactor behavior
that worked correctly.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor: reorganize src/ directory structure to comply with 10-item limit

2 participants