feat(desktop,cli): remove empty sidebar folders

CO
15d ago
+3586-7

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 a and b renders 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.list read. A workspace:changed event can create a partial cached list first, and that does not count.
  • Project lists get the same full-read rule. A project:changed event before the first project.list does 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.pruneEmptyFolders mutation. 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-folders on 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: GlobalSidebarRequests runs the purge and replies, checking the organization again.
  • An old desktop app (404) or an old host (no sidebar procedure) 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.
  • yankee and xray: one workspace tagged with both. It renders in yankee, and xray shows zero members but still owns its tag.

Every run below started from a window reload with the window not focused:

  1. Menu shows "Remove 1 empty folder". Clicked it: perf gone. docs, yankee, xray kept. Workspace tags before and after: alpha-one=docs alpha-two=docs pane-test=xray, yankee.
  2. Tagged alpha-two qa from the CLI, collapsed the qa folder in the UI, set its tag back to docs.
  3. superset workspaces folders prune --dry-run → would remove qa.
  4. superset workspaces folders prune --json → removed: [qa], skipped: [], failed: []. Sidebar: docs, yankee, xray. Tags unchanged.
  5. Dry run again → "Would remove 0 empty folders."
  6. After the review fixes (head 6e4526e6), repeated 2 to 5 with a new folder qa4: same result. Then again with qa5 through the button: toast "Removed 1 empty folder", docs, yankee, xray kept.

Before (empty perf folder under alpha-web):

before

Menu:

menu

After (menu stays open while it runs, now "No empty folders"):

after

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 lint and bun run typecheck pass (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 prune command, 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.