Files
pipelines/app/notes/I1.md
T

120 lines
6.8 KiB
Markdown

# I1 — live Runs destination, routes and resilient connection
## Change
- `lib/application/` composes the real app separately from `main.dart`:
`bootstrap.dart` resolves the endpoint and starts the composition,
`pipelines_app.dart` owns one `AppSession` and one `Router`,
`runs_destination.dart` frames the Runs destination, and `app.dart` keeps the
injectable `MyApp` shell for existing widget tests. `main.dart` exports `MyApp`
and calls `runPipelinesApp()`.
- Web endpoint: the page origin from `Uri.base` over `ws(s)` at `/connect`, so
the same server that served the bundle is the live server. Native builds use
only the explicit `--dart-define=PIPELINES_SERVER_URL=ws://host:port/connect`
value; there is no baked host or fallback endpoint.
- **Routes/deep links (I1's second half):** the app now uses Flutter's `Router`
with a total `AppRoute` parser (`/pipelines`, `/runs`, `/runs/:id`, `/chat`,
`/settings`) and the path URL strategy (`flutter_web_plugins` declared as a
direct dependency). `/runs/1` opens that run directly, tab and run selection
push browser history, Back/Forward move between them, and a malformed or
unknown path renders Pipelines and is corrected to `/pipelines`. Non-web
platforms keep the same routes through the Router without an address bar.
A single-page `Navigator` inside the Router delegate supplies the Overlay
native controls need while keeping the shell state across route changes.
- **Reconnects keep the destination:** before the first successful connection
the destination is a full connection screen. After that the loaded Runs screen
stays mounted through drops: a compact status banner reports `Reconnecting to
Pipelines…` or `Not live — Pipelines server unavailable.` with a Retry action,
and `connectionEpoch` triggers an in-place list/detail refresh. The open run,
its scroll position and Back all survive the reconnect; the screen is not
remounted and the selection is not reset.
- **Honest connection copy:** the full gate no longer prints a raw transport
exception. A failed first attempt stays `Pipelines server unavailable` with
`Retrying automatically…` while the client retries instead of flickering to
`Connecting…` on every attempt. Only the first attempt shows `Connecting to
Pipelines…`.
- **Live-watch status:** `AppSession` now observes the send-only `subscribe`
ack/error. A server refusal is reported as `Not live — run updates are
unavailable.` with the server's own refusal reason and a Retry that repeats the
watch; silence (servers that never ack, like the fixture) is left pending
rather than guessed as "not live".
- `AppSession` owns the single shared `PipelinesClient` and its state stream. It
sends `subscribe` with `{workspace: ''}` on every connected transition and
`unsubscribe` on stop/dispose.
- `RunsScreen` consumes `controller.selectedRunId` as the only selection source;
a route change, an initial run, a pending/failed detail and Back all navigate
the same path. Removed the nested `CupertinoPageScaffold`/`CupertinoNavigationBar`;
the shell owns the single native bar.
- `RunDetailView` keeps Back available while the detail is pending as well as on
failure. The detail's back row and the pending/error action now read
`Back to list` (Cupertino's compact row reads `Back`), matching web's
accessible name instead of the ambiguous `Runs`.
- Cupertino-host detection is centralized in `lib/ui/adaptive/host.dart` and used
by the destination, detail and runs list instead of three different checks.
- Inherited web build defect: `run_models.dart` used `0x7fffffffffffffff`
sentinels, which dart2js cannot represent. Replaced them with the `DateTime`
maximum millisecond value (`8640000000000000`), also an exact JavaScript
number; sort behavior is unchanged.
## Checks
- `flutter test`: **86 passed** (12 new since the previous visit; the prior suite
plus route, reconnect-retention, subscribe-status and composition coverage).
- `flutter analyze`: **no issues**.
- `flutter build web` (normal `lib/main.dart`): **succeeded**.
- `dart format --output=none --set-exit-if-changed lib test tool`: clean.
- `git diff --check`: clean.
## Browser acceptance
`tool/runs_probe.mjs` ran real headless Chrome against the isolated loopback
fixture (`tool/runs_probe_server.mjs`) with a same-origin `/connect` WebSocket.
HTML MIME is checked before launch; body assertions use Flutter semantics and
Tesseract OCR of canvas-rendered text. The probe now also drives:
- `Runs` tab → URL `/runs`; run row → `/runs/1`; browser Back → list at
`/runs`; browser Forward → detail at `/runs/1`.
- a direct `/runs/1` load opens the detail and leaves the address bar there.
- `/fixture/refuse` drops the socket and rejects upgrades: the open detail stays
visible, the banner reads `Reconnecting to Pipelines…`, no raw
`WebSocketException`/`Failed to connect` text is rendered, and the URL stays
`/runs/1`.
- accepting again plus Retry restores the same detail without a remount
(`subscribed`, `listRuns` and `getRun` all increase on the fixture).
- a fresh load while upgrades are refused shows the friendly
`Pipelines server unavailable` gate with no raw exception and does not flicker
back to `Connecting…`; Retry recovers the list.
Probe result: `ok: true`, `subscribed: 4`, `listRuns: 5`, `getRun: 7`,
`dropped: 2`, `live: true`. Captures are in
`/Users/alan/.local/share/pipelines/data/artifacts/50/public/i1-fixes/`
(18 PNGs), including:
- `i1-runs-phone-browser-back-list.png`
- `i1-runs-phone-browser-forward-detail.png`
- `i1-deeplink-run-1-phone.png`
- `i1-reconnect-detail-retained-phone.png`
- `i1-reconnect-detail-restored-phone.png`
- `i1-gate-unavailable-friendly-phone.png`
- `i1-gate-recovered-list-phone.png`
- `i1-material-deeplink-run-1-phone.png` — a Linux user-agent override selects
the Material host; the same deep link renders Material controls with the
`Back to list` action.
The existing list/detail/pending/error/input/output/metrics captures were also
regenerated. No page exceptions were logged in the final probe run.
## Limits
- Read-only live authenticated smoke through the manager preview was not
performed: `http://127.0.0.1:8096/` requires auth. No credentials were
available without reading secrets. The preview was not restarted or replaced.
- Mobile builds/devices were not run; mobile is unverified. The shared Router
and single-page Navigator are used on all targets but only web was exercised.
- The fixture does not ack `subscribe` (by design), so the "live" ack path is
covered by widget tests; the refusal banner is covered by tests and the gate
by browser evidence.
- No real run was modified. No commit, push or deployment was made.
- Adding `flutter_web_plugins` to `pubspec.yaml` is the one dependency change;
it is required for path-style routes on web.