@live-change/frontend-template 0.9.198 → 0.9.200

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

@@ -0,0 +1,296 @@
+---
+name: live-change-design-actions-views-triggers
+description: Design actions, views, triggers with indexes and batch processing patterns
+---
+
+# Skill: live-change-design-actions-views-triggers (Claude Code)
+
+Use this skill to design **actions, views, and triggers** in LiveChange services while making good use of indexes and avoiding full-table scans.
+
+## When to use
+
+- You add or change actions on existing models.
+- You define new views (especially list/range views).
+- You implement triggers (online/offline, batch processing, async result flows).
+
+## Step 1 – Design an action
+
+1. **Clarify the goal**:
+   - create / update / delete a record,
+   - or create a “command” that will be completed later.
+2. **Define `properties`** clearly:
+   - only include what the client must provide,
+   - fetch the rest from the database via indexes.
+3. **Use indexes**, not full scans:
+   - `indexObjectGet('bySomething', { ... })` for single-object lookups,
+   - `indexRangeGet('bySomething', { ... })` for lists.
+4. **Return a useful result**:
+   - new object id,
+   - session keys,
+   - any data needed for the next step.
+
+Example:
+
+```js
+definition.action({
+  name: 'someAction',
+  properties: {
+    someKey: { type: String }
+  },
+  async execute({ someKey }, { client, service }) {
+    const obj = await SomeModel.indexObjectGet('bySomeKey', { someKey })
+    if(!obj) throw new Error('notFound')
+
+    const id = app.generateUid()
+
+    await SomeOtherModel.create({
+      id
+      // ...
+    })
+
+    return { id }
+  }
+})
+```
+
+## Step 2 – Design a view
+
+1. Decide what kind of data source you have, then pick the **view variant** (exactly one):
+
+| Variant | When to use |
+| --- | --- |
+| `daoPath` | Data is stored in the framework DAO (preferred). The framework auto-generates both `get` and `observable` from `daoPath`. |
+| `get` + `observable` | External or custom reactive data source (eg. WebSocket client, RPC stream). **Both are required together.** |
+| `fetch` | Remote, non-reactive request/response data (eg. GeoIP). Often paired with `remote: true`. |
+
+2. Decide if you need:
+   - a **single** object view, or
+   - a **list/range** view.
+3. Define `properties` for the view:
+   - only parameters needed for filtering,
+   - types consistent with model fields.
+4. Prefer `daoPath` when you are reading from the DAO:
+   - use model paths (`Model.path`, `Model.rangePath`, `Model.sortedIndexRangePath`, `Model.indexObjectPath`)
+   - use `...App.rangeProperties` + `App.extractRange(props)` for range views
+
+### Example: `daoPath` (preferred, DAO-backed)
+
+```js
+definition.view({
+  name: 'costInvoice',
+  properties: {
+    costInvoice: {
+      type: String
+    }
+  },
+  returns: { type: Object },
+  async daoPath({ costInvoice }) {
+    return CostInvoice.path(costInvoice)
+  }
+})
+```
+
+### Example: `get` + `observable` together (external / reactive)
+
+```js
+definition.view({
+  name: 'session',
+  properties: {},
+  returns: { type: Number },
+  async get(params, { client }) {
+    return onlineClient.get(['online', 'session', { ...params, session: client.session }])
+  },
+  async observable(params, { client }) {
+    return onlineClient.observable(
+      ['online', 'session', { ...params, session: client.session }],
+      ReactiveDao.ObservableValue
+    )
+  }
+})
+```
+
+### Example: `fetch` (remote / non-reactive)
+
+```js
+definition.view({
+  name: 'myCountry',
+  properties: {},
+  returns: { type: String },
+  remote: true,
+  async fetch(props, { client }) {
+    return await getGeoIp(client.ip)
+  }
+})
+```
+
+### Anti-pattern: `get` without `observable` (do not do this)
+
+```js
+definition.view({
+  name: 'brokenView',
+  properties: {
+    id: { type: String }
+  },
+  returns: { type: Object },
+  async get({ id }) {
+    return await SomeModel.get(id)
+  }
+})
+```
+
+## Step 3 – Online/offline triggers
+
+1. Identify events:
+   - session or connection goes online,
+   - session or connection goes offline.
+2. Define triggers with minimal `properties` (usually just an id).
+3. Update only the necessary fields (`status`, `lastSeenAt`, etc.).
+
+Example:
+
+```js
+definition.trigger({
+  name: 'sessionConnectionOnline',
+  properties: {
+    connection: { type: String }
+  },
+  async execute({ connection }, { service }) {
+    await Connection.update(connection, {
+      status: 'online',
+      lastSeenAt: new Date()
+    })
+  }
+})
+
+definition.trigger({
+  name: 'sessionConnectionOffline',
+  properties: {
+    connection: { type: String }
+  },
+  async execute({ connection }, { service }) {
+    await Connection.update(connection, {
+      status: 'offline'
+    })
+  }
+})
+```
+
+## Step 4 – Batch triggers (avoid full scans)
+
+1. Pick a **batch size** (e.g. 32 or 128).
+2. Use `rangeGet` with `gt: lastId` in a loop:
+   - start with `last = ''`,
+   - after each batch, set `last` to the last record’s id,
+   - stop when the batch is empty.
+
+Example:
+
+```js
+definition.trigger({
+  name: 'allOffline',
+  async execute({}, { service }) {
+    let last = ''
+    while(true) {
+      const items = await Connection.rangeGet({
+        gt: last,
+        limit: 32
+      })
+      if(items.length === 0) break
+
+      for(const item of items) {
+        await Connection.update(item.id, { status: 'offline' })
+      }
+
+      last = items[items.length - 1].id
+    }
+  }
+})
+```
+
+## Step 5 – Grant access on entity creation
+
+When a model uses `entity` with `writeAccessControl` / `readAccessControl`, the auto-generated CRUD checks roles but does **not** grant them. Add a change trigger to grant the creator `'owner'` after creation:
+
+```js
+definition.trigger({
+  name: 'changeMyService_MyModel',
+  properties: {
+    object: { type: MyModel, validation: ['nonEmpty'] },
+    data: { type: Object },
+    oldData: { type: Object }
+  },
+  async execute({ object, data, oldData }, { client, triggerService }) {
+    if (!data || oldData) return   // only on create (data present, no oldData)
+    if (!client?.user) return
+
+    await triggerService({ service: 'accessControl', type: 'accessControl_setAccess' }, {
+      objectType: 'myService_MyModel',   // format: serviceName_ModelName
+      object,
+      roles: ['owner'],
+      sessionOrUserType: 'user_User',
+      sessionOrUser: client.user,
+      lastUpdate: new Date()
+    })
+  }
+})
+```
+
+For publicly accessible objects, also call `accessControl_setPublicAccess`:
+
+```js
+await triggerService({ service: 'accessControl', type: 'accessControl_setPublicAccess' }, {
+  objectType: 'myService_MyModel',
+  object,
+  userRoles: ['reader'],       // roles for all logged-in users
+  sessionRoles: ['reader'],    // roles for all sessions (including anonymous)
+  lastUpdate: new Date()
+})
+```
+
+Key points:
+- `objectType` format: `serviceName_ModelName` (e.g. `company_Company`, `uploadedFiles_File`)
+- `sessionOrUserType`: `'user_User'` for logged-in users, `'session_Session'` for anonymous
+- For anonymous users: `sessionOrUser: client.session`
+- Use `Promise.all([...])` when setting both public and per-user access
+
+## Step 6 – Pending + resolve pattern for async results
+
+Use this pattern when an action initiates a command that will be completed by an external process (device, worker, etc.) and you want the action to wait with a timeout.
+
+### Steps
+
+1. Implement a helper module with an in-memory `Map`:
+   - `waitForCommand(id, timeoutMs)` – returns a Promise,
+   - `resolveCommand(id, result)` – resolves and clears timeout.
+2. In the main action:
+   - create a record with `status: 'pending'`,
+   - call `waitForCommand(id, timeoutMs)` and `return` the result.
+3. In the reporting action:
+   - update the record (`status: 'completed'`, `result`),
+   - call `resolveCommand(id, result)`.
+
+Helper sketch:
+
+```js
+const pendingCommands = new Map()
+
+export function waitForCommand(commandId, timeoutMs = 115000) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingCommands.delete(commandId)
+      reject(new Error('timeout'))
+    }, timeoutMs)
+    pendingCommands.set(commandId, { resolve, reject, timer })
+  })
+}
+
+export function resolveCommand(commandId, result) {
+  const pending = pendingCommands.get(commandId)
+  if(pending) {
+    clearTimeout(pending.timer)
+    pendingCommands.delete(commandId)
+    pending.resolve(result)
+  }
+}
+```
+

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

@@ -0,0 +1,230 @@
+---
+name: live-change-design-models-relations
+description: Design models with userItem, itemOf, propertyOf relations and access control
+---
+
+# Skill: live-change-design-models-relations (Claude Code)
+
+Use this skill when you design or refactor **models and relations** in a LiveChange service.
+
+## When to use
+
+- You are adding a new model to a service.
+- You want to switch from manual CRUD/views to proper relations.
+- You need consistent access control and index usage.
+
+## Step 1 – Decide the relation type
+
+For each new model, decide how it relates to the rest of the domain:
+
+- **`userItem`** – the object belongs to the signed-in user (e.g. user’s device).
+- **`itemOf`** – a list of children belonging to a parent model (e.g. device connections).
+- **`propertyOf`** – a single state object with the same id as the parent (e.g. cursor state).
+- **no relation** – for global data or other special cases.
+
+Choose one main relation; other associations can be plain fields + indexes.
+
+## Step 2 – Define `properties` clearly
+
+1. Use a **multi-line** style for properties, with clear `type`, `default`, `validation`, etc.
+2. Avoid unreadable one-liners combining everything.
+3. **Do NOT re-declare fields that are auto-added by relations.** Each relation automatically adds identifier fields and indexes:
+
+| Relation | Auto-added field(s) | Auto-added index(es) |
+|---|---|---|
+| `itemOf: { what: Device }` | `device` | `byDevice` |
+| `propertyOf: { what: Device }` | `device` | `byDevice` |
+| `userItem` | `user` | `byUser` |
+| `sessionOrUserProperty` | `sessionOrUserType`, `sessionOrUser` | `bySessionOrUser` |
+| `propertyOfAny: { to: ['owner'] }` | `ownerType`, `owner` | `byOwner` |
+
+Naming convention: parent model name with first letter lowercased (`Device` → `device`, `CostInvoice` → `costInvoice`). Polymorphic relations add a `Type` + value pair (e.g. `ownerType` + `owner`).
+
+Example:
+
+```js
+// ✅ Only define YOUR fields — 'device' is auto-added by itemOf
+properties: {
+  name: {
+    type: String,
+    validation: ['nonEmpty']
+  },
+  status: {
+    type: String,
+    default: 'offline'
+  },
+  capabilities: {
+    type: Array,
+    of: {
+      type: String
+    }
+  }
+}
+```
+
+## Step 3 – Configure the relation
+
+### `userItem`
+
+1. Add a `userItem` block inside the model definition.
+2. Set roles for read/write and list which fields can be written.
+
+```js
+userItem: {
+  readAccessControl: { roles: ['owner', 'admin'] },
+  writeAccessControl: { roles: ['owner', 'admin'] },
+  writeableProperties: ['name']
+}
+```
+
+### `itemOf`
+
+1. Decide the parent model.
+2. If the parent is in another service, declare it via `foreignModel` (see next step).
+
+```js
+itemOf: {
+  what: Device,
+  readAccessControl: { roles: ['owner', 'admin'] },
+  writeAccessControl: { roles: ['owner', 'admin'] }
+}
+```
+
+### `propertyOf`
+
+1. Use when the child should share the same id as the parent.
+2. This simplifies lookups and avoids extra indexes.
+
+```js
+propertyOf: {
+  what: Device,
+  readAccessControl: { roles: ['owner', 'admin'] },
+  writeAccessControl: { roles: ['owner', 'admin'] }
+}
+```
+
+### `propertyOf` with multiple parents (1:1 link to each)
+
+Use this when a model should act as a dedicated 1:1 link between multiple entities (e.g. invoice ↔ contractor role links),
+so the relations/CRUD generator can treat it as a relation rather than a plain `someId` property.
+
+Notes:
+
+- Usually you’ll have 1–2 parents, but the `propertyOf` list 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:
+
+```js
+const CostInvoice = definition.foreignModel('invoice', 'CostInvoice')
+const Contractor = definition.foreignModel('company', 'Contractor')
+
+definition.model({
+  name: 'Supplier',
+  properties: {
+    // optional extra fields
+  },
+  propertyOf: [
+    { what: CostInvoice },
+    { what: Contractor }
+  ]
+})
+```
+
+## Step 4 – Use `foreignModel` for cross-service relations
+
+1. At the top of the domain file, declare:
+
+```js
+const Device = definition.foreignModel('deviceManager', 'Device')
+```
+
+2. Then use `Device` in `itemOf` or `propertyOf`:
+
+```js
+itemOf: {
+  what: Device,
+  readAccessControl: { roles: ['owner', 'admin'] }
+}
+```
+
+## Step 5 – Add indexes
+
+1. Identify frequent queries:
+   - by a single field (e.g. `sessionKey`),
+   - by combinations (e.g. `(device, status)`).
+2. Declare indexes in the model:
+
+```js
+indexes: {
+  bySessionKey: {
+    property: ['sessionKey']
+  },
+  byDeviceAndStatus: {
+    property: ['device', 'status']
+  }
+}
+```
+
+3. Use these indexes in views/actions, via `indexObjectGet` / `indexRangeGet`.
+
+## Step 6 – Set access control on relations
+
+1. For `userItem`, `itemOf`, and `propertyOf`, always define:
+   - `readAccessControl`,
+   - `writeAccessControl`.
+2. Don’t rely on unspecified defaults; access rules should be explicit in the model.
+
+## Step 7 – Grant access on `entity` model creation
+
+Models with `entity` and `writeAccessControl` / `readAccessControl` check roles on every CRUD operation, but do **not** auto-grant roles to the creator. Without granting roles, the creator cannot even read their own object.
+
+Add a change trigger that grants `'owner'` on creation:
+
+```js
+definition.trigger({
+  name: 'changeMyService_MyModel',
+  properties: {
+    object: { type: MyModel, validation: ['nonEmpty'] },
+    data: { type: Object },
+    oldData: { type: Object }
+  },
+  async execute({ object, data, oldData }, { client, triggerService }) {
+    if (!data || oldData) return   // only on create
+    if (!client?.user) return
+
+    await triggerService({ service: 'accessControl', type: 'accessControl_setAccess' }, {
+      objectType: 'myService_MyModel',   // format: serviceName_ModelName
+      object,
+      roles: ['owner'],
+      sessionOrUserType: 'user_User',
+      sessionOrUser: client.user,
+      lastUpdate: new Date()
+    })
+  }
+})
+```
+
+For objects that should also be publicly readable, add `accessControl_setPublicAccess`:
+
+```js
+await triggerService({ service: 'accessControl', type: 'accessControl_setPublicAccess' }, {
+  objectType: 'myService_MyModel',
+  object,
+  userRoles: ['reader'],       // roles for all logged-in users
+  sessionRoles: ['reader'],    // roles for all sessions (including anonymous)
+  lastUpdate: new Date()
+})
+```
+
+**Note:** `userItem` and `itemOf`/`propertyOf` relations automatically handle access through the parent — you typically don't need manual `triggerService` calls for those. This step applies primarily to `entity` models.
+
+## Step 8 – Check auto-generated views/actions
+
+1. After adding relations, review the auto-generated views/actions:
+   - “my X” views and CRUD for `userItem`,
+   - parent-scoped lists for `itemOf`/`propertyOf`.
+2. Only add custom views/actions when:
+   - you need special filters,
+   - or custom logic not covered by the generated ones.
+

package/.cursor/skills/live-change-design-service.md

@@ -0,0 +1,76 @@
+---
+name: live-change-design-service
+description: Create or restructure a LiveChange backend service with proper directory layout
+---
+
+# Skill: live-change-design-service
+
+Ten skill opisuje **krok po kroku**, jak zaprojektować nowy serwis w LiveChange / live-change-stack albo sensownie rozbudować istniejący.
+
+## Kiedy używać
+
+Użyj tego skilla, gdy:
+
+- dodajesz **nowy serwis domenowy** do projektu,
+- przenosisz większy kawałek logiki z innego serwisu,
+- potrzebujesz upewnić się, że struktura plików i rejestracja serwisu są zgodne z konwencją.
+
+## Kroki – nowy serwis
+
+1. **Nazwij serwis**
+   - Wybierz zwięzłą, domenową nazwę, np. `payments`, `notifications`, `deviceManager`.
+   - Nazwa będzie używana jako `name` w `createServiceDefinition` oraz w `app.config.js`.
+
+2. **Utwórz katalog serwisu**
+   - Ścieżka: `server/services/<serviceName>/`.
+   - W katalogu utwórz pliki:
+     - `definition.js`
+     - `index.js`
+     - opcjonalnie `config.js`
+     - pliki domenowe (np. `models.js`, `authenticator.js`, `actions.js`), jeśli potrzebne.
+
+3. **Zaimplementuj `definition.js`**
+   - Importuj `app` z `@live-change/framework`.
+   - Jeśli serwis korzysta z relacji lub access control:
+     - importuj `relationsPlugin` z `@live-change/relations-plugin`,
+     - importuj `accessControlService` z `@live-change/access-control-service`.
+   - Wywołaj `app.createServiceDefinition({ name, use })`.
+   - **Nie** deklaruj tu modeli, akcji ani widoków.
+
+4. **Zaimplementuj `index.js`**
+   - Importuj `definition` z `./definition.js`.
+   - Importuj wszystkie pliki domenowe (np. `./models.js`, `./authenticator.js`).
+   - Eksportuj `definition` jako `default`.
+   - Nie dodawaj innej logiki do `index.js`.
+
+5. **(Opcjonalnie) utwórz `config.js`**
+   - Importuj `definition`.
+   - Odczytaj `definition.config` i rozwiąż wartości domyślne.
+   - Eksportuj plain object z konfiguracją serwisu.
+
+6. **Dodaj serwis do `services.list.js`**
+   - Importuj z katalogu serwisu, nie z pojedynczego pliku.
+   - Dodaj serwis do eksportowanego obiektu.
+
+7. **Dodaj serwis do `app.config.js`**
+   - W sekcji `services` dodaj `{ name: '<serviceName>' }`.
+   - Upewnij się, że kolejność jest sensowna:
+     - serwisy bazowe/plugins (user, session, accessControl) na początku,
+     - serwisy domenowe zależne od nich – dalej.
+
+8. **Sprawdź zależności**
+   - Jeśli serwis korzysta z modeli w innych serwisach:
+     - użyj `definition.foreignModel` wewnątrz domenowych plików serwisu,
+     - nie importuj bezpośrednio ich plików modeli.
+   - Upewnij się, że serwisy, od których zależysz, są wcześniejsze w `app.config.js`.
+
+## Kroki – rozbudowa istniejącego serwisu
+
+1. Przejrzyj istniejący katalog `server/services/<serviceName>/`.
+2. Sprawdź, czy `definition.js` ma poprawne `use` (relacje, accessControl).
+3. Nowe modele/akcje/widoki/triggery dodaj do **osobnych plików domenowych**:
+   - jeśli logika jest powiązana z istniejącym modelem – do jego pliku,
+   - jeśli tworzysz większy nowy obszar – do nowego pliku (np. `notifications.js`).
+4. Upewnij się, że nowy plik jest importowany w `index.js`.
+5. Nie dodawaj ciężkiej logiki do `definition.js` ani `index.js`.
+