cd9ec62d28
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.
141 lines
7.9 KiB
Markdown
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.
|