@opengroundplan/core 0.1.1

package/templates/layers/testing-e2e/files/tests/e2e/test_api_contract.py

@@ -0,0 +1,35 @@
+"""HTTP contract every service must honour, regardless of what it serves."""
+
+import re
+
+import httpx
+from e2e_config import settings
+
+# Kept obviously synthetic so a real route can never collide with it.
+UNROUTED = "/e2e-unrouted-path-check"
+
+# Frame markers, not the word "error" — an error *message* in the body is fine.
+STACK_TRACE = re.compile(r'Traceback \(most recent call last\)|File "[^"]+", line \d+')
+
+
+def test_unknown_route_answers_404(client: httpx.Client) -> None:
+    assert client.get(UNROUTED).status_code == 404
+
+
+def test_not_found_body_carries_no_stack_trace(client: httpx.Client) -> None:
+    assert not STACK_TRACE.search(client.get(UNROUTED).text)
+
+
+def test_unsupported_method_is_rejected(client: httpx.Client) -> None:
+    # 405 is the correct answer; frameworks that route by method answer 404 instead.
+    assert client.post(settings.health_path, json={}).status_code in (404, 405)
+
+
+def test_malformed_json_is_a_client_error(client: httpx.Client) -> None:
+    response = client.post(
+        settings.health_path,
+        content=b"{ not json",
+        headers={"content-type": "application/json"},
+    )
+
+    assert response.status_code < 500

package/templates/layers/testing-e2e/files/tests/e2e/test_health_contract.py

@@ -0,0 +1,28 @@
+"""Health endpoint contract, asserted against a running deployment."""
+
+import httpx
+from e2e_config import settings
+
+
+def _health(client: httpx.Client) -> httpx.Response:
+    return client.get(settings.health_path)
+
+
+def test_health_answers_200(client: httpx.Client) -> None:
+    assert _health(client).status_code == 200
+
+
+def test_health_returns_a_json_object(client: httpx.Client) -> None:
+    response = _health(client)
+
+    assert "json" in response.headers.get("content-type", "")
+    body = response.json()
+    assert isinstance(body, dict) and body
+
+
+def test_health_shape_is_stable_across_calls(client: httpx.Client) -> None:
+    # The contract is the key set; values legitimately change between calls.
+    first = sorted(_health(client).json())
+    second = sorted(_health(client).json())
+
+    assert first == second

package/templates/layers/testing-unit/blueprint.yaml

@@ -0,0 +1,161 @@
+id: testing-unit
+kind: layer
+name: Unit test harness
+description: >-
+  Fast, isolated, deterministic unit tests: the stack's standard runner wired up with one
+  config file that owns every tunable, a shared set of test doubles (deterministic clock,
+  call recorder), a coverage gate that starts disabled, and one worked example suite per
+  stack demonstrating table-driven cases, injected time, and failure-path assertions.
+
+tags: [testing, unit-tests, quality, vitest, pytest, xunit, go-test, coverage]
+
+# Self-contained by design: the layer tests doubles it ships itself, so it needs no
+# production code, no HTTP surface, and no persistence. It composes onto any base.
+requires: []
+
+# Nothing to name yet. A rival runner (testing-unit-jest) or an opt-out (testing-none) must
+# declare the conflict from its own blueprint — naming an id that does not exist makes the
+# whole catalog fail to load (loader.assertReferencesResolve), and conflicts are symmetric.
+conflicts: []
+
+# Capability names other layers key off: a CI layer looks for `unit-tests` to know which
+# command to run, and a coverage-reporting layer looks for `coverage-report`.
+provides: [unit-tests, test-runner, test-doubles, coverage-report]
+
+# Testing is cross-cutting: no folder layout is more or less compatible with it.
+supportsArchitectures: []
+
+variables:
+  - name: testCoverageThreshold
+    prompt: >-
+      Minimum coverage percent enforced on coverage runs (0 leaves the gate off until real
+      suites exist)
+    type: number
+    default: 0
+    required: false
+
+  - name: testTimeoutMs
+    prompt: Per-test timeout in milliseconds
+    type: number
+    default: 5000
+    required: false
+    when: "stack == 'typescript' || stack == 'node'"
+
+  - name: testEnvironment
+    prompt: Vitest environment
+    type: select
+    default: node
+    required: false
+    when: "stack == 'typescript' || stack == 'node'"
+    choices:
+      - { value: node, label: 'node (server code, no DOM)' }
+      - { value: jsdom, label: 'jsdom (component and browser code)' }
+
+  - name: pythonPackageManager
+    prompt: Python package manager
+    type: select
+    default: uv
+    required: false
+    when: "stack == 'python'"
+    choices:
+      - { value: uv, label: uv }
+      - { value: pip, label: pip }
+      - { value: poetry, label: poetry }
+
+  - name: dotnetTargetFramework
+    prompt: Target framework for the test project
+    type: string
+    default: net10.0
+    required: false
+    when: "stack == 'dotnet'"
+
+files:
+  # ── shared ──────────────────────────────────────────────────────────────────
+  - from: files/docs/testing.md
+    to: .
+
+  # ── typescript / node ───────────────────────────────────────────────────────
+  # One Vitest setup serves both: ESM, no framework coupling.
+  - from: files/vitest.config.ts
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/tests/support/*.ts
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/tests/support.test.ts
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # Supplies the `test` script AGENTS.md advertises, plus the runner it needs.
+  - from: files/package.json
+    to: .
+    onConflict: merge-json
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # ── python ──────────────────────────────────────────────────────────────────
+  # pytest.ini beats pyproject.toml, so the base keeps sole ownership of its packaging file.
+  # Declared, not installed by a post-apply step. `uv run pytest` with no pytest in the
+  # manifest silently runs an ephemeral pytest in an environment that does not contain the
+  # project, so any test importing it fails with ModuleNotFoundError (ADR 0005, spec 003).
+  - from: files/pyproject.toml
+    to: .
+    onConflict: merge
+    when: "stack == 'python'"
+
+  - from: files/pytest.ini
+    to: .
+    when: "stack == 'python'"
+  - from: files/.coveragerc
+    to: .
+    when: "stack == 'python'"
+  # Raw: `__future__`, `__init__` and `__call__` all parse as groundplan path tokens, so plan-time
+  # token checking would reject these files. None of them carries a groundplan token.
+  - from: files/tests/*.py
+    to: .
+    raw: true
+    when: "stack == 'python'"
+
+  # ── go ──────────────────────────────────────────────────────────────────────
+  # The suite lives in the package it tests, so nothing here needs the module path.
+  - from: files/internal/testsupport/*.go
+    to: .
+    when: "stack == 'go'"
+
+  # ── dotnet ──────────────────────────────────────────────────────────────────
+  - from: files/tests/__solutionName.dot__.Tests/*
+    to: .
+    when: "stack == 'dotnet'"
+
+  # The solution is completed declaratively rather than by `dotnet sln add`, which runs
+  # after the first build and is skippable — a solution missing projects that exist on
+  # disk builds green while covering less than the repo contains (ADR 0005, spec 003).
+  - from: files/__solutionName.dot__.slnx
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+  # Central package management: versions live in Directory.Packages.props and projects
+  # reference without one. A bare Version= on a PackageReference fails restore (NU1008).
+  - from: files/Directory.Packages.props
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+postApply:
+  # Manifest-only, like the other layers: nothing installs here, so a pnpm or yarn repo
+  # never gains a stray npm lockfile. docs/testing.md states the install step.
+  - run: npm pkg set scripts.test="vitest run" "scripts.test:watch"="vitest" "scripts.test:coverage"="vitest run --coverage"
+    when: "stack == 'typescript' || stack == 'node'"
+    optional: true
+  - run: npm pkg set devDependencies.vitest=^4.1.10 "devDependencies.@vitest/coverage-v8"=^4.1.10
+    when: "stack == 'typescript' || stack == 'node'"
+    optional: true
+  - run: npm pkg set devDependencies.jsdom=^29.1.1
+    when: "(stack == 'typescript' || stack == 'node') && testEnvironment == 'jsdom'"
+    optional: true
+
+  # Python declares pytest in files/pyproject.toml instead, merged into [dependency-groups].
+
+  # Go needs no dependency: the suite is stdlib `testing` only.
+
+  # The csproj pins its own PackageReference versions and joins the solution declaratively.

package/templates/layers/testing-unit/files/.coveragerc

@@ -0,0 +1,12 @@
+[run]
+branch = true
+source = src
+
+[report]
+show_missing = true
+skip_covered = true
+; 0 disables the gate — raise it once the suite covers real code.
+fail_under = {{ testCoverageThreshold }}
+exclude_also =
+    if TYPE_CHECKING:
+    raise NotImplementedError

package/templates/layers/testing-unit/files/Directory.Packages.props

@@ -0,0 +1,9 @@
+<Project>
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.Extensions.TimeProvider.Testing" Version="10.8.0" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.8.1" />
+    <PackageVersion Include="coverlet.collector" Version="10.0.1" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
+    <PackageVersion Include="xunit.v3" Version="3.2.2" />
+  </ItemGroup>
+</Project>

package/templates/layers/testing-unit/files/__solutionName.dot__.slnx

@@ -0,0 +1,5 @@
+<Solution>
+  <Folder Name="/tests/">
+    <Project Path="tests/{{ solutionName | dot }}.Tests/{{ solutionName | dot }}.Tests.csproj" />
+  </Folder>
+</Solution>

package/templates/layers/testing-unit/files/docs/testing.md

@@ -0,0 +1,90 @@
+# Unit testing
+
+Fast, isolated, deterministic tests. A unit test in this repo touches no network, no clock,
+no filesystem, and no shared process state — anything it needs from the outside is injected.
+
+## Layout
+
+| Stack | Runner | Tests live in | Shared doubles |
+| --- | --- | --- | --- |
+| TypeScript / Node | Vitest | `tests/` and `src/`, named `*.test.ts` or `*.spec.ts` | `tests/support/` |
+| Python | pytest | `tests/test_*.py` | `tests/support.py`, fixtures in `tests/conftest.py` |
+| Go | `go test` | `*_test.go` beside the code | `internal/testsupport/` |
+| .NET | xUnit v3 | `tests/{{ solutionName | dot }}.Tests/` | same project |
+
+## Commands
+
+```bash
+# TypeScript / Node — swap `npm run` for your package manager's run command
+npm run test              # one pass
+npm run test:watch        # re-run on change
+npm run test:coverage     # adds the coverage gate
+
+# Python
+pytest
+pytest --cov              # adds the coverage gate
+pytest -m "not slow"      # skip anything marked slow
+
+# Go
+go test ./...
+go test -race ./...
+go test -coverprofile=coverage.out ./... && go tool cover -func=coverage.out
+
+# .NET
+dotnet test
+dotnet test --collect:"XPlat Code Coverage" --settings tests/*.Tests/coverlet.runsettings
+```
+
+## Where the knobs live
+
+Test tunables are never inlined in a test. Each stack has exactly one file that owns them:
+
+| Stack | File | Knobs |
+| --- | --- | --- |
+| TypeScript / Node | `vitest.config.ts` | environment, per-test timeout, coverage minimum — each overridable by env (`TEST_ENVIRONMENT`, `TEST_TIMEOUT_MS`, `TEST_COVERAGE_MIN`) |
+| Python | `pytest.ini`, `.coveragerc` | discovery, async mode, warning policy, coverage minimum |
+| Go | flags on `go test` | the runner has no config file by design |
+| .NET | `coverlet.runsettings` | coverage minimum and threshold type |
+
+The coverage minimum ships at whatever you chose during generation and is only enforced on a
+coverage run, so a plain test run is green from the first commit. Raise it as real coverage
+lands rather than starting at a number the repo cannot meet.
+
+## The doubles
+
+**FakeClock** (TypeScript, Python, Go) makes time an input. Nothing fires until `advance` is
+called, so a test for a timeout, a debounce, or a retry backoff runs in microseconds and never
+flakes on a slow CI machine. Callbacks scheduled *by* a callback also run if they fall inside
+the advanced window, which is what makes a self-rescheduling loop testable.
+
+.NET has no equivalent because the framework already ships one: inject `TimeProvider` into
+production code and pass `FakeTimeProvider` in tests.
+
+**Recorder** is a callable that remembers how it was called — enough of a spy for most unit
+tests without pulling in a mocking framework. Reach for a real mock only when you need to
+control return values or verify interaction order across several collaborators.
+
+## Conventions
+
+- One behaviour per test, and the test name states that behaviour. `advance_fires_due_timers`,
+  not `test_advance_2`.
+- Arrange / act / assert, with a blank line between the three.
+- No shared mutable state between tests. Build the subject inside the test (or in a fixture
+  that returns a fresh instance) so any test can run alone, in any order.
+- Assert on observable behaviour, not on internals. A test that breaks on a rename is noise.
+- Inject time, randomness, and IO. If a test needs `sleep`, the design is wrong, not the test.
+- Cover the failure path. Invalid input, boundaries, and the empty case are where bugs live.
+- Mark anything genuinely slow so the fast loop stays fast.
+
+## Adding a test for real code
+
+The shipped suite exercises the doubles themselves — it is a worked example, not coverage of
+your domain. Delete it once your own suites replace it as the reference, and point the
+coverage `include`/`source` setting at the code you actually ship.
+
+For .NET, uncomment the `ProjectReference` in the test project so it can see the code under
+test, then add the project to the solution:
+
+```bash
+dotnet sln add tests/*.Tests/*.Tests.csproj
+```

package/templates/layers/testing-unit/files/internal/testsupport/clock.go

@@ -0,0 +1,89 @@
+// Package testsupport holds deterministic doubles shared by the unit test suites.
+package testsupport
+
+import (
+	"fmt"
+	"sort"
+	"time"
+)
+
+type timer struct {
+	id    int
+	dueAt time.Time
+	run   func()
+}
+
+// FakeClock only moves when Advance is called, so timeout and backoff tests never sleep.
+type FakeClock struct {
+	now    time.Time
+	nextID int
+	timers map[int]*timer
+}
+
+func NewFakeClock(start time.Time) *FakeClock {
+	return &FakeClock{now: start, timers: make(map[int]*timer)}
+}
+
+func (c *FakeClock) Now() time.Time { return c.now }
+
+func (c *FakeClock) Pending() int { return len(c.timers) }
+
+// Schedule registers run to fire once the clock reaches now+delay. A negative delay is a
+// test bug rather than a runtime condition, so it panics instead of returning an error.
+func (c *FakeClock) Schedule(run func(), delay time.Duration) int {
+	if delay < 0 {
+		panic(fmt.Sprintf("testsupport: delay must be >= 0, got %s", delay))
+	}
+	c.nextID++
+	c.timers[c.nextID] = &timer{id: c.nextID, dueAt: c.now.Add(delay), run: run}
+	return c.nextID
+}
+
+// Cancel reports whether it removed a still-pending timer.
+func (c *FakeClock) Cancel(id int) bool {
+	if _, ok := c.timers[id]; !ok {
+		return false
+	}
+	delete(c.timers, id)
+	return true
+}
+
+// Advance fires every timer due within the window, in due order and — for ties — in the
+// order scheduled. Timers a callback schedules run too if they land inside the window,
+// which is what makes a self-rescheduling loop testable.
+func (c *FakeClock) Advance(delta time.Duration) {
+	if delta < 0 {
+		panic(fmt.Sprintf("testsupport: delta must be >= 0, got %s", delta))
+	}
+	target := c.now.Add(delta)
+	for {
+		next := c.nextDue(target)
+		if next == nil {
+			break
+		}
+		delete(c.timers, next.id)
+		// A callback observes its own due time, not the end of the window.
+		c.now = next.dueAt
+		next.run()
+	}
+	c.now = target
+}
+
+func (c *FakeClock) nextDue(target time.Time) *timer {
+	due := make([]*timer, 0, len(c.timers))
+	for _, t := range c.timers {
+		if !t.dueAt.After(target) {
+			due = append(due, t)
+		}
+	}
+	if len(due) == 0 {
+		return nil
+	}
+	sort.Slice(due, func(i, j int) bool {
+		if due[i].dueAt.Equal(due[j].dueAt) {
+			return due[i].id < due[j].id
+		}
+		return due[i].dueAt.Before(due[j].dueAt)
+	})
+	return due[0]
+}

package/templates/layers/testing-unit/files/internal/testsupport/clock_test.go

@@ -0,0 +1,132 @@
+package testsupport
+
+import (
+	"reflect"
+	"testing"
+	"time"
+)
+
+var epoch = time.Date(2000, time.January, 1, 0, 0, 0, 0, time.UTC)
+
+func TestScheduleDoesNotFireBeforeItsDelay(t *testing.T) {
+	t.Parallel()
+
+	clock := NewFakeClock(epoch)
+	rec := &Recorder{}
+	clock.Schedule(func() { rec.Record() }, 100*time.Millisecond)
+
+	clock.Advance(99 * time.Millisecond)
+	if got := rec.Count(); got != 0 {
+		t.Fatalf("timer fired early: got %d calls, want 0", got)
+	}
+
+	clock.Advance(time.Millisecond)
+	if got := rec.Count(); got != 1 {
+		t.Fatalf("timer did not fire at its deadline: got %d calls, want 1", got)
+	}
+	if got := clock.Pending(); got != 0 {
+		t.Fatalf("fired timer still pending: got %d, want 0", got)
+	}
+}
+
+func TestAdvanceOrdersTimersByDueTimeThenSchedulingOrder(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name  string
+		delay time.Duration
+		label string
+	}{
+		{name: "late", delay: 30 * time.Millisecond, label: "late"},
+		{name: "tie first scheduled", delay: 10 * time.Millisecond, label: "tie-a"},
+		{name: "tie second scheduled", delay: 10 * time.Millisecond, label: "tie-b"},
+	}
+
+	clock := NewFakeClock(epoch)
+	var fired []string
+	for _, tc := range cases {
+		clock.Schedule(func() { fired = append(fired, tc.label) }, tc.delay)
+	}
+
+	clock.Advance(30 * time.Millisecond)
+
+	want := []string{"tie-a", "tie-b", "late"}
+	if !reflect.DeepEqual(fired, want) {
+		t.Fatalf("fire order: got %v, want %v", fired, want)
+	}
+}
+
+func TestCallbackObservesItsOwnDueTime(t *testing.T) {
+	t.Parallel()
+
+	clock := NewFakeClock(epoch)
+	var seen []time.Time
+	clock.Schedule(func() { seen = append(seen, clock.Now()) }, 5*time.Millisecond)
+	clock.Schedule(func() { seen = append(seen, clock.Now()) }, 20*time.Millisecond)
+
+	clock.Advance(100 * time.Millisecond)
+
+	want := []time.Time{epoch.Add(5 * time.Millisecond), epoch.Add(20 * time.Millisecond)}
+	if !reflect.DeepEqual(seen, want) {
+		t.Fatalf("observed times: got %v, want %v", seen, want)
+	}
+	if got := clock.Now(); !got.Equal(epoch.Add(100 * time.Millisecond)) {
+		t.Fatalf("clock after advance: got %v, want %v", got, epoch.Add(100*time.Millisecond))
+	}
+}
+
+func TestTimersScheduledByACallbackRunInTheSameWindow(t *testing.T) {
+	t.Parallel()
+
+	clock := NewFakeClock(epoch)
+	rec := &Recorder{}
+
+	// Self-rescheduling loop: the shape of a poller or a retry with backoff.
+	var tick func(remaining int)
+	tick = func(remaining int) {
+		rec.Record(clock.Now().Sub(epoch))
+		if remaining > 0 {
+			clock.Schedule(func() { tick(remaining - 1) }, 10*time.Millisecond)
+		}
+	}
+	clock.Schedule(func() { tick(2) }, 10*time.Millisecond)
+
+	clock.Advance(30 * time.Millisecond)
+
+	want := []any{10 * time.Millisecond, 20 * time.Millisecond, 30 * time.Millisecond}
+	if got := rec.FirstArgs(); !reflect.DeepEqual(got, want) {
+		t.Fatalf("tick times: got %v, want %v", got, want)
+	}
+}
+
+func TestCancelReportsWhetherItRemovedATimer(t *testing.T) {
+	t.Parallel()
+
+	clock := NewFakeClock(epoch)
+	rec := &Recorder{}
+	id := clock.Schedule(func() { rec.Record() }, 10*time.Millisecond)
+
+	if !clock.Cancel(id) {
+		t.Fatal("first cancel: got false, want true")
+	}
+	if clock.Cancel(id) {
+		t.Fatal("second cancel: got true, want false")
+	}
+
+	clock.Advance(time.Second)
+	if got := rec.Count(); got != 0 {
+		t.Fatalf("cancelled timer fired: got %d calls, want 0", got)
+	}
+}
+
+func TestScheduleRejectsANegativeDelay(t *testing.T) {
+	t.Parallel()
+
+	defer func() {
+		if recover() == nil {
+			t.Fatal("negative delay: got no panic, want a panic")
+		}
+	}()
+
+	NewFakeClock(epoch).Schedule(func() {}, -time.Millisecond)
+}

package/templates/layers/testing-unit/files/internal/testsupport/recorder.go

@@ -0,0 +1,41 @@
+package testsupport
+
+import "sync"
+
+// Recorder remembers how it was called. Guarded by a mutex because a unit test that
+// exercises goroutines would otherwise trip the race detector on the slice append.
+type Recorder struct {
+	mu    sync.Mutex
+	calls [][]any
+}
+
+func (r *Recorder) Record(args ...any) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.calls = append(r.calls, args)
+}
+
+func (r *Recorder) Count() int {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return len(r.calls)
+}
+
+// FirstArgs returns the first argument of each call, which is what assertions usually want.
+func (r *Recorder) FirstArgs() []any {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	out := make([]any, 0, len(r.calls))
+	for _, call := range r.calls {
+		if len(call) > 0 {
+			out = append(out, call[0])
+		}
+	}
+	return out
+}
+
+func (r *Recorder) Reset() {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.calls = nil
+}

package/templates/layers/testing-unit/files/package.json

@@ -0,0 +1,10 @@
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
+  }
+}

package/templates/layers/testing-unit/files/pyproject.toml

@@ -0,0 +1,2 @@
+[dependency-groups]
+dev = ["pytest==9.1.1", "pytest-cov==7.1.0", "pytest-asyncio==1.4.0"]

package/templates/layers/testing-unit/files/pytest.ini

@@ -0,0 +1,16 @@
+; The only place pytest behaviour is configured. Takes precedence over pyproject.toml,
+; so the base's packaging file stays owned by the base.
+[pytest]
+minversion = 9.0
+testpaths = tests
+; Makes tests/support.py importable without turning the tests tree into a package.
+pythonpath = tests
+addopts = -ra --strict-markers --strict-config --import-mode=importlib
+; `async def test_...` works with no per-test decorator.
+asyncio_mode = auto
+; A warning your dependencies emit is a warning you will eventually debug. Allow-list one
+; with `ignore:<message regex>:<Category>` on its own line rather than dropping `error`.
+filterwarnings =
+    error
+markers =
+    slow: excluded from the default run with `-m "not slow"`