Files
pipelines/app/notes/T1a.md
T
alan cd9ec62d28 feat(app): add template catalogue and create-only submit repository
Add the nonvisual templates data/domain slice: TemplateRepository over the
shared ApiGateway for list_templates, validate and create-only submit, and
TemplateEntry preserving every server field in a deeply read-only raw map.

Re-include test/**/data/ in app/.gitignore so the mirroring tests are not
silently dropped from a fresh checkout.

Tests cover exact request shapes, source preservation, blank-name refusal,
malformed replies, server refusals and immutability.
2026-10-21 15:31:10 +01:00

141 lines
7.9 KiB
Markdown

# T1a — template catalogue, validate and create-only submit
## What changed
New nonvisual `templates` data/domain slice. One shared file was edited:
`app/.gitignore` re-includes `test/**/data/`, because the repository's runtime
`data/` rule was silently excluding this slice's tests from the candidate. No
other lane's work, `lib/main.dart`, shell, pubspec, `web/`, server or Android
file was touched.
| File | Lines | Responsibility |
| --- | --- | --- |
| `lib/features/templates/domain/template_entry.dart` | 63 | Immutable server template; models key/name/description/source/scheduled and keeps every unknown field in deeply read-only `raw` |
| `lib/features/templates/data/template_repository.dart` | 84 | `TemplateRepository(ApiGateway)`: list, validate, create-only submit |
| `test/features/templates/data/template_test_support.dart` | 47 | Recording/refusing fake gateways, server-refusal error, Unicode source fixture |
| `test/features/templates/data/template_list_test.dart` | 165 | Catalogue request shape, field preservation, deep immutability, missing/malformed catalogue |
| `test/features/templates/data/template_create_test.dart` | 147 | Validate/submit envelopes, blank-name gate, missing payloads, verbatim refusals |
| `app/.gitignore` | +4 | Re-includes `test/**/data/` so test files enter the candidate |
Nothing under `lib/main.dart`, `lib/shell/`, another feature, `pubspec.*`,
`web/`, the Go server or `android/` was changed. No dependency was added.
## Review findings addressed
- **Tests could never land (blocking).** `test/features/templates/data/` was
excluded by the repository root rule `data/`; `app/.gitignore` only re-included
`lib/**/data/`. The same negation now covers `test/**/data/`, so these three
test files are untracked-but-visible to git and `git add -n` succeeds. Fixing
the rule (rather than `git add -f`) also protects later `test/**/data/` lanes
such as S1a. No test was moved, so `test/` still mirrors `lib/`.
- **`raw` was only shallowly immutable (advisory).** `TemplateEntry.fromJson`
now deep-copies nested maps/lists into read-only collections, and the listed
test proves nested mutation throws and that the copy does not alias the reply.
- **Malformed-catalogue branches were untested (advisory).** Added tests for a
non-list `templates` value and a non-object catalogue entry, both rejecting
with explicit messages.
- `_text` still stringifies a non-string protocol value with `'$value'`; the
protocol only sends strings, and this matches how the browser would render
such a value, so the behaviour was left unchanged and is documented here
rather than claimed as strict parity.
## Wire behaviour (mirrors `web/src/repository.js`)
- `listTemplates()` sends exactly `{"type":"list_templates"}` with no fields and
returns the `templates` catalogue. A reply with no `templates` field is the
older server's empty catalogue (`?? []` in the browser), not a fake template.
Each entry keeps `key`, `name`, `description`, `source`, `scheduled` and all
unknown fields in `TemplateEntry.raw`; the reply list/maps are never mutated.
`raw` is a deep unmodifiable copy: nested unknown maps and lists are copied
into read-only collections, so neither the view nor a later caller can mutate
the server reply through it.
- `listTemplates()` rejects a malformed envelope instead of fabricating
entries: a non-list `templates` throws
`"The server returned no template catalogue."` and a non-object entry throws
`"The server returned a template that is not an object."`. The real server
cannot produce either, but a protocol mistake must not look like an empty or
half-populated catalogue.
- `validate(source)` sends exactly `{"type":"validate","source":<source>}` and
returns the reply's `graph`. A reply without a graph throws
`TemplateRepositoryException("The server returned no graph.")` — the browser's
exact words — rather than reporting a valid definition.
- `submit(name, source)` sends exactly
`{"type":"submit","name":<trimmed name>,"source":<source>,"create_only":true}`.
A blank/whitespace-only name is refused locally with
`TemplateRepositoryException("Enter a pipeline name.")` and no gateway call is
made; the accepted name is trimmed. A reply without `detail` throws
`TemplateRepositoryException("The server returned no pipeline detail.")`.
- The source string is never trimmed, normalised or re-encoded: Unicode, tabs,
newlines and significant leading/trailing whitespace arrive unchanged.
- A server refusal is never caught or reworded by the repository. It reaches the
caller as the same gateway error object, so the server's own text is shown.
- The repository exposes only these three operations. It has no publish, run,
schedule or overwrite path, so loading or validating a template cannot start
work or mutate a retained pipeline.
## Checks actually run
```
flutter pub get # Got dependencies
dart format lib/features/templates test/features/templates # clean
flutter analyze # No issues found! (0.9s)
flutter test test/features/templates # 13 passed
flutter test # 76 passed
flutter build web # ✓ Built build/web (15.5s)
git diff --check # clean
git check-ignore / git add -n # tests are no longer ignored
```
Tests are part of the candidate, not merely present on disk:
```
$ git add -n app/test/features/templates/data/template_list_test.dart \
app/test/features/templates/data/template_create_test.dart \
app/test/features/templates/data/template_test_support.dart
add 'app/test/features/templates/data/template_create_test.dart'
add 'app/test/features/templates/data/template_list_test.dart'
add 'app/test/features/templates/data/template_test_support.dart'
exit=0
$ git status --porcelain=v1 -uall
M app/.gitignore
?? app/lib/features/templates/data/template_repository.dart
?? app/lib/features/templates/domain/template_entry.dart
?? app/notes/T1a.md
?? app/test/features/templates/data/template_create_test.dart
?? app/test/features/templates/data/template_list_test.dart
?? app/test/features/templates/data/template_test_support.dart
```
Focused acceptance coverage:
- exact `list_templates` request (no fields, one call) and preservation of
modelled plus unknown fields, including nested unknown data;
- listing does not mutate the reply's template list or entry maps; `raw` and
every nested map/list are read-only, and the copy does not alias the reply;
- missing catalogue -> empty list; malformed catalogue -> explicit refusal;
- blank/whitespace name -> refusal with zero gateway calls;
- Unicode/emoji, tab/newline and leading/trailing source whitespace preserved in
both `validate` and `submit`; submit sends only name, source and
`create_only: true`, with the name trimmed;
- missing `graph` and missing `detail` rejected with the browser's exact
messages, with no fabricated graph/detail;
- validate and submit server refusals surface as the identical error object,
not a wrapper.
## Honest limits
- **Not wired into a screen.** This branch has no templates screen and the task
owns data/domain only; the manager owns integration. No browser capture was
made because there is no rendered change in this slice.
- **Mobile unverified.** No Android/iOS build, emulator, ADB or device was used.
The code is plain Dart with no platform-specific code.
- No live server, template catalogue, validate call or submit/creation was
performed. All tests use local fake gateways with no socket, so no real
pipeline was created or run.
- No export-gate workaround, server change or service operation was made; the
pending export-cap fix remains another lane's scope.
- **Not committed.** The stage instruction says not to commit, push or deploy,
so the candidate above is uncommitted in the working tree even though the run
prompt asks to commit a reviewed candidate. Nothing was pushed or deployed.