feat(cli): manage client-owned sidebar groups

KI
4mo ago
+2498-252

Summary

  • add superset sidebar list, group create/rename/delete/collapse/expand, and workspace move/ungroup commands
  • persist sidebar layout as client-owned state scoped by organization and user, independent of resource hosts
  • synchronize the same versioned state between the bundled CLI and Electron through atomic file writes, file watching, and revision checks
  • migrate existing renderer local state safely, including the CLI-first / Electron-closed case
  • keep pane layouts and other workspace-local fields outside the sidebar state document
  • document the client/host ownership boundary and the real bun dev CLI-to-CDP workflow

Architecture

A host can serve multiple clients, so it does not own their presentation preferences. State lives at:

<SUPERSET_HOME_DIR>/client-state/<organizationId>/<userId>/sidebar.json

The CLI reads and writes this client store directly. Electron main exposes the same store to its renderer over IPC and watches atomic renames. Host services remain responsible only for project/workspace resource lookup; this PR has no sidebar event-bus, acknowledgement, or host tRPC bridge.

Writes are serialized with a short-lived file lock. Renderer replacements use revision compare-and-swap so a stale window cannot overwrite a newer CLI mutation. Existing localStorage is merged once; CLI-first writes remain pending migration until Electron opens.

UX and compatibility

Names resolve by exact case-insensitive match while stable IDs remain available for automation. Ambiguous names fail with candidate IDs. Deleting a group ungroups its workspaces and never deletes them. Commands work while the Electron renderer is closed; resource-name lookup still requires the local host service.

The first Electron launch migrates existing sidebar rows. The persisted format is versioned, and organization/user scoping prevents two clients on one host from accidentally sharing layout.

Validation

  • bun run lint
  • bun run typecheck — 36/36 package tasks
  • 16 focused reducer, file-store, migration, concurrency, name-resolution, renderer synchronization, and pane-preservation tests
  • bun run test:cli-e2e — 8/8 assertions, 9 commands
  • real root bun dev bundled CLI against Electron CDP on final commit 83ec66e6e
    • healthy host status
    • create group and move workspace
    • visible expanded/collapsed group state
    • close renderer, rename through CLI with no CDP page target, reopen, and restore group/workspace
    • verified versioned client-state file and zero leftover lock/temp files
    • cleaned up only the temporary group

Local evidence: test-results/cli-cdp/cli-sidebar-final-20260721-090415/ contains machine-readable CLI/CDP assertions, persisted-state snapshot, screenshots, and a 15.5s H.264 CDP screencast.

Summary by CodeRabbit

  • New Features

    • Added sidebar workspace groups for organizing workspaces within projects.
    • Groups can be created, renamed, collapsed, expanded, moved, and deleted.
    • Added CLI commands to list sidebar state and manage groups and workspace placement.
    • Sidebar layout now persists across desktop and CLI sessions, including after restarts.

  • Bug Fixes

    • Deleting a group preserves its workspaces by returning them to the ungrouped project area.
    • Improved handling of ambiguous project, workspace, and group names.

  • Documentation

    • Added CLI reference and end-to-end guidance for sidebar group management.