Files
pipelines/app/notes/empty-server-states.md
T
alan dbd525a7b1 Clarify empty server states
Show calm, actionable empty states for pipelines, runs, and chats while keeping filtered and failed loads distinct. Add focused widget coverage and document the remaining verification limits.
2026-11-12 01:02:31 +00:00

62 lines
3.4 KiB
Markdown

# Empty-server states (Pipelines, Runs, Chat)
On a brand-new server (no pipelines, runs or chats) the healthy empty reply
should read as "nothing here yet" with the next step, not as a filter problem
or a missing list. Real failures keep their error treatment and never show the
empty copy.
## Changed states
| Destination | Before (empty, healthy server) | After |
| --- | --- | --- |
| Pipelines list | "No pipelines are defined on this server." | "No pipelines yet." + "Create one from a template in Templates." |
| Runs list | "No runs found." + "Try changing or clearing the filters." | "No runs yet." + "Start one from Pipelines and its runs appear here." |
| Runs list, filter hides every run | (same as above) | unchanged: "No runs found." + filter hint |
| Chat list | "No chat sessions on this server yet." | "No chats yet. Use New chat to start one." |
Source: `lib/features/pipelines/pipeline_filter.dart`,
`lib/features/pipelines/widgets/pipeline_list_panel.dart` (renders the new
`PipelineEmptyState.detail` line), `lib/features/runs/ui/runs_list.dart`,
`lib/features/chat/ui/sessions/chat_sessions_body.dart`.
Unchanged error paths: a failed Pipelines list shows its error banner with
Retry; a failed Runs list shows the error with Retry; a failed chat load hides
the empty message and shows the reason.
## Focused results
Command (from `app/`): `tool/memwatch/full.sh 'test/features/pipelines/pipelines_empty_server_test.dart test/features/pipelines/pipeline_filter_test.dart test/features/pipelines/pipelines_screen_filter_test.dart test/features/runs/ui/runs_list_widget_test.dart test/features/chat/ui/sessions/chat_sessions_screen_test.dart test/features/chat/ui/sessions/chat_ios_material_test.dart'`
- Before the source change (new and updated expectations): 18 passed, 6 failed,
as expected on the old copy. The new test file also failed to compile
(missing `Key` import), fixed before the rerun.
- After the change: PASS, 25 passed, 0 failed, peak 1484 MB, 5s.
- Review fix (runs must-fix): the no-runs state now also requires an empty
free-text query, so an empty server with a search query shows "No runs
found." with the filter hint. Covered by a new widget test in
`runs_list_widget_test.dart`. Focused rerun of that file: PASS, 6 passed,
0 failed, peak 768 MB, 4s.
- `tool/analyze.sh`: clean (rerun after the review fix).
New or extended coverage:
- `test/features/pipelines/pipelines_empty_server_test.dart`: empty server shows
the no-pipelines state and next step, with no spinner, list or Retry; a failed
list still shows the error and not the empty copy.
- `test/features/runs/ui/runs_list_widget_test.dart`: loading, error, and
server-empty states stay distinct; a status filter that hides every run keeps
the "No runs found." filter state.
- Chat and pipeline-filter expectations updated to the new copy.
## Not verified here
- No UI build or capture; `ui-review` owns rendered evidence.
- Schedules, Search, Settings, Usage/stats, Needs-you and Templates were read,
not changed or tested. Their empty copy is already calm, except that
"No schedules yet." has no next step because the list has no add action.
Stats says "No runs loaded." (secondary text, not an error).
- Runs and other error text still shows the raw error string (`'$e'`); this is
not an empty-server path and was not changed.
- Server gap: this stage did not check Go's empty-database replies. The client
treats an empty list as healthy. No Go change was made.