@live-change/frontend-template 0.9.201 → 0.9.204

package/.cursor/skills/live-change-backend-change-triggers.md

@@ -112,6 +112,21 @@ definition.trigger({
 
 This means: when a user creates a Schedule via the UI or API, the timer is automatically set up. When they update it, the old timer is canceled and a new one created. When they delete it, the timer is canceled.
 
+## Cron-service — planning and admin UI guardrails
+
+When the domain needs **wall-clock schedules** or **fixed repeating intervals** that run a **trigger**, default to **`@live-change/cron-service`** (models **Schedule** / **Interval**, internal **timer** + **changeCron_*** lifecycle), not ad-hoc timers only.
+
+**Backend:** define the **target `definition.trigger`** in your service; put **Schedule** / **Interval** rows in **cron** with **`trigger: { name, service, properties, returnTask }`**. Rely on **`changeCron_Schedule`** / **`changeCron_Interval`** for timer repair (already implemented in cron-service).
+
+**Admin / task-frontend-style UI:** use the same integration as the reference pages:
+
+- **Create:** `ActionForm` with `service="cron"` and `action="setSchedule"` or `action="setInterval"` (relations-driven forms).
+- **List:** `RangeViewer` + `path.cron.schedules` / `path.cron.intervals` with **`reverseRange(range)`** as needed.
+- **Per row:** `.with()` → `scheduleInfo` / `intervalInfo`, `runState` (`jobType` **`cron_Schedule`** or **`cron_Interval`**, **`job`** = id), and `task.tasksByCauseAndCreatedAt` for recent runs.
+- **Delete:** `api.actions.cron.deleteSchedule` / `deleteInterval`.
+
+See **server doc** `15-cron-and-intervals.md` → section **“API used by task-frontend”** for path examples and **Schedule** field semantics (**`NaN`** = “every” for that field).
+
 ## Step 4 – Specific lifecycle triggers (alternative)
 
 If you only care about one lifecycle event, use the specific variant:

package/.cursor/skills/live-change-design-actions-views-triggers.md

@@ -7,6 +7,12 @@ description: Design actions, views, triggers with indexes and batch processing p
 
 Use this skill to design **actions, views, and triggers** in LiveChange services while making good use of indexes and avoiding full-table scans.
 
+## Reads vs writes (CQRS-like)
+
+**Frontend (Vue):** load data with `usePath` + `live` / `useFetch` on **views**. Do **not** use `api.command` or `useActions()` only to fetch, preview, or compute display-only values — add a `definition.view` on the server and read it on the client.
+
+**Backend (services):** **`definition.view`** is the read surface (including computed or preview data). From triggers/actions use **`app.viewGet`** / **`app.serviceViewGet`** when you need the same view layer as the client, or direct model/index reads where appropriate. **Actions and triggers** change state via **`emit`** / **`trigger`** / **`triggerService`**, not via fake “read-only actions.”
+
 ## When to use
 
 - You add or change actions on existing models.
@@ -73,6 +79,57 @@ definition.action({
    - use model paths (`Model.path`, `Model.rangePath`, `Model.sortedIndexRangePath`, `Model.indexObjectPath`)
    - use `...App.rangeProperties` + `App.extractRange(props)` for range views
 
+### Step 2a – RangeViewer/rangeBuckets compatibility
+
+When a view is consumed by `RangeViewer` or `rangeBuckets`:
+
+- prefer `Model.sortedIndexRangePath(...)` for index-backed list views,
+- keep `App.extractRange(props)` as pagination cursor input,
+- do not reinterpret `gt/gte/lt/lte` as domain filters.
+
+Anti-patterns:
+
+- using `indexRangePath` for frontend bucket pagination flow,
+- injecting custom month/year bounds into cursor fields in frontend,
+- rewriting cursor values in backend with unrelated filter semantics.
+
+Preferred filtering strategy:
+
+1. design index prefix for frequent filters,
+2. use `App.utils.prefixRange` only as backend fallback,
+3. keep string min/max hacks as last resort.
+
+### Step 2b – Standalone indexes for union/equal sources
+
+When index rows are built from multiple equal tables (union-like flow), do not force the index into one model definition.
+
+Use `definition.index(...)` at service level (typically `indexes.js`) when:
+
+- index combines rows from two or more source tables,
+- source tables are peer entities (no natural single owner model),
+- index is a projection layer for cross-table reads.
+
+Example:
+
+```js
+definition.index({
+  name: 'Urls',
+  function: async (input, output) => {
+    await input.table('url_Redirect').onChange((obj, oldObj) =>
+      output.change(obj && mapRedirect(obj), oldObj && mapRedirect(oldObj))
+    )
+    await input.table('url_Canonical').onChange((obj, oldObj) =>
+      output.change(obj && mapCanonical(obj), oldObj && mapCanonical(oldObj))
+    )
+  }
+})
+```
+
+Decision rule:
+
+- model-local index -> `definition.model({ indexes: ... })`,
+- union/peer-source index -> standalone `definition.index(...)` in `indexes.js`.
+
 ### Example: `daoPath` (preferred, DAO-backed)
 
 ```js

package/.cursor/skills/live-change-design-models-relations.md

@@ -62,6 +62,25 @@ properties: {
 }
 ```
 
+## Step 2b – Relation arity rules (critical)
+
+Treat arity on two levels:
+
+- **Annotation arity**: can the annotation itself be a list of configs?
+- **Parent tuple arity**: can one config point to multiple parents/dimensions?
+
+| Relation | Annotation arity | Parent tuple arity |
+|---|---|---|
+| `propertyOf`, `itemOf`, `boundTo` | single config only | `what` can be one model or `[A, B, ...]` |
+| `relatedTo` | single config or config list | each config uses `what` with one model or `[A, B, ...]` |
+| `propertyOfAny`, `itemOfAny`, `boundToAny` | single config only | `to` can contain one or many names |
+| `relatedToAny` | single config or config list | each config uses `to` with one or many names |
+
+Guardrail:
+
+- valid: `propertyOf: { what: [A, B] }`
+- invalid: `propertyOf: [configA, configB]`
+
 ## Step 3 – Configure the relation
 
 ### `userItem`
@@ -110,7 +129,7 @@ so the relations/CRUD generator can treat it as a relation rather than a plain `
 
 Notes:
 
-- Usually you’ll have 1–2 parents, but the `propertyOf` list may contain **any number** of parent models (including 3+).
+- Usually you’ll have 1–2 parents, but `what` may contain **any number** of parent models (including 3+).
 - If the entity is a relation, avoid adding manual `...Id` fields in `properties` just to represent the link — CRUD generators won’t treat it as a relation.
 
 Example:
@@ -124,10 +143,9 @@ definition.model({
   properties: {
     // optional extra fields
   },
-  propertyOf: [
-    { what: CostInvoice },
-    { what: Contractor }
-  ]
+  propertyOf: {
+    what: [CostInvoice, Contractor]
+  }
 })
 ```
 

package/.cursor/skills/live-change-frontend-command-forms.md

@@ -19,15 +19,16 @@ Before using this skill, pick the right approach:
 |---|---|
 | `editorData` | **Editing model records** (create/update). Drafts, validation, `AutoField`. See `live-change-frontend-editor-form` skill. |
 | `actionData` | **One-shot action forms** (not CRUD). Submit once → done. See `live-change-frontend-action-form` skill. |
-| `api.command` | **Single button or programmatic calls** (no form fields). This skill, Step 1. |
+| `api.command` | **Mutations only** — single button or programmatic calls that **change persisted state** (no form fields). This skill, Step 1. Not for loading or previewing data (use views + `live` / `useFetch`; see `live-change-frontend-data-views`). |
 | `<command-form>` | **Avoid.** Legacy. Only for trivial prototypes without drafts or `AutoField`. This skill, Step 2. |
 
 **Decision flow:**
 
-1. Does the user fill in form fields? → **No**: use `api.command` (this skill).
-2. Is it editing a model record? → **Yes**: use `editorData`.
-3. Is it a one-shot action? → **Yes**: use `actionData`.
-4. Only use `<command-form>` for the simplest throwaway cases.
+1. Do you only need to **read** data (including previews)? → **Use views** (`live` / `useFetch`), not this skill.
+2. Does the user fill in form fields? → **No**: use `api.command` (this skill) **only if** the operation **mutates** state.
+3. Is it editing a model record? → **Yes**: use `editorData`.
+4. Is it a one-shot action? → **Yes**: use `actionData`.
+5. Only use `<command-form>` for the simplest throwaway cases.
 
 ## Step 1 – Use `api.command` directly
 

package/.cursor/skills/live-change-frontend-data-views.md

@@ -14,6 +14,8 @@ Use this skill when you build **reactive data views** using `usePath`, `live`, `
 - You need to load related objects alongside the main data.
 - You need to restrict data loading for unauthenticated users.
 
+**Do not use `api.command` / `useActions()` to load data.** Commands are for **mutations**. For every read (lists, details, previews, “next number”), use **views** with `live` or `useFetch` as in this skill.
+
 ## Step 1 – Basic data loading with computed paths
 
 When paths depend on reactive values (route params, props), wrap them in `computed()`:
@@ -36,6 +38,21 @@ const [article, comments] = await Promise.all([
 ])
 ```
 
+- Call `usePath()` **once** at the top of `setup` (synchronously). Inside `computed`, use only the returned `path` object to build paths — **never** call `usePath()` or the legacy `path()` inside the getter (there is often no active component instance, which breaks `getCurrentInstance()` / `appContext`).
+
+Wrong:
+
+```javascript
+computed(() => usePath().blog.article({ article: id }))
+```
+
+Right:
+
+```javascript
+const path = usePath()
+const articlePath = computed(() => path.blog.article({ article: id }))
+```
+
 In templates access `.value`:
 
 ```vue

package/.cursor/skills/live-change-frontend-e2e-lifecycle.md

@@ -0,0 +1,82 @@
+---
+name: live-change-frontend-e2e-lifecycle
+description: Set up stable node:test E2E lifecycle with env, withBrowser and e2eSuite
+---
+
+# Skill: live-change-frontend-e2e-lifecycle
+
+Use this skill when creating or refactoring LiveChange frontend E2E tests.
+
+## Goal
+
+Avoid flaky teardown where only the first test file runs because shared env teardown calls `process.exit`.
+
+## Step 1 - Build shared env helper
+
+Create `e2e/env.ts` with:
+
+- `getTestEnv()` that starts `TestServer` once and memoizes with `envPromise`
+- `disposeTestEnv()` that resets memoized state and disposes server
+- fallback cleanup:
+
+```ts
+process.on('beforeExit', () => {
+  void disposeTestEnv()
+})
+```
+
+Keep startup failure `process.exit(1)` inside `getTestEnv()` catch.
+
+Do not add `after(...process.exit(...))` to this file.
+
+## Step 2 - Isolate browser per test
+
+Create `e2e/withBrowser.ts` with Playwright setup/teardown in `try/finally`:
+
+- call `getTestEnv()` once per test execution
+- open browser/context/page
+- close context and browser in `finally`
+
+## Step 3 - Add suite-level teardown
+
+Create `e2e/e2eSuite.ts`:
+
+```ts
+import { after, describe } from 'node:test'
+import { disposeTestEnv } from './env.js'
+
+export function e2eSuite(name: string, define: () => void): void {
+  describe(name, () => {
+    after(async () => {
+      await disposeTestEnv()
+      process.exit(0)
+    })
+    define()
+  })
+}
+```
+
+## Step 4 - Wrap tests
+
+Each `e2e/*.test.ts` file should use one wrapper:
+
+```ts
+import test from 'node:test'
+import { e2eSuite } from './e2eSuite.js'
+
+e2eSuite('example-suite', () => {
+  test('renders page', async () => {
+    // test body
+  })
+})
+```
+
+## Step 5 - Verify
+
+Run from project root with `fnm exec`:
+
+```bash
+fnm exec -- npm run e2e
+```
+
+Confirm multiple test files execute and process exits only after full suite teardown.

package/.cursor/skills/live-change-frontend-range-list.md

@@ -27,6 +27,19 @@ function articlesPathRange(range) {
 }
 ```
 
+## Step 1a – Hard rules for index-backed ranges
+
+For lists loaded with `RangeViewer` / `rangeBuckets`:
+
+- backend views should use `sortedIndexRangePath`, not `indexRangePath`,
+- keep `range.gt/gte/lt/lte` for pagination cursor only,
+- never override `gt/lt` in frontend `pathFunction` with ad-hoc filters.
+
+Why:
+
+- RangeViewer computes next buckets from previous cursor boundaries,
+- replacing cursor fields causes repeated slices and broken infinite loading.
+
 ## Step 2 – Attach related objects with `.with()`
 
 Chain `.with()` calls to load related data for each item:
@@ -127,3 +140,35 @@ Iterate in the template:
   </div>
 </template>
 ```
+
+## Step 5 – Reactive filters and safe reloads
+
+When your `pathFunction` depends on changing filters (month, status, company, search), prefer `ReactiveRangeViewer`.
+
+Why:
+
+- reactivity in `pathFunction` can be subtle and lead to stale bucket state
+- ad-hoc `:key` resets spread fragile logic in pages
+- `ReactiveRangeViewer` centralizes reload logic and can preserve list height while reloading
+
+```vue
+<ReactiveRangeViewer
+  :pathFunction="transactionsPathRange"
+  :sourceKey="JSON.stringify({ accountId, month: filterByMonth ? month : null })"
+  :preserveHeightOnReload="true"
+  :canLoadTop="false"
+  canDropBottom
+>
+  <template #default="{ item }">
+    <BankTransactionListItem :transaction="item" />
+  </template>
+</ReactiveRangeViewer>
+```
+
+## Checklist – range pagination safety
+
+- [ ] backend index view is based on `sortedIndexRangePath`
+- [ ] frontend `pathFunction` forwards `range` unchanged (`...range` or `...reverseRange(range)`)
+- [ ] domain filters (`month`, `year`, `status`) are separate view params
+- [ ] no manual cursor overrides (`gt/gte/lt/lte`) in frontend code
+- [ ] if narrowing is needed, backend uses index prefix design first, `prefixRange` only as fallback

package/.cursor/skills/live-change-frontend-synchronized.md

@@ -0,0 +1,101 @@
+---
+name: live-change-frontend-synchronized
+description: Use synchronized and synchronizedList for autosave editing in LiveChange Vue frontends, including object vs list decision flow, identifiers mapping, and save/delete patterns
+---
+
+# Skill: live-change-frontend-synchronized (Cursor)
+
+Use this skill when implementing or refactoring frontend editing flows that should keep local form state synchronized with backend data.
+
+## When to use
+
+- Editing one object loaded from `live(...)` with autosave or manual save.
+- Editing list items inline (for example access roles) with per-row identifiers.
+- Replacing custom `watch + api.command` autosave logic with a standard helper.
+- Choosing between `synchronized`, `synchronizedList`, and `editorData`.
+
+## Decision flow
+
+1. **One editable object** (`profile`, `note`, `settings`) -> use `synchronized`.
+2. **Editable list rows** (`accesses`, `invitations`, `requests`) -> use `synchronizedList`.
+3. **Definition-driven CRUD form with validation UI** -> use `editorData` from auto-form stack.
+
+## What counts as "editable list rows"
+
+Treat the feature as a list flow (`synchronizedList`) when most of these are true:
+
+- The UI renders rows with `v-for` and each row has editable fields.
+- Users can edit many rows inline in one screen (table/config/admin list).
+- Autosave should happen per row while the list stays reactive.
+- Each row needs its own action payload keys in addition to shared list context.
+
+In this case, wire one `synchronizedList(...)` and edit fields directly on `syncList.value`.
+Do not build a parallel `id -> synchronized(...)` map for rows.
+
+## `synchronized` pattern (object)
+
+```javascript
+import { synchronized } from '@live-change/vue3-components'
+
+const sync = synchronized({
+  source: sourceRef,
+  update: actions.service.updateThing,
+  identifiers: computed(() => ({ thing: thingId.value })),
+  recursive: true,
+  autoSave: true,
+  debounce: 600
+})
+
+const { value: editable, changed, saving, save } = sync
+```
+
+### Rules
+
+- `source` should come from `live(...)` or a computed source.
+- Keep identifiers stable and pass them through `identifiers` (plain object or `computed`).
+- Use `updateDataProperty: 'data'` for draft-like payloads where backend expects nested data.
+- Use `autoSave: false` when save must happen only after explicit confirmation.
+
+## `synchronizedList` pattern (list)
+
+```javascript
+import { synchronizedList } from '@live-change/vue3-components'
+
+const syncList = synchronizedList({
+  source: accesses,
+  update: actions.accessControl.updateSessionOrUserAndObjectOwnedAccess,
+  delete: actions.accessControl.resetSessionOrUserAndObjectOwnedAccess,
+  identifiers: { object, objectType },
+  objectIdentifiers: ({ to, sessionOrUser, sessionOrUserType }) => ({
+    access: to, sessionOrUser, sessionOrUserType, object, objectType
+  }),
+  recursive: true
+})
+
+const editableRows = syncList.value
+await syncList.delete(editableRows.value[0])
+```
+
+### Rules
+
+- `source` should be a list from `live(...)`.
+- Every item should have stable `id`.
+- Put shared context in `identifiers`, and row-specific keys in `objectIdentifiers`.
+- Edit rows through `syncList.value`; call `syncList.delete(...)` / `syncList.insert(...)` on the helper object.
+- Prefer this pattern for configuration lists, permission tables, dictionaries, and other multi-row settings editors.
+
+## Project examples to follow
+
+- `speed-dating/front/src/components/notes/NoteEditor.vue` (`synchronized` with autosave)
+- `speed-dating/front/src/components/profile/ProfileSettings.vue` (`synchronized` + `updateDataProperty: 'data'`)
+- `family-tree/front/src/components/AgreementDialog.vue` (`synchronized` with manual save)
+- `rcstreamer/front/src/configuration/AccessRequests.vue` (`synchronizedList`)
+- `rcstreamer/front/src/configuration/AccessInvitations.vue` (`synchronizedList`)
+- `rcstreamer/front/src/configuration/AccessList.vue` (`synchronizedList`)
+
+## Common mistakes
+
+- Using `synchronized` for a list of rows instead of `synchronizedList`.
+- Forgetting `objectIdentifiers` when backend update/delete actions need per-row keys.
+- Mutating raw `live(...)` list data instead of `synchronizedList(...).value`.
+- Mixing autosave helper patterns with unrelated one-shot action form patterns.

package/.cursor/skills/live-change-node-toolchain-fnm.md

@@ -0,0 +1,44 @@
+---
+name: live-change-node-toolchain-fnm
+description: Run node, npm, npx, tsx and framework CLI with fnm exec so .node-version and .nvmrc are respected
+---
+
+# Skill: Node toolchain with fnm
+
+Use this skill whenever you run **Node**, **npm**, **npx**, **tsx**, or **corepack** in this repo (tests, `describe`, dev servers, scripts). Agents must not use the default sandbox Node; use **fnm exec** so the version from dotfiles applies.
+
+## When to use
+
+- Running `npm test`, `npm run …`, linters, builds
+- `node server/start.js describe` or any framework entry
+- `tsx` for TypeScript scripts
+- Any subprocess that would invoke `node` or `npm` for a project with `.node-version` / `.nvmrc`
+
+## Step 1 – Find the right directory
+
+Locate the nearest project root that has `.node-version` or `.nvmrc` for the task (often the app folder, e.g. `auto-firma/app/`).
+
+`cd` to that directory before running commands so fnm reads the correct file.
+
+## Step 2 – Prefix with fnm exec
+
+```bash
+fnm exec -- node server/start.js describe --service myService --output yaml
+fnm exec -- npm test
+fnm exec -- npx vitest
+fnm exec -- tsx ./tools/something.ts
+```
+
+The part after `--` is the same command you would run manually with the correct Node active.
+
+## Step 3 – Nested monorepo paths
+
+If you are in the repo root but the dotfile is only under `some-app/`:
+
+```bash
+cd some-app && fnm exec -- npm test
+```
+
+## If fnm is missing
+
+Do not fall back to bare `node` / `npm` for framework work. Report that fnm is required (or document a one-off alternative the user approved).

package/.node-version

@@ -0,0 +1 @@
+20.19.2

package/.nvmrc

@@ -0,0 +1 @@
+20.19.2

package/README.md

@@ -69,3 +69,21 @@ Typowy flow tworzenia nowej aplikacji:
 
 Dokładny „manual” tego flow znajdzie się w sekcji `frontend/01-getting-started.md` dokumentacji.
 
+### E2E starter (node:test + Playwright)
+
+Szablon zawiera przykładowy zestaw E2E w katalogu `e2e/`:
+
+- `env.ts` - lazy start `TestServer` i `disposeTestEnv()`
+- `withBrowser.ts` - lifecycle przeglądarki per test
+- `e2eSuite.ts` - wrapper `describe` + `after` z finalnym teardown
+- `homepage.test.ts`, `client-session.test.ts` - przykładowe testy
+
+Uruchamianie:
+
+```bash
+fnm exec -- npm run e2e
+fnm exec -- npm run e2e:headed
+```
+
+Ważne: nie rejestruj `after(...process.exit(...))` w `e2e/env.ts`. Finalny `process.exit(0)` powinien być tylko w `e2eSuite.ts`.
+

package/e2e/client-session.test.ts

@@ -0,0 +1,17 @@
+import test from 'node:test'
+import assert from 'node:assert'
+import { withBrowser } from './withBrowser.js'
+import { e2eSuite } from './e2eSuite.js'
+
+e2eSuite('client-session', () => {
+  test('frontend initializes api client session', async () => {
+    await withBrowser(async (page, env) => {
+      await page.goto(env.url + '/', { waitUntil: 'networkidle' })
+      const session = await page.evaluate(() => {
+        const root = window as unknown as { api?: { client?: { value?: { session?: string } } } }
+        return root.api?.client?.value?.session
+      })
+      assert.ok(typeof session === 'string' && session.length > 0, 'session id is present')
+    })
+  })
+})

package/e2e/e2eSuite.ts

@@ -0,0 +1,12 @@
+import { after, describe } from 'node:test'
+import { disposeTestEnv } from './env.js'
+
+export function e2eSuite(name: string, define: () => void): void {
+  describe(name, () => {
+    after(async () => {
+      await disposeTestEnv()
+      process.exit(0)
+    })
+    define()
+  })
+}

package/e2e/env.ts

@@ -0,0 +1,130 @@
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { TestServer } from '@live-change/server'
+import appConfig from '../server/app.config.js'
+import * as services from '../server/services.list.js'
+
+const READY_TIMEOUT_MS = 60000
+const READY_POLL_MS = 2000
+
+async function waitForServerReady(url: string): Promise<void> {
+  const deadline = Date.now() + READY_TIMEOUT_MS
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url)
+      if (res.ok) return
+    } catch {
+      // not ready yet
+    }
+    await new Promise((r) => setTimeout(r, READY_POLL_MS))
+  }
+  throw new Error(`Server at ${url} did not become ready within ${READY_TIMEOUT_MS}ms`)
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const serverDir = path.join(__dirname, '..', 'server')
+const frontDir = path.join(__dirname, '..', 'front')
+
+for (const serviceConfig of appConfig.services) {
+  const name = (serviceConfig as { name: string }).name
+  ;(serviceConfig as { module?: unknown }).module = (services as Record<string, unknown>)[name]
+}
+;(appConfig as { init?: (s: unknown) => Promise<void> }).init = (services as { init: (s: unknown) => Promise<void> }).init
+
+export type TestEnv = {
+  server: InstanceType<typeof TestServer>
+  url: string
+  haveService: (name: string) => { name: string; models: Record<string, { get: (id: string) => Promise<unknown> }>; views: Record<string, unknown>; actions: Record<string, unknown>; triggers: Record<string, unknown> }
+  haveModel: (serviceName: string, modelName: string) => { get: (id: string) => Promise<unknown>; create: (data: unknown) => Promise<unknown>; update: (id: string, data: unknown) => Promise<unknown>; delete: (id: string) => Promise<unknown>; indexObjectGet: (index: string, key: unknown, opts?: unknown) => Promise<unknown>; indexRangeGet: (index: string, key: unknown) => Promise<unknown[]>; definition: { properties: Record<string, { preFilter: (v: unknown) => unknown }> } }
+  haveView: (serviceName: string, viewName: string) => unknown
+  haveAction: (serviceName: string, actionName: string) => unknown
+  haveTrigger: (serviceName: string, triggerName: string) => unknown
+  grabObject: (serviceName: string, modelName: string, id: string) => Promise<unknown>
+}
+
+type TestServerInstance = InstanceType<typeof TestServer>
+
+let envPromise: Promise<TestEnv> | null = null
+let testServer: TestServerInstance | null = null
+
+export async function disposeTestEnv(): Promise<void> {
+  const s = testServer
+  testServer = null
+  envPromise = null
+  if (s) await s.dispose()
+}
+
+function haveService(server: TestServerInstance, name: string) {
+  const service = server.apiServer.services.services.find((s: { name: string }) => s.name === name)
+  if (!service) throw new Error('service ' + name + ' not found')
+  return service
+}
+
+function haveModel(server: TestServerInstance, serviceName: string, modelName: string) {
+  const service = haveService(server, serviceName)
+  const model = service.models[modelName]
+  if (!model) throw new Error('model ' + modelName + ' not found')
+  return model
+}
+
+export async function getTestEnv(): Promise<TestEnv> {
+  if (envPromise) return envPromise
+  envPromise = (async () => {
+    const server = new TestServer({
+      dev: true,
+      enableSessions: true,
+      port: 0,
+      ssrRoot: frontDir,
+      initScript: path.join(serverDir, 'init.js'),
+      services: appConfig
+    })
+    console.log('starting test server')
+    try {
+      await server.start()
+    } catch (error) {
+      console.error((error as Error).stack)
+      process.exit(1)
+    }
+    console.log('Test server started at', server.url)
+    console.log('waiting for front to be ready...')
+    await waitForServerReady(server.url!)
+    console.log('front ready')
+
+    testServer = server
+
+    process.on('beforeExit', () => {
+      void disposeTestEnv()
+    })
+
+    const url = server.url!
+    return {
+      server,
+      url,
+      haveService: (name: string) => haveService(server, name),
+      haveModel: (serviceName: string, modelName: string) => haveModel(server, serviceName, modelName),
+      haveView: (serviceName: string, viewName: string) => {
+        const service = haveService(server, serviceName)
+        const view = service.views[viewName]
+        if (!view) throw new Error('view ' + viewName + ' not found')
+        return view
+      },
+      haveAction: (serviceName: string, actionName: string) => {
+        const service = haveService(server, serviceName)
+        const action = service.actions[actionName]
+        if (!action) throw new Error('action ' + actionName + ' not found')
+        return action
+      },
+      haveTrigger: (serviceName: string, triggerName: string) => {
+        const service = haveService(server, serviceName)
+        const trigger = service.triggers[triggerName]
+        if (!trigger) throw new Error('trigger ' + triggerName + ' not found')
+        return trigger
+      },
+      grabObject: async (serviceName: string, modelName: string, id: string) => {
+        const model = haveModel(server, serviceName, modelName)
+        return await model.get(id)
+      }
+    }
+  })()
+  return envPromise
+}