Files
pipelines/app/notes/T1-wire.md
T

194 lines
11 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.
# T1-wire — register Templates in the real app
## Result
Templates is now a real app route and a Settings entry. `/templates` parses,
serialises and round-trips; unknown or malformed template paths still fall back
to `/pipelines`. The Settings screen has a `Templates` section with the web's
`Browse templates` row, which opens the landed `TemplatesScreen` in embedded
mode over the same `AppSession` gateway. Back — app bar, system Back and browser
Back — returns to the Settings screen instance that was already mounted, so its
fields, connection state and scroll offset survive.
A create accepted by the existing prompt no longer leaves the Pipelines data
stale. The accepted `detail` advances one reload token, and the mounted
Pipelines destination re-reads through its controller. No row is inserted
optimistically: the row appears only from the server's fresh `list_pipelines`
reply. Showing Pipelines again adds no request.
No fifth tab was added. `features/pipelines`, chat, runs, graph, artifacts,
attention and schedules were not edited.
## Navigation shape
Templates is a page in the app's existing `Navigator`, above the shell, exactly
like Search:
- The shell route stays `/settings`, so the Settings destination is never
unmounted and its state is restored when the page closes.
- The Templates page owns the one visible native bar: `Templates` plus a
`Back to Settings` control (Material icon tooltip / Cupertino semantic label).
The embedded `TemplatesScreen` adds no second bar.
- `openTemplates` records `/templates`; `closeTemplates` (`Back to Settings`,
system Back via `popRoute`, or browser Back through `setNewRoutePath`) returns
to `/settings`.
- A direct `/templates` launch closes to `/settings` rather than a guessed
previous page.
## Files
New:
| File | Lines | Responsibility |
| --- | ---: | --- |
| `lib/application/templates_destination.dart` | 122 | Templates page bar, shared-session connection states, embedded `TemplatesScreen`, accepted-detail forwarding |
| `lib/features/settings/settings_templates_section.dart` | 50 | Native `Templates` section row (`Browse templates` + server-catalogue line) |
| `test/application/templates_wiring_test.dart` | 344 | Embedded route, one-bar/one-socket, Back (bar + browser), Settings preservation, exactly-one create refresh, no optimistic row, standalone screen |
| `tool/templates_wiring_probe_entry.dart` | 26 | Real app composition with selectable Material/Cupertino host for the browser probe |
| `tool/templates_wiring_probe.mjs` | 713 | Isolated loopback websocket fixture + real headless-Chrome driver for both hosts |
Modified:
| File | Change |
| --- | --- |
| `lib/application/app_route.dart` | `templates` route kind/constant, `/templates` path, total parse branch (unknown detail paths stay Pipelines) |
| `lib/application/app_router.dart` | `templatesBuilder`, Templates page key, `openTemplates`/`closeTemplates`, system Back, page-removal close |
| `lib/application/pipelines_app.dart` | Templates builder over the shared session; `onCreated` advances a Pipelines reload token; Settings row callback; route→destination mapping |
| `lib/application/pipelines_destination.dart` | Optional `refreshToken`, composed with the connection epoch as the mounted screen's `syncToken` |
| `lib/features/settings/settings_screen.dart` | Optional `onOpenTemplates`; renders the section only when a route owner supplies it (no dead row standalone) |
| `lib/features/settings/settings_keys.dart` | `settings.templates` key |
| `test/application/app_route_test.dart` | `/templates` parse, slash normalisation, malformed detail fallback, round-trip |
| `test/application/app_router_test.dart` | open/close route, system Back, `/templates` boot close |
The reload token is the sum of the connection epoch and the create counter.
Both only increase, so any reconnect or accepted create changes the value
without remounting `PipelinesScreen`; the selection and requested version are
preserved by the existing `syncToken` path.
The Settings row uses the current web page's words exactly: the section heading
`Templates`, the row `Browse templates`, and the secondary line `Reusable
pipeline definitions offered by the server.`
## Acceptance coverage
- **Route**: `/templates` parses to `AppRoute.templates`, `/templates/` and a
full URL normalise, `/templates/release` and `/templates/a/b` fall back to
Pipelines, the serialiser round-trips every route, and `/templates` is the
serialised path.
- **Settings opens Templates**: tapping the row changes the URL to `/templates`
and shows the `TemplatesScreen` with `embedded: true`.
- **One bar / one socket**: exactly one visible `AppBar` (Material) or
`CupertinoNavigationBar` (Cupertino); no `Material` in the Cupertino host; the
client factory is called once; `list_templates` travels over that socket.
- **Back restores Settings**: the detail Back returns to the gallery; the page
Back returns to `/settings`, keeping the edited Server URL field; browser Back
from a second Templates visit does the same. Settings is not re-created (one
ping, no re-read).
- **Exactly one create refresh**: accepted `validate`/`submit` lead to exactly
one new `list_pipelines` and one new `list_runs`. Before the fresh reply,
`pipeline-row-41` is absent (no optimistic insert); after it, the row exists.
Switching to Pipelines adds no further request.
- **Standalone unchanged**: a non-embedded `TemplatesScreen` still owns its
`AppBar`; selecting a template shows the source and the bar's Back control.
- **Shared gateway**: the Templates destination reads `session.gateway`; no
screen or destination creates a client.
## Checks actually run
```
cd app
flutter pub get # Got dependencies
dart format --output=none --set-exit-if-changed \
lib/application lib/features/settings test/application \
tool/templates_wiring_probe_entry.dart # 0 changed
flutter analyze # No issues found!
flutter test test/application/templates_wiring_test.dart # 4 passed
flutter test test/application test/features/settings \
test/features/templates # 129 passed
flutter test # 952 passed
flutter build web -o <private>/web-normal # ✓ Built
flutter build web --target=tool/templates_wiring_probe_entry.dart \
-o <private>/probe-web # ✓ Built
git diff --check # clean
```
## Browser evidence (real headless Chrome, loopback only)
Both hosts run the real `PipelinesApp` composition from the probe entrypoint
against an isolated in-process websocket fixture. No production server,
database, operator session or real pipeline was contacted. The fixture records
the exact wire requests and exposes them at `/fixture/state`.
Each host passed the same flow, seven checks each: Settings opens; the
`Browse templates` row opens `/templates` with one `list_templates` read; the
template detail shows metadata and the verbatim source; opening a template
sends no write; Create sends exactly one `validate` and one `submit` with
`create_only: true` and the verbatim source; the accepted detail causes exactly
one fresh `list_pipelines`; detail Back → gallery → `Back to Settings` restores
the same Settings screen (`ping` unchanged); Pipelines then shows the new
server row with exactly two `list_pipelines`/`list_runs` reads and one socket.
Material dark, 390×844 (`public/t1-wire-material/`):
`t1-wire-material-pipelines.png`, `-settings.png`, `-gallery.png`, `-detail.png`,
`-created.png`, `-back-settings.png`, `-refreshed-pipelines.png`.
Cupertino dark, 390×844 (`public/t1-wire-cupertino/`): the same seven captures
with the `t1-wire-cupertino-` prefix.
Inspected captures: the Material Templates bar + gallery + detail; the Material
create dialog with `Created "Probe release". It is in the Pipelines list.`; the
returned Settings screen scrolled to the `Templates` section with
`Browse templates`; the refreshed Pipelines list showing `Probe release`. The
Cupertino bar, gallery, detail with `Back Templates`, created dialog, returned
Settings and refreshed list were inspected too. The returned Settings captures
show the retained scroll offset, matching the widget test's retained field text.
## Task diff
```
M app/lib/application/app_route.dart
M app/lib/application/app_router.dart
M app/lib/application/pipelines_app.dart
M app/lib/application/pipelines_destination.dart
M app/lib/features/settings/settings_keys.dart
M app/lib/features/settings/settings_screen.dart
M app/test/application/app_route_test.dart
M app/test/application/app_router_test.dart
?? app/lib/application/templates_destination.dart
?? app/lib/features/settings/settings_templates_section.dart
?? app/test/application/templates_wiring_test.dart
?? app/tool/templates_wiring_probe.mjs
?? app/tool/templates_wiring_probe_entry.dart
?? app/notes/T1-wire.md
```
No tracked file outside `app/` was touched; no other lane's files changed. The
only file outside the stated own list is `application/pipelines_destination.dart`
(the optional reload token seam), needed to re-read through the mounted
Pipelines controller rather than remounting it or inserting a row.
## Honest limits
- **Not committed.** The stage instruction says not to commit, push or deploy,
so the candidate above remains uncommitted even though the run prompt asks to
commit a reviewed candidate. Nothing was staged, pushed or deployed.
- The browser fixture is an isolated fake of the protocol, not the live server.
No real template create happened; no operator data or real pipeline changed.
- Mobile (Android/iOS) is unverified: no Android/iOS build, emulator, device or
ADB. Cupertino captures are Chrome's rendering of the Cupertino widgets.
- Templates detail selection is local state, not `/templates/:key`; the task
scoped the route to the gallery, and a deep-linked detail path falls back to
Pipelines rather than inventing a selection.
- `/settings/templates` is not parsed as an alias; the web has that alias, but
this slice registers only the requested `/templates` route.
- Stage counts/graphs in the gallery remain unimplemented from the existing
gallery slice; this task did not add per-card `validate` calls.
## Manager completion after the server evidence failure
The run ended with the server's re-saved-visit evidence bug (fixed and redeployed
separately). The retained tree is complete: 91 application/settings tests pass.
Manager merged it directly. Templates is reachable from Settings without adding a
tab, Back restores the same Settings screen, and an accepted create only
invalidates the Pipelines list so the next server reply supplies the new row.