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

## Scope

This change is a **pure structural refactoring** to split monolithic pages and routers into focused components and services. No API contracts, database schemas, or user-facing behaviors change.

### In Scope

#### 1. Frontend Page Extraction

Split the following pages into a thin page shell + extracted components:

**`pages/ToolWorkshopPage.tsx` (1,269 → ~80 lines)**
- Extract `ToolTypesTab` → `components/features/tool-workshop/ToolTypesTab.tsx`
- Extract `ToolConfigsTab` → `components/features/tool-workshop/ToolConfigsTab.tsx`
- Extract `ConfigFoldersTab` → `components/features/tool-workshop/ConfigFoldersTab.tsx`
- Page becomes: tab switcher only, imports the 3 tabs

**`pages/ConfigProfilesPage.tsx` (1,611 → ~80 lines)**
- Extract `ConfigProfileListView` → list view + mobile list view
- Extract `ConfigProfileDetailView` → detail view with edit toggle
- Extract `ConfigProfileEditForm` → edit/create form
- Extract `ConfigProfileMobileView` → mobile view state machine wrapper
- Page becomes: router between list/detail/edit views

**`pages/TerminalPage.tsx` (571 → ~80 lines)**
- Extract `TerminalSessionManager` → session tabs + auto-create logic
- Extract `TerminalKeyboardShortcuts` → shortcut handler hook (already exists, just use it)
- Extract `MobileTerminalOverlay` → mobile overlay toolbar + tabs
- Page becomes: choose between desktop (`TerminalComponent` + `TerminalSessionTabs`) and mobile (`MobileTerminalOverlay` + `TerminalComponent`) wrappers

**`pages/SettingsPage.tsx` (284 → ~80 lines)**
- Extract `SettingsNavigation` → settings nav sidebar
- Extract `GeneralSettingsTab`, `SSHKeysTab` (already separate pages, but move sections into components if inline)
- Page becomes: nav + `<Outlet>` for nested routes

**`pages/SshKeysPage.tsx` (277 → ~80 lines)**
- Extract `SSHKeyList` → list with actions
- Extract `SSHKeyCreateForm` → create form
- Page becomes: layout wrapper + conditionally render list or form

**`pages/RepoWorkspacePage.tsx` (505 → ~150 lines)**
- Extract `WorkspaceLayout` → sidebar + main content layout
- Page becomes: data loader + layout wrapper

**`pages/ProjectsPage.tsx` (433 → ~100 lines)**
- Extract `ProjectList` → list with cards
- Extract `ProjectCreateDialog` → create form in dialog
- Extract `ProjectEditDialog` → edit form in dialog
- Page becomes: data loader + layout + dialog state manager

#### 2. CSS Reorganization

**`styles.css` (5,683 lines → deleted)**
- Restore `styles/` directory with extracted files:
  - `styles/tokens.css` — CSS custom properties (colors, spacing, typography)
  - `styles/global.css` — global reset, body, shell layout
  - `styles/utilities.css` — utility classes (.stack, .card, .muted, etc.)
  - `styles/syntax-highlight.css` — code highlighting
- Restore `styles/pages/*.css` — page-specific styles:
  - `styles/pages/dashboard.css`
  - `styles/pages/projects.css`
  - `styles/pages/sessions.css`
  - `styles/pages/settings.css`
  - `styles/pages/ssh-keys.css`
  - `styles/pages/git-history.css`
  - `styles/pages/repo-workspace.css`
- Restore component CSS modules:
  - `components/features/terminal/TerminalComponent.module.css`
  - `components/features/git/GitToolbar.module.css`
  - `components/features/git/CommitDialog.module.css`
  - `components/features/git/MergeDialog.module.css`
  - `components/features/git/FileEditor.module.css`
  - `components/features/git/FileBrowser.module.css`
  - `components/features/git/FileViewer.module.css`
  - `components/features/git/CommitPanel.module.css`
  - `components/features/session/InstanceList.module.css`
  - `components/features/settings/SettingsTabLayout.module.css`
  - `components/layout/AppShell.module.css`
- Update all component imports to use `import styles from './ComponentName.module.css'`
- Update `main.tsx` to import `styles/tokens.css`, `styles/global.css`, `styles/utilities.css`, `styles/syntax-highlight.css`
- Update each page to import its `styles/pages/*.css`
- Delete monolithic `styles.css`

#### 3. Backend Router Slimming

**`api/tool/tool_instances.py` (2,900 → ~300 lines)**
- Extract terminal WebSocket handlers → `api/tool/terminal.py` (~400 lines)
- Extract instance lifecycle (create/start/stop/delete/restart) → `api/tool/tool_lifecycle.py` (~600 lines)
- Keep in `tool_instances.py`: CRUD endpoints (GET list, GET detail, POST, PATCH, DELETE) + instance proxy endpoint

**`api/project/git_repositories.py` (1,588 → ~300 lines)**
- Extract git command orchestration into `services/git/operations.py`
- Router keeps: auth, parameter validation, response building, error handling
- Service functions: `clone_repo`, `fetch_repo`, `pull_repo`, `push_repo`, `merge_repo`, etc.

**`api/config/config_profiles.py` (842 → ~200 lines)**
- Extract resolver orchestration into `services/config/resolver_service.py`
- Extract CRUD helpers into `services/config/crud_service.py`
- Router keeps: endpoint definitions, auth, input validation

### Out of Scope

- Any new features or behavioral changes
- Database schema changes (no migrations)
- API contract changes (same endpoints, same request/response shapes)
- Frontend UI behavior changes (same components, same interactions)
- Moving existing `features/` components (already organized)
- Renaming files (naming already done)
- Changing any CSS rules (only moving them)

## Acceptance Criteria

1. All pages ≤ 150 lines (except `RepoWorkspacePage` which may stay at ~150)
2. All API routers ≤ 400 lines
3. No monolithic `styles.css` — all CSS in `styles/` directory or `.module.css` files
4. All existing tests pass without modification (behavior unchanged)
5. All existing API endpoints return identical responses
6. Frontend `npm run typecheck` passes
7. Frontend `npm run build` passes
8. Backend `py_compile` passes on all files
9. No import errors in browser console
10. File count increases (more files, smaller files)

## Preconditions

- `dev` branch is stable (all fixes from this session are committed)
- Backend compiles (`py_compile` pass)
- Frontend typechecks and builds (`tsc`, `vite build` pass)
- Current tests pass (or known failures are documented)