Files
pipelines/app/notes/X1.md
T
alan 51140cd3b7 feat(app): add native omni-search screen over the search gateway
Pure request/parse/row logic in lib/features/search/domain, a
gateway-backed repository, and Material plus Cupertino bodies.
The header and rows share one scroll view, and the server's
truncation, scan and cap facts stay visible even when a bounded
scan returns no matches.

Tests cover the exact search envelope, token parsing, stale replies,
retry, truncation bounds and platform layouts. A Web-only fixture
and CDP probe support rendered verification; the screen is not yet
registered in the shell.
2026-10-21 16:41:30 +01:00

6.6 KiB
Raw Blame History

X1 — Omni-search

Scope and API

Implemented the search feature under lib/features/search/ with no main.dart, shell, pubspec, server, web or Android edits.

Entry point:

SearchScreen(
  gateway: apiGateway,       // required ApiGateway
  onOpen: (hit) { ... },     // required ValueChanged<JsonMap>
  cupertino: null,           // optional; omitted = iOS/macOS Cupertino, else Material
)

onOpen always receives the server's original result map unchanged, including its target. Unknown/absent payloads and results without a target are read-only and never call onOpen; the client never invents a route or mutates server state.

Request shape is exact and shared-gateway only:

{"type":"search","search":{"query":"plan","kind":"","limit":0}}

limit is always 0 (server default cap), never a client-chosen larger value.

Behaviour

  • t:/type: tokens: unquoted, whitespace-delimited, case-insensitive, last supported token wins; quoted, escaped, unknown and trailing-punctuation tokens stay literal. The parser mirrors web/src/search.js.
  • Kind selector: All kinds / Pipelines / Runs / Steps / Fields / Artifacts / Versions. Changing it removes recognised type tokens from the field and sends at once, like the browser's selector.
  • Empty text with All kinds clears locally and sends nothing. Blank text with a valid kind is a kind-only browse, matching the server/browser contract.
  • 250 ms debounce; Enter sends at once. Every request carries a monotonically increasing token, and replies for superseded edits are dropped.
  • Loading, searching, retained-results refresh progress, empty (query-specific and kind-only wording) and error are distinct. A truncated reply with no rows says the server's scan limit was reached and keeps its truncation/scan bounds on screen instead of claiming a complete empty; a complete empty has no bounds line. A reply without search_results and an unknown-command rejection use the server-upgrade sentence; any other failure shows the server's own text. Error state offers Retry.
  • Rows show the kind derived from the server payload (Unrecognised result for an unknown payload), title, snippet (first case-insensitive query occurrence in bold), and recency. Bounds show result count, cap, scanned steps/bytes, scan limit and a truncation sentence when the server reports it, including for a truncated reply with zero rows.
  • In-hand results are re-narrowed by the effective kind while a narrowed request loads, so the list always agrees with the control.
  • Standard platform controls only: Material SearchBar, dropdown, LinearProgressIndicator, CircularProgressIndicator, ListTile, FilledButton.tonalIcon; Cupertino CupertinoSearchTextField, action-sheet kind picker, CupertinoListSection/CupertinoListTile, CupertinoActivityIndicator, CupertinoButton.filled. No CSS port, custom palette, fixed row/bubble dimensions or bespoke buttons. Typography and colours come from the ambient Material/Cupertino theme; rows and the header scroll in one CustomScrollView so 2× text never clips.

Automated checks

Run from app/ with /Users/alan/development/flutter/bin/flutter:

  • flutter test test/features/search — 36 passed (controller, repository, query/token parser, row/snippet/routing, Material + Cupertino widget tests).
  • flutter test — 65 passed (whole app suite, including existing transport, runs and shell tests).
  • flutter analyze — No issues found.
  • flutter build web (default lib/main.dart) — succeeded.
  • flutter build web -t tool/search_fixture/main.dart — succeeded for the rendered probe.
  • node --check tool/search_probe.mjs — passed.
  • git diff --no-index --check /dev/null <file> on every touched file — no whitespace errors (all task files are untracked, so plain git diff --check would not see them).

Tests were written before the implementation (initial run failed on missing symbols). Coverage includes the exact envelope, token parsing, selector token clearing, no-request empty state, stale success and failure replies, error/retry, truncation/bounds (including a truncated reply with zero rows), per-kind row text, snippet spans, read-only hits, onOpen targets, and MaterialApp/CupertinoApp at 390/1000 wide with 2× text.

Rendered browser evidence

Built the Web-only fixture (tool/search_fixture/main.dart) and drove real headless Chrome through CDP with tool/search_probe.mjs on an OS-assigned loopback port. The probe typed plan into the real field, asserted five rows, the server snippet, recency and truncation/scanned bounds, then clicked the pipeline row and asserted that the fixture receiver got pipeline:24. It also typed needle with no matching fixtures and asserted the Material and Cupertino truncated-empty copy plus the retained Results truncated … 0 results … scanned 2000 steps … scan limit 1.0 MiB line, capturing both.

Captures are in the run's shared artifacts:

  • /Users/alan/.local/share/pipelines/data/artifacts/49/public/x1-search/x1-search-material-phone.png — 390×844, Material controls, five mixed-kind results with recency/snippet/bounds.
  • /Users/alan/.local/share/pipelines/data/artifacts/49/public/x1-search/x1-search-material-desktop.png — 1280×800, same results.
  • /Users/alan/.local/share/pipelines/data/artifacts/49/public/x1-search/x1-search-cupertino-phone.png — 390×844, Cupertino search field/kind picker/grouped rows, dark system theme.
  • /Users/alan/.local/share/pipelines/data/artifacts/49/public/x1-search/x1-search-open-target.png — the row click landing on Opened pipeline target: pipeline:24.
  • /Users/alan/.local/share/pipelines/data/artifacts/49/public/x1-search/x1-search-truncated-empty.png — 390×844 Material, zero rows with the server's scan-limit sentence and truncation/scan bounds.
  • /Users/alan/.local/share/pipelines/data/artifacts/49/public/x1-search/x1-search-truncated-empty-cupertino.png — 390×844 Cupertino dark, the same bounded empty state.

The fixture and probe are development-only entry points; they are not imported by lib/main.dart and are not part of the production routing. The browser run used a static fake gateway, not a live Pipelines server or operator data.

Not verified / open items

  • No shell registration or navigation wiring was added (manager owns main.dart/shell/); the screen is exported for that integration.
  • No real server, operator chat/run, or production URL was used.
  • Mobile targets (Android/iOS) were not built, installed or exercised; only Web was rendered and tested. Source is kept portable.
  • No commit, push, deployment or canonical URL change was made.