51140cd3b7
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.
122 lines
6.6 KiB
Markdown
122 lines
6.6 KiB
Markdown
# 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.
|