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

7.9 KiB

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.