feat(dashboard): opt-in sort control for the Projects zone

[schubydoo]

What

Adds an opt-in sort control to the dashboard's Projects zone — a Name / Last used / Cost dropdown. It defaults to the existing A–Z order and never reorders on its own; only an explicit non-name choice reorders the list (most-recent / highest-cost first; projects with no recorded history sink to the bottom) and reveals every project. The default-name path is byte-identical to today.

Closes #298.

How

• Backend: new read-only GET /api/projects/sortmeta — a batch endpoint returning {name: {last_used, cost_usd}} for every discovered project, sourced from the session-history rollup (db/stores.py rollup_for). Runs off the event loop via asyncio.to_thread; catches only infra errors (DB engine / IO) so a genuine bug surfaces as a 500 rather than a silently-empty sort (the client already falls back to name order on any non-OK response).
• Frontend (Alpine): client-side reorder via CSS order — no DOM moves, so x-show and the Jinja idx cap stay intact. New state projectSort / sortMeta / projectRanks; recomputeProjectRanks() builds the order map (whole-object assignment, reactive-safe per test(e2e): TS-1 e2e maturity slice + fix live-log frame drop #310/fix(ui): stop the hosted live-view dropping frames + repaint through the proxy #315); projectVisible() shows the full list when a sort is active (the 6-row cap governs only the default name order).

Note on the stale "blocked" label

The issue body and its 2026-06-21 triage note say blocked by #308 / #363. That prose is stale: #363 merged via #514 (2026-06-23), so the last_used / total_cost_usd rollup this builds on exists. #308 is the open umbrella Epic, not a true blocker for this slice. Verified against git/gh, not the doc.

a11y trade-off

CSS order reorders visually only — DOM / tab / screen-reader order stays A–Z even when the list is visually sorted. This is deliberate for an opt-in cosmetic sort (a DOM reorder is the anti-pattern the Active zone avoids) and is called out in a code comment by the :style binding.

Tests

• New /api/projects/sortmeta route tests (shape + all projects, null fields, degrade-to-empty on an infra error, literal-path-beats-name-route) plus a dashboard-render test asserting the select, its options, and the projectSort default.
• Full suite green locally — 98.28% coverage (≥96% gate). Reviewed against clauster's frontend and safety invariants (auth-gating, validate-before-use, fail-closed-but-surface-bugs, Alpine scope/reactivity, Tabler .list-group-flush separators under CSS order, XSS via the project-name regex).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

Adds an opt-in sort control (Name / Last used / Cost) to the Projects zone. The backend exposes a new GET /api/projects/sortmeta endpoint returning per-project rollup keys; the frontend reorders rows via CSS order (no DOM moves) using Alpine reactive state.

• Backend: new read-only /api/projects/sortmeta route placed before the {name}/\u2026 wildcard, validated through is_valid_project_name, offloaded with asyncio.to_thread, and degrades to {} on OSError/SQLAlchemyError. create_app always assigns a real SessionRunner before any route captures it, so the inner _collect closure is safe.
• Frontend: projectSort / sortMeta / projectRanks state added; whole-object assignment on projectRanks is Alpine-reactive-safe per test(e2e): TS-1 e2e maturity slice + fix live-log frame drop #310/fix(ui): stop the hosted live-view dropping frames + repaint through the proxy #315; loadSortMeta() is lazy \u2014 fetched only on the first (and each subsequent) non-name selection, ensuring ranks reflect the latest history.
• Tests: four new route tests cover shape, literal-path precedence, infra-error degradation, and dashboard-render assertions.

Confidence Score: 5/5

Safe to merge. The backend endpoint is read-only, correctly auth-gated, and degrades gracefully. The frontend sort is purely cosmetic with no mutation paths.

All changed paths are additive and read-only. The backend route is correctly ordered before the wildcard, offloaded safely to a thread, and fails closed to an empty dict. The Alpine state changes are isolated to the Projects zone with no cross-zone side effects. The one identified issue (newly created projects sinking under a non-name sort) is a cosmetic edge case that does not affect data integrity or crash the page.

No files require special attention. The _dashboard_script.html note about newly-created projects getting order:9999 is worth tracking as a follow-up.

Important Files Changed

Filename	Overview
src/clauster/app.py	Adds GET /api/projects/sortmeta — well-placed before the {name}/… wildcard route, guarded by is_valid_project_name, offloaded via asyncio.to_thread, and degrades to {} on OSError/SQLAlchemyError. runner is always non-None inside create_app (replaced at line 283).
src/clauster/templates/_dashboard_script.html	Adds projectSort/sortMeta/projectRanks state plus loadSortMeta/recomputeProjectRanks/projectOrderRank. Whole-object assignment on projectRanks is Alpine-reactive-safe. Newly created projects won't appear in PROJECT_NAMES and therefore get order:9999 when a non-name sort is active.
src/clauster/templates/_project_row.html	Adds :style CSS order binding for non-name sorts. p.name is HTML-escaped by Jinja autoescape, used only as a dict key inside projectOrderRank — no XSS surface. a11y trade-off (visual-only reorder) is explicitly documented in comment.
src/clauster/templates/dashboard.html	Adds sort select with correct x-model/@change wiring; hides 'Show all' button when non-name sort is active; wraps list-group-flush in display:flex when sorting. CSS order reorder of list-group-flush separators is called out in PR description as a reviewed trade-off.
tests/test_app_routes.py	Four new tests: shape/all-projects, literal-path-beats-name-route, infra-error degrades to {}, and dashboard render asserts. All use plain TestClient (no lifespan wrap), which is correct for synchronous GET routes per the custom rule.
.changeset/298-projects-sort.md	Changeset marking this as a minor release. Accurate description of the feature.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant User
    participant Alpine as Alpine (dashboard)
    participant API as GET /api/projects/sortmeta
    participant DB as SessionHistoryStore

    User->>Alpine: select Last used or Cost
    Note over Alpine: x-model sets projectSort, @change fires
    Alpine->>API: fetch /api/projects/sortmeta
    API->>DB: asyncio.to_thread rollup_for x N projects
    DB-->>API: name to last_used and cost_usd per project
    API-->>Alpine: JSON dict or empty on error
    Alpine->>Alpine: "sortMeta = response"
    Alpine->>Alpine: recomputeProjectRanks builds projectRanks map
    Alpine->>Alpine: CSS order applied per row
    Note over Alpine: Visual reorder, no DOM moves

    User->>Alpine: select Name A-Z
    Alpine->>Alpine: recomputeProjectRanks clears projectRanks
    Note over Alpine: CSS order removed, default A-Z restored

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant User
    participant Alpine as Alpine (dashboard)
    participant API as GET /api/projects/sortmeta
    participant DB as SessionHistoryStore

    User->>Alpine: select Last used or Cost
    Note over Alpine: x-model sets projectSort, @change fires
    Alpine->>API: fetch /api/projects/sortmeta
    API->>DB: asyncio.to_thread rollup_for x N projects
    DB-->>API: name to last_used and cost_usd per project
    API-->>Alpine: JSON dict or empty on error
    Alpine->>Alpine: "sortMeta = response"
    Alpine->>Alpine: recomputeProjectRanks builds projectRanks map
    Alpine->>Alpine: CSS order applied per row
    Note over Alpine: Visual reorder, no DOM moves

    User->>Alpine: select Name A-Z
    Alpine->>Alpine: recomputeProjectRanks clears projectRanks
    Note over Alpine: CSS order removed, default A-Z restored

Loading

_{Reviews (2): Last reviewed commit: "feat(dashboard): opt-in sort control for..." | Re-trigger Greptile}