admin-valentin/agent-ecosystem
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(visualization): enhance team and subagent visualization in README

Browse source 
- Updated the README to reflect new features in Claude Code, including the ability to spawn subagents via the Task tool and coordinate teams with improved visibility.
- Added details on the rendering of subagent sessions as expandable inline cards, including execution traces, metrics, and tool calls.
- Enhanced description of teammate messages, highlighting color-coded cards and team lifecycle visibility.
- Clarified session summary metrics to differentiate between teammate and subagent counts for better user insights.

This commit significantly improves the documentation of team and subagent visualization features, providing users with a clearer understanding of the capabilities and enhancements in the application.
This commit is contained in:
matt 2026-02-12 23:43:28 +09:00
parent c02c7d24cf
commit 524a62438e
59 changed files with 196 additions and 10240 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

72
.planning/PROJECT.md
View file

@ -1,72 +0,0 @@
# SSH Multi-Context Workspaces
## What This Is
A workspace-based multi-context system for claude-devtools that treats local and SSH connections as independent, switchable screens. Local mode is always alive. Each SSH connection is an independent workspace with its own projects, sessions, tabs, notifications, and state — freely switchable with instant state preservation. Like having multiple monitors you flip between.
## Core Value
Users can seamlessly switch between local and any number of SSH workspaces without losing state, and SSH sessions actually load their conversation history.
## Requirements
### Validated
- SSH connection establishment and SFTP file system provider — existing
- Session discovery over SSH (sidebar lists remote sessions) — existing
- SSH connection settings UI — existing
- SSH auto-reconnect and last-connection persistence — existing
### Active
- [ ] SSH sessions display full conversation history (fix provider plumbing bug)
- [ ] SSH subagent drill-down loads correctly over SFTP
- [ ] Multiple service contexts coexist (local always alive, SSH contexts independent)
- [ ] Context switching preserves full state (tabs, sidebar, notifications, selections)
- [ ] Workspace switcher in sidebar for switching between contexts
- [ ] Status bar indicator showing active workspace and connection status
- [ ] SSH file watchers stay alive in background while connected
- [ ] Loading overlay during context switch (prevent stale data flash)
- [ ] Switching to local restores all previous local state exactly
- [ ] Connection profiles saved in settings for quick reconnection
### Out of Scope
- SFTP performance optimization — investigating separately after workspace switching works
- SSH key management UI — use system SSH keys
- Multiple simultaneous SSH sessions visible side-by-side — workspace model is one-at-a-time switching
- Mobile/responsive layout for SSH features — desktop only
## Context
The existing SSH integration (commits 4b56186, 921420b, ad4e75b) established SFTP-based file system access and connection management. However, several critical issues surfaced:
1. **"No conversation history" bug**: `SessionParser`, `SubagentResolver`, and `SubagentDetailBuilder` don't pass the SSH `FileSystemProvider` to `parseJsonlFile()`, so JSONL parsing falls back to local filesystem and finds nothing.
2. **Stale sidebar during transitions**: Fire-and-forget fetches with no loading state means old local data is visible while SSH data loads.
3. **Destructive mode switch**: Connecting SSH destroys local services; disconnecting destroys SSH state. No way to switch back without re-fetching everything.
Reference design document: `~/.claude/plans/mighty-soaring-moore.md` — contains detailed implementation notes for all 4 phases including specific file changes, line numbers, and code patterns.
Brownfield codebase map: `.planning/codebase/` — 7 documents covering stack, architecture, structure, conventions, testing, integrations, and concerns.
## Constraints
- **Tech stack**: Electron 28.x, React 18.x, TypeScript 5.x, Zustand 4.x — no new frameworks
- **Architecture**: Must use existing IPC bridge pattern (main process services + preload API + renderer store)
- **Backward compatibility**: Local-only mode must work identically to current behavior
- **State isolation**: Each workspace must have fully independent Zustand state slices
## Key Decisions
| Decision | Rationale | Outcome |
|----------|-----------|---------|
| ServiceContextRegistry in main process | Centralizes context lifecycle, avoids scattered service variable management | -- Pending |
| Snapshot/restore for Zustand state | Instant switching without refetching; preserves exact user state | -- Pending |
| Workspace indicators in sidebar + status bar | Sidebar for active switching, status bar for passive awareness (VS Code model) | -- Pending |
| SSH watchers stay alive in background | Users expect real-time updates even for non-active workspaces; disconnect is explicit | -- Pending |
| Performance optimization deferred | Focus on correctness and UX first, investigate SFTP latency separately | -- Pending |
---
*Last updated: 2026-02-12 after initialization*

114
.planning/REQUIREMENTS.md
View file

@ -1,114 +0,0 @@
# Requirements: SSH Multi-Context Workspaces
**Defined:** 2026-02-12
**Core Value:** Users can seamlessly switch between local and SSH workspaces without losing state, and SSH sessions actually load their conversation history.
## v1 Requirements
Requirements for initial release. Each maps to roadmap phases.
### Provider Plumbing
- [ ] **PROV-01**: SSH sessions display full conversation history (fix FileSystemProvider plumbing through SessionParser)
- [ ] **PROV-02**: SSH subagent drill-down loads correctly over SFTP (fix SubagentResolver and SubagentDetailBuilder provider plumbing)
### Service Context Management
- [ ] **SCTX-01**: ServiceContextRegistry manages local + N SSH service contexts with getActive/switch/create/destroy lifecycle
- [ ] **SCTX-02**: Local service context is always alive and never destroyed on SSH connect/disconnect
- [ ] **SCTX-03**: Each SSH context has independent services (ProjectScanner, SessionParser, SubagentResolver, ChunkBuilder, DataCache, FileWatcher)
- [ ] **SCTX-04**: All services implement dispose() for proper cleanup (EventEmitter listeners, timers, SSH connections)
- [ ] **SCTX-05**: IPC requests are stamped with context ID to prevent race conditions during rapid switching
### IPC Context API
- [ ] **IPC-01**: Context management IPC channels exist (context:list, context:switch, context:connect-ssh, context:disconnect-ssh, context:destroy)
- [ ] **IPC-02**: Preload exposes context API to renderer (window.electronAPI.context)
- [ ] **IPC-03**: File watcher events are scoped to active context only
### State Snapshot/Restore
- [ ] **SNAP-01**: Full Zustand state snapshot captured on context switch (projects, sessions, tabs, pane layout, selections, notifications)
- [ ] **SNAP-02**: Switching to a previously visited context restores exact state instantly (no refetch)
- [ ] **SNAP-03**: Switching to a never-visited context shows empty/skeleton state (not stale local data)
- [ ] **SNAP-04**: Loading overlay displayed during context switch to prevent stale data flash
- [ ] **SNAP-05**: Context snapshots persist to IndexedDB (survive app restart)
### Workspace UI
- [ ] **WSUI-01**: Context switcher dropdown in sidebar lists Local + connected SSH workspaces
- [ ] **WSUI-02**: Status bar indicator shows active workspace name and connection status
- [ ] **WSUI-03**: Connection status indicators display connected/connecting/disconnected/error states
- [ ] **WSUI-04**: SSH connection profiles can be saved, edited, and deleted in settings
- [ ] **WSUI-05**: Keyboard shortcuts available for switching between workspaces
## v2 Requirements
Deferred to future release. Tracked but not in current roadmap.
### Enhanced UX
- **WSUI-06**: Color-coded workspace indicators per SSH connection
- **WSUI-07**: Fuzzy search in workspace switcher for quick filtering
- **WSUI-08**: Auto-reconnect with exponential backoff on SSH disconnect
- **WSUI-09**: Workspace health metrics (latency, connection uptime)
### Advanced Capabilities
- **ADV-01**: Parallel workspace windows (view two workspaces simultaneously)
- **ADV-02**: Cross-context session comparison (local vs remote side-by-side)
- **ADV-03**: Workspace groups (organize related SSH connections)
## Out of Scope
| Feature | Reason |
|---------|--------|
| SFTP performance optimization | Investigating separately after workspace switching works |
| SSH key management UI | Use system SSH keys, not app-managed |
| Multi-window side-by-side workspaces | v2+ complexity; current model is one-at-a-time switching |
| Mobile/responsive layout | Desktop-only app |
| BroadcastChannel multi-window sync | Single window for v1; multi-window is v2+ |
| Offline-first workspace caching | Would require conflict resolution strategy; defer |
## Traceability
Which phases cover which requirements. Updated during roadmap creation.
| Requirement | Phase | Status |
|-------------|-------|--------|
| PROV-01 | Phase 1 | Pending |
| PROV-02 | Phase 1 | Pending |
| SCTX-01 | Phase 2 | Pending |
| SCTX-02 | Phase 2 | Pending |
| SCTX-03 | Phase 2 | Pending |
| SCTX-04 | Phase 2 | Pending |
| SCTX-05 | Phase 2 | Pending |
| IPC-01 | Phase 2 | Pending |
| IPC-02 | Phase 2 | Pending |
| IPC-03 | Phase 2 | Pending |
| SNAP-01 | Phase 3 | Pending |
| SNAP-02 | Phase 3 | Pending |
| SNAP-03 | Phase 3 | Pending |
| SNAP-04 | Phase 3 | Pending |
| SNAP-05 | Phase 3 | Pending |
| WSUI-01 | Phase 4 | Pending |
| WSUI-02 | Phase 4 | Pending |
| WSUI-03 | Phase 4 | Pending |
| WSUI-04 | Phase 4 | Pending |
| WSUI-05 | Phase 4 | Pending |
**Coverage:**
- v1 requirements: 20 total
- Mapped to phases: 20
- Unmapped: 0
**Validation:**
- Phase 1: 2 requirements (PROV-01, PROV-02)
- Phase 2: 8 requirements (SCTX-01 through SCTX-05, IPC-01 through IPC-03)
- Phase 3: 5 requirements (SNAP-01 through SNAP-05)
- Phase 4: 5 requirements (WSUI-01 through WSUI-05)
- Total: 20 requirements mapped
---
*Requirements defined: 2026-02-12*
*Last updated: 2026-02-12 after roadmap creation (traceability complete)*

97
.planning/ROADMAP.md
View file

@ -1,97 +0,0 @@
# Roadmap: SSH Multi-Context Workspaces
## Overview
This roadmap transforms claude-devtools from a single-mode application (local XOR SSH) into a true multi-context workspace system where local mode is always alive and each SSH connection is an independent, switchable workspace with full state preservation. Phase 1 fixes the critical "no conversation history" bug by plumbing FileSystemProvider through all parsing services. Phase 2 establishes ServiceContextRegistry infrastructure to manage multiple independent service contexts. Phase 3 implements snapshot-based state management for instant context switching. Phase 4 delivers the workspace switcher UI and connection profiles.
## Phases
**Phase Numbering:**
- Integer phases (1, 2, 3, 4): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
Decimal phases appear between their surrounding integers in numeric order.
- [x] **Phase 1: Provider Plumbing** - Fix SSH session parsing and subagent loading ✓ 2026-02-12
- [x] **Phase 2: Service Infrastructure** - ServiceContextRegistry and IPC context API ✓ 2026-02-12
- [x] **Phase 3: State Management** - Snapshot/restore system for instant switching ✓ 2026-02-12
- [ ] **Phase 4: Workspace UI** - Context switcher and connection profiles
## Phase Details
### Phase 1: Provider Plumbing
**Goal**: SSH sessions display full conversation history and subagent drill-down works correctly
**Depends on**: Nothing (first phase)
**Requirements**: PROV-01, PROV-02
**Success Criteria** (what must be TRUE):
1. User can open an SSH session and see full conversation history (not "No conversation history" message)
2. User can drill down into subagents within SSH sessions and view their execution details
3. JSONL file parsing uses SSH FileSystemProvider when in SSH mode (not falling back to local filesystem)
**Plans**: 1 plan
Plans:
- [x] 01-01-PLAN.md — Thread FileSystemProvider through parsing stack (SessionParser, SubagentResolver, SubagentDetailBuilder) ✓
### Phase 2: Service Infrastructure
**Goal**: Multiple service contexts coexist with proper lifecycle management and IPC routing
**Depends on**: Phase 1
**Requirements**: SCTX-01, SCTX-02, SCTX-03, SCTX-04, SCTX-05, IPC-01, IPC-02, IPC-03
**Success Criteria** (what must be TRUE):
1. User can connect to SSH without destroying local service context (local projects/sessions remain available)
2. Multiple SSH connections can exist simultaneously with independent service instances
3. Switching between contexts routes IPC requests to the correct service context
4. Disconnecting SSH and reconnecting later restores the same SSH context (not recreated from scratch)
5. File watcher events only fire for the active context (no cross-context pollution)
**Plans**: 3 plans
Plans:
- [x] 02-01-PLAN.md — ServiceContext bundle class, ServiceContextRegistry coordinator, and dispose() methods for FileWatcher/DataCache ✓
- [x] 02-02-PLAN.md — Wire registry into main/index.ts and update all IPC handlers to route via registry ✓
- [x] 02-03-PLAN.md — Context management IPC channels, preload bridge, and connection profiles in ConfigManager ✓
### Phase 3: State Management
**Goal**: Context switching preserves exact UI state per workspace with instant restoration
**Depends on**: Phase 2
**Requirements**: SNAP-01, SNAP-02, SNAP-03, SNAP-04, SNAP-05
**Success Criteria** (what must be TRUE):
1. User can switch from local to SSH and back, returning to exact same state (open tabs, selected project, scroll position, sidebar selections)
2. First-time switch to new SSH context shows empty state (not stale local data)
3. Previously visited context restores instantly without refetching data
4. Loading overlay prevents stale data flash during context switch
5. Context snapshots survive app restart (stored in IndexedDB)
**Plans**: 1 plan
Plans:
- [x] 03-01-PLAN.md — Context snapshot system: contextSlice, IndexedDB storage, overlay, validation, and store wiring ✓
### Phase 4: Workspace UI
**Goal**: Users can visually manage and switch between workspaces with clear status indicators
**Depends on**: Phase 3
**Requirements**: WSUI-01, WSUI-02, WSUI-03, WSUI-04, WSUI-05
**Success Criteria** (what must be TRUE):
1. User sees context switcher in sidebar listing Local + all SSH workspaces
2. Status bar shows active workspace name and connection status at all times
3. Connection status indicators clearly show connected/connecting/disconnected/error states with distinct visual treatment
4. User can save SSH connection as a profile, then reconnect to it later without re-entering credentials
5. User can switch workspaces using keyboard shortcut (Cmd/Ctrl+K or similar)
**Plans**: 2 plans
Plans:
- [ ] 04-01-PLAN.md — ContextSwitcher dropdown, ConnectionStatusBadge, SidebarHeader integration, and Cmd+Shift+K shortcut
- [ ] 04-02-PLAN.md — WorkspaceSection settings for SSH profile CRUD with auto-refresh
## Progress
**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 4
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Provider Plumbing | 1/1 | ✓ Complete | 2026-02-12 |
| 2. Service Infrastructure | 3/3 | ✓ Complete | 2026-02-12 |
| 3. State Management | 1/1 | ✓ Complete | 2026-02-12 |
| 4. Workspace UI | 0/2 | Not started | - |
---
*Roadmap created: 2026-02-12*
*Last updated: 2026-02-12 after Phase 4 planning complete*

104
.planning/STATE.md
View file

@ -1,104 +0,0 @@
# Project State
## Project Reference
See: .planning/PROJECT.md (updated 2026-02-12)
**Core value:** Users can seamlessly switch between local and SSH workspaces without losing state, and SSH sessions actually load their conversation history.
**Current focus:** Phase 1 complete — ready for Phase 2
## Current Position
Phase: 4 of 4 (Workspace UI)
Plan: 2 of 2
Status: Phase 04 complete - all phases finished
Last activity: 2026-02-12 - Completed 04-02 (Workspace settings SSH profile CRUD)
Progress: [██████████] 100.0% (4/4 phases)
## Performance Metrics
**Velocity:**
- Total plans completed: 7
- Average duration: 5 min
- Total execution time: 0.68 hours
**By Phase:**
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| 01 Provider Plumbing | 1 | 4 min | 4 min |
| 02 Service Infrastructure | 3 | 12 min | 4 min |
| 03 State Management | 1 | 7 min | 7 min |
| 04 Workspace UI | 2 | 10 min | 5 min |
**Recent Trend:**
- Last 5 plans: 6, 2, 7, 6, 4
- Trend: Stable (UI tasks executing efficiently with clear patterns)
*Updated after each plan completion*
## Accumulated Context
### Decisions
Decisions are logged in PROJECT.md Key Decisions table.
Recent decisions affecting current work:
- ServiceContextRegistry in main process (centralizes context lifecycle)
- Snapshot/restore for Zustand state (instant switching without refetching)
- Workspace indicators in sidebar + status bar (VS Code model)
- SSH watchers stay alive in background (real-time updates for all workspaces)
- Added getFileSystemProvider() getter to ProjectScanner for consistent provider access (01-01)
- Threaded provider through all parseJsonlFile() call sites instead of relying on optional parameter fallback (01-01)
- Refactored SubagentDetailBuilder to accept fsProvider and projectsDir as explicit parameters (01-01)
- ServiceContext bundles all session-data services for single workspace isolation (02-01)
- dispose() separate from stop() - stop pauses (reversible), dispose destroys (permanent) (02-01)
- removeAllListeners() called LAST in dispose() to prevent events during cleanup (02-01)
- File watcher event rewiring via exported onContextSwitched callback from index.ts (02-02)
- SSH handler dynamically imports onContextSwitched to avoid circular dependencies (02-02)
- Context ID for SSH uses simple format: ssh-{host} (02-02)
- Destroy existing SSH context on reconnection to same host (02-02)
- [Phase 02-03]: SSH profiles stored in ConfigManager config.ssh.profiles for persistence
- [Phase 02-03]: lastActiveContextId persisted in config for app restart restoration
- [Phase 03-01]: 5-minute TTL for snapshot expiration (balances staleness vs utility)
- [Phase 03-01]: Exclude all transient state from snapshots (loading flags, errors, Maps/Sets)
- [Phase 03-01]: Validate restored tabs against fresh project/worktree data from target context
- [Phase 03-01]: Full-screen overlay prevents stale data flash during context transitions
- [Phase 04-01]: ContextSwitcher placed first in SidebarHeader Row 1, before project name, with vertical separator
- [Phase 04-01]: Cmd+Shift+K check placed before Cmd+K to avoid shortcut shadowing
- [Phase 04-01]: SSH status listener refreshes available contexts automatically on connection changes
- [Phase 04-02]: HardDrive icon for Workspaces tab to differentiate from Server icon on Connection tab
- [Phase 04-02]: WorkspaceSection manages own state internally (no props), matching ConnectionSection pattern
- [Phase 04-02]: AppConfig type cast via unknown for ssh field access since AppConfig interface lacks ssh property
### Pending Todos
None yet.
### Blockers/Concerns
**Phase 1:**
- ✓ RESOLVED: SessionParser, SubagentResolver, and SubagentDetailBuilder now receive FileSystemProvider correctly (01-01)
- Need to test SSH session loading and subagent drill-down thoroughly before proceeding to infrastructure changes (deferred to end-to-end testing)
**Phase 2:**
- ServiceContextRegistry pattern is novel for this codebase (no existing examples) - may need proof-of-concept validation
- EventEmitter listener cleanup must be bulletproof - memory leaks from orphaned listeners can consume 50-100MB per switch
**Phase 3:**
- ✓ RESOLVED: 5-minute TTL implemented with configurable version checking (03-01)
- ✓ RESOLVED: Snapshot validation filters invalid tabs and ensures at-least-one-pane invariant (03-01)
**Phase 4:**
- ✓ RESOLVED: Context switcher placed in Row 1 before project name with vertical separator — fits naturally without disrupting layout (04-01)
## Session Continuity
Last session: 2026-02-12
Stopped at: Completed 04-02 (Workspace settings SSH profile CRUD) — All phases complete
Resume file: None
---
*Created: 2026-02-12*
*Last updated: 2026-02-12 after completing 04-02-PLAN.md*

180
.planning/codebase/ARCHITECTURE.md
View file

@ -1,180 +0,0 @@
# Architecture
**Analysis Date:** 2026-02-12
## Pattern Overview
**Overall:** Three-process Electron architecture with domain-driven service layer and unidirectional data flow
**Key Characteristics:**
- Electron main process (Node.js) handles file system access, JSONL parsing, and business logic via domain-organized services
- Renderer process (React) manages UI state through Zustand slices with per-tab isolation
- Preload script provides secure IPC bridge via contextBridge
- Data flows: JSONL files → Services (parse/analyze) → IPC → Zustand store → React components
- Service layer organized into 5 domains: analysis, discovery, error, infrastructure, parsing
## Layers
**Main Process (Node.js):**
- Purpose: File system access, session parsing, chunk building, business logic
- Location: `src/main/`
- Contains: Entry point (`index.ts`), services (domain-organized), IPC handlers, types, utilities
- Depends on: Electron APIs, Node.js file system, shared types
- Used by: Renderer process via IPC
**Preload Bridge:**
- Purpose: Secure IPC communication layer between main and renderer
- Location: `src/preload/`
- Contains: ElectronAPI implementation (`index.ts`), IPC channel constants
- Depends on: Electron contextBridge, IPC channel definitions
- Used by: Renderer process via `window.electronAPI`
**Renderer Process (React):**
- Purpose: UI rendering, state management, user interaction
- Location: `src/renderer/`
- Contains: React components, Zustand store, hooks, utilities, contexts
- Depends on: React, Zustand, ElectronAPI, shared types
- Used by: End user
**Shared Code:**
- Purpose: Cross-process types, pure utilities, constants
- Location: `src/shared/`
- Contains: Type definitions, token formatting, model parsing, logger
- Depends on: Nothing (pure TypeScript)
- Used by: Main, renderer, preload processes
**Service Domains (Main Process):**
- Purpose: Business logic organized by responsibility
- Location: `src/main/services/{domain}/`
- Contains: 5 domains with specialized services
- Depends on: Node.js APIs, shared types, utilities
- Used by: IPC handlers, main process lifecycle
## Data Flow
**Session Loading Flow:**
1. User selects project/session in sidebar (renderer)
2. Renderer calls `window.electronAPI.getSessionDetail(projectId, sessionId)`
3. IPC handler in `src/main/ipc/sessions.ts` receives request
4. Handler checks `DataCache` (LRU cache, 50 entries, 10min TTL)
5. On cache miss: `SessionParser` reads JSONL file from `~/.claude/projects/{encoded-path}/{sessionId}.jsonl`
6. `SessionParser` parses messages, extracts metadata, calculates metrics
7. `SubagentResolver` finds subagent files in `{sessionId}/subagents/`, parses them, links to Task calls
8. `ChunkBuilder` orchestrates chunk building: classifies messages (user/AI/system/noise), groups into chunks, attaches subagents
9. Result cached in `DataCache` and returned via IPC
10. Renderer receives data, updates Zustand store (`sessionDetailSlice`)
11. React components re-render with new data
**Real-time Update Flow:**
1. `FileWatcher` detects change in session JSONL file (100ms debounce)
2. FileWatcher emits 'file-change' event with `{ type, path, projectId, sessionId, isSubagent }`
3. Main process forwards event to renderer via `mainWindow.webContents.send('file-change', event)`
4. Renderer's `initializeNotificationListeners()` receives event
5. Store action `refreshSessionInPlace()` called (debounced 150ms)
6. Cache invalidated, session re-parsed
7. Store updated without changing `selectedSessionId` (no flicker)
8. Components re-render with updated data
**State Management:**
- Zustand store with 14 slices (project, session, sessionDetail, subagent, conversation, tab, tabUI, pane, ui, notification, config, repository, connection, update)
- Each slice follows pattern: `{ data, selectedId, loading, error }`
- Per-tab UI state isolated in `tabUISlice` using tabId as key
- IPC event listeners registered once in `App.tsx`, update store directly
## Key Abstractions
**Chunk (Visualization Unit):**
- Purpose: Independent timeline visualization unit for chat display
- Examples: `UserChunk`, `AIChunk`, `SystemChunk`, `CompactChunk`
- Pattern: Discriminated union on `type` field, each with timestamp, duration, metrics (tokens, cost, tools)
- Built by: `ChunkBuilder` orchestrating `ChunkFactory`, `MessageClassifier`, `ProcessLinker`
**Process (Subagent):**
- Purpose: Represents spawned subagent execution with timing and metrics
- Examples: Task tool subagents, teammate messages in team coordination
- Pattern: Contains `id`, `name`, `startTime`, `endTime`, `metrics`, `isParallel`, optional `team` metadata
- Built by: `SubagentResolver` parsing subagent JSONL files, linking to Task calls, detecting parallel execution
**Service (Business Logic):**
- Purpose: Domain-specific business logic with single responsibility
- Examples: `ChunkBuilder` (analysis), `ProjectScanner` (discovery), `SessionParser` (parsing), `NotificationManager` (infrastructure), `ErrorDetector` (error)
- Pattern: Class-based, injected dependencies via constructor, exported from domain barrel
- Location: `src/main/services/{domain}/`
**Zustand Slice (State Domain):**
- Purpose: Domain-specific state management with actions
- Examples: `sessionSlice`, `tabSlice`, `notificationSlice`
- Pattern: Factory function returning slice with data, actions, selectors
- Combined in: `src/renderer/store/index.ts` via `create<AppState>()`
**IPC Handler (Communication):**
- Purpose: Request/response handlers for renderer-to-main communication
- Examples: `get-projects`, `get-session-detail`, `notifications:get`
- Pattern: Domain-organized modules with initialize/register/remove functions
- Location: `src/main/ipc/{domain}.ts`
## Entry Points
**Main Process Entry:**
- Location: `src/main/index.ts` (381 lines)
- Triggers: `app.whenReady()` Electron event
- Responsibilities: Initialize services (ProjectScanner, SessionParser, SubagentResolver, ChunkBuilder, DataCache, FileWatcher, NotificationManager, UpdaterService, SshConnectionManager), register IPC handlers, create BrowserWindow, start file watcher, apply configuration
**Renderer Entry:**
- Location: `src/renderer/main.tsx` (12 lines)
- Triggers: Page load after Electron window created
- Responsibilities: Render React app (`<App />`), mount to #root div
**Preload Entry:**
- Location: `src/preload/index.ts` (369 lines)
- Triggers: Before renderer loads (Electron lifecycle)
- Responsibilities: Expose ElectronAPI via contextBridge, wrap IPC calls with type-safe interface, provide event listener setup/cleanup
**React App Component:**
- Location: `src/renderer/App.tsx`
- Triggers: React render
- Responsibilities: Initialize theme, dismiss splash screen, register IPC event listeners (`initializeNotificationListeners()`), render layout (`<TabbedLayout />`)
## Error Handling
**Strategy:** Layer-specific error boundaries with graceful degradation
**Patterns:**
- Main process: Try/catch in services and IPC handlers, log errors with `createLogger()`, return null or empty arrays on failure
- Renderer: React `<ErrorBoundary>` component catches render errors, shows fallback UI
- IPC: Config handlers return `{ success: boolean, data?, error? }` wrapper, other handlers return null on failure
- Store actions: Catch async errors, set `error` state, display in UI
## Cross-Cutting Concerns
**Logging:** `createLogger(namespace)` from `@shared/utils/logger`, used throughout main and renderer
**Validation:**
- Path validation in `src/main/ipc/validation.ts` via `validatePath()`, `validateMentions()`
- Config validation in `src/main/ipc/configValidation.ts` for user input sanitization
- Type guards in `src/main/ipc/guards.ts` for IPC argument validation
**Authentication:** Not applicable (local desktop app accessing user's file system)
**Caching:**
- `DataCache` service (LRU, 50 entries, 10min TTL) for parsed session data
- Cache invalidation on file changes detected by `FileWatcher`
- Automatic cleanup every 5 minutes
**Performance:**
- Virtual scrolling for session lists and message lists (`@tanstack/react-virtual`)
- Debounced file watching (100ms) to batch rapid changes
- Session refresh debouncing (150ms) to prevent redundant IPC calls
- LRU cache to avoid re-parsing large JSONL files
**Configuration:**
- `ConfigManager` service manages `~/.claude-devtools/config.json`
- Accessed via `configManager.getConfig()`, `configManager.updateConfig()`
- IPC handlers in `src/main/ipc/config.ts` for renderer access
- Settings UI in `src/renderer/components/settings/`
---
*Architecture analysis: 2026-02-12*

309
.planning/codebase/CONCERNS.md
View file

@ -1,309 +0,0 @@
# Codebase Concerns
**Analysis Date:** 2026-02-12
## Tech Debt
**Large, complex files needing refactoring:**
- Issue: Several files exceed 700-1100 lines with complex business logic
- Files:
- `src/renderer/utils/contextTracker.ts` (1099 lines)
- `src/main/services/discovery/ProjectScanner.ts` (827 lines)
- `src/main/services/infrastructure/FileWatcher.ts` (798 lines)
- `src/renderer/components/chat/ChatHistory.tsx` (745 lines)
- `src/renderer/store/slices/tabSlice.ts` (740 lines)
- `src/main/services/infrastructure/ConfigManager.ts` (701 lines)
- `src/renderer/utils/groupTransformer.ts` (700 lines)
- `src/main/services/parsing/GitIdentityResolver.ts` (674 lines)
- `src/renderer/store/slices/sessionDetailSlice.ts` (658 lines)
- `src/main/services/infrastructure/NotificationManager.ts` (657 lines)
- `src/renderer/utils/claudeMdTracker.ts` (656 lines)
- `src/main/ipc/config.ts` (628 lines)
- Impact: Difficult to maintain, test, and debug; high cognitive load for changes
- Fix approach: Extract into smaller modules with single responsibilities; split contextTracker into separate concerns (injection detection, stats computation, phase tracking); break ConfigManager into domain-specific config handlers; split ChatHistory view logic from virtualization/scroll management
**Type safety gaps with `as any` and `as unknown` casts:**
- Issue: Type assertions bypass TypeScript's type checking
- Files:
- `src/main/services/infrastructure/SshConnectionManager.ts:171` - `sftp as any` for SSH provider
- `src/main/services/infrastructure/SshFileSystemProvider.ts:44` - `data as unknown as string`
- `src/main/services/infrastructure/NotificationManager.ts:170` - `JSON.parse(data) as unknown`
- `src/main/services/discovery/ProjectScanner.ts:659` - `JSON.parse(content) as unknown`
- `src/main/services/analysis/ToolResultExtractor.ts:140` - `content as unknown[]`
- `src/main/services/analysis/SemanticStepExtractor.ts:169` - `msg.toolUseResult as unknown`
- `src/main/utils/jsonl.ts:450` - `entry as unknown as Record<string, unknown>`
- Test files: Extensive use in `test/main/services/infrastructure/FileWatcher.test.ts` for mocking
- Impact: Potential runtime type errors; bypasses compiler safety net
- Fix approach: Create proper type guards and validation functions; use Zod schemas for JSON parsing; properly type SSH2/SFTP library interfaces instead of `any`
**Empty catch blocks silently swallowing errors:**
- Issue: 213 try/catch occurrences across 62 files, many with minimal error handling
- Files: All IPC handlers, store slices, service files
- Impact: Silent failures make debugging difficult; errors may go unnoticed
- Fix approach: Add structured logging to all catch blocks; implement error telemetry; ensure all errors bubble up or are explicitly handled with user feedback
**SSH connection type safety issues:**
- Issue: SSH2 library types not properly integrated, forcing `any` casts
- Files: `src/main/services/infrastructure/SshConnectionManager.ts`, `src/main/services/infrastructure/SshFileSystemProvider.ts`
- Impact: Runtime errors in SSH operations won't be caught at compile time
- Fix approach: Create proper TypeScript interfaces for SSH2/SFTP types; use branded types or runtime validation
**Disabled ESLint rules indicate code smells:**
- Issue: 30+ eslint-disable comments suggest underlying design issues
- Files:
- `src/renderer/components/chat/ChatHistory.tsx:417,425` - Direct DOM mutation for search highlighting
- `src/renderer/components/chat/AIChatGroup.tsx:195` - Manual memoization instead of React Compiler
- `src/renderer/hooks/useAutoScrollBottom.ts:144,178,204,247` - Complex effect dependencies
- `src/renderer/components/sidebar/DateGroupedSessions.tsx:157` - TanStack Virtual API limitation
- `src/renderer/utils/groupTransformer.ts:57` - Regex flagged as potentially unsafe
- Impact: Code may be fragile or have performance issues
- Fix approach: Refactor direct DOM mutations into proper React state management; simplify effect dependencies; document why ESLint rules must be disabled
## Known Bugs
**None explicitly documented in code:**
- Symptoms: No TODO/FIXME/HACK/BUG comments found in source
- Trigger: N/A
- Workaround: N/A
## Security Considerations
**IPC input validation present but could be stricter:**
- Risk: Malformed IPC inputs could cause crashes or unexpected behavior
- Files: `src/main/ipc/guards.ts`, all IPC handlers in `src/main/ipc/`
- Current mitigation: Validation guards with max length checks (128-512 chars), pattern validation, coercion for numeric inputs
- Recommendations:
- Add rate limiting on IPC calls to prevent DOS
- Validate file paths more strictly to prevent directory traversal
- Add schema validation for complex config objects (use Zod)
**Content sanitization exists but not comprehensive:**
- Risk: User-provided content from JSONL files could contain malicious content
- Files: `src/shared/utils/contentSanitizer.ts` - sanitizes display content, removes control characters
- Current mitigation: Basic content sanitization with regex pattern removal
- Recommendations:
- Add HTML escaping for any user content rendered in DOM
- Validate markdown content for XSS vectors
- Implement Content Security Policy headers
**File system access is broad:**
- Risk: App has access to entire user home directory via `~/.claude/`
- Files: `src/main/services/infrastructure/LocalFileSystemProvider.ts`, `src/main/services/infrastructure/SshFileSystemProvider.ts`
- Current mitigation: Access limited to specific Claude directories; path validation in IPC handlers
- Recommendations:
- Add explicit allow-list of accessible directories
- Log all file system operations for audit trail
- Implement file size limits to prevent memory exhaustion
**SSH connection security:**
- Risk: SSH credentials and private keys handled in memory
- Files: `src/main/services/infrastructure/SshConnectionManager.ts`, `src/main/services/infrastructure/SshConfigParser.ts`
- Current mitigation: Supports SSH agent, private key files; no plain password storage
- Recommendations:
- Ensure private keys are not logged
- Add connection timeout and retry limits
- Validate SSH host keys to prevent MITM attacks
- Document that passwords should use SSH agent, not inline
**Regex injection prevention:**
- Risk: User-provided regex patterns in notification triggers could cause ReDoS
- Files: `src/main/utils/regexValidation.ts`, `src/main/services/error/TriggerMatcher.ts`
- Current mitigation: Regex validation with complexity limits, documented as preventing ReDoS
- Recommendations: Continue validating all user regex; consider timeout mechanism for regex execution
## Performance Bottlenecks
**Large JSONL file parsing on every load:**
- Problem: Session files can be large (10k+ lines), parsed synchronously line-by-line
- Files: `src/main/utils/jsonl.ts:50-80` - `parseJsonlFile()`, `src/main/services/parsing/SessionParser.ts`
- Cause: Streaming reads mitigate memory issues but CPU-bound parsing still blocks
- Improvement path:
- Implement incremental parsing (read only viewport range initially)
- Add progress indicators for large files
- Cache parsed results more aggressively (current: 50 entries, 10min TTL)
- Consider worker threads for parsing if files exceed threshold
**DataCache could be more aggressive:**
- Problem: Cache size limited to 50 entries with 10min TTL; may evict frequently accessed sessions
- Files: `src/main/services/infrastructure/DataCache.ts:34`
- Cause: Conservative cache settings to limit memory usage
- Improvement path:
- Make cache size configurable based on available memory
- Implement smarter eviction (frequency-based, not just LRU)
- Add cache warming for recently accessed projects
- Monitor cache hit rate and adjust limits
**Virtual scrolling threshold may be too high:**
- Problem: ChatHistory uses virtualization only after 120 items
- Files: `src/renderer/components/chat/ChatHistory.tsx:33` - `VIRTUALIZATION_THRESHOLD = 120`
- Cause: Balance between performance and simplicity
- Improvement path: Lower threshold to 50 or make dynamic based on item complexity
**File watcher polling overhead in SSH mode:**
- Problem: SSH mode polls every 5 seconds instead of using native file watching
- Files: `src/main/services/infrastructure/FileWatcher.ts:76` - `SSH_POLL_INTERVAL_MS = 5000`
- Cause: SFTP doesn't support native file watching
- Improvement path:
- Increase polling interval for inactive sessions
- Only poll actively viewed sessions
- Implement exponential backoff when no changes detected
**React re-renders from array state updates:**
- Problem: Components use `useState` with arrays, triggering re-renders on mutation
- Files: Found in `src/renderer/components/search/CommandPalette.tsx`, `src/renderer/components/settings/NotificationTriggerSettings/hooks/useAddTriggerFormState.ts`
- Cause: React's immutability model
- Improvement path: Use immer for state updates; move to Zustand for complex state; add React.memo() strategically
**Context tracking computation on every turn:**
- Problem: `contextTracker.ts` (1099 lines) recomputes context stats for entire session
- Files: `src/renderer/utils/contextTracker.ts`
- Cause: Comprehensive tracking across 6 categories for all messages
- Improvement path:
- Memoize computation results
- Compute incrementally as messages arrive
- Move computation to web worker for large sessions
## Fragile Areas
**Search highlighting with direct DOM manipulation:**
- Files: `src/renderer/components/chat/ChatHistory.tsx:417-425`
- Why fragile: Directly mutates DOM outside React; tightly coupled to DOM structure
- Safe modification: Changes to chat item rendering may break highlighting; modify `searchHighlightUtils.ts` in parallel
- Test coverage: No automated tests for search highlighting
**File watcher concurrency handling:**
- Files: `src/main/services/infrastructure/FileWatcher.ts:79-82` - concurrency guards with `processingInProgress`, `pendingReprocess` Sets
- Why fragile: Complex state machine with polling, debouncing, catch-up scans, and concurrency guards; edge cases in reconnection
- Safe modification: Test thoroughly with concurrent file changes; validate that reprocessing queue works correctly
- Test coverage: Partial coverage in `test/main/services/infrastructure/FileWatcher.test.ts`
**Tab state synchronization across panes:**
- Files: `src/renderer/store/slices/tabSlice.ts:88-96` - `syncFromLayout()`, pane helpers
- Why fragile: Complex facade pattern synchronizing root state with focused pane; multi-level updates
- Safe modification: Changes to pane layout must maintain backward compatibility with openTabs/activeTabId
- Test coverage: Basic tests in `test/renderer/store/tabSlice.test.ts`
**Subagent resolution with parallel execution detection:**
- Files: `src/main/services/discovery/SubagentResolver.ts` (547 lines)
- Why fragile: Detects parallel execution by analyzing timing; enriches team metadata with color assignments
- Safe modification: Changes to team detection logic could break teammate display; timing heuristics may need tuning
- Test coverage: No automated tests for SubagentResolver
**Auto-scroll with search navigation:**
- Files: `src/renderer/hooks/useAutoScrollBottom.ts:144,178,204,247` - complex effect dependencies
- Why fragile: Multiple setTimeout/RAF coordination; interacts with virtualization, search, and user scroll
- Safe modification: Changes to scroll behavior should be tested with all interaction modes (search, navigation, user scroll)
- Test coverage: Basic tests in `test/renderer/hooks/useAutoScrollBottom.test.ts`
## Scaling Limits
**In-memory session storage:**
- Current capacity: Limited by DataCache (50 sessions) and Zustand store (unbounded arrays)
- Limit: Projects with 1000+ sessions may cause memory issues
- Scaling path:
- Implement pagination for session lists (already exists via `getSessionsPaginated`)
- Add session unloading when tabs close
- Consider IndexedDB for session metadata caching in renderer
**Context injection tracking:**
- Current capacity: All injections tracked for entire session in memory
- Limit: Very long sessions (1000+ turns) will accumulate large context stats
- Scaling path:
- Compute stats on-demand instead of upfront
- Store only aggregates, not individual injections
- Implement rolling window (last N turns)
**Notification storage:**
- Current capacity: Max 100 notifications in `~/.claude/claude-devtools-notifications.json`
- Limit: Hard cap prevents unbounded growth
- Scaling path: Already well-bounded; consider adding pagination UI if 100 is insufficient
**Virtual scrolling limitations:**
- Current capacity: Handles 1000+ items but estimated height may cause jumps
- Limit: Dynamic height items (collapsed/expanded) can cause scroll jank
- Scaling path: Use measured heights instead of estimates; implement "scroll anchoring"
## Dependencies at Risk
**Electron version updates:**
- Risk: Currently on Electron 40.3.0; major version updates may break IPC contracts
- Impact: File watching, native notifications, window management
- Migration plan: Test thoroughly on Electron beta releases; monitor breaking changes in Electron docs
**SSH2 library type coverage:**
- Risk: `ssh2@1.17.0` has incomplete TypeScript types, requiring `as any` casts
- Impact: SSH functionality breaks at runtime, not compile time
- Migration plan: Contribute types to DefinitelyTyped or switch to better-typed SSH library
**React 18 concurrent rendering:**
- Risk: Some components may not be concurrent-safe (direct DOM mutations)
- Impact: Search highlighting, scroll behavior may have race conditions
- Migration plan: Audit all DOM mutations; move to proper React state; enable strict mode
**Zustand store performance:**
- Risk: Large state trees with deep subscriptions cause re-render cascades
- Impact: Noticeable lag on large sessions
- Migration plan: Use `useShallow` more broadly; implement selector memoization; consider Jotai for derived state
## Missing Critical Features
**Offline SSH support:**
- Problem: SSH connections disconnect without graceful degradation
- Blocks: Viewing remote sessions when host unreachable
- Priority: Medium - add cached mode for read-only access
**Session export/archive:**
- Problem: No way to export session data for backup or sharing
- Blocks: Long-term archival, data portability
- Priority: Low - users can manually copy JSONL files
**Undo/redo for configuration:**
- Problem: No way to revert config changes or notification trigger edits
- Blocks: Safe experimentation with triggers
- Priority: Low - manual backup of `~/.claude/config.json` works
## Test Coverage Gaps
**Service layer severely undertested:**
- What's not tested: 38 of 44 service files lack tests (86% untested)
- Files:
- All infrastructure services except FileWatcher: `ConfigManager.ts`, `NotificationManager.ts`, `SshConnectionManager.ts`, `DataCache.ts` (DataCache has no tests despite complex LRU logic)
- All discovery services except ProjectScanner, SessionSearcher: `SubagentResolver.ts`, `SubagentLocator.ts`, `WorktreeGrouper.ts`, `SessionContentFilter.ts`
- All analysis services: `ChunkBuilder.ts` (tested), but `SubagentDetailBuilder.ts`, `SemanticStepExtractor.ts`, `ToolExecutionBuilder.ts` untested
- All error services: `ErrorDetector.ts`, `ErrorTriggerChecker.ts`, `ErrorMessageBuilder.ts`
- All parsing services except MessageClassifier, SessionParser: `GitIdentityResolver.ts`, `ClaudeMdReader.ts`
- Risk: Complex business logic could break unnoticed; refactoring is risky
- Priority: High - focus on: DataCache LRU eviction, NotificationManager throttling, SubagentResolver parallel detection, ErrorDetector token counting
**React components completely untested:**
- What's not tested: 126 component files, 0 component tests
- Files: All of `src/renderer/components/` (chat, sidebar, settings, dashboard, layout)
- Risk: UI regressions go unnoticed; interaction bugs not caught
- Priority: Medium - focus on critical paths: ChatHistory rendering, search functionality, tab management
**IPC handlers have minimal coverage:**
- What's not tested: Most IPC handlers in `src/main/ipc/` lack integration tests
- Files: `config.ts` (628 lines, 0% coverage), `sessions.ts`, `notifications.ts`, `ssh.ts`
- Risk: Handler crashes or incorrect responses not caught
- Priority: Medium - guards.ts has 53% coverage; add handler-level tests
**Store slices partially tested:**
- What's not tested: 6 of 12 slices tested; missing: `projectSlice`, `repositorySlice`, `sessionDetailSlice`, `subagentSlice`, `conversationSlice`, `configSlice`
- Files: `test/renderer/store/` has tests for `notificationSlice`, `paneSlice`, `sessionSlice`, `tabSlice`, `tabUISlice`
- Risk: State mutations may have side effects; action creators could have bugs
- Priority: Medium - focus on complex slices: sessionDetailSlice, conversationSlice
**Context tracking logic untested:**
- What's not tested: `contextTracker.ts` (1099 lines) has no tests
- Files: `src/renderer/utils/contextTracker.ts`, `src/renderer/utils/claudeMdTracker.ts`
- Risk: Context stats computation could be wrong; token counting inaccurate
- Priority: High - this is a core feature; add comprehensive tests for all 6 injection categories
**Utility functions have good coverage:**
- What's tested: `jsonl.ts`, `pathDecoder.ts`, `pathValidation.ts`, `regexValidation.ts`, `tokenizer.ts`, formatters, date grouping
- Coverage: Core parsing and utility logic is well-tested
- Priority: Low - maintain current coverage
---
*Concerns audit: 2026-02-12*

389
.planning/codebase/CONVENTIONS.md
View file

@ -1,389 +0,0 @@
# Coding Conventions
**Analysis Date:** 2026-02-12
## Naming Patterns
**Files:**
- Services/Components: PascalCase - `ChunkBuilder.ts`, `ProjectScanner.ts`, `AIChatGroup.tsx`
- Utilities: camelCase - `pathDecoder.ts`, `tokenizer.ts`, `formatters.ts`
- Type definitions: camelCase - `messages.ts`, `chunks.ts`, `data.ts`
- Test files: `*.test.ts` - mirrors source file name
**Functions:**
- Standard functions: camelCase - `encodePath`, `extractProjectName`, `formatDuration`
- Type guards: `isXxx` - `isParsedRealUserMessage`, `isAIChunk`, `isValidEncodedPath`
- Builder functions: `buildXxx` - `buildChunks`, `buildUserChunk`, `buildSessionPath`
- Getter functions: `getXxx` - `getProjectsBasePath`, `getExpandedDisplayItemIds`
- React components: Arrow functions with PascalCase names
**Variables:**
- Standard: camelCase - `chunkBuilder`, `sessionId`, `projectPath`
- Constants: UPPER_SNAKE_CASE - `EMPTY_METRICS`, `HARD_NOISE_TAGS`, `CONFIG_GET`
- React components: PascalCase - `AIChatGroup`, `TokenUsageDisplay`
- Unused parameters: Leading underscore - `_event`, `_arg`
**Types:**
- Interfaces/Types: PascalCase - `ParsedMessage`, `EnhancedChunk`, `SessionMetrics`
- Interfaces: NO "I" prefix (modern convention) - `ToolCall`, not `IToolCall`
- Enum members: PascalCase or UPPER_CASE - `TriggerColor`, `EMPTY_STDOUT`
## Code Style
**Formatting:**
- Tool: Prettier 3.8.1
- Config: `/Users/bskim/claude-devtools/.prettierrc.json`
- Key settings:
- Semi: true (always use semicolons)
- Single quotes: true
- Tab width: 2 spaces
- Trailing comma: es5
- Print width: 100 characters
- Arrow parens: always
- End of line: lf
- Bracket spacing: true
- Bracket same line: false
- Tailwind plugin: `prettier-plugin-tailwindcss` (auto-sorts classes)
**Linting:**
- Tool: ESLint 9.39.2 with typescript-eslint
- Config: `/Users/bskim/claude-devtools/eslint.config.js`
- Key rules:
- TypeScript strict mode enabled
- Type-aware linting via `projectService`
- React + Hooks + A11y rules
- Security plugin for AI-generated code
- SonarJS for code quality
- Module boundaries enforced (main/renderer/preload/shared separation)
- Import sorting via `simple-import-sort`
- No default exports (prefer named exports)
- Explicit function return types (warn)
- Explicit module boundary types (warn)
## Import Organization
**Order (enforced by `simple-import-sort`):**
1. Side effect imports (CSS, styles)
2. Node.js builtins (`node:fs`, `node:path`)
3. React packages (`react`, `react-dom`)
4. External packages (`@?\\w`)
5. Internal aliases (`@/`)
6. Parent imports (`../`)
7. Same-folder imports (`./`)
8. Type imports (last)
**Path Aliases:**
- `@main/*` → `src/main/*`
- `@renderer/*` → `src/renderer/*`
- `@shared/*` → `src/shared/*`
- `@preload/*` → `src/preload/*`
**Example:**
```typescript
import React, { useCallback, useMemo } from 'react';
import { ChunkBuilder, ProjectScanner } from '@main/services';
import { useStore } from '@renderer/store';
import { formatDuration } from '@shared/utils/formatters';
import { DisplayItemList } from './DisplayItemList';
import type { EnhancedChunk } from '@main/types';
```
**Import Restrictions:**
- No deep relative imports (`../../../`) - use path aliases
- No circular dependencies (max depth: 3)
- Module boundaries enforced:
- Renderer → renderer + shared only
- Main → main + shared only
- Preload → preload + shared only
- Shared → shared + main (for type re-exports)
## Type Conventions
**Type Imports:**
Use `type` modifier for type-only imports:
```typescript
import { type EnhancedChunk, type ParsedMessage } from '@main/types';
```
**Type Exports:**
```typescript
export type { Session, SessionDetail } from './types';
```
**Function Return Types:**
Always specify for exported functions (warn-level enforcement):
```typescript
export function buildChunks(messages: ParsedMessage[]): EnhancedChunk[] {
// ...
}
```
**Type Guards:**
Use discriminated union pattern with type predicates:
```typescript
export function isParsedRealUserMessage(msg: ParsedMessage): boolean {
return msg.type === 'user' && !msg.isMeta && typeof msg.content === 'string';
}
export function isUserChunk(chunk: Chunk | EnhancedChunk): chunk is UserChunk {
return chunk.type === 'user';
}
```
**Barrel Exports:**
Services use barrel exports via `index.ts`:
```typescript
// src/main/services/index.ts
export * from './analysis';
export * from './discovery';
export * from './error';
export * from './infrastructure';
export * from './parsing';
// Usage:
import { ChunkBuilder, ProjectScanner } from '@main/services';
```
Renderer utils/hooks/types do NOT have barrel exports - import directly from files.
## Error Handling
**Main Process:**
```typescript
try {
const result = await somethingRisky();
return result;
} catch (error) {
console.error('Operation failed:', error);
return safeDefault;
}
```
**Renderer:**
```typescript
// Store error state
set({
sessionsError: error instanceof Error ? error.message : 'Operation failed',
sessionsLoading: false,
});
```
**IPC Handlers:**
```typescript
// Validate parameters
if (!isValidProjectId(projectId)) {
throw new Error(`Invalid project ID: ${projectId}`);
}
// Return safe defaults on error
catch (error) {
logger.error('Handler failed:', error);
return [];
}
```
## Logging
**Framework:** Custom logger via `@shared/utils/logger`
**Pattern:**
```typescript
import { createLogger } from '@shared/utils/logger';
const logger = createLogger('Service:ChunkBuilder');
logger.info('Building chunks', { messageCount: messages.length });
logger.warn('Missing subagent', { taskId });
logger.error('Failed to parse', error);
```
**Console Usage:**
- Main process: `console.log/error` allowed (logging is expected)
- Renderer: Avoid console - use logger or store error state
- Tests: Console mocked in setup, errors/warnings cause test failures
## Comments
**When to Comment:**
- Complex business logic (chunk building, semantic step extraction)
- Non-obvious type guards (message classification rules)
- Workarounds or technical debt
- Public API documentation
**JSDoc/TSDoc:**
Used extensively for exported functions and types:
```typescript
/**
* Encodes an absolute path into Claude Code's directory naming format.
* Replaces all path separators (/ and \) with dashes.
*
* @param absolutePath - The absolute path to encode (e.g., "/Users/username/projectname")
* @returns The encoded directory name (e.g., "-Users-username-projectname")
*/
export function encodePath(absolutePath: string): string {
// ...
}
```
**Section Headers:**
Used to organize large files:
```typescript
// =============================================================================
// Chunk Building
// =============================================================================
```
## Function Design
**Size:** Keep focused and composable. Services orchestrate specialized modules.
**Parameters:**
- Use explicit types, no `any` (except in tests)
- Optional parameters last
- Use destructuring for options objects
**Return Values:**
- Always specify return type for exported functions
- Prefer explicit returns over implicit
- Return safe defaults instead of throwing (where appropriate)
**React Components:**
```typescript
// Prefer arrow functions for components
export const AIChatGroup: React.FC<AIChatGroupProps> = ({ aiGroup, userGroup }) => {
// Component implementation
};
```
**Component Props:**
```typescript
interface AIChatGroupProps {
aiGroup: AIGroup;
userGroup?: UserGroup;
onNavigate?: (messageId: string) => void;
}
```
## Module Design
**Exports:**
- Prefer named exports over default exports
- Barrel exports for service domains
- Direct exports for renderer utils/hooks
**File Organization:**
```typescript
// Imports
import { ... } from '...';
// Types/Interfaces
export interface MyInterface { ... }
// Constants
export const MY_CONSTANT = ...;
// Functions
export function myFunction() { ... }
// Classes
export class MyClass { ... }
```
**Services Pattern:**
```typescript
export class ChunkBuilder {
buildChunks(messages: ParsedMessage[]): EnhancedChunk[] {
// Implementation
}
buildSessionDetail(session: Session): SessionDetail {
// Implementation
}
}
```
## React Conventions
**Component Structure:**
```typescript
// Imports
import React, { useCallback, useMemo } from 'react';
// Types
interface ComponentProps { ... }
// Component
export const Component: React.FC<ComponentProps> = ({ prop1, prop2 }) => {
// Hooks first
const store = useStore();
const [state, setState] = useState();
// Memoized values
const computed = useMemo(() => ..., [deps]);
// Callbacks
const handleClick = useCallback(() => ..., [deps]);
// Render
return <div>...</div>;
};
```
**Hooks Rules:**
- Always use exhaustive deps (error-level enforcement)
- Custom hooks start with `use`: `useTabUI`, `useAutoScrollBottom`
- Keep hooks focused and composable
**State Management (Zustand):**
```typescript
// Slice pattern
export interface SessionSlice {
// State
sessions: Session[];
selectedSessionId: string | null;
sessionsLoading: boolean;
sessionsError: string | null;
// Actions
fetchSessions: (projectId: string) => Promise<void>;
selectSession: (id: string) => void;
}
```
## Tailwind CSS
**Use theme-aware classes:**
```tsx
<div className="bg-surface text-text border-border">
<div className="bg-surface-raised text-text-secondary">
```
**Auto-sorted by Prettier plugin:**
Classes automatically ordered by Prettier's Tailwind plugin.
**Custom CSS variables:**
Defined in `src/renderer/index.css` - use via Tailwind classes:
- `--color-surface` → `bg-surface`
- `--color-text` → `text-text`
- `--color-border` → `border-border`
## Security
**Enabled Rules:**
- `security/detect-eval-with-expression`: error
- `security/detect-child-process`: warn
- File system access: allowed (desktop app requirement)
- Dynamic patterns: allowed (intentional in this app)
**Parameter Mutation:**
Prevented via `no-param-reassign` except for:
- `draft` (Immer patterns)
- `acc` (reduce accumulators)
- `state` (Zustand)
---
*Convention analysis: 2026-02-12*

153
.planning/codebase/INTEGRATIONS.md
View file

@ -1,153 +0,0 @@
# External Integrations
**Analysis Date:** 2026-02-12
## APIs & External Services
**SSH/SFTP:**
- ssh2 - Direct SSH client implementation for remote session access
- SDK/Client: `ssh2` package (Node.js native)
- Auth: SSH agent, password, or private key authentication
- Implementation: `src/main/services/infrastructure/SshConnectionManager.ts`
- Config parsing: `src/main/services/infrastructure/SshConfigParser.ts` (reads `~/.ssh/config`)
- File system: `src/main/services/infrastructure/SshFileSystemProvider.ts` (SFTP-based)
- Purpose: Read Claude Code session files from remote machines
**GitHub Releases:**
- electron-updater - Auto-update via GitHub release assets
- SDK/Client: `electron-updater` package
- Configuration: `electron-builder.yml` publish section
- Implementation: `src/main/services/infrastructure/UpdaterService.ts`
- Update flow: Check → Download → Install (user-confirmed)
- Purpose: Application auto-updates
## Data Storage
**Databases:**
- None - File-based storage only
**File Storage:**
- Local filesystem only
- Session data: `~/.claude/projects/{encoded-path}/*.jsonl` (read-only)
- App config: `~/.claude/claude-devtools-config.json` (read-write)
- Notifications: `~/.claude/claude-devtools-notifications.json` (read-write)
- Remote access: SFTP via ssh2 (optional)
**Caching:**
- In-memory LRU cache - `src/main/services/infrastructure/DataCache.ts`
- Max entries: 50 sessions
- TTL: 10 minutes
- Auto-cleanup: Every 5 minutes
- Disable flag: `CLAUDE_CONTEXT_DISABLE_CACHE=1`
## Authentication & Identity
**Auth Provider:**
- SSH authentication (remote access only)
- Methods: SSH agent, password, private key
- Agent discovery: `SSH_AUTH_SOCK` env var, launchctl (macOS), known socket paths
- 1Password SSH agent: Supported via `~/Library/Group Containers/2BUA8C4S2C.com.1password/agent.sock`
- Default keys: `~/.ssh/id_ed25519`, `~/.ssh/id_rsa`, `~/.ssh/id_ecdsa`
- Config: `~/.ssh/config` parsing for host aliases, identity files
**Git Identity:**
- Git identity resolution - `src/main/services/parsing/GitIdentityResolver.ts`
- Reads `.git/config` for user.name/user.email
- Purpose: Display commit author information in UI
## Monitoring & Observability
**Error Tracking:**
- None - Local logging only via `@shared/utils/logger.ts`
**Logs:**
- Console output (main process)
- Electron DevTools console (renderer process)
- Log prefix format: `[Domain:Service]` (e.g., `[Infrastructure:SshConnectionManager]`)
## CI/CD & Deployment
**Hosting:**
- GitHub - Source repository and release hosting
**CI Pipeline:**
- GitHub Actions
- Workflow: `.github/workflows/ci.yml` - Lint, typecheck, test, build
- Workflow: `.github/workflows/release.yml` - Build and publish releases
**Build Output:**
- Local: `dist-electron/` (compiled code), `out/` (packaged app)
- Distribution: `release/` directory
- macOS: DMG, ZIP
- Windows: NSIS installer
- ASAR: Enabled (app code packaged into single archive)
## Environment Configuration
**Required env vars:**
- None for local mode
**Optional env vars:**
- `CLAUDE_CONTEXT_DISABLE_CACHE=1` - Disable in-memory cache
- `NODE_ENV=development` - Development mode
- `APPLE_TEAM_ID` - macOS code signing team ID (build-time only)
- `SSH_AUTH_SOCK` - SSH agent socket path (runtime, optional)
**Secrets location:**
- SSH keys: `~/.ssh/` directory
- SSH agent: External (OS keychain, 1Password)
- App config: `~/.claude/claude-devtools-config.json` (user preferences, no secrets)
## Webhooks & Callbacks
**Incoming:**
- None - Desktop application with no server component
**Outgoing:**
- None - No webhook emissions
## IPC Communication
**Electron IPC:**
- Pattern: Main ↔ Preload ↔ Renderer communication
- Bridge: `contextBridge` in `src/preload/index.ts` exposes `window.electronAPI`
- Channels: Defined in `src/preload/constants/ipcChannels.ts`
- Domains:
- Sessions: Project/session listing, search, detail views
- Repository: Git worktree grouping
- Validation: Path and mention validation
- CLAUDE.md: Configuration file reading
- Config: App settings management
- Notifications: Error notifications and triggers
- Utilities: Shell operations, file watching
- SSH: Remote connection management
- Updater: Update lifecycle events
**Real-time Updates:**
- File watching: `chokidar`-based file system monitoring
- Debounce: 100ms
- Events: `file-change`, `todo-change`
- Implementation: `src/main/services/infrastructure/FileWatcher.ts`
- Supports both local and SSH file systems
## External File Access
**Session Files:**
- Location: `~/.claude/projects/{encoded-path}/*.jsonl`
- Format: JSONL (JSON Lines) with Claude Code conversation data
- Access: Read-only
- Parser: `src/main/services/parsing/SessionParser.ts`
**Configuration Files:**
- `~/.claude/CLAUDE.md` - Global Claude Code configuration
- `{project-root}/CLAUDE.md` - Project-specific configuration
- `{directory}/CLAUDE.md` - Directory-specific configuration
- Reader: `src/main/services/parsing/ClaudeMdReader.ts`
**Git Worktrees:**
- Reads `.git/config` for worktree detection
- Grouper: `src/main/services/discovery/WorktreeGrouper.ts`
---
*Integration audit: 2026-02-12*

129
.planning/codebase/STACK.md
View file

@ -1,129 +0,0 @@
# Technology Stack
**Analysis Date:** 2026-02-12
## Languages
**Primary:**
- TypeScript 5.9.3 - All application code (main, preload, renderer)
**Secondary:**
- JavaScript - Configuration files (eslint.config.js, postcss.config.cjs, tailwind.config.js)
## Runtime
**Environment:**
- Node.js 25.2.1+ (ES2020/ES2022 target)
- Electron 40.3.0 (Chromium-based desktop runtime)
**Package Manager:**
- pnpm 10.25.0 (enforced via packageManager field)
- Lockfile: pnpm-lock.yaml (present)
## Frameworks
**Core:**
- Electron 40.3.0 - Desktop app framework (three-process architecture)
- React 18.3.1 - UI framework for renderer process
- React DOM 18.3.1 - React renderer
- Zustand 4.5.0 - State management
**Testing:**
- Vitest 3.1.4 - Test runner with happy-dom environment
- @vitest/coverage-v8 3.1.4 - Code coverage
- happy-dom 17.6.3 - Browser environment simulation
**Build/Dev:**
- electron-vite 2.3.0 - Build tool (Vite-based for Electron)
- Vite 5.4.2 - Development server and bundler
- electron-builder 24.13.3 - Packaging and distribution
- tsx 4.21.0 - TypeScript execution for test scripts
## Key Dependencies
**Critical:**
- ssh2 1.17.0 - SSH/SFTP connectivity for remote session access
- ssh-config 5.0.4 - SSH config file parsing
- electron-updater 6.7.3 - Auto-update functionality via GitHub releases
**Infrastructure:**
- @tanstack/react-virtual 3.10.8 - Virtual scrolling for large session lists
- @dnd-kit/core 6.3.1 + @dnd-kit/sortable 10.0.0 - Drag-and-drop for UI
- date-fns 3.6.0 - Date formatting and manipulation
- lucide-react 0.562.0 - Icon library
**Markdown/Content:**
- react-markdown 10.1.0 - Markdown rendering
- remark-gfm 4.0.1 - GitHub Flavored Markdown support
- unified 11.0.5 - Text processing pipeline
- remark-parse 11.0.0 - Markdown parser
- mdast-util-to-hast 13.2.1 - Markdown to HTML AST conversion
**Styling:**
- Tailwind CSS 3.4.1 - Utility-first CSS framework
- @tailwindcss/typography 0.5.19 - Typography plugin
- autoprefixer 10.4.17 - CSS vendor prefixing
- PostCSS 8.4.35 - CSS processing
**Code Quality:**
- ESLint 9.39.2 - Linting
- typescript-eslint 8.54.0 - TypeScript ESLint rules
- Prettier 3.8.1 - Code formatting
- prettier-plugin-tailwindcss 0.7.2 - Tailwind class sorting
- knip 5.82.1 - Unused code detection
**ESLint Plugins:**
- eslint-plugin-react 7.37.5 + eslint-plugin-react-hooks 7.0.1 - React rules
- eslint-plugin-jsx-a11y 6.10.2 - Accessibility rules
- eslint-plugin-tailwindcss 3.18.2 - Tailwind CSS rules
- eslint-plugin-boundaries 5.3.1 - Enforce Electron architecture boundaries
- eslint-plugin-security 3.0.1 - Security vulnerability detection
- eslint-plugin-sonarjs 3.0.6 - Code quality and bug detection
- eslint-plugin-simple-import-sort 12.1.1 - Import sorting
- eslint-plugin-import 2.32.0 - Import validation
## Configuration
**Environment:**
- No .env files - Desktop app reads from `~/.claude/` directories
- Local data: `~/.claude/projects/{encoded-path}/*.jsonl` - Session files
- Config: `~/.claude/claude-devtools-config.json` - App configuration
- Notifications: `~/.claude/claude-devtools-notifications.json` - Notification history
- Remote access: SSH/SFTP to remote `~/.claude/projects/` (optional)
**Build:**
- `electron.vite.config.ts` - Electron-specific Vite configuration with path aliases
- `tsconfig.json` - Main TypeScript config (renderer + shared)
- `tsconfig.node.json` - Main/preload process TypeScript config
- `tsconfig.test.json` - Test TypeScript config
- `vitest.config.ts` - Main test configuration
- `vitest.critical.config.ts` - Critical path coverage configuration
- `electron-builder.yml` - Build and packaging configuration
**Code Style:**
- `eslint.config.js` - Flat ESLint config with process-specific rules
- `.prettierrc.json` - Prettier formatting rules
- `tailwind.config.js` - Tailwind CSS customization with CSS variable theme
**Path Aliases:**
- `@main/*` → `src/main/*` (main process)
- `@renderer/*` → `src/renderer/*` (renderer process)
- `@shared/*` → `src/shared/*` (cross-process utilities)
- `@preload/*` → `src/preload/*` (preload bridge)
## Platform Requirements
**Development:**
- Node.js 25+ (specified in package.json engines would go here if present)
- pnpm 10.25.0+
- macOS or Windows (Linux support via Electron but not tested)
**Production:**
- macOS: DMG and ZIP distribution
- Windows: NSIS installer
- Code signing: macOS notarization via Apple Team ID (env.APPLE_TEAM_ID)
- Auto-updates: GitHub releases via electron-updater
---
*Stack analysis: 2026-02-12*

292
.planning/codebase/STRUCTURE.md
View file

@ -1,292 +0,0 @@
# Codebase Structure
**Analysis Date:** 2026-02-12
## Directory Layout
```
claude-devtools/
├── src/
│ ├── main/ # Electron main process (Node.js)
│ │ ├── constants/ # Message tags, worktree patterns
│ │ ├── ipc/ # IPC handlers by domain
│ │ ├── services/ # Business logic services
│ │ │ ├── analysis/ # Chunk building, semantic steps
│ │ │ ├── discovery/ # Project/session scanning
│ │ │ ├── error/ # Error detection, triggers
│ │ │ ├── infrastructure/ # Cache, config, file watching
│ │ │ └── parsing/ # JSONL parsing, message classification
│ │ ├── types/ # Main process type definitions
│ │ ├── utils/ # Main utilities (jsonl, pathDecoder)
│ │ └── index.ts # Main process entry point
│ ├── preload/ # Electron preload (IPC bridge)
│ │ ├── constants/ # IPC channel names
│ │ └── index.ts # ElectronAPI implementation
│ ├── renderer/ # React application
│ │ ├── components/ # UI components by feature
│ │ │ ├── chat/ # Session message display
│ │ │ ├── common/ # Shared UI primitives
│ │ │ ├── dashboard/ # Overview pages
│ │ │ ├── layout/ # App shell, sidebars
│ │ │ ├── notifications/ # Notification UI
│ │ │ ├── search/ # Search UI
│ │ │ ├── settings/ # Settings pages
│ │ │ └── sidebar/ # Navigation
│ │ ├── constants/ # CSS variables, layout, colors
│ │ ├── contexts/ # React contexts (TabUIContext)
│ │ ├── hooks/ # Custom React hooks
│ │ ├── store/ # Zustand state management
│ │ │ ├── slices/ # Domain slices
│ │ │ └── utils/ # Store helpers
│ │ ├── types/ # Renderer type definitions
│ │ ├── utils/ # Renderer utilities
│ │ ├── App.tsx # React root component
│ │ ├── main.tsx # React entry point
│ │ └── index.css # Global styles, theme
│ └── shared/ # Cross-process code
│ ├── constants/ # Cache, window, colors
│ ├── types/ # Shared type definitions
│ └── utils/ # Pure utilities
├── test/ # Vitest tests
│ ├── main/ # Main process tests
│ │ ├── ipc/ # IPC handler tests
│ │ ├── services/ # Service tests
│ │ └── utils/ # Utility tests
│ ├── renderer/ # Renderer tests
│ │ ├── hooks/ # Hook tests
│ │ ├── store/ # Store tests
│ │ └── utils/ # Utility tests
│ └── shared/ # Shared code tests
├── resources/ # App icons, assets
├── dist/ # Build output (renderer)
├── dist-electron/ # Build output (main, preload)
├── .claude/ # Claude Code configuration
│ ├── plans/ # Feature plans
│ └── rules/ # Project rules
├── .planning/ # GSD planning documents
│ └── codebase/ # Codebase analysis docs
├── package.json # Dependencies, scripts
├── tsconfig.json # TypeScript config (base)
├── tsconfig.node.json # TypeScript config (main)
├── vite.config.ts # Vite build config
└── vitest.config.ts # Vitest test config
```
## Directory Purposes
**src/main/**
- Purpose: Electron main process - file system access, JSONL parsing, business logic
- Contains: Entry point, services (5 domains), IPC handlers (10 domains), types, utilities
- Key files: `index.ts` (app lifecycle), `services/index.ts` (barrel export), `ipc/handlers.ts` (IPC setup)
**src/main/services/analysis/**
- Purpose: Chunk building and session analysis
- Contains: ChunkBuilder, ChunkFactory, ConversationGroupBuilder, ProcessLinker, SemanticStepExtractor, SemanticStepGrouper, SubagentDetailBuilder, ToolExecutionBuilder, ToolResultExtractor, ToolSummaryFormatter
- Key files: `ChunkBuilder.ts` (orchestrator), `ChunkFactory.ts` (chunk creation), `SemanticStepExtractor.ts` (step extraction)
**src/main/services/discovery/**
- Purpose: Project/session scanning, subagent resolution
- Contains: ProjectScanner, ProjectPathResolver, SessionSearcher, SessionContentFilter, SubagentLocator, SubagentResolver, SubprojectRegistry, WorktreeGrouper
- Key files: `ProjectScanner.ts` (file system scanning), `SubagentResolver.ts` (subagent linking)
**src/main/services/infrastructure/**
- Purpose: Core application infrastructure
- Contains: DataCache, FileWatcher, ConfigManager, NotificationManager, TriggerManager, UpdaterService, SshConnectionManager, FileSystemProvider (local/SSH)
- Key files: `DataCache.ts` (LRU cache), `FileWatcher.ts` (file monitoring), `ConfigManager.ts` (config persistence)
**src/main/services/parsing/**
- Purpose: JSONL parsing and classification
- Contains: SessionParser, MessageClassifier, ClaudeMdReader, GitIdentityResolver
- Key files: `SessionParser.ts` (JSONL parsing), `MessageClassifier.ts` (message categorization)
**src/main/services/error/**
- Purpose: Error detection and notification triggers
- Contains: ErrorDetector, ErrorMessageBuilder, ErrorTriggerChecker, ErrorTriggerTester, TriggerMatcher
- Key files: `ErrorDetector.ts` (token-based detection), `TriggerMatcher.ts` (pattern matching)
**src/main/ipc/**
- Purpose: IPC request handlers organized by domain
- Contains: projects, sessions, search, subagents, validation, utility, notifications, config, ssh, updater handlers
- Key files: `handlers.ts` (registration), `sessions.ts` (session operations), `config.ts` (configuration)
**src/preload/**
- Purpose: Secure IPC bridge between main and renderer
- Contains: ElectronAPI implementation, IPC channel constants
- Key files: `index.ts` (contextBridge API), `constants/ipcChannels.ts` (channel names)
**src/renderer/components/chat/**
- Purpose: Session message display and visualization
- Contains: Chat groups (User, AI, System), chat history, display items, viewers (markdown, code, diff), SessionContextPanel (visible context tracking)
- Key files: `ChatHistory.tsx` (timeline container), `AIChatGroup.tsx` (AI responses), `ContextBadge.tsx` (per-turn context popover)
**src/renderer/components/chat/items/**
- Purpose: Individual message/tool item renderers
- Contains: BaseItem, LinkedToolItem, ExecutionTrace, SubagentItem, ThinkingItem, TextItem, SlashItem, TeammateMessageItem, MetricsPill
- Key files: `LinkedToolItem.tsx` (tool call+result), `SubagentItem.tsx` (subagent display)
**src/renderer/components/chat/SessionContextPanel/**
- Purpose: Visible context tracking panel UI
- Contains: Main panel component, section wrappers, per-injection item renderers, directory tree, formatting utils
- Key files: `index.tsx` (panel component), `components/` (section wrappers), `items/` (injection renderers)
**src/renderer/store/**
- Purpose: Zustand state management
- Contains: Store creation, 14 domain slices, store utilities
- Key files: `index.ts` (store composition, IPC listeners), `slices/sessionDetailSlice.ts` (session data), `slices/tabSlice.ts` (tab management)
**src/renderer/store/slices/**
- Purpose: Domain-specific state slices
- Contains: projectSlice, repositorySlice, sessionSlice, sessionDetailSlice, subagentSlice, conversationSlice, tabSlice, tabUISlice, paneSlice, uiSlice, notificationSlice, configSlice, connectionSlice, updateSlice
- Key files: `sessionDetailSlice.ts` (session data), `tabUISlice.ts` (per-tab UI state)
**src/shared/**
- Purpose: Cross-process types and pure utilities
- Contains: Type definitions (api, notifications, visualization), utilities (tokenFormatting, modelParser, logger), constants (cache, window, colors)
- Key files: `types/index.ts` (type re-exports), `utils/tokenFormatting.ts` (token utilities)
**test/**
- Purpose: Vitest unit tests
- Contains: Tests organized by process (main, renderer, shared), mirrors src/ structure
- Key files: `main/services/analysis/ChunkBuilder.test.ts`, `renderer/store/sessionSlice.test.ts`
## Key File Locations
**Entry Points:**
- `src/main/index.ts`: Main process entry (381 lines) - app lifecycle, service initialization, window creation
- `src/renderer/main.tsx`: Renderer entry (12 lines) - React rendering
- `src/preload/index.ts`: Preload bridge (369 lines) - ElectronAPI implementation
- `src/renderer/App.tsx`: React root - theme, IPC listeners, layout
**Configuration:**
- `package.json`: Dependencies, build scripts
- `tsconfig.json`: Base TypeScript config
- `tsconfig.node.json`: Main process TypeScript config
- `vite.config.ts`: Vite build configuration
- `vitest.config.ts`: Vitest test configuration
- `src/renderer/index.css`: Global styles, CSS custom properties
**Core Logic:**
- `src/main/services/analysis/ChunkBuilder.ts`: Chunk building orchestration
- `src/main/services/parsing/SessionParser.ts`: JSONL parsing
- `src/main/services/discovery/SubagentResolver.ts`: Subagent linking
- `src/main/services/infrastructure/DataCache.ts`: LRU cache
- `src/main/services/infrastructure/FileWatcher.ts`: File monitoring
**Testing:**
- `test/main/services/analysis/ChunkBuilder.test.ts`: Chunk building tests
- `test/main/services/parsing/SessionParser.test.ts`: JSONL parsing tests
- `test/renderer/store/sessionSlice.test.ts`: Session state tests
## Naming Conventions
**Files:**
- Services/Components: PascalCase - `ChunkBuilder.ts`, `SessionParser.ts`, `AIChatGroup.tsx`
- Utilities: camelCase - `pathDecoder.ts`, `jsonl.ts`, `formatters.ts`
- Types: camelCase - `messages.ts`, `data.ts`, `api.ts`
- Barrel exports: `index.ts`
**Directories:**
- All lowercase with domain names - `services/`, `analysis/`, `components/`
- Feature-based organization - `components/chat/`, `components/settings/`
**Constants:**
- UPPER_SNAKE_CASE - `PARALLEL_WINDOW_MS`, `MAX_CACHE_SESSIONS`, `SESSION_REFRESH_DEBOUNCE_MS`
**Functions:**
- Type guards: `isXxx` - `isUserChunk()`, `isParsedRealUserMessage()`, `isAIChunk()`
- Builders: `buildXxx` - `buildChunks()`, `buildSubagentDetail()`, `buildDisplayItems()`
- Getters: `getXxx` - `getSessionPath()`, `getProjects()`, `getTaskCalls()`
- Creators: `createXxx` - `createLogger()`, `createConfigSlice()`, `createWindow()`
**Type Guards:**
- Message: `isParsedRealUserMessage()`, `isParsedInternalUserMessage()`, `isAssistantMessage()`
- Chunk: `isUserChunk()`, `isAIChunk()`, `isSystemChunk()`, `isCompactChunk()`
- Context: `isClaudeMdInjection()`, `isMentionedFileInjection()`, `isToolOutputInjection()`, `isThinkingTextInjection()`, `isTeamCoordinationInjection()`, `isUserMessageInjection()`
## Where to Add New Code
**New Service (Main Process):**
- Implementation: `src/main/services/{domain}/{ServiceName}.ts`
- Export: Add to `src/main/services/{domain}/index.ts` barrel
- Usage: Import from `@main/services` or `@main/services/{domain}`
**New IPC Handler:**
- Implementation: Add to existing `src/main/ipc/{domain}.ts` or create new domain file
- Channel constant: Add to `src/preload/constants/ipcChannels.ts`
- Registration: Add to `src/main/ipc/handlers.ts` if new domain
- API exposure: Add method to ElectronAPI in `src/preload/index.ts`
- Type: Update `@shared/types/api.ts` if needed
**New React Component:**
- Primary code: `src/renderer/components/{feature}/{ComponentName}.tsx`
- Feature categories: chat, common, dashboard, layout, notifications, search, settings, sidebar
- Tests: `test/renderer/components/{feature}/{ComponentName}.test.tsx`
**New Zustand Slice:**
- Implementation: `src/renderer/store/slices/{domain}Slice.ts`
- Export: Add factory function `create{Domain}Slice`
- Integration: Add to store composition in `src/renderer/store/index.ts`
- Type: Update `AppState` in `src/renderer/store/types.ts`
**New Hook:**
- Implementation: `src/renderer/hooks/use{Name}.ts`
- Tests: `test/renderer/hooks/use{Name}.test.ts`
- Import: Direct import from file (no barrel exports for hooks)
**Utilities:**
- Main process: `src/main/utils/{utilityName}.ts`
- Renderer: `src/renderer/utils/{utilityName}.ts`
- Shared (pure): `src/shared/utils/{utilityName}.ts`
**Types:**
- Main process only: `src/main/types/{name}.ts`
- Renderer only: `src/renderer/types/{name}.ts`
- Shared across processes: `src/shared/types/{name}.ts`
## Special Directories
**node_modules/**
- Purpose: Package dependencies
- Generated: Yes (via `pnpm install`)
- Committed: No
**dist/ and dist-electron/**
- Purpose: Build output (production bundles)
- Generated: Yes (via `pnpm build`)
- Committed: No
**.planning/codebase/**
- Purpose: GSD codebase analysis documents
- Generated: Yes (via `/gsd:map-codebase`)
- Committed: Yes (planning metadata)
**.claude/plans/**
- Purpose: Feature implementation plans
- Generated: Yes (via `/gsd:plan-phase`)
- Committed: Yes (project planning)
**test/mocks/**
- Purpose: Test fixtures and mock data
- Generated: No (manually created)
- Committed: Yes (test infrastructure)
**resources/**
- Purpose: Application icons and assets
- Generated: No (manually created)
- Committed: Yes (app resources)
**src/renderer/components/chat/SessionContextPanel/**
- Purpose: Visible context tracking panel UI (6 context categories)
- Generated: No
- Committed: Yes
- Special: Deep component hierarchy with section wrappers and item renderers
**src/main/services/**
- Purpose: Domain-organized business logic
- Generated: No
- Committed: Yes
- Special: Each domain has barrel export (`index.ts`)
---
*Structure analysis: 2026-02-12*

506
.planning/codebase/TESTING.md
View file

@ -1,506 +0,0 @@
# Testing Patterns
**Analysis Date:** 2026-02-12
## Test Framework
**Runner:**
- Vitest 3.1.4
- Config: `/Users/bskim/claude-devtools/vitest.config.ts`
**Environment:**
- `happy-dom` 17.4.6 (DOM simulation)
- Globals enabled (`describe`, `it`, `expect` available without imports)
**Assertion Library:**
- Vitest built-in assertions (Chai-compatible API)
**Run Commands:**
```bash
pnpm test # Run all tests
pnpm test:watch # Watch mode
pnpm test:coverage # Coverage report
pnpm test:coverage:critical # Critical path coverage only
pnpm test:chunks # Chunk building tests
pnpm test:semantic # Semantic step extraction
pnpm test:noise # Noise filtering tests
pnpm test:task-filtering # Task tool filtering
```
## Test File Organization
**Location:**
Co-located in separate `test/` directory, mirroring source structure.
**Naming:**
`*.test.ts` - matches source file name exactly.
**Structure:**
```
test/
├── main/
│ ├── ipc/ # IPC handler tests
│ │ ├── configValidation.test.ts
│ │ └── guards.test.ts
│ ├── services/ # Service layer tests
│ │ ├── analysis/ # ChunkBuilder, etc.
│ │ ├── discovery/ # ProjectPathResolver, SessionSearcher
│ │ ├── infrastructure/ # FileWatcher
│ │ └── parsing/ # MessageClassifier, SessionParser
│ └── utils/ # Utility function tests
│ ├── jsonl.test.ts
│ ├── pathDecoder.test.ts
│ ├── pathValidation.test.ts
│ ├── regexValidation.test.ts
│ └── tokenizer.test.ts
├── renderer/
│ ├── hooks/ # Hook tests
│ │ ├── navigationUtils.test.ts
│ │ ├── useAutoScrollBottom.test.ts
│ │ ├── useSearchContextNavigation.test.ts
│ │ └── useVisibleAIGroup.test.ts
│ ├── store/ # Zustand store slice tests
│ │ ├── notificationSlice.test.ts
│ │ ├── paneSlice.test.ts
│ │ ├── pathResolution.test.ts
│ │ ├── sessionSlice.test.ts
│ │ ├── tabSlice.test.ts
│ │ └── tabUISlice.test.ts
│ └── utils/ # Renderer utilities
│ ├── claudeMdTracker.test.ts
│ ├── dateGrouping.test.ts
│ ├── formatters.test.ts
│ └── pathUtils.test.ts
├── shared/
│ └── utils/ # Shared utilities
│ ├── markdownSearchRendererAlignment.test.ts
│ ├── markdownTextSearch.test.ts
│ ├── modelParser.test.ts
│ └── tokenFormatting.test.ts
├── mocks/ # Test fixtures and mocks
│ └── electronAPI.ts # Mock window.electronAPI
└── setup.ts # Global test setup
```
## Test Structure
**Suite Organization:**
```typescript
import { describe, expect, it } from 'vitest';
import { ChunkBuilder } from '../../../../src/main/services/analysis/ChunkBuilder';
import { isAIChunk, isUserChunk } from '../../../../src/main/types';
describe('ChunkBuilder', () => {
const builder = new ChunkBuilder();
describe('buildChunks', () => {
it('should return empty array for empty input', () => {
const chunks = builder.buildChunks([]);
expect(chunks).toEqual([]);
});
it('should filter out sidechain messages', () => {
const messages = [
createMessage({ type: 'user', isSidechain: false }),
createMessage({ type: 'assistant', isSidechain: true }),
];
const chunks = builder.buildChunks(messages);
expect(chunks).toHaveLength(1);
expect(isUserChunk(chunks[0])).toBe(true);
});
});
describe('UserChunk creation', () => {
// Nested describe for logical grouping
});
});
```
**Patterns:**
- Top-level `describe` per class/module
- Nested `describe` per method/function
- Descriptive `it` statements ("should do X when Y")
- Arrange-Act-Assert pattern
## Fixtures and Factories
**Test Data:**
Helper functions to create test objects:
```typescript
/**
* Creates a minimal ParsedMessage for testing.
*/
function createMessage(overrides: Partial<ParsedMessage>): ParsedMessage {
return {
uuid: `msg-${Math.random().toString(36).slice(2, 11)}`,
parentUuid: null,
type: 'user',
timestamp: new Date(),
content: '',
isSidechain: false,
isMeta: false,
toolCalls: [],
toolResults: [],
...overrides,
};
}
/**
* Creates a minimal Process (subagent) for testing.
*/
function createSubagent(overrides: Partial<Process>): Process {
return {
id: `agent-${Math.random().toString(36).slice(2, 11)}`,
filePath: '/path/to/agent.jsonl',
parentTaskId: 'task-1',
description: 'Test subagent',
startTime: new Date(),
endTime: new Date(),
durationMs: 1000,
isOngoing: false,
messages: [],
metrics: {
inputTokens: 100,
outputTokens: 50,
cacheReadTokens: 0,
cacheCreationTokens: 0,
totalTokens: 150,
messageCount: 2,
durationMs: 1000,
},
...overrides,
};
}
```
**Location:**
Defined in test files (not centralized) for visibility and simplicity.
## Mocking
**Framework:** Vitest built-in mocking (`vi.fn()`, `vi.mock()`, `vi.spyOn()`)
**ElectronAPI Mock Pattern:**
```typescript
// test/mocks/electronAPI.ts
export interface MockElectronAPI {
getProjects: ReturnType<typeof vi.fn>;
getSessions: ReturnType<typeof vi.fn>;
getSessionsPaginated: ReturnType<typeof vi.fn>;
// ... all IPC methods
}
export function installMockElectronAPI(): MockElectronAPI {
const mock: MockElectronAPI = {
getProjects: vi.fn(),
getSessions: vi.fn(),
// ...
};
vi.stubGlobal('window', {
electronAPI: mock,
});
return mock;
}
// Usage in tests:
import { installMockElectronAPI, type MockElectronAPI } from '../../mocks/electronAPI';
describe('sessionSlice', () => {
let mockAPI: MockElectronAPI;
beforeEach(() => {
mockAPI = installMockElectronAPI();
});
it('should fetch sessions', async () => {
mockAPI.getSessions.mockResolvedValue([/* data */]);
// Test implementation
});
});
```
**Console Mocking:**
Automatic via `test/setup.ts` - all tests fail if unexpected console.error/warn occurs:
```typescript
// test/setup.ts
beforeEach(() => {
errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
});
afterEach(() => {
const unexpectedErrors = errorSpy.mock.calls.map(formatConsoleCall);
const unexpectedWarnings = warnSpy.mock.calls.map(formatConsoleCall);
errorSpy.mockRestore();
warnSpy.mockRestore();
expect(unexpectedErrors, `Unexpected console.error calls:\n${unexpectedErrors.join('\n')}`).toEqual([]);
expect(unexpectedWarnings, `Unexpected console.warn calls:\n${unexpectedWarnings.join('\n')}`).toEqual([]);
});
```
**What to Mock:**
- `window.electronAPI` - Always mock in renderer tests
- File system operations - Mock when testing logic, not I/O
- External dependencies - Mock when testing integration points
**What NOT to Mock:**
- Internal utilities (test them directly)
- Type guards (pure functions)
- Formatters and transformers (integration is valuable)
## Coverage
**Requirements:** No enforced minimum (quality over coverage)
**Provider:** v8 (native V8 coverage)
**Reporters:**
- `text` - Terminal output
- `json` - Machine-readable
- `html` - Interactive browser report
**View Coverage:**
```bash
pnpm test:coverage # Full coverage
pnpm test:coverage:critical # Critical paths only
```
**Includes:**
- `src/**/*.ts`
- `src/**/*.tsx`
**Excludes:**
- `src/**/*.d.ts` (type definitions)
- `src/main/index.ts` (entry point)
- `src/preload/index.ts` (entry point)
**Critical Path Config:**
Separate config at `/Users/bskim/claude-devtools/vitest.critical.config.ts` focuses on:
- Chunk building (`ChunkBuilder.test.ts`)
- Message classification (`MessageClassifier.test.ts`)
- Session parsing (`SessionParser.test.ts`)
## Test Types
**Unit Tests:**
Test individual functions, classes, and utilities in isolation.
**Example:**
```typescript
describe('pathDecoder', () => {
describe('encodePath', () => {
it('should encode absolute POSIX paths', () => {
expect(encodePath('/Users/username/project')).toBe('-Users-username-project');
});
it('should encode Windows paths', () => {
expect(encodePath('C:\\Users\\username\\project')).toBe('-C:-Users-username-project');
});
});
});
```
**Integration Tests:**
Test interactions between modules (e.g., ChunkBuilder + MessageClassifier).
**Example:**
```typescript
it('should link subagents to AIChunks', () => {
const messages = [
createMessage({ type: 'assistant', toolCalls: [{ isTask: true, id: 'task-1' }] }),
];
const subagents = [
createSubagent({ parentTaskId: 'task-1' }),
];
const chunks = builder.buildChunks(messages, subagents);
const aiChunk = chunks.find(isAIChunk);
expect(aiChunk?.subagents).toHaveLength(1);
});
```
**Store Tests:**
Test Zustand slice behavior (state updates, async actions).
**Example:**
```typescript
describe('sessionSlice', () => {
it('should update sessions on fetch', async () => {
mockAPI.getSessions.mockResolvedValue([
{ id: 'session-1', createdAt: '2024-01-15T10:00:00Z' },
]);
await store.getState().fetchSessions('project-1');
expect(store.getState().sessions).toHaveLength(1);
expect(store.getState().sessionsLoading).toBe(false);
});
});
```
**E2E Tests:**
Not currently implemented.
## Common Patterns
**Async Testing:**
```typescript
it('should handle async operations', async () => {
mockAPI.getSessions.mockResolvedValue([/* data */]);
await store.getState().fetchSessions('project-1');
expect(store.getState().sessions).toHaveLength(1);
});
```
**Error Testing:**
```typescript
it('should handle fetch error', async () => {
mockAPI.getSessions.mockRejectedValue(new Error('Network error'));
await store.getState().fetchSessions('project-1');
expect(store.getState().sessionsError).toBe('Network error');
expect(store.getState().sessionsLoading).toBe(false);
});
```
**Timing/Debounce Testing:**
```typescript
it('should debounce rapid calls', async () => {
vi.useFakeTimers();
const callback = vi.fn();
const debounced = debounce(callback, 100);
debounced();
debounced();
debounced();
vi.advanceTimersByTime(100);
expect(callback).toHaveBeenCalledTimes(1);
vi.useRealTimers();
});
```
**State Transitions:**
```typescript
it('should set loading state during fetch', async () => {
mockAPI.getSessions.mockImplementation(
() => new Promise(resolve => setTimeout(() => resolve([]), 100))
);
const fetchPromise = store.getState().fetchSessions('project-1');
expect(store.getState().sessionsLoading).toBe(true);
await fetchPromise;
expect(store.getState().sessionsLoading).toBe(false);
});
```
## Test-Specific ESLint Relaxations
Tests use relaxed TypeScript rules (from `eslint.config.js`):
```typescript
// Relaxed for tests
'@typescript-eslint/no-explicit-any': 'off',
'@typescript-eslint/no-non-null-assertion': 'off',
'@typescript-eslint/no-unsafe-assignment': 'off',
'@typescript-eslint/no-unsafe-member-access': 'off',
'@typescript-eslint/no-unsafe-call': 'off',
'@typescript-eslint/no-unsafe-argument': 'off',
'@typescript-eslint/no-unsafe-return': 'off',
'@typescript-eslint/unbound-method': 'off',
'@typescript-eslint/no-floating-promises': 'off',
```
**Rationale:** Test code prioritizes readability and flexibility over type safety.
## Setup and Teardown
**Global Setup:**
`/Users/bskim/claude-devtools/test/setup.ts` runs before each test file:
- Mocks `process.env.HOME`
- Installs console spies (fail on unexpected errors/warnings)
**Per-Suite Setup:**
```typescript
describe('MyService', () => {
let mockAPI: MockElectronAPI;
let store: TestStore;
beforeEach(() => {
mockAPI = installMockElectronAPI();
store = createTestStore();
});
afterEach(() => {
vi.restoreAllMocks();
});
});
```
## Path Aliases in Tests
Vitest config mirrors TypeScript paths:
```typescript
resolve: {
alias: {
'@shared': resolve(__dirname, 'src/shared'),
'@main': resolve(__dirname, 'src/main'),
'@renderer': resolve(__dirname, 'src/renderer'),
},
}
```
Use same aliases as source code:
```typescript
import { ChunkBuilder } from '@main/services';
import { useStore } from '@renderer/store';
import { formatTokens } from '@shared/utils/tokenFormatting';
```
## Best Practices
**Test Independence:**
Each test should run independently - no shared state between tests.
**Descriptive Names:**
```typescript
// Good
it('should return empty array when no messages provided', () => {});
// Bad
it('returns []', () => {});
```
**Single Assertion Focus:**
Prefer multiple small tests over one large test with many assertions.
**Factory Functions:**
Use factory functions for test data creation - more maintainable than inline objects.
**Mock Minimally:**
Only mock external boundaries (IPC, file system) - test real logic.
**Console Discipline:**
If a test legitimately logs errors, it will fail. Either:
1. Fix the code to not log errors
2. Mock the specific logger call
3. Adjust test expectations
---
*Testing analysis: 2026-02-12*

12
.planning/config.json
View file

@ -1,12 +0,0 @@
{
"mode": "yolo",
"depth": "quick",
"parallelization": true,
"commit_docs": false,
"model_profile": "balanced",
"workflow": {
"research": true,
"plan_check": false,
"verifier": false
}
}

329
.planning/phases/01-provider-plumbing/01-01-PLAN.md
View file

@ -1,329 +0,0 @@
---
phase: 01-provider-plumbing
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- src/main/services/discovery/ProjectScanner.ts
- src/main/services/parsing/SessionParser.ts
- src/main/services/discovery/SubagentResolver.ts
- src/main/services/analysis/SubagentDetailBuilder.ts
- src/main/services/analysis/ChunkBuilder.ts
- test/main/services/parsing/SessionParser.test.ts
autonomous: true
must_haves:
truths:
- "SessionParser.parseSessionFile() passes FileSystemProvider to parseJsonlFile()"
- "SubagentResolver.parseSubagentFile() passes FileSystemProvider to parseJsonlFile()"
- "SubagentDetailBuilder uses FileSystemProvider.exists() instead of fs.access()"
- "SubagentDetailBuilder constructs paths using ProjectScanner.getSubagentsPath() instead of os.homedir()"
- "No service in the parsing stack imports fs/promises directly for session data reads"
artifacts:
- path: "src/main/services/discovery/ProjectScanner.ts"
provides: "getFileSystemProvider() getter"
contains: "getFileSystemProvider"
- path: "src/main/services/parsing/SessionParser.ts"
provides: "Provider-aware session parsing"
contains: "getFileSystemProvider"
- path: "src/main/services/discovery/SubagentResolver.ts"
provides: "Provider-aware subagent resolution"
contains: "getFileSystemProvider"
- path: "src/main/services/analysis/SubagentDetailBuilder.ts"
provides: "Provider-aware subagent detail building"
contains: "fsProvider"
key_links:
- from: "src/main/services/parsing/SessionParser.ts"
to: "src/main/utils/jsonl.ts"
via: "parseJsonlFile(filePath, provider)"
pattern: "parseJsonlFile\\(.*,.*getFileSystemProvider"
- from: "src/main/services/discovery/SubagentResolver.ts"
to: "src/main/utils/jsonl.ts"
via: "parseJsonlFile(filePath, provider)"
pattern: "parseJsonlFile\\(.*,.*getFileSystemProvider"
- from: "src/main/services/analysis/SubagentDetailBuilder.ts"
to: "src/main/services/infrastructure/FileSystemProvider.ts"
via: "fsProvider.exists() replaces fs.access()"
pattern: "fsProvider\\.exists"
---
<objective>
Thread FileSystemProvider through the entire session parsing stack so SSH sessions load correctly.
Purpose: Currently, SessionParser, SubagentResolver, and SubagentDetailBuilder all call parseJsonlFile() without passing a FileSystemProvider, causing silent fallback to LocalFileSystemProvider. In SSH mode, this means sessions show "No conversation history" because the local filesystem has no matching files. SubagentDetailBuilder additionally hardcodes os.homedir() for path construction. This plan fixes all three services to use the provider from ProjectScanner.
Output: All three services use FileSystemProvider consistently. SSH sessions display full conversation history and subagent drill-down works over SFTP.
</objective>
<execution_context>
@/Users/bskim/.claude/get-shit-done/workflows/execute-plan.md
@/Users/bskim/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-provider-plumbing/01-RESEARCH.md
@src/main/services/infrastructure/FileSystemProvider.ts
@src/main/services/discovery/ProjectScanner.ts
@src/main/services/parsing/SessionParser.ts
@src/main/services/discovery/SubagentResolver.ts
@src/main/services/analysis/SubagentDetailBuilder.ts
@src/main/services/analysis/ChunkBuilder.ts
@src/main/utils/jsonl.ts
@src/main/ipc/subagents.ts
@src/main/index.ts
</context>
<tasks>
<task type="auto">
<name>Task 1: Add provider getter to ProjectScanner and thread through SessionParser + SubagentResolver</name>
<files>
src/main/services/discovery/ProjectScanner.ts
src/main/services/parsing/SessionParser.ts
src/main/services/discovery/SubagentResolver.ts
test/main/services/parsing/SessionParser.test.ts
</files>
<action>
**ProjectScanner (1 change):**
Add a public getter method `getFileSystemProvider()` that returns `this.fsProvider`. Place it in the "Utility Methods" section near `getProjectsDir()` and `getTodosDir()`:
```typescript
getFileSystemProvider(): FileSystemProvider {
return this.fsProvider;
}
```
This requires adding `FileSystemProvider` to the type imports (it's currently only imported as a type for the constructor parameter — verify the import is accessible for the return type annotation).
**SessionParser (2 changes):**
1. In `parseSessionFile()` (line 77), change:
```typescript
const messages = await parseJsonlFile(filePath);
```
to:
```typescript
const messages = await parseJsonlFile(filePath, this.projectScanner.getFileSystemProvider());
```
2. In `parseSubagentFile()` (line 342), change:
```typescript
const messages = await parseJsonlFile(filePath);
```
to:
```typescript
const messages = await parseJsonlFile(filePath, this.projectScanner.getFileSystemProvider());
```
No constructor changes needed — SessionParser already receives ProjectScanner in its constructor.
**SubagentResolver (1 change):**
In the private `parseSubagentFile()` method (line 88), change:
```typescript
const messages = await parseJsonlFile(filePath);
```
to:
```typescript
const messages = await parseJsonlFile(filePath, this.projectScanner.getFileSystemProvider());
```
No constructor changes needed — SubagentResolver already receives ProjectScanner in its constructor.
**Test updates (SessionParser.test.ts):**
The existing `mockProjectScanner` object (lines 24-33) must include the new `getFileSystemProvider` method. Add:
```typescript
getFileSystemProvider: vi.fn().mockReturnValue(new LocalFileSystemProvider()),
```
Import `LocalFileSystemProvider` from `@main/services/infrastructure/LocalFileSystemProvider` (or use a minimal mock object with type 'local' if import resolution is an issue in tests — check the existing test's module resolution).
</action>
<verify>
Run `pnpm typecheck` — no type errors in the modified files.
Run `pnpm test test/main/services/parsing/SessionParser.test.ts` — all existing tests pass.
Grep for bare `parseJsonlFile(filePath)` calls (without second argument) in SessionParser.ts and SubagentResolver.ts — should find zero matches:
```bash
grep -n 'parseJsonlFile(filePath)' src/main/services/parsing/SessionParser.ts src/main/services/discovery/SubagentResolver.ts
```
</verify>
<done>
SessionParser.parseSessionFile() and parseSubagentFile() both pass FileSystemProvider to parseJsonlFile(). SubagentResolver.parseSubagentFile() passes FileSystemProvider to parseJsonlFile(). ProjectScanner exposes getFileSystemProvider() getter. All existing SessionParser tests pass with updated mock.
</done>
</task>
<task type="auto">
<name>Task 2: Fix SubagentDetailBuilder to use FileSystemProvider instead of hardcoded fs/os imports</name>
<files>
src/main/services/analysis/SubagentDetailBuilder.ts
src/main/services/analysis/ChunkBuilder.ts
</files>
<action>
**SubagentDetailBuilder (major refactor of buildSubagentDetail function):**
The current function (lines 39-135) has three problems:
1. Imports `fs/promises` dynamically (line 48) — bypasses provider abstraction
2. Uses `os.homedir()` to construct paths (line 53) — always resolves to local home directory
3. Uses `fs.access()` for existence check (line 58) — bypasses provider abstraction
Refactor the function signature to accept `fsProvider` and `projectsDir` parameters:
```typescript
export async function buildSubagentDetail(
projectId: string,
_sessionId: string,
subagentId: string,
sessionParser: SessionParser,
subagentResolver: SubagentResolver,
buildChunksFn: (messages: ParsedMessage[], subagents: Process[]) => EnhancedChunk[],
fsProvider: FileSystemProvider,
projectsDir: string
): Promise<SubagentDetail | null>
```
Replace the function body's path construction and existence check (lines 47-62):
- Remove the dynamic `fs`, `path`, `os` imports at lines 48-50.
- Add a static `import * as path from 'path'` at the top of the file (alongside existing imports).
- Add `import type { FileSystemProvider } from '../infrastructure/FileSystemProvider'` at the top.
- Replace path construction:
```typescript
// OLD (lines 53-54):
const claudeDir = path.join(os.homedir(), '.claude', 'projects');
const subagentPath = path.join(claudeDir, projectId, 'subagents', `agent-${subagentId}.jsonl`);
// NEW:
const subagentPath = path.join(projectsDir, projectId, 'subagents', `agent-${subagentId}.jsonl`);
```
- Replace existence check:
```typescript
// OLD (lines 57-62):
try {
await fs.access(subagentPath);
} catch {
logger.warn(`Subagent file not found: ${subagentPath}`);
return null;
}
// NEW:
if (!(await fsProvider.exists(subagentPath))) {
logger.warn(`Subagent file not found: ${subagentPath}`);
return null;
}
```
The rest of the function body (lines 64-134) can remain unchanged — it delegates to `sessionParser.parseSessionFile()` and `subagentResolver.resolveSubagents()` which now use the provider from Task 1.
**ChunkBuilder (update the delegation call):**
In `ChunkBuilder.buildSubagentDetail()` (lines 426-442), update the call to pass the new parameters. The ChunkBuilder needs access to `fsProvider` and `projectsDir`. Two options — use the simpler one: pass them as parameters from the IPC layer.
Update `ChunkBuilder.buildSubagentDetail()` signature and implementation:
```typescript
async buildSubagentDetail(
projectId: string,
sessionId: string,
subagentId: string,
sessionParser: SessionParser,
subagentResolver: SubagentResolver,
fsProvider: FileSystemProvider,
projectsDir: string
): Promise<SubagentDetail | null> {
return buildSubagentDetailFn(
projectId,
sessionId,
subagentId,
sessionParser,
subagentResolver,
(messages, subagents) => this.buildChunks(messages, subagents),
fsProvider,
projectsDir
);
}
```
Add `import type { FileSystemProvider } from '../infrastructure/FileSystemProvider'` to ChunkBuilder.ts imports if not already present.
**IPC subagents.ts (update the call site):**
In `handleGetSubagentDetail()` (line 101), the call to `chunkBuilder.buildSubagentDetail()` needs `fsProvider` and `projectsDir`. The subagent handler module has access to `sessionParser` which has `projectScanner`. However, the handler doesn't have direct access to projectScanner.
Add `projectScanner` to the subagent handler's service dependencies:
1. Add `let projectScanner: ProjectScanner;` to the module-level service variables
2. Update `initializeSubagentHandlers` to accept and store `projectScanner`
3. In the handler, get provider and projectsDir from projectScanner:
```typescript
const fsProvider = projectScanner.getFileSystemProvider();
const projectsDir = projectScanner.getProjectsDir();
```
4. Pass them to the call:
```typescript
const builtDetail = await chunkBuilder.buildSubagentDetail(
safeProjectId,
safeSessionId,
safeSubagentId,
sessionParser,
subagentResolver,
fsProvider,
projectsDir
);
```
**IPC handlers.ts (update initialization calls):**
Update `initializeSubagentHandlers` calls in both `initializeIpcHandlers` and `reinitializeServiceHandlers` to pass `scanner`:
```typescript
initializeSubagentHandlers(builder, cache, parser, resolver, scanner);
```
**src/main/index.ts** — no changes needed since it calls `initializeIpcHandlers` and `reinitializeServiceHandlers` which will propagate the change.
</action>
<verify>
Run `pnpm typecheck` — no type errors across the entire project.
Run `pnpm test` — all tests pass (especially ChunkBuilder tests).
Grep for `fs/promises` or `os.homedir` in SubagentDetailBuilder.ts — should find zero matches:
```bash
grep -n "fs/promises\|os\.homedir" src/main/services/analysis/SubagentDetailBuilder.ts
```
Grep for bare `parseJsonlFile(filePath)` (without second arg) across all services — should find zero matches:
```bash
grep -rn 'parseJsonlFile(filePath)$' src/main/services/
```
</verify>
<done>
SubagentDetailBuilder uses fsProvider.exists() instead of fs.access(), constructs paths using projectsDir parameter instead of os.homedir(), and no longer imports fs/promises or os. ChunkBuilder passes fsProvider and projectsDir through to SubagentDetailBuilder. IPC subagent handler obtains provider from ProjectScanner and passes it through the call chain. Full session parsing and subagent drill-down chain uses FileSystemProvider consistently.
</done>
</task>
</tasks>
<verification>
After both tasks are complete, verify the full provider chain:
1. **Type safety:** `pnpm typecheck` passes with zero errors
2. **Test suite:** `pnpm test` passes — all existing tests remain green
3. **No local filesystem leaks in services:**
```bash
# Should find ZERO matches in these three files:
grep -n "fs/promises\|fs\.access\|os\.homedir\|parseJsonlFile(filePath)" \
src/main/services/parsing/SessionParser.ts \
src/main/services/discovery/SubagentResolver.ts \
src/main/services/analysis/SubagentDetailBuilder.ts
```
4. **Provider flows through entire chain:** Trace the call path:
- `index.ts` creates `ProjectScanner(projectsDir, undefined, provider)` in SSH mode
- `SessionParser.parseSessionFile()` calls `parseJsonlFile(filePath, this.projectScanner.getFileSystemProvider())`
- `SubagentResolver.parseSubagentFile()` calls `parseJsonlFile(filePath, this.projectScanner.getFileSystemProvider())`
- `SubagentDetailBuilder.buildSubagentDetail()` receives `fsProvider` and `projectsDir`, uses `fsProvider.exists()` for file check
</verification>
<success_criteria>
- All parseJsonlFile() calls in SessionParser and SubagentResolver pass the FileSystemProvider from ProjectScanner
- SubagentDetailBuilder does not import fs/promises, os, or use os.homedir()
- SubagentDetailBuilder uses fsProvider.exists() for file existence checks
- SubagentDetailBuilder uses projectsDir parameter for path construction (not hardcoded ~/.claude/projects)
- pnpm typecheck passes
- pnpm test passes
- The provider chain is complete: SSH provider set in index.ts flows all the way to parseJsonlFile() in every code path
</success_criteria>
<output>
After completion, create `.planning/phases/01-provider-plumbing/01-01-SUMMARY.md`
</output>

153
.planning/phases/01-provider-plumbing/01-01-SUMMARY.md
View file

@ -1,153 +0,0 @@
---
phase: 01-provider-plumbing
plan: 01
subsystem: session-parsing
tags: [ssh-support, provider-threading, refactoring]
dependency-graph:
requires: [FileSystemProvider, ProjectScanner]
provides: [provider-aware-parsing, provider-aware-subagent-detail]
affects: [SessionParser, SubagentResolver, SubagentDetailBuilder, ChunkBuilder, IPC-handlers]
tech-stack:
added: []
patterns: [provider-injection, dependency-threading]
key-files:
created: []
modified:
- src/main/services/discovery/ProjectScanner.ts
- src/main/services/parsing/SessionParser.ts
- src/main/services/discovery/SubagentResolver.ts
- src/main/services/analysis/SubagentDetailBuilder.ts
- src/main/services/analysis/ChunkBuilder.ts
- src/main/ipc/subagents.ts
- src/main/ipc/handlers.ts
- test/main/services/parsing/SessionParser.test.ts
decisions:
- "Added getFileSystemProvider() getter to ProjectScanner for consistent provider access across services"
- "Threaded provider through all three parseJsonlFile() call sites instead of relying on optional parameter fallback"
- "Refactored SubagentDetailBuilder to accept fsProvider and projectsDir as explicit parameters instead of using dynamic imports"
- "Propagated ProjectScanner to IPC subagent handler to obtain provider and projectsDir at runtime"
metrics:
duration: 4
completed: 2026-02-12T00:15:16Z
---
# Phase 01 Plan 01: Thread FileSystemProvider Through Session Parsing Stack Summary
**FileSystemProvider now flows consistently from ProjectScanner through SessionParser, SubagentResolver, and SubagentDetailBuilder, enabling SSH sessions to load conversation history over SFTP.**
## What Was Built
Threaded the `FileSystemProvider` abstraction through the entire session parsing stack, eliminating silent fallbacks to `LocalFileSystemProvider` that caused SSH sessions to show "No conversation history."
### Task 1: Provider Threading Through SessionParser and SubagentResolver
Added `getFileSystemProvider()` getter to `ProjectScanner` and updated three `parseJsonlFile()` call sites to pass the provider:
1. **ProjectScanner.getFileSystemProvider()** - New getter exposes the provider instance
2. **SessionParser.parseSessionFile()** - Now passes `this.projectScanner.getFileSystemProvider()` to `parseJsonlFile()`
3. **SessionParser.parseSubagentFile()** - Now passes `this.projectScanner.getFileSystemProvider()` to `parseJsonlFile()`
4. **SubagentResolver.parseSubagentFile()** - Now passes `this.projectScanner.getFileSystemProvider()` to `parseJsonlFile()`
Updated `SessionParser.test.ts` mock to include `getFileSystemProvider` method returning `LocalFileSystemProvider` instance.
**Commit:** `a3f5daf` - feat(01-01): thread FileSystemProvider through SessionParser and SubagentResolver
### Task 2: Refactor SubagentDetailBuilder to Use Provider
Removed hardcoded `fs/promises`, `os.homedir()`, and `fs.access()` calls from `SubagentDetailBuilder`, replacing them with provider-based operations:
1. **SubagentDetailBuilder.buildSubagentDetail()** - Added `fsProvider` and `projectsDir` parameters, removed dynamic imports of `fs/promises`, `os`, replaced `os.homedir()` with `projectsDir`, replaced `fs.access()` with `fsProvider.exists()`
2. **ChunkBuilder.buildSubagentDetail()** - Added `fsProvider` and `projectsDir` parameters, passed through to `buildSubagentDetailFn()`
3. **IPC subagents handler** - Updated `initializeSubagentHandlers()` to accept `ProjectScanner`, obtains `fsProvider` and `projectsDir` from scanner in `handleGetSubagentDetail()`
4. **IPC handlers.ts** - Updated both `initializeIpcHandlers()` and `reinitializeServiceHandlers()` to pass `scanner` to `initializeSubagentHandlers()`
**Commit:** `c12b329` - feat(01-01): refactor SubagentDetailBuilder to use FileSystemProvider
## Technical Implementation
### Provider Flow Architecture
```
index.ts (creates ProjectScanner with SSH provider)
└─> ProjectScanner.fsProvider (stored privately)
└─> ProjectScanner.getFileSystemProvider() (public getter)
├─> SessionParser.parseSessionFile() → parseJsonlFile(path, provider)
├─> SessionParser.parseSubagentFile() → parseJsonlFile(path, provider)
├─> SubagentResolver.parseSubagentFile() → parseJsonlFile(path, provider)
└─> IPC subagents handler → ChunkBuilder → SubagentDetailBuilder
├─> fsProvider.exists() (file check)
└─> projectsDir (path construction)
```
### Key Pattern Changes
**Before (Task 1):**
```typescript
const messages = await parseJsonlFile(filePath);
// Silently falls back to LocalFileSystemProvider
```
**After (Task 1):**
```typescript
const messages = await parseJsonlFile(filePath, this.projectScanner.getFileSystemProvider());
// Explicitly uses the provider from ProjectScanner
```
**Before (Task 2):**
```typescript
const fs = await import('fs/promises');
const os = await import('os');
const claudeDir = path.join(os.homedir(), '.claude', 'projects');
await fs.access(subagentPath);
// Always uses local filesystem, always assumes ~/.claude/projects
```
**After (Task 2):**
```typescript
const subagentPath = path.join(projectsDir, projectId, 'subagents', `agent-${subagentId}.jsonl`);
if (!(await fsProvider.exists(subagentPath))) { /* ... */ }
// Uses injected provider and projectsDir, works for both local and SSH
```
## Deviations from Plan
None - plan executed exactly as written.
## Testing & Verification
- **Type safety:** `pnpm typecheck` passes with zero errors
- **Test suite:** All 494 tests pass (31 test files)
- **No local filesystem leaks:** Verified zero matches for `fs/promises`, `os.homedir`, and bare `parseJsonlFile(filePath)` calls in SessionParser, SubagentResolver, and SubagentDetailBuilder
- **Provider flow confirmed:** All three services now receive FileSystemProvider from ProjectScanner's getter
## Impact
### Immediate
- SSH sessions will now load conversation history correctly (once SSH provider is fully wired in index.ts)
- Subagent drill-down will work over SFTP
- No more silent fallbacks to local filesystem in parsing stack
### Downstream
- Phase 1 Plans 02-04 can now implement provider-based operations for todos, watchers, and search
- All file operations in the parsing/analysis layer now use the provider abstraction consistently
## Self-Check: PASSED
### Created Files
No new files created (all modifications to existing files).
### Modified Files Verified
- [x] src/main/services/discovery/ProjectScanner.ts - Contains `getFileSystemProvider()` getter
- [x] src/main/services/parsing/SessionParser.ts - Both `parseJsonlFile()` calls pass provider
- [x] src/main/services/discovery/SubagentResolver.ts - `parseJsonlFile()` call passes provider
- [x] src/main/services/analysis/SubagentDetailBuilder.ts - No `fs/promises` or `os.homedir`, uses `fsProvider.exists()`
- [x] src/main/services/analysis/ChunkBuilder.ts - Passes `fsProvider` and `projectsDir` parameters
- [x] src/main/ipc/subagents.ts - Obtains provider from `ProjectScanner`
- [x] src/main/ipc/handlers.ts - Passes `scanner` to `initializeSubagentHandlers()`
- [x] test/main/services/parsing/SessionParser.test.ts - Mock includes `getFileSystemProvider()`
### Commits Verified
- [x] a3f5daf - Task 1 commit exists
- [x] c12b329 - Task 2 commit exists
All files exist, all commits present. Self-check passed.

350
.planning/phases/01-provider-plumbing/01-RESEARCH.md
View file

@ -1,350 +0,0 @@
# Phase 1: Provider Plumbing - Research
**Researched:** 2026-02-12
**Domain:** Electron main process service architecture, filesystem abstraction patterns
**Confidence:** HIGH
## Summary
Phase 1 requires threading `FileSystemProvider` through three critical parsing services (`SessionParser`, `SubagentResolver`, `SubagentDetailBuilder`) to enable SSH session loading. The current architecture already has the provider abstraction and SSH implementation in place, but the parsing stack hardcodes calls to `parseJsonlFile()` which defaults to local filesystem access. The fix is straightforward: pass `FileSystemProvider` through service constructors and method signatures to reach `parseJsonlFile()`, which already accepts an optional provider parameter.
The existing mode-switching architecture in `src/main/index.ts` (lines 96-136) provides the blueprint: when switching local↔SSH, services are recreated with the correct provider. However, Phase 1 only needs to ensure the provider threads through correctly; Phase 2 will handle multi-context infrastructure.
**Primary recommendation:** Add `FileSystemProvider` parameters to service constructors and method signatures following the existing `ProjectScanner` pattern, ensuring all `parseJsonlFile()` calls receive the correct provider instance.
## Standard Stack
### Core
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| ssh2 | (current) | SFTP implementation | Industry standard Node.js SSH/SFTP client, already used in `SshFileSystemProvider` |
| Node.js stream | Built-in | Streaming JSONL parsing | Native API, optimal for large file processing |
### Supporting
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| readline | Built-in | Line-by-line JSONL processing | Already used in `parseJsonlFile()` for streaming |
### Alternatives Considered
| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| Constructor injection | Service locator pattern | Constructor injection is explicit and testable; avoid service locator for this scope |
| Optional parameters | Required parameters | Keep optional for backward compatibility during refactor, but document the default |
**Installation:**
No new dependencies required. Existing code has all necessary abstractions.
## Architecture Patterns
### Recommended Project Structure
Current structure is correct:
```
src/main/
├── services/
│ ├── infrastructure/ # FileSystemProvider, LocalFileSystemProvider, SshFileSystemProvider
│ ├── parsing/ # SessionParser (NEEDS provider threading)
│ ├── discovery/ # SubagentResolver (NEEDS provider threading)
│ └── analysis/ # SubagentDetailBuilder (NEEDS provider threading)
├── utils/
│ └── jsonl.ts # parseJsonlFile() already accepts provider parameter
└── index.ts # Service instantiation, mode-switching handler
```
### Pattern 1: Provider Injection via Constructor
**What:** Pass `FileSystemProvider` to service constructors, store as instance field
**When to use:** For services that make multiple filesystem calls (SessionParser, SubagentResolver)
**Example:**
```typescript
// Source: Existing pattern in ProjectScanner (lines 78-89)
export class SessionParser {
private projectScanner: ProjectScanner;
private fsProvider: FileSystemProvider; // ADD THIS
constructor(projectScanner: ProjectScanner, fsProvider?: FileSystemProvider) {
this.projectScanner = projectScanner;
// Default to local provider if not specified
this.fsProvider = fsProvider ?? new LocalFileSystemProvider();
}
async parseSessionFile(filePath: string): Promise<ParsedSession> {
const messages = await parseJsonlFile(filePath, this.fsProvider); // PASS THROUGH
return this.processMessages(messages);
}
}
```
### Pattern 2: Provider Access via Delegation
**What:** Services that already have a `ProjectScanner` instance can get provider from it
**When to use:** When refactoring would be minimal and avoids parameter bloat
**Example:**
```typescript
// ProjectScanner already stores fsProvider (line 71)
export class SessionParser {
private projectScanner: ProjectScanner;
// Access provider through projectScanner
async parseSessionFile(filePath: string): Promise<ParsedSession> {
const provider = this.projectScanner.getFileSystemProvider();
const messages = await parseJsonlFile(filePath, provider);
return this.processMessages(messages);
}
}
```
**Note:** Pattern 2 requires adding a `getFileSystemProvider()` getter to `ProjectScanner`, but reduces constructor parameter changes and keeps provider access centralized.
### Pattern 3: SubagentDetailBuilder Function Signature
**What:** `buildSubagentDetail()` is a standalone function, not a class. Add provider parameter.
**When to use:** For functional builders called directly by IPC handlers
**Example:**
```typescript
// Current signature (line 39-46)
export async function buildSubagentDetail(
projectId: string,
_sessionId: string,
subagentId: string,
sessionParser: SessionParser,
subagentResolver: SubagentResolver,
buildChunksFn: (messages: ParsedMessage[], subagents: Process[]) => EnhancedChunk[]
): Promise<SubagentDetail | null>
// After Phase 1: add fsProvider parameter
export async function buildSubagentDetail(
projectId: string,
_sessionId: string,
subagentId: string,
sessionParser: SessionParser,
subagentResolver: SubagentResolver,
buildChunksFn: (messages: ParsedMessage[], subagents: Process[]) => EnhancedChunk[],
fsProvider: FileSystemProvider // ADD THIS
): Promise<SubagentDetail | null>
```
### Anti-Patterns to Avoid
- **Importing `fs/promises` directly in services:** SubagentDetailBuilder (lines 48-62) bypasses provider abstraction by using direct `fs.access()`. Replace with `fsProvider.exists()`.
- **Global default provider:** `jsonl.ts` line 36 creates `defaultProvider = new LocalFileSystemProvider()`. This is correct as a fallback, but services must explicitly pass their provider to avoid silent local fallback in SSH mode.
- **Provider singleton:** Do not create a global provider instance. Each service context needs its own provider instance (critical for Phase 2).
## Don't Hand-Roll
| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| SFTP read streams | Custom buffer management, chunk assembly | ssh2's `createReadStream()` piped to PassThrough | ssh2 handles SSH protocol details, reconnection, buffering; PassThrough ensures Node.js stream compatibility (see `SshFileSystemProvider.ts` lines 98-112) |
| Filesystem abstraction testing | Mock entire `fs` module | Inject `FileSystemProvider` interface | Interface injection enables clean testing without rewiring Node.js internals |
| Service lifecycle during mode switch | Manual cleanup tracking | Follow existing `handleModeSwitch()` pattern | Already proven pattern in `index.ts` lines 96-136: stop watchers, clear cache, recreate services |
**Key insight:** The provider abstraction already exists and works correctly (`FileSystemProvider`, `LocalFileSystemProvider`, `SshFileSystemProvider`). The problem is not the abstraction itself, but that some services bypass it. Don't rebuild the abstraction; just use it consistently.
## Common Pitfalls
### Pitfall 1: Silent Fallback to Local Provider
**What goes wrong:** `parseJsonlFile()` defaults to local provider when no provider is passed, causing SSH sessions to silently read local files (or fail with "file not found").
**Why it happens:** Optional parameter with default value in `jsonl.ts` line 52: `fsProvider: FileSystemProvider = defaultProvider`
**How to avoid:**
- Always explicitly pass provider to `parseJsonlFile()` in all service methods
- Add logging in development mode when default provider is used (helps catch missed call sites)
**Warning signs:**
- SSH mode shows "No conversation history" for sessions that definitely have messages
- Console logs from `jsonl.ts` show ENOENT errors for paths that should exist remotely
### Pitfall 2: Hardcoded Path Construction
**What goes wrong:** `SubagentDetailBuilder` constructs paths using `os.homedir()` + hardcoded `.claude/projects/` (lines 53-54), which always resolves to local filesystem even in SSH mode.
**Why it happens:** Function was written before SSH support, assumes single filesystem
**How to avoid:**
- Use `ProjectScanner` path utilities (`buildSessionPath`, `buildSubagentsPath`) which already handle encoding
- OR: Accept absolute file paths from callers who know the correct base directory
**Warning signs:**
- Subagent drill-down works locally but fails with "file not found" in SSH mode
- Path logging shows local home directory when SSH mode is active
### Pitfall 3: Forgetting Nested Subagent Resolution
**What goes wrong:** `SubagentDetailBuilder` calls `subagentResolver.resolveSubagents()` (line 68) which internally calls `parseJsonlFile()` multiple times. If `SubagentResolver.parseSubagentFile()` doesn't have the provider, nested subagents fail to load.
**Why it happens:** Chain of calls: `buildSubagentDetail()` → `SubagentResolver.resolveSubagents()` → `SubagentResolver.parseSubagentFile()` → `parseJsonlFile()`. Provider must thread through entire chain.
**How to avoid:**
- Test subagent drill-down specifically in SSH mode (not just session loading)
- Ensure `SubagentResolver` stores provider as instance field and uses it in `parseSubagentFile()`
**Warning signs:**
- Main session messages load correctly but subagent cards show "Failed to load" or empty state
- Subagent drill-down modal opens but shows no content
### Pitfall 4: Test Mocking Inconsistency
**What goes wrong:** Tests mock `ProjectScanner` but don't provide a `getFileSystemProvider()` method, causing tests to fail after refactoring.
**Why it happens:** Test mocks in `SessionParser.test.ts` (lines 24-33) are partial mocks missing new methods
**How to avoid:**
- Update test mocks to include `getFileSystemProvider()` returning a `LocalFileSystemProvider` instance
- Consider creating a `MockFileSystemProvider` test helper for consistent mocking
**Warning signs:**
- Tests pass before refactor, fail with "getFileSystemProvider is not a function" after
- Tests fail even though manual testing works
## Code Examples
Verified patterns from existing codebase:
### Example 1: Service Initialization with Provider (from main/index.ts)
```typescript
// Source: src/main/index.ts lines 111-113
const provider = sshConnectionManager.getProvider();
const projectsDir = mode === 'ssh'
? (sshConnectionManager.getRemoteProjectsPath() ?? undefined)
: undefined;
projectScanner = new ProjectScanner(projectsDir, undefined, provider);
sessionParser = new SessionParser(projectScanner);
subagentResolver = new SubagentResolver(projectScanner);
```
### Example 2: Existing Provider Pattern in ProjectScanner
```typescript
// Source: src/main/services/discovery/ProjectScanner.ts lines 78-89
constructor(projectsDir?: string, todosDir?: string, fsProvider?: FileSystemProvider) {
this.projectsDir = projectsDir ?? getProjectsBasePath();
this.todosDir = todosDir ?? getTodosBasePath();
this.fsProvider = fsProvider ?? new LocalFileSystemProvider();
// Initialize delegated services WITH PROVIDER
this.sessionContentFilter = SessionContentFilter;
this.worktreeGrouper = new WorktreeGrouper(this.projectsDir, this.fsProvider);
this.subagentLocator = new SubagentLocator(this.projectsDir, this.fsProvider);
this.sessionSearcher = new SessionSearcher(this.projectsDir, this.fsProvider);
this.projectPathResolver = new ProjectPathResolver(this.projectsDir, this.fsProvider);
}
```
### Example 3: parseJsonlFile with Provider Parameter
```typescript
// Source: src/main/utils/jsonl.ts lines 50-64
export async function parseJsonlFile(
filePath: string,
fsProvider: FileSystemProvider = defaultProvider // OPTIONAL with default
): Promise<ParsedMessage[]> {
const messages: ParsedMessage[] = [];
if (!(await fsProvider.exists(filePath))) {
return messages;
}
const fileStream = fsProvider.createReadStream(filePath, { encoding: 'utf8' });
const rl = readline.createInterface({
input: fileStream,
crlfDelay: Infinity,
});
for await (const line of rl) {
if (!line.trim()) continue;
try {
const parsed = parseJsonlLine(line);
if (parsed) {
messages.push(parsed);
}
} catch (error) {
logger.error(`Error parsing line in ${filePath}:`, error);
}
}
return messages;
}
```
### Example 4: Mode Switch Handler (Service Recreation Pattern)
```typescript
// Source: src/main/index.ts lines 96-136
const handleModeSwitch = async (mode: 'local' | 'ssh'): Promise<void> => {
logger.info(`Switching to ${mode} mode`);
// 1. Stop watchers
fileWatcher.stop();
// 2. Clear cache
dataCache.clear();
// 3. Get provider from connection manager
const provider = sshConnectionManager.getProvider();
const projectsDir = mode === 'ssh'
? (sshConnectionManager.getRemoteProjectsPath() ?? undefined)
: undefined;
// 4. Recreate services with new provider
projectScanner = new ProjectScanner(projectsDir, undefined, provider);
sessionParser = new SessionParser(projectScanner);
subagentResolver = new SubagentResolver(projectScanner);
// 5. Re-initialize IPC handlers with new instances
reinitializeServiceHandlers(
projectScanner,
sessionParser,
subagentResolver,
chunkBuilder,
dataCache
);
// 6. Update file watcher provider
fileWatcher.setFileSystemProvider(provider);
// 7. Restart watcher
fileWatcher.start();
// 8. Notify renderer
if (mainWindow && !mainWindow.isDestroyed()) {
mainWindow.webContents.send(SSH_STATUS, sshConnectionManager.getStatus());
}
logger.info(`Mode switch to ${mode} complete`);
};
```
## State of the Art
| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| Direct `fs` imports throughout services | `FileSystemProvider` abstraction | Added with SSH support (recent) | Enables remote file access, but not all services use it yet |
| Single global service instances | Mode-switching service recreation | Added with SSH support (recent) | Enables local↔SSH switching, but destroys local state (Phase 2 will fix) |
| Synchronous file reads | Streaming with readline | Original architecture | Efficient for large JSONL files, correct pattern |
**Deprecated/outdated:**
- Direct `fs/promises` imports in services: `SubagentDetailBuilder` still uses this (lines 48-50). Should be replaced with provider calls.
## Open Questions
1. **Should ProjectScanner expose `getFileSystemProvider()` or should services store their own reference?**
- What we know: ProjectScanner already stores `fsProvider` (line 71). SessionParser and SubagentResolver both receive ProjectScanner in constructor.
- What's unclear: Whether delegating through ProjectScanner is cleaner than duplicating the reference in each service.
- Recommendation: Add `getFileSystemProvider()` getter to ProjectScanner. Reduces constructor changes, centralizes provider access, matches existing delegation pattern (line 84 uses SessionContentFilter, lines 85-88 pass provider to delegated services).
2. **Should SubagentDetailBuilder become a class or stay a function?**
- What we know: It's currently a standalone function (line 39). IPC handler calls it directly. It needs access to `fsProvider`, `projectsDir`, and multiple service instances.
- What's unclear: Whether the complexity warrants a class or if adding parameters is sufficient.
- Recommendation: Keep as function for Phase 1, add `fsProvider` parameter. Phase 2 (ServiceContextRegistry) may benefit from a builder class, but don't pre-optimize.
3. **Do tests need a dedicated MockFileSystemProvider or just mock existing providers?**
- What we know: Tests currently mock ProjectScanner (test/main/services/parsing/SessionParser.test.ts lines 24-33). LocalFileSystemProvider is a real implementation.
- What's unclear: Whether tests should use real LocalFileSystemProvider with temp files, or mock it.
- Recommendation: Use real LocalFileSystemProvider for integration-style tests (current pattern). Mock only for unit tests that don't need real file I/O. Create `MockFileSystemProvider` helper if tests start duplicating mock setup.
## Sources
### Primary (HIGH confidence)
- Existing codebase files:
- `src/main/services/infrastructure/FileSystemProvider.ts` - Interface definition
- `src/main/services/infrastructure/SshFileSystemProvider.ts` - SSH implementation
- `src/main/services/discovery/ProjectScanner.ts` - Provider injection pattern
- `src/main/utils/jsonl.ts` - parseJsonlFile provider parameter
- `src/main/index.ts` - Mode-switching handler
- `.planning/ROADMAP.md` - Phase 1 requirements and success criteria
- `.planning/REQUIREMENTS.md` - PROV-01, PROV-02 detailed requirements
### Secondary (MEDIUM confidence)
- None required; all information sourced from codebase inspection
### Tertiary (LOW confidence)
- None
## Metadata
**Confidence breakdown:**
- Standard stack: HIGH - No external libraries needed, existing abstractions are complete
- Architecture: HIGH - Patterns already proven in ProjectScanner and delegated services
- Pitfalls: HIGH - All identified from actual code inspection and known failure modes
**Research date:** 2026-02-12
**Valid until:** 30 days (stable architecture, no fast-moving dependencies)

208
.planning/phases/02-service-infrastructure/02-01-PLAN.md
View file

@ -1,208 +0,0 @@
---
phase: 02-service-infrastructure
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- src/main/services/infrastructure/ServiceContext.ts
- src/main/services/infrastructure/ServiceContextRegistry.ts
- src/main/services/infrastructure/index.ts
- src/main/services/infrastructure/FileWatcher.ts
- src/main/services/infrastructure/DataCache.ts
autonomous: true
must_haves:
truths:
- "ServiceContext bundles all session-data services for a single workspace context"
- "ServiceContextRegistry manages local + N SSH contexts with create/switch/destroy lifecycle"
- "Local context is always alive and cannot be destroyed"
- "All EventEmitter-based services have comprehensive dispose() methods that prevent memory leaks"
- "FileWatcher dispose() clears all timers, watchers, tracking maps, and listeners"
artifacts:
- path: "src/main/services/infrastructure/ServiceContext.ts"
provides: "Service bundle class for a single workspace context"
exports: ["ServiceContext", "ServiceContextConfig"]
- path: "src/main/services/infrastructure/ServiceContextRegistry.ts"
provides: "Registry coordinator for all contexts"
exports: ["ServiceContextRegistry"]
- path: "src/main/services/infrastructure/FileWatcher.ts"
provides: "dispose() method on FileWatcher"
contains: "dispose()"
- path: "src/main/services/infrastructure/DataCache.ts"
provides: "dispose() method on DataCache"
contains: "dispose()"
key_links:
- from: "src/main/services/infrastructure/ServiceContextRegistry.ts"
to: "src/main/services/infrastructure/ServiceContext.ts"
via: "creates ServiceContext instances"
pattern: "new ServiceContext"
- from: "src/main/services/infrastructure/ServiceContext.ts"
to: "src/main/services/infrastructure/FileWatcher.ts"
via: "creates and owns FileWatcher instance"
pattern: "new FileWatcher"
- from: "src/main/services/infrastructure/ServiceContext.ts"
to: "src/main/services/infrastructure/DataCache.ts"
via: "creates and owns DataCache instance"
pattern: "new DataCache"
---
<objective>
Create the ServiceContext bundle class and ServiceContextRegistry coordinator, plus add comprehensive dispose() methods to all EventEmitter-based services.
Purpose: These are the foundational types for multi-context support. ServiceContext encapsulates all session-data services for a single workspace (local or SSH). ServiceContextRegistry manages the Map of contexts, tracks the active context, and enforces lifecycle rules (local never destroyed, proper cleanup on destroy).
Output: Two new TypeScript files (ServiceContext.ts, ServiceContextRegistry.ts), updated dispose methods on FileWatcher and DataCache, updated barrel exports.
</objective>
<execution_context>
@.planning/phases/02-service-infrastructure/02-RESEARCH.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/01-provider-plumbing/01-01-SUMMARY.md
@src/main/services/infrastructure/FileSystemProvider.ts
@src/main/services/infrastructure/FileWatcher.ts
@src/main/services/infrastructure/DataCache.ts
@src/main/services/infrastructure/LocalFileSystemProvider.ts
@src/main/services/discovery/ProjectScanner.ts
@src/main/services/parsing/SessionParser.ts
@src/main/services/discovery/SubagentResolver.ts
@src/main/services/analysis/ChunkBuilder.ts
@src/main/services/infrastructure/index.ts
@src/main/index.ts
</context>
<tasks>
<task type="auto">
<name>Task 1: Create ServiceContext and ServiceContextRegistry</name>
<files>
src/main/services/infrastructure/ServiceContext.ts
src/main/services/infrastructure/ServiceContextRegistry.ts
src/main/services/infrastructure/index.ts
</files>
<action>
**ServiceContext.ts** - Create a service bundle class:
1. Define `ServiceContextConfig` interface:
- `id: string` (e.g., 'local', 'ssh-myserver')
- `type: 'local' | 'ssh'`
- `fsProvider: FileSystemProvider`
- `projectsDir?: string` (defaults to getProjectsBasePath())
- `todosDir?: string` (defaults to getTodosBasePath())
2. Define `ServiceContext` class with:
- Readonly properties: `id`, `type`
- Service instances (all readonly): `projectScanner: ProjectScanner`, `sessionParser: SessionParser`, `subagentResolver: SubagentResolver`, `chunkBuilder: ChunkBuilder`, `dataCache: DataCache`, `fileWatcher: FileWatcher`
- `fsProvider: FileSystemProvider` (readonly, stored for reference)
- Constructor that creates all services with correct dependency chain:
- `projectScanner = new ProjectScanner(config.projectsDir, config.todosDir, config.fsProvider)`
- `sessionParser = new SessionParser(this.projectScanner)`
- `subagentResolver = new SubagentResolver(this.projectScanner)`
- `chunkBuilder = new ChunkBuilder()`
- `dataCache = new DataCache(MAX_CACHE_SESSIONS, CACHE_TTL_MINUTES, !disableCache)` where `disableCache = process.env.CLAUDE_CONTEXT_DISABLE_CACHE === '1'`
- `fileWatcher = new FileWatcher(this.dataCache)` — do NOT call setFileSystemProvider here; FileWatcher uses local fs by default and the setFileSystemProvider pattern is used externally. Actually, looking at the code, FileWatcher stores an fsProvider internally. Check its constructor — if it accepts a provider, pass it. If not, call `setFileSystemProvider(config.fsProvider)` after construction.
- `start()` method: calls `fileWatcher.start()` and `dataCache.startAutoCleanup(CACHE_CLEANUP_INTERVAL_MINUTES)`, stores the cleanup interval handle
- `stopFileWatcher()` method: calls `fileWatcher.stop()` (for pausing on context switch)
- `startFileWatcher()` method: calls `fileWatcher.start()` (for resuming on context switch)
- `dispose()` method: calls `fileWatcher.dispose()`, `dataCache.dispose()`, clears cleanup interval. Does NOT dispose fsProvider (ownership belongs to SshConnectionManager per research).
Import constants from `@shared/constants`: `MAX_CACHE_SESSIONS`, `CACHE_TTL_MINUTES`, `CACHE_CLEANUP_INTERVAL_MINUTES`.
**ServiceContextRegistry.ts** - Create the registry coordinator:
1. Define `ServiceContextRegistry` class:
- `private contexts = new Map<string, ServiceContext>()`
- `private activeContextId: string = 'local'`
- Constructor takes NO arguments. It does NOT create the local context internally (that happens in index.ts where the mainWindow and notification manager wiring exists).
- `registerContext(context: ServiceContext): void` — adds to map, throws if id already exists
- `getActive(): ServiceContext` — returns context for activeContextId, throws if not found
- `get(contextId: string): ServiceContext | undefined` — returns context by id
- `has(contextId: string): boolean` — check existence
- `switch(contextId: string): { previous: ServiceContext; current: ServiceContext }` — validates contextId exists, stops file watcher on previous context, sets activeContextId, starts file watcher on new context, returns both contexts for caller to do IPC re-init
- `destroy(contextId: string): void` — throws if 'local', calls context.dispose(), removes from map, if activeContextId was this context switch to 'local'
- `list(): Array<{ id: string; type: 'local' | 'ssh' }>` — returns metadata for all contexts
- `getActiveContextId(): string` — getter
- `dispose(): void` — disposes ALL contexts (including local), clears map. Used only on app shutdown.
Use `createLogger('Infrastructure:ServiceContextRegistry')` for logging.
**index.ts** - Add exports:
- Add `export * from './ServiceContext';`
- Add `export * from './ServiceContextRegistry';`
</action>
<verify>
Run `pnpm typecheck` — must pass with zero errors. Verify the new files exist and export the expected classes.
</verify>
<done>
ServiceContext.ts exports ServiceContext class and ServiceContextConfig interface. ServiceContextRegistry.ts exports ServiceContextRegistry class. Both are type-safe and compile without errors. Barrel export updated.
</done>
</task>
<task type="auto">
<name>Task 2: Add comprehensive dispose() methods to FileWatcher and DataCache</name>
<files>
src/main/services/infrastructure/FileWatcher.ts
src/main/services/infrastructure/DataCache.ts
</files>
<action>
**FileWatcher.ts** - Add a `dispose()` method (separate from existing `stop()`):
The existing `stop()` method closes watchers but does NOT clear all internal state or remove EventEmitter listeners. Add a `dispose()` method that performs complete cleanup:
1. Call `this.stop()` first (closes fs.watch watchers)
2. Clear retry timer: `if (this.retryTimer) { clearTimeout(this.retryTimer); this.retryTimer = null; }`
3. Clear all debounce timers: `for (const timer of this.debounceTimers.values()) { clearTimeout(timer); } this.debounceTimers.clear();`
4. Clear catch-up timer: `if (this.catchUpTimer) { clearInterval(this.catchUpTimer); this.catchUpTimer = null; }`
5. Clear polling timer: `if (this.pollingTimer) { clearInterval(this.pollingTimer); this.pollingTimer = null; }`
6. Clear all tracking maps: `this.lastProcessedLineCount.clear()`, `this.lastProcessedSize.clear()`, `this.activeSessionFiles.clear()`, `this.polledFileSizes.clear()`, `this.processingInProgress.clear()`
7. Also clear `this.pendingReprocess` if it exists (check the class for this field)
8. LAST: `this.removeAllListeners()` — MUST be last to prevent firing events during cleanup
Add a `private disposed = false` flag. Set it in dispose(). Check it in `start()` to prevent restarting a disposed watcher (throw error or log warning and return early).
**DataCache.ts** - Add a `dispose()` method:
1. Call `this.cache.clear()`
2. Set `this.enabled = false`
3. Add a `private disposed = false` flag, set it in dispose
4. If DataCache has a `startAutoCleanup()` method that returns an interval handle, the caller (ServiceContext) manages that interval. But also add internal cleanup: check if there's an internal auto-cleanup timer stored as a class field. If `startAutoCleanup()` only returns the interval for the caller to manage, just clear the cache and disable.
Look at the actual DataCache code to see if it stores the cleanup interval internally. If it only returns it, the caller is responsible. If it stores it, clear it in dispose().
</action>
<verify>
Run `pnpm typecheck` — must pass. Run `pnpm test` — all existing tests must still pass. Verify FileWatcher.dispose() exists and calls removeAllListeners(). Verify DataCache.dispose() exists and clears cache.
</verify>
<done>
FileWatcher has a dispose() method that: stops watchers, clears ALL timers (retry, debounce, catch-up, polling), clears ALL tracking maps, and calls removeAllListeners() LAST. DataCache has a dispose() method that clears the cache and disables it. Both have a `disposed` flag to prevent reuse after disposal. All existing tests pass.
</done>
</task>
</tasks>
<verification>
1. `pnpm typecheck` passes with zero errors
2. `pnpm test` — all existing tests pass (no regressions)
3. New files exist at expected paths: `src/main/services/infrastructure/ServiceContext.ts`, `src/main/services/infrastructure/ServiceContextRegistry.ts`
4. ServiceContext constructor creates all 6 services correctly
5. ServiceContextRegistry.switch() stops old FileWatcher and starts new one
6. ServiceContextRegistry.destroy('local') throws an error
7. FileWatcher.dispose() calls removeAllListeners()
</verification>
<success_criteria>
- ServiceContext class creates isolated service bundles with correct dependency chain
- ServiceContextRegistry manages Map of contexts with active tracking
- Local context cannot be destroyed (throws on attempt)
- FileWatcher.dispose() performs comprehensive cleanup (timers, maps, listeners)
- DataCache.dispose() clears cache and disables
- All existing tests pass with no regressions
- Type checking passes
</success_criteria>
<output>
After completion, create `.planning/phases/02-service-infrastructure/02-01-SUMMARY.md`
</output>

284
.planning/phases/02-service-infrastructure/02-01-SUMMARY.md
View file

@ -1,284 +0,0 @@
---
phase: 02-service-infrastructure
plan: 01
subsystem: service-lifecycle
tags:
- infrastructure
- multi-context
- lifecycle
- memory-management
dependency-graph:
requires: []
provides:
- ServiceContext
- ServiceContextRegistry
- EventEmitter disposal pattern
affects:
- src/main/index.ts (will use ServiceContextRegistry in Phase 2 Plan 2)
- IPC handlers (will get services from active context)
tech-stack:
added: []
patterns:
- Registry pattern for context management
- Comprehensive dispose() with EventEmitter cleanup
- Start/stop/dispose lifecycle separation
key-files:
created:
- src/main/services/infrastructure/ServiceContext.ts
- src/main/services/infrastructure/ServiceContextRegistry.ts
modified:
- src/main/services/infrastructure/FileWatcher.ts
- src/main/services/infrastructure/DataCache.ts
- src/main/services/infrastructure/index.ts
decisions:
- title: ServiceContext bundles all session-data services
rationale: Isolation and lifecycle management for local vs SSH contexts
- title: Local context is permanent, SSH contexts are ephemeral
rationale: App always has local access, SSH can disconnect
- title: dispose() is separate from stop()
rationale: stop() pauses (reversible), dispose() destroys (permanent)
- title: removeAllListeners() called last in dispose()
rationale: Prevents event emission during cleanup, avoiding memory leaks
metrics:
duration: 4
tasks_completed: 2
files_created: 2
files_modified: 3
tests_added: 0
tests_passing: 494
commits: 2
completed: 2026-02-12
---
# Phase 2 Plan 1: ServiceContext Infrastructure Summary
ServiceContext bundle and ServiceContextRegistry coordinator created with comprehensive EventEmitter cleanup for multi-context support.
## Overview
Created the foundational infrastructure for multi-context support in claude-devtools. ServiceContext encapsulates all session-data services (ProjectScanner, SessionParser, SubagentResolver, ChunkBuilder, DataCache, FileWatcher) for a single workspace context (local or SSH). ServiceContextRegistry manages the Map of contexts, tracks the active context, and enforces lifecycle rules (local context is permanent, SSH contexts can be destroyed).
**Key innovation:** Comprehensive dispose() methods on EventEmitter-based services prevent memory leaks during context switching by clearing all timers, tracking maps, and listeners in the correct order.
## What Was Built
### ServiceContext (src/main/services/infrastructure/ServiceContext.ts)
Service bundle class that creates and owns all session-data services for one workspace:
**Configuration:**
- `id: string` - Unique identifier (e.g., 'local', 'ssh-myserver')
- `type: 'local' | 'ssh'` - Context type
- `fsProvider: FileSystemProvider` - Filesystem provider
- `projectsDir?: string` - Projects directory (defaults to ~/.claude/projects)
- `todosDir?: string` - Todos directory (defaults to ~/.claude/todos)
**Services created in dependency order:**
1. ProjectScanner(projectsDir, todosDir, fsProvider)
2. SessionParser(projectScanner)
3. SubagentResolver(projectScanner)
4. ChunkBuilder()
5. DataCache(MAX_CACHE_SESSIONS, CACHE_TTL_MINUTES, !disableCache)
6. FileWatcher(dataCache, projectsDir, todosDir, fsProvider)
**Lifecycle methods:**
- `start()` - Activates file watching and cache cleanup
- `stopFileWatcher()` - Pauses file watching (for context switch)
- `startFileWatcher()` - Resumes file watching
- `dispose()` - Destroys all resources (irreversible)
**Disposed flag:** Prevents reuse after disposal, logs errors if start() called on disposed context.
### ServiceContextRegistry (src/main/services/infrastructure/ServiceContextRegistry.ts)
Registry coordinator that manages all contexts:
**State:**
- `contexts: Map<string, ServiceContext>` - All registered contexts
- `activeContextId: string` - Currently active context (defaults to 'local')
**Methods:**
- `registerContext(context)` - Adds context to map (throws if ID exists)
- `getActive()` - Returns active context (throws if not found)
- `get(contextId)` - Returns context by ID or undefined
- `has(contextId)` - Check existence
- `switch(contextId)` - Switches to different context:
- Stops old file watcher
- Updates activeContextId
- Starts new file watcher
- Returns {previous, current} for IPC re-init
- `destroy(contextId)` - Destroys SSH context:
- Throws if contextId === 'local' (permanent context)
- Calls context.dispose()
- Removes from map
- If destroying active context, switches to 'local'
- `list()` - Returns array of {id, type} metadata
- `dispose()` - Disposes ALL contexts (app shutdown only)
**Enforcement:** Local context permanence enforced in destroy() method.
### FileWatcher.dispose() (src/main/services/infrastructure/FileWatcher.ts)
Comprehensive cleanup for EventEmitter-based service:
**Cleanup sequence:**
1. Call `stop()` - Closes watchers, clears most timers and maps
2. Explicitly clear retry timer (redundant but explicit)
3. Clear all debounce timers + debounceTimers map
4. Clear catch-up interval timer
5. Clear polling interval timer (SSH mode)
6. Clear all tracking maps:
- lastProcessedLineCount
- lastProcessedSize
- activeSessionFiles
- polledFileSizes
- processingInProgress
- pendingReprocess
7. **LAST:** Call `removeAllListeners()` - Prevents events during cleanup
8. Set `disposed = true` flag
**Disposed flag check:** Added to `start()` method to prevent restarting disposed watcher.
### DataCache.dispose() (src/main/services/infrastructure/DataCache.ts)
Simple cleanup for cache service:
**Cleanup:**
1. Clear cache Map
2. Set `enabled = false`
3. Set `disposed = true` flag
**Note:** Auto-cleanup interval returned by `startAutoCleanup()` is managed by caller (ServiceContext), not stored internally, so no timer cleanup needed here.
## Deviations from Plan
None - plan executed exactly as written.
## Technical Decisions
### 1. ServiceContext owns cleanup interval handle
**Decision:** ServiceContext stores the cleanup interval handle returned by `dataCache.startAutoCleanup()` and clears it in `dispose()`.
**Rationale:** DataCache doesn't store the interval internally (it only returns it), so ownership belongs to the caller.
### 2. removeAllListeners() called LAST in FileWatcher.dispose()
**Decision:** EventEmitter cleanup happens after all other cleanup steps.
**Rationale:** Prevents firing events (like 'file-change') during cleanup when internal state is partially cleared. Emitting events mid-cleanup can cause memory leaks if listeners try to access cleared maps.
### 3. Separated start() check for disposal vs already watching
**Decision:** Added explicit `if (this.disposed)` check before `if (this.isWatching)` in FileWatcher.start().
**Rationale:** Disposal is a permanent error condition (log error), while already watching is a normal edge case (log warning). Clearer error messaging.
### 4. Registry does NOT create local context in constructor
**Decision:** ServiceContextRegistry constructor is empty - local context registered externally.
**Rationale:** Local context creation requires mainWindow and NotificationManager wiring that exists in index.ts, not in registry constructor. Keeps registry focused on coordination, not initialization.
## Testing Results
**Type checking:** ✅ Passed (0 errors)
**Test suite:** ✅ 494/494 tests passing (no regressions)
Existing FileWatcher tests verify:
- File watching lifecycle (start/stop)
- Debouncing behavior
- Error detection
- SSH polling mode
No new tests added (infrastructure code, tested via integration in Phase 2 Plan 2).
## Verification
**Created files exist:**
```bash
✅ src/main/services/infrastructure/ServiceContext.ts
✅ src/main/services/infrastructure/ServiceContextRegistry.ts
```
**Exports updated:**
```bash
✅ infrastructure/index.ts exports ServiceContext and ServiceContextRegistry
```
**ServiceContext constructor creates all 6 services:**
```typescript
✅ projectScanner: ProjectScanner
✅ sessionParser: SessionParser
✅ subagentResolver: SubagentResolver
✅ chunkBuilder: ChunkBuilder
✅ dataCache: DataCache
✅ fileWatcher: FileWatcher
```
**ServiceContextRegistry enforces lifecycle rules:**
```typescript
✅ destroy('local') throws Error
✅ switch() stops old watcher, starts new watcher
✅ destroy(activeContext) switches to 'local'
```
**Dispose methods exist:**
```typescript
✅ FileWatcher.dispose() calls removeAllListeners()
✅ DataCache.dispose() clears cache
✅ Both have disposed flag
```
## Integration Points
**Used by (Phase 2 Plan 2):**
- `src/main/index.ts` - Will create ServiceContextRegistry, register local context, wire IPC handlers
- IPC handlers - Will get services from `registry.getActive()` instead of global instances
- SSH connection flow - Will create/register/destroy SSH contexts
**Provides to system:**
- Isolated service stacks per workspace
- Safe context switching without memory leaks
- Foundation for SSH multi-context support
## Performance Impact
**Memory:** Minimal overhead - registry is a simple Map, contexts reuse existing service code.
**Context switch latency:** ~10-50ms (stop old watcher + start new watcher), acceptable for user-initiated action.
**Disposal thoroughness:** Prevents memory leaks - comprehensive cleanup of all timers, maps, and listeners. Critical for long-running sessions with frequent SSH connect/disconnect cycles.
## Next Steps
**Phase 2 Plan 2 (IPC Refactoring):**
1. Create ServiceContextRegistry in index.ts
2. Register local context with NotificationManager wiring
3. Refactor IPC handlers to use `registry.getActive()` instead of global instances
4. Add context switch IPC handlers (`ssh:switch-context`, `ssh:destroy-context`)
**Phase 2 Plan 3 (SSH Integration):**
1. Wire SshConnectionManager to create ServiceContext on connect
2. Register SSH context in registry
3. Switch to SSH context on successful connection
4. Destroy SSH context on disconnect
## Self-Check
**Files created:**
✅ src/main/services/infrastructure/ServiceContext.ts (exists, 5932 bytes)
✅ src/main/services/infrastructure/ServiceContextRegistry.ts (exists, 5552 bytes)
**Commits exist:**
✅ 777d93f: feat(02-01): create ServiceContext and ServiceContextRegistry
✅ 767c985: feat(02-01): add comprehensive dispose() to FileWatcher and DataCache
**Type checking:**
✅ `pnpm typecheck` passes with 0 errors
**Test suite:**
✅ `pnpm test` passes with 494/494 tests
**Self-Check: PASSED**

311
.planning/phases/02-service-infrastructure/02-02-PLAN.md
View file

@ -1,311 +0,0 @@
---
phase: 02-service-infrastructure
plan: 02
type: execute
wave: 2
depends_on: ["02-01"]
files_modified:
- src/main/index.ts
- src/main/ipc/handlers.ts
- src/main/ipc/sessions.ts
- src/main/ipc/projects.ts
- src/main/ipc/search.ts
- src/main/ipc/subagents.ts
- src/main/ipc/ssh.ts
autonomous: true
must_haves:
truths:
- "main/index.ts creates a ServiceContextRegistry instead of individual global service variables"
- "Local context is created and registered at startup, behaving identically to current behavior"
- "IPC handlers route through the registry to get service instances, not module-level variables"
- "SSH connect creates a new ServiceContext in the registry instead of destroying/recreating globals"
- "SSH disconnect destroys the SSH context but leaves local context untouched"
- "reinitializeServiceHandlers is no longer needed — handlers always fetch from registry"
artifacts:
- path: "src/main/index.ts"
provides: "Registry-based service initialization"
contains: "ServiceContextRegistry"
- path: "src/main/ipc/handlers.ts"
provides: "Registry-aware IPC initialization"
contains: "ServiceContextRegistry"
- path: "src/main/ipc/sessions.ts"
provides: "Registry-routed session handlers"
contains: "registry"
- path: "src/main/ipc/projects.ts"
provides: "Registry-routed project handlers"
contains: "registry"
- path: "src/main/ipc/search.ts"
provides: "Registry-routed search handlers"
contains: "registry"
- path: "src/main/ipc/subagents.ts"
provides: "Registry-routed subagent handlers"
contains: "registry"
key_links:
- from: "src/main/index.ts"
to: "src/main/services/infrastructure/ServiceContextRegistry.ts"
via: "creates and uses registry"
pattern: "new ServiceContextRegistry"
- from: "src/main/ipc/handlers.ts"
to: "src/main/services/infrastructure/ServiceContextRegistry.ts"
via: "receives registry for handler initialization"
pattern: "ServiceContextRegistry"
- from: "src/main/ipc/sessions.ts"
to: "src/main/services/infrastructure/ServiceContextRegistry.ts"
via: "calls registry.getActive() for service resolution"
pattern: "registry\\.getActive\\(\\)"
- from: "src/main/ipc/ssh.ts"
to: "src/main/services/infrastructure/ServiceContextRegistry.ts"
via: "creates SSH context and switches via registry"
pattern: "registry\\.(createSshContext|switch|destroy)"
---
<objective>
Replace the global service variables in main/index.ts with ServiceContextRegistry, and update all IPC handler modules to route through the registry instead of holding module-level service references.
Purpose: This is the core integration that transforms the app from single-mode (global services) to multi-context (registry-managed services). After this plan, SSH connections will create new contexts instead of destroying/recreating globals, and local context remains alive throughout.
Output: Refactored main/index.ts using registry pattern, all IPC handlers routing via registry.getActive().
</objective>
<execution_context>
@.planning/phases/02-service-infrastructure/02-RESEARCH.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/02-service-infrastructure/02-01-PLAN.md
@src/main/index.ts
@src/main/ipc/handlers.ts
@src/main/ipc/sessions.ts
@src/main/ipc/projects.ts
@src/main/ipc/search.ts
@src/main/ipc/subagents.ts
@src/main/ipc/ssh.ts
@src/main/services/infrastructure/ServiceContext.ts
@src/main/services/infrastructure/ServiceContextRegistry.ts
</context>
<tasks>
<task type="auto">
<name>Task 1: Refactor main/index.ts to use ServiceContextRegistry</name>
<files>
src/main/index.ts
src/main/ipc/handlers.ts
</files>
<action>
**src/main/index.ts** - Replace global service variables with registry:
1. Remove these individual service variable declarations:
- `let projectScanner: ProjectScanner;`
- `let sessionParser: SessionParser;`
- `let subagentResolver: SubagentResolver;`
- `let chunkBuilder: ChunkBuilder;`
- `let dataCache: DataCache;`
- `let fileWatcher: FileWatcher;`
- `let cleanupInterval: NodeJS.Timeout | null = null;`
2. Add: `let contextRegistry: ServiceContextRegistry;`
3. Rewrite `initializeServices()`:
- Create `sshConnectionManager` (unchanged)
- Create `contextRegistry = new ServiceContextRegistry()`
- Create local ServiceContext:
```
const localContext = new ServiceContext({
id: 'local',
type: 'local',
fsProvider: new LocalFileSystemProvider(),
});
```
- Register: `contextRegistry.registerContext(localContext)`
- Start: `localContext.start()`
- Initialize notification manager (unchanged — singleton, stays global, not context-scoped)
- Set notification manager on local context's fileWatcher: `localContext.fileWatcher.setNotificationManager(notificationManager)`
- Forward file-change and todo-change events from local context's fileWatcher to renderer (same as current, but using `localContext.fileWatcher.on(...)`)
- Initialize IPC handlers — change signature to pass `contextRegistry` instead of individual services. Also pass `sshConnectionManager`.
- Forward SSH state changes (unchanged)
4. Remove the `handleModeSwitch` callback entirely. SSH connect/disconnect will be handled by the SSH IPC handler using the registry directly (Plan 02 Task 2 below).
5. Rewrite `shutdownServices()`:
- Call `contextRegistry.dispose()` (disposes all contexts including local)
- Dispose `sshConnectionManager`
- Call `removeIpcHandlers()`
6. **File watcher event forwarding concern:** Currently events are wired to the single global fileWatcher. With multi-context, we need to forward events from the ACTIVE context's fileWatcher. Two approaches:
- Simple (do this): Wire events on local context at startup. When context switches happen (in SSH IPC handler), re-wire events to new active context's fileWatcher.
- Complex (don't do this): Create a proxy event system.
For now, wire local context's fileWatcher events at startup. The SSH IPC handler (Task 2) will handle re-wiring on switch.
Store the event cleanup functions so they can be unwired:
```
let fileChangeCleanup: (() => void) | null = null;
let todoChangeCleanup: (() => void) | null = null;
```
Create a `wireFileWatcherEvents(context: ServiceContext)` helper that:
- Cleans up previous listeners (if any)
- Adds new listeners to context.fileWatcher for 'file-change' and 'todo-change'
- Stores cleanup functions
Export this function (or make it accessible to IPC handlers via a setter).
Actually, simpler approach: have the registry emit a 'context-switched' event, and index.ts listens to it to re-wire. But the registry doesn't extend EventEmitter. Even simpler: have `switch()` in the registry return the previous and current contexts, and let the caller (SSH IPC handler) call a function on index.ts to re-wire.
Simplest approach: Create and export a `rewireFileWatcherEvents(context: ServiceContext, mainWindow: BrowserWindow | null)` function from index.ts that the SSH handler can import and call after switching contexts. This function removes old listeners, adds new ones.
**src/main/ipc/handlers.ts** - Update initialization signature:
1. Change `initializeIpcHandlers` signature to accept `ServiceContextRegistry` instead of individual services:
```typescript
export function initializeIpcHandlers(
registry: ServiceContextRegistry,
updater: UpdaterService,
sshManager: SshConnectionManager,
): void
```
2. Inside, pass registry to each domain handler's initialize function:
- `initializeProjectHandlers(registry)`
- `initializeSessionHandlers(registry)`
- `initializeSearchHandlers(registry)`
- `initializeSubagentHandlers(registry)`
- `initializeSshHandlers(sshManager, registry)` — SSH handler now gets registry instead of mode switch callback
- `initializeUpdaterHandlers(updater)` — unchanged (not context-dependent)
3. Remove `reinitializeServiceHandlers()` entirely — no longer needed because handlers always call `registry.getActive()` to get current services.
4. Keep `removeIpcHandlers()` unchanged.
</action>
<verify>
Run `pnpm typecheck` — must pass with zero errors. The main/index.ts should no longer have individual service variables (projectScanner, sessionParser, etc.) and should use contextRegistry instead.
</verify>
<done>
main/index.ts creates ServiceContextRegistry at startup with local context registered. handlers.ts accepts ServiceContextRegistry. reinitializeServiceHandlers is removed. Type checking passes.
</done>
</task>
<task type="auto">
<name>Task 2: Update domain IPC handlers to route via registry</name>
<files>
src/main/ipc/sessions.ts
src/main/ipc/projects.ts
src/main/ipc/search.ts
src/main/ipc/subagents.ts
src/main/ipc/ssh.ts
</files>
<action>
Update each domain IPC handler to receive `ServiceContextRegistry` instead of individual service instances, and call `registry.getActive()` to resolve services at invocation time.
**src/main/ipc/projects.ts:**
1. Change `initializeProjectHandlers(scanner: ProjectScanner)` to `initializeProjectHandlers(registry: ServiceContextRegistry)`
2. Store registry as module-level variable: `let registry: ServiceContextRegistry;`
3. Remove module-level `scanner` variable
4. In each handler, resolve scanner from registry: `const { projectScanner } = registry.getActive();`
5. Update all references from `scanner.` to `projectScanner.`
**src/main/ipc/sessions.ts:**
1. Change `initializeSessionHandlers(scanner, parser, resolver, builder, cache)` to `initializeSessionHandlers(registry: ServiceContextRegistry)`
2. Store registry as module-level variable
3. Remove module-level scanner, parser, resolver, builder, cache variables
4. In each handler, destructure from registry: `const { projectScanner, sessionParser, subagentResolver, chunkBuilder, dataCache } = registry.getActive();`
5. Update all references to use destructured names
**src/main/ipc/search.ts:**
1. Change `initializeSearchHandlers(scanner: ProjectScanner)` to `initializeSearchHandlers(registry: ServiceContextRegistry)`
2. Store registry, resolve from `registry.getActive()` in handlers
3. Update references
**src/main/ipc/subagents.ts:**
1. Change `initializeSubagentHandlers(builder, cache, parser, resolver, scanner)` to `initializeSubagentHandlers(registry: ServiceContextRegistry)`
2. Store registry, resolve from `registry.getActive()` in handlers
3. In the handler, get `fsProvider` and `projectsDir` from `registry.getActive().projectScanner` as was done in Phase 1
**src/main/ipc/ssh.ts:**
1. Change `initializeSshHandlers(manager, modeSwitchCallback)` to `initializeSshHandlers(manager: SshConnectionManager, registry: ServiceContextRegistry)`
2. Store registry as module-level variable, remove `onModeSwitch` callback
3. Rewrite `SSH_CONNECT` handler:
- Call `connectionManager.connect(config)` (unchanged)
- Get provider and remoteProjectsPath from connectionManager
- Generate contextId: `ssh-${config.host}` (or `ssh-${config.host}-${config.port}` if port is non-standard)
- Check if context already exists in registry (reconnection case): if yes, destroy old and create new
- Create new ServiceContext: `new ServiceContext({ id: contextId, type: 'ssh', fsProvider: provider, projectsDir: remoteProjectsPath })`
- Register in registry: `registry.registerContext(context)`
- Start context: `context.start()`
- Switch registry to new context: `registry.switch(contextId)`
- Import and call `rewireFileWatcherEvents(context, mainWindow)` from index.ts (or accept a callback for this)
- Return success with status
4. Rewrite `SSH_DISCONNECT` handler:
- Get current contextId from registry if it's SSH type
- Call `connectionManager.disconnect()`
- Call `registry.switch('local')` to switch back
- Call `registry.destroy(contextId)` to clean up SSH context
- Re-wire file watcher events to local context
- Return success with status
5. All other SSH handlers (test, getConfigHosts, resolveHost, saveLastConnection, getLastConnection) remain unchanged — they operate on SshConnectionManager directly, not service contexts.
**Important:** For the file watcher re-wiring, two approaches:
- Option A: Export `rewireFileWatcherEvents` from index.ts (simple but circular dependency risk)
- Option B: Pass a callback to `initializeSshHandlers` that the SSH handler calls after switching
- Option C: Have `initializeSshHandlers` also accept `mainWindow` reference and handle rewiring internally
Choose Option B: Add a `onContextSwitched: (context: ServiceContext) => void` callback parameter to `initializeSshHandlers`. index.ts passes a callback that re-wires FileWatcher events and sends context-changed notification to renderer.
Updated signature: `initializeSshHandlers(manager: SshConnectionManager, registry: ServiceContextRegistry, onContextSwitched: (context: ServiceContext) => void)`
In index.ts, the callback:
```typescript
const onContextSwitched = (context: ServiceContext) => {
// Re-wire file watcher events
rewireFileWatcherEvents(context);
// Notify renderer
if (mainWindow && !mainWindow.isDestroyed()) {
mainWindow.webContents.send(SSH_STATUS, sshConnectionManager.getStatus());
mainWindow.webContents.send('context-changed', {
contextId: context.id,
type: context.type,
});
}
};
```
The `rewireFileWatcherEvents` function in index.ts removes old listeners and adds new ones from context.fileWatcher, forwarding to mainWindow.
</action>
<verify>
1. Run `pnpm typecheck` — must pass with zero errors
2. Run `pnpm test` — all existing tests must pass (IPC handler tests may need mock updates)
3. Verify no remaining module-level service variables in sessions.ts, projects.ts, search.ts, subagents.ts (should all use `registry`)
4. Verify ssh.ts creates ServiceContext on connect and destroys on disconnect
</verify>
<done>
All domain IPC handlers (sessions, projects, search, subagents) resolve services via registry.getActive() at invocation time. SSH handler creates/destroys ServiceContext instances and switches registry on connect/disconnect. No module-level service variables remain — all routing goes through the registry. reinitializeServiceHandlers is fully removed. All tests pass.
</done>
</task>
</tasks>
<verification>
1. `pnpm typecheck` passes with zero errors
2. `pnpm test` — all existing tests pass
3. main/index.ts has `contextRegistry` instead of individual service globals
4. `reinitializeServiceHandlers` no longer exists in handlers.ts
5. All IPC handlers use `registry.getActive()` pattern
6. SSH connect creates a new ServiceContext and registers it
7. SSH disconnect destroys SSH context and switches to local
8. File watcher events are re-wired on context switch
</verification>
<success_criteria>
- Global service variables replaced with ServiceContextRegistry in main/index.ts
- All IPC domain handlers route through registry, not module-level service refs
- SSH connect creates isolated context; SSH disconnect destroys it without affecting local
- File watcher events forward from active context to renderer
- reinitializeServiceHandlers removed (no longer needed)
- No regressions in existing tests
</success_criteria>
<output>
After completion, create `.planning/phases/02-service-infrastructure/02-02-SUMMARY.md`
</output>

257
.planning/phases/02-service-infrastructure/02-02-SUMMARY.md
View file

@ -1,257 +0,0 @@
---
phase: 02-service-infrastructure
plan: 02
subsystem: main-process
tags: [registry-integration, ipc-refactoring, ssh-context-management]
dependency-graph:
requires: [02-01]
provides: [registry-based-service-routing]
affects: [all-ipc-handlers, ssh-connect-flow]
tech-stack:
added: []
patterns: [registry-routing, dynamic-service-resolution, context-switching]
key-files:
created: []
modified:
- src/main/index.ts
- src/main/ipc/handlers.ts
- src/main/ipc/projects.ts
- src/main/ipc/sessions.ts
- src/main/ipc/search.ts
- src/main/ipc/subagents.ts
- src/main/ipc/ssh.ts
decisions:
- "File watcher event rewiring handled by exported onContextSwitched callback from index.ts"
- "SSH handler imports onContextSwitched dynamically to avoid circular dependencies"
- "Context ID for SSH uses simple format: ssh-{host}"
- "Destroy existing SSH context on reconnection to same host"
metrics:
duration: 6
completed: 2026-02-12
---
# Phase 02 Plan 02: Registry Integration Summary
**Registry-based service routing with multi-context SSH support**
## Objective Achieved
Replaced global service variables in main/index.ts with ServiceContextRegistry, updated all IPC handlers to route through registry.getActive(), and implemented SSH context creation/destruction flow.
## Tasks Completed
### Task 1: Refactor main/index.ts to use ServiceContextRegistry
**Changed:**
- Removed global service variables (projectScanner, sessionParser, subagentResolver, chunkBuilder, dataCache, fileWatcher, cleanupInterval)
- Added `contextRegistry: ServiceContextRegistry`
- Removed `handleModeSwitch` callback entirely
- Created `wireFileWatcherEvents(context)` helper to manage event listener cleanup
- Created `onContextSwitched(context)` export for SSH handler to call
**Implementation:**
```typescript
// Create ServiceContextRegistry
contextRegistry = new ServiceContextRegistry();
// Create local context
const localContext = new ServiceContext({
id: 'local',
type: 'local',
fsProvider: new LocalFileSystemProvider(),
});
// Register and start
contextRegistry.registerContext(localContext);
localContext.start();
// Wire file watcher events
wireFileWatcherEvents(localContext);
// Initialize IPC handlers with registry
initializeIpcHandlers(contextRegistry, updaterService, sshConnectionManager);
```
**handlers.ts changes:**
- Changed `initializeIpcHandlers` to accept `ServiceContextRegistry` instead of individual services
- Removed `reinitializeServiceHandlers` entirely (no longer needed)
- Updated all domain handler initialize calls to pass registry
**Files modified:**
- src/main/index.ts (111 insertions, 161 deletions)
- src/main/ipc/handlers.ts
**Commit:** 5bf41c6
### Task 2: Update domain IPC handlers to route via registry
**Pattern applied to all handlers:**
```typescript
let registry: ServiceContextRegistry;
export function initialize{Domain}Handlers(contextRegistry: ServiceContextRegistry): void {
registry = contextRegistry;
}
async function handleXxx(...): Promise<...> {
const { projectScanner, sessionParser, ... } = registry.getActive();
// Use services
}
```
**projects.ts:**
- Changed signature to `initializeProjectHandlers(registry: ServiceContextRegistry)`
- Resolve `projectScanner` via `registry.getActive()` in each handler
- 3 handlers updated
**sessions.ts:**
- Changed signature to `initializeSessionHandlers(registry: ServiceContextRegistry)`
- Destructure all services from `registry.getActive()` at invocation time
- 6 handlers updated
**search.ts:**
- Changed signature to `initializeSearchHandlers(registry: ServiceContextRegistry)`
- Resolve `projectScanner` via `registry.getActive()`
- 1 handler updated
**subagents.ts:**
- Changed signature to `initializeSubagentHandlers(registry: ServiceContextRegistry)`
- Resolve all services from `registry.getActive()`
- Still passes fsProvider and projectsDir to buildSubagentDetail as before
- 1 handler updated
**ssh.ts:**
- Changed signature to `initializeSshHandlers(manager, registry)`
- Removed `onModeSwitch` callback parameter
- **SSH_CONNECT handler:**
- Creates new `ServiceContext` with SSH provider
- Registers in registry
- Starts context
- Switches registry to new context
- Dynamically imports `onContextSwitched` from index.ts and calls it
- **SSH_DISCONNECT handler:**
- Switches registry back to 'local'
- Destroys SSH context
- Calls `onContextSwitched` with local context
- All other SSH handlers unchanged (test, getConfigHosts, etc.)
**Files modified:**
- src/main/ipc/projects.ts
- src/main/ipc/sessions.ts
- src/main/ipc/search.ts
- src/main/ipc/subagents.ts
- src/main/ipc/ssh.ts (100 insertions, 70 deletions)
**Commit:** 24051ac
## Deviations from Plan
None - plan executed exactly as written.
## Verification Results
**Type checking:** ✅ Pass
```
pnpm typecheck — zero errors
```
**Tests:** ✅ Pass
```
Test Files: 31 passed
Tests: 494 passed
Duration: 4.88s
```
**Code inspection:** ✅ Pass
- main/index.ts has `contextRegistry` instead of individual service globals
- `reinitializeServiceHandlers` no longer exists in handlers.ts
- All IPC handlers use `registry.getActive()` pattern (12 occurrences)
- SSH connect creates ServiceContext and registers it
- SSH disconnect destroys SSH context and switches to local
- File watcher events rewired via onContextSwitched callback
## Architecture Impact
**Before (single-context):**
```
main/index.ts:
let projectScanner: ProjectScanner
let sessionParser: SessionParser
...
IPC handlers:
let projectScanner = /* set at init */
function handleXxx() {
projectScanner.scan() // always uses same instance
}
SSH connect:
recreate all services with new provider
call reinitializeServiceHandlers()
```
**After (multi-context):**
```
main/index.ts:
let contextRegistry: ServiceContextRegistry
contextRegistry.registerContext(localContext)
IPC handlers:
let registry: ServiceContextRegistry
function handleXxx() {
const { projectScanner } = registry.getActive()
projectScanner.scan() // dynamically resolved
}
SSH connect:
create new ServiceContext
registry.registerContext(sshContext)
registry.switch('ssh-host')
// local context stays alive in background
```
**Key improvements:**
1. **No service recreation** - contexts are isolated, switching is instant
2. **Local context persists** - can switch back without re-initialization
3. **No reinitializeServiceHandlers** - dynamic routing eliminates the need
4. **Clean separation** - SSH connection management vs. service context management
5. **File watcher stays alive** - only pause/resume on switch
## Next Steps
**Phase 02 Plan 03 (SSH notification manager integration):**
- Set NotificationManager on SSH context's FileWatcher
- Ensure error detection works for SSH sessions
- Wire up SSH context file watcher to NotificationManager
**Phase 03 (Renderer state management):**
- Snapshot/restore Zustand state on context switch
- Validate tab restoration against current context
- Update workspace indicators in sidebar
## Self-Check
**Created files exist:** N/A (no new files created)
**Modified files verified:**
```
✓ src/main/index.ts — uses contextRegistry
✓ src/main/ipc/handlers.ts — accepts registry, no reinitialize function
✓ src/main/ipc/projects.ts — routes via registry.getActive()
✓ src/main/ipc/sessions.ts — routes via registry.getActive()
✓ src/main/ipc/search.ts — routes via registry.getActive()
✓ src/main/ipc/subagents.ts — routes via registry.getActive()
✓ src/main/ipc/ssh.ts — creates/destroys ServiceContext
```
**Commits exist:**
```
✓ 5bf41c6 — refactor(02-02): main/index.ts to use ServiceContextRegistry
✓ 24051ac — refactor(02-02): IPC handlers route via ServiceContextRegistry
```
**Self-Check: PASSED**
---
*Completed: 2026-02-12*
*Duration: 6 minutes*

299
.planning/phases/02-service-infrastructure/02-03-PLAN.md
View file

@ -1,299 +0,0 @@
---
phase: 02-service-infrastructure
plan: 03
type: execute
wave: 3
depends_on: ["02-02"]
files_modified:
- src/main/ipc/context.ts
- src/main/ipc/handlers.ts
- src/preload/constants/ipcChannels.ts
- src/preload/index.ts
- src/shared/types/api.ts
- src/main/services/infrastructure/ConfigManager.ts
autonomous: true
must_haves:
truths:
- "Renderer can list all available contexts (local + SSH workspaces)"
- "Renderer can request a context switch and receive confirmation"
- "Renderer can get the current active context ID"
- "Context change events propagate to renderer via IPC"
- "SSH connection profiles are persisted in ConfigManager for reconnection"
artifacts:
- path: "src/main/ipc/context.ts"
provides: "Context management IPC handlers"
exports: ["initializeContextHandlers", "registerContextHandlers", "removeContextHandlers"]
- path: "src/preload/constants/ipcChannels.ts"
provides: "Context IPC channel constants"
contains: "CONTEXT_"
- path: "src/preload/index.ts"
provides: "Context API exposed to renderer"
contains: "context:"
- path: "src/shared/types/api.ts"
provides: "Context API type definitions on ElectronAPI"
contains: "context"
key_links:
- from: "src/preload/index.ts"
to: "src/main/ipc/context.ts"
via: "IPC invoke for context operations"
pattern: "ipcRenderer\\.invoke.*CONTEXT_"
- from: "src/main/ipc/context.ts"
to: "src/main/services/infrastructure/ServiceContextRegistry.ts"
via: "calls registry methods"
pattern: "registry\\.(list|switch|getActiveContextId)"
- from: "src/main/services/infrastructure/ConfigManager.ts"
to: "src/shared/types/api.ts"
via: "connection profiles stored in config"
pattern: "sshProfiles"
---
<objective>
Create the context management IPC channels, preload bridge, and connection profile persistence so the renderer can query, switch, and manage workspace contexts.
Purpose: This completes the service infrastructure by giving the renderer process the ability to interact with the context system. Without this, the registry exists but the UI has no way to list contexts, trigger switches, or restore saved connections. Connection profiles in ConfigManager enable reconnection without re-entering credentials (Success Criterion 4).
Output: New context IPC handler module, updated preload bridge with context API, connection profiles in ConfigManager config schema.
</objective>
<execution_context>
@.planning/phases/02-service-infrastructure/02-RESEARCH.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/02-service-infrastructure/02-01-PLAN.md
@.planning/phases/02-service-infrastructure/02-02-PLAN.md
@src/main/ipc/handlers.ts
@src/main/ipc/ssh.ts
@src/preload/index.ts
@src/preload/constants/ipcChannels.ts
@src/shared/types/api.ts
@src/main/services/infrastructure/ConfigManager.ts
@src/main/services/infrastructure/ServiceContextRegistry.ts
</context>
<tasks>
<task type="auto">
<name>Task 1: Create context IPC handler and channel constants</name>
<files>
src/main/ipc/context.ts
src/main/ipc/handlers.ts
src/preload/constants/ipcChannels.ts
</files>
<action>
**src/preload/constants/ipcChannels.ts** - Add context channel constants:
```typescript
// Context API Channels
export const CONTEXT_LIST = 'context:list';
export const CONTEXT_GET_ACTIVE = 'context:getActive';
export const CONTEXT_SWITCH = 'context:switch';
export const CONTEXT_CHANGED = 'context:changed'; // main -> renderer event
```
Note: context:connect-ssh and context:disconnect-ssh are NOT needed here — those operations are handled by the existing SSH IPC handlers (ssh:connect, ssh:disconnect) which now internally create/destroy contexts via the registry (done in Plan 02). The context IPC is for listing and switching only.
**src/main/ipc/context.ts** - Create context management handler module:
Follow the existing handler pattern (initialize, register, remove exports):
1. Module state:
```typescript
let registry: ServiceContextRegistry;
```
2. `initializeContextHandlers(reg: ServiceContextRegistry)`:
- Store registry reference
3. `registerContextHandlers(ipcMain: IpcMain)`:
- `CONTEXT_LIST` handler: Returns `registry.list()` — array of `{ id: string; type: 'local' | 'ssh' }`. Wrap in try/catch, return `{ success: true, data: [...] }`.
- `CONTEXT_GET_ACTIVE` handler: Returns `registry.getActiveContextId()`. Wrap in try/catch, return `{ success: true, data: contextId }`.
- `CONTEXT_SWITCH` handler: Takes `contextId: string` argument. Calls `registry.switch(contextId)`. On success return `{ success: true, data: { contextId } }`. On error (context doesn't exist), return `{ success: false, error: message }`.
Important: After switching, the caller (or this handler) should also trigger the `onContextSwitched` callback to re-wire FileWatcher events. Two approaches:
- Store the onContextSwitched callback in this module too
- Have the switch handler emit the CONTEXT_CHANGED event to renderer
Approach: Accept an `onContextSwitched` callback in `initializeContextHandlers` (same pattern as SSH handler). After successful switch, call it with the new active context, and also send CONTEXT_CHANGED event to renderer via mainWindow.
Updated init signature: `initializeContextHandlers(reg: ServiceContextRegistry, onSwitched: (context: ServiceContext) => void)`
In the CONTEXT_SWITCH handler:
```typescript
const { current } = registry.switch(contextId);
onSwitched(current);
// mainWindow notification happens inside onSwitched callback
return { success: true, data: { contextId } };
```
4. `removeContextHandlers(ipcMain: IpcMain)`:
- Remove all three handlers
**src/main/ipc/handlers.ts** - Register the new context handler module:
1. Import: `import { initializeContextHandlers, registerContextHandlers, removeContextHandlers } from './context';`
2. In `initializeIpcHandlers()`, add: `initializeContextHandlers(registry, onContextSwitched)` — the `onContextSwitched` callback needs to be passed through. Update the `initializeIpcHandlers` signature to accept it:
```typescript
export function initializeIpcHandlers(
registry: ServiceContextRegistry,
updater: UpdaterService,
sshManager: SshConnectionManager,
onContextSwitched: (context: ServiceContext) => void,
): void
```
3. Register: `registerContextHandlers(ipcMain);`
4. Remove: `removeContextHandlers(ipcMain);` in `removeIpcHandlers()`
</action>
<verify>
Run `pnpm typecheck` — must pass. Verify context.ts exports the three standard functions. Verify ipcChannels.ts has CONTEXT_LIST, CONTEXT_GET_ACTIVE, CONTEXT_SWITCH, CONTEXT_CHANGED constants.
</verify>
<done>
Context IPC handler created with list, getActive, and switch operations. Channel constants defined. Handler registered in handlers.ts init/register/remove flow. Context switching triggers onContextSwitched callback for event re-wiring.
</done>
</task>
<task type="auto">
<name>Task 2: Expose context API in preload bridge and add connection profiles to ConfigManager</name>
<files>
src/preload/index.ts
src/shared/types/api.ts
src/main/services/infrastructure/ConfigManager.ts
</files>
<action>
**src/shared/types/api.ts** - Add context API types to ElectronAPI:
1. Define `ContextInfo` type:
```typescript
export interface ContextInfo {
id: string;
type: 'local' | 'ssh';
}
```
2. Define `SshConnectionProfile` type (for saved profiles):
```typescript
export interface SshConnectionProfile {
id: string;
name: string;
host: string;
port: number;
username: string;
authMethod: 'password' | 'privateKey' | 'agent' | 'auto';
privateKeyPath?: string;
}
```
3. Add `context` property to `ElectronAPI` interface:
```typescript
context: {
list: () => Promise<ContextInfo[]>;
getActive: () => Promise<string>;
switch: (contextId: string) => Promise<{ contextId: string }>;
onChanged: (callback: (event: unknown, data: ContextInfo) => void) => () => void;
};
```
Note: Check the existing `ElectronAPI` type definition in `src/shared/types/api.ts` to see the exact structure and follow its conventions. The type may be defined there or it may be inferred from the preload implementation. If it's explicitly defined, add the context property. If it's not (i.e., type is inferred from `contextBridge.exposeInMainWorld`), then just update preload/index.ts and the type will follow.
**src/preload/index.ts** - Add context methods to electronAPI:
1. Import new channel constants: `CONTEXT_LIST`, `CONTEXT_GET_ACTIVE`, `CONTEXT_SWITCH`, `CONTEXT_CHANGED`
2. Add `context` namespace to the electronAPI object (alongside existing `ssh`, `config`, `notifications` etc.):
```typescript
context: {
list: async () => {
return invokeIpcWithResult<ContextInfo[]>(CONTEXT_LIST);
},
getActive: async () => {
return invokeIpcWithResult<string>(CONTEXT_GET_ACTIVE);
},
switch: async (contextId: string) => {
return invokeIpcWithResult<{ contextId: string }>(CONTEXT_SWITCH, contextId);
},
onChanged: (callback: (event: unknown, data: { id: string; type: string }) => void) => {
ipcRenderer.on(CONTEXT_CHANGED, callback as (event: Electron.IpcRendererEvent, ...args: unknown[]) => void);
return () => {
ipcRenderer.removeListener(CONTEXT_CHANGED, callback as (event: Electron.IpcRendererEvent, ...args: unknown[]) => void);
};
},
},
```
3. Import `ContextInfo` type if needed for type safety (may need to add to the imports from `@shared/types`).
**src/main/services/infrastructure/ConfigManager.ts** - Add connection profiles:
1. Add `SshConnectionProfile` interface (or import from shared types if defined there):
```typescript
export interface SshConnectionProfile {
id: string;
name: string;
host: string;
port: number;
username: string;
authMethod: SshAuthMethod;
privateKeyPath?: string;
}
```
2. Find the SSH config section type in ConfigManager. Currently there's `ssh.lastConnection`. Extend to add `ssh.profiles`:
```typescript
ssh: {
lastConnection: SshLastConnection | null;
profiles: SshConnectionProfile[];
lastActiveContextId: string; // Which context was active when app closed
}
```
3. Add defaults in the default config: `profiles: []`, `lastActiveContextId: 'local'`
4. Add profile management methods to ConfigManager:
- `addSshProfile(profile: SshConnectionProfile): void` — adds to profiles array, saves
- `removeSshProfile(profileId: string): void` — removes by id, saves
- `updateSshProfile(profileId: string, updates: Partial<SshConnectionProfile>): void` — updates, saves
- `getSshProfiles(): SshConnectionProfile[]` — returns profiles array
- `setLastActiveContextId(contextId: string): void` — persists for restore on restart
5. Ensure the config migration handles existing configs that don't have `profiles` or `lastActiveContextId` fields (add them with defaults in the config loading/merge logic).
</action>
<verify>
1. Run `pnpm typecheck` — must pass with zero errors
2. Run `pnpm test` — all existing tests pass (especially config-related tests)
3. Verify preload/index.ts has `context` namespace with list, getActive, switch, onChanged methods
4. Verify ConfigManager has ssh.profiles and ssh.lastActiveContextId with defaults
5. Verify ElectronAPI type includes context property
</verify>
<done>
Renderer can call window.electronAPI.context.list(), context.getActive(), context.switch(id), and context.onChanged(callback). ConfigManager stores SSH connection profiles array and last active context ID for reconnection on restart. All types are properly shared between processes.
</done>
</task>
</tasks>
<verification>
1. `pnpm typecheck` passes with zero errors
2. `pnpm test` — all existing tests pass
3. Context IPC channels exist: context:list, context:getActive, context:switch, context:changed
4. Preload exposes window.electronAPI.context with 4 methods
5. ConfigManager config includes ssh.profiles (array) and ssh.lastActiveContextId (string)
6. ElectronAPI type includes context property definition
</verification>
<success_criteria>
- Renderer process can list all contexts, get active context, switch contexts, and listen for context changes
- SSH connection profiles persisted in ConfigManager for quick reconnection
- Last active context ID persisted for app restart restoration
- All IPC channels follow existing naming and error handling patterns
- No regressions in existing tests or type checking
</success_criteria>
<output>
After completion, create `.planning/phases/02-service-infrastructure/02-03-SUMMARY.md`
</output>

202
.planning/phases/02-service-infrastructure/02-03-SUMMARY.md
View file

@ -1,202 +0,0 @@
---
phase: 02-service-infrastructure
plan: 03
subsystem: context-management-ipc
tags: [ipc, context-switching, ssh-profiles, persistence]
dependency-graph:
requires:
- 02-02 (ServiceContextRegistry and context lifecycle)
provides:
- Context management IPC API (list, getActive, switch)
- Context change events for renderer
- SSH connection profile persistence
- Last active context restoration
affects:
- Renderer can now query and switch contexts
- SSH connections can be saved as profiles for reconnection
- App can restore last active context on restart
tech-stack:
added:
- Context IPC handlers (context.ts)
- Context API in preload bridge
- SSH profile management in ConfigManager
patterns:
- IPC handler pattern (initialize, register, remove)
- IpcResult<T> wrapper for type-safe responses
- invokeIpcWithResult helper for preload
key-files:
created: []
modified:
- src/main/services/infrastructure/ConfigManager.ts
- src/preload/index.ts
- src/shared/types/api.ts
- src/main/ipc/context.ts (created in 02-02)
- src/preload/constants/ipcChannels.ts (updated in 02-02)
- src/main/ipc/handlers.ts (updated in 02-02)
decisions:
- Context IPC handlers follow standard pattern (initialize with services, register/remove with ipcMain)
- Context switch IPC handler calls onContextSwitched callback for file watcher event rewiring
- SSH profiles stored in ConfigManager config.ssh.profiles array for persistence
- lastActiveContextId stored in config.ssh.lastActiveContextId for app restart restoration
- Profile management methods use logger for visibility (add/remove/update operations)
metrics:
duration: 2 min
tasks: 2
files: 3
commits: 1
completed: 2026-02-12
---
# Phase 2 Plan 03: Context Management IPC and Profile Persistence Summary
Context IPC channels and SSH profile persistence enable renderer to manage workspace contexts and save connections for quick reconnection.
## Tasks Completed
### Task 1: Context IPC handler and channel constants ✓
**Status:** Already complete from Plan 02-02
**Details:**
- Context IPC handler module (`src/main/ipc/context.ts`) created with:
- `CONTEXT_LIST` handler: Returns array of context metadata `{ id, type }`
- `CONTEXT_GET_ACTIVE` handler: Returns current active context ID
- `CONTEXT_SWITCH` handler: Switches context, calls onContextSwitched callback
- Channel constants defined in `src/preload/constants/ipcChannels.ts`:
- `CONTEXT_LIST`, `CONTEXT_GET_ACTIVE`, `CONTEXT_SWITCH`, `CONTEXT_CHANGED`
- Handlers registered in `src/main/ipc/handlers.ts`:
- `initializeContextHandlers(registry, onContextSwitched)` - stores references
- `registerContextHandlers(ipcMain)` - registers IPC handlers
- `removeContextHandlers(ipcMain)` - cleanup on shutdown
- Context switching triggers `onContextSwitched` callback for file watcher event rewiring
- All handlers follow standard error handling pattern with try/catch and IpcResult<T> wrapper
**Verification:** ✓ typecheck passes, handlers registered, channels defined
### Task 2: Context API in preload bridge and SSH profile management ✓
**Status:** Preload API existed from 02-02, profile management added
**Details:**
- **Preload bridge** (`src/preload/index.ts`):
- Context API exposed with `list()`, `getActive()`, `switch()`, `onChanged()`
- All methods use `invokeIpcWithResult<T>` helper for type-safe IPC
- `onChanged` returns cleanup function for proper event listener removal
- **Type definitions** (`src/shared/types/api.ts`):
- `ContextInfo` interface: `{ id: string; type: 'local' | 'ssh' }`
- `SshConnectionProfile` interface: stores connection details without password
- Context API property added to `ElectronAPI` interface
- **ConfigManager** (`src/main/services/infrastructure/ConfigManager.ts`):
- Added `profiles: SshConnectionProfile[]` to `ssh` config section
- Added `lastActiveContextId: string` to `ssh` config section
- Defaults: `profiles: []`, `lastActiveContextId: 'local'`
- Profile management methods:
- `addSshProfile(profile)` - adds profile, checks for duplicates
- `removeSshProfile(profileId)` - removes by ID
- `updateSshProfile(profileId, updates)` - updates existing profile
- `getSshProfiles()` - returns deep clone of profiles array
- `setLastActiveContextId(contextId)` - persists for app restart
- All methods include logging for visibility
- Config migration handles missing fields automatically via `mergeWithDefaults()`
**Verification:** ✓ typecheck passes, all tests pass (494 tests), profile methods accessible
## Deviations from Plan
### Auto-fixed Issues
**None** - Plan executed exactly as written. Context IPC infrastructure was already created in Plan 02-02, so this plan only needed to add SSH profile management to ConfigManager.
## Verification Results
1. ✓ `pnpm typecheck` - Zero errors
2. ✓ `pnpm test` - All 494 tests pass
3. ✓ Context IPC channels exist: `context:list`, `context:getActive`, `context:switch`, `context:changed`
4. ✓ Preload exposes `window.electronAPI.context` with 4 methods
5. ✓ ConfigManager includes `ssh.profiles` (array) and `ssh.lastActiveContextId` (string)
6. ✓ ElectronAPI type includes context property definition
7. ✓ Profile management methods exist with proper logging
## Success Criteria Met
- ✓ Renderer process can list all contexts via `window.electronAPI.context.list()`
- ✓ Renderer can get active context via `window.electronAPI.context.getActive()`
- ✓ Renderer can switch contexts via `window.electronAPI.context.switch(contextId)`
- ✓ Renderer can listen for context changes via `window.electronAPI.context.onChanged(callback)`
- ✓ SSH connection profiles persisted in ConfigManager for quick reconnection
- ✓ Last active context ID persisted for app restart restoration
- ✓ All IPC channels follow existing naming and error handling patterns
- ✓ No regressions in existing tests or type checking
## What This Enables
**For Renderer:**
- Query all available workspace contexts (local + SSH)
- Get currently active context ID
- Trigger context switches programmatically
- Listen for context change events
- Build context switcher UI (Phase 4)
**For SSH Reconnection:**
- Save connection profiles after first successful connection
- Reconnect to saved profiles without re-entering credentials
- Remember last active context across app restarts
- Quick reconnection workflow for frequently used SSH hosts
**For App Lifecycle:**
- Restore last active context on app restart (if auto-reconnect enabled)
- Persist connection preferences across sessions
- Support multiple saved SSH profiles
## Architecture Notes
**IPC Flow:**
1. Renderer calls `window.electronAPI.context.list()`
2. Preload invokes `context:list` IPC channel
3. Main process handler calls `registry.list()`
4. Returns array of `{ id, type }` wrapped in `IpcResult<T>`
5. Preload helper unwraps result or throws error
6. Renderer receives typed `ContextInfo[]`
**Context Switch Flow:**
1. Renderer calls `window.electronAPI.context.switch(contextId)`
2. Main handler calls `registry.switch(contextId)` - stops old watcher, starts new watcher
3. Handler calls `onContextSwitched(current)` - rewires file watcher events to renderer
4. Returns `{ contextId }` on success or `{ error }` on failure
5. Renderer receives confirmation or error
**Profile Persistence:**
- SSH profiles stored in `~/.claude/claude-devtools-config.json`
- No passwords stored (security)
- `lastActiveContextId` persisted for app restart restoration
- Config automatically migrated on load if fields missing
## Integration Points
**Depends on:**
- ServiceContextRegistry (Plan 02-02) - provides list(), switch(), getActiveContextId()
- ServiceContext (Plan 02-01) - context lifecycle management
- ConfigManager - existing config persistence infrastructure
**Enables:**
- Phase 3 (Renderer State Management) - context switching in Zustand store
- Phase 4 (UI Components) - context switcher dropdown component
- SSH reconnection workflow - quick reconnection from saved profiles
## Testing Coverage
- Existing test suite passes (494 tests)
- Type safety verified (zero TypeScript errors)
- ConfigManager profile methods covered by existing config test patterns
- IPC handler pattern validated by existing handler tests
## Self-Check: PASSED
**Created files verification:**
- No new files created (infrastructure existed from 02-02)
**Modified files verification:**
- ✓ FOUND: src/main/services/infrastructure/ConfigManager.ts
- ✓ FOUND: src/preload/index.ts
- ✓ FOUND: src/shared/types/api.ts
**Commit verification:**
- ✓ FOUND: 4921c61 (feat(02-03): add SSH profile management to ConfigManager)
All files exist and commit is present in git history.

624
.planning/phases/02-service-infrastructure/02-RESEARCH.md
View file

@ -1,624 +0,0 @@
# Phase 2: Service Infrastructure - Research
**Researched:** 2026-02-12
**Domain:** Service lifecycle management, multi-context architecture, IPC routing
**Confidence:** HIGH
## Summary
Phase 2 establishes the infrastructure for managing multiple independent service contexts (local + N SSH connections) with proper lifecycle management, cleanup, and IPC routing. The core challenge is transforming a single-mode application into a multi-context system where the local context is always alive and each SSH connection gets its own isolated service instances.
**Key insight:** The codebase already has all the building blocks needed — FileSystemProvider abstraction (Phase 1), EventEmitter-based services with cleanup paths, and module-level IPC handler references that support re-initialization. The registry pattern will coordinate these existing pieces rather than introducing fundamentally new mechanisms.
**Primary recommendation:** Build ServiceContextRegistry as a Map-based coordinator that creates/destroys service bundles, route IPC requests using context ID stamping, and implement bulletproof dispose() methods on all EventEmitter-based services.
## Standard Stack
### Core
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| Node.js EventEmitter | Built-in | Event-driven service communication | Already used by FileWatcher, NotificationManager, SshConnectionManager |
| Map | Built-in | Context registry storage | Fast O(1) lookups, iteration support, built-in size tracking |
| Electron IPC (ipcMain/ipcRenderer) | 28.x | Process communication | Existing IPC infrastructure |
### Supporting
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| ssh2 | Current (Phase 1) | SSH connections | Already integrated for SFTP |
| fs.FSWatcher | Built-in | File watching | Already used in FileWatcher service |
### Alternatives Considered
| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| Map | WeakMap | Would enable GC of contexts, but need explicit lifecycle control for cleanup |
| IPC context stamping | Separate IPC channels per context | Would explode channel count (5-10 channels × N contexts), harder to manage |
| Module-level service refs | Dependency injection container | More complex, unnecessary when re-initialization pattern already works |
**Installation:**
No new dependencies required — using existing stack.
## Architecture Patterns
### Recommended Project Structure
```
src/main/
├── services/
│ ├── infrastructure/
│ │ ├── ServiceContext.ts # NEW: Context bundle class
│ │ ├── ServiceContextRegistry.ts # NEW: Registry coordinator
│ │ └── [existing services...] # MODIFY: Add dispose() methods
│ └── [domain services...]
├── ipc/
│ ├── handlers.ts # MODIFY: Add context routing
│ ├── context.ts # NEW: Context management IPC
│ └── [domain handlers...] # MODIFY: Route via context ID
└── index.ts # MODIFY: Use registry instead of globals
```
### Pattern 1: Service Context Bundle
**What:** A ServiceContext class encapsulates all service instances for a single context (local or SSH).
**When to use:** For each workspace context that needs independent service lifecycle.
**Example:**
```typescript
// Source: Based on existing service initialization in src/main/index.ts (lines 78-92)
export interface ServiceContextConfig {
id: string;
type: 'local' | 'ssh';
fsProvider: FileSystemProvider;
projectsDir?: string;
todosDir?: string;
}
export class ServiceContext {
readonly id: string;
readonly type: 'local' | 'ssh';
// Service instances
readonly projectScanner: ProjectScanner;
readonly sessionParser: SessionParser;
readonly subagentResolver: SubagentResolver;
readonly chunkBuilder: ChunkBuilder;
readonly dataCache: DataCache;
readonly fileWatcher: FileWatcher;
constructor(config: ServiceContextConfig) {
this.id = config.id;
this.type = config.type;
// Initialize services with provider
this.projectScanner = new ProjectScanner(
config.projectsDir,
config.todosDir,
config.fsProvider
);
this.sessionParser = new SessionParser(this.projectScanner);
this.subagentResolver = new SubagentResolver(this.projectScanner);
this.chunkBuilder = new ChunkBuilder();
this.dataCache = new DataCache(MAX_CACHE_SESSIONS, CACHE_TTL_MINUTES);
// FileWatcher with provider
this.fileWatcher = new FileWatcher(
this.dataCache,
config.projectsDir,
config.todosDir,
config.fsProvider
);
}
// Start active services
start(): void {
this.fileWatcher.start();
this.dataCache.startAutoCleanup(CACHE_CLEANUP_INTERVAL_MINUTES);
}
// Critical: Proper cleanup
dispose(): void {
this.fileWatcher.stop();
this.dataCache.clear();
// FileSystemProvider cleanup handled by caller
}
}
```
### Pattern 2: Registry with Active Context Tracking
**What:** ServiceContextRegistry manages Map of contexts and tracks which one is currently active.
**When to use:** Single registry instance in main process coordinates all context operations.
**Example:**
```typescript
// Source: Adapted from existing SshConnectionManager state management pattern
export class ServiceContextRegistry {
private contexts = new Map<string, ServiceContext>();
private activeContextId: string = 'local';
constructor() {
// Local context is always alive
const localContext = this.createContext({
id: 'local',
type: 'local',
fsProvider: new LocalFileSystemProvider(),
});
this.contexts.set('local', localContext);
localContext.start();
}
getActive(): ServiceContext {
const context = this.contexts.get(this.activeContextId);
if (!context) {
throw new Error(`Active context ${this.activeContextId} not found`);
}
return context;
}
switch(contextId: string): void {
if (!this.contexts.has(contextId)) {
throw new Error(`Context ${contextId} does not exist`);
}
this.activeContextId = contextId;
}
createSshContext(
id: string,
fsProvider: FileSystemProvider,
projectsDir: string
): ServiceContext {
if (this.contexts.has(id)) {
throw new Error(`Context ${id} already exists`);
}
const context = this.createContext({
id,
type: 'ssh',
fsProvider,
projectsDir,
});
this.contexts.set(id, context);
context.start();
return context;
}
destroy(contextId: string): void {
if (contextId === 'local') {
throw new Error('Cannot destroy local context');
}
const context = this.contexts.get(contextId);
if (context) {
context.dispose();
this.contexts.delete(contextId);
}
}
private createContext(config: ServiceContextConfig): ServiceContext {
return new ServiceContext(config);
}
}
```
### Pattern 3: IPC Context Routing
**What:** IPC handlers read context ID from event args and route to correct service context.
**When to use:** All session-data IPC handlers (projects, sessions, search, subagents).
**Example:**
```typescript
// Source: Based on existing IPC handler pattern in src/main/ipc/sessions.ts
let contextRegistry: ServiceContextRegistry;
export function initializeContextHandlers(registry: ServiceContextRegistry): void {
contextRegistry = registry;
}
// Modified handler with context routing
ipcMain.handle('get-projects', async (event, contextId?: string) => {
const context = contextId
? contextRegistry.get(contextId)
: contextRegistry.getActive();
if (!context) {
return [];
}
return context.projectScanner.scan();
});
```
### Pattern 4: EventEmitter Dispose Pattern
**What:** Services extending EventEmitter must remove all listeners and clear resources in dispose().
**When to use:** FileWatcher, NotificationManager, and any EventEmitter-based service.
**Example:**
```typescript
// Source: Best practices from Node.js EventEmitter cleanup research
export class FileWatcher extends EventEmitter {
private projectsWatcher: fs.FSWatcher | null = null;
private todosWatcher: fs.FSWatcher | null = null;
private debounceTimers = new Map<string, NodeJS.Timeout>();
private catchUpTimer: NodeJS.Timeout | null = null;
private pollingTimer: NodeJS.Timeout | null = null;
dispose(): void {
// Stop watchers first
this.stop();
// Clear all timers
for (const timer of this.debounceTimers.values()) {
clearTimeout(timer);
}
this.debounceTimers.clear();
if (this.catchUpTimer) {
clearInterval(this.catchUpTimer);
this.catchUpTimer = null;
}
if (this.pollingTimer) {
clearInterval(this.pollingTimer);
this.pollingTimer = null;
}
// CRITICAL: Remove ALL listeners to prevent memory leaks
this.removeAllListeners();
// Clear tracking state
this.lastProcessedLineCount.clear();
this.lastProcessedSize.clear();
this.activeSessionFiles.clear();
this.processingInProgress.clear();
this.pendingReprocess.clear();
}
}
```
### Anti-Patterns to Avoid
- **Global service instances:** Don't keep services as global module variables when using registry — use registry.getActive() instead
- **Async dispose:** Keep dispose() synchronous — cleanup should be immediate and deterministic
- **Partial cleanup:** Missing even one timer or listener causes memory leaks — use comprehensive checklists
- **Shared caches across contexts:** Each context must have its own DataCache instance to prevent cross-contamination
## Don't Hand-Roll
| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Service lifecycle management | Custom dependency injection container | Map-based registry with explicit create/dispose | DI containers add complexity; explicit lifecycle is easier to debug |
| IPC routing | Separate channels per context | Context ID stamping on existing channels | Channel explosion (N contexts × M channels); harder to manage |
| Event cleanup | Manual tracking of each listener | removeAllListeners() in dispose() | Guaranteed cleanup; prevents missed listeners |
| Context switching race conditions | Custom mutex/lock | Node.js single-threaded execution + synchronous switch | IPC handlers run sequentially; no parallelism within main process |
**Key insight:** The main process is single-threaded, so context switching is naturally serialized. No need for complex synchronization primitives.
## Common Pitfalls
### Pitfall 1: Memory Leaks from Orphaned EventEmitter Listeners
**What goes wrong:** Services extend EventEmitter but don't call removeAllListeners() in dispose(), causing listeners to persist after context destruction.
**Why it happens:** EventEmitter automatically manages a listeners array, but it never auto-clears. Each listener closure captures references to the service instance and any data it touches.
**How to avoid:**
- Add dispose() method to ALL services extending EventEmitter
- Call removeAllListeners() at the END of dispose() (after stopping watchers/timers)
- Test disposal by creating/destroying context 100+ times and monitoring memory
**Warning signs:**
- MaxListenersExceededWarning after multiple context switches
- Memory usage climbs 50-100MB per switch without leveling off
- DevTools heap snapshot shows growing EventEmitter listener arrays
**Example fix:**
```typescript
// Source: Verified pattern from FileWatcher.ts stop() method
dispose(): void {
// 1. Stop active operations
if (this.projectsWatcher) {
this.projectsWatcher.close();
this.projectsWatcher = null;
}
// 2. Clear timers/intervals
if (this.retryTimer) {
clearTimeout(this.retryTimer);
this.retryTimer = null;
}
// 3. Clear data structures
this.debounceTimers.clear();
this.lastProcessedLineCount.clear();
// 4. CRITICAL: Remove ALL listeners LAST
this.removeAllListeners();
}
```
### Pitfall 2: File Watcher Cross-Context Pollution
**What goes wrong:** FileWatcher in background SSH context emits events that trigger IPC sends for wrong context, causing UI to show stale data.
**Why it happens:** FileWatcher.on('file-change') forwards to renderer via mainWindow.webContents.send(). If watcher stays alive in background context, it keeps emitting for inactive context.
**How to avoid:**
- Option A: Only start FileWatcher for active context, stop on switch
- Option B: Scope events with contextId, filter in renderer
- **Recommended:** Option A — simpler, no renderer filtering needed
**Warning signs:**
- Switching from SSH to local shows SSH file change notifications
- Project list updates with data from inactive context
- Cache invalidation affects wrong context
**Implementation:**
```typescript
// In ServiceContextRegistry.switch()
switch(newContextId: string): void {
const oldContext = this.getActive();
// Stop file watcher in old context
oldContext.fileWatcher.stop();
// Switch active
this.activeContextId = newContextId;
const newContext = this.getActive();
// Start file watcher in new context
newContext.fileWatcher.start();
}
```
### Pitfall 3: IPC Handler Re-initialization Timing
**What goes wrong:** Switching contexts before re-initializing IPC handlers causes next IPC call to use old service instances from previous context.
**Why it happens:** Module-level variables in ipc/sessions.ts etc. hold service references. Calling registry.switch() doesn't update those refs until reinitializeServiceHandlers() is called.
**How to avoid:**
- Always call reinitializeServiceHandlers() IMMEDIATELY after registry.switch()
- Make switch() method handle re-init internally, don't rely on caller
- Verify with integration test: switch context, call IPC, check which projectsDir was scanned
**Warning signs:**
- Switching to SSH shows local projects for first query
- Race condition where sometimes switch works, sometimes shows stale data
- Logs show scans hitting wrong directory path
**Implementation:**
```typescript
// In ServiceContextRegistry
switch(newContextId: string): void {
this.activeContextId = newContextId;
const newContext = this.getActive();
// CRITICAL: Re-init IPC handlers with new context's services
reinitializeServiceHandlers(
newContext.projectScanner,
newContext.sessionParser,
newContext.subagentResolver,
newContext.chunkBuilder,
newContext.dataCache
);
}
```
### Pitfall 4: SSH Connection Manager Lifecycle Confusion
**What goes wrong:** SshConnectionManager owns the SSH client and SftpWrapper, but ServiceContext also needs to dispose its SshFileSystemProvider. Double-dispose or leaked connections result.
**Why it happens:** Ownership unclear — does SshConnectionManager own the connection, or does ServiceContext?
**How to avoid:**
- **SshConnectionManager owns:** Client, SFTP channel, SshFileSystemProvider instance
- **ServiceContext receives:** Pre-created FileSystemProvider (interface, not lifecycle)
- **On context destroy:** ServiceContext calls fsProvider.dispose() to end SFTP, SshConnectionManager tracks this and cleans up Client
- **Clean separation:** Context disposal -> provider disposal -> connection manager cleanup chain
**Warning signs:**
- SFTP channel stays open after context destroy
- Multiple SFTP channels open for same SSH connection
- "Channel already closed" errors on reconnect
**Implementation:**
```typescript
// ServiceContext.dispose()
dispose(): void {
this.fileWatcher.stop();
this.dataCache.clear();
// Dispose FileSystemProvider (closes SFTP if SSH)
if (this.fsProvider.type === 'ssh') {
this.fsProvider.dispose();
}
}
// SshConnectionManager watches for provider disposal
connect(config: SshConnectionConfig): Promise<void> {
// Create SFTP
const sftp = await this.openSftp();
const provider = new SshFileSystemProvider(sftp);
// Track this provider
this.activeProviders.add(provider);
return provider;
}
// When provider.dispose() is called, it ends SFTP
// Connection manager can detect and clean up client
```
## Code Examples
Verified patterns from existing codebase and research:
### Service Bundle Creation
```typescript
// Source: Adapted from src/main/index.ts initializeServices() pattern
export class ServiceContext {
constructor(config: ServiceContextConfig) {
this.id = config.id;
this.type = config.type;
// Chain dependencies: ProjectScanner -> SessionParser/SubagentResolver
this.projectScanner = new ProjectScanner(
config.projectsDir,
config.todosDir,
config.fsProvider
);
this.sessionParser = new SessionParser(this.projectScanner);
this.subagentResolver = new SubagentResolver(this.projectScanner);
this.chunkBuilder = new ChunkBuilder();
// Isolated cache per context
this.dataCache = new DataCache(
MAX_CACHE_SESSIONS,
CACHE_TTL_MINUTES,
true // enabled
);
// FileWatcher with context-specific provider
this.fileWatcher = new FileWatcher(
this.dataCache,
config.projectsDir,
config.todosDir,
config.fsProvider
);
}
}
```
### Registry Initialization in Main Process
```typescript
// Source: New pattern replacing src/main/index.ts service initialization
let contextRegistry: ServiceContextRegistry;
function initializeServices(): void {
logger.info('Initializing service context registry...');
// Registry creates local context internally
contextRegistry = new ServiceContextRegistry();
// Initialize IPC with registry
initializeIpcHandlers(contextRegistry, sshConnectionManager);
logger.info('Service context registry initialized');
}
```
### IPC Handler with Context Routing
```typescript
// Source: Pattern for src/main/ipc/sessions.ts modification
let registry: ServiceContextRegistry;
export function initializeSessionHandlers(reg: ServiceContextRegistry): void {
registry = reg;
}
export function registerSessionHandlers(ipcMain: IpcMain): void {
ipcMain.handle('get-session-detail', async (event, projectId, sessionId, contextId?) => {
try {
const context = contextId ? registry.get(contextId) : registry.getActive();
if (!context) {
return null;
}
const sessionPath = context.projectScanner.getSessionPath(projectId, sessionId);
const messages = await parseJsonlFile(
sessionPath,
context.projectScanner.getFileSystemProvider()
);
// ... rest of handler using context services
} catch (error) {
logger.error('Error getting session detail:', error);
return null;
}
});
}
```
### Context Creation Flow
```typescript
// Source: Integration of SshConnectionManager with ServiceContextRegistry
async function handleSshConnect(config: SshConnectionConfig): Promise<string> {
// 1. Connect SSH (creates provider)
await sshConnectionManager.connect(config);
const provider = sshConnectionManager.getProvider();
const projectsPath = sshConnectionManager.getRemoteProjectsPath();
// 2. Create context with SSH provider
const contextId = `ssh-${config.host}`;
const context = contextRegistry.createSshContext(
contextId,
provider,
projectsPath
);
// 3. Switch to new context
contextRegistry.switch(contextId);
// 4. Notify renderer
if (mainWindow) {
mainWindow.webContents.send('context-changed', contextId);
}
return contextId;
}
```
## State of the Art
| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| Global service instances in main/index.ts | ServiceContext bundles in registry | Phase 2 (this phase) | Enables multiple contexts, proper isolation |
| Mode switching destroys/recreates all services | Local context always alive, SSH contexts independent | Phase 2 | Local data never lost, faster switching |
| Single FileSystemProvider swapped on mode change | Provider per context, passed to services at creation | Phase 1 (completed) | Foundation for multi-context |
| IPC handlers hold direct service refs | IPC handlers route via contextId to registry | Phase 2 | Enables context-aware routing |
| FileWatcher events global | FileWatcher scoped to active context | Phase 2 | Prevents cross-context pollution |
**Deprecated/outdated:**
- **handleModeSwitch callback in main/index.ts:** Will be replaced by registry.switch() method
- **Global projectScanner/sessionParser variables:** Will be replaced by registry.getActive().projectScanner
- **reinitializeServiceHandlers() called manually:** Will be called automatically by registry.switch()
## Open Questions
1. **Should inactive SSH contexts keep FileWatcher running?**
- What we know: FileWatcher can run in background (SSH polling mode exists)
- What's unclear: Performance impact of N watchers polling simultaneously
- Recommendation: Start with "only active context watches" approach (simpler), measure performance, add background watching if users request it
2. **How to handle context switching during active IPC request?**
- What we know: Node.js event loop serializes IPC handlers
- What's unclear: Can registry.switch() be called mid-request?
- Recommendation: Make switch() synchronous and immediate — in-flight requests complete with old context, next request uses new context. Document this behavior.
3. **Should DataCache be shared across contexts or isolated?**
- What we know: Each SessionDetail is context-specific (local vs SSH paths differ)
- What's unclear: Could shared cache with composite keys work?
- Recommendation: Isolate caches — simpler, avoids key collision risks, allows per-context TTL tuning
4. **How to persist context metadata across app restarts?**
- What we know: Need to restore SSH contexts on app restart
- What's unclear: Where to persist (ConfigManager? Separate state file?)
- Recommendation: Add sshContexts array to ConfigManager schema, store connection profiles + last active context ID
## Sources
### Primary (HIGH confidence)
- Codebase analysis: src/main/index.ts, src/main/services/infrastructure/FileWatcher.ts, src/main/ipc/handlers.ts
- FileSystemProvider abstraction (Phase 1): src/main/services/infrastructure/FileSystemProvider.ts
- Existing EventEmitter usage: FileWatcher, NotificationManager, SshConnectionManager
### Secondary (MEDIUM confidence)
- [Process Model | Electron](https://www.electronjs.org/docs/latest/tutorial/process-model) — Electron main process lifecycle
- [Inter-Process Communication | Electron](https://www.electronjs.org/docs/latest/tutorial/ipc) — IPC patterns and channel management
- [How to fix possible EventEmitter memory leak detected](https://cri.dev/posts/2020-07-16-How-to-fix-possible-EventEmitter-memory-leak-detected/) — EventEmitter cleanup patterns
- [Dependency injection in ASP.NET Core | Microsoft Learn](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection) — Service lifetime and disposal patterns
- [Scaling 1M lines of TypeScript: Registries](https://puzzles.slash.com/blog/scaling-1m-lines-of-typescript-registries) — Registry pattern for large codebases
### Tertiary (LOW confidence)
- [Advanced Electron.js architecture - LogRocket Blog](https://blog.logrocket.com/advanced-electron-js-architecture/) — General Electron architecture patterns
- [How to Profile Node.js Applications for Memory Leaks](https://oneuptime.com/blog/post/2026-01-26-nodejs-memory-leak-profiling/view) — Memory leak detection techniques
## Metadata
**Confidence breakdown:**
- Standard stack: HIGH - All components already in codebase (EventEmitter, Map, IPC)
- Architecture: HIGH - Patterns verified against existing services and IPC handlers
- Pitfalls: HIGH - Identified from EventEmitter research + codebase analysis of FileWatcher/SshConnectionManager
**Research date:** 2026-02-12
**Valid until:** 60 days (2026-04-12) — stable domain, established patterns

476
.planning/phases/03-state-management/03-01-PLAN.md
View file

@ -1,476 +0,0 @@
---
phase: 03-state-management
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- src/renderer/services/contextStorage.ts
- src/renderer/store/slices/contextSlice.ts
- src/renderer/store/types.ts
- src/renderer/store/index.ts
- src/renderer/hooks/useContextSwitch.ts
- src/renderer/components/common/ContextSwitchOverlay.tsx
- src/renderer/App.tsx
autonomous: true
must_haves:
truths:
- "Switching from local to SSH and back restores exact tab state, selected project, and sidebar selections"
- "First-time switch to a new SSH context shows empty state with dashboard tab (not stale local data)"
- "Previously visited context restores instantly from snapshot without refetching"
- "Loading overlay covers entire app during context switch to prevent stale data flash"
- "Context snapshots survive app restart via IndexedDB persistence"
- "Expired snapshots (older than 5 minutes) are treated as missing and cleaned up"
artifacts:
- path: "src/renderer/services/contextStorage.ts"
provides: "IndexedDB persistence layer for context snapshots with TTL"
exports: ["contextStorage"]
- path: "src/renderer/store/slices/contextSlice.ts"
provides: "Zustand slice for context switching state and snapshot/restore orchestration"
exports: ["ContextSlice", "createContextSlice"]
- path: "src/renderer/hooks/useContextSwitch.ts"
provides: "React hook that exposes context switch action to components"
exports: ["useContextSwitch"]
- path: "src/renderer/components/common/ContextSwitchOverlay.tsx"
provides: "Full-screen loading overlay shown during context transitions"
exports: ["ContextSwitchOverlay"]
key_links:
- from: "src/renderer/store/slices/contextSlice.ts"
to: "src/renderer/services/contextStorage.ts"
via: "import contextStorage; called in captureSnapshot/restoreSnapshot actions"
pattern: "contextStorage\\.(saveSnapshot|loadSnapshot)"
- from: "src/renderer/store/slices/contextSlice.ts"
to: "src/renderer/store/index.ts"
via: "createContextSlice composed into useStore"
pattern: "createContextSlice"
- from: "src/renderer/hooks/useContextSwitch.ts"
to: "src/renderer/store/index.ts"
via: "useStore selector for switchContext action"
pattern: "useStore.*switchContext"
- from: "src/renderer/components/common/ContextSwitchOverlay.tsx"
to: "src/renderer/store/index.ts"
via: "useStore selector for isContextSwitching state"
pattern: "useStore.*isContextSwitching"
- from: "src/renderer/App.tsx"
to: "src/renderer/components/common/ContextSwitchOverlay.tsx"
via: "ContextSwitchOverlay rendered at root level"
pattern: "<ContextSwitchOverlay"
---
<objective>
Implement the complete context snapshot/restore system for instant workspace switching.
Purpose: When users switch between local and SSH workspaces, their exact UI state (open tabs, selected project, sidebar selections, scroll positions) must be captured, persisted to IndexedDB, and restored instantly on switch-back. New contexts show clean empty state. A full-screen overlay prevents stale data flash during transitions.
Output: contextSlice (Zustand), contextStorage (IndexedDB), useContextSwitch hook, ContextSwitchOverlay component, all wired into the store and App.
</objective>
<execution_context>
@/home/bskim/.claude/get-shit-done/workflows/execute-plan.md
@/home/bskim/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/03-state-management/03-RESEARCH.md
@.planning/phases/02-service-infrastructure/02-03-SUMMARY.md
# Key existing files to reference:
@src/renderer/store/index.ts
@src/renderer/store/types.ts
@src/renderer/store/slices/connectionSlice.ts
@src/renderer/store/utils/stateResetHelpers.ts
@src/renderer/App.tsx
@src/renderer/store/slices/projectSlice.ts
@src/renderer/store/slices/tabSlice.ts
@src/renderer/store/slices/paneSlice.ts
@src/renderer/store/slices/repositorySlice.ts
@src/renderer/store/slices/sessionSlice.ts
@src/renderer/store/slices/notificationSlice.ts
@src/renderer/store/slices/sessionDetailSlice.ts
@src/renderer/store/slices/conversationSlice.ts
@src/renderer/store/slices/uiSlice.ts
</context>
<tasks>
<task type="auto">
<name>Task 1: Create IndexedDB storage layer and contextSlice</name>
<files>
src/renderer/services/contextStorage.ts
src/renderer/store/slices/contextSlice.ts
</files>
<action>
**Install idb-keyval:**
```bash
pnpm add idb-keyval
```
**Create `src/renderer/services/contextStorage.ts`:**
IndexedDB persistence layer using `idb-keyval` (get, set, del, keys). Implements:
- `SNAPSHOT_TTL_MS = 5 * 60 * 1000` (5-minute TTL)
- `STORAGE_KEY_PREFIX = 'context-snapshot:'`
- `StoredSnapshot` interface: `{ snapshot: ContextSnapshot, timestamp: number, version: number }`
- `saveSnapshot(contextId, snapshot)` — wraps in StoredSnapshot with timestamp, saves via `set()`
- `loadSnapshot(contextId)` — loads via `get()`, checks TTL, returns null if expired (deletes expired entry)
- `deleteSnapshot(contextId)` — deletes via `del()`
- `cleanupExpired()` — iterates all keys with prefix, deletes expired entries
- `isAvailable()` — returns boolean indicating whether IndexedDB is accessible (try/catch around a test `set`/`del`)
- Export as `contextStorage` object (not class)
- All methods are async and handle errors gracefully (catch + console.error + return safe defaults)
**Create `src/renderer/store/slices/contextSlice.ts`:**
Zustand slice managing context switching lifecycle. Interface:
```typescript
export interface ContextSlice {
// State
activeContextId: string; // 'local' initially
isContextSwitching: boolean; // true during switch transition
targetContextId: string | null; // context being switched to
contextSnapshotsReady: boolean; // true after initial IndexedDB check
// Actions
switchContext: (targetContextId: string) => Promise<void>;
initializeContextSystem: () => Promise<void>;
}
```
**`ContextSnapshot` type** — define within contextSlice.ts (not exported from types.ts to keep it internal):
```typescript
interface ContextSnapshot {
// Data state (persistable)
projects: Project[];
selectedProjectId: string | null;
repositoryGroups: RepositoryGroup[];
selectedRepositoryId: string | null;
selectedWorktreeId: string | null;
viewMode: 'flat' | 'grouped';
sessions: Session[];
selectedSessionId: string | null;
sessionsCursor: string | null;
sessionsHasMore: boolean;
sessionsTotalCount: number;
pinnedSessionIds: string[];
notifications: DetectedError[];
unreadCount: number;
// Tab/pane state
openTabs: Tab[];
activeTabId: string | null;
selectedTabIds: string[];
activeProjectId: string | null;
paneLayout: PaneLayout;
// UI state
sidebarCollapsed: boolean;
// Metadata
_metadata: {
contextId: string;
capturedAt: number;
version: number;
};
}
```
**IMPORTANT exclusions from snapshot** (transient state that must NOT be persisted):
- All `*Loading` flags (projectsLoading, sessionsLoading, etc.)
- All `*Error` flags (projectsError, sessionsError, etc.)
- sessionDetail, conversation, sessionClaudeMdStats, sessionContextStats, sessionPhaseInfo (per-session detail data — too large and stale)
- tabSessionData (per-tab cached data — will be re-fetched)
- tabUIStates (per-tab expansion state — Set/Map types not serializable)
- searchQuery, searchVisible, searchMatches, etc. (transient search state)
- commandPaletteOpen (transient UI)
- connectionMode, connectionState, connectedHost, etc. (connection state managed separately)
- configState (managed by ConfigManager, not per-context)
- update state (app-level, not per-context)
- conversationSlice expansion states (not serializable Maps/Sets)
- sessionsLoadingMore (transient)
**`switchContext` action implementation:**
1. Early return if `targetContextId === activeContextId`
2. Set `isContextSwitching: true, targetContextId`
3. Capture current context's snapshot: extract persistable state from `get()`, create ContextSnapshot
4. Save snapshot to IndexedDB via `contextStorage.saveSnapshot(activeContextId, snapshot)`
5. Call `window.electronAPI.context.switch(targetContextId)` to switch main process context
6. Attempt to restore snapshot for target: `contextStorage.loadSnapshot(targetContextId)`
7. If snapshot exists: apply via `set()` with validated state (see validation in Task 3)
8. If no snapshot: apply empty context state via `getEmptyContextState()` helper
9. Fetch fresh data: `fetchProjects()`, `fetchRepositoryGroups()`, `fetchNotifications()`
10. Set `isContextSwitching: false, targetContextId: null, activeContextId: targetContextId`
11. Wrap in try/catch — on error, log, set isContextSwitching: false, do NOT leave in broken state
**`getEmptyContextState()` helper** (internal function):
Returns Partial<AppState> with empty arrays, null selections, single-pane dashboard layout. Pattern: same as `getFullResetState()` but also resets tabs to empty dashboard tab and single pane.
**`initializeContextSystem` action:**
1. Check IndexedDB availability via `contextStorage.isAvailable()`
2. If available: run `contextStorage.cleanupExpired()` to purge stale snapshots
3. Set `contextSnapshotsReady: true`
4. Fetch active context from main process: `window.electronAPI.context.getActive()` and set `activeContextId`
Follow existing slice patterns: use `StateCreator<AppState, [], [], ContextSlice>`, export `createContextSlice`.
</action>
<verify>
pnpm typecheck passes. Both files exist with correct exports. idb-keyval in package.json dependencies.
</verify>
<done>
contextStorage provides IndexedDB save/load/delete/cleanup with TTL. contextSlice provides switchContext and initializeContextSystem actions with proper snapshot capture/restore flow. Transient state (loading, errors, search, Maps/Sets) excluded from snapshots.
</done>
</task>
<task type="auto">
<name>Task 2: Create overlay component, hook, and wire into store</name>
<files>
src/renderer/components/common/ContextSwitchOverlay.tsx
src/renderer/hooks/useContextSwitch.ts
src/renderer/store/types.ts
src/renderer/store/index.ts
</files>
<action>
**Create `src/renderer/components/common/ContextSwitchOverlay.tsx`:**
Full-screen loading overlay displayed during context switches. Uses theme CSS variables for consistency.
```tsx
// Functional component, no props needed
// Reads isContextSwitching and targetContextId from useStore
// If !isContextSwitching, return null
// Render: fixed inset-0 div with bg-surface z-[9999], centered spinner + text
// Spinner: animate-spin h-8 w-8 border-4 border-text border-t-transparent rounded-full
// Text: "Switching to {contextLabel}..." where contextLabel is:
// - 'Local' if targetContextId === 'local'
// - targetContextId with 'ssh-' prefix stripped otherwise
// Use Tailwind classes from project theme (bg-surface, text-text, text-text-secondary)
```
**Create `src/renderer/hooks/useContextSwitch.ts`:**
Thin hook exposing context switch to components.
```typescript
import { useCallback } from 'react';
import { useStore } from '../store';
export function useContextSwitch() {
const switchContext = useStore(state => state.switchContext);
const isContextSwitching = useStore(state => state.isContextSwitching);
const activeContextId = useStore(state => state.activeContextId);
const handleSwitch = useCallback(async (targetContextId: string) => {
await switchContext(targetContextId);
}, [switchContext]);
return {
switchContext: handleSwitch,
isContextSwitching,
activeContextId,
};
}
```
**Update `src/renderer/store/types.ts`:**
- Import `ContextSlice` from `./slices/contextSlice`
- Add `ContextSlice` to the `AppState` intersection type
**Update `src/renderer/store/index.ts`:**
- Import `createContextSlice` from `./slices/contextSlice`
- Add `...createContextSlice(...args)` to the store creation (compose with other slices)
- Do NOT add it to `initializeNotificationListeners` yet (that's Task 3)
</action>
<verify>
pnpm typecheck passes. ContextSwitchOverlay, useContextSwitch, updated types.ts and index.ts all compile without errors. useStore now includes ContextSlice properties.
</verify>
<done>
ContextSwitchOverlay renders loading state during context switch. useContextSwitch hook exposes switchContext/isContextSwitching/activeContextId. Store types and creation updated to include contextSlice.
</done>
</task>
<task type="auto">
<name>Task 3: Wire overlay into App, add context event listener, add snapshot validation</name>
<files>
src/renderer/App.tsx
src/renderer/store/index.ts
src/renderer/store/slices/contextSlice.ts
</files>
<action>
**Update `src/renderer/App.tsx`:**
- Import `ContextSwitchOverlay` from `./components/common/ContextSwitchOverlay`
- Import `useStore` from `./store`
- Add a `useEffect` that calls `useStore.getState().initializeContextSystem()` on mount (before notification listeners init)
- Render `<ContextSwitchOverlay />` as first child inside `<ErrorBoundary>`, before `<TabbedLayout />`
**Update `src/renderer/store/index.ts` — add context:onChanged listener:**
In `initializeNotificationListeners()`, add a listener for context change events from main process:
```typescript
// Listen for context changes from main process (e.g., SSH disconnect)
if (window.electronAPI.context?.onChanged) {
const cleanup = window.electronAPI.context.onChanged((_event: unknown, data: unknown) => {
const { contextId } = data as { contextId: string };
const currentContextId = useStore.getState().activeContextId;
if (contextId !== currentContextId) {
// Main process switched context externally (e.g., SSH disconnect)
// Trigger renderer-side context switch to sync state
void useStore.getState().switchContext(contextId);
}
});
if (typeof cleanup === 'function') {
cleanupFns.push(cleanup);
}
}
```
**Add snapshot validation to `src/renderer/store/slices/contextSlice.ts`:**
Add a `validateSnapshot` internal function called during `restoreSnapshot` step of `switchContext`:
```typescript
function validateSnapshot(
snapshot: ContextSnapshot,
freshProjects: Project[],
freshRepoGroups: RepositoryGroup[]
): Partial<AppState> {
const validProjectIds = new Set(freshProjects.map(p => p.id));
const validWorktreeIds = new Set(
freshRepoGroups.flatMap(rg => rg.worktrees.map(w => w.id))
);
// Validate selectedProjectId
const selectedProjectId = snapshot.selectedProjectId && validProjectIds.has(snapshot.selectedProjectId)
? snapshot.selectedProjectId
: null;
// Validate selectedRepositoryId and selectedWorktreeId
const selectedRepositoryId = snapshot.selectedRepositoryId; // repos may differ but allow graceful fallback
const selectedWorktreeId = snapshot.selectedWorktreeId && validWorktreeIds.has(snapshot.selectedWorktreeId)
? snapshot.selectedWorktreeId
: null;
// Validate tabs — filter out session tabs referencing invalid projects
const validTabs = snapshot.openTabs.filter(tab => {
if (tab.type === 'session' && tab.projectId) {
return validProjectIds.has(tab.projectId) || validWorktreeIds.has(tab.projectId);
}
return true; // Keep dashboard and non-session tabs
});
// Validate activeTabId
let activeTabId = snapshot.activeTabId;
if (activeTabId && !validTabs.find(t => t.id === activeTabId)) {
activeTabId = validTabs[0]?.id ?? null;
}
// Validate pane layout tabs
const validatedPanes = snapshot.paneLayout.panes.map(pane => {
const paneTabs = pane.tabs.filter(tab => {
if (tab.type === 'session' && tab.projectId) {
return validProjectIds.has(tab.projectId) || validWorktreeIds.has(tab.projectId);
}
return true;
});
const paneActiveId = paneTabs.find(t => t.id === pane.activeTabId)
? pane.activeTabId
: paneTabs[0]?.id ?? null;
return {
...pane,
tabs: paneTabs,
activeTabId: paneActiveId,
selectedTabIds: pane.selectedTabIds.filter(id => paneTabs.some(t => t.id === id)),
};
}).filter(pane => pane.tabs.length > 0); // Remove empty panes
// Ensure at least one pane exists
const finalPanes = validatedPanes.length > 0
? validatedPanes
: [{
id: 'pane-default',
tabs: [],
activeTabId: null,
selectedTabIds: [],
widthFraction: 1,
}];
return {
// Restored from snapshot
projects: freshProjects, // Use fresh data, not snapshot's stale list
selectedProjectId,
repositoryGroups: freshRepoGroups, // Use fresh data
selectedRepositoryId,
selectedWorktreeId,
viewMode: snapshot.viewMode,
sessions: snapshot.sessions,
selectedSessionId: snapshot.selectedSessionId,
sessionsCursor: snapshot.sessionsCursor,
sessionsHasMore: snapshot.sessionsHasMore,
sessionsTotalCount: snapshot.sessionsTotalCount,
pinnedSessionIds: snapshot.pinnedSessionIds,
notifications: snapshot.notifications,
unreadCount: snapshot.unreadCount,
openTabs: validTabs,
activeTabId,
selectedTabIds: snapshot.selectedTabIds.filter(id => validTabs.some(t => t.id === id)),
activeProjectId: snapshot.activeProjectId && (validProjectIds.has(snapshot.activeProjectId) || validWorktreeIds.has(snapshot.activeProjectId))
? snapshot.activeProjectId
: selectedProjectId,
paneLayout: {
panes: finalPanes,
focusedPaneId: finalPanes.find(p => p.id === snapshot.paneLayout.focusedPaneId)
? snapshot.paneLayout.focusedPaneId
: finalPanes[0].id,
},
sidebarCollapsed: snapshot.sidebarCollapsed,
};
}
```
**Update `switchContext` action flow** to use validation:
After loading snapshot and BEFORE applying it, fetch fresh projects and repoGroups:
1. Call `window.electronAPI.context.switch(targetContextId)` — switches main process
2. Fetch fresh data: `const [projects, repoGroups] = await Promise.all([window.electronAPI.getProjects(), window.electronAPI.getRepositoryGroups()])`
3. If snapshot exists: call `validateSnapshot(snapshot, projects, repoGroups)` to get validated state, apply via `set()`
4. If no snapshot: apply empty state, then set fresh projects/repoGroups
5. Also fetch notifications in background: `void get().fetchNotifications()`
6. Set `isContextSwitching: false, activeContextId: targetContextId, targetContextId: null`
This ensures restored data references are validated against REAL data from the switched context.
</action>
<verify>
pnpm typecheck passes. pnpm test passes (all existing tests). App.tsx renders ContextSwitchOverlay. Context change listener registered in initializeNotificationListeners. validateSnapshot filters invalid tabs/selections.
</verify>
<done>
App renders overlay during context switches. Main process context change events trigger renderer-side state sync. Snapshot validation ensures restored tabs reference valid projects/worktrees in the target context. Empty panes are removed, at-least-one-pane invariant maintained.
</done>
</task>
</tasks>
<verification>
1. `pnpm typecheck` — zero TypeScript errors
2. `pnpm test` — all existing tests pass (no regressions)
3. `pnpm build` — production build succeeds
4. Verify these files exist with correct exports:
- `src/renderer/services/contextStorage.ts` exports `contextStorage`
- `src/renderer/store/slices/contextSlice.ts` exports `ContextSlice`, `createContextSlice`
- `src/renderer/hooks/useContextSwitch.ts` exports `useContextSwitch`
- `src/renderer/components/common/ContextSwitchOverlay.tsx` exports `ContextSwitchOverlay`
5. Verify `useStore` includes context switching state (activeContextId, isContextSwitching)
6. Verify App.tsx renders `<ContextSwitchOverlay />` inside ErrorBoundary
7. Verify `initializeNotificationListeners` includes context:onChanged listener
</verification>
<success_criteria>
- Context snapshot captures all user-facing data state (projects, sessions, tabs, pane layout, selections, notifications) while excluding transient state (loading flags, errors, search, non-serializable Maps/Sets)
- Snapshot is saved to IndexedDB on context exit and restored on context re-entry
- Expired snapshots (>5 min) are deleted and treated as missing
- New/never-visited contexts get clean empty state with dashboard tab
- Loading overlay prevents stale data flash during the switch transition
- Restored tabs are validated against fresh project/worktree data from the target context
- Main process context change events sync renderer state
- No regressions in existing tests or type checking
</success_criteria>
<output>
After completion, create `.planning/phases/03-state-management/03-01-SUMMARY.md`
</output>

252
.planning/phases/03-state-management/03-01-SUMMARY.md
View file

@ -1,252 +0,0 @@
---
phase: 03-state-management
plan: 01
subsystem: context-switching
tags: [state-management, IndexedDB, snapshot-restore, workspace-switching]
dependency_graph:
requires: [02-03]
provides: [context-snapshot-persistence, instant-workspace-switching]
affects: [renderer-store, ui-state-management]
tech_stack:
added: [idb-keyval@6.2.2]
patterns: [TTL-based-caching, snapshot-validation, discriminated-unions]
key_files:
created:
- src/renderer/services/contextStorage.ts
- src/renderer/store/slices/contextSlice.ts
- src/renderer/components/common/ContextSwitchOverlay.tsx
- src/renderer/hooks/useContextSwitch.ts
modified:
- src/renderer/store/types.ts
- src/renderer/store/index.ts
- src/renderer/App.tsx
- package.json
decisions:
- summary: "5-minute TTL for snapshot expiration (balances staleness vs utility)"
rationale: "SSH sessions often reconnect within 5 minutes; longer TTLs risk stale data confusion"
- summary: "Exclude all transient state from snapshots (loading flags, errors, Maps/Sets)"
rationale: "Only persistable, serializable state survives context switches; transient UI recomputes on restore"
- summary: "Validate restored tabs against fresh project/worktree data"
rationale: "Projects available in local context may not exist in SSH context and vice versa"
- summary: "Full-screen overlay prevents stale data flash during transitions"
rationale: "Users should never see old context data while switching to new context"
metrics:
duration_minutes: 7
tasks_completed: 3
files_created: 4
files_modified: 4
commits: 3
test_status: passing
completed_at: 2026-02-12T01:40:02Z
---
# Phase 03 Plan 01: Context Snapshot and Restore System Summary
**One-liner:** IndexedDB-backed workspace state snapshots with TTL for instant switching between local and SSH contexts, validated against fresh data.
## Objective Achieved
Implemented complete context snapshot/restore system enabling instant workspace switching with zero data loss. Users can switch from local to SSH (or vice versa), perform work, then switch back to find their exact tab layout, selected projects, and UI state perfectly preserved.
## Implementation Details
### IndexedDB Persistence Layer (`contextStorage.ts`)
**Storage mechanism:**
- Uses `idb-keyval` for simple key-value IndexedDB access
- Key format: `context-snapshot:{contextId}` (e.g., `context-snapshot:local`, `context-snapshot:ssh-192.168.1.10`)
- Stored structure: `{ snapshot: ContextSnapshot, timestamp: number, version: number }`
- TTL enforcement: 5 minutes (snapshots older than 5 min are deleted on load/cleanup)
- Version checking: Snapshots with mismatched versions are discarded (future-proofing for schema changes)
**API surface:**
- `saveSnapshot(contextId, snapshot)` — wraps snapshot with metadata, saves to IndexedDB
- `loadSnapshot(contextId)` — loads, checks TTL + version, returns null if expired/invalid/missing
- `deleteSnapshot(contextId)` — removes snapshot
- `cleanupExpired()` — purges all expired snapshots (called on app init)
- `isAvailable()` — tests IndexedDB accessibility (graceful degradation if unavailable)
**Error handling:** All methods catch errors, log via `console.error`, return safe defaults (null/void). Never throws.
### Context Switching Slice (`contextSlice.ts`)
**State:**
- `activeContextId: string` — currently active context (default: `'local'`)
- `isContextSwitching: boolean` — true during transition (triggers full-screen overlay)
- `targetContextId: string | null` — context being switched to
- `contextSnapshotsReady: boolean` — true after IndexedDB init check
**Snapshot structure (`ContextSnapshot` interface):**
Captures persistable state only:
- **Data:** projects, sessions, repositoryGroups, notifications, pinnedSessionIds, unreadCount
- **Selections:** selectedProjectId, selectedSessionId, selectedRepositoryId, selectedWorktreeId, viewMode
- **Tabs/Panes:** openTabs, activeTabId, selectedTabIds, activeProjectId, paneLayout (full pane tree with tabs)
- **UI:** sidebarCollapsed
- **Metadata:** contextId, capturedAt timestamp, version
**Excluded from snapshots (transient state):**
- All `*Loading` flags (projectsLoading, sessionsLoading, etc.)
- All `*Error` strings
- `sessionDetail`, `conversation`, `sessionClaudeMdStats` (too large, stale)
- `tabSessionData`, `tabUIStates` (non-serializable Maps/Sets, will re-fetch)
- Search state (searchQuery, searchMatches, etc.)
- Connection state (managed separately by connectionSlice)
- Config state (managed by ConfigManager)
- Update state (app-level, not per-context)
**`switchContext(targetContextId)` flow:**
1. Early return if `targetContextId === activeContextId`
2. Set `isContextSwitching: true` (triggers overlay)
3. Capture current context snapshot via `captureSnapshot()` helper
4. Save snapshot to IndexedDB via `contextStorage.saveSnapshot()`
5. Switch main process context via `window.electronAPI.context.switch(targetContextId)`
6. Fetch fresh data from target context: `getProjects()`, `getRepositoryGroups()` (parallel)
7. Load target snapshot from IndexedDB via `contextStorage.loadSnapshot(targetContextId)`
8. If snapshot exists:
- Validate via `validateSnapshot()` (filters invalid tabs, ensures at-least-one-pane invariant)
- Apply validated state via `set()`
9. If no snapshot (new/expired):
- Apply empty context state via `getEmptyContextState()` (empty arrays, null selections, single pane)
- Set fresh projects/repoGroups from step 6
10. Fetch notifications in background (non-blocking)
11. Set `isContextSwitching: false, activeContextId: targetContextId, targetContextId: null`
12. Errors: catch, log, set `isContextSwitching: false` (never leave in broken state)
**`validateSnapshot()` logic:**
- Builds `validProjectIds` and `validWorktreeIds` Sets from fresh data
- Filters `openTabs` to remove session tabs referencing invalid projects/worktrees
- Validates `activeTabId` against filtered tabs (fallback to first tab or null)
- Validates pane layout tabs (per-pane filtering)
- Removes empty panes, ensures at-least-one-pane invariant
- Validates `selectedProjectId`, `selectedWorktreeId` against fresh IDs
- Returns `Partial<AppState>` with validated state (safe to spread into `set()`)
**`initializeContextSystem()` action:**
- Checks IndexedDB availability via `contextStorage.isAvailable()`
- Runs `contextStorage.cleanupExpired()` to purge stale snapshots
- Fetches active context ID from main process via `window.electronAPI.context.getActive()`
- Sets `contextSnapshotsReady: true, activeContextId`
### UI Components
**`ContextSwitchOverlay.tsx`:**
- Full-screen overlay (fixed inset-0, z-[9999])
- Displays spinner + "Switching to {contextLabel}..." text
- Renders only when `isContextSwitching === true`
- Context label: strips `ssh-` prefix from contextId (e.g., `ssh-192.168.1.10` → `192.168.1.10`)
- Uses theme CSS variables (`bg-surface`, `text-text`, `text-text-secondary`)
**`useContextSwitch.ts` hook:**
- Thin wrapper exposing `switchContext`, `isContextSwitching`, `activeContextId` from store
- `handleSwitch` callback wraps `switchContext()` with useCallback for stable reference
### Store Integration
**`types.ts`:**
- Added `ContextSlice` import and intersection to `AppState` type
**`index.ts`:**
- Added `createContextSlice` to store composition
- Added `context:onChanged` listener in `initializeNotificationListeners()`:
- Listens for context change events from main process (e.g., SSH disconnect)
- Compares incoming `contextId` with `activeContextId`
- Triggers `switchContext()` if different (syncs renderer state with main process)
**`App.tsx`:**
- Added `initializeContextSystem()` call on mount (before notification listeners)
- Rendered `<ContextSwitchOverlay />` as first child inside `<ErrorBoundary>`
## Deviations from Plan
None — plan executed exactly as written.
## Verification Results
1. ✓ `pnpm typecheck` — zero TypeScript errors
2. ✓ `pnpm test` — 494 tests passed, no regressions
3. ✓ `pnpm build` — production build succeeded
4. ✓ All specified files exist with correct exports:
- `contextStorage` exports `saveSnapshot`, `loadSnapshot`, `deleteSnapshot`, `cleanupExpired`, `isAvailable`
- `contextSlice` exports `ContextSlice` interface, `createContextSlice` function
- `useContextSwitch` exports hook exposing `switchContext`, `isContextSwitching`, `activeContextId`
- `ContextSwitchOverlay` renders full-screen overlay during switches
5. ✓ `useStore` includes ContextSlice properties (activeContextId, isContextSwitching, etc.)
6. ✓ App.tsx renders `<ContextSwitchOverlay />` inside ErrorBoundary
7. ✓ `initializeNotificationListeners` includes `context:onChanged` listener
## Success Criteria Met
- [x] Context snapshot captures all user-facing data state (projects, sessions, tabs, panes, selections, notifications)
- [x] Transient state (loading flags, errors, search, Maps/Sets) excluded from snapshots
- [x] Snapshot saved to IndexedDB on context exit, restored on re-entry
- [x] Expired snapshots (>5 min TTL) deleted and treated as missing
- [x] New/never-visited contexts get clean empty state with empty pane layout
- [x] Loading overlay prevents stale data flash during transitions
- [x] Restored tabs validated against fresh project/worktree data from target context
- [x] Main process context change events sync renderer state
- [x] No regressions in existing tests or type checking
## Testing Strategy
**Manual testing recommended:**
1. Open local project → open tabs → switch to SSH context
2. Verify overlay shows "Switching to {host}..."
3. Verify SSH context shows empty state (no stale local data)
4. Open different tabs in SSH context → switch back to local
5. Verify local tabs restored exactly (same tabs, same active tab, same pane layout)
6. Wait 5+ minutes → switch contexts → verify expired snapshot discarded (fresh empty state)
7. Trigger main process context change (SSH disconnect) → verify renderer syncs automatically
**Snapshot structure validation:**
1. Use browser DevTools → Application → IndexedDB → inspect `context-snapshot:*` keys
2. Verify snapshot contains expected state (tabs, projects, selections)
3. Verify excluded state NOT present (loading flags, errors, search)
## Integration Points
**Upstream (depends on):**
- 02-03: Context IPC handlers (`window.electronAPI.context.switch()`, `getActive()`, `onChanged()`)
- ConfigManager: Provides SSH profile persistence for reconnection
- ServiceContextRegistry: Manages main process context lifecycle
**Downstream (enables):**
- 03-02: Context switcher UI (will consume `useContextSwitch` hook)
- 04-*: UI enhancements (workspace indicators, context-aware displays)
## Known Limitations
1. **Snapshot validation is conservative** — invalid tabs are silently removed. If a project exists in local but not SSH, its tabs are discarded on switch to SSH.
2. **No cross-context session correlation** — if the same session filename exists in local and SSH, they are treated as separate entities.
3. **TTL is global** — cannot configure per-context TTL (all snapshots expire after 5 minutes).
4. **No snapshot size limits** — large pane layouts with 100+ tabs may exceed IndexedDB quota (unlikely in practice).
5. **Version bump strategy undefined** — schema changes require manual `SNAPSHOT_VERSION` increment and migration logic.
## Performance Notes
- **Snapshot capture:** O(n) where n = total state size (~10-50ms for typical workspaces)
- **Snapshot restore:** O(n) validation + IndexedDB read (~20-80ms including validation)
- **IndexedDB cleanup:** O(k) where k = number of stored snapshots (~5-20ms for 5-10 snapshots)
- **Full context switch:** ~200-500ms total (50ms capture + 100ms IPC + 50ms restore + 100-200ms data fetch)
## Self-Check
✓ **Files created:**
- [x] `/home/bskim/claude-devtools/src/renderer/services/contextStorage.ts` exists
- [x] `/home/bskim/claude-devtools/src/renderer/store/slices/contextSlice.ts` exists
- [x] `/home/bskim/claude-devtools/src/renderer/components/common/ContextSwitchOverlay.tsx` exists
- [x] `/home/bskim/claude-devtools/src/renderer/hooks/useContextSwitch.ts` exists
✓ **Commits created:**
- [x] f129715: feat(03-01): add IndexedDB storage layer and contextSlice
- [x] f01d545: feat(03-01): add context switch overlay, hook, and store wiring
- [x] 4ab6b4b: feat(03-01): wire overlay into App and add context event listener
✓ **Verification:**
- [x] `pnpm typecheck` passes
- [x] `pnpm test` passes (494 tests)
- [x] `pnpm build` succeeds
## Self-Check: PASSED
All files, commits, and verifications confirmed.

618
.planning/phases/03-state-management/03-RESEARCH.md
View file

@ -1,618 +0,0 @@
# Phase 3: State Management - Research
**Researched:** 2026-02-12
**Domain:** Frontend state persistence and snapshot/restore patterns for multi-context workspace switching
**Confidence:** HIGH
## Summary
Phase 3 implements snapshot-based state management to enable instant context switching between local and SSH workspaces. The core challenge is capturing complete Zustand state (12 slices totaling ~20+ state properties), persisting snapshots to IndexedDB, and restoring them without flickering or stale data flash. This requires: (1) a contextSlice managing the snapshot/restore lifecycle, (2) IndexedDB persistence with TTL-based expiration, (3) validation logic to ensure restored state references valid data (e.g., projectIds exist in current context), and (4) loading overlays to prevent UI flicker during transition.
The research validates that Zustand's architecture supports manual snapshot/restore via `getState()`/`setState()`, IndexedDB provides the storage layer (with third-party TTL libraries for expiration), and React Suspense-style loading overlays prevent stale data flash. The key architectural pattern is **snapshot-on-exit + validate-on-restore**: capture full state when switching away from a context, persist to IndexedDB, then restore and validate when switching back.
**Primary recommendation:** Use Zustand's native snapshot/restore with `idb-keyval` for IndexedDB storage, implement custom TTL tracking (simpler than external library), validate restored tabs/selections against current context data, and show full-screen loading overlay during context switch to prevent any visual artifacts.
## Standard Stack
### Core
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| Zustand | 4.x (installed) | State management | Already used app-wide; `getState()`/`setState()` enable manual snapshot/restore |
| idb-keyval | Latest (5.x) | IndexedDB wrapper | Official recommendation from Zustand docs for async storage; minimal API (get/set/del) |
| React 18 | 18.x (installed) | UI framework | Suspense/transition APIs enable loading states without flicker |
### Supporting
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| zustand-indexeddb | 0.1.1 | IndexedDB integration via persist middleware | NOT RECOMMENDED - designed for persist() middleware which auto-hydrates; we need manual control for context switching |
| ttl-db | Latest | TTL support for IndexedDB | NOT NEEDED - manual TTL tracking is simpler for this use case (single timestamp per snapshot) |
| zustand/middleware persist | Built-in | Auto-persist state | NOT SUITABLE - auto-hydrates on app start; we need per-context snapshots with manual restore |
### Alternatives Considered
| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| Manual snapshot/restore | Zustand persist middleware | Persist middleware auto-hydrates into a single global state; we need isolated per-context snapshots with manual restoration |
| idb-keyval | localForage | localForage is heavier (~5KB vs ~600B), adds async wrapper complexity we don't need |
| Custom TTL tracking | ttl-db library | ttl-db adds dependency for lazy expiration (checked on read); we need eager cleanup (background interval) to free IndexedDB space |
**Installation:**
```bash
pnpm add idb-keyval
```
## Architecture Patterns
### Recommended Project Structure
```
src/renderer/
├── store/
│ └── slices/
│ └── contextSlice.ts # New: snapshot/restore orchestration
├── services/
│ └── contextStorage.ts # New: IndexedDB persistence layer
├── hooks/
│ └── useContextSwitch.ts # New: hook for triggering context switches
└── components/
└── common/
└── ContextSwitchOverlay.tsx # New: full-screen loading overlay
```
### Pattern 1: Manual Snapshot/Restore (NOT persist middleware)
**What:** Use Zustand's `getState()` to capture state snapshot, store in IndexedDB, then restore via `setState()` on context switch.
**When to use:** When you need isolated state snapshots per context with manual control over when to capture/restore. NOT when you want auto-hydration on app start (that's what persist middleware does).
**Example:**
```typescript
// Capture snapshot
const captureSnapshot = (contextId: string) => {
const state = useStore.getState();
// Extract persistable slices (exclude transient state)
const snapshot = {
projects: state.projects,
selectedProjectId: state.selectedProjectId,
sessions: state.sessions,
selectedSessionId: state.selectedSessionId,
openTabs: state.openTabs,
activeTabId: state.activeTabId,
paneLayout: state.paneLayout,
notifications: state.notifications,
// ... all other slices
_metadata: {
contextId,
capturedAt: Date.now(),
version: 1 // for future migrations
}
};
await contextStorage.saveSnapshot(contextId, snapshot);
};
// Restore snapshot
const restoreSnapshot = async (contextId: string) => {
const snapshot = await contextStorage.loadSnapshot(contextId);
if (!snapshot) return false; // Never visited this context
// Validate snapshot against current context data
const validated = validateSnapshot(snapshot);
// Restore via setState
useStore.setState(validated);
return true;
};
```
**Why manual over persist middleware:**
- Persist middleware auto-hydrates on app init (single global state)
- We need **per-context** snapshots with **manual** restore on switch
- Switching to "never-visited" context must show empty state, not auto-hydrate from IndexedDB
### Pattern 2: IndexedDB Storage Layer with TTL
**What:** Wrapper around `idb-keyval` that stores snapshots with timestamps and provides TTL-based cleanup.
**When to use:** When persisting context snapshots with expiration to prevent unbounded IndexedDB growth.
**Example:**
```typescript
// src/renderer/services/contextStorage.ts
import { get, set, del, keys } from 'idb-keyval';
interface StoredSnapshot {
snapshot: StateSnapshot;
timestamp: number;
version: number;
}
const SNAPSHOT_TTL_MS = 5 * 60 * 1000; // 5 minutes (from phase notes)
const STORAGE_KEY_PREFIX = 'context-snapshot:';
export const contextStorage = {
async saveSnapshot(contextId: string, snapshot: StateSnapshot): Promise<void> {
const stored: StoredSnapshot = {
snapshot,
timestamp: Date.now(),
version: 1
};
await set(`${STORAGE_KEY_PREFIX}${contextId}`, stored);
},
async loadSnapshot(contextId: string): Promise<StateSnapshot | null> {
const stored = await get<StoredSnapshot>(`${STORAGE_KEY_PREFIX}${contextId}`);
if (!stored) return null;
// Check TTL
const age = Date.now() - stored.timestamp;
if (age > SNAPSHOT_TTL_MS) {
await del(`${STORAGE_KEY_PREFIX}${contextId}`); // Expired, delete
return null;
}
return stored.snapshot;
},
async deleteSnapshot(contextId: string): Promise<void> {
await del(`${STORAGE_KEY_PREFIX}${contextId}`);
},
// Background cleanup - call periodically (e.g., on app init, every 5 min)
async cleanupExpired(): Promise<void> {
const allKeys = await keys();
const now = Date.now();
for (const key of allKeys) {
if (typeof key === 'string' && key.startsWith(STORAGE_KEY_PREFIX)) {
const stored = await get<StoredSnapshot>(key);
if (stored && (now - stored.timestamp) > SNAPSHOT_TTL_MS) {
await del(key);
}
}
}
}
};
```
**Why custom TTL over ttl-db:**
- ttl-db uses lazy expiration (checked on read) - we need eager cleanup to free space
- Simple timestamp comparison is easier to reason about than external library
- Only storing one snapshot per context - not a large-scale key-value use case
### Pattern 3: Snapshot Validation
**What:** Validate restored snapshots to ensure references (projectIds, sessionIds, tabIds) exist in the current context.
**When to use:** Always validate after restoring a snapshot to prevent rendering errors from stale references.
**Example:**
```typescript
// Validate that restored tabs reference projects/sessions that exist in current context
const validateSnapshot = (snapshot: StateSnapshot): StateSnapshot => {
const currentProjects = useStore.getState().projects; // Freshly fetched for new context
const validProjectIds = new Set(currentProjects.map(p => p.id));
// Filter tabs to only those with valid projectIds
const validTabs = snapshot.openTabs.filter(tab => {
if (tab.type === 'session' && tab.projectId) {
return validProjectIds.has(tab.projectId);
}
return true; // Keep non-session tabs (e.g., dashboard)
});
// Reset activeTabId if it references invalid tab
let activeTabId = snapshot.activeTabId;
if (activeTabId && !validTabs.find(t => t.id === activeTabId)) {
activeTabId = validTabs[0]?.id ?? null;
}
// Validate pane layout tabs
const validatedPanes = snapshot.paneLayout.panes.map(pane => ({
...pane,
tabs: pane.tabs.filter(tab => {
if (tab.type === 'session' && tab.projectId) {
return validProjectIds.has(tab.projectId);
}
return true;
}),
activeTabId: validTabs.find(t => t.id === pane.activeTabId) ? pane.activeTabId : null
}));
return {
...snapshot,
openTabs: validTabs,
activeTabId,
paneLayout: {
...snapshot.paneLayout,
panes: validatedPanes
}
};
};
```
**Why validation is critical:**
- Switching to a different context means different projects/sessions exist
- Restored tabs may reference projectIds that don't exist in the new context
- Without validation: React will error trying to render non-existent data
### Pattern 4: Loading Overlay During Context Switch
**What:** Display full-screen overlay during context switch to prevent stale data flash.
**When to use:** During context switches to mask the snapshot/restore + data refetch sequence.
**Example:**
```typescript
// src/renderer/components/common/ContextSwitchOverlay.tsx
export const ContextSwitchOverlay: React.FC = () => {
const isSwitching = useStore(state => state.isContextSwitching);
const targetContext = useStore(state => state.targetContextId);
if (!isSwitching) return null;
return (
<div className="fixed inset-0 bg-surface z-[9999] flex items-center justify-center">
<div className="flex flex-col items-center gap-4">
<div className="animate-spin h-8 w-8 border-4 border-text border-t-transparent rounded-full" />
<p className="text-text-secondary">
Switching to {targetContext === 'local' ? 'Local' : targetContext}...
</p>
</div>
</div>
);
};
// In App.tsx
return (
<>
<ContextSwitchOverlay />
{/* Rest of app */}
</>
);
```
**Based on Next.js loading.js pattern:** Show instant loading state while content switches, then remove overlay once restoration completes. See [Loading UI and Streaming - Next.js](https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming).
### Anti-Patterns to Avoid
- **DON'T use Zustand persist middleware for context snapshots:** Persist middleware auto-hydrates on app init into a single global state. We need per-context snapshots with manual restore on switch.
- **DON'T skip validation after restore:** Restored state may contain references to projects/sessions that don't exist in the new context. Always validate and filter invalid references.
- **DON'T restore without showing loading state:** Users will see stale data flash as the old context's UI renders briefly before restoration completes. Always show full-screen overlay during transition.
- **DON'T store derived/computed state:** Only persist base state. Derived values (e.g., filtered lists, computed counts) should be recomputed from restored base state.
- **DON'T persist transient UI state:** Loading flags, error messages, and other transient state should NOT be persisted. Only persist user-facing data and selections.
## Don't Hand-Roll
| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| IndexedDB wrapper | Custom promise-based IndexedDB code | `idb-keyval` | Handles browser quirks, transaction management, error recovery; battle-tested across browsers |
| State serialization | Custom JSON serialization with special cases | Native `JSON.stringify/parse` | Zustand state is already JSON-serializable (no Maps, Sets, Dates in store) |
| TTL expiration checking | Complex timestamp algebra | Simple `Date.now() - stored.timestamp > TTL_MS` | Single comparison is sufficient; no need for date libraries |
| Loading state coordination | Manual boolean flags and setTimeout | React 18 transitions (optional) | Built-in concurrent rendering prevents UI flicker |
**Key insight:** State persistence is deceptively complex due to:
- **Browser compatibility:** IndexedDB behavior varies across browsers (quota limits, transaction lifetimes, error modes)
- **Race conditions:** Multiple tabs accessing same IndexedDB can cause conflicts
- **Quota limits:** Browsers impose storage limits; need cleanup strategy
- **Serialization edge cases:** Circular references, non-serializable types (functions, symbols)
Using `idb-keyval` eliminates these concerns with a 600-byte library that's maintained by the Dexie.js team (IndexedDB experts).
## Common Pitfalls
### Pitfall 1: Auto-hydration with persist middleware
**What goes wrong:** Using Zustand's persist middleware causes auto-hydration on app init, loading the last-saved snapshot into the global store before the user switches contexts.
**Why it happens:** Persist middleware is designed for single-state persistence (e.g., saving user preferences). It auto-calls `rehydrate()` on store creation.
**How to avoid:** Use manual snapshot/restore with `getState()`/`setState()`. Only call restore when the user explicitly switches to a context.
**Warning signs:**
- UI shows data from a different context on app start
- "Hydration mismatch" errors in console
- State resets unexpectedly after reload
### Pitfall 2: Stale Data Flash During Restore
**What goes wrong:** When restoring a snapshot, the UI briefly shows the previous context's data before the new snapshot applies, causing visual flicker.
**Why it happens:** React re-renders with old state before `setState()` completes. Without a loading overlay, users see the old context's projects/sessions for 50-100ms.
**How to avoid:**
1. Set `isContextSwitching: true` BEFORE calling `setState()`
2. Show full-screen loading overlay while `isContextSwitching` is true
3. Complete restore sequence (snapshot + data refetch)
4. Set `isContextSwitching: false` to remove overlay
**Warning signs:**
- Users report seeing "flickering" or "old data" during context switch
- Tabs briefly show wrong session titles before updating
- Sidebar jumps between different project lists
### Pitfall 3: Invalid References After Restore
**What goes wrong:** Restored tabs reference projectIds or sessionIds that don't exist in the new context, causing React to throw errors or render empty states.
**Why it happens:** Contexts have different projects/sessions. Restoring a snapshot from Context A into Context B means tab.projectId may not exist in Context B's data.
**How to avoid:** Always validate restored state against current context data:
```typescript
const validTabs = snapshot.openTabs.filter(tab => {
if (tab.type === 'session' && tab.projectId) {
return currentProjectIds.has(tab.projectId);
}
return true;
});
```
**Warning signs:**
- Console errors: "Cannot read property 'name' of undefined"
- Tabs show blank content or "Session not found"
- Sidebar selections don't match visible tabs
### Pitfall 4: IndexedDB Quota Exceeded
**What goes wrong:** Snapshots accumulate in IndexedDB until browser quota is exceeded, causing storage failures.
**Why it happens:** No cleanup strategy for expired snapshots or old SSH contexts that no longer exist.
**How to avoid:**
1. Implement TTL-based expiration (5 minutes per phase notes)
2. Run cleanup on app init and periodically (every 5 minutes)
3. Delete snapshots when SSH context is destroyed
4. Store only essential state (exclude transient loading/error flags)
**Warning signs:**
- "QuotaExceededError" in console
- Snapshots fail to save silently
- IndexedDB inspector shows hundreds of old snapshot entries
### Pitfall 5: Restoring Transient State
**What goes wrong:** Loading flags, error messages, and other transient UI state get persisted and restored, causing confusing behavior (e.g., "Loading..." shown on restore).
**Why it happens:** Snapshot captures entire Zustand state including transient flags like `projectsLoading: true`.
**How to avoid:** Use `partialize` pattern to exclude transient state:
```typescript
const snapshot = {
// Include
projects: state.projects,
selectedProjectId: state.selectedProjectId,
openTabs: state.openTabs,
// Exclude transient state
// projectsLoading: false, // NEVER persist loading flags
// projectsError: null, // NEVER persist errors
};
```
**Warning signs:**
- Restored context shows loading spinners that never complete
- Error messages from previous context appear in new context
- UI is "stuck" in loading state after restore
## Code Examples
Verified patterns from official sources:
### Zustand Manual State Capture/Restore
```typescript
// Source: Zustand docs - https://zustand.docs.pmnd.rs/guides/how-to-reset-state
import { useStore } from './store';
// Capture current state
const currentState = useStore.getState();
// Restore state later
useStore.setState({
projects: restoredProjects,
selectedProjectId: restoredSelectedProjectId,
// ... all other slices
}, true); // Second arg `true` = replace entire state (not merge)
```
**Note:** The `replace` parameter (second arg) controls whether to merge or replace. For context switching, use `replace: false` (default) to merge the snapshot with current state, preserving any runtime-only state.
### IndexedDB with idb-keyval
```typescript
// Source: Zustand persist docs - https://zustand.docs.pmnd.rs/integrations/persisting-store-data
import { get, set, del } from 'idb-keyval';
// Save
await set('context-snapshot:local', {
snapshot: { /* state */ },
timestamp: Date.now()
});
// Load
const stored = await get('context-snapshot:local');
// Delete
await del('context-snapshot:local');
```
### Context Switch Hook
```typescript
// Pattern based on Zustand actions + async state transitions
export const useContextSwitch = () => {
const switchContext = useStore(state => state.switchContext);
const handleSwitch = async (targetContextId: string) => {
// 1. Show loading overlay
useStore.setState({ isContextSwitching: true, targetContextId });
try {
// 2. Capture current context's snapshot
const currentContextId = await window.electronAPI.context.getActiveContextId();
await captureSnapshot(currentContextId);
// 3. Switch context in main process (updates ServiceContextRegistry)
await window.electronAPI.context.switch(targetContextId);
// 4. Try to restore snapshot for target context
const restored = await restoreSnapshot(targetContextId);
if (!restored) {
// Never visited this context - show empty state
useStore.setState(getEmptyContextState());
}
// 5. Fetch fresh data for target context
await Promise.all([
useStore.getState().fetchProjects(),
useStore.getState().fetchRepositoryGroups(),
useStore.getState().fetchNotifications()
]);
// 6. Hide loading overlay
useStore.setState({ isContextSwitching: false, targetContextId: null });
} catch (error) {
console.error('Context switch failed:', error);
useStore.setState({
isContextSwitching: false,
targetContextId: null,
// Show error to user
});
}
};
return { switchContext: handleSwitch };
};
```
### Empty State for New Context
```typescript
// When switching to a never-visited context, reset to empty state
const getEmptyContextState = (): Partial<AppState> => ({
// Projects
projects: [],
selectedProjectId: null,
// Sessions
sessions: [],
selectedSessionId: null,
sessionsPagination: { hasMore: false, currentPage: 0 },
// Tabs
openTabs: [{ type: 'dashboard', id: 'dashboard', label: 'Dashboard' }],
activeTabId: 'dashboard',
// Pane layout - single pane with dashboard tab
paneLayout: {
panes: [{
id: 'pane-default',
tabs: [{ type: 'dashboard', id: 'dashboard', label: 'Dashboard' }],
activeTabId: 'dashboard',
selectedTabIds: [],
widthFraction: 1
}],
focusedPaneId: 'pane-default'
},
// Notifications
notifications: [],
unreadCount: 0,
// Repository
repositoryGroups: [],
// Session detail
sessionDetail: null,
sessionChunks: [],
sessionMetrics: null,
// Conversation
conversationGroups: [],
// Subagent
subagentDetail: null,
selectedSubagentId: null,
});
```
## State of the Art
| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| localStorage for state | IndexedDB for state | 2020+ | IndexedDB supports larger quotas (50MB+) and structured data; localStorage limited to 5-10MB strings |
| Redux persist middleware | Zustand manual snapshot | 2021+ | Zustand's simpler API enables custom snapshot/restore without middleware complexity |
| Manual TTL tracking | Libraries like ttl-db | 2023+ | For simple TTL use cases (single timestamp), manual tracking is simpler than library dependency |
| Class components with getDerivedStateFromProps | React 18 Suspense/Transitions | 2022+ | Concurrent rendering prevents UI flicker during async state changes |
**Deprecated/outdated:**
- **localStorage for large state:** Replaced by IndexedDB for quota limits and structured data support
- **Zustand persist middleware for multi-context:** Designed for single-state persistence; manual snapshot/restore needed for per-context isolation
- **react-loading-overlay package:** React 18's Suspense provides built-in loading state coordination
## Open Questions
1. **Snapshot size optimization**
- What we know: Full Zustand state snapshot includes all 12 slices (projects, sessions, tabs, notifications, etc.)
- What's unclear: If snapshots exceed 1MB, should we compress (e.g., pako) or partialize more aggressively?
- Recommendation: Start without compression; monitor snapshot sizes in production. Add compression if snapshots exceed 500KB.
2. **TTL tuning for different contexts**
- What we know: Phase notes suggest 5-minute TTL based on "typical user switching patterns"
- What's unclear: Should SSH contexts have longer TTL than local (users might stay in SSH for hours)?
- Recommendation: Start with uniform 5-minute TTL; add per-context TTL configuration if users report frequent "empty state on switch back" issues.
3. **Graceful degradation when IndexedDB unavailable**
- What we know: Private browsing modes and some browsers disable IndexedDB
- What's unclear: Should we fall back to in-memory snapshots or disable persistence entirely?
- Recommendation: Detect IndexedDB availability on app init; if unavailable, log warning and use in-memory Map for current session only (no persistence across restarts).
4. **Migration strategy for snapshot schema changes**
- What we know: Zustand persist middleware supports version migrations
- What's unclear: How to handle breaking changes to snapshot structure in future releases?
- Recommendation: Include `version` field in stored snapshot; implement migration function that transforms old versions to current schema on load.
## Sources
### Primary (HIGH confidence)
- [Zustand Persist Middleware Documentation](https://zustand.docs.pmnd.rs/integrations/persisting-store-data) - Official docs covering persist middleware, custom storage engines, version migration, and sync vs async storage differences
- [GitHub: zustand-indexeddb](https://github.com/zustandjs/zustand-indexeddb) - Official IndexedDB integration library showing API and limitations
- [GitHub: How can I use zustand persist with indexeddb?](https://github.com/pmndrs/zustand/discussions/1721) - Official discussion confirming idb-keyval as recommended approach
- [Zustand Beginner TypeScript Guide](https://zustand.docs.pmnd.rs/guides/beginner-typescript) - TypeScript patterns for selectors and derived state
### Secondary (MEDIUM confidence)
- [Loading UI and Streaming - Next.js](https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming) - Pattern for instant loading states during transitions
- [Data Grid - Overlays - MUI X](https://mui.com/x/react-data-grid/overlays/) - Loading overlay patterns for preventing stale data display
- [GitHub: ttl-db](https://github.com/jtsang4/ttl-db) - TTL implementation for IndexedDB showing API and expiration patterns
### Tertiary (LOW confidence)
- [Understanding Zustand: A Lightweight State Management Library](https://blog.msar.me/understanding-zustand-a-lightweight-state-management-library-for-react) - Third-party blog covering derived state patterns
- [Fixing React UI Updates: Stale Data and Caching Issues](https://www.techedubyte.com/react-ui-updates-stale-data-caching-fix/) - Community articles on preventing stale data flash (validate patterns against official docs)
## Metadata
**Confidence breakdown:**
- Standard stack: HIGH - Zustand + idb-keyval confirmed via official docs and recommendations
- Architecture: HIGH - Manual snapshot/restore pattern verified through Zustand docs and community discussions
- Pitfalls: MEDIUM - Common issues identified through GitHub issues and community discussions; validated against official docs
**Research date:** 2026-02-12
**Valid until:** 2026-03-12 (30 days - Zustand is stable, patterns unlikely to change)
**Key findings:**
1. Zustand persist middleware is NOT suitable for per-context snapshots (auto-hydrates single global state)
2. Manual snapshot/restore via `getState()`/`setState()` is the correct pattern for multi-context isolation
3. IndexedDB via `idb-keyval` provides simple async storage with browser compatibility handled
4. Custom TTL tracking (timestamp comparison) is simpler than library dependency for single-snapshot use case
5. Snapshot validation is CRITICAL to prevent rendering errors from stale references
6. Loading overlay during context switch prevents stale data flash (Next.js loading.js pattern)

302
.planning/phases/04-workspace-ui/04-01-PLAN.md
View file

@ -1,302 +0,0 @@
---
phase: 04-workspace-ui
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- src/renderer/components/common/ContextSwitcher.tsx
- src/renderer/components/common/ConnectionStatusBadge.tsx
- src/renderer/components/layout/SidebarHeader.tsx
- src/renderer/hooks/useKeyboardShortcuts.ts
- src/renderer/store/slices/contextSlice.ts
- src/renderer/App.tsx
autonomous: true
must_haves:
truths:
- "User sees context switcher in SidebarHeader Row 1 listing Local + all connected SSH workspaces"
- "Each workspace item shows connection status icon (connected/connecting/disconnected/error with distinct colors)"
- "User can click a workspace in the dropdown to switch contexts (triggers switchContext from contextSlice)"
- "User can press Cmd/Ctrl+Shift+K to cycle to the next context"
- "Context switcher is disabled while isContextSwitching is true (prevents race condition)"
- "Available contexts refresh on mount and when SSH status changes"
artifacts:
- path: "src/renderer/components/common/ContextSwitcher.tsx"
provides: "Dropdown listing local + SSH contexts with status badges, switch-on-click"
min_lines: 60
- path: "src/renderer/components/common/ConnectionStatusBadge.tsx"
provides: "Icon component rendering 4 connection states with distinct visual treatment"
min_lines: 25
- path: "src/renderer/components/layout/SidebarHeader.tsx"
provides: "Modified Row 1 with ContextSwitcher before project name"
- path: "src/renderer/hooks/useKeyboardShortcuts.ts"
provides: "Cmd+Shift+K shortcut for context cycling"
- path: "src/renderer/store/slices/contextSlice.ts"
provides: "availableContexts state + fetchAvailableContexts action"
key_links:
- from: "src/renderer/components/common/ContextSwitcher.tsx"
to: "src/renderer/store/slices/contextSlice.ts"
via: "useStore consuming availableContexts, activeContextId, switchContext, isContextSwitching"
pattern: "useStore.*availableContexts|switchContext"
- from: "src/renderer/components/common/ConnectionStatusBadge.tsx"
to: "src/renderer/store/slices/connectionSlice.ts"
via: "useStore consuming connectionState for SSH contexts"
pattern: "connectionState"
- from: "src/renderer/components/layout/SidebarHeader.tsx"
to: "src/renderer/components/common/ContextSwitcher.tsx"
via: "ContextSwitcher rendered in Row 1"
pattern: "<ContextSwitcher"
- from: "src/renderer/hooks/useKeyboardShortcuts.ts"
to: "src/renderer/store/slices/contextSlice.ts"
via: "Cmd+Shift+K triggers switchContext with next context from availableContexts"
pattern: "shiftKey.*switchContext|availableContexts"
---
<objective>
Create the context switcher UI and keyboard shortcuts for workspace switching.
Purpose: Users need a visible, always-accessible way to see which workspace (local or SSH) they are in, switch between workspaces, and understand connection status at a glance. This is the primary user-facing UI for the multi-context system built in Phases 1-3.
Output: ContextSwitcher dropdown in SidebarHeader, ConnectionStatusBadge icons, Cmd+Shift+K shortcut, and availableContexts state in contextSlice.
</objective>
<execution_context>
@/home/bskim/.claude/get-shit-done/workflows/execute-plan.md
@/home/bskim/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/04-workspace-ui/04-RESEARCH.md
@.planning/phases/03-state-management/03-01-SUMMARY.md
@src/renderer/components/layout/SidebarHeader.tsx
@src/renderer/hooks/useKeyboardShortcuts.ts
@src/renderer/store/slices/contextSlice.ts
@src/renderer/store/slices/connectionSlice.ts
@src/renderer/App.tsx
@src/renderer/components/settings/sections/ConnectionSection.tsx
@src/preload/index.ts
@src/shared/types/api.ts
</context>
<tasks>
<task type="auto">
<name>Task 1: Create ConnectionStatusBadge and ContextSwitcher components</name>
<files>
src/renderer/components/common/ConnectionStatusBadge.tsx
src/renderer/components/common/ContextSwitcher.tsx
src/renderer/store/slices/contextSlice.ts
</files>
<action>
**1. Add availableContexts state to contextSlice.ts:**
Add to `ContextSlice` interface:
- `availableContexts: ContextInfo[]` (import `ContextInfo` from `@shared/types/api`)
- `fetchAvailableContexts: () => Promise<void>`
Add to slice creator initial state:
- `availableContexts: [{ id: 'local', type: 'local' as const }]`
Implement `fetchAvailableContexts`:
- Call `window.electronAPI.context.list()`
- `set({ availableContexts: result })`
- Wrap in try/catch, on error fallback to `[{ id: 'local', type: 'local' }]`
Also call `fetchAvailableContexts()` inside `initializeContextSystem()` after setting `contextSnapshotsReady: true`.
**2. Create ConnectionStatusBadge.tsx:**
Small icon component that renders connection state visually:
```typescript
import { Loader2, Monitor, Wifi, WifiOff } from 'lucide-react';
import { useStore } from '@renderer/store';
```
Props: `{ contextId: string; className?: string }`
Logic:
- If `contextId === 'local'`: render `<Monitor className="size-3.5 text-text-muted" />`
- If SSH: read `connectionState` and `connectedHost` from store via `useStore`
- Determine if this specific SSH context matches the connected host: `contextId === 'ssh-' + connectedHost`
- If match: use `connectionState` value
- If no match: treat as `'disconnected'`
- Render by state:
- `'connected'`: `<Wifi className="size-3.5 text-green-400" />`
- `'connecting'`: `<Loader2 className="size-3.5 animate-spin text-text-muted" />`
- `'disconnected'`: `<WifiOff className="size-3.5 text-text-muted" />`
- `'error'`: `<WifiOff className="size-3.5 text-red-400" />`
Apply `className` prop to wrapper if provided.
**3. Create ContextSwitcher.tsx:**
Follow the SidebarHeader dropdown pattern exactly (useRef, outside click, escape key, `inset-x-4` dropdown positioning).
Props: none (reads everything from store).
Store selectors (via `useShallow`):
- `activeContextId`, `isContextSwitching`, `availableContexts`, `switchContext`
State:
- `isOpen: boolean` (dropdown visibility)
- `dropdownRef: useRef<HTMLDivElement>`
Effects:
- Close on outside click (same pattern as SidebarHeader line 266-283)
- Close on Escape key (same pattern as SidebarHeader line 286-295)
Render:
- Trigger button:
- `ConnectionStatusBadge` for active context
- Display label: `'Local'` for `contextId === 'local'`, strip `'ssh-'` prefix for SSH (e.g., `ssh-192.168.1.10` -> `192.168.1.10`)
- `ChevronDown` icon (rotate-180 when open)
- `disabled={isContextSwitching}` and `opacity-50` when switching
- `style={{ WebkitAppRegion: 'no-drag' }}` (sits in drag region)
- Dropdown panel (when `isOpen && !isContextSwitching`):
- Fixed backdrop overlay `className="fixed inset-0 z-10"` (same as SidebarHeader)
- Panel: `absolute inset-x-4 top-full z-20 mt-1 max-h-[250px] overflow-y-auto rounded-lg py-1 shadow-xl`
- Background: `var(--color-surface-sidebar)`, border: `var(--color-border)`
- Header label: "Switch Workspace" (same style as SidebarHeader "Switch Repository")
- For each context in `availableContexts`:
- Button with hover state (follow ProjectDropdownItem pattern)
- `ConnectionStatusBadge` icon
- Label text (Local or host name)
- `Check` icon if `ctx.id === activeContextId`
- onClick: `switchContext(ctx.id)` then `setIsOpen(false)`
Use theme CSS variables throughout (no hardcoded colors except green-400/red-400 for status).
</action>
<verify>
Run `pnpm typecheck` - zero errors. Verify ContextSwitcher.tsx, ConnectionStatusBadge.tsx, and updated contextSlice.ts exist with correct exports. Confirm `availableContexts` is in the ContextSlice interface.
</verify>
<done>
ContextSwitcher renders a dropdown listing Local + SSH contexts with status badges. ConnectionStatusBadge shows 4 distinct states. contextSlice tracks availableContexts fetched from context.list() IPC. All three files type-check cleanly.
</done>
</task>
<task type="auto">
<name>Task 2: Wire ContextSwitcher into SidebarHeader and add keyboard shortcut</name>
<files>
src/renderer/components/layout/SidebarHeader.tsx
src/renderer/hooks/useKeyboardShortcuts.ts
src/renderer/App.tsx
</files>
<action>
**1. Modify SidebarHeader.tsx - Add ContextSwitcher to Row 1:**
Import `ContextSwitcher` from `'../common/ContextSwitcher'`.
In the Row 1 div (the one with `height: HEADER_ROW1_HEIGHT`, `paddingLeft: var(--macos-traffic-light-padding-left)`), add `ContextSwitcher` as the FIRST child before the existing project name button:
```tsx
{/* ROW 1: Project Identity (Title Bar / Drag Region) */}
<div ref={projectDropdownRef} className="relative flex select-none items-center justify-between pr-2" ...>
{/* NEW: Context Switcher - workspace indicator */}
<ContextSwitcher />
{/* Existing: Project name dropdown button */}
<button onClick={() => setIsProjectDropdownOpen(...)} ...>
...
</button>
{/* Existing: Collapse sidebar button */}
<button onClick={toggleSidebar} ...>
...
</button>
</div>
```
The ContextSwitcher already has `WebkitAppRegion: 'no-drag'` on its button, and the Row 1 div is the drag region, so it integrates naturally.
Add a small visual separator between ContextSwitcher and project name. Use a `<div>` with `className="mx-1 h-4 w-px"` and `style={{ backgroundColor: 'var(--color-border)' }}` between them. This gives a subtle vertical line separating "workspace" from "project".
Ensure the Row 1 layout uses `gap-2` or appropriate spacing so the new element fits without overflow. The existing `justify-between` may need adjustment - change to `gap-2` and keep the collapse button at the right with `ml-auto`.
**2. Modify useKeyboardShortcuts.ts - Add Cmd+Shift+K:**
Add to useShallow selector:
- `availableContexts: s.availableContexts`
- `activeContextId: s.activeContextId`
- `switchContext: s.switchContext`
- `isContextSwitching: s.isContextSwitching`
IMPORTANT: The Cmd+Shift+K check MUST come BEFORE the existing Cmd+K check (line 209). Since both match `event.key === 'k'`, the shiftKey variant must be tested first:
```typescript
// Cmd+Shift+K: Cycle to next workspace context
if (event.key === 'k' && event.shiftKey) {
event.preventDefault();
if (!isContextSwitching && availableContexts.length > 1) {
const currentIndex = availableContexts.findIndex(c => c.id === activeContextId);
const nextIndex = (currentIndex + 1) % availableContexts.length;
void switchContext(availableContexts[nextIndex].id);
}
return;
}
// Cmd+K: Open command palette for global search (existing)
if (event.key === 'k') {
...
}
```
Add `availableContexts`, `activeContextId`, `switchContext`, `isContextSwitching` to the useEffect dependency array.
**3. Modify App.tsx - Refresh contexts on SSH status change:**
Add a useEffect that listens for SSH status changes and refreshes the available contexts list:
```typescript
// Refresh available contexts when SSH connection state changes
useEffect(() => {
if (!window.electronAPI.ssh?.onStatus) return;
const cleanup = window.electronAPI.ssh.onStatus(() => {
void useStore.getState().fetchAvailableContexts();
});
return cleanup;
}, []);
```
This ensures the ContextSwitcher dropdown always reflects current SSH connections. Place this after the existing context system initialization effect.
</action>
<verify>
Run `pnpm typecheck` - zero errors. Run `pnpm test` - all tests pass. Run `pnpm build` - production build succeeds. Verify SidebarHeader renders ContextSwitcher in Row 1. Verify useKeyboardShortcuts handles Cmd+Shift+K before Cmd+K.
</verify>
<done>
SidebarHeader Row 1 shows [ContextSwitcher | separator | ProjectName | CollapseBtn]. Cmd+Shift+K cycles through available contexts. SSH status changes trigger context list refresh. No regressions in existing tests or type checking.
</done>
</task>
</tasks>
<verification>
1. `pnpm typecheck` passes with zero errors
2. `pnpm test` passes with no regressions
3. `pnpm build` succeeds
4. ContextSwitcher.tsx exports a component that renders a dropdown
5. ConnectionStatusBadge.tsx exports a component with 4 visual states
6. SidebarHeader.tsx imports and renders ContextSwitcher in Row 1
7. useKeyboardShortcuts.ts checks Cmd+Shift+K BEFORE Cmd+K
8. contextSlice.ts has availableContexts state and fetchAvailableContexts action
9. App.tsx has SSH status listener that refreshes available contexts
</verification>
<success_criteria>
- Context switcher visible in sidebar header showing active workspace with status icon
- Dropdown lists Local + all connected SSH workspaces
- Connection status icons: Monitor (local), Wifi/green (connected), Spinner (connecting), WifiOff/muted (disconnected), WifiOff/red (error)
- Clicking a workspace triggers context switch with overlay
- Cmd+Shift+K cycles through available workspaces
- Switcher disabled during active context switch
- Available contexts refresh when SSH status changes
</success_criteria>
<output>
After completion, create `.planning/phases/04-workspace-ui/04-01-SUMMARY.md`
</output>

97
.planning/phases/04-workspace-ui/04-01-SUMMARY.md
View file

@ -1,97 +0,0 @@
---
phase: 04-workspace-ui
plan: 01
subsystem: ui
tags: [react, zustand, lucide-react, keyboard-shortcuts, dropdown]
requires:
- phase: 03-state-management
provides: contextSlice with switchContext, activeContextId, isContextSwitching
- phase: 02-service-infrastructure
provides: context.list() IPC, context.switch() IPC, ssh.onStatus() listener
provides:
- ContextSwitcher dropdown component listing Local + SSH workspaces with status badges
- ConnectionStatusBadge icon component with 4 visual states
- Cmd+Shift+K keyboard shortcut for workspace cycling
- availableContexts state and fetchAvailableContexts action in contextSlice
- SSH status listener in App.tsx refreshing context list on changes
affects: [04-02-workspace-settings]
tech-stack:
added: []
patterns: [sidebar-header-dropdown-pattern, connection-status-icon-states]
key-files:
created:
- src/renderer/components/common/ContextSwitcher.tsx
- src/renderer/components/common/ConnectionStatusBadge.tsx
modified:
- src/renderer/store/slices/contextSlice.ts
- src/renderer/components/layout/SidebarHeader.tsx
- src/renderer/hooks/useKeyboardShortcuts.ts
- src/renderer/App.tsx
key-decisions:
- "ContextSwitcher placed first in SidebarHeader Row 1, before project name, with vertical separator"
- "Cmd+Shift+K check placed before Cmd+K to avoid shortcut shadowing"
- "SSH status listener refreshes available contexts automatically on connection changes"
patterns-established:
- "ConnectionStatusBadge: 4-state icon rendering (Monitor/local, Wifi/green connected, Loader2/spinner connecting, WifiOff/muted disconnected, WifiOff/red error)"
- "Context switcher dropdown follows SidebarHeader dropdown pattern (useRef, outside click, escape key)"
duration: 6min
completed: 2026-02-12
---
# Plan 04-01: Context Switcher Summary
**ContextSwitcher dropdown in SidebarHeader with ConnectionStatusBadge icons and Cmd+Shift+K workspace cycling**
## Performance
- **Duration:** 6 min
- **Completed:** 2026-02-12
- **Tasks:** 2
- **Files modified:** 6
## Accomplishments
- ContextSwitcher dropdown in sidebar header listing Local + SSH workspaces with connection status badges
- ConnectionStatusBadge component with 4 distinct visual states (local/connected/connecting/disconnected/error)
- Cmd+Shift+K keyboard shortcut for cycling through available workspaces
- Automatic context list refresh when SSH connection state changes
## Task Commits
1. **Task 1: Create ConnectionStatusBadge and ContextSwitcher components** - `ca60158` (feat)
2. **Task 2: Wire ContextSwitcher into SidebarHeader and add keyboard shortcut** - `58f4be0` (feat)
## Files Created/Modified
- `src/renderer/components/common/ConnectionStatusBadge.tsx` - Icon component rendering 4 connection states
- `src/renderer/components/common/ContextSwitcher.tsx` - Dropdown listing local + SSH contexts with switch-on-click
- `src/renderer/store/slices/contextSlice.ts` - Added availableContexts state and fetchAvailableContexts action
- `src/renderer/components/layout/SidebarHeader.tsx` - Added ContextSwitcher to Row 1 with separator
- `src/renderer/hooks/useKeyboardShortcuts.ts` - Added Cmd+Shift+K before Cmd+K
- `src/renderer/App.tsx` - Added SSH status listener for context refresh
## Decisions Made
- ContextSwitcher placed first in Row 1 (before project name) with vertical divider separator
- Cmd+Shift+K must come before Cmd+K in the handler to avoid shortcut shadowing
- Row 1 layout changed from justify-between to gap-2 with ml-auto on collapse button
## Deviations from Plan
None - plan executed exactly as written
## Issues Encountered
None
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- Context switcher is functional and ready for 04-02 (workspace settings) to add SSH profile CRUD
- fetchAvailableContexts is called by WorkspaceSection after profile changes
---
*Phase: 04-workspace-ui*
*Completed: 2026-02-12*

256
.planning/phases/04-workspace-ui/04-02-PLAN.md
View file

@ -1,256 +0,0 @@
---
phase: 04-workspace-ui
plan: 02
type: execute
wave: 2
depends_on: ["04-01"]
files_modified:
- src/renderer/components/settings/sections/WorkspaceSection.tsx
- src/renderer/components/settings/sections/index.ts
- src/renderer/components/settings/SettingsTabs.tsx
- src/renderer/components/settings/SettingsView.tsx
autonomous: true
must_haves:
truths:
- "User can see a 'Workspace' tab in settings that lists saved SSH connection profiles"
- "User can add a new SSH profile with name, host, port, username, and auth method"
- "User can edit an existing SSH profile's fields"
- "User can delete an SSH profile with confirmation"
- "Profile changes persist across app restarts (stored via ConfigManager)"
- "After saving/deleting a profile, the context switcher dropdown reflects the change"
artifacts:
- path: "src/renderer/components/settings/sections/WorkspaceSection.tsx"
provides: "CRUD UI for SSH connection profiles following NotificationTriggerSettings pattern"
min_lines: 100
- path: "src/renderer/components/settings/sections/index.ts"
provides: "Barrel export including WorkspaceSection"
- path: "src/renderer/components/settings/SettingsTabs.tsx"
provides: "New 'workspace' tab option in settings tabs"
- path: "src/renderer/components/settings/SettingsView.tsx"
provides: "WorkspaceSection rendered when workspace tab active"
key_links:
- from: "src/renderer/components/settings/sections/WorkspaceSection.tsx"
to: "window.electronAPI.config"
via: "config.get() reads profiles, config.update('ssh', ...) writes profiles"
pattern: "config\\.get|config\\.update.*ssh"
- from: "src/renderer/components/settings/sections/WorkspaceSection.tsx"
to: "window.electronAPI.context.list"
via: "Refreshes available contexts after profile save/delete"
pattern: "context\\.list|fetchAvailableContexts"
- from: "src/renderer/components/settings/SettingsView.tsx"
to: "src/renderer/components/settings/sections/WorkspaceSection.tsx"
via: "Conditionally renders WorkspaceSection when activeSection === 'workspace'"
pattern: "<WorkspaceSection"
---
<objective>
Create the SSH connection profiles settings section for managing saved workspaces.
Purpose: Users need a persistent way to save, edit, and delete SSH connection profiles so they can reconnect to previously configured remote machines without re-entering credentials. This completes the workspace management story alongside the context switcher from Plan 01.
Output: WorkspaceSection in settings with full CRUD for SSH profiles, integrated into settings tabs, with automatic context list refresh on changes.
</objective>
<execution_context>
@/home/bskim/.claude/get-shit-done/workflows/execute-plan.md
@/home/bskim/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/04-workspace-ui/04-RESEARCH.md
@.planning/phases/04-workspace-ui/04-01-SUMMARY.md
@src/renderer/components/settings/SettingsView.tsx
@src/renderer/components/settings/SettingsTabs.tsx
@src/renderer/components/settings/sections/ConnectionSection.tsx
@src/renderer/components/settings/sections/index.ts
@src/shared/types/api.ts
@src/main/services/infrastructure/ConfigManager.ts
</context>
<tasks>
<task type="auto">
<name>Task 1: Create WorkspaceSection settings component with SSH profile CRUD</name>
<files>
src/renderer/components/settings/sections/WorkspaceSection.tsx
</files>
<action>
Create a settings section following the pattern established by ConnectionSection and NotificationTriggerSettings.
**Imports:**
```typescript
import { useCallback, useEffect, useState } from 'react';
import { useStore } from '@renderer/store';
import { Edit2, Loader2, Plus, Save, Server, Trash2, X } from 'lucide-react';
import { SettingsSectionHeader } from '../components/SettingsSectionHeader';
import type { SshConnectionProfile, SshAuthMethod } from '@shared/types';
```
**State management:**
- `profiles: SshConnectionProfile[]` - loaded from config
- `loading: boolean` - initial load state
- `editingId: string | null` - profile being edited (null = not editing)
- `showAddForm: boolean` - new profile form visibility
- Form state: `formName`, `formHost`, `formPort`, `formUsername`, `formAuthMethod`, `formPrivateKeyPath`
**Profile loading:**
On mount, call `window.electronAPI.config.get()` and extract `config.ssh?.profiles ?? []`. Set into `profiles` state.
Create `loadProfiles` callback that refetches from config and updates state. Call after every CRUD operation.
**Add profile handler:**
- Generate ID: `crypto.randomUUID()` (available in renderer)
- Build profile object: `{ id, name: formName, host: formHost, port: parseInt(formPort) || 22, username: formUsername, authMethod: formAuthMethod, privateKeyPath: formAuthMethod === 'privateKey' ? formPrivateKeyPath : undefined }`
- Save: `await window.electronAPI.config.update('ssh', { profiles: [...profiles, newProfile] })`
- After save: `await loadProfiles()`, reset form, `setShowAddForm(false)`
- After save: `void useStore.getState().fetchAvailableContexts()` to refresh context switcher
**Edit profile handler:**
- Populate form fields from selected profile when `editingId` changes
- Save: Replace profile in array by id, `await window.electronAPI.config.update('ssh', { profiles: updatedProfiles })`
- After save: `await loadProfiles()`, `setEditingId(null)`
- After save: `void useStore.getState().fetchAvailableContexts()`
**Delete profile handler:**
- Filter profile out: `profiles.filter(p => p.id !== id)`
- Save: `await window.electronAPI.config.update('ssh', { profiles: filtered })`
- After delete: `await loadProfiles()`
- After delete: `void useStore.getState().fetchAvailableContexts()`
**UI Structure:**
```
SettingsSectionHeader title="Workspace Profiles"
Description text: "Save SSH connection profiles for quick reconnection"
{loading && Loader2 spinner}
{!loading && profiles.length === 0 && empty state message}
{profiles.map(profile => (
ProfileCard:
- If editingId === profile.id: render inline edit form
- Else: render display card with:
- Server icon + profile.name (bold)
- profile.username@profile.host:profile.port (muted text)
- Auth method badge (muted)
- Edit button (Edit2 icon)
- Delete button (Trash2 icon, confirm with window.confirm())
))}
{showAddForm ? (
Add Profile Form:
- Name input (required)
- Host input (required)
- Port input (default 22)
- Username input (required)
- Auth method select (auto/agent/privateKey/password)
- Private key path input (conditional on authMethod === 'privateKey')
- Save button + Cancel button
) : (
Add Profile button (Plus icon)
)}
```
**Styling:**
- Use `var(--color-surface-raised)` for card backgrounds
- Use `var(--color-border)` for card borders
- Use `var(--color-text)`, `var(--color-text-secondary)`, `var(--color-text-muted)` for text hierarchy
- Input styling: same as ConnectionSection (`inputClass` and `inputStyle` pattern)
- Buttons: same styling as ConnectionSection action buttons
- Cards: `rounded-md border p-4 space-y-2` with surface-raised background
</action>
<verify>
Run `pnpm typecheck` - zero errors. Verify WorkspaceSection.tsx exists and exports the component. Confirm it imports SshConnectionProfile from shared types.
</verify>
<done>
WorkspaceSection renders a list of saved SSH profiles with add/edit/delete functionality. Profile changes are persisted via ConfigManager and trigger context list refresh. Component follows existing settings patterns.
</done>
</task>
<task type="auto">
<name>Task 2: Wire WorkspaceSection into SettingsView and SettingsTabs</name>
<files>
src/renderer/components/settings/sections/index.ts
src/renderer/components/settings/SettingsTabs.tsx
src/renderer/components/settings/SettingsView.tsx
</files>
<action>
**1. Update sections/index.ts barrel export:**
Add: `export { WorkspaceSection } from './WorkspaceSection';`
**2. Update SettingsTabs.tsx:**
Add `'workspace'` to the `SettingsSection` type:
```typescript
export type SettingsSection = 'general' | 'connection' | 'workspace' | 'notifications' | 'advanced';
```
Add workspace tab to the `tabs` array, positioned after 'connection':
```typescript
{ id: 'workspace', label: 'Workspaces', icon: Server },
```
Import `Server` from lucide-react (it may already be imported - check first, do not duplicate).
The tabs array order should be: general, connection, workspace, notifications, advanced.
**3. Update SettingsView.tsx:**
Import `WorkspaceSection` from the sections barrel:
```typescript
import {
AdvancedSection,
ConnectionSection,
GeneralSection,
NotificationsSection,
WorkspaceSection,
} from './sections';
```
Add the workspace section render block in the content area, between connection and notifications:
```tsx
{activeSection === 'workspace' && <WorkspaceSection />}
```
The component takes no props (it manages its own state internally, similar to ConnectionSection).
</action>
<verify>
Run `pnpm typecheck` - zero errors. Run `pnpm test` - all tests pass. Run `pnpm build` - production build succeeds. Verify SettingsTabs includes 'workspace' option. Verify SettingsView renders WorkspaceSection when workspace tab is active.
</verify>
<done>
Settings view has a "Workspaces" tab showing SSH profile management. Tab sits between Connection and Notifications in the tab bar. The full CRUD flow works: add profile -> appears in list -> edit fields -> save -> delete with confirm. Profile changes refresh context switcher dropdown automatically.
</done>
</task>
</tasks>
<verification>
1. `pnpm typecheck` passes with zero errors
2. `pnpm test` passes with no regressions
3. `pnpm build` succeeds
4. WorkspaceSection.tsx exists with CRUD operations for SSH profiles
5. SettingsTabs.tsx includes 'workspace' in SettingsSection type
6. SettingsView.tsx renders WorkspaceSection when workspace tab is active
7. sections/index.ts exports WorkspaceSection
8. Profile add/edit/delete calls config.update('ssh', ...) and fetchAvailableContexts()
</verification>
<success_criteria>
- "Workspaces" tab visible in settings between Connection and Notifications
- Empty state shown when no profiles saved
- User can add SSH profile with name, host, port, username, auth method
- User can inline-edit existing profile fields
- User can delete profile with confirmation dialog
- Profile changes persist via ConfigManager (survive app restart)
- After any profile change, context switcher dropdown refreshes automatically
</success_criteria>
<output>
After completion, create `.planning/phases/04-workspace-ui/04-02-SUMMARY.md`
</output>

110
.planning/phases/04-workspace-ui/04-02-SUMMARY.md
View file

@ -1,110 +0,0 @@
---
phase: 04-workspace-ui
plan: 02
subsystem: ui
tags: [react, zustand, settings, ssh-profiles, crud]
requires:
- phase: 04-workspace-ui
provides: ContextSwitcher, ConnectionStatusBadge, fetchAvailableContexts action
- phase: 02-service-infrastructure
provides: ConfigManager with SSH profile persistence, config.update('ssh', ...) IPC
provides:
- WorkspaceSection settings component with full SSH profile CRUD
- Workspaces tab in settings between Connection and Notifications
- Automatic context list refresh after profile add/edit/delete
affects: []
tech-stack:
added: []
patterns: [settings-section-self-contained-state-pattern]
key-files:
created:
- src/renderer/components/settings/sections/WorkspaceSection.tsx
modified:
- src/renderer/components/settings/sections/index.ts
- src/renderer/components/settings/SettingsTabs.tsx
- src/renderer/components/settings/SettingsView.tsx
key-decisions:
- "Used HardDrive icon for Workspaces tab to differentiate from Server icon used by Connection tab"
- "WorkspaceSection manages own state internally (no props), matching ConnectionSection pattern"
- "AppConfig type cast via unknown for ssh field access since AppConfig interface lacks ssh property"
patterns-established:
- "Self-contained settings section: loads config on mount, manages form state internally, persists via config.update()"
duration: 4min
completed: 2026-02-12
---
# Plan 04-02: Workspace Settings Summary
**WorkspaceSection with SSH profile CRUD in settings, auto-refreshing context switcher on profile changes**
## Performance
- **Duration:** 4 min
- **Started:** 2026-02-12T04:39:09Z
- **Completed:** 2026-02-12T04:43:23Z
- **Tasks:** 2
- **Files modified:** 4
## Accomplishments
- Full CRUD UI for SSH connection profiles (add, inline edit, delete with confirmation)
- Workspaces tab in settings positioned between Connection and Notifications
- Profile changes automatically refresh context switcher dropdown via fetchAvailableContexts()
- Empty state with server icon when no profiles are saved
## Task Commits
1. **Task 1: Create WorkspaceSection settings component with SSH profile CRUD** - `8b9132e` (feat)
2. **Task 2: Wire WorkspaceSection into SettingsView and SettingsTabs** - `d00940d` (feat)
## Files Created/Modified
- `src/renderer/components/settings/sections/WorkspaceSection.tsx` - CRUD UI for SSH profiles with form state, config persistence, context refresh
- `src/renderer/components/settings/sections/index.ts` - Added WorkspaceSection barrel export
- `src/renderer/components/settings/SettingsTabs.tsx` - Added 'workspace' to SettingsSection type, HardDrive icon tab
- `src/renderer/components/settings/SettingsView.tsx` - Renders WorkspaceSection when workspace tab active
## Decisions Made
- Used HardDrive icon for Workspaces tab (Server already used by Connection)
- WorkspaceSection manages own state (no props from SettingsView), same as ConnectionSection
- Used `config as unknown as { ssh?: ... }` cast since AppConfig interface doesn't declare ssh field
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 1 - Bug] Fixed AppConfig type cast for SSH field access**
- **Found during:** Task 1 (WorkspaceSection component creation)
- **Issue:** Plan specified `(config as Record<string, unknown>).ssh` but TypeScript rejected this cast because AppConfig and Record<string, unknown> don't overlap
- **Fix:** Used double cast via `unknown`: `(config as unknown as { ssh?: { profiles?: SshConnectionProfile[] } }).ssh`
- **Files modified:** src/renderer/components/settings/sections/WorkspaceSection.tsx
- **Verification:** pnpm typecheck passes with zero errors
- **Committed in:** 8b9132e (Task 1 commit)
---
**Total deviations:** 1 auto-fixed (1 bug)
**Impact on plan:** Trivial type cast fix for correctness. No scope creep.
## Issues Encountered
None
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- Phase 04 (Workspace UI) is now complete with both plans finished
- Context switcher (04-01) and workspace settings (04-02) are fully wired
- End-to-end SSH workflow: save profile in settings, see it in context switcher, switch contexts
## Self-Check: PASSED
All files verified present. All commits verified in git log.
---
*Phase: 04-workspace-ui*
*Completed: 2026-02-12*

463
.planning/phases/04-workspace-ui/04-RESEARCH.md
View file

@ -1,463 +0,0 @@
# Phase 4: Workspace UI - Research
**Researched:** 2026-02-12
**Domain:** React UI components, Electron desktop patterns, workspace/connection management UI
**Confidence:** HIGH
## Summary
Phase 4 delivers the final UI layer for workspace switching, building on Phases 1-3's infrastructure. The core challenge is creating an intuitive workspace switcher and persistent status indicators that integrate seamlessly with the existing sidebar-based layout without disrupting established patterns.
**Key findings:**
- Existing codebase already has dropdown/selector patterns to follow (SidebarHeader project/worktree selectors, CommandPalette, SettingsSelect)
- VS Code model places workspace indicators on left side of status bar; this app lacks a traditional status bar but has SidebarHeader
- Keyboard shortcuts use Cmd/Ctrl+K pattern already (CommandPalette); context switching could use Cmd/Ctrl+Shift+K or similar to avoid collision
- Connection states need distinct visual treatment: connected (green), connecting (spinner), disconnected (neutral), error (red)
- SSH profiles already stored in ConfigManager; settings UI needs CRUD interface following existing NotificationTriggerSettings pattern
**Primary recommendation:** Place context switcher in SidebarHeader Row 1 (alongside project name), add connection status badge next to switcher, implement settings section for SSH profile management, register Cmd/Ctrl+Shift+K shortcut for quick switching.
## Standard Stack
### Core
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| React 18.x | 18.x | UI framework | Already used throughout codebase |
| Zustand 4.x | 4.x | State management | Already used for contextSlice, connectionSlice |
| Tailwind CSS 3.x | 3.x | Styling | Theme-aware CSS variables already established |
| lucide-react | latest | Icons | Consistent with existing icon usage |
### Supporting
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| date-fns | latest | Date formatting | Already used in CommandPalette for "last active" display |
### Alternatives Considered
| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| Custom dropdown | Headless UI Listbox | Headless UI adds dependency but provides accessibility features. Codebase already has working custom dropdowns (SidebarHeader, SettingsSelect) — stick with existing patterns for consistency. |
| Custom dropdown | Radix UI Dropdown Menu | Radix provides ARIA-compliant primitives with collision detection. Same tradeoff as Headless UI — codebase patterns work well, adding library introduces dependency for marginal benefit. |
**Installation:**
```bash
# No new dependencies needed - use existing stack
```
## Architecture Patterns
### Recommended Project Structure
```
src/renderer/components/
├── common/
│ ├── ContextSwitcher.tsx # Main switcher component
│ ├── ContextSwitchOverlay.tsx # Already exists
│ └── ConnectionStatusBadge.tsx # Status indicator
├── layout/
│ └── SidebarHeader.tsx # Modified to include switcher
├── settings/
│ └── sections/
│ └── WorkspaceSection.tsx # SSH profile management
```
### Pattern 1: Context Switcher Component
**What:** Dropdown component listing Local + all SSH contexts, with connection status indicators and keyboard navigation.
**When to use:** Embedded in SidebarHeader Row 1 alongside project name.
**Example:**
```typescript
// Based on existing SidebarHeader dropdown pattern
interface ContextSwitcherProps {
activeContextId: string;
onSwitch: (contextId: string) => void;
}
export const ContextSwitcher: React.FC<ContextSwitcherProps> = ({
activeContextId,
onSwitch
}) => {
const [isOpen, setIsOpen] = useState(false);
const dropdownRef = useRef<HTMLDivElement>(null);
// Close on outside click (same pattern as SidebarHeader)
useEffect(() => {
const handleClickOutside = (e: MouseEvent) => {
if (dropdownRef.current && !dropdownRef.current.contains(e.target as Node)) {
setIsOpen(false);
}
};
document.addEventListener('mousedown', handleClickOutside);
return () => document.removeEventListener('mousedown', handleClickOutside);
}, []);
// Close on escape (same pattern as SidebarHeader)
useEffect(() => {
const handleEscape = (e: KeyboardEvent) => {
if (e.key === 'Escape') setIsOpen(false);
};
document.addEventListener('keydown', handleEscape);
return () => document.removeEventListener('keydown', handleEscape);
}, []);
const contexts = useStore((s) => s.availableContexts); // From contextSlice
return (
<div ref={dropdownRef} className="relative">
<button onClick={() => setIsOpen(!isOpen)}>
<ConnectionStatusBadge contextId={activeContextId} />
<span>{activeContextId === 'local' ? 'Local' : activeContextId.replace('ssh-', '')}</span>
<ChevronDown className={isOpen ? 'rotate-180' : ''} />
</button>
{isOpen && (
<div className="absolute dropdown-menu">
{contexts.map(ctx => (
<button
key={ctx.id}
onClick={() => { onSwitch(ctx.id); setIsOpen(false); }}
>
{ctx.type === 'local' ? 'Local' : ctx.id.replace('ssh-', '')}
{ctx.id === activeContextId && <Check />}
</button>
))}
</div>
)}
</div>
);
};
```
### Pattern 2: Connection Status Badge
**What:** Visual indicator showing connection state with distinct colors/icons.
**When to use:** Always visible next to active context name.
**Example:**
```typescript
// Similar to OngoingIndicator pattern
type ConnectionState = 'connected' | 'connecting' | 'disconnected' | 'error';
export const ConnectionStatusBadge: React.FC<{ contextId: string }> = ({
contextId
}) => {
const state = useStore((s) =>
contextId === 'local'
? 'connected'
: s.connectionState
);
if (contextId === 'local') {
return <Monitor className="size-4 text-text-muted" />;
}
// SSH context
switch (state) {
case 'connected':
return <Wifi className="size-4 text-green-400" />;
case 'connecting':
return <Loader2 className="size-4 animate-spin text-text-muted" />;
case 'disconnected':
return <WifiOff className="size-4 text-text-muted" />;
case 'error':
return <WifiOff className="size-4 text-red-400" />;
}
};
```
### Pattern 3: SSH Profile Management Settings Section
**What:** Settings section for creating, editing, deleting SSH connection profiles.
**When to use:** Settings view under new "Workspace" tab.
**Example:**
```typescript
// Follow NotificationTriggerSettings pattern
export const WorkspaceSection: React.FC = () => {
const [profiles, setProfiles] = useState<SshConnectionProfile[]>([]);
const [editingProfile, setEditingProfile] = useState<string | null>(null);
// CRUD operations via ConfigManager IPC
const handleAddProfile = async (profile: Omit<SshConnectionProfile, 'id'>) => {
await window.electronAPI.config.update('ssh', {
profiles: [...profiles, { ...profile, id: generateId() }]
});
await loadProfiles();
};
const handleEditProfile = async (id: string, updates: Partial<SshConnectionProfile>) => {
// Update via ConfigManager
};
const handleDeleteProfile = async (id: string) => {
// Delete via ConfigManager
};
return (
<div className="space-y-6">
<SettingsSectionHeader title="SSH Connection Profiles" />
{profiles.map(profile => (
<ProfileCard
key={profile.id}
profile={profile}
onEdit={handleEditProfile}
onDelete={handleDeleteProfile}
/>
))}
<AddProfileForm onSubmit={handleAddProfile} />
</div>
);
};
```
### Pattern 4: Keyboard Shortcut Registration
**What:** Register Cmd/Ctrl+Shift+K for quick context switching.
**When to use:** Registered in useKeyboardShortcuts hook.
**Example:**
```typescript
// Add to useKeyboardShortcuts.ts
if (event.key === 'k' && event.shiftKey) {
event.preventDefault();
// Open context switcher dropdown or cycle to next context
const currentIndex = contexts.findIndex(c => c.id === activeContextId);
const nextContext = contexts[(currentIndex + 1) % contexts.length];
void switchContext(nextContext.id);
return;
}
```
### Anti-Patterns to Avoid
- **Don't add status bar component**: App uses sidebar-centric layout (not bottom status bar like VS Code). Place indicators in SidebarHeader instead.
- **Don't block UI during switch**: ContextSwitchOverlay already exists for loading state — use it, don't create inline spinners that block interaction.
- **Don't duplicate connection state**: connectionSlice and contextSlice both track state — contextSlice owns activeContextId, connectionSlice owns SSH connection state. Don't mix concerns.
## Don't Hand-Roll
| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Dropdown accessibility (focus trap, escape, arrow navigation) | Custom keyboard handler | Follow existing SidebarHeader pattern | Codebase already has working dropdown with keyboard support. Headless UI/Radix would add dependency for marginal benefit. |
| Context switch animation | Custom fade/slide | ContextSwitchOverlay (already exists) | Overlay prevents stale data flash during transition. Don't reinvent. |
| SSH config parsing | Custom parser | Use main process SshConnectionManager (already exists) | Main process already resolves SSH config hosts via `ssh.getConfigHosts()` IPC. |
| Profile persistence | IndexedDB or localStorage | ConfigManager (already exists) | SSH profiles already stored in config.json via ConfigManager. Don't create separate storage. |
**Key insight:** This phase is primarily UI composition, not new infrastructure. Almost all backend logic exists from Phases 1-3. Focus on clean UI patterns that match existing components.
## Common Pitfalls
### Pitfall 1: Dropdown Positioning Conflict with macOS Traffic Lights
**What goes wrong:** Context switcher dropdown placed too close to window edge overlaps with macOS traffic lights (close/minimize/zoom buttons).
**Why it happens:** SidebarHeader Row 1 uses `--macos-traffic-light-padding-left` to avoid traffic lights, but dropdown menu anchoring doesn't account for this.
**How to avoid:** Use `inset-x-4` (same as SidebarHeader project dropdown) to ensure dropdown stays within safe area. See SidebarHeader.tsx line 381.
**Warning signs:** Dropdown menu appears behind or overlapping traffic lights on macOS.
### Pitfall 2: Context Switch State Race Condition
**What goes wrong:** User rapidly clicks between contexts, causing stale state to be restored.
**Why it happens:** contextSlice.switchContext is async; second click can start before first completes.
**How to avoid:** Disable switcher UI while `isContextSwitching` is true. Add guard in switchContext to early-return if already switching.
**Warning signs:** Console errors about "Cannot read property of undefined" after rapid switching; snapshot restore fails validation.
### Pitfall 3: SSH Connection Status Not Updating in UI
**What goes wrong:** Connection state changes in main process but UI shows stale "connecting" state.
**Why it happens:** IPC event listener not registered or cleaned up improperly.
**How to avoid:** Register `ssh.onStatus` listener in App.tsx alongside notification listeners. Update connectionSlice state on event. Clean up listener on unmount.
**Warning signs:** Status badge stuck on spinner; requires app restart to update.
### Pitfall 4: Settings Section Doesn't Reflect Profile Changes
**What goes wrong:** User adds SSH profile in settings but it doesn't appear in context switcher.
**Why it happens:** Settings section modifies ConfigManager, but contextSlice doesn't refetch available contexts.
**How to avoid:** After profile save, call `context.list()` IPC to refresh available contexts. Or: add `config.onUpdated` listener in contextSlice to auto-refresh when ssh.profiles changes.
**Warning signs:** Profile appears in settings but not in switcher dropdown until app restart.
### Pitfall 5: Keyboard Shortcut Collision with Existing Shortcuts
**What goes wrong:** Cmd+K already opens CommandPalette; using it for context switch breaks search.
**Why it happens:** useKeyboardShortcuts processes shortcuts in order; first match wins.
**How to avoid:** Use Cmd+Shift+K (or Cmd+Option+K) for context switching. Document in UI (tooltip, settings help text).
**Warning signs:** CommandPalette no longer opens on Cmd+K after adding context switch shortcut.
## Code Examples
Verified patterns from codebase:
### Dropdown Component Pattern (from SidebarHeader.tsx)
```typescript
// Source: src/renderer/components/layout/SidebarHeader.tsx lines 236-295
const [isDropdownOpen, setIsDropdownOpen] = useState(false);
const dropdownRef = useRef<HTMLDivElement>(null);
// Close dropdowns on outside click
useEffect(() => {
function handleClickOutside(event: MouseEvent): void {
if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
setIsDropdownOpen(false);
}
}
document.addEventListener('mousedown', handleClickOutside);
return () => document.removeEventListener('mousedown', handleClickOutside);
}, []);
// Close on escape
useEffect(() => {
function handleEscape(event: KeyboardEvent): void {
if (event.key === 'Escape') {
setIsDropdownOpen(false);
}
}
document.addEventListener('keydown', handleEscape);
return () => document.removeEventListener('keydown', handleEscape);
}, []);
```
### Connection Status Indicator Pattern (from ConnectionSection.tsx)
```typescript
// Source: src/renderer/components/settings/sections/ConnectionSection.tsx lines 150-178
{isConnected && (
<div
className="flex items-center gap-3 rounded-md border px-4 py-3"
style={{
borderColor: 'rgba(34, 197, 94, 0.3)',
backgroundColor: 'rgba(34, 197, 94, 0.05)',
}}
>
<Wifi className="size-4 text-green-400" />
<div className="flex-1">
<p className="text-sm font-medium" style={{ color: 'var(--color-text)' }}>
Connected to {connectedHost}
</p>
<p className="text-xs" style={{ color: 'var(--color-text-muted)' }}>
Viewing remote sessions via SSH
</p>
</div>
</div>
)}
```
### Keyboard Shortcut Pattern (from useKeyboardShortcuts.ts)
```typescript
// Source: src/renderer/hooks/useKeyboardShortcuts.ts lines 68-97
useEffect(() => {
function handleKeyDown(event: KeyboardEvent): void {
const isMod = event.metaKey || event.ctrlKey;
if (!isMod) return;
// Cmd+K: Open command palette
if (event.key === 'k') {
event.preventDefault();
openCommandPalette();
return;
}
// Add context switcher shortcut here
// Cmd+Shift+K: Open context switcher or cycle contexts
if (event.key === 'k' && event.shiftKey) {
event.preventDefault();
// Implementation here
return;
}
}
window.addEventListener('keydown', handleKeyDown);
return () => window.removeEventListener('keydown', handleKeyDown);
}, [dependencies]);
```
### IPC Event Listener Pattern (from App.tsx and store initialization)
```typescript
// Source: src/renderer/App.tsx lines 22-31
// Initialize IPC event listeners (notifications, file changes)
useEffect(() => {
const cleanup = initializeNotificationListeners();
return cleanup;
}, []);
// Add SSH status listener similarly
useEffect(() => {
const unsubscribe = window.electronAPI.ssh.onStatus((event, status) => {
useStore.getState().setConnectionStatus(
status.state,
status.host,
status.error
);
});
return unsubscribe;
}, []);
```
### Settings CRUD Pattern (from NotificationTriggerSettings)
```typescript
// Source: src/renderer/components/settings/NotificationTriggerSettings/index.tsx
const handleAddProfile = async (profile: Omit<SshConnectionProfile, 'id'>) => {
const newProfile = { ...profile, id: generateId() };
await window.electronAPI.config.update('ssh', {
profiles: [...profiles, newProfile]
});
await loadProfiles(); // Refetch from config
};
const handleDeleteProfile = async (id: string) => {
await window.electronAPI.config.update('ssh', {
profiles: profiles.filter(p => p.id !== id)
});
await loadProfiles();
};
```
## State of the Art
| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| Manual SSH connection in terminal, copy session files | In-app SSH connection with file watcher | Phase 2 (completed) | Users can now connect to remote machines without leaving app |
| No workspace concept, single active project | Multi-workspace with snapshot/restore | Phase 3 (completed) | Users can switch between local and remote without losing UI state |
| Status indicators only in settings view | Persistent status in sidebar/status bar | This phase (04) | Users always know which workspace is active without navigating to settings |
**Deprecated/outdated:**
- N/A — This is a greenfield feature building on new infrastructure.
## Open Questions
1. **Context switcher placement in SidebarHeader Row 1**
- What we know: Row 1 has project name (left) and collapse button (right). Project name is clickable dropdown.
- What's unclear: Should context switcher be separate button left of project name, or integrated into project dropdown?
- Recommendation: Separate button left of project name (before traffic light padding). This keeps "where am I" (workspace) distinct from "what am I viewing" (project). VS Code model supports this (Remote indicator is separate from workspace name).
2. **Keyboard shortcut choice**
- What we know: Cmd+K is CommandPalette. Requirements specify "Cmd/Ctrl+K or similar" for switching.
- What's unclear: Should Cmd+Shift+K open switcher dropdown, or directly cycle to next context?
- Recommendation: Cmd+Shift+K cycles to next context (faster for power users with 2-3 contexts). Cmd+Option+K opens dropdown (for users with many SSH profiles). Document both.
3. **SSH profile quick-connect in switcher**
- What we know: SSH profiles stored in config can be saved/edited/deleted in settings.
- What's unclear: Should context switcher dropdown show saved profiles (allowing one-click connect), or only show currently active contexts?
- Recommendation: Show active contexts only (Local + currently connected SSH). Use settings section for profile management and initial connection. This keeps switcher simple (switch between established contexts) vs. connection manager (complex).
4. **Connection failure handling in switcher**
- What we know: Switching to SSH context can fail (network error, auth failure).
- What's unclear: Should switcher show error inline, or defer to toast notification?
- Recommendation: Show inline error in dropdown (similar to ConnectionSection error display lines 180-184). User attempted action in switcher, error should appear there. Toast would be easy to miss.
## Sources
### Primary (HIGH confidence)
- Existing codebase patterns:
- `/home/bskim/claude-devtools/src/renderer/components/layout/SidebarHeader.tsx` - Dropdown pattern, macOS traffic light handling
- `/home/bskim/claude-devtools/src/renderer/components/settings/sections/ConnectionSection.tsx` - Connection status display, SSH config
- `/home/bskim/claude-devtools/src/renderer/hooks/useKeyboardShortcuts.ts` - Keyboard shortcut registration pattern
- `/home/bskim/claude-devtools/src/renderer/components/common/ContextSwitchOverlay.tsx` - Context switching overlay (already implemented)
- `/home/bskim/claude-devtools/src/renderer/store/slices/contextSlice.ts` - Context switching state management
- `/home/bskim/claude-devtools/src/renderer/store/slices/connectionSlice.ts` - SSH connection state management
### Secondary (MEDIUM confidence)
- [VS Code Status Bar UX Guidelines](https://code.visualstudio.com/api/ux-guidelines/status-bar) - Official VS Code extension API docs specifying status bar item placement (workspace items on left)
- [Electron Keyboard Shortcuts Documentation](https://www.electronjs.org/docs/latest/tutorial/keyboard-shortcuts) - Official Electron docs for keyboard shortcut implementation
- [Headless UI Listbox Documentation](https://headlessui.com/react/listbox) - Keyboard navigation and accessibility patterns for dropdowns
- [Radix UI Dropdown Menu Documentation](https://www.radix-ui.com/primitives/docs/components/dropdown-menu) - WAI-ARIA compliant dropdown patterns
- [DoltHub: Building a Custom Title Bar in Electron](https://www.dolthub.com/blog/2025-02-11-building-a-custom-title-bar-in-electron/) - Recent (Feb 2025) article on Electron title bar patterns with dropdowns
### Tertiary (LOW confidence)
- N/A — No unverified claims requiring low-confidence flagging.
## Metadata
**Confidence breakdown:**
- Standard stack: HIGH - All libraries already in use, verified in package.json and codebase
- Architecture patterns: HIGH - Patterns extracted directly from existing components (SidebarHeader, ConnectionSection, useKeyboardShortcuts)
- Don't hand-roll recommendations: HIGH - Based on existing infrastructure from Phases 1-3
- Pitfalls: MEDIUM-HIGH - Based on common React/Electron patterns and analysis of existing code; actual pitfalls will emerge during implementation
**Research date:** 2026-02-12
**Valid until:** ~30 days (March 2026) - UI patterns are stable, but Electron/React ecosystem updates could introduce new best practices

580
.planning/research/ARCHITECTURE.md
View file

@ -1,580 +0,0 @@
# Architecture Research: Multi-Context Workspace System
**Domain:** Electron application with multi-context workspace switching
**Researched:** 2026-02-12
**Confidence:** MEDIUM
## Standard Architecture
### System Overview
```
┌───────────────────────────────────────────────────────────────────────┐
│ Main Process (Node.js) │
├───────────────────────────────────────────────────────────────────────┤
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ ServiceContextRegistry (NEW) │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ LocalContext │ │ SshContext │ │ SshContext │ │ │
│ │ │ (always) │ │ (Host A) │ │ (Host B) │ │ │
│ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │
│ │ │ │ │ │ │
│ │ ┌────▼──────────────────▼──────────────────▼───────┐ │ │
│ │ │ Services (per context) │ │ │
│ │ │ - ProjectScanner │ │ │
│ │ │ - SessionParser │ │ │
│ │ │ - SubagentResolver │ │ │
│ │ │ - ChunkBuilder (shared) │ │ │
│ │ │ - DataCache (per context) │ │ │
│ │ │ - FileWatcher (per context) │ │ │
│ │ └──────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────────▼───────────────────────────────┐ │
│ │ IPC Bridge (via preload) │ │
│ │ - getCurrentContext() │ │
│ │ - switchContext(contextId) │ │
│ │ - getContextSnapshot(contextId) │ │
│ │ - listContexts() │ │
│ └────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────┬────────────────────────────────────┘
│ IPC
┌──────────────────────────────────▼────────────────────────────────────┐
│ Renderer Process (Chromium) │
├───────────────────────────────────────────────────────────────────────┤
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ ContextSwitcher (NEW) │ │
│ │ - Manages active context ID │ │
│ │ - Coordinates switch flow │ │
│ │ - Updates connection slice │ │
│ └───────────────────────────────┬────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────────▼────────────────────────────────┐ │
│ │ Zustand Store (with snapshots) │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────────────┐ │ │
│ │ │ Current State (active context) │ │ │
│ │ │ - projects, sessions, selectedProjectId, etc. │ │ │
│ │ └────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────────────┐ │ │
│ │ │ contextSnapshots: Map<contextId, StateSnapshot> │ │ │
│ │ │ - Stores full state per context for instant restore │ │ │
│ │ └────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────────▼────────────────────────────────┐ │
│ │ React Components │ │
│ │ - ContextSwitcher UI (dropdown/sidebar) │ │
│ │ - Dashboard (context-aware) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────┘
```
### Component Responsibilities
| Component | Responsibility | Typical Implementation |
|-----------|----------------|------------------------|
| **ServiceContextRegistry** | Manages multiple service contexts (local + N SSH), lifecycle, and active context switching | Map of contextId → ServiceContext objects, provides getActive(), switch(), register() |
| **ServiceContext** | Encapsulates service instances and FileSystemProvider for one context | Holds ProjectScanner, SessionParser, SubagentResolver, DataCache, FileWatcher, fsProvider |
| **ContextSwitcher** (renderer) | Orchestrates context switches from renderer side, manages UI state | Calls IPC to switch, captures/restores snapshots, updates Zustand |
| **StateSnapshot** | Frozen copy of renderer state for a context | Full or partial state (projects, sessions, selections, UI state) |
| **IPC Context Handlers** | Exposes context management to renderer | getCurrentContext, switchContext, getContextSnapshot, listContexts |
## Recommended Project Structure
```
src/
├── main/
│ ├── services/
│ │ ├── infrastructure/
│ │ │ ├── ServiceContext.ts # NEW: Encapsulates services for one context
│ │ │ ├── ServiceContextRegistry.ts # NEW: Manages all contexts
│ │ │ └── ContextLifecycleManager.ts # NEW: Start/stop context services
│ │ └── ... (existing services)
│ ├── ipc/
│ │ └── context.ts # NEW: Context switching IPC handlers
│ └── index.ts # Modified: Initialize registry
├── renderer/
│ ├── store/
│ │ ├── slices/
│ │ │ ├── contextSlice.ts # NEW: Context management state
│ │ │ └── connectionSlice.ts # Modified: Works with contextSlice
│ │ └── utils/
│ │ └── stateSnapshot.ts # NEW: Snapshot capture/restore
│ ├── components/
│ │ └── common/
│ │ └── ContextSwitcher.tsx # NEW: Context switcher UI
│ └── hooks/
│ └── useContextSwitch.ts # NEW: Hook for switching contexts
└── shared/
└── types/
└── context.ts # NEW: Context-related types
```
### Structure Rationale
- **ServiceContextRegistry** in infrastructure: Central registry pattern, manages context lifecycle
- **ServiceContext** wraps all service instances: Clean isolation boundary, easy to create/destroy
- **ContextSlice** separate from connectionSlice: Context is broader than SSH (could add Docker, WSL, etc. later)
- **State snapshots** in store utils: Serialize/deserialize state for instant restore
- **IPC context handlers** in dedicated file: Clear separation of concerns from existing SSH handlers
## Architectural Patterns
### Pattern 1: Service Context Registry
**What:** Central registry that manages multiple isolated service contexts, each with its own FileSystemProvider and service instances.
**When to use:** When you need to support multiple data sources (local, SSH hosts, containers) without tearing down/recreating all services on every switch.
**Trade-offs:**
- **Pros:**
- Local context stays alive (critical for notifications, config)
- Instant switching between known contexts
- Clear isolation boundaries
- Easy to add new context types (Docker, WSL, etc.)
- **Cons:**
- Memory overhead (multiple service sets in memory)
- Complexity of managing context lifecycle
- Need to handle cross-context data requests carefully
**Example:**
```typescript
// ServiceContext.ts
export interface ServiceContext {
id: string;
type: 'local' | 'ssh';
label: string; // "Local" or "user@hostname"
// Service instances
projectScanner: ProjectScanner;
sessionParser: SessionParser;
subagentResolver: SubagentResolver;
dataCache: DataCache;
fileWatcher: FileWatcher;
// Provider
fsProvider: FileSystemProvider;
// Lifecycle
isActive: boolean;
createdAt: Date;
lastAccessedAt: Date;
}
// ServiceContextRegistry.ts
export class ServiceContextRegistry {
private contexts = new Map<string, ServiceContext>();
private activeContextId: string = 'local';
constructor() {
// Always initialize local context
this.registerLocalContext();
}
register(context: ServiceContext): void {
this.contexts.set(context.id, context);
}
getActive(): ServiceContext {
return this.contexts.get(this.activeContextId)!;
}
async switch(contextId: string): Promise<ServiceContext> {
const context = this.contexts.get(contextId);
if (!context) throw new Error(`Context ${contextId} not found`);
// Pause current context's watchers
const current = this.getActive();
current.fileWatcher.stop();
current.isActive = false;
// Activate new context
context.isActive = true;
context.lastAccessedAt = new Date();
context.fileWatcher.start();
this.activeContextId = contextId;
return context;
}
list(): ServiceContext[] {
return Array.from(this.contexts.values());
}
async createSshContext(
host: string,
sshManager: SshConnectionManager
): Promise<ServiceContext> {
// Create services with SSH provider
const provider = sshManager.getProvider();
const projectsDir = sshManager.getRemoteProjectsPath()!;
const context: ServiceContext = {
id: `ssh:${host}`,
type: 'ssh',
label: host,
projectScanner: new ProjectScanner(projectsDir, undefined, provider),
sessionParser: new SessionParser(/* ... */),
subagentResolver: new SubagentResolver(/* ... */),
dataCache: new DataCache(MAX_CACHE_SESSIONS, CACHE_TTL_MINUTES),
fileWatcher: new FileWatcher(/* ... */),
fsProvider: provider,
isActive: false,
createdAt: new Date(),
lastAccessedAt: new Date(),
};
this.register(context);
return context;
}
}
```
### Pattern 2: State Snapshot with Instant Restore
**What:** Capture full renderer state for each context and restore it instantly on switch, avoiding re-fetching from main process.
**When to use:** When you need instant (<50ms) context switching and want to preserve user's navigation/selection state per context.
**Trade-offs:**
- **Pros:**
- Instant perceived switching (no loading states)
- Preserves user's place in each context (selected project, open tabs, scroll position)
- Reduces IPC round-trips
- **Cons:**
- Memory overhead in renderer (full state × N contexts)
- Snapshot can become stale (need expiration/refresh strategy)
- Need to handle snapshot compatibility across app versions
**Example:**
```typescript
// stateSnapshot.ts
export interface StateSnapshot {
contextId: string;
capturedAt: Date;
expiresAt: Date; // Auto-refresh if older than 5 minutes
// Core data
projects: Project[];
sessions: Session[];
repositoryGroups: RepositoryGroup[];
// Selections
selectedProjectId: string | null;
selectedSessionId: string | null;
// UI state
tabs: Tab[];
activeTabId: string | null;
paneLayout: PaneLayout;
// Metadata
version: string; // App version for compatibility check
}
export function captureSnapshot(state: AppState, contextId: string): StateSnapshot {
return {
contextId,
capturedAt: new Date(),
expiresAt: new Date(Date.now() + 5 * 60 * 1000), // 5 min
projects: state.projects,
sessions: state.sessions,
repositoryGroups: state.repositoryGroups,
selectedProjectId: state.selectedProjectId,
selectedSessionId: state.selectedSessionId,
tabs: state.tabs,
activeTabId: state.activeTabId,
paneLayout: state.paneLayout,
version: state.appVersion,
};
}
export function restoreSnapshot(snapshot: StateSnapshot): Partial<AppState> {
// Check if snapshot is stale
if (new Date() > snapshot.expiresAt) {
// Return only UI state, let data re-fetch
return {
tabs: snapshot.tabs,
activeTabId: snapshot.activeTabId,
paneLayout: snapshot.paneLayout,
};
}
// Restore full state
return {
projects: snapshot.projects,
sessions: snapshot.sessions,
repositoryGroups: snapshot.repositoryGroups,
selectedProjectId: snapshot.selectedProjectId,
selectedSessionId: snapshot.selectedSessionId,
tabs: snapshot.tabs,
activeTabId: snapshot.activeTabId,
paneLayout: snapshot.paneLayout,
};
}
```
### Pattern 3: IPC Handler Re-Routing
**What:** IPC handlers always query the active context from registry instead of using module-level service variables.
**When to use:** When you need IPC handlers to automatically target the active context without manual re-initialization on every switch.
**Trade-offs:**
- **Pros:**
- No need for `reinitializeServiceHandlers()` on every switch
- Handlers automatically use correct context
- Less code to maintain
- **Cons:**
- Need to pass registry to all handler initializers
- Small performance cost (registry lookup on every IPC call)
**Example:**
```typescript
// ipc/projects.ts (modified)
let registry: ServiceContextRegistry;
export function initializeProjectHandlers(reg: ServiceContextRegistry): void {
registry = reg;
}
export function registerProjectHandlers(ipcMain: IpcMain): void {
ipcMain.handle(GET_PROJECTS, async () => {
try {
// Always use active context
const context = registry.getActive();
const projects = await context.projectScanner.scan();
return projects;
} catch (err) {
logger.error('Failed to get projects:', err);
return [];
}
});
}
```
## Data Flow
### Context Switch Flow
```
User clicks context in UI
↓
[Renderer: ContextSwitcher]
↓ (1) Capture current state
[Renderer: captureSnapshot(currentContextId)]
↓ (2) Store in contextSnapshots map
[Renderer: contextSnapshots.set(currentContextId, snapshot)]
↓ (3) Call IPC to switch context
[IPC: switchContext(newContextId)]
↓ (4) Switch active context in registry
[Main: ServiceContextRegistry.switch(newContextId)]
│
├── Stop current context's FileWatcher
├── Mark current context inactive
├── Activate new context
└── Start new context's FileWatcher
↓ (5) Return new context metadata
[IPC Response: { contextId, type, label }]
↓ (6) Check for existing snapshot
[Renderer: contextSnapshots.get(newContextId)]
│
├─── Snapshot exists? ──────────┐
│ │
│ (instant restore)
│ ↓
│ [restoreSnapshot(snapshot)]
│ ↓
│ [UI updates immediately]
│
└─── No snapshot? ──────────────┐
│
(fetch fresh)
↓
[fetchProjects(), fetchRepositoryGroups()]
↓
[Show loading states]
↓
[UI updates when data arrives]
```
### Key Data Flows
1. **Context registration (SSH):** User connects → SshConnectionManager.connect() → ServiceContextRegistry.createSshContext() → Context registered
2. **Active context query:** IPC handler → registry.getActive() → ServiceContext → service.method()
3. **Context list update:** Registry change → main sends IPC event → renderer updates context list UI
4. **Snapshot refresh:** Context switch + stale snapshot → partial restore → background re-fetch → update snapshot
## Scaling Considerations
| Scale | Architecture Adjustments |
|-------|--------------------------|
| 1-3 contexts | Simple Map-based registry, full state snapshots, no eviction |
| 4-10 contexts | Add LRU eviction (keep 3 most recent contexts), lazy service initialization |
| 10+ contexts | Move to connection pool pattern, on-demand context creation, aggressive cache eviction |
### Scaling Priorities
1. **First bottleneck:** Memory usage from multiple DataCache instances. **Fix:** Share ChunkBuilder, only keep DataCache per-context for active requests.
2. **Second bottleneck:** FileWatcher overhead. **Fix:** Only watch active context + local (for notifications). Pause watchers on inactive contexts.
## Anti-Patterns
### Anti-Pattern 1: Destroying Local Context on SSH Connect
**What people do:** Call `disconnect()` on local services when connecting to SSH, assuming exclusive mode.
**Why it's wrong:** Notifications, config updates, and local file watching should continue running even when viewing remote data. User may want to quickly check local sessions without full reconnect.
**Do this instead:** Keep local context always alive. Add it to registry at startup with id="local". SSH contexts are additive, not replacements.
### Anti-Pattern 2: Re-Initializing All Services on Every Switch
**What people do:** Call `initializeServices()` and `reinitializeServiceHandlers()` on every context switch, recreating everything.
**Why it's wrong:** Expensive (2-3 second delay), destroys caches, resets watchers, loses in-flight operations. Causes UI flicker and poor UX.
**Do this instead:** Use ServiceContextRegistry to maintain multiple contexts. Switch by updating `activeContextId` pointer. Services stay alive and warm.
### Anti-Pattern 3: Blocking UI on Context Switch
**What people do:** Show full-screen loading spinner, disable all controls, wait for all data to re-fetch before showing any UI.
**Why it's wrong:** Context switch feels slow (500ms+ perceived latency). User loses sense of continuity. Can't cancel or go back.
**Do this instead:** Use optimistic state snapshots. Restore snapshot immediately (<50ms), show UI instantly, refresh data in background. Show subtle loading indicators only for stale data.
### Anti-Pattern 4: Sharing DataCache Across Contexts
**What people do:** Use a single DataCache for all contexts, keyed by `${contextId}:${projectId}:${sessionId}`.
**Why it's wrong:** Cache keys collide if same project path exists on multiple hosts. Eviction strategy becomes complex. Memory usage unbounded.
**Do this instead:** Each ServiceContext has its own DataCache. When context becomes inactive, optionally clear its cache to free memory (LRU policy).
### Anti-Pattern 5: No Context Metadata in IPC Responses
**What people do:** IPC handlers return raw data (projects, sessions) without indicating which context it came from.
**Why it's wrong:** Renderer can't detect stale responses from previous context. If user switches quickly A→B→A, response from first A might arrive after B response, causing wrong data to display.
**Do this instead:** Every IPC response includes `contextId` field. Renderer checks if response matches current active context before applying to state. Discard stale responses.
## Integration Points
### External Services
| Service | Integration Pattern | Notes |
|---------|---------------------|-------|
| SshConnectionManager | Wrap in ServiceContext | Create ServiceContext after successful connect, register with registry |
| FileWatcher | Per-context instance | Only active context's watcher runs. Start/stop on switch. |
| NotificationManager | Singleton, local only | Always uses local FileSystemProvider. Notifications are local-only feature. |
| ConfigManager | Singleton, local only | Settings stored locally. Applies across all contexts. |
### Internal Boundaries
| Boundary | Communication | Notes |
|----------|---------------|-------|
| Registry ↔ IPC Handlers | Direct method calls | Handlers call `registry.getActive().service.method()` |
| Main ↔ Renderer | IPC events + responses | Main sends `context-list-updated` event when contexts change |
| ServiceContext ↔ Services | Constructor injection | Pass fsProvider, projectsDir to service constructors |
| ContextSwitcher ↔ Store | Zustand actions | Call `switchContext(id)` action, store handles snapshot logic |
## Implementation Phases
### Phase 1: Main Process Architecture (Foundation)
**Goal:** Establish ServiceContext and ServiceContextRegistry
**Components to build:**
1. `ServiceContext.ts` - Interface and factory function
2. `ServiceContextRegistry.ts` - Registry with register/switch/getActive
3. Modify `index.ts` - Initialize registry instead of individual services
4. Update `ipc/handlers.ts` - Pass registry to all handlers
**Why first:** Main process architecture must be stable before renderer changes. This phase has no user-facing changes.
**Build order:** ServiceContext → ServiceContextRegistry → Modify index.ts → Update IPC handlers
### Phase 2: IPC Context API (Bridge)
**Goal:** Expose context operations to renderer
**Components to build:**
1. `ipc/context.ts` - Context IPC handlers (getCurrentContext, switchContext, listContexts)
2. `preload/index.ts` - Expose context API methods
3. Add IPC channel constants in `preload/constants/ipcChannels.ts`
**Why second:** Bridge must exist before renderer can consume it. Testable from Node.js before building UI.
**Build order:** IPC handlers → Preload API → Test with node REPL
### Phase 3: Renderer State Management (State)
**Goal:** Add context slice and snapshot system
**Components to build:**
1. `store/slices/contextSlice.ts` - Context state, actions, snapshot storage
2. `store/utils/stateSnapshot.ts` - Snapshot capture/restore functions
3. Modify `store/slices/connectionSlice.ts` - Delegate to contextSlice for SSH mode
**Why third:** State layer must exist before UI components can trigger switches.
**Build order:** stateSnapshot utils → contextSlice → Update connectionSlice → Test actions in console
### Phase 4: UI Integration (User-Facing)
**Goal:** Add context switcher UI
**Components to build:**
1. `components/common/ContextSwitcher.tsx` - Dropdown or sidebar UI
2. `hooks/useContextSwitch.ts` - Hook for switching with loading states
3. Update `Dashboard.tsx` - Show current context, integrate switcher
**Why last:** UI is the final layer. Depends on all previous phases.
**Build order:** useContextSwitch hook → ContextSwitcher UI → Integrate in Dashboard
## Build Dependencies
```
Phase 1 (Main)
↓ (ServiceContextRegistry needed by IPC)
Phase 2 (IPC Bridge)
↓ (IPC API needed by store)
Phase 3 (Renderer State)
↓ (Store actions needed by UI)
Phase 4 (UI)
```
**Critical path:** ServiceContext → ServiceContextRegistry → IPC context handlers → contextSlice → ContextSwitcher UI
**Parallelizable:**
- Phase 1 and Phase 3 (main vs renderer) can be worked on by different developers
- stateSnapshot utils can be built before contextSlice is finalized
- UI components can be mocked with fake data while state layer is being built
## Sources
**Architecture Patterns:**
- [Electron Process Model](https://www.electronjs.org/docs/latest/tutorial/process-model) - Official Electron multi-process architecture
- [Electron Inter-Process Communication](https://www.electronjs.org/docs/latest/tutorial/ipc) - IPC patterns for context coordination
- [Advanced Electron.js architecture - LogRocket Blog](https://blog.logrocket.com/advanced-electron-js-architecture/) - Advanced patterns for Electron apps
- [Building Multi-Screen Electron Applications - CorticalFlow](https://corticalflow.com/en/blog/building-multi-screen-electron-apps) - Cognitive workflow optimization with multi-context apps
**State Management:**
- [Syncing State between Electron Contexts - Bruno Scheufler](https://brunoscheufler.com/blog/2023-10-29-syncing-state-between-electron-contexts) - State synchronization patterns
- [Zutron - GitHub](https://github.com/goosewobbler/zutron) - Zustand for Electron, main-renderer sync
- [Creating a synchronized store between main and renderer - BigBinary](https://www.bigbinary.com/blog/sync-store-main-renderer-electron) - Store sync techniques
**Service Registry & DI:**
- [tsyringe - GitHub](https://github.com/microsoft/tsyringe) - Microsoft's TypeScript DI container
- [node-dependency-injection - npm](https://www.npmjs.com/package/node-dependency-injection) - DI for Node.js
- [Dependency Injection in NodeJS TypeScript - Lodely](https://www.lodely.com/blog/dependency-injection-in-nodejs-typescript) - DI patterns for Node.js/TypeScript
- [Top 5 TypeScript dependency injection containers - LogRocket](https://blog.logrocket.com/top-five-typescript-dependency-injection-containers/) - Comparison of DI libraries
**Context Patterns:**
- [ServiceTalk Asynchronous Context](https://apple.github.io/servicetalk/servicetalk-concurrent-api/SNAPSHOT/async-context.html) - Context isolation in async systems
- [Provider Pattern with React Context API - Flexiple](https://flexiple.com/react/provider-pattern-with-react-context-api) - Provider patterns for context management
---
*Architecture research for: Multi-context workspace switching in claude-devtools*
*Researched: 2026-02-12*

512
.planning/research/FEATURES.md
View file

@ -1,512 +0,0 @@
# Feature Research: Multi-Context Workspace Switching
**Domain:** Desktop application with multi-context/workspace switching
**Researched:** 2026-02-12
**Confidence:** HIGH
## Executive Summary
Multi-context desktop applications require three fundamental pillars: **instant switching**, **comprehensive state preservation**, and **clear status communication**. Research across VS Code Remote, JetBrains Gateway, Slack, Notion, Discord, and Figma reveals that users expect workspace switching to feel instantaneous with zero cognitive load, complete context preservation across switches, and continuous awareness of connection status. The line between table stakes and differentiators is clear: users will leave apps with clunky switching UX but deeply value innovations that reduce mental overhead during context transitions.
## Feature Landscape
### Table Stakes (Users Expect These)
Features users assume exist. Missing these = product feels incomplete.
| Feature | Why Expected | Complexity | Dependencies | Notes |
|---------|--------------|------------|--------------|-------|
| **Visual workspace list** | Every multi-context app shows available workspaces | LOW | None | Dropdown, sidebar, or command palette |
| **Keyboard shortcuts for switching** | Power users demand keyboard-driven workflows | LOW | Visual workspace list | Ctrl/Cmd+Number or dedicated switcher shortcut |
| **Current workspace indicator** | Users need to know "where am I?" at all glance | LOW | None | Status bar, title bar, or persistent sidebar element |
| **Connection status indicators** | Network-dependent contexts require real-time status | MEDIUM | None | Online, connecting, offline, error states with distinct visual treatment |
| **Saved connection profiles** | Users refuse to re-enter connection details repeatedly | MEDIUM | Profile storage system | Name, host, port, credentials (secure), last connected |
| **Recent connections list** | Users return to recent contexts 80%+ of the time | LOW | Profile system | Default to showing 5-10 most recent |
| **Per-workspace state preservation** | Context loss on switch = immediate user frustration | HIGH | State management system | Window size, scroll position, open files, UI state |
| **Auto-reconnect on network restore** | Brief network blips shouldn't require manual reconnection | MEDIUM | Connection health monitoring | Exponential backoff, max 6-10 retries |
| **Error state communication** | Silent failures destroy user trust | LOW | Connection monitoring | Clear error messages with actionable guidance |
| **Loading indicators during switch** | Switching delays without feedback feel like freezes | LOW | None | Skeleton states, progress indicators, or spinners |
### Differentiators (Competitive Advantage)
Features that set the product apart. Not required, but valued.
| Feature | Value Proposition | Complexity | Dependencies | Notes |
|---------|-------------------|------------|--------------|-------|
| **Instant context preview on hover** | Reduces cognitive load by showing context before switching | MEDIUM | State caching | Slack's tab preview pattern - preview without full switch |
| **Workspace-specific color coding** | Visual distinction reduces mental overhead | LOW | Visual theming system | Discord/Slack pattern - unique color per workspace |
| **Parallel workspace windows** | Advanced users want simultaneous multi-context view | HIGH | Window management, resource isolation | Slack's separate windows feature |
| **Smart workspace ordering** | Auto-prioritize by usage frequency | LOW | Usage analytics | VS Code's MRU (most recently used) ordering |
| **Workspace search/filter** | Critical when managing 10+ workspaces | LOW | Workspace metadata | Command palette pattern from VS Code |
| **One-click duplicate workspace** | Speeds up creating similar configurations | MEDIUM | Profile cloning system | Common in database tools |
| **Workspace activity notifications** | Stay informed without context switching | MEDIUM | Event system | Slack's unread indicators per workspace |
| **Offline-first with sync queue** | Continue working during network issues | HIGH | Local storage, sync engine | WhatsApp pattern - queue and sync later |
| **Workspace templates** | Accelerate common setup patterns | MEDIUM | Template storage system | JetBrains pattern for remote dev environments |
| **Connection health metrics** | Proactive awareness prevents surprises | MEDIUM | Network monitoring | Latency, bandwidth, stability indicators |
| **Workspace-specific keyboard shortcuts** | Power users customize per context | HIGH | Shortcut management system | VS Code's workspace-level settings pattern |
| **Quick switcher with fuzzy search** | Fastest method for 20+ workspaces | LOW | Search algorithm | Cmd+K pattern from modern apps |
| **Workspace groups/folders** | Organize 50+ workspaces hierarchically | MEDIUM | Grouping data model | Remote Desktop Manager pattern |
| **Context-aware AI assistance** | Auto-suggest next workspace based on patterns | HIGH | ML/pattern recognition | 2026 trend - VS Code January 2026 release |
### Anti-Features (Commonly Requested, Often Problematic)
Features that seem good but create problems.
| Feature | Why Requested | Why Problematic | Alternative |
|---------|---------------|-----------------|-------------|
| **Automatic workspace switching** | Users think it saves time | Destroys mental model, causes confusion about current context | Suggest switching with one-click confirmation |
| **Unlimited parallel workspaces** | Power users want "all contexts open" | Resource exhaustion, performance degradation | Limit to 3-5 windows with clear capacity indicator |
| **Real-time sync of all workspace state** | Seems like cloud-native best practice | Network overhead, conflict resolution complexity | Sync critical state only (profiles, favorites); defer non-critical |
| **Complex workspace hierarchies** | Enterprise users request deep nesting | Cognitive overhead, navigation confusion | Flat list with tags/labels for filtering |
| **Automatic reconnection without confirmation** | Reduces user friction | Security risk for sensitive connections; unexpected costs | Auto-reconnect with user-configurable policy per profile |
| **Workspace merging** | Requested for "combining contexts" | State collision, unclear semantics | Support opening multiple windows instead |
| **Background workspace updates** | Keep all contexts "warm" | Resource drain, battery impact | Update on switch or on-demand refresh only |
| **Infinite workspace history** | "Never lose a workspace" | Storage bloat, performance degradation | Keep 50-100 recent, archive older |
| **Cross-workspace clipboard sync** | Seems convenient | Security issue, unexpected data leakage between contexts | Explicit "copy to..." action with user confirmation |
## Feature Dependencies
```
Core Infrastructure:
Profile Storage System
└──requires──> Secure Credential Storage
└──enables──> Recent Connections List
└──enables──> Favorite/Pinned Workspaces
└──enables──> Workspace Templates
Connection Manager
└──requires──> Profile System
└──enables──> Connection Status Indicators
└──enables──> Auto-reconnect
└──enables──> Connection Health Metrics
State Preservation System
└──requires──> Per-workspace state isolation
└──enables──> Instant context switching
└──enables──> Context preview on hover
└──enables──> Parallel workspace windows
Visual Layer:
Workspace List UI
└──requires──> Profile System
└──enhances──with──> Quick Switcher
└──enhances──with──> Fuzzy Search
└──enhances──with──> Workspace Groups
Status Indicators
└──requires──> Connection Manager
└──enhances──with──> Connection Health Metrics
└──enhances──with──> Activity Notifications
Advanced Features:
Parallel Windows
└──requires──> State Preservation
└──requires──> Resource Isolation
└──conflicts──with──> Unlimited Parallel Workspaces (anti-pattern)
Offline-First
└──requires──> Local State Storage
└──requires──> Sync Queue
└──requires──> Conflict Resolution
└──enables──> Continue work during outages
Context-Aware AI
└──requires──> Usage Analytics
└──requires──> Pattern Recognition
└──enhances──> Quick Switcher
```
### Dependency Notes
- **Profile System is foundational**: Nearly all features depend on having profile storage and management
- **State Preservation enables advanced features**: Context preview, parallel windows, and offline mode all require robust state management
- **Connection Manager is critical path**: Status indicators, health metrics, and auto-reconnect all depend on centralized connection management
- **Quick Switcher amplifies other features**: When combined with fuzzy search, workspace groups, and AI suggestions, it becomes the primary navigation method
- **Parallel windows conflict with unlimited contexts**: Must enforce limits to prevent resource exhaustion
## MVP Definition
### Launch With (v1) - Core Context Switching
**Goal**: Users can switch between local and SSH workspaces without friction
**Essential features** (ranked by priority):
1. **Visual workspace list with status** - Users need to see available workspaces and connection status at a glance
- Why: Table stakes. Users can't switch if they can't see options
- Implementation: Sidebar with workspace cards showing name, type (local/SSH), and status dot
2. **Saved connection profiles** - Store SSH host, port, user for quick access
- Why: Re-entering connection details is unacceptable UX
- Implementation: Profile manager with CRUD operations, secure credential storage
3. **Recent connections (5-10)** - Most users return to same 3-5 workspaces
- Why: 80% of switches go to recent contexts
- Implementation: Auto-populate list from connection history
4. **Current workspace indicator** - Status bar showing active workspace
- Why: Prevents "where am I?" confusion
- Implementation: Persistent badge in title bar or status bar
5. **Per-workspace state preservation** - Restore open files, scroll position, window size
- Why: Context loss = user frustration and productivity loss
- Implementation: State snapshot per workspace, restore on switch
6. **Connection status indicators** - Online, connecting, offline, error states
- Why: Network-dependent contexts need real-time status
- Implementation: Color-coded dots with tooltip details
7. **Loading states during switch** - Visual feedback for 0.5s+ operations
- Why: Delays without feedback feel like hangs
- Implementation: Skeleton UI or progress bar
8. **Basic error handling** - Clear messages for connection failures
- Why: Silent failures destroy trust
- Implementation: Error modal with actionable message and retry button
9. **Keyboard shortcut for switcher** - Cmd/Ctrl+K to open workspace list
- Why: Power users demand keyboard access
- Implementation: Keyboard shortcut opening modal or command palette
**Explicitly NOT in v1**:
- Command palette/fuzzy search (v1.x priority)
- Auto-reconnect (v1.x priority)
- Parallel windows (v2+ complexity)
- Workspace groups (only needed at 20+ workspaces)
- AI suggestions (v2+ nice-to-have)
### Add After Validation (v1.x) - Enhanced Switching
**Triggers for adding**:
- User feedback: "I have 10+ workspaces and can't find them"
- Analytics: Users repeatedly reconnecting after brief network blips
- Support tickets: Confusion about workspace state after switch
**Features to add**:
1. **Quick switcher with fuzzy search** - Cmd+K to instantly filter workspaces
- When: Users managing 10+ workspaces
- Why: Linear list becomes overwhelming; search is faster than scrolling
2. **Auto-reconnect with exponential backoff** - Automatically retry failed connections
- When: Users report frustration with manual reconnection
- Why: Brief network blips are common; auto-recovery improves UX
3. **Workspace templates** - Save connection profile as reusable template
- When: Users creating multiple similar configurations
- Why: Accelerates common setup patterns
4. **Connection health metrics** - Latency, stability indicators in workspace list
- When: Users working across high-latency connections
- Why: Proactive awareness prevents surprises
5. **Workspace-specific color coding** - Visual distinction per workspace
- When: Users managing 5+ workspaces and switching frequently
- Why: Reduces cognitive load through visual patterns
6. **Activity notifications** - Unread indicators for background workspaces
- When: Users need to monitor multiple contexts simultaneously
- Why: Stay informed without switching
### Future Consideration (v2+) - Advanced Capabilities
Features to defer until product-market fit is established.
1. **Parallel workspace windows** - Open 2-3 workspaces simultaneously
- Why defer: High complexity, resource management challenges
- Prerequisites: Usage data showing demand for multi-window workflows
2. **Offline-first with sync queue** - Queue operations during network outages
- Why defer: Complex conflict resolution, requires robust sync engine
- Prerequisites: Users reporting productivity loss during outages
3. **Context-aware AI workspace suggestions** - Predict next workspace based on patterns
- Why defer: Requires ML infrastructure, significant training data
- Prerequisites: Strong v1 adoption, usage analytics baseline
4. **Workspace groups/folders** - Hierarchical organization for 50+ workspaces
- Why defer: Only needed at significant scale
- Prerequisites: Users managing 20+ workspaces
5. **Workspace-specific keyboard shortcuts** - Customize shortcuts per context
- Why defer: Implementation complexity, potential user confusion
- Prerequisites: Power user requests for per-workspace customization
6. **Cross-workspace search** - Search files/content across all workspaces
- Why defer: Performance challenges, requires indexing infrastructure
- Prerequisites: Users managing large numbers of workspaces
## Feature Prioritization Matrix
| Feature | User Value | Implementation Cost | Priority | Phase |
|---------|------------|---------------------|----------|-------|
| Visual workspace list | HIGH | LOW | P1 | v1 |
| Saved connection profiles | HIGH | MEDIUM | P1 | v1 |
| Recent connections | HIGH | LOW | P1 | v1 |
| Current workspace indicator | HIGH | LOW | P1 | v1 |
| Per-workspace state preservation | HIGH | HIGH | P1 | v1 |
| Connection status indicators | HIGH | MEDIUM | P1 | v1 |
| Loading states | HIGH | LOW | P1 | v1 |
| Basic error handling | HIGH | LOW | P1 | v1 |
| Keyboard shortcut for switcher | HIGH | LOW | P1 | v1 |
| Quick switcher with fuzzy search | HIGH | LOW | P2 | v1.x |
| Auto-reconnect | HIGH | MEDIUM | P2 | v1.x |
| Workspace templates | MEDIUM | MEDIUM | P2 | v1.x |
| Connection health metrics | MEDIUM | MEDIUM | P2 | v1.x |
| Workspace color coding | MEDIUM | LOW | P2 | v1.x |
| Activity notifications | MEDIUM | MEDIUM | P2 | v1.x |
| Context preview on hover | MEDIUM | MEDIUM | P2 | v1.x |
| Parallel workspace windows | HIGH | HIGH | P3 | v2+ |
| Offline-first with sync queue | MEDIUM | HIGH | P3 | v2+ |
| Context-aware AI suggestions | LOW | HIGH | P3 | v2+ |
| Workspace groups/folders | MEDIUM | MEDIUM | P3 | v2+ |
| Workspace-specific shortcuts | LOW | HIGH | P3 | v2+ |
| Cross-workspace search | MEDIUM | HIGH | P3 | v2+ |
**Priority key**:
- **P1 (Must have for launch)**: Core functionality, missing = broken product
- **P2 (Should have, add when possible)**: Significantly improves UX, validates value proposition
- **P3 (Nice to have, future consideration)**: Advanced capabilities for mature product
## UX Pattern Analysis by Application
### VS Code Remote (2026)
**Table Stakes Implemented**:
- Remote Explorer with visual host list
- SSH config file integration (saved profiles)
- Status bar indicator showing local/remote context
- Recent connections in Command Palette
- Extension classification (UI vs Workspace) for state isolation
**Differentiators**:
- Workspace indexing for faster code search (January 2026)
- Agent integration with remote workspaces (AI-assisted development)
- Extension recommendations per workspace type
- Transparent remote filesystem access
**Observed Patterns**:
- Command Palette as primary navigation (Ctrl+Shift+P)
- Activity Bar for persistent context (sidebar with icons)
- Status bar for ambient awareness (current context, connection status)
### JetBrains Gateway
**Table Stakes Implemented**:
- Workspace list with start/stop controls
- Connection status display (started, stopped, busy)
- Recent workspaces list
- IDE backend management (version control)
**Differentiators**:
- Explicit workspace lifecycle control (start, stop, not just connect)
- IDE backend version management from Gateway
- Integration with cloud dev environments (Coder, Gitpod, Harness)
**Observed Patterns**:
- Explicit state management (stopped vs running)
- Green/red controls for visual clarity (start/stop icons)
- Backend management separated from connection management
### Slack
**Table Stakes Implemented**:
- Workspace switcher icon in title bar
- Keyboard shortcuts (Ctrl+Shift+S for switcher, Ctrl+Number to jump)
- Recent workspace list
- Per-workspace notifications
**Differentiators**:
- Separate windows for simultaneous multi-workspace view
- Workspace filter to show/hide specific workspaces
- Tab preview on hover (see content without switching)
- Ctrl+Shift+[ and ] for sequential navigation
- Enterprise Grid support (simplified multi-workspace in large orgs)
**Observed Patterns**:
- Workspace switcher always visible (persistent awareness)
- Multiple access methods (click, keyboard numbers, sequential nav)
- Parallel windows for advanced users
### Notion
**Table Stakes Implemented**:
- Workspace dropdown in top-left
- Ctrl+Shift+Number for quick switching
- Multi-account support (10+ accounts without hard limit)
- Drag-to-reorder workspaces
**Differentiators**:
- Account aggregation (multiple email accounts in one app)
- Workspace prioritization via drag-and-drop
- Smooth tab switching with preview on hover
**Observed Patterns**:
- Top-left corner for workspace identity (consistent with OS patterns)
- Visual priority ordering (users customize workspace sequence)
- Performance degradation warning (10+ accounts)
### Discord
**Table Stakes Implemented**:
- Server list in left sidebar (always visible)
- Status indicators (online, idle, DND, streaming)
- Platform-specific icons (desktop vs mobile)
- Quick Switcher (Ctrl+K) with online status indicators (October 2025)
**Differentiators**:
- Color-coded status (green=online, yellow=idle, red=DND, purple=streaming)
- Platform awareness (desktop vs mobile indicators)
- Status shown in Quick Switcher search results
- Unread indicators per server
**Observed Patterns**:
- Persistent sidebar for context awareness
- Quick Switcher as power user feature
- Visual status prioritized over text labels
### Figma (2026)
**Table Stakes Implemented**:
- File list with recent files
- Standardized page structures (Cover, Playground, Handoff, Archive)
- Team file navigation
**Differentiators**:
- Multi-file modular architecture (tokens, components, docs in separate files)
- AI-powered search across team files
- UI3 redesign maximizing canvas space while retaining navigation anchors
- Zero cognitive load context switching via standardized structures
**Observed Patterns**:
- Standardization reduces cognitive load (consistent structure = instant familiarity)
- Modular file architecture for independent updates
- AI assistance for cross-file navigation
## Common Patterns Across Applications
### Switcher UI Patterns
1. **Dropdown** (Notion, VS Code partial): Click workspace name to show list
2. **Sidebar** (Discord, Slack partial): Always-visible list for instant access
3. **Command Palette** (VS Code, Discord, Figma): Keyboard-first fuzzy search
4. **Hybrid** (Slack): All three methods available
**Recommendation**: Start with dropdown + keyboard shortcut for MVP; add command palette in v1.x when users manage 10+ workspaces.
### Status Indicator Patterns
1. **Color-coded dots** (Discord, VS Code): Green=connected, yellow=connecting, red=error, gray=offline
2. **Text labels** (JetBrains): "Started", "Stopped", "Busy"
3. **Icon + text combo** (Slack): Icon with tooltip on hover
**Recommendation**: Color-coded dots with tooltip for details (minimal space, accessible, standard pattern).
### Connection Profile Patterns
1. **Manual entry** (VS Code): Edit SSH config file
2. **Form-based** (JetBrains, database tools): GUI for connection details
3. **Implicit** (Notion, Slack): Profiles created automatically on first connection
**Recommendation**: Form-based GUI for SSH connections (lower friction); auto-save on successful connection as implicit profile.
### State Preservation Patterns
1. **Full snapshot** (VS Code): Restore all open files, cursor positions, UI state
2. **Partial snapshot** (Slack): Remember channel but not scroll position
3. **Session storage** (Web apps): Local/session storage for UI state
**Recommendation**: Full snapshot for development tools (VS Code pattern); partial for lighter contexts if needed.
### Loading State Patterns
1. **Skeleton screens** (Modern web apps): Show structure while loading
2. **Progress bars** (JetBrains): Percentage-based for long operations
3. **Spinners** (Generic): Simple animation for indeterminate duration
**Recommendation**: Skeleton screens for predictable loading (workspace list); spinners for connection attempts (unpredictable duration).
### Error Handling Patterns
1. **Modal dialogs** (Traditional apps): Blocking error message with retry
2. **Toast notifications** (Modern apps): Non-blocking error with auto-dismiss
3. **Inline errors** (Forms): Error message in context of failure
**Recommendation**: Toast notifications for transient errors (network blip); modal for critical errors requiring user action (invalid credentials).
## Roadmap Implications
### Phase 1: Core Infrastructure (v1)
**Focus**: Make workspace switching work reliably
**Critical features**:
- Profile storage with secure credentials
- Connection manager with status tracking
- State preservation per workspace
- Visual workspace list with status
- Basic keyboard navigation
**Success criteria**: Users can switch between local and SSH workspaces without re-entering details, with state preserved across switches.
### Phase 2: Enhanced UX (v1.x)
**Focus**: Make switching delightful
**Critical features**:
- Quick switcher with fuzzy search
- Auto-reconnect on network restore
- Workspace color coding
- Connection health metrics
- Activity notifications
**Success criteria**: Users with 10+ workspaces can find and switch to any workspace in <2 seconds; network blips don't interrupt workflows.
### Phase 3: Advanced Capabilities (v2+)
**Focus**: Support power users and scale
**Critical features**:
- Parallel workspace windows
- Offline-first with sync queue
- Workspace groups for 50+ contexts
- Context-aware AI suggestions
- Cross-workspace search
**Success criteria**: Users managing 20+ workspaces across flaky networks maintain productivity; power users can monitor multiple contexts simultaneously.
## Sources
### VS Code Remote Development
- [VS Code Remote Development Overview](https://code.visualstudio.com/docs/remote/remote-overview)
- [Remote Development using SSH](https://code.visualstudio.com/docs/remote/ssh)
- [January 2026 Release Notes (version 1.109)](https://code.visualstudio.com/updates/v1_109)
- [Supporting Remote Development and GitHub Codespaces](https://code.visualstudio.com/api/advanced-topics/remote-extensions)
- [Remote Development FAQ](https://code.visualstudio.com/docs/remote/faq)
### JetBrains Gateway
- [JetBrains Gateway - Remote Development for JetBrains IDEs](https://www.jetbrains.com/remote-development/gateway/)
- [Connect and work with JetBrains Gateway | IntelliJ IDEA Documentation](https://www.jetbrains.com/help/idea/remote-development-a.html)
- [A Deep Dive Into JetBrains Gateway | The JetBrains Blog](https://blog.jetbrains.com/blog/2021/12/03/dive-into-jetbrains-gateway/)
- [Remote development overview | IntelliJ IDEA Documentation](https://www.jetbrains.com/help/idea/remote-development-overview.html)
### Slack
- [Switch between workspaces | Slack](https://slack.com/help/articles/1500002200741-Switch-between-workspaces)
- [A consolidated set of tabs for Slack on desktop | Slack](https://slack.com/help/articles/16764236868755-An-overview-of-Slacks-new-design)
- [A redesigned Slack, built for focus | Slack](https://slack.com/blog/productivity/a-redesigned-slack-built-for-focus)
- [More Intuitive Multi-Workspace Slack Experience | Medium](https://medium.com/design-bootcamp/slack-home-reinventing-a-more-intuitive-experience-for-you-a-ux-case-study-da7c3e399cc6)
### Notion
- [Create, join & leave workspaces – Notion Help Center](https://www.notion.com/help/create-delete-and-switch-workspaces)
- [Notion for desktop – Notion Help Center](https://www.notion.com/help/notion-for-desktop)
- [A Notion guide on switching between work and personal accounts](https://www.notion.com/help/guides/a-notion-guide-on-switching-between-work-and-personal-accounts)
- [Intro to workspaces – Notion Help Center](https://www.notion.com/help/intro-to-workspaces)
### Discord
- [Discord Patch Notes: October 7, 2025](https://discord.com/blog/discord-patch-notes-october-7-2025)
- [User Status | Discord Wiki](https://discord.fandom.com/wiki/User_Status)
- [Discord Status Icons: 2026 Guide](https://www.qqtube.com/blog/what-does-the-green-phone-icon-mean-on-discord)
### Figma
- [The Complete Guide to Design Systems in Figma (2026 Edition) | Medium](https://medium.com/@EmiliaBiblioKit/the-world-of-design-systems-is-no-longer-just-about-components-and-libraries-its-about-5beecc0d21cb)
- [Stop the Chaos: The Best Figma Plugins to Organize Design Files in 2026 | Medium](https://medium.com/design-bootcamp/stop-the-chaos-the-best-figma-plugins-to-organize-design-files-in-2026-ff9941d213a6)
- [Figma Config 2025: What's new, what's next, and what you should be doing - LogRocket Blog](https://blog.logrocket.com/ux-design/figma-config-2025-whats-new-whats-next/)
### UX Patterns & Best Practices
- [Linux Desktop: Do we need better Workspace Management?](https://linuxblog.io/linux-desktop-workspace-management/)
- [Designing desktop apps for cross-platform UX | ToDesktop Blog](https://www.todesktop.com/blog/posts/designing-desktop-apps-cross-platform-ux)
- [Command Palette | UX Patterns #1 | Medium](https://medium.com/design-bootcamp/command-palette-ux-patterns-1-d6b6e68f30c1)
- [Command Palette UI Design: Best practices, Design variants & Examples | Mobbin](https://mobbin.com/glossary/command-palette)
### Connection Profile Management
- [Remote Desktop Connection Manager - Microsoft Learn](https://learn.microsoft.com/en-us/sysinternals/downloads/rdcman)
- [Favorite Connections - Compass - MongoDB Docs](https://docs.mongodb.com/compass/master/connect/favorite-connections/)
- [Manage Connection Profiles](https://github.com/microsoft/vscode-mssql/wiki/manage-connection-profiles)
- [Preferred connections: "remember" frequently used servers/databases with SSMSBoost](https://www.ssmsboost.com/Features/ssms-add-in-preferred-connections)
### Error Handling & Reconnection
- [Finally! Improved Blazor Server reconnection UX](https://jonhilton.net/blazor-server-reconnects/)
- [Connection Management | PubNub Docs](https://www.pubnub.com/docs/general/setup/connection-management)
- [Handling Database Reconnection Issues in .NET with Polly - NashTech Blog](https://blog.nashtechglobal.com/handling-database-reconnection-issues-in-net-with-polly/)
- [Offline Mobile App Design: Challenges, Strategies, Best Practices - LeanCode](https://leancode.co/blog/offline-mobile-app-design)
### Loading States & System Status
- [UX Design Patterns for Loading - Pencil & Paper](https://www.pencilandpaper.io/articles/ux-pattern-analysis-loading-feedback)
- [6 Loading State Patterns That Feel Premium | Medium](https://medium.com/uxdworld/6-loading-state-patterns-that-feel-premium-716aa0fe63e8)
- [4 Ways To Communicate the Visibility of System Status in UI | UX Planet](https://uxplanet.org/4-ways-to-communicate-the-visibility-of-system-status-in-ui-14ff2351c8e8)
- [FOSDEM 2026 - Designing for Local-First: UX Patterns for a Network-Optional World](https://fosdem.org/2026/schedule/event/JX7Y3D-ux-design-for-local-first/)
---
*Feature research for: Multi-context workspace switching in desktop applications*
*Researched: 2026-02-12*

408
.planning/research/PITFALLS.md
View file

@ -1,408 +0,0 @@
# Pitfalls Research
**Domain:** Multi-context workspace switching for Electron + Zustand apps
**Researched:** 2026-02-12
**Confidence:** HIGH
---
## Critical Pitfalls
### Pitfall 1: Destructive Context Switching with Incomplete State Snapshots
**What goes wrong:**
Switching from SSH to local (or vice versa) calls `getFullResetState()` which wipes ALL selections and loaded data, destroying the user's previous workspace state. When switching back, users must re-navigate to their project, re-open sessions, and restore their scroll position manually.
**Why it happens:**
Current implementation treats context switch as a "hard reset" instead of maintaining separate state snapshots per context. The `connectionSlice` spreads `getFullResetState()` on connect/disconnect, clearing `selectedProjectId`, `selectedSessionId`, `conversation`, tabs, and all derived state.
**How to avoid:**
- **Snapshot before switching**: Capture full AppState before connect/disconnect
- **Scope snapshots by context**: Use `Map<'local' | SshHostKey, AppState>` to store separate state per context
- **Partial restoration**: Only restore state compatible with the new context (project IDs may differ between local/SSH)
- **Preserve UI preferences**: Tab layout, expanded groups, scroll positions are context-agnostic and should always restore
**Warning signs:**
- User complaints about "losing their place" when switching contexts
- Empty dashboard after SSH connect, despite having viewed sessions before
- No tabs open after switching back to local mode
- Context panel expansions reset on every switch
**Phase to address:**
Phase 1 (Core Infrastructure) — state snapshot/restore must be foundational before adding multi-context features.
---
### Pitfall 2: EventEmitter Listener Accumulation on Repeated Context Switches
**What goes wrong:**
FileWatcher, SshConnectionManager, and NotificationManager are EventEmitters. Each context switch may call `setFileSystemProvider()` or re-initialize services without removing old listeners, causing:
- Memory leaks (listeners hold references to previous provider instances)
- Duplicate event emissions (one event triggers 2x, 3x handlers)
- Stale event handlers executing against wrong context
**Why it happens:**
Services use `.on()` to attach listeners but don't call `.removeAllListeners()` or track cleanup functions. The `initializeNotificationListeners()` function in store/index.ts returns a cleanup function, but there's no guarantee it's called before re-initialization.
**How to avoid:**
- **Centralized cleanup**: Create `dispose()` methods for all EventEmitter services
- **Lifecycle tracking**: Maintain `Map<string, () => void>` of cleanup functions keyed by service name
- **Pre-switch cleanup**: Call all cleanup functions BEFORE provider swap
- **Idempotent initialization**: Check `if (this.isInitialized) return` to prevent double-init
- **Avoid `removeAllListeners()` on ipcRenderer**: Always specify channel name — blanket removal breaks Electron internals
**Warning signs:**
- Process memory usage (RSS) grows 50-100MB per context switch
- DevTools heap snapshot shows multiple FileWatcher/SshConnectionManager instances
- Console logs show duplicate "file-change" events for same file
- IPC handlers fire 2x for single user action
**Phase to address:**
Phase 1 (Core Infrastructure) — service lifecycle management is critical before multi-context.
**Sources:**
- [Error: Removing all listeners from ipcRenderer will make Electron internals stop working](https://github.com/electron/electron/issues/10379)
- [IPC in Electron - Ray](https://myray.app/blog/ipc-in-electron)
---
### Pitfall 3: Stale Closures in Zustand Actions Capturing Old Provider References
**What goes wrong:**
Zustand actions like `fetchProjects()` capture the FileSystemProvider in their closure at store creation time. After calling `sshConnectionManager.getProvider()` which returns a new SshFileSystemProvider, existing actions still reference the old LocalFileSystemProvider, causing operations to execute against the wrong context.
**Why it happens:**
JavaScript closures capture variables at definition time. When a Zustand action calls `window.electronAPI.getProjects()`, the IPC handler calls `projectScanner.scan()`, which calls `this.fsProvider.readdir()`. If the scanner's provider reference wasn't updated, it uses the stale provider.
**How to avoid:**
- **Late binding via getter**: Services should call `getProvider()` on every operation, not cache at construction
- **Provider as parameter**: Pass provider explicitly to service methods instead of storing as instance variable
- **Re-initialize services**: After provider swap, call `fileWatcher.setFileSystemProvider(newProvider)` on ALL services
- **Service registry pattern**: Centralize provider injection so swap happens in one place
- **Verify in tests**: Mock provider swap and assert service calls hit new provider
**Warning signs:**
- SSH connect succeeds but dashboard shows local projects
- File operations fail with "ENOENT" after provider swap
- Console shows "LocalFileSystemProvider" operations when SSH is connected
- User switches to SSH but sees local data until app restart
**Phase to address:**
Phase 1 (Core Infrastructure) — provider injection architecture must be correct from the start.
**Sources:**
- [Be Aware of Stale Closures when Using React Hooks](https://dmitripavlutin.com/react-hooks-stale-closures/)
- [How to Fix "Stale Closure" Issues in React Hooks](https://oneuptime.com/blog/post/2026-01-26-fix-stale-closure-issues-react-hooks/view)
---
### Pitfall 4: IPC Race Conditions During Context Switch with In-Flight Requests
**What goes wrong:**
User clicks "Connect SSH" → IPC handler starts scanning remote projects → user quickly clicks "Disconnect" → scan completes and populates store with SSH data → store now shows SSH projects in local mode, creating data corruption.
**Why it happens:**
Async IPC calls (getProjects, getSessions) don't track which context initiated them. By the time a response arrives, the context may have switched, but Zustand applies the stale response anyway.
**How to avoid:**
- **Context ID stamping**: Include `contextId` (UUID per connection) in every IPC request/response
- **Response validation**: Check `if (currentContextId !== response.contextId) return` before applying
- **Request cancellation**: Track in-flight requests via AbortController and cancel on context switch
- **State machine**: Use FSM with states: `idle → connecting → connected → disconnecting → idle`. Reject operations in wrong states.
- **Sequential transitions**: Wait for disconnect cleanup to complete before starting connect
**Warning signs:**
- Dashboard briefly flickers between local and SSH data during transitions
- Error notifications appear for wrong context after switching
- Search results from previous context appear after switch
- Console shows "Cannot read property of null" after rapid connect/disconnect
**Phase to address:**
Phase 1 (Core Infrastructure) — race condition prevention is non-negotiable for reliability.
**Sources:**
- [Syncing State between Electron Contexts](https://brunoscheufler.com/blog/2023-10-29-syncing-state-between-electron-contexts)
- [Advanced Electron.js architecture - LogRocket Blog](https://blog.logrocket.com/advanced-electron-js-architecture/)
---
### Pitfall 5: FileWatcher Polling Timer Not Cleared on SSH Disconnect
**What goes wrong:**
SSH mode uses `setInterval()` polling (5s) instead of fs.watch(). When user disconnects, `stop()` clears `pollingTimer`, but the cleanup happens in `finally` block — if an exception occurs, timer keeps running. After 10 switches, 10 polling timers consume CPU checking a disconnected SSH provider.
**Why it happens:**
Interval timers require explicit `clearInterval()`, and error paths may skip cleanup. The `pollingTimer` property is set to null without actually clearing the interval, causing orphaned timers.
**How to avoid:**
- **Cleanup in finally**: Always clear timers in `finally` block, not just normal path
- **Defensive clearing**: Before creating new timer, clear existing: `if (this.timer) clearInterval(this.timer)`
- **Timer registry**: Track all active timers in Set<NodeJS.Timeout> and clear all on dispose
- **Polling refactor**: Consider using a single interval that checks `isRemote()` flag instead of separate modes
- **Memory profiling**: Add setInterval/clearInterval tracking to detect orphaned timers
**Warning signs:**
- CPU usage increases by 5-10% per context switch
- Chrome DevTools → Performance shows multiple "pollForChanges" concurrent executions
- Memory usage grows 20MB per switch (timer closures hold provider references)
- App becomes sluggish after 5-10 SSH switches
**Phase to address:**
Phase 1 (Core Infrastructure) — timer lifecycle bugs cause performance degradation.
---
### Pitfall 6: SSH Connection Not Properly Disposed, Keeping Socket Open
**What goes wrong:**
`SshConnectionManager.disconnect()` calls `client.end()`, but if the SFTP channel is still processing operations, the socket remains open (TCP FIN not sent). After 10 context switches, 10 SSH connections consume file descriptors and remote server resources.
**Why it happens:**
ssh2 Client `.end()` is graceful (waits for channel closure), but `.destroy()` is immediate. If you don't wait for SFTP operations to complete before calling `.end()`, the connection may linger. The `dispose()` method swallows errors, hiding cleanup failures.
**How to avoid:**
- **Force close on disconnect**: Use `client.destroy()` instead of `.end()` for immediate termination
- **SFTP channel close**: Call `sftp.end()` explicitly before `client.end()`
- **Connection timeout**: Set 5s timeout on disconnect — if client doesn't close, force destroy
- **Socket tracking**: Expose `net.Socket` from Client and verify `socket.destroyed === true` post-cleanup
- **Resource monitoring**: Log open file descriptors (lsof) to detect leaks
**Warning signs:**
- `lsof -p <pid>` shows 10+ TCP connections to SSH host
- SSH host reports "Max sessions exceeded" after many switches
- `netstat` shows multiple ESTABLISHED connections to port 22
- Disconnect takes 5+ seconds (waiting for timeout)
**Phase to address:**
Phase 1 (Core Infrastructure) — connection leaks cause operational issues at scale.
**Sources:**
- [Diagnosing and Fixing Memory Leaks in Electron Applications](https://www.mindfulchase.com/explore/troubleshooting-tips/frameworks-and-libraries/diagnosing-and-fixing-memory-leaks-in-electron-applications.html)
- [Viacheslav Eremin | Memory Leaks in Electron application](https://www.vb-net.com/AngularElectron/MemoryLeaks.htm)
---
### Pitfall 7: Tab State Restoration Without Context Validation
**What goes wrong:**
Snapshot captures open tabs with `projectId: "abc-local-path"`. User switches to SSH where projects have different IDs. Restoration tries to open tab with local projectId against SSH provider → tab shows "Project not found" error or stale local data.
**Why it happens:**
ProjectId encoding includes file path (`-Users-name-project`), so local and SSH projects for the same logical directory have different IDs. Tab restoration doesn't validate whether a project exists in the new context.
**How to avoid:**
- **Path normalization**: Introduce `logicalProjectPath` (e.g., `/home/user/project`) separate from encoded ID
- **Cross-context mapping**: Maintain `Map<logicalPath, {localId, sshId}>` to translate IDs during restore
- **Graceful degradation**: If project doesn't exist in new context, close tab or show empty state instead of error
- **Restore validation**: Before applying snapshot, call `window.electronAPI.getProjects()` and filter tabs to existing projects
- **User notification**: Show toast "3 tabs closed - projects not available in SSH mode"
**Warning signs:**
- User switches to SSH, tabs show "Failed to load session"
- Console errors "Project ID abc-local not found" after context switch
- Tab bar shows ghost tabs (visible but non-functional)
- Click on restored tab triggers navigation to dashboard instead
**Phase to address:**
Phase 2 (State Persistence) — after Phase 1 establishes snapshots, validation ensures safe restoration.
---
### Pitfall 8: Partial Snapshot Creates Inconsistent Derived State
**What goes wrong:**
Snapshot captures `selectedProjectId`, `selectedSessionId`, but omits `sessionDetail`, `conversation`, `chunks`. Restoration sets selections without corresponding data → store state says "session XYZ selected" but detail is null → UI renders empty or crashes on null access.
**Why it happens:**
Developers manually list fields to snapshot instead of capturing full AppState. Derived state (detail, conversation) is computed from selections, but if selections restore before data loads, the UI sees inconsistent state.
**How to avoid:**
- **Snapshot everything**: Capture `AppState` wholesale, excluding only ephemeral UI flags (loading, error)
- **Atomic restoration**: Use `setState(() => snapshot)` so all fields update simultaneously
- **Lazy detail loading**: On restoration, if `selectedSessionId` exists but `sessionDetail` is null, trigger background fetch
- **State versioning**: Include `snapshotVersion: 1` to handle schema changes (e.g., new fields added)
- **Whitelist vs blacklist**: Easier to exclude ephemeral fields (`loading`, `error`) than enumerate 50+ persistent fields
**Warning signs:**
- After switch, session viewer shows spinner indefinitely
- Console error "Cannot read property 'chunks' of null"
- Dashboard shows selected project but no sessions loaded
- Tab labels show "undefined" or "[object Object]"
**Phase to address:**
Phase 1 (Core Infrastructure) — snapshot completeness is foundational to state restoration.
**Sources:**
- [Zustand - react state management made easy](https://graphqleditor.com/blog/zustand/)
---
## Technical Debt Patterns
Shortcuts that seem reasonable but create long-term problems.
| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
|----------|-------------------|----------------|-----------------|
| **Storing provider as instance variable** | Simple, no getter needed | Stale closure bugs on provider swap | Never — always use getter |
| **Not tracking cleanup functions** | Less boilerplate code | Memory leaks accumulate with usage | Never — cleanup is mandatory |
| **Hard reset on context switch** | Easy to implement (3 lines) | User loses workspace state | Never — destroys UX |
| **Using `removeAllListeners()`** | Clears everything at once | Breaks Electron IPC internals | Never — specify channel |
| **Sync IPC for connect** | Blocks until complete | UI freezes 2-5s on slow networks | Never — SSH is async |
| **Single global DataCache** | Shared cache across contexts | Cache pollution (local data in SSH mode) | Never — scope cache per context |
| **Manual field-by-field snapshot** | Fine-grained control | Fragile, breaks when state schema evolves | Only for specific performance tuning |
| **Not versioning snapshots** | Don't need migration code | Can't safely restore after app updates | Only in MVP — add versioning in Phase 2 |
---
## Integration Gotchas
Common mistakes when connecting to external services.
| Integration | Common Mistake | Correct Approach |
|-------------|----------------|------------------|
| **SSH2 Client** | Using `.end()` without waiting for SFTP close | Call `sftp.end()`, wait 100ms, then `client.destroy()` |
| **SFTP operations** | Not catching ENOENT on remote path access | Wrap all `sftp.stat()` in try/catch, validate paths exist |
| **IPC context bridge** | Passing large objects (10MB+ session JSON) | Stream via chunks or use temp file + file path |
| **FileWatcher SSH polling** | Polling every 1s (too aggressive) | 5s minimum — SSH has latency |
| **Zustand subscriptions** | Subscribing to full store on every render | Use selectors: `useStore((s) => s.field, shallow)` |
| **React useEffect** | Empty deps array with state access | Include all state in deps or use functional updates |
---
## Performance Traps
Patterns that work at small scale but fail as usage grows.
| Trap | Symptoms | Prevention | When It Breaks |
|------|----------|------------|----------------|
| **Cache not scoped by context** | Search returns SSH results in local mode | Separate caches: `localCache`, `sshCache` | After first context switch |
| **Snapshot entire 50MB state** | 500ms freeze during switch | Exclude non-serializable (functions, DOM refs) | 10+ open sessions |
| **No debounce on provider swap events** | 10 re-renders per switch | Debounce 100ms, batch provider updates | Rapid switching (QA testing) |
| **Loading all tabs eagerly** | UI freezes restoring 20 tabs | Virtual scrolling + lazy load tab content | 10+ open tabs |
| **Not canceling in-flight IPC** | Stale responses overwrite new data | AbortController per IPC call | Slow network (SSH over VPN) |
| **Synchronous validation during snapshot** | Blocks UI during switch | Validate asynchronously post-restoration | Large state (100+ projects) |
---
## Security Mistakes
Domain-specific security issues beyond general web security.
| Mistake | Risk | Prevention |
|---------|------|------------|
| **Storing SSH passwords in snapshot** | Plaintext credentials in memory dump | Never snapshot credentials — only host/port/user |
| **Not validating SSH host keys** | MITM attacks | Use ssh2 `hostVerifier` callback, check known_hosts |
| **Exposing SSH provider to renderer** | Renderer can execute arbitrary commands | Keep provider in main process only, expose via IPC |
| **Logging full AppState snapshots** | Sensitive data in logs | Redact: `password`, `privateKey`, `sessionContent` |
| **Not sanitizing project paths** | Path traversal attacks | Validate paths with `path.resolve()`, reject ".." |
---
## UX Pitfalls
Common user experience mistakes in this domain.
| Pitfall | User Impact | Better Approach |
|---------|-------------|-----------------|
| **No visual feedback during switch** | User doesn't know if click worked | Show connecting spinner + progress bar |
| **Immediate switch without confirmation** | Accidental clicks lose workspace | "Switch will close X tabs. Continue?" dialog |
| **No indication of current context** | User forgets if in local/SSH | Persistent badge in header: "Local" or "SSH: hostname" |
| **Context switch closes all tabs** | User loses 10+ open sessions | Restore tabs if projects exist in new context |
| **No way to view both contexts** | Can't compare local vs SSH data | Split view or dual panes (future enhancement) |
| **Errors shown as raw exceptions** | "ENOTFOUND" means nothing to user | Friendly: "Cannot connect to SSH host. Check network." |
---
## "Looks Done But Isn't" Checklist
Things that appear complete but are missing critical pieces.
- [ ] **Context switch** — Looks like it works because SSH connects, but missing: cleanup old listeners, cancel in-flight IPC, validate restored tabs
- [ ] **State snapshot** — Appears to save state, but missing: exclude ephemeral fields, version snapshots, validate restorable
- [ ] **Provider swap** — FileWatcher updated, but missing: update ProjectScanner, SessionParser, ErrorDetector, NotificationManager
- [ ] **Tab restoration** — Tabs re-open, but missing: validate project exists, load session detail, restore scroll position
- [ ] **IPC request tracking** — Responses return, but missing: context ID validation, abort on disconnect, timeout handling
- [ ] **Service dispose** — dispose() method exists, but missing: remove EventEmitter listeners, clear timers, close connections
- [ ] **Cache invalidation** — Cache cleared on switch, but missing: scope cache per context, invalidate on reconnect
- [ ] **Error handling** — Try/catch present, but missing: rollback state on failure, show user-friendly message, log to sentry
---
## Recovery Strategies
When pitfalls occur despite prevention, how to recover.
| Pitfall | Recovery Cost | Recovery Steps |
|---------|---------------|----------------|
| **Destructive switch lost state** | MEDIUM | Phase 2: Add persistent storage (localStorage) to survive restarts |
| **Listener leaks** | LOW | Add dispose tracking, expose `debug.listenerCount()` IPC for diagnosis |
| **Stale closure** | HIGH | Refactor service architecture to inject provider per call (breaking change) |
| **IPC race condition** | MEDIUM | Add context ID retroactively, reject responses with mismatched ID |
| **Timer leak** | LOW | DevTools audit: setInterval/clearInterval coverage, add cleanup tests |
| **SSH connection leak** | LOW | Add connection pool with max limit, force destroy after 30s timeout |
| **Tab validation missing** | MEDIUM | Add migration: filter invalid tabs on app startup |
| **Partial snapshot** | HIGH | Ship hotfix: capture full state, deprecate manual field list |
---
## Pitfall-to-Phase Mapping
How roadmap phases should address these pitfalls.
| Pitfall | Prevention Phase | Verification |
|---------|------------------|--------------|
| Destructive context switching | Phase 1 | Unit test: switch → switch back → assert state restored |
| EventEmitter listener accumulation | Phase 1 | Memory profiler: assert RSS stable after 10 switches |
| Stale closures | Phase 1 | Integration test: mock provider swap, assert service calls new provider |
| IPC race conditions | Phase 1 | E2E test: rapid connect/disconnect, assert no stale data |
| FileWatcher polling timer | Phase 1 | Unit test: call stop(), assert pollingTimer cleared |
| SSH connection disposal | Phase 1 | Integration test: assert socket.destroyed after disconnect |
| Tab restoration validation | Phase 2 | E2E test: open tabs → switch SSH → assert only valid tabs restored |
| Partial snapshot | Phase 1 | Integration test: snapshot → restore → assert detail populated |
---
## Sources
### Official Documentation
- [Electron IPC Documentation](https://www.electronjs.org/docs/latest/tutorial/ipc)
- [Electron ipcRenderer API](https://www.electronjs.org/docs/api/ipc-renderer)
- [Node.js Events API](https://nodejs.org/api/events.html)
### Electron State Management
- [Syncing State between Electron Contexts - Bruno Scheufler](https://brunoscheufler.com/blog/2023-10-29-syncing-state-between-electron-contexts)
- [Advanced Electron.js architecture - LogRocket Blog](https://blog.logrocket.com/advanced-electron-js-architecture/)
- [Zutron: Streamlined Electron State Management](https://github.com/goosewobbler/zutron)
- [Notes on Electron Processes, Context Isolation, and IPC](https://abstractentropy.com/notes-on-electron/)
### Memory Leaks and Cleanup
- [Diagnosing and Fixing Memory Leaks in Electron Applications](https://www.mindfulchase.com/explore/troubleshooting-tips/frameworks-and-libraries/diagnosing-and-fixing-memory-leaks-in-electron-applications.html)
- [Viacheslav Eremin | Memory Leaks in Electron application](https://www.vb-net.com/AngularElectron/MemoryLeaks.htm)
- [Error: Removing all listeners from ipcRenderer](https://github.com/electron/electron/issues/10379)
- [IPC in Electron - Ray](https://myray.app/blog/ipc-in-electron)
### React Stale Closures
- [Be Aware of Stale Closures when Using React Hooks](https://dmitripavlutin.com/react-hooks-stale-closures/)
- [How to Fix "Stale Closure" Issues in React Hooks](https://oneuptime.com/blog/post/2026-01-24-fix-stale-closure-issues-react-hooks/view)
- [React Stale Closure: Common Problems and Easy Solutions](https://www.dhiwise.com/post/react-stale-closure-common-problems-and-easy-solutions)
- [Hooks, Dependencies and Stale Closures | TkDodo's blog](https://tkdodo.eu/blog/hooks-dependencies-and-stale-closures)
### Zustand and State Management
- [Zustand - react state management made easy](https://graphqleditor.com/blog/zustand/)
- [Stores with React Context: Memory Leak Issue or Redux DevTools Bug?](https://github.com/pmndrs/zustand/discussions/2540)
- [In an ESModule, will not cleaning up subscriber result in a memory leak?](https://github.com/pmndrs/zustand/discussions/2054)
### VS Code Multi-Root Workspaces (Reference Architecture)
- [Adopting Multi Root Workspace APIs](https://github.com/microsoft/vscode/wiki/Adopting-Multi-Root-Workspace-APIs)
- [Multi-Root Workspaces in VS Code](https://code.visualstudio.com/docs/editing/workspaces/multi-root-workspaces)
- [Workspace Management: Multi-project VS Code Setup](https://www.mikul.me/blog/workspace-management-multi-project-vscode-setup)
### Dependency Injection and Service Lifecycle
- [Dependency injection guidelines - .NET](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection/guidelines)
- [Service lifetimes (dependency injection) - .NET](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection/service-lifetimes)
- [TSyringe: Lightweight dependency injection for TypeScript](https://github.com/microsoft/tsyringe)
---
*Pitfalls research for: Multi-context workspace switching in Electron + Zustand*
*Researched: 2026-02-12*

357
.planning/research/STACK.md
View file

@ -1,357 +0,0 @@
# Technology Stack: Multi-Context Workspace Management
**Domain:** Electron desktop app with SSH remote + local context switching
**Researched:** 2026-02-12
**Confidence:** HIGH
## Recommended Stack
### Core State Management Pattern
| Technology | Version | Purpose | Why Recommended |
|------------|---------|---------|-----------------|
| **Zustand persist middleware** | 4.x | State snapshot/restoration | Built-in hydration control (`skipHydration`, `rehydrate`), selective persistence via `partialize`, storage backend abstraction. Already in use. |
| **Context isolation per workspace** | Pattern | Independent workspace state | Each workspace (local + N SSH hosts) gets own Zustand store instance, snapshotted to storage, restored on context switch. |
| **Broadcast Channel API** | Native | Multi-window state sync | Native browser API for same-origin window messaging. VS Code Remote and Akiflow use this. Zero dependencies, straightforward implementation. |
| **Workspace registry in main process** | Pattern | Service lifecycle management | Main process owns workspace registry mapping `contextId → { store snapshot, service instances, connection state }`. IPC triggers context switches. |
### IPC Architecture
| Technology | Version | Purpose | Why Recommended |
|------------|---------|---------|-----------------|
| **ipcMain.handle / ipcRenderer.invoke** | Electron 28.x+ | Request/response IPC | Official Electron recommendation for async two-way IPC. Already in use. Type-safe with preload bridge. |
| **Workspace-scoped IPC channels** | Pattern | Context-aware requests | Prefix channels with contextId: `workspace:${contextId}:getSessions`. Main process routes to correct service instance. |
| **EventEmitter for status broadcasts** | Node.js native | Connection state events | Already used by SshConnectionManager. Extend pattern for workspace lifecycle events. |
### State Persistence
| Technology | Version | Purpose | Why Recommended |
|------------|---------|---------|-----------------|
| **Zustand persist → localStorage** | 4.x | Active workspace state | Fast synchronous access. Already configured. Each workspace gets namespaced key: `claude-devtools-workspace-${contextId}`. |
| **Zustand persist → IndexedDB** | 4.x (via idb-keyval) | Inactive workspace snapshots | Async storage for multiple workspace snapshots without localStorage quota limits. Zustand persist middleware supports custom storage backends. |
| **partialize for selective persistence** | Zustand built-in | Minimize storage overhead | Persist only domain data (projects, sessions, tabs), exclude transient UI state (loading flags, scroll positions). |
### Service Registry Pattern (Main Process)
| Component | Purpose | Implementation |
|-----------|---------|----------------|
| **WorkspaceRegistry** | Owns all workspace instances | `Map<contextId, WorkspaceContext>` where `WorkspaceContext = { provider: FileSystemProvider, services: ServiceInstances, lastAccessed: timestamp }` |
| **ServiceInstances** | Per-workspace service lifecycle | Each workspace gets own instances of ProjectScanner, SessionParser, FileWatcher, etc. Services use workspace-specific FileSystemProvider. |
| **Active workspace tracking** | Single active context at a time | `activeContextId: string`. IPC handlers route to `registry.get(activeContextId).services`. |
| **Lazy initialization** | Services created on first use | Registry initializes workspace services on connect (SSH) or app launch (local). Disposes inactive workspaces after TTL (e.g., 30min). |
### Context Switching Flow
| Phase | Mechanism | Rationale |
|-------|-----------|-----------|
| **1. Save current state** | `zustand.getState()` → IndexedDB | Snapshot entire store before switch. Non-blocking async operation. |
| **2. Broadcast workspace change** | `new BroadcastChannel('workspace-switch').postMessage({ contextId })` | Notify all renderer windows to update their UI for new context. |
| **3. Switch main process context** | `WorkspaceRegistry.setActive(contextId)` | Atomic switch of active FileSystemProvider + service instances. |
| **4. Restore target state** | IndexedDB → `zustand.setState()` | Hydrate store from snapshot. If no snapshot (new workspace), use empty initial state. |
| **5. Re-fetch live data** | `fetchProjects()`, `fetchRepositoryGroups()` | Refresh data from new context's file system. Already implemented in connectionSlice. |
## What NOT to Use
| Avoid | Why | Use Instead |
|-------|-----|-------------|
| **Zutron library** | Designed for syncing single store across main+renderer. We need multiple independent workspace stores. Adds unnecessary abstraction. | Direct Zustand persist + IPC for workspace switching. |
| **Redux/Redux Toolkit** | Overkill for context switching. Boilerplate-heavy. Zustand already in use and handles this elegantly with persist middleware. | Zustand with workspace-scoped stores. |
| **Global store with workspace slice** | Single store with `workspaces: { [id]: WorkspaceState }` scales poorly with large states, makes persistence complex, increases re-render surface. | Separate Zustand store instance per workspace. |
| **SharedWorker for multi-window** | More complex than BroadcastChannel, requires separate worker script, no tangible benefit for workspace switching use case. | BroadcastChannel API. |
| **Electron IPC for multi-window sync** | Round-trip through main process for window-to-window messaging is slower and more complex than BroadcastChannel. | BroadcastChannel for renderer-to-renderer, IPC for renderer-to-main. |
## Stack Patterns by Variant
### Pattern 1: Workspace Store Initialization
**When:** User switches to a workspace (SSH connect or local mode)
**Implementation:**
```typescript
// Renderer: Create workspace-scoped store
const createWorkspaceStore = (contextId: string) => {
return create<AppState>()(
persist(
(...args) => ({
...createProjectSlice(...args),
...createSessionSlice(...args),
// ... other slices
}),
{
name: `claude-devtools-workspace-${contextId}`,
storage: createJSONStorage(() => indexedDBStorage), // For inactive
partialize: (state) => ({
// Only persist domain data, not UI state
projects: state.projects,
sessions: state.sessions,
tabs: state.tabs,
// Exclude: loading, error, selectedIds
}),
skipHydration: true, // Manual hydration control
}
)
);
};
// After switch, manually rehydrate
await store.persist.rehydrate();
```
**Why:**
- `skipHydration: true` prevents auto-load on store creation, gives control over when to restore state
- `partialize` minimizes storage size, excludes transient state that shouldn't survive context switch
- IndexedDB storage for inactive workspaces avoids localStorage 5MB quota issues
### Pattern 2: Main Process Service Registry
**When:** Routing IPC calls to workspace-specific services
**Implementation:**
```typescript
// Main process
class WorkspaceRegistry {
private workspaces = new Map<string, WorkspaceContext>();
private activeContextId: string = 'local';
async initializeWorkspace(contextId: string, provider: FileSystemProvider) {
const context: WorkspaceContext = {
provider,
services: {
projectScanner: new ProjectScanner(provider),
sessionParser: new SessionParser(provider),
fileWatcher: new FileWatcher(provider),
// ... other services
},
lastAccessed: Date.now(),
};
this.workspaces.set(contextId, context);
}
getActiveServices(): ServiceInstances {
const context = this.workspaces.get(this.activeContextId);
if (!context) throw new Error('No active workspace');
return context.services;
}
setActive(contextId: string) {
this.activeContextId = contextId;
}
}
// IPC handler uses active workspace
ipcMain.handle('getProjects', async () => {
const services = workspaceRegistry.getActiveServices();
return services.projectScanner.scan();
});
```
**Why:**
- Services use FileSystemProvider interface → same code works for local + SSH
- Main process owns service lifecycle → renderer just calls IPC, doesn't manage connections
- Active workspace pattern → single source of truth for which context is current
### Pattern 3: Context Switch with State Preservation
**When:** User clicks "Switch to SSH" or "Switch to Local"
**Implementation:**
```typescript
// Renderer
async function switchWorkspace(newContextId: string) {
const currentStore = useStore.getState();
// 1. Save current workspace state to IndexedDB
const currentSnapshot = currentStore;
await saveWorkspaceSnapshot(currentContextId, currentSnapshot);
// 2. Broadcast switch event to other windows
const channel = new BroadcastChannel('workspace-switch');
channel.postMessage({ contextId: newContextId });
// 3. Tell main process to switch active context
await window.electronAPI.workspace.setActive(newContextId);
// 4. Restore target workspace state from IndexedDB
const targetSnapshot = await loadWorkspaceSnapshot(newContextId);
if (targetSnapshot) {
useStore.setState(targetSnapshot);
} else {
// New workspace: reset to initial state
useStore.setState(getInitialState());
}
// 5. Re-fetch live data from new context
await currentStore.fetchProjects();
await currentStore.fetchRepositoryGroups();
}
```
**Why:**
- State snapshot before switch → instant restoration when switching back
- BroadcastChannel → multi-window apps stay in sync
- Main process switch → IPC handlers route to correct services
- Re-fetch after restore → fresh data from new filesystem
### Pattern 4: Multi-Window Sync with BroadcastChannel
**When:** User has multiple app windows open, switches workspace in one window
**Implementation:**
```typescript
// Each renderer window listens
const channel = new BroadcastChannel('workspace-switch');
channel.onmessage = async (event) => {
const { contextId } = event.data;
// Don't process if this window initiated the switch
if (contextId === currentContextId) return;
// Update this window's state to match
await switchWorkspace(contextId);
};
// Send when switching
channel.postMessage({ contextId: newContextId });
```
**Why:**
- Native API, no library needed
- Same-origin by default → secure
- Simpler than IPC round-trip for window-to-window messaging
- VS Code Remote and Akiflow use this pattern
## Installation
### Core Dependencies (Already Installed)
```bash
# Already in package.json
zustand@4.x
electron@28.x
ssh2@latest # For SSH connections
```
### Additional Dependencies
```bash
# For IndexedDB storage backend
pnpm install idb-keyval
# No other dependencies needed - BroadcastChannel is native
```
## Architecture Best Practices
### Memory Management
- **Dispose inactive workspaces**: After 30min of inactivity, dispose service instances and FileSystemProvider. Keep snapshot in IndexedDB for instant restoration.
- **Limit snapshot count**: Keep max 5 workspace snapshots in IndexedDB. LRU eviction by `lastAccessed` timestamp.
- **Clear transient state on switch**: Don't persist loading flags, error messages, scroll positions → they're meaningless in restored context.
### Error Handling
- **Connection errors**: If SSH disconnects mid-session, auto-switch to local mode, preserve SSH workspace snapshot for reconnect.
- **Storage quota**: IndexedDB quota errors → warn user, fall back to localStorage for active workspace only, disable snapshot restoration.
- **Service initialization failures**: If workspace service init fails (e.g., remote path doesn't exist), show error banner but don't crash app. Allow manual retry.
### Performance Optimization
- **Debounced persistence**: Don't save snapshot on every state change. Debounce by 2-5 seconds, trigger on workspace blur.
- **Lazy service initialization**: Don't create all services on workspace init. Create ProjectScanner immediately, defer SessionParser until first session view.
- **Partial state updates**: When re-fetching after context switch, use `refreshSessionsInPlace` pattern (already implemented) to avoid flickering.
## TypeScript Patterns
### Workspace Context Type
```typescript
type WorkspaceContextId = `local` | `ssh-${string}`;
interface WorkspaceContext {
id: WorkspaceContextId;
provider: FileSystemProvider;
services: ServiceInstances;
lastAccessed: number;
connectionInfo?: {
host: string;
port: number;
username: string;
};
}
interface ServiceInstances {
projectScanner: ProjectScanner;
sessionParser: SessionParser;
fileWatcher: FileWatcher;
// ... other services
}
```
### Storage Backend Interface
```typescript
interface WorkspaceStorage {
getItem(key: string): Promise<string | null>;
setItem(key: string, value: string): Promise<void>;
removeItem(key: string): Promise<void>;
}
// IndexedDB implementation
const indexedDBStorage: WorkspaceStorage = {
getItem: async (key) => {
const value = await idbKeyval.get(key);
return value ?? null;
},
setItem: async (key, value) => {
await idbKeyval.set(key, value);
},
removeItem: async (key) => {
await idbKeyval.del(key);
},
};
```
## Version Compatibility
| Package | Version | Compatible With | Notes |
|---------|---------|-----------------|-------|
| zustand | 4.x | persist middleware 4.x | Persist middleware ships with zustand 4.x, no separate install |
| electron | 28.x+ | BroadcastChannel native | BroadcastChannel available in Chromium 54+ (Electron 1.x+) |
| idb-keyval | 6.x | TypeScript 5.x | Simple IndexedDB wrapper, 600 bytes minified |
| ssh2 | Latest | Node.js 18+ | Already in use for SSH connections |
## Confidence Levels
| Area | Confidence | Rationale |
|------|------------|-----------|
| **Zustand persist for state snapshotting** | HIGH | Official Zustand middleware, documented patterns for selective persistence and hydration control. Production-proven. |
| **BroadcastChannel for multi-window** | HIGH | Native browser API, used by VS Code Remote, Akiflow, and other Electron apps. Well-documented, zero dependencies. |
| **Service registry in main process** | HIGH | Standard Electron pattern for managing per-context resources. FileSystemProvider interface already supports this (SshFileSystemProvider vs LocalFileSystemProvider). |
| **IndexedDB for inactive snapshots** | MEDIUM | Zustand persist supports custom storage, idb-keyval is battle-tested, but no direct examples of multi-workspace Electron apps using this exact pattern. Low risk. |
| **Workspace TTL and eviction** | MEDIUM | Pattern is sound, but optimal TTL (30min) and max snapshots (5) are heuristics. May need tuning based on real-world usage. |
## Sources
### State Management
- [React State Management in 2025: Zustand vs. Redux vs. Jotai vs. Context](https://www.meerako.com/blogs/react-state-management-zustand-vs-redux-vs-context-2025)
- [React State Management 2025: Redux,Context, Recoil & Zustand](https://www.zignuts.com/blog/react-state-management-2025)
- [Zustand persist middleware documentation](https://zustand.docs.pmnd.rs/middlewares/persist)
- [Zustand persist - partialize option discussion](https://github.com/pmndrs/zustand/discussions/1273)
### Electron Multi-Window & IPC
- [Multiple Windows in Electron apps (2025)](https://blog.bloomca.me/2025/07/21/multi-window-in-electron.html)
- [Creating multi-window Electron apps using React portals](https://pietrasiak.com/creating-multi-window-electron-apps-using-react-portals)
- [Advanced Electron.js architecture - LogRocket Blog](https://blog.logrocket.com/advanced-electron-js-architecture/)
- [Electron IPC documentation](https://www.electronjs.org/docs/latest/tutorial/ipc)
- [Electron – 3 Methods for Inter Process Communications (IPC)](https://www.intertech.com/electron-3-methods-for-inter-process-communications-ipc/)
### BroadcastChannel Pattern
- [Multi-Window Messaging In Akiflow](https://akiflow.com/blog/multi-window-messaging-in-akiflow)
- [Creating a synchronized store between main and renderer process in Electron](https://www.bigbinary.com/blog/sync-store-main-renderer-electron)
- [BroadcastChannel API - 12 Days of Web](https://12daysofweb.dev/2024/broadcastchannel-api/)
### VS Code Architecture
- [Supporting Remote Development and GitHub Codespaces | Visual Studio Code Extension API](https://code.visualstudio.com/api/advanced-topics/remote-extensions)
- [VS Code 1.107 (November 2025 Update) Expands Multi-Agent Orchestration](https://visualstudiomagazine.com/articles/2025/12/12/vs-code-1-107-november-2025-update-expands-multi-agent-orchestration-model-management.aspx)
- [Behind the feature: building multi-account | Figma Blog](https://www.figma.com/blog/behind-the-feature-building-multi-account/)
### Electron State Management Libraries
- [Zutron: Streamlined Electron State Management](https://github.com/goosewobbler/zutron)
- [Syncing State between Electron Contexts - Bruno Scheufler](https://brunoscheufler.com/blog/2023-10-29-syncing-state-between-electron-contexts)
---
*Stack research for: Multi-context workspace management in Electron + Zustand*
*Researched: 2026-02-12*

320
.planning/research/SUMMARY.md
View file

@ -1,320 +0,0 @@
# Project Research Summary
**Project:** Multi-Context Workspace Management for claude-devtools
**Domain:** Electron desktop application with SSH remote + local context switching
**Researched:** 2026-02-12
**Confidence:** HIGH
## Executive Summary
Multi-context workspace switching in Electron desktop applications requires a careful balance of instant switching, comprehensive state preservation, and robust resource lifecycle management. Research across VS Code Remote, JetBrains Gateway, Slack, and Notion reveals that users demand sub-second context switches with zero data loss and continuous connection awareness. The recommended approach centers on three architectural pillars: (1) a ServiceContextRegistry pattern to maintain separate service instances per context, avoiding expensive teardown/recreation; (2) Zustand state snapshots with IndexedDB persistence for instant restoration; (3) BroadcastChannel API for multi-window synchronization, eliminating the complexity of IPC-based window coordination.
The critical insight from research is that "destructive switching" (clearing all state on context change) is the primary UX killer. Users switching between local and SSH contexts expect their open sessions, selected projects, tab layout, and scroll positions to be preserved per context. VS Code Remote and Slack demonstrate that this is achievable through snapshot-based state management with context validation—when switching back to SSH, the app should restore exactly where the user left off, not force re-navigation. The technology stack already in place (Zustand 4.x, Electron 28.x, ssh2) fully supports this pattern through persist middleware with selective hydration control and workspace-scoped storage keys.
The most dangerous pitfall identified is the combination of EventEmitter listener accumulation and stale closures capturing old FileSystemProvider references. After 5-10 context switches, memory leaks from orphaned listeners (FileWatcher polling timers, SSH connections, IPC subscriptions) can consume 50-100MB per switch while services continue calling methods on the wrong provider. Prevention requires explicit lifecycle management: every service must implement a `dispose()` method that clears timers, removes listeners, and closes connections, coupled with late-binding provider injection (getter pattern instead of constructor caching) to avoid closure staleness. The roadmap must address these lifecycle issues in Phase 1 before any user-facing features, as retrofitting proper cleanup after discovering production memory leaks is expensive and risky.
## Key Findings
### Recommended Stack
Research confirms that the existing stack (Zustand 4.x, Electron 28.x, ssh2) is well-suited for multi-context workspace management. The key addition is leveraging Zustand's persist middleware with IndexedDB storage (via idb-keyval) for inactive workspace snapshots, combined with BroadcastChannel API for multi-window synchronization. The ServiceContextRegistry pattern provides the architectural backbone—a main-process registry that owns service instances per context (local + N SSH hosts), eliminating expensive service recreation on every switch.
**Core technologies:**
- **Zustand persist middleware**: State snapshot/restoration per workspace with selective hydration control (`skipHydration`, `rehydrate`, `partialize`)—already in use, no new dependencies
- **ServiceContextRegistry pattern**: Map of contextId → ServiceContext (FileSystemProvider + service instances), provides `getActive()`, `switch()`, lifecycle management
- **BroadcastChannel API**: Native browser API for same-origin window messaging, used by VS Code Remote and Akiflow for multi-window state sync—zero dependencies
- **IndexedDB via idb-keyval**: Async storage for inactive workspace snapshots, avoids localStorage 5MB quota limits—only new dependency (600 bytes minified)
- **IPC workspace-scoped channels**: Prefix channels with contextId (`workspace:${contextId}:getSessions`) for context-aware request routing through main process registry
**Critical version requirements:**
- Zustand 4.x includes persist middleware (no separate install)
- Electron 28.x+ includes BroadcastChannel (native in Chromium 54+)
- idb-keyval 6.x compatible with TypeScript 5.x
**What NOT to use:**
- Zutron library (designed for syncing single store across main+renderer, not multiple independent workspace stores)
- Redux/Redux Toolkit (overkill for context switching, unnecessary boilerplate)
- Global store with workspace slice pattern (scales poorly, makes persistence complex)
### Expected Features
Multi-context applications have a clear division between table stakes (users will leave if missing) and differentiators (competitive advantage but not required). Research across VS Code Remote, JetBrains Gateway, Slack, Notion, Discord, and Figma establishes the feature baseline.
**Must have (table stakes):**
- **Visual workspace list with status** — users expect to see available workspaces at a glance (dropdown, sidebar, or command palette)
- **Saved connection profiles** — users refuse to re-enter SSH details (host, port, username) repeatedly
- **Recent connections list** — 80%+ of switches go to recent contexts (default 5-10 most recent)
- **Current workspace indicator** — users need persistent "where am I?" awareness (status bar or title bar badge)
- **Per-workspace state preservation** — context loss on switch = immediate frustration (open files, selections, scroll position, tabs, UI state)
- **Connection status indicators** — real-time online/connecting/offline/error states with distinct visual treatment
- **Loading indicators during switch** — delays without feedback feel like freezes (skeleton states or spinners)
- **Basic error handling** — clear messages with actionable guidance, not raw exceptions
- **Keyboard shortcut for switcher** — power users demand keyboard-driven workflows (Ctrl/Cmd+K pattern)
**Should have (competitive):**
- **Quick switcher with fuzzy search** — fastest method for 10+ workspaces (Cmd+K command palette pattern)
- **Auto-reconnect on network restore** — brief network blips shouldn't require manual reconnection (exponential backoff, max 6-10 retries)
- **Workspace color coding** — visual distinction reduces cognitive load (Discord/Slack pattern)
- **Connection health metrics** — latency, stability indicators provide proactive awareness
- **Activity notifications** — unread indicators per workspace, stay informed without switching
- **Context preview on hover** — reduce cognitive load by showing context before full switch (Slack's tab preview pattern)
**Defer (v2+):**
- **Parallel workspace windows** — advanced users want simultaneous multi-context view (HIGH complexity, resource isolation challenges)
- **Offline-first with sync queue** — continue working during network issues (HIGH complexity, requires conflict resolution)
- **Workspace groups/folders** — hierarchical organization only needed at 50+ workspaces
- **Context-aware AI suggestions** — predict next workspace based on patterns (HIGH complexity, requires ML infrastructure)
- **Workspace-specific keyboard shortcuts** — per-workspace customization (HIGH complexity, potential confusion)
**Explicitly avoid (anti-features):**
- Automatic workspace switching (destroys mental model)
- Unlimited parallel workspaces (resource exhaustion)
- Real-time sync of all state (network overhead, conflict complexity)
- Complex workspace hierarchies (cognitive overhead)
- Cross-workspace clipboard sync (security issue)
### Architecture Approach
The recommended architecture uses a ServiceContextRegistry pattern in the main process to manage multiple isolated service contexts, each with its own FileSystemProvider and service instances. This avoids expensive teardown/recreation on every switch and maintains separate caches per context. The renderer uses workspace-scoped Zustand stores with state snapshots captured in IndexedDB for instant restoration. IPC handlers are re-routed through the registry's `getActive()` method rather than using module-level service variables, eliminating the need for `reinitializeServiceHandlers()` on every switch.
**Major components:**
1. **ServiceContextRegistry (main)** — Central registry managing multiple ServiceContext instances (local + N SSH), provides `getActive()`, `switch()`, `register()`, handles lifecycle (start/stop watchers, dispose inactive contexts)
2. **ServiceContext (main)** — Encapsulates service instances for one context: ProjectScanner, SessionParser, SubagentResolver, DataCache, FileWatcher, plus FileSystemProvider reference—isolated state per context
3. **ContextSwitcher (renderer)** — Orchestrates context switches: captures current state snapshot, calls IPC to switch, restores target state from IndexedDB, triggers background data refresh
4. **StateSnapshot (renderer)** — Frozen copy of AppState per context (projects, sessions, selections, tabs, pane layout) with expiration timestamp (5-minute TTL)—instant restore if fresh, partial restore + re-fetch if stale
5. **IPC Context Handlers** — Expose `getCurrentContext()`, `switchContext(contextId)`, `listContexts()`, `getContextSnapshot(contextId)` via preload bridge
**Key architectural decisions:**
- Local context always stays alive (never disposed) for notifications and config updates
- Only active context's FileWatcher runs; inactive watchers are paused to conserve resources
- Snapshots stored with `contextId` + `expiresAt` to handle stale data (older than 5 minutes triggers background refresh)
- Each ServiceContext has its own DataCache to prevent cache pollution (local data appearing in SSH mode)
- BroadcastChannel syncs context switches across multiple app windows without IPC round-trips
### Critical Pitfalls
Research identified eight critical pitfalls that must be prevented from Phase 1. The most dangerous ones combine to create subtle bugs that manifest only after repeated context switches.
1. **Destructive context switching with incomplete state snapshots** — Current implementation calls `getFullResetState()` on SSH connect/disconnect, wiping all selections, open tabs, and loaded data. When switching back, users must re-navigate to their project and re-open sessions. **Fix:** Capture full AppState snapshot before switching, store in `Map<contextId, AppState>`, restore on switch. Phase 1 critical.
2. **EventEmitter listener accumulation on repeated switches** — FileWatcher, SshConnectionManager use `.on()` without cleanup, causing memory leaks (50-100MB per switch) and duplicate event emissions. **Fix:** Every service implements `dispose()` method with `removeAllListeners(channelName)` (never blank `removeAllListeners()` which breaks Electron IPC), track cleanup functions in registry. Phase 1 critical.
3. **Stale closures capturing old FileSystemProvider references** — Zustand actions and service methods capture provider at definition time. After SSH connect swaps provider, operations still hit old LocalFileSystemProvider. **Fix:** Use getter pattern (`getProvider()` on every operation) instead of constructor caching, or re-initialize services after provider swap. Phase 1 critical.
4. **IPC race conditions during context switch with in-flight requests** — User clicks Connect → IPC starts scanning remote projects → user clicks Disconnect → scan completes and populates store with SSH data in local mode. **Fix:** Include `contextId` UUID in every IPC request/response, validate `if (currentContextId !== response.contextId) return` before applying. Use AbortController to cancel in-flight requests on switch. Phase 1 critical.
5. **FileWatcher polling timer not cleared on SSH disconnect** — SSH mode uses `setInterval()` polling (5s). If error occurs in `stop()`, `clearInterval()` never runs, leaving orphaned timers. After 10 switches, 10 timers consume CPU. **Fix:** Always clear timers in `finally` block, defensive clearing before creating new timer. Phase 1 critical.
6. **SSH connection not properly disposed, keeping socket open** — `client.end()` is graceful but if SFTP channel is processing, socket stays open. After 10 switches, 10 SSH connections consume file descriptors. **Fix:** Call `sftp.end()` explicitly before `client.end()`, set 5s timeout and force `client.destroy()` if graceful close fails. Phase 1 critical.
7. **Tab state restoration without context validation** — Snapshot captures tabs with `projectId: "abc-local-path"`, user switches to SSH where projects have different IDs, restoration tries to open tab with local projectId → "Project not found" error. **Fix:** Validate restored tabs against `window.electronAPI.getProjects()`, close invalid tabs with user notification. Phase 2 priority.
8. **Partial snapshot creates inconsistent derived state** — Snapshot captures `selectedProjectId` but omits `sessionDetail`/`conversation`/`chunks`, restoration sets selection without data → UI renders empty or crashes on null access. **Fix:** Snapshot entire AppState except ephemeral flags (`loading`, `error`), restore atomically via `setState(() => snapshot)`. Phase 1 critical.
## Implications for Roadmap
Based on combined research, the roadmap must prioritize infrastructure over features. Six of eight critical pitfalls must be resolved in Phase 1 before any user-facing context switching is exposed—memory leaks, stale closures, and race conditions will cause production incidents if not addressed foundationally.
### Phase 1: Core Infrastructure (Foundation)
**Rationale:** Main process architecture and lifecycle management must be bulletproof before renderer integration. Memory leaks, stale closures, and race conditions cannot be retrofitted after user-facing features ship.
**Delivers:**
- ServiceContextRegistry in main process managing multiple ServiceContext instances
- IPC context API (getCurrentContext, switchContext, listContexts)
- Service lifecycle management: dispose() methods, EventEmitter cleanup, timer cleanup
- StateSnapshot system with capture/restore in renderer
- Context ID stamping for IPC request/response validation
**Addresses pitfalls:**
- #1 Destructive switching (snapshot system)
- #2 Listener accumulation (dispose methods)
- #3 Stale closures (getActive() pattern)
- #4 IPC race conditions (contextId stamping)
- #5 Timer leaks (finally block cleanup)
- #6 SSH connection leaks (explicit sftp.end() + timeout)
- #8 Partial snapshots (full AppState capture)
**Key features from FEATURES.md:**
- Per-workspace state preservation (table stakes)
- Saved connection profiles (table stakes)
**Build order:**
1. ServiceContext.ts + ServiceContextRegistry.ts (main)
2. IPC context handlers + preload API
3. stateSnapshot.ts + contextSlice.ts (renderer)
4. Service dispose() methods + cleanup tracking
**Research flag:** Standard patterns—ServiceContextRegistry uses established DI container patterns, Zustand persist is well-documented. No additional research needed.
### Phase 2: Basic UI Integration (MVP)
**Rationale:** With infrastructure stable, add minimal UI to expose context switching to users. Focus on table stakes features that users expect.
**Delivers:**
- ContextSwitcher UI component (dropdown or sidebar)
- Current workspace indicator in title bar/status bar
- Connection status indicators (online/connecting/offline/error)
- Loading states during switch
- Basic error handling with user-friendly messages
- Keyboard shortcut (Cmd/Ctrl+K) to open switcher
**Uses stack from STACK.md:**
- Zustand persist with IndexedDB (idb-keyval)
- BroadcastChannel for multi-window sync
**Implements architecture from ARCHITECTURE.md:**
- ContextSwitcher component
- useContextSwitch hook
**Addresses pitfall:**
- #7 Tab validation (validate restored tabs, close invalid)
**Key features from FEATURES.md:**
- Visual workspace list with status (table stakes)
- Recent connections list (table stakes)
- Current workspace indicator (table stakes)
- Connection status indicators (table stakes)
- Loading indicators (table stakes)
- Basic error handling (table stakes)
- Keyboard shortcut for switcher (table stakes)
**Research flag:** Standard patterns—workspace switcher UI follows VS Code/Slack patterns. Status indicators use established color-coding (green/yellow/red). No additional research needed.
### Phase 3: Enhanced UX (v1.x)
**Rationale:** After validating core switching works, add features that significantly improve UX based on user feedback and analytics. Only add when usage data shows need (10+ workspaces, frequent network blips).
**Delivers:**
- Quick switcher with fuzzy search (command palette pattern)
- Auto-reconnect with exponential backoff
- Workspace color coding for visual distinction
- Connection health metrics (latency, stability)
- Activity notifications (unread indicators)
- Context preview on hover
**Key features from FEATURES.md:**
- Quick switcher with fuzzy search (competitive)
- Auto-reconnect (competitive)
- Workspace color coding (competitive)
- Connection health metrics (competitive)
- Activity notifications (competitive)
- Context preview on hover (competitive)
**Research flag:** **Needs phase research** for fuzzy search algorithm (Fuse.js vs native), auto-reconnect retry strategies (exponential backoff parameters), and connection health monitoring implementation (latency measurement techniques).
### Phase 4: Advanced Capabilities (v2+)
**Rationale:** Defer high-complexity features until product-market fit is established and usage data justifies investment. Parallel windows and offline-first require significant architectural work and resource isolation.
**Delivers:**
- Parallel workspace windows (2-3 simultaneous)
- Offline-first with sync queue
- Workspace groups/folders (50+ workspace scale)
- Context-aware AI workspace suggestions
- Workspace-specific keyboard shortcuts
**Key features from FEATURES.md:**
- Parallel workspace windows (deferred)
- Offline-first with sync queue (deferred)
- Workspace groups (deferred)
- AI suggestions (deferred)
- Workspace-specific shortcuts (deferred)
**Research flag:** **Needs phase research** for parallel windows (resource isolation techniques, Chromium multi-process architecture), offline-first (conflict resolution strategies, operational transformation patterns), and AI suggestions (pattern recognition approaches, feature engineering for workspace switching).
### Phase Ordering Rationale
**Why Phase 1 before UI:**
- Memory leaks discovered in production are expensive to fix and damage user trust
- Stale closures cause subtle bugs that only appear after repeated switches (hard to debug)
- IPC race conditions lead to data corruption if not prevented architecturally
- ServiceContextRegistry is foundational—all subsequent phases depend on it
**Why Phase 2 focused on table stakes:**
- Users will abandon app if basic switching doesn't work smoothly
- Visual workspace list, status indicators, and error handling are MVP requirements
- Keyboard shortcuts are expected by power users (primary demographic)
- State preservation makes or breaks the UX—users switching contexts expect zero data loss
**Why Phase 3 deferred until validation:**
- Fuzzy search only matters at 10+ workspaces (analytics will show when threshold hits)
- Auto-reconnect can be implemented after observing real-world network patterns
- Color coding is nice-to-have, not essential for functionality
- Connection health metrics require telemetry infrastructure
**Why Phase 4 is v2+:**
- Parallel windows require Chromium multi-process expertise (HIGH complexity)
- Offline-first needs conflict resolution (HIGH complexity, many edge cases)
- Workspace groups only needed at significant scale (50+ workspaces)
- AI suggestions require ML infrastructure and training data
**Dependency chain:**
```
ServiceContextRegistry → IPC Context API → StateSnapshot → ContextSwitcher UI
↓
Service disposal → Listener cleanup → Timer cleanup
↓
Provider injection pattern → Stale closure prevention
↓
Context ID stamping → Race condition prevention
```
### Research Flags
**Phases needing deeper research during planning:**
- **Phase 3** — Fuzzy search algorithm selection, auto-reconnect retry strategies, connection health monitoring
- **Phase 4** — Parallel window resource isolation, offline-first conflict resolution, AI pattern recognition
**Phases with standard patterns (skip research-phase):**
- **Phase 1** — ServiceContextRegistry uses established DI patterns, Zustand persist is documented, EventEmitter cleanup is standard Node.js
- **Phase 2** — Workspace switcher UI follows VS Code/Slack patterns, status indicators use established conventions
## Confidence Assessment
| Area | Confidence | Notes |
|------|------------|-------|
| Stack | HIGH | Zustand persist middleware well-documented with official examples, BroadcastChannel used by VS Code Remote and Akiflow, ServiceContextRegistry pattern proven in Microsoft TSyringe and node-dependency-injection |
| Features | HIGH | Feature baseline verified across 6 major applications (VS Code, JetBrains, Slack, Notion, Discord, Figma) with consistent patterns, table stakes vs differentiators clearly delineated |
| Architecture | MEDIUM | ServiceContextRegistry pattern is sound and used in production systems, but no direct examples of multi-workspace Electron apps using this exact combination (Zustand + ServiceContext + BroadcastChannel). Low risk—components individually proven. |
| Pitfalls | HIGH | All 8 pitfalls documented with real-world examples (Electron GitHub issues, production bug reports), prevention strategies verified through official docs and battle-tested patterns |
**Overall confidence:** HIGH
### Gaps to Address
**Architecture validation:** No reference implementation combining Zustand persist + ServiceContextRegistry + BroadcastChannel for Electron multi-context switching. Each component individually proven, but integration is novel.
- **Handle during planning:** Build small proof-of-concept in Phase 1 (10-file mini-app) to validate integration before full implementation
- **Validation criteria:** Prove context switch completes in <100ms, no memory leaks after 50 switches, multi-window sync works
**IndexedDB snapshot expiration strategy:** Research provides 5-minute TTL heuristic, but optimal value depends on actual data refresh latency and user switching patterns.
- **Handle during planning:** Start with 5-minute TTL, add telemetry in Phase 2 to track snapshot age at restoration, adjust based on p95 latency
- **Validation criteria:** <5% of switches trigger full re-fetch (snapshot expired), user doesn't perceive staleness
**Parallel window resource limits:** Phase 4 defers parallel windows, but no research on optimal limit (2 windows? 5? 10?).
- **Handle during execution:** When implementing Phase 4, research Chromium per-process memory overhead, test with 2/3/5/10 windows, establish limit based on 8GB RAM baseline
- **Validation criteria:** Memory usage stays under 500MB per window, no UI jank with N windows open
**Auto-reconnect backoff parameters:** Research mentions exponential backoff and max 6-10 retries, but no specifics on initial delay or multiplier.
- **Handle during Phase 3 planning:** Research PubNub connection management docs (cited in PITFALLS.md sources), test with 1s initial, 2x multiplier, 10s max to match SSH timeout patterns
- **Validation criteria:** 90%+ of transient network blips recover within 30s, users rarely see manual reconnect prompt
## Sources
### Primary (HIGH confidence)
- [Electron Official Documentation](https://www.electronjs.org/docs/latest/) — IPC patterns, process model, security best practices
- [Zustand Persist Middleware](https://zustand.docs.pmnd.rs/middlewares/persist) — Hydration control, partialize, storage backends
- [VS Code Remote Development](https://code.visualstudio.com/docs/remote/remote-overview) — Context switching patterns, extension classification, workspace indexing
- [Slack Workspace Switching](https://slack.com/help/articles/1500002200741-Switch-between-workspaces) — Multi-workspace UX patterns, keyboard shortcuts
- [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/) — Workspace lifecycle, IDE backend management
- [Akiflow Multi-Window Messaging](https://akiflow.com/blog/multi-window-messaging-in-akiflow) — BroadcastChannel implementation patterns
### Secondary (MEDIUM confidence)
- [Advanced Electron.js Architecture - LogRocket](https://blog.logrocket.com/advanced-electron-js-architecture/) — Main process architecture, IPC best practices
- [Syncing State Between Electron Contexts - Bruno Scheufler](https://brunoscheufler.com/blog/2023-10-29-syncing-state-between-electron-contexts) — State synchronization patterns
- [React Stale Closures - Dmitri Pavlutin](https://dmitripavlutin.com/react-hooks-stale-closures/) — Stale closure prevention in React/Zustand
- [Diagnosing Memory Leaks in Electron - Mindful Chase](https://www.mindfulchase.com/explore/troubleshooting-tips/frameworks-and-libraries/diagnosing-and-fixing-memory-leaks-in-electron-applications.html) — EventEmitter leak patterns
### Tertiary (LOW confidence)
- [TSyringe - Microsoft DI Container](https://github.com/microsoft/tsyringe) — Dependency injection patterns for ServiceContextRegistry (used as inspiration, not direct implementation)
- [Connection Management - PubNub](https://www.pubnub.com/docs/general/setup/connection-management) — Auto-reconnect strategies (provides parameters for Phase 3)
---
*Research completed: 2026-02-12*
*Ready for roadmap: yes*

8
README.md
View file

@ -71,7 +71,12 @@ Define rules for when you want to be notified. Match on regex patterns, assign c
### :busts_in_silhouette: Team & Subagent Visualization
When Claude uses multi-agent orchestration, see the full picture. Teammate messages render as color-coded cards. Subagent sessions are expandable inline with their own execution traces, metrics, and tool calls.
Claude Code now spawns subagents via the Task tool and coordinates entire teams via `TeamCreate`, `SendMessage`, and `TaskUpdate`. In the terminal, all of this collapses into an unreadable stream. claude-devtools untangles it.
- **Subagent sessions** are resolved from Task tool calls and rendered as expandable inline cards — each with its own tool trace, token metrics, duration, and cost. Nested subagents (agents spawning agents) render as a recursive tree.
- **Teammate messages** — sent via `SendMessage` with color and summary metadata — are detected and rendered as distinct color-coded cards, separated from regular user messages. Each teammate is identified by name and assigned color.
- **Team lifecycle** is fully visible: `TeamCreate` initialization, `TaskCreate`/`TaskUpdate` coordination, `SendMessage` direct messages and broadcasts, shutdown requests and responses, and `TeamDelete` teardown.
- **Session summary** shows distinct teammate count separately from subagent count, so you can tell at a glance how many agents participated and how work was distributed.
### :zap: Command Palette & Cross-Session Search
@ -98,6 +103,7 @@ Open multiple sessions side-by-side. Drag-and-drop tabs between panes, split vie
| `Edited 2 files` | Inline diffs with added/removed highlighting per file |
| A three-segment context bar | Per-turn token attribution across 6 categories with compaction-phase tracking |
| Subagent output interleaved with the main thread | Isolated execution trees per agent, expandable inline with their own metrics |
| Teammate messages buried in session logs | Color-coded teammate cards with name, message, and full team lifecycle visibility |
| `--verbose` JSON dump | Structured, filterable, navigable interface — no noise |
---

2
electron-builder.yml
View file

@ -21,6 +21,8 @@ mac:
- zip
hardenedRuntime: true
gatekeeperAssess: false
entitlements: resources/entitlements.mac.plist
entitlementsInherit: resources/entitlements.mac.inherit.plist
notarize:
teamId: ${env.APPLE_TEAM_ID}
icon: resources/icons/mac/icon.icns

9
knip.json
View file

@ -4,14 +4,17 @@
"src/main/index.ts",
"src/preload/index.ts",
"src/renderer/main.tsx",
"electron.vite.config.ts"
"electron.vite.config.ts",
"remotion/index.ts",
"remotion/**/*.{ts,tsx}"
],
"project": ["src/**/*.{ts,tsx}!"],
"project": ["src/**/*.{ts,tsx}!", "remotion/**/*.{ts,tsx}!"],
"ignore": ["tsconfig*.json"],
"paths": {
"@main/*": ["./src/main/*"],
"@renderer/*": ["./src/renderer/*"],
"@preload/*": ["./src/preload/*"],
"@shared/*": ["./src/shared/*"]
}
},
"ignoreDependencies": ["remotion"]
}

1
package.json
View file

@ -47,6 +47,7 @@
"@dnd-kit/utilities": "^3.2.2",
"@fastify/cors": "^11.2.0",
"@fastify/static": "^9.0.0",
"@remotion/light-leaks": "4.0.421",
"@tanstack/react-virtual": "^3.10.8",
"date-fns": "^3.6.0",
"electron-updater": "^6.7.3",

23
pnpm-lock.yaml
View file

@ -26,6 +26,9 @@ importers:
'@fastify/static':
specifier: ^9.0.0
version: 9.0.0
'@remotion/light-leaks':
specifier: 4.0.421
version: 4.0.421(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
'@tanstack/react-virtual':
specifier: ^3.10.8
version: 3.13.18(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
@ -1147,6 +1150,12 @@ packages:
'@remotion/licensing@4.0.421':
resolution: {integrity: sha512-kSbssnwkTXDxtY/PXzu9Q6mFt9jmgNN6wygZxxH6gy01lzua1ucivSZOSrrdRRbtF0kk3BZ4EqOqW5D5ovyHXA==}
'@remotion/light-leaks@4.0.421':
resolution: {integrity: sha512-+udVz+5zvNBiYago7KJeO7BcQJrHUarFKWpcWtwhNHbwjaBAvtZ/UGzk9ZUG6wrsUdKtkDLKK2l8wH77etJDAw==}
peerDependencies:
react: '>=16.8.0'
react-dom: '>=16.8.0'
'@remotion/media-parser@4.0.421':
resolution: {integrity: sha512-Pv/63mN4gnG5hP2+7ldWy67u2FoIOmN3lijEzk3w/e4b5dvJp+kWcXGbUszePbDxFF0NnJrP4clj6iLLB0M9bw==}
@ -5709,14 +5718,14 @@ snapshots:
'@remotion/media-parser': 4.0.421
'@remotion/studio': 4.0.421(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
'@remotion/studio-shared': 4.0.421(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
css-loader: 5.2.7(webpack@5.105.0)
css-loader: 5.2.7(webpack@5.105.0(esbuild@0.25.0))
esbuild: 0.25.0
react: 18.3.1
react-dom: 18.3.1(react@18.3.1)
react-refresh: 0.9.0
remotion: 4.0.421(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
source-map: 0.7.3
style-loader: 4.0.0(webpack@5.105.0)
style-loader: 4.0.0(webpack@5.105.0(esbuild@0.25.0))
webpack: 5.105.0(esbuild@0.25.0)
transitivePeerDependencies:
- '@swc/core'
@ -5779,6 +5788,12 @@ snapshots:
'@remotion/licensing@4.0.421': {}
'@remotion/light-leaks@4.0.421(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
dependencies:
react: 18.3.1
react-dom: 18.3.1(react@18.3.1)
remotion: 4.0.421(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
'@remotion/media-parser@4.0.421': {}
'@remotion/media-utils@4.0.421(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
@ -7003,7 +7018,7 @@ snapshots:
shebang-command: 2.0.0
which: 2.0.2
css-loader@5.2.7(webpack@5.105.0):
css-loader@5.2.7(webpack@5.105.0(esbuild@0.25.0)):
dependencies:
icss-utils: 5.1.0(postcss@8.5.6)
loader-utils: 2.0.4
@ -9845,7 +9860,7 @@ snapshots:
dependencies:
js-tokens: 9.0.1
style-loader@4.0.0(webpack@5.105.0):
style-loader@4.0.0(webpack@5.105.0(esbuild@0.25.0)):
dependencies:
webpack: 5.105.0(esbuild@0.25.0)

14
resources/entitlements.mac.inherit.plist Normal file
View file

@ -0,0 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.cs.allow-jit</key>
<true/>
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
<true/>
<key>com.apple.security.cs.disable-library-validation</key>
<true/>
<key>com.apple.security.inherit</key>
<true/>
</dict>
</plist>

12
resources/entitlements.mac.plist Normal file
View file

@ -0,0 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.cs.allow-jit</key>
<true/>
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
<true/>
<key>com.apple.security.cs.disable-library-validation</key>
<true/>
</dict>
</plist>

4
src/main/http/index.ts
View file

@ -8,7 +8,7 @@
import { createLogger } from '@shared/utils/logger';
import { registerConfigRoutes } from './config';
import { broadcastEvent, registerEventRoutes } from './events';
import { registerEventRoutes } from './events';
import { registerNotificationRoutes } from './notifications';
import { registerProjectRoutes } from './projects';
import { registerSearchRoutes } from './search';
@ -61,5 +61,3 @@ export function registerHttpRoutes(
logger.info('All HTTP routes registered');
}
export { broadcastEvent };

2
src/main/index.ts
View file

@ -94,7 +94,7 @@ function wireFileWatcherEvents(context: ServiceContext): void {
context.fileWatcher.on('file-change', fileChangeHandler);
fileChangeCleanup = () => context.fileWatcher.off('file-change', fileChangeHandler);
// Wire todo-change events to renderer and HTTP SSE
// Forward checklist-change events to renderer and HTTP SSE (mirrors file-change pattern above)
const todoChangeHandler = (event: unknown) => {
if (mainWindow && !mainWindow.isDestroyed()) {
mainWindow.webContents.send('todo-change', event);

6
src/main/ipc/context.ts
View file

@ -7,9 +7,13 @@
* - context:switch - Switch to a different context
*/
import { CONTEXT_GET_ACTIVE, CONTEXT_LIST, CONTEXT_SWITCH } from '@preload/constants/ipcChannels';
import { createLogger } from '@shared/utils/logger';
// Channel constants (mirrored from preload/constants/ipcChannels.ts to respect module boundaries)
const CONTEXT_LIST = 'context:list';
const CONTEXT_GET_ACTIVE = 'context:getActive';
const CONTEXT_SWITCH = 'context:switch';
import type { ServiceContext, ServiceContextRegistry } from '../services';
import type { IpcMain } from 'electron';

20
src/main/ipc/ssh.ts
View file

@ -8,17 +8,17 @@
* - ssh:test - Test connection without switching
*/
import {
SSH_CONNECT,
SSH_DISCONNECT,
SSH_GET_CONFIG_HOSTS,
SSH_GET_LAST_CONNECTION,
SSH_GET_STATE,
SSH_RESOLVE_HOST,
SSH_SAVE_LAST_CONNECTION,
SSH_TEST,
} from '@preload/constants/ipcChannels';
import { createLogger } from '@shared/utils/logger';
// Channel constants (mirrored from preload/constants/ipcChannels.ts to respect module boundaries)
const SSH_CONNECT = 'ssh:connect';
const SSH_DISCONNECT = 'ssh:disconnect';
const SSH_GET_STATE = 'ssh:getState';
const SSH_TEST = 'ssh:test';
const SSH_GET_CONFIG_HOSTS = 'ssh:getConfigHosts';
const SSH_RESOLVE_HOST = 'ssh:resolveHost';
const SSH_SAVE_LAST_CONNECTION = 'ssh:saveLastConnection';
const SSH_GET_LAST_CONNECTION = 'ssh:getLastConnection';
import * as path from 'path';
import { configManager, ServiceContext } from '../services';

4
src/main/services/infrastructure/FileWatcher.ts
View file

@ -413,7 +413,9 @@ export class FileWatcher extends EventEmitter {
const fullPath = path.join(projectPath, entry.name);
try {
const observedSize =
typeof entry.size === 'number' ? entry.size : (await this.fsProvider.stat(fullPath)).size;
typeof entry.size === 'number'
? entry.size
: (await this.fsProvider.stat(fullPath)).size;
const lastSize = this.polledFileSizes.get(fullPath);
if (lastSize === undefined) {

6
src/main/services/infrastructure/NotificationManager.ts
View file

@ -77,11 +77,7 @@ const MAX_NOTIFICATIONS = 100;
const THROTTLE_MS = 5000;
/** Path to notifications storage file */
const NOTIFICATIONS_PATH = path.join(
os.homedir(),
'.claude',
'claude-devtools-notifications.json'
);
const NOTIFICATIONS_PATH = path.join(os.homedir(), '.claude', 'claude-devtools-notifications.json');
// =============================================================================
// NotificationManager Class

35
src/main/services/infrastructure/SshConnectionManager.ts
View file

@ -15,7 +15,7 @@ import { EventEmitter } from 'events';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import { Client, type ConnectConfig } from 'ssh2';
import { Client, type ConnectConfig, type SFTPWrapper } from 'ssh2';
import { LocalFileSystemProvider } from './LocalFileSystemProvider';
import { SshConfigParser } from './SshConfigParser';
@ -43,16 +43,6 @@ export interface SshConnectionConfig {
privateKeyPath?: string;
}
export interface SshConnectionProfile {
id: string;
name: string;
host: string;
port: number;
username: string;
authMethod: SshAuthMethod;
privateKeyPath?: string;
}
export interface SshConnectionStatus {
state: SshConnectionState;
host: string | null;
@ -154,21 +144,18 @@ export class SshConnectionManager extends EventEmitter {
});
// Open SFTP channel
const sftp = await new Promise<ReturnType<Client['sftp']> extends void ? never : never>(
(resolve, reject) => {
client.sftp((err, sftp) => {
if (err) {
reject(err);
return;
}
resolve(sftp as never);
});
}
);
const sftpChannel = await new Promise<SFTPWrapper>((resolve, reject) => {
client.sftp((err, channel) => {
if (err) {
reject(err);
return;
}
resolve(channel);
});
});
// Create SSH provider
// eslint-disable-next-line @typescript-eslint/no-explicit-any
this.provider = new SshFileSystemProvider(sftp as any);
this.provider = new SshFileSystemProvider(sftpChannel);
// Resolve remote ~/.claude/projects/ path
this.remoteProjectsPath = await this.resolveRemoteProjectsPath(config.username);

29
src/main/services/infrastructure/SshFileSystemProvider.ts
View file

@ -69,7 +69,10 @@ export class SshFileSystemProvider implements FileSystemProvider {
});
} catch (error) {
lastError = error;
if (this.classifySftpError(error) === 'transient' && attempt < SshFileSystemProvider.MAX_RETRIES) {
if (
this.classifySftpError(error) === 'transient' &&
attempt < SshFileSystemProvider.MAX_RETRIES
) {
await this.sleep(SshFileSystemProvider.RETRY_BASE_DELAY_MS * attempt);
continue;
}
@ -108,7 +111,10 @@ export class SshFileSystemProvider implements FileSystemProvider {
});
} catch (error) {
lastError = error;
if (this.classifySftpError(error) === 'transient' && attempt < SshFileSystemProvider.MAX_RETRIES) {
if (
this.classifySftpError(error) === 'transient' &&
attempt < SshFileSystemProvider.MAX_RETRIES
) {
await this.sleep(SshFileSystemProvider.RETRY_BASE_DELAY_MS * attempt);
continue;
}
@ -137,7 +143,15 @@ export class SshFileSystemProvider implements FileSystemProvider {
for (const item of list) {
const mode = item.attrs.mode;
entries.push(
this.buildDirent(item.filename, mode, S_IFMT, S_IFREG, S_IFDIR, item.attrs.size, item.attrs.mtime)
this.buildDirent(
item.filename,
mode,
S_IFMT,
S_IFREG,
S_IFDIR,
item.attrs.size,
item.attrs.mtime
)
);
}
resolve(entries);
@ -145,7 +159,10 @@ export class SshFileSystemProvider implements FileSystemProvider {
});
} catch (error) {
lastError = error;
if (this.classifySftpError(error) === 'transient' && attempt < SshFileSystemProvider.MAX_RETRIES) {
if (
this.classifySftpError(error) === 'transient' &&
attempt < SshFileSystemProvider.MAX_RETRIES
) {
await this.sleep(SshFileSystemProvider.RETRY_BASE_DELAY_MS * attempt);
continue;
}
@ -153,7 +170,9 @@ export class SshFileSystemProvider implements FileSystemProvider {
}
}
throw lastError instanceof Error ? lastError : new Error(`Failed to read directory: ${dirPath}`);
throw lastError instanceof Error
? lastError
: new Error(`Failed to read directory: ${dirPath}`);
}
createReadStream(filePath: string, opts?: ReadStreamOptions): Readable {

7
src/preload/index.ts
View file

@ -131,11 +131,8 @@ const electronAPI: ElectronAPI = {
ipcRenderer.invoke('get-subagent-detail', projectId, sessionId, subagentId),
getSessionGroups: (projectId: string, sessionId: string) =>
ipcRenderer.invoke('get-session-groups', projectId, sessionId),
getSessionsByIds: (
projectId: string,
sessionIds: string[],
options?: SessionsByIdsOptions
) => ipcRenderer.invoke('get-sessions-by-ids', projectId, sessionIds, options),
getSessionsByIds: (projectId: string, sessionIds: string[], options?: SessionsByIdsOptions) =>
ipcRenderer.invoke('get-sessions-by-ids', projectId, sessionIds, options),
// Repository grouping (worktree support)
getRepositoryGroups: () => ipcRenderer.invoke('get-repository-groups'),

3
src/renderer/api/httpClient.ts
View file

@ -91,7 +91,8 @@ export class HttpAPIClient implements ElectronAPI {
* serialization turns them into strings. This restores them so that
* `.getTime()` and other Date methods work in the renderer.
*/
private static readonly ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?$/;
// eslint-disable-next-line security/detect-unsafe-regex -- anchored pattern with bounded quantifier; no backtracking risk
private static readonly ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z?$/;
private static reviveDates(_key: string, value: unknown): unknown {
if (typeof value === 'string' && HttpAPIClient.ISO_DATE_RE.test(value)) {

2
src/renderer/components/common/ConnectionStatusBadge.tsx
View file

@ -32,7 +32,7 @@ export const ConnectionStatusBadge = ({
}
// SSH context - determine if this specific SSH context matches connected host
const isConnectedToThisHost = contextId === `ssh-${connectedHost}`;
const isConnectedToThisHost = connectedHost != null && contextId === `ssh-${connectedHost}`;
// If this SSH context doesn't match the connected host, treat as disconnected
const effectiveState = isConnectedToThisHost ? connectionState : 'disconnected';

36
src/renderer/components/settings/sections/ConnectionSection.tsx
View file

@ -287,10 +287,15 @@ export const ConnectionSection = (): React.JSX.Element => {
<div className="grid grid-cols-2 gap-3">
{/* Host input with combobox */}
<div className="relative">
<label className="mb-1 block text-xs" style={{ color: 'var(--color-text-muted)' }}>
<label
htmlFor="ssh-host"
className="mb-1 block text-xs"
style={{ color: 'var(--color-text-muted)' }}
>
Host
</label>
<input
id="ssh-host"
ref={hostInputRef}
type="text"
value={host}
@ -342,10 +347,15 @@ export const ConnectionSection = (): React.JSX.Element => {
)}
</div>
<div>
<label className="mb-1 block text-xs" style={{ color: 'var(--color-text-muted)' }}>
<label
htmlFor="ssh-port"
className="mb-1 block text-xs"
style={{ color: 'var(--color-text-muted)' }}
>
Port
</label>
<input
id="ssh-port"
type="text"
value={port}
onChange={(e) => setPort(e.target.value)}
@ -357,10 +367,15 @@ export const ConnectionSection = (): React.JSX.Element => {
</div>
<div>
<label className="mb-1 block text-xs" style={{ color: 'var(--color-text-muted)' }}>
<label
htmlFor="ssh-username"
className="mb-1 block text-xs"
style={{ color: 'var(--color-text-muted)' }}
>
Username
</label>
<input
id="ssh-username"
type="text"
value={username}
onChange={(e) => {
@ -374,6 +389,7 @@ export const ConnectionSection = (): React.JSX.Element => {
</div>
<div>
{/* eslint-disable-next-line jsx-a11y/label-has-associated-control -- SettingsSelect is a custom dropdown without a native control */}
<label className="mb-1 block text-xs" style={{ color: 'var(--color-text-muted)' }}>
Authentication
</label>
@ -387,10 +403,15 @@ export const ConnectionSection = (): React.JSX.Element => {
{authMethod === 'privateKey' && (
<div>
<label className="mb-1 block text-xs" style={{ color: 'var(--color-text-muted)' }}>
<label
htmlFor="ssh-private-key-path"
className="mb-1 block text-xs"
style={{ color: 'var(--color-text-muted)' }}
>
Private Key Path
</label>
<input
id="ssh-private-key-path"
type="text"
value={privateKeyPath}
onChange={(e) => setPrivateKeyPath(e.target.value)}
@ -403,10 +424,15 @@ export const ConnectionSection = (): React.JSX.Element => {
{authMethod === 'password' && (
<div>
<label className="mb-1 block text-xs" style={{ color: 'var(--color-text-muted)' }}>
<label
htmlFor="ssh-password"
className="mb-1 block text-xs"
style={{ color: 'var(--color-text-muted)' }}
>
Password
</label>
<input
id="ssh-password"
type="password"
value={password}
onChange={(e) => setPassword(e.target.value)}

14
src/renderer/components/settings/sections/GeneralSection.tsx
View file

@ -32,7 +32,10 @@ export const GeneralSection = ({
onGeneralToggle,
onThemeChange,
}: GeneralSectionProps): React.JSX.Element => {
const [serverStatus, setServerStatus] = useState<HttpServerStatus>({ running: false, port: 3456 });
const [serverStatus, setServerStatus] = useState<HttpServerStatus>({
running: false,
port: 3456,
});
const [serverLoading, setServerLoading] = useState(false);
const [copied, setCopied] = useState(false);
@ -44,9 +47,7 @@ export const GeneralSection = ({
const handleServerToggle = useCallback(async (enabled: boolean) => {
setServerLoading(true);
try {
const status = enabled
? await api.httpServer.start()
: await api.httpServer.stop();
const status = enabled ? await api.httpServer.start() : await api.httpServer.stop();
setServerStatus(status);
} catch {
// Status didn't change
@ -114,10 +115,7 @@ export const GeneralSection = ({
className="mb-2 flex items-center gap-3 rounded-md px-3 py-2.5"
style={{ backgroundColor: 'var(--color-surface-raised)' }}
>
<div
className="size-2 shrink-0 rounded-full"
style={{ backgroundColor: '#22c55e' }}
/>
<div className="size-2 shrink-0 rounded-full" style={{ backgroundColor: '#22c55e' }} />
<span className="text-xs font-medium" style={{ color: 'var(--color-text-secondary)' }}>
Running on
</span>

36
src/renderer/components/settings/sections/WorkspaceSection.tsx
View file

@ -171,10 +171,15 @@ export const WorkspaceSection = (): React.JSX.Element => {
>
<div className="grid grid-cols-2 gap-3">
<div>
<label className="mb-1 block text-xs" style={{ color: 'var(--color-text-muted)' }}>
<label
htmlFor="ws-profile-name"
className="mb-1 block text-xs"
style={{ color: 'var(--color-text-muted)' }}
>
Name
</label>
<input
id="ws-profile-name"
type="text"
value={formName}
onChange={(e) => setFormName(e.target.value)}
@ -184,10 +189,15 @@ export const WorkspaceSection = (): React.JSX.Element => {
/>
</div>
<div>
<label className="mb-1 block text-xs" style={{ color: 'var(--color-text-muted)' }}>
<label
htmlFor="ws-profile-host"
className="mb-1 block text-xs"
style={{ color: 'var(--color-text-muted)' }}
>
Host
</label>
<input
id="ws-profile-host"
type="text"
value={formHost}
onChange={(e) => setFormHost(e.target.value)}
@ -200,10 +210,15 @@ export const WorkspaceSection = (): React.JSX.Element => {
<div className="grid grid-cols-2 gap-3">
<div>
<label className="mb-1 block text-xs" style={{ color: 'var(--color-text-muted)' }}>
<label
htmlFor="ws-profile-port"
className="mb-1 block text-xs"
style={{ color: 'var(--color-text-muted)' }}
>
Port
</label>
<input
id="ws-profile-port"
type="text"
value={formPort}
onChange={(e) => setFormPort(e.target.value)}
@ -213,10 +228,15 @@ export const WorkspaceSection = (): React.JSX.Element => {
/>
</div>
<div>
<label className="mb-1 block text-xs" style={{ color: 'var(--color-text-muted)' }}>
<label
htmlFor="ws-profile-username"
className="mb-1 block text-xs"
style={{ color: 'var(--color-text-muted)' }}
>
Username
</label>
<input
id="ws-profile-username"
type="text"
value={formUsername}
onChange={(e) => setFormUsername(e.target.value)}
@ -228,6 +248,7 @@ export const WorkspaceSection = (): React.JSX.Element => {
</div>
<div>
{/* eslint-disable-next-line jsx-a11y/label-has-associated-control -- SettingsSelect is a custom dropdown without a native control */}
<label className="mb-1 block text-xs" style={{ color: 'var(--color-text-muted)' }}>
Authentication
</label>
@ -241,10 +262,15 @@ export const WorkspaceSection = (): React.JSX.Element => {
{formAuthMethod === 'privateKey' && (
<div>
<label className="mb-1 block text-xs" style={{ color: 'var(--color-text-muted)' }}>
<label
htmlFor="ws-profile-private-key-path"
className="mb-1 block text-xs"
style={{ color: 'var(--color-text-muted)' }}
>
Private Key Path
</label>
<input
id="ws-profile-private-key-path"
type="text"
value={formPrivateKeyPath}
onChange={(e) => setFormPrivateKeyPath(e.target.value)}

28
src/renderer/hooks/useContextSwitch.ts
View file

@ -1,28 +0,0 @@
/**
* useContextSwitch - Hook for context switching actions.
*
* Thin wrapper exposing context switch functionality to components.
*/
import { useCallback } from 'react';
import { useStore } from '../store';
export function useContextSwitch() {
const switchContext = useStore((state) => state.switchContext);
const isContextSwitching = useStore((state) => state.isContextSwitching);
const activeContextId = useStore((state) => state.activeContextId);
const handleSwitch = useCallback(
async (targetContextId: string) => {
await switchContext(targetContextId);
},
[switchContext]
);
return {
switchContext: handleSwitch,
isContextSwitching,
activeContextId,
};
}

8
src/renderer/services/contextStorage.ts
View file

@ -99,7 +99,7 @@ async function saveSnapshot(contextId: string, snapshot: ContextSnapshot): Promi
async function loadSnapshot(contextId: string): Promise<ContextSnapshot | null> {
try {
const key = `${STORAGE_KEY_PREFIX}${contextId}`;
const stored = await get(key);
const stored = await get<StoredSnapshot>(key);
if (!stored) {
return null;
@ -148,15 +148,15 @@ async function deleteSnapshot(contextId: string): Promise<void> {
async function cleanupExpired(): Promise<void> {
try {
const allKeys = await keys();
const snapshotKeys = allKeys.filter((k) =>
typeof k === 'string' ? k.startsWith(STORAGE_KEY_PREFIX) : false
const snapshotKeys = allKeys.filter(
(k): k is IDBValidKey & string => typeof k === 'string' && k.startsWith(STORAGE_KEY_PREFIX)
);
const now = Date.now();
for (const key of snapshotKeys) {
try {
const stored = await get(key);
const stored = await get<StoredSnapshot>(key);
if (stored) {
const age = now - stored.timestamp;
if (age > SNAPSHOT_TTL_MS) {

2
test/renderer/store/sessionSlice.test.ts
View file

@ -41,6 +41,7 @@ describe('sessionSlice', () => {
expect(mockAPI.getSessionsPaginated).toHaveBeenCalledWith('project-1', null, 20, {
includeTotalCount: false,
prefilterAll: false,
metadataLevel: 'deep',
});
expect(store.getState().sessions).toHaveLength(2);
expect(store.getState().sessionsCursor).toBe('cursor-1');
@ -211,6 +212,7 @@ describe('sessionSlice', () => {
expect(mockAPI.getSessionsPaginated).toHaveBeenCalledWith('project-1', null, 20, {
includeTotalCount: false,
prefilterAll: false,
metadataLevel: 'deep',
});
// Should not have set loading state
expect(store.getState().sessionsLoading).toBe(false);