@live-change/frontend-template 0.9.198 → 0.9.199

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

@@ -0,0 +1,190 @@
+---
+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 if you need:
+   - a **single** object view, or
+   - a **list/range** view.
+2. Define `properties` for the view:
+   - only parameters needed for filtering,
+   - types consistent with model fields.
+3. Use the right primitive:
+   - `get` / `indexObjectGet` for single object,
+   - `indexRangeGet` for lists.
+
+Range view example:
+
+```js
+definition.view({
+  name: 'myItemsByStatus',
+  properties: {
+    status: { type: String }
+  },
+  async get({ status }, { client, service }) {
+    return MyModel.indexRangeGet('byStatus', { status })
+  }
+})
+```
+
+## 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 – 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/.claude/skills/live-change-design-models-relations.md

@@ -0,0 +1,173 @@
+---
+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.
+
+Example:
+
+```js
+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 – 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/.claude/skills/live-change-design-service.md

@@ -0,0 +1,132 @@
+---
+description: Create or restructure a LiveChange backend service with proper directory layout
+---
+
+# Skill: live-change-design-service (Claude Code)
+
+Use this skill when you need to **create or restructure a LiveChange service** in this project or any other live-change-stack project.
+
+## When to use
+
+- You are adding a **new domain service** (payments, devices, notifications, etc.).
+- You are splitting logic out of an existing service.
+- You want to make sure the service structure follows the project conventions.
+
+## Step 1 – Choose the service name
+
+1. Pick a short, domain-oriented name, e.g. `deviceManager`, `payments`, `notifications`.
+2. This name will be used:
+   - as `name` in `app.createServiceDefinition({ name })`,
+   - as the `name` entry in `app.config.js` (`services: [{ name: '...' }]`),
+   - in `services.list.js` as the property key.
+
+## Step 2 – Create the service directory
+
+1. Create `server/services/<serviceName>/`.
+2. Inside, create at least:
+   - `definition.js`
+   - `index.js`
+3. Optionally also:
+   - `config.js` – for resolving `definition.config`,
+   - domain files like `models.js`, `authenticator.js`, `actions.js`, or more fine-grained files.
+
+## Step 3 – Implement `definition.js`
+
+1. Import `app` from `@live-change/framework`.
+2. If the service uses relations or access control:
+   - import `relationsPlugin` from `@live-change/relations-plugin`,
+   - import `accessControlService` from `@live-change/access-control-service`.
+3. Call `app.createServiceDefinition({ name: '...', use: [...] })`.
+4. **Do not register models, actions or views** in this file – only the definition.
+
+Example:
+
+```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
+```
+
+## Step 4 – Implement `index.js`
+
+1. Import `definition` from `./definition.js`.
+2. Import all domain files (models, views, actions, triggers, authenticators) as side-effect imports.
+3. Export `definition` as the default export.
+4. Do **not** put heavy logic into `index.js`.
+
+Example:
+
+```js
+import definition from './definition.js'
+
+import './models.js'
+import './authenticator.js'
+import './actions.js'
+
+export default definition
+```
+
+## Step 5 – (Optional) Implement `config.js`
+
+1. Import `definition`.
+2. Read `definition.config` and apply default values.
+3. Export a plain object.
+
+Example:
+
+```js
+import definition from './definition.js'
+
+const {
+  someOption = 'default'
+} = definition.config
+
+export default { someOption }
+```
+
+## Step 6 – Register the service in `services.list.js`
+
+1. Import from the service directory `index.js`:
+
+```js
+import myService from './services/myService/index.js'
+```
+
+2. Add the service to the exported object:
+
+```js
+export default {
+  // ...
+  myService
+}
+```
+
+## Step 7 – Register the service in `app.config.js`
+
+1. Ensure there is an entry in `services`:
+
+```js
+services: [
+  // ...
+  { name: 'myService' }
+]
+```
+
+2. Keep a sensible order:
+   - core/common services and plugins (user, session, accessControl, etc.) first,
+   - domain-specific application services later.
+
+## Step 8 – Handle dependencies on other services
+
+1. If the service needs to reference models from other services:
+   - use `definition.foreignModel('otherService', 'ModelName')` in domain files,
+   - do **not** import their model files directly.
+2. Make sure the other services are listed **before** this one in `app.config.js`.
+

package/.claude/skills/live-change-frontend-action-buttons.md

@@ -0,0 +1,128 @@
+---
+description: Build async action buttons with workingZone, toast and confirm dialogs
+---
+
+# Skill: live-change-frontend-action-buttons (Claude Code)
+
+Use this skill when you build **buttons that trigger async actions** outside of forms, using `workingZone`, `toast`, and optionally `confirm`.
+
+## When to use
+
+- A button triggers a backend action (delete, approve, toggle, etc.) — **no form fields**.
+- You want the global loading spinner to appear while the action runs.
+- Destructive actions need a confirmation dialog before executing.
+
+**Need a form with fields?** Use `editorData` (model editing) or `actionData` (one-shot actions) instead.
+
+## Step 1 – Inject workingZone, set up toast/confirm
+
+```javascript
+import { inject } from 'vue'
+import { useToast } from 'primevue/usetoast'
+import { useConfirm } from 'primevue/useconfirm'
+import { useApi, useActions } from '@live-change/vue3-ssr'
+
+const workingZone = inject('workingZone')
+const toast = useToast()
+const confirm = useConfirm()
+const api = useApi()
+const actions = useActions()
+```
+
+`workingZone` is provided by `ViewRoot` (which wraps every page in `<WorkingZone>`). When you call `workingZone.addPromise(name, promise)`, the global spinner/blur activates until the promise resolves.
+
+## Step 2 – Simple action button
+
+Wrap the async operation in `workingZone.addPromise()`:
+
+```javascript
+function createItem() {
+  workingZone.addPromise('createItem', (async () => {
+    const result = await actions.blog.createArticle({})
+    toast.add({ severity: 'success', summary: 'Article created', life: 2000 })
+    router.push({ name: 'article:edit', params: { article: result } })
+  })())
+}
+```
+
+**Important:** Note the `(async () => { ... })()` pattern – you must invoke the async IIFE immediately so `addPromise` receives a Promise, not a function.
+
+Template:
+
+```vue
+<Button label="Create article" icon="pi pi-plus" @click="createItem" />
+```
+
+## Step 3 – Destructive action with confirm
+
+Use `confirm.require()` before the action:
+
+```javascript
+function deleteItem(item) {
+  confirm.require({
+    message: 'Are you sure you want to delete this article?',
+    header: 'Confirmation',
+    icon: 'pi pi-trash',
+    acceptClass: 'p-button-danger',
+    accept: async () => {
+      workingZone.addPromise('deleteArticle', (async () => {
+        await actions.blog.deleteArticle({ article: item.id })
+        toast.add({ severity: 'success', summary: 'Deleted', life: 2000 })
+      })())
+    },
+    reject: () => {
+      toast.add({ severity: 'info', summary: 'Cancelled', life: 1500 })
+    }
+  })
+}
+```
+
+Template:
+
+```vue
+<Button label="Delete" icon="pi pi-trash" severity="danger" @click="deleteItem(article)" />
+```
+
+## Step 4 – Error handling
+
+Add try/catch inside the async IIFE:
+
+```javascript
+function toggleStatus(item) {
+  workingZone.addPromise('toggleStatus', (async () => {
+    try {
+      await actions.blog.toggleArticleStatus({ article: item.id })
+      toast.add({ severity: 'success', summary: 'Status updated', life: 2000 })
+    } catch(e) {
+      toast.add({ severity: 'error', summary: 'Error', detail: e?.message ?? e, life: 5000 })
+    }
+  })())
+}
+```
+
+## Step 5 – Using api.command instead of actions
+
+Both work. `actions` is shorthand for typed service actions:
+
+```javascript
+// Using actions (preferred when available):
+await actions.blog.deleteArticle({ article: id })
+
+// Using api.command (always works):
+await api.command(['blog', 'deleteArticle'], { article: id })
+```
+
+## Pattern summary
+
+```
+Button click
+  → confirm.require() (if destructive)
+    → workingZone.addPromise('name', (async () => {
+        try {
+          await actions.service.action({ ... })
+          toast.add({ severity: 'success', ... })
+        } catch(e) {
+          toast.add({ severity: 'error', ... })
+        }
+      })())
+```