194 lines
11 KiB
Markdown
194 lines
11 KiB
Markdown
# 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.
|