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

122 lines
6.6 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.
# 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:
```dart
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:
```json
{"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.