@live-change/frontend-template 0.9.197 → 0.9.199

package/.cursor/rules/live-change-frontend-vue-primevue.mdc

@@ -0,0 +1,290 @@
+---
+description: Rules for Vue 3, PrimeVue, Tailwind frontend development on LiveChange
+globs: **/front/src/**/*.{vue,js,ts}
+alwaysApply: false
+---
+
+# Frontend na live-change-stack – Vue 3 + PrimeVue + Tailwind
+
+## Stack
+
+- Vue 3 + TypeScript
+- PrimeVue 4 – główna biblioteka komponentów UI
+- Tailwind CSS – podstawowe stylowanie (unikaj zbędnego custom CSS)
+- vite-plugin-pages – file-based routing w `src/pages/`
+- @live-change/vue3-ssr – integracja z backendem LiveChange
+
+## Pobieranie danych – `live` + `Promise.all`
+
+- **Nie** używaj `ref(null)` + `onMounted` do ładowania danych.
+- Dane ładuj w `setup`/`script setup` przez `await Promise.all(...)` na `live(path()....)`.
+- Rodzic powinien owijać stronę w `<Suspense>` (w projektach live-change robi to zazwyczaj `ViewRoot` globalnie).
+
+Przykład:
+
+```js
+import { path, live, api as useApi } from '@live-change/vue3-ssr'
+
+const api = useApi()
+
+const [devices] = await Promise.all([
+  live(path().deviceManager.myUserDevices({}))
+])
+
+const [device, connections] = await Promise.all([
+  live(path().deviceManager.myUserDevice({ device: deviceId })),
+  live(path().deviceManager.deviceOwnedDeviceConnections({ device: deviceId }))
+])
+```
+
+Dostęp w template:
+
+```vue
+<template>
+  <div v-if="device.value">
+    {{ device.value.name }}
+  </div>
+</template>
+```
+
+## Komendy i formularze – wybór wzorca
+
+Są 4 sposoby wywoływania akcji backendowych. Używaj właściwego:
+
+| Wzorzec | Kiedy używać |
+|---|---|
+| `editorData` | **Edycja rekordów modelu** (create/update). Drafty, walidacja, `AutoField`. Ustawienia, edytory, profile. |
+| `actionData` | **Jednorazowe formularze akcji** (nie CRUD). Submit → done. Publikacja, zaproszenie, import. |
+| `api.command` | **Pojedynczy przycisk lub wywołanie z kodu** (bez pól formularza). Usuwanie, toggle, akcje z kodu. |
+| `<command-form>` | **Unikaj.** Legacy, tylko trywialne prototypy. Preferuj `editorData` lub `actionData`. |
+
+Schemat decyzji:
+
+1. Użytkownik wypełnia pola formularza? → **Nie**: użyj `api.command` (owijaj w `workingZone.addPromise` dla przycisków).
+2. Edytuje rekord modelu (create/update)? → **Tak**: użyj `editorData`. **Nie**: użyj `actionData`.
+3. `<command-form>` tylko do najprostszych jednorazowych przypadków.
+
+### `api.command`
+
+```js
+await api.command(['deviceManager', 'createMyUserDevice'], {
+  name: 'Moje urządzenie'
+})
+
+await api.command(['deviceManager', 'deleteMyUserDevice'], {
+  device: id
+})
+```
+
+Format komendy:
+
+- tablica `[serviceName, actionName]`,
+- payload jako zwykły obiekt.
+
+## Routing – blok `<route>` i meta `signedIn`
+
+- Każda strona w `src/pages/` może mieć blok `<route>` z metadanymi.
+- Używaj `meta.signedIn` do oznaczania stron wymagających logowania.
+
+```vue
+<route>
+  { "name": "devices", "meta": { "signedIn": true } }
+</route>
+```
+
+Dynamiczne ścieżki:
+
+- plik `[id].vue` odpowiada ścieżce `/devices/:id`.
+
+```js
+import { useRoute } from 'vue-router'
+
+const route = useRoute()
+const deviceId = route.params.id
+```
+
+## Confirm + Toast – wzorzec dla akcji destrukcyjnych
+
+```js
+import { useConfirm } from 'primevue/useconfirm'
+import { useToast } from 'primevue/usetoast'
+
+const confirm = useConfirm()
+const toast = useToast()
+
+function deleteDevice(id) {
+  confirm.require({
+    message: 'Czy na pewno chcesz usunąć to urządzenie?',
+    header: 'Potwierdzenie',
+    icon: 'pi pi-exclamation-triangle',
+    accept: async () => {
+      await api.command(['deviceManager', 'deleteMyUserDevice'], { device: id })
+      toast.add({
+        severity: 'success',
+        summary: 'Usunięto',
+        life: 2000
+      })
+    }
+  })
+}
+```
+
+## Wzorce UI – lista i szczegóły
+
+### Lista
+
+```vue
+<template>
+  <div class="container mx-auto p-4">
+    <div class="flex items-center justify-between mb-6">
+      <h1 class="text-2xl font-bold">Urządzenia</h1>
+      <Button label="Dodaj" icon="pi pi-plus" @click="openDialog" />
+    </div>
+
+    <Card v-if="devices.value?.length === 0">
+      <template #content>
+        <p class="text-center text-gray-500">
+          Brak urządzeń
+        </p>
+      </template>
+    </Card>
+
+    <div class="grid gap-4">
+      <Card v-for="device in devices.value" :key="device.id">
+        <template #content>
+          <!-- zawartość -->
+        </template>
+      </Card>
+    </div>
+  </div>
+</template>
+```
+
+### Tag statusu
+
+```vue
+<Tag
+  :value="conn.status"
+  :severity="conn.status === 'online' ? 'success' : 'secondary'"
+/>
+```
+
+## Computed paths – reaktywne parametry
+
+Gdy ścieżki zależą od reaktywnych wartości (route params, props), owijaj je w `computed()`:
+
+```js
+import { computed, unref } from 'vue'
+import { usePath, live } from '@live-change/vue3-ssr'
+
+const path = usePath()
+
+const articlePath = computed(() => path.blog.article({ article: unref(articleId) }))
+const [article] = await Promise.all([live(articlePath)])
+```
+
+Dla warunkowego ładowania (np. tylko gdy zalogowany), zwróć wartość falsy:
+
+```js
+import { useClient } from '@live-change/vue3-ssr'
+const client = useClient()
+
+const myDataPath = computed(() => client.value.user && path.blog.myArticles({}))
+const [myData] = await Promise.all([live(myDataPath)])
+```
+
+## Powiązane dane – `.with()`
+
+Dołączaj powiązane obiekty do elementów w jednym reaktywnym zapytaniu:
+
+```js
+path.blog.articles({})
+  .with(article => path.userIdentification.identification({
+    sessionOrUserType: article.authorType,
+    sessionOrUser: article.author
+  }).bind('authorProfile'))
+```
+
+Dostęp: `article.authorProfile?.firstName`. Działa zarówno z `live()` jak i `RangeViewer`.
+
+## WorkingZone dla akcji asynchronicznych
+
+`ViewRoot` opakowuje każdą stronę w `<WorkingZone>`. Używaj `inject('workingZone')` dla akcji przycisków poza formularzami:
+
+```js
+import { inject } from 'vue'
+const workingZone = inject('workingZone')
+
+function doAction() {
+  workingZone.addPromise('actionName', (async () => {
+    await actions.blog.publishArticle({ article: id })
+    toast.add({ severity: 'success', summary: 'Opublikowano', life: 2000 })
+  })())
+}
+```
+
+Aktywuje globalny spinner/blur na czas trwania promisy.
+
+## Kontrola dostępu z `useClient`
+
+```js
+import { useClient } from '@live-change/vue3-ssr'
+const client = useClient()
+```
+
+- `client.value.user` – truthy gdy zalogowany
+- `client.value.roles` – tablica ról (np. `['admin', 'owner']`)
+
+W template:
+
+```vue
+<Button v-if="client.roles.includes('admin')" label="Admin" />
+<div v-if="!client.user">Zaloguj się</div>
+```
+
+## Locale i czas
+
+- Wywołaj `useLocale().captureLocale()` w `App.vue` żeby zapisać locale przeglądarki do backendu.
+- Używaj `locale.localTime(date)` z `d()` z vue-i18n do wyświetlania dat bezpiecznego dla SSR.
+- `currentTime` z `@live-change/frontend-base` to reaktywny ref który tykuje co 500ms.
+- `useTimeSynchronization()` z `@live-change/vue3-ssr` koryguje różnicę zegarów – używaj gdy timing jest krytyczny (odliczanie, eventy real-time).
+
+## Analityka
+
+Używaj `analytics` z `@live-change/vue3-components`:
+
+```js
+import { analytics } from '@live-change/vue3-components'
+analytics.emit('article:published', { articleId: id })
+```
+
+Podpinaj providery (PostHog, GA4) w osobnym pliku importowanym z `App.vue`.
+
+## SSR i konfiguracja frontendu
+
+- Utrzymuj standardowy układ entry points:
+
+```js
+// entry-client.js
+import { clientEntry } from '@live-change/frontend-base/client-entry.js'
+export default clientEntry(App, createRouter, config)
+
+// entry-server.js
+import { serverEntry, sitemapEntry } from '@live-change/frontend-base/server-entry.js'
+export const render = serverEntry(App, createRouter, config)
+export const sitemap = sitemapEntry(App, createRouter, routerSitemap, config)
+```
+
+- Konfigurację PrimeVue trzymaj w jednym miejscu (`config.js`) i używaj `definePreset` do nadpisania motywu.
+
+## Odkrywanie widoków i akcji z `describe`
+
+Komenda CLI `describe` pozwala znaleźć dostępne widoki (do `live()`) i akcje (do `api.command` / `editorData` / `actionData`):
+
+```bash
+node server/start.js describe --service blog
+node server/start.js describe --service blog --view articlesByCreatedAt --output yaml
+node server/start.js describe --service blog --action createMyUserArticle --output yaml
+```
+
+To najszybszy sposób na odkrycie jakie ścieżki i akcje są dostępne, w tym te wygenerowane automatycznie przez relacje.

package/.cursor/rules/live-change-service-structure.mdc

@@ -0,0 +1,107 @@
+---
+description: LiveChange service file structure — every service must be a directory with separate definition.js, index.js, etc.
+globs: server/**/*.js
+alwaysApply: true
+---
+
+# LiveChange Service Structure
+
+Every LiveChange service **must** be a directory, not a single file.
+
+## Required structure
+
+```
+server/<serviceName>/
+  definition.js   # creates app.createServiceDefinition({ name }) – nothing else
+  index.js        # imports definition, imports all domain files, exports definition
+  config.js       # required – resolves definition.config, sets definition.clientConfig, exports plain config object
+  <domain>.js     # one file per domain area (models, views, actions, triggers)
+```
+
+## definition.js
+
+Only creates and exports the definition. No models, no actions here.
+
+```js
+import App from '@live-change/framework'
+const app = App.app()
+
+const definition = app.createServiceDefinition({ name: 'myService' })
+
+export default definition
+```
+
+## index.js
+
+Imports definition and all domain files (side-effect imports), then re-exports definition.
+
+```js
+import App from '@live-change/framework'
+const app = App.app()
+
+import definition from './definition.js'
+
+import './authenticator.js'
+import './myModel.js'
+import './otherModel.js'
+
+export default definition
+```
+
+## config.js (required)
+
+Reads `definition.config` (passed from `app.config.js`), resolves defaults, sets `definition.clientConfig` (for frontend),
+and exports a plain config object used by other domain files.
+
+```js
+import definition from './definition.js'
+
+const {
+  defaultAccess = {
+    writeAccessControl: ['owner', 'admin'],
+    readAllAccess: ['admin']
+  }
+} = definition.config || {}
+
+definition.clientConfig = {
+  // values exposed to frontend, if needed
+}
+
+export default { defaultAccess }
+```
+
+## Domain files (e.g. myModel.js)
+
+Each file imports `definition` (and `config` if needed) and registers models/views/actions/triggers.
+
+```js
+import App from '@live-change/framework'
+const app = App.app()
+
+import definition from './definition.js'
+import config from './config.js'
+
+export const MyModel = definition.model({ name: 'MyModel', ... })
+
+definition.view({ name: 'myList', ... })
+definition.action({ name: 'doThing', ... })
+```
+
+Rule of thumb:
+
+- Domain files should read configuration from `config` (exported from `config.js`), not directly from `definition.config`.
+
+## services.list.js import
+
+Always import from the directory index, not a flat file:
+
+```js
+import myService from './myService/index.js'   // ✓
+import myService from './myService.js'         // ✗
+```
+
+## Why
+
+A flat single-file service makes it hard to add new domain files (auth, models, triggers, etc.)
+without the file growing unmanageably. The directory structure mirrors the pattern used in
+`@live-change/live-change-stack/services/*`.

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

@@ -0,0 +1,197 @@
+---
+description: Design actions, views, triggers with indexes and batch processing patterns
+---
+
+# Skill: live-change-design-actions-views-triggers
+
+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.
+
+## Kiedy używać
+
+Użyj tego skilla, gdy:
+
+- dodajesz nowe akcje do istniejących modeli,
+- tworzysz widoki (szczególnie zakresowe) dla list,
+- implementujesz triggery (online/offline, batchowe przetwarzanie, asynchroniczne wyniki).
+
+## 1. Projekt akcji
+
+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
+
+```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 }
+  }
+})
+```
+
+## 2. Projekt widoku
+
+1. **Zdecyduj, czy to pojedynczy obiekt czy lista**
+   - pojedynczy: użyj `get` lub `indexObjectGet`,
+   - lista: użyj `indexRangeGet` z indeksem.
+
+2. **Zdefiniuj `properties` widoku**
+   - tylko parametry potrzebne do wyszukiwania,
+   - typy zgodne z modelem (String/Number/itp.).
+
+3. **Użyj indeksów**
+
+Przykład widoku zakresowego:
+
+```js
+definition.view({
+  name: 'myItemsByStatus',
+  properties: {
+    status: {
+      type: String
+    }
+  },
+  async get({ status }, { client, service }) {
+    return MyModel.indexRangeGet('byStatus', {
+      status
+    })
+  }
+})
+```
+
+## 3. Triggery – online/offline
+
+1. **Zidentyfikuj zdarzenie**
+   - np. „połączenie online/offline”, „sesja utworzona”, „serwer się uruchomił”.
+
+2. **Zdefiniuj trigger z `properties`**
+   - triggery online/offline zwykle potrzebują tylko ID obiektu.
+
+3. **Aktualizuj minimalny zestaw pól**
+   - np. `status`, `lastSeenAt`.
+
+Przykład:
+
+```js
+definition.trigger({
+  name: 'sessionConnectionOnline',
+  properties: {
+    connection: {
+      type: String
+    }
+  },
+  async execute({ connection }, { service }) {
+    await Connection.update(connection, {
+      status: 'online',
+      lastSeenAt: new Date()
+    })
+  }
+})
+```
+
+## 4. Triggery batchowe – unikaj pełnych skanów
+
+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**.
+
+Przykład:
+
+```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
+    }
+  }
+})
+```
+
+## 5. Wzorzec „pending + resolve” dla asynchronicznych wyników
+
+Użyj tego wzorca, gdy:
+
+- akcja tworzy zlecenie/komendę,
+- wynik przychodzi później z innego procesu (urządzenie, worker, itp.),
+- chcesz, żeby akcja czekała na wynik z timeoutem.
+
+### Kroki
+
+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)`.
+
+### Szkic helpera
+
+```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)
+  }
+}
+```
+