@live-change/frontend-template 0.9.198 → 0.9.199

package/.claude/rules/live-change-backend-actions-views-triggers.md

@@ -0,0 +1,184 @@
+---
+description: Rules for implementing actions, views, and triggers in LiveChange services
+globs: **/services/**/*.js
+---
+
+# LiveChange backend – actions, views, triggers (Claude Code)
+
+Use these rules when implementing actions, views, and triggers in LiveChange services.
+
+## Actions
+
+- Place actions in domain files, near the models they operate on.
+- Each action should:
+  - declare clear input `properties`,
+  - perform minimal but necessary validation,
+  - use indexes instead of full scans,
+  - return a meaningful result (ids, data, etc.).
+
+Example:
+
+```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 }
+  }
+})
+```
+
+## Views
+
+- Views should be simple query endpoints over models.
+- Prefer `indexObjectGet` / `indexRangeGet` instead of scanning whole tables.
+
+Example of a range view:
+
+```js
+definition.view({
+  name: 'pendingCommands',
+  properties: {
+    connectionId: { type: String }
+  },
+  async get({ connectionId }, { client, service }) {
+    return BotCommand.indexRangeGet('byConnectionAndStatus', {
+      connection: connectionId,
+      status: 'pending'
+    })
+  }
+})
+```
+
+## Triggers – online/offline and batch updates
+
+- Use triggers for reacting to events (e.g. connection online/offline, server startup).
+- There are two typical patterns:
+  - single-object triggers (update one record),
+  - batch triggers (update many records safely).
+
+Online/offline example:
+
+```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'
+    })
+  }
+})
+```
+
+### Batch processing – always paginate
+
+- Never load “all rows” in one go.
+- Use a fixed `limit` (e.g. 32 or 128) and a cursor (`gt: lastId`) in a loop.
+
+```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
+    }
+  }
+})
+```
+
+## Pending + resolve pattern (async result)
+
+Use this pattern when an action must wait for a result from an external process (device, worker, etc.).
+
+1. The main action creates a “pending” record and calls `waitForCommand(id, timeoutMs)`.
+2. Another action or trigger updates the record and calls `resolveCommand(id, result)`.
+
+In-memory helper:
+
+```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)
+  }
+}
+```
+
+Usage in an action:
+
+```js
+await SomeCommand.create({ id, status: 'pending', ... })
+const result = await waitForCommand(id)
+return result
+```
+
+And in a reporting action:
+
+```js
+await SomeCommand.update(id, {
+  status: 'completed',
+  result
+})
+resolveCommand(id, result)
+```
+

package/.claude/rules/live-change-backend-architecture.md

@@ -0,0 +1,126 @@
+---
+description: Rules for LiveChange backend service architecture and directory structure
+globs: **/services/**/*.js
+---
+
+# LiveChange backend – service architecture (Claude Code)
+
+Use these rules whenever you work on backend services in this repo or other live-change-stack projects.
+
+## Service must be a directory
+
+- Each LiveChange service **must be a directory**, not a single file.
+- Use a consistent structure:
+
+```
+server/services/<serviceName>/
+  definition.js  # createServiceDefinition + use – no models/actions here
+  index.js       # imports definition + all domain files, exports definition
+  config.js      # optional – reads definition.config and exports plain object
+  <domain>.js    # domain files: models, views, actions, triggers
+```
+
+## `definition.js`
+
+- Import `app` from `@live-change/framework`.
+- Create the service definition **without** registering models/actions/views there.
+- If the service uses relations or access control, **always** add the plugins in `use`.
+
+```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`
+
+- Import `definition`.
+- Import all domain files (models/views/actions/triggers) as side-effect imports.
+- Re-export `definition` as default.
+
+```js
+import definition from './definition.js'
+
+import './modelA.js'
+import './modelB.js'
+import './authenticator.js'
+
+export default definition
+```
+
+## `config.js` (optional)
+
+- Read `definition.config` (set in `app.config.js`).
+- Apply defaults and export a plain object.
+
+```js
+import definition from './definition.js'
+
+const {
+  someOption = 'default'
+} = definition.config
+
+export default { someOption }
+```
+
+## Registering the service in the app
+
+### `services.list.js`
+
+- Always import the service from its `index.js`:
+
+```js
+import myService from './services/myService/index.js'
+
+export default {
+  // ...
+  myService
+}
+```
+
+### `app.config.js`
+
+- Make sure `services: [{ name }]` matches the name in `createServiceDefinition`.
+- Keep a **sensible order** of services:
+  - core/common services and plugins first,
+  - application-specific services last (they can depend on earlier ones).
+
+```js
+services: [
+  { name: 'user' },
+  { name: 'session' },
+  { name: 'accessControl' },
+  // ...
+  { name: 'myService' }
+]
+```
+
+## Inspecting services with `describe`
+
+Use the `describe` CLI command to see what the framework generated from your definitions (models, views, actions, triggers, indexes, events):
+
+```bash
+# All services overview
+node server/start.js describe
+
+# One service in YAML (shows all generated code)
+node server/start.js describe --service myService --output yaml
+
+# Specific entity
+node server/start.js describe --service myService --model MyModel --output yaml
+```
+
+This is especially useful after using relations (`userItem`, `itemOf`, `propertyOf`) — `describe` shows all the auto-generated views, actions, triggers, and indexes.
+
+## When to create a new service
+
+- When you have a clearly separate domain (payments, notifications, devices, etc.).
+- When a group of models/actions/views has its own configuration and dependencies.
+- When adding it to an existing service would mix unrelated responsibilities.

package/.claude/rules/live-change-backend-models-and-relations.md

@@ -0,0 +1,188 @@
+---
+description: Rules for defining models, relations, indexes and access control in LiveChange
+globs: **/services/**/*.js
+---
+
+# LiveChange backend – models and relations (Claude Code)
+
+Use these rules when defining or editing models and relations in LiveChange services.
+
+## General style for models
+
+- Put models in domain files imported from the service `index.js`.
+- Prefer **readable, multi-line** property definitions.
+- Avoid squeezing `type`, `default`, `validation` into a single unreadable line.
+
+```js
+properties: {
+  name: {
+    type: String,
+    validation: ['nonEmpty']
+  },
+  status: {
+    type: String,
+    default: 'offline'
+  },
+  capabilities: {
+    type: Array,
+    of: {
+      type: String
+    }
+  }
+}
+```
+
+## `userItem` – belongs to the signed-in user
+
+Use when the model is owned by the currently signed-in user.
+
+```js
+definition.model({
+  name: 'Device',
+  properties: {
+    name: {
+      type: String
+    }
+  },
+  userItem: {
+    readAccessControl: { roles: ['owner', 'admin'] },
+    writeAccessControl: { roles: ['owner', 'admin'] },
+    writeableProperties: ['name']
+  }
+})
+```
+
+This automatically generates:
+
+- “my X” views (list + single),
+- basic CRUD actions for the owner.
+
+## `itemOf` – child belongs to a parent
+
+Use for lists of items related to another model.
+
+```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'] }
+  }
+})
+```
+
+Guidelines:
+
+- `what` must point to a model defined earlier (in this or another service).
+- The relation generates standard views/actions for listing and managing children.
+
+## `propertyOf` – one-to-one property, id = parent id
+
+Use when the model represents a single “state object” for a parent, with the same id.
+
+```js
+definition.model({
+  name: 'DeviceCursorState',
+  properties: {
+    x: { type: Number },
+    y: { type: Number }
+  },
+  propertyOf: {
+    what: Device,
+    readAccessControl: { roles: ['owner', 'admin'] },
+    writeAccessControl: { roles: ['owner', 'admin'] }
+  }
+})
+```
+
+Effects:
+
+- You can fetch it directly as `DeviceCursorState.get(deviceId)`.
+- No need for an extra `device` field or index for lookups by parent id.
+
+## `propertyOf` with multiple parents (1:1 link to each)
+
+Sometimes a model is a dedicated 1:1 link between entities (for example: invoice ↔ contractor in a specific role).
+Most commonly this is 1–2 parents, but `propertyOf` can point to **any number** of parent models (including 3+), if that matches the domain semantics.
+
+In that case:
+
+- avoid storing the “other side id” as a plain `contractorId` / `someId` property
+- avoid adding ad-hoc `...Id` fields in a relation model just to “join” entities — CRUD/relations generators won’t treat it as a relation
+- instead, define the relation as `propertyOf` to **each** parent so the relations/CRUD generator understands the model is connecting entities.
+
+Example (schematic):
+
+```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 }
+  ]
+})
+```
+
+## `foreignModel` – parent from another service
+
+Use when `itemOf` / `propertyOf` refers to a model from a different service.
+
+```js
+const Device = definition.foreignModel('deviceManager', 'Device')
+
+definition.model({
+  name: 'BotSession',
+  properties: {
+    // ...
+  },
+  itemOf: {
+    what: Device,
+    readAccessControl: { roles: ['owner', 'admin'] }
+  }
+})
+```
+
+Notes:
+
+- First argument is the service name.
+- Second is the model name in that service.
+
+## Indexes
+
+- Declare indexes explicitly when you frequently query by a field or field combination.
+- Use descriptive names like `bySessionKey`, `byDeviceAndStatus`, etc.
+
+```js
+indexes: {
+  bySessionKey: {
+    property: ['sessionKey']
+  },
+  byDeviceAndStatus: {
+    property: ['device', 'status']
+  }
+}
+```
+
+In other services, the same index may be visible with a prefixed name such as `myService_Model_byDeviceAndStatus`.
+
+## Access control on relations
+
+- Always set `readAccessControl` and `writeAccessControl` on relations (`userItem`, `itemOf`, `propertyOf`).
+- Treat access control as part of the model definition, not an afterthought.
+