merge(app): land Templates entry from Settings after retained-run recovery

This commit is contained in:
2026-10-22 00:29:50 +01:00
14 changed files with 1576 additions and 5 deletions
+193
View File
@@ -0,0 +1,193 @@
# 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.