headquarter/openspec/changes/reorganize-long-files/tasks.md

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: CSS Reorganization

2.1 Restore styles/ Directory Structure

• 2.1.1 Create styles/ directory
• 2.1.2 Extract styles/tokens.css from styles.css — CSS custom properties
• 2.1.3 Extract styles/global.css from styles.css — global reset, body, shell layout
• 2.1.4 Extract styles/utilities.css from styles.css — utility classes (.stack, .card, .muted, .dialog, etc.)
• 2.1.5 Extract styles/syntax-highlight.css from styles.css — code highlighting
• 2.1.6 Update main.tsx to import: styles/tokens.css, styles/global.css, styles/utilities.css, styles/syntax-highlight.css
• 2.1.7 Verify build passes

2.2 Restore Page-Specific CSS

• 2.2.1 Extract styles/pages/dashboard.css from styles.css
• 2.2.2 Extract styles/pages/projects.css from styles.css
• 2.2.3 Extract styles/pages/sessions.css from styles.css
• 2.2.4 Extract styles/pages/settings.css from styles.css
• 2.2.5 Extract styles/pages/ssh-keys.css from styles.css
• 2.2.6 Extract styles/pages/git-history.css from styles.css
• 2.2.7 Extract styles/pages/repo-workspace.css from styles.css
• 2.2.8 Update each page to import its page CSS
• 2.2.9 Verify build passes

2.3 Restore Component CSS Modules

• 2.3.1 Create components/features/terminal/TerminalComponent.module.css from terminal styles in styles.css
• 2.3.2 Create components/features/git/GitToolbar.module.css from git toolbar styles in styles.css
• 2.3.3 Create components/features/git/CommitDialog.module.css from commit dialog styles in styles.css
• 2.3.4 Create components/features/git/MergeDialog.module.css from merge dialog styles in styles.css
• 2.3.5 Create components/features/git/FileEditor.module.css from file editor styles in styles.css
• 2.3.6 Create components/features/git/FileBrowser.module.css from file browser styles in styles.css
• 2.3.7 Create components/features/git/FileViewer.module.css from file viewer styles in styles.css
• 2.3.8 Create components/features/git/CommitPanel.module.css from commit panel styles in styles.css
• 2.3.9 Create components/features/session/InstanceList.module.css from instance list styles in styles.css
• 2.3.10 Create components/features/settings/SettingsTabLayout.module.css from settings tab layout styles in styles.css
• 2.3.11 Create components/layout/AppShell.module.css from shell styles in styles.css
• 2.3.12 Update each component to use import styles from './ComponentName.module.css'
• 2.3.13 Remove extracted styles from styles.css
• 2.3.14 Verify build passes

2.4 Verify and Delete Monolith

• 2.4.1 Confirm styles.css is empty (or only has truly unclassifiable styles)
• 2.4.2 Delete styles.css
• 2.4.3 Verify build passes
• 2.4.4 Verify no visual regressions

Phase 3: Frontend — Tool Workshop Page

• 3.1 Extract ToolTypesTab from pages/ToolWorkshopPage.tsx into components/features/tool-workshop/ToolTypesTab.tsx
• 3.2 Extract ToolConfigsTab into components/features/tool-workshop/ToolConfigsTab.tsx
• 3.3 Extract ConfigFoldersTab into components/features/tool-workshop/ConfigFoldersTab.tsx
• 3.4 Slim pages/ToolWorkshopPage.tsx to ~80 lines (tab switcher only)
• 3.5 Update imports in all consumers
• 3.6 Verify tsc --noEmit and npm run build pass

Phase 4: Frontend — Config Profiles Page

• 4.1 Extract ConfigProfileListView into components/features/config-profiles/ConfigProfileListView.tsx
• 4.2 Extract ConfigProfileDetailView into components/features/config-profiles/ConfigProfileDetailView.tsx
• 4.3 Extract ConfigProfileEditForm into components/features/config-profiles/ConfigProfileEditForm.tsx
• 4.4 Extract ConfigProfileMobileView into components/features/config-profiles/ConfigProfileMobileView.tsx
• 4.5 Slim pages/ConfigProfilesPage.tsx to ~80 lines
• 4.6 Update imports
• 4.7 Verify tsc --noEmit and npm run build pass

Phase 5: Frontend — Terminal Page

• 5.1 Extract TerminalSessionManager (tabs + auto-create) into components/features/terminal/TerminalSessionManager.tsx
• 5.2 Extract MobileTerminalOverlay into components/features/terminal/MobileTerminalOverlay.tsx
• 5.3 Extract fullscreen keyboard shortcut handler into hooks/use-terminal-shortcuts.ts
• 5.4 Slim pages/TerminalPage.tsx to ~80 lines
• 5.5 Update imports
• 5.6 Verify tsc --noEmit and npm run build pass

Phase 6: Frontend — Settings & SSH Keys Pages

• 6.1 Extract SettingsNavigation into components/features/settings/SettingsNavigation.tsx
• 6.2 Slim pages/SettingsPage.tsx to ~80 lines
• 6.3 Extract SSHKeyList into components/features/ssh-keys/SSHKeyList.tsx
• 6.4 Extract SSHKeyCreateForm into components/features/ssh-keys/SSHKeyCreateForm.tsx
• 6.5 Slim pages/SshKeysPage.tsx to ~80 lines
• 6.6 Verify tsc --noEmit and npm run build pass

Phase 7: Frontend — Projects & Repo Workspace Pages

• 7.1 Extract ProjectList into components/features/project/ProjectList.tsx
• 7.2 Extract ProjectCreateDialog into components/features/project/ProjectCreateDialog.tsx
• 7.3 Extract ProjectEditDialog into components/features/project/ProjectEditDialog.tsx
• 7.4 Slim pages/ProjectsPage.tsx to ~100 lines
• 7.5 Extract WorkspaceLayout into components/features/workspace/WorkspaceLayout.tsx
• 7.6 Slim pages/RepoWorkspacePage.tsx to ~150 lines
• 7.7 Verify tsc --noEmit and npm run build pass

Phase 8: Integration and Verification

• 8.1 Run backend py_compile on all files
• 8.2 Run frontend npm run typecheck
• 8.3 Run frontend npm run build
• 8.4 Run frontend tests: npm test
• 8.5 Verify file size targets met (pages ≤ 150, routers ≤ 400, no styles.css monolith)
• 8.6 Verify no 404s or import errors in browser console
• 8.7 Manual smoke test: create project, start terminal, open config profiles
• 8.8 Verify visual regression: colors, spacing, typography unchanged
• 8.9 Verify mobile terminal styles intact
• 8.10 Verify notification dropdown styles intact