Files
pipelines/app/notes/P1.md
T

261 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# P1 — Pipelines list, detail, source and versions
## Manager native-default acceptance correction
The original reviewed candidate remains at a44f31b9. Its custom per-label
segmented-control replacement was not acceptable under the user's native-only
constraint. Manager removed PipelineTabRow and all measured/fixed segment sizing.
Both narrow and wide layouts now keep the actual platform segmented control;
when scaled labels need extra width, horizontal mouse/touch scrolling reveals
them. No label wraps inside its word, and keyboard navigation reveals Source.
Removed the source/hash monospace font override as well. Host selection now
recognizes a real CupertinoApp, not just an iOS target override.
Updated native-control/whole-label/selection/host-font tests pass. Fresh final
fixture builds passed7 baseline browser checks/9 captures and30 scale/history/
keyboard checks/10 captures. At320px/2x, the native row intentionally scrolls;
the previous expectation that all labels must fit simultaneously is superseded,
not accomplished by replacing the native control. Evidence lives in approved
temp/pipelines-native-tabs-browser and pipelines-native-tabs-scaled. Manager
inspected scaled at-rest and Source-selected captures. Shell registration and
real Cupertino app composition remain a separate integration slice; mobile is
still unverified. Earlier evidence below describes the historical candidate.
Candidate implementation for run 34 / Task v6. All work is under `app/`; no
commit, push, deployment or shell/main/pubspec edit was made.
## Implemented
- Public `PipelinesScreen({required ApiGateway gateway, graphBuilder,
onStageSelected})` in `lib/features/pipelines/screen.dart`.
- Read-only repository calls, with the web's exact request shapes:
- `list_pipelines` with no fields -> `pipelines` array;
- `list_runs` with no fields -> last-run join;
- `get_pipeline` `{pipeline_id, version}` -> `detail` (`version: 0` = latest).
No start, submit, schedule or other mutation exists in this feature.
- List: name, `id {id} · v{version} · {N stages}`, `updated d MMM HH:mm`,
configured-schedule label, and the latest run's state/ago/duration/id
(`no runs recorded` when absent). Rows request their own summary version.
- Filter: name contains, Runs Any/Has runs/No runs, seven last-run statuses,
Scheduling Any/Has/No schedules (paused counts as configured; older records
without metadata stay unclassified and are not matched by Has/No).
Run facets wait until `list_runs` has succeeded, matching web.
- Sort: Server order, Name A–Z/Z–A, Most recent run, Fewest/Most stages, with
the web's tie-breaks and server-order preservation.
- Clear filters and truthful filtered/no-pipeline empty wording.
- Detail: Summary (content hash, latest version, version created, pipeline
created/updated), Source as `SelectableText`, Versions always shown and
selectable, an explicit `View latest vN` return, and the selected row marked.
Historical selection shows `Viewing vN (latest vM).`
- Loading, empty, run-history, list and detail errors are explicit. Server
refusal text is shown verbatim; malformed replies get a fixed honest message.
- Request sequencing: a late detail reply cannot paint over a newer selection
or a cleared selection; late list refreshes cannot replace newer rows. Refresh
preserves the selected pipeline id and requested version and re-reads detail.
A failed refresh keeps already-loaded rows/history rather than inventing empty
data; a failed runs refresh keeps the previous successful run history and says
it could not be refreshed.
- Platform controls via `defaultTargetPlatform`: Material `Scaffold`/`ListTile`/
`SegmentedButton`/menu on Android/desktop; `CupertinoPageScaffold`/
`CupertinoListTile`/`CupertinoSegmentedControl`/action sheet/grouped lists on
iOS. One local 720px wide/narrow breakpoint; no custom palette, CSS tokens or
fixed button/row sizes.
- Graph remains P2. The Graph tab states `Graph rendering is pending (P2).` and
`graphBuilder`/`onStageSelected` provide the integration hook with pipeline
id, resolved version and stage key.
## Files
Source (all new, none ignored):
- `lib/features/pipelines/screen.dart`
- `lib/features/pipelines/pipelines_controller.dart`
- `lib/features/pipelines/pipeline_repository.dart`
- `lib/features/pipelines/pipeline_models.dart`
- `lib/features/pipelines/pipeline_format.dart`
- `lib/features/pipelines/pipeline_filter.dart`
- `lib/features/pipelines/pipeline_sort.dart`
- `lib/features/pipelines/pipeline_query.dart`
- `lib/features/pipelines/pipeline_graph_hook.dart`
- `lib/features/pipelines/widgets/pipeline_controls.dart`
- `lib/features/pipelines/widgets/pipeline_list_panel.dart`
- `lib/features/pipelines/widgets/pipeline_detail_panel.dart`
- `lib/features/pipelines/widgets/pipeline_detail_styles.dart`
- `lib/features/pipelines/widgets/pipeline_summary_view.dart`
- `lib/features/pipelines/widgets/pipeline_detail_tab.dart`
- `lib/features/pipelines/widgets/pipeline_tab_row.dart`
- `lib/features/pipelines/widgets/pipeline_tabs.dart`
- `lib/features/pipelines/widgets/pipeline_filter_page.dart`
- `lib/features/pipelines/widgets/pipeline_filter_material_body.dart`
- `lib/features/pipelines/widgets/pipeline_filter_cupertino_body.dart`
Tests (fake gateway only; no sockets):
- `test/features/pipelines/fixtures.dart`
- `test/features/pipelines/test_helpers.dart`
- `test/features/pipelines/pipeline_format_test.dart`
- `test/features/pipelines/pipeline_sort_test.dart`
- `test/features/pipelines/pipeline_filter_test.dart`
- `test/features/pipelines/pipelines_controller_load_test.dart`
- `test/features/pipelines/pipelines_controller_detail_test.dart`
- `test/features/pipelines/pipelines_screen_test.dart`
- `test/features/pipelines/pipelines_screen_filter_test.dart`
- `test/features/pipelines/pipelines_adaptive_test.dart`
- `test/features/pipelines/pipeline_tabs_test.dart` (added with the scaled-text tab fix)
Tooling:
- `tool/pipelines_probe_entry.dart` — separate fixture entry, main untouched
- `tool/pipelines_probe_fixture.dart`
- `tool/pipelines_probe_cdp.mjs`
- `tool/pipelines_probe_cdp_lib.mjs`
- `tool/pipelines_probe_cdp_input.mjs`
- `tool/pipelines_probe_tabs_scale.mjs` (added with the scaled-text tab fix)
## Checks actually run
| Check | Result |
| --- | --- |
| `flutter pub get` | completed |
| `flutter analyze` | `No issues found!` |
| `flutter test` (all app tests) | **52 passed** |
| `flutter test test/features/pipelines` (feature only) | **51 passed** |
| `flutter test test/features/pipelines/pipeline_tabs_test.dart` | **12 passed** |
| `dart format --output=none --set-exit-if-changed` (changed Dart files) | 0 changed |
| `flutter build web` (default `lib/main.dart`) | `✓ Built build/web` |
| `flutter build web -t tool/pipelines_probe_entry.dart --output .../private/web-fit` | `✓ Built` |
| `node --check` on all four probe scripts | passed |
| real Chrome fixture probe (`tool/pipelines_probe_cdp.mjs`) | exit 0; 7 AX checks + 9 PNGs, `probe.json` has no error |
| real Chrome tab-scale probe (`tool/pipelines_probe_tabs_scale.mjs`) | exit 0; 29 checks + 10 PNGs, `probe.json` has no error |
Coverage includes exact list/get/list_runs envelopes and request fields, filter/
sort/schedule wording and behavior, version selection, server refusals and
malformed detail, out-of-order detail replies (including after Back), stale list
refresh, refresh selection retention, narrow 390px, 2x text at 390px and
1100px, iOS Cupertino controls, graph-pending message, the graph hook, and
whole plus at-rest-visible tab labels at 150%/320px and 200%/320/390/720px
(including scrolling to the last tab with a mouse drag and by keyboard).
## Browser captures (real Chrome, fixture bundle)
Directory: `/Users/alan/.local/share/pipelines/data/artifacts/34/public/p1-captures`
- `01-list-desktop.png` — 1200×900 list with all rows, schedules, last runs.
- `02-detail-summary.png` — list→detail Summary, fields and Versions.
- `03-source-latest.png` — Source tab with latest (v3) source.
- `04-source-selection.png` — the first source line visibly selected by a real
mouse drag, proving the source is selectable text.
- `05-version-v1.png` — after selecting v1: `Viewing v1 (latest v3).`, v1 hash/
stage count, `View latest v3`, and v1 checked.
- `06-source-v1.png` — Source tab after the version change, ending in
`# selected version 1`.
- `07-list-390.png` — 390×844 list.
- `08-detail-390.png` — 390×844 Hotfix triage detail with versions.
- `09-filter-390.png` — 390×844 native filter page (name, Runs, last statuses,
Scheduling).
- `probe.json` — actions, AX checks and capture paths.
The probe uses the fixture gateway from `tool/pipelines_probe_fixture.dart`; it
never contacts a server. The version row was clicked at the fixed fixture layout
position `(620, 489)` for the 1200×900 viewport because Flutter's web semantics
tree in this build exposes the tabs/heading/list rows but omits the detail-body
rows. Version selection evidence is the rendered `05`/`06` captures inspected
after the run, not an AX assertion.
## Scaled-text tab sizing (UI review findings)
The UI review found two successive defects in the detail tabs
(`pipeline_tabs.dart`):
1. Labels broke inside words when scaled text no longer fitted the
equal-width segments (`Summa`/`ry`, `Sourc`/`e`).
2. After making labels single-line and the row scrollable, the row was still
3 × the widest label wide. At rest it cut the third tab to `Sour` at
320/150%, `Sourc` at 390/200%, and an empty 16 px cell at 320/200%.
Cause: `SegmentedButton` (and `CupertinoSegmentedControl`) give every segment
the width of the widest label. That share is both narrow enough to wrap a
different label and up to a third wider than the labels need together.
Fix: `PipelineDetailTabs` measures each label with the control's own text
style and text scaler and picks one of two layouts:
- When `3 × (widest label + the control's inner padding)` still fits the pane,
the standard Material `SegmentedButton` / Cupertino `CupertinoSegmentedControl`
is used unchanged, filling the pane as before. This is the normal-text and
wide-pane path.
- Otherwise a per-label segmented row gives every segment exactly its own
label width plus 8 px on each side. If the three labels fit, the spare width
is spread evenly and the row fills the pane; if they do not, only the row's
real minimum overflow scrolls (mouse drag, trackpad/Shift+wheel and keyboard
traversal on desktop; touch elsewhere). The row keeps the platform
segmented control's shape and theme colors (`secondaryContainer`/
`onSecondaryContainer`/`outline`, or the Cupertino primary/contrasting
colors) and uses standard `InkWell`/`CupertinoButton` segments, so no
palette, font size or wording is hard-coded. Labels stay single-line: no
intra-word break and no ellipsis.
Acceptance checks (real Chrome, fixture bundle):
| State | Result |
| --- | --- |
| 320×640 @150% | All three labels fully visible at rest; row fills the 288 px pane. |
| 390×844 @200% | All three labels fully visible at rest; row fills the 358 px pane. |
| 720×900 @200% | All three labels fully visible at rest; row fills the 401 px detail pane. |
| 320×640 @200% | `Source` is a recognisable partial label at rest (60.1 px visible, `Sour`), not an empty cell; a mouse drag reveals it fully. |
| 1200×900 @100% | Row still 687.4 px wide, matching the previous layout exactly. |
| Selection | Mouse drag + click switches to the source text; keyboard Tab traversal reaches and scrolls `Source` into view. |
Widget tests cover: no intra-word wrap at the four states; per-label segment
widths when overflowing; a row whose labels fit fills the pane with every
label inside it; an overflowing row scrolls only by its measured overflow and
selects the last tab; the standard Material/Cupertino control is still used
where it fits; Cupertino at 320/2× uses per-label standard Cupertino buttons.
The Flutter test font (Ahem) is much wider than Roboto, so at-rest visibility
at the exact acceptance widths is browser evidence, not widget-test evidence.
Evidence (real Chrome, fixture bundle):
`/Users/alan/.local/share/pipelines/data/artifacts/34/public/p1-tabs-fit`
- `01-320-text150-atrest.png`, `02-320-text200-atrest.png`
- `03-390-text200-atrest.png`, `04-720-text200-atrest.png`
- `05-320-text150-atrest-dark.png`, `06-390-text200-atrest-dark.png`
- `07-320-text200-scrolled.png`, `08-320-text200-source.png`
- `09-320-text200-keyboard.png`, `10-1200-text100-detail.png`
- `README.md`, `probe.json`, reproduced by
`node tool/pipelines_probe_tabs_scale.mjs <build-dir> <capture-dir>`.
The probe asserts at-rest visibility directly, not only label heights: for
every full-visibility state it drags the row to its limit and fails if that
exposes any extra label width (a clipped accessibility box still reports an
edge inside the pane), and it checks the allowed partial `Source` at 320/200%.
The Cupertino path is covered by widget tests only: the web build reports
Material.
## Explicitly not done / unverified
- Graph nodes, edges and stage panes are **not implemented** (P2); only the tab
message and host hook exist. No list mini-graphs either.
- No live-server or authenticated preview was used. Browser evidence is against
an in-memory fixture; it does not claim live parity.
- Android and iOS were not built, installed or run. Only web was tested; mobile
remains unverified. 2x text and narrow layout are widget-test evidence, not a
real-device claim.
- No schedules editor, templates, create/submit/run actions, live events or
search integration.
- Versions are rendered always visible rather than the web's collapsed-by-
default section. This is a layout choice; selection/history behavior and
wording are preserved.
- The browser semantics omission means no automated AX assertion exists for the
detail fields/source/version row; those are proven by captures and widget
tests.
## Repository state
`git diff --stat` is empty because every file is new and untracked. `git status
--short --untracked-files=all` lists all 38 source/test/tool files above; `git
ls-files --others --exclude-standard` returns the same set and `git check-ignore`
reports none of them ignored. No tracked file (including `main.dart`,
`pubspec.*`, shell/web) was modified. Not committed, pushed or deployed, per the
stage rules.