@live-change/frontend-template 0.9.199 → 0.9.201

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

@@ -1,46 +1,41 @@
 ---
+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
+# Skill: live-change-design-actions-views-triggers (Claude Code)
 
-Ten skill opisuje **krok po kroku**, jak projektować akcje, widoki i triggery w serwisach LiveChange, korzystając z indeksów i unikając pełnych skanów.
+Use this skill to design **actions, views, and triggers** in LiveChange services while making good use of indexes and avoiding full-table scans.
 
-## Kiedy używać
+## When to use
 
-Użyj tego skilla, gdy:
+- 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).
 
-- dodajesz nowe akcje do istniejących modeli,
-- tworzysz widoki (szczególnie zakresowe) dla list,
-- implementujesz triggery (online/offline, batchowe przetwarzanie, asynchroniczne wyniki).
+## Step 1 – Design an action
 
-## 1. Projekt akcji
+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.
 
-1. **Określ cel akcji**
-   - Czy tworzy/aktualizuje/usunie obiekt?
-   - Czy ma czekać na zewnętrzny wynik (np. urządzenie)?
-
-2. **Zdefiniuj `properties`**
-   - Każde pole opisane wieloliniowo,
-   - tylko to, co faktycznie potrzebne – resztę pobieraj z bazy na podstawie kluczy.
-
-3. **Użyj indeksów do wyszukiwania**
-   - Zamiast pełnych skanów, korzystaj z `indexObjectGet` / `indexRangeGet`.
-
-4. **Zwróć sensowny wynik**
-   - ID utworzonego obiektu,
-   - klucze sesyjne, jeśli trzeba je przechować po stronie klienta,
-   - dane potrzebne do dalszych kroków.
-
-### Szkic wzorca
+Example:
 
 ```js
 definition.action({
   name: 'someAction',
   properties: {
-    someKey: {
-      type: String
-    }
+    someKey: { type: String }
   },
   async execute({ someKey }, { client, service }) {
     const obj = await SomeModel.indexObjectGet('bySomeKey', { someKey })
@@ -49,7 +44,7 @@ definition.action({
     const id = app.generateUid()
 
     await SomeOtherModel.create({
-      id,
+      id
       // ...
     })
 
@@ -58,56 +53,106 @@ definition.action({
 })
 ```
 
-## 2. Projekt widoku
+## Step 2 – Design a view
 
-1. **Zdecyduj, czy to pojedynczy obiekt czy lista**
-   - pojedynczy: użyj `get` lub `indexObjectGet`,
-   - lista: użyj `indexRangeGet` z indeksem.
+1. Decide what kind of data source you have, then pick the **view variant** (exactly one):
 
-2. **Zdefiniuj `properties` widoku**
-   - tylko parametry potrzebne do wyszukiwania,
-   - typy zgodne z modelem (String/Number/itp.).
+| 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`. |
 
-3. **Użyj indeksów**
+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
 
-Przykład widoku zakresowego:
+### Example: `daoPath` (preferred, DAO-backed)
 
 ```js
 definition.view({
-  name: 'myItemsByStatus',
+  name: 'costInvoice',
   properties: {
-    status: {
+    costInvoice: {
       type: String
     }
   },
-  async get({ status }, { client, service }) {
-    return MyModel.indexRangeGet('byStatus', {
-      status
-    })
+  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)
   }
 })
 ```
 
-## 3. Triggery – online/offline
+### Anti-pattern: `get` without `observable` (do not do this)
 
-1. **Zidentyfikuj zdarzenie**
-   - np. „połączenie online/offline”, „sesja utworzona”, „serwer się uruchomił”.
+```js
+definition.view({
+  name: 'brokenView',
+  properties: {
+    id: { type: String }
+  },
+  returns: { type: Object },
+  async get({ id }) {
+    return await SomeModel.get(id)
+  }
+})
+```
 
-2. **Zdefiniuj trigger z `properties`**
-   - triggery online/offline zwykle potrzebują tylko ID obiektu.
+## Step 3 – Online/offline triggers
 
-3. **Aktualizuj minimalny zestaw pól**
-   - np. `status`, `lastSeenAt`.
+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.).
 
-Przykład:
+Example:
 
 ```js
 definition.trigger({
   name: 'sessionConnectionOnline',
   properties: {
-    connection: {
-      type: String
-    }
+    connection: { type: String }
   },
   async execute({ connection }, { service }) {
     await Connection.update(connection, {
@@ -116,17 +161,29 @@ definition.trigger({
     })
   }
 })
+
+definition.trigger({
+  name: 'sessionConnectionOffline',
+  properties: {
+    connection: { type: String }
+  },
+  async execute({ connection }, { service }) {
+    await Connection.update(connection, {
+      status: 'offline'
+    })
+  }
+})
 ```
 
-## 4. Triggery batchowe – unikaj pełnych skanów
+## Step 4 – Batch triggers (avoid full scans)
 
-1. **Ustal limit batcha** (np. 32 lub 128 rekordów).
-2. **Wykorzystaj `rangeGet` z `gt: lastId`**
-   - inicjalnie `last = ''`,
-   - po każdym batchu ustaw `last` na ID ostatniego rekordu.
-3. **Kończ, gdy batch jest pusty**.
+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.
 
-Przykład:
+Example:
 
 ```js
 definition.trigger({
@@ -141,9 +198,7 @@ definition.trigger({
       if(items.length === 0) break
 
       for(const item of items) {
-        await Connection.update(item.id, {
-          status: 'offline'
-        })
+        await Connection.update(item.id, { status: 'offline' })
       }
 
       last = items[items.length - 1].id
@@ -152,25 +207,69 @@ definition.trigger({
 })
 ```
 
-## 5. Wzorzec „pending + resolve” dla asynchronicznych wyników
+## 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
 
-Użyj tego wzorca, gdy:
+## Step 6 – Pending + resolve pattern for async results
 
-- akcja tworzy zlecenie/komendę,
-- wynik przychodzi później z innego procesu (urządzenie, worker, itp.),
-- chcesz, żeby akcja czekała na wynik z timeoutem.
+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.
 
-### Kroki
+### Steps
 
-1. Utwórz helper `pendingCommands` (Map) w osobnym module.
-2. W akcji tworzącej:
-   - utwórz rekord z `status: 'pending'`,
-   - wywołaj `waitForCommand(id, timeoutMs)`.
-3. W akcji raportującej:
-   - zaktualizuj rekord (`status: 'completed'`, `result`),
-   - wywołaj `resolveCommand(id, result)`.
+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)`.
 
-### Szkic helpera
+Helper sketch:
 
 ```js
 const pendingCommands = new Map()

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

@@ -1,39 +1,49 @@
 ---
+name: live-change-design-models-relations
 description: Design models with userItem, itemOf, propertyOf relations and access control
 ---
 
-# Skill: live-change-design-models-relations
+# Skill: live-change-design-models-relations (Claude Code)
 
-Ten skill opisuje **krok po kroku**, jak projektować modele i relacje (`userItem`, `itemOf`, `propertyOf`, `foreignModel`) w serwisach LiveChange.
+Use this skill when you design or refactor **models and relations** in a LiveChange service.
 
-## Kiedy używać
+## When to use
 
-Użyj tego skilla, gdy:
+- 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.
 
-- dodajesz nowy model do serwisu,
-- przenosisz dane z ręcznego CRUD na relacje,
-- potrzebujesz spójnego wzorca dla access control i indeksów.
+## Step 1 – Decide the relation type
 
-## 1. Dobierz typ relacji
+For each new model, decide how it relates to the rest of the domain:
 
-Zastanów się, jak model jest powiązany z resztą domeny:
+- **`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.
 
-- **`userItem`** – obiekt należy do zalogowanego użytkownika (np. konto, urządzenie użytkownika).
-- **`itemOf`** – lista elementów należy do innego modelu (np. połączenia urządzenia, pozycje zamówienia).
-- **`propertyOf`** – pojedyncza właściwość/model ze stanem o ID równym rodzicowi (np. stan kursora, ustawienia).
-- **bez relacji** – gdy obiekt jest globalny lub ma inną strukturę (np. globalny config).
+Choose one main relation; other associations can be plain fields + indexes.
 
-Wybierz jedną główną relację na model – dodatkowe powiązania możesz odzwierciedlić polami i indeksami.
+## Step 2 – Define `properties` clearly
 
-## 2. Zdefiniuj `properties` w czytelny sposób
+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:
 
-1. Utwórz sekcję `properties`:
-   - każdą właściwość zapisuj wieloliniowo,
-   - jasno określ typ, domyślne wartości, walidację.
+| 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` |
 
-2. Przykład:
+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,
@@ -52,13 +62,12 @@ properties: {
 }
 ```
 
-## 3. Skonfiguruj relację
+## Step 3 – Configure the relation
 
 ### `userItem`
 
-1. Dodaj blok `userItem` w definicji modelu.
-2. Ustaw role dla odczytu i zapisu.
-3. Ogranicz `writeableProperties` do pól, które użytkownik może zmieniać.
+1. Add a `userItem` block inside the model definition.
+2. Set roles for read/write and list which fields can be written.
 
 ```js
 userItem: {
@@ -70,8 +79,8 @@ userItem: {
 
 ### `itemOf`
 
-1. Ustal model rodzica (`what`).
-2. W razie potrzeby użyj `definition.foreignModel`, jeśli rodzic jest w innym serwisie.
+1. Decide the parent model.
+2. If the parent is in another service, declare it via `foreignModel` (see next step).
 
 ```js
 itemOf: {
@@ -83,8 +92,8 @@ itemOf: {
 
 ### `propertyOf`
 
-1. Użyj, gdy chcesz, żeby ID modelu = ID rodzica.
-2. To ułatwia odczyt (`Model.get(parentId)`).
+1. Use when the child should share the same id as the parent.
+2. This simplifies lookups and avoids extra indexes.
 
 ```js
 propertyOf: {
@@ -94,17 +103,17 @@ propertyOf: {
 }
 ```
 
-### `propertyOf` z wieloma rodzicami (1:1 relacja do wielu encji)
+### `propertyOf` with multiple parents (1:1 link to each)
 
-Użyj, gdy model ma być „łącznikiem 1:1” pomiędzy kilkoma encjami (np. faktura ↔ kontrahent w konkretnej roli),
-żeby generator relacji/CRUD rozumiał, że to jest relacja, a nie pole `someId` w `properties`.
+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.
 
-Uwagi:
+Notes:
 
-- Najczęściej jest to 1 lub 2 rodziców, ale lista `propertyOf` może zawierać **dowolnie wiele** modeli (np. relacja łącząca 3+ encje).
-- Jeśli encja jest relacją, **nie dodawaj ręcznie** pól typu `...Id` w `properties` tylko po to, żeby “zrobić join” – generator CRUD nie potraktuje tego jako relacji.
+- 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.
 
-Przykład:
+Example:
 
 ```js
 const CostInvoice = definition.foreignModel('invoice', 'CostInvoice')
@@ -113,7 +122,7 @@ const Contractor = definition.foreignModel('company', 'Contractor')
 definition.model({
   name: 'Supplier',
   properties: {
-    // opcjonalne pola dodatkowe
+    // optional extra fields
   },
   propertyOf: [
     { what: CostInvoice },
@@ -122,20 +131,29 @@ definition.model({
 })
 ```
 
-### `foreignModel`
+## Step 4 – Use `foreignModel` for cross-service relations
 
-1. Na początku pliku z modelem zadeklaruj:
+1. At the top of the domain file, declare:
 
 ```js
 const Device = definition.foreignModel('deviceManager', 'Device')
 ```
 
-2. Potem używaj `Device` w `itemOf`/`propertyOf`.
+2. Then use `Device` in `itemOf` or `propertyOf`:
 
-## 4. Dodaj indeksy
+```js
+itemOf: {
+  what: Device,
+  readAccessControl: { roles: ['owner', 'admin'] }
+}
+```
 
-1. Zidentyfikuj typowe zapytania (np. po `sessionKey`, po `(device, status)`).
-2. Dodaj sekcję `indexes`:
+## 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: {
@@ -148,21 +166,65 @@ indexes: {
 }
 ```
 
-3. Używaj tych indeksów w widokach i akcjach (`indexObjectGet`, `indexRangeGet`).
+3. Use these indexes in views/actions, via `indexObjectGet` / `indexRangeGet`.
 
-## 5. Ustal access control na poziomie modelu/relacji
+## Step 6 – Set access control on relations
 
-1. Dla `userItem` / `itemOf` / `propertyOf` ustaw zawsze:
+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.
 
-2. Nie zakładaj domyślnych reguł – wpisz je wprost w definicji modelu.
+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()
+})
+```
 
-## 6. Sprawdź wygenerowane widoki/akcje
+**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.
 
-Po dodaniu relacji:
+## Step 8 – Check auto-generated views/actions
 
-1. Sprawdź, jakie widoki/akcje generuje plugin (np. `myUserDevices`, `createMyUserDevice`, itp.).
-2. Zastanów się, czy potrzebujesz dodatkowych, niestandardowych widoków/akcji:
-   - jeśli tak, dodaj je, ale **nie duplikuj** tego, co generuje relacja.
+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

@@ -1,4 +1,5 @@
 ---
+name: live-change-design-service
 description: Create or restructure a LiveChange backend service with proper directory layout
 ---