alex/headquarter
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d472c4109291a4056afa53d7248b92cb5c44c418
headquarter/openspec/changes/reorganize-long-files/tasks.md
T
Developer d472c41092 docs: add OpenSpec spec for reorganize-long-files 
Create SDD proposal, spec, and tasks for splitting monolithic pages
and routers into focused components and services.

Targets:
- Frontend pages: 50-150 lines max (from 300-1600)
- Backend routers: 300-400 lines max (from 800-2900)
- Follow main branch pattern: thin pages + extracted components

Quality gates: tsc, build, py_compile, file size limits
2026-06-05 10:19:27 +00:00

5.1 KiB
Raw Blame History

Phase 0: Preparation

  • 0.1 Verify dev builds cleanly (backend py_compile, frontend tsc + vite build)
  • 0.2 Document current file sizes for before/after comparison
  • 0.3 Create component directory stubs if missing:
    • apps/web/src/components/features/tool-workshop/
    • apps/web/src/components/features/config-profiles/
    • apps/web/src/components/features/terminal/
    • apps/web/src/components/features/settings/
    • apps/web/src/components/features/ssh-keys/
    • apps/api/src/services/git/operations.py (extract from router)
    • apps/api/src/services/config/crud_service.py
    • apps/api/src/services/config/resolver_service.py

Phase 1: Backend — Router Slimming

1.1 Terminal WebSocket Extraction

  • 1.1.1 Create api/tool/terminal.py from terminal WebSocket handlers in api/tool/tool_instances.py
  • 1.1.2 Move _handle_terminal_websocket, _get_user_from_websocket, SessionRef class
  • 1.1.3 Update main.py to include terminal_router from api.tool.terminal
  • 1.1.4 Remove terminal routes from api/tool/tool_instances.py
  • 1.1.5 Verify py_compile passes

1.2 Instance Lifecycle Extraction

  • 1.2.1 Create api/tool/tool_lifecycle.py for start/stop/restart/delete endpoints
  • 1.2.2 Extract lifecycle endpoints from api/tool/tool_instances.py
  • 1.2.3 Update main.py to include lifecycle router
  • 1.2.4 Verify py_compile passes

1.3 Git Repository Router

  • 1.3.1 Create services/git/operations.py for git command orchestration
  • 1.3.2 Extract clone_repo, fetch_repo, pull_repo, push_repo, merge_repo, commit_repo helpers
  • 1.3.3 Update api/project/git_repositories.py to call service functions
  • 1.3.4 Verify py_compile passes

1.4 Config Profile Router

  • 1.4.1 Extract CRUD helpers into services/config/crud_service.py
  • 1.4.2 Extract resolver helpers into services/config/resolver_service.py
  • 1.4.3 Update api/config/config_profiles.py to call services
  • 1.4.4 Verify py_compile passes

Phase 2: Frontend — Tool Workshop Page

  • 2.1 Extract ToolTypesTab from pages/ToolWorkshopPage.tsx into components/features/tool-workshop/ToolTypesTab.tsx
  • 2.2 Extract ToolConfigsTab into components/features/tool-workshop/ToolConfigsTab.tsx
  • 2.3 Extract ConfigFoldersTab into components/features/tool-workshop/ConfigFoldersTab.tsx
  • 2.4 Slim pages/ToolWorkshopPage.tsx to ~80 lines (tab switcher only)
  • 2.5 Update imports in all consumers
  • 2.6 Verify tsc --noEmit and npm run build pass

Phase 3: Frontend — Config Profiles Page

  • 3.1 Extract ConfigProfileListView into components/features/config-profiles/ConfigProfileListView.tsx
  • 3.2 Extract ConfigProfileDetailView into components/features/config-profiles/ConfigProfileDetailView.tsx
  • 3.3 Extract ConfigProfileEditForm into components/features/config-profiles/ConfigProfileEditForm.tsx
  • 3.4 Extract ConfigProfileMobileView into components/features/config-profiles/ConfigProfileMobileView.tsx
  • 3.5 Slim pages/ConfigProfilesPage.tsx to ~80 lines
  • 3.6 Update imports
  • 3.7 Verify tsc --noEmit and npm run build pass

Phase 4: Frontend — Terminal Page

  • 4.1 Extract TerminalSessionManager (tabs + auto-create) into components/features/terminal/TerminalSessionManager.tsx
  • 4.2 Extract MobileTerminalOverlay into components/features/terminal/MobileTerminalOverlay.tsx
  • 4.3 Extract fullscreen keyboard shortcut handler into hooks/use-terminal-shortcuts.ts
  • 4.4 Slim pages/TerminalPage.tsx to ~80 lines
  • 4.5 Update imports
  • 4.6 Verify tsc --noEmit and npm run build pass

Phase 5: Frontend — Settings & SSH Keys Pages

  • 5.1 Extract SettingsNavigation into components/features/settings/SettingsNavigation.tsx
  • 5.2 Slim pages/SettingsPage.tsx to ~80 lines
  • 5.3 Extract SSHKeyList into components/features/ssh-keys/SSHKeyList.tsx
  • 5.4 Extract SSHKeyCreateForm into components/features/ssh-keys/SSHKeyCreateForm.tsx
  • 5.5 Slim pages/SshKeysPage.tsx to ~80 lines
  • 5.6 Verify tsc --noEmit and npm run build pass

Phase 6: Frontend — Projects & Repo Workspace Pages

  • 6.1 Extract ProjectList into components/features/project/ProjectList.tsx
  • 6.2 Extract ProjectCreateDialog into components/features/project/ProjectCreateDialog.tsx
  • 6.3 Extract ProjectEditDialog into components/features/project/ProjectEditDialog.tsx
  • 6.4 Slim pages/ProjectsPage.tsx to ~100 lines
  • 6.5 Extract WorkspaceLayout into components/features/workspace/WorkspaceLayout.tsx
  • 6.6 Slim pages/RepoWorkspacePage.tsx to ~150 lines
  • 6.7 Verify tsc --noEmit and npm run build pass

Phase 7: Integration and Verification

  • 7.1 Run backend py_compile on all files
  • 7.2 Run frontend npm run typecheck
  • 7.3 Run frontend npm run build
  • 7.4 Run frontend tests: npm test
  • 7.5 Verify file size targets met (pages ≤ 150, routers ≤ 400)
  • 7.6 Verify no 404s or import errors in browser console
  • 7.7 Manual smoke test: create project, start terminal, open config profiles
Reference in New Issue View Git Blame Copy Permalink