feat(desktop,cli): remove empty sidebar folders
What & why
Adds "Remove N empty folders" to the sidebar Projects menu, and superset workspaces folders prune to the CLI. Both remove stored folder rows whose tag no workspace carries anymore.
Fixes #8834.
Why? Folders I colored or collapsed stay in the sidebar after their workspaces are archived. Plain derived folders go away on their own. Stored ones do not. Many of mine come from agents through the CLI, so the cleanup needs a CLI path too.
What counts as empty:
- No workspace in the folder's scope carries its tag, on any host or in the cloud.
- Zero members shown is not enough. A workspace tagged
aandbrenders in one folder, and the other folder still owns the tag, so it stays. - Legacy rows (no tag) and hidden folders are never touched.
What it removes: the local v2SidebarSections row and the host tag_folder_settings row for that scope and tag. It never calls deleteSection, so no workspace is untagged and the lane is not renumbered. Host deletes are awaited, so each folder's result is honest.
When unsure, skip:
- A scope is purged only when every source answered in this window. That means the host roster, the cloud list, the local host, and every host serving the scope. A snapshot, a failed read or an offline host keeps its folders.
- A host's list counts only after a full
workspace.listread. Aworkspace:changedevent can create a partial cached list first, and that does not count. - Project lists get the same full-read rule. A
project:changedevent before the firstproject.listdoes not count. - A project scope also needs every host to have answered
project.list, so a folder is never reported removed while its host setting stays behind. - When a prune starts, sources that are not live are refetched first, with a 5 s limit. After a reload the roster comes back from the persisted cache and is not refetched until the window gets focus, which is the normal case for a CLI run from an outside terminal.
- If PostHog flags can never load (no key, init failed, blocked), cloud workspaces count as not applicable instead of waiting forever. Only a flags request still in flight holds the cloud list back.
- Each folder is checked again against the latest data right before its host deletes and before its row delete. One that changed meanwhile sends no deletes and is reported skipped (
noLongerEmpty). - If the window switches organization mid-prune, it stops before the next delete and reports the rest as skipped (
organizationChanged). Row deletes always go to the starting organization. - Skipped folders carry a reason, shown in the toast and in a NOTE column in the CLI.
CLI path: the folders are renderer state, so the request goes the same way pane layout ops do.
- host-service: new
sidebar.pruneEmptyFoldersmutation. Callers on this machine only (relay callers get FORBIDDEN), needs an attached desktop app, and sends the host's organizationId. - desktop main:
POST /sidebar/prune-empty-folderson the bridge and a small broker. It only hands the request to a window whose active organization matches, never to another org's window. No match is a 412 with a clear message. - renderer:
GlobalSidebarRequestsruns the purge and replies, checking the organization again. - An old desktop app (404) or an old host (no
sidebarprocedure) gives an "update the desktop app" error. All tRPC changes are additive.
useHostWorkspaces now exposes per-host read state and roster freshness, and useCloudWorkspaces exposes isLive. Both are additive.
How I tested it
Unit tests cover:
- The detector: multi-tag folders, legacy and hidden rows, and sandbox hosts.
- The skip rules for each unanswered source: partial cached list, project discovery pending and failed, Sessions with no active host, flags never loading versus still loading.
- The refetch before a prune: a restored roster refetches and the folder is removed. A failed or hung refetch still skips.
- The host-service router (local only, relay refused) and the CLI command.
Each regression test fails on the code before its fix.
Commands: bun run lint (clean), bun run typecheck (clean), bun run check:i18n (clean). Test counts: apps/desktop full suite 8665 pass / 0 fail, packages/cli 447 pass, packages/shared 1444 pass, host-service sidebar router 6 pass. 4 new strings, translated in every locale.
End to end in the dev app (setup.local.sh + bun run dev), driven over CDP with real clicks, CLI from this branch. Setup under alpha-web and Marketing-site:
perf: a stored folder (colored, collapsed) whose tag nothing carries anymore.docs: holds two workspaces.yankeeandxray: one workspace tagged with both. It renders inyankee, andxrayshows zero members but still owns its tag.
Every run below started from a window reload with the window not focused:
- Menu shows "Remove 1 empty folder". Clicked it:
perfgone.docs,yankee,xraykept. Workspace tags before and after:alpha-one=docs alpha-two=docs pane-test=xray, yankee. - Tagged alpha-two
qafrom the CLI, collapsed theqafolder in the UI, set its tag back todocs. superset workspaces folders prune --dry-runāwould remove qa.superset workspaces folders prune --jsonāremoved: [qa],skipped: [],failed: []. Sidebar:docs,yankee,xray. Tags unchanged.- Dry run again ā "Would remove 0 empty folders."
- After the review fixes (head 6e4526e6), repeated 2 to 5 with a new folder
qa4: same result. Then again withqa5through the button: toast "Removed 1 empty folder",docs,yankee,xraykept.
Before (empty perf folder under alpha-web):
Menu:
After (menu stays open while it runs, now "No empty folders"):
Notes:
- #8045 hides interaction-materialized folders once empty. This is the explicit cleanup for stored ones. They should work fine together.
- #8826 (project name order, also mine) touches the same sort menu. Whichever lands second needs a small rebase. I will do it.
- No MCP tool for this yet. Happy to add one as a follow-up.
- If PostHog hits its flags quota, it never marks flags loaded, so cloud-scoped folders would keep skipping. Safe, but worth knowing.
Checklist
- PR title follows conventional commits (
type(scope): subject) -
bun run lintandbun run typecheckpass (CI fails on lint warnings too) - "Allow edits from maintainers" is checked on fork PRs
š¤ Generated with Claude Code
Summary by CodeRabbit
- New Features
- Added a sidebar option to remove empty workspace folders, with results showing folders removed, skipped, or failed.
- Added the
superset workspaces folders prunecommand, with project filtering and a dry-run option. - Folder cleanup rechecks folders before removal and reports cases where data is unavailable or a folder is no longer empty.
- Documentation
- Documented the CLI command and its options.
- Translations
- Added folder-cleanup messages in multiple languages.