feat(desktop): add Workbench/Review mode + group tabs + workspace navigation sidebar

Merged
AN
10mo ago
+10221-1806

Happy Path Demo

Happy Paths Demo

Summary

This PR bundles several related features for the desktop app:

  1. Workbench/Review Mode - A workspace-level view mode toggle:

    • Workbench mode: Mosaic panes layout with terminals + file viewers side-by-side
    • Review mode: Dedicated Changes page for focused code review
  2. Configurable Workspace Navigation - A setting to choose between:

    • Top bar: Horizontal tabs (current behavior)
    • Sidebar: Vertical list grouped by project (Linear/GitHub Desktop style)
  3. Configurable Group Tabs Position - A setting to control where terminal group tabs appear:

    • Sidebar (default): Full-featured ModeCarousel with TabsView (rename, reorder, presets)
    • Content header: Compact horizontal GroupStrip

Also includes:

  • "Mark as Unread" / "Mark as Read" context menu for workspaces with auto-clear and undo
  • Configurable terminal file link behavior (open in file viewer vs external editor)
  • Inline file editing in FileViewerPane with ⌘+S save
  • Improved sidebar mode layout: "Open In" and "Workbench/Review" controls moved to content header

Design decisions & future direction:

  • Terminal group tabs position and workspace navigation are independently configurable for backward compatibility. The recommended UX pairs the workspace sidebar with sidebar group tabs—we can unify these as the default once we're confident in the pattern and deprecate the separate toggles.
  • The only visual "breaking" change is relocating the "Open In" control. The branch name it displayed is already visible in two other places in the app shell, so no information is lost.
  • The Workbench/Review mode split is transitional. As we improve inline diff viewing in the workbench, we expect to merge these modes—making workbench the single default with integrated review capabilities.

Part 1: Workbench/Review Mode

Why

Users need to view code, diffs, and docs while keeping terminals visible in the same window. The existing Changes page is great for focused review, but doesn't support in-flow work where you want terminals and file viewers side-by-side.

What / How

Introduces a workspace-level Workbench | Review view mode toggle:

  • Workbench mode: Mosaic panes layout with terminals + file viewers for in-flow work. Clicking a file in the sidebar opens a FileViewer pane next to your terminals.
  • Review mode: Dedicated Changes page for focused code review (existing behavior preserved).

Key implementation details:

  1. ViewModeToggle - Prominent segmented control in workspace header for switching modes
  2. FileViewerPane - New pane type with Raw/Rendered/Diff view modes, lock/unlock (prevents file replacement), and split support
  3. GroupStrip - Group switching strip above Mosaic content (when group tabs position is "content-header")
  4. Unified sidebar - Full ChangesView in both modes; in Workbench, file clicks trigger onFileOpen callback to open FileViewer panes
  5. workspace-view-mode store - Per-workspace persistence via Zustand + localStorage
  6. readWorkingFile tRPC - Safe file reads with size cap (2MB) and binary detection
  7. MRU pane reuse - File clicks reuse most-recently-used unlocked FileViewer pane; locked panes are preserved
  8. ⌘+T behavior - In Review mode, switches to Workbench first, then creates terminal

Inline Editing Support

FileViewerPane supports full editing in both Raw and Diff modes:

  • Raw mode - Monaco Editor with syntax highlighting
  • Diff mode - Editing enabled on the modified side of the diff viewer
  • ⌘+S to save - Standard keyboard shortcut saves changes to disk
  • Dirty state tracking - Orange dot (●) indicator before filename when unsaved changes exist
  • Editable badge - Shows "⌘S" hint (changes to "Saving..." during save operation)
  • Auto-refresh - Queries invalidated after save to keep UI in sync
  • Unsaved changes protection - Switching between Raw/Diff modes with unsaved changes shows a dialog with options to Cancel, Discard & Switch, or Save & Switch (with loading state during save)

Security Hardening

File Viewer file operations include robust symlink escape protection:

  • Centralized security module: New security/ folder with path validation, secure fs, and git command wrappers
  • Centralized read security: secureFs.readFile() and readFileBuffer() enforce symlink-escape checks internally
  • ENOENT handling: Writes through non-existent paths validate parent directory chain (detects dangling symlinks pointing outside worktree)
  • Distinct error codes: symlink-escape reason returned separately from outside-worktree for precise error handling
  • Fail-closed behavior: All validation errors default to blocking the operation
  • SafeImage for markdown: Only renders embedded data: URLs in markdown images; blocks http/https (tracking pixels), file:// (local file access), and relative paths (traversal attacks)

Configurable Terminal File Link Behavior

Added a global setting to control how Cmd+clicking file paths in the terminal behaves:

  • Setting location: Settings → Behavior → "Terminal file links"
  • Options:
    • "External editor" (default) - Opens file in configured external editor
    • "File viewer" - Opens file in the in-app FileViewerPane
  • Uses ref pattern to avoid terminal recreation when setting changes
  • Setting changes apply immediately without terminal restart
  • Line/column support - Terminal links with file:line:col format navigate to the correct position in File Viewer

Part 2: Workspace Navigation Sidebar

Architecture

  • Persisted setting: Navigation style stored in SQLite via settings.navigationStyle column
  • Shared hook pattern: useWorkspaceShortcuts extracts keyboard shortcuts (⌘1-9) and auto-create logic shared between both modes
  • Zustand state: Sidebar width, collapsed projects, and open state persisted with zustand/persist
  • Lazy data loading: GitHub PR status loaded on hover to avoid N+1 queries

How it works

  1. User selects "Top bar" or "Sidebar" in Settings → Behavior
  2. MainScreen queries the setting and conditionally renders:
    • Top bar mode: WorkspacesTabs in the header (current behavior)
    • Sidebar mode: ResizableWorkspaceSidebar on the left + simplified TopBar
  3. Both modes share the same keyboard shortcuts via useWorkspaceShortcuts hook

Sidebar Mode Layout Improvements

In sidebar navigation mode, the "Open In" button and "Workbench/Review" toggle have been moved from the TopBar down to the ContentHeader:

Before:

TopBar:        [◧] │ Project / workspace-name │ [Open ▾] [Workbench│Review] [👤]
ContentHeader: [☰] │ [Group1 ×] [Group2 ×] [+]

After:

TopBar:        [◧] │ Project / workspace-name │ [👤]
ContentHeader: [☰] │ [Group1 ×] [Group2 ×] [+] │ [Open ▾] [Workbench│Review]

This keeps the profile dropdown at the top while placing workspace controls closer to the content they affect. The controls are visible in both:

  • Workbench mode: With group tabs (when position is "content-header")
  • Review mode: Without group tabs (just the controls)

Top-bar navigation mode is unchanged.

Key decisions

DecisionChoiceRationale
Sidebar typeNew dedicated sidebarAvoids complexity of reusing ModeCarousel
State storageZustand + localStorageMatches existing sidebar patterns
Collapsed projectsstring[] not Set<string>JSON serialization for persist middleware
Diff stats sourcegetGitHubStatus on hoverAvoids N+1 queries, lazy load pattern
TopBar in sidebar modeShow project/workspace nameMaintains context without tabs
Controls placement (sidebar mode)ContentHeaderKeeps controls near content, profile at top

New Components

WorkspaceSidebar

  • WorkspaceSidebar.tsx - Main sidebar component
  • WorkspaceSidebarHeader.tsx - "Workspaces" title header
  • WorkspaceSidebarFooter.tsx - "Add project" button
  • ResizableWorkspaceSidebar.tsx - Wrapper with resize handle

ProjectSection

  • ProjectSection.tsx - Collapsible project group with workspaces
  • ProjectHeader.tsx - Project name, color dot, collapse toggle

WorkspaceListItem

  • WorkspaceListItem.tsx - Individual workspace row with lazy-loaded PR data
  • WorkspaceStatusBadge.tsx - PR status badge (open/merged/closed/draft)
  • WorkspaceDiffStats.tsx - Additions/deletions display

Shared

  • useWorkspaceShortcuts.ts - Shared hook for ⌘1-9 shortcuts and auto-create logic
  • workspace-sidebar-state.ts - Zustand store for sidebar UI state

Part 3: Mark as Unread/Read for Workspaces

Right-click any workspace (in top bar tabs or sidebar) to toggle its "unread" state. This is a workspace-level feature, separate from pane-level agent notifications.

How it works

  1. "Mark as Unread" - Sets workspace.isUnread = true in SQLite database
  2. Red pulsing indicator - Shows on the workspace tab/list item when unread
  3. Auto-clear on switch - When you click to switch to an unread workspace:
    • The unread state is automatically cleared
    • An undo toast appears for 5 seconds: "Marked as read" with Undo button
    • Clicking Undo restores the unread state
  4. "Mark as Read" - Explicitly clear the unread state via context menu

Why workspace-level instead of pane-level?

Previously, "Mark as Unread" set needsAttention: true on all panes in the workspace, causing:

  • ❌ Every tab and pane showing attention indicators (visual clutter)
  • ❌ Semantic confusion (manual reminder ≠ agent output needing attention)
  • ❌ Tedious to clear (had to visit every pane)

The new approach:

  • ✅ Single indicator on the workspace only
  • ✅ Clean semantic separation: workspace.isUnread (manual reminder) vs pane.needsAttention (agent notifications)
  • ✅ Indicator shows if either workspace is manually unread OR any pane has agent attention

Why SQLite instead of Zustand/localStorage?

We store isUnread in SQLite rather than in-memory state for two key reasons:

  1. Persistence across app restarts - Users expect "mark as unread" to survive closing and reopening the app, similar to email clients and Slack. SQLite data persists to disk automatically.

  2. Workspace is a database entity - The workspaces table already exists in SQLite with other workspace metadata. Adding isUnread as a column keeps related data together and avoids split-brain between SQLite and localStorage.

Implementation details

  • New isUnread column in workspaces table (migration: 0007_add_workspace_is_unread.sql)
  • New workspaces.setUnread tRPC mutation
  • setActive mutation now returns wasUnread and auto-clears + invalidates queries
  • Context menu shows "Mark as Read" or "Mark as Unread" based on current state

Part 4: Configurable Group Tabs Position

Why

The initial implementation of this PR moved group tabs from the sidebar (via ModeCarousel + TabsView) to the content header (GroupStrip). This was unintended—the original sidebar behavior should be the default to match the main branch.

What

A new setting allows users to choose where terminal group tabs appear:

  • Sidebar (default): Full ModeCarousel with swipeable Tabs/Changes modes
    • TabsView has rename, drag-and-drop reorder, and terminal presets
    • Matches original behavior on main branch
  • Content header: Compact horizontal GroupStrip
    • Simpler UI, fewer features
    • Good for users who want more sidebar space for changes

How it works

  1. User selects position in Settings → Behavior → "Group tabs position"
  2. Setting stored in SQLite via settings.groupTabsPosition column
  3. Sidebar and ContentView query the setting and render conditionally:
    • Sidebar: Shows ModeCarousel (sidebar position) or just ChangesView (content-header position)
    • ContentView: Shows GroupStrip only when position is "content-header"
  4. Review mode always shows ChangesView regardless of setting (never shows tabs)

Key decisions

DecisionChoiceRationale
Default value"sidebar"Matches main branch behavior, minimizes breaking change
Feature parityNOT requiredTabsView and GroupStrip serve different UX needs
Review modeAlways ChangesViewReview mode requires file list to function
StorageSQLite settingFollows existing navigationStyle pattern

Keyboard Shortcuts

ShortcutAction
⌘⇧BToggle workspace sidebar (sidebar mode only)
⌘BToggle files sidebar
⌘1-9Switch to workspace N (works in both modes)
⌘← / ⌘→Previous/next workspace (works in both modes)

Manual Test Checklist

Workbench/Review Mode

  • Toggle between Workbench/Review modes
  • File clicks open FileViewer panes in Workbench
  • ⌘+T switches to Workbench from Review mode
  • FileViewer Raw/Rendered/Diff modes work
  • Lock/unlock and split pane work
  • GroupStrip switches between groups (when position is "content-header")
  • Edit files in Raw mode and save with ⌘+S
  • Edit files in Diff mode and save with ⌘+S
  • Dirty indicator appears when changes are unsaved
  • Switching modes with unsaved changes shows confirmation dialog
  • "Save & Switch" saves then switches (dirty indicator clears)
  • "Discard & Switch" discards changes and switches
  • "Cancel" stays in current mode

Terminal Link Behavior

  • Settings → Behavior shows "Terminal file links" dropdown
  • Default is "External editor" (existing behavior preserved)
  • With "External editor": Cmd+click file path → opens in external editor
  • With "File viewer": Cmd+click file path → opens FileViewerPane
  • With "File viewer": Cmd+click file:line:col → opens at correct line/column (Known issue - see below)
  • Changing setting applies immediately (no terminal restart needed)
  • Setting persists after app restart

Security (Symlink Escape Protection)

(Skipped - requires manual symlink setup)

Navigation Style Setting

  • Setting persists across app restarts
  • Changing setting immediately switches layout
  • Default is "Top bar" for new installs

Group Tabs Position Setting

  • Settings → Behavior shows "Group tabs position" dropdown
  • Default is "Sidebar" for new installs
  • "Sidebar" position: ModeCarousel with Tabs/Changes modes appears in sidebar
  • "Sidebar" position: Can swipe between Tabs and Changes views
  • "Sidebar" position: TabsView features work (rename, reorder, presets)
  • "Sidebar" position: No GroupStrip in content header
  • "Content header" position: GroupStrip appears in content header
  • "Content header" position: Sidebar shows only ChangesView
  • Changing setting immediately updates UI (no restart needed)
  • Setting persists after app restart
  • In Review mode, groups are NEVER shown (regardless of setting)
  • Works correctly with both "Top bar" and "Sidebar" navigation styles

Sidebar Mode

  • Sidebar renders with correct width (default 280px)
  • Sidebar is resizable between 220-400px
  • Resize persists across restarts
  • ⌘⇧B toggles sidebar visibility
  • Projects are collapsible
  • Collapsed state persists
  • Active workspace has left border indicator
  • Hover shows keyboard shortcut (⌘1-9)
  • PR status/diff stats load on hover (worktree workspaces)
  • "Add project" button works

Sidebar Mode Layout

  • In sidebar mode, "Open In" and "Workbench/Review" controls appear in ContentHeader (not TopBar)
  • Profile dropdown remains in TopBar
  • Controls visible in Workbench mode (with group tabs when position is "content-header")
  • Controls visible in Review mode (without group tabs)
  • Changes sidebar toggle (☰) works in both Workbench and Review modes
  • Top-bar navigation mode is unchanged (controls remain in TopBar)

Top Bar Mode

  • Existing tab behavior unchanged
  • No workspace sidebar visible
  • ⌘⇧B does nothing (correct)

Keyboard Shortcuts (Both Modes)

  • ⌘1-9 switches to correct workspace
  • ⌘← / ⌘→ navigates workspaces
  • Auto-create main workspace still works

Mark as Unread/Read Feature

  • Right-click workspace in top bar shows context menu
  • Right-click workspace in sidebar shows context menu
  • "Mark as Unread" shows red pulsing indicator on workspace only (not on every tab)
  • "Mark as Read" clears the indicator
  • Switching to unread workspace shows "Marked as read" toast with Undo button
  • Clicking Undo in toast restores the unread state
  • Unread state persists after app restart
  • Works for both worktree and branch workspaces
  • Works in both top bar and sidebar navigation modes
  • Pane-level agent attention indicators still work independently

Known Issues

  • Unsaved changes lost on group/workspace switch - Switching between groups or workspaces while a FileViewer has unsaved changes will discard those changes without warning. The unsaved changes dialog currently only protects Raw↔Diff mode switches within the same pane. Follow-up needed to add protection for group and workspace navigation.

  • Terminal file links don't navigate to line/column - Cmd+clicking a file path with line:column format (e.g., src/file.ts:42:10) opens the file but doesn't navigate to the specified line/column. Will fix in follow-up PR.


Future Work

  • Keyboard shortcut for mode toggle - Add ⌘+\ or similar to toggle between Workbench/Review
  • Migrate to workspaceId-based APIs - Accept workspaceId instead of worktreePath in renderer calls
  • Reconsider FileViewer lock/unlock UX - The current lock mechanism (to prevent MRU pane reuse) works but may not be discoverable. Consider alternatives like VS Code's preview mode (single-click = preview, double-click = pin), or auto-locking on edit, or a more prominent visual distinction between locked/unlocked states.

Files Changed

New Files (Workbench/Review)

  • GroupStrip/GroupStrip.tsx - Group switching strip component
  • FileViewerPane/FileViewerPane.tsx - File viewer with Raw/Rendered/Diff modes + inline editing
  • FileViewerPane/UnsavedChangesDialog.tsx - Confirmation dialog for unsaved changes on mode switch
  • ChangesView/components/ViewModeToggle/ViewModeToggle.tsx - Segmented control for mode toggle
  • TopBar/WorkspaceControls/ViewModeToggleCompact.tsx - Compact version for content header
  • workspace-view-mode.ts - Per-workspace view mode store
  • 0004_add_terminal_link_behavior_setting.sql - Migration for terminal link behavior setting

New Files (Security)

  • security/index.ts - Security module exports
  • security/path-validation.ts - Path validation utilities with symlink escape detection
  • security/secure-fs.ts - Secure filesystem operations
  • security/git-commands.ts - Secure git command wrappers
  • SafeImage/SafeImage.tsx - Secure image component for markdown (only allows data: URLs)

New Files (Workspace Sidebar)

  • apps/desktop/src/renderer/hooks/useWorkspaceShortcuts.ts
  • apps/desktop/src/renderer/stores/workspace-sidebar-state.ts
  • apps/desktop/src/renderer/screens/main/components/TopBar/WorkspaceSidebarControl.tsx
  • apps/desktop/src/renderer/screens/main/components/TopBar/WorkspaceControls/ - New folder with OpenInMenuButton and WorkspaceControls
  • apps/desktop/src/renderer/screens/main/components/WorkspaceSidebar/* (10 files)
  • packages/local-db/drizzle/0005_add_navigation_style.sql

New Files (Mark as Unread)

  • packages/local-db/drizzle/0007_add_workspace_is_unread.sql - Migration for isUnread column

New Files (Group Tabs Position)

  • packages/local-db/drizzle/0008_add_group_tabs_position.sql - Migration for groupTabsPosition column
  • apps/desktop/plans/20260104-1916-restore-group-tabs-sidebar.md - Implementation plan

New Files (Database)

  • packages/local-db/drizzle/0006_add_unique_branch_workspace_index.sql - Migration to dedupe existing branch workspaces and add unique index (one branch workspace per project)

New Files (Hooks)

  • useWorkspaceDeleteHandler.ts - Shared hook for workspace delete/close dialog state

Deleted Files

  • WorkspaceActionBar/WorkspaceActionBar.tsx - Removed (controls moved to TopBar/ContentHeader)
  • WorkspaceActionBar/components/WorkspaceActionBarLeft/ - Removed
  • WorkspaceActionBar/components/WorkspaceActionBarRight/ - Renamed to TopBar/WorkspaceControls/OpenInMenuButton.tsx

Modified Files

  • file-contents.ts - Added readWorkingFile procedure
  • ContentView/index.tsx - Routes to TabsContent or ChangesContent based on mode; conditional GroupStrip based on position setting
  • ContentHeader/ContentHeader.tsx - Added trailingAction prop for right-side controls
  • ChangesView.tsx - Added onFileOpen callback prop
  • Sidebar/index.tsx - Conditional ModeCarousel vs ChangesView based on position setting
  • WorkspaceView/index.tsx - View mode reactivity and ⌘+T behavior
  • tabs/store.ts - Removed old markWorkspaceAsUnread (now uses tRPC)
  • tabs/types.ts - Removed markWorkspaceAsUnread from interface
  • shared/tabs-types.ts - Added file-viewer pane type
  • Terminal/helpers.ts - Refactored to accept onFileLinkClick callback
  • Terminal/Terminal.tsx - Wired up terminal link behavior setting
  • BehaviorSettings.tsx - Added terminal link behavior, navigation style, and group tabs position dropdowns
  • settings/index.ts (tRPC) - Added getters/setters for all new settings
  • schema.ts / zod.ts (local-db) - Added isUnread column to workspaces, groupTabsPosition to settings
  • workspaces.ts (tRPC) - Added setUnread mutation, updated setActive to auto-clear and return wasUnread
  • useSetActiveWorkspace.ts - Added undo toast for auto-cleared unread state
  • WorkspaceItemContextMenu.tsx - Now uses tRPC mutation, shows Read/Unread toggle
  • WorkspaceItem.tsx - Uses workspace-level isUnread for indicator
  • WorkspaceGroup.tsx - Passes isUnread to WorkspaceItem
  • WorkspaceListItem.tsx - Uses workspace-level isUnread for indicator
  • ProjectSection.tsx - Passes isUnread to WorkspaceListItem
  • TopBar/index.tsx - Conditional rendering based on navigation style; WorkspaceControls only in top-bar mode
  • TopBar/WorkspaceTabs/index.tsx - Refactored to use shared hook
  • MainScreen/index.tsx - Wire up sidebar and navigation style
  • shared/constants.ts - Added DEFAULT_NAVIGATION_STYLE and DEFAULT_GROUP_TABS_POSITION
  • shared/hotkeys.ts - Added TOGGLE_WORKSPACE_SIDEBAR, renamed TOGGLE_SIDEBAR

Summary by CodeRabbit

  • New Features

    • File viewer pane (raw/rendered/diff) with editing, save flow, unsaved-changes dialog; resizable Workspaces sidebar, workspace list items, group strip, and workspace controls.
    • Terminal link behavior setting to open file links in external editor or in the file viewer.
    • SafeImage for rendering Markdown images.
  • Security

    • Stricter worktree/path validation and secure filesystem/git helpers to prevent traversal and symlink escapes.
  • Improvements

    • Per‑workspace view modes (workbench/review), unread indicators, updated hotkeys, and refined top bar/controls for accessibility.

✏️ Tip: You can customize this high-level summary in your review settings.