@live-change/frontend-template 0.9.197 → 0.9.199

package/.claude/skills/live-change-frontend-ssr-setup.md

@@ -0,0 +1,118 @@
+---
+description: Set up SSR entry points, router, PrimeVue theme and Suspense data loading
+---
+
+# Skill: live-change-frontend-ssr-setup (Claude Code)
+
+Use this skill to set up or adjust a **LiveChange SSR frontend**:
+
+- client/server entry points,
+- router + `meta.signedIn`,
+- PrimeVue theme configuration.
+
+## Step 1 – Client and server entry points
+
+1. Ensure the frontend has two entry files:
+   - `entry-client.js` (or `.ts`),
+   - `entry-server.js` (or `.ts`).
+
+2. Use helpers from `@live-change/frontend-base`:
+
+```js
+// entry-client.js
+import { clientEntry } from '@live-change/frontend-base/client-entry.js'
+import App from './App.vue'
+import { createRouter } from './router.js'
+import { config } from './config.js'
+
+export default clientEntry(App, createRouter, config)
+```
+
+```js
+// entry-server.js
+import { serverEntry, sitemapEntry } from '@live-change/frontend-base/server-entry.js'
+import App from './App.vue'
+import { createRouter, routerSitemap } from './router.js'
+import { config } from './config.js'
+
+export const render = serverEntry(App, createRouter, config)
+export const sitemap = sitemapEntry(App, createRouter, routerSitemap, config)
+```
+
+## Step 2 – Router and `meta.signedIn`
+
+1. Use `vite-plugin-pages` to auto-generate routes from `src/pages/`.
+2. Add a `<route>` block to each page with basic meta:
+
+```vue
+<route>
+  { "name": "devices", "meta": { "signedIn": true } }
+</route>
+```
+
+3. Add a navigation guard for signed-in pages:
+
+```js
+router.beforeEach((to) => {
+  if(to.meta.signedIn && !isLoggedIn()) {
+    localStorage.setItem('redirectAfterLogin', to.fullPath)
+    return { name: 'user:signIn' }
+  }
+})
+```
+
+Implement `isLoggedIn()` according to the project’s auth/session model.
+
+## Step 3 – PrimeVue theme configuration
+
+1. In `config.js`, configure the PrimeVue theme using `definePreset`:
+
+```js
+import { definePreset } from '@primevue/themes'
+import Aura from '@primevue/themes/aura'
+
+const MyPreset = definePreset(Aura, {
+  semantic: {
+    primary: {
+      50: '{indigo.50}',
+      100: '{indigo.100}',
+      200: '{indigo.200}',
+      300: '{indigo.300}',
+      400: '{indigo.400}',
+      500: '{indigo.500}',
+      600: '{indigo.600}',
+      700: '{indigo.700}',
+      800: '{indigo.800}',
+      900: '{indigo.900}',
+      950: '{indigo.950}'
+    }
+  }
+})
+
+export const config = {
+  theme: {
+    preset: MyPreset,
+    options: {
+      darkModeSelector: '.app-dark-mode'
+    }
+  }
+}
+```
+
+2. Ensure the app uses this config when initializing PrimeVue (usually in `App.vue` / main entry).
+
+## Step 4 – Global components and forms
+
+1. In `App.vue` (or main setup), register global components used throughout the app:
+   - auto-form components,
+   - common layout components, etc.
+2. This allows pages to use components like `<command-form>` without local imports.
+
+## Step 5 – SSR-friendly data loading
+
+1. Ensure the root of the app (e.g. `ViewRoot`) wraps content in `<Suspense>`.
+2. In page components:
+   - use `await Promise.all([live(path()....)])` inside `script setup`,
+   - read from `.value` in templates,
+   - **do not** fetch main data in `onMounted`.
+

package/.cursor/rules/live-change-backend-actions-views-triggers.mdc

@@ -0,0 +1,202 @@
+---
+description: Rules for implementing actions, views, and triggers in LiveChange services
+globs: **/services/**/*.js
+alwaysApply: false
+---
+
+# LiveChange backend – akcje, widoki, triggery
+
+## Akcje – ogólne zasady
+
+- Akcje umieszczaj w plikach domenowych, razem z modelami, których dotyczą.
+- Każda akcja powinna:
+  - jasno określać wejście (`properties`),
+  - wykonywać minimalną potrzebną walidację,
+  - używać indeksów zamiast pełnych skanów,
+  - zwracać sensowny wynik (ID obiektu, fragment stanu itp.).
+
+### Wzorzec prostej akcji
+
+```js
+definition.action({
+  name: 'registerDeviceConnection',
+  properties: {
+    pairingKey: {
+      type: String
+    },
+    connectionType: {
+      type: String
+    },
+    capabilities: {
+      type: Array
+    }
+  },
+  async execute({ pairingKey, connectionType, capabilities }, { client, service }) {
+    const device = await Device.indexObjectGet('byPairingKey', { pairingKey })
+    if(!device) throw new Error('notFound')
+
+    const id = app.generateUid()
+    const sessionKey = app.generateUid() + app.generateUid()
+
+    await DeviceConnection.create({
+      id,
+      device: device.id,
+      connectionType,
+      capabilities,
+      sessionKey,
+      status: 'offline'
+    })
+
+    return { connectionId: id, sessionKey }
+  }
+})
+```
+
+## Widoki – ogólne zasady
+
+- Widok ma być prostym, czytelnym wejściem do danych:
+  - korzystaj z indeksów (`indexObjectGet`, `indexRangeGet`),
+  - nie implementuj skomplikowanej logiki w widokach, jeśli można ją przenieść do akcji.
+
+### Wzorzec widoku zakresowego
+
+```js
+definition.view({
+  name: 'pendingCommands',
+  properties: {
+    connectionId: {
+      type: String
+    }
+  },
+  async get({ connectionId }, { client, service }) {
+    return BotCommand.indexRangeGet('byConnectionAndStatus', {
+      connection: connectionId,
+      status: 'pending'
+    })
+  }
+})
+```
+
+## Triggery – online/offline i batchowanie
+
+- Triggery są do reakcji na zdarzenia (np. zmiana stanu sesji, start serwera).
+- Dwie podstawowe kategorie:
+  - triggery dla pojedynczych obiektów (np. połączenie online/offline),
+  - triggery „hurtowe” (np. ustawienie wszystkich na offline przy starcie).
+
+### Wzorzec triggerów online/offline
+
+```js
+definition.trigger({
+  name: 'sessionDeviceConnectionOnline',
+  properties: {
+    connection: {
+      type: String
+    }
+  },
+  async execute({ connection }, { service }) {
+    await DeviceConnection.update(connection, {
+      status: 'online',
+      lastSeenAt: new Date()
+    })
+  }
+})
+
+definition.trigger({
+  name: 'sessionDeviceConnectionOffline',
+  properties: {
+    connection: {
+      type: String
+    }
+  },
+  async execute({ connection }, { service }) {
+    await DeviceConnection.update(connection, {
+      status: 'offline'
+    })
+  }
+})
+```
+
+### Wzorzec batchowania odczytów (unikaj pełnych skanów)
+
+- Przy triggerach, które mają przejść po wielu rekordach, **zawsze** używaj paginacji:
+  - stały `limit` (np. 32 lub 128),
+  - zakres po kluczu (`gt: lastId`),
+  - pętla aż do pustego batcha.
+
+```js
+definition.trigger({
+  name: 'allOffline',
+  async execute({}, { service }) {
+    let last = ''
+    while(true) {
+      const connections = await DeviceConnection.rangeGet({
+        gt: last,
+        limit: 32
+      })
+      if(connections.length === 0) break
+
+      for(const conn of connections) {
+        await DeviceConnection.update(conn.id, {
+          status: 'offline'
+        })
+      }
+
+      last = connections[connections.length - 1].id
+    }
+  }
+})
+```
+
+## Wzorzec „pending + resolve” (asynchroniczny wynik)
+
+- Używaj, gdy akcja w serwisie musi poczekać na wynik z zewnętrznego procesu (np. urządzenie, worker).
+- Struktura:
+  1. Akcja tworzy rekord „pending”.
+  2. Akcja czeka na `Promise` powiązany z ID.
+  3. Inna akcja/trigger aktualizuje rekord i rozwiązuje `Promise`.
+
+Szkic:
+
+```js
+// pendingCommands.js – singleton w pamięci
+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)
+  }
+}
+```
+
+W akcji wywołującej:
+
+```js
+await SomeCommand.create({ id, status: 'pending', ... })
+const result = await waitForCommand(id)
+return result
+```
+
+W akcji raportującej:
+
+```js
+await SomeCommand.update(id, {
+  status: 'completed',
+  result
+})
+resolveCommand(id, result)
+```
+

package/.cursor/rules/live-change-backend-architecture.mdc

@@ -0,0 +1,131 @@
+---
+description: Rules for LiveChange backend service architecture and directory structure
+globs: **/services/**/*.js
+alwaysApply: false
+---
+
+# LiveChange backend – architektura serwisów
+
+## Główna zasada
+
+- Każdy serwis LiveChange **musi być katalogiem**, nie pojedynczym plikiem.
+- Serwis ma czytelną, powtarzalną strukturę plików.
+
+## Struktura katalogu serwisu
+
+```
+server/services/<serviceName>/
+  definition.js  # createServiceDefinition + use – żadnych modeli/akcji
+  index.js       # import definition, import plików domenowych, export definition
+  config.js      # opcjonalnie – rozwiązywanie definition.config do plain object
+  <domain>.js    # pliki domenowe: modele, widoki, akcje, triggery
+```
+
+### `definition.js`
+
+- Importuj `app` z `@live-change/framework`.
+- Twórz definicję serwisu **bez** modeli/akcji/widoków w tym pliku.
+- Jeśli serwis używa relacji lub kontroli dostępu, **od razu** podłącz pluginy w `use`.
+
+Przykład:
+
+```js
+import { app } from '@live-change/framework'
+import relationsPlugin from '@live-change/relations-plugin'
+import accessControlService from '@live-change/access-control-service'
+
+const definition = app.createServiceDefinition({
+  name: 'myService',
+  use: [relationsPlugin, accessControlService]
+})
+
+export default definition
+```
+
+### `index.js`
+
+- Importuj `definition`.
+- Importuj wszystkie pliki domenowe tylko po to, żeby wykonały się side-effecty (rejestracja modeli/akcji/widoków/triggerów).
+- Eksportuj `definition` jako default.
+
+```js
+import definition from './definition.js'
+
+import './modelA.js'
+import './modelB.js'
+import './authenticator.js'
+
+export default definition
+```
+
+### `config.js` (opcjonalnie)
+
+- Czyta `definition.config` (ustawiane w `app.config.js`).
+- Nadaje wartości domyślne i eksportuje zwykły obiekt.
+
+```js
+import definition from './definition.js'
+
+const {
+  someOption = 'default'
+} = definition.config
+
+export default { someOption }
+```
+
+## Rejestracja serwisu w projekcie
+
+### `services.list.js`
+
+- Importuj serwis z jego `index.js` w katalogu, nie z płaskiego pliku.
+
+```js
+import myService from './services/myService/index.js'
+
+export default {
+  // ...
+  myService
+}
+```
+
+### `app.config.js`
+
+- Upewnij się, że nazwa serwisu w configu odpowiada nazwie z `createServiceDefinition`.
+- Zachowaj **sensowną kolejność** serwisów:
+  - na początku serwisy bazowe, wspólne i pluginy,
+  - na końcu serwisy właściwe dla aplikacji, które z nich korzystają.
+
+```js
+services: [
+  // serwisy bazowe / wspólne
+  { name: 'user' },
+  { name: 'session' },
+  { name: 'accessControl' },
+  // ...
+  // serwisy własne aplikacji
+  { name: 'myService' }
+]
+```
+
+## Podgląd serwisów komendą `describe`
+
+Komenda CLI `describe` pokazuje co framework wygenerował z twoich definicji (modele, widoki, akcje, triggery, indeksy, eventy):
+
+```bash
+# Przegląd wszystkich serwisów
+node server/start.js describe
+
+# Jeden serwis w YAML (z wygenerowanym kodem)
+node server/start.js describe --service myService --output yaml
+
+# Konkretna encja
+node server/start.js describe --service myService --model MyModel --output yaml
+```
+
+Szczególnie przydatne po użyciu relacji (`userItem`, `itemOf`, `propertyOf`) — `describe` pokaże wszystkie automatycznie wygenerowane widoki, akcje, triggery i indeksy.
+
+## Kiedy tworzyć nowy serwis
+
+- Gdy masz wyraźnie wydzieloną domenę (np. urządzenia, płatności, powiadomienia).
+- Gdy zestaw modeli/akcji/widoków ma własną konfigurację i zależności.
+- Gdy logika nie mieści się sensownie w istniejącym serwisie bez mieszania odpowiedzialności.

package/.cursor/rules/live-change-backend-models-and-relations.mdc

@@ -0,0 +1,194 @@
+---
+description: Rules for defining models, relations, indexes and access control in LiveChange
+globs: **/services/**/*.js
+alwaysApply: false
+---
+
+# LiveChange backend – modele i relacje
+
+## Ogólne zasady
+
+- Modele zapisuj w plikach domenowych (`<domain>.js`) importowanych w `index.js` serwisu.
+- Dbaj o czytelność definicji – **właściwości wieloliniowo**, z jasnymi polami `type`, `default`, `validation` itd.
+- Tam, gdzie to możliwe, używaj relacji (`userItem`, `itemOf`, `propertyOf`, `foreignModel`) zamiast ręcznego klepania CRUD i widoków.
+
+## Styl definicji `properties`
+
+- Każde pole opisane wieloliniowo, jedna rzecz na linię.
+- Unikaj upychania typu i walidacji w jednej linii, jeśli zmniejsza to czytelność.
+
+```js
+properties: {
+  name: {
+    type: String,
+    validation: ['nonEmpty']
+  },
+  status: {
+    type: String,
+    default: 'offline'
+  },
+  capabilities: {
+    type: Array,
+    of: {
+      type: String
+    }
+  }
+}
+```
+
+## `userItem` – zasób należący do użytkownika
+
+Używaj, gdy model należy do zalogowanego użytkownika.
+
+```js
+definition.model({
+  name: 'Device',
+  properties: {
+    name: {
+      type: String
+    }
+  },
+  userItem: {
+    readAccessControl: { roles: ['owner', 'admin'] },
+    writeAccessControl: { roles: ['owner', 'admin'] },
+    writeableProperties: ['name']
+  }
+})
+```
+
+Skutek:
+
+- automatyczne widoki typu „moje X”,
+- automatyczne akcje create/update/delete dla właściciela.
+
+## `itemOf` – dziecko należy do rodzica
+
+Używaj, gdy model jest listą elementów powiązanych z innym modelem.
+
+```js
+definition.model({
+  name: 'DeviceConnection',
+  properties: {
+    connectionType: {
+      type: String
+    },
+    status: {
+      type: String,
+      default: 'offline'
+    }
+  },
+  itemOf: {
+    what: Device,
+    readAccessControl: { roles: ['owner', 'admin'] },
+    writeAccessControl: { roles: ['owner', 'admin'] }
+  }
+})
+```
+
+Zasady:
+
+- rodzic `what` to model zadeklarowany wcześniej w tym lub innym serwisie,
+- relacja generuje standardowe widoki/akcje dla listy i elementów.
+
+## `propertyOf` – właściwość z ID równym rodzicowi
+
+Używaj, gdy model przechowuje „stan” jednego obiektu (ID dziecka = ID rodzica).
+
+```js
+definition.model({
+  name: 'DeviceCursorState',
+  properties: {
+    x: { type: Number },
+    y: { type: Number }
+  },
+  propertyOf: {
+    what: Device,
+    readAccessControl: { roles: ['owner', 'admin'] },
+    writeAccessControl: { roles: ['owner', 'admin'] }
+  }
+})
+```
+
+Skutek:
+
+- prosty dostęp: `DeviceCursorState.get(deviceId)`,
+- bez potrzeby dodatkowych indeksów po polu `device`.
+
+## `propertyOf` dla wielu modeli (relacja 1:1 do każdego z nich)
+
+W niektórych domenach model jest „łącznikiem 1:1” pomiędzy rekordami (np. faktura ↔ kontrahent w roli dostawcy/klienta).
+Najczęściej są to 2 modele, ale `propertyOf` może wskazywać na **dowolnie wiele** modeli (np. relacja łącząca 3+ encje), jeśli taka jest semantyka domeny.
+
+Wtedy:
+
+- **nie** przechowuj „drugiej strony” jako zwykłego `contractorId` (albo ogólnie `someId`) w `properties`
+- **nie** dodawaj ręcznie pól `...Id` w modelu relacyjnym, jeśli to ma być relacja – to utrudnia generatorowi CRUD/relacji poprawne wnioskowanie o powiązaniach
+- zamiast tego zdefiniuj relacje jako `propertyOf` do **każdego** z modeli, które mają być rodzicami relacji
+
+To jest istotne, bo generator CRUD/relacji rozumie wtedy, że encja jest powiązaniem pomiędzy dwiema encjami, a nie „zwykłym obiektem z polem id”.
+
+Przykład (schematycznie):
+
+```js
+const CostInvoice = definition.foreignModel('invoice', 'CostInvoice')
+const Contractor = definition.foreignModel('company', 'Contractor')
+
+definition.model({
+  name: 'Supplier',
+  properties: {
+    // dodatkowe pola relacji (opcjonalnie)
+  },
+  propertyOf: [
+    { what: CostInvoice },
+    { what: Contractor }
+  ]
+})
+```
+
+## `foreignModel` – relacja do modelu z innego serwisu
+
+Używaj, gdy `itemOf`/`propertyOf` ma wskazywać na model spoza aktualnego serwisu.
+
+```js
+const Device = definition.foreignModel('deviceManager', 'Device')
+
+definition.model({
+  name: 'BotSession',
+  properties: {
+    // ...
+  },
+  itemOf: {
+    what: Device,
+    readAccessControl: { roles: ['owner', 'admin'] }
+  }
+})
+```
+
+Zasady:
+
+- pierwszy argument to nazwa serwisu,
+- drugi to nazwa modelu w tamtym serwisie.
+
+## Indeksy
+
+- Definiuj indeksy jawnie w modelu, gdy będziesz często wyszukiwać po danym polu lub kombinacji pól.
+- Nazwy indeksów powinny być opisowe, bez skrótów trudnych do odczytania.
+
+```js
+indexes: {
+  bySessionKey: {
+    property: ['sessionKey']
+  },
+  byDeviceAndStatus: {
+    property: ['device', 'status']
+  }
+}
+```
+
+Poza serwisem indeks bywa widoczny pod nazwą z prefiksem serwisu, np. `myService_Model_byDeviceAndStatus`.
+
+## Access control na relacjach
+
+- Zawsze ustawiaj `readAccessControl` i `writeAccessControl` na relacjach (`userItem`, `itemOf`, `propertyOf`), zamiast polegać na domyślnym zachowaniu.
+- Traktuj to jako część modelu, nie dodatek na końcu.
+